diff options
Diffstat (limited to 'doc/manual/en_US/man_VBoxManage-modifyvm.xml')
| -rw-r--r-- | doc/manual/en_US/man_VBoxManage-modifyvm.xml | 2818 |
1 files changed, 2818 insertions, 0 deletions
diff --git a/doc/manual/en_US/man_VBoxManage-modifyvm.xml b/doc/manual/en_US/man_VBoxManage-modifyvm.xml new file mode 100644 index 00000000..2e3b4ffe --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-modifyvm.xml @@ -0,0 +1,2818 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifyvm +--> +<!-- + Copyright (C) 2006-2022 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifyvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-11 01:49:16 +0100 (Wed, 11 Jan 2023) $</pubdate> + <title>VBoxManage modifyvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifyvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifyvm</refname> + <refpurpose>Change settings for a virtual machine that is stopped</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-general"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--name=<replaceable>name</replaceable></arg> + <arg>--groups= <arg choice="plain"><replaceable>group</replaceable> [,<replaceable>group</replaceable>...]</arg></arg> + <arg>--description=<replaceable>description</replaceable></arg> + <arg>--os-type=<replaceable>OS-type</replaceable></arg> + <arg>--icon-file=<replaceable>filename</replaceable></arg> + <arg>--memory=<replaceable>size-in-MB</replaceable></arg> + <arg>--page-fusion=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vram=<replaceable>size-in-MB</replaceable></arg> + <arg>--acpi=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ioapic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hardware-uuid=<replaceable>UUID</replaceable></arg> + <arg>--cpus=<replaceable>CPU-count</replaceable></arg> + <arg>--cpu-hotplug=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--plug-cpu=<replaceable>CPU-ID</replaceable></arg> + <arg>--unplug-cpu=<replaceable>CPU-ID</replaceable></arg> + <arg>--cpu-execution-cap=<replaceable>number</replaceable></arg> + <arg>--pae=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--long-mode=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ibpb-on-vm-exit=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ibpb-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--spec-ctrl=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--l1d-flush-on-sched=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--l1d-flush-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--mds-clear-on-sched=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--mds-clear-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--cpu-profile=<group choice="plain"> + <arg choice="plain">host</arg> + <arg choice="plain">Intel 8086</arg> + <arg choice="plain">Intel 80286</arg> + <arg choice="plain">Intel 80386</arg> + </group></arg> + <arg>--hpet=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hwvirtex=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--triple-fault-reset=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--apic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--x2apic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--paravirt-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">default</arg> + <arg choice="plain">legacy</arg> + <arg choice="plain">minimal</arg> + <arg choice="plain">hyperv</arg> + <arg choice="plain">kvm</arg> + </group></arg> + <arg>--paravirt-debug= <arg choice="plain"><replaceable>key</replaceable>=<replaceable>value</replaceable> [,<replaceable>key</replaceable>=<replaceable>value</replaceable>...]</arg></arg> + <arg>--nested-paging=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--large-pages=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vtx-vpid=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vtx-ux=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nested-hw-virt=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--virt-vmsave-vmload=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--accelerate-3d=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--accelerate-2d-video=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--chipset=<group choice="plain"> + <arg choice="plain">ich9</arg> + <arg choice="plain">piix3</arg> + </group></arg> + <arg>--iommu=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">automatic</arg> + <arg choice="plain">amd</arg> + <arg choice="plain">intel</arg> + </group></arg> + <arg>--tpm-type=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">1.2</arg> + <arg choice="plain">2.0</arg> + <arg choice="plain">host</arg> + <arg choice="plain">swtpm</arg> + </group></arg> + <arg>--tpm-location=<group choice="plain"> + <arg choice="plain"><replaceable>location</replaceable></arg> + </group></arg> + <arg>--bios-logo-fade-in=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--bios-logo-fade-out=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--bios-logo-display-time=<replaceable>msec</replaceable></arg> + <arg>--bios-logo-image-path=<replaceable>pathname</replaceable></arg> + <arg>--bios-boot-menu=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">menuonly</arg> + <arg choice="plain">messageandmenu</arg> + </group></arg> + <arg>--bios-apic=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">apic</arg> + <arg choice="plain">x2apic</arg> + </group></arg> + <arg>--bios-system-time-offset=<replaceable>msec</replaceable></arg> + <arg>--bios-pxe-debug=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--system-uuid-le=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--boot<replaceable>X</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">floppy</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">disk</arg> + <arg choice="plain">net</arg> + </group></arg> + <arg>--rtc-use-utc=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--graphicscontroller=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">vboxvga</arg> + <arg choice="plain">vmsvga</arg> + <arg choice="plain">vboxsvga</arg> + </group></arg> + <arg>--snapshot-folder=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>pathname</replaceable></arg> + </group></arg> + <arg>--firmware=<group choice="plain"> + <arg choice="plain">bios</arg> + <arg choice="plain">efi</arg> + <arg choice="plain">efi32</arg> + <arg choice="plain">efi64</arg> + </group></arg> + <arg>--guest-memory-balloon=<replaceable>size-in-MB</replaceable></arg> + <arg>--default-frontend=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> +<!-- There are currently undocumented options --iocache and +--iocachesize which are scheduled for removal. Not worth spending +time on documenting it. --> + <arg>--vm-process-priority=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain">flat</arg> + <arg choice="plain">low</arg> + <arg choice="plain">normal</arg> + <arg choice="plain">high</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--nic<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">null</arg> + <arg choice="plain">nat</arg> + <arg choice="plain">bridged</arg> + <arg choice="plain">intnet</arg> + <arg choice="plain">hostonly</arg> + <arg choice="plain">hostonlynet</arg> + <arg choice="plain">generic</arg> + <arg choice="plain">natnetwork</arg> + <arg choice="plain">cloud</arg> + </group></arg> + <arg>--nic-type<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">Am79C970A</arg> + <arg choice="plain">Am79C973</arg> + <arg choice="plain">82540EM</arg> + <arg choice="plain">82543GC</arg> + <arg choice="plain">82545EM</arg> + <arg choice="plain">virtio</arg> + </group></arg> + <arg>--cable-connected<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nic-trace<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nic-trace-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></arg> + <arg>--nic-property<replaceable>N</replaceable>=<replaceable>name</replaceable>= <arg><replaceable>value</replaceable></arg></arg> + <arg>--nic-speed<replaceable>N</replaceable>=<replaceable>kbps</replaceable></arg> + <arg>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>priority</replaceable></arg> + <arg>--nic-promisc<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">deny</arg> + <arg choice="plain">allow-vms</arg> + <arg choice="plain">allow-all</arg> + </group></arg> + <arg>--nic-bandwidth-group<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--bridge-adapter<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--cloud-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--host-only-adapter<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--host-only-net<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--intnet<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--nat-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>driver-name</replaceable></arg> + <arg>--mac-address<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">auto</arg> + <arg choice="plain"><replaceable>MAC-address</replaceable></arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking-nat"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--nat-net<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain"><replaceable>network</replaceable></arg> + <arg choice="plain">default</arg> + </group></arg> + <arg>--nat-pf<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">[<replaceable>rule-name</replaceable>],tcp</arg> + <arg choice="plain">udp,[<replaceable>host-IP</replaceable>],<replaceable>hostport</replaceable>,[<replaceable>guest-IP</replaceable>],<replaceable>guestport</replaceable></arg> + </group></arg> + <arg>--nat-pf<replaceable>N</replaceable>=delete=<replaceable>rule-name</replaceable></arg> + <arg>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>prefix</replaceable></arg> + <arg>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></arg> + <arg>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></arg> + <arg>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></arg> + <arg>--nat-dns-pass-domain<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-dns-proxy<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-dns-host-resolver<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-localhostreachable<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>socksnd</replaceable>],[<replaceable>sockrcv</replaceable>],[<replaceable>tcpsnd</replaceable>],[<replaceable>tcprcv</replaceable>]</arg> + <arg>--nat-alias-mode<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain">[log],[proxyonly],[sameports]</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-other-hardware"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--mouse=<group choice="plain"> + <arg choice="plain">ps2</arg> + <arg choice="plain">usb</arg> + <arg choice="plain">usbtablet</arg> + <arg choice="plain">usbmultitouch</arg> + <arg choice="plain">usbmtscreenpluspad</arg> + </group></arg> + <arg>--keyboard=<group choice="plain"> + <arg choice="plain">ps2</arg> + <arg choice="plain">usb</arg> + </group></arg> + <arg>--uart<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">off</arg> + <arg choice="plain"><replaceable>IO-base</replaceable> <replaceable>IRQ</replaceable></arg> + </group></arg> + <arg>--uart-mode<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">disconnected</arg> + <arg choice="plain">server <replaceable>pipe</replaceable></arg> + <arg choice="plain">client <replaceable>pipe</replaceable></arg> + <arg choice="plain">tcpserver <replaceable>port</replaceable></arg> + <arg choice="plain">tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg> + <arg choice="plain">file <replaceable>filename</replaceable></arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--uart-type<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">16450</arg> + <arg choice="plain">16550A</arg> + <arg choice="plain">16750</arg> + </group></arg> + <arg>--lpt-mode<replaceable>N</replaceable>=<replaceable>device-name</replaceable></arg> + <arg>--lpt<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">off</arg> + <arg choice="plain"><replaceable>IO-base</replaceable> <replaceable>IRQ</replaceable></arg> + </group></arg> + <arg>--audio-controller=<group choice="plain"> + <arg choice="plain">ac97</arg> + <arg choice="plain">hda</arg> + <arg choice="plain">sb16</arg> + </group></arg> + <arg>--audio-codec=<group choice="plain"> + <arg choice="plain">stac9700</arg> + <arg choice="plain">ad1980</arg> + <arg choice="plain">stac9221</arg> + <arg choice="plain">sb16</arg> + </group></arg> + <arg>--audio-driver=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">default</arg> + <arg choice="plain">null</arg> + <arg choice="plain">dsound</arg> + <arg choice="plain">was</arg> + <arg choice="plain">oss</arg> + <arg choice="plain">alsa</arg> + <arg choice="plain">pulse</arg> + <arg choice="plain">coreaudio</arg> + </group></arg> + <arg>--audio-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--audio-in=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--audio-out=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--clipboard-mode=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group></arg> +<!-- There is a currently undocumented option --clipboard-file-transfers. +The implementation is not finished, so postpone documenting until it +actually is ready for users. --> + <arg>--drag-and-drop=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group></arg> + <arg>--monitor-count=<replaceable>number</replaceable></arg> + <arg>--usb-ehci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-ohci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-xhci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-rename=<replaceable>old-name</replaceable> <replaceable>new-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-recording"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--recording=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--recording-screens=<group choice="plain"> + <arg choice="plain">all</arg> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...]</arg> + </group></arg> + <arg>--recording-file=<replaceable>filename</replaceable></arg> + <arg>--recording-max-size=<replaceable>MB</replaceable></arg> + <arg>--recording-max-time=<replaceable>msec</replaceable></arg> + <arg>--recording-opts= <arg choice="plain"><replaceable>key</replaceable>=<replaceable>value</replaceable>[,<replaceable>key</replaceable>=<replaceable>value</replaceable>...]</arg></arg> + <arg>--recording-video-fps=<replaceable>fps</replaceable></arg> + <arg>--recording-video-rate=<replaceable>rate</replaceable></arg> + <arg>--recording-video-res=<replaceable>width</replaceable> <replaceable>height</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-vrde"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--vrde=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-property=<replaceable>property-name</replaceable>= <arg><replaceable>property-value</replaceable></arg></arg> + <arg>--vrde-extpack=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--vrde-port=<replaceable>port</replaceable></arg> + <arg>--vrde-address=<replaceable>hostip</replaceable></arg> + <arg>--vrde-auth-type=<group choice="plain"> + <arg choice="plain">null</arg> + <arg choice="plain">external</arg> + <arg choice="plain">guest</arg> + </group></arg> + <arg>--vrde-auth-library=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--vrde-multi-con=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-reuse-con=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-video-channel=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-video-channel-quality=<replaceable>percent</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-teleport"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--teleporter=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--teleporter-port=<replaceable>port</replaceable></arg> + <arg>--teleporter-address=<group choice="plain"> + <arg choice="plain"><replaceable>address</replaceable></arg> + <arg choice="plain">empty</arg> + </group></arg> + <arg>--teleporter-password=<replaceable>password</replaceable></arg> + <arg>--teleporter-password-file=<group choice="plain"> + <arg choice="plain"><replaceable>filename</replaceable></arg> + <arg choice="plain">stdin</arg> + </group></arg> + <arg>--cpuid-portability-level=<replaceable>level</replaceable></arg> + <arg>--cpuid-set=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg> <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></arg> + <arg>--cpuid-remove=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg></arg> + <arg>--cpuid-remove-all</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-debugging"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--tracing-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--tracing-config=<replaceable>string</replaceable></arg> + <arg>--tracing-allow-vm-access=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-usbcardreader"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--usb-card-reader=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-autostart"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--autostart-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--autostart-delay=<replaceable>seconds</replaceable></arg> +<!-- There is a currently undocumented option --autostop-type. +Most autostart service implementations either ignore it or rely it is +left unchanged due to otherwise running into timeouts established by the +host OS, defeating the purpose. Not worth spending time on documenting +it unless this changes. --> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-guest-debug"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--guest-debug-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">native</arg> + <arg choice="plain">gdb</arg> + <arg choice="plain">kd</arg> + </group></arg> + <arg>--guest-debug-io-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">tcp</arg> + <arg choice="plain">udp</arg> + <arg choice="plain">ipc</arg> + </group></arg> + <arg>--guest-debug-address=<group choice="plain"> + <arg choice="plain"><replaceable>IP-Address</replaceable></arg> + <arg choice="plain"><replaceable>path</replaceable></arg> + </group></arg> + <arg>--guest-debug-port=<replaceable>port</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-pcipassthrough"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--pci-attach=<replaceable>host-PCI-address</replaceable><arg>@<replaceable>guest-PCI-bus-address</replaceable></arg></arg> + <arg>--pci-detach=<replaceable>host-PCI-address</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-testing"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--testing-enabled=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg> + <arg>--testing-mmio=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg> + <arg>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>value</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage modifyvm</command> command enables you to + change the properties of a registered virtual machine (VM) that is + not running. + </para> + <para> + Most of these properties correspond to the VM settings that are + shown in each VM's <emphasis role="bold">Settings</emphasis> + dialog in the VirtualBox Manager. See + <xref linkend="BasicConcepts" />. However, some settings can only + be viewed and managed with the <command>VBoxManage</command> + command. + </para> + <para> + You can use the <command>VBoxManage modifyvm</command> command to + change VM settings only when the VM is powered off. The VM cannot + be running or in saved state when you use this command. + </para> + <para> + You can use the <command>VBoxManage controlvm</command> command to + dynamically change some VM machine settings while the VM is + running. See <xref linkend="vboxmanage-controlvm" />. + </para> + <refsect2 id="vboxmanage-modifyvm-general"> + <title>General Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify general information + about your VM. + </para> + <para> + The <command>VBoxManage modifyvm</command> command supports the + following options: + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>vmname</replaceable></option></term> + <listitem><para> + Changes the name of the VM and its related internal VM + files. See <xref linkend="vboxmanage-createvm"/>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--groups=<replaceable>group</replaceable></option></term> + <listitem><para> + Changes the group membership of a VM. Group names always + begin with a slash character (<literal>/</literal>) and + can be nested. By default, VMs are members of the + <literal>/</literal> group. A VM can be member of multiple + groups, but its primary group determines the directory + structure where the internal VM files are placed by default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>desc</replaceable></option></term> + <listitem><para> + Changes the optional VM description. Use a description to + record details about the VM in a meaningful way. The GUI + interprets HTML markup while the <command>VBoxManage + modifyvm</command> command enables you include arbitrary + strings that can contain multiple lines. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--os-type=<replaceable>OS-type</replaceable></option></term> + <listitem><para> + Specifies the guest operating system (OS) information for + the VM. Use the <command>VBoxManage list ostypes</command> + command to view the OS type identifiers. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--icon-file=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the path to the VM icon file in PNG format + on the host system. The icon is shown in the VM manager + UI and when running the VM with UI. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--memory=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifies the amount of host system RAM to allocate to the + VM. The size is in MB. See + <xref linkend="create-vm-wizard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--page-fusion=on | off</option></term> + <listitem><para> + Enables or disables the Page Fusion feature, which is + disabled by default. Use the Page Fusion feature to + minimize the memory duplication between VMs that have + similar configurations and that run on the same host + system. See <xref linkend="guestadd-pagefusion" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vram=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifies the amount of RAM to allocate to the virtual + graphics card. See <xref linkend="settings-display" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--acpi=on | off</option></term> + <listitem><para> + Determines whether the VM has ACPI support. See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ioapic=on | off</option></term> + <listitem><para> + Determines whether the VM has I/O APIC support. See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hardware-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) to + present to the guest VM in memory tables (DMI/SMBIOS), + hardware, and VM properties. By default this hardware UUID + is the same as the VM UUID. Cloning a VM and the teleporting + feature automatically preserve the hardware UUID value. + Likewise for Virtual Appliance export and import, but only + if both operations are done by &product-name;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpus=<replaceable>CPU-count</replaceable></option></term> + <listitem><para> + Specifies the number of virtual CPUs to assign to the VM. + See <xref linkend="settings-processor" />. + </para><para> + If CPU hot-plugging is enabled, this option specifies the + maximum number of virtual CPUs that can be plugged into + the VMs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu-hotplug=on | off</option></term> + <listitem><para> + Enables or disables CPU hot-plugging. When enabled, you + can dynamically add virtual CPUs to a VM or remove virtual + CPUs from a VM. See <xref linkend="cpuhotplug" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--plug-cpu=<replaceable>CPU-ID</replaceable></option></term> + <listitem><para> + Adds a virtual CPU to the VM. + <replaceable>CPU-ID</replaceable> is the index of the + virtual CPU to add. A valid index value is a number from + <literal>0</literal> to the maximum number of CPUs that + you configured by using the <option>--cpus</option> + option. + </para><para> + Only use this option if CPU hot-plugging is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unplug-cpu=<replaceable>CPU-ID</replaceable></option></term> + <listitem><para> + Removes a virtual CPU from the VM. + <replaceable>CPU-ID</replaceable> is the index of the + virtual CPU to remove. A valid index value is a number + from <literal>1</literal> to the maximum number of CPUs + that you configured by using the <option>--cpus</option> + option. + </para><para> + Only use this option if CPU hot-plugging is enabled. + </para><para> + Note that you cannot remove CPU 0. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuexectioncap=<replaceable>percentage</replaceable></option></term> + <listitem> + <para> + Specifies how much CPU time a virtual CPU can use. A valid + value is from <literal>1</literal> to + <literal>100</literal>. A value of 50 indicates that a + single virtual CPU can use up to 50% of a single host CPU. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--pae=on | off</option></term> + <listitem><para> + Enables or disables physical address extension (PAE). See + <xref linkend="settings-processor" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--long-mode=on | off</option></term> + <listitem><para> + Enables or disables long mode. See + <xref linkend="settings-processor" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ibpb-on-vm-exit=on | off</option></term> + <listitem><para> + Enables use of Indirect Branch Prediction Barrier (IBPB) + on every VM exit. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ibpb-on-vm-entry=on | off</option></term> + <listitem><para> + Enables use of Indirect Branch Prediction Barrier (IBPB) + on every VM entry. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--spec-ctrl=on | off</option></term> + <listitem><para> + Enables or disables the exposure of speculation control + interfaces to the guest VM. These interfaces must be + available on the host system. + </para><para> + Depending on the host CPU and the workload, enabling + speculation control might significantly reduce + performance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--l1d-flush-on-sched=on | off</option></term> + <listitem><para> + Enables or disables level 1 data cache flushing when a + thread is scheduled to execute guest code. See + <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--l1d-flush-on-vm-entry=on | off</option></term> + <listitem><para> + Enables or disables level 1 data cache flushing on every + VM entry. See <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mds-clear-on-sched=on | off</option></term> + <listitem><para> + Enables CPU buffer clearing when a thread is scheduled to + execute guest code. See + <xref linkend="sec-rec-cve-2018-12126-et-al" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mds-clear-on-vm-entry=on | off</option></term> + <listitem><para> + Enables CPU buffer clearing on every VM entry. See + <xref linkend="sec-rec-cve-2018-12126-et-al" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu-profile=host | Intel 8086 | Intel 80286 | Intel 80386</option></term> + <listitem><para> + Specifies the profile to use for guest CPU emulation. + Specify a value that is based on the host system CPU + (<literal>host</literal>) or one of the following older + Intel micro-architectures: <literal>8086</literal>, + <literal>80286</literal>, or <literal>80386</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hpet=on | off</option></term> + <listitem><para> + Enables or disables a High Precision Event Timer (HPET) + that can replace a legacy system timer. This feature is + disabled by default. Note HPET is supported on Windows + versions starting with Vista. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hwvirtex=on | off</option></term> + <listitem><para> + Enables or disables the use of hardware virtualization + extensions in the processor of the host system. Such + extensions are Intel VT-x or AMD-V. See + <xref linkend="hwvirt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--triple-fault-reset=on | off</option></term> + <listitem><para> + Enables or disables the resetting of the guest VM instead + of triggering a Guru Meditation. Some guest VMs raise a + triple fault to reset the CPU, so sometimes resetting the + guest VM is the best outcome. This option only applies to + guests that do not use symmetric multiprocessing (SMP). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--apic=on | off</option></term> + <listitem><para> + 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 <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--x2apic=on | off</option></term> + <listitem><para> + 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 + virtualized environments. This feature is enabled by + default. + </para><para> + Disable this feature when the OS that runs on a host + system or a guest VM is incompatible with CPU x2APIC. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--paravirt-provider=none | default | legacy | minimal | hyperv | kvm</option></term> + <listitem><para> + Specifies one of the following paravirtualization + interfaces to provide to the guest OS: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> does not expose any + paravirtualization interface. + </para></listitem> + <listitem><para> + <literal>default</literal> selects the appropriate + interface based on the guest OS type when starting the + VM. This is the default value used when creating new + VMs. + </para></listitem> + <listitem><para> + <literal>legacy</literal> selects a paravirtual + interface for VMs that were created by older + &product-name; versions. + </para></listitem> + <listitem><para> + <literal>minimal</literal> is required for Mac OS X + guest VMs. + </para></listitem> + <listitem><para> + <literal>kvm</literal> is recommended for Linux guest + VMs. See <xref linkend="gimproviders" />. + </para></listitem> + <listitem><para> + <literal>hyperv</literal> is recommended for Windows + guest VMs. See <xref linkend="gimproviders" />. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--paravirt-debug=<replaceable>property</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies debugging properties that are specific to the + paravirtualization provider configured for the specified + VM. See <xref linkend="gimdebug" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nested-paging=on | off</option></term> + <listitem><para> + Enables or disables the nested paging feature in the + processor of the host system. This option is available + only when hardware virtualization is enabled. See + <xref linkend="hwvirt" /> and + <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--large-pages=on | off</option></term> + <listitem><para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vtx-vpid=on | off</option></term> + <listitem><para> + Enables or disables the use of the tagged TLB (VPID) + feature in the processor of your host system. See + <xref linkend="hwvirt" />. This option is available only + when hardware virtualization is enabled on Intel VT-x. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vtx-ux=on | off</option></term> + <listitem><para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nested-hw-virt=on | off</option></term> + <listitem><para> + Enables or disables nested virtualization. Enabling makes + hardware virtualization features available to the VM. See + <xref linkend="nested-virt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--virt-vmsave-vmload=on | off</option></term> + <listitem><para> + If hardware virtualization is enabled and the host has an + AMD CPU, this setting enables or 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. + <xref linkend="nested-virt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accelerated3d=on | off</option></term> + <listitem><para> + Enables or disables hardware 3D acceleration for the + graphics adapter variants which support it. This option + has an effect only when the Guest Additions are installed. + See <xref linkend="guestadd-3d" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accelerated2dvideo=on | off</option></term> + <listitem><para> + 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 + <xref linkend="guestadd-2d" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--chipset=piix3 | ich9</option></term> + <listitem><para> + Specify the Intel chipset for &product-name; to emulate. + The default value is the Intel PIIX3 chipset + (<literal>piix3</literal>). + </para><para> + Change this value only if you need to relax some of the + chipset constraints. See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--iommu=none | automatic | amd | intel</option></term> + <listitem><para> + Specifies the IOMMU type for &product-name; to emulate. + Both Intel and AMD IOMMU emulation currently require the + use of the Intel ICH9 chipset (see + <option>--chipset</option> option). + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – No IOMMU is present + and is the default value. + </para></listitem> + <listitem><para> + <literal>automatic</literal> – An IOMMU is + present but its type is automatically chosen to match + the host CPU vendor when the VM is powered on. + </para></listitem> + <listitem><para> + <literal>amd</literal> – An AMD IOMMU is + present. + </para></listitem> + <listitem><para> + <literal>intel</literal> – An Intel IOMMU is + present. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--tpm-type=none | 1.2 | 2.0 | host | swtpm</option></term> + <listitem><para> + Specifies the TPM type for &product-name; to emulate. + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – No TPM is present + and is the default value. + </para></listitem> + <listitem><para> + <literal>1.2</literal> – A TPM conforming to the TCG specification + version 1.2 is present. + </para></listitem> + <listitem><para> + <literal>2.0</literal> – A TPM conforming to the TCG specification + version 2.0 is present. + </para></listitem> + <listitem><para> + <literal>host</literal> – The host TPM is passed through to the guest. + May not be available on all supported host platforms. + </para></listitem> + <listitem><para> + <literal>swtpm</literal> – The VM connects to an external TPM emulation + compliant to swtpm. Requires to set the TPM location to connect to (see + <option>--tpm-location</option> option). + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-fade-in=on | off</option></term> + <listitem><para> + Specifies whether the BIOS logo fades in on VM startup. By + default, an &product-name; logo is shown. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-fade-out=on | off</option></term> + <listitem><para> + Specifies whether the BIOS logo fades out on VM startup. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-display-time=<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the amount of time in milliseconds that the BIOS + logo is visible. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-image-path=<replaceable>pathname</replaceable></option></term> + <listitem><para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-boot-menu=disabled | menuonly | messageandmenu</option></term> + <listitem><para> + Specifies whether the BIOS permits you to select a + temporary boot device. Valid values are: + </para><itemizedlist> + <listitem><para> + <literal>disabled</literal> outputs the alternate boot + device message and permits you to select a temporary + boot device by pressing F12. + </para></listitem> + <listitem><para> + <literal>menuonly</literal> suppresses the alternate + boot device message, but permits you to select a + temporary boot device by pressing F12. + </para></listitem> + <listitem><para> + <literal>messageandmenu</literal> suppresses the + alternate boot device message and prevents you from + selecting a temporary boot device by pressing F12. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-apic=x2apic | apic | disabled</option></term> + <listitem><para> + Specifies the APIC level of the firmware. Valid values + are: <literal>x2apic</literal>, <literal>apic</literal>, + and <literal>disabled</literal>. When the value is + <literal>disabled</literal>, neither the + <literal>apic</literal> nor the <literal>x2apic</literal> + version of the firmware is used. + </para><para> + Note that if you specify the <literal>x2apic</literal> + value and x2APIC is unsupported by the virtual CPU, the + APIC level downgrades to <literal>apic</literal>, if + supported. Otherwise, the APIC level downgrades to + <literal>disabled</literal>. Similarly, if you specify the + <literal>apic</literal> value and APIC is unsupported by + the virtual CPU, the APIC level downgrades to + <literal>disabled</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-system-time-offset=<replaceable>msec</replaceable></option></term> + <listitem><para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-pxe-debug=on | off</option></term> + <listitem><para> + Enables or disables additional debugging output when using + the Intel PXE boot ROM. The debug output is written to the + release log file. See + <xref linkend="collect-debug-info" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--system-uuid-le=on | off</option></term> + <listitem><para> + Enables or disables representing the system UUID in little + endian form. The default value is <literal>on</literal> for + new VMs. For old VMs the setting is <literal>off</literal> to + keep the content of the DMI/SMBIOS table unchanged, which can + be important for Windows license activation. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot<replaceable>N</replaceable>=none | floppy | dvd | disk | net</option></term> + <listitem><para> + 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 + <replaceable>N</replaceable> in the option name. + </para><para> + A value of 1 for <replaceable>N</replaceable> represents + the first boot device slot, and so on. + </para><para> + The device types are <literal>floppy</literal> for floppy + disks, <literal>dvd</literal> for DVDs or CDs, + <literal>disk</literal> for hard disks, and + <literal>net</literal> for a network device. A value of + <literal>none</literal> indicates that no boot device is + associated with the specified slot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--rtc-use-utc=on | off</option></term> + <listitem><para> + Specifies whether the real-time clock (RTC) uses + coordinated universal time (UTC). See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--graphicscontroller=none | vboxvga | vmsvga | vboxsvga</option></term> + <listitem><para> + Specifies the graphics controller type to use. See + <xref linkend="settings-screen" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--snapshot-folder=default | <replaceable>pathname</replaceable></option></term> + <listitem><para> + Specifies the name of the VM's snapshot storage folder. If + you specify <literal>default</literal>, the folder name is + <filename>Snapshots/</filename> in the machine folder. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--firmware=bios | efi | efi32 | efi64</option></term> + <listitem><para> + Specifies the firmware used to boot the VM. Valid values + are: <literal>bios</literal>, <literal>efi</literal>, + <literal>efi32</literal>, or <literal>efi64</literal>. Use + EFI values with care. + </para><para> + By default, BIOS firmware is used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-memory-balloon=<replaceable>size</replaceable></option></term> + <listitem><para> + 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 + <replaceable>size</replaceable> in megabytes. The default + value is <literal>0</literal> megabytes. See + <xref linkend="guestadd-balloon" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-frontend=default | <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the default frontend to use when starting the + specified VM. If you specify <literal>default</literal>, + the VM is shown in a window on the user's desktop. See + <xref linkend="vboxmanage-startvm" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vm-process-priority=default | flat | low | normal | high</option></term> + <listitem><para> + Specifies the priority scheme of the VM process to use + when starting the specified VM and while the VM runs. + </para><para> + The following valid values are: + </para><itemizedlist> + <listitem><para> + <literal>default</literal> – Default process + priority determined by the OS. + </para></listitem> + <listitem><para> + <literal>flat</literal> – Assumes a scheduling + policy which puts the process at the default priority + and with all threads at the same priority. + </para></listitem> + <listitem><para> + <literal>low</literal> – Assumes a scheduling + policy which puts the process mostly below the default + priority of the host OS. + </para></listitem> + <listitem><para> + <literal>normal</literal> – Assume a scheduling + policy which shares the CPU resources fairly with + other processes running with the default priority of + the host OS. + </para></listitem> + <listitem><para> + <literal>high</literal> – 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. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-networking"> + <title>Networking Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify networking on your + VM. With all these options, <replaceable>N</replaceable> is an + integer greater than zero that represents the particular virtual + network adapter to configure. + </para> + <variablelist> + <varlistentry> + <term><option>--nic<replaceable>N</replaceable>=none | null | nat | natnetwork | bridged | intnet | hostonly | generic</option></term> + <listitem><para> + Configures the network type used by each virtual network + card in the VM. + </para><para> + The following valid values correspond to the modes + described in <xref linkend="networkingmodes" />: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – No networking present + </para></listitem> + <listitem><para> + <literal>null</literal> – Not connected to the + host system + </para></listitem> + <listitem><para> + <literal>nat</literal> – Use network address + translation (NAT) + </para></listitem> + <listitem><para> + <literal>natnetwork</literal> – Use a NAT + network + </para></listitem> + <listitem><para> + <literal>bridged</literal> – Use bridged + networking + </para></listitem> + <listitem><para> + <literal>intnet</literal> – Use internal + networking + </para></listitem> + <listitem><para> + <literal>hostonly</literal> – Use host-only + networking + </para></listitem> + <listitem><para> + <literal>generic</literal> – Access rarely used + sub-modes + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-type<replaceable>N</replaceable>=Am79C970A | Am79C973 | 82540EM | 82543GC | 82545EM | virtio</option></term> + <listitem><para> + Identifies the type of networking hardware that + &product-name; presents to the guest VM for the specified + virtual network card. See <xref linkend="nichardware" />. + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>Am79C970A</literal> represents the AMD PCNet + PCI II. + </para></listitem> + <listitem><para> + <literal>Am79C973</literal> represents the AMD PCNet + FAST III, which is the default value. + </para></listitem> + <listitem><para> + <literal>82540EM</literal> represents the Intel + PRO/1000 MT Desktop. + </para></listitem> + <listitem><para> + <literal>82543GC</literal> represents the Intel + PRO/1000 T Server. + </para></listitem> + <listitem><para> + <literal>82545EM</literal> represents the Intel + PRO/1000 MT Server. + </para></listitem> + <listitem><para> + <literal>virtio</literal> represents a paravirtualized + network adapter. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--cable-connected<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-trace<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Enables or disables network tracing for the specified + virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-trace-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the file in which to write + trace log information. Use this option if network tracing + is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-property<replaceable>N</replaceable>=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Enables you to set property values and pass them to rarely + used network backends. To use this option, you must also + use the <option>--nic-generic-drv</option> option. + </para><para> + These properties are specific to the backend engine and + differ between the UDP Tunnel and the VDE backend drivers. + For property examples, see + <xref linkend="network_udp_tunnel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-speed<replaceable>N</replaceable>=<replaceable>kbps</replaceable></option></term> + <listitem><para> + 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 + <option>--nic</option> option to enable generic networking + for the specified virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>priority</replaceable></option></term> + <listitem><para> + 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 + <literal>0</literal> to <literal>4</literal>. Priority + <literal>0</literal>, which is the default value, is the + lowest priority. Priority <literal>1</literal> is the + highest priority, and priorities <literal>3</literal> and + <literal>4</literal> are lower. + </para><para> + This option has an effect only when using the Intel PXE + boot ROM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-promisc<replaceable>N</replaceable>=deny | allow-vms | allow-all</option></term> + <listitem><para> + 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: + </para><itemizedlist> + <listitem><para> + <literal>deny</literal> hides any traffic that is not + intended for the VM. This is the default value. + </para></listitem> + <listitem><para> + <literal>allow-vms</literal> hides all host traffic + from the VM, but allows the VM to see traffic to and + from other VMs. + </para></listitem> + <listitem><para> + <literal>allow-all</literal> allows the VM to see all + traffic. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-bandwidth-group<replaceable>N</replaceable>=none | <replaceable>name</replaceable></option></term> + <listitem><para> + Adds or removes a bandwidth group assignment to the + specified virtual network interface. Valid values are as + follows: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> removes any current bandwidth + group assignment from the specified virtual network + interface. + </para></listitem> + <listitem><para> + <replaceable>name</replaceable> adds a bandwidth group + assignment to the specified virtual network interface. + </para></listitem> + </itemizedlist><para> + See <xref linkend="network_bandwidth_limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bridge-adapter<replaceable>N</replaceable>=none | <replaceable>device-name</replaceable></option></term> + <listitem><para> + Specifies the host interface to use for the specified + virtual network interface. See + <xref linkend="network_bridged" />. Use this option only + if you used the <option>--nic</option> option to enable + bridged networking for the specified virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--host-only-adapter<replaceable>N</replaceable>=none | <replaceable>device-name</replaceable></option></term> + <listitem><para> + Specifies which host-only networking interface to use for + the specified virtual network interface. See + <xref linkend="network_hostonly" />. Use this option only + if you used the <option>--nic</option> option to enable + host-only networking for the specified virtual network + card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--intnet<replaceable>N</replaceable>=<replaceable>network-name</replaceable></option></term> + <listitem><para> + Specifies the name of the internal network. See + <xref linkend="network_internal" />. Use this option only + if you used the <option>--nic</option> option to enable + internal networking for the specified virtual network + card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></option></term> + <listitem><para> + Specifies the name of the NAT network to which this + adapter is connected. Use this option only if the + networking type is <literal>natnetwork</literal>, not + <literal>nat</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>backend-driver</replaceable></option></term> + <listitem><para> + Enables you to access rarely used networking sub-modes, + such as VDE networks and UDP Tunnel. Use this option only + if you used the <option>--nic</option> option to enable + generic networking for a virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mac-address<replaceable>N</replaceable>=auto | <replaceable>MAC-address</replaceable></option></term> + <listitem><para> + Specifies the MAC address of the specified network adapter + on the VM. By default, &product-name; assigns a random MAC + address to each network adapter at VM creation. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-networking-nat"> + <title>NAT Networking Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options use <replaceable>N</replaceable> to + specify the particular virtual network adapter to modify. + </para> + <variablelist> + <varlistentry> + <term><option>--nat-net<replaceable>N</replaceable>=default | <replaceable>network</replaceable></option></term> + <listitem><para> + Specifies the IP address range to use for this network. + See <xref linkend="changenat" />. Use this option only if + the networking type is <literal>nat</literal>, not + <literal>natnetwork</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-pf<replaceable>N</replaceable>=[<replaceable>name</replaceable>],tcp | udp,[<replaceable>host-IP</replaceable>],<replaceable>hostport</replaceable>,[<replaceable>guest-IP</replaceable>],<replaceable>guestport</replaceable></option></term> + <listitem><para> + Specifies the NAT port-forwarding rule to use. See + <xref linkend="natforward" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-pf<replaceable>N</replaceable>=delete <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the NAT port-forwarding rule to delete. See + <xref linkend="natforward" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>prefix</replaceable></option></term> + <listitem><para> + 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 <xref linkend="nat-tftp" /> and + <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>boot-file</replaceable></option></term> + <listitem><para> + Specifies the name of the TFT boot file. See + <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>tftp-server</replaceable></option></term> + <listitem><para> + Specifies the address of the TFTP server from which to + boot. See <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies an alternate IP address to which the NAT engine + binds. See <xref linkend="nat-adv-settings" />. By + default, &product-name;'s NAT engine routes TCP/IP packets + through the default interface assigned by the host's + TCP/IP stack. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-pass-domain<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the built-in DHCP server passes the + domain name for network name resolution. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-proxy<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the NAT engine is the proxy for all + guest DNS requests to the host system's DNS servers. See + <xref linkend="nat-adv-dns" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-host-resolver<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the NAT engine uses the host system's + resolver mechanisms to handle DNS requests. See + <xref linkend="nat-adv-dns" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-localhostreachable<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>socksnd</replaceable>],[<replaceable>sockrcv</replaceable>],[<replaceable>tcpsnd</replaceable>],[<replaceable>tcprcv</replaceable>]</option></term> + <listitem><para> + Specifies values for tuning NAT performance. See + <xref linkend="nat-adv-settings" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-alias-mode<replaceable>N</replaceable>=default | [log],[proxyonly],[sameports]</option></term> + <listitem><para> + Specifies the behavior of the NAT engine core as follows: + </para><itemizedlist> + <listitem><para> + <literal>log</literal> enables logging + </para></listitem> + <listitem><para> + <literal>proxyonly</literal> switches off aliasing + mode and makes NAT transparent + </para></listitem> + <listitem><para> + <literal>sameports</literal> enforces that the NAT + engine sends packets through the same port on which + they originated + </para></listitem> + <listitem><para> + <literal>default</literal> disables all aliasing modes + </para></listitem> + </itemizedlist><para> + For more information, see + <xref linkend="nat-adv-alias" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-other-hardware"> + <title>Other Hardware Settings</title> + <remark role="help-copy-synopsis"/> + <para> + 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. + </para> + <variablelist> + <varlistentry> + <term><option>--mouse=ps2 | usb | usbtablet | usbmultitouch | usbmtscreenpluspad</option></term> + <listitem><para> + Specifies the mode of the mouse to use in the VM. Valid + values are: <literal>ps2</literal>, + <literal>usb</literal>, <literal>usbtablet</literal>, + <literal>usbmultitouch</literal> and + <literal>usbmtscreenpluspad</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyboard=ps2 | usb</option></term> + <listitem><para> + Specifies the mode of the keyboard to use in the VM. Valid + values are: <literal>ps2</literal> and + <literal>usb</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart<replaceable>N</replaceable>=off | <replaceable>I/O-base</replaceable> <replaceable>IRQ</replaceable></option></term> + <listitem><para> + Configures virtual serial ports for the VM. + <replaceable>N</replaceable> represents the serial port to + modify. Valid values are <literal>off</literal> 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 <xref linkend="serialports" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart-mode<replaceable>N</replaceable>=<replaceable>mode</replaceable></option></term> + <listitem><para> + Specifies how &product-name; connects the specified + virtual serial port to the host system that runs the VM. + See <xref linkend="serialports" />. + </para><para> + Ensure that you first configure the virtual serial port by + using the + <option>--uart<replaceable>N</replaceable></option> + option. + </para><para> + Specify one of the following connection modes for each + port: + </para><itemizedlist> + <listitem><para> + <literal>disconnected</literal> 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. + </para></listitem> + <listitem><para> + <literal>server</literal> + <replaceable>pipe-name</replaceable> creates the + specified named pipe or local domain socket on the + host system and connects the virtual serial device to + it. + </para><para> + On a Windows host system, + <replaceable>pipe-name</replaceable> is a named pipe + that has a name that uses the following form: + <literal>\\.\pipe\<replaceable>pipe-name</replaceable></literal>. + </para><para> + On a Linux host system, + <replaceable>pipe-name</replaceable> is a local domain + socket. + </para></listitem> + <listitem><para> + <literal>client</literal> + <replaceable>pipe-name</replaceable> connects the + virtual serial device to the specified named pipe or + local domain socket. + </para><para> + Note that the named pipe or local domain socket must + already exist. + </para></listitem> + <listitem><para> + <literal>tcpserver</literal> + <replaceable>port</replaceable> creates a TCP socket + with the specified TCP port on the host system and + connects the virtual serial device to it. + </para><para> + For UNIX-like systems, use ports over 1024 for + non-root users. + </para></listitem> + <listitem><para> + <literal>tcpclient</literal> + <replaceable>hostname</replaceable>:<replaceable>port</replaceable> + connects the virtual serial device to the TCP socket. + </para><para> + Note that the TCP socket must already exist. + </para></listitem> + <listitem><para> + <literal>file</literal> + <replaceable>filename</replaceable> redirects the + serial port output to the specified raw file. Ensure + that <replaceable>filename</replaceable> is the + absolute path of the file on the host system. + </para></listitem> + <listitem><para> + <replaceable>device-name</replaceable>: specifies the + device name of a physical hardware serial port on the + specified host system to which the virtual serial port + connects. + </para><para> + Use this mode to connect a physical serial port to a + VM. + </para><para> + On a Windows host system, the device name is a COM + port such as <literal>COM1</literal>. On a Linux host + system, the device name is similar to + <filename>/dev/ttyS0</filename>. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart-type<replaceable>N</replaceable>=<replaceable>UART-type</replaceable></option></term> + <listitem><para> + Configures the UART type for the specified virtual serial + port (<replaceable>N</replaceable>). Valid values are + <literal>16450</literal>, <literal>16550A</literal>, and + <literal>16750</literal>. The default value is + <literal>16550A</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lpt-mode<replaceable>N</replaceable>=<replaceable>device-name</replaceable></option></term> + <listitem><para> + Specifies the device name of the parallel port to use. + </para><para> + For a Windows host system, use a device name such as + <command>lpt1</command>. For a Linux host system, use a + device name such as <filename>/dev/lp0</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lpt<replaceable>N</replaceable>=<replaceable>I/O-base</replaceable> <replaceable>IRQ</replaceable></option></term> + <listitem><para> + Specifies the I/O base address and IRQ of the parallel + port. + </para><para> + You can view the I/O base address and IRQ that the VM uses + for the parallel port in the Device Manager. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-controller=<replaceable>controller-type</replaceable></option></term> + <listitem><para> + Specifies the audio controller to be used with the VM. + Valid audio controller type values are: + <literal>ac97</literal>, <literal>hda</literal>, and + <literal>sb16</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-codec=<replaceable>codec-type</replaceable></option></term> + <listitem><para> + Specifies the audio codec to be used with the VM. Valid + audio codec type values are: <literal>stac9700</literal>, + <literal>ad1980</literal>, <literal>stac9221</literal>, + and <literal>sb16</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-driver=<replaceable>type</replaceable></option></term> + <listitem><para> + Specifies whether which audio driver (backend) to use. + <literal>none</literal>, <literal>default</literal>, + <literal>null</literal>, <literal>dsound</literal>, + <literal>was</literal>, <literal>oss</literal>, + <literal>alsa</literal>, <literal>pulse</literal>, and + <literal>coreaudio</literal>. + </para><para> + Note that the audio driver are dependent on the host + operating system. Use the <command>VBoxManage + modifyvm</command> command usage output to determine the + supported audio types for your host system. + </para> + <para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-enabled=on|off</option></term> + <listitem><para> + Specifies whether to enable or disable audio for the VM. + </para> + <para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-in=on|off</option></term> + <listitem><para> + Specifies whether to enable or disable audio capture from + the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-out=on|off</option></term> + <listitem><para> + Specifies whether to enable or disable audio playback from + the guest VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clipboard-mode=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies how to share the guest VM or host system OS's + clipboard with the host system or guest VM, respectively. + Valid values are: <literal>disabled</literal>, + <literal>hosttoguest</literal>, + <literal>guesttohost</literal>, and + <literal>bidirectional</literal>. See + <xref linkend="generalsettings" />. + </para><para> + The clipboard feature is available only if you have the + Guest Additions be installed in the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--drag-and-drop=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies how to use the drag and drop feature between the + host system and the VM. Valid values are: + <literal>disabled</literal>, + <literal>hosttoguest</literal>, + <literal>guesttohost</literal>, and + <literal>bidirectional</literal>. See + <xref linkend="guestadd-dnd" />. + </para><para> + The drag and drop feature is available only if you have + the Guest Additions be installed in the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--monitor-count=<replaceable>count</replaceable></option></term> + <listitem><para> + Enables you to configure multiple monitors. See + <xref linkend="settings-display" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-ohci=on | off</option></term> + <listitem><para> + Enables or disables the VM's virtual USB 1.1 controller. + See <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-ehci=on | off</option></term> + <listitem><para> + Enables or disables the VM's virtual USB 2.0 controller. + See <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-xhci=on | off</option></term> + <listitem><para> + Enables or disables the VM's virtual USB 3.0 controller. + This is the most efficient option if the VM supports it. + See <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-rename=<replaceable>old-name</replaceable> <replaceable>new-name</replaceable></option></term> + <listitem><para> + Rename's the VM's virtual USB controller from + <replaceable>old-name</replaceable> to + <replaceable>new-name</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-recording"> + <title>Recording Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify settings for video + recording, audio recording, or both. + </para> + <variablelist> + <varlistentry> + <term><option>--recording=on | off</option></term> + <listitem><para> + Enables or disables the recording of a VM session into a + WebM or VP8 file. When set to <literal>on</literal>, + recording begins when the VM session starts. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-screens=all | none | <replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...</option></term> + <listitem><para> + Enables you to specify the VM screens to record. The + recording for each screen is output to its own file. Valid + values are: <literal>all</literal>, which records all + screens, <literal>none</literal>, which records no + screens, or one or more specified screens. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-file=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the name of the file in which to save the + recording. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-max-size=<replaceable>MB</replaceable></option></term> + <listitem><para> + Specifies the maximum size of the recorded video file in + megabytes. When the file reaches the specified size, + recording stops. If the value is <literal>0</literal>, + recording continues until you manually stop recording. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-max-time=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the maximum amount of time to record in seconds. + When the specified time elapses, recording stops. If the + value is <literal>0</literal>, recording continues until + you manually stop recording. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-opts=<replaceable>keyword</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies additional video-recording properties as a + comma-separated property keyword-value list. For example, + <literal>foo=bar,a=b</literal>. + </para><para> + Only use this option if you are an advanced user. For + information about keywords, see the <citetitle>Oracle VM + VirtualBox Programming Guide and Reference</citetitle>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-fps=<replaceable>fps</replaceable></option></term> + <listitem><para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-rate=<replaceable>bit-rate</replaceable></option></term> + <listitem><para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-res=<replaceable>width</replaceable>x<replaceable>height</replaceable></option></term> + <listitem><para> + Specifies the video resolution (width and height) of the + recorded video in pixels. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-vrde"> + <title>Remote Machine Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify the VirtualBox Remote + Desktop Extension (VRDE) behavior. + </para> + <variablelist> + <varlistentry> + <term><option>--vrde=on | off</option></term> + <listitem><para> + Enables or disables the VRDE server. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=TCP/Ports=<replaceable>port</replaceable></option></term> + <listitem><para> + <replaceable>port</replaceable> is the port or port range + to which the VRDE server binds. The + <literal>default</literal> or <literal>0</literal> value + uses port <literal>3389</literal>, which is the standard + RDP port. + </para><para> + Also see the <option>--vrde-port</option> option + description. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=TCP/Address=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + <replaceable>IP-address</replaceable> 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. + </para><para> + Also see the <option>--vrde-address</option> option + description. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=VideoChannel/Enabled=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies whether the VRDP video channel is on or off. + <literal>1</literal> means <literal>on</literal> and + <literal>0</literal> means <literal>off</literal>. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Quality=<replaceable>value</replaceable></option></term> + <listitem><para> + 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 + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DownscaleProtection=<replaceable>value</replaceable></option></term> + <listitem><para> + Enables or disables the video downscale protection + feature. Valid values are <literal>1</literal> to enable + the feature and <literal>0</literal> to disable the + feature. + </para><para> + When this feature is enabled, &product-name; determines + whether to display the video: + </para><itemizedlist> + <listitem><para> + When the video size equals the size of the shadow + buffer, the video is considered to be full screen and + is displayed. + </para></listitem> + <listitem><para> + 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. + </para></listitem> + </itemizedlist><para> + When this feature is disabled, an attempt is always made + to display a video. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableDisplay=1</option></term> + <listitem><para> + Disables the display VRDE server feature. + </para><para> + To reenable a feature, assign an empty value. For example, + to reenable the display feature, specify the + <command>VBoxManage modifyvm + --vrde-property=Client/DisableDisplay=</command> command. + See <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableInput=1</option></term> + <listitem><para> + Disables the input VRDE server feature. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableAudio=1</option></term> + <listitem><para> + Disables the audio VRDE server feature. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableUSB=1</option></term> + <listitem><para> + Disables the USB VRDE server feature. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableClipboard=1</option></term> + <listitem><para> + Disables the clipboard VRDE server feature. To reenable + the feature, assign an empty value. See + <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableUpstreamAudio=1</option></term> + <listitem><para> + Disables the upstream audio VRDE server feature. To + reenable the feature, assign an empty value. See + <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableRDPDR=1</option></term> + <listitem><para> + Disables the RDP device redirection for smart cards VRDE + server feature. To reenable this feature, assign an empty + value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=H3DRedirect/Enabled=1</option></term> + <listitem><para> + Enables the 3D redirection VRDE server feature. To disable + this feature, assign an empty value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Security/Method=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the following information that is required for a + connection: + </para><itemizedlist> + <listitem><para> + <literal>Negotiate</literal> indicates that both + Enhanced (TLS) and Standard RDP Security connections + are permitted. The security method is negotiated with + the client. This is the default value. + </para></listitem> + <listitem><para> + <literal>RDP</literal> indicates that only Standard + RDP Security is accepted. + </para></listitem> + <listitem><para> + <literal>TLS</literal> indicates that only Enhanced + RDP Security is accepted. The client must support TLS. + </para></listitem> + </itemizedlist><para> + See <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=ServerCertificate=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the server certificate. See + <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=ServerPrivateKey=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the server private key. See + <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=CACertificate=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the CA self-signed + certificate. See <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property Audio/RateCorrectionMode=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the audio connection mode or the path to the + audio log file. Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>VRDP_AUDIO_MODE_VOID</literal> is no mode. + Use this value to unset any set audio mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_RC</literal> is the rate + correction mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_LPF</literal> is the low pass + filter mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_CS</literal> is the client + sync sync mode to prevent an underflow or overflow of + the client queue. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=LogPath=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the audio log file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-extpack=default | <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the library to use to access the VM remotely. + The <literal>default</literal> value uses the RDP code + that is part of the &product-name; Extension Pack. + </para><para> + To use the VRDE module in VNC, specify + <literal>VNC</literal>. See + <xref linkend="otherextpacks"/>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-port=default | <replaceable>port</replaceable></option></term> + <listitem><para> + <replaceable>port</replaceable> is the port or port range + to which the VRDE server binds. The + <literal>default</literal> or <literal>0</literal> value + uses port <literal>3389</literal>, which is the standard + RDP port. + </para><para> + 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 available ports from the list. Only one machine can + use a given port at a time. For example, the + <option>--vrde-port=5000,5010-5012</option> option + specifies that server can bind to one of following ports: + <literal>5000</literal>, <literal>5010</literal>, + <literal>5011</literal>, or <literal>5012</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-address=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + 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. + </para><para> + Use this option to specify whether the VRDP server should + accept IPv4, IPv6, or both type of connections: + </para><itemizedlist> + <listitem><para> + <emphasis role="bold">Only IPv4:</emphasis> Use the + <option>--vrde-address="0.0.0.0"</option> option. + </para></listitem> + <listitem><para> + <emphasis role="bold">Only IPv6:</emphasis> Use the + <option>--vrde-address="::"</option> option. + </para></listitem> + <listitem><para> + <emphasis role="bold">Both IPv6 and IPv4:</emphasis> + Use the <option>--vrde-address=""</option> + option. This is the default value. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-auth-type=null | external | guest</option></term> + <listitem><para> + Specify whether to use authorization and how to perform + authorization. See <xref linkend="vbox-auth" />. Valid + values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>null</literal> provides no authentication. + </para></listitem> + <listitem><para> + <literal>external</literal> provides external + authentication through an authentication library. + </para></listitem> + <listitem><para> + <literal>guest</literal> performs authentication by + using guest user accounts. This unsupported method + requires that you install the Guest Additions on the + VM. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-auth-library=default | <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the library to use for RDP authentication. The + default library for external authentication is + <filename>VBoxAuth</filename>. See + <xref linkend="vbox-auth" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-multi-con=on | off</option></term> + <listitem><para> + Enables or disables the multiple connections VRDE server + feature, if supported. See + <xref linkend="vrde-multiconnection" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-reuse-con=on | off</option></term> + <listitem><para> + Specifies how the VRDE server behaves when multiple + connections are disabled. When the value is + <literal>on</literal>, the server permits a new client to + connect and drops the existing connection. When the value + is <literal>off</literal>, a new connection is not + accepted if a client is already connected to the server. + This is the default value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-video-channel=on | off</option></term> + <listitem><para> + Enables video redirection if supported by the VRDE server. + See <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-video-channel-quality=<replaceable>percent</replaceable></option></term> + <listitem><para> + Specifies the image quality for video redirection as a + value from 10 to 100 percent. The percentage represents + the JPEG compression level where a lower number diminishes + quality and provides higher compression. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-teleport"> + <title>Teleporting Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to configure a machine as a + teleporting target. See <xref linkend="teleporting" /> and the + teleporting related entries in <xref linkend="pot-insecure" />. + </para> + <variablelist> + <varlistentry> + <term><option>--teleporter=on | off</option></term> + <listitem><para> + 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. + </para><para> + Teleporting requests are received on the port and address + specified using the following parameters. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-port=<replaceable>port</replaceable></option></term> + <listitem><para> + Specifies the port on which the VM listens to receive a + teleporting request from another VM. + <replaceable>port</replaceable> is any free TCP/IP port + number, such as <literal>6000</literal>. You must also + specify the <option>--teleporter</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-address=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies the IP address on which the VM listens to + receive a teleporting request from another VM. + <replaceable>IP-address</replaceable> is any IP address or + host name and specifies the TCP/IP socket on which to + bind. The default IP address is + <literal>0.0.0.0</literal>, which represents any IP + address. You must also specify the + <option>--teleporter</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-password=<replaceable>password</replaceable></option></term> + <listitem><para> + 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-password-file=<replaceable>filename</replaceable></option></term> + <listitem><para> + 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 password as the one you specify in the password file. + A value of <literal>stdin</literal> reads the password + from standard input. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-portability-level=<replaceable>level</replaceable></option></term> + <listitem> + <para> + Restricts the virtual CPU capabilities that &product-name; + presents to the guest OS by using portability rules. Higher + integer values designate more restrictive behavior. The + default level of <literal>0</literal> indicates that all + virtualized features supported by the host are made available + to the guest. The value <literal>3</literal> supresses most + features. Values of <literal>1</literal> and <literal>2</literal> + represent restrictions in between. The behavior may change + depending on the product version. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-set=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>] + <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></option></term> + <listitem> + <para> + Advanced users can use this setting before a teleporting + operation (in fact before starting the VM) to restrict the + virtual CPU capabilities that &product-name; presents to + the guest operating system. This must be run on both the + source and the target machines involved 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. + </para><para> + The values of <replaceable>leaf</replaceable>, + <replaceable>subleaf</replaceable> (optional), + <replaceable>eax</replaceable>, <replaceable>ebx</replaceable>, + <replaceable>ecx</replaceable> and <replaceable>edx</replaceable> + are integers given in hexadecimal format, i.e. using a radix + (base) of 16 without requiring any prefix. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-remove=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>]</option></term> + <listitem> + <para> + Removes an adjustment established with <option>--cpuid-set</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-remove-all</option></term> + <listitem> + <para> + Removes all adjustments established with <option>--cpuid-set</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-debugging"> + <title>Debugging Settings</title> + <remark role="help-copy-synopsis"/> + <para> + Only use the following options to perform low-level VM + debugging. These options are for advanced users only. + </para> + <variablelist> + <varlistentry> + <term><option>--tracing-enabled=on | off</option></term> + <listitem><para> + Enables or disables the trace buffer. Note that when + specified, the trace buffer consumes some memory and adds + overhead. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tracing-config=<replaceable>config-string</replaceable></option></term> + <listitem><para> + Enables a tracing configuration that defines which group + of trace points are enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tracing-allow-vm-access=on | off</option></term> + <listitem><para> + Enables or disables VM access to the trace buffer. The + default value is <literal>off</literal>, which disables + access. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-usbcardreader"> + <title>USB Card Reader Settings</title> + <remark role="help-copy-synopsis"/> + <para> + 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). + </para> + <variablelist> + <varlistentry> + <term><option>--usb-card-reader=on | off</option></term> + <listitem><para> + Enables or disables the USB card reader interface. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-autostart"> + <title>Autostarting VMs During Host System Boot</title> + <para> + 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 <xref linkend="autostart" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--autostart-enabled=on | off</option></term> + <listitem><para> + Enables or disables VM autostart at host system boot-up + for the specified users. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--autostart-delay=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the number of seconds after host system boot-up + to autostart the VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-guest-debug"> + <title>Guest Debugging</title> + <para> + These options are for configuring the VMM for guest debugging. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--guest-debug-provider=none | native | gdb | kd</option></term> + <listitem><para>Selects the given debug stub provider. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-debug-io-provider=none | tcp | udp | ipc</option></term> + <listitem><para>Selects the given I/O transport backend for the selected provider.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-debug-address=<replaceable>IP-Address</replaceable> | <replaceable>path</replaceable></option></term> + <listitem><para>Sets the path the debugger is accessible under, depends on the selected I/O transport.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-debug-port=<replaceable>port</replaceable></option></term> + <listitem><para>Sets the port the debugger is accessible under, depends on the selected I/O transport.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-pcipassthrough"> + <title>PCI Passthrough Settings</title> + <para> + The following options enable you to configure the PCI passthrough + feature, which currently is not available in &product-name;. It is + planned to bring this functionality back in the future. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--pci-attach=<replaceable>host-PCI-address</replaceable>[@<replaceable>guest-PCI-bus-address</replaceable>]</option></term> + <listitem><para> + Attaches the specified PCI network controller on the host + to the guest VM. You can optionally specify the PCI bus on + the guest VM on which to attach the controller. +<!-- See <xref linkend="pcipassthrough" />. --> + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--pci-detach=<replaceable>host-PCI-address</replaceable></option></term> + <listitem><para> + Detaches the specified PCI network controller from the + attached PCI bus on the guest VM. +<!-- See <xref linkend="pcipassthrough" />. --> + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-testing"> + <title>Testing (ValidationKit / Bootsector)</title> + <para> + These options are for configuring the testing functionality of the VMM + device and almost exclusively used by the bootsector testcases in the + ValidationKit. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--testing-enabled=on | off</option></term> + <listitem><para>Enabled the testing functionality of the VMMDev. See VMMDevTesting.h for details. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--testing-mmio=on | off</option></term> + <listitem><para>Enabled the MMIO region of the VMMDev testing feature.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + This sets one of the 10 dword configuration values. The + <replaceable>idx</replaceable> must be in the range 0 thru 9. + The <replaceable>value</replaceable> is limited to 32 bits (dword). + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command changes the description for the + <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage modifyvm ol7 --description "Oracle Linux 7 with UEK4"</screen> + <para> + The following command enables VirtualBox Remote Display Protocol + (VRDP) support for the <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage modifyvm ol7 --vrde on</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-controlvm" />, + <xref linkend="vboxmanage-createvm" />, + <xref linkend="vboxmanage-startvm" /> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> |