user_VBoxManage.xml revision ac153c99053f1edf42b00bf3a13475923bc4fcf1
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As briefly mentioned in <xref linkend="frontends" />, VBoxManage is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the command-line interface to VirtualBox. With it, you can completely
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync control VirtualBox from the command line of your host operating system.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VBoxManage supports all the features that the graphical user interface
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync gives you access to, but it supports a lot more than that. It exposes
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync really all the features of the virtualization engine, even those that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync cannot (yet) be accessed from the GUI.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You will need to use the command line if you want to</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>use a different user interface than the main GUI (for example,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VBoxSDL or the VBoxHeadless server);</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>control some of the more advanced and experimental
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync configuration settings for a VM.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>There are two main things to keep in mind when using
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage</computeroutput>: First,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage</computeroutput> must always be used with a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specific "subcommand", such as "list" or "createvm" or "startvm". All the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync subcommands that <computeroutput>VBoxManage</computeroutput> supports are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync described in detail in <xref linkend="vboxmanage" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Second, most of these subcommands require that you specify a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync particular virtual machine after the subcommand. There are two ways you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can do this:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You can specify the VM name, as it is shown in the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync GUI. Note that if that name contains spaces, then you must enclose the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync entire name in double quotes (as it is always required with command
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync line arguments that contain spaces).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For example:<screen>VBoxManage startvm "Windows XP"</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You can specify the UUID, which is the internal unique
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync identifier that VirtualBox uses to refer to the virtual machine.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Assuming that the aforementioned VM called "Windows XP" has the UUID
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync shown below, the following command has the same effect as the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync previous:<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You can type <computeroutput>VBoxManage list vms</computeroutput> to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync have all currently registered VMs listed with all their settings,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync including their respective names and UUIDs.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Some typical examples of how to control VirtualBox from the command
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync line are listed below:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To create a new virtual machine from the command line and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync immediately register it with VirtualBox, use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage createvm</computeroutput> with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--register</computeroutput> option,<footnote>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>$ VBoxManage createvm --name "SUSE 10.2" --register
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncAll rights reserved.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVirtual machine 'SUSE 10.2' is created.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncUUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncSettings file: '/home/username/.VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As can be seen from the above output, a new virtual machine has
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync been created with a new UUID and a new XML settings file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To show the configuration of a particular VM, use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage showvminfo</computeroutput>; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="vboxmanage-showvminfo" /> for details and an example.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To change settings while a VM is powered off, use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage modifyvm</computeroutput>, e.g. as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync follows:<screen>VBoxManage modifyvm "Windows XP" --memory "512MB"</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For details, see <xref linkend="vboxmanage-modifyvm" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To change the storage configuration (e.g. to add a storage
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync controller and then a virtual disk), use <computeroutput>VBoxManage
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync storagectl</computeroutput> and <computeroutput>VBoxManage
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync linkend="vboxmanage-storageattach" /> for details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To control VM operation, use one of the following:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To start a VM that is currently powered off, use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage startvm</computeroutput>; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="vboxmanage-startvm" /> for details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To pause or save a VM that is currently running or change
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync some of its settings, use <computeroutput>VBoxManage
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="vboxmanage-controlvm" /> for details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When running VBoxManage without parameters or when supplying an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync invalid command line, the below syntax diagram will be shown. Note that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the output will be slightly different depending on the host platform; when
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in doubt, check the output of <computeroutput>VBoxManage</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the commands available on your particular host.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Each time VBoxManage is invoked, only one command can be executed.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync However, a command might support several subcommands which then can be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync invoked in one single call. The following sections provide detailed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync reference information on the different commands.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>list</computeroutput> command gives relevant
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information about your system and information about VirtualBox's current
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync settings.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following subcommands are available with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage list</computeroutput>: <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>vms</computeroutput> lists all virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machines currently registered with VirtualBox. By default this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync displays a compact list with each VM's name and UUID; if you also
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-l</computeroutput>, this will be a detailed list as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with the <computeroutput>showvminfo</computeroutput> command (see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync below).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>runningvms</computeroutput> lists all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync currently running virtual machines by their unique identifiers
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (UUIDs) in the same format as with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>ostypes</computeroutput> lists all guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operating systems presently known to VirtualBox, along with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync identifiers used to refer to them with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>modifyvm</computeroutput> command.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>hostfloppies</computeroutput>, respectively, list
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync DVD, floppy, bridged networking and host-only networking interfaces
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync on the host, along with the name used to access them from within
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VirtualBox.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>dhcpservers</computeroutput>, respectively, list
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync bridged network interfaces, host-only network interfaces and DHCP
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync servers currently available on the host. Please see <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync linkend="networkingdetails" /> for details on these.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>hostinfo</computeroutput> displays information
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync about the host system, such as CPUs, memory size and operating
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync system version.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>hostcpuids</computeroutput> dumps the CPUID
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync parameters for the host CPUs. This can be used for a more fine
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync grained analyis of the host's virtualization capabilities.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>hddbackends</computeroutput> lists all known
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync virtual disk back-ends of VirtualBox. For each such format (such as
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VDI, VMDK or RAW), this lists the back-end's capabilities and
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync configuration.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>floppies</computeroutput> all give you information
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync about virtual disk images currently in use by VirtualBox, including
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync all their settings, the unique identifiers (UUIDs) associated with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync them by VirtualBox and all files associated with them. This is the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync command-line equivalent of the Virtual Media Manager; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>usbhost</computeroutput> supplies information
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync about USB devices attached to the host, notably information useful
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for constructing USB filters and whether they are currently in use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync by the host.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>usbfilters</computeroutput> lists all global
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync USB filters registered with VirtualBox -- that is, filters for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync devices which are accessible to all virtual machines -- and displays
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the filter parameters.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>systemproperties</computeroutput> displays
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync some global VirtualBox settings, such as minimum and maximum guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync RAM and virtual hard disk size, folder settings and the current
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync authentication library in use.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>extpacks</computeroutput> displays all
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VirtualBox extension packs currently installed; see <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync linkend="vboxmanage-extpack" /> for more information.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>showvminfo</computeroutput> command shows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information about a particular virtual machine. This is the same
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information as <computeroutput>VBoxManage list vms --long</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync would show for all virtual machines.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You will get information similar to the following:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncAll rights reserved.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncName: Windows XP
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncUUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncConfig file: /home/username/.VirtualBox/Machines/Windows XP/Windows XP.xml
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncMemory size: 512MB
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVRAM size: 12MB
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNumber of CPUs: 2
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncSynthetic Cpu: off
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncBoot menu mode: message and menu
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncBoot Device (1): DVD
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncBoot Device (2): HardDisk
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncBoot Device (3): Not Assigned
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncBoot Device (4): Not Assigned
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncTime offset: 0 ms
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncHardw. virt.ext exclusive: on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNested Paging: on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVT-x VPID: off
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncState: powered off (since 2009-10-20T14:52:19.000000000)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncMonitor count: 1
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync3D Acceleration: off
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync2D Video Acceleration: off
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncTeleporter Enabled: off
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncTeleporter Port: 0
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncTeleporter Address:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncTeleporter Password:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncStorage Controller (0): IDE Controller
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncStorage Controller Type (0): PIIX4
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncStorage Controller (1): Floppy Controller 1
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncStorage Controller Type (1): I82078
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIDE Controller (0, 0): /home/user/windows.vdi (UUID: 46f6e53a-4557-460a-9b95-68b0f17d744b)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIDE Controller (0, 1): /home/user/openbsd-cd46.iso (UUID: 4335e162-59d3-4512-91d5-b63e94eebe0b)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncFloppy Controller 1 (0, 0): /home/user/floppy.img (UUID: 62ac6ccb-df36-42f2-972e-22f836368137)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNIC 1: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNIC 2: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNIC 3: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNIC 4: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNIC 5: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNIC 6: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNIC 7: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncNIC 8: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncUART 1: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncUART 2: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncAudio: disabled (Driver: Unknown)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncClipboard Mode: Bidirectional
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVRDE: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncUSB: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncUSB Device Filters:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync<none>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncShared folders:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync<none>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncStatistics update: disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>VBoxManage registervm / unregistervm</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>registervm</computeroutput> command allows you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to import a virtual machine definition in an XML file into VirtualBox. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine must not conflict with one already registered in VirtualBox and it
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync may not have any hard or removable disks attached. It is advisable to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync place the definition file in the machines folder before registering
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When creating a new virtual machine with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage createvm</computeroutput> (see below), you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can directly specify the <computeroutput>--register</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync option to avoid having to register it separately.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>unregistervm</computeroutput> command
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync unregisters a virtual machine. If
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--delete</computeroutput> is also specified, the following
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync files will automatically be deleted as well:<orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>all hard disk image files, including differencing files, which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync are used by the machine and not shared with other machines;</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>saved state files that the machine created, if any (one if the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine was in "saved" state and one for each online
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync snapshot);</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>the machine directory, if it is empty after having deleted all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the above.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title id="vboxmanage-createvm">VBoxManage createvm</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command creates a new XML virtual machine definition
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>--name <name></computeroutput> parameter
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is required and must specify the name of the machine. Since this name is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync used by default as the file name of the settings file (with the extension
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>.xml</computeroutput>) and the machine folder (a subfolder
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the <computeroutput>.VirtualBox/Machines</computeroutput> folder), it
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync must conform to your host operating system's requirements for file name
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specifications. If the VM is later renamed, the file and folder names will
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync change automatically.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <path></computeroutput> option is used, the machine folder will be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync named <computeroutput><path></computeroutput>. In this case, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync names of the file and the folder will not change if the virtual machine is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync renamed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>By default, this command only creates the XML file without
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync automatically registering the VM with your VirtualBox installation. To
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync register the VM instantly, use the optional
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--register</computeroutput> option, or run
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage registervm</computeroutput> separately
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync afterwards.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command changes the properties of a registered virtual machine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which is not running. Most of the properties that this command makes
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync available correspond to the VM settings that VirtualBox graphical user
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface displays in each VM's "Settings" dialog; these were described in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="BasicConcepts" />. Some of the more advanced settings,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync however, are only available through the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage</computeroutput> interface.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>These commands require that the machine is powered off (neither
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync running nor in "saved" state). Some machine settings can also be changed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync while a machine is running; those settings will then have a corresponding
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync subcommand with the <computeroutput>VBoxManage controlvm</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync subcommand (see <xref linkend="vboxmanage-controlvm" />).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following general settings are available through
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--name <name></computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync changes the VM's name and possibly renames the internal virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine files, as described with <computeroutput>VBoxManage
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--ostype <ostype></computeroutput>:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This specifies what guest operating system is supposed to run in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VM. To learn about the various identifiers that can be used
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync here, use <computeroutput>VBoxManage list
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <memorysize></computeroutput>: This sets the amount of RAM,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in MB, that the virtual machine should allocate for itself from
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the host. See the remarks in <xref linkend="gui-createvm" /> for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync more information.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--vram <vramsize></computeroutput>:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This sets the amount of RAM that the virtual graphics card should
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync have. See <xref linkend="settings-display" /> for details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--acpi on|off</computeroutput>;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--ioapic on|off</computeroutput>: These two
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync determine whether the VM should have ACPI and I/O APIC support,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync respectively; see <xref linkend="settings-motherboard" /> for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <uuid></computeroutput>: The UUID presented to the guest via
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync memory tables (DMI/SMBIOS), hardware and guest properties. By
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync default this is the same as the VM uuid. Useful when cloning a VM.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Teleporting takes care of this automatically.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--cpus <cpucount></computeroutput>:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This sets the number of virtual CPUs for the virtual machine (see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="settings-processor" />). If CPU hot-plugging is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enabled (see below), this then sets the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <emphasis>maximum</emphasis> number of virtual CPUs that can be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync plugged into the virtual machines.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--rtcuseutc on|off</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync option lets the real-time clock (RTC) operate in UTC time (see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--cpuhotplug on|off</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enables CPU hot-plugging. When enabled, virtual CPUs can be added
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to and removed from a virtual machine while it is running. See
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="cpuhotplug" /> for more information.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <id></computeroutput>: If CPU hot-plugging is enabled (see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync above), this adds a virtual CPU to the virtual machines (or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync removes one). <computeroutput><id></computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specifies the index of the virtual CPU to be added or removed and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync must be a number from 0 to the maximum no. of CPUs configured with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the <computeroutput>--cpus</computeroutput> option. CPU 0 can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync never be removed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <1-100></computeroutput>: This setting controls how much cpu
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync time a virtual CPU can use. A value of 50 implies a single virtual
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync CPU can use up to 50% of a single host CPU.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--synthcpu on|off</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync setting determines whether VirtualBox will expose a synthetic CPU
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to the guest to allow live migration between host systems that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync differ significantly.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--pae on|off</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--hpet on|off</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enables/disables a High Precision Event Timer (HPET) which can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync replace the legacy system timers. This is turned off by default.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Note that Windows supports a HPET only from Vista onwards.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--hwvirtex on|off</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enables or disables the use of hardware virtualization extensions
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (Intel VT-x or AMD-V) in the processor of your host system; see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--hwvirtexexcl on|off</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specifies whether VirtualBox will make exclusive use of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hardware virtualization extensions (Intel VT-x or AMD-V) in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync processor of your host system; see <xref linkend="hwvirt" />. If
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you wish to simultaneously share these extensions with other
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hypervisors, then you must disable this setting. Doing so has
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync negative performance implications.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--nestedpaging on|off</computeroutput>: If
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hardware virtualization is enabled, this additional setting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enables or disables the use of the nested paging feature in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync processor of your host system; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--largepages on|off</computeroutput>: If
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hardware virtualization <emphasis>and</emphasis> nested paging are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enabled, for Intel VT-x only, an additional performance
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync improvement of up to 5% can be obtained by enabling this setting.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This causes the hypervisor to use large pages to reduce TLB use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and overhead.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--vtxvpid on|off</computeroutput>: If
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hardware virtualization is enabled, for Intel VT-x only, this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync additional setting enables or disables the use of the tagged TLB
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (VPID) feature in the processor of your host system; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--accelerate3d on|off</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enables, if the Guest Additions are installed, whether hardware 3D
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync acceleration should be available; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You can influence the BIOS logo that is displayed when a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machine starts up with a number of settings. Per default,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a VirtualBox logo is displayed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on|off</computeroutput> and <computeroutput>--bioslogofadeout
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on|off</computeroutput>, you can determine whether the logo should
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync fade in and out, respectively.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <msec></computeroutput> you can set how long the logo should
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be visible, in milliseconds.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <imagepath></computeroutput> you can, if you are so
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync inclined, replace the image that is shown, with your own logo. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync image must be an uncompressed 256 color BMP file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disabled|menuonly|messageandmenu</computeroutput>: This specifies
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync whether the BIOS allows the user to select a temporary boot
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync device. <computeroutput>menuonly</computeroutput> suppresses the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync message, but the user can still press F12 to select a temporary
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync boot device.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync none|floppy|dvd|disk|net</computeroutput>: This specifies the boot
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync order for the virtual machine. There are four "slots", which the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VM will try to access from 1 to 4, and for each of which you can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync set a device that the VM should attempt to boot from.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync default|<path></computeroutput>: This allows you to specify
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the folder in which snapshots will be kept for a virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--firmware efi|bios</computeroutput>:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Specifies which firmware is used to boot particular virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine: EFI or BIOS. Use EFI only if your fully understand what
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you're doing.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <size></computeroutput> sets the default size of the guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync memory balloon, that is, memory allocated by the VirtualBox Guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Additions from the guest operating system and returned to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hypervisor for re-use by other virtual machines. <size> must
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be specified in megabytes. The default size is 0 megabytes. For
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync details, see <xref linkend="guestadd-balloon" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following networking settings are available through
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync settings, the decimal number directly following the option name ("1-N"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in the list below) specifies the virtual network adapter whose settings
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync should be changed.<itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync none|null|nat|bridged|intnet|hostonly|generic
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </computeroutput>: With
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this, you can set, for each of the VM's virtual network cards,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync what type of networking should be available. They can be not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync present (<computeroutput>none</computeroutput>), not connected to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the host (<computeroutput>null</computeroutput>), use network
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync address translation (<computeroutput>nat</computeroutput>),
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync bridged networking (<computeroutput>bridged</computeroutput>) or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync communicate with other virtual machines using internal networking
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (<computeroutput>intnet</computeroutput>), host-only networking
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (<computeroutput>hostonly</computeroutput>), or access rarely used
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync sub-modes (<computeroutput>generic</computeroutput>).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync These options correspond
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to the modes which are described in detail in <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio</computeroutput>:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This allows you, for each of the VM's virtual network cards, to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specify which networking hardware VirtualBox presents to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on|off</computeroutput>: This allows you to temporarily disconnect
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a virtual network interface, as if a network cable had been pulled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync from a real network card. This might be useful for resetting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync certain software components in the VM.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With the "nictrace" options, you can optionally trace
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync network traffic by dumping it to a file, for debugging
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync purposes.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on|off</computeroutput>, you can enable network tracing for a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync particular virtual network card.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If enabled, you must specify with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--nictracefile<1-N>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <filename></computeroutput> what file the trace should be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync logged to.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync none|<devicename></computeroutput>: If bridged networking
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync has been enabled for a virtual network card (see the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--nic</computeroutput> option above; otherwise
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this setting has no effect), use this option to specify which host
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface the given virtual network interface will use. For
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync details, please see <xref linkend="network_bridged" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync none|<devicename></computeroutput>: If host-only networking
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync has been enabled for a virtual network card (see the --nic option
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync above; otherwise this setting has no effect), use this option to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specify which host-only networking interface the given virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync network interface will use. For details, please see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync network</computeroutput>: If internal networking has been enabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for a virtual network card (see the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--nic</computeroutput> option above; otherwise
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this setting has no effect), use this option to specify the name
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the internal network (see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync auto|<mac></computeroutput>: With this option you can set
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the MAC address of the virtual network card. Normally, each
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual network card is assigned a random address by VirtualBox at
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VM creation.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <backend driver></computeroutput>: If generic networking has been
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync enabled for a virtual network card (see the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--nic</computeroutput> option above; otherwise
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync this setting has no effect), this mode allows you to access
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync rarely used networking sub-modes, such as VDE network or UDP Tunnel.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <paramname>="paramvalue"</computeroutput>:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This option, in combination with "nicgenericdrv" allows you to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync pass parameters to rarely-used network backends.</para><para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Those parameters are backend engine-specific, and are different
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync between UDP Tunnel and the VDE backend drivers. For example,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following NAT networking settings are available through
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync settings, the decimal number directly following the option name ("1-N"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in the list below) specifies the virtual network adapter whose
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync settings should be changed.<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync [<name>],tcp|udp,[<hostip>],<hostport>,[<guestip>],
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <guestport></computeroutput>: This option defines a NAT
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync port-forwarding rule (please see <xref linkend="natforward" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for details).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <name></computeroutput>: This option deletes a NAT
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync port-forwarding rule (please see <xref linkend="natforward" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for details).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <prefix></computeroutput>: This option defines a prefix
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the built-in TFTP server, i.e. where the boot file is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync located (please see <xref linkend="nat-tftp" /> and <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <bootfile></computeroutput>: This option defines the TFT
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync boot file (please see <xref linkend="nat-adv-tftp" /> for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync details).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <tftpserver></computeroutput>: This option defines the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync TFTP server address to boot from (please see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--natdnspassdomain<1-N>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on|off</computeroutput>: This option specifies whether the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync built-in DHCP server passes the domain name for network name
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync resolution.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on|off</computeroutput>: This option makes the NAT engine proxy
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync all guest DNS requests to the host's DNS servers (please see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="nat-adv-dns" /> for details).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--natdnshostresolver<1-N>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on|off</computeroutput>: This option makes the NAT engine use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the host's resolver mechanisms to handle DNS requests (please
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync see <xref linkend="nat-adv-dns" /> for details).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync [<mtu>],[<socksnd>],[<sockrcv>],[<tcpsnd>],
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync [<tcprcv>]</computeroutput>: This option controls several
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync NAT settings (please see <xref linkend="nat-adv-settings" /> for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync details).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync default|[log],[proxyonly],[sameports]</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync option defines behaviour of NAT engine core: log - enables
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync logging, proxyonly - switches of aliasing mode makes NAT
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync transparent, sameports enforces NAT engine to send packets via
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the same port as they originated on, default - disable all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync mentioned modes above . (please see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>Serial port, audio, clipboard, remote desktop and USB
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync settings</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following other hardware settings are available through
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--uart<1-N> off|<I/O base>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <IRQ></computeroutput>: With this option you can configure
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual serial ports for the VM; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="serialports" /> for an introduction.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <arg></computeroutput>: This setting controls how VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync connects a given virtual serial port (previously configured with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the <computeroutput>--uartX</computeroutput> setting, see above)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to the host on which the virtual machine is running. As described
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in detail in <xref linkend="serialports" />, for each such port,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you can specify <computeroutput><arg></computeroutput> as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync one of the following options:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>disconnected</computeroutput>: Even
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync though the serial port is shown to the guest, it has no
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "other end" -- like a real COM port without a cable.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <pipename></computeroutput>: On a Windows host, this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync tells VirtualBox to create a named pipe on the host named
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput><pipename></computeroutput> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync connect the virtual serial device to it. Note that Windows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync requires that the name of a named pipe begin with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On a Linux host, instead of a named pipe, a local
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync domain socket is used.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <pipename></computeroutput>: This operates just like
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>server ...</computeroutput>, except that the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync pipe (or local domain socket) is not created by VirtualBox,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync but assumed to exist already.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput><devicename></computeroutput>:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync If, instead of the above, the device name of a physical
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hardware serial port of the host is specified, the virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync serial port is connected to that hardware port. On a Windows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync host, the device name will be a COM port such as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>COM1</computeroutput>; on a Linux host, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync device name will look like
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/dev/ttyS0</computeroutput>. This allows you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to "wire" a real serial port to a virtual machine.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--audio none|null|oss</computeroutput>: With
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this option, you can set whether the VM should have audio
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync support.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync With this setting, you can select whether the guest operating
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync system's clipboard should be shared with the host; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="generalsettings" />. This requires that the Guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Additions be installed in the virtual machine.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <count></computeroutput>: This enables multi-monitor
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync support; see <xref linkend="settings-display" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--usb on|off</computeroutput>: This option
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enables or disables the VM's virtual USB controller; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--usbehci on|off</computeroutput>: This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync option enables or disables the VM's virtual USB 2.0 controller;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync see <xref linkend="settings-usb" /> for details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following settings that affect remote machine behavior are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync available through <computeroutput>VBoxManage
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--vrde on|off</computeroutput>: With the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox graphical user interface, this enables or disables the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VirtualBox remote desktop extension (VRDE) server. Note that if
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync you are using <computeroutput>VBoxHeadless</computeroutput> (see
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <xref linkend="vboxheadless" />), VRDE is enabled by
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync default.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync default|<ports></computeroutput>: A port or a range of ports
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the VRDE server can bind to; "default" or "0" means port 3389, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync standard port for RDP. You can specify a comma-separated list of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ports or ranges of ports. Use a dash between two port numbers to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync specify a range. The VRDE server will bind to <emphasis
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync role="bold">one</emphasis> of available ports from the specified
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync list. Only one machine can use a given port at a time. For
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync example, the option <computeroutput> --vrdeport
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 5000,5010-5012</computeroutput> will tell the server to bind to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync one of following ports: 5000, 5010, 5011 or 5012.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync address></computeroutput>: The IP address of the host network
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync interface the VRDE server will bind to. If specified, the server
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync will accept connections only on the specified host network
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync null|external|guest</computeroutput>: This allows you to choose
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync whether and how authorization will be performed; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--vrdemulticon on|off</computeroutput>: This
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync enables multiple connections to the same VRDE server, if the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--vrdereusecon on|off</computeroutput>: This
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync specifies the VRDE server behavior when multiple connections are
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync disabled. When this option is enabled, the server will allow a new
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync client to connect and will drop the existing connection. When this
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync option is disabled (this is the default setting), a new connection
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync will not be accepted if there is already a client connected to the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync server.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--vrdevideochannel on|off</computeroutput>:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This enables video redirection, if it is supported by the VRDE
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync server; see <xref lang="" linkend="vrde-videochannel" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <percent></computeroutput>: Sets the image quality for video
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With the following commands for <computeroutput>VBoxManage
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync modifyvm</computeroutput> you can configure a machine to be a target for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync teleporting. See <xref linkend="teleporting" /> for an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync introduction.<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--teleporter on|off</computeroutput>: With
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this setting you turn on or off whether a machine waits for a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync teleporting request to come in on the network when it is started.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync If "on", when the machine is started, it does not boot the virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine as it would normally; instead, it then waits for a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync teleporting request to come in on the port and address listed with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the next two parameters.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <port></computeroutput>, <computeroutput>--teleporteraddress
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <address></computeroutput>: these must be used with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync --teleporter and tell the virtual machine on which port and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync address it should listen for a teleporting request from another
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machine. <computeroutput><port></computeroutput> can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput><address></computeroutput> can be any IP
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync address or hostname and specifies the TCP/IP socket to bind to.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync The default is "0.0.0.0", which means any address.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <password></computeroutput>: if this optional argument is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync given, then the teleporting request will only succeed if the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync source machine specifies the same password as the one given with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync this command.<note>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Currently, the password is stored without encryption
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (i.e. in clear text) in the XML machine configuration
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--cpuid <leaf> <eax> <ebx>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <ecx> <edx></computeroutput>: Advanced users can use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this command before a teleporting operation to restrict the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual CPU capabilities that VirtualBox presents to the guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operating system. This must be run on both the source and the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync target machines involved in the teleporting and will then modify
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync what the guest sees when it executes the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>CPUID</computeroutput> machine instruction. This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync might help with misbehaving applications that wrongly assume that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync certain CPU capabilities are present. The meaning of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync parameters is hardware dependent; please refer to the AMD or Intel
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync processor manuals.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This command creates a full or linked copy of an existing virtual
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync machine.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>clonevm</computeroutput> subcommand takes at
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync least the name of the virtual machine which should be cloned. The following
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync additional settings can be used to further configure the clone VM
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync operation:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--snapshot <uuid>|<name></computeroutput>:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Select a specific snapshot where the clone operation should refer
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to. Default is referring to the current state.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--mode machine|machineandchildren|all</computeroutput>:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Selects the cloning mode of the operation. If
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>machine</computeroutput> is selected (the default),
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the current state of the VM without any snapshots is cloned. In the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>machineandchildren</computeroutput> mode the snapshot
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync provided by <computeroutput>--snapshot</computeroutput> and all
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync child snapshots are cloned. If <computeroutput>all</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync is the selected mode all snapshots and the current state are cloned.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--options link|keepallmacs|keepnatmacs|keepdisknames</computeroutput>:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Allows additional fine tuning of the clone operation. The first
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync option defines that a linked clone should be created, which is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync only possible for a machine clone from a snapshot. The next two
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync options allow to define how the MAC addresses of every virtual
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync network card should be handled. They can either be reinitialized
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (the default), left unchanged
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (<computeroutput>keepallmacs</computeroutput>) or left unchanged
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync when the network type is NAT
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (<computeroutput>keepnatmacs</computeroutput>). If you add
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>keepdisknames</computeroutput> all new disk images
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync are called like the original once, otherwise they are
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync renamed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--name <name></computeroutput>: Select a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync new name for the new virtual machine. Default is "Original Name
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Clone".</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--basefolder <basefolder></computeroutput>:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Select the folder where the new virtual machine configuration should
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync be saved in.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>--uuid <uuid></computeroutput>:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Select the UUID the new VM should have. This id has to be unique in
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the VirtualBox instance this clone should be registered. Default is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync creating a new UUID.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Automatically register the new clone in this VirtualBox
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync installation. If you manually want register the new VM later, see
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <xref linkend="vboxmanage-registervm" /> for instructions how to do
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command imports a virtual appliance in OVF format by copying
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the virtual disk images and creating virtual machines in VirtualBox. See
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="ovf" /> for an introduction to appliances.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>import</computeroutput> subcommand takes at
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync least the path name of an OVF file as input and expects the disk images,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync if needed, in the same directory as the OVF file. A lot of additional
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync command-line options are supported to control in detail what is being
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync imported and modify the import parameters, but the details depend on the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync content of the OVF file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>It is therefore recommended to first run the import subcommand with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-n</computeroutput> option. This will then print a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync description of the appliance's contents to the screen how it would be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync imported into VirtualBox, together with the optional command-line options
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to influence the import behavior.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As an example, here is the screen output with a sample appliance
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync containing a Windows XP guest:<screen>VBoxManage import WindowsXp.ovf --dry-run
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVirtual system 0:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 0: Suggested OS type: "WindowsXP"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 1: Suggested VM name "Windows XP Professional_1"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (change with "--vsys 0 --vmname <name>")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 3: Number of CPUs: 1
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (change with "--vsys 0 --cpus <n>")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 4: Guest memory: 956 MB (change with "--vsys 0 --memory <MB>")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 5: Sound card (appliance expects "ensoniq1371", can change on import)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (disable with "--vsys 0 --unit 5 --ignore")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 6: USB controller
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (disable with "--vsys 0 --unit 6 --ignore")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 7: Network adapter: orig bridged, config 2, extra type=bridged
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (disable with "--vsys 0 --unit 8 --ignore")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 9: SCSI controller, type BusLogic
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}";
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disable with "--vsys 0 --unit 9 --ignore")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync10: IDE controller, type PIIX4
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (disable with "--vsys 0 --unit 10 --ignore")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync11: Hard disk image: source image=WindowsXp.vmdk,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (change controller with "--vsys 0 --unit 11 --controller <id>";
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disable with "--vsys 0 --unit 11 --ignore")</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As you can see, the individual configuration items are numbered, and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync depending on their type support different command-line options. The import
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync subcommand can be directed to ignore many such items with a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--vsys X --unit Y --ignore</computeroutput> option, where
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync X is the number of the virtual system (zero unless there are several
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual system descriptions in the appliance) and Y the item number, as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync printed on the screen.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the above example, Item #1 specifies the name of the target
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine in VirtualBox. Items #9 and #10 specify hard disk controllers,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync respectively. Item #11 describes a hard disk image; in this case, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync additional <computeroutput>--controller</computeroutput> option indicates
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which item the disk image should be connected to, with the default coming
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync from the OVF file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You can combine several items for the same virtual system behind the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync same <computeroutput>--vsys</computeroutput> option. For example, to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync import a machine as described in the OVF, but without the sound card and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync without the USB controller, and with the disk image connected to the IDE
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync controller instead of the SCSI controller, use this:<screen>VBoxManage import WindowsXp.ovf
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command exports one or more virtual machines from VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync into a virtual appliance in OVF format, including copying their virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disk images to compressed VMDK. See <xref linkend="ovf" /> for an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync introduction to appliances.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>export</computeroutput> command is simple to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use: list the machine (or the machines) that you would like to export to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the same OVF file and specify the target OVF file after an additional
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-o</computeroutput> option. Note that the directory of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync target OVF file will also receive the exported disk images in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync compressed VMDK format (regardless of the original format) and should have
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enough disk space left for them.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Beside a simple export of a given virtual machine, you can append
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync several product information to the appliance file. Use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--version</computeroutput> to specify this additional
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information. For legal reasons you may add a license text or the content
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of a license file by using the <computeroutput>--eula</computeroutput> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--eulafile</computeroutput> option respectively. As with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync OVF import, you must use the <computeroutput>--vsys X</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync option to direct the previously mentioned options to the correct virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For virtualization products which aren't fully compatible with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync OVF standard 1.0 you can enable a OVF 0.9 legacy mode with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--legacy09</computeroutput> option.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command starts a virtual machine that is currently in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "Powered off" or "Saved" states.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This is provided for backwards compatibility only. We recommend to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync start virtual machines directly by running the respective front-end, as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you might otherwise miss important error and state information that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox may display on the console. This is especially important for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync front-ends other than <computeroutput>VirtualBox</computeroutput>, our
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync graphical user interface, because those cannot display error messages in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a popup window. See <xref linkend="vboxheadless" /> for more
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync information.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The optional <computeroutput>--type</computeroutput> specifier
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync determines whether the machine will be started in a window (GUI mode,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which is the default) or whether the output should go through
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>VBoxHeadless</computeroutput>, with VRDE enabled or not;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync see <xref linkend="vboxheadless" /> for more information. The list of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync types is subject to change, and it's not guaranteed that all types are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync accepted by any product variant.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glosslist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Starts a VM showing a GUI window. This is the default.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Starts a VM without a window for remote display only.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glosslist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>controlvm</computeroutput> subcommand allows you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to change the state of a virtual machine that is currently running. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following can be specified:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>VBoxManage controlvm <vm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync pause</computeroutput> temporarily puts a virtual machine on hold,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync without changing its state for good. The VM window will be painted
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in gray to indicate that the VM is currently paused. (This is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync equivalent to selecting the "Pause" item in the "Machine" menu of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the GUI.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Use <computeroutput>VBoxManage controlvm <vm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync resume</computeroutput> to undo a previous
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>pause</computeroutput> command. (This is equivalent
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to selecting the "Resume" item in the "Machine" menu of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync GUI.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>VBoxManage controlvm <vm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync reset</computeroutput> has the same effect on a virtual machine as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync pressing the "Reset" button on a real computer: a cold reboot of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machine, which will restart and boot the guest operating
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync system again immediately. The state of the VM is not saved
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync beforehand, and data may be lost. (This is equivalent to selecting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the "Reset" item in the "Machine" menu of the GUI.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>VBoxManage controlvm <vm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync poweroff</computeroutput> has the same effect on a virtual machine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync as pulling the power cable on a real computer. Again, the state of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VM is not saved beforehand, and data may be lost. (This is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync equivalent to selecting the "Close" item in the "Machine" menu of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the GUI or pressing the window's close button, and then selecting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "Power off the machine" in the dialog.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>After this, the VM's state will be "Powered off". From there,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync it can be started again; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>VBoxManage controlvm <vm>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync savestate</computeroutput> will save the current state of the VM to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disk and then stop the VM. (This is equivalent to selecting the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "Close" item in the "Machine" menu of the GUI or pressing the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync window's close button, and then selecting "Save the machine state"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in the dialog.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>After this, the VM's state will be "Saved". From there, it can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be started again; see <xref linkend="vboxmanage-startvm" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>VBoxManage controlvm <vm> teleport
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync --hostname <name> --port <port> [--password
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <password>]</computeroutput> makes the machine the source of a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync teleporting operation and initiates a teleport to the given target.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync See <xref linkend="teleporting" /> for an introduction. If the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync optional password is specified, it must match the password that was
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync given to the <computeroutput>modifyvm</computeroutput> command for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the target machine; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="vboxmanage-modifyvm-teleport" /> for details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>A few extra options are available with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>controlvm</computeroutput> that do not directly affect the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VM's running state:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>setlinkstate<1-N></computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operation connects or disconnects virtual network cables from their
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync network interfaces.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync null|nat|bridged|intnet|hostonly|generic</computeroutput>: With this, you can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync set, for each of the VM's virtual network cards, what type of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync networking should be available. They can be not connected to the host
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (<computeroutput>null</computeroutput>), use network address
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync translation (<computeroutput>nat</computeroutput>), bridged networking
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (<computeroutput>bridged</computeroutput>) or communicate with other
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machines using internal networking
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (<computeroutput>intnet</computeroutput>) or host-only networking
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (<computeroutput>hostonly</computeroutput>) or access to rarely used
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (<computeroutput>generic</computeroutput>). These options correspond
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to the modes which are described in detail in <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>usbattach</computeroutput> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>usbdettach</computeroutput> make host USB devices
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync visible to the virtual machine on the fly, without the need for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync creating filters first. The USB devices can be specified by UUID
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (unique identifier) or by address on the host system.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync usbhost</computeroutput> to locate this information.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>vrde on|off</computeroutput> lets you enable or
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync disable the VRDE server, if it is installed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>vrdeport default|<ports></computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync changes the port or a range of ports that the VRDE server can bind to;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "default" or "0" means port 3389, the standard port for RDP. For
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync details, see the description for the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--vrdeport</computeroutput> option in <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>setvideomodehint</computeroutput> requests that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the guest system change to a particular video mode. This requires that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the Guest Additions be installed, and will not work for all guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync systems.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>screenshotpng</computeroutput> takes a screenshot
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync of the guest display and saves it in PNG format.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>setcredentials</computeroutput> operation is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync used for remote logons in Windows guests. For details, please refer to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>guestmemoryballoon</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operation changes the size of the guest memory balloon, that is,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync memory allocated by the VirtualBox Guest Additions from the guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operating system and returned to the hypervisor for re-use by other
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machines. This must be specified in megabytes. For details,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <1-100></computeroutput>: This operation controls how much cpu
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync time a virtual CPU can use. A value of 50 implies a single virtual CPU
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync can use up to 50% of a single host CPU.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command discards the saved state of a virtual machine which is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync not currently running, which will cause its operating system to restart
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync next time you start it. This is the equivalent of pulling out the power
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync cable on a physical machine, and should be avoided if possible.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>If you have a saved state file (<computeroutput>.sav</computeroutput>)
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync that is seperate from the VM configuration, you can use this command to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "adopt" the file. This will change the VM to saved state and when you
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync start it, VirtualBox will attempt to restore it from the saved state file
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync you indicated. This command should only be used in special setups.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command is used to control snapshots from the command line. A
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync snapshot consists of a complete copy of the virtual machine settings,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync copied at the time when the snapshot was taken, and optionally a virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine saved state file if the snapshot was taken while the machine was
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync running. After a snapshot has been taken, VirtualBox creates differencing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hard disk for each normal hard disk associated with the machine so that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync when a snapshot is restored, the contents of the virtual machine's virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hard disks can be quickly reset by simply dropping the pre-existing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync differencing files.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>take</computeroutput> operation takes a snapshot
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the current state of the virtual machine. You must supply a name for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the snapshot and can optionally supply a description. The new snapshot is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync inserted into the snapshots tree as a child of the current snapshot and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync then becomes the new current snapshot.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>delete</computeroutput> operation deletes a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync snapshot (specified by name or by UUID). This can take a while to finish
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync since the differencing images associated with the snapshot might need to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be merged with their child differencing images.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>restore</computeroutput> operation will restore
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the given snapshot (specified by name or by UUID) by resetting the virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine's settings and current state to that of the snapshot. The previous
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync current state of the machine will be lost. After this, the given snapshot
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync becomes the new "current" snapshot so that subsequent snapshots are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync inserted under the snapshot from which was restored.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>restorecurrent</computeroutput> operation is a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync shortcut to restore the current snapshot (i.e. the snapshot from which the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync current state is derived). This subcommand is equivalent to using the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "restore" subcommand with the name or UUID of the current snapshot, except
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that it avoids the extra step of determining that name or UUID.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With the <computeroutput>edit</computeroutput> operation, you can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync change the name or description of an existing snapshot.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With the <computeroutput>showvminfo</computeroutput> operation, you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can view the virtual machine settings that were stored with an existing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync snapshot.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This commands removes a hard disk, DVD or floppy image from a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VirtualBox media registry.<footnote>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Before VirtualBox 4.0, it was necessary to call VBoxManage
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync openmedium before a medium could be attached to a virtual machine;
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync that call "registered" the medium with the global VirtualBox media
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync registry. With VirtualBox 4.0 this is no longer necessary; media are
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync added to media registries automatically. The "closemedium" call has
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync been retained, however, to allow for explicitly removing a medium from
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync a registry.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Optionally, you can request that the image be deleted. You will get
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync appropriate diagnostics that the deletion failed, however the image will
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync become unregistered in any case.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title id="vboxmanage-storageattach">VBoxManage storageattach</title>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This command attaches/modifies/removes a storage medium connected to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync a storage controller that was previously added with the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>storagectl</computeroutput> command (see the previous
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync section). The syntax is as follows:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage storageattach <uuid|vmname>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync --storagectl <name>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--port <number>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--device <number>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--type dvddrive|hdd|fdd]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--medium none|emptydrive|
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <uuid>|<filename>|host:<drive>|iscsi]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--mtype normal|writethrough|immutable|shareable]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--comment <text>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--setuuid <uuid>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--setparentuuid <uuid>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--passthrough on|off]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--tempeject on|off]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--bandwidthgroup name|none]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--forceunmount]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--server <name>|<ip>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--target <target>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--tport <port>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--lun <lun>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--encodedlun <lun>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--username <username>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--password <password>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>A number of parameters are commonly required; the ones at the end of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the list are required only for iSCSI targets (see below).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Name of the storage controller. Mandatory. The list of the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync storage controllers currently attached to a VM can be obtained
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync with <computeroutput>VBoxManage showvminfo</computeroutput>; see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The number of the storage controller's port which is to be
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync modified. Mandatory, unless the storage controller has only a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync single port.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The number of the port's device which is to be modified.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Mandatory, unless the storage controller has only a single device
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync per port.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Define the type of the drive to which the medium is being
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync attached/detached/modified. This argument can only be omitted if
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the type of medium can be determined from either the medium given
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync with the <computeroutput>--medium</computeroutput> argument or
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync from a previous medium attachment.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Specifies what is to be attached. The following values are
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync supported:<itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>"none": Any existing device should be removed from the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync given slot.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>"emptydrive": For a virtual DVD or floppy drive only,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync this makes the device slot behaves like a removeable drive
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync into which no media has been inserted.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>If a UUID is specified, it must be the UUID of a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync storage medium that is already known to VirtualBox (e.g.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync because it has been attached to another virtual machine).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync See <xref linkend="vboxmanage-list" /> for how to list known
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync media. This medium is then attached to the given device
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync slot.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>If a filename is specified, it must be the full path
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync of an existing disk image (ISO, RAW, VDI, VMDK or other),
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync which is then attached to the given device slot.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>"host:<drive>": For a virtual DVD or floppy
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync drive only, this connects the given device slot to the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync specified DVD or floppy drive on the host computer.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>"iscsi": For virtual hard disks only, this allows for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync specifying an iSCSI target. In this case, more parameters
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync must be given; see below.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Some of the above changes, in particular for removeable
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync media (floppies and CDs/DVDs), can be effected while a VM is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync running. Others (device changes or changes in hard disk device
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync slots) require the VM to be powered off.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Defines how this medium behaves with respect to snapshots
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync and write operations. See <xref linkend="hdimagewrites" /> for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Any description that you want to have stored with this
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync medium (optional; for example, for an iSCSI target, "Big storage
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync server downstairs"). This is purely descriptive and not needed for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the medium to function correctly.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Modifies the UUID or parent UUID of a medium before
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync attaching it to a VM. This is an expert option. Inappropriate use
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync can make the medium unusable or lead to broken VM configurations
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync if any other VM is referring to the same media already. The most
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync frequently used variant is <code>--setuuid ""</code>, which assigns
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync a new (random) UUID to an image. This is useful to resolve the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync duplicate UUID errors if one duplicated an image using file copy
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync utilities.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For a virtual DVD drive only, you can enable DVD writing
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync support (currently experimental; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For a virtual DVD drive only, you can configure the behavior
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync for guest-triggered medium eject. If this is set to "on", the eject
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync has only temporary effects. If the VM is powered off and restarted
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the originally configured medium will be still in the drive.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Sets the bandwidth group to use for the given device; see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For a virtual DVD or floppy drive only, this forcibly
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy even if
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the previous one is locked down by the guest for reading. Again,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync see <xref linkend="storage-cds" /> for details.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>When "iscsi" is used with the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--medium</computeroutput> parameter for iSCSI support --
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync see <xref linkend="storage-iscsi" /> --, additional parameters must or can
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync be used:<glosslist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The host name or IP address of the iSCSI target;
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync required.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Target name string. This is determined by the iSCSI target
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync and used to identify the storage resource; required.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>TCP/IP port number of the iSCSI service on the target
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (optional).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Logical Unit Number of the target resource (optional).
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Often, this value is zero.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Username and password for target authentication, if required
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (optional).<note>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Currently, username and password are stored without
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync encryption (i.e. in clear text) in the XML machine
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync configuration file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>If specified, connect to the iSCSI target via Internal
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Networking. This needs further configuration which is described in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This command attaches/modifies/removes a storage controller. After
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync this, virtual media can be attached to the controller with the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>storageattach</computeroutput> command (see the next
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync section).</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage storagectl <uuid|vmname>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync --name <name>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--controller <LsiLogic|LSILogicSAS|BusLogic|
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync IntelAhci|PIIX3|PIIX4|ICH6|I82078>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--sataideemulation<1-4> <1-30>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--sataportcount <1-30>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--hostiocache on|off]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--bootable on|off]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--remove]</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Name of the storage controller. Mandatory.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Define the type of the system bus to which the storage
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync controller must be connected.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Allows to choose the type of chipset being emulated for the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync given storage controller.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This specifies which SATA ports should operate in IDE
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync emulation mode. As explained in <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync linkend="harddiskcontrollers" />, by default, this is the case for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync SATA ports 1-4; with this command, you can map four IDE channels
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to any of the 30 supported SATA ports.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This determines how many ports the SATA controller should
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync support.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Configures the use of the host I/O cache for all disk images
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync attached to this storage controller. For details, please see <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Selects whether this controller is bootable.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Removes the storage controller from the VM config.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This command creates/deletes/modifies bandwidth groups of the given
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync virtual machine:<screen>VBoxManage bandwidthctl <uuid|vmname>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync --name <name>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--add disk
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>See <xref linkend="storage-bandwidth-limit" /> for an introduction
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to bandwidth limits. The parameters mean:<glosslist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Name of the bandwidth group. Mandatory.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Creates a new bandwdith group with the given type.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Deletes a bandwdith group if it isn't used anymore.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Sets the limit for the given group to the specified amount.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Can be changed while the VM is running.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This command shows information about a virtual hard disk image,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync notably its size, its size on disk, its type and the virtual machines
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync which use it.<note>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For compatibility with earlier versions of VirtualBox, the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "showvdiinfo" command is also supported and mapped internally to the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "showhdinfo" command.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The disk image must be specified either by its UUID (if the medium
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync is registered) or by its filename. Registered images can be listed by
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>VBoxManage list hdds</computeroutput> (see <xref linkend="vboxmanage-list" />
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync for more information). A filename must be specified as valid path, either
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync as an absolute path or as a relative path starting from the current
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync directory.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This command creates a new virtual hard disk image. The syntax is as
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync follows:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage createhd --filename <filename>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync --size <megabytes>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--format VDI|VMDK|VHD] (default: VDI)
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--variant Standard,Fixed,Split2G,Stream,ESX]</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Allows to choose a file name. Mandatory.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Allows to define the image capacity, in 1 MiB units.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Mandatory.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Allows to choose a file format for the output file different
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync from the file format of the input file.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Allows to choose a file format variant for the output file.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync It is a comma-separated list of variant flags. Not all
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync combinations are supported, and specifying inconsistent flags will
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync result in an error message.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For compatibility with earlier versions of VirtualBox, the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "createvdi" command is also supported and mapped internally to the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "createhd" command.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>With the <computeroutput>modifyhd</computeroutput> command, you can
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync change the characteristics of a disk image after it has been
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync created:<screen>VBoxManage modifyhd <uuid>|<filename>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--type normal|writethrough|immutable|shareable|
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync readonly|multiattach]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--autoreset on|off]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--compact]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--resize <megabytes>|--resizebyte <bytes>]</screen><note>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Despite the "hd" in the subcommand name, the command works with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync all disk images, not only hard disks. For compatibility with earlier
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync versions of VirtualBox, the "modifyvdi" command is also supported and
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync mapped internally to the "modifyhd" command.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The disk image to modify must be specified either by its UUID
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (if the medium is registered) or by its filename. Registered images
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (see <xref linkend="vboxmanage-list" /> for more information).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync A filename must be specified as valid path, either as an absolute path
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync or as a relative path starting from the current directory.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The following options are available:<itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>With the <computeroutput>--type</computeroutput> argument, you
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync can change the type of an existing image between the normal,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync immutable, write-through and other modes; see <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For immutable (differencing) hard disks only, the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--autoreset on|off</computeroutput> option
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync determines whether the disk is automatically reset on every VM
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync startup (again, see <xref linkend="hdimagewrites" />). The default
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync is "on".</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>With the <computeroutput>--compact</computeroutput> option,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync can be used to compact disk images, i.e. remove blocks that only
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync contains zeroes. This will shrink a dynamically allocated image
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync again; it will reduce the <emphasis>physical</emphasis> size of the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync image without affecting the logical size of the virtual disk.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Compaction works both for base images and for diff images created as
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync part of a snapshot.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For this operation to be effective, it is required that free
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync space in the guest system first be zeroed out using a suitable
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync software tool. For Windows guests, you can use the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>sdelete</computeroutput> tool provided by Microsoft.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Execute <computeroutput>sdelete -c</computeroutput> in the guest to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync zero the free disk space before compressing the virtual disk
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync image. For Linux, use the <code>zerofree</code> utility which
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Please note that compacting is currently only available for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VDI images. A similar effect can be achieved by zeroing out free
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync blocks and then cloning the disk to any other dynamically allocated
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync format. You can use this workaround until compacting is also
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync supported for disk formats other than VDI.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>--resize</computeroutput> option allows you
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to change the capacity of an existing image; this adjusts the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <emphasis>logical</emphasis> size of a virtual disk without affecting
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the physical size much.<footnote>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Image resizing was added with VirtualBox 4.0.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </footnote> This currently works only for expanding the capacity of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VDI and VHD formats, and only for the dynamically allocated variants.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync For example, if you originally created a 10G disk which is now full,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync you can use the <computeroutput>--resize 15360</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync command to add 5 GByte more space to the virtual disk without
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync having to create a new image and copy all data from within a virtual
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync machine.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This command duplicates a registered virtual hard disk image to a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync new image file with a new unique identifier (UUID). The new image can be
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync transferred to another host system or imported into VirtualBox again using
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the Virtual Media Manager; see <xref linkend="vdis" /> and <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync linkend="cloningvdis" />. The syntax is as follows:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage clonehd <uuid>|<filename> <outputfile>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--format VDI|VMDK|VHD|RAW|<other>]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--variant Standard,Fixed,Split2G,Stream,ESX]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--existing]</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The disk image to clone as well as the target image must be described
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync either by its UUIDs (if the mediums are registered) or by its filename.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Registered images can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (see <xref linkend="vboxmanage-list" /> for more information).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync A filename must be specified as valid path, either as an absolute path or
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync as a relative path starting from the current directory.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The following options are available:<glosslist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Allow to choose a file format for the output file different
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync from the file format of the input file.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Allow to choose a file format variant for the output file.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync It is a comma-separated list of variant flags. Not all
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync combinations are supported, and specifying inconsistent flags will
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync result in an error message.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Perform the clone operation to an already existing
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync destination medium. Only the portion of the source medium which
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync fits into the destination medium is copied. This means if the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync destination medium is smaller than the source only a part of it is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync copied, and if the destination medium is larger than the source
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the remaining part of the destination medium is unchanged.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For compatibility with earlier versions of VirtualBox, the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "clonevdi" command is also supported and mapped internally to the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "clonehd" command.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This command converts a raw disk image to a VirtualBox Disk Image
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync (VDI) file. The syntax is as follows:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage convertfromraw <filename> <outputfile>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--format VDI|VMDK|VHD]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--variant Standard,Fixed,Split2G,Stream,ESX]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsyncVBoxManage convertfromraw stdin <outputfile> <bytes>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--format VDI|VMDK|VHD]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--variant Standard,Fixed,Split2G,Stream,ESX]</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Select the disk image format to create. Default is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VDI.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Allow to choose a file format variant for the output file.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync It is a comma-separated list of variant flags. Not all
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync combinations are supported, and specifying inconsistent flags will
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync result in an error message.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glosslist> The second form forces VBoxManage to read the content for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the disk image from standard input (useful for using that command in a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync pipe).</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>For compatibility with earlier versions of VirtualBox, the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "convertdd" command is also supported and mapped internally to the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "convertfromraw" command.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>VBoxManage getextradata/setextradata</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>These commands let you attach and retrieve string data to a virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine or to a VirtualBox configuration (by specifying
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>global</computeroutput> instead of a virtual machine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync name). You must specify a key (as a text string) to associate the data
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with, which you can later use to retrieve it. For example:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxManage setextradata SUSE10 installdate 2006.02.02</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>would associate the string "2006.01.01" with the key installdate for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the virtual machine Fedora5, and "2006.02.02" on the machine SUSE10. You
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync could retrieve the information as follows:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage getextradata Fedora5 installdate</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncAll rights reserved.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncValue: 2006.01.01</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command is used to change global settings which affect the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync entire VirtualBox installation. Some of these correspond to the settings
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in the "Global settings" dialog in the graphical user interface. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following properties are available:<glosslist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This specifies the default folder in which virtual machine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync definitions are kept; see <xref linkend="vboxconfigdata" /> for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This specifies which library to use when "external"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync authentication has been selected for a particular virtual machine;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync see <xref linkend="vbox-auth" /> for details.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This specifies which library the web service uses to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync authenticate users. For details about the VirtualBox web service,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync please refer to the separate VirtualBox SDK reference (see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This specifies which library implements the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Remote Desktop Extension.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This selects whether or not hardware virtualization support
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is enabled by default.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <title>VBoxManage usbfilter add/modify/remove</title>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>usbfilter</computeroutput> commands are used for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync working with USB filters in virtual machines, or global filters which
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync affect the whole VirtualBox setup. Global filters are applied before
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync machine-specific filters, and may be used to prevent devices from being
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync captured by any virtual machine. Global filters are always applied in a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync particular order, and only the first filter which fits a device is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync applied. So for example, if the first global filter says to hold (make
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync available) a particular Kingston memory stick device and the second to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync ignore all Kingston devices, that memory stick will be available to any
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync machine with an appropriate filter, but no other Kingston device
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync will.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>When creating a USB filter using <computeroutput>usbfilter
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync add</computeroutput>, you must supply three or four mandatory parameters.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync The index specifies the position in the list at which the filter should be
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync placed. If there is already a filter at that position, then it and the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync following ones will be shifted back one place. Otherwise the new filter
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync will be added onto the end of the list. The
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>target</computeroutput> parameter selects the virtual
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync machine that the filter should be attached to or use "global" to apply it
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to all virtual machines. <computeroutput>name</computeroutput> is a name
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync for the new filter and for global filters,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>action</computeroutput> says whether to allow machines
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync access to devices that fit the filter description ("hold") or not to give
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync them access ("ignore"). In addition, you should specify parameters to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync filter by. You can find the parameters for devices attached to your system
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync using <computeroutput>VBoxManage list usbhost</computeroutput>. Finally,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync you can specify whether the filter should be active, and for local
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync filters, whether they are for local devices, remote (over an RDP
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync connection) or either.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>When you modify a USB filter using <computeroutput>usbfilter
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync modify</computeroutput>, you must specify the filter by index (see the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync output of <computeroutput>VBoxManage list usbfilters</computeroutput> to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync find global filter indexes and that of <computeroutput>VBoxManage
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync showvminfo</computeroutput> to find indexes for individual machines) and
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync by target, which is either a virtual machine or "global". The properties
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync which can be changed are the same as for <computeroutput>usbfilter
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync add</computeroutput>. To remove a filter, use <computeroutput>usbfilter
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync remove</computeroutput> and specify the index and the target.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This command allows you to share folders on the host computer with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync guest operating systems. For this, the guest systems must have a version
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync of the VirtualBox Guest Additions installed which supports this
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync functionality.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Shared folders are described in detail in <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The "guestproperty" commands allow you to get or set properties of a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync running virtual machine. Please see <xref linkend="guestadd-guestprops" />
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync for an introduction. As explained there, guest properties are arbitrary
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync key/value string pairs which can be written to and read from by either the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync guest or the host, so they can be used as a low-volume communication
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync channel for strings, provided that a guest is running and has the Guest
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Additions installed. In addition, a number of values whose keys begin with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "/VirtualBox/" are automatically set and maintained by the Guest
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Additions.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The following subcommands are available (where
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput><vm></computeroutput>, in each case, can either be a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>enumerate <vm> [--patterns
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <pattern>]</computeroutput>: This lists all the guest
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync properties that are available for the given VM, including the value.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This list will be very limited if the guest's service process cannot
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync be contacted, e.g. because the VM is not running or the Guest
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Additions are not installed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>If <computeroutput>--patterns <pattern></computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync is specified, it acts as a filter to only list properties that match
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the given pattern. The pattern can contain the following wildcard
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync characters:<itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>*</computeroutput> (asterisk):
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync represents any number of characters; for example,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "<computeroutput>/VirtualBox*</computeroutput>" would match
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync all properties beginning with "/VirtualBox".</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>?</computeroutput> (question mark):
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync represents a single arbitrary character; for example,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "<computeroutput>fo?</computeroutput>" would match both "foo"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync and "for".</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>|</computeroutput> (pipe symbol): can be
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync used to specify multiple alternative patterns; for example,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "<computeroutput>s*|t*</computeroutput>" would match anything
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync starting with either "s" or "t".</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>get <vm></computeroutput>: This
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync retrieves the value of a single property only. If the property
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync cannot be found (e.g. because the guest is not running), this will
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>set <vm> <property> [<value>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--flags <flags>]]</computeroutput>: This allows you to set a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync guest property by specifying the key and value. If
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput><value></computeroutput> is omitted, the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync property is deleted. With <computeroutput>--flags</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync you can optionally specify additional behavior (you can combine
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync several by separating them with commas):<itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>TRANSIENT</computeroutput>: the value
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync will not be stored with the VM data when the VM exits;</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>TRANSRESET</computeroutput>: the value
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync will be deleted as soon as the VM restarts and/or exits;</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>RDONLYGUEST</computeroutput>: the value
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync can only be changed by the host, but the guest can only read
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>RDONLYHOST</computeroutput>: reversely,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the value can only be changed by the guest, but the host can
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync only read it;</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>READONLY</computeroutput>: a combination
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync of the two, the value cannot be changed at all.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>wait <vm> <pattern> --timeout
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <timeout></computeroutput>: This waits for a particular value
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync described by "pattern" to change or to be deleted or created. The
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync pattern rules are the same as for the "enumerate" subcommand
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync above.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The "guestcontrol" commands allow you to control certain things
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync inside a guest from the host. Please see <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync linkend="guestadd-guestcontrol" /> for an introduction.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage guestcontrol <command></screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The following subcommands are available (where
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput><vm></computeroutput>, in each case, can either be a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>execute</computeroutput>, which allows for
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync executing a program/script (process) which is already installed and
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync runnable on the guest. This command only works while a VM is up and
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync running and has the following syntax:</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage guestcontrol <vmname>|<uuid> exec[ute]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync --image <path to program>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync --username <name> --password <password>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--dos2unix]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--environment "<NAME>=<VALUE> [<NAME>=<VALUE>]"]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--timeout <msec>] [--unix2dos] [--verbose]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--wait-exit] [--wait-stdout] [--wait-stderr]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync -- [[<argument1>] ... [<argumentN>]]</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossterm>--image "<path to program>"</glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Absolute path and process name of process to execute
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync in the guest, e.g.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>C:\Windows\System32\calc.exe</computeroutput></para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Name of the user the process should run under. This
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync user must exist on the guest OS.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Password of the user account specified with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--username</computeroutput>. If not given,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync an empty password is assumed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Converts output from DOS/Windows guests to UNIX-compatible
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync line endings (CR + LF -> LF). Not implemented yet.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossterm>--environment
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync "<NAME>=<VALUE>"</glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>One or more environment variables to be set or
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync unset.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>By default, the new process in the guest will be
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync created with the standard environment of the guest OS. This
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync option allows for modifying that environment. To set/modify
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync a variable, a pair of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>NAME=VALUE</computeroutput> must be
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync specified; to unset a certain variable, the name with no
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync value must set, e.g.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Arguments containing spaces must be enclosed in
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync quotation marks. More than one
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--environment</computeroutput> at a time can
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync be specified to keep the command line tidy.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Value (in milliseconds) that specifies the time how
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync long the started process is allowed to run and how long
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VBoxManage waits for getting output from that process. If no
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync timeout is specified, VBoxManage will wait forever until the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync started process ends or an error occured.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Converts output from a UNIX/Linux guests to DOS-/Windows-compatible
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync line endings (LF -> CR + LF). Not implemented yet.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Waits until the process ends and outputs its
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Waits until the process ends and outputs its
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync exit code along with the exit reason/flags. While waiting
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VBoxManage retrieves the process output collected from stdout.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Waits until the process ends and outputs its
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync exit code along with the exit reason/flags. While waiting
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VBoxManage retrieves the process output collected from stderr.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossterm>[-- [<argument1s>] ... [<argumentNs>]]</glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>One or more arguments to pass to the process being
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync executed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Arguments containing spaces must be enclosed in
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync quotation marks.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>On Windows there are certain limitations for graphical
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync applications; please see <xref linkend="KnownIssues" /> for more
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync information.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </note> Examples: <screen>VBoxManage --nologo guestcontrol "My VM" execute --image "/bin/ls"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync --username foo --password bar --wait-exit --wait-stdout -- -l /usr</screen> <screen>VBoxManage --nologo guestcontrol "My VM" execute --image "c:\\windows\\system32\\ipconfig.exe"
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync --username foo --password bar --wait-exit --wait-stdout</screen> Note that
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the double backslashes in the second example are only required on
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Unix hosts.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Starting at VirtualBox 4.1.2 guest process execution by default is limited
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to serve up to 5 guest processes at a time. If a new guest process gets started
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync which would exceed this limit, the oldest not running guest process will be discarded
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync in order to be able to run that new process. Also, retrieving output from this
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync old guest process will not be possible anymore then. If all 5 guest processes
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync are still active and running, starting a new guest process will result in an
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync appropriate error message.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To raise or lower the guest process execution limit, either the guest
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync property <computerouptut>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computerouptut>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync or VBoxService' command line by specifying <computeroutput>--control-procs-max-kept</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync guest processes, a value of <computeroutput>0</computeroutput> needs to be set (not recommended).</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>copyto</computeroutput>, which allows copying
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync files from the host to the guest (only with installed Guest
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Additions 4.0 and later).</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage guestcontrol <vmname>|<uuid> copyto|cp
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <source on host> <destination on guest>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync --username <name> --password <password>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--dryrun] [--follow] [--recursive] [--verbose]</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Absolute path of source file(s) on host to copy over
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync to the guest, e.g.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This also can be a wildcard expression, e.g.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>C:\Windows\System32\*.dll</computeroutput></para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Name of the user the copy process should run under.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This user must exist on the guest OS.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Password of the user account specified with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--username</computeroutput>. If not given,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync an empty password is assumed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Tells VBoxManage to only perform a dry run instead of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync really copying files to the guest.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Enables following symlinks on the host's
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync source.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Recursively copies files/directories of the specified
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync source.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Additional flags to set. This is not used at the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync moment.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>createdirectory</computeroutput>, which allows
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync copying files from the host to the guest (only with installed Guest
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Additions 4.0 and later).</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage guestcontrol <vmname>|<uuid> createdir[ectory]|mkdir|md
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <directory to create on guest>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--username "<name>"] [--password "<password>"]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--parents] [--mode <mode>] [--verbose]</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossterm>directory to create on guest</glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Absolute path of directory/directories to create on
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync guest, e.g. <computeroutput>D:\Foo\Bar</computeroutput>.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Parent directories need to exist (e.g. in this example
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>D:\Foo</computeroutput>) when switch
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--parents</computeroutput> is omitted. The
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync specified user must have appropriate rights to create the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync specified directory.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Name of the user the copy process should run under.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This user must exist on the guest OS.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Password of the user account specified with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--username</computeroutput>. If not given,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync an empty password is assumed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Also creates not yet existing parent directories of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the specified directory, e.g. if the directory
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>D:\Foo\Bar</computeroutput> does not exist
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync yet it will be created. Without specifying
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--parent</computeroutput> the action would
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync have failed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Sets the permission mode of the specified directory.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync Only octal modes (e.g.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>0755</computeroutput>) are supported right
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync now.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>stat</computeroutput>, which displays file
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync or file system status on the guest.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage guestcontrol <vmname>|<uuid> stat
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <file element(s) to check on guest>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--username "<name>"] [--password "<password>"]
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--verbose]</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossterm>file element(s) to check on guest</glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Absolute path of directory/directories to check on
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync guest, e.g. <computeroutput>/home/foo/a.out</computeroutput>.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync The specified user must have appropriate rights to access
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the given file element(s).</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Name of the user the copy process should run under.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync This user must exist on the guest OS.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Password of the user account specified with
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--username</computeroutput>. If not given,
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync an empty password is assumed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para><computeroutput>updateadditions</computeroutput>, which allows
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync for updating an already installed Guest Additions version on the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync guest (only already installed Guest Additions 4.0 and later).</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <screen>VBoxManage guestcontrol updateadditions <vmname>|<uuid>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync [--source "<guest additions .ISO file to use>"] [--verbose]</screen>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossterm>--source "<guest additions .ISO file to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync use>"</glossterm>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>Full path to an alternative VirtualBox Guest Additions
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync .ISO file to use for the Guest Additions update.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossdef>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </glossentry>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The "debugvm" commands are for experts who want to tinker with the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync exact details of virtual machine execution. Like the VM debugger described
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync in <xref linkend="debugger" />, these commands are only useful if you are
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync very familiar with the details of the PC architecture and how to debug
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync software.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The subcommands of "debugvm" all operate on a running virtual
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync machine. The following are available:<itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>With <computeroutput>dumpguestcore --filename
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <name></computeroutput>, you can create a system dump of the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync running VM, which will be written into the given file. This file
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync will have the standard ELF core format (with custom sections); see
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This corresponds to the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>writecore</computeroutput> command in the debugger.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>info</computeroutput> command is used to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync display info items relating to the VMM, device emulations and
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync associated drivers. This command takes one or two arguments: the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync name of the info item, optionally followed by a string containing
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync arguments specific to the info item.
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync The <computeroutput>help</computeroutput> info item provides a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync listning of the available items and hints about any optional
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync arguments.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This corresponds to the <computeroutput>info</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync command in the debugger.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>injectnmi</computeroutput> command causes
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync a non-maskable interrupt (NMI) in the guest, which might be useful
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync for certain debugging scenarios. What happens exactly is dependent
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync on the guest operating system, but an NMI can crash the whole guest
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync operating system. Do not use unless you know what you're
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync doing.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>osdetect</computeroutput> command makes the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync VMM's debugger facility (re-)detection the guest operation
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync system.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>This corresponds to the <computeroutput>detect</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync command in the debugger.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>osinfo</computeroutput> command is used to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync display info about the operating system (OS) detected by the VMM's
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync debugger facility.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>getregisters</computeroutput> command is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync used to display CPU and device registers. The command takes a list
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync of registers, each having one of the following forms:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem><computeroutput>register-set.register-name.sub-field</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem><computeroutput>register-set.register-name</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem><computeroutput>cpu-register-name.sub-field</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem><computeroutput>cpu-register-name</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem><computeroutput>all</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync The <computeroutput>all</computeroutput> form will cause all
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync registers to be shown (no sub-fields). The registers names are
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync case-insensitive. When requesting a CPU register the register set
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync can be omitted, it will be selected using the value of the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--cpu</computeroutput> option (defaulting to 0).
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>setregisters</computeroutput> command is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync used to change CPU and device registers. The command takes a list
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync of register assignments, each having one of the following forms:
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem><computeroutput>register-set.register-name.sub-field=value</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem><computeroutput>register-set.register-name=value</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem><computeroutput>cpu-register-name.sub-field=value</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <listitem><computeroutput>cpu-register-name=value</computeroutput></listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </itemizedlist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync The value format should be in the same style as what
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>getregisters</computeroutput> displays, with the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync exception that both octal and decimal can be used instead of
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync hexadecimal. The register naming and the default CPU register set
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync are handled the same way as with the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>getregisters</computeroutput> command.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The <computeroutput>statistics</computeroutput> command can be
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync used to display VMM statistics on the command line. The
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--reset</computeroutput> option will reset
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync statistics. The affected statistics can be filtered with the
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--pattern</computeroutput> option, which accepts
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync DOS/NT-style wildcards (<computeroutput>?</computeroutput> and
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This command supports monitoring the usage of system resources.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Resources are represented by various metrics associated with the host
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync system or a particular VM. For example, the host system has a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>CPU/Load/User</computeroutput> metric that shows the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync percentage of time CPUs spend executing in user mode over a specific
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync sampling period.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Metric data is collected and retained internally; it may be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync retrieved at any time with the <computeroutput>VBoxManage metrics
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync query</computeroutput> subcommand. The data is available as long as the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync background <computeroutput>VBoxSVC</computeroutput> process is alive. That
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync process terminates shortly after all VMs and frontends have been
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync closed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>By default no metrics are collected at all. Metrics collection does
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync not start until <computeroutput>VBoxManage metrics setup</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is invoked with a proper sampling interval and the number of metrics to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync retained. The interval is measured in seconds. For example, to enable
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync collecting the host processor and memory usage metrics every second and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync keeping the 5 most current samples, the following command can be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync used:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Metric collection can only be enabled for started VMs. Collected
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data and collection settings for a particular VM will disappear as soon as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync it shuts down. Use <computeroutput>VBoxManage metrics list
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </computeroutput> subcommand to see which metrics are currently available.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync You can also use <computeroutput>--list</computeroutput> option with any
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync subcommand that modifies metric settings to find out which metrics were
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync affected.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Note that the <computeroutput>VBoxManage metrics
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync setup</computeroutput> subcommand discards all samples that may have been
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync previously collected for the specified set of objects and metrics.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To enable or disable metrics collection without discarding the data
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage metrics enable</computeroutput> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage metrics disable</computeroutput> subcommands
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can be used. Note that these subcommands expect metrics, not submetrics,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync like <code>CPU/Load</code> or <code>RAM/Usage</code> as parameters. In
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync other words enabling <code>CPU/Load/User</code> while disabling
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <code>CPU/Load/Kernel</code> is not supported.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The host and VMs have different sets of associated metrics.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Available metrics can be listed with <computeroutput>VBoxManage metrics
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>A complete metric name may include an aggregate function. The name
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync has the following form:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync For example, <computeroutput>RAM/Usage/Free:min</computeroutput> stands
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the minimum amount of available memory over all retained data if
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync applied to the host object.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Subcommands may apply to all objects and metrics or can be limited
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to one object or/and a list of metrics. If no objects or metrics are given
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in the parameters, the subcommands will apply to all available metrics of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync all objects. You may use an asterisk
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ("<computeroutput>*</computeroutput>") to explicitly specify that the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync command should be applied to all objects or metrics. Use "host" as the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object name to limit the scope of the command to host-related metrics. To
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync limit the scope to a subset of metrics, use a metric list with names
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync separated by commas.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For example, to query metric data on the CPU time spent in user and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync kernel modes by the virtual machine named "test", you can use the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following command:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following list summarizes the available subcommands:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glosslist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This subcommand shows the parameters of the currently existing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync metrics. Note that VM-specific metrics are only available when a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync particular VM is running.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This subcommand sets the interval between taking two samples
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of metric data and the number of samples retained internally. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync retained data is available for displaying with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <code>query</code> subcommand. The <computeroutput>--list
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </computeroutput> option shows which metrics have been modified as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the result of the command execution.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This subcommand "resumes" data collection after it has been
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync stopped with <code>disable</code> subcommand. Note that specifying
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync submetrics as parameters will not enable underlying metrics. Use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--list</computeroutput> to find out if the command
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync did what was expected.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This subcommand "suspends" data collection without affecting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync collection parameters or collected data. Note that specifying
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync submetrics as parameters will not disable underlying metrics. Use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--list</computeroutput> to find out if the command
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync did what was expected.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This subcommand retrieves and displays the currently retained
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync metric data.<note>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <code>query</code> subcommand does not remove or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "flush" retained data. If you query often enough you will see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync how old samples are gradually being "phased out" by new
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync samples.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This subcommand sets the interval between taking two samples
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of metric data and the number of samples retained internally. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync collected data is displayed periodically until Ctrl-C is pressed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync unless the <computeroutput>--detach</computeroutput> option is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync specified. With the <computeroutput>--detach</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync option, this subcommand operates the same way as <code>setup</code>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync does. The <computeroutput>--list</computeroutput> option shows which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync metrics match the specified filter.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossdef>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glossentry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </glosslist>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>With "hostonlyif" you can change the IP configuration of a host-only
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync network interface. For a description of host-only networking, please
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync refer to <xref linkend="network_hostonly" />. Each host-only interface is
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync identified by a name and can either use the internal DHCP server or a
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync manual IP configuration (both IP4 and IP6).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The "dhcpserver" commands allow you to control the DHCP server that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is built into VirtualBox. You may find this useful when using internal or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync host-only networking. (Theoretically, you can enable it for a bridged
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync network as well, but that will likely cause conflicts with other DHCP
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync servers in your physical network.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Use the following command line options:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If you use internal networking for a virtual network adapter
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync --netname <network_name></computeroutput>, where
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput><network_name></computeroutput> is the same
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync network name you used with <computeroutput>VBoxManage modifyvm
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <vmname> --intnet<X>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If you use host-only networking for a virtual network adapter
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync --ifname <hostonly_if_name></computeroutput> instead, where
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput><hostonly_if_name></computeroutput> is the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync same host-only interface name you used with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage modifyvm <vmname>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync --hostonlyadapter<X>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Alternatively, you can also use the --netname option as with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync internal networks if you know the host-only network's name; you can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync see the names with <computeroutput>VBoxManage list
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hostonlyifs</computeroutput> (see <xref linkend="vboxmanage-list" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync above).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following additional parameters are required when first adding a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync DHCP server:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With <computeroutput>--ip</computeroutput>, specify the IP
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync address of the DHCP server itself.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With <computeroutput>--netmask</computeroutput>, specify the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync netmask of the network.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With <computeroutput>--lowerip</computeroutput> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--upperip</computeroutput>, you can specify the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync lowest and highest IP address, respectively, that the DHCP server
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync will hand out to clients.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Finally, you must specify <computeroutput>--enable</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync or the DHCP server will be created in the disabled state, doing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync nothing.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>After this, VirtualBox will automatically start the DHCP server for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync given internal or host-only network as soon as the first virtual machine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which uses that network is started.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Reversely, use <computeroutput>VBoxManage dhcpserver
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync remove</computeroutput> with the given <computeroutput>--netname
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <network_name></computeroutput> or <computeroutput>--ifname
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <hostonly_if_name></computeroutput> to remove the DHCP server again
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the given internal or host-only network.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To modify the settings of a DHCP server created earlier with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage dhcpserver add</computeroutput>, you can use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage dhcpserver modify</computeroutput> for a given
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync network or host-only interface name.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>The "extpack" command allows you to add or remove VirtualBox
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync extension packs, as described in <xref
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To add a new extension pack, use <computeroutput>VBoxManage
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync extpack install <tarball></computeroutput>. This command
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync will fail if an older version of the same extension pack is already
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync installed. The optional <computeroutput>--replace</computeroutput>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync parameter can be used to uninstall the old package before the new
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync package is installed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <para>To remove a previously installed extension pack, use
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>VBoxManage extpack uninstall
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <name></computeroutput>. You can use
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>VBoxManage list extpacks</computeroutput> to show
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync the names of the extension packs which are currently installed;
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync please see <xref linkend="vboxmanage-list" /> also. The optional
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync <computeroutput>--force</computeroutput> parameter can be used to
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync override the refusal of an extension pack to be uninstalled.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync cleanup</computeroutput> command can be used to remove temporary
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync files and directories that may have been left behind if a previous
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync install or uninstall command failed.</para>
ac153c99053f1edf42b00bf3a13475923bc4fcf1vboxsync </listitem>