VBoxManage controlvm

The controlvm subcommand enables you to change the state of a virtual machine that is currently running. The following can be specified:

VBoxManage controlvm <vm> pause: Temporarily puts a virtual machine on hold, without permanently changing its state. The VM window is 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: Undoes 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 is done, which immediately restarts and reboots the guest operating system. 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. 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 clicking the VM window's close button, and then selecting Power Off the Machine in the displayed dialog.
After this, the VM's state will be Powered Off. From that state, it can be started again. See Section 8.12, "VBoxManage startvm".
VBoxManage controlvm <vm> savestate: Saves the current state of the VM to disk and then stops the VM. This is equivalent to selecting the Close item in the Machine menu of the GUI or clicking the VM window's close button, and then selecting Save the Machine State in the displayed dialog.
After this, the VM's state will be Saved. From this state, it can be started again. See Section 8.12, "VBoxManage startvm".
VBoxManage controlvm <vm> acpipowerbutton: Sends 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. For example: 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". 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".

The following extra options are available with controlvm that do not directly affect the VM's running state:

setlinkstate<1-N> on|off: 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 available types are: not connected to the host (null), use network address translation (nat), bridged networking (bridged), communicate with other virtual machines using internal networking (intnet), host-only networking (hostonly), natnetwork networking (natnetwork), or access to rarely used submodes (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.
nictrace<1-N> on|off: Enables network tracing for a particular virtual network card.
Before enabling you should specify a file name to which the trace should be logged. This can be done with the nictracefile<1-N> <filename> option to VBoxManage controlvm at runtime or with the <filename> option to VBoxManage modifyvm otherwise.
nicpromisc<1-N> deny|allow-vms|allow-all: Specifies how the promiscious mode is handled for the specified VM virtual network card. This setting is only relevant for bridged networking. The default setting of deny hides any traffic not intended for this VM. allow-vms hides all host traffic from this VM but enables the VM to see traffic to and from 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. See Section 6.8, "UDP Tunnel Networking".
natpf<1-N> [<name>],tcp|udp,[<hostip>],<hostport>,[<guestip>], <guestport>: Specifies a NAT port-forwarding rule. See Section 6.3.1, "Configuring Port Forwarding with NAT".
natpf<1-N> delete <name>: Deletes a NAT port-forwarding rule. See Section 6.3.1, "Configuring Port Forwarding with NAT".
The guestmemoryballoon<balloon size in MB>: Changes the size of the guest memory balloon. This is the memory allocated by the Oracle VM VirtualBox Guest Additions from the guest operating system and returned to the hypervisor for reuse by other virtual machines. This must be specified in megabytes. See Section 4.10.1, "Memory Ballooning".
usbattach<uuid|address> [--capturefile <filename>]
and usbdetach <uuid|address> [--capturefile <filename>]: Makes host USB devices visible or 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: Selects whether capturing audio from the host is enabled or disabled.
audioout on: Selects whether audio playback from the guest is enabled or disabled.
clipboard mode disabled|hosttoguest|guesttohost|bidirectional: Selects 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.
clipboard filetransfers enabled|disabled: Specifies if clipboard file transfers are allowed between host and guest OSes or not.
draganddrop disabled|hosttoguest|guesttohost|bidirectional: Selects 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: Enables and disables 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. See the description for the --vrdeport option in Section 8.8.5, "Remote Machine Settings".
vrdeproperty "TCP/Ports|Address=<value>": Sets the port numbers and IP address on the VM to which the VRDE server can bind.
- For TCP/Ports, <value> should be a port or a range of ports to which the VRDE server can bind. default or 0 means port 3389, the standard port for RDP. See the description for the --vrdeport option in Section 8.8.5, "Remote Machine Settings".
- For TCP/Address, <value>: The IP address of the host network interface that the VRDE server will bind to. If specified, the server will accept connections only on the specified host network interface. See the description for the --vrdeaddress option in Section 8.8.5, "Remote Machine Settings".
vrdeproperty "VideoChannel/Enabled|Quality|DownscaleProtection=<value>": Sets the VRDP video redirection properties.
- For VideoChannel/Enabled, <value> can be set to "1" switching the VRDP video channel on. See Section 7.1.9, "VRDP Video Redirection".
- For VideoChannel/Quality, <value> should be set between 10 and 100% inclusive, representing a JPEG compression level on the VRDE server video channel. Lower values mean lower quality but higher compression. See Section 7.1.9, "VRDP Video Redirection".
- For VideoChannel/DownscaleProtection, <value> can be set to "1" to enable the videochannel downscale protection feature. When enabled, if a video's size equals the shadow buffer size, then it is regarded as a full screen video, and is displayed. If its size is between fullscreen and the downscale threshold it is not displayed, as it could be an application window, which would be unreadable when downscaled. When the downscale protection feature is disabled, an attempt is always made to display videos.
vrdeproperty "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1": Disables one of the VRDE server features: Display, Input, Audio, or USB. To reenable a feature, use "Client/DisableDisplay=" for example. See Section 7.1.10, "VRDP Customization".
vrdeproperty "Client/DisableClipboard|DisableUpstreamAudio=1". Disables one of the VRDE server features: Clipboard or UpstreamAudio. To reenable a feature, use "Client/DisableClipboard=" for example. See Section 7.1.10, "VRDP Customization".
vrdeproperty "Client/DisableRDPDR=1": Disables the VRDE server feature: RDP device redirection for smart cards. To reenable this feature, use "Client/DisableRDPR=".
vrdeproperty "H3DRedirect/Enabled=1": Enables the VRDE server feature: 3D redirection. To disable this feature, use "H3DRedirect/Enabled=".
vrdeproperty "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=<value>": Sets the desired security method, path of the server certificate, path of the server private key, and path of CA certificate, used for a connection.
- vrdeproperty "Security/Method=<value>": Sets the desired security method, which is used for a connection. Valid values are as follows:
  - Negotiate: Both Enhanced (TLS) and Standard RDP Security connections are allowed. The security method is negotiated with the client. This is the default setting.
  - RDP: Only Standard RDP Security is accepted.
  - TLS: Only Enhanced RDP Security is accepted. The client must support TLS.
  See Section 7.1.6, "RDP Encryption".
- vrdeproperty "Security/ServerCertificate=<value>" where <value> is the absolute path of the server certificate. See Section 7.1.6, "RDP Encryption".
- vrdeproperty "Security/ServerPrivateKey=<value>" where <value> is the absolute path of the server private key. See Section 7.1.6, "RDP Encryption".
- vrdeproperty "Security/CACertificate=<value>" where <value> is the absolute path of the CA self signed certificate. See Section 7.1.6, "RDP Encryption".
vrdeproperty "Audio/RateCorrectionMode|LogPath=<value>": Sets the audio connection mode, or path of the audio logfile.
- vrdeproperty "Audio/RateCorrectionMode=<value>" where <value> is the desired rate correction mode, allowed values are:
  - VRDP_AUDIO_MODE_VOID: No mode specified, use to unset any Audio mode already set.
  - VRDP_AUDIO_MODE_RC: Rate correction mode.
  - VRDP_AUDIO_MODE_LPF: Low pass filter mode.
  - VRDP_AUDIO_MODE_CS: Client sync mode to prevent underflow or overflow of the client queue.
- vrdeproperty "Audio/LogPath=<value>" where <value> is the absolute path of the audio log file.
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.
recording on|off enables or disables the recording of a VM session into a WebM/VP8 file. When this option value is on, recording begins when the VM session starts.
recordingscreens all|screen-ID [screen-ID ...] enables you to specify which VM screens to record. The recording for each screen that you specify is saved to its own file. You cannot modify this setting while recording is enabled.
recordingfile filename specifies the file in which to save the recording. You cannot modify this setting while recording is enabled.
recordingvideores widthxheight specifies the resolution of the recorded video in pixels. You cannot modify this setting while recording is enabled.
recordingvideorate bit-rate specifies the bit rate of the video in kilobits per second. Increasing this value improves the appearance of the video at the cost of an increased file size. You cannot modify this setting while recording is enabled.
recordingvideofps fps specifies the maximum number of video frames per second (FPS) to record. Frames that have a higher frequency are skipped. Increasing this value reduces the number of skipped frames and increases the file size. You cannot modify this setting while recording is enabled.
recordingmaxtime seconds specifies the maximum amount time to record in seconds. The recording stops after the specified number of seconds elapses. If this value is zero, the recording continues until you stop the recording.
recordingmaxsize MB specifies the maximum size of the recorded video file in megabytes. The recording stops when the file reaches the specified size. If this value is zero, the recording continues until you stop the recording. You cannot modify this setting while recording is enabled.
recordingopts keyword=value[,keyword=value ...] specifies additional recording options in a comma-separated keyword-value format. For example, foo=bar,a=b. You cannot modify this setting while recording is enabled.
Only use this option only if you are an advanced user. For information about keywords, see Oracle VM VirtualBox Programming Guide and Reference.
setcredentials: Used for remote logins on Windows guests. See Section 9.1, "Automated Guest Logins".
teleport --host <name> --port <port>: Configures 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, such as 6000. See Section 7.2, "Teleporting".
- --maxdowntime <msec>: Specifies the maximum downtime, in milliseconds, for the teleporting target VM. Optional.
- --password <password>: The teleporting request will only succeed if the source machine specifies the same password as the one given with this command. Optional.
- --passwordfile <password file>: The teleporting request will only succeed if the source machine specifies the same password as the one specified in the password file with the path specified with this command. Use stdin to read the password from stdin. Optional.
plugcpu|unplugcpu <id>: If CPU hot-plugging is enabled, this setting adds and removes a virtual CPU to the virtual machine. <id> specifies the index of the virtual CPU to be added or removed and must be a number from 0 to the maximum number of CPUs configured. CPU 0 can never be removed.
The cpuexecutioncap <1-100>: 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.
vm-process-priority default|flat|low|normal|high: Changes the priority scheme of the VM process. See Section 8.12, "VBoxManage startvm".
webcam attach <path|alias> [<keyword=value>[;<keyword=value>...]]: 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 the 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: Specifies the highest rate in frames per second, 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. The default setting is no maximum limit, thus enabling the guest to use all frame rates supported by the host webcam.
MaxPayloadTransferSize: Specifies the maximum number of bytes the emulated webcam can send to the guest in one buffer. The default setting is 3060 bytes, which 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>: Detaches a webcam from a running VM. Specify the absolute path of the webcam on the host, or use its alias obtained from the webcam list command.
Please note the following points, 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 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 webcam detach command.
webcam list: 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.
addencpassword <id> <password file>|- [--removeonsuspend <yes|no>]: 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 - to instruct VBoxManage to prompt the user for the encryption password.
--removeonsuspend <yes|no>: Specifies whether to remove the passsword or keep the password 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 does not want the password to be stored in VM memory, and the VM is suspended by a host suspend event.

Note

On Oracle VM VirtualBox versions 5.0 and later, data stored on hard disk images can be transparently encrypted for the guest. Oracle VM 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 command is used to create a DEK encrypted medium. See Section 9.28.2, "Encrypting Disk Images". When starting an encrypted VM from the Oracle VM VirtualBox GUI, the user will be prompted for the encryption password.
For a headless encrypted VM start, use the following command:
```
          VBoxManage startvm "vmname" --type headless
        
```
Then supply the required encryption password as follows:
```
          VBoxManage "vmname" controlvm "vmname" addencpassword ...
        
```
removeencpassword <id>: Removes encryption password authorization for password <id> for all encrypted media attached to the VM.
removeallencpasswords: Removes encryption password authorization for all passwords for all encrypted media attached to the VM.
changeuartmode <1-N>: Changes the connection mode for a given virtual serial port.

VBoxManage controlvm

Note