Kavoom manual
Kavoom is a thin wrapper around the kvm binary. It provides a command line driven management interface to kvm without running any additional daemons. See the project page.
This document uses ‘pikachu’ as the name for an example VM guest.
Table of contents
Basic usage
Starting a VM:
kavoom start pikachu
Gracefully stopping a VM by sending an ACPI powerbutton event:
kavoom shutdown pikachu
Forcefully stopping a VM by doing the equivalent of pulling the power cable:
kavoom destroy pikachu
Forcefully rebooting a VM by doing the equivalent of pressing the reset button:
kavoom monitor pikachu system_reset
Sending ctrl-alt-del to a VM:
kavoom monitor pikachu sendkey ctrl-alt-delete
Sending alt-sysrq-s to a VM:
kavoom monitor pikachu sendkey alt-sysrq-s
Suspending a VM (assumes you haven't changed the shutdown policy):
service kavoom stop pikachu
Resuming a VM:
service kavoom start pikachu
Accessing the serial console of a VM:
kavoom serial pikachu
Checking which VMs are running:
pgrep -a qemu-system
Kavoom components
The kavoom system consists of several parts. Each part is responsible for providing part of the functionality.
kvm itself
While you should never have to call kvm directly, part of the management of kvm VMs is done by interfacing with kvm, usually using the kavoom monitor subcommand. Some knowledge of kvm is required for this.
The main kavoom script
This script can be used to interface with kvm. You can use it to start and stop VMs and contact their monitor and serial ports.
The main kavoom script and its configuration file format is described in detail in its manpage.
The kavoom init script
This script is a layer on top of the main kavoom script that makes sure VMs are started and stopped whenever the host boots and shuts down. It can shut down VMs by either suspending them to disk or by doing a (graceful) shutdown sequence. You can also invoke this script for specific instances, by naming these after the command verb.
Creating a VM
Generate a MAC address:
head -c3 /dev/urandom | od -t x1 -A n | sed 's/ /:/g; s/^/52:54:00/' 52:54:00:2c:a7:3f
Create an LV for the virtual disk:
lvcreate -L 16g -n pikachu vg
Then, a configuration file /etc/kavoom/pikachu.cfg
:
mem = 1024 disk = /dev/vg/pikachu mac = 52:54:00:2c:a7:3f
If you want this VM to be started whenever the host boots, create an empty file /etc/kavoom/pikachu.auto
.
Installing an operating system
Tip: on consumer grade hardware, adding cache = unsafe
to the configuration file during installation may yield a huge speed boost.
Be sure to remove this line after installing though!
Start a VM with a CD image attached, booting from this CD and with a VNC console:
kavoom start pikachu -cdrom /tmp/debian-netinst.iso -boot d -vnc localhost:0
This will open a VNC socket on TCP port 5900. If the VM host is not the same machine as your desktop, you will need to set up port forwarding:
ssh -L 5900:localhost:5900 root@vmhost
You can start a VNC session using vinagre:
vinagre localhost::5900
Now install the operating system. When done, shut down the VM and start it normally:
kavoom start pikachu
Considerations for VMs
- On UNIX-based VM's, you can configure the console to be on the serial port.
On Debian GNU/Linux systems, add
console=ttyS0,115200
to the$GRUB_CMDLINE_LINUX
variable in/etc/default/grub
. - On systemd-based Linux VM's, configure a serial login by running the following commands:
systemctl enable getty@ttyS0 systemctl start getty@ttyS0
- On SysV-init-based Linux VM's, configure a serial login by adding the following line to
/etc/inittab
:T0:23:respawn:/sbin/getty -L ttyS0 115200 vt100
- On VMs based on common Linux distributions or on FreeBSD, you can safely add
virtio = yes
to the configuration file. For Microsoft Windows based guests the process may be a bit more laborious but you can download the Virtio driver CD at the Fedora site. - Enabling virtio also enables virtio console ports.
These are similar to serial ports but do not suffer from arbitrary speed limits.
Enable these the same way as the above serial ports but use
hvc
instead ofttyS
. - For Windows based VMs, adding the following line to
/etc/kavoom/pikachu.cfg
makes sure the clock is set properly:-rtc base=localtime
- If you wish to add SMP units to a Windows version that does not support multiple CPUs, you can add multiple ‘cores’ instead (the effect is the same) by adding the following line to
/etc/kavoom/pikachu.cfg
:-smp cores=4