Starting with VirtualBox 3.2, the VRDP server can redirect video streams from the guest to the RDP client. Video frames are compressed using the JPEG algorithm allowing a higher com- pression ratio than standard RDP bitmap compression methods. It is possible to increase the compression ratio by lowering the video quality.
The VRDP server automatically detects video streams in a guest as frequently updated rectan- gular areas. As a result, this method works with any guest operating system without having to install additional software in the guest; in particular, the Guest Additions are not required.
On the client side, however, currently only the Windows 7 Remote Desktop Connection client supports this feature. If a client does not support video redirection, the VRDP server falls back to regular bitmap updates.
The following command enables video redirection:
VBoxManage modifyvm "VM name" --vrdevideochannel on
The quality of the video is defined as a value from 10 to 100 percent, representing a JPEG compression level (where lower numbers mean lower quality but higher compression). The quality can be changed using the following command:
VBoxManage modifyvm "VM name" --vrdevideochannelquality 75
7.1.10 VRDP customization
With VirtualBox 4.0 it is possible to disable display output, mouse and keyboard input, audio, remote USB or clipboard individually in the VRDP server.
The following commands change corresponding server settings:
VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1 VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableInput=1 VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUSB=1 VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableAudio=1 VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableClipboard=1 VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUpstreamAudio=1
To reenable a feature use a similar command without the trailing 1. For example:
VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=
These properties were introduced with VirtualBox 3.2.10. However, in the 3.2.x series, it was necessary to use the following commands to alter these settings instead:
VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableInput" 1 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableUSB" 1 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableAudio" 1 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1
To reenable a feature use a similar command without the trailing 1. For example:
7.2 Teleporting
Starting with version 3.1, VirtualBox supports “teleporting” – that is, moving a virtual machine over a network from one VirtualBox host to another, while the virtual machine is running. This works regardless of the host operating system that is running on the hosts: you can teleport virtual machines between Solaris and Mac hosts, for example.
Teleporting requires that a machine be currently running on one host, which is then called the“source”. The host to which the virtual machine will be teleported will then be called the “target”; the machine on the target is then configured to wait for the source to contact the target.
The machine’s running state will then be transferred from the source to the target with minimal downtime.
Teleporting happens over any TCP/IP network; the source and the target only need to agree on a TCP/IP port which is specified in the teleporting settings.
At this time, there are a few prerequisites for this to work, however:
1. On the target host, you must configure a virtual machine in VirtualBox with exactly the same hardware settings as the machine on the source that you want to teleport. This does not apply to settings which are merely descriptive, such as the VM name, but obviously for teleporting to work, the target machine must have the same amount of memory and other hardware settings. Otherwise teleporting will fail with an error message.
2. The two virtual machines on the source and the target must share the same storage (hard disks as well as floppy and CD/DVD images). This means that they either use the same iSCSI targets or that the storage resides somewhere on the network and both hosts have access to it via NFS or SMB/CIFS.
This also means that neither the source nor the target machine can have any snapshots. Then perform the following steps:
1. On the target host, configure the virtual machine to wait for a teleport request to arrive when it is started, instead of actually attempting to start the machine. This is done with the following VBoxManage command:
VBoxManage modifyvm <targetvmname> --teleporter on --teleporterport <port>
where<targetvmname>is the name of the virtual machine on the target host and<port> is a TCP/IP port number to be used on both the source and the target hosts. For example, use 6000. For details, see chapter8.8.5,Teleporting settings, page125.
2. Start the VM on the target host. You will see that instead of actually running, it will show a progress dialog. indicating that it is waiting for a teleport request to arrive.
3. Start the machine on the source host as usual. When it is running and you want it to be teleported, issue the following command on the source host:
VBoxManage controlvm <sourcevmname> teleport --host <targethost> --port <port>
where<sourcevmname>is the name of the virtual machine on the source host (the machine that is currently running),<targethost>is the host or IP name of the target host on which the machine is waiting for the teleport request, and<port>must be the same number as specified in the command on the target host. For details, see chapter 8.13, VBoxManage controlvm, page128.
For testing, you can also teleport machines on the same host; in that case, use “localhost” as the hostname on both the source and the target host.
Note: In rare cases, if the CPUs of the source and the target are very different, tele-
porting can fail with an error message, or the target may hang. This may happen especially if the VM is running application software that is highly optimized to run on a particular CPU without correctly checking that certain CPU features are actually present. VirtualBox filters what CPU capabilities are presented to the guest operating system. Advanced users can attempt to restrict these virtual CPU capabilities with the VBoxManage --modifyvm --cpuidcommand; see chapter8.8.5, Teleporting settings, page125.
8 VBoxManage
8.1 Introduction
As briefly mentioned in chapter 1.16, Alternative front-ends, page 31, 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 VBoxHead- less server);
• control some of the more advanced and experimental configuration settings for a VM. There are two main things to keep in mind when usingVBoxManage: First,VBoxManagemust always be used with a specific “subcommand”, such as “list” or “createvm” or “startvm”. All the subcommands thatVBoxManagesupports are described in detail in chapter8,VBoxManage, page
109.
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 typeVBoxManage list vmsto 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, useVBoxManage createvmwith the--registeroption,1like this: $ VBoxManage createvm --name "SUSE 10.2" --register
VirtualBox Command Line Management Interface Version 4.2.6 (C) 2005-2012 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, useVBoxManage showvminfo; see chapter
8.5,VBoxManage showvminfo, page118for details and an example.
• To change settings while a VM is powered off, useVBoxManage modifyvm, e.g. as follows:
VBoxManage modifyvm "Windows XP" --memory "512MB"
For details, see chapter8.8,VBoxManage modifyvm, page120.
• To change the storage configuration (e.g. to add a storage controller and then a virtual disk), useVBoxManage storagectlandVBoxManage storageattach; see chapter8.19,
VBoxManage storagectl, page133and chapter 8.18,VBoxManage storageattach, page131
for details.
• To control VM operation, use one of the following:
– To start a VM that is currently powered off, use VBoxManage startvm; see chapter
8.12,VBoxManage startvm, page128for details.
– To pause or save a VM that is currently running or change some of its settings, use
VBoxManage controlvm; see chapter8.13,VBoxManage controlvm, page128for de- tails.
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.