I recently abandoned VMWare Fusion for Sun Microsystems’ VirtualBox and I wanted to share some command line tools for working with virtual machines.

First be aware that if you are using a Mac, like I am, you can only access those machines already installed for your user.  This is important because if you attempt to execute these commands as the root user your machines will not be located by the command-line interface (CLI) and you’ll see some nasty and poorly explained errors.

The most important command is VBoxManage.  VBoxManage is the parent command for many of the examples I’m going to show you.

Do you want to see some info about your installed machines?  You use the following command:

VBoxManage list vms

I only have a Windows XP Pro machine, so the output of this command looks like this:

VirtualBox Command Line Management Interface Version 2.0.2
(C) 2005-2008 Sun Microsystems, Inc.
All rights reserved.

Name:            Win_XP_Pro
Guest OS:        Windows XP
UUID:            7de0279c-0f4b-4253-aafb-97b368a53216
Config file:     /Users/devon/Library/VirtualBox/Machines/Win_XP_Pro/Win_XP_Pro.xml
Memory size:     512MB
VRAM size:       16MB
Boot menu mode:  message and menu
ACPI:            off
IOAPIC:          off
PAE:             off
Time offset:     0 ms
Hardw. virt.ext: off
Nested Paging:   off
State:           powered off (since 2008-10-29T16:13:02.000000000)
Monitor count:   1
Floppy:          empty
SATA:            disabled
Primary master:  /Users/devon/Library/VirtualBox/Machines/Win_XP_Pro/Snapshots/{f7590e42-38a4-4099-9d9e-dbe02fe5a6e6}.vdi (UUID: f7590e42-38a4-4099-9d9e-dbe02fe5a6e6)
DVD:             empty
NIC 1:           MAC: 080027E05975, Attachment: NAT, Cable connected: off, Trace: off (file: none), Type: 82543GC, Reported speed: 0 Mbps
NIC 2:           disabled
NIC 3:           disabled
NIC 4:           disabled
UART 1:          disabled
UART 2:          disabled
Audio:           disabled (Driver: Unknown, Controller: Unknown)
Clipboard Mode:  Bidirectional
VRDP:            disabled
USB:             enabled

USB Device Filters:

Index:            0
Active:           yes
Name:             JMicron USB to ATA/ATAPI Bridge [0100]
VendorId:         152D
ProductId:        2338
Revision:         0100
Manufacturer:     JMicron
Product:          USB to ATA/ATAPI Bridge
Remote:           no
Serial Number:    885345113712

Shared folders:  <none>

Guest:

Statistics update:                   disabled

Snapshots:

   Name: Snapshot 1 (UUID: 5048d617-804b-48fa-a170-7933f1388bc7)

In the output above you can see the allocated amount of RAM, VRAM (Video RAM), and the state which is currently “powered off” – you can also see how long it’s been powered off.

You can also start, stop, restart, suspend, and restore a suspended machine using the VBoxManage controlvm command:

VBoxManage controlvm “Win_XP_Pro” [poweroff|pause|resume|reset]

This command, using the name of my virtual machine, can restart, shut down, pause or resume the machine.  And there are many other options available, but this is kind of the quick and dirty how-to, so check out the command directly for those options.  Of course, if you simply want to start a machine use:

VBoxManage startvm “Win_XP_Pro”

You can use the VBoxManage modifyvm command to change all kinds of things including the name, allocated RAM, VRAM, ACPI on\off, number of monitors, BIOS logo settings, availability and number of SATA devices, boot priority, etc.  Here are some examples:

VBoxManage modifyvm Win_XP_Pro -name “NEW_NAME_XP”

VBoxManage modifyvm Win_XP_Pro -memory “1024MB”

VBoxManage modifyvm Win_XP_Pro -vram “32MB”

VBoxManage modifyvm Win_XP_Pro -sataportcount “12″

VBoxManage modifyvm Win_XP_Pro -acpi off

VBoxManage modifyvm Win_XP_Pro -boot1 dvd -boot2 disk -boot3 floppy -boot4 net

You can also use this command to copy the disk image, which is in .vdi format using the command:

VBoxManage clonevdi /path/to/VDINAME.vdi CLONEDFILENAME.vdi

This command will create an exact duplicate of the virtual machine’s drive.  You will have to use the complete path to the .vdi and to the output file, but the output of VBoxManage list vms can give you that info.

You can do some more advanced things too.  Let’s add an iSCSI connection to a local server:

VBoxManage addiscsidisk -server 192.168.0.2 -target “Win_XP_Pro” -port 10237 -username diskuser -password vgy7%TGB

the above command adds a connection to an iSCSI disk at the IP 192.168.0.2 on port 10237 using diskuser as it’s username and the password vgy7%TGB and it is going to attempt to add it to Win_XP_Pro.

One of the more interesting applications of the VBoxManage CLI is it’s ability to record and present statistics on virtual machines that can be analyzed.

VBoxManage metrics setup -period 5 -sample 100 Win_XP_Pro

this command activates the recording of statistical information on the Win_XP_Pro machine at an interval of 5 seconds and tells the CLI to record 100 samples.  When you want to view this data you can use the following command for all the information:

VBoxManage metrics query Win_XP_Pro

or, if you only want CPU and Memory info:

VBoxManage metrics query Win_XP_Pro CPU/Load/User, RAM/Usage/Used

Those are some quick examples, but you should investigate the CLI for this if you’re interested.