diff options
Diffstat (limited to 'doc/manual/en_US/user_VBoxManage.xml')
| -rw-r--r-- | doc/manual/en_US/user_VBoxManage.xml | 9270 |
1 files changed, 9270 insertions, 0 deletions
diff --git a/doc/manual/en_US/user_VBoxManage.xml b/doc/manual/en_US/user_VBoxManage.xml new file mode 100644 index 00000000..f758bbe5 --- /dev/null +++ b/doc/manual/en_US/user_VBoxManage.xml @@ -0,0 +1,9270 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + user_VBoxManage.xml: + VBoxManage documentation for the user manual. + + This XML document is also be used for generating the help text + built into VBoxManage as well as manpages (hacking in progress). + + Copyright (C) 2006-2018 Oracle Corporation + + This file is part of VirtualBox Open Source Edition (OSE), as + available from http://www.virtualbox.org. This file is free software; + you can redistribute it and/or modify it under the terms of the GNU + General Public License (GPL) as published by the Free Software + Foundation, in version 2 as it comes in the "COPYING" file of the + VirtualBox OSE distribution. VirtualBox OSE is distributed in the + hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. + --> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="vboxmanage"> + + <title>VBoxManage</title> + + <sect1 id="vboxmanage-intro"> + + <title>Introduction</title> + + <para> + As briefly mentioned in <xref linkend="frontends" />, + <command>VBoxManage</command> is the command-line interface to + &product-name;. With it, you can completely control &product-name; + from the command line of your host operating system. + <command>VBoxManage</command> supports all the features that the + graphical user interface gives you access to, but it supports a + lot more than that. It exposes all the features of the + virtualization engine, even those that cannot be accessed from the + GUI. + </para> + + <para> + You will need to use the command line if you want to do the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Use a different user interface than the main GUI such as the + VBoxHeadless server. + </para> + </listitem> + + <listitem> + <para> + Control some of the more advanced and experimental + configuration settings for a VM. + </para> + </listitem> + + </itemizedlist> + + <para> + There are two main things to keep in mind when using + <command>VBoxManage</command>. First, + <command>VBoxManage</command> must always be used with a specific + subcommand, such as <command>list</command> or + <command>createvm</command> or <command>startvm</command>. All the + subcommands that <command>VBoxManage</command> supports are + described in detail in <xref linkend="vboxmanage" />. + </para> + + <para> + Second, most of these subcommands require that you specify a + particular virtual machine after the subcommand. There are two + ways you can do this: + </para> + + <itemizedlist> + + <listitem> + <para> + You can specify the VM name, as it is shown in the + &product-name; GUI. Note that if that name contains spaces, + then you must enclose the entire name in double quotes. This + is always required with command line arguments that contain + spaces. For example: + </para> + +<screen>VBoxManage startvm "Windows XP"</screen> + </listitem> + + <listitem> + <para> + You can specify the UUID, which is the internal unique + identifier that &product-name; uses to refer to the virtual + machine. Assuming that the VM called "Windows XP" has the UUID + shown below, the following command has the same effect as the + previous example: + </para> + +<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen> + </listitem> + + </itemizedlist> + + <para> + You can enter <command>VBoxManage list vms</command> to have all + currently registered VMs listed with all their settings, including + their respective names and UUIDs. + </para> + + <para> + Some typical examples of how to control &product-name; from the + command line are listed below: + </para> + + <itemizedlist> + + <listitem> + <para> + To create a new virtual machine from the command line and + immediately register it with &product-name;, use + <command>VBoxManage createvm</command> with the + <option>--register</option> option, as follows: + </para> + +<screen>$ VBoxManage createvm --name "SUSE 10.2" --register +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +(C) 2005-2018 Oracle Corporation +All rights reserved. + +Virtual machine 'SUSE 10.2' is created. +UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5 +Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'</screen> + + <para> + As can be seen from the above output, a new virtual machine + has been created with a new UUID and a new XML settings file. + </para> + + <para> + For more details, see + <xref + linkend="vboxmanage-createvm" />. + </para> + </listitem> + + <listitem> + <para> + To show the configuration of a particular VM, use + <command>VBoxManage showvminfo</command>. See + <xref + linkend="vboxmanage-showvminfo" /> for details + and an example. + </para> + </listitem> + + <listitem> + <para> + To change settings while a VM is powered off, use + <command>VBoxManage modifyvm</command>. For example: + </para> + +<screen>VBoxManage modifyvm "Windows XP" --memory 512</screen> + + <para> + See also <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + <listitem> + <para> + To change the storage configuration, such as to add a storage + controller and then a virtual disk, use <command>VBoxManage + storagectl</command> and <command>VBoxManage + storageattach</command>. See + <xref + linkend="vboxmanage-storagectl" /> and + <xref + linkend="vboxmanage-storageattach" />. + </para> + </listitem> + + <listitem> + <para> + To control VM operation, use one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + To start a VM that is currently powered off, use + <command>VBoxManage startvm</command>. See + <xref + linkend="vboxmanage-startvm" />. + </para> + </listitem> + + <listitem> + <para> + To pause or save a VM that is currently running or change + some of its settings, use <command>VBoxManage + controlvm</command>. See + <xref + linkend="vboxmanage-controlvm" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-cmd-overview"> + + <title>Commands Overview</title> + + <para> + When running <command>VBoxManage</command> without parameters or + when supplying an invalid command line, the following command + syntax list is shown. Note that the output will be slightly + different depending on the host platform. If in doubt, check the + output of <command>VBoxManage</command> for the commands available + on your particular host. + </para> + + <xi:include href="user_VBoxManage_CommandsOverview.xml" xpointer="xpointer(/sect1/*)" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <para> + Each time <command>VBoxManage</command> is invoked, only one + command can be executed. However, a command might support several + subcommands which then can be invoked in one single call. The + following sections provide detailed reference information on the + different commands. + </para> + + </sect1> + + <sect1 id="vboxmanage-general"> + + <title>General Options</title> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>-v|--version</computeroutput>: Show the + version of this tool and exit. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nologo</computeroutput>: Suppress the output + of the logo information. This option is useful for scripts. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--settingspw</computeroutput>: Specifiy a + settings password. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--settingspwfile</computeroutput>: Specify a + file containing the settings password. + </para> + </listitem> + + </itemizedlist> + + <para> + The settings password is used for certain settings which need to + be stored in encrypted form for security reasons. At the moment, + the only encrypted setting is the iSCSI initiator secret, see + <xref linkend="vboxmanage-storageattach" />. As long as no + settings password is specified, this information is stored in + <emphasis>plain text</emphasis>. After using the + <computeroutput>--settingspw|--settingspwfile</computeroutput> + option once, it must be always used. Otherwise, the encrypted + setting cannot be unencrypted. + </para> + + </sect1> + + <sect1 id="vboxmanage-list"> + + <title>VBoxManage list</title> + + <para> + The <command>list</command> command gives relevant information + about your system and information about &product-name;'s current + settings. + </para> + + <para> + The following subcommands are available with <command>VBoxManage + list</command>: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>vms</command>: Lists all virtual machines currently + registered with &product-name;. By default this displays a + compact list with each VM's name and UUID. If you also specify + <computeroutput>--long</computeroutput> or + <computeroutput>-l</computeroutput>, this will be a detailed + list as with the <command>showvminfo</command> command, see + <xref linkend="vboxmanage-showvminfo"/>. + </para> + </listitem> + + <listitem> + <para> + <command>runningvms</command>: Lists all currently running + virtual machines by their unique identifiers (UUIDs) in the + same format as with <command>vms</command>. + </para> + </listitem> + + <listitem> + <para> + <command>ostypes</command>: Lists all guest operating systems + presently known to &product-name;, along with the identifiers + used to refer to them with the <command>modifyvm</command> + command. + </para> + </listitem> + + <listitem> + <para> + <command>hostdvds</command>, <command>hostfloppies</command>: + Lists the DVD, floppy, bridged networking, and host-only + networking interfaces on the host, along with the name used to + access them from within &product-name;. + </para> + </listitem> + + <listitem> + <para> + <command>intnets</command>: Displays information about the + internal networks. + </para> + </listitem> + + <listitem> + <para> + <command>bridgedifs</command>, <command>hostonlyifs</command>, + <command>natnets</command>, <command>dhcpservers</command>: + Lists the bridged network interfaces, host-only network + interfaces, NAT network interfaces, and DHCP servers currently + available on the host. See + <xref linkend="networkingdetails" />. + </para> + </listitem> + + <listitem> + <para> + <command>hostinfo</command>: Displays information about the + host system, such as CPUs, memory size, and operating system + version. + </para> + </listitem> + + <listitem> + <para> + <command>hostcpuids</command>: Lists the CPUID parameters for + the host CPUs. This can be used for a more fine grained + analyis of the host's virtualization capabilities. + </para> + </listitem> + + <listitem> + <para> + <command>hddbackends</command>: Lists all known virtual disk + back-ends of &product-name;. For each such format, such as + VDI, VMDK, or RAW, this subcommand lists the back-end's + capabilities and configuration. + </para> + </listitem> + + <listitem> + <para> + <command>hdds</command>, <command>dvds</command>, + <command>floppies</command>: Shows information about virtual + disk images currently in use by &product-name;, including all + their settings, the unique identifiers (UUIDs) associated with + them by &product-name; and all files associated with them. + This is the command-line equivalent of the Virtual Media + Manager. See <xref linkend="vdis" />. + </para> + </listitem> + + <listitem> + <para> + <command>usbhost</command>: Shows information about USB + devices attached to the host, including information useful for + constructing USB filters and whether they are currently in use + by the host. + </para> + </listitem> + + <listitem> + <para> + <command>usbfilters</command>: Lists all global USB filters + registered with &product-name; and displays the filter + parameters. Global USB filters are for devices which are + accessible to all virtual machines. + </para> + </listitem> + + <listitem> + <para> + <command>systemproperties</command>: Displays some global + &product-name; settings, such as minimum and maximum guest RAM + and virtual hard disk size, folder settings and the current + authentication library in use. + </para> + </listitem> + + <listitem> + <para> + <command>extpacks</command>: Displays all &product-name; + extension packs that are currently installed. See + <xref linkend="intro-installing" /> and + <xref linkend="vboxmanage-extpack" />. + </para> + </listitem> + + <listitem> + <para> + <command>groups</command>: Displays details of the VM Groups. + See <xref linkend="gui-vmgroups" />. + </para> + </listitem> + + <listitem> + <para> + <command>webcams</command>: Displays a list of webcams + attached to the running VM. The output format is a list of + absolute paths or aliases that were used for attaching the + webcams to the VM using the webcam attach command. + </para> + </listitem> + + <listitem> + <para> + <command>screenshotformats</command>: Displays a list of + available screenshot formats. + </para> + </listitem> + + <listitem> + <para> + <command>cloudproviders</command>: Displays a list of cloud + providers that are supported by &product-name;. &oci; is an + example of a cloud provider. + </para> + </listitem> + + <listitem> + <para> + <command>cloudprofiles</command>: Displays a list of cloud + profiles that have been configured. + </para> + + <para> + Cloud profiles are used when exporting VMs to a cloud service. + See <xref linkend="ovf-export-oci"/>. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-showvminfo"> + + <title>VBoxManage showvminfo</title> + + <para> + The <command>showvminfo</command> command shows information about + a particular virtual machine. This is the same information as + <command>VBoxManage list vms --long</command> would show for all + virtual machines. + </para> + + <para> + You will see information as shown in the following example. + </para> + +<screen>$ VBoxManage showvminfo "Windows XP" +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +(C) 2005-2018 Oracle Corporation +All rights reserved. + +Name: Windows XP +Guest OS: Other/Unknown +UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7 +Config file: /home/username/.config/VirtualBox/Machines/Windows XP/Windows XP.xml +Memory size: 512MB +VRAM size: 12MB +Number of CPUs: 2 +Boot menu mode: message and menu +Boot Device (1): DVD +Boot Device (2): HardDisk +Boot Device (3): Not Assigned +Boot Device (4): Not Assigned +ACPI: on +IOAPIC: on +... + </screen> + + <para> + Use the <computeroutput>--machinereadable</computeroutput> option + to produce the same output, but in machine readable format with a + property=value string on each line. For example: + </para> + +<screen> +... +groups="/" +ostype="Oracle (64-bit)" +UUID="457af700-bc0a-4258-aa3c-13b03da171f2" +... + </screen> + + </sect1> + + <sect1 id="vboxmanage-registervm"> + + <title>VBoxManage registervm/unregistervm</title> + + <para> + The <computeroutput>registervm</computeroutput> command enables + you to import a virtual machine definition in an XML file into + &product-name;. The machine must not conflict with one already + registered in &product-name; and it may not have any hard or + removable disks attached. It is advisable to place the definition + file in the machines folder before registering it. + </para> + + <note> + <para> + When creating a new virtual machine with <command>VBoxManage + createvm</command>, as shown in + <xref linkend="vboxmanage-createvm"/>, you can directly specify + the <option>--register</option> option to avoid having to + register it separately. + </para> + </note> + + <para> + The <command>unregistervm</command> command unregisters a virtual + machine. If <option>--delete</option> is also specified, the + following files will also be deleted automatically: + </para> + + <itemizedlist> + + <listitem> + <para> + All hard disk image files, including differencing files, which + are used by the machine and not shared with other machines. + </para> + </listitem> + + <listitem> + <para> + Saved state files that the machine created. One if the machine + was in Saved state and one for each online snapshot. + </para> + </listitem> + + <listitem> + <para> + The machine XML file and its backups. + </para> + </listitem> + + <listitem> + <para> + The machine log files. + </para> + </listitem> + + <listitem> + <para> + The machine directory, if it is empty after having deleted all + of the above files. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-createvm"> + + <title>VBoxManage createvm</title> + + <para> + The <command>VBoxManage createvm</command> command creates a new + XML virtual machine definition file. + </para> + + <para> + You must specify the name of the VM by using <option>--name + <replaceable>name</replaceable></option>. This name is used by + default as the file name of the settings file that has the + <computeroutput>.xml</computeroutput> extension and the machine + folder, which is a subfolder of the + <computeroutput>.config/VirtualBox/Machines</computeroutput> + folder. Note that the machine folder path name varies based on the + OS type and the &product-name; version. + </para> + + <para> + Ensure that the VM name conforms to the host OS's file name + requirements. If you later rename the VM, the file and folder + names will be updated to match the new name automatically. + </para> + + <para> + The <option>--basefolder <replaceable>path</replaceable></option> + option specifies the machine folder path name. Note that the names + of the file and the folder do not change if you rename the VM. + </para> + + <para> + The <option>--group <replaceable>group-ID</replaceable>, + ...</option> option assigns the VM to the specified groups. Note + that group IDs always start with + <computeroutput>/</computeroutput> so that they can be nested. By + default, each VM is assigned membership to the + <computeroutput>/</computeroutput> group. + </para> + + <para> + The <option>--ostype <replaceable>ostype</replaceable></option> + option specifies the guest OS to run in the VM. Run the + <command>VBoxManage list ostypes</command> command to see the + available OS types. + </para> + + <para> + The <option>--uuid <replaceable>uuid</replaceable></option> option + specifies the universal unique identifier (UUID) of the VM. The + UUID must be unique within the namespace of the host or of its VM + group memberships. By default, the <command>VBoxManage</command> + command automatically generates the UUID. + </para> + + <para> + The <computeroutput>--default</computeroutput> option applies a + default hardware configuration for the specified guest OS. By + default, the VM is created with minimal hardware. + </para> + + <para> + The <option>--register</option> option registers the VM with your + &product-name; installation. By default, the <command>VBoxManage + createvm</command> command creates only the XML configuration for + the VM but does not registered the VM. If you do not register the + VM at creation, you can run the <command>VBoxManage + registervm</command> command after you create the VM. + </para> + + </sect1> + + <sect1 id="vboxmanage-modifyvm"> + + <title>VBoxManage modifyvm</title> + + <para> + This command changes the properties of a registered virtual + machine which is not running. Most of the properties that this + command makes available correspond to the VM settings that + &product-name; graphical user interface displays in each VM's + <emphasis role="bold">Settings</emphasis> dialog. These are + described in <xref linkend="BasicConcepts" />. However, some of + the more advanced settings are only available through the + <command>VBoxManage</command> interface. + </para> + + <para> + These commands require that the machine is powered off, neither + running nor in a Saved state. Some machine settings can also be + changed while a machine is running. Those settings will then have + a corresponding subcommand with the <command>VBoxManage + controlvm</command> subcommand. See + <xref linkend="vboxmanage-controlvm" />. + </para> + + <sect2 id="vboxmanage-modifyvm-general"> + + <title>General Settings</title> + + <para> + The following general settings are available through + <command>VBoxManage modifyvm</command>: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--name <name></computeroutput>: + Changes the VM's name and can be used to rename the internal + virtual machine files, as described in + <xref linkend="vboxmanage-createvm"/>. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--groups <group>, + ...</computeroutput>: Changes the group membership of a VM. + Groups always start with a + <computeroutput>/</computeroutput> and can be nested. By + default VMs are in group <computeroutput>/</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--description <desc></computeroutput>: + Changes the VM's description, which is a way to record + details about the VM in a way which is meaningful for the + user. The GUI interprets HTML formatting, the command line + allows arbitrary strings potentially containing multiple + lines. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--ostype <ostype></computeroutput>: + Specifies what guest operating system is supposed to run in + the VM. To learn about the various identifiers that can be + used here, use <command>VBoxManage list ostypes</command>. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--iconfile + <filename></computeroutput>: Specifies the absolute + path on the host file system for the &product-name; icon to + be displayed in the VM. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--memory + <memorysize></computeroutput>: Sets the amount of RAM, + in MB, that the virtual machine should allocate for itself + from the host. See <xref linkend="gui-createvm" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--pagefusion on|off</computeroutput>: + Enables and disables the Page Fusion feature. Page Fusion is + disabled by default. The Page Fusion feature minimises + memory duplication between VMs with similar configurations + running on the same host. See + <xref linkend="guestadd-pagefusion" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vram <vramsize></computeroutput>: + Sets the amount of RAM that the virtual graphics card should + have. See <xref linkend="settings-display" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--acpi on|off</computeroutput> and + <computeroutput>--ioapic on|off</computeroutput>: Determines + whether the VM has ACPI and I/O APIC support. See + <xref linkend="settings-motherboard" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--pciattach <host PCI address [@ guest + PCI bus address]></computeroutput>: Attaches a specified + PCI network controller on the host to a specified PCI bus on + the guest. See <xref linkend="pcipassthrough" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--pcidetach <host PCI + address></computeroutput>: Detaches a specified PCI + network controller on the host from the attached PCI bus on + the guest. See <xref linkend="pcipassthrough" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--hardwareuuid + <uuid></computeroutput>: The UUID presented to the + guest through memory tables (DMI/SMBIOS), hardware, and + guest properties. By default this is the same as the VM + UUID. This setting is useful when cloning a VM. Teleporting + takes care of this automatically. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--cpus <cpucount></computeroutput>: + Sets the number of virtual CPUs for the virtual machine, see + <xref linkend="settings-processor" />. If CPU hot-plugging + is enabled, this then sets the <emphasis>maximum</emphasis> + number of virtual CPUs that can be plugged into the virtual + machines. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--cpuhotplug on|off</computeroutput>: + Enables CPU hot-plugging. When enabled, virtual CPUs can be + added to and removed from a virtual machine while it is + running. See <xref linkend="cpuhotplug" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--plugcpu|unplugcpu + <id></computeroutput>: If CPU hot-plugging is enabled, + this setting adds or removes a virtual CPU on the virtual + machine. <computeroutput><id></computeroutput> + specifies the index of the virtual CPU to be added or + removed and must be a number from 0 to the maximum number of + CPUs configured with the + <computeroutput>--cpus</computeroutput> option. CPU 0 can + never be removed. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--cpuexecutioncap + <1-100></computeroutput>: Controls how much CPU time a + virtual CPU can use. A value of 50 implies a single virtual + CPU can use up to 50% of a single host CPU. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--pae on|off</computeroutput>: Enables and + disables PAE. See <xref linkend="settings-processor" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--longmode on|off</computeroutput>: Enables + and disables long mode. See + <xref linkend="settings-processor" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--spec-ctrl on|off</computeroutput>: Enables + and disables the exposure of speculation control interfaces + to the guest, provided they are available on the host. + Depending on the host CPU and workload, enabling speculation + control may significantly reduce performance. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--cpu-profile <host|intel + 80[86|286|386]></computeroutput>: Enables specification + of a profile for guest CPU emulation. Specify either one + based on the host system CPU (host), or one from a number of + older Intel Micro-architectures: 8086, 80286, 80386. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--hpet on|off</computeroutput>: Enables and + disables a High Precision Event Timer (HPET) which can + replace the legacy system timers. This is turned off by + default. Note that Windows supports a HPET only from Vista + onwards. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--hwvirtex on|off</computeroutput>: Enables + and disables the use of hardware virtualization extensions, + such as Intel VT-x or AMD-V, in the processor of your host + system. See <xref linkend="hwvirt" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--triplefaultreset on|off</computeroutput>: + Enables resetting of the guest instead of triggering a Guru + Meditation. Some guests raise a triple fault to reset the + CPU so sometimes this is desired behavior. Works only for + non-SMP guests. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--apic on|off</computeroutput>: Enables and + disables I/O APIC. With I/O APIC, operating systems can use + more than 16 interrupt requests (IRQs) thus avoiding IRQ + sharing for improved reliability. This setting is enabled by + default. See <xref linkend="settings-motherboard" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--x2apic on|off</computeroutput>: Enables + and disables CPU x2APIC support. CPU x2APIC support helps + operating systems run more efficiently on high core count + configurations, and optimizes interrupt distribution in + virtualized environments. This setting is enabled by + default. Disable this setting when using host or guest + operating systems that are incompatible with x2APIC support. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--paravirtprovider + none|default|legacy|minimal|hyperv|kvm</computeroutput>: + Specifies which paravirtualization interface to provide to + the guest operating system. Specifying + <computeroutput>none</computeroutput> explicitly turns off + exposing any paravirtualization interface. The option + <computeroutput>default</computeroutput> selects an + appropriate interface when starting the VM, depending on the + guest OS type. This is the default option chosen when + creating new VMs. The + <computeroutput>legacy</computeroutput> option is used for + VMs which were created with older &product-name; versions + and will pick a paravirtualization interface when starting + the VM with &product-name; 5.0 and newer. The + <computeroutput>minimal</computeroutput> provider is + mandatory for Mac OS X guests. + <computeroutput>kvm</computeroutput> and + <computeroutput>hyperv</computeroutput> are recommended for + Linux and Windows guests respectively. These options are + explained in <xref linkend="gimproviders" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--paravirtdebug <keyword=value> + [,<keyword=value> ...]</computeroutput>: Specifies + debugging options specific to the paravirtualization + provider configured for this VM. See the provider specific + options in <xref linkend="gimdebug" /> for a list of + supported keyword-value pairs for each provider. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nestedpaging on|off</computeroutput>: If + hardware virtualization is enabled, this additional setting + enables or disables the use of the nested paging feature in + the processor of your host system. See + <xref linkend="hwvirt" /> and + <xref linkend="sec-rec-cve-2018-3646" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--largepages on|off</computeroutput>: If + hardware virtualization <emphasis>and</emphasis> nested + paging are enabled, for Intel VT-x only, an additional + performance improvement of up to 5% can be obtained by + enabling this setting. This causes the hypervisor to use + large pages to reduce TLB use and overhead. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vtxvpid on|off</computeroutput>: If + hardware virtualization is enabled, for Intel VT-x only, + this additional setting enables or disables the use of the + tagged TLB (VPID) feature in the processor of your host + system. See <xref linkend="hwvirt" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vtxux on|off</computeroutput>: If hardware + virtualization is enabled, for Intel VT-x only, this setting + enables or disables the use of the unrestricted guest mode + feature for executing your guest. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--accelerate3d on|off</computeroutput>: If + the Guest Additions are installed, this setting enables or + disables hardware 3D acceleration. See + <xref linkend="guestadd-3d" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--accelerate2dvideo on|off</computeroutput>: + If the Guest Additions are installed, this setting enables + or disables 2D video acceleration. See + <xref linkend="guestadd-2d" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--chipset piix3|ich9</computeroutput>: By + default, &product-name; emulates an Intel PIIX3 chipset. + Usually there is no reason to change the default setting + unless this is required to relax some of its constraints. + See <xref linkend="settings-motherboard" />. + </para> + </listitem> + + <listitem> + <para> + You can influence the BIOS logo that is displayed when a + virtual machine starts up with a number of settings. By + default, an &product-name; logo is displayed. + </para> + + <para> + With <computeroutput>--bioslogofadein + on|off</computeroutput> and + <computeroutput>--bioslogofadeout on|off</computeroutput>, + you can determine whether the logo should fade in and out, + respectively. + </para> + + <para> + With <computeroutput>--bioslogodisplaytime + <msec></computeroutput> you can set how long the logo + should be visible, in milliseconds. + </para> + + <para> + With <computeroutput>--bioslogoimagepath + <imagepath></computeroutput> you can replace the image + that is shown with your own logo. The image must be an + uncompressed 256 color BMP file without color space + information (Windows 3.0 format). The image must not be + bigger than 640 x 480. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--biosbootmenu + disabled|menuonly|messageandmenu</computeroutput>: Specifies + whether the BIOS enables the user to select a temporary boot + device. The <computeroutput>menuonly</computeroutput> option + suppresses the message, but the user can still press F12 to + select a temporary boot device. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--biosapic + x2apic|apic|disabled</computeroutput>: Specifies the + firmware APIC level to be used. Options are: x2apic, apic or + disabled (no apic or x2apic) respectively. + </para> + + <para> + Note that if x2apic is specified and x2APIC is unsupported + by the VCPU, biosapic downgrades to apic, if supported. + Otherwise biosapic downgrades to disabled. Similarly, if + apic is specified, and APIC is unsupported, a downgrade to + disabled results. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--biossystemtimeoffset + <ms></computeroutput>: Specifies a fixed time offset, + in milliseconds, of the guest relative to the host time. If + the offset is positive, the guest time runs ahead of the + host time. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--biospxedebug on|off</computeroutput>: + Enables additional debugging output when using the Intel PXE + boot ROM. The output is written to the release log file. See + <xref linkend="collect-debug-info" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--boot<1-4> + none|floppy|dvd|disk|net</computeroutput>: Specifies the + boot order for the virtual machine. There are four + <emphasis>slots</emphasis>, which the VM will try to access + from 1 to 4, and for each of which you can set a device that + the VM should attempt to boot from. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--rtcuseutc on|off</computeroutput>: Sets + the real-time clock (RTC) to operate in UTC time. See + <xref linkend="settings-motherboard" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--graphicscontroller + none|vboxvga|vmsvga|vboxsvga</computeroutput>: Specifies the + use of a graphics controller, with an option to choose a + specific type. See <xref linkend="settings-screen" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--snapshotfolder + default|<path></computeroutput>: Specifies the folder + where snapshots are kept for a virtual machine. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--firmware + bios|efi|efi32|efi64</computeroutput>: Specifies the + firmware to be used to boot the VM: Available options are: + BIOS, or one of the EFI options: efi, efi32, or efi64. Use + EFI options with care. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--guestmemoryballoon + <size></computeroutput> Sets the default size of the + guest memory balloon. This is the memory allocated by the + &product-name; Guest Additions from the guest operating + system and returned to the hypervisor for reuse by other + virtual machines. + <computeroutput><size></computeroutput> must be + specified in megabytes. The default size is 0 megabytes. See + <xref linkend="guestadd-balloon" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--defaultfrontend + default|<name></computeroutput>: Specifies the default + frontend to be used when starting this VM. See + <xref linkend="vboxmanage-startvm" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxmanage-modifyvm-networking"> + + <title>Networking Settings</title> + + <para> + The following networking settings are available through + <command>VBoxManage modifyvm</command>. With all these settings, + the decimal number directly following the option name, 1-N in + the list below, specifies the virtual network adapter whose + settings should be changed. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--nic<1-N> + none|null|nat|natnetwork|bridged|intnet|hostonly|generic</computeroutput>: + Configures the type of networking for each of the VM's + virtual network cards. Options are: not present + (<computeroutput>none</computeroutput>), not connected to + the host (<computeroutput>null</computeroutput>), use + network address translation + (<computeroutput>nat</computeroutput>), use the new network + address translation engine + (<computeroutput>natnetwork</computeroutput>), bridged + networking (<computeroutput>bridged</computeroutput>), or + use internal networking + (<computeroutput>intnet</computeroutput>), host-only + networking (<computeroutput>hostonly</computeroutput>), or + access rarely used sub-modes + (<computeroutput>generic</computeroutput>). These options + correspond to the modes described in + <xref + linkend="networkingmodes" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nictype<1-N> + Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio</computeroutput>: + Enables you to specify the networking hardware that + &product-name; presents to the guest for a specified VM + virtual network card. See <xref linkend="nichardware" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--cableconnected<1-N> + on|off</computeroutput>: Enables you to temporarily + disconnect a virtual network interface, as if a network + cable had been pulled from a real network card. This might + be useful, for example for resetting certain software + components in the VM. + </para> + </listitem> + + <listitem> + <para> + With the <computeroutput>nictrace</computeroutput> options, + you can optionally trace network traffic by dumping it to a + file, for debugging purposes. + </para> + + <para> + With <computeroutput>--nictrace<1-N> + on|off</computeroutput>, you can enable network tracing for + a particular virtual network card. + </para> + + <para> + If enabled, you must specify with + <computeroutput>--nictracefile<1-N> + <filename></computeroutput> the absolute path of the + file the trace should be logged to. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nicproperty<1-N> + <paramname>="paramvalue"</computeroutput>: This + option, in combination with + <computeroutput>nicgenericdrv</computeroutput> enables you + to pass parameters to rarely-used network backends. + </para> + + <para> + These parameters are backend engine-specific, and are + different between UDP Tunnel and the VDE backend drivers. + For examples, see <xref linkend="network_udp_tunnel" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nicspeed<1-N> + <kbps></computeroutput>: Only has an effect if generic + networking has been enabled for a particular virtual network + card. See the <computeroutput>--nic</computeroutput> option. + This mode enables access to rarely used networking + sub-modes, such as VDE network or UDP Tunnel. This option + specifies the throughput rate in KBps. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nicbootprio<1-N> + <priority></computeroutput>: Specifies the order in + which NICs are tried for booting over the network, using + PXE. The priority is an integer in the 0 to 4 range. + Priority 1 is the highest, priority 4 is low. Priority 0, + which is the default unless otherwise specified, is the + lowest. + </para> + + <para> + Note that this option only has an effect when the Intel PXE + boot ROM is used. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nicpromisc<1-N> + deny|allow-vms|allow-all</computeroutput>: Enables you to + specify how promiscuous mode is handled for the specified VM + virtual network card. This setting is only relevant for + bridged networking. <computeroutput>deny</computeroutput>, + the default setting, hides any traffic not intended for the + VM. <computeroutput>allow-vms</computeroutput> hides all + host traffic from the VM, but allows the VM to see traffic + to and from other VMs. + <computeroutput>allow-all</computeroutput> removes this + restriction completely. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nicbandwidthgroup<1-N> + none|<name></computeroutput>: Adds and removes an + assignment of a bandwidth group for the specified virtual + network interface. Specifying + <computeroutput>none</computeroutput> removes any current + bandwidth group assignment from the specified virtual + network interface. Specifying + <computeroutput><name></computeroutput> adds an + assignment of a bandwidth group to the specified virtual + network interface. + </para> + + <para> + See <xref linkend="network_bandwidth_limit" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--bridgeadapter<1-N> + none|<devicename></computeroutput>: Only has an effect + if bridged networking has been enabled for a virtual network + card. See the <computeroutput>--nic</computeroutput> option. + Use this option to specify which host interface the given + virtual network interface will use. See + <xref linkend="network_bridged" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--hostonlyadapter<1-N> + none|<devicename></computeroutput>: Only has an effect + if host-only networking has been enabled for a virtual + network card. See the <computeroutput>--nic</computeroutput> + option. Use this option to specify which host-only + networking interface the given virtual network interface + will use. See <xref linkend="network_hostonly" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--intnet<1-N> + network</computeroutput>: Only has an effect if internal + networking has been enabled for a virtual network card. See + the <computeroutput>--nic</computeroutput> option. Use this + option to specify the name of the internal network. See + <xref linkend="network_internal" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nat-network<1-N> <network + name></computeroutput>: If the networking type is set to + <computeroutput>natnetwork</computeroutput>, not + <computeroutput>nat</computeroutput>, then this setting + specifies the name of the NAT network this adapter is + connected to. Optional. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nicgenericdrv<1-N> <backend + driver></computeroutput>: Only has an effect if generic + networking has been enabled for a virtual network card. See + the <computeroutput>--nic</computeroutput> option. This mode + enables you to access rarely used networking sub-modes, such + as VDE network or UDP Tunnel. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--macaddress<1-N> + auto|<mac></computeroutput>: With this option you can + set the MAC address of a particular network adapter on the + VM. Normally, each network adapter is assigned a random + address by &product-name; at VM creation. + </para> + </listitem> + + </itemizedlist> + + <sect3 id="vboxmanage-modifyvm-networking-nat"> + + <title>NAT Networking Settings</title> + + <para> + The following NAT networking settings are available through + <command>VBoxManage modifyvm</command>. With all these + settings, the decimal number directly following the option + name, 1-N in the list below, specifies the virtual network + adapter whose settings should be changed. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--natnet<1-N> + <network>|default</computeroutput>: If the + networking type is set to + <computeroutput>nat</computeroutput>, not + <computeroutput>natnetwork</computeroutput>, then this + setting specifies the IP address range to be used for this + network. See <xref linkend="changenat" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--natpf<1-N> + [<name>],tcp|udp,[<hostip>],<hostport>,[<guestip>], + <guestport></computeroutput>: Defines a NAT + port-forwarding rule. See <xref linkend="natforward" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--natpf<1-N> delete + <name></computeroutput>: Deletes a NAT + port-forwarding rule. See <xref linkend="natforward" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nattftpprefix<1-N> + <prefix></computeroutput>: Defines a prefix for the + built-in TFTP server. For example, where the boot file is + located. See <xref linkend="nat-tftp" /> and + <xref linkend="nat-adv-tftp" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nattftpfile<1-N> + <bootfile></computeroutput>: Defines the TFT boot + file. See <xref linkend="nat-adv-tftp" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nattftpserver<1-N> + <tftpserver></computeroutput>: Defines the TFTP + server address to boot from. See + <xref linkend="nat-adv-tftp" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nattbindip<1-N> + <ip;></computeroutput>: &product-name;'s NAT engine + normally routes TCP/IP packets through the default + interface assigned by the host's TCP/IP stack. Use this + setting to instruct the NAT engine to bind to a specified + IP address instead. See + <xref linkend="nat-adv-settings" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--natdnspassdomain<1-N> + on|off</computeroutput>: Specifies whether the built-in + DHCP server passes the domain name for network name + resolution. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--natdnsproxy<1-N> + on|off</computeroutput>: Makes the NAT engine proxy all + guest DNS requests to the host's DNS servers. See + <xref linkend="nat-adv-dns" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--natdnshostresolver<1-N> + on|off</computeroutput>: Makes the NAT engine use the + host's resolver mechanisms to handle DNS requests. See + <xref linkend="nat-adv-dns" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--natsettings<1-N> + [<mtu>],[<socksnd>],[<sockrcv>],[<tcpsnd>], + [<tcprcv>]</computeroutput>: Controls several NAT + settings. See <xref linkend="nat-adv-settings" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--nataliasmode<1-N> + default|[log],[proxyonly],[sameports]</computeroutput>: + Defines behaviour of the NAT engine core: log - enables + logging, proxyonly - switches off aliasing mode and makes + NAT transparent, sameports - enforces the NAT engine to + send packets through the same port as they originated on, + default - disable all aliasing modes. See + <xref linkend="nat-adv-alias" />. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + </sect2> + + <sect2 id="vboxmanage-modifyvm-other"> + + <title>Miscellaneous Settings</title> + + <para> + The following hardware settings, such as serial port, audio, + clipboard, drag and drop, monitor, and USB settings are + available through <command>VBoxManage modifyvm</command>: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--mouse + <ps2|usb|usbtablet|usbmultitouch></computeroutput>: + Specifies the mode of the mouse to be used in the VM. + Available options are: ps2, usb, usbtablet, usbmultitouch. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--keyboard <ps2|usb></computeroutput>: + Specifies the mode of the keyboard to be used in the VM. + Available options are: ps2, usb. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--uart<1-N> off|<I/O base> + <IRQ></computeroutput>: Configures virtual serial + ports for the VM. See <xref linkend="serialports" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--uartmode<1-N> + <arg></computeroutput>: Controls how &product-name; + connects a given virtual serial port, configured with the + <computeroutput>--uartX</computeroutput> setting, to the + host on which the virtual machine is running. As described + in <xref linkend="serialports" />, for each such port, you + can specify <computeroutput><arg></computeroutput> as + one of the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>disconnected</computeroutput>: Even + though the serial port is shown to the guest, it has no + "other end". This is like a real COM port without a + cable. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>server + <pipename></computeroutput>: On a Windows host, + this tells &product-name; to create a named pipe on the + host named + <computeroutput><pipename></computeroutput> and + connect the virtual serial device to it. Note that + Windows requires that the name of a named pipe begins + with <computeroutput>\\.\pipe\</computeroutput>. + </para> + + <para> + On a Linux host, instead of a named pipe, a local domain + socket is used. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>client + <pipename></computeroutput>: Operates as for + <computeroutput>server</computeroutput>, except that the + pipe, or local domain socket, is not created by + &product-name; but is assumed to exist already. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>tcpserver <port></computeroutput>: + Configures &product-name; to create a TCP socket on the + host with TCP + <computeroutput><port></computeroutput> and + connect the virtual serial device to it. Note that + UNIX-like systems require ports over 1024 for normal + users. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>tcpclient + <hostname:port></computeroutput>: Operates as for + <computeroutput>tcpserver</computeroutput>, except that + the TCP socket is not created by &product-name;, but is + assumed to exist already. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>uarttype <1-N> + 16450|16550A|16750</computeroutput>: Confgures the UART + type for a virtual serial port. The default UART type is + 16550A. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>file <file></computeroutput>: + Redirects the serial port output to a raw file + <file> specified by its absolute path on the host + file system. + </para> + </listitem> + + <listitem> + <para> + <computeroutput><devicename></computeroutput>: If, + instead of the above options, the device name of a + physical hardware serial port of the host is specified, + the virtual serial port is connected to that hardware + port. On a Windows host, the device name will be a COM + port such as <computeroutput>COM1</computeroutput>. On a + Linux host, the device name will be + <computeroutput>/dev/ttyS0</computeroutput> or similar. + This enables you to wire up a real serial port to a + virtual machine. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>--lptmode<1-N> + <Device></computeroutput>: Specifies the Device Name + of the parallel port that the Parallel Port feature will be + using. Use this <emphasis>before</emphasis> + <computeroutput>--lpt</computeroutput>. This feature depends + on the host operating system. For Windows hosts, use a + device name such as lpt1. On Linux hosts, use a device name + such as /dev/lp0. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--lpt<1-N> <I/O base> + <IRQ></computeroutput>: Specifies the I/O address of + the parallel port and the IRQ number that the Parallel Port + feature will be using. Optional. Use this + <emphasis>after</emphasis> + <computeroutput>--lptmod</computeroutput>. I/O base address + and IRQ are the values that guest sees. For example, the + values avalable under guest Device Manager. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--audio + none|null|dsound|oss|alsa|pulse|coreaudio</computeroutput>: + Specifies whether the VM should have audio support, and if + so, which type. The list of supported audio types depends on + the host and can be determined with <command>VBoxManage + modifyvm</command>. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--audiocontroller + ac97|hda|sb16</computeroutput>: Specifies the audio + controller to be used with the VM. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--audiocodec + stac9700|ad1980|stac9221|sb16</computeroutput>: Specifies + the audio codec to be used with the VM. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--audioin on</computeroutput>: Specifies + whether capturing audio from the host is enabled or + disabled. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--audioout on</computeroutput>: Specifies + whether audio playback from the guest is enabled or + disabled. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--clipboard + disabled|hosttoguest|guesttohost|bidirectional</computeroutput>: + Configues how the guest or host operating system's clipboard + should be shared with the host or guest. See + <xref linkend="generalsettings" />. This setting requires + that the Guest Additions be installed in the virtual + machine. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--draganddrop + disabled|hosttoguest|guesttohost|bidirectional</computeroutput>: + Specifies the drag and drop mode to use between the host and + the virtual machine. See <xref linkend="guestadd-dnd" />. + This requires that the Guest Additions be installed in the + virtual machine. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--monitorcount + <count></computeroutput>: Enables multi-monitor + support. See <xref linkend="settings-display" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--usb on|off</computeroutput>: Enables and + disables the VM's virtual USB controller. See + <xref linkend="settings-usb" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--usbehci on|off</computeroutput>: Enables + and disables the VM's virtual USB 2.0 controller. See + <xref linkend="settings-usb" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--usbxhci on|off</computeroutput>: Enables + and disables the VM's virtual USB 3.0 controller. See + <xref linkend="settings-usb" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--usbrename <oldname> + <newname></computeroutput>: Enables renaming of the + VM's virtual USB controller from <oldname> to + <newname>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxmanage-modifyvm-recording"> + + <title>Recording Settings</title> + + <para> + The <command>VBoxManage modifyvm</command> command enables you + to modify recording settings for video recording, audio + recording, or both. + </para> + + <para> + Use the following options to update the recording settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <option>--recording on|off</option> enables or disables the + recording of a VM session into a WebM/VP8 file. When this + option value is <computeroutput>on</computeroutput>, + recording begins when the VM session starts. + </para> + </listitem> + + <listitem> + <para> + <option>--recordingscreens + all|<replaceable>screen-ID</replaceable> + [<replaceable>screen-ID</replaceable> ...]</option> enables + you to specify which VM screens to record. The recording for + each screen that you specify is saved to its own file. + </para> + </listitem> + + <listitem> + <para> + <option>--recordingfile + <replaceable>filename</replaceable></option> specifies the + file in which to save the recording. + </para> + </listitem> + + <listitem> + <para> + <option>--recordingmaxsize + <replaceable>MB</replaceable></option> specifies the maximum + size of the recorded video file in megabytes. The recording + stops when the file reaches the specified size. If this + value is zero, the recording continues until you stop the + recording. + </para> + </listitem> + + <listitem> + <para> + <option>--recordingmaxtime + <replaceable>seconds</replaceable></option> specifies the + maximum amount time to record in seconds. The recording + stops after the specified number of seconds elapses. If this + value is zero, the recording continues until you stop the + recording. + </para> + </listitem> + + <listitem> + <para> + <option>--recordingopts + <replaceable>keyword</replaceable>=<replaceable>value</replaceable>[,<replaceable>keyword</replaceable>=<replaceable>value</replaceable> + ...]</option> specifies additional video-recording options + in a comma-separated keyword-value format. For example, + <computeroutput>foo=bar,a=b</computeroutput>. + </para> + + <para> + Only use this option only if you are an advanced user. For + information about keywords, see <emphasis>Oracle VM + VirtualBox Programming Guide and Reference</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <option>--recordingvideofps + <replaceable>fps</replaceable></option> specifies the + maximum number of video frames per second (FPS) to record. + Frames that have a higher frequency are skipped. Increasing + this value reduces the number of skipped frames and + increases the file size. + </para> + </listitem> + + <listitem> + <para> + <option>--recordingvideorate + <replaceable>bit-rate</replaceable></option> specifies the + bit rate of the video in kilobits per second. Increasing + this value improves the appearance of the video at the cost + of an increased file size. + </para> + </listitem> + + <listitem> + <para> + <option>--recordingvideores + <replaceable>width</replaceable>x<replaceable>height</replaceable></option> + specifies the video resolution of the recorded video in + pixels. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxmanage-modifyvm-vrde"> + + <title>Remote Machine Settings</title> + + <para> + The following settings that affect remote machine behavior are + available through <command>VBoxManage modifyvm</command>: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--vrde on|off</computeroutput>: Enables and + disables the VirtualBox Remote Desktop Extension (VRDE) + server. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "TCP/Ports|Address=<value>"</computeroutput>: Sets the + port numbers and IP address on the VM that the VRDE server + can bind to. + </para> + + <itemizedlist> + + <listitem> + <para> + For TCP/Ports, <value> should be a port or a range + of ports that the VRDE server can bind to. + <computeroutput>default</computeroutput> or + <computeroutput>0</computeroutput> means port 3389, the + standard port for RDP. See the description for the + <computeroutput>--vrdeport</computeroutput> option in + <xref linkend="vboxmanage-modifyvm-vrde" />. + </para> + </listitem> + + <listitem> + <para> + For TCP/Address, <value> should be the IP address + of the host network interface that the VRDE server will + bind to. If specified, the server will accept + connections only on the specified host network + interface. See the description for the + <computeroutput>--vrdeaddress</computeroutput> option in + <xref linkend="vboxmanage-modifyvm-vrde" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "VideoChannel/Enabled|Quality|DownscaleProtection=<value>"</computeroutput>: + Sets the VRDP video redirection properties. + </para> + + <itemizedlist> + + <listitem> + <para> + For VideoChannel/Enabled, <value> can be set to + "1", switching the VRDP video channel on. See + <xref linkend="vrde-videochannel" />. + </para> + </listitem> + + <listitem> + <para> + For VideoChannel/Quality, <value> should be set + between 10 and 100% inclusive, representing a JPEG + compression level on the VRDE server video channel. + Lower values mean lower quality but higher compression. + See <xref linkend="vrde-videochannel" />. + </para> + </listitem> + + <listitem> + <para> + For VideoChannel/DownscaleProtection, <value> can + be set to "1" to enable the videochannel downscale + protection feature. When enabled, if a video's size + equals the shadow buffer size, then it is regarded as a + full screen video, and is displayed. But if its size is + between fullscreen and the downscale threshold then it + is <emphasis>not</emphasis> displayed, as it could be an + application window, which would be unreadable when + downscaled. When the downscale protection feature is + disabled, an attempt is always made to display videos. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1"</computeroutput>: + Disables one of the VRDE server features: Display, Input, + Audio or USB respectively. To reenable a feature, use + "Client/DisableDisplay=" for example. See + <xref linkend="vrde-customization" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Client/DisableClipboard|DisableUpstreamAudio=1"</computeroutput>: + Disables one of the VRDE server features: Clipboard or + UpstreamAudio respectively. To reenable a feature, use + "Client/DisableClipboard=" for example. See + <xref linkend="vrde-customization" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Client/DisableRDPDR=1"</computeroutput>: Disables the VRDE + server feature: RDP device redirection for smart cards. To + reenable this feature, use "Client/DisableRDPR=". + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "H3DRedirect/Enabled=1"</computeroutput>: Enables the VRDE + server feature: 3D redirection. To disable this feature, use + "H3DRedirect/Enabled=". + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=<value>"</computeroutput>: + Sets the desired security method and path of server + certificate, path of server private key, path of CA + certificate, that are used for a connection. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Security/Method=<value>"</computeroutput> sets + the desired security method, which is used for a + connection. Valid values are: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>Negotiate</computeroutput>: Both + Enhanced (TLS) and Standard RDP Security connections + are allowed. The security method is negotiated with + the client. This is the default setting. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>RDP</computeroutput>: Only Standard + RDP Security is accepted. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>TLS</computeroutput>: Only Enhanced + RDP Security is accepted. The client must support + TLS. + </para> + </listitem> + + </itemizedlist> + + <para> + See <xref linkend="vrde-crypt" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Security/ServerCertificate=<value>"</computeroutput> + where <value> is the absolute path of the server + certificate. See <xref linkend="vrde-crypt" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Security/ServerPrivateKey=<value>"</computeroutput> + where <value> is the absolute path of the server + private key. See <xref linkend="vrde-crypt" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Security/CACertificate=<value>"</computeroutput> + where <value> is the absolute path of the CA self + signed certificate. See <xref linkend="vrde-crypt" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Audio/RateCorrectionMode|LogPath=<value>"</computeroutput> + sets the audio connection mode, or path of the audio + logfile. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Audio/RateCorrectionMode=<value>"</computeroutput> + where <value> is the desired rate correction mode. + Allowed values are: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput>: + No mode specified, use to unset any Audio mode + already set. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput>: + Rate correction mode. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput>: + Low pass filter mode. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput>: + Client sync mode to prevent underflow or overflow of + the client queue. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeproperty + "Audio/LogPath=<value>"</computeroutput> where + <value> is the absolute path of the Audio log + file. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeextpack + default|<name></computeroutput>: Specifies the library + to use for accessing the VM remotely. The default is to use + the RDP code which is part of the &product-name; Extension + Pack. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeport + default|<ports></computeroutput>: A port or a range of + ports the VRDE server can bind to. + <computeroutput>default</computeroutput> or + <computeroutput>0</computeroutput> means port 3389, the + standard port for RDP. You can specify a comma-separated + list of ports or ranges of ports. Use a dash between two + port numbers to specify a range. The VRDE server will bind + to <emphasis>one</emphasis> of the available ports from the + specified list. Only one machine can use a given port at a + time. For example, the option <computeroutput> --vrdeport + 5000,5010-5012</computeroutput> will tell the server to bind + to one of following ports: 5000, 5010, 5011, or 5012. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeaddress <IP + address></computeroutput>: The IP address of the host + network interface the VRDE server will bind to. If + specified, the server will accept connections only on the + specified host network interface. + </para> + + <para> + The setting can be used to specify whether the VRDP server + should accept either IPv4, IPv6, or both connections: + </para> + + <itemizedlist> + + <listitem> + <para> + Only IPv4: <computeroutput>--vrdeaddress + "0.0.0.0"</computeroutput> + </para> + </listitem> + + <listitem> + <para> + Only IPv6: <computeroutput>--vrdeaddress + "::"</computeroutput> + </para> + </listitem> + + <listitem> + <para> + Both IPv6 and IPv4: <computeroutput>--vrdeaddress + ""</computeroutput> + </para> + + <para> + This is the default setting. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeauthtype + null|external|guest</computeroutput>: Enables you to + indicate use of authorization, and specify how authorization + will be performed. See <xref linkend="vbox-auth" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdeauthlibrary + default|<name></computeroutput>: Specifies the library + used for RDP authentication. See + <xref linkend="vbox-auth" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdemulticon on|off</computeroutput>: + Enables multiple connections to be made to the same VRDE + server, if the server supports this feature. See + <xref linkend="vrde-multiconnection" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdereusecon on|off</computeroutput>: This + specifies the VRDE server behavior when multiple connections + are disabled. When this option is enabled, the server will + allow a new client to connect and will drop the existing + connection. When this option is disabled, the default + setting, a new connection will not be accepted if there is + already a client connected to the server. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdevideochannel on|off</computeroutput>: + Enables video redirection, if it is supported by the VRDE + server. See <xref linkend="vrde-videochannel" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vrdevideochannelquality + <percent></computeroutput>: Specifies the image + quality for video redirection. See + <xref linkend="vrde-videochannel" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxmanage-modifyvm-teleport"> + + <title>Teleporting Settings</title> + + <para> + With the following commands for <command>VBoxManage + modifyvm</command> you can configure a machine to be a target + for teleporting. See <xref linkend="teleporting" />. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--teleporter on|off</computeroutput>: + Enables and disables the teleporter feature whereby when the + machine is started, it waits to receive a teleporting + request from the network instead of booting normally. + Teleporting requests are received on the port and address + specified using the following parameters. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--teleporterport + <port></computeroutput>, + <computeroutput>--teleporteraddress + <address></computeroutput>: These settings must be + used with <computeroutput>--teleporter</computeroutput>. + They specify the port and address the virtual machine should + listen to in order to receive a teleporting request sent + from another virtual machine. + <computeroutput><port></computeroutput> can be any + free TCP/IP port number, such as 6000. + <computeroutput><address></computeroutput> can be any + IP address or hostname and specifies the TCP/IP socket to + bind to. The default is 0.0.0.0, which means any address. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--teleporterpassword + <password></computeroutput>: If this optional setting + is used, then the teleporting request will only succeed if + the source machine specifies the same password as the one + given with this command. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--teleporterpasswordfile + <password></computeroutput>: If this optional setting + is used, then the teleporting request will only succeed if + the source machine specifies the same password as the one + specified in the file give with this command. Use + <computeroutput>stdin</computeroutput> to read the password + from stdin. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--cpuid <leaf> <eax> <ebx> + <ecx> <edx></computeroutput>: Advanced users can + use this setting before a teleporting operation, to restrict + the virtual CPU capabilities that &product-name; presents to + the guest operating system. This must be run on both the + source and the target machines involved in the teleporting + and will then modify what the guest sees when it executes + the <computeroutput>CPUID</computeroutput> machine + instruction. This might help with misbehaving applications + that wrongly assume that certain CPU capabilities are + present. The meaning of the parameters is hardware + dependent, refer to the AMD or Intel processor + documentation. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxmanage-modifyvm-debugging"> + + <title>Debugging Settings</title> + + <para> + The following settings are only relevant for low-level VM + debugging. Regular users will never need these settings. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--tracing-enabled on|off</computeroutput>: + Enables the tracebuffer. This consumes some memory for the + tracebuffer and adds extra overhead. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--tracing-config + <config-string></computeroutput>: Enables tracing + configuration. In particular, this defines which group of + tracepoints are enabled. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--tracing-allow-vm-access + on|off</computeroutput>: Enables and disables VM access to + the tracebuffer. By default, this setting is disabled. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxmanage-usbcardreader"> + + <title>USB Card Reader Settings</title> + + <para> + The following setting defines access to a USB Card Reader by the + guest environment. USB card readers are typically used for + accessing data on memory cards such as CompactFlash (CF), Secure + Digital (SD), or MultiMediaCard (MMC). + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--usbcardreader on|off</computeroutput>: + Enables and disables the USB card reader interface. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxmanage-autostart"> + + <title>Autostarting VMs During Host System Boot</title> + + <para> + These settings configure the VM autostart feature, which + automatically starts the VM at host system boot-up. Note that + there are prerequisites that need to be addressed before using + this feature. See <xref linkend="autostart" />. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--autostart-enabled on|off</computeroutput>: + Enables and disables VM autostart at host system boot-up, + using the specified user name. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--autostart-delay + <seconds></computeroutput>: Specifies a delay, in + seconds, following host system boot-up, before the VM + autostarts. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="vboxmanage-clonevm"> + + <title>VBoxManage clonevm</title> + + <para> + The <command>VBoxManage clonevm</command> command creates a clone + of an existing virtual machine (VM). The clone can be a full copy + of the VM or a linked copy of a VM. + </para> + +<screen> +VBoxManage clonevm <replaceable>vm</replaceable> [ --basefolder <replaceable>basefolder</replaceable> ] +[ --group <replaceable>group</replaceable>, ... ] [ --mode machine | machinechildren | all ] +[ --name <replaceable>name</replaceable> ] [ --options link | keepallmacs | keepnatmacs | keepdisknames | keephwuuids ] +[ --register ] [ --snapshot <replaceable>vm</replaceable> ] [ --uuid <replaceable>uuid</replaceable> ] +</screen> + + <para> + In addition to specifying the name of the VM to clone, which is + required, you can specify any of the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + <option>--basefolder</option> + <replaceable>basefolder</replaceable> specifies the name of + the folder in which to save the configuration for the new VM. + </para> + </listitem> + + <listitem> + <para> + <option>--groups <replaceable>group</replaceable>, + ...</option> assigns the clone to the specified group or + groups. If you specify more than one group, separate each + group name with a comma. + </para> + + <para> + Note that each group is identified by a group ID that starts + with a slash character (<computeroutput>/</computeroutput>) so + that groups can be nested. By default, a clone is always + assigned membership to the <computeroutput>/</computeroutput> + group. + </para> + </listitem> + + <listitem> + <para> + <option>--mode machine|machineandchildren|all</option> + specifies which of the following cloning modes to use: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>machine</computeroutput> mode clones the + current state of the existing VM without any snapshots. + This is the default mode. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>machineandchildren</computeroutput> mode + clones the snapshot specified by by the + <option>--snapshot</option> option and all child + snapshots. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>all</computeroutput> mode clones all + snapshots and the current state of the existing VM. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <option>--name <replaceable>name</replaceable></option> + specifies a new name for the new VM. The default value is + "<replaceable>name</replaceable> Clone", where + <replaceable>name</replaceable> is the original name of the + VM. + </para> + </listitem> + + <listitem> + <para> + <option>--options</option> specifies how to create a new + clone. + </para> + + <itemizedlist> + + <listitem> + <para> + <option>--options link</option> creates a linked clone, + which can be cloned only from a snapshot. + </para> + </listitem> + + <listitem> + <para> + <option>--options keepallmacs</option> specifies that the + new clone reuses the MAC addresses of each virtual network + card from the existing VM. + </para> + + <para> + If you do not specify this option or the <option>--options + keepnatmacs</option> option, the default behavior is to + reinitialize the MAC addresses of each virtual network + card. + </para> + </listitem> + + <listitem> + <para> + <option>--options keepnatmacs</option> specifies that the + new clone reuses the MAC addresses of each virtual network + card from the existing VM when the network type is NAT. + </para> + + <para> + If you do not specify this option or the <option>--options + keepallmacs</option> option, the default behavior is to + reinitialize the MAC addresses of each virtual network + card. + </para> + </listitem> + + <listitem> + <para> + <option>--option keepdisknames</option> specifies that the + new clone reuses the disk image names from the existing + VM. By default, disk images are renamed. You can preserve + source hardware IDs by adding + <computeroutput>keephwuuids</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + <option>--option keephwuuids</option> specifies that the + new clone reuses the hardware IDs from the existing VM. By + default, new UUIDs are used. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <option>--register</option> automatically registers the new + clone in this &product-name; installation. You can manually + register the new VM later by using the <command>VBoxManage + registervm</command> command. See + <xref linkend="vboxmanage-registervm" />. + </para> + </listitem> + + <listitem> + <para> + <option>--snapshot <replaceable>vm</replaceable></option> + specifies the snapshot on which to base the new VM. By + default, the clone is created from the current state of the + specified VM. + </para> + </listitem> + + <listitem> + <para> + <option>--uuid <replaceable>uuid</replaceable></option> + specifies the UUID for the new VM. Ensure that this ID is + unique for the &product-name; instance if you decide to + register this new VM. By default, &product-name; provides a + new UUID. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-movevm"> + + <title>VBoxManage movevm</title> + + <para> + This command moves a virtual machine to a new location on the + host. + </para> + + <para> + Associated files of the virtual machine, such as settings files + and disk image files, are moved to the new location. The + &product-name; configuration is updated automatically. + </para> + + <para> + The <command>movevm</command> subcommand requires the name of the + virtual machine which should be moved. + </para> + + <para> + Also required is the type of move operation, specified by + <computeroutput>--type basic</computeroutput>. Other types of move + operation may be supported in future releases. + </para> + + <para> + The <computeroutput>--folder</computeroutput> setting configures + the new location on the host file system. Enter a relative + pathname or a full pathname. + </para> + + </sect1> + + <sect1 id="vboxmanage-import"> + + <title>VBoxManage import</title> + + <para> + This command imports a virtual appliance in OVF format by copying + the virtual disk images and creating virtual machines in + &product-name;. See <xref linkend="ovf" /> for an introduction to + appliances. + </para> + + <para> + The <command>import</command> subcommand takes at least the path + name of an OVF file as input and expects the disk images, if + needed, in the same directory as the OVF file. A lot of additional + command-line options are supported to control in detail what is + being imported and modify the import parameters, but the details + depend on the content of the OVF file. + </para> + + <para> + It is therefore recommended to first run the + <command>import</command> subcommand with the + <computeroutput>--dry-run</computeroutput> or + <computeroutput>-n</computeroutput> option. This will then print a + description of the appliance's contents to the screen how it would + be imported into &product-name;, together with the optional + command-line options to influence the import behavior. + </para> + + <para> + Use of the <computeroutput>--options + keepallmacs|keepnatmacs|keepdisknames</computeroutput> option + enables additional fine tuning of the clone operation. The first + two options enable specification of how the MAC addresses of every + virtual network card should be handled. They can either be + reinitialized, which is the default setting, left unchanged + (<computeroutput>keepallmacs</computeroutput>) or left unchanged + when the network type is NAT + (<computeroutput>keepnatmacs</computeroutput>). If you add + <computeroutput>keepdisknames</computeroutput> all new disk images + are assigned the same names as the originals, otherwise they are + renamed. + </para> + + <para> + As an example, the following is a screen output for a sample + appliance containing a Windows XP guest: + </para> + +<screen>VBoxManage import WindowsXp.ovf --dry-run +Interpreting WindowsXp.ovf... +OK. +Virtual system 0: + 0: Suggested OS type: "WindowsXP" + (change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all) + 1: Suggested VM name "Windows XP Professional_1" + (change with "--vsys 0 --vmname <name>") + 2: Suggested VM group "/" + (change with "--vsys 0 --group <group>") + 3: Suggested VM settings file name "/home/klaus/VirtualBox VMs/dummy2 2/dummy2 2.vbox" + (change with "--vsys 0 --settingsfile <filename>") + 4: Suggested VM base folder "/home/klaus/VirtualBox VMs" + (change with "--vsys 0 --basefolder <path>") + 5: End-user license agreement + (display with "--vsys 0 --eula show"; + accept with "--vsys 0 --eula accept") + 6: Number of CPUs: 1 + (change with "--vsys 0 --cpus <n>") + 7: Guest memory: 956 MB (change with "--vsys 0 --memory <MB>") + 8: Sound card (appliance expects "ensoniq1371", can change on import) + (disable with "--vsys 0 --unit 5 --ignore") + 9: USB controller + (disable with "--vsys 0 --unit 6 --ignore") +10: Network adapter: orig bridged, config 2, extra type=bridged +11: Floppy + (disable with "--vsys 0 --unit 8 --ignore") +12: SCSI controller, type BusLogic + (change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}"; + disable with "--vsys 0 --unit 9 --ignore") +13: IDE controller, type PIIX4 + (disable with "--vsys 0 --unit 10 --ignore") +14: Hard disk image: source image=WindowsXp.vmdk, + target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0 + (change controller with "--vsys 0 --unit 11 --controller <id>"; + disable with "--vsys 0 --unit 11 --ignore")</screen> + + <para> + The individual configuration items are numbered, and depending on + their type support different command-line options. The import + subcommand can be directed to ignore many such items with a + <computeroutput>--vsys X --unit Y --ignore</computeroutput> + option, where X is the number of the virtual system and Y the item + number, as printed on the screen. X is zero, unless there are + several virtual system descriptions in the appliance. + </para> + + <para> + In the above example, Item #1 specifies the name of the target + machine in &product-name;. Items #9 and #10 specify hard disk + controllers, respectively. Item #11 describes a hard disk image. + In this case, the additional + <computeroutput>--controller</computeroutput> option indicates + which item the disk image should be connected to, with the default + coming from the OVF file. + </para> + + <para> + You can combine several items for the same virtual system behind + the same <computeroutput>--vsys</computeroutput> option. For + example, to import a machine as described in the OVF, but without + the sound card and without the USB controller, and with the disk + image connected to the IDE controller instead of the SCSI + controller, use the following command: + </para> + +<screen>VBoxManage import WindowsXp.ovf + --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen> + + </sect1> + + <sect1 id="vboxmanage-export"> + + <title>VBoxManage export</title> + + <para> + This command exports one or more virtual machines from + &product-name;. You can export to either of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + A virtual appliance in OVF format, including copying their + virtual disk images to compressed VMDK. + </para> + </listitem> + + <listitem> + <para> + A cloud service, such as &oci;. A single VM can be exported in + VMDK format. + </para> + </listitem> + + </itemizedlist> + + <para> + See <xref linkend="ovf" /> for more details on exporting VMs from + &product-name;. + </para> + + <sect2 id="vboxmanage-export-ovf"> + + <title>Export to OVF</title> + + <para> + List the machine, or the machines, that you would like to export + to the same OVF file and specify the target OVF file after an + additional <computeroutput>--output</computeroutput> or + <computeroutput>-o</computeroutput> option. Note that the + directory of the target OVF file will also receive the exported + disk images in the compressed VMDK format, regardless of the + original format, and should have enough disk space left for + them. + </para> + + <para> + Beside a simple export of a given virtual machine, you can + append several product information to the appliance file. Use + <computeroutput>--product</computeroutput>, + <computeroutput>--producturl</computeroutput>, + <computeroutput>--vendor</computeroutput>, + <computeroutput>--vendorurl</computeroutput>, + <computeroutput>--version</computeroutput> and + <computeroutput>--description</computeroutput> to specify this + additional information. For legal reasons you may add a license + text or the content of a license file by using the + <computeroutput>--eula</computeroutput> and + <computeroutput>--eulafile</computeroutput> option respectively. + </para> + + <para> + As with OVF import, you use the <computeroutput>--vsys + X</computeroutput> option to apply these options to the correct + virtual machine. + </para> + + <para> + For virtualization products which are not fully compatible with + the OVF standard 1.0 you can enable an OVF 0.9 legacy mode with + the <computeroutput>--legacy09</computeroutput> option. Other + options are <computeroutput>--ovf09</computeroutput>, + <computeroutput>--ovf10</computeroutput>, + <computeroutput>--ovf20</computeroutput>. + </para> + + <para> + To specify options controlling the exact content of the + appliance file, you can use <option>--options</option> to + request the creation of a manifest file, which enables detection + of corrupted appliances on import, the additional export of DVD + images, and the exclusion of MAC addresses. You can specify a + list of options, such as <option>--options + manifest,nomacs</option>. For details, check the help output of + <command>VBoxManage export</command>. + </para> + + </sect2> + + <sect2 id="vboxmanage-export-cloud"> + + <title>Export to &oci;</title> + + <para> + By default, an exported disk image is converted into stream VMDK + format. This ensures compatibility with &oci;. + </para> + + <para> + List the machine that you want to export to &oci; and specify + the target cloud service provider by using the + <computeroutput>--output</computeroutput> or + <computeroutput>-o</computeroutput> option. + </para> + + <para> + To export a VM to a cloud service such as &oci;, use the + <option>--cloud</option> option to specify the VM to export. + This option works in the same way as the <option>--vsys</option> + option for OVF export. + </para> + + <para> + Some of the following options are settings for the VM instance. + As a result, you must enter an Oracle Cloud Identifier (OCID) + for a resource. Use the &oci; Console to view OCIDs. + </para> + + <itemizedlist> + + <listitem> + <para> + <option>--output/-o</option>: Specifies the short name of + the cloud service provider to which you export. For &oci;, + enter <computeroutput>OCI://</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + <option>--cloud</option> + <replaceable>number-of-virtual-system</replaceable>: + Specifies a number that identifies the VM that you are + exporting. Numbering starts at + <computeroutput>0</computeroutput> for the first VM. + </para> + </listitem> + + <listitem> + <para> + <option>--vmname</option> <replaceable>name</replaceable>: + Specifies the name of the exported VM. This name is used as + the VM instance name in &oci;. + </para> + </listitem> + + <listitem> + <para> + <option>--cloudprofile</option> + <replaceable>cloud-profile-name</replaceable>: Specifies the + cloud profile that is used to connect to the cloud service + provider. The cloud profile contains your &oci; account + details, such as your user OCID and the fingerprint for your + public key. See <xref linkend="ovf-export-oci"/>. + </para> + + <para> + To use a cloud profile, you must have the required + permissions on &oci;. + </para> + + <remark> + Add xref to information about the required permissions. + </remark> + </listitem> + + <listitem> + <para> + <option>--cloudshape</option> + <replaceable>shape</replaceable>: Specifies the shape used + for the VM instance. The shape defines the number of CPUs + and the amount of memory allocated to the VM instance. The + shape must be compatible with the exported image. + </para> + </listitem> + + <listitem> + <para> + <option>--clouddomain</option> + <replaceable>domain</replaceable>: Specifies the + availability domain to use for the VM instance. Enter the + OCID for the availability domain. + </para> + </listitem> + + <listitem> + <para> + <option>--clouddisksize</option> + <replaceable>disk-size-in-GB</replaceable>: Specifies the + disk size used for the exported disk image in gigabytes. The + minimum value is 50 GB and the maximum value is 300 GB. + </para> + </listitem> + + <listitem> + <para> + <option>--cloudbucket</option> + <replaceable>bucket-name</replaceable>: Specifies the bucket + in which to store the uploaded files. In &oci;, a bucket is + a logical container for storing objects. + </para> + </listitem> + + <listitem> + <para> + <option>--cloudocivcn</option> + <replaceable>OCI-vcn-ID</replaceable>: Specifies the virtual + cloud network (VCN) to use for the VM instance. Enter the + OCID for the VCN. + </para> + </listitem> + + <listitem> + <para> + <option>--cloudocisubnet</option> + <replaceable>OCI-subnet-ID</replaceable>: Specifies the + subnet of the VCN to use for the VM instance. Enter the OCID + for the subnet. + </para> + </listitem> + + <listitem> + <para> + <option>--cloudkeepobject true | false</option>: Specifies + whether to store the exported disk image in Oracle Object + Storage. + </para> + </listitem> + + <listitem> + <para> + <option>--cloudlaunchinstance true | false</option>: + Specifies whether to start the VM instance after the export + to &oci; completes. + </para> + </listitem> + + <listitem> + <para> + <option>--cloudpublicip true | false</option>: Specifies + whether to enable a public IP address for the VM instance. + </para> + </listitem> + + </itemizedlist> + + <para> + The following example shows a typical command line for exporting + a VM to &oci;. + </para> + + <remark> + For the next release, describe exactly what this command does in + terms of the command line options. + </remark> + +<screen># VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \ +--cloudprofile "standard user" --cloudbucket myBucket \ +--cloudshape VM.Standard2.1 --clouddomain aaaa:US-ASHBURN-AD-1 --clouddisksize 50 \ +--cloudocivcn ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet ocid1.subnet.oc1.iad.aaaa... \ +--cloudkeepobject true --cloudlaunchinstance true --cloudpublicip true</screen> + + </sect2> + + </sect1> + + <sect1 id="vboxmanage-startvm"> + + <title>VBoxManage startvm</title> + + <para> + This command starts a virtual machine that is currently in the + Powered Off or Saved states. + </para> + + <para> + The optional <computeroutput>--type</computeroutput> specifier + determines whether the machine will be started in a window or + whether the output should go through + <command>VBoxHeadless</command>, with VRDE enabled or not. See + <xref linkend="vboxheadless" />. The list of types is subject to + change, and it is not guaranteed that all types are accepted by + any product variant. + </para> + + <para> + The global or per-VM default value for the VM frontend type will + be taken if the type is not explicitly specified. If none of these + are set, the GUI variant will be started. + </para> + + <para> + The following values are allowed: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>gui</computeroutput> + </term> + + <listitem> + <para> + Starts a VM showing a GUI window. This is the default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>headless</computeroutput> + </term> + + <listitem> + <para> + Starts a VM without a window for remote display only. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>separate</computeroutput> + </term> + + <listitem> + <para> + Starts a VM with a detachable UI. Technically, it is a + headless VM with user interface in a separate process. This + is an experimental feature as it lacks certain + functionality, such as 3D acceleration. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <note> + <para> + If you experience problems with starting virtual machines with + particular frontends and there is no conclusive error + information, consider starting virtual machines directly by + running the respective front-end, as this can give additional + error information. + </para> + </note> + + </sect1> + + <sect1 id="vboxmanage-controlvm"> + + <title>VBoxManage controlvm</title> + + <para> + The <command>controlvm</command> subcommand enables you to change + the state of a virtual machine that is currently running. The + following can be specified: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>VBoxManage controlvm <vm> pause</command>: + Temporarily puts a virtual machine on hold, without + permanently changing its state. The VM window is gray, to + indicate that the VM is currently paused. This is equivalent + to selecting the <emphasis role="bold">Pause</emphasis> item + in the <emphasis role="bold">Machine</emphasis> menu of the + GUI. + </para> + </listitem> + + <listitem> + <para> + Use <command>VBoxManage controlvm <vm> resume</command>: + Undoes a previous <command>pause</command> command. This is + equivalent to selecting the + <emphasis role="bold">Resume</emphasis> item in the + <emphasis role="bold">Machine</emphasis> menu of the GUI. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxManage controlvm <vm> reset</command>: Has + the same effect on a virtual machine as pressing the Reset + button on a real computer. A cold reboot of the virtual + machine is done, which immediately restarts and reboots the + guest operating system. The state of the VM is not saved + beforehand, and data may be lost. This is equivalent to + selecting the <emphasis role="bold">Reset</emphasis> item in + the <emphasis role="bold">Machine</emphasis> menu of the GUI. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxManage controlvm <vm> poweroff</command>: + Has the same effect on a virtual machine as pulling the power + cable on a real computer. The state of the VM is not saved + beforehand, and data may be lost. This is equivalent to + selecting the <emphasis role="bold">Close</emphasis> item in + the <emphasis role="bold">Machine</emphasis> menu of the GUI, + or clicking the VM window's close button, and then selecting + <emphasis role="bold">Power Off the Machine</emphasis> in the + displayed dialog. + </para> + + <para> + After this, the VM's state will be Powered Off. From that + state, it can be started again. See + <xref + linkend="vboxmanage-startvm" />. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxManage controlvm <vm> savestate</command>: + Saves the current state of the VM to disk and then stops the + VM. This is equivalent to selecting the + <emphasis role="bold">Close</emphasis> item in the + <emphasis role="bold">Machine</emphasis> menu of the GUI or + clicking the VM window's close button, and then selecting + <emphasis role="bold">Save the Machine State</emphasis> in the + displayed dialog. + </para> + + <para> + After this, the VM's state will be Saved. From this state, it + can be started again. See + <xref linkend="vboxmanage-startvm" />. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxManage controlvm <vm> + acpipowerbutton</command>: Sends an ACPI shutdown signal to + the VM, as if the power button on a real computer had been + pressed. So long as the VM is running a fairly modern guest + operating system providing ACPI support, this should trigger a + proper shutdown mechanism from within the VM. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxManage controlvm <vm> keyboardputscancode + <hex> [<hex>...]</command>: Sends commands using + keycodes to the VM. Keycodes are documented in the public + domain. For example: + http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxManage controlvm "VM name" teleport --hostname + <name> --port <port> [--passwordfile <file> + | --password <password>]</command>: Makes the machine + the source of a teleporting operation and initiates a teleport + to the given target. See <xref linkend="teleporting" />. If + the optional password is specified, it must match the password + that was given to the <command>modifyvm</command> command for + the target machine. See + <xref linkend="vboxmanage-modifyvm-teleport" />. + </para> + </listitem> + + </itemizedlist> + + <para> + The following extra options are available with + <command>controlvm</command> that do not directly affect the VM's + running state: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>setlinkstate<1-N></computeroutput>: + Connects or disconnects virtual network cables from their + network interfaces. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>nic<1-N> + null|nat|bridged|intnet|hostonly|generic|natnetwork[<devicename>]</computeroutput>: + Specifies the type of networking that should be made available + on the specified VM virtual network card. They available types + are: not connected to the host + (<computeroutput>null</computeroutput>), use network address + translation (<computeroutput>nat</computeroutput>), bridged + networking (<computeroutput>bridged</computeroutput>), + communicate with other virtual machines using internal + networking (<computeroutput>intnet</computeroutput>), + host-only networking + (<computeroutput>hostonly</computeroutput>), natnetwork + networking (<computeroutput>natnetwork</computeroutput>), or + access to rarely used submodes + (<computeroutput>generic</computeroutput>). These options + correspond to the modes which are described in detail in + <xref + linkend="networkingmodes" />. + </para> + </listitem> + + <listitem> + <para> + With the <computeroutput>nictrace</computeroutput> options, + you can optionally trace network traffic by dumping it to a + file, for debugging purposes. + </para> + + <para> + <computeroutput>nictrace<1-N> on|off</computeroutput>: + Enables network tracing for a particular virtual network card. + </para> + + <para> + If enabled, you must specify with + <computeroutput>--nictracefile<1-N> + <filename></computeroutput> the pathname of the file to + which the trace should be logged. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>nicpromisc<1-N> + deny|allow-vms|allow-all</computeroutput>: Specifies how the + promiscious mode is handled for the specified VM virtual + network card. This setting is only relevant for bridged + networking. The default setting of + <computeroutput>deny</computeroutput> hides any traffic not + intended for this VM. + <computeroutput>allow-vms</computeroutput> hides all host + traffic from this VM but enables the VM to see traffic to and + from other VMs. <computeroutput>allow-all</computeroutput> + removes this restriction completely. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>nicproperty<1-N> + <paramname>="paramvalue"</computeroutput>: This option, + in combination with + <computeroutput>nicgenericdrv</computeroutput> enables you to + pass parameters to rarely-used network backends. + </para> + + <para> + Those parameters are backend engine-specific, and are + different between UDP Tunnel and the VDE backend drivers. See + <xref linkend="network_udp_tunnel" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>natpf<1-N> + [<name>],tcp|udp,[<hostip>],<hostport>,[<guestip>], + <guestport></computeroutput>: Specifies a NAT + port-forwarding rule. See <xref linkend="natforward"/>. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>natpf<1-N> delete + <name></computeroutput>: Deletes a NAT port-forwarding + rule. See <xref linkend="natforward"/>. + </para> + </listitem> + + <listitem> + <para> + The <computeroutput>guestmemoryballoon<balloon size in + MB></computeroutput>: Changes the size of the guest memory + balloon. This is the memory allocated by the &product-name; + Guest Additions from the guest operating system and returned + to the hypervisor for reuse by other virtual machines. This + must be specified in megabytes. See + <xref linkend="guestadd-balloon" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>usbattach<uuid|address> [--capturefile + <filename>]</computeroutput> + </para> + + <para> + and <computeroutput>usbdetach <uuid|address> + [--capturefile <filename>]</computeroutput>: Makes host + USB devices visible or invisible to the virtual machine on the + fly, without the need for creating filters first. The USB + devices can be specified by UUID (unique identifier) or by + address on the host system. Use the + <computeroutput>--capturefile</computeroutput> option to + specify the absolute path of a file for writing activity + logging data. + </para> + + <para> + You can use <command>VBoxManage list usbhost</command> to + locate this information. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>audioin on</computeroutput>: Selects whether + capturing audio from the host is enabled or disabled. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>audioout on</computeroutput>: Selects whether + audio playback from the guest is enabled or disabled. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>clipboard + disabled|hosttoguest|guesttohost|bidirectional</computeroutput>: + Selects how the guest or host operating system's clipboard + should be shared with the host or guest. See + <xref linkend="generalsettings" />. This requires that the + Guest Additions be installed in the virtual machine. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>draganddrop + disabled|hosttoguest|guesttohost|bidirectional</computeroutput>: + Selects the current drag and drop mode being used between the + host and the virtual machine. See + <xref linkend="guestadd-dnd" />. This requires that the Guest + Additions be installed in the virtual machine. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrde on|off</computeroutput>: Enables and + disables the VRDE server, if it is installed. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeport + default|<ports></computeroutput>: Changes the port or a + range of ports that the VRDE server can bind to. + <computeroutput>default</computeroutput> or + <computeroutput>0</computeroutput> means port 3389, the + standard port for RDP. See the description for the + <computeroutput>--vrdeport</computeroutput> option in + <xref + linkend="vboxmanage-modifyvm-vrde" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "TCP/Ports|Address=<value>"</computeroutput>: Sets the + port numbers and IP address on the VM to which the VRDE server + can bind. + </para> + + <itemizedlist> + + <listitem> + <para> + For TCP/Ports, <value> should be a port or a range + of ports to which the VRDE server can bind. + <computeroutput>default</computeroutput> or + <computeroutput>0</computeroutput> means port 3389, the + standard port for RDP. See the description for the + <computeroutput>--vrdeport</computeroutput> option in + <xref + linkend="vboxmanage-modifyvm-vrde" />. + </para> + </listitem> + + <listitem> + <para> + For TCP/Address, <value>: The IP address of the host + network interface that the VRDE server will bind to. If + specified, the server will accept connections only on the + specified host network interface. See the description for + the <computeroutput>--vrdeaddress</computeroutput> option + in + <xref + linkend="vboxmanage-modifyvm-vrde" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "VideoChannel/Enabled|Quality|DownscaleProtection=<value>"</computeroutput>: + Sets the VRDP video redirection properties. + </para> + + <itemizedlist> + + <listitem> + <para> + For VideoChannel/Enabled, <value> can be set to "1" + switching the VRDP video channel on. See + <xref linkend="vrde-videochannel" />. + </para> + </listitem> + + <listitem> + <para> + For VideoChannel/Quality, <value> should be set + between 10 and 100% inclusive, representing a JPEG + compression level on the VRDE server video channel. Lower + values mean lower quality but higher compression. See + <xref linkend="vrde-videochannel" />. + </para> + </listitem> + + <listitem> + <para> + For VideoChannel/DownscaleProtection, <value> can be + set to "1" to enable the videochannel downscale protection + feature. When enabled, if a video's size equals the shadow + buffer size, then it is regarded as a full screen video, + and is displayed. If its size is between fullscreen and + the downscale threshold it is not displayed, as it could + be an application window, which would be unreadable when + downscaled. When the downscale protection feature is + disabled, an attempt is always made to display videos. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1"</computeroutput>: + Disables one of the VRDE server features: Display, Input, + Audio, or USB. To reenable a feature, use + "Client/DisableDisplay=" for example. See + <xref linkend="vrde-customization" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Client/DisableClipboard|DisableUpstreamAudio=1"</computeroutput>. + Disables one of the VRDE server features: Clipboard or + UpstreamAudio. To reenable a feature, use + "Client/DisableClipboard=" for example. See + <xref linkend="vrde-customization" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Client/DisableRDPDR=1"</computeroutput>: Disables the VRDE + server feature: RDP device redirection for smart cards. To + reenable this feature, use "Client/DisableRDPR=". + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "H3DRedirect/Enabled=1"</computeroutput>: Enables the VRDE + server feature: 3D redirection. To disable this feature, use + "H3DRedirect/Enabled=". + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=<value>"</computeroutput>: + Sets the desired security method, path of the server + certificate, path of the server private key, and path of CA + certificate, used for a connection. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Security/Method=<value>"</computeroutput>: Sets the + desired security method, which is used for a connection. + Valid values are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>Negotiate</computeroutput>: Both + Enhanced (TLS) and Standard RDP Security connections + are allowed. The security method is negotiated with + the client. This is the default setting. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>RDP</computeroutput>: Only Standard + RDP Security is accepted. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>TLS</computeroutput>: Only Enhanced + RDP Security is accepted. The client must support TLS. + </para> + </listitem> + + </itemizedlist> + + <para> + See <xref linkend="vrde-crypt" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Security/ServerCertificate=<value>"</computeroutput> + where <value> is the absolute path of the server + certificate. See <xref linkend="vrde-crypt" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Security/ServerPrivateKey=<value>"</computeroutput> + where <value> is the absolute path of the server + private key. See <xref linkend="vrde-crypt" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Security/CACertificate=<value>"</computeroutput> + where <value> is the absolute path of the CA self + signed certificate. See <xref linkend="vrde-crypt" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Audio/RateCorrectionMode|LogPath=<value>"</computeroutput>: + Sets the audio connection mode, or path of the audio logfile. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Audio/RateCorrectionMode=<value>"</computeroutput> + where <value> is the desired rate correction mode, + allowed values are: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput>: + No mode specified, use to unset any Audio mode already + set. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput>: + Rate correction mode. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput>: + Low pass filter mode. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput>: + Client sync mode to prevent underflow or overflow of + the client queue. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>vrdeproperty + "Audio/LogPath=<value>"</computeroutput> where + <value> is the absolute path of the audio log file. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>vrdevideochannelquality + <percent></computeroutput>: Sets the image quality for + video redirection. See <xref linkend="vrde-videochannel" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>setvideomodehint</computeroutput>: Requests + that the guest system change to a particular video mode. This + requires that the Guest Additions be installed, and will not + work for all guest systems. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>screenshotpng</computeroutput>: Takes a + screenshot of the guest display and saves it in PNG format. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>recording on|off</computeroutput> enables or + disables the recording of a VM session into a WebM/VP8 file. + When this option value is <computeroutput>on</computeroutput>, + recording begins when the VM session starts. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>recordingscreens + all|<replaceable>screen-ID</replaceable> + [<replaceable>screen-ID</replaceable> ...]</computeroutput> + enables you to specify which VM screens to record. The + recording for each screen that you specify is saved to its own + file. You cannot modify this setting while recording is + enabled. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>recordingfile + <replaceable>filename</replaceable></computeroutput> specifies + the file in which to save the recording. You cannot modify + this setting while recording is enabled. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>recordingvideores + <replaceable>width</replaceable>x<replaceable>height</replaceable></computeroutput> + specifies the resolution of the recorded video in pixels. You + cannot modify this setting while recording is enabled. + </para> + </listitem> + + <listitem> +<!-- @todo r=andy Clarify rate. --> + + <para> + <computeroutput>recordingvideorate + <replaceable>bit-rate</replaceable></computeroutput> specifies + the bit rate of the video in kilobits per second. Increasing + this value improves the appearance of the video at the cost of + an increased file size. You cannot modify this setting while + recording is enabled. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>recordingvideofps + <replaceable>fps</replaceable></computeroutput> specifies the + maximum number of video frames per second (FPS) to record. + Frames that have a higher frequency are skipped. Increasing + this value reduces the number of skipped frames and increases + the file size. You cannot modify this setting while recording + is enabled. + </para> + </listitem> + + <listitem> +<!-- @todo r=andy Clarify time format. --> + + <para> + <computeroutput>recordingmaxtime + <replaceable>seconds</replaceable></computeroutput> specifies + the maximum amount time to record in seconds. The recording + stops after the specified number of seconds elapses. If this + value is zero, the recording continues until you stop the + recording. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>recordingmaxsize + <replaceable>MB</replaceable></computeroutput> specifies the + maximum size of the recorded video file in megabytes. The + recording stops when the file reaches the specified size. If + this value is zero, the recording continues until you stop the + recording. You cannot modify this setting while recording is + enabled. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>recordingopts + <replaceable>keyword</replaceable>=<replaceable>value</replaceable>[,<replaceable>keyword</replaceable>=<replaceable>value</replaceable> + ...]</computeroutput> specifies additional recording options + in a comma-separated keyword-value format. For example, + <computeroutput>foo=bar,a=b</computeroutput>. You cannot + modify this setting while recording is enabled. + </para> + + <para> + Only use this option only if you are an advanced user. For + information about keywords, see <emphasis>Oracle VM VirtualBox + Programming Guide and Reference</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>setcredentials</computeroutput>: Used for + remote logins on Windows guests. See + <xref linkend="autologon" />. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>teleport --host <name> --port + <port></computeroutput>: Configures a VM as a target for + teleporting. <name> specifies the virtual machine name. + <port> specifies the port on the virtual machine which + should listen for teleporting requests from other virtual + machines. It can be any free TCP/IP port number, such as 6000. + See <xref linkend="teleporting" />. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--maxdowntime + <msec></computeroutput>: Specifies the maximum + downtime, in milliseconds, for the teleporting target VM. + Optional. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--password + <password></computeroutput>: The teleporting request + will only succeed if the source machine specifies the same + password as the one given with this command. Optional. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--passwordfile <password + file></computeroutput>: The teleporting request will + only succeed if the source machine specifies the same + password as the one specified in the password file with + the path specified with this command. Use + <computeroutput>stdin</computeroutput> to read the + password from stdin. Optional. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>plugcpu|unplugcpu <id></computeroutput>: + If CPU hot-plugging is enabled, this setting adds and removes + a virtual CPU to the virtual machine. + <computeroutput><id></computeroutput> specifies the + index of the virtual CPU to be added or removed and must be a + number from 0 to the maximum number of CPUs configured. CPU 0 + can never be removed. + </para> + </listitem> + + <listitem> + <para> + The <computeroutput>cpuexecutioncap + <1-100></computeroutput>: Controls how much CPU time a + virtual CPU can use. A value of 50 implies a single virtual + CPU can use up to 50% of a single host CPU. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>webcam attach <path|alias> + [<keyword=value>[;<keyword=value>...]]</computeroutput>: + Attaches a webcam to a running VM. Specify the absolute path + of the webcam on the host operating system, or use its alias, + obtained by using the command: <command>VBoxManage list + webcams</command>. + </para> + + <para> + Note that alias '.0' means the default video input device on + the host operating system, '.1', '.2', etc. mean first, + second, etc. video input device. The device order is + host-specific. + </para> + + <para> + The optional settings parameter is a + <computeroutput>;</computeroutput> delimited list of + name-value pairs, enabling configuration of the emulated + webcam device. + </para> + + <para> + The following settings are supported: + </para> + + <para> + MaxFramerate: Specifies the highest rate in frames per second, + at which video frames are sent to the guest. Higher frame + rates increase CPU load, so this setting can be useful when + there is a need to reduce CPU load. The default setting is + <computeroutput>no maximum limit</computeroutput>, thus + enabling the guest to use all frame rates supported by the + host webcam. + </para> + + <para> + MaxPayloadTransferSize: Specifies the maximum number of bytes + the emulated webcam can send to the guest in one buffer. The + default setting is 3060 bytes, which is used by some webcams. + Higher values can slightly reduce CPU load, if the guest is + able to use larger buffers. Note that higher + MaxPayloadTransferSize values may be not supported by some + guest operating systems. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>webcam detach + <path|alias></computeroutput>: Detaches a webcam from a + running VM. Specify the absolute path of the webcam on the + host, or use its alias obtained from the <command>webcam + list</command> command. + </para> + + <para> + Please note the following points, relating to specific host + operating systems: + </para> + + <itemizedlist> + + <listitem> + <para> + Windows hosts: When the webcam device is detached from the + host, the emulated webcam device is automatically detached + from the guest. + </para> + </listitem> + + <listitem> + <para> + Mac OS X hosts: OS X version 10.7 or newer is required. + </para> + + <para> + When the webcam device is detached from the host, the + emulated webcam device remains attached to the guest and + must be manually detached using the <command>VBoxManage + controlvm webcam detach</command> command. + </para> + </listitem> + + <listitem> + <para> + Linux hosts: When the webcam is detached from the host, + the emulated webcam device is automatically detached from + the guest only if the webcam is streaming video. If the + emulated webcam is inactive, it should be manually + detached using the <command>VBoxManage controlvm webcam + detach</command> command. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>webcam list</computeroutput>: Lists webcams + attached to the running VM. The output is a list of absolute + paths or aliases that were used for attaching the webcams to + the VM using the <command>webcam attach</command> command. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>addencpassword <id> <password + file>|- [--removeonsuspend + <yes|no>]</computeroutput>: Supplies an encrypted VM + specified by <id> with the encryption password to enable + a headless start. Either specify the absolute path of a + password file on the host file system: <password file>, + or use <option>-</option> to instruct + <command>VBoxManage</command> to prompt the user for the + encryption password. + </para> + + <para> + <computeroutput>--removeonsuspend + <yes|no></computeroutput>: Specifies whether to remove + the passsword or keep the password in VM memory when the VM is + suspended. If the VM has been suspended and the password has + been removed, the user needs to resupply the password before + the VM can be resumed. This feature is useful in cases where + the user does not want the password to be stored in VM memory, + and the VM is suspended by a host suspend event. + </para> + + <note> + <para> + On &product-name; versions 5.0 and later, data stored on + hard disk images can be transparently encrypted for the + guest. &product-name; uses the AES algorithm in XTS mode and + supports 128 or 256 bit data encryption keys (DEK). The DEK + is stored encrypted in the medium properties, and is + decrypted during VM startup by supplying the encryption + password. + </para> + </note> + + <para> + The <command>VBoxManage encryptmedium</command> command is + used to create a DEK encrypted medium. See + <xref linkend="diskencryption-encryption" />. When starting an + encrypted VM from the &product-name; GUI, the user will be + prompted for the encryption password. + </para> + + <para> + For a headless encrypted VM start, use the following command: + </para> + +<screen> + VBoxManage startvm "vmname" --type headless + </screen> + + <para> + Then supply the required encryption password as follows: + </para> + +<screen> + VBoxManage "vmname" controlvm "vmname" addencpassword ... + </screen> + + <para></para> + </listitem> + + <listitem> + <para> + <computeroutput>removeencpassword <id></computeroutput>: + Removes encryption password authorization for password + <id> for all encrypted media attached to the VM. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>removeallencpasswords</computeroutput>: + Removes encryption password authorization for all passwords + for all encrypted media attached to the VM. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>changeuartmode <1-N></computeroutput>: + Changes the connection mode for a given virtual serial port. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-discardstate"> + + <title>VBoxManage discardstate</title> + + <para> + This command discards the saved state of a virtual machine which + is not currently running. This will cause the VM's operating + system to restart next time you start it. This is the equivalent + of pulling out the power cable on a physical machine, and should + be avoided if possible. + </para> + + </sect1> + + <sect1 id="vboxmanage-adoptstate"> + + <title>VBoxManage adoptstate</title> + + <para> + If you have a Saved state file + (<computeroutput>.sav</computeroutput>) that is separate from the + VM configuration, you can use this command to + <emphasis>adopt</emphasis> the file. This will change the VM to + saved state and when you start it, &product-name; will attempt to + restore it from the saved state file you indicated. This command + should only be used in special setups. + </para> + + </sect1> + + <sect1 id="vboxmanage-snapshot"> + + <title>VBoxManage snapshot</title> + + <para> + This command is used to control snapshots from the command line. A + snapshot consists of a complete copy of the virtual machine + settings, copied at the time when the snapshot was taken, and + optionally a virtual machine saved state file if the snapshot was + taken while the machine was running. After a snapshot has been + taken, &product-name; creates a differencing hard disk for each + normal hard disk associated with the machine so that when a + snapshot is restored, the contents of the virtual machine's + virtual hard disks can be quickly reset by simply dropping the + preexisting differencing files. + </para> + +<screen>VBoxManage snapshot <uuid|vmname> + take <name> [--description <desc>] [--live] + [--uniquename Number,Timestamp,Space,Force] | + delete <uuid|snapname> | + restore <uuid|snapname> | + restorecurrent | + edit <uuid|snapname>|--current + [--name <name>] + [--description <desc>] | + list [--details|--machinereadable] + showvminfo <uuid|snapname></screen> + + <para> + The <command>take</command> operation takes a snapshot of the + current state of the virtual machine. You must supply a name for + the snapshot and can optionally supply a description. The new + snapshot is inserted into the snapshots tree as a child of the + current snapshot and then becomes the new current snapshot. The + <computeroutput>--description</computeroutput> parameter enables + you to describe the snapshot. If + <computeroutput>--live</computeroutput> is specified, the VM will + not be stopped during the snapshot creation. This is called live + snapshotting. + </para> + + <para> + The <command>delete</command> operation deletes a snapshot, + specified by name or by UUID. This can take a while to finish + since the differencing images associated with the snapshot might + need to be merged with their child differencing images. + </para> + + <para> + The <command>restore</command> operation will restore the given + snapshot, specified by name or by UUID, by resetting the virtual + machine's settings and current state to that of the snapshot. The + previous current state of the machine will be lost. After this, + the given snapshot becomes the new current snapshot so that + subsequent snapshots are inserted under the snapshot from which + was restored. + </para> + + <para> + The <command>restorecurrent</command> operation is a shortcut to + restore the current snapshot, which is the snapshot from which the + current state is derived. This subcommand is equivalent to using + the <command>restore</command> subcommand with the name or UUID of + the current snapshot, except that it avoids the extra step of + determining that name or UUID. + </para> + + <para> + With the <command>edit</command> operation, you can change the + name or description of an existing snapshot. + </para> + + <para> + The <command>list</command> operation shows all snapshots of a + virtual machine. + </para> + + <para> + With the <command>showvminfo</command> operation, you can view the + virtual machine settings that were stored with an existing + snapshot. + </para> + + </sect1> + + <sect1 id="vboxmanage-closemedium"> + + <title>VBoxManage closemedium</title> + + <para> + This command removes a hard disk, DVD, or floppy image from a + &product-name; media registry. + </para> + +<screen>VBoxManage closemedium [disk|dvd|floppy] <uuid|filename> + [--delete]</screen> + + <para> + Optionally, you can request that the image be deleted. You will + get appropriate diagnostics that the deletion failed, however the + image will become unregistered in any case. + </para> + + </sect1> + + <sect1 id="vboxmanage-storageattach"> + + <title>VBoxManage storageattach</title> + + <para> + This command attaches, modifies, and removes a storage medium + connected to a storage controller that was previously added with + the <command>storagectl</command> command. The syntax is as + follows: + </para> + +<screen>VBoxManage storageattach <uuid|vmname> + --storagectl <name> + [--port <number>] + [--device <number>] + [--type dvddrive|hdd|fdd] + [--medium none|emptydrive|additions| + <uuid>|<filename>|host:<drive>|iscsi] + [--mtype normal|writethrough|immutable|shareable + readonly|multiattach] + [--comment <text>] + [--setuuid <uuid>] + [--setparentuuid <uuid>] + [--passthrough on|off] + [--tempeject on|off] + [--nonrotational on|off] + [--discard on|off] + [--hotpluggable on|off] + [--bandwidthgroup name|none] + [--forceunmount] + [--server <name>|<ip>] + [--target <target>] + [--tport <port>] + [--lun <lun>] + [--encodedlun <lun>] + [--username <username>] + [--password <password>] + [--passwordfile <file>] + [--initiator <initiator>] + [--intnet]</screen> + + <para> + A number of parameters are commonly required. Some parameters are + required only for iSCSI targets. + </para> + + <para> + The common parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>uuid|vmname</computeroutput> + </term> + + <listitem> + <para> + The VM UUID or VM Name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--storagectl</computeroutput> + </term> + + <listitem> + <para> + Name of the storage controller. Mandatory. The list of the + storage controllers currently attached to a VM can be + obtained with <command>VBoxManage showvminfo</command>. See + <xref linkend="vboxmanage-showvminfo" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--port</computeroutput> + </term> + + <listitem> + <para> + The number of the storage controller's port which is to be + modified. Mandatory, unless the storage controller has only + a single port. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--device</computeroutput> + </term> + + <listitem> + <para> + The number of the port's device which is to be modified. + Mandatory, unless the storage controller has only a single + device per port. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--type</computeroutput> + </term> + + <listitem> + <para> + Define the type of the drive to which the medium is being + attached, detached, or modified. This argument can only be + omitted if the type of medium can be determined from either + the medium given with the + <computeroutput>--medium</computeroutput> argument or from a + previous medium attachment. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--medium</computeroutput> + </term> + + <listitem> + <para> + Specifies what is to be attached. The following values are + supported: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>none</computeroutput>: Any existing + device should be removed from the given slot. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>emptydrive</computeroutput>: For a + virtual DVD or floppy drive only, this makes the device + slot behave like a removeable drive into which no media + has been inserted. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>additions</computeroutput>: For a + virtual DVD drive only, this attaches the + <emphasis>VirtualBox Guest Additions</emphasis> image to + the given device slot. + </para> + </listitem> + + <listitem> + <para> + If a UUID is specified, it must be the UUID of a storage + medium that is already known to &product-name;. For + example, because it has been attached to another virtual + machine. See <xref linkend="vboxmanage-list" /> for + details of how to list known media. This medium is then + attached to the given device slot. + </para> + </listitem> + + <listitem> + <para> + If a filename is specified, it must be the full path of + an existing disk image in ISO, RAW, VDI, VMDK, or other + format. The disk image is then attached to the given + device slot. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>host:<drive></computeroutput>: For + a virtual DVD or floppy drive only, this connects the + given device slot to the specified DVD or floppy drive + on the host computer. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>iscsi</computeroutput>: For virtual hard + disks only, this is used for specifying an iSCSI target. + In this case, additional parameters must be given. These + are described below. + </para> + </listitem> + + </itemizedlist> + + <para> + Some of the above changes, in particular for removeable + media such as floppies and CDs/DVDs, can be effected while a + VM is running. Others, such as device changes or changes in + hard disk device slots, require the VM to be powered off. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--mtype</computeroutput> + </term> + + <listitem> + <para> + Defines how this medium behaves with respect to snapshots + and write operations. See <xref linkend="hdimagewrites" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--comment</computeroutput> + </term> + + <listitem> + <para> + An optional description that you want to have stored with + this medium. For example, for an iSCSI target, "Big storage + server downstairs". This is purely descriptive and not + needed for the medium to function correctly. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--setuuid, --setparentuuid</computeroutput> + </term> + + <listitem> + <para> + Modifies the UUID or parent UUID of a medium before + attaching it to a VM. This is an expert option. + Inappropriate use can make the medium unusable or lead to + broken VM configurations if any other VM is referring to the + same media already. The most frequently used variant is + <computeroutput>--setuuid ""</computeroutput>, which assigns + a new random UUID to an image. This option is useful for + resolving duplicate UUID errors if you duplicated an image + using a file copy utility. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--passthrough</computeroutput> + </term> + + <listitem> + <para> + For a virtual DVD drive only, you can enable DVD writing + support. This feature is currently experimental, see + <xref + linkend="storage-cds" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--tempeject</computeroutput> + </term> + + <listitem> + <para> + For a virtual DVD drive only, you can configure the behavior + for guest-triggered medium eject. If this is set to on, the + eject has only a temporary effect. If the VM is powered off + and restarted the originally configured medium will be still + in the drive. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--nonrotational</computeroutput> + </term> + + <listitem> + <para> + Enables you to enable the non-rotational flag for virtual + hard disks. Some guests, such as Windows 7 or later, treat + such disks like SSDs and do not perform disk fragmentation + on such media. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--discard</computeroutput> + </term> + + <listitem> + <para> + Enables the auto-discard feature for a virtual hard disks. + This specifies that a VDI image will be shrunk in response + to the trim command from the guest OS. The following + requirements must be met: + </para> + + <itemizedlist> + + <listitem> + <para> + The disk format must be VDI. + </para> + </listitem> + + <listitem> + <para> + The size of the cleared area must be at least 1 MB. + </para> + </listitem> + + <listitem> + <para> + &product-name; will only trim whole 1 MB blocks. The + VDIs themselves are organized into 1 MB blocks, so this + will only work if the space being trimmed is at least a + 1 MB contiguous block at a 1 MB boundary. On Windows, + occasional defragmentation with <command>defrag.exe + /D</command>, or on Linux running <command>btrfs + filesystem defrag</command> as a background cron job may + be beneficial. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + The Guest OS must be configured to issue the + <command>trim</command> command, and typically this means + that the guest OS is made to see the disk as an SSD. Ext4 + supports the -o discard mount flag. Mac OS X probably + requires additional settings. Windows should automatically + detect and support SSDs, at least in versions 7, 8, and + 10. The Linux exFAT driver from Samsung supports the + <command>trim</command> command. + </para> + </note> + + <para> + It is unclear whether Microsoft's implementation of exFAT + supports this feature, even though that file system was + originally designed for flash. + </para> + + <para> + Alternatively, there are other methods to issue trim. For + example, the Linux <command>fstrim</command> command, part + of the util-linux package. Earlier solutions required a user + to zero out unused areas, using zerofree or similar, and to + compact the disk. This is only possible when the VM is + offline. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--bandwidthgroup</computeroutput> + </term> + + <listitem> + <para> + Sets the bandwidth group to use for the given device. See + <xref linkend="storage-bandwidth-limit" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--forceunmount</computeroutput> + </term> + + <listitem> + <para> + For a virtual DVD or floppy drive only, this forcibly + unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy + even if the previous one is locked down by the guest for + reading. See <xref linkend="storage-cds" />. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + When <computeroutput>iscsi</computeroutput> is used with the + <computeroutput>--medium</computeroutput> parameter for iSCSI + support, additional parameters must or can be used. See also + <xref linkend="storage-iscsi" />. + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>--server</computeroutput> + </term> + + <listitem> + <para> + The host name or IP address of the iSCSI target. Required. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--target</computeroutput> + </term> + + <listitem> + <para> + Target name string. This is determined by the iSCSI target + and used to identify the storage resource. Required. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--tport</computeroutput> + </term> + + <listitem> + <para> + TCP/IP port number of the iSCSI service on the target. + Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--lun</computeroutput> + </term> + + <listitem> + <para> + Logical Unit Number of the target resource. Optional. Often, + this value is zero. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--encodedlun</computeroutput> + </term> + + <listitem> + <para> + Hex-encoded Logical Unit Number of the target resource. + Optional. Often, this value is zero. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--username, --password, + --passwordfile</computeroutput> + </term> + + <listitem> + <para> + Username and password, called the initiator secret, for + target authentication, if required. Optional. + </para> + + <note> + <para> + Username and password are stored without encryption, in + clear text, in the XML machine configuration file if no + settings password is provided. When a settings password is + specified for the first time, the password is stored in + encrypted form. As an alternative to providing the + password on the command line, a reference to a file + containing the text can be provided using the + <computeroutput>passwordfile</computeroutput> option. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--initiator</computeroutput> + </term> + + <listitem> + <para> + iSCSI Initiator. Optional. + </para> + + <para> + Microsoft iSCSI Initiator is a system, such as a server that + attaches to an IP network and initiates requests and + receives responses from an iSCSI target. The SAN components + in Microsoft iSCSI Initiator are largely analogous to Fibre + Channel SAN components, and they include the following: + </para> + + <itemizedlist> + + <listitem> + <para> + To transport blocks of iSCSI commands over the IP + network, an iSCSI driver must be installed on the iSCSI + host. An iSCSI driver is included with Microsoft iSCSI + Initiator. + </para> + </listitem> + + <listitem> + <para> + A gigabit Ethernet adapter that transmits 1000 megabits + per second (Mbps) is recommended for the connection to + an iSCSI target. Like standard 10/100 adapters, most + gigabit adapters use a preexisting Category 5 or + Category 6E cable. Each port on the adapter is + identified by a unique IP address. + </para> + </listitem> + + <listitem> + <para> + An iSCSI target is any device that receives iSCSI + commands. The device can be an end node, such as a + storage device, or it can be an intermediate device, + such as a network bridge between IP and Fibre Channel + devices. Each port on the storage array controller or + network bridge is identified by one or more IP addresses + </para> + </listitem> + + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--intnet</computeroutput> + </term> + + <listitem> + <para> + If specified, connect to the iSCSI target using Internal + Networking. This needs further configuration, see + <xref linkend="iscsi-intnet" />. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect1> + + <sect1 id="vboxmanage-storagectl"> + + <title>VBoxManage storagectl</title> + + <para> + This command attaches, modifies, and removes a storage controller. + After this, virtual media can be attached to the controller with + the <command>storageattach</command> command. + </para> + + <para> + The syntax for this command is as follows: + </para> + +<screen>VBoxManage storagectl <uuid|vmname> + --name <name> + [--add ide|sata|scsi|floppy|sas|usb|pcie] + [--controller LSILogic|LSILogicSAS|BusLogic| + IntelAhci|PIIX3|PIIX4|ICH6|I82078| + USB|NVMe] + [--portcount <1-30>] + [--hostiocache on|off] + [--bootable on|off] + [--rename <name>] + [--remove]</screen> + + <para> + The parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>uuid|vmname</computeroutput> + </term> + + <listitem> + <para> + The VM UUID or VM Name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--name</computeroutput> + </term> + + <listitem> + <para> + Specifies the name of the storage controller. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--add</computeroutput> + </term> + + <listitem> + <para> + Specifies the type of the system bus to which the storage + controller must be connected. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--controller</computeroutput> + </term> + + <listitem> + <para> + Enables a choice of chipset type being emulated for the + given storage controller. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--portcount</computeroutput> + </term> + + <listitem> + <para> + This specifies the number of ports the storage controller + should support. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--hostiocache</computeroutput> + </term> + + <listitem> + <para> + Configures the use of the host I/O cache for all disk images + attached to this storage controller. See + <xref + linkend="iocaching" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--bootable</computeroutput> + </term> + + <listitem> + <para> + Specifies whether this controller is bootable. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--rename</computeroutput> + </term> + + <listitem> + <para> + Specifies a new name for the storage controller. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--remove</computeroutput> + </term> + + <listitem> + <para> + Removes the storage controller from the VM configuration. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect1> + + <sect1 id="vboxmanage-bandwidthctl"> + + <title>VBoxManage bandwidthctl</title> + + <para> + This command creates, deletes, modifies, and shows bandwidth + groups of the given virtual machine. + </para> + +<screen>VBoxManage bandwidthctl <uuid|vmname> + add <name> --type disk|network --limit <MBps>[k|m|g|K|M|G] | + set <name> --limit <MBps>[k|m|g|K|M|G] | + remove <name> | + list [--machinereadable]</screen> + + <para> + The following subcommands are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>add</command>: Creates a new bandwidth group of a + given type. + </para> + </listitem> + + <listitem> + <para> + <command>set</command>: Modifies the limit for an existing + bandwidth group. + </para> + </listitem> + + <listitem> + <para> + <command>remove</command>: Deletes a bandwidth group. + </para> + </listitem> + + <listitem> + <para> + <command>list</command>: Shows all bandwidth groups defined + for the given VM. Use the + <computeroutput>--machinereadable</computeroutput> option to + produce the same output, but in machine readable format. This + is of the form: name="value" on a line by line basis. + </para> + </listitem> + + </itemizedlist> + + <para> + The parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>uuid|vmname</computeroutput> + </term> + + <listitem> + <para> + The VM UUID or VM Name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--name</computeroutput> + </term> + + <listitem> + <para> + Name of the bandwidth group. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--type</computeroutput> + </term> + + <listitem> + <para> + Type of the bandwidth group. Mandatory. Two types are + supported: <computeroutput>disk</computeroutput> and + <computeroutput>network</computeroutput>. See + <xref linkend="storage-bandwidth-limit" /> or + <xref linkend="network_bandwidth_limit" /> for the + description of a particular type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--limit</computeroutput> + </term> + + <listitem> + <para> + Specifies the limit for the given bandwidth group. This can + be changed while the VM is running. The default unit is + megabytes per second. The unit can be changed by specifying + one of the following suffixes: + <computeroutput>k</computeroutput> for kilobits per second, + <computeroutput>m</computeroutput> for megabits per second, + <computeroutput>g</computeroutput> for gigabits per second, + <computeroutput>K</computeroutput> for kilobytes per second, + <computeroutput>M</computeroutput> for megabytes per second, + <computeroutput>G</computeroutput> for gigabytes per second. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <note> + <para> + The network bandwidth limits apply only to the traffic being + sent by virtual machines. The traffic being received by VMs is + unlimited. + </para> + </note> + + <note> + <para> + To remove a bandwidth group it must not be referenced by any + disks or adapters in the running VM. + </para> + </note> + + </sect1> + + <sect1 id="vboxmanage-showmediuminfo"> + + <title>VBoxManage showmediuminfo</title> + + <para> + This command shows information about a medium, notably its size, + its size on disk, its type, and the virtual machines which use it. + </para> + + <note> + <para> + For compatibility with earlier versions of &product-name;, the + <command>showvdiinfo</command> command is also supported and + mapped internally to the <command>showmediuminfo</command> + command. + </para> + </note> + +<screen>VBoxManage showmediuminfo [disk|dvd|floppy] <uuid|filename></screen> + + <para> + The medium must be specified either by its UUID, if the medium is + registered, or by its filename. Registered images can be listed + using <command>VBoxManage list hdds</command>, <command>VBoxManage + list dvds</command>, or <command>VBoxManage list + floppies</command>, as appropriate. See + <xref linkend="vboxmanage-list" />. + </para> + + </sect1> + + <sect1 id="vboxmanage-createmedium"> + + <title>VBoxManage createmedium</title> + + <para> + This command creates a new medium. The syntax is as follows: + </para> + +<screen>VBoxManage createmedium [disk|dvd|floppy] --filename <filename> + [--size <megabytes>|--sizebyte <bytes>] + [--diffparent <uuid>|<filename> + [--format VDI|VMDK|VHD] (default: VDI) + [--variant Standard,Fixed,Split2G,Stream,ESX]</screen> + + <para> + The parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>--filename <filename></computeroutput> + </term> + + <listitem> + <para> + Specifies a file name <filename> as an absolute path + on the host file system. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--size <megabytes></computeroutput> + </term> + + <listitem> + <para> + Specifies the image capacity, in 1 MB units. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--diffparent + <uuid>|<filename></computeroutput> + </term> + + <listitem> + <para> + Specifies the differencing image parent, either as a UUID or + by the absolute pathname of the file on the host file + system. Useful for sharing a base box disk image among + several VMs. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--format VDI|VMDK|VHD</computeroutput> + </term> + + <listitem> + <para> + Specifies the file format for the output file. Available + options are VDI, VMDK, VHD. The default format is VDI. + Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--variant</computeroutput> + </term> + + <listitem> + <para> + Specifies any required file format variants for the output + file. This is a comma-separated list of variant flags. + Options are Standard,Fixed,Split2G,Stream,ESX. Not all + combinations are supported, and specifying mutually + incompatible flags results in an error message. Optional. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <note> + <para> + For compatibility with earlier versions of &product-name;, the + <command>createvdi</command> and <command>createhd</command> + commands are also supported and mapped internally to the + <command>createmedium</command> command. + </para> + </note> + + </sect1> + + <sect1 id="vboxmanage-modifyvdi"> + + <title>VBoxManage modifymedium</title> + + <para> + With the <command>modifymedium</command> command, you can change + the characteristics of a disk image after it has been created. + </para> + +<screen>VBoxManage modifymedium [disk|dvd|floppy] <uuid|filename> + [--type normal|writethrough|immutable|shareable| + readonly|multiattach] + [--autoreset on|off] + [--property <name=[value]>] + [--compact] + [--resize <megabytes>|--resizebyte <bytes>] + [--move <path>] + [--setlocation <path>]</screen> + + <note> + <para> + For compatibility with earlier versions of &product-name;, the + <command>modifyvdi</command> and <command>modifyhd</command> + commands are also supported and mapped internally to the + <command>modifymedium</command> command. + </para> + </note> + + <para> + The disk image to modify must be specified either by its UUID, if + the medium is registered, or by its filename. Registered images + can be listed using <command>VBoxManage list hdds</command>, see + <xref linkend="vboxmanage-list" />. A filename must be specified + as a valid path, either as an absolute path or as a relative path + starting from the current directory. + </para> + + <para> + The following options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + With the <computeroutput>--type</computeroutput> argument, you + can change the type of an existing image between the normal, + immutable, write-through and other modes. See + <xref + linkend="hdimagewrites" />. + </para> + </listitem> + + <listitem> + <para> + For immutable hard disks only, the <computeroutput>--autoreset + on|off</computeroutput> option determines whether the disk is + automatically reset on every VM startup. See + <xref linkend="hdimagewrites" />. By default, autoreset is on. + </para> + </listitem> + + <listitem> + <para> + The <computeroutput>--compact</computeroutput> option can be + used to compact disk images. Compacting removes blocks that + only contains zeroes. Using this option will shrink a + dynamically allocated image. It will reduce the + <emphasis>physical</emphasis> size of the image without + affecting the logical size of the virtual disk. Compaction + works both for base images and for differencing images created + as part of a snapshot. + </para> + + <para> + For this operation to be effective, it is required that free + space in the guest system first be zeroed out using a suitable + software tool. For Windows guests, you can use the + <command>sdelete</command> tool provided by Microsoft. Run + <command>sdelete -z</command> in the guest to zero the free + disk space, before compressing the virtual disk image. For + Linux, use the <command>zerofree</command> utility which + supports ext2/ext3 filesystems. For Mac OS X guests, use the + <computeroutput>diskutil secureErase freespace 0 + /</computeroutput> command from an elevated Terminal. + </para> + + <para> + Please note that compacting is currently only available for + VDI images. A similar effect can be achieved by zeroing out + free blocks and then cloning the disk to any other dynamically + allocated format. You can use this workaround until compacting + is also supported for disk formats other than VDI. + </para> + </listitem> + + <listitem> + <para> + The <computeroutput>--resize x</computeroutput> option, where + x is the desired new total space in megabytes enables you to + change the capacity of an existing image. This adjusts the + <emphasis>logical</emphasis> size of a virtual disk without + affecting the physical size much. + </para> + + <para> + This option currently works only for VDI and VHD formats, and + only for the dynamically allocated variants. It can only be + used to expand, but not shrink, the capacity. For example, if + you originally created a 10 GB disk which is now full, you can + use the <computeroutput>--resize 15360</computeroutput> + command to change the capacity to 15 GB (15,360 MB) without + having to create a new image and copy all data from within a + virtual machine. Note however that this only changes the drive + capacity. You will typically next need to use a partition + management tool inside the guest to adjust the main partition + to fill the drive. + </para> + + <para> + The <computeroutput>--resizebyte x</computeroutput> option + does almost the same thing, except that x is expressed in + bytes instead of megabytes. + </para> + </listitem> + + <listitem> + <para> + The <computeroutput>--move <path></computeroutput> + option can be used to relocate a medium to a different + location <path> on the host file system. The path can be + either relative to the current directory or absolute. + </para> + </listitem> + + <listitem> + <para> + The <computeroutput>--setlocation + <path></computeroutput> option can be used to set the + new location <path> of the medium on the host file + system if the medium has been moved for any reasons. The path + can be either relative to the current directory or absolute. + </para> + + <note> + <para> + The new location is used as is, without any sanity checks. + The user is responsible for setting the correct path. + </para> + </note> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-clonevdi"> + + <title>VBoxManage clonemedium</title> + + <para> + This command duplicates a virtual disk, DVD, or floppy medium to a + new medium, usually an image file, with a new unique identifier + (UUID). The new image can be transferred to another host system or + reimported into &product-name; using the Virtual Media Manager. + See <xref linkend="vdis" /> and <xref linkend="cloningvdis" />. + The syntax is as follows: + </para> + +<screen>VBoxManage clonemedium [disk|dvd|floppy] <uuid|inputfile> <uuid|outputfile> + + [--format VDI|VMDK|VHD|RAW|<other>] + [--variant Standard,Fixed,Split2G,Stream,ESX] + [--existing]</screen> + + <para> + The medium to clone as well as the target image must be described + either by its UUIDs, if the mediums are registered, or by its + filename. Registered images can be listed by <command>VBoxManage + list hdds</command>. See <xref linkend="vboxmanage-list" />. A + filename must be specified as valid path, either as an absolute + path or as a relative path starting from the current directory. + </para> + + <para> + The following options are available: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>--format</computeroutput> + </term> + + <listitem> + <para> + Set a file format for the output file different from the + file format of the input file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--variant</computeroutput> + </term> + + <listitem> + <para> + Set a file format variant for the output file. This is a + comma-separated list of variant flags. Not all combinations + are supported, and specifying inconsistent flags will result + in an error message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--existing</computeroutput> + </term> + + <listitem> + <para> + Perform the clone operation to an already existing + destination medium. Only the portion of the source medium + which fits into the destination medium is copied. This means + if the destination medium is smaller than the source only a + part of it is copied, and if the destination medium is + larger than the source the remaining part of the destination + medium is unchanged. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <note> + <para> + For compatibility with earlier versions of &product-name;, the + <command>clonevdi</command> and <command>clonehd</command> + commands are still supported and mapped internally to the + <command>clonehd disk</command> command. + </para> + </note> + + </sect1> + + <sect1 id="vboxmanage-mediumproperty"> + + <title>VBoxManage mediumproperty</title> + + <para> + This command sets, gets, or deletes a medium property. The syntax + is as follows: + </para> + +<screen>VBoxManage mediumproperty [disk|dvd|floppy] set <uuid|filename> + <property> <value></screen> + + <itemizedlist> + + <listitem> + <para> + Use <computeroutput><disk|dvd|floppy></computeroutput> + to optionally specify the type of medium: disk (hard drive), + dvd, or floppy. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput><uuid|filename></computeroutput> to + supply either the UUID or absolute path of the medium or + image. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput><property></computeroutput> to + supply the name of the property. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput><value></computeroutput> to supply + the property value. + </para> + </listitem> + + </itemizedlist> + +<screen>VBoxManage mediumproperty [disk|dvd|floppy] get <uuid|filename> + <property></screen> + + <itemizedlist> + + <listitem> + <para> + Use <computeroutput><disk|dvd|floppy></computeroutput> + to optionally specify the type of medium: disk (hard drive), + dvd, or floppy. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput><uuid|filename></computeroutput> to + supply either the UUID or absolute path of the medium or + image. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput><property></computeroutput> to + supply the name of the property. + </para> + </listitem> + + </itemizedlist> + +<screen>VBoxManage mediumproperty [disk|dvd|floppy] delete <uuid|filename> + <property></screen> + + <itemizedlist> + + <listitem> + <para> + Use <computeroutput><disk|dvd|floppy></computeroutput> + to optionally specify the type of medium: disk (hard drive), + dvd, or floppy. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput><uuid|filename></computeroutput> to + supply either the UUID or absolute path of the medium or + image. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput><property></computeroutput> to + supply the name of the property. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-encryptmedium"> + + <title>VBoxManage encryptmedium</title> + + <para> + This command is used to create a DEK encrypted medium or image. + See <xref linkend="diskencryption-encryption" />. + </para> + + <para> + The syntax is as follows: + </para> + +<screen>VBoxManage encryptmedium <uuid|filename> + [--newpassword <file|->] + [--oldpassword <file|->] + [--cipher <cipher id>] + [--newpasswordid <password id>]</screen> + + <itemizedlist> + + <listitem> + <para> + Use <computeroutput><uuid|filename></computeroutput> to + supply the UUID or absolute path of the medium or image to be + encrypted. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput>--newpassword + <file|-></computeroutput> to supply a new encryption + password. Either specify the absolute pathname of a password + file on the host operating system, or + <computeroutput>-</computeroutput> to prompt you for the + password on the command line. Always use the + <computeroutput>--newpasswordid</computeroutput> option with + this option. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput>--oldpassword + <file|-></computeroutput> to supply any old encryption + password. Either specify the absolute pathname of a password + file on the host operating system, or + <computeroutput>-</computeroutput> to prompt you for the old + password on the command line. + </para> + + <para> + Use this option to gain access to an encrypted medium or image + to either change its password using + <computeroutput>--newpassword</computeroutput> or change its + encryption using <computeroutput>--cipher</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput>--cipher <cipher></computeroutput> + to specify the cipher to use for encryption. This can be + either <computeroutput>AES-XTS128-PLAIN64</computeroutput> or + <computeroutput>AES-XTS256-PLAIN64</computeroutput>. + </para> + + <para> + Use this option to change any existing encryption on the + medium or image, or to set up new encryption on it for the + first time. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput>--newpasswordid <password + id></computeroutput> to supply the new password identifier. + This can be chosen by the user, and is used for correct + identification when supplying multiple passwords during VM + startup. + </para> + + <para> + If the user uses the same password when encrypting multiple + images and also the same password identifier, the user needs + to supply the password only once during VM startup. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-checkmediumpwd"> + + <title>VBoxManage checkmediumpwd</title> + + <para> + This command is used to check the current encryption password on a + DEK encrypted medium or image. See + <xref linkend="diskencryption-encryption" />. + </para> + + <para> + The syntax is as follows: + </para> + +<screen>VBoxManage checkmediumpwd <uuid|filename> + <pwd file|-></screen> + + <itemizedlist> + + <listitem> + <para> + Use <computeroutput><uuid|filename></computeroutput> to + supply the UUID or absolute path of the medium or image to be + checked. + </para> + </listitem> + + <listitem> + <para> + Use <computeroutput><pwd file|-></computeroutput> to + supply the password identifier to be checked. Either specify + the absolute pathname of a password file on the host operating + system, or <computeroutput>-</computeroutput> to prompt you + for the password on the command line. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-convertfromraw"> + + <title>VBoxManage convertfromraw</title> + + <para> + This command converts a raw disk image to a &product-name; Disk + Image (VDI) file. The syntax is as follows: + </para> + +<screen>VBoxManage convertfromraw <filename> <outputfile> + [--format VDI|VMDK|VHD] + [--variant Standard,Fixed,Split2G,Stream,ESX] + [--uuid <uuid>] +VBoxManage convertfromraw stdin <outputfile> <bytes> + [--format VDI|VMDK|VHD] + [--variant Standard,Fixed,Split2G,Stream,ESX] + [--uuid <uuid>]</screen> + + <para> + The parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>--bytes</computeroutput> + </term> + + <listitem> + <para> + The size of the image file, in bytes, provided through + stdin. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--format</computeroutput> + </term> + + <listitem> + <para> + Select the disk image format to create. The default format + is VDI. Other options are VMDK and VHD. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--variant</computeroutput> + </term> + + <listitem> + <para> + Choose a file format variant for the output file. This is a + comma-separated list of variant flags. Not all combinations + are supported, and specifying inconsistent flags will result + in an error message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--uuid</computeroutput> + </term> + + <listitem> + <para> + Specify the UUID of the output file. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + The <command>stdin</command> form of the command forces + <command>VBoxManage</command> to read the content of the disk + image from standard input. This useful when using the command in a + pipe. + </para> + + <note> + <para> + For compatibility with earlier versions of &product-name;, the + <command>convertdd</command> command is also supported and + mapped internally to the <command>convertfromraw</command> + command. + </para> + </note> + + </sect1> + + <sect1 id="vboxmanage-extradata"> + + <title>VBoxManage getextradata/setextradata</title> + + <para> + These commands enable you to attach and retrieve string data for a + virtual machine or for a &product-name; configuration, by + specifying <computeroutput>global</computeroutput> instead of a + virtual machine name. You must specify a keyword as a text string + to associate the data with, which you can later use to retrieve + it. For example: + </para> + +<screen>VBoxManage setextradata Fedora5 installdate 2006.01.01 +VBoxManage setextradata SUSE10 installdate 2006.02.02</screen> + + <para> + This example would associate the string "2006.01.01" with the + keyword installdate for the virtual machine Fedora5, and + "2006.02.02" on the machine SUSE10. You could then retrieve the + information as follows: + </para> + +<screen>VBoxManage getextradata Fedora5 installdate</screen> + + <para> + This would return the following: + </para> + +<screen>VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +(C) 2005-2018 Oracle Corporation +All rights reserved. + +Value: 2006.01.01</screen> + + <para> + You could retrieve the information for all keywords as follows: + </para> + +<screen>VBoxManage getextradata Fedora5 enumerate</screen> + + <para> + To remove a keyword, the <command>setextradata</command> command + must be run without specifying data, only the keyword. For + example: + </para> + +<screen>VBoxManage setextradata Fedora5 installdate</screen> + + </sect1> + + <sect1 id="vboxmanage-setproperty"> + + <title>VBoxManage setproperty</title> + + <para> + This command is used to change global settings which affect the + entire &product-name; installation. Some of these correspond to + the settings in the <emphasis role="bold">Global + Settings</emphasis> dialog in the graphical user interface. The + following properties are available: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>machinefolder</computeroutput> + </term> + + <listitem> + <para> + Specifies the default folder in which virtual machine + definitions are kept. See <xref linkend="vboxconfigdata" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>hwvirtexclusive</computeroutput> + </term> + + <listitem> + <para> + Specifies whether &product-name; will make exclusive use of + the hardware virtualization extensions (Intel VT-x or AMD-V) + of the host system's processor. See + <xref linkend="hwvirt" />. If you wish to share these + extensions with other hypervisors running at the same time, + you must disable this setting. Doing so has negative + performance implications. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>vrdeauthlibrary</computeroutput> + </term> + + <listitem> + <para> + Specifies which library to use when external authentication + has been selected for a particular virtual machine. See + <xref linkend="vbox-auth" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>websrvauthlibrary</computeroutput> + </term> + + <listitem> + <para> + Specifies which library the web service uses to authenticate + users. For details about the &product-name; web service, see + the &product-name; SDK reference, + <xref + linkend="VirtualBoxAPI" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>vrdeextpack</computeroutput> + </term> + + <listitem> + <para> + Specifies which library implements the VirtualBox Remote + Desktop Extension. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>loghistorycount</computeroutput> + </term> + + <listitem> + <para> + Selects how many rotated VM logs are retained. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>autostartdbpath</computeroutput> + </term> + + <listitem> + <para> + Selects the path to the autostart database. See + <xref linkend="autostart" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>defaultfrontend</computeroutput> + </term> + + <listitem> + <para> + Selects the global default VM frontend setting. See + <xref linkend="vboxmanage-startvm" />. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>logginglevel</computeroutput> + </term> + + <listitem> + <para> + Configures the VBoxSVC release logging details. See + <ulink url="http://www.virtualbox.org/wiki/VBoxLogging">http://www.virtualbox.org/wiki/VBoxLogging</ulink>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>proxymode</computeroutput> + </term> + + <listitem> + <para> + Configures the mode for an HTTP proxy server. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>proxyurl</computeroutput> + </term> + + <listitem> + <para> + Configures the URL for an HTTP proxy server. Used when a + manual proxy is configured using the + <computeroutput>manual</computeroutput> setting of the + <computeroutput>proxymode</computeroutput> property. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect1> + + <sect1 id="vboxmanage-usbfilter"> + + <title>VBoxManage usbfilter add/modify/remove</title> + +<screen>VBoxManage usbfilter add <index,0-N> + --target <uuid|vmname>global + --name <string> + --action ignore|hold (global filters only) + [--active yes|no (yes)] + [--vendorid <XXXX> (null)] + [--productid <XXXX> (null)] + [--revision <IIFF> (null)] + [--manufacturer <string> (null)] + [--product <string> (null)] + [--remote yes|no (null, VM filters only)] + [--serialnumber <string> (null)] + [--maskedinterfaces <XXXXXXXX>] + </screen> + +<screen>VBoxManage usbfilter modify <index,0-N> + --target <uuid|vmname>global + [--name <string>] + [--action ignore|hold (global filters only)] + [--active yes|no] + [--vendorid <XXXX>] + [--productid <XXXX>] + [--revision <IIFF>] + [--manufacturer <string>] + [--product <string>] + [--remote yes|no (null, VM filters only)] + [--serialnumber <string>] + [--maskedinterfaces <XXXXXXXX>] + </screen> + +<screen>VBoxManage usbfilter remove <index,0-N> + --target <uuid|vmname>global + </screen> + + <para> + The <command>usbfilter</command> commands are used for working + with USB filters in virtual machines, or global filters which + affect the whole &product-name; setup. Global filters are applied + before machine-specific filters, and may be used to prevent + devices from being captured by any virtual machine. Global filters + are always applied in a particular order, and only the first + filter which fits a device is applied. For example, if the first + global filter says to hold, or make available, a particular + Kingston memory stick device and the second filter says to ignore + all Kingston devices. That particular Kingston memory stick will + be available to any machine with the appropriate filter, but no + other Kingston device will. + </para> + + <para> + When creating a USB filter using <command>usbfilter add</command>, + you must supply three or four mandatory parameters. The index + specifies the position in the list at which the filter should be + placed. If there is already a filter at that position, then it and + the following ones will be shifted back one place. Otherwise, the + new filter will be added onto the end of the list. The + <computeroutput>target</computeroutput> parameter selects the + virtual machine that the filter should be attached to or use + <computeroutput>global</computeroutput> to apply it to all virtual + machines. <computeroutput>name</computeroutput> is a name for the + new filter. For global filters, + <computeroutput>action</computeroutput> says whether to allow VMs + access to devices that fit the filter description (hold) or not to + give them access (ignore). In addition, you should specify + parameters to filter by. You can find the parameters for devices + attached to your system using <command>VBoxManage list + usbhost</command>. Finally, you can specify whether the filter + should be active. For local filters, whether they are for local + devices, remote devices over an RDP connection, or either. + </para> + + <para> + When you modify a USB filter using <command>usbfilter + modify</command>, you must specify the filter by index and by + target, which is either a virtual machine or + <computeroutput>global</computeroutput>. See the output of + <command>VBoxManage list usbfilters</command> to find global + filter indexes and <command>VBoxManage showvminfo</command> to + find indexes for individual machines. The properties which can be + changed are the same as for <command>usbfilter add</command>. To + remove a filter, use <command>usbfilter remove</command> and + specify the index and the target. + </para> + + <para> + The following is a list of the additional <command>usbfilter + add</command> and <command>usbfilter modify</command> options, + with details of how to use them. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>--action ignore|hold</computeroutput>: + Specifies whether devices that fit the filter description are + allowed access by machines (hold), or have access denied + (ignore). Applies to global filters only. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--active yes|no</computeroutput>: Specifies + whether the USB Filter is active or temporarily disabled. For + <computeroutput>usbfilter create</computeroutput> the default + is active. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--vendorid <XXXX>|""</computeroutput>: + Specifies a vendor ID filter. The string representation for an + exact match has the form XXXX, where X is the hexadecimal + digit, including leading zeroes. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--productid <XXXX>|""</computeroutput>: + Specifies a product ID filter. The string representation for + an exact match has the form XXXX, where X is the hexadecimal + digit, including leading zeroes. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--revision <IIFF>|""</computeroutput>: + Specifies a revision ID filter. The string representation for + an exact match has the form IIFF, where I is the decimal digit + of the integer part of the revision, and F is the decimal + digit of its fractional part, including leading and trailing + zeros. Note that for interval filters, it is best to use the + hexadecimal form, because the revision is stored as a 16-bit + packed BCD value. Therefore, the expression int:0x0100-0x0199 + will match any revision from 1.0 to 1.99 inclusive. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--manufacturer + <string>|""</computeroutput>: Specifies a manufacturer + ID filter, as a string. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--product <string>|""</computeroutput>: + Specifies a product ID filter, as a string. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--remote yes|no""</computeroutput>: Specifies + a remote filter, indicating whether the device is physically + connected to a remote VRDE client or to a local host machine. + Applies to VM filters only. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--serialnumber + <string>|""</computeroutput>: Specifies a serial number + filter, as a string. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--maskedinterfaces + <XXXXXXXX></computeroutput>: Specifies a masked + interface filter, for hiding one or more USB interfaces from + the guest. The value is a bit mask where the set bits + correspond to the USB interfaces that should be hidden, or + masked off. This feature only works on Linux hosts. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-sharedfolder"> + + <title>VBoxManage sharedfolder add/remove</title> + +<screen> +VBoxManage sharedfolder add <uuid|vmname> + --name <name> --hostpath <hostpath> + [--transient] [--readonly] [--automount] +</screen> + + <para> + This command enables you to share folders on the host computer + with guest operating systems. For this, the guest systems must + have a version of the &product-name; Guest Additions installed + which supports this functionality. + </para> + + <para> + Parameters are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput><uuid|vmname></computeroutput>: + Specifies the UUID or name of the VM whose guest operating + system will be sharing folders with the host computer. + Mandatory. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--name <name></computeroutput>: + Specifies the name of the share. Each share has a unique name + within the namespace of the host operating system. Mandatory. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>-hostpath <hostpath></computeroutput>: + Specifies the absolute path on the host operating system of + the directory to be shared with the guest operating system. + Mandatory. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>-transient</computeroutput>: Specifies that + the share is transient, meaning that it can be added and + removed at runtime and does not persist after the VM has + stopped. Optional. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>-readonly</computeroutput>: Specifies that the + share has only read-only access to files at the host path. + </para> + + <para> + By default, shared folders have read/write access to the files + on the host path. On Linux distributions, shared folders are + mounted with 770 file permissions with root user and vboxsf as + the group. Using this option the file permissions change to + 700. Optional. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>-automount</computeroutput>: Specifies that + the share will be automatically mounted. On Linux + distributions, this will be to either + <computeroutput>/media/USER/sf_<name></computeroutput> + or <computeroutput>/media/sf_<name></computeroutput>, + where <name> is the share named. The actual location + depends on the guest OS. Optional. + </para> + </listitem> + + </itemizedlist> + +<screen> +VBoxManage sharedfolder remove <uuid|vmname> + --name <name> [--transient] + +</screen> + + <para> + This command enables you to delete shared folders on the host + computer shares with the guest operating systems. For this, the + guest systems must have a version of the &product-name; Guest + Additions installed which supports this functionality. + </para> + + <para> + Parameters are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput><uuid|vmname></computeroutput>: + Specifies the UUID or name of the VM whose guest operating + system is sharing folders with the host computer. Mandatory. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--name <name></computeroutput>: + Specifies the name of the share to be removed. Each share has + a unique name within the namespace of the host operating + system. Mandatory. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>-transient</computeroutput>: Specifies that + the share is transient, meaning that it can be added and + removed at runtime and does not persist after the VM has + stopped. Optional. + </para> + </listitem> + + </itemizedlist> + + <para> + Shared folders are described in <xref linkend="sharedfolders" />. + </para> + + </sect1> + + <sect1 id="vboxmanage-guestproperty"> + + <title>VBoxManage guestproperty</title> + + <para> + The <command>guestproperty</command> commands enable you to get or + set properties of a running virtual machine. See + <xref linkend="guestadd-guestprops" />. Guest properties are + arbitrary keyword-value string pairs which can be written to and + read from by either the guest or the host, so they can be used as + a low-volume communication channel for strings, provided that a + guest is running and has the Guest Additions installed. In + addition, a number of values whose keywords begin with + <computeroutput>/VirtualBox/</computeroutput>are automatically set + and maintained by the Guest Additions. + </para> + + <para> + The following subcommands are available, where + <computeroutput><vm></computeroutput> can either be a VM + name or a VM UUID, as with the other <command>VBoxManage</command> + commands: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>enumerate <vm> [--patterns + <pattern>]</computeroutput>: Lists all the guest + properties that are available for the given VM, including the + value. This list will be very limited if the guest's service + process cannot be contacted, for example because the VM is not + running or the Guest Additions are not installed. + </para> + + <para> + If <computeroutput>--patterns <pattern></computeroutput> + is specified, it acts as a filter to only list properties that + match the given pattern. The pattern can contain the following + wildcard characters: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>*</computeroutput> (asterisk): Represents + any number of characters. For example, + "<computeroutput>/VirtualBox*</computeroutput>" would + match all properties beginning with "/VirtualBox". + </para> + </listitem> + + <listitem> + <para> + <computeroutput>?</computeroutput> (question mark): + Represents a single arbitrary character. For example, + "<computeroutput>fo?</computeroutput>" would match both + "foo" and "for". + </para> + </listitem> + + <listitem> + <para> + <computeroutput>|</computeroutput> (pipe symbol): Can be + used to specify multiple alternative patterns. For + example, "<computeroutput>s*|t*</computeroutput>" would + match anything starting with either "s" or "t". + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>get <vm> + <property></computeroutput>: Retrieves the value of a + single property only. If the property cannot be found, for + example because the guest is not running, the following + message is shown: + </para> + +<screen>No value set!</screen> + </listitem> + + <listitem> + <para> + <computeroutput>set <vm> <property> [<value> + [--flags <flags>]]</computeroutput>: Enables you to set + a guest property by specifying the keyword and value. If + <computeroutput><value></computeroutput> is omitted, the + property is deleted. With + <computeroutput>--flags</computeroutput>, you can specify + additional behavior. You can combine several flags by + separating them with commas. + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>TRANSIENT</computeroutput>: The value will + not be stored with the VM data when the VM exits. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>TRANSRESET</computeroutput>: The value + will be deleted as soon as the VM restarts or exits. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>RDONLYGUEST</computeroutput>: The value + can only be changed by the host, but the guest can only + read it. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>RDONLYHOST</computeroutput>: The value can + only be changed by the guest, but the host can only read + it. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>READONLY</computeroutput>: The value + cannot be changed at all. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <computeroutput>wait <vm> <pattern> --timeout + <timeout></computeroutput>: Waits for a particular value + described by the pattern string to change or to be deleted or + created. The pattern rules are the same as for the + <command>enumerate</command> subcommand. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>delete <vm> + <property></computeroutput>: Deletes a guest property + which has been set previously. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-guestcontrol"> + + <title>VBoxManage guestcontrol</title> + + <para> + The <command>guestcontrol</command> commands enable control of the + guest from the host. See + <xref + linkend="guestadd-guestcontrol" /> for an introduction. + </para> + + <para> + The <command>guestcontrol</command> command has two sets of + subcommands. The first set requires guest credentials to be + specified, the second does not. + </para> + + <para> + The first set of subcommands is of the following form: + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> <sub-command> + [--username <name> ] + [--passwordfile <file> | --password <password>] + [--domain <domain> ] + [-v|--verbose] [-q|quiet] ... + </screen> + + <para> + The common options are as follows: + </para> + +<screen> + [--username <name> ] + [--passwordfile <file> | --password <password>] + [--domain <domain> ] + [-v|--verbose] [-q|quiet] + </screen> + + <para> + The common options for the first set of subcommands are explained + in the following list. + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--username <name></computeroutput> + </term> + + <listitem> + <para> + Specifies the user name on guest OS under which the process + should run. This user name must already exist on the guest + OS. If unspecified, the host user name is used. Optional + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--passwordfile + <file>|--password</computeroutput> + </term> + + <listitem> + <para> + Specifies the absolute path on guest file system of password + file containing the password for the specified user account + or password for the specified user account. Optional. If + both are omitted, empty password is assumed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--domain <domain></computeroutput> + </term> + + <listitem> + <para> + User domain for Windows guests. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>-v|--verbose</computeroutput> + </term> + + <listitem> + <para> + Makes the subcommand execution more verbose. Optional + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>-q|--quiet</computeroutput> + </term> + + <listitem> + <para> + Makes the subcommand execution quieter. Optional. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + The first set of subcommands are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>run</computeroutput>: Executes a guest + program, forwarding stdout, stderr, and stdin to and from the + host until it completes. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> run [common-options] + --exe <path to executable> [--timeout <msec>] + [-E|--putenv <NAME>[=<VALUE>]] [--unquoted-args] + [--ignore-operhaned-processes] [--profile] + [--no-wait-stdout|--wait-stdout] + [--no-wait-stderr|--wait-stderr] + [--dos2unix] [--unix2dos] + -- <program/arg0> [argument1] ... [argumentN]] + </screen> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--exe <path to + executable></computeroutput> + </term> + + <listitem> + <para> + Specifies the absolute path of the executable on the + guest OS file system. Mandatory. For example: + <computeroutput>C:\Windows\System32\calc.exe</computeroutput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--timeout <msec></computeroutput> + </term> + + <listitem> + <para> + Specifies the maximum time, in microseconds, that the + executable can run, during which + <command>VBoxManage</command> receives its output. + Optional. If unspecified, <command>VBoxManage</command> + waits indefinitely for the process to end, or an error + occurs. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>-E|--putenv + <NAME>=<VALUE></computeroutput> + </term> + + <listitem> + <para> + Sets, modifies, and unsets environment variables in the + environment in which the program will run. Optional. + </para> + + <para> + The guest process is created with the standard default + guest OS environment. Use this option to modify that + default environment. To set or modify a variable use: + <computeroutput><NAME>=<VALUE></computeroutput>. + To unset a variable use: + <computeroutput><NAME>=</computeroutput> + </para> + + <para> + Any spaces in names and values should be enclosed by + quotes. + </para> + + <para> + To set, modify, and unset multiple variables, use + multiple instances of the + <computeroutput>--E|--putenv</computeroutput> option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--unquoted-args</computeroutput> + </term> + + <listitem> + <para> + Disables escaped double quoting, such as \"fred\", on + arguments passed to the executed program. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--ignore-operhaned-processes</computeroutput> + </term> + + <listitem> + <para> + Ignore orphaned processes. Not yet implemented. + Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--profile</computeroutput> + </term> + + <listitem> + <para> + Use Profile. Not yet implemented. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--no-wait-stdout|--wait-stdout</computeroutput> + </term> + + <listitem> + <para> + Does not wait or waits until the guest process ends and + receives its exit code and reason/flags. In the case of + <computeroutput>--wait-stdout</computeroutput>, + <command>VBoxManage</command> receives its stdout while + the process runs. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--no-wait-stderr|--wait-stderr</computeroutput> + </term> + + <listitem> + <para> + Does not wait or waits until the guest process ends and + receives its exit code, error messages, and flags. In + the case of + <computeroutput>--wait-stderr</computeroutput>, + <command>VBoxManage</command> receives its stderr while + the process runs. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--dos2unix</computeroutput> + </term> + + <listitem> + <para> + Converts output from DOS/Windows guests to + UNIX/Linux-compatible line endings, CR + LF to LF. Not + yet implemented. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--unix2dos</computeroutput> + </term> + + <listitem> + <para> + Converts output from a UNIX/Linux guests to + DOS/Windows-compatible line endings, LF to CR + LF. Not + yet implemented. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>[-- <program/arg0> + [<argument1>] ... + [<argumentN>]]</computeroutput> + </term> + + <listitem> + <para> + Specifies the program name, followed by one or more + arguments to pass to the program. Optional. + </para> + + <para> + Any spaces in arguments should be enclosed by quotes. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <note> + <para> + On Windows there are certain limitations for graphical + applications. See <xref linkend="KnownIssues" />. + </para> + </note> + + <para> + Examples of using the <command>guestcontrol run</command> + command are as follows: + </para> + +<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "/bin/ls" + --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen> + +<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "c:\\windows\\system32\\ipconfig.exe" + --username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen> + + <para> + Note that the double backslashes in the second example are + only required on UNIX hosts. + </para> + + <note> + <para> + For certain commands a user name of an existing user account + on the guest must be specified. Anonymous executions are not + supported for security reasons. A user account password, + however, is optional and depends on the guest's OS security + policy or rules. If no password is specified for a given + user name, an empty password will be used. On certain OSes + like Windows the security policy may needs to be adjusted in + order to allow user accounts with an empty password set. + Also, global domain rules might apply and therefore cannot + be changed. + </para> + </note> + + <para> + Starting at &product-name; 4.1.2 guest process execution by + default is limited to serve up to five guest processes at a + time. If a new guest process gets started which would exceed + this limit, the oldest not running guest process will be + discarded in order to be able to run that new process. Also, + retrieving output from this old guest process will not be + possible anymore then. If all five guest processes are still + active and running, starting a new guest process will result + in an appropriate error message. + </para> + + <para> + To raise or lower the guest process execution limit, either + use the guest property + <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput> + or <command>VBoxService</command> command line by specifying + <computeroutput>--control-procs-max-kept</computeroutput> + needs to be modified. A restart of the guest OS is required + afterwards. To serve unlimited guest processes, a value of + <computeroutput>0</computeroutput> needs to be set, but this + is not recommended. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>start</computeroutput>: Executes a guest + program until it completes. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> start [common-options] + [--exe <path to executable>] [--timeout <msec>] + [-E|--putenv <NAME>[=<VALUE>]] [--unquoted-args] + [--ignore-operhaned-processes] [--profile] + -- <program/arg0> [argument1] ... [argumentN]] + </screen> + + <para> + Where the options are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--exe <path to + executable></computeroutput> + </term> + + <listitem> + <para> + Specifies the absolute path of the executable on the + guest OS file system. Mandatory. For example: + <computeroutput>C:\Windows\System32\calc.exe</computeroutput> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--timeout <msec></computeroutput> + </term> + + <listitem> + <para> + Specifies the maximum time, in microseconds, that the + executable can run. Optional. If unspecified, + <command>VBoxManage</command> waits indefinitely for the + process to end, or an error occurs. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>-E|--putenv + <NAME>=<VALUE></computeroutput> + </term> + + <listitem> + <para> + Sets, modifies, and unsets environment variables in the + environment in which the program will run. Optional. + </para> + + <para> + The guest process is created with the standard default + guest OS environment. Use this option to modify that + default environment. To set or modify a variable use: + <computeroutput><NAME>=<VALUE></computeroutput>. + To unset a variable use: + <computeroutput><NAME>=</computeroutput> + </para> + + <para> + Any spaces in names and values should be enclosed by + quotes. + </para> + + <para> + To set, modify, or unset multiple variables, use + multiple instances of the + <computeroutput>--E|--putenv</computeroutput> option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--unquoted-args</computeroutput> + </term> + + <listitem> + <para> + Disables escaped double quoting, such as \"fred\", on + arguments passed to the executed program. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--ignore-operhaned-processes</computeroutput> + </term> + + <listitem> + <para> + Ignores orphaned processes. Not yet implemented. + Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--profile</computeroutput> + </term> + + <listitem> + <para> + Use a profile. Not yet implemented. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>[-- <program/arg0> + [<argument1>] ... + [<argumentN>]]</computeroutput> + </term> + + <listitem> + <para> + Specifies the program name, followed by one or more + arguments to pass to the program. Optional. + </para> + + <para> + Any spaces in arguments should be enclosed by quotes. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <note> + <para> + On Windows there are certain limitations for graphical + applications. See <xref linkend="KnownIssues" />. + </para> + </note> + + <para> + Examples of using the <command>guestcontrol start</command> + command are as follows: + </para> + +<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "/bin/ls" + --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen> + +<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "c:\\windows\\system32\\ipconfig.exe" + --username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen> + + <para> + Note that the double backslashes in the second example are + only required on UNIX hosts. + </para> + + <note> + <para> + For certain commands a user name of an existing user account + on the guest must be specified. Anonymous executions are not + supported for security reasons. A user account password, + however, is optional and depends on the guest's OS security + policy or rules. If no password is specified for a given + user name, an empty password will be used. On certain OSes + like Windows the security policy may needs to be adjusted in + order to allow user accounts with an empty password set. + Also, global domain rules might apply and therefore cannot + be changed. + </para> + </note> + + <para> + Starting at &product-name; 4.1.2 guest process execution by + default is limited to serve up to five guest processes at a + time. If a new guest process gets started which would exceed + this limit, the oldest not running guest process will be + discarded in order to be able to run that new process. Also, + retrieving output from this old guest process will not be + possible anymore then. If all five guest processes are still + active and running, starting a new guest process will result + in an appropriate error message. + </para> + + <para> + To raise or lower the guest process execution limit, either + use the guest property + <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput> + or <command>VBoxService</command> command line by specifying + <computeroutput>--control-procs-max-kept</computeroutput> + needs to be modified. A restart of the guest OS is required + afterwards. To serve unlimited guest processes, a value of + <computeroutput>0</computeroutput> needs to be set, but this + is not recommended. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>copyfrom</computeroutput>: Copies files from + the guest to the host file system. Only available with Guest + Additions 4.0 or later installed. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> copyfrom [common-options] + [--follow] [--R|recursive] + --target-directory <host-dst-dir> + <guest-src0> [<guest-src1> [...]] </screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--follow</computeroutput> + </term> + + <listitem> + <para> + Enables symlink following on the guest file system. + Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>-R|--recursive</computeroutput> + </term> + + <listitem> + <para> + Enables recursive copying of files and directories from + the specified guest file system directory. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--target-directory + <host-dst-dir></computeroutput> + </term> + + <listitem> + <para> + Specifies the absolute path of the host file system + destination directory. Mandatory. For example: + <computeroutput>C:\Temp</computeroutput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><guest-src0> [<guest-src1> + [...]]</computeroutput> + </term> + + <listitem> + <para> + Specifies the absolute paths of guest file system files + to be copied. Mandatory. For example: + <computeroutput>C:\Windows\System32\calc.exe</computeroutput>. + Wildcards can be used in the expressions. For example: + <computeroutput>C:\Windows\System*\*.dll</computeroutput>. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>copyto</computeroutput>: Copies files from the + host to the guest file system. Only available with Guest + Additions 4.0 or later installed. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> copyto [common-options] + [--follow] [--R|recursive] + --target-directory <guest-dst> + <host-src0> [<host-src1> [...]] </screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--follow</computeroutput> + </term> + + <listitem> + <para> + Enables symlink following on the host file system. + Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>-R|--recursive</computeroutput> + </term> + + <listitem> + <para> + Enables recursive copying of files and directories from + the specified host file system directory. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--target-directory + <guest-dst></computeroutput> + </term> + + <listitem> + <para> + Specifies the absolute path of the guest file system + destination directory. Mandatory. For example: + <computeroutput>C:\Temp</computeroutput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><host-src0> [<host-src1> + [...]]</computeroutput> + </term> + + <listitem> + <para> + Specifies the absolute paths of host file system files + to be copied. Mandatory. For example: + <computeroutput>C:\Windows\System32\calc.exe</computeroutput>. + Wildcards can be used in the expressions. For example: + <computeroutput>C:\Windows\System*\*.dll</computeroutput>. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>md|mkdir|createdir|createdirectory</computeroutput>: + Creates one or more directories on the guest file system. Only + available with Guest Additions 4.0 or later installed. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> md|mkdir|createdir|createdirectory [common-options] + [--parents] [--mode <mode>] + <guest-dir0> [<guest-dir1> [...]] </screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--parents</computeroutput> + </term> + + <listitem> + <para> + Creates any absent parent directories of the specified + directory. Optional. + </para> + + <para> + For example: If specified directory is + <computeroutput>D:\Foo\Bar</computeroutput> and + <computeroutput>D:\Foo</computeroutput> is absent, it + will be created. In such a case, had the + <computeroutput>--parents</computeroutput> option not + been used, this command would have failed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--mode <mode></computeroutput> + </term> + + <listitem> + <para> + Specifies the permission mode on the specified + directories, and any parents, if the + <computeroutput>--parents</computeroutput> option is + used. Currently octal modes only, such as. + <computeroutput>0755</computeroutput>, are supported. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><guest-dir0> [<guest-dir1> + [...]]</computeroutput> + </term> + + <listitem> + <para> + Specifies a list of absolute paths of directories to be + created on guest file system. Mandatory. For example: + <computeroutput>D:\Foo\Bar</computeroutput>. + </para> + + <para> + All parent directories must already exist unless the + switch <computeroutput>--parents</computeroutput> is + used. For example, in the above example + <computeroutput>D:\Foo</computeroutput>. The specified + user must have sufficient rights to create the specified + directories, and any parents that need to be created. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>rmdir|removedir|removedirectory</computeroutput>: + Deletes specified guest file system directories. Only + available with installed Guest Additions 4.3.2 and later. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> rmdir|removedir|removedirectory [common-options] + [--recursive|-R] + <guest-dir0> [<guest-dir1> [...]] + </screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--recursive</computeroutput> + </term> + + <listitem> + <para> + Recursively removes directories and contents. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><guest-dir0> [<guest-dir1> + [...]]</computeroutput> + </term> + + <listitem> + <para> + Specifies a list of the absolute paths of directories to + be deleted on guest file system. Mandatory. Wildcards + are allowed. For example: + <computeroutput>D:\Foo\*Bar</computeroutput>. The + specified user must have sufficient rights to delete the + specified directories. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>rm|removefile</computeroutput>: Deletes + specified files on the guest file system. Only available with + installed Guest Additions 4.3.2 and later. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> rm|removefile [common-options] + [-f|--force] + <guest-file0> [<guest-file1> [...]] </screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>-f|--force</computeroutput> + </term> + + <listitem> + <para> + Enforce operation and override any requests for + confirmations. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><guest-file0> [<guest-file1> + [...]]</computeroutput> + </term> + + <listitem> + <para> + Specifies a list of absolute paths of files to be + deleted on guest file system. Mandatory. Wildcards are + allowed. For example: + <computeroutput>D:\Foo\Bar\text*.txt</computeroutput>. + The specified user should have sufficient rights to + delete the specified files. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>mv|move|ren|rename</computeroutput>: Renames + files and/or directories on the guest file system. Only + available with installed Guest Additions 4.3.2 and later. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> mv|move|ren|rename [common-options] + <guest-source0> [<guest-source1> [...]] <guest-dest></screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><guest-source0> + [<guest-source1> [...]]</computeroutput> + </term> + + <listitem> + <para> + Specifies absolute paths of files or a single directory + to be moved and renamed on guest file system. Mandatory. + Wildcards are allowed in file names. The specified user + should have sufficient rights to access the specified + files. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><dest></computeroutput> + </term> + + <listitem> + <para> + Specifies the absolute path of the destination file or + directory to which the files are to be moved. Mandatory. + If only one file to be moved, <dest> can be file + or directory, else it must be a directory. The specified + user must have sufficient rights to access the + destination file or directory. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>mktemp|createtemp|createtemporary</computeroutput>: + Creates a temporary file or directory on the guest file + system, to assist subsequent copying of files from the host to + the guest file systems. By default, the file or directory is + created in the guest's platform specific temp directory. Not + currently supported. Only available with installed Guest + Additions 4.2 and later. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> mktemp|createtemp|createtemporary [common-options] + [--directory] [--secure] [--mode <mode>] [--tmpdir <directory>] + <template> + </screen> + + <para> + The parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--directory</computeroutput> + </term> + + <listitem> + <para> + Creates a temporary directory instead of a file, + specified by the <template> parameter. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--secure</computeroutput> + </term> + + <listitem> + <para> + Enforces secure file and directory creation. Optional. + The permission mode is set to + <computeroutput>0755</computeroutput>. Operation fails + if it cannot be performed securely. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--mode <mode></computeroutput> + </term> + + <listitem> + <para> + Specifies the permission mode of the specified + directory. Optional. Currently only octal modes, such as + <computeroutput>0755</computeroutput>, are supported. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--tmpdir + <directory></computeroutput> + </term> + + <listitem> + <para> + Specifies the absolute path of the directory on the + guest file system where the file or directory specified + will be created. Optional. If unspecified, the + platform-specific temp directory is used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><template></computeroutput> + </term> + + <listitem> + <para> + Specifies a file name without a directory path, + containing at least one sequence of three consecutive X + characters, or ending in X. Mandatory. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>stat</computeroutput>: Displays file or file + system statuses on the guest. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> stat [common-options] + <file0> [<file1> [...]]</screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><file0> [<file1> + [...]]</computeroutput> + </term> + + <listitem> + <para> + Specifies absolute paths of files or file systems on the + guest file system. Mandatory. For example: + <computeroutput>/home/foo/a.out</computeroutput>. The + specified user should have sufficient rights to access + the specified files or file systems. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + </itemizedlist> + + <para> + The second set of subcommands is of the form: + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> <sub-command> + [-v|--verbose] [-q|quiet] ... + </screen> + + <para> + The common options are as follows: + </para> + +<screen> + [-v|--verbose] [-q|--quiet] + </screen> + + <para> + Details of the common options for the second set of subcommands + are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>-v|--verbose</computeroutput> + </term> + + <listitem> + <para> + Makes the subcommand execution more verbose. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>-q|--quiet</computeroutput> + </term> + + <listitem> + <para> + Makes the subcommand execution quieter. Optional. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + The second set of subcommands are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput>list</computeroutput>: Lists guest control + configuration and status data. For example: open guest + sessions, guest processes, and files. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> list [common-opts] + <all|sessions|processes|files> </screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>all|sessions|processes|files</computeroutput> + </term> + + <listitem> + <para> + Indicates whether to list all available data or guest + sessions, processes or files. Mandatory. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>closeprocess</computeroutput>: Terminates + guest processes specified by PIDs running in a guest session, + specified by the session ID or name. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> closeprocess [common-options] + --session-id <ID> | --session-name <name or pattern> + <PID0> [<PID1> [...]] </screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--session-id <ID></computeroutput> + </term> + + <listitem> + <para> + Specifies the guest session by its ID. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--session-name <name or + pattern></computeroutput> + </term> + + <listitem> + <para> + Specifies the guest session by its name, or multiple + sessions using a pattern containing wildcards. Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput><PID0> [<PID1> + [...]]</computeroutput> + </term> + + <listitem> + <para> + Specifies a list of process identifiers (PIDs) of guest + processes to be terminated. Mandatory. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>closesession</computeroutput>: Closes + specified guest sessions, specified either by session ID or + name. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> closesession [common-options] + --session-id <ID> | --session-name <name or pattern> | --all </screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--session-id <ID></computeroutput> + </term> + + <listitem> + <para> + Specifies the guest session to be closed by ID. + Optional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--session-name <name or + pattern></computeroutput> + </term> + + <listitem> + <para> + Specifies the guest session to be closed by name. + Optional. Multiple sessions can be specified by using a + pattern containing wildcards. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--all</computeroutput> + </term> + + <listitem> + <para> + Close all guest sessions. Optional. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>updatega|updateadditions|updateguestadditions</computeroutput>: + Ugrades Guest Additions already installed on the guest. Only + available for already installed Guest Additions 4.0 and later. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> updatega|updateadditions|updateguestadditions + [common-options] + [--source <New .ISO path>] + [--wait-start] + [-- <argument0> [<argument1> [...]]]</screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--source</computeroutput> <New .ISO + path> + </term> + + <listitem> + <para> + Specifies the absolute path on the guest file system of + the .ISO file for the Guest Additions update. Mandatory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--wait-start</computeroutput> + </term> + + <listitem> + <para> + Indicates that <command>VBoxManage</command> starts the + usual updating process on the guest and then waits until + the actual Guest Additions updating begins, at which + point <command>VBoxManage</command> self-terminates. + Optional. + </para> + + <para> + Default behavior is that <command>VBoxManage</command> + waits for completion of the Guest Additions update + before terminating. Use of this option is sometimes + necessary, as a running <command>VBoxManage</command> + can affect the interaction between the installer and the + guest OS. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>[-- <argument0> [<argument1> + [...]]]</computeroutput> + </term> + + <listitem> + <para> + Specifies optional command line arguments to be supplied + to the Guest Additions updater. Useful for retrofitting + features which are not currently installed. + </para> + + <para> + Arguments containing spaces should be enclosed by + quotes. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + <listitem> + <para> + <computeroutput>watch</computeroutput>: Prints current guest + control activity. + </para> + +<screen>VBoxManage guestcontrol <uuid|vmname> watch [common-options] + </screen> + + <para> + Where the parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput><uuid|vmname></computeroutput> + </term> + + <listitem> + <para> + Specifies the VM UUID or VM name. Mandatory. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-metrics"> + + <title>VBoxManage metrics</title> + + <para> + This command supports monitoring the usage of system resources. + Resources are represented by various metrics associated with the + host system or a particular VM. For example, the host system has a + <computeroutput>CPU/Load/User</computeroutput> metric that shows + the percentage of time CPUs spend executing in user mode over a + specific sampling period. + </para> + + <para> + Metric data is collected and retained internally. It may be + retrieved at any time with the <command>VBoxManage metrics + query</command> subcommand. The data is available as long as the + background <computeroutput>VBoxSVC</computeroutput> process is + alive. That process terminates shortly after all VMs and frontends + have been closed. + </para> + + <para> + By default no metrics are collected at all. Metrics collection + does not start until <command>VBoxManage metrics setup</command> + is invoked with a proper sampling interval and the number of + metrics to be retained. The interval is measured in seconds. For + example, to enable collecting the host processor and memory usage + metrics every second and keeping the five most current samples, + the following command can be used: + </para> + +<screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen> + + <para> + Metric collection can only be enabled for started VMs. Collected + data and collection settings for a particular VM will disappear as + soon as it shuts down. Use the <command>VBoxManage metrics + list</command> subcommand to see which metrics are currently + available. You can also use the <option>--list</option> option + with any subcommand that modifies metric settings to find out + which metrics were affected. + </para> + + <para> + Note that the <command>VBoxManage metrics setup</command> + subcommand discards all samples that may have been previously + collected for the specified set of objects and metrics. + </para> + + <para> + To enable or disable metrics collection without discarding the + data, <command>VBoxManage metrics enable</command> and + <command>VBoxManage metrics disable</command> subcommands can be + used. Note that these subcommands expect metrics as parameters, + not submetrics such as <computeroutput>CPU/Load</computeroutput> + or <computeroutput>RAM/Usage</computeroutput>. In other words + enabling <computeroutput>CPU/Load/User</computeroutput> while + disabling <computeroutput>CPU/Load/Kernel</computeroutput> is not + supported. + </para> + + <para> + The host and VMs have different sets of associated metrics. + Available metrics can be listed with <command>VBoxManage metrics + list</command> subcommand. + </para> + + <para> + A complete metric name may include an aggregate function. The name + has the following form: + <computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>. + For example, <computeroutput>RAM/Usage/Free:min</computeroutput> + stands for the minimum amount of available memory over all + retained data if applied to the host object. + </para> + + <para> + Subcommands may apply to all objects and metrics or can be limited + to one object and a list of metrics. If no objects or metrics are + given in the parameters, the subcommands will apply to all + available metrics of all objects. You may use an asterisk + "<computeroutput>*</computeroutput>" to explicitly specify that + the command should be applied to all objects or metrics. Use + <computeroutput>host</computeroutput> as the object name to limit + the scope of the command to host-related metrics. To limit the + scope to a subset of metrics, use a metric list with names + separated by commas. + </para> + + <para> + For example, to query metric data on the CPU time spent in user + and kernel modes by the virtual machine named + <computeroutput>test</computeroutput>, use the following command: + </para> + +<screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen> + + <para> + The following list summarizes the available subcommands: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>list</computeroutput> + </term> + + <listitem> + <para> + Shows the parameters of the currently existing metrics. Note + that VM-specific metrics are only available when a + particular VM is running. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>setup</computeroutput> + </term> + + <listitem> + <para> + Sets the interval between taking two samples of metric data + and the number of samples retained internally. The retained + data is available for displaying with the + <command>query</command> subcommand. The + <computeroutput>--list</computeroutput> option shows which + metrics have been modified as the result of the command + execution. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>enable</computeroutput> + </term> + + <listitem> + <para> + Resumes data collection after it has been stopped with the + <command>disable</command> subcommand. Note that specifying + submetrics as parameters will not enable underlying metrics. + Use <computeroutput>--list</computeroutput> to find out if + the command worked as expected. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>disable</computeroutput> + </term> + + <listitem> + <para> + Suspends data collection without affecting collection + parameters or collected data. Note that specifying + submetrics as parameters will not disable underlying + metrics. Use <computeroutput>--list</computeroutput> to find + out if the command worked as expected. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>query</computeroutput> + </term> + + <listitem> + <para> + Retrieves and displays the currently retained metric data. + </para> + + <note> + <para> + The <command>query</command> subcommand does not remove or + flush retained data. If you query often enough you will + see how old samples are gradually being phased out by new + samples. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>collect</computeroutput> + </term> + + <listitem> + <para> + Sets the interval between taking two samples of metric data + and the number of samples retained internally. The collected + data is displayed periodically until Ctrl+C is pressed, + unless the <computeroutput>--detach</computeroutput> option + is specified. With the + <computeroutput>--detach</computeroutput> option, this + subcommand operates the same way as + <computeroutput>setup</computeroutput> does. The + <computeroutput>--list</computeroutput> option shows which + metrics match the specified filter. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect1> + + <sect1 id="vboxmanage-natnetwork"> + + <title>VBoxManage natnetwork</title> + + <para> + NAT networks use the Network Address Translation (NAT) service, + which works in a similar way to a home router. It groups systems + using it into a network and prevents outside systems from directly + accessing those inside, while letting systems inside communicate + with each other and outside systems using TCP and UDP over IPv4 + and IPv6. + </para> + + <para> + A NAT service is attached to an internal network. Virtual machines + to make use of one should be attached to it. The name of an + internal network is chosen when the NAT service is created, and + the internal network will be created if it does not already exist. + The following is an example command to create a NAT network: + </para> + +<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen> + + <para> + Here, <computeroutput>natnet1</computeroutput> is the name of the + internal network to be used and + <computeroutput>192.168.15.0/24</computeroutput> is the network + address and mask of the NAT service interface. By default, in this + static configuration the gateway will be assigned the address + 192.168.15.1, the address after the interface address, though this + is subject to change. + </para> + + <para> + To add a DHCP server to the NAT network after creation, run the + following command: + </para> + +<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen> + + <para> + The subcommands for <command>VBoxManage natnetwork</command> are + as follows: + </para> + +<screen>VBoxManage natnetwork add --netname <name> + [--network <network>] + [--enable|--disable] + [--dhcp on|off] + [--port-forward-4 <rule>] + [--loopback-4 <rule>] + [--ipv6 on|off] + [--port-forward-6 <rule>] + [--loopback-6 <rule>] + </screen> + + <para> + <command>VBoxManage natnetwork add</command>: Creates a new + internal network interface, and adds a NAT network service. This + command is a prerequisite for enabling attachment of VMs to the + NAT network. Parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>--netname <name></computeroutput> + </term> + + <listitem> + <para> + Where <name> is the name of the new internal network + interface on the host OS. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--network <network></computeroutput> + </term> + + <listitem> + <para> + Where <network> specifies the static or DHCP network + address and mask of the NAT service interface. The default + is a static network address. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--enable|--disable</computeroutput> + </term> + + <listitem> + <para> + Enables and disables the NAT network service. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--dhcp on|off</computeroutput> + </term> + + <listitem> + <para> + Enables and disables a DHCP server specified by + <computeroutput>--netname</computeroutput>. Use of this + option also indicates that it is a DHCP server. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--port-forward-4 <rule></computeroutput> + </term> + + <listitem> + <para> + Enables IPv4 port forwarding, with a rule specified by + <rule>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--loopback-4 <rule></computeroutput> + </term> + + <listitem> + <para> + Enables the IPv4 loopback interface, with a rule specified + by <rule>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--ipv6 on|off</computeroutput> + </term> + + <listitem> + <para> + Enables and disables IPv6. The default setting is IPv4, + disabling IPv6 enables IPv4. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--port-forward-6 <rule></computeroutput> + </term> + + <listitem> + <para> + Enables IPv6 port forwarding, with a rule specified by + <rule>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--loopback-6 <rule></computeroutput> + </term> + + <listitem> + <para> + Enables the IPv6 loopback interface, with a rule specified + by <rule>. + </para> + </listitem> + </varlistentry> + + </variablelist> + +<screen>VBoxManage natnetwork remove --netname <name> </screen> + + <para> + <command>VBoxManage natnetwork remove</command>: Removes a NAT + network service. Parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>--netname <name></computeroutput> + </term> + + <listitem> + <para> + Where <name> specifies an existing NAT network + service. Does not remove any DHCP server enabled on the + network. + </para> + </listitem> + </varlistentry> + + </variablelist> + +<screen>VBoxManage natnetwork modify --netname <name> + [--network <network>] + [--enable|--disable] + [--dhcp on|off] + [--port-forward-4 <rule>] + [--loopback-4 <rule>] + [--ipv6 on|off] + [--port-forward-6 <rule>] + [--loopback-6 <rule>] + </screen> + + <para> + <command>VBoxManage natnetwork modify</command>: Modifies an + existing NAT network service. Parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>--netname <name></computeroutput> + </term> + + <listitem> + <para> + Where <name> specifies an existing NAT network + service. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--network <network></computeroutput> + </term> + + <listitem> + <para> + Where <network> specifies the new static or DHCP + network address and mask of the NAT service interface. The + default is a static network address. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--enable|--disable</computeroutput> + </term> + + <listitem> + <para> + Enables and disables the NAT network service. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--dhcp on|off</computeroutput> + </term> + + <listitem> + <para> + Enables and disables a DHCP server. If a DHCP server is not + present, using enable adds a new DHCP server. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--port-forward-4 <rule></computeroutput> + </term> + + <listitem> + <para> + Enables IPv4 port forwarding, with a rule specified by + <rule>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--loopback-4 <rule></computeroutput> + </term> + + <listitem> + <para> + Enables the IPv4 loopback interface, with a rule specified + by <rule>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--ipv6 on|off</computeroutput> + </term> + + <listitem> + <para> + Enables and disables IPv6. The default setting is IPv4, + disabling IPv6 enables IPv4. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--port-forward-6 <rule></computeroutput> + </term> + + <listitem> + <para> + Enables IPv6 port forwarding, with a rule specified by + <rule>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>--loopback-6 <rule></computeroutput> + </term> + + <listitem> + <para> + Enables IPv6 loopback interface, with a rule specified by + <rule>. + </para> + </listitem> + </varlistentry> + + </variablelist> + +<screen>VBoxManage natnetwork start --netname <name> + </screen> + + <para> + <command>VBoxManage natnetwork start</command>: Starts the + specified NAT network service and any associated DHCP server. + Parameters are as follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>--netname <name></computeroutput> + </term> + + <listitem> + <para> + Where <name> specifies an existing NAT network + service. + </para> + </listitem> + </varlistentry> + + </variablelist> + +<screen>VBoxManage natnetwork stop --netname <name> + </screen> + + <para> + <command>VBoxManage natnetwork stop</command>: Stops the specified + NAT network service and any DHCP server. Parameters are as + follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>--netname <name></computeroutput> + </term> + + <listitem> + <para> + Where <name> specifies an existing NAT network + service. + </para> + </listitem> + </varlistentry> + + </variablelist> + +<screen>VBoxManage natnetwork list [<pattern>] </screen> + + <para> + <command>VBoxManage natnetwork list</command>: Lists all NAT + network services, with optional filtering. Parameters are as + follows: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>[<pattern>]</computeroutput> + </term> + + <listitem> + <para> + Where <pattern> is an optional filtering pattern. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect1> + + <sect1 id="vboxmanage-hostonlyif"> + + <title>VBoxManage hostonlyif</title> + + <para> + The <command>hostonlyif</command> command enables you to change + the IP configuration of a host-only network interface. For a + description of host-only networking, see + <xref linkend="network_hostonly" />. Each host-only interface is + identified by a name and can either use the internal DHCP server + or a manual IP configuration, both IP4 and IP6. + </para> + + <para> + The following list summarizes the available subcommands: + </para> + + <variablelist> + + <varlistentry> + <term> + <computeroutput>ipconfig "<name>"</computeroutput> + </term> + + <listitem> + <para> + Configures a host-only interface. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>create</computeroutput> + </term> + + <listitem> + <para> + Creates a new vboxnet<N> interface on the host OS. + This command is essential before you can attach VMs to a + host-only network. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <computeroutput>remove vboxnet<N></computeroutput> + </term> + + <listitem> + <para> + Removes a vboxnet<N> interface from the host OS. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect1> + + <sect1 id="vboxmanage-dhcpserver"> + + <title>VBoxManage dhcpserver</title> + + <para> + The <command>dhcpserver</command> commands enable you to control + the DHCP server that is built into &product-name;. You may find + this useful when using internal or host-only networking. + Theoretically, you can also enable it for a bridged network, but + that may cause conflicts with other DHCP servers in your physical + network. + </para> + + <para> + Use the following command line options: + </para> + + <itemizedlist> + + <listitem> + <para> + If you use internal networking for a virtual network adapter + of a virtual machine, use <computeroutput>VBoxManage + dhcpserver add --netname + <network_name></computeroutput>, where + <computeroutput><network_name></computeroutput> is the + same network name you used with <computeroutput>VBoxManage + modifyvm <vmname> --intnet<X> + <network_name></computeroutput>. + </para> + </listitem> + + <listitem> + <para> + If you use host-only networking for a virtual network adapter + of a virtual machine, use <computeroutput>VBoxManage + dhcpserver add --ifname + <hostonly_if_name></computeroutput> instead, where + <computeroutput><hostonly_if_name></computeroutput> is + the same host-only interface name you used with + <computeroutput>VBoxManage modifyvm <vmname> + --hostonlyadapter<X> + <hostonly_if_name></computeroutput>. + </para> + + <para> + Alternatively, you can also use the <option>--netname</option> + option as with internal networks if you know the host-only + network's name. You can see the names with <command>VBoxManage + list hostonlyifs</command>. See + <xref linkend="vboxmanage-list" />. + </para> + </listitem> + + </itemizedlist> + + <para> + The following additional parameters are required when first adding + a DHCP server: + </para> + + <itemizedlist> + + <listitem> + <para> + With <computeroutput>--ip</computeroutput>, specify the IP + address of the DHCP server. + </para> + </listitem> + + <listitem> + <para> + With <computeroutput>--netmask</computeroutput>, specify the + netmask of the network. + </para> + </listitem> + + <listitem> + <para> + With <computeroutput>--lowerip</computeroutput> and + <computeroutput>--upperip</computeroutput>, you can specify + the lowest and highest IP address that the DHCP server will + assign to clients. + </para> + </listitem> + + </itemizedlist> + + <para> + You can specify additional DHCP options with the + <computeroutput>--options</computeroutput> command option. Use + <computeroutput>--id</computeroutput> and + <computeroutput>--value</computeroutput> to configure a number and + string pair corresponding to the DHCP option. Use + <computeroutput>--remove</computeroutput> to remove a DHCP option. + </para> + + <para> + The <computeroutput>--vm</computeroutput> and + <computeroutput>--nic</computeroutput> settings enable you to + configure DHCP options for a specific network adapter used by the + named VM. + </para> + + <para> + Finally, you must specify + <computeroutput>--enable</computeroutput> or the DHCP server will + be created in the disabled state and will not be running. + </para> + + <para> + After this, &product-name; will automatically start the DHCP + server for the specified internal network or host-only network as + soon as the first virtual machine which uses that network is + started. + </para> + + <para> + Use <command>VBoxManage dhcpserver remove</command> with the given + <computeroutput>--netname <network_name></computeroutput> or + <computeroutput>--ifname <hostonly_if_name></computeroutput> + to remove the DHCP server for the specified internal network or + host-only network. + </para> + + <para> + To modify the settings of a DHCP server created using + <command>VBoxManage dhcpserver add</command>, you can use + <command>VBoxManage dhcpserver modify</command> for a given + network or host-only interface name. This has the same parameters + as <command>VBoxManage dhcpserver add</command>. + </para> + + </sect1> + + <sect1 id="vboxmanage-usbdevsource"> + + <title>VBoxManage usbdevsource</title> + + <para> + The <command>usbdevsource</command> commands enable you to add and + remove USB devices globally. + </para> + + <para> + The following command adds a USB device. + </para> + +<screen>VBoxManage usbdevsource add <source name> + --backend <backend> + --address <address> + </screen> + + <para> + Where the command line options are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput><source name></computeroutput>: + Specifies the ID of the source USB device to be added. + Mandatory. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>--backend <backend></computeroutput>: + Specifies the USB proxy service backend to use. Mandatory. + </para> + </listitem> + + <listitem> + <para> + <computeroutput> --address <address></computeroutput>: + Specifies the backend specific address. Mandatory. + </para> + </listitem> + + </itemizedlist> + + <para> + The following command removes a USB device. + </para> + +<screen>VBoxManage usbdevsource remove <source name> + </screen> + + <para> + Where the command line options are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <computeroutput><source name></computeroutput>: + Specifies the ID of the source USB device to be removed. + Mandatory. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <xi:include href="user_man_VBoxManage-mediumio.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-unattended.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</chapter> |