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

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


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.

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'
    # 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:

  * boot <OPTIONS>: 
    Configures the boot order of the virtual machine. Use the 'order' option 
    to configure boot order; use the 'once' option to configure the first
    boot of the machine. For more options, please see the QEMU documentation 
    on '-boot'.

        # Boot off the CDROM device, alyways
        boot order: 'd'

        # Boot off the CDROM the next time, otherwise from harddisk first
        boot order: 'c', once: 'dc'

  * 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
        # 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](
        # 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`
        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)

    You *must* specify a `macaddr:` option using an address that is unique
    on your network. No checking is done for this in qemu-toolkit. This is 
    a limitation that will be lifted in future versions.
    nic `model:` will default to `virtio`. The `virtio` driver will be 
    configured for maximum throughput by setting driver options directly 
    as smartos does. This optimisation may change over time, but will always
    try to optimise throughput and availability. 

    To configure the DHCP server that kvm has built in, use `ip:`, 
    `netmask:`, `gateway:`, `hostname:` and `dns_ip:` options. Please see the
    example below.
    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'

        # Create an interface and provide the IP address by built-in DHCP
        nic 'eth1', macaddr: '...', via: 'igb2', 
          ip: '', netmask: '', gateway: '', 
          hostname: 'test', dns_ip0: '', dns_ip1: ''

  * 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'

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