# 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
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
# 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
* 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
* 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'
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',
net :nic, vlan: 1, name: "vm1", model: "virtio",
* 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:`
The `via:` option takes either physical links or etherstub switches as
value. You can also specify a VLAN tag, separated by a colon.
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
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: '10.0.0.2', netmask: '255.255.255.0', gateway: '10.0.0.1',
hostname: 'test', dns_ip0: '22.214.171.124', dns_ip1: '126.96.36.199'
* 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)
* 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)
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
* 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:
## SEE ALSO
qemu-toolkit-configuration(7), storadm(1), vmadm(1), README(7)