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 colon-separated list of virtio paravirtual block devices
   to pass to the guest system.

NET_TYPE=user
   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=
   Define the MAC address of the guest machine's network card

VLAN=${ID}
   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=
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.

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.

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

Acknowledgements
================

Thanks are due to Damian Brasher for working out how to do bridged
networking properly.
