Table of Contents
As briefly mentioned in Section 1.13, “Alternative front-ends”, VBoxManage is the command-line interface to VirtualBox. With it, you can completely control VirtualBox from the command line of your host operating system. VBoxManage supports all the features that the graphical user interface gives you access to, but it supports a lot more than that. It exposes really all the features of the virtualization engine, even those that cannot (yet) be accessed from the GUI.
You will need to use the command line if you want to
use a different user interface than the main GUI (for example, VBoxSDL or the VBoxHeadless server);
control some of the more advanced and experimental configuration settings for a VM.
There are two main things to keep in mind when using
VBoxManage
: First,
VBoxManage
must always be used with a
specific "subcommand", such as "list" or "createvm" or "startvm". All the
subcommands that VBoxManage
supports are
described in detail in Chapter 8, VBoxManage.
Second, most of these subcommands require that you specify a particular virtual machine after the subcommand. There are two ways you can do this:
You can specify the VM name, as it is shown in the VirtualBox GUI. Note that if that name contains spaces, then you must enclose the entire name in double quotes (as it is always required with command line arguments that contain spaces).
For example:
VBoxManage startvm "Windows XP"
You can specify the UUID, which is the internal unique identifier that VirtualBox uses to refer to the virtual machine. Assuming that the aforementioned VM called "Windows XP" has the UUID shown below, the following command has the same effect as the previous:
VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5
You can type VBoxManage list vms
to
have all currently registered VMs listed with all their settings,
including their respective names and UUIDs.
Some typical examples of how to control VirtualBox from the command line are listed below:
To create a new virtual machine from the command line and
immediately register it with VirtualBox, use
VBoxManage createvm
with the
--register
option,[31] like this:
$ VBoxManage createvm --name "SUSE 10.2" --register VirtualBox Command Line Management Interface Version 4.0.4 (C) 2005-2011 Oracle Corporation All rights reserved. Virtual machine 'SUSE 10.2' is created. UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5 Settings file: '/home/username/.VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'
As can be seen from the above output, a new virtual machine has been created with a new UUID and a new XML settings file.
To show the configuration of a particular VM, use
VBoxManage showvminfo
; see Section 8.4, “VBoxManage showvminfo” for details and an example.
To change settings while a VM is powered off, use
VBoxManage modifyvm
, e.g. as
follows:
VBoxManage modifyvm "Windows XP" --memory "512MB"
For details, see Section 8.7, “VBoxManage modifyvm”.
To change the storage configuration (e.g. to add a storage
controller and then a virtual disk), use VBoxManage
storagectl
and VBoxManage
storageattach
; see Section 8.17, “VBoxManage storagectl” and Section 8.16, “VBoxManage storageattach” for details.
To control VM operation, use one of the following:
To start a VM that is currently powered off, use
VBoxManage startvm
; see Section 8.10, “VBoxManage startvm” for details.
To pause or save a VM that is currently running or change
some of its settings, use VBoxManage
controlvm
; see Section 8.11, “VBoxManage controlvm” for details.