7.8. VBoxManage modifyvm

This command changes the properties of a registered virtual machine which is not running. Most of the properties that this command makes available correspond to the VM settings that Oracle VM VirtualBox graphical user interface displays in each VM's Settings dialog. These are described in Chapter 3, Configuring Virtual Machines. However, some of the more advanced settings are only available through the VBoxManage interface.

These commands require that the machine is powered off, neither running nor in a Saved state. Some machine settings can also be changed while a machine is running. Those settings will then have a corresponding subcommand with the VBoxManage controlvm subcommand. See Section 7.14, “VBoxManage controlvm”.

7.8.1. General Settings

The following general settings are available through VBoxManage modifyvm:

  • --name <name>: Changes the VM's name and can be used to rename the internal virtual machine files, as described in Section 7.7, “VBoxManage createvm”.

  • --groups <group>, ...: Changes the group membership of a VM. Groups always start with a / and can be nested. By default VMs are in group /.

  • --description <desc>: Changes the VM's description, which is a way to record details about the VM in a way which is meaningful for the user. The GUI interprets HTML formatting, the command line allows arbitrary strings potentially containing multiple lines.

  • --ostype <ostype>: Specifies what guest operating system is supposed to run in the VM. To learn about the various identifiers that can be used here, use VBoxManage list ostypes.

  • --iconfile <filename>: Specifies the absolute path on the host file system for the Oracle VM VirtualBox icon to be displayed in the VM.

  • --memory <memorysize>: Sets the amount of RAM, in MB, that the virtual machine should allocate for itself from the host. See Section 1.8, “Creating Your First Virtual Machine”.

  • --pagefusion on|off: Enables and disables the Page Fusion feature. Page Fusion is disabled by default. The Page Fusion feature minimises memory duplication between VMs with similar configurations running on the same host. See Section 4.10.2, “Page Fusion”.

  • --vram <vramsize>: Sets the amount of RAM that the virtual graphics card should have. See Section 3.6, “Display Settings”.

  • --acpi on|off and --ioapic on|off: Determines whether the VM has ACPI and I/O APIC support. See Section 3.5.1, “Motherboard Tab”.

  • --pciattach <host PCI address [@ guest PCI bus address]>: Attaches a specified PCI network controller on the host to a specified PCI bus on the guest. See PCI Passthrough.

  • --pcidetach <host PCI address>: Detaches a specified PCI network controller on the host from the attached PCI bus on the guest. See PCI Passthrough.

  • --hardwareuuid <uuid>: The UUID presented to the guest through memory tables (DMI/SMBIOS), hardware, and guest properties. By default this is the same as the VM UUID. This setting is useful when cloning a VM. Teleporting takes care of this automatically.

  • --cpus <cpucount>: Sets the number of virtual CPUs for the virtual machine, see Section 3.5.2, “Processor Tab”. If CPU hot-plugging is enabled, this then sets the maximum number of virtual CPUs that can be plugged into the virtual machines.

  • --cpuhotplug on|off: Enables CPU hot-plugging. When enabled, virtual CPUs can be added to and removed from a virtual machine while it is running. See CPU Hot-Plugging.

  • --plugcpu|unplugcpu <id>: If CPU hot-plugging is enabled, this setting adds or removes a virtual CPU on the virtual machine. <id> specifies the index of the virtual CPU to be added or removed and must be a number from 0 to the maximum number of CPUs configured with the --cpus option. CPU 0 can never be removed.

  • --cpuexecutioncap <1-100>: Controls how much CPU time a virtual CPU can use. A value of 50 implies a single virtual CPU can use up to 50% of a single host CPU.

  • --pae on|off: Enables and disables PAE. See Section 3.5.2, “Processor Tab”.

  • --longmode on|off: Enables and disables long mode. See Section 3.5.2, “Processor Tab”.

  • --spec-ctrl on|off: Enables and disables the exposure of speculation control interfaces to the guest, provided they are available on the host. Depending on the host CPU and workload, enabling speculation control may significantly reduce performance.

  • --cpu-profile <host|intel 80[86|286|386]>: Enables specification of a profile for guest CPU emulation. Specify either one based on the host system CPU (host), or one from a number of older Intel Micro-architectures: 8086, 80286, 80386.

  • --hpet on|off: Enables and disables a High Precision Event Timer (HPET) which can replace the legacy system timers. This is turned off by default. Note that Windows supports a HPET only from Vista onwards.

  • --hwvirtex on|off: Enables and disables the use of hardware virtualization extensions, such as Intel VT-x or AMD-V, in the processor of your host system. See Hardware vs. Software Virtualization.

  • --triplefaultreset on|off: Enables resetting of the guest instead of triggering a Guru Meditation. Some guests raise a triple fault to reset the CPU so sometimes this is desired behavior. Works only for non-SMP guests.

  • --apic on|off: Enables and disables I/O APIC. With I/O APIC, operating systems can use more than 16 interrupt requests (IRQs) thus avoiding IRQ sharing for improved reliability. This setting is enabled by default. See Section 3.5.1, “Motherboard Tab”.

  • --x2apic on|off: Enables and disables CPU x2APIC support. CPU x2APIC support helps operating systems run more efficiently on high core count configurations, and optimizes interrupt distribution in virtualized environments. This setting is enabled by default. Disable this setting when using host or guest operating systems that are incompatible with x2APIC support.

  • --paravirtprovider none|default|legacy|minimal|hyperv|kvm: Specifies which paravirtualization interface to provide to the guest operating system. Specifying none explicitly turns off exposing any paravirtualization interface. The option default selects an appropriate interface when starting the VM, depending on the guest OS type. This is the default option chosen when creating new VMs. The legacy option is used for VMs which were created with older Oracle VM VirtualBox versions and will pick a paravirtualization interface when starting the VM with Oracle VM VirtualBox 5.0 and newer. The minimal provider is mandatory for Mac OS X guests. kvm and hyperv are recommended for Linux and Windows guests respectively. These options are explained in Paravirtualization Providers.

  • --paravirtdebug <keyword=value> [,<keyword=value> ...]: Specifies debugging options specific to the paravirtualization provider configured for this VM. See the provider specific options in Paravirtualized Debugging for a list of supported keyword-value pairs for each provider.

  • --nestedpaging on|off: If hardware virtualization is enabled, this additional setting enables or disables the use of the nested paging feature in the processor of your host system. See Hardware vs. Software Virtualization and CVE-2018-3646.

  • --largepages on|off: If hardware virtualization and nested paging are enabled, for Intel VT-x only, an additional performance improvement of up to 5% can be obtained by enabling this setting. This causes the hypervisor to use large pages to reduce TLB use and overhead.

  • --vtxvpid on|off: If hardware virtualization is enabled, for Intel VT-x only, this additional setting enables or disables the use of the tagged TLB (VPID) feature in the processor of your host system. See Hardware vs. Software Virtualization.

  • --vtxux on|off: If hardware virtualization is enabled, for Intel VT-x only, this setting enables or disables the use of the unrestricted guest mode feature for executing your guest.

  • --accelerate3d on|off: If the Guest Additions are installed, this setting enables or disables hardware 3D acceleration. See Section 4.5.1, “Hardware 3D Acceleration (OpenGL and Direct3D 8/9)”.

  • --accelerate2dvideo on|off: If the Guest Additions are installed, this setting enables or disables 2D video acceleration. See Section 4.5.2, “Hardware 2D Video Acceleration for Windows Guests”.

  • --chipset piix3|ich9: By default, Oracle VM VirtualBox emulates an Intel PIIX3 chipset. Usually there is no reason to change the default setting unless this is required to relax some of its constraints. See Section 3.5.1, “Motherboard Tab”.

  • You can influence the BIOS logo that is displayed when a virtual machine starts up with a number of settings. By default, an Oracle VM VirtualBox logo is displayed.

    With --bioslogofadein on|off and --bioslogofadeout on|off, you can determine whether the logo should fade in and out, respectively.

    With --bioslogodisplaytime <msec> you can set how long the logo should be visible, in milliseconds.

    With --bioslogoimagepath <imagepath> you can replace the image that is shown with your own logo. The image must be an uncompressed 256 color BMP file without color space information (Windows 3.0 format). The image must not be bigger than 640 x 480.

  • --biosbootmenu disabled|menuonly|messageandmenu: Specifies whether the BIOS enables the user to select a temporary boot device. The menuonly option suppresses the message, but the user can still press F12 to select a temporary boot device.

  • --biosapic x2apic|apic|disabled: Specifies the firmware APIC level to be used. Options are: x2apic, apic or disabled (no apic or x2apic) respectively.

    Note that if x2apic is specified and x2APIC is unsupported by the VCPU, biosapic downgrades to apic, if supported. Otherwise biosapic downgrades to disabled. Similarly, if apic is specified, and APIC is unsupported, a downgrade to disabled results.

  • --biossystemtimeoffset <ms>: Specifies a fixed time offset, in milliseconds, of the guest relative to the host time. If the offset is positive, the guest time runs ahead of the host time.

  • --biospxedebug on|off: Enables additional debugging output when using the Intel PXE boot ROM. The output is written to the release log file. See Collecting Debugging Information.

  • --boot<1-4> none|floppy|dvd|disk|net: Specifies the boot order for the virtual machine. There are four slots, which the VM will try to access from 1 to 4, and for each of which you can set a device that the VM should attempt to boot from.

  • --rtcuseutc on|off: Sets the real-time clock (RTC) to operate in UTC time. See Section 3.5.1, “Motherboard Tab”.

  • --graphicscontroller none|vboxvga|vmsvga|vboxsvga: Specifies the use of a graphics controller, with an option to choose a specific type. See Section 3.6.1, “Screen Tab”.

  • --snapshotfolder default|<path>: Specifies the folder where snapshots are kept for a virtual machine.

  • --firmware bios|efi|efi32|efi64: Specifies the firmware to be used to boot the VM: Available options are: BIOS, or one of the EFI options: efi, efi32, or efi64. Use EFI options with care.

  • --guestmemoryballoon <size> Sets the default size of the guest memory balloon. This is the memory allocated by the Oracle VM VirtualBox Guest Additions from the guest operating system and returned to the hypervisor for reuse by other virtual machines. <size> must be specified in megabytes. The default size is 0 megabytes. See Section 4.10.1, “Memory Ballooning”.

  • --defaultfrontend default|<name>: Specifies the default frontend to be used when starting this VM. See Section 7.13, “VBoxManage startvm”.

7.8.2. Networking Settings

The following networking settings are available through VBoxManage modifyvm. With all these settings, the decimal number directly following the option name, 1-N in the list below, specifies the virtual network adapter whose settings should be changed.

  • --nic<1-N> none|null|nat|natnetwork|bridged|intnet|hostonly|generic: Configures the type of networking for each of the VM's virtual network cards. Options are: not present (none), not connected to the host (null), use network address translation (nat), use the new network address translation engine (natnetwork), bridged networking (bridged), or use internal networking (intnet), host-only networking (hostonly), or access rarely used sub-modes (generic). These options correspond to the modes described in Section 6.2, “Introduction to Networking Modes”.

  • --nictype<1-N> Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio: Enables you to specify the networking hardware that Oracle VM VirtualBox presents to the guest for a specified VM virtual network card. See Section 6.1, “Virtual Networking Hardware”.

  • --cableconnected<1-N> on|off: Enables you to temporarily disconnect a virtual network interface, as if a network cable had been pulled from a real network card. This might be useful, for example for resetting certain software components in the VM.

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

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

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

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

    These parameters are backend engine-specific, and are different between UDP Tunnel and the VDE backend drivers. For examples, see Section 6.8, “UDP Tunnel Networking”.

  • --nicspeed<1-N> <kbps>: Only has an effect if generic networking has been enabled for a particular virtual network card. See the --nic option. This mode enables access to rarely used networking sub-modes, such as VDE network or UDP Tunnel. This option specifies the throughput rate in KBps.

  • --nicbootprio<1-N> <priority>: Specifies the order in which NICs are tried for booting over the network, using PXE. The priority is an integer in the 0 to 4 range. Priority 1 is the highest, priority 4 is low. Priority 0, which is the default unless otherwise specified, is the lowest.

    Note that this option only has an effect when the Intel PXE boot ROM is used.

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

  • --nicbandwidthgroup<1-N> none|<name>: Adds and removes an assignment of a bandwidth group for the specified virtual network interface. Specifying none removes any current bandwidth group assignment from the specified virtual network interface. Specifying <name> adds an assignment of a bandwidth group to the specified virtual network interface.

    See Section 6.10, “Limiting Bandwidth for Network Input/Output”.

  • --bridgeadapter<1-N> none|<devicename>: Only has an effect if bridged networking has been enabled for a virtual network card. See the --nic option. Use this option to specify which host interface the given virtual network interface will use. See Section 6.5, “Bridged Networking”.

  • --hostonlyadapter<1-N> none|<devicename>: Only has an effect if host-only networking has been enabled for a virtual network card. See the --nic option. Use this option to specify which host-only networking interface the given virtual network interface will use. See Section 6.7, “Host-Only Networking”.

  • --intnet<1-N> network: Only has an effect if internal networking has been enabled for a virtual network card. See the --nic option. Use this option to specify the name of the internal network. See Section 6.6, “Internal Networking”.

  • --nat-network<1-N> <network name>: If the networking type is set to natnetwork, not nat, then this setting specifies the name of the NAT network this adapter is connected to. Optional.

  • --nicgenericdrv<1-N> <backend driver>: Only has an effect if generic networking has been enabled for a virtual network card. See the --nic option. This mode enables you to access rarely used networking sub-modes, such as VDE network or UDP Tunnel.

  • --macaddress<1-N> auto|<mac>: With this option you can set the MAC address of a particular network adapter on the VM. Normally, each network adapter is assigned a random address by Oracle VM VirtualBox at VM creation.

7.8.2.1. NAT Networking Settings

The following NAT networking settings are available through VBoxManage modifyvm. With all these settings, the decimal number directly following the option name, 1-N in the list below, specifies the virtual network adapter whose settings should be changed.

7.8.3. Miscellaneous Settings

The following hardware settings, such as serial port, audio, clipboard, drag and drop, monitor, and USB settings are available through VBoxManage modifyvm:

  • --mouse <ps2|usb|usbtablet|usbmultitouch>: Specifies the mode of the mouse to be used in the VM. Available options are: ps2, usb, usbtablet, usbmultitouch.

  • --keyboard <ps2|usb>: Specifies the mode of the keyboard to be used in the VM. Available options are: ps2, usb.

  • --uart<1-N> off|<I/O base> <IRQ>: Configures virtual serial ports for the VM. See Section 3.10, “Serial Ports”.

  • --uartmode<1-N> <arg>: Controls how Oracle VM VirtualBox connects a given virtual serial port, configured with the --uartX setting, to the host on which the virtual machine is running. As described in Section 3.10, “Serial Ports”, for each such port, you can specify <arg> as one of the following options:

    • disconnected: Even though the serial port is shown to the guest, it has no "other end". This is like a real COM port without a cable.

    • server <pipename>: On a Windows host, this tells Oracle VM VirtualBox to create a named pipe on the host named <pipename> and connect the virtual serial device to it. Note that Windows requires that the name of a named pipe begins with \\.\pipe\.

      On a Linux host, instead of a named pipe, a local domain socket is used.

    • client <pipename>: Operates as for server, except that the pipe, or local domain socket, is not created by Oracle VM VirtualBox but is assumed to exist already.

    • tcpserver <port>: Configures Oracle VM VirtualBox to create a TCP socket on the host with TCP <port> and connect the virtual serial device to it. Note that UNIX-like systems require ports over 1024 for normal users.

    • tcpclient <hostname:port>: Operates as for tcpserver, except that the TCP socket is not created by Oracle VM VirtualBox, but is assumed to exist already.

    • uarttype <1-N> 16450|16550A|16750: Confgures the UART type for a virtual serial port. The default UART type is 16550A.

    • file <file>: Redirects the serial port output to a raw file <file> specified by its absolute path on the host file system.

    • <devicename>: If, instead of the above options, the device name of a physical hardware serial port of the host is specified, the virtual serial port is connected to that hardware port. On a Windows host, the device name will be a COM port such as COM1. On a Linux host, the device name will be /dev/ttyS0 or similar. This enables you to wire up a real serial port to a virtual machine.

  • --lptmode<1-N> <Device>: Specifies the Device Name of the parallel port that the Parallel Port feature will be using. Use this before --lpt. This feature depends on the host operating system. For Windows hosts, use a device name such as lpt1. On Linux hosts, use a device name such as /dev/lp0.

  • --lpt<1-N> <I/O base> <IRQ>: Specifies the I/O address of the parallel port and the IRQ number that the Parallel Port feature will be using. Optional. Use this after --lptmod. I/O base address and IRQ are the values that guest sees. For example, the values avalable under guest Device Manager.

  • --audio none|null|dsound|oss|alsa|pulse|coreaudio: Specifies whether the VM should have audio support, and if so, which type. The list of supported audio types depends on the host and can be determined with VBoxManage modifyvm.

  • --audiocontroller ac97|hda|sb16: Specifies the audio controller to be used with the VM.

  • --audiocodec stac9700|ad1980|stac9221|sb16: Specifies the audio codec to be used with the VM.

  • --audioin on: Specifies whether capturing audio from the host is enabled or disabled.

  • --audioout on: Specifies whether audio playback from the guest is enabled or disabled.

  • --clipboard disabled|hosttoguest|guesttohost|bidirectional: Configues how the guest or host operating system's clipboard should be shared with the host or guest. See Section 3.4, “General Settings”. This setting requires that the Guest Additions be installed in the virtual machine.

  • --draganddrop disabled|hosttoguest|guesttohost|bidirectional: Specifies the drag and drop mode to use between the host and the virtual machine. See Section 4.4, “Drag and Drop”. This requires that the Guest Additions be installed in the virtual machine.

  • --monitorcount <count>: Enables multi-monitor support. See Section 3.6, “Display Settings”.

  • --usb on|off: Enables and disables the VM's virtual USB controller. See Section 3.11.1, “USB Settings”.

  • --usbehci on|off: Enables and disables the VM's virtual USB 2.0 controller. See Section 3.11.1, “USB Settings”.

  • --usbxhci on|off: Enables and disables the VM's virtual USB 3.0 controller. See Section 3.11.1, “USB Settings”.

  • --usbrename <oldname> <newname>: Enables renaming of the VM's virtual USB controller from <oldname> to <newname>.

7.8.4. Recording Settings

The VBoxManage modifyvm command enables you to modify recording settings for video recording, audio recording, or both.

Use the following options to update the recording settings:

  • --recording on|off enables or disables the recording of a VM session into a WebM/VP8 file. When this option value is on, recording begins when the VM session starts.

  • --recordingscreens all|screen-ID [screen-ID ...] enables you to specify which VM screens to record. The recording for each screen that you specify is saved to its own file.

  • --recordingfile filename specifies the file in which to save the recording.

  • --recordingmaxsize MB specifies the maximum size of the recorded video file in megabytes. The recording stops when the file reaches the specified size. If this value is zero, the recording continues until you stop the recording.

  • --recordingmaxtime seconds specifies the maximum amount time to record in seconds. The recording stops after the specified number of seconds elapses. If this value is zero, the recording continues until you stop the recording.

  • --recordingopts keyword=value[,keyword=value ...] specifies additional video-recording options in a comma-separated keyword-value format. For example, foo=bar,a=b.

    Only use this option only if you are an advanced user. For information about keywords, see Oracle VM VirtualBox Programming Guide and Reference.

  • --recordingvideofps fps specifies the maximum number of video frames per second (FPS) to record. Frames that have a higher frequency are skipped. Increasing this value reduces the number of skipped frames and increases the file size.

  • --recordingvideorate bit-rate specifies the bit rate of the video in kilobits per second. Increasing this value improves the appearance of the video at the cost of an increased file size.

  • --recordingvideores widthxheight specifies the video resolution of the recorded video in pixels.

7.8.5. Remote Machine Settings

The following settings that affect remote machine behavior are available through VBoxManage modifyvm:

  • --vrde on|off: Enables and disables the VirtualBox Remote Desktop Extension (VRDE) server.

  • --vrdeproperty "TCP/Ports|Address=<value>": Sets the port numbers and IP address on the VM that the VRDE server can bind to.

    • For TCP/Ports, <value> should be a port or a range of ports that the VRDE server can bind to. default or 0 means port 3389, the standard port for RDP. See the description for the --vrdeport option in Section 7.8.5, “Remote Machine Settings”.

    • For TCP/Address, <value> should be the IP address of the host network interface that the VRDE server will bind to. If specified, the server will accept connections only on the specified host network interface. See the description for the --vrdeaddress option in Section 7.8.5, “Remote Machine Settings”.

  • --vrdeproperty "VideoChannel/Enabled|Quality|DownscaleProtection=<value>": Sets the VRDP video redirection properties.

    • For VideoChannel/Enabled, <value> can be set to "1", switching the VRDP video channel on. See VRDP Video Redirection.

    • For VideoChannel/Quality, <value> should be set between 10 and 100% inclusive, representing a JPEG compression level on the VRDE server video channel. Lower values mean lower quality but higher compression. See VRDP Video Redirection.

    • For VideoChannel/DownscaleProtection, <value> can be set to "1" to enable the videochannel downscale protection feature. When enabled, if a video's size equals the shadow buffer size, then it is regarded as a full screen video, and is displayed. But if its size is between fullscreen and the downscale threshold then it is not displayed, as it could be an application window, which would be unreadable when downscaled. When the downscale protection feature is disabled, an attempt is always made to display videos.

  • --vrdeproperty "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1": Disables one of the VRDE server features: Display, Input, Audio or USB respectively. To reenable a feature, use "Client/DisableDisplay=" for example. See VRDP Customization.

  • --vrdeproperty "Client/DisableClipboard|DisableUpstreamAudio=1": Disables one of the VRDE server features: Clipboard or UpstreamAudio respectively. To reenable a feature, use "Client/DisableClipboard=" for example. See VRDP Customization.

  • --vrdeproperty "Client/DisableRDPDR=1": Disables the VRDE server feature: RDP device redirection for smart cards. To reenable this feature, use "Client/DisableRDPR=".

  • --vrdeproperty "H3DRedirect/Enabled=1": Enables the VRDE server feature: 3D redirection. To disable this feature, use "H3DRedirect/Enabled=".

  • --vrdeproperty "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=<value>": Sets the desired security method and path of server certificate, path of server private key, path of CA certificate, that are used for a connection.

    • --vrdeproperty "Security/Method=<value>" sets the desired security method, which is used for a connection. Valid values are:

      • Negotiate: Both Enhanced (TLS) and Standard RDP Security connections are allowed. The security method is negotiated with the client. This is the default setting.

      • RDP: Only Standard RDP Security is accepted.

      • TLS: Only Enhanced RDP Security is accepted. The client must support TLS.

      See RDP Encryption.

    • --vrdeproperty "Security/ServerCertificate=<value>" where <value> is the absolute path of the server certificate. See RDP Encryption.

    • --vrdeproperty "Security/ServerPrivateKey=<value>" where <value> is the absolute path of the server private key. See RDP Encryption.

    • --vrdeproperty "Security/CACertificate=<value>" where <value> is the absolute path of the CA self signed certificate. See RDP Encryption.

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

    • --vrdeproperty "Audio/RateCorrectionMode=<value>" where <value> is the desired rate correction mode. Allowed values are:

      • VRDP_AUDIO_MODE_VOID: No mode specified, use to unset any Audio mode already set.

      • VRDP_AUDIO_MODE_RC: Rate correction mode.

      • VRDP_AUDIO_MODE_LPF: Low pass filter mode.

      • VRDP_AUDIO_MODE_CS: Client sync mode to prevent underflow or overflow of the client queue.

    • --vrdeproperty "Audio/LogPath=<value>" where <value> is the absolute path of the Audio log file.

  • --vrdeextpack default|<name>: Specifies the library to use for accessing the VM remotely. The default is to use the RDP code which is part of the Oracle VM VirtualBox Extension Pack.

  • --vrdeport default|<ports>: A port or a range of ports the VRDE server can bind to. default or 0 means port 3389, the standard port for RDP. You can specify a comma-separated list of ports or ranges of ports. Use a dash between two port numbers to specify a range. The VRDE server will bind to one of the available ports from the specified list. Only one machine can use a given port at a time. For example, the option --vrdeport 5000,5010-5012 will tell the server to bind to one of following ports: 5000, 5010, 5011, or 5012.

  • --vrdeaddress <IP address>: The IP address of the host network interface the VRDE server will bind to. If specified, the server will accept connections only on the specified host network interface.

    The setting can be used to specify whether the VRDP server should accept either IPv4, IPv6, or both connections:

    • Only IPv4: --vrdeaddress "0.0.0.0"

    • Only IPv6: --vrdeaddress "::"

    • Both IPv6 and IPv4: --vrdeaddress ""

      This is the default setting.

  • --vrdeauthtype null|external|guest: Enables you to indicate use of authorization, and specify how authorization will be performed. See RDP Authentication.

  • --vrdeauthlibrary default|<name>: Specifies the library used for RDP authentication. See RDP Authentication.

  • --vrdemulticon on|off: Enables multiple connections to be made to the same VRDE server, if the server supports this feature. See Multiple Connections to the VRDP Server.

  • --vrdereusecon on|off: This specifies the VRDE server behavior when multiple connections are disabled. When this option is enabled, the server will allow a new client to connect and will drop the existing connection. When this option is disabled, the default setting, a new connection will not be accepted if there is already a client connected to the server.

  • --vrdevideochannel on|off: Enables video redirection, if it is supported by the VRDE server. See VRDP Video Redirection.

  • --vrdevideochannelquality <percent>: Specifies the image quality for video redirection. See VRDP Video Redirection.

7.8.6. Teleporting Settings

With the following commands for VBoxManage modifyvm you can configure a machine to be a target for teleporting. See Teleporting.

  • --teleporter on|off: Enables and disables the teleporter feature whereby when the machine is started, it 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.

  • --teleporterport <port>, --teleporteraddress <address>: These settings must be used with --teleporter. They specify the port and address the virtual machine should listen to in order to receive a teleporting request sent from another virtual machine. <port> can be any free TCP/IP port number, such as 6000. <address> can be any IP address or hostname and specifies the TCP/IP socket to bind to. The default is 0.0.0.0, which means any address.

  • --teleporterpassword <password>: If this optional setting is used, then the teleporting request will only succeed if the source machine specifies the same password as the one given with this command.

  • --teleporterpasswordfile <password>: If this optional setting is used, then the teleporting request will only succeed if the source machine specifies the same password as the one specified in the file give with this command. Use stdin to read the password from stdin.

  • --cpuid <leaf> <eax> <ebx> <ecx> <edx>: Advanced users can use this setting before a teleporting operation, 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 involved in the 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.

7.8.7. Debugging Settings

The following settings are only relevant for low-level VM debugging. Regular users will never need these settings.

  • --tracing-enabled on|off: Enables the tracebuffer. This consumes some memory for the tracebuffer and adds extra overhead.

  • --tracing-config <config-string>: Enables tracing configuration. In particular, this defines which group of tracepoints are enabled.

  • --tracing-allow-vm-access on|off: Enables and disables VM access to the tracebuffer. By default, this setting is disabled.

7.8.8. USB Card Reader Settings

The following setting defines access to a USB Card Reader by the guest environment. USB card readers are typically used for accessing data on memory cards such as CompactFlash (CF), Secure Digital (SD), or MultiMediaCard (MMC).

  • --usbcardreader on|off: Enables and disables the USB card reader interface.

7.8.9. Autostarting VMs During Host System Boot

These settings configure the VM autostart feature, which automatically starts the VM at host system boot-up. Note that there are prerequisites that need to be addressed before using this feature. See Starting Virtual Machines During System Boot.

  • --autostart-enabled on|off: Enables and disables VM autostart at host system boot-up, using the specified user name.

  • --autostart-delay <seconds>: Specifies a delay, in seconds, following host system boot-up, before the VM autostarts.