Source

qemu-toolkit / doc / qemu-toolkit-configuration.7.ronn

Full commit
# qemu-toolkit-configuration(7) -- configuration for qemu-toolkit

## SYNTAX

The tool `vmadm` reads all files ending in `.rb` from `/etc/qemu-toolkit` on
startup. It expects these Ruby scripts to define virtual machines using the 
syntax defined below. 

### basic vm definition

A virtual machine definition is written in a Ruby-DSL and looks like this: 

    virtual_machine "myvm" do
      # Options go here! You'd need at least one disk to start.
    end

Since the definition is Ruby, nothing stops you from doing more complicated 
things like connecting to a database or generating definitions using method 
calls. Here's an example we've used in the wild: 

    def lan name, mac
      virtual_machine(name) do
        nic 'eth0', macaddr: mac, via: 'lan0'
      end
    end
    
    # Allows for very short VM definitions:
    lan 'vm1', '1:8:20:52:a6:7e'

### available options

Here's a list of configuration options within the virtual_machine declaration:

  * cpus <NUMBER>: 
    Configures the number of SMP cpus simulated to the guest system. 
    You should not configure more SMP cpus than you have physical CPU cores
    available. 
    
        # configures 4 SMP cpus
        cpus 4      

  * disk <DEVICE_PATH>: 
    Add a disk drive to the guest system. <DEVICE_PATH> should be the 
    quoted full path to a block device. 
    
    This is a macro that will define a `virtio`-device and automatically number
    your drives from 0 to N. If you're looking for more immediate control
    over qemu options, use the `drive`-option.
    
        # Use a zvol block device
        disk '/dev/zvol/rdsk/pool1/myvm/disk1'

  * drive <OPTIONS>:
    Directly add a drive directive to qemu options. If you use this, you'll
    need to provide all key-value pairs for the directive as a Ruby hash. Note
    that if you do not specify 'index', your drive will get the next free disk
    index. (as is the case with `disk`) For the full list of options, please
    refer to the [QEMU documentation](http://qemu.weilnetz.de/qemu-doc.html).
    
        # Manual drive configuration:
        drive if: 'floppy', file: 'floppy.dsk'
        
  * keyboard_layout <LAYOUT>:
    Configure keyboard layout of the VNC display. The default is 'en-us'. 
    
        # Set keyboard to 'de-ch'
        keyboard_layout 'de-ch'
        
    The available layouts are: 
        
        ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
        da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
        de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
        
  * net <TYPE>, <OPTIONS>:
    Manual network configuration. This gives you full access to QEMU options, 
    with the disadvantage of a slightly more complicated set of options. 
    Here's what you would need to do to duplicate the convencience macro `nic`
    below: 
      
        net :vnic, vlan: 1, name: 'vm1', ifname: 'vm1', 
          macaddr: '1:8:20:52:a6:7e'
        net :nic, vlan: 1, name: "vm1", model: "virtio", 
          macaddr: '1:8:20:52:a6:7e'

  
  * nic <NAME>, <OPTIONS>:
    Add a virtual network card to the guest. Virtual network cards are made
    to correspond to vnic links on the host system. These vnic links are 
    automatically generated for you, all you have to do is to specify a `via:`
    option here. 
    
    The `via:` option takes either physical links or etherstub switches as 
    value. 
    You can also specify a VLAN tag, separated by a colon. (ie: e1000g0:4)
    
    nic `model:` will default to `virtio`.
    
    NOTE: QEMU/kvm on Illumos will default to providing a single pseudo-nic
    that has a DHCP server attached to it by default. If you do not specify
    a `nic`, this is what you'll get. 
    
        # Create eth0 interface with given mac address via 'igb1'.
        nic 'eth0', macaddr: '2:8:20:52:a6:7e', via: 'igb1'

  * ram <MEGABYTES>: 
    Configures the amount of RAM the guest system sees. Note that the qemu 
    on Illumos locks memory down for the guest and never swaps it out. This
    means that you cannot simulate RAM you don't have available. (free)
    
        # One gigabyte of RAM should be enough for everyone. (default)
        ram 1024
    
  * vnc <PORT>:
    Enables VNC server on port <PORT>. Caution: This will listen for
    connections from all networks and allow unauthorized access to the guests
    console. Don't use this in real world deployments. Instead, use `vmadm
    console` or connect directly to the unix socket using socat.
    
        # Make vnc listen on a given port: (5900 + display = tcp/ip port)
        vnc_display ":0"
        
    This option is passed through to the '-vnc' option on qemu. All the values
    permitted there are permitted here as well. Note that a vnc socket is 
    created in `/var/run/qemu-toolkit/VMNAME/vm.vnc` even if this option is 
    not given. 

  * extra_arg <ARGUMENT>:
    Extra argument for QEMU, appended to the QEMU command line on launch. If
    you'd like to do something that you cannot achieve with the above options, 
    this is your last resort. 
    
    Note that we're interested in extending the DSL for common use cases, so 
    you might want to mention your extra_arg usage on the mailing list and 
    get proper treatment from qemu-toolkit. 
    
        # Arguments that are appended to the qemu launch command line: 
        extra_arg '-foo'
    
## SEE ALSO

qemu-toolkit-overview(7), qemu-toolkit-install(7),
qemu-toolkit-configuration(7), storadm(1), vmadm(1), README(7)