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 -lf kavoom

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 = writeback 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

Back to the index page

mail me