8.13. VBoxManage controlvm

VBoxManage controlvm <vm> pause temporarily puts a virtual machine on hold, without changing its state for good. The VM window will be painted in gray to indicate that the VM is currently paused. (This is equivalent to selecting the "Pause" item in the "Machine" menu of the GUI).

Use VBoxManage controlvm <vm> resume to undo a previous pause command. (This is equivalent to selecting the "Resume" item in the "Machine" menu of the GUI.)

VBoxManage controlvm <vm> reset has the same effect on a virtual machine as pressing the "Reset" button on a real computer: a cold reboot of the virtual machine, which will restart and boot the guest operating system again immediately. The state of the VM is not saved beforehand, and data may be lost. (This is equivalent to selecting the "Reset" item in the "Machine" menu of the GUI).

VBoxManage controlvm <vm> poweroff has the same effect on a virtual machine as pulling the power cable on a real computer. Again, the state of the VM is not saved beforehand, and data may be lost. (This is equivalent to selecting the "Close" item in the "Machine" menu of the GUI or pressing the window's close button, and then selecting "Power off the machine" in the dialog).

After this, the VM's state will be "Powered off". From there, it can be started again; see Section 8.12, “VBoxManage startvm”.

VBoxManage controlvm <vm> savestate will save the current state of the VM to disk and then stop the VM. (This is equivalent to selecting the "Close" item in the "Machine" menu of the GUI or pressing the window's close button, and then selecting "Save the machine state" in the dialog.)

After this, the VM's state will be "Saved". From there, it can be started again; see Section 8.12, “VBoxManage startvm”.

VBoxManage controlvm <vm> acpipowerbutton will send an ACPI shutdown signal to the VM, as if the power button on a real computer had been pressed. So long as the VM is running a fairly modern guest operating system providing ACPI support, this should trigger a proper shutdown mechanism from within the VM.

VBoxManage controlvm <vm> keyboardputscancode <hex> [<hex>...] Sends commands using keycodes to the VM. Keycodes are documented in the public domain, e.g. http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html.

VBoxManage controlvm "VM name" teleport --hostname <name> --port <port> [--passwordfile <file> | --password <password>] makes the machine the source of a teleporting operation and initiates a teleport to the given target. See Section 7.2, “Teleporting” for an introduction. If the optional password is specified, it must match the password that was given to the modifyvm command for the target machine; see Section 8.8.6, “Teleporting settings” for details.

The setlinkstate<1-N> operation connects or disconnects virtual network cables from their network interfaces.

nic<1-N> null|nat|bridged|intnet|hostonly|generic|natnetwork[<devicename>]: specifies the type of networking that should be made available on the specified VM virtual network card. They can be: not connected to the host (null), use network address translation (nat), bridged networking (bridged) or communicate with other virtual machines using internal networking (intnet) or host-only networking (hostonly) or natnetwork networking (natnetwork) or access to rarely used sub-modes (generic). These options correspond to the modes which are described in detail in Section 6.2, “Introduction to networking modes”.

With the "nictrace" options, you can optionally trace network traffic by dumping it to a file, for debugging purposes.

With nictrace<1-N> on|off, you can enable network tracing for a particular virtual network card.

If enabled, you must specify with --nictracefile<1-N> <filename> the pathname of the file to which the trace should be logged.

nicpromisc<1-N> deny|allow-vms|allow-all: This specifies how the promiscious mode is handled for the specified VM virtual network card. This setting is only relevant for bridged networking. deny (default setting) hides any traffic not intended for this VM. allow-vms hides all host traffic from this VM but allows the VM to see traffic from/to other VMs. allow-all removes this restriction completely.

nicproperty<1-N> <paramname>="paramvalue": This option, in combination with "nicgenericdrv" enables you to pass parameters to rarely-used network backends.

Those parameters are backend engine-specific, and are different between UDP Tunnel and the VDE backend drivers. For example, please see Section 6.8, “UDP Tunnel networking”.

natpf<1-N> [<name>],tcp|udp,[<hostip>],<hostport>,[<guestip>], <guestport>: This option specifies a NAT port-forwarding rule (please see Section 6.3.1, “Configuring port forwarding with NAT” for details).

natpf<1-N> delete <name>: This option deletes a NAT port-forwarding rule (please see Section 6.3.1, “Configuring port forwarding with NAT” for details).

The guestmemoryballoon<balloon size in MB> operation changes the size of the guest memory balloon, that is, memory allocated by the VirtualBox Guest Additions from the guest operating system and returned to the hypervisor for re-use by other virtual machines. This must be specified in megabytes. For details, see Section 4.9.1, “Memory ballooning”.

usbattach<uuid|address> [--capturefile <filename>]

and usbdetach <uuid|address> [--capturefile <filename>] make host USB devices visible/invisible to the virtual machine on the fly, without the need for creating filters first. The USB devices can be specified by UUID (unique identifier) or by address on the host system. Use the --capturefile option to specify the absolute path of a file for writing activity logging data.

You can use VBoxManage list usbhost to locate this information.

audioin on: With this setting, you can select whether capturing audio from the host is enabled or disabled.

audioout on: With this setting, you can select whether audio playback from the guest is enabled or disabled.

clipboard disabled|hosttoguest|guesttohost|bidirectional: With this setting, you can select if and how the guest or host operating system's clipboard should be shared with the host or guest; see Section 3.4, “General settings”. This requires that the Guest Additions be installed in the virtual machine.

draganddrop disabled|hosttoguest|guesttohost|bidirectional: With this setting, you can select the current drag and drop mode being used between the host and the virtual machine; see Section 4.4, “Drag and Drop”. This requires that the Guest Additions be installed in the virtual machine.

vrde on|off lets you enable or disable the VRDE server, if it is installed.

vrdeport default|<ports> changes the port or a range of ports that the VRDE server can bind to; "default" or "0" means port 3389, the standard port for RDP. For details, see the description for the --vrdeport option in Section 8.8.5, “Remote machine settings”.

vrdeproperty "TCP/Ports|Address=<value>" sets the port number(s) and IP address on the VM to which the VRDE server can bind.

vrdeproperty "VideoChannel/Enabled|Quality|DownscaleProtection=<value>" sets the VRDP video redirection properties.

vrdeproperty "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1"

disables one of the VRDE server features: Display, Input, Audio or USB respectively. To re-enable a feature, use e.g. "Client/DisableDisplay=". For details, see Section 7.1.10, “VRDP customization”.

vrdeproperty "Client/DisableClipboard|DisableUpstreamAudio=1"

disables one of the VRDE server features: Clipboard or UpstreamAudio respectively. To re-enable a feature, use e.g. "Client/DisableClipboard=". For details, see Section 7.1.10, “VRDP customization”.

vrdeproperty "Client/DisableRDPDR=1"

disables the VRDE server feature: RDP device redirection for smart cards. To re-enable this feature, use "Client/DisableRDPR=".

vrdeproperty "H3DRedirect/Enabled=1"

enables the VRDE server feature: 3D redirection. To re-disable this feature, use "H3DRedirect/Enabled=".

vrdeproperty "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=<value>" sets the desired security method/Path of server certificate, path of server private key, path of CA certificate, used for a connection.

vrdeproperty "Audio/RateCorrectionMode|LogPath=<value>" sets the Audio connection mode, or Path of the audio logfile.

vrdevideochannelquality <percent>: Sets the image quality for video redirection; see Section 7.1.9, “VRDP video redirection”.

setvideomodehint requests that the guest system change to a particular video mode. This requires that the Guest Additions be installed, and will not work for all guest systems.

screenshotpng takes a screenshot of the guest display and saves it in PNG format.

videocap on|off enables or disables recording a VM session into a WebM/VP8 file.

videocapscreens all|<screen ID> [<screen ID> ...]] allows to specify which screens of the VM are being recorded. This setting cannot be changed while video capturing is enabled. Each screen is recorded into a separate file.

videocapfile <file> sets the filename VirtualBox uses to save the recorded content. This setting cannot be changed while video capturing is enabled.

videocapres <width> <height> sets the resolution (in pixels) of the recorded video. This setting cannot be changed while video capturing is enabled.

videocaprate <rate> sets the bitrate in kilobits (kb) per second. Increasing this value makes the video look better for the cost of an increased file size. This setting cannot be changed while video capturing is enabled.

videocapfps <fps> sets the maximum number of frames per second (FPS) to be recorded. Frames with a higher frequency will be skipped. Reducing this value increases the number of skipped frames and reduces the file size. This setting cannot be changed while video capturing is enabled.

videocapmaxtime <ms> sets the maximum time in milliseconds the video capturing will be enabled since activation. The capturing stops when the defined time interval has elapsed. If this value is zero the capturing is not limited by time. This setting cannot be changed while video capturing is enabled.

videocapmaxsize <MB> limits the maximum size of the captured video file (in MB). The capturing stops when the file size has reached the specified size. If this value is zero the capturing will not be limited by file size. This setting cannot be changed while video capturing is enabled.

videocapopts <key=value>[,<key=value> ...] can be used to specify additional video capturing options. These options only are for advanced users and must be specified in a comma-separated key=value format, e.g. foo=bar,a=b. This setting cannot be changed while video capturing is enabled.

The setcredentials operation is used for remote logons in Windows guests. For details, please refer to Section 9.2, “Automated guest logons”.

teleport --host <name> --port <port> can be used to configure a VM as a target for teleporting. <name> specifies the virtual machine name. <port> specifies the port on the virtual machine which should listen for teleporting requests from other virtual machines. It can be any free TCP/IP port number (e.g. 6000); See Section 7.2, “Teleporting” for an introduction.

plugcpu|unplugcpu <id>: If CPU hot-plugging is enabled, 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. CPU 0 can never be removed.

The cpuexecutioncap <1-100>: This operation 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.

webcam attach <path|alias> [<key=value>[;<key=value>...]]: This operation attaches a webcam to a running VM. Specify the absolute path of the webcam on the host operating system, or use its alias (obtained by using the command: VBoxManage list webcams).

Note that alias '.0' means default video input device on the host operating system, '.1', '.2', etc. mean first, second, etc. video input device. The device order is host-specific.

The optional settings parameter is a ';' delimited list of name/value pairs, enabling configuration of the emulated webcam device.

The following settings are supported:

MaxFramerate (default no maximum limit) - this specifies the highest rate (frames/sec) at which video frames are sent to the guest. Higher frame rates increase CPU load, so this setting can be useful when there is a need to reduce CPU load. Its default 'value' is 'no maximum limit', thus enabling the guest to use all frame rates supported by the host webcam.

MaxPayloadTransferSize (default 3060 bytes) - this specifies the maximum number of bytes the emulated webcam can send to the guest in one buffer. The default is used by some webcams. Higher values can slightly reduce CPU load, if the guest is able to use larger buffers. Note that higher MaxPayloadTransferSize values may be not supported by some guest operating systems.

webcam detach <path|alias>: This operation detaches a webcam from a running VM. Specify the absolute path of the webcam on the host, or use its alias (obtained from webcam list below).

Note the points below relating to specific Host Operating Systems:

Windows hosts

When the webcam device is detached from the host, the emulated webcam device is automatically detached from the guest.

Mac OS X hosts

OS X version 10.7 or newer is required.

When the webcam device is detached from the host, the emulated webcam device remains attached to the guest and must be manually detached using the VBoxManage controlvm "VM name" webcam detach command.

Linux hosts

When the webcam is detached from the host, the emulated webcam device is automatically detached from the guest only if the webcam is streaming video. If the emulated webcam is inactive, it should be manually detached using the VBoxManage controlvm "VM name" webcam detach command.

webcam list: This operation lists webcams attached to the running VM. The output is a list of absolute paths or aliases that were used for attaching the webcams to the VM using the 'webcam attach' command above.

addencpassword <id> <password file>|- [--removeonsuspend <yes|no>]: This operation supplies an encrypted VM specified by <id> with the encryption password to enable a headless start. Either specify the absolute path of a password file on the host file system: <password file>, or use a '-' to instruct VBoxManage to prompt the user for the encryption password.

--removeonsuspend <yes|no> specifies whether to remove/keep the password from/in VM memory when the VM is suspended. If the VM has been suspended and the password has been removed, the user needs to resupply the password before the VM can be resumed. This feature is useful in cases where the user doesn't want the password to be stored in VM memory, and the VM is suspended by a host suspend event.

Note: On VirtualBox versions 5.0 and later, data stored on hard disk images can be transparently encrypted for the guest. VirtualBox uses the AES algorithm in XTS mode and supports 128 or 256 bit data encryption keys (DEK). The DEK is stored encrypted in the medium properties, and is decrypted during VM startup by supplying the encryption password.

The "VBoxManage encryptmedium" operation is used to create a DEK encrypted medium. See Section 9.31.2, “Encrypting disk images”" for details. When starting an encrypted VM from a VirtualBox GUI app, the user will be prompted for the encryption password.

For a headless encrypted VM start, use:

VBoxManage startvm "vmname" --type headless

followed by:

VBoxManage "vmname" controlvm "vmname" addencpassword ...

to supply the encryption password required.

removeencpassword <id>: This operation removes encryption password authorization for password <id> for all encrypted media attached to the VM.

removeallencpasswords: This operation removes encryption password authorization for all passwords for all encrypted media attached to the VM.