8.2 Commands overview
When running VBoxManage without parameters or when supplying an invalid command line, the below syntax diagram will be shown. Note that the output will be slightly different depending on the host platform; when in doubt, check the output ofVBoxManagefor the commands available on your particular host.
Usage:
VBoxManage [<general option>] <command> General Options:
[-v|--version] print version number and exit [-q|--nologo] suppress the logo
[--settingspw <pw>] provide the settings password
[--settingspwfile <file>] provide a file containing the settings password Commands:
list [--long|-l] vms|runningvms|ostypes|hostdvds|hostfloppies| bridgedifs|dhcpservers|hostinfo|
hostcpuids|hddbackends|hdds|dvds|floppies| usbhost|usbfilters|systemproperties|extpacks| groups
showvminfo <uuid>|<name> [--details] [--machinereadable] showvminfo <uuid>|<name> --log <idx> registervm <filename>
createvm --name <name> [--groups <group>, ...] [--ostype <ostype>] [--register] [--basefolder <path>] [--uuid <uuid>] modifyvm <uuid|name> [--name <name>] [--groups <group>, ...] [--ostype <ostype>] [--memory <memorysize in MB>] [--pagefusion on|off] [--vram <vramsize in MB>] [--acpi on|off] [--ioapic on|off] [--pae on|off] [--hpet on|off] [--hwvirtex on|off] [--hwvirtexexcl on|off] [--nestedpaging on|off] [--largepages on|off] [--vtxvpid on|off] [--synthcpu on|off]
[--cpuidset <leaf> <eax> <ebx> <ecx> <edx>] [--cpuidremove <leaf>] [--cpuidremoveall] [--hardwareuuid <uuid>] [--cpus <number>] [--cpuhotplug on|off] [--plugcpu <id>] [--unplugcpu <id>] [--cpuexecutioncap <1-100>] [--rtcuseutc on|off] [--monitorcount <number>] [--accelerate3d on|off] [--firmware bios|efi|efi32|efi64] [--chipset ich9|piix3] [--bioslogofadein on|off] [--bioslogofadeout on|off] [--bioslogodisplaytime <msec>] [--bioslogoimagepath <imagepath>] [--biosbootmenu disabled|menuonly|messageandmenu] [--biossystemtimeoffset <msec>] [--biospxedebug on|off] [--boot<1-4> none|floppy|dvd|disk|net>] [--nic<1-N> none|null|nat|bridged|intnet| generic] [--nictype<1-N> Am79C970A|Am79C973] [--cableconnected<1-N> on|off] [--nictrace<1-N> on|off] [--nictracefile<1-N> <filename>] [--nicproperty<1-N> name=[value]] [--nicspeed<1-N> <kbps>] [--nicbootprio<1-N> <priority>] [--nicpromisc<1-N> deny|allow-vms|allow-all] [--nicbandwidthgroup<1-N> none|<name>] [--bridgeadapter<1-N> none|<devicename>] [--intnet<1-N> <network name>]
[--natnet<1-N> <network>|default] [--nicgenericdrv<1-N> <driver> [--natsettings<1-N> [<mtu>],[<socksnd>], [<sockrcv>],[<tcpsnd>], [<tcprcv>]] [--natpf<1-N> [<rulename>],tcp|udp,[<hostip>], <hostport>,[<guestip>],<guestport>] [--natpf<1-N> delete <rulename>]
[--nattftpprefix<1-N> <prefix>] [--nattftpfile<1-N> <file>] [--nattftpserver<1-N> <ip>] [--natbindip<1-N> <ip> [--natdnspassdomain<1-N> on|off] [--natdnsproxy<1-N> on|off] [--natdnshostresolver<1-N> on|off] [--nataliasmode<1-N> default|[log],[proxyonly], [sameports]] [--macaddress<1-N> auto|<mac>] [--mouse ps2|usb|usbtablet [--keyboard ps2|usb
[--uart<1-N> off|<I/O base> <IRQ>] [--uartmode<1-N> disconnected|
server <pipe>| client <pipe>| file <file>| <devicename>] [--lpt<1-N> off|<I/O base> <IRQ>] [--lptmode<1-N> <devicename>] [--guestmemoryballoon <balloonsize in MB>] [--gueststatisticsinterval <seconds>] [--audio none|null|dsound|solaudio|oss| oss|coreaudio] [--audiocontroller ac97|hda|sb16] [--clipboard disabled|hosttoguest|guesttohost| bidirectional] [--draganddrop disabled|hosttoguest [--vrde on|off] [--vrdeextpack default|<name> [--vrdeproperty <name=[value]>] [--vrdeport <hostport>] [--vrdeaddress <hostip>] [--vrdeauthtype null|external|guest] [--vrdeauthlibrary default|<name> [--vrdemulticon on|off] [--vrdereusecon on|off] [--vrdevideochannel on|off] [--vrdevideochannelquality <percent>] [--usb on|off] [--usbehci on|off] [--snapshotfolder default|<path>] [--teleporter on|off] [--teleporterport <port>] [--teleporteraddress <address|empty> [--teleporterpassword <password>] [--teleporterpasswordfile <file>|stdin] [--tracing-enabled on|off] [--tracing-config <config-string>] [--tracing-allow-vm-access on|off] [--autostart-enabled on|off] [--autostart-delay <seconds>] clonevm <uuid>|<name> [--snapshot <uuid>|<name>] [--mode machine|machineandchildren|all] [--options link|keepallmacs|keepnatmacs| keepdisknames] [--name <name>] [--groups <group>, ...] [--basefolder <basefolder>] [--uuid <uuid>] [--register] import <ovf/ova> [--dry-run|-n] [--options keepallmacs|keepnatmacs]
[more options]
(run with -n to have options displayed for a particular OVF)
export <machines> --output|-o <name>.<ovf/ova> [--legacy09|--ovf09|--ovf10|--ovf20] [--manifest]
[--vsys <number of virtual system>] [--product <product name>] [--producturl <product url>] [--vendor <vendor name>] [--vendorurl <vendor url>] [--version <version info>] [--eula <license text>] [--eulafile <filename>] startvm <uuid>|<name>... [--type gui|sdl|headless] controlvm <uuid>|<name> pause|resume|reset|poweroff|savestate| acpipowerbutton|acpisleepbutton| keyboardputscancode <hex> [<hex> ...]| setlinkstate<1-N> on|off | nic<1-N> null|nat|bridged|intnet|generic [<devicename>] | nictrace<1-N> on|off nictracefile<1-N> <filename> nicproperty<1-N> name=[value] natpf<1-N> [<rulename>],tcp|udp,[<hostip>], <hostport>,[<guestip>],<guestport> natpf<1-N> delete <rulename>
guestmemoryballoon <balloonsize in MB>] gueststatisticsinterval <seconds>] usbattach <uuid>|<address> | usbdetach <uuid>|<address> | clipboard disabled|hosttoguest|guesttohost| bidirectional] draganddrop disabled|hosttoguest] vrde on|off | vrdeport <port> | vrdeproperty <name=[value]> | vrdevideochannelquality <percent> setvideomodehint <xres> <yres> <bpp>
[[<display>] [<enabled:yes|no> [<xorigin> <yorigin>]]] | screenshotpng <file> [display] |
setcredentials <username>
--passwordfile <file> | <password> <domain>
[--allowlocallogon <yes|no>] | teleport --host <name> --port <port>
[--maxdowntime <msec>] [--passwordfile <file> | --password <password>] plugcpu <id> unplugcpu <id> cpuexecutioncap <1-100> discardstate <uuid>|<name>
adoptstate <uuid>|<name> <state_file> snapshot <uuid>|<name>
take <name> [--description <desc>] [--pause] | delete <uuid>|<name> |
restorecurrent | edit <uuid>|<name>|--current [--name <name>] [--description <desc>] | list [--details|--machinereadable] showvminfo <uuid>|<name>
closemedium disk|dvd|floppy <uuid>|<filename> [--delete] storageattach <uuid|vmname> --storagectl <name> [--port <number>] [--device <number>] [--type dvddrive|hdd|fdd] [--medium none|emptydrive|additions| <uuid>|<filename>|host:<drive>|iscsi] [--mtype normal|writethrough|immutable|shareable| readonly|multiattach] [--comment <text>] [--setuuid <uuid>] [--setparentuuid <uuid>] [--passthrough on|off] [--tempeject on|off] [--nonrotational on|off] [--discard on|off] [--bandwidthgroup <name>] [--forceunmount] [--server <name>|<ip>] [--target <target>] [--tport <port>] [--lun <lun>] [--encodedlun <lun>] [--username <username>] [--password <password>] [--initiator <initiator>] [--intnet] storagectl <uuid|vmname> --name <name> [--add ide|sata|scsi|floppy|sas] [--controller LSILogic|LSILogicSAS|BusLogic| IntelAHCI|PIIX3|PIIX4|ICH6|I82078] [--sataportcount <1-30>] [--hostiocache on|off] [--bootable on|off] [--remove] bandwidthctl <uuid|vmname>
add <name> --type disk|network
--limit <megabytes per second>[k|m|g|K|M|G] | set <name>
--limit <megabytes per second>[k|m|g|K|M|G] | remove <name> |
list [--machinereadable]
(limit units: k=kilobit, m=megabit, g=gigabit, K=kilobyte, M=megabyte, G=gigabyte) showhdinfo <uuid>|<filename>
createhd --filename <filename>
[--size <megabytes>|--sizebyte <bytes>] [--diffparent <uuid>|<filename>
[--format VDI|VMDK|VHD] (default: VDI) [--variant Standard,Fixed,Split2G,Stream,ESX] modifyhd <uuid>|<filename>
[--type normal|writethrough|immutable|shareable| readonly|multiattach]
[--autoreset on|off] [--compact]
[--resize <megabytes>|--resizebyte <bytes>] clonehd <uuid>|<filename> <uuid>|<outputfile>
[--format VDI|VMDK|VHD|RAW|<other>]
[--variant Standard,Fixed,Split2G,Stream,ESX] [--existing]
convertfromraw <filename> <outputfile> [--format VDI|VMDK|VHD]
[--variant Standard,Fixed,Split2G,Stream,ESX] [--uuid <uuid>]
convertfromraw stdin <outputfile> <bytes> [--format VDI|VMDK|VHD] [--variant Standard,Fixed,Split2G,Stream,ESX] [--uuid <uuid>] getextradata global|<uuid>|<name> <key>|enumerate setextradata global|<uuid>|<name> <key>
[<value>] (no value deletes key) setproperty machinefolder default|<folder> |
vrdeauthlibrary default|<library> | websrvauthlibrary default|null|<library> | vrdeextpack null|<library> |
autostartdbpath null|<folder> | loghistorycount <value>
usbfilter add <index,0-N>
--target <uuid>|<name>|global --name <string>
--action ignore|hold (global filters only) [--active yes|no] (yes)
[--vendorid <XXXX>] (null) [--productid <XXXX>] (null) [--revision <IIFF>] (null) [--manufacturer <string>] (null) [--product <string>] (null)
[--remote yes|no] (null, VM filters only) [--serialnumber <string>] (null)
[--maskedinterfaces <XXXXXXXX>] usbfilter modify <index,0-N>
--target <uuid>|<name>|global [--name <string>]
[--action ignore|hold] (global filters only) [--active yes|no] [--vendorid <XXXX>|""] [--productid <XXXX>|""] [--revision <IIFF>|""] [--manufacturer <string>|""] [--product <string>|""]
[--remote yes|no] (null, VM filters only) [--serialnumber <string>|""]
[--maskedinterfaces <XXXXXXXX>] usbfilter remove <index,0-N>
--target <uuid>|<name>|global sharedfolder add <vmname>|<uuid>
[--transient] [--readonly] [--automount] sharedfolder remove <vmname>|<uuid>
--name <name> [--transient] debugvm <uuid>|<name>
dumpguestcore --filename <name> | info <item> [args] |
injectnmi |
log [--release|--debug] <settings> ...| logdest [--release|--debug] <settings> ...| logflags [--release|--debug] <settings> ...| osdetect |
osinfo |
getregisters [--cpu <id>] <reg>|all ... | setregisters [--cpu <id>] <reg>=<value> ... | show [--human-readable|--sh-export|--sh-eval|
--cmd-set]
<logdbg-settings|logrel-settings> [[opt] what ...] |
statistics [--reset] [--pattern <pattern>] [--descriptions]
metrics list [*|host|<vmname> [<metric_list>]] (comma-separated) metrics setup
[--period <seconds>] (default: 1) [--samples <count>] (default: 1) [--list]
[*|host|<vmname> [<metric_list>]] metrics query [*|host|<vmname> [<metric_list>]] metrics enable [--list] [*|host|<vmname> [<metric_list>]] metrics disable [--list] [*|host|<vmname> [<metric_list>]] metrics collect
[--period <seconds>] (default: 1) [--samples <count>] (default: 1) [--list]
[--detach]
[*|host|<vmname> [<metric_list>]] dhcpserver add|modify --netname <network_name> |
[--ip <ip_address> --netmask <network_mask> --lowerip <lower_ip> --upperip <upper_ip>] [--enable | --disable]
dhcpserver remove --netname <network_name> | extpack install [--replace] <tarball> |
uninstall [--force] <name> | cleanup
Each time VBoxManage is invoked, only one command can be executed. However, a command might support several subcommands which then can be invoked in one single call. The following sections provide detailed reference information on the different commands.
8.3 General options
• --version: show the version of this tool and exit.
• --nologo: suppress the output of the logo information (useful for scripts) • --settingspw: specifiy a settings password
• --settingspwfile: specify a file containing the settings password.
The settings password is used for certain settings which need to be stored encrypted for secu- rity reasons. At the moment, the only encrypted setting is the iSCSI initiator secret (see chapter
8.18,VBoxManage storageattach, page131for details). As long as no settings password is speci- fied, this information is stored inplain text. After using the--settingspw|--settingspwfile option once, it must be always used, otherwise the encrypted setting cannot be unencrypted.
8.4 VBoxManage list
The list command gives relevant information about your system and information about VirtualBox’s current settings.
The following subcommands are available withVBoxManage list:
• vmslists all virtual machines currently registered with VirtualBox. By default this displays a compact list with each VM’s name and UUID; if you also specify--longor-l, this will be a detailed list as with theshowvminfocommand (see below).
• runningvmslists all currently running virtual machines by their unique identifiers (UUIDs) in the same format as withvms.
• ostypeslists all guest operating systems presently known to VirtualBox, along with the identifiers used to refer to them with themodifyvmcommand.
• hostdvds,hostfloppies, respectively, list DVD, floppy, bridged networking and host-only networking interfaces on the host, along with the name used to access them from within VirtualBox.
• bridgedifs,hostonlyifsanddhcpservers, respectively, list bridged network interfaces, host-only network interfaces and DHCP servers currently available on the host. Please see chapter6,Virtual networking, page89for details on these.
• hostinfo displays information about the host system, such as CPUs, memory size and operating system version.
• hostcpuidsdumps the CPUID parameters for the host CPUs. This can be used for a more fine grained analyis of the host’s virtualization capabilities.
• hddbackends lists all known virtual disk back-ends of VirtualBox. For each such format (such as VDI, VMDK or RAW), this lists the back-end’s capabilities and configuration. • hdds,dvdsandfloppiesall give you information about virtual disk images currently in
use by VirtualBox, including all their settings, the unique identifiers (UUIDs) associated with them by VirtualBox and all files associated with them. This is the command-line equivalent of the Virtual Media Manager; see chapter5.3,The Virtual Media Manager, page
80.
• usbhostsupplies information about USB devices attached to the host, notably information useful for constructing USB filters and whether they are currently in use by the host.
• usbfilterslists all global USB filters registered with VirtualBox – that is, filters for devices which are accessible to all virtual machines – and displays the filter parameters.
• systempropertiesdisplays some global VirtualBox settings, such as minimum and maxi- mum guest RAM and virtual hard disk size, folder settings and the current authentication library in use.
• extpacksdisplays all VirtualBox extension packs currently installed; see chapter1.5,In- stalling VirtualBox and extension packs, page 15 and chapter 8.36, VBoxManage extpack, page147for more information.
8.5 VBoxManage showvminfo
Theshowvminfo command shows information about a particular virtual machine. This is the same information asVBoxManage list vms --longwould show for all virtual machines.
You will get information similar to the following:
$ VBoxManage showvminfo "Windows XP"
VirtualBox Command Line Management Interface Version 4.2.6 (C) 2005-2012 Oracle Corporation
All rights reserved. Name: Windows XP Guest OS: Other/Unknown
UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
Config file: /home/username/.VirtualBox/Machines/Windows XP/Windows XP.xml Memory size: 512MB
VRAM size: 12MB Number of CPUs: 2 Synthetic Cpu: off
Boot menu mode: message and menu Boot Device (1): DVD
Boot Device (2): HardDisk Boot Device (3): Not Assigned Boot Device (4): Not Assigned ACPI: on
IOAPIC: on
PAE: on
Time offset: 0 ms Hardw. virt.ext: on
Hardw. virt.ext exclusive: on Nested Paging: on
VT-x VPID: off
State: powered off (since 2009-10-20T14:52:19.000000000) Monitor count: 1
3D Acceleration: off 2D Video Acceleration: off Teleporter Enabled: off Teleporter Port: 0 Teleporter Address: Teleporter Password:
Storage Controller (0): IDE Controller Storage Controller Type (0): PIIX4
Storage Controller (1): Floppy Controller 1 Storage Controller Type (1): I82078
IDE Controller (0, 0): /home/user/windows.vdi (UUID: 46f6e53a-4557-460a-9b95-68b0f17d744b) IDE Controller (0, 1): /home/user/openbsd-cd46.iso (UUID: 4335e162-59d3-4512-91d5-b63e94eebe0b) Floppy Controller 1 (0, 0): /home/user/floppy.img (UUID: 62ac6ccb-df36-42f2-972e-22f836368137) NIC 1: disabled NIC 2: disabled NIC 3: disabled NIC 4: disabled NIC 5: disabled NIC 6: disabled
NIC 7: disabled NIC 8: disabled UART 1: disabled UART 2: disabled
Audio: disabled (Driver: Unknown) Clipboard Mode: Bidirectional
VRDE: disabled USB: disabled USB Device Filters: <none>
Shared folders: <none>
Statistics update: disabled
8.6 VBoxManage registervm / unregistervm
Theregistervmcommand allows you to import a virtual machine definition in an XML file into VirtualBox. The machine must not conflict with one already registered in VirtualBox and it may not have any hard or removable disks attached. It is advisable to place the definition file in the machines folder before registering it.
Note: When creating a new virtual machine withVBoxManage createvm(see below), you can directly specify the--registeroption to avoid having to register it separately. Theunregistervmcommand unregisters a virtual machine. If--deleteis also specified, the following files will automatically be deleted as well:
1. all hard disk image files, including differencing files, which are used by the machine and not shared with other machines;
2. saved state files that the machine created, if any (one if the machine was in “saved” state and one for each online snapshot);
3. the machine XML file and its backups; 4. the machine log files, if any;
5. the machine directory, if it is empty after having deleted all the above.
8.7 VBoxManage createvm
This command creates a new XML virtual machine definition file.
The--name <name>parameter is required and must specify the name of the machine. Since this name is used by default as the file name of the settings file (with the extension.xml) and the machine folder (a subfolder of the.VirtualBox/Machinesfolder), it must conform to your host operating system’s requirements for file name specifications. If the VM is later renamed, the file and folder names will change automatically.
However, if the --basefolder <path> option is used, the machine folder will be named <path>. In this case, the names of the file and the folder will not change if the virtual machine is renamed.
By default, this command only creates the XML file without automatically registering the VM with your VirtualBox installation. To register the VM instantly, use the optional --register option, or runVBoxManage registervmseparately afterwards.
8.8 VBoxManage modifyvm
This command changes the properties of a registered virtual machine which is not running. Most of the properties that this command makes available correspond to the VM settings that VirtualBox graphical user interface displays in each VM’s “Settings” dialog; these were described in chapter3,Configuring virtual machines, page43. Some of the more advanced settings, how- ever, are only available through theVBoxManageinterface.
These commands require that the machine is powered off (neither running nor in “saved” state). Some machine settings can also be changed while a machine is running; those settings will then have a corresponding subcommand with the VBoxManage controlvm subcommand (see chapter8.13,VBoxManage controlvm, page128).
8.8.1 General settings
The following general settings are available throughVBoxManage modifyvm:
• --name <name>: This changes the VM’s name and possibly renames the internal virtual machine files, as described withVBoxManage createvmabove.
• --ostype <ostype>: This specifies what guest operating system is supposed to run in the VM. To learn about the various identifiers that can be used here, use VBoxManage list ostypes.
• --memory <memorysize>: This sets the amount of RAM, in MB, that the virtual machine should allocate for itself from the host. See the remarks in chapter1.7,Creating your first virtual machine, page17for more information.
• --vram <vramsize>: This sets the amount of RAM that the virtual graphics card should have. See chapter3.5,Display settings, page49for details.
• --acpi on|off;--ioapic on|off: These two determine whether the VM should have ACPI and I/O APIC support, respectively; see chapter3.4.1,“Motherboard” tab, page47for details.
• --hardwareuuid <uuid>: The UUID presented to the guest via memory tables (DMI/SMBIOS), hardware and guest properties. By default this is the same as the VM uuid. Useful when cloning a VM. Teleporting takes care of this automatically.
• --cpus <cpucount>: This sets the number of virtual CPUs for the virtual machine (see chapter3.4.2, “Processor” tab, page48). If CPU hot-plugging is enabled (see below), this then sets the maximum number of virtual CPUs that can be plugged into the virtual ma- chines.
• --rtcuseutc on|off: This option lets the real-time clock (RTC) operate in UTC time (see chapter3.4.1,“Motherboard” tab, page47).
• --cpuhotplug on|off: This enables CPU hot-plugging. When enabled, virtual CPUs can be added to and removed from a virtual machine while it is running. See chapter9.5,CPU hot-plugging, page155for more information.
• --plugcpu|unplugcpu <id>: If CPU hot-plugging is enabled (see above), this adds a virtual CPU to the virtual machines (or removes one). <id> specifies the index of the virtual CPU to be added or removed and must be a number from 0 to the maximum no. of CPUs configured with the--cpusoption. CPU 0 can never be removed.
• --cpuexecutioncap <1-100>: This setting controls how much cpu time a virtual CPU can use. A value of 50 implies a single virtual CPU can use up to 50% of a single host CPU.
• --synthcpu on|off: This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow live migration between host systems that differ significantly. • --pae on|off: This enables/disables PAE (see chapter3.4.2,“Processor” tab, page48). • --hpet on|off: This enables/disables a High Precision Event Timer (HPET) which can
replace the legacy system timers. This is turned off by default. Note that Windows supports a HPET only from Vista onwards.
• --hwvirtex on|off: This enables or disables the use of hardware virtualization exten- sions (Intel VT-x or AMD-V) in the processor of your host system; see chapter10.3,Hard- ware vs. software virtualization, page183.
• --hwvirtexexcl on|off: This specifies whether VirtualBox will make exclusive use of the hardware virtualization extensions (Intel VT-x or AMD-V) in the processor of your host system; see chapter10.3, Hardware vs. software virtualization, page183. If you wish to simultaneously share these extensions with other hypervisors, then you must disable this setting. Doing so has negative performance implications.
• --nestedpaging on|off: If hardware virtualization is enabled, this additional setting enables or disables the use of the nested paging feature in the processor of your host system; see chapter10.3,Hardware vs. software virtualization, page183.
• --largepages on|off: If hardware virtualization and nested paging are enabled, for Intel VT-x only, an additional performance improvement of up to 5% can be obtained by enabling this setting. This causes the hypervisor to use large pages to reduce TLB use and overhead. • --vtxvpid on|off: If hardware virtualization is enabled, for Intel VT-x only, this addi- tional setting enables or disables the use of the tagged TLB (VPID) feature in the processor of your host system; see chapter10.3,Hardware vs. software virtualization, page183. • --accelerate3d on|off: This enables, if the Guest Additions are installed, whether hard-
ware 3D acceleration should be available; see chapter 4.4.1, Hardware 3D acceleration (OpenGL and Direct3D 8/9), page69.
• You can influence the BIOS logo that is displayed when a virtual machine starts up with a number of settings. Per default, a VirtualBox logo is displayed.