8.7. 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 VirtualBox graphical user interface displays in each VM's "Settings" dialog; these were described in Chapter 3, Configuring virtual machines. Some of the more advanced settings, however, are only available through the VBoxManage interface.

These commands require that the machine is powered off (neither running nor in "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 8.11, “VBoxManage controlvm”).

8.7.1. General settings

The following general settings are available through VBoxManage modifyvm:

  • --name <name>: This changes the VM's name and possibly renames the internal virtual machine files, as described with VBoxManage createvm above.

  • --ostype <ostype>: This 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.

  • --memory <memorysize>: This sets the amount of RAM, in MB, that the virtual machine should allocate for itself from the host. See the remarks in Section 1.7, “Creating your first virtual machine” for more information.

  • --vram <vramsize>: This sets the amount of RAM that the virtual graphics card should have. See Section 3.5, “Display settings” for details.

  • --acpi on|off; --ioapic on|off: These two determine whether the VM should have ACPI and I/O APIC support, respectively; see Section 3.4.1, “"Motherboard" tab” for details.

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

  • --cpus <cpucount>: This sets the number of virtual CPUs for the virtual machine (see Section 3.4.2, “"Processor" tab”). If CPU hot-plugging is enabled (see below), this then sets the maximum number of virtual CPUs that can be plugged into the virtual machines.

  • --rtcuseutc on|off: This option lets the real-time clock (RTC) operate in UTC time (see Section 3.4.1, “"Motherboard" tab”).

  • --cpuhotplug on|off: This enables CPU hot-plugging. When enabled, virtual CPUs can be added to and removed from a virtual machine while it is running. See Section 9.5, “CPU hot-plugging” for more information.

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

  • --cpuexecutioncap <1-100>: This setting 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.

  • --synthcpu on|off: This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow live migration between host systems that differ significantly.

  • --pae on|off: This enables/disables PAE (see Section 3.4.2, “"Processor" tab”).

  • --hpet on|off: This enables/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: This enables or disables the use of hardware virtualization extensions (Intel VT-x or AMD-V) in the processor of your host system; see Section 10.3, “Hardware vs. software virtualization”.

  • --hwvirtexexcl on|off: This specifies whether VirtualBox will make exclusive use of the hardware virtualization extensions (Intel VT-x or AMD-V) in the processor of your host system; see Section 10.3, “Hardware vs. software virtualization”. If you wish to simultaneously share these extensions with other hypervisors, then you must disable this setting. Doing so has negative performance implications.

  • --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 Section 10.3, “Hardware vs. software virtualization”.

  • --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 Section 10.3, “Hardware vs. software virtualization”.

  • --accelerate3d on|off: This enables, if the Guest Additions are installed, whether hardware 3D acceleration should be available; see Section 4.4.1, “Hardware 3D acceleration (OpenGL and Direct3D 8/9)”.

  • You can influence the BIOS logo that is displayed when a virtual machine starts up with a number of settings. Per default, a 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, if you are so inclined, replace the image that is shown, with your own logo. The image must be an uncompressed 256 color BMP file.

  • --biosbootmenu disabled|menuonly|messageandmenu: This specifies whether the BIOS allows the user to select a temporary boot device. menuonly suppresses the message, but the user can still press F12 to select a temporary boot device.

  • --boot<1-4> none|floppy|dvd|disk|net: This 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.

  • --snapshotfolder default|<path>: This allows you to specify the folder in which snapshots will be kept for a virtual machine.

  • --firmware efi|bios: Specifies which firmware is used to boot particular virtual machine: EFI or BIOS. Use EFI only if your fully understand what you're doing.

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

8.7.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|bridged|intnet|hostonly|vde: With this, you can set, for each of the VM's virtual network cards, what type of networking should be available. They can be not present (none), not connected to the host (null), use network address translation (nat), bridged networking (bridged) or communicate with other virtual machines using internal networking (intnet), host-only networking (hostonly) or on Linux and FreeBSD hosts a Virtual Distributed Ethernet switch (vde). These options correspond to the modes which are described in detail in Section 6.2, “Introduction to networking modes”.

  • --nictype<1-N> Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio: This allows you, for each of the VM's virtual network cards, to specify which networking hardware VirtualBox presents to the guest; see Section 6.1, “Virtual networking hardware”.

  • --cableconnected<1-N> on|off: This allows 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 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> what file the trace should be logged to.

  • --bridgeadapter<1-N> none|<devicename>: If bridged networking has been enabled for a virtual network card (see the --nic option above; otherwise this setting has no effect), use this option to specify which host interface the given virtual network interface will use. For details, please see Section 6.4, “Bridged networking”.

  • --hostonlyadapter<1-N> none|<devicename>: If host-only networking has been enabled for a virtual network card (see the --nic option above; otherwise this setting has no effect), use this option to specify which host-only networking interface the given virtual network interface will use. For details, please see Section 6.6, “Host-only networking”.

  • --intnet<1-N> network: If internal networking has been enabled for a virtual network card (see the --nic option above; otherwise this setting has no effect), use this option to specify the name of the internal network (see Section 6.5, “Internal networking”).

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

  • --vdenet<1-N> network: If Virtual Distributed Ethernet is available on the host and has been enabled for a virtual network card (see the --nic option above; otherwise this setting has no effect). Use this option to specify the name of a VDE network for the interface to connect to (see Section 6.2, “Introduction to networking modes” and the VDE documentation).

8.7.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.

8.7.3. Serial port, audio, clipboard, remote desktop and USB settings

The following other hardware settings are available through VBoxManage modifyvm:

  • --uart<1-N> off|<I/O base> <IRQ>: With this option you can configure virtual serial ports for the VM; see Section 3.9, “Serial ports” for an introduction.

  • --uartmode<1-N> <arg>: This setting controls how VirtualBox connects a given virtual serial port (previously configured with the --uartX setting, see above) to the host on which the virtual machine is running. As described in detail in Section 3.9, “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" -- like a real COM port without a cable.

    • server <pipename>: On a Windows host, this tells 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 begin with \\.\pipe\.

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

    • client <pipename>: This operates just like server ..., except that the pipe (or local domain socket) is not created by VirtualBox, but assumed to exist already.

    • <devicename>: If, instead of the above, 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 look like /dev/ttyS0. This allows you to "wire" a real serial port to a virtual machine.

  • --audio none|null|oss: With this option, you can set whether the VM should have audio support.

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

  • --monitorcount <count>: This enables multi-monitor support; see Section 3.5, “Display settings”.

  • --usb on|off: This option enables or disables the VM's virtual USB controller; see Section 3.10.1, “USB settings” for details.

  • --usbehci on|off: This option enables or disables the VM's virtual USB 2.0 controller; see Section 3.10.1, “USB settings” for details.

8.7.4. Remote machine settings

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

  • --vrde on|off: With the VirtualBox graphical user interface, this enables or disables the VirtualBox remote desktop extension (VRDE) server. Note that if you are using VBoxHeadless (see Section 7.1.2, “VBoxHeadless, the remote desktop server”), VRDE is enabled by default.

  • --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 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.

  • --vrdeauthtype null|external|guest: This allows you to choose whether and how authorization will be performed; see Section 7.1.5, “RDP authentication” for details.

  • --vrdemulticon on|off: This enables multiple connections to the same VRDE server, if the server supports this feature; see Section 7.1.7, “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 (this is the default setting), a new connection will not be accepted if there is already a client connected to the server.

  • --vrdevideochannel on|off: This enables video redirection, if it is supported by the VRDE server; see Section 7.1.9, “VRDP video redirection”.

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

8.7.5. Teleporting settings

With the following commands for VBoxManage modifyvm you can configure a machine to be a target for teleporting. See Section 7.2, “Teleporting” for an introduction.

  • --teleporter on|off: With this setting you turn on or off whether a machine waits for a teleporting request to come in on the network when it is started. If "on", when the machine is started, it does not boot the virtual machine as it would normally; instead, it then waits for a teleporting request to come in on the port and address listed with the next two parameters.

  • --teleporterport <port>, --teleporteraddress <address>: these must be used with --teleporter and tell the virtual machine on which port and address it should listen for a teleporting request from another virtual machine. <port> can be any free TCP/IP port number (e.g. 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 argument is given, then the teleporting request will only succeed if the source machine specifies the same password as the one given with this command.

    Note

    Currently, the password is stored without encryption (i.e. in clear text) in the XML machine configuration file.

  • --cpuid <leaf> <eax> <ebx> <ecx> <edx>: Advanced users can use this command before a teleporting operation to restrict the virtual CPU capabilities that 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; please refer to the AMD or Intel processor manuals.