HowToConfigScript

Intro

I have written a utility called kvmctl to manage KVM-based VMs, along with a configuration file format, and other associated utilities. Feel free to use it, or to expand on it. While not strictly required by the license, I would appreciate knowing if you use it, and would appreciate being credited if you expand upon it.

A couple of assumptions are made for this work:

• all the VMs have unique host names.
• all the VMs have config files in /etc/kvm that are named <host>.kvm. These are shell script fragments that initialise variabless related to the VM.
• all the VMs are given unique numeric identifiers between 00 and 99. This is used for the VNC port number and the last 2 digits of the virtual MAC address.
• there is a single bridge configured for all VMs to use, and all VMs will use bridged networking

I don't proclaim to be a great shell programmer, so there are undoubtedly better ways to do a lot of things in this script. However, this works well enough for us, covers all the things we need to do, and has been running without issues for a couple of weeks now. I have made a bunch of changes to the script, and have released it as 2.0.4.  :)

There's a simple init.d/ script included that can be used to auto-start VMs when the host system boots. Just symlink config files into /etc/kvm/auto/ and then add the script to whichever runlevel you want. Just be sure to set it to start after networking is up.

Download

Version 2.0.4

Stable and working. Auto-shutdown doesn't work yet, as I haven't found a way to send a "powerdown" event to the guest OS to tell it to initiate a clean shutdown.

• Download the tarball here: kvmctl-2.0.4.tbz2

Version 2.1.0

I've added a possibility to start a monitor port as telnet server and added a shutdown. Since debian has removed bash tcp support i need netcat (nc) to send a power-button-press to the monitor of virtual machine. So if you like to test the shutdown, start the machine with a monitor and install "nc". This Version includes some other changes and is not roughly tested.

• Download the tarball here: kvmctl-2.1.0.tar.gz

Note: The tarball for 2.1.0 is gone, nobody has a copy, don't report this issue. The above paragraph is here strictly for people who already have kvmctl 2.1.0 and for historical purposes.

Usage

The script can be run as a normal user. It uses sudo internally for the start/stop commands (all the rest are run as the normal user). Currently, all kvm processes are run as root, as this was developed on Debian Lenny which (for whatever reason) decided to include kernel capabilities which prevents non-root users from accessing tun devices.

To see a blurb that describe all the options:

# kvmctl help
kvmctl 2.0.4
Licensed under BSDL
Copyright 2009

kvmctl is a management and control script for KVM-based virtual machines.

Usage:  kvmctl start    host    - start the named VM
        kvmctl startvnc host    - start the named VM, and then connect to console via VNC
        kvmctl stop     host    - stop  the named VM (only use if the guest is hung)
        kvmctl restart  host    - stop and then start the named VM (only use if the guest is hung)

        kvmctl vnc      host    - connect via VNC to the console of the named VM
        kvmctl whichvnc host    - show which VNC display port is assigned to the named VM
        kvmctl killvnc  host    - kills any running vncviewer processes attached to the named VM

        kvmctl edit     host    - open config file for host using $EDITOR, or create a new config file based on a template

        kvmctl status           - show the names of all running VMs
        kvmctl status   kvm     - show full details for all running kvm processes
        kvmctl status   host    - show full details for the named kvm process

        kvmctl help             - show this usage blurb

** Using stop is the same as pulling the power cord on a physical system. Use with caution.

To start a VM named webmail:

# kvmctl start webmail
Starting webmail.     
The VNC port for webmail is :05

To start a VM named webmail, and then immediately attach to the console via VNC:

# kvmctl startvnc webmail
Starting webmail.        
The VNC port for webmail is :05
<vncviewer is started>         

To check the status of all running VMs (just outputs the name of the running VMs):

# kvmctl status
The following VMs are running:
fcsync                        
webmail                       

To see the process info for all the running VMs:

# kvmctl status kvm
The following VMs are running:
3792 /usr/bin/kvm -name fcsync -daemonize -localtime -usb -usbdevice tablet -smp 1 -m 1048 -vnc :02 -pidfile /var/run/kvm/fcsync.pid -net nic,macaddr=00:16:3e:00:00:02,model=rtl8139 -net tap,ifname=tap02 -boot c -drive index=0,media=disk,if=ide,file=/dev/mapper/vol0-fcsync                                         
5123 /usr/bin/kvm -name webmail -daemonize -localtime -usb -usbdevice tablet -smp 2 -m 2048 -vnc :05 -pidfile /var/run/kvm/webmail.pid -net nic,macaddr=00:16:3e:00:00:05,model=e1000 -net tap,ifname=tap05 -boot c -drive index=1,media=disk,if=scsi,file=/dev/mapper/vol0-webmail--storage -drive index=0,media=disk,if=ide,file=/dev/mapper/vol0-webmail                                                                        

To see the process info for a specific VM:

# kvmctl status webmail
VM for host webmail is running with:
5123 /usr/bin/kvm -name webmail -daemonize -localtime -usb -usbdevice tablet -smp 2 -m 2048 -vnc :05 -pidfile /var/run/kvm/webmail.pid -net nic,macaddr=00:16:3e:00:00:05,model=e1000 -net tap,ifname=tap05 -boot c -drive index=1,media=disk,if=scsi,file=/dev/mapper/vol0-webmail--storage -drive index=0,media=disk,if=ide,file=/dev/mapper/vol0-webmail                                                                        

To "pull the power cord" of a running VM:

# kvmctl stop webmail
Attempting to stop VM for webmail
VM for webmail has stopped       

To "powercycle" a running VM:

# kvmctl restart webmail
Attempting to stop VM for webmail
VM for webmail has stopped       
Starting webmail.                
The VNC port for webmail is :05  

To see which VNC port has been assigned to a VM:

# kvmctl whichvnc webmail
The VNC port for webmail is :05

To connect to the VNC port of a VM (requires vncviewer installed on the host):

# kvmctl vnc webmail
<vncviewer is started>

To create a new config file for a VM:

# kvmctl edit newvm
/etc/kvm/test.kvm does not exist.  Would you like to create one from the template? (y/n)
<if yes, $EDITOR is opened with the template loaded>                                    

To edit an existing config file:

# kvmctl edit webmail
<$EDITOR is opened with /etc/kvm/webmail.kvm loaded.>

kvmctl 2.0 config file format

# kvmctl Version:  2.0.0

# The name of the VM must be unique across all VMs running on this server
# This is not actually used anywhere, instead kvmctl uses the filename without
# the .kvm as the host name.
# host="hostname"

# An ID number for the VM. 
# This is used to generate the MAC address of the virtual NIC, the tap device in the host, and
# the VNC port for the VM's console.
id="##"

# How much RAM to associate with the VM.
# This is the max amount of RAM that it will use.
mem="1024"

# Whether to enable ACPI support in the virtual BIOS
# Default is to enable ACPI
# noacpi cannot be set if cpus > 1.
noacpi=""

# The number of virtual CPUs to assign to the VM.
# Stable values are 1-4.
# cpus must be set to 1 if noacpi is set.
cpus="1"

# Which mouse device to use
# Values:  mouse, tablet
# Default: tablet
mouse="tablet"

# The network chipset to use in the VM.
# Values:  rtl1389, e1000
# Default: rtl8139
nic="rtl8139"

# Which virtual block device to boot from
# Values:  a=floppy0, b=floppy1, c=disk0, d=disk1
# Default: c
boot="c"

# If the VM is set to boot from "d" and "d" is a CD-ROM, an extra '-no-reboot'
# option is added to the kvm commandline.  This will cause the VM to treat a
# "reboot" command as if it were a "shutdown" command.

# Values  for disktype: ide, scsi, virtio
# Default for disktype: ide

# If the value for disktyp0 is scsi or virtio, an extra ',boot=on' option will
# be added to the kvm commandline.  This is needed in order to boot from SCSI
# and paravirtualised block devices.

# Values  for media:    disk, cdrom
# Default for disktype: disk

# Values  for disk:     a path to either a disk image file, or an LVM logical v volume
# Default for disk:     /dev/mapper/vol0-${host}

# The first virtual block device
# For IDE devices, this is primary master.
disktype0="ide"
media0="disk"
disk0="/path/to/diskimage"

# The second virtual block device
# For IDE devices, this is primary slave.
disktype1=""
media1=""
disk1=""

# The third virtual block device
# For IDE devices, this is secondary master
# USE THIS FOR CD-ROMS OR PERFORMANCE WILL SUFFER GREATLY!!
disktype2="ide"
media2="cdrom"
disk2="/path/to/osinstall.iso"

# The fourth virtual block device
# For IDE devices, this is secondary slave
disktype3=""
media3=""
disk3=""