9 VBoxManage

--pae=on | off
Enables or disables physical address extension (PAE). See chapter 4.5.2, Processor Tab, page
76.
--long-mode=on | off
Enables or disables long mode. See chapter 4.5.2, Processor Tab, page 76.
--ibpb-on-vm-exit=on | off
Enables use of Indirect Branch Prediction Barrier (IBPB) on every VM exit.

--ibpb-on-vm-entry=on | off
Enables use of Indirect Branch Prediction Barrier (IBPB) on every VM entry.
--spec-ctrl=on | off
Enables or disables the exposure of speculation control interfaces to the guest VM. These
interfaces must be available on the host system.
Depending on the host CPU and the workload, enabling speculation control might signifi-
cantly reduce performance.
--l1d-flush-on-sched=on | off
Enables or disables level 1 data cache flushing when a thread is scheduled to execute guest
code. See chapter 14.4.1, CVE-2018-3646, page 419.
--l1d-flush-on-vm-entry=on | off
Enables or disables level 1 data cache flushing on every VM entry. See chapter 14.4.1,
CVE-2018-3646, page 419.

--mds-clear-on-sched=on | off
Enables CPU buffer clearing when a thread is scheduled to execute guest code. See chapter
14.4.2, CVE-2018-12126, CVE-2018-12127, CVE-2018-12130, CVE-2019-11091, page 420.
--mds-clear-on-vm-entry=on | off
Enables CPU buffer clearing on every VM entry. See chapter 14.4.2, CVE-2018-12126,
CVE-2018-12127, CVE-2018-12130, CVE-2019-11091, page 420.

--cpu-profile=host | Intel 8086 | Intel 80286 | Intel 80386

Specifies the profile to use for guest CPU emulation. Specify a value that is based on the
host system CPU (host) or one of the following older Intel micro-architectures: 8086,
80286, or 80386.

--hpet=on | off
Enables or disables a High Precision Event Timer (HPET) that can replace a legacy system
timer. This feature is disabled by default. Note HPET is supported on Windows versions
starting with Vista.
--hwvirtex=on | off
Enables or disables the use of hardware virtualization extensions in the processor of the
host system. Such extensions are Intel VT-x or AMD-V. See chapter 11.3, Hardware Virtual-
ization, page 395.
--triple-fault-reset=on | off
Enables or disables the resetting of the guest VM instead of triggering a Guru Meditation.
Some guest VMs raise a triple fault to reset the CPU, so sometimes resetting the guest
VM is the best outcome. This option only applies to guests that do not use symmetric
multiprocessing (SMP).

185
 9 VBoxManage

--apic=on | off
Enables or disables APIC. With APIC, OSes can use more than 16 interrupt requests (IRQs)
to avoid IRQ sharing and to improve reliability. APIC is enabled by default. See chapter
4.5.1, Motherboard Tab, page 74.
--x2apic=on | off
Enables or disables the CPU x2APIC feature. CPU x2APIC enables an OS to run more
efficiently on high core count configurations and to optimize interrupt distribution in vir-
tualized environments. This feature is enabled by default.
Disable this feature when the OS that runs on a host system or a guest VM is incompatible
with CPU x2APIC.
--paravirt-provider=none | default | legacy | minimal | hyperv | kvm
Specifies one of the following paravirtualization interfaces to provide to the guest OS:
• none does not expose any paravirtualization interface.
• default selects the appropriate interface based on the guest OS type when starting
the VM. This is the default value used when creating new VMs.
• legacy selects a paravirtual interface for VMs that were created by older Oracle VM
VirtualBox versions.
• minimal is required for Mac OS X guest VMs.
• kvm is recommended for Linux guest VMs. See chapter 11.5, Paravirtualization
Providers, page 396.
• hyperv is recommended for Windows guest VMs. See chapter 11.5, Paravirtualization
Providers, page 396.
--paravirt-debug=<property>=<value>
Specifies debugging properties that are specific to the paravirtualization provider config-
ured for the specified VM. See chapter 10.30, Paravirtualized Debugging, page 378.
--nested-paging=on | off
Enables or disables the nested paging feature in the processor of the host system. This op-
tion is available only when hardware virtualization is enabled. See chapter 11.3, Hardware
Virtualization, page 395 and chapter 14.4.1, CVE-2018-3646, page 419.

--large-pages=on | off
Enables or disables the hypervisor’s use of large pages, which can improve performance by
up to 5%. The use of large pages reduces TLB use and overhead. This option is available
only when both hardware virtualization and nested paging are enabled.
--vtx-vpid=on | off
Enables or disables the use of the tagged TLB (VPID) feature in the processor of your host
system. See chapter 11.3, Hardware Virtualization, page 395. This option is available only
when hardware virtualization is enabled on Intel VT-x.
--vtx-ux=on | off
Enables or disables the use of unrestricted guest mode for executing the guest VM. This
option is available only when hardware virtualization is enabled on Intel VT-x.
--nested-hw-virt=on | off
Enables or disables nested virtualization. Enabling makes hardware virtualization features
available to the VM. See chapter 10.34, Nested Virtualization, page 383.

--virt-vmsave-vmload=on | off
If hardware virtualization is enabled and the host has an AMD CPU, this setting enables or

186
 9 VBoxManage

disables the use of the virtualized vmsave/vmload host feature while executing the VM. It
is enabled by default. It is recommended to leave it enabled as it has a drastic impact on
performance while executing nested VMs when using the nested hardware virtualization
feature. chapter 10.34, Nested Virtualization, page 383.
--accelerate-3d=on | off
Enables or disables hardware 3D acceleration for the graphics adapter variants which sup-
port it. This option has an effect only when the Guest Additions are installed. See chapter
5.5.1, Hardware 3D Acceleration (OpenGL and Direct3D 8/9), page 102.
--accelerate-2d-video=on | off
Enables or disables 2D video acceleration for the graphics adapter variants which support
it. This option has an effect only when the Guest Additions are installed. See chapter 5.5.2,
Hardware 2D Video Acceleration for Windows Guests, page 103.

--chipset=piix3 | ich9
Specify the Intel chipset for Oracle VM VirtualBox to emulate. The default value is the Intel
PIIX3 chipset (piix3).
Change this value only if you need to relax some of the chipset constraints. See chapter
4.5.1, Motherboard Tab, page 74.

--iommu=none | automatic | amd | intel

Specifies the IOMMU type for Oracle VM VirtualBox to emulate. Both Intel and AMD
IOMMU emulation currently require the use of the Intel ICH9 chipset (see --chipset
option).
Valid values are as follows:
• none âĂŞ No IOMMU is present and is the default value.
• automatic âĂŞ An IOMMU is present but its type is automatically chosen to match
the host CPU vendor when the VM is powered on.
• amd âĂŞ An AMD IOMMU is present.
• intel âĂŞ An Intel IOMMU is present.
--tpm-type=none | 1.2 | 2.0 | host | swtpm
Specifies the TPM type for Oracle VM VirtualBox to emulate.
Valid values are as follows:
• none âĂŞ No TPM is present and is the default value.
• 1.2 âĂŞ A TPM conforming to the TCG specification version 1.2 is present.
• 2.0 âĂŞ A TPM conforming to the TCG specification version 2.0 is present.
• host âĂŞ The host TPM is passed through to the guest. May not be available on all
supported host platforms.
• swtpm âĂŞ The VM connects to an external TPM emulation compliant to swtpm. Re-
quires to set the TPM location to connect to (see --tpm-location option).
--bios-logo-fade-in=on | off
Specifies whether the BIOS logo fades in on VM startup. By default, an Oracle VM
VirtualBox logo is shown.

--bios-logo-fade-out=on | off
Specifies whether the BIOS logo fades out on VM startup.
--bios-logo-display-time=<msec>
Specifies the amount of time in milliseconds that the BIOS logo is visible.

187
 9 VBoxManage

--bios-logo-image-path=<pathname>
Replaces the existing BIOS logo with a different image. The replacement image must be an
uncompressed 16, 256 or 16M color bitmap file (BMP) that does not contain color space
information (Windows 3.0 format). Also ensure that the image is no larger than 640 X 480
pixels.
--bios-boot-menu=disabled | menuonly | messageandmenu
Specifies whether the BIOS permits you to select a temporary boot device. Valid values are:
• disabled outputs the alternate boot device message and permits you to select a tem-
porary boot device by pressing F12.
• menuonly suppresses the alternate boot device message, but permits you to select a
temporary boot device by pressing F12.
• messageandmenu suppresses the alternate boot device message and prevents you from
selecting a temporary boot device by pressing F12.
--bios-apic=x2apic | apic | disabled
Specifies the APIC level of the firmware. Valid values are: x2apic, apic, and disabled.
When the value is disabled, neither the apic nor the x2apic version of the firmware is
used.
Note that if you specify the x2apic value and x2APIC is unsupported by the virtual CPU,
the APIC level downgrades to apic, if supported. Otherwise, the APIC level downgrades to
disabled. Similarly, if you specify the apic value and APIC is unsupported by the virtual
CPU, the APIC level downgrades to disabled.
--bios-system-time-offset=<msec>
Specifies the time offset in milliseconds of the guest VM relative to the time on the host
system. If the offset value is positive, the guest VM time runs ahead of the time on the host
system.

--bios-pxe-debug=on | off
Enables or disables additional debugging output when using the Intel PXE boot ROM. The
debug output is written to the release log file. See chapter 13.1.2, Collecting Debugging
Information, page 400.

--system-uuid-le=on | off
Enables or disables representing the system UUID in little endian form. The default value
is on for new VMs. For old VMs the setting is off to keep the content of the DMI/SMBIOS
table unchanged, which can be important for Windows license activation.
--boot<N>=none | floppy | dvd | disk | net
Enables you to specify the boot device order for the VM by assigning one of the device
types to each of the four boot device slots that are represented by N in the option name.
A value of 1 for N represents the first boot device slot, and so on.
The device types are floppy for floppy disks, dvd for DVDs or CDs, disk for hard disks,
and net for a network device. A value of none indicates that no boot device is associated
with the specified slot.

--rtc-use-utc=on | off
Specifies whether the real-time clock (RTC) uses coordinated universal time (UTC). See
chapter 4.5.1, Motherboard Tab, page 74.
--graphicscontroller=none | vboxvga | vmsvga | vboxsvga
Specifies the graphics controller type to use. See chapter 4.6.1, Screen Tab, page 77.

188
 9 VBoxManage

--snapshot-folder=default | <pathname>
Specifies the name of the VM’s snapshot storage folder. If you specify default, the folder
name is Snapshots/ in the machine folder.
--firmware=bios | efi | efi32 | efi64
Specifies the firmware used to boot the VM. Valid values are: bios, efi, efi32, or efi64.
Use EFI values with care.
By default, BIOS firmware is used.

--guest-memory-balloon=<size>
Specifies the size of the guest memory balloon. The guest memory balloon is the memory
allocated by the Guest Additions from the guest OS and returned to the hypervisor for use
by other VMs. Specify size in megabytes. The default value is 0 megabytes. See chapter
5.10.1, Memory Ballooning, page 108.

--default-frontend=default | <name>
Specifies the default frontend to use when starting the specified VM. If you specify default,
the VM is shown in a window on the user’s desktop. See chapter 9.19, VBoxManage startvm,
page 225.
--vm-process-priority=default | flat | low | normal | high
Specifies the priority scheme of the VM process to use when starting the specified VM and
while the VM runs.
The following valid values are:
• default âĂŞ Default process priority determined by the OS.
• flat âĂŞ Assumes a scheduling policy which puts the process at the default priority
and with all threads at the same priority.
• low âĂŞ Assumes a scheduling policy which puts the process mostly below the default
priority of the host OS.
• normal âĂŞ Assume a scheduling policy which shares the CPU resources fairly with
other processes running with the default priority of the host OS.
• high âĂŞ Assumes a scheduling policy which puts the task above the default priority
of the host OS. This policy might easily cause other tasks in the system to starve.

Networking Settings
VBoxManage modifyvm <uuid | vmname> [--nicN= none | null | nat | bridged
| intnet | hostonly | hostonlynet | generic | natnetwork | cloud ]
[--nic-typeN= Am79C970A | Am79C973 | 82540EM | 82543GC | 82545EM | virtio ]
[--cable-connectedN= on | off ] [--nic-traceN= on | off ]
[--nic-trace-fileN=filename] [--nic-propertyN=name= [value] ]
[--nic-speedN=kbps] [--nic-boot-prioN=priority] [--nic-promiscN= deny
| allow-vms | allow-all ] [--nic-bandwidth-groupN= none | name ]
[--bridge-adapterN= none | device-name ] [--cloud-networkN=network-name]
[--host-only-adapterN= none | device-name ]
[--host-only-netN=network-name] [--intnetN=network-name]
[--nat-networkN=network-name] [--nic-generic-drvN=driver-name]
[--mac-addressN= auto | MAC-address ]

The following options enable you to modify networking on your VM. With all these options, N
is an integer greater than zero that represents the particular virtual network adapter to configure.

189
 9 VBoxManage

--nic<N>=none | null | nat | natnetwork | bridged | intnet | hostonly |

generic
Configures the network type used by each virtual network card in the VM.
The following valid values correspond to the modes described in chapter 7.2, Introduction
to Networking Modes, page 129:
• none âĂŞ No networking present
• null âĂŞ Not connected to the host system
• nat âĂŞ Use network address translation (NAT)
• natnetwork âĂŞ Use a NAT network
• bridged âĂŞ Use bridged networking
• intnet âĂŞ Use internal networking
• hostonly âĂŞ Use host-only networking
• generic âĂŞ Access rarely used sub-modes
--nic-type<N>=Am79C970A | Am79C973 | 82540EM | 82543GC | 82545EM |
virtio
Identifies the type of networking hardware that Oracle VM VirtualBox presents to the guest
VM for the specified virtual network card. See chapter 7.1, Virtual Networking Hardware,
page 128.
Valid values are as follows:
• Am79C970A represents the AMD PCNet PCI II.
• Am79C973 represents the AMD PCNet FAST III, which is the default value.
• 82540EM represents the Intel PRO/1000 MT Desktop.
• 82543GC represents the Intel PRO/1000 T Server.
• 82545EM represents the Intel PRO/1000 MT Server.
• virtio represents a paravirtualized network adapter.
--cable-connected<N>=on | off
Temporarily disconnects a virtual network interface, as if you pull a network cable from a
physical network card. You might use this option to reset certain software components in
the VM.
--nic-trace<N>=on | off
Enables or disables network tracing for the specified virtual network card.
--nic-trace-file<N>=<filename>
Specifies the absolute path of the file in which to write trace log information. Use this
option if network tracing is enabled.
--nic-property<N>=<name>=<value>
Enables you to set property values and pass them to rarely used network backends. To use
this option, you must also use the --nic-generic-drv option.
These properties are specific to the backend engine and differ between the UDP Tunnel and
the VDE backend drivers. For property examples, see chapter 7.8, UDP Tunnel Networking,
page 137.
--nic-speed<N>=<kbps>
Specifies the throughput rate in kilobits per second for rarely used networking sub-modes
such as VDE network and UDP Tunnel. Use this option only if you used the --nic option
to enable generic networking for the specified virtual network card.

190
 9 VBoxManage

--nic-boot-prio<N>=<priority>
Assigns a priority to each NIC that determines the order in which that NIC is used to
perform a PXE network boot. The priority value is an integer in the range from 0 to 4.
Priority 0, which is the default value, is the lowest priority. Priority 1 is the highest priority,
and priorities 3 and 4 are lower.
This option has an effect only when using the Intel PXE boot ROM.
--nic-promisc<N>=deny | allow-vms | allow-all
Enables you to specify whether to deny or allow promiscuous mode for the specified VM
virtual network card. This option is relevant only for bridged networking. Valid values are
as follows:
• deny hides any traffic that is not intended for the VM. This is the default value.
• allow-vms hides all host traffic from the VM, but allows the VM to see traffic to and
from other VMs.
• allow-all allows the VM to see all traffic.

--nic-bandwidth-group<N>=none | <name>
Adds or removes a bandwidth group assignment to the specified virtual network interface.
Valid values are as follows:
• none removes any current bandwidth group assignment from the specified virtual
network interface.
• name adds a bandwidth group assignment to the specified virtual network interface.
See chapter 7.12, Limiting Bandwidth for Network Input/Output, page 140.
--bridge-adapter<N>=none | <device-name>
Specifies the host interface to use for the specified virtual network interface. See chapter
7.5, Bridged Networking, page 134. Use this option only if you used the --nic option to
enable bridged networking for the specified virtual network card.
--host-only-adapter<N>=none | <device-name>
Specifies which host-only networking interface to use for the specified virtual network
interface. See chapter 7.7, Host-Only Networking, page 136. Use this option only if you
used the --nic option to enable host-only networking for the specified virtual network
card.
--intnet<N>=<network-name>
Specifies the name of the internal network. See chapter 7.6, Internal Networking, page
135. Use this option only if you used the --nic option to enable internal networking for
the specified virtual network card.

--nat-network<N>=<network-name>
Specifies the name of the NAT network to which this adapter is connected. Use this option
only if the networking type is natnetwork, not nat.
--nic-generic-drv<N>=<backend-driver>
Enables you to access rarely used networking sub-modes, such as VDE networks and UDP
Tunnel. Use this option only if you used the --nic option to enable generic networking for
a virtual network card.
--mac-address<N>=auto | <MAC-address>
Specifies the MAC address of the specified network adapter on the VM. By default, Oracle
VM VirtualBox assigns a random MAC address to each network adapter at VM creation.

191
 9 VBoxManage

NAT Networking Settings

VBoxManage modifyvm <uuid | vmname> [--nat-netN= network | default ]
[--nat-pfN= [rule-name],tcp | udp,[host-IP],hostport,[guest-IP],guestport
] [--nat-pfN=delete=rule-name] [--nat-tftp-prefixN=prefix]
[--nat-tftp-fileN=filename] [--nat-tftp-serverN=IP-address]
[--nat-bind-ipN=IP-address] [--nat-dns-pass-domainN= on | off ]
[--nat-dns-proxyN= on | off ] [--nat-dns-host-resolverN= on | off ]
[--nat-localhostreachableN= on | off ]
[--nat-settingsN=[mtu],[socksnd],[sockrcv],[tcpsnd],[tcprcv]]
[--nat-alias-modeN= default | [log],[proxyonly],[sameports] ]

The following options use N to specify the particular virtual network adapter to modify.
--nat-net<N>=default | <network>
Specifies the IP address range to use for this network. See chapter 10.8, Fine Tuning the
Oracle VM VirtualBox NAT Engine, page 345. Use this option only if the networking type is
nat, not natnetwork.

--nat-pf<N>=[<name>],tcp |
udp,[<host-IP>],<hostport>,[<guest-IP>],<guestport>
Specifies the NAT port-forwarding rule to use. See chapter 7.3.1, Configuring Port Forward-
ing with NAT, page 131.
--nat-pf<N>=delete <name>
Specifies the NAT port-forwarding rule to delete. See chapter 7.3.1, Configuring Port For-
warding with NAT, page 131.
--nat-tftp-prefix<N>=<prefix>
Specifies a prefix to use for the built-in TFTP server. For example, you might use a prefix to
indicate where the boot file is located. See chapter 7.3.2, PXE Booting with NAT, page 131
and chapter 10.8.2, Configuring the Boot Server (Next Server) of a NAT Network Interface,
page 345.
--nat-tftp-file<N>=<boot-file>
Specifies the name of the TFT boot file. See chapter 10.8.2, Configuring the Boot Server
(Next Server) of a NAT Network Interface, page 345.
--nat-tftp-server<N>=<tftp-server>
Specifies the address of the TFTP server from which to boot. See chapter 10.8.2, Configur-
ing the Boot Server (Next Server) of a NAT Network Interface, page 345.
--nat-bind-ip<N>=<IP-address>
Specifies an alternate IP address to which the NAT engine binds. See chapter 10.8.3, Tuning
TCP/IP Buffers for NAT, page 345. By default, Oracle VM VirtualBox’s NAT engine routes
TCP/IP packets through the default interface assigned by the host’s TCP/IP stack.
--nat-dns-pass-domain<N>=on | off
Specifies whether the built-in DHCP server passes the domain name for network name
resolution.
--nat-dns-proxy<N>=on | off
Specifies whether the NAT engine is the proxy for all guest DNS requests to the host system’s
DNS servers. See chapter 10.8.5, Enabling DNS Proxy in NAT Mode, page 346.
--nat-dns-host-resolver<N>=on | off
Specifies whether the NAT engine uses the host system’s resolver mechanisms to handle
DNS requests. See chapter 10.8.5, Enabling DNS Proxy in NAT Mode, page 346.

192
 9 VBoxManage

--nat-localhostreachable<N>=on | off
Specifies whether the NAT engine allows traffic from the guest directed to 10.0.2.2 to pass
to the host’s loopback interface, i.e. localhost or 127.0.0.1.
--nat-settings<N>=[<mtu>],[<socksnd>],[<sockrcv>],[<tcpsnd>],[<tcprcv>]
Specifies values for tuning NAT performance. See chapter 10.8.3, Tuning TCP/IP Buffers for
NAT, page 345.
--nat-alias-mode<N>=default | [log],[proxyonly],[sameports]
Specifies the behavior of the NAT engine core as follows:
• log enables logging
• proxyonly switches off aliasing mode and makes NAT transparent
• sameports enforces that the NAT engine sends packets through the same port on
which they originated
• default disables all aliasing modes
For more information, see chapter 10.8.7, Configuring Aliasing of the NAT Engine, page 347.

Other Hardware Settings

VBoxManage modifyvm <uuid | vmname> [--mouse= ps2 | usb | usbtablet
| usbmultitouch | usbmtscreenpluspad ] [--keyboard= ps2 | usb ] [--uartN=
off | IO-baseIRQ ] [--uart-modeN= disconnected | server pipe | client pipe
| tcpserver port | tcpclient hostname:port | file filename | device-name ]
[--uart-typeN= 16450 | 16550A | 16750 ] [--lpt-modeN=device-name] [--lptN=
off | IO-baseIRQ ] [--audio-controller= ac97 | hda | sb16 ] [--audio-codec=
stac9700 | ad1980 | stac9221 | sb16 ] [--audio-driver= none | default | null
| dsound | was | oss | alsa | pulse | coreaudio ] [--audio-enabled= on | off ]
[--audio-in= on | off ] [--audio-out= on | off ] [--clipboard-mode=
disabled | hosttoguest | guesttohost | bidirectional ] [--drag-and-drop=
disabled | hosttoguest | guesttohost | bidirectional ]
[--monitor-count=number] [--usb-ehci= on | off ] [--usb-ohci= on | off ]
[--usb-xhci= on | off ] [--usb-rename=old-namenew-name]

The following options enable you to configure other hardware, such as the serial port, monitor,
audio device, USB ports, and the clipboard, and drag-and-drop features.
--mouse=ps2 | usb | usbtablet | usbmultitouch | usbmtscreenpluspad
Specifies the mode of the mouse to use in the VM. Valid values are: ps2, usb, usbtablet,
usbmultitouch and usbmtscreenpluspad.

--keyboard=ps2 | usb
Specifies the mode of the keyboard to use in the VM. Valid values are: ps2 and usb.
--uart<N>=off | <I/O-base><IRQ>
Configures virtual serial ports for the VM. N represents the serial port to modify. Valid
values are off to disable the port or an I/O base address and IRQ. For information about
the traditional COM port I/O base address and IRQ values, see chapter 4.10, Serial Ports,
page 81.
--uart-mode<N>=<mode>
Specifies how Oracle VM VirtualBox connects the specified virtual serial port to the host
system that runs the VM. See chapter 4.10, Serial Ports, page 81.
Ensure that you first configure the virtual serial port by using the --uart<N> option.
Specify one of the following connection modes for each port:

193
 9 VBoxManage

• disconnected indicates that even though the serial port is shown to the guest VM, it
is not connected. This state is like a physical COM port without a cable attached.
• serverpipe-name creates the specified named pipe or local domain socket on the
host system and connects the virtual serial device to it.
On a Windows host system, pipe-name is a named pipe that has a name that uses the
following form: \\.\pipe\pipe-name.
On a Linux host system, pipe-name is a local domain socket.
• clientpipe-name connects the virtual serial device to the specified named pipe or
local domain socket.
Note that the named pipe or local domain socket must already exist.
• tcpserverport creates a TCP socket with the specified TCP port on the host system
and connects the virtual serial device to it.
For UNIX-like systems, use ports over 1024 for non-root users.
• tcpclienthostname:port connects the virtual serial device to the TCP socket.
Note that the TCP socket must already exist.
• filefilename redirects the serial port output to the specified raw file. Ensure that
filename is the absolute path of the file on the host system.
• device-name: specifies the device name of a physical hardware serial port on the
specified host system to which the virtual serial port connects.
Use this mode to connect a physical serial port to a VM.
On a Windows host system, the device name is a COM port such as COM1. On a Linux
host system, the device name is similar to /dev/ttyS0.
--uart-type<N>=<UART-type>
Configures the UART type for the specified virtual serial port (N). Valid values are 16450,
16550A, and 16750. The default value is 16550A.

--lpt-mode<N>=<device-name>
Specifies the device name of the parallel port to use.
For a Windows host system, use a device name such as lpt1. For a Linux host system, use
a device name such as /dev/lp0.
--lpt<N>=<I/O-base><IRQ>
Specifies the I/O base address and IRQ of the parallel port.
You can view the I/O base address and IRQ that the VM uses for the parallel port in the
Device Manager.
--audio-controller=<controller-type>
Specifies the audio controller to be used with the VM. Valid audio controller type values
are: ac97, hda, and sb16.
--audio-codec=<codec-type>
Specifies the audio codec to be used with the VM. Valid audio codec type values are:
stac9700, ad1980, stac9221, and sb16.

--audio-driver=<type>
Specifies whether which audio driver (backend) to use. none, default, null, dsound,
was, oss, alsa, pulse, and coreaudio.
Note that the audio driver are dependent on the host operating system. Use the
VBoxManage modifyvm command usage output to determine the supported audio types
for your host system.

194
 9 VBoxManage

For maximum interoperability between hosts, the default audio driver can be used. The
VM will then automatically select the most appropriate audio driver for the current host
available.
--audio-enabled=on|off
Specifies whether to enable or disable audio for the VM.
This option has precedence over the –audio-on and –audio-off options, i.e. turning off
audio via this option will turn off both, input and output, audio.

--audio-in=on|off
Specifies whether to enable or disable audio capture from the host system.
--audio-out=on|off
Specifies whether to enable or disable audio playback from the guest VM.

--clipboard-mode=<value>
Specifies how to share the guest VM or host system OS’s clipboard with the host system
or guest VM, respectively. Valid values are: disabled, hosttoguest, guesttohost, and
bidirectional. See chapter 4.4, General Settings, page 73.
The clipboard feature is available only if you have the Guest Additions be installed in the
VM.
--drag-and-drop=<value>
Specifies how to use the drag and drop feature between the host system and the VM. Valid
values are: disabled, hosttoguest, guesttohost, and bidirectional. See chapter 5.4,
Drag and Drop, page 100.
The drag and drop feature is available only if you have the Guest Additions be installed in
the VM.
--monitor-count=<count>
Enables you to configure multiple monitors. See chapter 4.6, Display Settings, page 77.
--usb-ohci=on | off
Enables or disables the VM’s virtual USB 1.1 controller. See chapter 4.11.1, USB Settings,
page 83.
--usb-ehci=on | off
Enables or disables the VM’s virtual USB 2.0 controller. See chapter 4.11.1, USB Settings,
page 83.

--usb-xhci=on | off
Enables or disables the VM’s virtual USB 3.0 controller. This is the most efficient option if
the VM supports it. See chapter 4.11.1, USB Settings, page 83.
--usb-rename=<old-name><new-name>
Rename’s the VM’s virtual USB controller from old-name to new-name.

Recording Settings
VBoxManage modifyvm <uuid | vmname> [--recording= on | off ]
[--recording-screens= all | none | screen-ID[,screen-ID...] ]
[--recording-file=filename] [--recording-max-size=MB]
[--recording-max-time=msec] [--recording-opts= key=value[,key=value...]
] [--recording-video-fps=fps] [--recording-video-rate=rate]
[--recording-video-res=widthheight]

195
 9 VBoxManage

The following options enable you to modify settings for video recording, audio recording, or
both.

--recording=on | off
Enables or disables the recording of a VM session into a WebM or VP8 file. When set to on,
recording begins when the VM session starts.
--recording-screens=all | none | <screen-ID>[,<screen-ID>...
Enables you to specify the VM screens to record. The recording for each screen is output
to its own file. Valid values are: all, which records all screens, none, which records no
screens, or one or more specified screens.
--recording-file=<filename>
Specifies the name of the file in which to save the recording.
--recording-max-size=<MB>
Specifies the maximum size of the recorded video file in megabytes. When the file reaches
the specified size, recording stops. If the value is 0, recording continues until you manually
stop recording.
--recording-max-time=<seconds>
Specifies the maximum amount of time to record in seconds. When the specified time
elapses, recording stops. If the value is 0, recording continues until you manually stop
recording.
--recording-opts=<keyword>=<value>
Specifies additional video-recording properties as a comma-separated property keyword-
value list. For example, foo=bar,a=b.
Only use this option if you are an advanced user. For information about keywords, see the
Oracle VM VirtualBox Programming Guide and Reference.
--recording-video-fps=<fps>
Specifies the maximum number of video frames per second (FPS) to record. The recording
ignores any frames that have a higher frequency. When you increase the FPS, fewer frames
are ignored but the recording and the size of the recording file increases.
--recording-video-rate=<bit-rate>
Specifies the bit rate of the video in kilobits per second. When you increase the bit rate,
the recording appearance improves and the size of the recording file increases.
--recording-video-res=<width>x<height>
Specifies the video resolution (width and height) of the recorded video in pixels.

Remote Machine Settings

VBoxManage modifyvm <uuid | vmname> [--vrde= on | off ]
[--vrde-property=property-name= [property-value] ] [--vrde-extpack=
default | name ] [--vrde-port=port] [--vrde-address=hostip]
[--vrde-auth-type= null | external | guest ] [--vrde-auth-library= default
| name ] [--vrde-multi-con= on | off ] [--vrde-reuse-con= on | off ]
[--vrde-video-channel= on | off ] [--vrde-video-channel-quality=percent]

The following options enable you to modify the VirtualBox Remote Desktop Extension (VRDE)
behavior.

--vrde=on | off
Enables or disables the VRDE server.

196
 9 VBoxManage

--vrde-property=TCP/Ports=<port>
port is the port or port range to which the VRDE server binds. The default or 0 value
uses port 3389, which is the standard RDP port.
Also see the --vrde-port option description.
--vrde-property=TCP/Address=<IP-address>
IP-address is the IP address of the host network interface to which the VRDE server binds.
When specified, the server accepts connections only on the host network interface at that
IP address.
Also see the --vrde-address option description.
--vrde-property=VideoChannel/Enabled=<value>
Specifies whether the VRDP video channel is on or off. 1 means on and 0 means off. See
chapter 8.1.9, VRDP Video Redirection, page 150.

--vrde-property=Quality=<value>
Specifies a value between 10% and 100%, inclusive, that represents the JPEG compression
level on the VRDE server video channel. A lower value produces lower JPEG quality but
higher compression. See chapter 8.1.9, VRDP Video Redirection, page 150.

--vrde-property=DownscaleProtection=<value>
Enables or disables the video downscale protection feature. Valid values are 1 to enable
the feature and 0 to disable the feature.
When this feature is enabled, Oracle VM VirtualBox determines whether to display the
video:
• When the video size equals the size of the shadow buffer, the video is considered to
be full screen and is displayed.
• When the video size is between full screen and the downscale threshold, the video
is not displayed. Such a video might be an application window, which is unreadable
when downscaled.
When this feature is disabled, an attempt is always made to display a video.
--vrde-property=Client/DisableDisplay=1
Disables the display VRDE server feature.
To reenable a feature, assign an empty value. For example, to reenable the display fea-
ture, specify the VBoxManage modifyvm --vrde-property=Client/DisableDisplay=
command. See chapter 8.1.10, VRDP Customization, page 150.
--vrde-property=DisableInput=1
Disables the input VRDE server feature.
--vrde-property=DisableAudio=1
Disables the audio VRDE server feature.

--vrde-property=DisableUSB=1
Disables the USB VRDE server feature.
--vrde-property=Client/DisableClipboard=1
Disables the clipboard VRDE server feature. To reenable the feature, assign an empty value.
See chapter 8.1.10, VRDP Customization, page 150.
--vrde-property=DisableUpstreamAudio=1
Disables the upstream audio VRDE server feature. To reenable the feature, assign an empty
value. See chapter 8.1.10, VRDP Customization, page 150.

197
 9 VBoxManage

--vrde-property=Client/DisableRDPDR=1
Disables the RDP device redirection for smart cards VRDE server feature. To reenable this
feature, assign an empty value.
--vrde-property=H3DRedirect/Enabled=1
Enables the 3D redirection VRDE server feature. To disable this feature, assign an empty
value.
--vrde-property=Security/Method=<value>
Specifies the following information that is required for a connection:
• Negotiate indicates that both Enhanced (TLS) and Standard RDP Security connec-
tions are permitted. The security method is negotiated with the client. This is the
default value.
• RDP indicates that only Standard RDP Security is accepted.
• TLS indicates that only Enhanced RDP Security is accepted. The client must support
TLS.
See chapter 8.1.6, RDP Encryption, page 148.
--vrde-property=ServerCertificate=<value>
Specifies the absolute path to the server certificate. See chapter 8.1.6, RDP Encryption,
page 148.
--vrde-property=ServerPrivateKey=<value>
Specifies the absolute path to the server private key. See chapter 8.1.6, RDP Encryption,
page 148.
--vrde-property=CACertificate=<value>
Specifies the absolute path to the CA self-signed certificate. See chapter 8.1.6, RDP Encryp-
tion, page 148.
--vrde-property Audio/RateCorrectionMode=<value>
Specifies the audio connection mode or the path to the audio log file. Valid values are as
follows:
• VRDP_AUDIO_MODE_VOID is no mode. Use this value to unset any set audio mode.
• VRDP_AUDIO_MODE_RC is the rate correction mode.
• VRDP_AUDIO_MODE_LPF is the low pass filter mode.
• VRDP_AUDIO_MODE_CS is the client sync sync mode to prevent an underflow or over-
flow of the client queue.
--vrde-property=LogPath=<value>
Specifies the absolute path to the audio log file.
--vrde-extpack=default | <name>
Specifies the library to use to access the VM remotely. The default value uses the RDP
code that is part of the Oracle VM VirtualBox Extension Pack.
To use the VRDE module in VNC, specify VNC. See chapter 10.20, Other Extension Packs,
page 370.
--vrde-port=default | <port>
port is the port or port range to which the VRDE server binds. The default or 0 value
uses port 3389, which is the standard RDP port.
You can specify a comma-separated list of ports or port ranges of ports. Use a dash between
two port numbers to specify a port range. The VRDE server binds to only one of the avail-
able ports from the list. Only one machine can use a given port at a time. For example, the

198
 9 VBoxManage

--vrde-port=5000,5010-5012 option specifies that server can bind to one of following

ports: 5000, 5010, 5011, or 5012.

--vrde-address=<IP-address>
Specifies the IP address of the host network interface to which the VRDE server binds. If
you specify an IP address, the server accepts connections only on the specified host network
interface.
Use this option to specify whether the VRDP server should accept IPv4, IPv6, or both type
of connections:
• Only IPv4: Use the --vrde-address="0.0.0.0" option.
• Only IPv6: Use the --vrde-address="::" option.
• Both IPv6 and IPv4: Use the --vrde-address="" option. This is the default value.
--vrde-auth-type=null | external | guest
Specify whether to use authorization and how to perform authorization. See chapter 8.1.5,
RDP Authentication, page 147. Valid values are as follows:
• null provides no authentication.
• external provides external authentication through an authentication library.
• guest performs authentication by using guest user accounts. This unsupported
method requires that you install the Guest Additions on the VM.
--vrde-auth-library=default | <name>
Specifies the library to use for RDP authentication. The default library for external authen-
tication is VBoxAuth. See chapter 8.1.5, RDP Authentication, page 147.

--vrde-multi-con=on | off
Enables or disables the multiple connections VRDE server feature, if supported. See chapter
8.1.7, Multiple Connections to the VRDP Server, page 149.
--vrde-reuse-con=on | off
Specifies how the VRDE server behaves when multiple connections are disabled. When the
value is on, the server permits a new client to connect and drops the existing connection.
When the value is off, a new connection is not accepted if a client is already connected to
the server. This is the default value.
--vrde-video-channel=on | off
Enables video redirection if supported by the VRDE server. See chapter 8.1.9, VRDP Video
Redirection, page 150.
--vrde-video-channel-quality=<percent>
Specifies the image quality for video redirection as a value from 10 to 100 percent. The per-
centage represents the JPEG compression level where a lower number diminishes quality
and provides higher compression. See chapter 8.1.9, VRDP Video Redirection, page 150.

Teleporting Settings
VBoxManage modifyvm <uuid | vmname> [--teleporter= on | off ]
[--teleporter-port=port] [--teleporter-address= address | empty ]
[--teleporter-password=password] [--teleporter-password-file= filename
| stdin ] [--cpuid-portability-level=level] [--cpuid-set=leaf [:subleaf]
eaxÂăebxÂăecxÂăedx] [--cpuid-remove=leaf [:subleaf] ]
[--cpuid-remove-all]

199
 9 VBoxManage

The following options enable you to configure a machine as a teleporting target. See chap-
ter 8.2, Teleporting, page 151 and the teleporting related entries in chapter 14.3.4, Potentially
Insecure Operations, page 418.

--teleporter=on | off
Enables or disables the teleporter. When enabled, a machine starts up and waits to receive
a teleporting request from the network instead of booting normally.
Teleporting requests are received on the port and address specified using the following
parameters.
--teleporter-port=<port>
Specifies the port on which the VM listens to receive a teleporting request from another
VM. port is any free TCP/IP port number, such as 6000. You must also specify the
--teleporter option.

--teleporter-address=<IP-address>
Specifies the IP address on which the VM listens to receive a teleporting request from
another VM. IP-address is any IP address or host name and specifies the TCP/IP socket
on which to bind. The default IP address is 0.0.0.0, which represents any IP address. You
must also specify the --teleporter option.
--teleporter-password=<password>
Specifies the password to use for authentication. When specified, the teleporting request
only succeeds if the password on the source machine is the same password as the one you
specify.
--teleporter-password-file=<filename>
Specifies a file that contains the password to use for authentication. When specified, the
teleporting request only succeeds if the password on the source machine is the same pass-
word as the one you specify in the password file. A value of stdin reads the password
from standard input.
--cpuid-portability-level=<level>
Restricts the virtual CPU capabilities that Oracle VM VirtualBox presents to the guest OS
by using portability rules. Higher integer values designate more restrictive behavior. The
default level of 0 indicates that all virtualized features supported by the host are made
available to the guest. The value 3 supresses most features. Values of 1 and 2 represent
restrictions in between. The behavior may change depending on the product version.
--cpuid-set=<leaf>[:<subleaf>] <eax>Âă<ebx>Âă<ecx>Âă<edx>
Advanced users can use this setting before a teleporting operation (in fact before starting
the VM) to restrict the virtual CPU capabilities that Oracle VM VirtualBox presents to the
guest operating system. This must be run on both the source and the target machines in-
volved in teleporting and will then modify what the guest sees when it executes the CPUID
machine instruction. This might help with misbehaving applications that wrongly assume
that certain CPU capabilities are present. The meaning of the parameters is hardware
dependent. Refer to the AMD or Intel processor documentation.
The values of leaf, subleaf (optional), eax, ebx, ecx and edx are integers given in
hexadecimal format, i.e. using a radix (base) of 16 without requiring any prefix.
--cpuid-remove=<leaf>[:<subleaf>]
Removes an adjustment established with --cpuid-set.
--cpuid-remove-all
Removes all adjustments established with --cpuid-set.

200
 9 VBoxManage

Debugging Settings
VBoxManage modifyvm <uuid | vmname> [--tracing-enabled= on | off ]
[--tracing-config=string] [--tracing-allow-vm-access= on | off ]

Only use the following options to perform low-level VM debugging. These options are for
advanced users only.

--tracing-enabled=on | off
Enables or disables the trace buffer. Note that when specified, the trace buffer consumes
some memory and adds overhead.
--tracing-config=<config-string>
Enables a tracing configuration that defines which group of trace points are enabled.

--tracing-allow-vm-access=on | off
Enables or disables VM access to the trace buffer. The default value is off, which disables
access.

USB Card Reader Settings

VBoxManage modifyvm <uuid | vmname> [--usb-card-reader= on | off ]

The following options specify the access to a USB Card Reader by the guest environment. A
USB card reader can access data on memory cards, such as CompactFlash (CF), Secure Digital
(SD), and MultiMediaCard (MMC).

--usb-card-reader=on | off
Enables or disables the USB card reader interface.

Autostarting VMs During Host System Boot

The following options enable you to configure the VM autostart feature, which automatically
starts the VM at host system boot-up. You must do some host system configuration before you
can use this feature. See chapter 10.21, Starting Virtual Machines During System Boot, page 370.

VBoxManage modifyvm <uuid | vmname> [--autostart-enabled= on | off ]

[--autostart-delay=seconds]

--autostart-enabled=on | off
Enables or disables VM autostart at host system boot-up for the specified users.

--autostart-delay=<seconds>
Specifies the number of seconds after host system boot-up to autostart the VM.

Guest Debugging
These options are for configuring the VMM for guest debugging.

VBoxManage modifyvm <uuid | vmname> [--guest-debug-provider= none | native

| gdb | kd ] [--guest-debug-io-provider= none | tcp | udp | ipc ]
[--guest-debug-address= IP-Address | path ] [--guest-debug-port=port]

201
 9 VBoxManage

--guest-debug-provider=none | native | gdb | kd

Selects the given debug stub provider.

--guest-debug-io-provider=none | tcp | udp | ipc

Selects the given I/O transport backend for the selected provider.
--guest-debug-address=<IP-Address> | <path>
Sets the path the debugger is accessible under, depends on the selected I/O transport.

--guest-debug-port=<port>
Sets the port the debugger is accessible under, depends on the selected I/O transport.

PCI Passthrough Settings

The following options enable you to configure the PCI passthrough feature, which currently is
not available in Oracle VM VirtualBox. It is planned to bring this functionality back in the future.

VBoxManage modifyvm <uuid | vmname> [--pci-attach=host-PCI-address

[@guest-PCI-bus-address] ] [--pci-detach=host-PCI-address]

--pci-attach=<host-PCI-address>[@<guest-PCI-bus-address>]
Attaches the specified PCI network controller on the host to the guest VM. You can option-
ally specify the PCI bus on the guest VM on which to attach the controller.
--pci-detach=<host-PCI-address>
Detaches the specified PCI network controller from the attached PCI bus on the guest VM.

Testing (ValidationKit / Bootsector)

These options are for configuring the testing functionality of the VMM device and almost exclu-
sively used by the bootsector testcases in the ValidationKit.

VBoxManage modifyvm <uuid | vmname> [--testing-enabled= on | off ]

[--testing-mmio= on | off ] [--testing-cfg-dwordidx=value]

--testing-enabled=on | off
Enabled the testing functionality of the VMMDev. See VMMDevTesting.h for details.
--testing-mmio=on | off
Enabled the MMIO region of the VMMDev testing feature.
--testing-cfg-dword<idx>=<value>
This sets one of the 10 dword configuration values. The idx must be in the range 0 thru 9.
The value is limited to 32 bits (dword).

Examples
The following command changes the description for the ol7 VM.
$ VBoxManage modifyvm ol7 --description "Oracle Linux 7 with UEK4"

The following command enables VirtualBox Remote Display Protocol (VRDP) support for the
ol7 VM.

$ VBoxManage modifyvm ol7 --vrde on

202
 9 VBoxManage

See Also
chapter 9.6, VBoxManage showvminfo, page 175, chapter 9.20, VBoxManage controlvm, page
226, chapter 9.9, VBoxManage createvm, page 179, chapter 9.19, VBoxManage startvm, page
225chapter 9.5, VBoxManage list, page 170

9.11 VBoxManage clonevm

Create a clone of an existing virtual machine.

Synopsis
VBoxManage clonevm <vmname|uuid> [--basefolder=basefolder]
[--groups=group,. . . ] [--mode=machine | --mode=machinechildren
| --mode=all] [--name=name] [--options=option,. . . ] [--register]
[--snapshot=snapshot-name] [--uuid=uuid]

Description
The VBoxManage clonevm command creates a clone of an existing virtual machine (VM). The
clone can be a full copy of the VM or a linked copy of a VM.
You must specify the name or the universal unique identifier (UUID) of the VM you want to
clone.

Command Operand and Options

The following list describes the operand and the options that you can use with the
VBoxManage clonevm command:

vmname|uuid
Specifies the name or UUID of the VM to clone.
--basefolder=<basefolder>
Specifies the name of the folder in which to save the configuration for the new VM.
--groups=<group>,...
Assigns the clone to the specified group or groups. If you specify more than one group,
separate each group name with a comma.
Note that each group is identified by a group ID that starts with a slash character (/) so
that groups can be nested. By default, a clone is always assigned membership to the /
group.
--mode=machine|machineandchildren|all
Specifies which of the following cloning modes to use:
• machine mode clones the current state of the existing VM without any snapshots. This
is the default mode.
• machineandchildren mode clones the snapshot specified by by the --snapshot op-
tion and all child snapshots.
• all mode clones all snapshots and the current state of the existing VM.
--name=<name>
Specifies a new name for the new VM. The default value is original-name Clone where
original-name is the original name of the VM.

203
 9 VBoxManage

--options=<option>,...
Specifies how to create the new clone.
The --options argument can be used multiple times to enable multiple options, or the
options can be given as a comma separated list. The options are case insensitive.
The following options (case-insensitive) are recognized:
Link
Creates a linked clone from a snapshot only.
KeepAllMACs
Specifies that the new clone reuses the MAC addresses of each virtual network card
from the existing VM.
If you do not specify this option or the --options=keepnatmacs option, the default
behavior is to reinitialize the MAC addresses of each virtual network card.
KeepNATMACs
Specifies that the new clone reuses the MAC addresses of each virtual network card
from the existing VM when the network type is NAT.
If you do not specify this option or the KeepAllMACs option, the default behavior is
to reinitialize the MAC addresses of each virtual network card.
KeepDiskNames
Specifies that the new clone reuses the disk image names from the existing VM. By
default, disk images are renamed.
KeepHwUUIDs
Specifies that the new clone reuses the hardware IDs from the existing VM. By default,
new UUIDs are used.
--register
Automatically registers the new clone in this Oracle VM VirtualBox installation. You can
manually register the new VM later by using the VBoxManage registervm command. See
chapter 9.7, VBoxManage registervm, page 177.
--snapshot=<snapshot-name>
Specifies the snapshot on which to base the new VM. By default, the clone is created from
the current state of the specified VM.
--uuid=<uuid>
Specifies the UUID for the new VM. Ensure that this ID is unique for the Oracle VM
VirtualBox instance if you decide to register this new VM. By default, Oracle VM VirtualBox
provides a new UUID.

Examples
The following command creates and registers an exact clone of the ol7 VM. The clone is called
ol7-dev-001.
The new clone includes all of the source VM’s snapshots. The new VM also reuses all network
interface MAC addresses, disk names, and UUIDs from the source VM.

$ VBoxManage clonevm ol7 --name="ol7-dev-001" --register --mode=all \

--options=keepallmacs --options=keepdisknames --options=keephwuuids

The following command creates and registers a clone of the Snapshot 1 snapshot of the ol7
VM. The clone is called ol7-dev-002.

$ VBoxManage clonevm ol7 --name="ol7-dev-002" --register --snapshot="Snapshot 1"

204
 9 VBoxManage

See Also
chapter 9.7, VBoxManage registervm, page 177

9.12 VBoxManage movevm

Move a virtual machine to a new location on the host system.

Synopsis
VBoxManage movevm <uuid | vmname> [--type=basic] [--folder=folder-name]

Description
The VBoxManage movevm command moves a virtual machine (VM) to a new location on the host
system.
When moved, all of the files that are associated with the VM, such as settings files and disk
image files, are moved to the new location. The Oracle VM VirtualBox configuration is updated
automatically.
uuid|vmname
Specifies the Universally Unique Identifier (UUID) or name of the VM to move.
--type=basic
Specifies the type of the move operation. So far basic is the only recognized value and
also the default if not specified.
--folder=<folder-name>
Specifies a full path name or relative path name of the new location on the host file system.
Not specifying the option or specifying the current location is allowed, and moves disk
images and other parts of the VM to this location if they are currently in other locations.

Examples
The following command moves the ol7 VM to a new location on the host system.
$ VBoxManage movevm ol7 --folder "/home/testuser/vms" --type basic
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
Machine has been successfully moved into /home/testuser/vms

9.13 VBoxManage encryptvm

Change encryption and passwords of the VM.

Synopsis
VBoxManage encryptvm <uuid | vmname> setencryption --old-password file
--cipher cipher-identifier --new-password file
--new-password-id password-identifier --force

VBoxManage encryptvm <uuid | vmname> checkpassword <file>

VBoxManage encryptvm <uuid | vmname> addpassword --password file

--password-id password-identifier

VBoxManage encryptvm <uuid | vmname> removepassword <password-identifier>

205