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”).
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”.
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).
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.
--natpf<1-N>
[<name>],tcp|udp,[<hostip>],<hostport>,[<guestip>],
<guestport>
: This option defines a NAT
port-forwarding rule (please see Section 6.3.1, “Configuring port forwarding with NAT”
for details).
--natpf<1-N> delete
<name>
: This option deletes a NAT
port-forwarding rule (please see Section 6.3.1, “Configuring port forwarding with NAT”
for details).
--nattftpprefix<1-N>
<prefix>
: This option defines a prefix
for the built-in TFTP server, i.e. where the boot file is
located (please see Section 6.3.2, “PXE booting with NAT” and Section 9.10.2, “Configuring the boot server (next server) of a NAT network
interface” for details).
--nattftpfile<1-N>
<bootfile>
: This option defines the TFT
boot file (please see Section 9.10.2, “Configuring the boot server (next server) of a NAT network
interface” for
details).
--nattftpserver<1-N>
<tftpserver>
: This option defines the
TFTP server address to boot from (please see Section 9.10.2, “Configuring the boot server (next server) of a NAT network
interface” for details).
--natdnspassdomain<1-N>
on|off
: This option specifies whether the
built-in DHCP server passes the domain name for network name
resolution.
--natdnsproxy<1-N>
on|off
: This option makes the NAT engine proxy
all guest DNS requests to the host's DNS servers (please see
Section 9.10.5, “Enabling DNS proxy in NAT mode” for details).
--natdnshostresolver<1-N>
on|off
: This option makes the NAT engine use
the host's resolver mechanisms to handle DNS requests (please
see Section 9.10.5, “Enabling DNS proxy in NAT mode” for details).
--natnatsettings<1-N>
[<mtu>],[<socksnd>],[<sockrcv>],[<tcpsnd>],
[<tcprcv>]
: This option controls several
NAT settings (please see Section 9.10.3, “Tuning TCP/IP buffers for NAT” for
details).
--nataliasmode<1-N>
default|[log],[proxyonly],[sameports]
: This
option defines behaviour of NAT engine core: log - enables
logging, proxyonly - switches of aliasing mode makes NAT
transparent, sameports enforces NAT engine to send packets via
the same port as they originated on, default - disable all
mentioned modes above . (please see Section 9.10.7, “Configuring aliasing of the NAT engine” for details).
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.
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”.
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.
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.