Creating a virtual machine using the VirtualBox CLI

VirtualBox is a very accessible open source virtualazition software platform. When combined with the optional free-as-in-beer guest additions, it makes for some really slick guest/host desktop integration. In my experience it is very stable and the guest machines seem to operate at native or near-native speed. While the underlying platform is excellent, the management tools aren't as advanced as what, say, VMware has to offer. Part of the problem is that thorough user documentation is hard to find, though their manual is improving.

This article describes how to create and clone a virtual machine almost entirely from the CLI. I'm going to use Fedora 11 as my guest OS and give it 1024 Megs of RAM and a 20 Gig hard drive. Of course, all of this can be done with the GUI as well, and there are other tutorials online which explain GUI configuration. The only part of these instructions that needs a GUI is the OS installation. If you use a Kickstart install disk or the Windows equivalent, you can probably do the entire installation from the command line.

We're primarily going to deal with two types of objects: VirtualBox machine entries and VirtualBox hard disk images. VirtualBox keeps track of both of these in its configuration file, which by default is ~/.VirtualBox/VirtualBox.xml. VirtualBox uses UUIDs internally to keep track of them. Most of the CLI commands can refer to objects either by UUID or by name. In these examples, I'll refer to objects by name since they're much more legible.

Here is the entire sequence for creating a VirtualMachine. A more detailed explanation follows.

VBoxManage createhd --remember --filename /path/to/hard_drive_image/FedoraTest.vdi --size 20480
VBoxManage createvm --register --name FedoraTest --ostype RedHat_64
VBoxManage modifyvm FedoraTest --hda /path/to/hard_drive_image/FedoraTest.vdi
VBoxManage modifyvm FedoraTest --memory 1024
VBoxManage modifyvm FedoraTest --dvd /path/to/installation_iso_file/Fedora-11-x86_64-DVD.iso
VBoxManage startvm FedoraTest
VBoxManage modifyvm FedoraTest --dvd none

I'll start by creating the hard drive image named /path/to/hard_drive_image/FedoraTest.vdi. By default the initial .vdi file is fairly small and it will grow as needed until it reaches it's maximum size of 20 Gigs. The --filename and --size parameters are mandatory. The --remember parameter is so the hard disk image gets added to the VirtualBox configuration file. It isn't strictly necessary since we can still refer to the image by filename.

$ VBoxManage createhd --filename /path/to/hard_drive_image/FedoraTest.vdi --size 20480 --remember
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
Disk image created. UUID: f9a22cb4-1704-48d8-be29-434ae78849c6

One thing to note about VBoxManage commands is filenames are relative to VirtualBox's home directory which by default is ~/.VirtualBox. If you want to store these large disk image files someplace else, be sure to use full pathnames like I'm doing here. My initial 20 Gig hard drive image is only 81k since nothing has been put onto it yet.

Our next step will be to create the virtual machine. Really, all this command will do is create the xml configuration file. The only mandatory parameter is --name but I'll also give it an optional --ostype parameter to give VirtualBox some hints about the guest OS. I'll also give it the --register parameter so it gets registered in the main configuration file as well. This time, it really is more important to register the object because modifications can only be made after the machine is registered. If I don't register it here, I'd need to register it using the VBoxManage registervm <UUID> command before doing anything else with it. By default, the config file will be created under ~/.VirtualBox/Machines, but this can be changed with the --basefolder or --settingsfile parameters. For this example, I'll let the file go in the default location because, unlike the hard drive images, these don't grow very big.

$ VBoxManage createvm --name FedoraTest --ostype Fedora_64 --register
Virtual machine 'FedoraTest' is created and registered.
UUID: d7a11374-ad15-4a14-b855-060692f78f5e
Settings file: '/home/nick/.VirtualBox/Machines/FedoraTest/FedoraTest.xml'

Fedora_64 is the best fit for the Fedora 11 guest OS I'm using in this example. Run VBoxManage list ostypes to see what the other options are.

Next, I'm going to make several modifications to the virtual machine I just created. I could do all this in one command, but I'll break it up to make the changes more clear. First, I'm going to add the hard drive.

$ VBoxManage modifyvm FedoraTest --hda /path/to/hard_drive_image/FedoraTest.vdi

--hda is the primary IDE master drive. By default, VirtualBox assigns its guest machines 128 Megs of RAM. 64 bit Fedora 11 won't even install with less than 256 megs, so I'm going to raise mine to a Gig.

$ VBoxManage modifyvm FedoraTest --memory 1024

Note that the --memory parameter is given in Megs. Before we can boot, we need to install an OS. To make this process completely CLI based, we could use a non-interactive installation disk here, but I'm using a generic Fedora .iso image.

$ VBoxManage modifyvm FedoraTest --dvd /path/to/installation_iso_file/Fedora-11-x86_64-DVD.iso

Conveniently, I can boot directly from the .iso without burning it to a CD first. If I wanted to boot from a physical drive, I would have specified --dvd host:/dev/dvd

At this point, I can boot the virtual machine and install the OS. A new window opens and I go through the OS installation process:

$ VBoxManage startvm FedoraTest

Once it's complete, I'll unmount the DVD image so the virtual machine boots from the hard drive.

$ VBoxManage modifyvm FedoraTest --dvd none

The most likely reason for wanting to do a CLI install is to use the guest host as some kind of server. For this, you will likely want to change the host's NIC interface from the the default mode which is NAT'd through the host OS to bridged mode:

$ VBoxManage modifyvm FedoraTest --nic1 bridged

For this to work, you will need to set up NAT port forwarding or bridging on the host OS.