The CLI works well for users who want to control a VirtualBox running on a headless server with no monitor or keyboard attached. Even desktop users, running and managing VirtualBox from the same machine, can pull a stunt or two with the CLI that they can't do in the GUI, such as shrinking or cloning virtual disks, customizing the BIOS logo, and collecting metrics data from virtual machines.

While you can create a VM from the CLI, unless you are running VirtualBox on a headless server it's easier to use the GUI. The most common VM creation options are available in the GUI, which saves a lot of time compared to creating a VM from the CLI. But once you have created a VM, you can use the CLI to tweak it as you please.

From the CLI, you control VirtualBox with the VBoxManage command. Depending on how you want to modify or control the VM, there are various sub-commands and options you can use with VBoxManage. You'll also need to identify the VM or a particular component, such as a virtual disk, that you want to control with the CLI. You can do this by specifying the name of the VM or its unique identifier (UUID). You specify the former when you create a VM; the latter is automatically assigned by VirtualBox.

To find out the UUID, use the list command followed by the type of device you want a UUID for. VBoxManage list vms prints a lot of details about all the VMs, including the assigned memory, the VM's current state (running or powered off), its UUID, and the UUID of the virtual disks attached to it:

		


			$ VBoxManage list vms

			VirtualBox Command Line Management Interface Version 2.0.2

			(C) 2005-2008 Sun Microsystems, Inc.

			All rights reserved.

			

			Name:            Fedora

			Guest OS:        Fedora

			UUID:            50da82bf-9c03-48d2-99ad-66f9885f30c1

			Config file:     /home/bodhi/.VirtualBox/Machines/Fedora/Fedora.xml

			Memory size:     128MB

			VRAM size:       8MB

			Boot menu mode:  message and menu

			ACPI:            on

			IOAPIC:          off

			PAE:             off

			Time offset:     0 ms

			Hardw. virt.ext: off

			Nested Paging:   off

			State:           powered off (since 2008-10-15T20:29:41.000000000)

			Monitor count:   1

			Floppy:          empty

			SATA:            disabled

			Primary master:  /home/bodhi/.VirtualBox/VDI/eightgig (UUID: c00ef0b0-173a-4f10-aa9b-94f38a5306af)

			NIC 1:           MAC: 0800273EBD00, Attachment: NAT, Cable connected: on, Trace: off, Type: Am79C973, Reported speed: 0 Mbps

			

Using the UUID you can modify the VM. For example, VBoxManage modifyvm 50da82bf-9c03-48d2-99ad-66f9885f30c1 -memory "512MB" increases the memory of VM to 512MB. Similarly, VBoxManage modifyvm 50da82bf-9c03-48d2-99ad-66f9885f30c1 -vram "16MB" increases video RAM to 16MB.

While the project advises you use UUIDs when working with the CLI, in this article I'll use the name of the VM instead to make it easier to read.

If your VM boots slowly, you can shave a few seconds by reducing the BIOS logo display time. VBoxManage modifyvm "Fedora" -bioslogodisplaytime 1000 sets the time to 1000ms (10 seconds). You can also replace the default Sun BIOS image with any uncompressed 256-color BMP file, using VBoxManage modifyvm "Fedora" -bioslogoimagepath path-to-the-image.

As is common with most BIOSes, the VirtualBox BIOS lets you interrupt the boot process and select a temporary boot device. This can be a potential security risk, since most computers can now boot from USB devices. VBoxManage modifyvm "Fedora" -biosbootmenu disabled prevents users from selecting a temporary boot device.

Finally, you can also change the boot order of the VM without entering the BIOS. VBoxManage modifyvm "Fedora" -boot1 dvd -boot2 disk -boot3 floppy -boot4 net makes the VM first access the DVD drive, followed by hard disk, diskette drive, and the network. You can also specify none as a boot device to leave a slot empty.

You can also configure a VM to log all network traffic. VBoxManage modifyvm "Fedora" -nictrace1 on -nictracefile1 /tmp/nictraffic.log enables the trace on the first virtual network card and logs all traffic to the file specified.

Controlling virtual disks and removable devices

In the virtual realm of VirtualBox, a VM can have three virtual hard disks -- a primary master, primary slave, and secondary slave -- with the secondary master reserved for removable devices. When you create a VM using the GUI, VirtualBox asks you to add a virtual disk using the built-in Virtual Disk Manager tool. In the example above, the Fedora VM uses an 8GB disk named "eightgig" as the primary master.

You can also create disks with the createvdi command, specifying a name and size (in MB). VBoxManage createvdi -filename fourgig -size 4096 -register creates a 4GB (4096MB) disk and registers it with VirtualBox; you need to register a disk before it can be used by a VM.

Once a disk has been created and registered you need to assign it to a VM. VBoxManage modifyvm Fedora -hdb fourgig adds the newly created disk as the primary slave disk in the Fedora VM.

As for removable devices, VirtualBox can use a registered ISO image or a physical drive as the virtual CD/DVD drive. VBoxManage modifyvm "Fedora" -dvd host:/dev/hdc attaches the physical /dev/hdc drive on the host to the VM. By default VirtualBox allows read-only access to the host drive. To write DVDs, you need to enable the experimental DVD writing support with VBoxManage modifyvm "Fedora" -dvdpassthrough on.

If you have a VM running and need to use an image temporarily, you can do so without registering it first. VBoxManage controlvm "Fedora" dvdattach path-to-ISO-image will attach the ISO to the specified VM.

Managing snapshots

One of the most useful feature of virtualization software is its ability to take snapshots of VMs. It's always a good idea to take a snapshot of a VM before making changes to it. Snapshots help on the hardware level to recover a system that has been rendered unusable due to changes to the hardware configuration, and on the software level they protect against data loss due to accidental deletion or virus.

Taking a snapshot from the VirtualBox CLI is child's play. VBoxManage snapshot "Fedora" take snap1-stable-system takes the snapshot of a stable Fedora VM when everything is working perfectly. Saving a snapshot might take some time, depending on the VM and the resources on the host. To make sure you don't make changes to a system while a snapshot is being taken, VirtualBox grays out the whole VM interface, and you cannot use it until the snapshot has been saved.

With a stable snapshot in hand, go ahead and play with the system. If you get in trouble and your machine won't boot or starts behaving abnormally, you can revert to the snapshot of the stable machine. To do this, first power off the VM with VBoxManage controlvm "Fedora" poweroff, then revert to last snapshot with VBoxManage snapshot "Fedora" discardcurrent -state. If you have multiple snapshots, you can revert to the last but one snapshot with the -all switch instead of -state.

Of course when you revert to an older state, all the changes you made since that snapshot was taken are lost, including all configuration changes and changes to old and new files. You can work around this by specifying that your data should be stored on a "writethrough" disk, which behaves like a normal disk but isn't affected by snapshots. Put another way, when you take a snapshot, VirtualBox ignores the writethrough disk. You can store all your important data and files or your complete /home directory on that disk.

To add a writethrough disk, use the -type writethough option when creating a new disk with createvdi. You can also change a disk you created earlier and make it writethrough. To do so, first unattach it from the VM with VBoxManage modifyvm "Fedora" -hdb none, and then unregister it with VBoxManage unregisterimage disk fourgig (using the name of the disk on your system in place of fourgig). Now register it back again but as a writethrough disk with VBoxManage registerimage disk "fourgig" -type writethrough. Finally, attach it back to the VM using VBoxManage modifyvm "Fedora" -hdb fourgig.

Now you can safely save data on this disk, and no matter what state the VM is in, the data will always be safe. But remember not to revert back to a state that was saved before this disk was created; if you do, VirtualBox will simply delete the disk, becase it didn't exist in that state. Also, VirtualBox doesn't currently let you take a snapshot of a VM that has a writethrough disk attached, so you have to unattach a writethough disk before saving the state of the VM and then reattach it. I hope in upcoming VirtualBox versions the presence of a writethrough disk will have no influence on the snapshot process.

Measuring performance

VirtualBox can monitor the performance and resource utilization of both the host and the VM. VBoxManage metrics list displays all the metrics VirtualBox can monitor for both guest and host. Some of the metrics it can monitor are CPU/Load/User (percentage of processor time spent in user mode both by guest and VM), CPU/MHz (average of current frequency of all processors), RAM/Usage/Free (physical memory currently available to applications), and RAM/Usage/Used (size of resident portion of VM process in memory).

VBoxManage metrics setup -period 10 -samples 5 host activates the process of collecting the data by specifying the interval after which samples are collected (10 seconds) and how many of them it should retain (5). You can replace host with the name of the VM if you want to activate the process for the VM. You can also limit the metrics monitored by specifying them. For example, to collect processor and memory information about the Fedora VM, type VBoxManage metrics setup -period 10 -samples 5 "Fedora" CPU/Load/User, RAM/Usage/Used.

The collected data is retrieved with the query command. VBoxManage metrics query host CPU/Load/User displays the processor information for the host. If you don't mention the name of the metric, values of all metrics are displayed.

If you wish to observe a continuous stream of metrics, use a collect command such as VBoxManage metrics collect -period 3 -samples 5 "Fedora" CPU/Load/User,RAM/Usage/Used, which displays the processor and RAM usage for the VM every three seconds until the process is terminated with the Ctrl-C key combination.

Conclusion

VirtualBox keeps its GUI simple by packing in only the most used functions, and offers complete control to users from the CLI. The CLI is essential for controlling VirtualBox VMs remotely but is also useful for accessing some advanced features locally, such as measuring performance. You can also save yourself some time by using the CLI when performing repetetive operations that require multiple commands. For example, if you are a developer and revert back to a particular state often, you can throw the commands used to revert to a snapshot into a script. All in all, VirtualBox's comprehesive CLI is impressive, and can improve your productivity.