Vamos -- for managing virtual machines ===== Licensed under GPLv2. See the file COPYING for full details. What is it? =========== Vamos is a simple (mostly shell-script) system for managing virtual machines run using the qemu/kqemu/kvm family of virtualisation tools. It allows VMs to be pre-defined so that they can be easily started without remembering lots of options. It also handles the network configuration for the VMs, so that they can be run in user mode, bridged mode, or routed mode with minimal effort or fuss. Quick start guide ================= $ make # Build the tools $ make install # Install the tools $ emacs /etc/vamos/vm1 # Define a VM with your favourite editor $ vm vm1 # Start your VM $ vm vm2 -noacpi # Start your VM with additional (one-time) options $ vmkill vm1 # Kill a VM (no clean shutdown) Configuration guide =================== There are two types of configuration files used by vamos. The first is the global configuration, and can be used to define common options across all your VMs, plus alter things such as the working directories of the Vamos tools. The second type is the VM configuration file, which gives the options for each individual VM. Global configuration -------------------- By default, the Vamos tools look in /etc/vamos/vamos.conf for the global configuration. Per-user overrides may also be set (see below). Global configuration directives may be any of the following, plus any of the per-VM configuration options. Where a default option exists, it is shown below. CONFDIR=/etc/vamos The directory containing the configuration files for VMs, plus the networking scripts. USERCONFDIR=${HOME}/.vamos The location for per-user configuration. If a file called vamos.conf exists in this directory, that will be read as global options as well. VM configuration ---------------- VMs are configured using files in ${CONFDIR} or ${USERCONFDIR}. ID= This is the only mandatory option for a VM, and should be a unique number on the host machine for each VM defined. RAM=128 The amount of memory to give the VM CPUS=1 The number of CPUs to define in the VM HDA= HDB= HDC= HDD= CDROM= These options define the files (or devices) used for the four hard disks. If CDROM is defined, it overrides the value of HDC, which will not be used. VIRTIO= Define a virtio paravirtual block device to pass to the guest system. Additional devices may be specified using directives starting with VIRTIO. e.g. VIRTIO1 VIRTIO2 VIRTIO_ROOT VIRTIO_USER, etc. SCSI= Define a SCSI block device to pass to the guest system. Additional devices may be specified using directives starting with SCSI. NET_TYPE_foo=user Define the type of network used in the VM for interface "foo". Values are "user", "bridged" or "routed". Bridged and routed networking require root privileges to configure the network correctly. NET_MAC_foo= Define the MAC address of the guest machine's network card, for interface "foo". NET_NIC_foo= Define the network interface card type for interface "foo". e.g. "virtio", or "rtl8139" NET_VLAN_foo=${ID} Define the qemu vlan to use for interface "foo". Defaults to the VM's ID. Also defines the suffix to the tap device created, if using bridged or routed networking. NET_IP_foo= NET_MASK_foo=255.255.255.0 If the host interface "foo" is configured to use routed networking, the network tap device on the host must be given an IP address and netmask. These options define that configuration. NET_BRIDGE_foo= If the host interface "foo" is configured to use bridged networking, attach the tap interface to the bridge given by this option. VIDEO=sdl Define the type of video output the VM will use. Valid options are "sdl", "vnc" or "none". VNC_DISPLAY=${ID} Set the display number used for a VNC-style display. OPTIONS= Any additional options to the qemu command needed. QEMU_COMMAND=qemu-system-x86_64 The name of the command used to start a VM. [The following configuration options are deprecated.] NET_TYPE=user DEPRECATED Define the type of network used in the VM. Values are "user", "bridged" or "routed". Bridged and routed networking require root privileges to configure the network correctly. GUEST_MAC= DEPRECATED Define the MAC address of the guest machine's network card VLAN=${ID} DEPRECATED Define the qemu vlan to use for networking. Defaults to the VM's ID. Also defines the suffix to the tap device created, if using bridged or routed networking. NETHOST= DEPRECATED NETMASK=255.255.255.0 If the host interface is configured to use routed networking, the network tap device on the host must be given an IP address and netmask. These options define that configuration. Other tools =========== offset-loop ----------- offset-loop is a simple script which allows you to mount a partition contained on a copy of a disk. For example, if /dev/vg00/vm-image is a disk image with a standard DOS partition table on it, you can create and mount a loop device with the first partition with the commands: $ offset-loop /dev/vg00/vm-image 1 /dev/loop/0 $ mount /dev/loop/0 /mnt/vm-image-partition-1 Removing the loop device is then accomplished with: $ umount /dev/loop/0 $ losetup -d /dev/loop/0 frankendisk ----------- frankendisk is the opposite of offset-loop. Where offset-loop allows you to break up a single disk image into its component partitions, frankendisk allows you to make a disk image, including partition table, from a bunch of files or devices representing the partitions. It will preserve the boot sector between setups. Setting up a frankendisk is a simple case of creating one, and starting it: $ frankendisk -C mydisk /dev/hda1 /dev/sdb3 /home/me/files/partition $ frankendisk -A mydisk The disk image is now available in /dev/mapper/mydisk. The sizes of the partitions in the frankendisk can be changed while the disk is stopped, and the partition table will be recreated appropriately when the disk is restarted. To stop the disk: $ frankendisk -D mydisk To remove the disk configuration (including the stored boot sector): $ frankendisk -X mydisk Disk configurations may be listed and examined with the -L and -E commands: $ frankendisk -L $ frankendisk -E mydisk Frankendisks should *not* be re-partitioned manually -- if you need to change the size of a partition in a frankendisk, stop the disk, change the size of the underlying device, and then restart the disk. Frankendisk will automatically rewrite the partition table to fit the new partition sizes. Frankendisks, once set up with -C, can be used in VM configurations for the "vm" tool above. Wherever a disk device may be specified, a frankendisk may be used instead, with "frankendisk:diskname". If the frankendisk is not already running, it will be started automatically. Acknowledgements ================ Thanks are due to Damian Brasher for working out how to do bridged networking properly, and for testing in a larger-scale environment than I am capable of.