VMBuilder is a Python-based software package for creating VM images of free software GNU/Linux-based operating systems. It's currently being developed by the Ubuntu Virtualization Team at this address https://launchpad.net/vmbuilder. It makes building and installing VMs a breeze. The vanilla / trunk release supports Ubuntu on Xen, VirtualBox, VMware, KVM and Amazon EC2.

As part of a SummerOfCode2009 project, DavidWendt is working to expand VMBuilder to support Debian Etch and Lenny on the aforementioned VMs, as well as extend the Amazon EC2 support to Eucalyptus.


Currently, David works on an Alioth Git repository as part of pkg-escience. You can grab the latest master branch revision by typing:

git clone git://git.debian.org/git/pkg-escience/vmbuilder.git

The current master branch includes Debian packaging so can be built with dpkg-buildpackage, or just run debian-vm-builder within the source directory as shown below. You may also install the package into your filesystem with "sudo python setup.py install". In this case the program name is 'vmbuilder'. The package depends on parted, kpartx, and python-cheetah.


First of all, note that VMbuilder requires you to be superuser/root in order to build VMs.

Usage of our VMbuilder is very similar to the trunk revision, except obviously you can select Debian as a distro and Etch and Lenny as a suite. You can find some documentation in the Community Ubuntun Documentation site

Lenny on KVM - basic

The following command line will install a default lenny system with default --user "debian", --pass "debian" and non-refault root password "debian". What may be handy for all those with a memory-mapped /tmp file system is the specification of an alternative path to prepare the image:

./debian-vm-builder kvm lenny --tmp=/var/tmp --mirror http://ftp.de.debian.org/debian --rootpass debian

Lenny on Eucalyptus - more advanced

Running on Eucalyptus is a bit more advanced than running on KVM. First off, it will be much helpful if you install euca2ools (the ec2-ami tools from Amazon are technically compatible with Eucalyptus, but it's a EULA violation to do so) so you can actually bundle and upload your images. To do anything involving EC2 or Eucalyptus, first we must enable the special --ec2 flag. --ec2 tells the EC2 module that we're building for EC2. By default, it throws an exception if you didn't select Xen - for KVM, you have to turn on the --ec2-is-eucalyptus flag to disable hypervisor sanity checks.

Additionally, by enabling --ec2 you'll need to provide it with your Eucalyptus/EC2 credentials. Sourcing the eucarc file that Eucalyptus gives you will automatically satisfy the --ec2-access-key, --ec2-secret-key, --ec2-user, --ec2-cert, --ec2-key, -ec2-url, --ec2-s3-url, and --ec2-cloud-cert settings so you don't have to type those in.

Finally, there are the options --ec2-bundle, --ec2-upload, and --ec2-register. These use either euca2ools or ec2-ami-tools, so you need to have them installed to use these options. They also have to be enabled in order - you can't upload if you haven't bundled, and you can't register if you haven't uploaded. They communicate with two servers - a storage server, which we will call Walrus (technically S3 if you're using Amazon), and the cloud service which we call Eucalyptus. (Again, technically EC2 if you're using Amazon.)

Bundling takes a machine image, tars it, splits it, and signs it. The end product of this is a <machine_name>.manifest.xml file as well as several part files holding the actual data. The <machine_name> is determined by the mandatory parameter --ec2-name, and is not your machine's hostname. Then it must be uploaded to the cluster's storage server. This is handled by the upload-bundle command; which takes a little while as it must send your image over the network. The manifest.xml file and part files are stored in a 'bucket' - all you need to know is that buckets are owned by users, have unique names, and you need to put your image in one of 'em. To specify this bucket name, use the mandatory parameter --ec2-bucket. Finally, you need to tell Eucalyptus about the new image Walrus is storing, by registering the image. This gives the image a Eucalyptus id like 'emi-amG90SML' and means you can finally run instances of it.

The last prickly thing I haven't mentioned, is kernels. Kernels and ramdisks are built and stored separately from the actual machine image. Amazon restricts you to specific kernels and ramdisks which they have already packaged up and registered. If you are building for Amazon, you must manually specify your kernel or ramdisk with the --ec2-kernel and --ec2-ramdisk parameters. The Debian plugins do NOT have reasonable defaults set for these, you must find your own kernels and ramdisks that work.

That is, of course, if you're on Amazon. If you are on a Eucalyptus cluster, you most likely can use your own kernels and ramdisks just fine. This is because Eucalyptus allows arbitrary kernel and ramdisk registration by default. VMBuilder can bundle the kernel and ramdisk for you from whatever the distro plugin installs. To enable this, you must employ three more parameter flags: --ec2-bundle-kernel, --ec2-upload-kernel, and --ec2-register-kernel. These all control bundling, uploading, and registering the machine's kernel and ramdisk pair. They will be uploaded to the same Walrus bucket as the machine image. If registration is successful, they will also be used as the default kernel and ramdisk for the machine image when it's bundled, avoiding having to specify your own kernel and ramdisk on your own.

See also