|
|
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 âĂS No IOMMU is present and is the default value.
• automatic âĂS An IOMMU is present but its type is automatically chosen to match
the host CPU vendor when the VM is powered on.
• amd âĂS An AMD IOMMU is present.
• intel âĂS 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 âĂS No TPM is present and is the default value.
• 1.2 âĂS A TPM conforming to the TCG specification version 1.2 is present.
• 2.0 âĂS A TPM conforming to the TCG specification version 2.0 is present.
• host âĂS The host TPM is passed through to the guest. May not be available on all
supported host platforms.
• swtpm âĂS 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 âĂS Default process priority determined by the OS.
• flat âĂS Assumes a scheduling policy which puts the process at the default priority
and with all threads at the same priority.
• low âĂS Assumes a scheduling policy which puts the process mostly below the default
priority of the host OS.
• normal âĂS Assume a scheduling policy which shares the CPU resources fairly with
other processes running with the default priority of the host OS.
• high âĂS 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 âĂS No networking present
• null âĂS Not connected to the host system
• nat âĂS Use network address translation (NAT)
• natnetwork âĂS Use a NAT network
• bridged âĂS Use bridged networking
• intnet âĂS Use internal networking
• hostonly âĂS Use host-only networking
• generic âĂS 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
9 VBoxManage
Description
The VBoxManage encryptvm command enables you to change the encryption or add and remove
user passwords for the virtual machine (VM). The following sections describe the subcommands
that you can use:
Set encryption of the Virtual Machine
VBoxManage encryptvm <uuid | vmname> setencryption --old-password file
--cipher cipher-identifier --new-password file
--new-password-id password-identifier --force
The VBoxManage encryptvm vmname setencryption command changes encryption of a
VM.
Use the --old-password to supply old encryption password. Either specify the absolute path-
name of a password file on the host operating system, or - to prompt you for the old password.
Use the --cipher option to specify the new cipher for encryption of the VM. Only AES-128 and
AES-256 are supported. Appropriate mode GCM, CTR or XTS will be selected by VM depending
on encrypting component.
Use the --new-password option to specify the new password for encryption of the VM. Either
specify the absolute pathname of a password file on the host operating system, or - to prompt
you for the new password.
Use the --new-password-id option to specify the new id for the password for encryption of
the VM.
Use the --force option to make the system to reencrypt the VM instead of simple changing
the password.
Check the supplied password is correct
VBoxManage encryptvm <uuid | vmname> checkpassword <file>
The VBoxManage encryptvm vmname checkpassword command checks the correctness of
the supplied password.
The password can be supplied from file. Specify the absolute pathname of a password file on
the host operating system. Also, you can specify - to prompt you for the password.
Add password for decrypting the Virtual Machine
VBoxManage encryptvm <uuid | vmname> addpassword --password file
--password-id password-identifier
The VBoxManage encryptvm vmname addpassword command adds a password for decrypt-
ing the VM.
Use the --password to supply the encryption password. Either specify the absolute pathname
of a password file on the host operating system, or - to prompt you for the password.
Use the --password-id option to specify the id the password is supplied for.
Remove password used for decrypting the Virtual Machine
VBoxManage encryptvm <uuid | vmname> removepassword <password-identifier>
206
9 VBoxManage
The VBoxManage encryptvm vmname removepassword command removes a password used
for decrypting the VM.
Specify the password identifier for removing. The password becomes unknown and the VM
can not be decrypted.
Examples
The following command encrypts the ol7 VM using AES-256 giving password via command
prompt:
$ VBoxManage encryptvm ol7 setencryption --cipher=AES-256 --new-password - --new-password-id vmid
See Also
chapter 9.9, VBoxManage createvm, page 179,
9.14 VBoxManage cloud
Manage the cloud entities.
Synopsis
VBoxManage cloud <--provider=name> <--profile=name>
list instances [--state=string] [--compartment-id=string]
VBoxManage cloud <--provider=name> <--profile=name>
list images <--compartment-id=string> [--state=string]
VBoxManage cloud <--provider=name> <--profile=name>
list vnicattachments <--compartment-id=string> [--filter=string]
VBoxManage cloud <--provider=name> <--profile=name>
instance create <--domain-name=name> <<--image-id=id>
| <--boot-volume-id=id>> <--display-name=name> <--shape=type>
<--subnet=id> [--boot-disk-size=size in GB] [--publicip=true/false]
[--privateip=IP address] [--public-ssh-key=key string. . . ]
[--launch-mode=NATIVE/EMULATED/PARAVIRTUALIZED]
[--cloud-init-script-path=path to a script]
VBoxManage cloud <--provider=name> <--profile=name>
instance info <--id=unique id>
VBoxManage cloud <--provider=name> <--profile=name>
instance terminate <--id=unique id>
VBoxManage cloud <--provider=name> <--profile=name>
instance start <--id=unique id>
VBoxManage cloud <--provider=name> <--profile=name>
instance pause <--id=unique id>
VBoxManage cloud <--provider=name> <--profile=name>
instance reset <--id=unique id>
207
9 VBoxManage
VBoxManage cloud <--provider=name> <--profile=name>
image create <--display-name=name> [--bucket-name=name]
[--object-name=name] [--instance-id=unique id]
VBoxManage cloud <--provider=name> <--profile=name>
image info <--id=unique id>
VBoxManage cloud <--provider=name> <--profile=name>
image delete <--id=unique id>
VBoxManage cloud <--provider=name> <--profile=name>
image import <--id=unique id> [--bucket-name=name] [--object-name=name]
VBoxManage cloud <--provider=name> <--profile=name>
image export <--id=unique id> <--display-name=name>
[--bucket-name=name] [--object-name=name]
VBoxManage cloud <--provider=name> <--profile=name>
network setup [--gateway-os-name=string] [--gateway-os-version=string]
[--gateway-shape=string] [--tunnel-network-name=string]
[--tunnel-network-range=string] [--proxy=string]
[--compartment-id=string]
VBoxManage cloud <--provider=name> <--profile=name>
network create <--name=string> <--network-id=string> [--enable
| --disable]
VBoxManage cloud network update <--name=string> [--network-id=string]
[--enable | --disable]
VBoxManage cloud network delete <--name=string>
VBoxManage cloud network info <--name=string>
Description
Common options
The word “cloud” is an umbrella for all commands related to the interconnection with the Cloud.
The next common options must be placed between the “cloud” and the following sub-commands:
-provider=name
Short cloud provider name.
-profile=name
Cloud profile name.
cloud list instances
VBoxManage cloud <--provider=name> <--profile=name>
list instances [--state=string] [--compartment-id=string]
Displays the list of the instances for a specified compartment.
-state"running/paused/terminated"
The state of cloud instance. The possible states are “running/paused/terminated” at mo-
ment. If the state isn’t provided the list of instances with all possible states is returned.
--compartment-id
A compartment is the logical container used to organize and isolate cloud resources. The
different cloud providers can have the different names for this entity.
208
9 VBoxManage
cloud list images
VBoxManage cloud <--provider=name> <--profile=name>
list images <--compartment-id=string> [--state=string]
Displays the list of the images for a specified compartment.
-state"available/disabled/deleted"
The state of cloud image. The possible states are “available/disabled/deleted” at moment.
If the state isn’t provided the list of images with all possible states is returned.
--compartment-id
A compartment is the logical container used to organize and isolate cloud resources. The
different cloud providers can have the different names for this entity.
cloud list vnic attachments
VBoxManage cloud <--provider=name> <--profile=name>
list vnicattachments <--compartment-id=string> [--filter=string]
Displays the list of the vnic attachments for a specified compartment.
-filter"instanceId/vnicId/domainName=string"
Filters are used to narrow down the set of Vnic attachments of interest. This parame-
ter is repeatible. The possible filters are “instanceId” or “vnicId” or “availabilityDomain”
at moment. The form is “instanceId/vnicId/domainName=[string value]“ and can be
repeated. In instance, “-filter instanceId=ocid1.instance.oc1.iad.anuwcl...js6 -filter vni-
cId=ocid1.vnic.oc1.iad.abuwcl...jsm -filter domainName=ergw:US-ASHBURN-AD-2”. But
in most cases, this is redundant and one filter is enough. If the filter isn’t provided the
whole list of vnic attachments for a specified compartment is returned.
--compartment-id
A compartment is the logical container used to organize and isolate cloud resources. The
different cloud providers can have the different names for this entity.
cloud instance create
VBoxManage cloud <--provider=name> <--profile=name>
instance create <--domain-name=name> <<--image-id=id>
| <--boot-volume-id=id>> <--display-name=name> <--shape=type>
<--subnet=id> [--boot-disk-size=size in GB] [--publicip=true/false]
[--privateip=IP address] [--public-ssh-key=key string. . . ]
[--launch-mode=NATIVE/EMULATED/PARAVIRTUALIZED]
[--cloud-init-script-path=path to a script]
Creates new instance in the Cloud. There are two standard ways to create an instance in
the Cloud: 1. Create an instance from an existing custom image. 2. Create an instance from
an existing bootable volume. This bootable volume shouldn’t be attached to any instance. For
the 1st approach next parameters are required: image-id, boot-disk-size. For the 2nd approach
next parameters are required: boot-volume-id. The rest parameters are common for both cases:
display-name, launch-mode, subnet-id, publicIP, privateIP, shape, domain.
--domain-name
Cloud domain where new instance is created.
209
9 VBoxManage
--image-id
Unique identifier which fully identifies a custom image in the Cloud.
--boot-volume-id
Unique identifier which fully identifies a boot volume in the Cloud.
--display-name
Name for new instance in the Cloud.
--shape
The shape of instance, defines the number of CPUs and RAM memory.
--subnet
Unique identifier which fully identifies an existing subnet in the Cloud which will be used
by the instance.
--boot-disk-size
The size of bootable image in GB. Default is 50GB.
--publicip
Whether the instance will have a public IP or not.
--privateip
Private IP address for the created instance.
--public-ssh-key
Public SSH key used to connect to the instance via SSH. This parameter may be re-
peated if you plan to use more than one key as: “-public-ssh-key=firstSSHKey -public-
ssh-key=secondSSHKey”.
--launch-mode
The most known values here may be EMULATED, NATIVE, PARAVIRTUALIZED.
--cloud-init-script-path
Absolute path to the user cloud-init script.
cloud instance info
Display information about a cloud instance with a specified id.
--id
Unique identifier which fully identify the instance in the Cloud.
cloud instance termination
Delete a cloud instance with a specified id.
--id
Unique identifier which fully identify the instance in the Cloud.
cloud instance start
Start a cloud instance with a specified id.
--id
Unique identifier which fully identify the instance in the Cloud.
210
9 VBoxManage
cloud instance pause
Pause a cloud instance with a specified id.
--id
Unique identifier which fully identify the instance in the Cloud.
cloud instance reset
Force reset a cloud instance with a specified id.
--id
Unique identifier which fully identify the instance in the Cloud.
cloud image create
VBoxManage cloud <--provider=name> <--profile=name>
image create <--display-name=name> [--bucket-name=name]
[--object-name=name] [--instance-id=unique id]
Creates new image in the Cloud. There are two standard ways to create an image in the
Cloud: 1. Create an image from an object in the Cloud Storage; 2. Create an image from an
existing cloud instance. For the 1st approach next parameters are required: bucket-name - cloud
bucket name where an object is located; object-name - name of object in the bucket; display-
name - name for new image in the Cloud. For the 2d approach next parameters are required:
instance-id - Id of instance in the Cloud; display-name - name for new image in the Cloud.
--display-name
Name for new image in the Cloud.
--bucket-name
Cloud bucket name where an object is located.
--object-name
Name of object in the bucket.
--instance-id
Unique identifier which fully identifies the instance in the Cloud.
cloud image info
VBoxManage cloud <--provider=name> <--profile=name>
image info <--id=unique id>
Display information about a cloud image with a specified id.
--id
Unique identifier which fully identifies the image in the Cloud.
cloud image delete
VBoxManage cloud <--provider=name> <--profile=name>
image delete <--id=unique id>
Delete an image with a specified id from the Cloud.
--id
Unique identifier which fully identifies the image in the Cloud.
211
9 VBoxManage
cloud image import
VBoxManage cloud <--provider=name> <--profile=name>
image import <--id=unique id> [--bucket-name=name] [--object-name=name]
Import an image with a specified id from the Cloud to a local host. The result is an object
in the local “temp” folder on the local host. Possible approach may have two general steps: 1.
Create an object from an image in the Cloud Storage; 2. Download the object to the local host.
So the next parameters may be required: bucket-name - cloud bucket name where the object will
be created; object-name - name of object in the bucket. if parameter “object-name” is absent a
displayed image name is used. If the first step isn’t needed only the parameter “id” is required.
--id
Unique identifier which fully identifies the image in the Cloud.
--bucket-name
Cloud bucket name where an object will be created.
--object-name
Name of created object in the bucket. The downloaded object will have this name.
cloud image export
VBoxManage cloud <--provider=name> <--profile=name>
image export <--id=unique id> <--display-name=name>
[--bucket-name=name] [--object-name=name]
Export an existing VBox image with a specified uuid from a local host to the Cloud. The result
is new image in the Cloud. Possible approach may have two general steps: 1. Upload VBox image
to the Cloud Storage; 2. Create an image from the uploaded object. So the next parameters may
be required: bucket-name -cloud bucket name where the object will be uploaded; object-name -
name of object in the bucket. If parameter “object-name” is absent the image id is used; display-
name - name for new image in the Cloud. If the first step isn’t needed the parameters “id” and
“display-name” are required only.
--id
Unique identifier of the image in the VirtualBox.
--display-name
Name for new image in the Cloud.
--bucket-name
Cloud bucket name where the image (object) will be uploaded.
--object-name
Name of object in the bucket.
cloud network setup
VBoxManage cloud <--provider=name> <--profile=name>
network setup [--gateway-os-name=string] [--gateway-os-version=string]
[--gateway-shape=string] [--tunnel-network-name=string]
[--tunnel-network-range=string] [--proxy=string]
[--compartment-id=string]
212
9 VBoxManage
Set up a cloud network environment for the specified cloud profile.
--gateway-os-name
The name of OS to use for a cloud gateway.
--gateway-os-version
The version of OS to use for a cloud gateway.
--gateway-shape
The instance shape to use for a cloud gateway.
--tunnel-network-name
The name of VCN/subnet to use for tunneling.
--tunnel-network-range
The IP address range to use for tunneling.
--proxy
The proxy URL to be used in local gateway installation.
--compartment-id
The compartment to create the tunnel network in.
cloud network create
VBoxManage cloud <--provider=name> <--profile=name>
network create <--name=string> <--network-id=string> [--enable
| --disable]
Create a new cloud network descriptor associated with an existing cloud subnet.
--name
The name to assign to the cloud network descriptor.
--network-id
The unique identifier of an existing subnet in the cloud.
--enable, -disable
Whether to enable the network descriptor or disable it. If not specified, the network will
be enabled.
cloud network update
VBoxManage cloud network update <--name=string> [--network-id=string]
[--enable | --disable]
Modify an existing cloud network descriptor.
--name
The name of an existing cloud network descriptor.
--network-id
The unique identifier of an existing subnet in the cloud.
--enable, -disable
Whether to enable the network descriptor or disable it.
213
9 VBoxManage
cloud network delete
VBoxManage cloud network delete <--name=string>
Delete an existing cloud network descriptor.
--name
The name of an existing cloud network descriptor.
cloud network info
VBoxManage cloud network info <--name=string>
Display information about a cloud network descriptor.
--name
The name of an existing cloud network descriptor.
9.15 VBoxManage cloudprofile
Manage the cloud profiles.
Synopsis
VBoxManage cloudprofile <--provider=name> <--profile=name> add
[--clouduser=unique id] [--fingerprint=MD5 string] [--keyfile=path]
[--passphrase=string] [--tenancy=unique id] [--compartment=unique id]
[--region=string]
VBoxManage cloudprofile <--provider=name> <--profile=name> update
[--clouduser=unique id] [--fingerprint=MD5 string] [--keyfile=path]
[--passphrase=string] [--tenancy=unique id] [--compartment=unique id]
[--region=string]
VBoxManage cloudprofile <--provider=name> <--profile=name> delete
VBoxManage cloudprofile <--provider=name> <--profile=name> show
Description
Common options
The subcommands of cloudprofile implement the standard CRUD operations for a cloud pro-
file. The next common options must be placed between the “cloud” and the following sub-
commands:
-provider=name
Short cloud provider name.
-profile=name
Cloud profile name.
214
9 VBoxManage
cloudprofile add
VBoxManage cloudprofile <--provider=name> <--profile=name> add
[--clouduser=unique id] [--fingerprint=MD5 string] [--keyfile=path]
[--passphrase=string] [--tenancy=unique id] [--compartment=unique id]
[--region=string]
Add new cloud profile for a specified cloud provider.
--clouduser
The name which fully identifies the user in the specified cloud provider.
--fingerprint
Fingerprint for the key pair being used.
--keyfile
Full path and filename of the private key.
--passphrase
Passphrase used for the key, if it is encrypted.
--tenancy
ID of your tenancy.
--compartment
ID of your compartment.
--region
Region name. Region is where you plan to deploy an application.
cloudprofile show
VBoxManage cloudprofile <--provider=name> <--profile=name> show
Display information about a cloud profile for a specified cloud provider.
cloudprofile update
VBoxManage cloudprofile <--provider=name> <--profile=name> update
[--clouduser=unique id] [--fingerprint=MD5 string] [--keyfile=path]
[--passphrase=string] [--tenancy=unique id] [--compartment=unique id]
[--region=string]
Modify a cloud profile for the specified cloud provider.
--clouduser
The name which fully identifies the user in the specified cloud provider.
--fingerprint
Fingerprint for the key pair being used.
--keyfile
Full path and filename of the private key.
--passphrase
Passphrase used for the key, if it is encrypted.
215
9 VBoxManage
--tenancy
ID of your tenancy.
--compartment
ID of your compartment.
--region
Region name. Region is where you plan to deploy an application.
cloudprofile delete
VBoxManage cloudprofile <--provider=name> <--profile=name> delete
Delete a cloud profile for a specified cloud provider.
9.16 VBoxManage import
Import a virtual appliance in OVF format or from a cloud service and create virtual machines.
Synopsis
VBoxManage import <ovfname | ovaname> [--dry-run] [--options= keepallmacs
| keepnatmacs | importtovdi ] [--vsys=n] [--ostype=ostype] [--vmname=name]
[--settingsfile=file] [--basefolder=folder] [--group=group] [--memory=MB]
[--cpus=n] [--description=text] [--eula= show | accept ] [--unit=n]
[--ignore] [--scsitype= BusLogic | LsiLogic ] [--disk=path]
[--controller=index] [--port=n]
VBoxManage import OCI:// --cloud [--ostype=ostype] [--vmname=name]
[--basefolder=folder] [--memory=MB] [--cpus=n] [--description=text]
<--cloudprofile=profile> <--cloudinstanceid=id>
[--cloudbucket=bucket]
Description
The VBoxManage import command imports a virtual appliance either in OVF format or from a
cloud service such as Oracle Cloud Infrastructure. The import is performed by copying virtual
disk images (by default using the VMDK image format) and by creating virtual machines (VMs)
in Oracle VM VirtualBox. See chapter 2.15, Importing and Exporting Virtual Machines, page 30.
You must specify the path name of an OVF file or OVA archive to use as input, or a placeholder
for the cloud case. For OVF appliances ensure that any disk images are in the same directory as
the OVF file.
Note that any options you specify to control the imported virtual appliance or to modify the
import parameters rely on the contents of the OVF file or the information from the cloud service.
Before you use the import operation to create the VM, perform a dry run to verify the correct-
ness of your configuration. This is more useful with an OVF or OVA appliance, because with a
cloud service even a dry run needs to perform most of the time consuming steps.
The import from a cloud service downloads a temporary file containing both the boot image
and some metadata describing the details of the VM instance. The temporary file is deleted after
successful import.
216
9 VBoxManage
Common Options
ovfname | ovaname
Specifies the name of the OVF file or OVA archive that describes the appliance. In the cloud
case this is usually a fixed string such as OCI://.
--dry-run
Performs a dry run of the VBoxManage import command before you perform the actual
import operation. A dry run operation does the following:
• Outputs a description of the appliance’s contents based on the specified OVF or OVA
file.
• Shows how the appliance would be imported into Oracle VM VirtualBox. In addition,
the output shows any options that you can use to change the import behavior.
The shortened form of this option is -n.
--options=keepallmacs | keepnatmacs | importtovdi
Enables you to fine tune the import operation.
Valid arguments are as follows:
• keepallmacs: Specifies that the MAC addresses of every virtual network card are left
unchanged.
• keepnatmacs: Specifies that the MAC addresses of every virtual network card are left
unchanged if the network type is NAT.
• importtovdi: Specifies that all new disk images are in VDI file format.
--ostype=<ostype>
Specifies the guest operating system (OS) information for the VM. Use the
VBoxManage list ostypes command to view the OS type identifiers.
--vmname=<name>
Specifies the name of the VM to be used by Oracle VM VirtualBox.
--basefolder=<folder>
Specifies the folder where the files of the imported VM are stored.
--memory=<MB>
Specifies the memory size in Megabytes for the imported VM.
--cpus=<n>
Specifies the number of CPUs for the imported VM.
--description=<text>
Specifies the description text visible in the GUI and CLI when checking the VM details.
OVF / OVA Import Options
The following options are specific for importing a virtual appliance in OVF or OVA format. Such
an appliance can contain one or more VMs, which requires specifying which VM configuration
should be adjusted in case you want to change it. See chapter 2.15.2, Importing an Appliance in
OVF Format, page 31.
VBoxManage import <ovfname | ovaname> [--dry-run] [--options= keepallmacs
| keepnatmacs | importtovdi ] [--vsys=n] [--ostype=ostype] [--vmname=name]
[--settingsfile=file] [--basefolder=folder] [--group=group] [--memory=MB]
[--cpus=n] [--description=text] [--eula= show | accept ] [--unit=n]
217
9 VBoxManage
[--ignore] [--scsitype= BusLogic | LsiLogic ] [--disk=path]
[--controller=index] [--port=n]
--vsys=<n>
Specifies the index selecting a specific VM within the appliance. Affects the following
options.
--unit=<n>
Specifies the index selecting a specific unit of a VM within the appliance. Affects the fol-
lowing options.
--settingsfile=<file>
Specifies the name (with or without path) of the VM config file which will be created as
part of the import. Usually the preferred way is overriding the VM name with --vmname
and if necessary specify the folder in which to create the VM with --basefolder.
--group=<group>
Specifies the primary group of the imported VM.
--eula=show | accept
Enables you to show or accept the license conditions of a VM within the appliance,
Valid arguments are as follows:
• show: Shows the EULA of a VM.
• accepts: Accepts the EULA of a VM. Any VMs in an appliance which have an EULA
require accepting it, otherwise the import will fail.
--ignore
Ignores the current unit of an imported VM, effectively removing the associated hardware.
--scsitype=BusLogic | LsiLogic
Enables you to select the type of the SCSI controller for the current unit of an imported
VM.
Valid arguments are as follows:
• BusLogic: Uses the (very old) BusLogic SCSI controller type.
• LsiLogic: Uses the (more modern) LsiLogic SCSI controller type.
Cloud Import Options
The following options are specific for importing a VM instance from a cloud service provider.
It always deals with a single VM. See chapter 2.16.9, Importing an Instance from Oracle Cloud
Infrastructure, page 45.
VBoxManage import OCI:// --cloud [--ostype=ostype] [--vmname=name]
[--basefolder=folder] [--memory=MB] [--cpus=n] [--description=text]
<--cloudprofile=profile> <--cloudinstanceid=id>
[--cloudbucket=bucket]
--cloud
Specifies that the import should be from the cloud.
218
9 VBoxManage
--cloudprofile=<profile>
Specifies the cloud profile which is used to connect to the cloud service provider. The cloud
profile contains your Oracle Cloud Infrastructure account details, such as your user OCID
and the fingerprint for your public key. To use a cloud profile, you must have the required
permissions on Oracle Cloud Infrastructure.
--cloudinstanceid=<id>
Specifies the ID of an existing instance in the cloud.
--cloudbucket=<bucket>
Specifies the bucket name in which to store the object created from the instance. In Oracle
Cloud Infrastructure, a bucket is a logical container for storing objects. By default the first
bucket available with the cloud profile is used.
Examples
The following example performs the dry run of an OVF import operation for a sample appliance
that contains a Windows 10 guest:
$ VBoxManage import Windows10.ovf --dry-run
Interpreting Windows10.ovf...
OK.
Virtual system 0:
0: Suggested OS type: "Windows10_64"
(change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all)
1: Suggested VM name "win10-appliance"
(change with "--vsys 0 --vmname <name>")
2: Suggested VM group "/"
(change with "--vsys 0 --group <group>")
3: Suggested VM settings file name "/home/user1/VirtualBox VMs/win10-appliance/win10-appliance.vbox"
(change with "--vsys 0 --settingsfile <filename>")
4: Suggested VM base folder "/home/user1/VirtualBox VMs"
(change with "--vsys 0 --basefolder <path>")
5: End-user license agreement
(display with "--vsys 0 --eula show";
accept with "--vsys 0 --eula accept")
6: Number of CPUs: 1
(change with "--vsys 0 --cpus <n>")
7: Guest memory: 2048 MB (change with "--vsys 0 --memory <MB>")
8: Sound card (appliance expects "ensoniq1371", can change on import)
(disable with "--vsys 0 --unit 8 --ignore")
9: USB controller
(disable with "--vsys 0 --unit 9 --ignore")
10: Network adapter: orig bridged, config 2, extra type=bridged
11: Floppy
(disable with "--vsys 0 --unit 11 --ignore")
12: SCSI controller, type BusLogic
(change with "--vsys 0 --unit 12 --scsitype {BusLogic|LsiLogic}";
disable with "--vsys 0 --unit 12 --ignore")
13: IDE controller, type PIIX4
(disable with "--vsys 0 --unit 13 --ignore")
14: Hard disk image: source image=Windows10.vmdk,
target path=/home/user1/disks/Windows10.vmdk, controller=12;channel=0
(change target path with "--vsys 0 --unit 14 --disk <path>";
change controller with "--vsys 0 --unit 14 --controller <index>";
change controller port with "--vsys 0 --unit 14 --port <n>";
disable with "--vsys 0 --unit 14 --ignore")
The dry run output lists and numbers the individual configuration items that are described in
the Windows10.ovf file. Some of the items include information about how to disable or change
the configuration of the item.
219
9 VBoxManage
You can disable many of the items by using the --vsys <X> --unit <Y> --ignore options.
X is the number of the virtual system. The value is 0 unless the appliance includes several virtual
system descriptions. Y is the configuration item number.
Item 1 in the example command output specifies the name of the target machine. Items 12
and 13 specify the IDE and SCSI hard disk controllers, respectively.
Item 14 indicates the hard disk image and the --disk option specifies the target path where
the image will be stored, the --controller option specifies which controller the disk will be
attached to, and the --port option specifies which port on the controller the disk will be attached
to. The default values are specified in the OVF file.
You can combine several items for the same virtual system by specifying the same value for
the --vsys option. For example use the following command to import a machine as described
in the OVF, exclude the sound card and USB controller and specify that the disk image is stored
with a different name.
$ VBoxManage import Windows10.ovf --vsys 0 --unit 8 --ignore \
--unit 9 --ignore --unit 14 --disk Windows10_disk0.vmdk
The following example illustrates how to import a VM from Oracle Cloud Infrastructure. To
find the Oracle Cloud Infrastructure VM instances and its ID you can list all available instances
with:
$ VBoxManage cloud --provider=OCI --profile=<cloud-profile-name> list instances
Once you know the ID the following command imports the instance from Oracle Cloud Infras-
tructure:
$ VBoxManage import OCI:// --cloud --vmname OCI_FreeBSD_VM --memory 4000 \
--cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" \
--cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket
9.17 VBoxManage export
Export one or more virtual machines to a virtual appliance or to a cloud service.
Synopsis
VBoxManage export <machines> <--output=name> [--legacy09 | --ovf09
| --ovf10 | --ovf20] [--manifest] [--options= manifest | iso | nomacs
| nomacsbutnat . . .
]
[--vsys=virtual-system-number]
[--description=description-info] [--eula=license-text]
[--eulafile=filename] [--product=product-name]
[--producturl=product-URL] [--vendor=vendor-name]
[--vendorurl=vendor-URL] [--version=version-info] [--vmname=vmname]
VBoxManage export <machine> <--output=cloud-service-provider> [--opc10]
[--vmname=vmname] [--cloud=virtual-system-number]
[--cloudprofile=cloud-profile-name] [--cloudshape=cloud-shape-name]
[--clouddomain=cloud-domain] [--clouddisksize=disk-size-in-GB]
[--cloudbucket=bucket-name] [--cloudocivcn=OCI-VCN-ID]
[--cloudocisubnet=OCI-subnet-ID] [--cloudkeepobject= true | false ]
[--cloudlaunchinstance= true | false ] [--cloudlaunchmode= EMULATED
| PARAVIRTUALIZED ] [--cloudpublicip= true | false ]
220
9 VBoxManage
Description
The VBoxManage export command enables you to export one or more virtual machines (VMs)
from Oracle VM VirtualBox. You can export the VM to one of the following:
• Virtual appliance in OVF format. Includes the copying of its virtual disk images to com-
pressed VMDK.
• Cloud service such as Oracle Cloud Infrastructure. Exports a single VM.
For more information about exporting VMs from Oracle VM VirtualBox, see chapter 2.15,
Importing and Exporting Virtual Machines, page 30
Export a Virtual Machine to an OVF Virtual Appliance
VBoxManage export <machines> <--output=name> [--legacy09 | --ovf09
| --ovf10 | --ovf20] [--manifest] [--options= manifest | iso | nomacs
| nomacsbutnat . . .
]
[--vsys=virtual-system-number]
[--description=description-info] [--eula=license-text]
[--eulafile=filename] [--product=product-name]
[--producturl=product-URL] [--vendor=vendor-name]
[--vendorurl=vendor-URL] [--version=version-info] [--vmname=vmname]
The VBoxManage export command enables you to export a VM as a virtual appliance in OVF
format.
machines
Specifies a comma-separated list of one or more machines to export to the same OVF file.
--output=<filename>
Specifies the target OVF file. The file can be OVF, OVA, or a ZIP file compressed with the
gzip command. Because the directory that contains the target OVF file will also store
the exported disk images in the compressed VMDK format, ensure that this directory has
sufficient disk space in which to store the images.
The short form of this option is -o.
--legacy09
Exports in OVF 0.9 legacy mode if the virtualization product is not fully compatible with
the OVF 1.0 standard.
--ovf09
Exports in OVF 0.9 format.
--ovf10
Exports in OVF 1.0 format.
--ovf20
Exports in OVF 2.0 format.
--manifest
Creates a manifest of the exported files.
--options=<argument>,...
Specifies information to control the exact content of the appliance file. Specify one or more
comma-separated arguments:
manifest
Produces a manifest file that detects corrupted appliances on import.
221
9 VBoxManage
iso
Exports DVD images in an ISO file.
nomacs
Excludes all MAC addresses.
nomacsbutnat
Excludes all MAC addresses except for those in a NAT network.
--description=<description-info>
Specifies a description of the VM.
--eula=<license-text>
Specifies end-user license text.
--eulafile=<filename>
Specifies an end-user license file.
--product=<product-name>
Specifies a product name.
--producturl=<product-URL>
Specifies a product URL.
--vendor=<vendor-name>
Specifies a vendor name.
--vendorurl=<vendor-URL>
Specifies a vendor URL.
--version=<version-info>
Specifies version information.
--vmname=<vmname>
Specifies the name of the exported VM.
--vsys=<virtual-system-number>
Specifies the number of the virtual system.
Export a Virtual Machine to Oracle Cloud Infrastructure
VBoxManage export <machine> <--output=cloud-service-provider> [--opc10]
[--vmname=vmname] [--cloud=virtual-system-number]
[--cloudprofile=cloud-profile-name] [--cloudshape=cloud-shape-name]
[--clouddomain=cloud-domain] [--clouddisksize=disk-size-in-GB]
[--cloudbucket=bucket-name] [--cloudocivcn=OCI-VCN-ID]
[--cloudocisubnet=OCI-subnet-ID] [--cloudkeepobject= true | false ]
[--cloudlaunchinstance= true | false ] [--cloudlaunchmode= EMULATED
| PARAVIRTUALIZED ] [--cloudpublicip= true | false ]
The VBoxManage export command enables you to export a VM to a cloud service provider
such as Oracle Cloud Infrastructure. By default, the exported disk image is converted into com-
pressed VMDK format. This minimizes the amount of data to transfer to the cloud service.
Some of the following options are configuration settings for the VM instance. As a result,
specify an Oracle Cloud Identifier (OCID) for a resource. Use the Oracle Cloud Infrastructure
Console to view OCIDs.
222
9 VBoxManage
--output=<cloud-service-provider>
Specifies the short name of the cloud service provider to which you export the VM. For
Oracle Cloud Infrastructure, specify OCI://.
The short form of this option is -o.
--opc10
Exports in Oracle Cloud Infrastructure format.
--cloud=<number-of-virtual-system>
Specifies a number that identifies the VM to export. Numbering starts at 0 for the first VM.
--vmname=<vmname>
Specifies the name of the exported VM, which is used as the VM instance name in Oracle
Cloud Infrastructure.
--cloudprofile=<cloud-profile-name>
Specifies the cloud profile to use to connect to the cloud service provider. The cloud profile
contains your Oracle Cloud Infrastructure account details, such as your user OCID and the
fingerprint for your public key.
To use a cloud profile, you must have the required permissions on Oracle Cloud Infrastruc-
ture.
--cloudshape=<cloud-shape-name>
Specifies the shape used by the VM instance. The shape defines the number of CPUs and
the amount of memory that is allocated to the VM instance. Ensure that the shape is
compatible with the exported image.
--clouddomain=<cloud-domain>
Specifies the availability domain to use for the VM instance. Enter the full name of the
availability domain.
--clouddisksize=<disk-size-in-GB>
Specifies the amount of disk space, in gigabytes, to use for the exported disk image. Valid
values are from 50 GB to 300 GB.
--cloudbucket=<bucket-name>
Specifies the bucket in which to store uploaded files. In Oracle Cloud Infrastructure, a
bucket is a logical container for storing objects.
--cloudocivcn=<OCI-VCN-ID>
Specifies the OCID of the virtual cloud network (VCN) to use for the VM instance.
--cloudocisubnet=<OCI-subnet-ID>
Specifies the OCID of the VCN subnet to use for the VM instance.
--cloudkeepobject=true | false
Specifies whether to store the exported disk image in Oracle Object Storage.
--cloudlaunchinstance=true | false
Specifies whether to start the VM instance after the export to Oracle Cloud Infrastructure
completes.
--cloudlaunchinstance=EMULATED | PARAVIRTUALIZED
Specifies the launch mode used for the instance. Paravirtualized mode gives improved
performance.
--cloudpublicip=true | false
Specifies whether to enable a public IP address for the VM instance.
223
9 VBoxManage
Example
The following example shows how to export the myVM VM to Oracle Cloud Infrastructure. The
command’s option arguments describe the configuration of the myVM_Cloud VM in Oracle Cloud
Infrastructure.
# VBoxManage export myVM --output=OCI:// --cloud=0 --vmname=myVM_Cloud \
--cloudprofile="standard user" --cloudbucket=myBucket \
--cloudshape=VM.Standard2.1 --clouddomain=US-ASHBURN-AD-1 --clouddisksize=50
\
--cloudocivcn=ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet=ocid1.subnet.oc1.iad.aaaa... \
--cloudkeepobject=true --cloudlaunchinstance=true --cloudpublicip=true
9.18 VBoxManage signova
Digitally sign an OVA.
Synopsis
VBoxManage signova <ova> <--certificate=file> <--private-key=file>
[--private-key-password-file=password-file
| --private-key-password=password] [--digest-type=type] [--pkcs7
| --no-pkcs7] [--intermediate-cert=file] [--force] [--verbose] [--quiet]
[--dry-run]
Description
The VBoxManage signova command adds a digital signature to an OVA file.
ova
The OVA file to sign.
--certificate=<file>
File containing the certificate that the OVA should be signed with. This can either be in
PEM format (base64) or DER (binary), the command will detect which.
--private-key=<file>
The file containing the private key. This can either be in PEM (base64) or DER (binary)
format, the command will detect which.
--private-key-password-file=<password-file>
File containing the private key password.
--private-key-password=<password>
The private key password.
--digest-type=<type>
Select the cryptographic digest algorithm to use in the signing. Possible values: SHA-256
(default), SHA-512 and SHA-1.
Some older versions of OVFTool and other VMware produces may require
--digest-type=sha-1 to accept the OVA.
--pkcs7, --no-pkcs7
Enables or disables the creation of an additional PKCS#7/CMS signature. This is enabled
by default.
224
9 VBoxManage
--intermediate-cert=<file>
File containing an intermediary certificate that should be included in the optional
PKCS#7/CMS signature. Like the others, the file can either be in PEM or DER format.
This option can be repeated to add multiple intermediate certificates. This option implies
the --pkcs7 option.
--force
Overwrite existing signature if present. The default behaviour is to fail if the OVA is already
signed.
--dry-run
Do not actually modify the OVA, just test-run the signing operation.
-v, --verbose, -q, --quiet
Controls the verbositity of the command execution. The --verbose option can be used
multiple times to get more output.
9.19 VBoxManage startvm
Start a virtual machine.
Synopsis
VBoxManage startvm <uuid | vmname . . . > [--putenv=name[=value]] [--type= [gui
| headless | sdl | separate] ] --password file --password-id password
identifier
Description
The VBoxManage startvm command starts an Oracle VM VirtualBox virtual machine (VM) that
is in the Powered Off or Saved state.
uuid | vmname
Specifies the name or Universally Unique Identifier (UUID) of the VM.
--putenv=<name>=<value>
Assigns a value to an environment variable as a name-value pair.
For example,
VBOX_DISABLE_HOST_DISK_CACHE=1.
The short form of this option is -E.
--type=gui | headless | sdl | separate
Specifies the frontend used to start the VM.
You can use the VBoxManage setproperty command to set a global default value for the
frontend. Alternatively, you can use the VBoxManage modifyvm command to specify a
default frontend value for a specific VM. If neither a global or per-VM default value is set
and you do not specify the --type option, then the VM opens in a window on the host
desktop.
The --type option accepts the following values:
gui
Starts a VM in a graphical user interface (GUI) window. This is the default.
headless
Starts a VM for remote display only.
225
9 VBoxManage
sdl
Starts a VM using the VBoxSDL frontend.
separate
Starts a VM with a detachable user interface (UI), which means that the VM runs
headless with the UI in a separate process.
This is an experimental feature that lacks certain functionality, such as 3D accelera-
tion.
--password
Use the --password to supply the encryption password. Either specify the absolute path-
name of a password file on the host operating system, or - to prompt you for the password
on the command line.
--password-id
Use the --password-id option to specify the id the password is supplied for.
Note: If a VM fails to start with a particular frontend and the error information is in-
conclusive, consider starting the VM directly by running the frontend. This workaround
might provide additional error information.
Examples
The following command starts the ol7u6 VM:
$ VBoxManage startvm ol7u6
The following command starts the ol7u6-mininstall VM in headless mode.
$ VBoxManage startvm ol7u6-mininstall --type headless
See Also
chapter 8.1.2, VBoxHeadless, the Remote Desktop Server, page 144, chapter 9.40, VBoxManage
setproperty, page 275, chapter 9.10, VBoxManage modifyvm, page 180.
9.20 VBoxManage controlvm
Change state and settings for a running virtual machine.
Synopsis
VBoxManage controlvm <uuid | vmname> pause
VBoxManage controlvm <uuid | vmname> resume
VBoxManage controlvm <uuid | vmname> reset
VBoxManage controlvm <uuid | vmname> poweroff
VBoxManage controlvm <uuid | vmname> savestate
VBoxManage controlvm <uuid | vmname> acpipowerbutton
226
9 VBoxManage
VBoxManage controlvm <uuid | vmname> acpisleepbutton
VBoxManage controlvm <uuid | vmname> reboot
VBoxManage controlvm <uuid | vmname> shutdown [--force]
VBoxManage controlvm <uuid | vmname> keyboardputscancode <hex> [hex. . . ]
VBoxManage controlvm <uuid | vmname> keyboardputstring <string> [string. . . ]
VBoxManage controlvm <uuid | vmname> keyboardputfile <filename>
VBoxManage controlvm <uuid | vmname> setlinkstateN <on | off>
VBoxManage controlvm <uuid | vmname> nicN <null | nat | bridged | intnet
| hostonly | generic | natnetwork> [device-name]
VBoxManage controlvm <uuid | vmname> nictraceN <on | off>
VBoxManage controlvm <uuid | vmname> nictracefileN <filename>
VBoxManage controlvm <uuid | vmname> nicpropertyN <prop-name=prop-value>
VBoxManage controlvm <uuid | vmname> nicpromiscN <deny | allow-vms
| allow-all>
VBoxManage controlvm <uuid | vmname> natpfN <[rulename] ,tcp | udp,
[host-IP] , hostport, [guest-IP] , guestport >
VBoxManage controlvm <uuid | vmname> natpfN delete <rulename>
VBoxManage controlvm <uuid | vmname> guestmemoryballoon <balloon-size>
VBoxManage controlvm <uuid | vmname> usbattach <uuid | address>
[--capturefile=filename]
VBoxManage controlvm <uuid | vmname> usbdetach <uuid | address>
VBoxManage controlvm <uuid | vmname> audioin <on | off>
VBoxManage controlvm <uuid | vmname> audioout <on | off>
VBoxManage controlvm <uuid | vmname> clipboard mode <disabled | hosttoguest
| guesttohost | bidirectional>
VBoxManage controlvm <uuid | vmname> clipboard filetransfers <on | off>
VBoxManage controlvm <uuid | vmname> draganddrop <disabled | hosttoguest
| guesttohost | bidirectional>
VBoxManage controlvm <uuid | vmname> vrde <on | off>
VBoxManage controlvm <uuid | vmname> vrdeport <port>
VBoxManage controlvm <uuid | vmname> vrdeproperty <prop-name=prop-value>
VBoxManage controlvm <uuid | vmname> vrdevideochannelquality <percentage>
VBoxManage controlvm <uuid | vmname> setvideomodehint <xres> <yres>
<bpp> [[display] [enabled:yes | no | [x-originÂăy-origin]] ]
227
9 VBoxManage
VBoxManage controlvm <uuid | vmname> setscreenlayout <display> <on
| primary x-originÂăy-originÂăx-resolutionÂăy-resolutionÂăbpp | off>
VBoxManage controlvm <uuid | vmname> screenshotpng <filename> [display]
VBoxManage controlvm <uuid | vmname> recording <on | off>
VBoxManage controlvm <uuid | vmname> recording screens <all | none
| screen-ID[,screen-ID...]>
VBoxManage controlvm <uuid | vmname> recording filename <filename>
VBoxManage controlvm <uuid | vmname> recording videores <widthxheight>
VBoxManage controlvm <uuid | vmname> recording videorate <rate>
VBoxManage controlvm <uuid | vmname> recording videofps <fps>
VBoxManage controlvm <uuid | vmname> recording maxtime <sec>
VBoxManage controlvm <uuid | vmname> recording maxfilesize <MB>
VBoxManage controlvm <uuid | vmname> setcredentials <username>
--passwordfile= <filename | password> <domain-name> --allowlocallogon=
<yes | no>
VBoxManage controlvm <uuid | vmname> teleport <--host=host-name>
<--port=port-name> [--maxdowntime=msec] [--passwordfile=filename
| --password=password]
VBoxManage controlvm <uuid | vmname> plugcpu <ID>
VBoxManage controlvm <uuid | vmname> unplugcpu <ID>
VBoxManage controlvm <uuid | vmname> cpuexecutioncap <num>
VBoxManage controlvm <uuid | vmname> vm-process-priority <default | flat
| low | normal | high>
VBoxManage controlvm <uuid | vmname> webcam attach [pathname [settings] ]
VBoxManage controlvm <uuid | vmname> webcam detach [pathname]
VBoxManage controlvm <uuid | vmname> webcam list
VBoxManage controlvm <uuid | vmname> addencpassword <ID> <password-file
| -> [--removeonsuspend= yes | no ]
VBoxManage controlvm <uuid | vmname> removeencpassword <ID>
VBoxManage controlvm <uuid | vmname> removeallencpasswords
VBoxManage controlvm <uuid | vmname> changeuartmodeN disconnected
| server pipe-name | client pipe-name | tcpserver port
| tcpclient hostname:port | file filename | device-name
VBoxManage controlvm <uuid | vmname> autostart-enabledN on | off
VBoxManage controlvm <uuid | vmname> autostart-delayseconds
228
9 VBoxManage
Description
The VBoxManage controlvm command enables you to change the state of a running virtual
machine (VM). The following sections describe the subcommands that you can use:
Pause a Virtual Machine
VBoxManage controlvm <uuid | vmname> pause
The VBoxManage controlvm vmname pause command temporarily stops the execution of a
VM. When paused, the VM’s state is not permanently changed.
The VM window appears as gray and the title bar of the window indicates that the VM is
currently Paused. This action is equivalent to selecting Pause from the Machine menu of the
GUI.
Resume a Paused Virtual Machine
VBoxManage controlvm <uuid | vmname> resume
The VBoxManage controlvm vmname resume command restarts the execution of a paused
VM. This action is equivalent to selecting Resume from the Machine menu of the GUI.
Reset a Virtual Machine
VBoxManage controlvm <uuid | vmname> reset
The VBoxManage controlvm vmname reset command performs a cold reset the VM. This
command has the same effect on a VM as pressing the Reset button on a physical computer.
The cold reboot immediately restarts and reboots the guest operating system (OS). The state
of the VM is not saved prior to the reset, so data might be lost. This action is equivalent to
selecting Reset from the Machine menu of the GUI.
Power Off a Virtual Machine
VBoxManage controlvm <uuid | vmname> poweroff
The VBoxManage controlvm vmname poweroff command powers off the VM. This command
has the same effect on a VM as pulling the power cable on a physical computer.
The state of the VM is not saved prior to poweroff, so data might be lost. This action is
equivalent to selecting Close from the Machine menu of the GUI or to clicking the VM window’s
Close button, and then selecting Power Off the Machine.
When in the powered off state, you can restart the VM. See chapter 9.19, VBoxManage startvm,
page 225.
Save the State of a Virtual Machine
VBoxManage controlvm <uuid | vmname> savestate
The VBoxManage controlvm vmname savestate command saves the current state of the VM
to disk and then stops the VM.
This action is equivalent to selecting Close from the Machine menu of the GUI or to clicking
the VM window’s Close button, and then selecting Save the Machine State.
When in the saved state, you can restart the VM. It will continue exactly in the state you saved.
229
9 VBoxManage
Send an APCI Shutdown Signal to a Virtual Machine
VBoxManage controlvm <uuid | vmname> acpipowerbutton
The VBoxManage controlvm vmname acpipowerbutton command sends an ACPI shutdown
signal to the VM. This command has the same effect on a VM as pressing the Power button on a
physical computer.
So long as the VM runs a guest OS that provides appropriately configured ACPI support, this
command triggers an operating system shutdown from within the VM.
Send an APCI Sleep Signal to a Virtual Machine
VBoxManage controlvm <uuid | vmname> acpisleepbutton
The VBoxManage controlvm vmname acpisleepbutton command sends an ACPI sleep sig-
nal to the VM.
So long as the VM runs a guest OS that provides appropriately configured ACPI support, this
command triggers a sleep mechanism from within the VM.
Reboot the guest OS
VBoxManage controlvm <uuid | vmname> reboot
The VBoxManage controlvm vmname reboot command asks the guest OS to reboot itself.
This commands requires Guest Additions to be installed in the VM.
Shut down the guest OS
VBoxManage controlvm <uuid | vmname> shutdown [--force]
The VBoxManage controlvm vmname shutdown command asks the guest OS to halt + shut-
down, optionally forcing the shutdown.
This commands requires Guest Additions to be installed in the VM.
Send Keyboard Scancodes to a Virtual Machine
VBoxManage controlvm <uuid | vmname> keyboardputscancode <hex> [hex. . . ]
The VBoxManage controlvm vmname keyboardputscancode command sends keyboard
scancode commands to the VM.
For information about keyboard scancodes, see http://www.win.tue.nl/~aeb/linux/kbd/
scancodes-1.html.
Send Keyboard Strings to a Virtual Machine
VBoxManage controlvm <uuid | vmname> keyboardputstring <string> [string. . . ]
The VBoxManage controlvm vmname keyboardputstring command sends keyboard strings
to the VM.
230
9 VBoxManage
Send a File to a Virtual Machine
VBoxManage controlvm <uuid | vmname> keyboardputfile <filename>
The VBoxManage controlvm vmname keyboardputfile command sends a file to the VM.
Set the Link State for a Virtual Machine
VBoxManage controlvm <uuid | vmname> setlinkstateN <on | off>
VBoxManage controlvm vmname setlinkstateN command enables you to connect or dis-
connect the virtual network cable from the network interface instance (N). Valid values are on
and off. The default value is on.
Set the Type of Networking to Use for a Virtual Machine
VBoxManage controlvm <uuid | vmname> nicN <null | nat | bridged | intnet
| hostonly | generic | natnetwork> [device-name]
The VBoxManage controlvm vmname nicN command specifies the type of networking to use
on the specified VM’s virtual network card. N numbering begins with 1.
The following valid network types are also described in chapter 7.2, Introduction to Networking
Modes, page 129:
• null specifies that the VM is is not connected to the host system.
• nat specifies that the VM uses network address translation (NAT).
• bridged specifies that the VM uses bridged networking.
• intnet specifies that the VM communicates with other VMs by using internal networking.
• hostonly specifies that the VM uses host-only networking.
• natnetwork specifies that the VM uses NAT networking.
• generic specifies that the VM has access to rarely used submodes
Trace the Network Traffic of a Virtual Machine
VBoxManage controlvm <uuid | vmname> nictraceN <on | off>
The VBoxManage controlvm vmname nictraceN command enables you to trace the network
traffic on the specified virtual network card (N). N numbering begins with 1. Valid values are on
and off. The default value is off.
If you did not configure a file name for the trace file then a default one is used, placing it in
the VM subdirectory.
Specify the Network Traffic Trace Log File for a Virtual Machine
VBoxManage controlvm <uuid | vmname> nictracefileN <filename>
The VBoxManage controlvm vmname nictracefileN command enables you to specify the
name of the network traffic trace log file for the specified virtual network card (N). N numbering
begins with 1.
231
9 VBoxManage
Specify the Promiscuous Mode to Use for a Virtual Machine
VBoxManage controlvm <uuid | vmname> nicpromiscN <deny | allow-vms
| allow-all>
The VBoxManage controlvm vmname nicpromiscN command enables you to specify how to
handle promiscuous mode for a bridged network. The default value of deny hides any traffic that
is not intended for this VM. The allow-vms value hides all host traffic from this VM but enables
the VM to see traffic to and from other VMs. The allow-all value removes this restriction
completely.
Specify the Network Backend Property Values for a Virtual Machine
VBoxManage controlvm <uuid | vmname> nicpropertyN <prop-name=prop-value>
The VBoxManage controlvm vmname nicpropertyNprop-name=prop-value command, in
combination with nicgenericdrv, enables you to pass property values to rarely-used network
backends.
Those properties are backend engine-specific, and are different between UDP Tunnel and the
VDE backend drivers. See chapter 7.8, UDP Tunnel Networking, page 137.
Specify a NAT Port Forwarding Rule for a Virtual Machine
VBoxManage controlvm <uuid | vmname> natpfN <[rulename] ,tcp | udp,
[host-IP] , hostport, [guest-IP] , guestport >
The VBoxManage controlvm vmname natpfN command specifies a NAT port-forwarding rule.
See chapter 7.3.1, Configuring Port Forwarding with NAT, page 131.
Delete a NAT Port Forwarding Rule for a Virtual Machine
VBoxManage controlvm <uuid | vmname> natpfN delete <rulename>
The VBoxManage controlvm vmname natpfN delete command deletes the specified NAT
port-forwarding rule. See chapter 7.3.1, Configuring Port Forwarding with NAT, page 131.
Change Size of a Virtual Machine’s Guest Memory Balloon
VBoxManage controlvm <uuid | vmname> guestmemoryballoon <balloon-size>
The VBoxManage controlvm vmname guestmemoryballoon command changes the size of
the guest memory balloon. The guest memory balloon is the memory allocated by the Oracle VM
VirtualBox Guest Additions from the guest OS and returned to the hypervisor for reuse by other
VMs. The value you specify is in megabytes. See chapter 5.10.1, Memory Ballooning, page 108.
Make a Host System USB Device Visible to a Virtual Machine
VBoxManage controlvm <uuid | vmname> usbattach <uuid | address>
[--capturefile=filename]
232
9 VBoxManage
The VBoxManage controlvm vmname usbattach command dynamically attaches a host USB
device to the VM, which makes it visible. You do not need to create a filter.
Specify a USB device by its Universally Unique Identifier (UUID) or by its address on the host
system. Use the VBoxManage list usbhost command to obtain information about USB devices
on the host system.
Use the --capturefile option to specify the absolute path of a file in which to write logging
data.
Make a Host System USB Device Invisible to a Virtual Machine
VBoxManage controlvm <uuid | vmname> usbdetach <uuid | address>
The VBoxManage controlvm vmname usbdetach command dynamically detaches a host USB
device from the VM, which makes it invisible. You do not need to create a filter.
Specify a USB device by its UUID or by its address on the host system.
Use the
VBoxManage list usbhost command to obtain information about USB devices on the host
system.
Enable or Disable Audio Capture From the Host System
VBoxManage controlvm <uuid | vmname> audioin <on | off>
The VBoxManage controlvm vmname audioin command specifies whether to enable or dis-
able audio capture from the host system. Valid values are on, which enables audio capture and
off, which disables audio capture. The default value is off.
Enable or Disable Audio Playback From a Virtual Machine
VBoxManage controlvm <uuid | vmname> audioout <on | off>
The VBoxManage controlvm vmname audioout command specifies whether to enable or dis-
able audio playback from the guest VM. Valid values are on, which enables audio playback and
off, which disables audio playback. The default value is off.
Specify How to Share the Host OS or Guest OS Clipboard
VBoxManage controlvm <uuid | vmname> clipboard mode <disabled | hosttoguest
| guesttohost | bidirectional>
The VBoxManage controlvm vmname clipboard mode command specifies how to share
the guest or host OS’s clipboard with the host system or VM. Valid values are disabled,
hosttoguest, guesttohost, and bidirectional. The default value is disabled. See chapter
4.4, General Settings, page 73.
This feature requires that the Oracle VM VirtualBox Guest Additions are installed in the VM.
Specify If Files Can Be Transferred Through the Clipboard
VBoxManage controlvm <uuid | vmname> clipboard filetransfers <on | off>
233
9 VBoxManage
The VBoxManage controlvm vmname clipboard filetransfers command specifies if it is
possible to transfer files through the clipboard between the host and VM, in the direction which
is allowed. Valid values are off and on. The default value is off.
This feature requires that the Oracle VM VirtualBox Guest Additions are installed in the VM.
Set the Drag and Drop Mode Between the Host System and a Virtual Machine
VBoxManage controlvm <uuid | vmname> draganddrop <disabled | hosttoguest
| guesttohost | bidirectional>
The VBoxManage controlvm vmname draganddrop command specifies the current drag and
drop mode to use between the host system and the VM. Valid values are disabled, hosttoguest,
guesttohost, and bidirectional. The default value is disabled. See chapter 5.4, Drag and
Drop, page 100.
This feature requires that the Oracle VM VirtualBox Guest Additions are installed in the VM.
Enable or Disable the VRDE Server
VBoxManage controlvm <uuid | vmname> vrde <on | off>
The VBoxManage controlvm vmname vrde command enables or disables the VirtualBox Re-
mote Desktop Extension (VRDE) server, if installed. Valid values are on and off. The default
value is off.
Specify VRDE Server Ports
VBoxManage controlvm <uuid | vmname> vrdeport <port>
The VBoxManage controlvm vmname vrdeport command specifies the port or range of ports
to which the VRDE server can bind. The default value is default or 0, which is the standard
RDP port, 3389.
Also see the --vrde-port option description in chapter 9.10, Remote Machine Settings, page
196.
Specify VRDE Server Port Numbers and IP Addresses
VBoxManage controlvm <uuid | vmname> vrdeproperty <prop-name=prop-value>
The VBoxManage controlvm vmname vrdeproperty command specifies the port numbers
and IP address on the VM to which the VRDE server can bind.
• TCP/Ports specifies a port or a range of ports to which the VRDE server can bind. The
default value is default or 0, which is the standard RDP port, 3389.
Also see the --vrde-port option description in chapter 9.10, Remote Machine Settings,
page 196.
• TCP/Address specifies the IP address of the host network interface to which the VRDE
server binds. When specified, the server accepts to connect only on the specified host
network interface.
Also see the --vrde-address option description in chapter 9.10, Remote Machine Settings,
page 196.
234
9 VBoxManage
•
VideoChannel/Enabled specifies whether to enable the VirtualBox Remote Desktop Proto-
col (VRDP) video channel. Valid values are 1 to enable the video channel and 0 to disable
the video channel. The default value is off. See chapter 8.1.9, VRDP Video Redirection,
page 150.
•
VideoChannel/Quality specifies the JPEG compression level on the VRDE server video
channel. Valid values are between 10% and 100%, inclusive. Lower values mean lower
quality but higher compression. The default value is 100. See chapter 8.1.9, VRDP Video
Redirection, page 150.
•
VideoChannel/DownscaleProtection specifies whether to enable the video channel
downscale protection feature. Specify 1 to enable the feature. This feature is disabled
by default.
When enabled, if the video’s size equals the shadow buffer size, the video is shown in full-
screen mode. If the video’s size is between full-screen mode and the downscale threshold,
the video is not shown as it might be an application window that is unreadable when
downscaled. When disabled, the downscale protection feature always attempts to show
videos.
•
Client/DisableDisplay specifies whether to disable the VRDE server display feature.
Valid values are 1 to disable the feature and an empty string ("") to enable the feature.
The default value is an empty string. See chapter 8.1.10, VRDP Customization, page 150.
•
Client/DisableInput specifies whether to disable the VRDE server input feature. Valid
values are 1 to disable the feature and an empty string ("") to enable the feature. The
default value is 1. See chapter 8.1.10, VRDP Customization, page 150.
•
Client/DisableAudio specifies whether to disable the VRDE server audio feature. Valid
values are 1 to disable the feature and an empty string ("") to enable the feature. The
default value is 1. See chapter 8.1.10, VRDP Customization, page 150.
•
Client/DisableUSB specifies whether to disable the VRDE server USB feature. Valid val-
ues are 1 to disable the feature and an empty string ("") to enable the feature. The default
value is 1. See chapter 8.1.10, VRDP Customization, page 150.
•
Client/DisableClipboard specifies whether to disable the VRDE clipboard feature. Valid
values are 1 to disable the feature and an empty string ("") to enable the feature. To
reenable the feature, use Client/DisableClipboard=. The default value is 1. See chapter
8.1.10, VRDP Customization, page 150.
•
Client/DisableUpstreamAudio specifies whether to disable the VRDE upstream audio
feature. Valid values are 1 to disable the feature and an empty string ("") to enable the
feature. To reenable the feature, use Client/DisableUpstreamAudio=. The default value
is 1. See chapter 8.1.10, VRDP Customization, page 150.
•
Client/DisableRDPDR specifies whether to disable the RDP Device Redirection For Smart
Cards feature on the VRDE server. Valid values are 1 to disable the feature and an empty
string ("") to enable the feature. The default value is 1. See chapter 8.1.10, VRDP Cus-
tomization, page 150.
•
H3DRedirect/Enabled specifies whether to enable the VRDE server 3D redirection fea-
ture. Valid values are 1 to enable the feature and an empty string ("") to disable the
feature. See chapter 8.1.10, VRDP Customization, page 150.
•
Security/Method specifies the security method to use for a connection. See chapter 8.1.6,
RDP Encryption, page 148.
235
9 VBoxManage
- Negotiate accepts both enhanced (TLS) and standard RDP security connections. The
security method is negotiated with the client. This is the default value.
- RDP accepts only standard RDP security connections.
- TLS accepts only enhanced RDP security connections. The client must support TLS.
• Security/ServerCertificate specifies the absolute path of the server certificate to use
for a connection. See chapter 8.1.6, RDP Encryption, page 148.
• Security/ServerPrivateKey specifies the absolute path of the server private key. See
chapter 8.1.6, RDP Encryption, page 148.
• Security/CACertificate specifies the absolute path of the CA self-signed certificate. See
chapter 8.1.6, RDP Encryption, page 148.
• Audio/RateCorrectionMode specifies the rate correction mode to use.
- VRDP_AUDIO_MODE_VOID indicates that no mode is specified. Use this value to unset
any audio mode that is already set.
- VRDP_AUDIO_MODE_RC specifies to use the rate correction mode.
- VRDP_AUDIO_MODE_LPF specifies to use the low pass filter mode.
- VRDP_AUDIO_MODE_CS specifies to use the client sync mode to prevent underflow or
overflow of the client queue.
• Audio/LogPath specifies the absolute path of the audio log file.
Specify the Image Quality for VRDP Video Redirection
VBoxManage controlvm <uuid | vmname> vrdevideochannelquality <percentage>
The VBoxManage controlvm vmname vrdevideochannelquality command sets the image
quality, as a JPEG compression level value, for video redirection. Valid values are between 10%
and 100%, inclusive. Lower values mean lower quality but higher compression. See chapter
8.1.9, VRDP Video Redirection, page 150.
Specify the Video Mode for the Guest VM
VBoxManage controlvm <uuid | vmname> setvideomodehint <xres> <yres>
<bpp> [[display] [enabled:yes | no | [x-originÂăy-origin]] ]
The VBoxManage controlvm vmname setvideomodehint command specifies the video
mode for the guest VM to use. You must have the Oracle VM VirtualBox Guest Additions in-
stalled. Note that this feature does not work for all guest systems.
Specify the Screen Layout for a Display on the Guest VM
VBoxManage controlvm <uuid | vmname> setscreenlayout <display> <on
| primary x-originÂăy-originÂăx-resolutionÂăy-resolutionÂăbpp | off>
The VBoxManage controlvm vmname setscreenlayout command can be used to configure
multiscreen displays. The specified screen on the guest VM can be enabled or disabled, or a
custom screen layout can be configured.
236
9 VBoxManage
Take a Screen Shot of the Virtual Machine Display
VBoxManage controlvm <uuid | vmname> screenshotpng <filename> [display]
The VBoxManage controlvm vmname screenshotpng command takes a screenshot of the
guest display and saves it as PNG in the specified file.
• filename specifies the name of the PNG file to create.
• display specifies the display number for the screen shot. For a single monitor guest dis-
play, this is 0.
Enable or Disable the Recording of a Virtual Machine Session
VBoxManage controlvm <uuid | vmname> recording <on | off>
The VBoxManage controlvm vmname recording command enables or disables the recording
of a VM session into a WebM/VP8 file. Valid values are on, which begins recording when the VM
session starts and off, which disables recording. The default value is off.
Specify the Virtual Machine Screens to Record
VBoxManage controlvm <uuid | vmname> recording screens <all | none
| screen-ID[,screen-ID...]>
The VBoxManage controlvm vmname recording screens command enables you to specify
which VM screens to record. The recording for each screen that you specify is saved to its own
file in the machine folder. You cannot modify this setting while recording is enabled.
• all specifies that you record all VM screens.
• none specifies that you do not record any VM screens.
• screen-ID specifies one or more VM screens to record.
Specify the File in Which to Save Virtual Machine Recording
VBoxManage controlvm <uuid | vmname> recording filename <filename>
The VBoxManage controlvm vmname recording filename command specifies the file in
which to save the recording. You cannot modify this setting while recording is enabled.
The default setting is to store a recording in the machine folder, using the VM name as the file
name, with a webm file name extension.
Specify the Resolution of the Recorded Video
VBoxManage controlvm <uuid | vmname> recording videores <widthxheight>
VBoxManage controlvm vmname recording videores command specifies the resolution of
the recorded video in pixels. You cannot modify this setting while recording is enabled.
Use the Settings tool to view the video recording settings, which are based on the resolution
(frame size). See the Frame Size field on the Recording tab of the Display page to view the
default value.
Specify the resolution as widthxheight:
237
9 VBoxManage
• width specifies the width in pixels.
• height specifies the height in pixels.
Specify the Bit Rate of the Video
VBoxManage controlvm <uuid | vmname> recording videorate <rate>
The VBoxManage controlvm vmname recording videorate command specifies the bit
rate, bit-rate, of the video in kilobits per second. Increasing this value improves the appear-
ance of the video at the cost of an increased file size. You cannot modify this setting while
recording is enabled.
Use the Settings tool to view the video recording settings, which are based on the frame size.
See the Video Quality field on the Recording tab of the Display page to view the default value.
Specify the Maximum Frequency of the Video
VBoxManage controlvm <uuid | vmname> recording videofps <fps>
The VBoxManage controlvm vmname recording videofps command specifies the maxi-
mum frequency of the video to record. Video frequency is measured in frames per second (FPS).
The recording skips any frames that have a frequency higher than the specified maximum. In-
creasing the frequency reduces the number of skipped frames and increases the file size. You
cannot modify this setting while recording is enabled.
Use the Settings tool to view the video recording settings, which are based on the frame size.
See the Frame Rate field on the Recording tab of the Display page to view the default value.
Specify the Maximum Amount of Time to Record Video
VBoxManage controlvm <uuid | vmname> recording maxtime <sec>
The VBoxManage controlvm vmname recording maxtime command 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.
Specify the Maximum Size of the Recorded Video
VBoxManage controlvm <uuid | vmname> recording maxfilesize <MB>
The VBoxManage controlvm vmname recording maxfilesize command specifies the max-
imum 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.
Specify Credentials for Remote Logins on Windows Virtual Machines
VBoxManage controlvm <uuid | vmname> setcredentials <username>
--passwordfile= <filename | password> <domain-name> --allowlocallogon=
<yes | no>
238
9 VBoxManage
The setcredentials command enables you to specify the credentials for remotely logging in
to Windows VMs. See chapter 10.1, Automated Guest Logins, page 332.
• username specifies the user name with which to log in to the Windows VM.
• --passwordfile=<filename> specifies the file from which to obtain the password for
username.
The --passwordfile is mutually exclusive with the --password option.
• --password=<password> specifies the password for username.
The --password is mutually exclusive with the --passwordfile option.
• --allowlocallogin specifies whether to enable or disable local logins. Valid values are
on to enable local logins and off to disable local logins.
Configure a Virtual Machine Target for Teleporting
VBoxManage controlvm <uuid | vmname> teleport <--host=host-name>
<--port=port-name> [--maxdowntime=msec] [--passwordfile=filename
| --password=password]
The VBoxManage controlvm vmname teleport command initiates a teleporting operation
between the specified VM and the specified host system. See chapter 8.2, Teleporting, page 151.
If you specify a password, it must match the password you specified when you issued the
VBoxManage modifyvm command for the target machine.
--host=<hostname>
Specifies the name of the VM.
--port=<port>
Specifies the port on the VM that should listen for a teleporting request from other VMs.
The port number can be any free TCP/IP port number, such as 6000.
--maxdowntime=<msec>
Specifies the maximum downtime, in milliseconds, for the teleporting target VM.
--password=<password>
Specifies the password that the source machine uses for the teleporting request. The re-
quest succeeds only if the source machine specifies the same password.
The --password is mutually exclusive with the --passwordfile option.
--passwordfile=<filename>
Specifies the file from which to obtain the password that the source machine uses for the
teleporting request. The request succeeds only if the source machine specifies the same
password.
When you specify a file name of stdin, you can read the password from standard input.
The --passwordfile is mutually exclusive with the --password option.
Add a Virtual CPU to a Virtual Machine
VBoxManage controlvm <uuid | vmname> plugcpu <ID>
The VBoxManage controlvm vmname plugcpu command adds a virtual CPU to the specified
VM if CPU hot-plugging is enabled. ID specifies the index of the virtual CPU to be added and
must be a number from 0 to the maximum number of CPUs configured.
239
9 VBoxManage
Remove a Virtual CPU From a Virtual Machine
VBoxManage controlvm <uuid | vmname> unplugcpu <ID>
The VBoxManage controlvm vmname unplugcpu command removes a virtual CPU from the
specified VM if CPU hot-plugging is enabled. ID specifies the index of the virtual CPU to be
removed and must be a number from 0 to the maximum number of CPUs configured. You cannot
remove CPU 0.
Set the Maximum Amount of Physical CPU Time Used by a Virtual CPU
VBoxManage controlvm <uuid | vmname> cpuexecutioncap <num>
The VBoxManage controlvm vmname cpuexecutioncap command specifies how the maxi-
mum amount of physical CPU time used by a virtual CPU. Valid values are a percentage between
1 and 100. A value of 50 specifies that a single virtual CPU can use up to 50% of a physical CPU.
The default value is 100.
Use this feature with caution, it can have unexpected results including timekeeping problems
and lower performance than specified. If you want to limit the resource usage of a VM it is more
reliable to pick an appropriate number of VCPUs.
Change the Priority of a VM Process
VBoxManage controlvm <uuid | vmname> vm-process-priority <default | flat
| low | normal | high>
The VBoxManage controlvm vmname vm-process-priority command specifies the priority
scheme of the VM process to use when starting the specified VM and while the VM runs.
Valid values are:
• default âĂS Default process priority determined by the OS.
• flat âĂS Assumes a scheduling policy which puts the process at the default priority and
with all threads at the same priority.
• low âĂS Assumes a scheduling policy which puts the process mostly below the default
priority of the host OS.
• normal âĂS Assume a scheduling policy which shares the CPU resources fairly with other
processes running with the default priority of the host OS.
• high âĂS 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.
Attach a Webcam to a Virtual Machine
VBoxManage controlvm <uuid | vmname> webcam attach [pathname [settings] ]
The VBoxManage controlvm vmname webcam attach command attaches a webcam to a run-
ning VM. Specify the webcam as the absolute path of the webcam on the host OS or as an alias.
Use the VBoxManage list webcams command to obtain the webcam alias.
240
9 VBoxManage
Note that the .0 alias is the default video input device on the host OS. .1 is the first video
input device, .2 is the second video input device, and so on. The order of the devices is specific
to the host system.
You can specify optional settings in the form of semi-colon-separated (;) name-value pairs.
These properties enable you to configure the emulated webcam device.
The following settings are supported:
MaxFramerate
Specifies the highest rate at which to send video frames to the VM. The rate is in frames
per second. Higher frame rates increase CPU load, so you can use this setting to reduce
CPU load. The default value is no maximum limit. This value enables the VM to use any
frame rate supported by the webcam.
MaxPayloadTransferSize
Specifies the maximum number of bytes that the VM receives from the emulated webcam
in one buffer. The default setting is 3060 bytes, which is used by some webcams. If the VM
is able to use larger buffers, higher values might reduce CPU load slightly. Note that some
guest OSes might not suppport higher MaxPayloadTransferSize values.
Detach a Webcam From a Virtual Machine
VBoxManage controlvm <uuid | vmname> webcam detach [pathname]
The VBoxManage controlvm vmname webcam detach command detaches a webcam from a
running VM. Specify the webcam as the absolute path of the webcam on the host OS or as an
alias. Use the VBoxManage list webcams to obtain the webcam alias.
When a webcam device is detached from the host, the host OS determines how the emulated
webcam behaves.
• Windows hosts: The emulated webcam device is detached from the VM automatically.
• Mac OS X hosts that run at least OS X
10.7: The emulated webcam de-
vice remains attached to the VM and you must detach it manually by using the
VBoxManage controlvm webcam detach command.
• Linux hosts: The emulated webcam device is detached from the VM automatically only
if the webcam is actively streaming video. If the emulated webcam is inactive, manually
detach it by using the VBoxManage controlvm vmname webcam detach command.
List the Webcams Attached to a Virtual Machine
VBoxManage controlvm <uuid | vmname> webcam list
The VBoxManage controlvm vmname webcam list command lists webcams that are at-
tached to the running VM. The output shows a list of absolute paths or aliases that attached the
webcams to the VM by using the VBoxManage controlvm vmname webcam attach command.
Set an Encryption Password for a Virtual Machine
VBoxManage controlvm <uuid | vmname> addencpassword <ID> <password-file
| -> [--removeonsuspend= yes | no ]
241
9 VBoxManage
The VBoxManage controlvm vmname addencpassword command provides the vmname en-
crypted VM with the encryption password to enable a headless start. Specify the absolute path
of a password file on the host system. If filename is -, VBoxManage prompts for the encryption
password.
Use the --removeonsuspend option to specify whether to save the passsword or clear it from
VM memory when the VM is suspended.
If
the
VM
is
suspended
and
the
password
is
cleared,
use
the
VBoxManage controlvm vmname addencpassword to provide the password to resume
execution on the VM. Use this feature when you do not want to store the password in VM
memory while the VM is suspended by a host suspend event.
Note: You can encrypt data stored on hard disk images used by the VM. Oracle VM
VirtualBox uses the AES algorithm in XTS mode and supports 128-bit or 256-bit data
encryption keys (DEK). The encrypted DEK is stored in the medium properties and is
decrypted during VM startup when you provide the encryption password.
Use the VBoxManage encryptmedium command to create a DEK encrypted medium. See chap-
ter 10.29.2, Encrypting Disk Images, page 377.
The Oracle VM VirtualBox GUI prompts you for the encryption password when you start an
encrypted VM.
Use the following command to perform a headless start of an encrypted VM:
$ VBoxManage startvm <vmname> --type headless
Then, use the following command to provide the encryption password:
$ VBoxManage <vmname> controlvm addencpassword <vmname> -
Password: <encryption-password>
Disable an Encryption Password for a Virtual Machine
VBoxManage controlvm <uuid | vmname> removeencpassword <ID>
The VBoxManage controlvm vmname removeencpassword command disables a specific en-
cryption password for all encrypted media attached to the VM.
ID is the password identifier for the encryption password that you want to disable.
Disable All Encryption Passwords for a Virtual Machine
VBoxManage controlvm <uuid | vmname> removeallencpasswords
The VBoxManage controlvm vmname removeallencpasswords command disables all en-
cryption passwords for all encrypted media attached to the VM.
Change the Connection Mode for a Virtual Serial Port on a Virtual Machine
VBoxManage controlvm <uuid | vmname> changeuartmodeN disconnected
| server pipe-name | client pipe-name | tcpserver port
| tcpclient hostname:port | file filename | device-name
242
9 VBoxManage
The VBoxManage controlvm vmname changeuartmode command changes the connection
mode for the specified virtual serial port. Valid serial port values are integers that start from
1.
disconnected
Disconnects the device.
server pipe-name
Specifies the pipe name of the server.
client pipe-name
Specifies the pipe name of the client.
tcpserver port
Specifies the port number of the TCP server.
tcpclient hostname:port
Specifies the host name and port number of the TCP client.
file filename
Specifies the name of the file.
device-name
Specifies the name of the device.
Enabling autostart the VM during host system boot
VBoxManage controlvm <uuid | vmname> autostart-enabledN on | off
The VBoxManage controlvm vmname autostart-enabled command specifies whether to
enable or disable automatically start 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 Ma-
chines During System Boot, page 370. Valid values are on, which enables autostart feature for the
VM and off, which disables it. The default value is off.
Setting the delay of starting the VM on host system boot
VBoxManage controlvm <uuid | vmname> autostart-delayseconds
The VBoxManage controlvm vmname autostart-delay command specifies the delay in sec-
onds before the VM starts on host system boot-up. See chapter 10.21, Starting Virtual Machines
During System Boot, page 370.
Examples
The following command temporarily stops the execution of the ol7 VM.
$ VBoxManage controlvm ol7 pause
The following command configures shared clipboard operation for the ol7 VM. Copying of
clipboard data is allowed in both directions between the host and guest.
$ VBoxManage controlvm ol7 clipboard mode bidirectional
243
9 VBoxManage
See Also
chapter 9.5, VBoxManage list, page 170, chapter 9.10, VBoxManage modifyvm, page 180, chapter
9.19, VBoxManage startvm, page 225
9.21 VBoxManage unattended
Unattended guest OS installation.
Synopsis
VBoxManage unattended detect <--iso=install-iso> [--machine-readable]
VBoxManage unattended install <uuid|vmname> <--iso=install-iso>
[--user=login] [--password=password] [--password-file=file]
[--full-user-name=name] [--key=product-key] [--install-additions]
[--no-install-additions] [--additions-iso=add-iso] [--install-txs]
[--no-install-txs] [--validation-kit-iso=testing-iso] [--locale=ll_CC]
[--country=CC] [--time-zone=tz] [--hostname=fqdn]
[--package-selection-adjustment=keyword] [--dry-run]
[--auxiliary-base-path=path] [--image-index=number]
[--script-template=file] [--post-install-template=file]
[--post-install-command=command]
[--extra-install-kernel-parameters=params] [--language=lang]
[--start-vm=session-type]
Description
unattended detect
VBoxManage unattended detect <--iso=install-iso> [--machine-readable]
Detects the guest operating system (OS) on the specified installation ISO and displays the
result. This can be used as input when creating a VM for the ISO to be installed in.
--iso=<install-iso>
The installation ISO to run the detection on.
--machine-readable
Produce output that is simpler to parse from a script.
unattended install
VBoxManage unattended install <uuid|vmname> <--iso=install-iso>
[--user=login] [--password=password] [--password-file=file]
[--full-user-name=name] [--key=product-key] [--install-additions]
[--no-install-additions] [--additions-iso=add-iso] [--install-txs]
[--no-install-txs] [--validation-kit-iso=testing-iso] [--locale=ll_CC]
[--country=CC] [--time-zone=tz] [--hostname=fqdn]
[--package-selection-adjustment=keyword] [--dry-run]
[--auxiliary-base-path=path] [--image-index=number]
[--script-template=file] [--post-install-template=file]
[--post-install-command=command]
[--extra-install-kernel-parameters=params] [--language=lang]
244
9 VBoxManage
[--start-vm=session-type]
Reconfigures the specified VM for installation and optionally starts it up.
uuid|vmname
Either the UUID or the name (case sensitive) of a VM.
--iso=<install-iso>
The installation ISO to run the detection on.
--user=<login>
The login name. (default: vboxuser)
--password=<password>
The login password.
This is used for the user given by --user as well as the
root/administrator user. (default: changeme)
--password-file=<file>
Alternative to --password for providing the password. Special filename stdin can be used
to read the password from standard input.
--full-user-name=<name>
The full user name. (default: -user)
--key=<product-key>
The guest OS product key. Not all guest OSes requires this.
--install-additions, --no-install-additions
Whether to install the VirtualBox guest additions. (default: -no-install-addations)
--additions-iso=<add-iso>
Path to the VirtualBox guest additions ISO. (default: installed/downloaded GAs)
--install-txs, --no-install-txs
Whether to install the test execution service (TXS) from the VirtualBox ValidationKit. This
is useful when preparing VMs for testing or similar. (default: -no-install-txs)
--validation-kit-iso=<testing-iso>
Path to the VirtualBox ValidationKit ISO. This is required if --install-txs is specified.
--locale=<ll_CC>
The base locale specification for the guest, like en_US, de_CH, or nn_NO. (default: host or
en_US)
--country=<CC>
The two letter country code if it differs from the specified by --location.
--time-zone=<tz>
The time zone to set up the guest OS with. (default: host time zone or UTC)
--hostname=<fqdn>
The
fully
qualified
domain
name
of
the
guest
machine.
(default:
vmname.myguest.virtualbox.org)
--package-selection-adjustment=<keyword>
Adjustments to the guest OS packages/components selection. This can be specfied more
than once. Currently the only recognized keyword is minimal which triggers a minimal
installation for some of the guest OSes.
245
9 VBoxManage
--dry-run
Do not create any files or make any changes to the VM configuration.
--start-vm=<session-type>
Start the VM using the front end given by session-type. This is the same as the --type
option for the startvm command, but we have add none for indicating that the VM should
not be started. (default: none)
Advanced options:
--auxiliary-base-path=<path>
The path prefix to the media related files generated for the installation. (default:
vm-config-dir/Unattended-vm-uuid-)
--image-index=<number>
Windows installation image index. (default: 1)
--script-template=<file>
The unattended installation script template. (default: IMachine::OSTypeId dependent)
--post-install-template=<file>
The post installation script template. (default: IMachine::OSTypeId dependent)
--post-install-command=<command>
A single command to run after the installation is completed. The exact format and exactly
when this is run is guest OS installer dependent.
--extra-install-kernel-parameters=<params>
List of extra linux kernel parameters to use during the installation. (default: IMa-
chine::OSTypeId dependent)
--language=<lang>
Specifies the UI language for a Windows installation. The lang is generally on the form
{ll}-{CC}. See detectedOSLanguages results from VBoxManage unattended detect. (de-
fault: detectedOSLanguages[0])
9.22 VBoxManage discardstate
Discard the saved state of a virtual machine.
Synopsis
VBoxManage discardstate <uuid | vmname>
Description
The VBoxManage discardstate command discards the saved state of a virtual machine (VM)
that is not currently running. This command causes the VM’s operating system to restart the next
time you start the VM.
Note: Where possible, avoid performing this action. The effects of this command are
equivalent to unplugging the power cable on a physical machine.
uuid|vmname
Specifies the Universally Unique Identifier (UUID) or name of the VM.
246
9 VBoxManage
Examples
The following command discards the saved state file for the VM called vm2. When you next start
the VM, the VM’s operating system is restarted.
$ VBoxManage discardstate vm2
See Also
chapter 9.23, VBoxManage adoptstate, page 247
9.23 VBoxManage adoptstate
Change a virtual machine’s state based on a saved state file.
Synopsis
VBoxManage adoptstate <uuid | vmname> <state-filename>
Description
The VBoxManage adoptstate command enables you to change the state of a virtual machine
(VM) to a state described in a saved state file (.sav). This action is referred to as a VM adopting
a saved state file. The saved state file must be separate from the VM configuration.
When you start the VM after adopting the saved state, the VM restores its state from the saved
state file.
Only use this command for custom deployments.
uuid | vmname
Specifies the Universally Unique Identifier (UUID) or name of the VM.
state-filename
Specifies the name of the saved state file.
Examples
The following command adopts a saved state file called mystate.sav by a VM called vm2. A
subsequent start of the VM called vm2 restores the state from the saved state file mystate.sav.
$ VBoxManage adoptstate vm2 /home/user/mystate.sav
See Also
chapter 9.22, VBoxManage discardstate, page 246
9.24 VBoxManage snapshot
Manage virtual machine snapshots.
247
9 VBoxManage
Synopsis
VBoxManage snapshot <uuid|vmname>
VBoxManage snapshot <uuid|vmname> take <snapshot-name>
[--description=description] [--live]
[--uniquename Number,Timestamp,Space,Force]
VBoxManage snapshot <uuid|vmname> delete <snapshot-name>
VBoxManage snapshot <uuid|vmname> restore <snapshot-name>
VBoxManage snapshot <uuid|vmname> restorecurrent
VBoxManage snapshot <uuid|vmname> edit <snapshot-name | --current>
[--description=description] [--name=new-name]
VBoxManage snapshot <uuid|vmname> list [[--details] | [--machinereadable]]
VBoxManage snapshot <uuid|vmname> showvminfo <snapshot-name>
Description
The VBoxManage snapshot command manages snapshots.
Oracle VM VirtualBox uses the snapshot to capture the state of a virtual machine (VM). You
can later use the snapshot to revert to the state described by the snapshot.
A snapshot is a complete copy of a VM’s settings. If you take the snapshot while the VM is
running, the snapshot also includes the VM’s state file.
After you take a snapshot, Oracle VM VirtualBox creates a differencing hard disk for each
normal hard disk that is associated with the host machine. When you restore a snapshot, Oracle
VM VirtualBox uses these differencing files to quickly reset the contents of the VM’s virtual hard
disks.
For each VBoxManage snapshot command, you must specify the name or the universal unique
identifier (UUID) of the VM for which you want to take a snapshot.
General Command Operand
uuid|vmname
Specifies the UUID or name of the VM.
Take a Snapshot of a Virtual Machine
VBoxManage snapshot <uuid|vmname> take <snapshot-name>
[--description=description] [--live]
[--uniquename Number,Timestamp,Space,Force]
The VBoxManage snapshot take command takes a snapshot of the current state of the VM.
You must supply a name for the snapshot and can optionally supply a description. The new
snapshot is inserted into the snapshots tree as a child of the current snapshot and then becomes
the new current snapshot.
--description=<description>
Specifies a description of the snapshot.
248
9 VBoxManage
--live
Specifies that the VM is not stopped while you create the snapshot. This operation is know
as live snapshotting.
--uniquename Number,Timestamp,Space,Force
TBD.
snapshot-name
Specifies the name of the snapshot to create.
Delete a Snapshot
VBoxManage snapshot <uuid|vmname> delete <snapshot-name>
The VBoxManage snapshot delete command removes the specified snapshot.
The delete operation may take some time to finish. This is because the differencing images that
are associated with the snapshot may need to be merged with their child differencing images.
snapshot-name
Specifies the UUID or name of the snapshot.
Restore a Snapshot
VBoxManage snapshot <uuid|vmname> restore <snapshot-name>
The VBoxManage snapshot restore command restores the specified snapshot. This opera-
tion resets the VM’s settings and current state to that of the snapshot. The state of the VM on
which you restore a snapshot is lost. When restored, the specified snapshot becomes the new
current snapshot and subsequent snapshots are children of that snapshot.
snapshot-name
Specifies the UUID or name of the snapshot.
Restore the Current Snapshot
VBoxManage snapshot <uuid|vmname> restorecurrent
The VBoxManage snapshot restorecurrent command restores the current snapshot. The
current snapshot is the one from which the current state is derived. This command is equivalent
to using the VBoxManage snapshot restore command and specifying the name or UUID of the
current snapshot.
Change the Name or Description of an Existing Snapshot
VBoxManage snapshot <uuid|vmname> edit <snapshot-name | --current>
[--description=description] [--name=new-name]
The VBoxManage snapshot edit command enables you to change the name or the descrip-
tion of a specified snapshot.
snapshot-name
Specifies the UUID or name of the snapshot to edit.
This option is mutually exclusive with the --current option.
249
9 VBoxManage
--current
Specifies that you update the current version of the snapshot.
This option is mutually exclusive with a specific snapshot name or its UUID.
--description=<description>
Specifies a new description for the snapshot.
--name=<new-name>
Specifies a new name for the snapshot.
List the Snapshots
VBoxManage snapshot <uuid|vmname> list [[--details] | [--machinereadable]]
The VBoxManage snapshot list command lists all the snapshots for a VM.
--details
Specifies that the output shows detailed information about the snapshot.
This option is mutually exclusive with the --machinereadable option.
--machinereadable
Specifies that the output is shown in a machine-readable format.
This option is mutually exclusive with the --details option.
Show Information About a Snapshot’s Settings
VBoxManage snapshot <uuid|vmname> showvminfo <snapshot-name>
The VBoxManage snapshot showvminfo command enables you to view the VM settings that
are part of an existing snapshot.
snapshot-name
Specifies the UUID or name of the snapshot.
Examples
The following command creates a snapshot of the ol7u4 VM. The snapshot is called
ol7u4-snap-001. The command uses the --description option to provide a description of
the snapshot contents.
$ VBoxManage snapshot ol7u4 take ol7u4-snap-001 \
--description="Oracle Linux 7.4"
The following command lists the snapshots for the ol7u4 VM.
$ VBoxManage snapshot ol7u4 list
The following command changes the description for the ol7u4-snap-001 snapshot of the
ol7u4 VM.
250
9 VBoxManage
$ VBoxManage snapshot ol7u4 edit ol7u4-snap-001 \
--description="Oracle Linux 7.4 with UEK4 kernel"
The following command shows VM settings for the ol7u1-snap-001 snapshot of the ol7u4
VM.
$ VBoxManage snapshot ol7u4 showvminfo ol7u4-snap-001
Name:
ol7u4
Groups:
/
Guest OS:
Oracle (64-bit)
UUID:
43349d78-2ab3-4cb8-978f-0e755cd98090
Config file:
C:\Users\user1\VirtualBox VMs\ol7u4\ol7u4.vbox
Snapshots:
Name: ol7u4-snap-001 (UUID: 1cffc37d-5c37-4b86-b9c5-a0f157a55f43)
Description: Oracle Linux 7.4 with UEK4 kernel
9.25 VBoxManage closemedium
Remove a hard disk, DVD, or floppy image from the media registry.
Synopsis
VBoxManage closemedium [disk | dvd | floppy] <uuid | filename> [--delete]
Description
The VBoxManage closemedium command removes a hard disk, DVD, or floppy image from the
list of known media used by Oracle VM VirtualBox. The image is then unavailable for selection
in the Virtual Media Manager.
To use this command, the image must not be attached to any VMs.
Optionally, you can request that the image be deleted.
disk|dvd|floppy
Specifies the type of medium. Valid values are disk (hard drive), dvd, or floppy.
uuid|filename
Specifies the Universally Unique Identifier (UUID) or absolute path name of the medium
or image.
--delete
Deletes the image file.
Examples
The following command removes the disk image file called disk01.vdi from the registry.
$ VBoxManage closemedium disk01.vdi
The following command removes the disk image file called disk01.vdi from the registry and
deletes the image file.
$ VBoxManage closemedium disk01.vdi --delete
251
9 VBoxManage
9.26 VBoxManage storageattach
Attach, remove, and modify storage media used by a virtual machine.
Synopsis
VBoxManage storageattach <uuid | vmname> <--storagectl=name>
[--bandwidthgroup= name | none ] [--comment=text] [--device=number]
[--discard= on | off ] [--encodedlun=lun] [--forceunmount]
[--hotpluggable= on | off ] [--initiator=initiator] [--intnet] [--lun=lun]
[--medium= none | emptydrive | additions | uuid | filename | host:drive
| iscsi ] [--mtype= normal | writethrough | immutable | shareable | readonly
| multiattach ] [--nonrotational= on | off ] [--passthrough= on | off ]
[--passwordfile=file] [--password=password] [--port=number] [--server=
name | ip ] [--setparentuuid=uuid] [--setuuid=uuid] [--target=target]
[--tempeject= on | off ] [--tport=port] [--type= dvddrive | fdd | hdd ]
[--username=username]
Description
The VBoxManage storageattach command enables you to manage a storage medium that you
connected to a storage controller by using the VBoxManage storagectl command.
uuid | vmname
Specifies the Universally Unique Identifier (UUID) or the name of the virtual machine (VM).
--storagectl=<name>
Specifies the name of the storage controller. Use the VBoxManage showvminfo command
to list the storage controllers that are attached to the VM.
--port=<number>
Specifies the port number of the storage controller to modify. You must specify this option
unless the storage controller has only a single port.
--device=<number>
Specifies the port’s device number to modify. You must specify this option unless the storage
controller has only one device per port.
--type=dvddrive | fdd | hdd
Specifies the drive type to which the medium is associated. Only omit this option if the
medium type can be determined by using the --medium option or by information provided
by an earlier medium attachment command.
--medium=none | emptydrive | additions | <uuid> | <filename> |
host:<drive> | iscsi
Specifies one of the following values:
none
Removes any existing device from the specified slot.
emptydrive
For a virtual DVD or floppy drive only.
Makes the device slot behave like a removeable drive into which no media has been
inserted.
additions
For a virtual DVD drive only.
Attaches the VirtualBox Guest Additions image to the specified device slot.
252
9 VBoxManage
uuid
Specifies the UUID of a storage medium to attach to the specified device slot. The
storage medium must already be known to Oracle VM VirtualBox, such as a storage
medium that is attached to another VM. Use the VBoxManage list command to list
media.
filename
Specifies the full path of an existing disk image to attach to the specified device slot.
The disk image can be in ISO, RAW, VDI, VMDK, or other format.
host:drive
For a virtual DVD or floppy drive only.
Connects the specified device slot to the specified DVD or floppy drive on the host
computer.
iscsi
For virtual hard disks only.
Specifies an iSCSI target for which you must specify additional information. See chap-
ter 6.10, iSCSI Servers, page 125.
For removeable media such as floppies and DVDs, you can make configuration changes
while a VM is running. Changes to devices or hard disk device slots require that the VM be
powered off.
--mtype=normal | writethrough | immutable | shareable | readonly |
multiattach
Specifies how this medium behaves with respect to snapshots and write operations. See
chapter 6.4, Special Image Write Modes, page 119.
--comment=<text>
Specifies an optional description to store with the medium.
--setuuid=<uuid>
Modifies the UUID of a medium before attaching it to a VM.
This is an expert option. Inappropriate values might make the medium unusable or lead to
broken VM configurations if another VM already refers to the same medium.
Using the --setuuid="" option assigns a new random UUID to an image, which can re-
solve duplicate UUID errors if you used a file copy utility to duplicate an image.
--setparentuuid=<uuid>
Modifies the parent UUID of a medium before attaching it to a VM.
This is an expert option. Inappropriate values might make the medium unusable or lead to
broken VM configurations if another VM already refers to the same medium.
--passthrough=on | off
For a virtual DVD drive only.
Enables writing to a DVD. This feature is experimental, see chapter 6.9, CD/DVD Support,
page 124.
--tempeject=on | off
For a virtual DVD drive only.
Specifies whether to permit a temporary guest-triggered medium eject operation. When
set to on, you can eject a medium. The ability for a guest-triggered eject operation does
not persist if the VM is powered off and restarted. So, when you set this option to on and
the VM is restarted, the originally configured medium is still in the drive.
253
9 VBoxManage
--nonrotational=on | off
Enables you to specify that the virtual hard disk is non-rotational. Some guest OSes, such
as Windows 7 or later, treat such disks as solid state drives (SSDs) and do not perform disk
fragmentation on them.
--discard=on | off
Specifies whether to enable the auto-discard feature for a virtual hard disk. When set to
on, a VDI image is shrunk in response to a trim command from the guest OS.
The virtual hard disk must meet the following requirements:
• The disk format must be VDI.
• The size of the cleared area of the disk must be at least 1 MB.
• Ensure that the space being trimmed is at least a 1 MB contiguous block at a 1 MB
boundary.
Consider running defragmentation commands as background cron jobs to save
space.
On Windows, run the defrag.exe /D command.
On Linux, run the
btrfs filesystem defrag command.
Note: When you configure the guest OS to issue the trim command, the guest OS
typically sees the disk as an SSD.
Ext4 supports the -o discard mount option. Mac OS X might require additional set-
tings. Windows 7, 8, and 10 automatically detect and support SSDs. The Linux exFAT
driver from Samsung supports the trim command.
The Microsoft implementation of exFAT might not support this feature.
You can use other methods to issue trim commands. The Linux fstrim command is part of
the util-linux package. Earlier solutions required you to zero out unused areas by using
the zerofree or a similar command, and then to compact the disk. You can only perform
these steps when the VM is offline.
--bandwidthgroup=<name>
Specifies the bandwidth group to use for the device. See chapter 6.8, Limiting Bandwidth
for Disk Images, page 123.
--forceunmount
For a virtual DVD or floppy drive only.
Forcibly unmounts the DVD, CD, or floppy or mounts a new DVD, CD, or floppy even if the
previous removable storage is locked by the guest for reading. See chapter 6.9, CD/DVD
Support, page 124.
The following options are applicable when you specify the --medium=iscsi option:
--server=<hostname> | <IP-address>
Specifies the host name or IP address of the iSCSI target.
--target=<target>
Specifies the target name string, which is determined by the iSCSI target and is used to
identify the storage resource.
--tport=<port>
Specifies the TCP/IP port number of the iSCSI service on the target.
254
9 VBoxManage
--lun=<LUN>
Specifies the logical unit number (LUN) of the target resource. For a single disk drive, the
value is zero.
--encodedlun=<LUN>
Specifies the hexadecimal-encoded of the target resource. For a single disk drive, the value
is zero.
--username=<username>
Specifies the user name to use for target authentication.
Note: Unless you provide a settings password, the user name is stored as clear text in
the XML machine configuration file.
--password=<password>
Specifies the password used for target authentication.
Note: Unless you provide a settings password, this password is stored as clear text in
the XML machine configuration file. When you specify a settings password for the first
time, the target authentication password is stored in encrypted form.
--passwordfile=<password-filename>
Specifies a file that contains the target authentication password as clear text.
Note: Use permission and ownership settings to ensure that the contents of this file
cannot be read by unauthorized users.
--initiator=<initiator>
Specifies the iSCSI initiator.
The Microsoft iSCSI Initiator is a system, such as a server, that attaches to an IP network
and initiates requests and receives responses from an iSCSI target. The SAN components
in the iSCSI initiator are largely analogous to Fibre Channel SAN components, and they
include the following:
• iSCSI driver. Transports blocks of iSCSI commands over the IP network. This iSCSI
driver is installed on the iSCSI host and is included with the Microsoft iSCSI Initiator.
• Gigabit Ethernet adapter. Connects to an iSCSI target. Use an Ethernet adapter that
can transmit 1000 megabits per second (Mbps). Like standard 10/100 adapters, most
gigabit adapters use a preexisting Category 5 or Category 6E cable. Each port on the
adapter is identified by a unique IP address.
• iSCSI target. Is any device that receives iSCSI commands. The device can be an
end node such as a storage device, or it can be an intermediate device such as a
network bridge between IP and Fibre Channel devices. Each port on the storage array
controller or network bridge is identified by one or more IP addresses.
--intnet
Specifies whether to connect to the iSCSI target that uses internal networking. This con-
figuration requires further configuration. See chapter 10.7.3, Access iSCSI Targets Using
Internal Networking, page 344.
255
9 VBoxManage
Examples
The following command attaches the o7.vdi disk image to the specified SATA storage controller
on the ol7 VM.
$ storageattach ol7 --storagectl "SATA Controller" --port 0 --device 0 \
--type hdd --medium /VirtualBox/ol7/ol7.vdi
The following command attaches the o7-r6-dvd.iso DVD image to the specified IDE storage
controller on the ol7 VM.
$ VBoxManage storageattach ol7 --storagectl "IDE Controller" --port 0 --device 0 \
--type dvddrive --medium ol7-r6-dvd.iso
See Also
chapter 9.5, VBoxManage list, page 170, chapter 9.6, VBoxManage showvminfo, page 175, chapter
9.27, VBoxManage storagectl, page 256
9.27 VBoxManage storagectl
Manage a storage controller.
Synopsis
VBoxManage storagectl <uuid | vmname> <--name=controller-name> [--add=
floppy | ide | pcie | sas | sata | scsi | usb ] [--controller= BusLogic
| I82078 | ICH6 | IntelAhci | LSILogic | LSILogicSAS | NVMe | PIIX3 | PIIX4
| USB | VirtIO ] [--bootable= on | off ] [--hostiocache= on | off ]
[--portcount=count] [--remove] [--rename=new-controller-name]
Description
The VBoxManage storagectl command enables you to attach, modify, and remove
a storage controller.
After you configure the storage controller, you can use the
VBoxManage storageattach command to attach virtual media to the controller.
uuid | vmname
Specifies the Universally Unique Identifier (UUID) or name of the virtual machine (VM).
--name=<controller-name>
Specifies the name of the storage controller.
--add=<system-bus-type>
Specifies the type of the system bus to which to connect the storage controller. Valid values
are floppy, ide, pcie, sas, sata, scsi, and usb.
--controller=<chipset-type>
Specifies the chipset type to emulate for the specified storage controller. Valid values are
BusLogic, I82078, ICH6, IntelAHCI, LSILogic, LSILogicSAS, NVMe, PIIX3, PIIX4, and
USB.
The default value varies, according to the type of storage controller.
--portcount=<count>
Specifies the number of ports that the storage controller supports. Valid values depend on
the type of storage controller.
256
9 VBoxManage
--hostiocache=on|off
Specifies whether to use the host I/O cache for all disk images attached to this storage
controller. Valid values are on and off. See chapter 6.7, Host Input/Output Caching, page
123.
--bootable=on|off
Specifies whether this controller is bootable. Valid values are on and off.
--rename=<new-controller-name>
Specifies a new name for the storage controller.
--remove
Removes a storage controller from the VM configuration.
Examples
The following command creates a SATA storage controller called sata01 and adds it to the ol7
VM. The storage controller emulates the IntelAHCI chipset.
$ VBoxManage storagectl ol7 --name "sata01" --add sata --controller IntelAHCI
The following command creates an IDE storage controller called ide01 and adds it to the ol7
VM.
$ VBoxManage storagectl ol7 --name "ide01" --add ide
See Also
chapter 9.26, VBoxManage storageattach, page 252
9.28 VBoxManage bandwidthctl
Manage bandwidth groups.
Synopsis
VBoxManage bandwidthctl <uuid | vmname> add <bandwidth-group-name>
<--limit=bandwidth-limit[k|m|g|K|M|G]> <--type=disk|network>
VBoxManage bandwidthctl <uuid | vmname> list [--machinereadable]
VBoxManage bandwidthctl <uuid | vmname> remove <bandwidth-group-name>
VBoxManage bandwidthctl <uuid | vmname> set <bandwidth-group-name>
<--limit=bandwidth-limit[k|m|g|K|M|G]>
Description
The VBoxManage bandwidthctl command enables you to manage bandwidth groups for vir-
tual machines (VMs). A bandwidth group specifies the bandwidth limit for the disks or for the
network adapters of a VM.
Note that a network bandwidth limit applies only to the outbound traffic from the VM. The
inbound traffic is unlimited.
257
9 VBoxManage
Create a Bandwidth Group
VBoxManage bandwidthctl <uuid | vmname> add <bandwidth-group-name>
<--limit=bandwidth-limit[k|m|g|K|M|G]> <--type=disk|network>
The VBoxManage bandwidthctl add command creates a bandwidth group for the specified
VM. You must specify whether the bandwidth group is for disks or for networks, and specify the
bandwidth limit.
uuid | vmname
Specifies the Universally Unique Identifier (UUID) or the name of the VM.
<bandwidth-group-name>
Specifies the name of the bandwidth group.
--type=disk|network
Specifies the type of the bandwidth group: disk and network. For more information,
see chapter 6.8, Limiting Bandwidth for Disk Images, page 123 or chapter 7.12, Limiting
Bandwidth for Network Input/Output, page 140.
--limit=<bandwidth-limit>[k|m|g|K|M|G]
Specifies the bandwidth limit for a bandwidth group. The default unit is megabytes per
second. You can modify this value while the VM is running.
You can change the unit by appending one of the following unit specifiers to the bandwidth
limit:
• k âĂS kilobits per second
• m âĂS megabits per second
• g âĂS gigabits per second
• K âĂS kilobytes per second
• M âĂS megabytes per second
• G âĂS gigabytes per second
List Bandwidth Groups
VBoxManage bandwidthctl <uuid | vmname> list [--machinereadable]
The VBoxManage bandwidthctl list command lists the all the bandwidth groups that have
been defined for the specified VM. Use the --machinereadable option to produce the output in
a machine-readable format, which uses name-value pairs.
uuid | vmname
Specifies the UUID or the name of the VM.
--machinereadable
Outputs the information about the bandwidth groups in name-value pairs.
Remove a Bandwidth Group
VBoxManage bandwidthctl <uuid | vmname> remove <bandwidth-group-name>
The VBoxManage bandwidthctl remove command removes a bandwidth group.
258
9 VBoxManage
Note: To successfully remove a bandwidth group, ensure that it is not referenced by
any disk or adapter in the running VM.
uuid | vmname
Specifies the UUID or the name of the VM.
<bandwidth-group-name>
Specifies the name of the bandwidth group.
Modify the Bandwidth Limit of a Bandwidth Group
VBoxManage bandwidthctl <uuid | vmname> set <bandwidth-group-name>
<--limit=bandwidth-limit[k|m|g|K|M|G]>
The VBoxManage bandwidthctl set command modifies the bandwidth limit for a bandwidth
group.
uuid | vmname
Specifies the UUID or the name of the VM.
<bandwidth-group-name>
Specifies the name of the bandwidth group.
--limit=<bandwidth-limit>[k|m|g|K|M|G]
Specifies the bandwidth limit for a bandwidth group. The default unit is megabytes per
second. You can modify this value while the VM is running.
You can change the unit by appending one of the following unit specifiers to the bandwidth
limit:
• k âĂS kilobits per second
• m âĂS megabits per second
• g âĂS gigabits per second
• K âĂS kilobytes per second
• M âĂS megabytes per second
• G âĂS gigabytes per second
Examples
The following example shows how to use the VBoxManage bandwidthctl command to create
the Limit bandwidth group and set the limit to 20 Mbps. Then use the VBoxManage modifyvm
command to assign this bandwidth group to the first and second adapters of the vm1 VM.
$ VBoxManage bandwidthctl "vm1" add Limit --type network --limit 20m
$ VBoxManage modifyvm "vm1" --nicbandwidthgroup1 Limit
$ VBoxManage modifyvm "vm1" --nicbandwidthgroup2 Limit
You can dynamically modify the limit of a bandwidth group while the VM is running. The
following example shows how to modify the limit for the Limit bandwidth group from 20 Mbps
to 100 kbps:
$ VBoxManage bandwidthctl "vm1" set Limit --limit 100k
The following command disables shaping for all adapters in the Limit bandwidth group by
specifying a limit of zero (0):
$ VBoxManage bandwidthctl "vm1" set Limit --limit 0
259
9 VBoxManage
9.29 VBoxManage showmediuminfo
Show information about a medium.
Synopsis
VBoxManage showmediuminfo [disk | dvd | floppy] <uuid | filename>
Description
The VBoxManage showmediuminfo command shows the following information about a medium:
• Size
• Size on disk
• Type
• In use by virtual machines (VMs)
The medium must be specified either by its UUID, if the medium is registered, or by its file-
name. Registered images can be listed using VBoxManage list hdds, VBoxManage list dvds,
or VBoxManage list floppies, as appropriate.
For backward compatibility, you can also use the showvdiinfo command to obtain information
about the medium.
disk | dvd | floppy
Specifies the type of medium. Valid values are disk (hard drive), dvd, or floppy.
uuid | filename
Specifies the Universally Unique Identifier (UUID) or absolute path name of the medium
or image.
If the medium is registered, you can specify the UUID. You can also list reg-
istered images by using the VBoxManage list hdds, VBoxManage list dvds, or
VBoxManage list floppies command.
Examples
The following command shows information about the disk01.vdi disk image:
$ VBoxManage showmediuminfo disk01.vdi
The following command shows information about the floppy01.img floppy disk image.
$ VBoxManage showmediuminfo floppy floppy01.img
See Also
chapter 9.5, VBoxManage list, page 170
9.30 VBoxManage createmedium
Create a new medium.
260
9 VBoxManage
Synopsis
VBoxManage createmedium [disk | dvd | floppy] <--filename=filename>
[--size=megabytes | --sizebyte=bytes] [--diffparent= UUID | filename ]
[--format= VDI | VMDK | VHD ]
[--variant Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk]
--property name=value. . .
--property-file name=/path/to/file/with/value. . .
Description
The VBoxManage createmedium command creates a new medium, such as a disk image file.
Note: For compatibility with earlier versions of Oracle VM VirtualBox, you can use the
createvdi and createhd commands instead of the createmedium command.
disk | dvd | floppy
Specifies the media type. The default value is disk.
--filename=<filename>
Specifies the absolute path name to a file on the host file system.
--size=<megabytes>
Specifies the image capacity in one megabyte units.
--sizebyte=<bytes>
Specifies the image capacity in one byte units.
--diffparent=<UUID> | <filename>
Specifies the Universally Unique Identifier (UUID) or absolute path name of a differencing
image parent file on the host file system.
Use this file to share a base box disk image among VMs.
--format=VDI | VMDK | VHD
Specifies the file format of the output file. Valid formats are VDI, VMDK, and VHD. The
default format is VDI.
--variant=Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk
Specifies the file format variant for the target medium, which is a comma-separated list of
variants. Following are the valid values:
• Standard is the default disk image type, which has a dynamically allocated file size.
• Fixed uses a disk image that has a fixed file size.
• Split2G indicates that the disk image is split into 2GB segments. This value is valid
for VMDK disk images only.
• Stream optimizes the disk image for downloading. This value is valid for VMDK disk
images only.
• ESX is used for some VMWare products. This value is valid for VMDK disk images only.
• Formatted formats the medium automatically. This value is valid for floppy images
only.
• RawDisk is used for creating a VMDK image which provides direct access to the hard
disk on the host using its raw interface. This value is valid for VMDK disk images only.
For detailed information about raw disk access, see chapter 10.7, Advanced Storage
Configuration, page 341.
261
9 VBoxManage
Note that not all variant combinations are valid. Specifying incompatible variant values in
the list will produce an error message.
--property <name>=<value>
Specifies any required file format dependent parameters in key=value form. Optional.
--property-file <name >=</path/to/file/with/value>
Specifies any required file format dependent parameters in key=file/with/value form.
The value is taken from the file. Optional.
Examples
The following command creates a new disk image file named disk01.vdi. The file size is 1024
megabytes.
$ VBoxManage createmedium --filename disk01.vdi --size 1024
The following command creates a new floppy disk image file named floppy01.vdi. The file
size is 1 megabyte.
$ VBoxManage createmedium floppy --filename floppy01.img --size 1
The following command creates a raw disk image of an entire physical disk on a Linux host.
$ VBoxManage createmedium disk --filename=/path/to/rawdisk.vmdk --variant=RawDisk --format=VMDK --property RawDrive=/
9.31 VBoxManage modifymedium
Change the characteristics of an existing disk image.
Synopsis
VBoxManage modifymedium [disk | dvd | floppy] <uuid | filename>
[--autoreset=on | off] [--compact] [--description=description]
[--move=pathname] [--property=name=[value]]
[--resize=megabytes | --resizebyte=bytes] [--setlocation=pathname]
[--type=normal | writethrough | immutable | shareable | readonly | multiattach]
Description
The VBoxManage modifymedium command enables you to change the characteristics of an ex-
isting disk image.
Note: For compatibility with earlier versions of Oracle VM VirtualBox, you can use the
modifyvdi and modifyhd commands.
disk | dvd | floppy
Specifies the media type of the image.
filename
Specifies the Universally Unique Identifier (UUID) or path name of the disk image on the
host file system. You can specify the UUID only if the medium is registered. Use the
VBoxManage list hdds command to list the registered images. You can specfy an abso-
lute or relative path to the medium.
262
9 VBoxManage
--autoreset=on | off
Specifies whether to automatically reset an immutable hard disk on every virtual machine
(VM) startup. This option is only for immutable hard disks and the default value is on. See
chapter 6.4, Special Image Write Modes, page 119.
--compact
Compresses disk images by removing blocks that contain only zeroes. This option shrinks
a dynamically allocated image and reduces the physical size of the image without affecting
the logical size of the virtual disk.
You can use this option for base images and for differencing images that are created as part
of a snapshot.
Note: Before you compress the image, you must use a suitable software tool to zero
out free space in the guest system. For example:
• Windows guests. Run the sdelete -z command.
• Linux guests. Use the zerofree utility, which supports ext2 and ext3 file sys-
tems.
• Mac OS X guests. Use the diskutil secureErase freespace 0 / command.
Note that you can only use this option to compress VDI images. To compress non-VID
images, you can zero out free blocks and then clone the disk to any other dynamically
allocated format.
--description=<description>
Specifies a text description of the medium.
--move=<pathname>
Specifies a relative or absolute path to a medium on the host system. Use this option to
relocate a medium to a different location on the host system.
--property=<name>=<value>
Specifies a property name and value for the medium.
--resize=<size>
Specifes the new capacity of an existing image in MB. You can use this option only to
expand the capacity of an image. You can cannot shrink the capacity of an image.
Note that you can resize only dynamically allocated disk images that use the VDI and VHD
formats. This option adjusts the logical size of a virtual disk and has only a minor affect on
the physical size.
For example, if your dynamically allocated 10 GB disk is full, you can use the --resize
15360 option to increase the capacity of the existing disk to 15 GB (15,360 MB). This
operation enables you to avoid having to create a new image and copy all data from within
a VM.
Note that using this option only changes the capacity of the drive. So, you might need to
subsequently use a partition management tool in the guest to adjust the main partition to
fill the drive.
--resizebyte=<size>
Specifes the new capacity of an existing image in bytes. This option is similar to the
--resize option, but you specify the size in bytes instead of megabytes.
263
9 VBoxManage
--setlocation=<pathname>
Specifies the new location of the medium on the host system after the medium has been
moved. The path name can be relative to the current directory or be absolute to the root.
Note that the VBoxManage modifymedium command does not perform any sanity checks
on the path name you specify. Ensure that the path name is valid.
--type
Specifies the new mode type of an existing image. Valid values are normal, immutable,
writethrough, multi-attach, shareable, and readonly. For descriptions of these mode
types, see chapter 6.4, Special Image Write Modes, page 119.
Examples
The following command modifies the description for the disk image file called disk01.vdi.
$ VBoxManage modifymedium disk disk01.vdi --description "Oracle Linux 7 image"
The following command modifies the write mode for the disk image file called disk01.vdi.
$ VBoxManage modifymedium disk disk01.vdi --type writethrough
See Also
chapter 9.5, VBoxManage list, page 170
9.32 VBoxManage clonemedium
Create a clone of a medium.
Synopsis
VBoxManage clonemedium <uuid | source-medium> <uuid | target-medium> [disk
| dvd | floppy] [--existing] [--format= VDI | VMDK | VHD | RAW | other ]
[--variant=Standard,Fixed,Split2G,Stream,ESX]
Description
The VBoxManage clonemedium command enables you to clone an existing medium (virtual disk,
DVD, or floppy), which is typically an image file. Only the Universally Unique Identifier (UUID)
differs between the original image and the cloned image.
You can use the Virtual Media Manager to transfer the cloned image to another host system
or reimport it into Oracle VM VirtualBox. See chapter 6.3, The Virtual Media Manager, page 115
and chapter 6.6, Cloning Disk Images, page 122.
uuid | source-medium
Specifies the UUID or the absolute or relative file name of the source medium to
clone. You can specify the UUID of the medium only if it is registered. Use the
VBoxManage list hdds command to list registered images.
uuid | target-medium
Specifies the UUID or the absolute or relative file name of the target (clone) medium.
You can specify the UUID of the target medium only if it is registered. Use the
VBoxManage list hdds command to list registered images.
264
9 VBoxManage
disk | dvd | floppy
Specifies the type of the medium to clone. Valid values are disk, dvd, and floppy. The
default value is disk.
--existing
Performs the clone operation by overwriting an existing target medium. The result is that
only the portion of the source medium that fits into the existing target medium is copied.
If the target medium is smaller than the source, only the portion of the source medium up
to the size of the target medium is copied.
If the target medium is larger than the source, the remaining part of the target medium is
unchanged.
--format
Specifies the file format of the target medium if it differs from the format of the source
medium. Valid values are VDI, VMDK, VHD, RAW, and other.
--variant=Standard,Fixed,Split2G,Stream,ESX
Specifies the file format variant for the target medium, which is a comma-separated list of
variants. Following are the valid values:
• Standard is the default disk image type, which has a dynamically allocated file size.
• Fixed uses a disk image that has a fixed file size.
• Split2G indicates that the disk image is split into 2GB segments. This value is for
VMDK only.
• Stream optimizes the disk image for downloading. This value is for VMDK only.
• ESX is used for some VMWare products. This value is for VMDK only.
Note that not all variant combinations are valid. Specifying incompatible variant values in
the list will produce an error message.
Note: For compatibility with earlier versions of Oracle VM VirtualBox, you can use the
clonevdi and clonehd commands instead of the clonemedium command.
Examples
The following command creates a clone of the disk01.vdi disk image file. The clone is called
disk02.vdi.
$ VBoxManage clonemedium disk01.vdi disk02.vdi
The following command creates a clone of the disk01.vdi disk image file. The clone is in
VMDK format and is called disk02.vmdk.
$ VBoxManage clonemedium disk01.vdi disk02.vmdk --format VMDK
See Also
chapter 9.5, VBoxManage list, page 170
9.33 VBoxManage mediumproperty
Manage medium properties.
265
9 VBoxManage
Synopsis
VBoxManage mediumproperty [disk | dvd | floppy] set <uuid | filename>
<property-name> <property-value>
VBoxManage mediumproperty [disk | dvd | floppy] get <uuid | filename>
<property-name>
VBoxManage mediumproperty [disk | dvd | floppy] delete <uuid | filename>
<property-name>
Description
The VBoxManage mediumproperty command enables you to set, retrieve, or delete a medium
property.
Set a Medium Property
VBoxManage mediumproperty [disk | dvd | floppy] set <uuid | filename>
<property-name> <property-value>
The VBoxManage mediumproperty set command enables you to set a medium property.
disk | dvd | floppy
Specifies the type of medium. Valid values are disk (hard drive), dvd, or floppy.
uuid | filename
Specifies the Universally Unique Identifier (UUID) or absolute path name of the medium
or image.
property-name
Specifies the name of the property.
property-value
Specifies the value of the specified property.
Retrieve a Medium Property Value
VBoxManage mediumproperty [disk | dvd | floppy] get <uuid | filename>
<property-name>
The VBoxManage mediumproperty get command enables you to retrieve the value of a
medium property.
disk | dvd | floppy
Specifies the type of medium. Valid values are disk (hard drive), dvd, or floppy.
uuid | filename
Specifies the Universally Unique Identifier (UUID) or absolute path name of the medium
or image.
property-name
Specifies the name of the property.
266
9 VBoxManage
Delete a Medium Property
VBoxManage mediumproperty [disk | dvd | floppy] delete <uuid | filename>
<property-name>
The VBoxManage mediumproperty delete command enables you to delete a medium prop-
erty.
disk | dvd | floppy
Specifies the type of medium. Valid values are disk (hard drive), dvd, or floppy.
uuid | filename
Specifies the Universally Unique Identifier (UUID) or absolute path name of the medium
or image.
property-name
Specifies the name of the property.
Examples
The following command sets the property called prop1 to val1 for the ol7.vdi disk image.
$ VBoxManage mediumproperty disk set ol7.vdi prop1 val1
The following command gets the value of the property called prop1 for the ol7.vdi disk
image.
$ VBoxManage mediumproperty disk get ol7.vdi prop1
9.34 VBoxManage encryptmedium
Manage a DEK-encrypted medium or image.
Synopsis
VBoxManage encryptmedium <uuid | filename> [--cipher=cipher-ID]
[--newpassword=password] [--newpasswordid=password-ID]
[--oldpassword=password]
Description
The VBoxManage encryptmedium command enables you to create and manage a DEK-encrypted
medium or image. You can encrypt an image, decrypt an image, and change the encryption
password of an image. See chapter 10.29.2, Encrypting Disk Images, page 377.
uuid | filename
Specifies the Universally Unique Identifier (UUID) or the absolute path name of the
medium or image to encrypt.
--newpassword=<password>
Specifies the new encryption password. password is either the absolute path name of a
password file on the host operating system or -, which prompts you for the password.
You must use the --newpasswordid option with this --newpassword option.
267
9 VBoxManage
--oldpassword=<password>
Specifies the original encryption password. password is either the absolute path name
of a password file on the host operating system or -, which prompts you for the original
password.
This option enables you to gain access to an encrypted medium or image to do the follow-
ing:
• Decrypt an encrypted image by using this option by itself.
• Change the password of the encrypted image by using the --newpassword option.
• Change the encryption cipher of the image by using the --cipher option.
--cipher=<cipher-ID>
Specifies the cipher to use for encryption. Valid values are AES-XTS128-PLAIN64 or
AES-XTS256-PLAIN64.
This option enables you to set up or change encryption on the medium or image.
--newpasswordid=<password-ID>
Specifies a new password identifier that is used for correct identification when supplying
multiple passwords during VM startup.
If you use the same password and password identifier when encrypting multiple images,
you need to supply the password only one time during VM startup.
Examples
The following example shows how to encrypt the ol7u4-1.vdi image by using the
AES-XTS128-PLAIN64 cipher, specifying a password identifier of
1001, and using the
$HOME/pwfile password file:
$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" \
--cipher="AES-XTS128-PLAIN64" --newpasswordid="1001" --newpassword=$HOME/pwfile
The following example shows how to decrypt an encrypted image called ol7u4-2.vdi:
$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-2.vdi" \
--oldpassword=-
Password: <original-password>
The following example shows how to change the password for an encrypted image called
ol7u4-3.vdi. The command reads the original password from the $HOME/pwfile.orig file,
reads the new password from the $HOME/pwfile file, and assigns a password identifier of 1001.
$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-3.vdi" \
--oldpassword=$HOME/pwfile.orig --newpassword=$HOME/pwfile --newpasswordid="1001"
9.35 VBoxManage checkmediumpwd
Check encryption password on a DEK-encrypted medium or a disk image.
Synopsis
VBoxManage checkmediumpwd <uuid | filename> <password-file>
268
9 VBoxManage
Description
The VBoxManage checkmediumpwd command checks the current encryption password on a DEK-
encrypted medium or a disk image. See chapter 10.29.2, Encrypting Disk Images, page 377.
The command response indicates if the specified password is correct.
uuid|filename
Specifies the Universally Unique Identifier (UUID) or the absolute path name of the
medium or image.
password-file
Specifies the password to check. The password can be the absolute path name of a pass-
word file on the host OS or the dash character (-) to prompt you for the password on the
command line.
Examples
The following example checks the encryption password for the ol7u4-1.vdi disk image. The
password is contained in a file called pwfile.
The command returns a message indicating that the specified password is correct.
$ VBoxManage checkmediumpwd "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" /home/user/pwfile
The given password is correct
See Also
chapter 9.34, VBoxManage encryptmedium, page 267
9.36 VBoxManage convertfromraw
Convert a raw disk image to a virtual disk image.
Synopsis
VBoxManage convertfromraw <inputfile> <outputfile> [--format= VDI | VMDK
| VHD ] [--uuid=uuid] [--variant=Standard,Fixed,Split2G,Stream,ESX]
VBoxManage convertfromraw stdin <outputfile> <bytes> [--format= VDI | VMDK
| VHD ] [--uuid=uuid] [--variant=Standard,Fixed,Split2G,Stream,ESX]
Description
The VBoxManage convertfromraw command enables you to convert a raw disk image to an
Oracle VM VirtualBox virtual disk image (VDI).
Note: For compatibility with earlier versions of Oracle VM VirtualBox, you can use
the VBoxManage convertdd command instead of the VBoxManage convertfromraw
command.
269
9 VBoxManage
Convert a Raw Disk File to a Virtual Disk Image File
VBoxManage convertfromraw <inputfile> <outputfile> [--format= VDI | VMDK
| VHD ] [--uuid=uuid] [--variant=Standard,Fixed,Split2G,Stream,ESX]
The VBoxManage convertfromraw command converts the specified raw disk image input file
to an Oracle VM VirtualBox VDI file.
inputfile
Specifies the name of the raw disk image file to convert.
outputfile
Specifies the name of the file in which to write the VDI output.
--format=VDI | VMDK | VHD
Specifies the format of the disk image to create. Valid values are VDI, VMDK, and VHD. The
default format is VDI.
--uuid=<uuid>
Specifies the Universally Unique Identifier (UUID) of the output file.
--variant=Standard,Fixed,Split2G,Stream,ESX
Specifies any required file format variants for the output file. This is a comma-separated
list of variant values. Following are the valid values:
• Standard is the default disk image type, which has a dynamically allocated file size.
• Fixed uses a disk image that has a fixed file size.
• Split2G indicates that the disk image is split into 2GB segments. This value is for
VMDK only.
• Stream optimizes the disk image for downloading. This value is for VMDK only.
• ESX is used for some VMWare products. This value is for VMDK only.
Note that not all variant combinations are valid. Specifying incompatible variant values in
the list will produce an error message.
Convert Raw Data From Standard Input to a Virtual Disk Image File
VBoxManage convertfromraw stdin <outputfile> <bytes> [--format= VDI | VMDK
| VHD ] [--uuid=uuid] [--variant=Standard,Fixed,Split2G,Stream,ESX]
The VBoxManage convertfromraw stdin command reads the content of the disk image from
standard input. Consider using this form of the command in a pipe sequence.
outputfile
Specifies the name of the file in which to write the disk image output.
bytes
Specifies the capacity of the targe image name. Needs to be given explicitly, because gen-
erally pipes do not support querying the overall size of the data stream.
--format=VDI | VMDK | VHD
Specifies the format of the disk image to create. Valid values are VDI, VMDK, and VHD. The
default format is VDI.
--uuid=<uuid>
Specifies the UUID of the output file.
270
9 VBoxManage
--variant=Standard,Fixed,Split2G,Stream,ESX
Specifies any required file format variants for the output file. This is a comma-separated
list of variant values. Following are the valid values:
• Standard is the default disk image type, which has a dynamically allocated file size.
• Fixed uses a disk image that has a fixed file size.
• Split2G indicates that the disk image is split into 2GB segments. This value is for
VMDK only.
• Stream optimizes the disk image for downloading. This value is for VMDK only.
• ESX is used for some VMWare products. This value is for VMDK only.
Note that not all variant combinations are valid. Specifying incompatible variant values in
the list will produce an error message.
Examples
The following command converts the raw disk image input file disk01.raw. The output file is a
VDI disk image called disk02.vdi.
$ VBoxManage convertfromraw disk01.raw disk02.vdi
The following command converts the raw disk image input file disk01.raw. The output file is
a VMDK disk image called disk02.vmdk.
$ VBoxManage convertfromraw disk01.raw disk02.vmdk --format VMDK
The following command reads from disk /dev/sda using a pipe and therefore needs the exact
disk size in bytes as an additional parameter, which is assumed to be 10737418240. The output
file is a VDI disk image called disk.vdi.
$ dd if=/dev/sda bs=512 | VBoxManage convertfromraw stdin disk.vdi 10737418240
9.37 VBoxManage mediumio
Medium content access.
Synopsis
VBoxManage mediumio <--disk=uuid|filename | --dvd=uuid|filename
| --floppy=uuid|filename> [--password-file=-|filename] formatfat
[--quick]
VBoxManage mediumio <--disk=uuid|filename | --dvd=uuid|filename
| --floppy=uuid|filename> [--password-file=-|filename] cat [--hex]
[--offset=byte-offset] [--size=bytes] [--output=-|filename]
VBoxManage mediumio <--disk=uuid|filename | --dvd=uuid|filename
| --floppy=uuid|filename> [--password-file=-|filename] stream
[--format=image-format] [--variant=image-variant] [--output=-|filename]
271
9 VBoxManage
Description
Common options
The subcommands of mediumio all operate on a medium which need to be specified, optionally
with an encryption password. The following common options can be placed before or after the
sub-command:
-disk=uuid|filename
Either the UUID or filename of a harddisk image, e.g. VDI, VMDK, VHD, ++.
-dvd=uuid|filename
Either the UUID or filename of a DVD image, e.g. ISO, DMG, CUE.
-floppy=uuid|filename
Either the UUID or filename of a floppy image, e.g. IMG.
-password-file=-|filename
The name of a file containing the medium encryption password. If - is specified, the
password will be read from stdin.
mediumio formatfat
VBoxManage mediumio <--disk=uuid|filename | --dvd=uuid|filename
| --floppy=uuid|filename> [--password-file=-|filename] formatfat
[--quick]
Formats a floppy medium with the FAT file system. This will erase the content of the medium.
--quick
Quickformat the medium.
mediumio cat
VBoxManage mediumio <--disk=uuid|filename | --dvd=uuid|filename
| --floppy=uuid|filename> [--password-file=-|filename] cat [--hex]
[--offset=byte-offset] [--size=bytes] [--output=-|filename]
Dumps the medium content to stdout or the specified file.
--hex
Dump as hex bytes.
--offset
The byte offset in the medium to start.
--size
The number of bytes to dump.
--output
The output filename. As usual - is take to mean stdout.
272
9 VBoxManage
mediumio stream
VBoxManage mediumio <--disk=uuid|filename | --dvd=uuid|filename
| --floppy=uuid|filename> [--password-file=-|filename] stream
[--format=image-format] [--variant=image-variant] [--output=-|filename]
Converts the medium to a streamable format and dumps it to the given output.
--format
The format of the destination image.
--variant
The medium variant for the destination.
--output
The output filename. As usual - is take to mean stdout.
9.38 VBoxManage setextradata
Set a keyword value that is associated with a virtual machine or configuration.
Synopsis
VBoxManage setextradata <global | uuid | vmname> <keyword> [value]
Description
The VBoxManage setextradata command enables you to set a keyword value that is associated
with a virtual machine (VM) or with an Oracle VM VirtualBox configuration.
global
Sets information about the configuration rather than a VM.
uuid|vmname
Specifies the Universally Unique Identifier (UUID) or name of the VM.
keyword
Specifies the keyword for which to set its value.
value
Specifies the keyword value. Specifying no value removes the keyword.
Examples
The following command sets the installdate keyword value for the Fedora5 VM to
2019.01.01:
$ VBoxManage setextradata Fedora5 installdate 2019.01.01
The following command unsets the value of the installdate keyword for the Fedora5 VM:
$ VBoxManage setextradata Fedora5 installdate
See Also
chapter 9.39, VBoxManage getextradata, page 274
273
9 VBoxManage
9.39 VBoxManage getextradata
View keyword values that are associated with a virtual machine or configuration.
Synopsis
VBoxManage getextradata <global | uuid | vmname> <keyword> | [enumerate]
Description
The VBoxManage getextradata command enables you to retrieve keyword data that is associ-
ated with a virtual machine (VM) or with an Oracle VM VirtualBox configuration.
global
Specifies to retrieve information about the configuration rather than a VM.
uuid | vmname
Specifies the Universally Unique Identifier (UUID) or name of the VM.
enumerate
Shows all keyword values for the specified VM or configuration.
keyword
Specifies the keyword for which to retrieve its value.
Examples
The following command retrieves the installdate keyword value for the Fedora5 VM:
$ VBoxManage getextradata Fedora5 installdate
VirtualBox Command Line Management Interface Version <version-number>
Value: 2006.01.01
The following command retrieves the information for all keywords of the OracleLinux7u4
VM:
$ VBoxManage getextradata OracleLinux7u4 enumerate
Key: GUI/LastCloseAction, Value: PowerOff
Key: GUI/LastGuestSizeHint, Value: 1048,696
Key: GUI/LastNormalWindowPosition, Value: 851,286,1048,738
The following command retrieves the information for all keywords in the configuration:
$ VBoxManage getextradata global enumerate
Key: GUI/Details/Elements, Value: general,system,preview,display,storage,audio,network,usb,sharedFolders,description
Key: GUI/DetailsPageBoxes, Value: general,system,preview,display,storage,audio,network,usb,sharedFolders,description
Key: GUI/GroupDefinitions/, Value: m=43349dd8-2aa3-41b8-988f-0e255ce68090,m=9ebcd81e-5231-48ce-a27d-28218757f3fe,m=c6
Key: GUI/HideDescriptionForWizards, Value: NewVM
Key: GUI/LastItemSelected, Value: m=ol7u4
Key: GUI/LastWindowPosition, Value: 951,510,960,520
Key: GUI/RecentFolderCD, Value: C:/Users/user1
Key: GUI/RecentListCD, Value: C:\Users\user1\V1.iso,C:\Users\user1\V2.iso,C:\Users\user1\V3.iso
Key: GUI/SplitterSizes, Value: 318,637
Key: GUI/SuppressMessages, Value: remindAboutMouseIntegration,remindAboutAutoCapture
Key: GUI/Toolbar/MachineTools/Order, Value: Details
Key: GUI/Tools/LastItemsSelected, Value: Welcome,Details
Key: GUI/UpdateCheckCount, Value: 71
Key: GUI/UpdateDate, Value: 1 d, 2019-04-10, stable, 5.2.22
Key: GUI/VirtualMediaManager/Details/Expanded, Value: true
274
9 VBoxManage
See Also
chapter 9.38, VBoxManage setextradata, page 273
9.40 VBoxManage setproperty
Change global settings.
Synopsis
VBoxManage setproperty <property-name> <property-value>
Description
The VBoxManage setproperty command enables you to change global settings that affect the
entire Oracle VM VirtualBox installation. Some of these settings correspond to the settings in the
Preferences dialog in the VirtualBox Manager.
The following properties are available:
autostartdbpath
Specifies the path to the autostart database. Valid values are null, which disables the
autostart database, or the name of the folder that contains the database. See chapter
10.21, Starting Virtual Machines During System Boot, page 370.
defaultfrontend
Specifies the global default VM frontend. Valid values are default, which specifies the
default frontend, or the name of the frontend to use.
hwvirtexclusive
Specifies whether Oracle VM VirtualBox makes exclusive use of the Intel VT-x or AMD-
V hardware virtualization extensions of the host system’s processor. See chapter 11.3,
Hardware Virtualization, page 395.
Valid values are as follows:
• on enables Oracle VM VirtualBox to make exclusive use of these extensions. This is
the default value.
• off shares these extensions with other hypervisors that run simultaneously. Note that
disabling this setting has negative performance implications.
language
Specifies the user language used to translate API messages. Valid values are C, which means
no translation or language code in form either ll or ll_CC, where ll is language 2 letters
code in lower case and CC is country 2 letter code in upper case.
logginglevel
Specifies the VBoxSVC release logging details. See http://www.virtualbox.org/wiki/
VBoxLogging.
loghistorycount
Specifies the number of rotated VM logs to retain.
machinefolder
Specifies the default folder in which virtual machine (VM) definitions are stored. Valid
values are default, which specifies the default storage folder, or the name of the folder to
use. See chapter 11.1, Where Oracle VM VirtualBox Stores its Files, page 391.
275
9 VBoxManage
proxymode
Configures the mode for an HTTP proxy server. Valid values are as follows:
manual
Configure the URL of a HTTP proxy server manually, using the proxyurl property
value.
noproxy
Do not use an HTTP proxy server. A direct connection to the Internet is used.
system
Detect the proxy settings automatically for the host network. This is the default value.
proxyurl
Specifies the URL for an HTTP proxy server when you specify a manual proxy by setting
the proxymode property to manual.
vrdeauthlibrary
Specifies which library to use when external authentication has been configured for a par-
ticular VM. Valid values are default, which specifies the default library, or the name of the
library to use. See chapter 8.1.5, RDP Authentication, page 147.
vrdeextpack
Specifies the library that implements the VirtualBox Remote Desktop Extension (RDE).
Valid values are null, which disables the RDE, or the name of the library to use.
websrvauthlibrary
Specifies which library the web service uses to authenticate users. Valid values are
default, which specifies the default library, null, which disables authentication, or the
name of the library to use. For information about the Oracle VM VirtualBox web service,
see chapter 12, Oracle VM VirtualBox Programming Interfaces, page 398.
Examples
The following command configures Oracle VM VirtualBox to use the specified HTTP proxy server.
$ VBoxManage setproperty proxymode manual
$ VBoxManage setproperty proxyurl "http://myproxy.com:8080"
See Also
chapter 9.19, VBoxManage startvm, page 225
9.41 VBoxManage usbfilter
Manage USB filters.
Synopsis
VBoxManage usbfilter add <index,0-N> <--target= <uuid | vmname | global> >
<--name=string> <--action=ignore | hold> [--active=yes | no]
[--vendorid=XXXX] [--productid=XXXX] [--revision=IIFF]
[--manufacturer=string] [--product=string] [--port=hex]
[--remote=yes | no] [--serialnumber=string]
[--maskedinterfaces=XXXXXXXX]
276
9 VBoxManage
VBoxManage usbfilter modify <index,0-N> <--target= <uuid | vmname
| global> > [--name=string] [--action=ignore | hold] [--active=yes | no]
[--vendorid=XXXX | ""] [--productid=XXXX | ""] [--revision=IIFF | ""]
[--manufacturer=string | ""] [--product=string | ""] [--port=hex]
[--remote=yes | no] [--serialnumber=string | ""]
[--maskedinterfaces=XXXXXXXX]
VBoxManage usbfilter remove <index,0-N> <--target= <uuid | vmname
| global> >
Description
The VBoxManage usbfilter command enables you to manage USB filters for a specific virtual
machine (VM), or global USB filters that affect the entire Oracle VM VirtualBox configuration.
Global filters are applied before VM-specific filters. This means that you can use a global filter
to prevent devices from being captured by any VM.
Global filters are applied in a particular order. Only the first filter that fits a device is applied.
For example, the first global filter makes a specific Kingston memory stick device available while
the second filter ignores all Kingston devices. The result of applying these filters is that the
specific Kingston memory stick is made available to any machine that has the appropriate filter,
but no other Kingston devices are made available.
Common Operand and Options
index,0-N
Specifies a single integer that indicates the position of the filter in the list. Zero (0) rep-
resents the first position in the list. If a filter already exists at the specified position, the
existing filter and any existing filters that follow are moved down the list. Otherwise, the
new filter is appended to the list.
--action=ignore | hold
Specifies whether to permit VMs access to devices that fit the filter description (hold) or to
deny them access (ignore). This option applies only to global filters.
--active=yes | no
Specifies whether the USB filter is active or temporarily disabled. Valid values are yes,
which activates the filter, and no, which disables the filter. The default value is yes.
--manufacturer=<string>
Specifies a manufacturer ID filter as a string. The default value is an empty string ("").
--maskedinterfaces=<XXXXXXXX>
Specifies a masked interface filter that is used to hide one or more USB interfaces from the
guest. The value is a bit mask where the set bits correspond to the USB interfaces to hide,
or mask off. This feature is supported on Linux host systems only.
--name=<filter-name>
Specifies the name of the filter.
--port=<hex>
Specifies a hub port number filter as a string. The default value is an empty string ("").
--product=<string>
Specifies a product ID filter as a string. The default value is an empty string ("").
277
9 VBoxManage
--productid=<XXXX>
Specifies a product ID filter. The string representation for an exact match has the form
XXXX, where X is a hexadecimal digit including leading zeroes. The default value is an
empty string ("").
--remote=yes | no
Specifies a remote filter that indicates whether the device is physically connected to a
remote VRDE client or to a local host system. This option applies to VM filters only. The
default value is an empty string ("").
--revision=<IIFF>
Specifies a revision ID filter. The string representation for an exact match has the form
IIFF. I is a decimal digit of the integer part of the revision. F is a decimal digit of its
fractional part that includes leading and trailing zeros. The default value is an empty
string ("").
To specify a range of revision IDs, ensure that you use the hexadecimal form so that the
revision is stored as a 16-bit packed BCD value. For example, the int:0x0100-0x0199
expression matches any revision from 1.0 to 1.99, inclusive.
--serialnumber=<string>
Specifies a serial number filter as a string. The default value is an empty string ("").
--target=<uuid> | <vmname> | global
Specifies the VM that the filter is attached to. You can specify the Universally Unique
Identifier (UUID) or the name of the VM. To apply the filter description to all VMs, specify
global.
--vendorid=<XXXX>
Specifies a vendor ID filter, which is a string representation of a four-digit hexadecimal
number. X is the hexadecimal digit including leading zeroes. The default value is an empty
string ("").
Add a USB Filter or a Global Filter
VBoxManage usbfilter add <index,0-N> <--target= <uuid | vmname | global> >
<--name=string> <--action=ignore | hold> [--active=yes | no]
[--vendorid=XXXX] [--productid=XXXX] [--revision=IIFF]
[--manufacturer=string] [--product=string] [--port=hex]
[--remote=yes | no] [--serialnumber=string]
[--maskedinterfaces=XXXXXXXX]
Use the VBoxManage usbfilter add command to create a new USB filter.
In addition, specify parameters by which to filter. You can use the VBoxManage list usbhost
command to view the parameters for devices that are attached to your system.
Modify a USB Filter or a Global Filter
VBoxManage usbfilter modify <index,0-N> <--target= <uuid | vmname
| global> > [--name=string] [--action=ignore | hold] [--active=yes | no]
[--vendorid=XXXX | ""] [--productid=XXXX | ""] [--revision=IIFF | ""]
[--manufacturer=string | ""] [--product=string | ""] [--port=hex]
[--remote=yes | no] [--serialnumber=string | ""]
[--maskedinterfaces=XXXXXXXX]
278
9 VBoxManage
Use the VBoxManage usbfilter modify command to modify a USB filter.
You can
use the VBoxManage list usbfilters command to list global filter indexes and the
VBoxManage showvminfo command to list indexes for a specific machine.
Remove a USB Filter or a Global Filter
VBoxManage usbfilter remove <index,0-N> <--target= <uuid | vmname
| global> >
Use the VBoxManage usbfilter remove command to remove a USB filter entry.
Examples
The following command lists the available USB devices on the host system.
$ VBoxManage list usbhost
The following command adds a USB filter called filter01 to the ol7 VM. The filter specifies
a Kingston DataTraveler memory stick and is placed first in the list of USB filters for the VM.
$ VBoxManage usbfilter add 0 --target ol7 --name filter01 --vendorid 0x0930 --productid 0x6545
The following command removes the USB filter that is second in the list for the ol7 VM.
$ VBoxManage usbfilter remove 1 --target ol7
9.42 VBoxManage sharedfolder
Add and remove shared folders.
Synopsis
VBoxManage sharedfolder add <uuid | vmname> <--name=name>
<--hostpath=hostpath> [--readonly] [--transient] [--automount]
[--auto-mount-point=path]
VBoxManage sharedfolder remove <uuid | vmname> <--name=name> [--transient]
Description
Shared folders enable you to share data between the host system and guests. To use shared
folders, you must first install the Oracle VM VirtualBox Guest Additions software on the guest
OS.
The shared folder is associated with a share name and the full path name of the folder or
directory on the host system. The share name is a unique name within the namespace of the host
OS.
279
9 VBoxManage
Add a Shared Folder
VBoxManage sharedfolder add <uuid | vmname> <--name=name>
<--hostpath=hostpath> [--readonly] [--transient] [--automount]
[--auto-mount-point=path]
The VBoxManage sharedfolder add command creates a shared folder. The folder you spec-
ify is on the host computer. When configured, the contents of the folder on the host system can
be shared with the guest OS.
uuid|vmname
Specifies the name or UUID of the guest VM that shares a folder with the host system.
-name=name
Specifies the name of the share, which is a unique name within the namespace of the host
OS.
-hostpath=hostpath
Specifies the absolute path of the folder or directory on the host OS to share with the guest
OS.
-readonly
Specifies that the share has only read-only access to files at the host path.
By default, shared folders have read-write access to the files at the host path. However on
Linux distributions, shared folders are mounted with 770 file permissions with the root
user and the vboxsf group. By using this option, the file permissions become 700.
-transient
Specifies that the share is transient, which means that it can be added and removed at
runtime and does not persist after the VM stops.
-automount
Specifies that the share is automatically mounted.
-auto-mount-point=path
Specifies the mount point of the share. This guest OS specific.
For Windows and OS/2 guest this must be an unused drive letter. If left blank (or if the
drive letter is already in use), the last unused drive letter is used instead (i.e. searching
from Z: thru A:).
For Linux, Solaris and other unix guest, it must be an absolute path like
/mnt/mysharedfolder. If left empty the default location is /media/sf_sharename.
Remove a Shared Folder
VBoxManage sharedfolder remove <uuid | vmname> <--name=name> [--transient]
The VBoxManage sharedfolder remove command removes a shared folder.
uuid|vmname
Specifies the name or UUID of the guest VM that shares a folder with the host system.
-name=name
Specifies the name of the share to remove.
-transient
Specifies that the share is transient, which means that it can be added and removed at
runtime and does not persist after the VM stops.
280
9 VBoxManage
Examples
The following command creates a shared folder called o7share for the ol7 VM. The share is
mounted automatically when the VM is started.
$ VBoxManage sharedfolder add ol7 --name ol7share --hostpath "/home/user/ol7share" --automount
The following command removes the shared folder called o7share for the ol7 VM.
$ VBoxManage sharedfolder remove ol7 --name ol7share
9.43 VBoxManage guestproperty
Manage virtual machine guest properties.
Synopsis
VBoxManage guestproperty get <uuid | vmname> <property-name> [--verbose]
VBoxManage guestproperty enumerate <uuid | vmname> [--no-timestamp]
[--no-flags] [--relative] [--old-format] [patterns. . . ]
VBoxManage guestproperty set <uuid | vmname> <property-name>
[property-value [--flags=flags] ]
VBoxManage guestproperty unset <uuid | vmname> <property-name>
VBoxManage guestproperty wait <uuid | vmname> <patterns> [--timeout=msec]
[--fail-on-timeout]
Description
The VBoxManage guestproperty command enables you to set or retrieve the properties of a
running virtual machine (VM). See chapter 5.7, Guest Properties, page 104. Guest properties are
arbitrary name-value string pairs that can be written to and read from by either the guest or the
host. As a result, these properties can be used as a low-volume communication channel for strings
provided that a guest is running and has the Guest Additions installed. In addition, the Guest
Additions automatically set and maintain values whose keywords begin with /VirtualBox/.
General Command Operand
uuid|vmname
Specifies the Universally Unique Identifier (UUID) or name of the VM.
List All Properties for a Virtual Machine
VBoxManage guestproperty enumerate <uuid | vmname> [--no-timestamp]
[--no-flags] [--relative] [--old-format] [patterns. . . ]
The VBoxManage guestproperty enumerate command lists each guest property and value
for the specified VM. Note that the output is limited if the guest’s service is not updating the
properties, for example because the VM is not running or because the Guest Additions are not
installed.
281
9 VBoxManage
--relative
Display the timestamp relative to current time.
--no-timestamp
Do not display the timestamp of the last update.
--no-flags
Do not display the flags.
--old-format
Use the output format from VirtualBox 6.1 and earlier.
<pattern>
Filters the list of properties based on the specified pattern, which can contain the following
wildcard characters:
* (asterisk)
Represents any number of characters. For example, the /VirtualBox* pattern
matches all properties that begin with /VirtualBox.
? (question mark)
Represents a single arbitrary character. For example, the fo? pattern matches both
foo and for.
| (pipe)
Specifies multiple alternative patterns. For example, the s*|t* pattern matches any
property that begins with s or t.
Retrieve a Property Value for a Virtual Machine
VBoxManage guestproperty get <uuid | vmname> <property-name> [--verbose]
The VBoxManage guestproperty get command retrieves the value of the specified property.
If the property cannot be found, for example because the guest is not running, the command
issues the following message:
No value set!
property-name
Specifies the name of the property.
--verbose
Provides the property value, timestamp, and any specified value attributes.
Set a Property Value for a Virtual Machine
VBoxManage guestproperty set <uuid | vmname> <property-name>
[property-value [--flags=flags] ]
The VBoxManage guestproperty set command enables you to set a guest property by spec-
ifying the property and its value. If you omit the value, the property is deleted.
property-name
Specifies the name of the property.
property-value
Specifies the value of the property. If no value is specified, any existing value is removed.
282
9 VBoxManage
--flags=<flags>
Specify the additional attributes of the value. The following attributes can be specified as
a comma-separated list:
TRANSIENT
Removes the value with the VM data when the VM exits.
TRANSRESET
Removes the value when the VM restarts or exits.
RDONLYGUEST
Specifies that the value can be changed only by the host and that the guest can read
the value.
RDONLYHOST
Specifies that the value can be changed only by the guest and that the host can read
the value.
READONLY
Specifies that the value cannot be changed.
Wait for a Property Value to Be Created, Deleted, or Changed
VBoxManage guestproperty wait <uuid | vmname> <patterns> [--timeout=msec]
[--fail-on-timeout]
The VBoxManage guestproperty wait command waits for a particular value that is de-
scribed by the pattern string to change, to be deleted, or to be created.
patterns
Specifies a pattern that matches the properties on which you want to wait. For information
about the pattern wildcards, see the description of the --patterns option.
--timeout<msec>
Specifies the number of microseconds to wait.
--fail-on-timeout
Specifies that the command fails if the timeout is reached.
Unset a Virtual Machine Property Value
VBoxManage guestproperty unset <uuid | vmname> <property-name>
The VBoxManage guestproperty unset command unsets the value of a guest property.
The alternate form of this subcommand is delete.
property-name
Specifies the name of the property.
Examples
The following command lists the guest properties and their values for the win8 VM.
$ VBoxManage guestproperty enumerate win8
The following command creates a guest property called region for the win8 VM. The value of
the property is set to west.
$ VBoxManage guestproperty set win8 region west
283
9 VBoxManage
9.44 VBoxManage guestcontrol
Control a virtual machine from the host system.
Synopsis
VBoxManage guestcontrol <uuid | vmname> run [--arg0=argument 0]
[--domain=domainname] [--dos2unix] [--exe=filename]
[--ignore-orphaned-processes] [--no-wait-stderr | --wait-stderr]
[--no-wait-stdout | --wait-stdout] [--passwordfile=password-file
| --password=password] [--profile] [--putenv=var-name=[value]] [--quiet]
[--timeout=msec] [--unix2dos] [--unquoted-args] [--username=username]
[--verbose] <-- [argument. . . ]
>
VBoxManage guestcontrol <uuid | vmname> start [--arg0=argument 0]
[--domain=domainname] [--exe=filename] [--ignore-orphaned-processes]
[--passwordfile=password-file | --password=password] [--profile]
[--putenv=var-name=[value]] [--quiet] [--timeout=msec] [--unquoted-args]
[--username=username] [--verbose] <-- [argument. . . ]
>
VBoxManage guestcontrol <uuid | vmname> copyfrom [--dereference]
[--domain=domainname] [--passwordfile=password-file
| --password=password] [--quiet] [--no-replace] [--recursive]
[--target-directory=host-destination-dir] [--update]
[--username=username] [--verbose] <guest-source0> guest-source1 [...]
<host-destination>
VBoxManage guestcontrol <uuid | vmname> copyto [--dereference]
[--domain=domainname] [--passwordfile=password-file
| --password=password] [--quiet] [--no-replace] [--recursive]
[--target-directory=guest-destination-dir] [--update]
[--username=username] [--verbose] <host-source0> host-source1 [...]
VBoxManage guestcontrol <uuid | vmname> mkdir [--domain=domainname]
[--mode=mode] [--parents] [--passwordfile=password-file
| --password=password] [--quiet] [--username=username] [--verbose]
<guest-directory. . . >
VBoxManage guestcontrol <uuid | vmname> rmdir [--domain=domainname]
[--passwordfile=password-file | --password=password] [--quiet]
[--recursive] [--username=username] [--verbose] <guest-directory. . . >
VBoxManage guestcontrol <uuid | vmname> rm [--domain=domainname] [--force]
[--passwordfile=password-file | --password=password] [--quiet]
[--username=username] [--verbose] <guest-directory. . . >
VBoxManage guestcontrol <uuid | vmname> mv [--domain=domainname]
[--passwordfile=password-file | --password=password] [--quiet]
[--username=username] [--verbose] <source. . . > <destination-directory>
VBoxManage guestcontrol <uuid | vmname> mktemp [--directory]
[--domain=domainname] [--mode=mode] [--passwordfile=password-file
| --password=password] [--quiet] [--secure] [--tmpdir=directory-name]
[--username=username] [--verbose] <template-name>
284
9 VBoxManage
VBoxManage guestcontrol <uuid | vmname> stat [--domain=domainname]
[--passwordfile=password-file | --password=password] [--quiet]
[--username=username] [--verbose] <filename>
VBoxManage guestcontrol <uuid | vmname> list <all | files | processes
| sessions> [--quiet] [--verbose]
VBoxManage guestcontrol <uuid | vmname> closeprocess [--session-id=ID
| --session-name=name-or-pattern] [--quiet] [--verbose] <PID. . . >
VBoxManage guestcontrol <uuid | vmname> closesession [--all
| --session-id=ID | --session-name=name-or-pattern] [--quiet] [--verbose]
VBoxManage guestcontrol <uuid | vmname> updatega [--quiet] [--verbose]
[--source=guest-additions.ISO] [--wait-start] [-- [argument. . . ]
]
VBoxManage guestcontrol <uuid | vmname> watch [--quiet] [--verbose]
Description
The VBoxManage guestcontrol command enables you to control a guest (VM) from the host
system. See chapter 5.9, Guest Control of Applications, page 108.
Common Options and Operands
The following options can be used by any of the VBoxManage guestcontrol subcommands:
uuid|vmname
Specifies the Universally Unique Identifier (UUID) or name of the VM.
--quiet
Specifies that the command produce quieter output.
The short form of this option is -q.
--verbose
Specifies that the command produce more detailed output.
The short form of this option is -v.
Some of the VBoxManage guestcontrol subcommands require that you provide guest cre-
dentials for authentication. The subcommands are: copyfrom, copyto, mkdir, mktemp, mv,
rmdir, rm, run, start, and stat.
While you cannot perform anonymous executions, a user account password is optional and
depends on the guest’s OS security policy. If a user account does not have an associated password,
specify an empty password. On OSes such as Windows, you might need to adjust the security
policy to permit user accounts with an empty password. In additional, global domain rules might
apply and therefore cannot be changed.
The following options are used for authentication on the guest VM:
--domain=<domainname>
Specifies the user domain for Windows guest VMs.
--password=<password>
Specifies the password for the specified user. If you do not specify a password on the
command line or if the password file is empty, the specified user needs to have an empty
password.
285
|
||
|
|
|