VirtualBox

Changeset 91204 in vbox for trunk/doc/manual


Ignore:
Timestamp:
Sep 10, 2021 2:59:21 PM (3 years ago)
Author:
vboxsync
Message:

doc, Frontends/VBoxManage: Integrate several refentry documentation pieces, bringing them up to date (making sure everything documented is actually understood). Remove the corresponding old style documentation and also the manually written help text in VBoxManage. Also fixes the synopsis printing when showing a syntax error message for new style documentation.

Location:
trunk/doc/manual
Files:
7 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/Config.kmk

    r87087 r91204  
    3636## List of refentry files (manpages).
    3737VBOX_MANUAL_XML_REFENTRY_FILES := \
     38        man_VBoxManage.xml \
     39        man_VBoxManage-list.xml \
     40        man_VBoxManage-showvminfo.xml \
     41        man_VBoxManage-registervm.xml \
     42        man_VBoxManage-unregistervm.xml \
     43        man_VBoxManage-createvm.xml \
     44        man_VBoxManage-modifyvm.xml \
     45        man_VBoxManage-clonevm.xml \
     46        man_VBoxManage-movevm.xml \
     47        man_VBoxManage-import.xml \
     48        man_VBoxManage-export.xml \
    3849        man_VBoxManage-snapshot.xml \
    39         man_VBoxManage-clonevm.xml \
    4050        man_VBoxManage-mediumio.xml \
    4151        man_VBoxManage-sharedfolder.xml \

  • trunk/doc/manual/en_US/man_VBoxManage-export.xml

    r87075 r91204  
    2020<refentry id="vboxmanage-export" lang="en">
    2121  <refentryinfo>
    22     <pubdate>November 2019</pubdate>
     22    <pubdate>$Date</pubdate>
    2323    <title>VBoxManage export</title>
    2424  </refentryinfo>
    … …  
    3131  <refnamediv>
    3232    <refname>VBoxManage-export</refname>
    33     <refpurpose>export a virtual machine to a virtual appliance or to a cloud service</refpurpose>
     33    <refpurpose>export one or more virtual machines to a virtual appliance or to a cloud service</refpurpose>
    3434    <refclass>Oracle VM VirtualBox</refclass>
    3535  </refnamediv>
    … …  
    4646        <arg choice="plain">--ovf10</arg>
    4747        <arg choice="plain">--ovf20</arg>
    48         <arg choice="plain">--opc10</arg>
    4948      </group>
    5049      <arg>--manifest</arg>
    … …  
    7271      <arg choice="req"><replaceable>machine</replaceable></arg>
    7372      <arg choice="req">--output=<replaceable>cloud-service-provider</replaceable></arg>
     73      <arg>--opc10</arg>
    7474      <arg>--vmname=<replaceable>vmname</replaceable></arg>
    7575      <arg>--cloud=<replaceable>virtual-system-number</replaceable></arg>
    … …  
    115115      <listitem><para>
    116116          <emphasis role="bold">Cloud service such as &oci;.</emphasis>
    117           Exports a single VM in VMDK format.
     117          Exports a single VM.
    118118        </para></listitem>
    119119    </itemizedlist>
    … …  
    173173          <listitem><para>
    174174              Exports in OVF 2.0 format.
    175             </para></listitem>
    176         </varlistentry>
    177         <varlistentry>
    178           <term><option>--opc10</option></term>
    179           <listitem><para>
    180               Exports in &oci; format.
    181175            </para></listitem>
    182176        </varlistentry>
    … …  
    296290        The <command>VBoxManage export</command> command enables you to
    297291        export a VM to a cloud service provider such as &oci;. By
    298         default, the exported disk image is converted into stream VMDK
    299         format. This ensures compatibility with &oci;.
     292        default, the exported disk image is converted into compressed VMDK
     293        format. This minimizes the amount of data to transfer to the cloud
     294        service.
    300295      </para>
    301296      <para>
    … …  
    313308            </para><para>
    314309              The short form of this option is <option>-o</option>.
     310            </para></listitem>
     311        </varlistentry>
     312        <varlistentry>
     313          <term><option>--opc10</option></term>
     314          <listitem><para>
     315              Exports in &oci; format.
    315316            </para></listitem>
    316317        </varlistentry>

  • trunk/doc/manual/en_US/man_VBoxManage-import.xml

    r87075 r91204  
    2020<refentry id="vboxmanage-import" lang="en">
    2121  <refentryinfo>
    22     <pubdate>August 2019</pubdate>
     22    <pubdate>$Date$</pubdate>
    2323    <title>VBoxManage import</title>
    2424  </refentryinfo>
    … …  
    3131  <refnamediv>
    3232    <refname>VBoxManage-import</refname>
    33     <refpurpose>import a virtual appliance in OVF format and create virtual machines</refpurpose>
     33    <refpurpose>import a virtual appliance in OVF format or from a cloud service and create virtual machines</refpurpose>
    3434    <refclass>Oracle VM VirtualBox</refclass>
    3535  </refnamediv>
    3636
    3737  <refsynopsisdiv>
    38     <cmdsynopsis id="synopsis-vboxmanage-import">
     38    <cmdsynopsis id="synopsis-vboxmanage-import-ovf">
    3939<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
    4040      <command>VBoxManage import</command>
    … …  
    4747          <arg choice="plain">keepallmacs</arg>
    4848          <arg choice="plain">keepnatmacs</arg>
    49           <arg choice="plain">keepdisknames</arg>
    5049          <arg choice="plain">importtovdi</arg>
    5150        </group></arg>
     51      <arg>--vsys=<replaceable>n</replaceable></arg>
     52      <arg>--ostype=<replaceable>ostype</replaceable></arg>
     53      <arg>--vmname=<replaceable>name</replaceable></arg>
     54      <arg>--settingsfile=<replaceable>file</replaceable></arg>
     55      <arg>--basefolder=<replaceable>folder</replaceable></arg>
     56      <arg>--group=<replaceable>group</replaceable></arg>
     57      <arg>--memory=<replaceable>MB</replaceable></arg>
     58      <arg>--cpus=<replaceable>n</replaceable></arg>
     59      <arg>--description=<replaceable>text</replaceable></arg>
     60      <arg>--eula=<group choice="plain">
     61          <arg choice="plain">show</arg>
     62          <arg choice="plain">accept</arg>
     63        </group></arg>
     64      <arg>--unit=<replaceable>n</replaceable></arg>
     65      <arg>--ignore</arg>
     66      <arg>--scsitype=<group choice="plain">
     67          <arg choice="plain">BusLogic</arg>
     68          <arg choice="plain">LsiLogic</arg>
     69        </group></arg>
     70      <!-- <arg>&#45;&#45;controller=<replaceable>n</replaceable></arg> -->
     71      <arg>--disk=<replaceable>path</replaceable></arg>
     72    </cmdsynopsis>
     73
     74    <cmdsynopsis id="synopsis-vboxmanage-import-cloud">
     75<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
     76      <command>VBoxManage import</command>
     77      <arg choice="plain">OCI://</arg>
     78      <arg choice="plain">--cloud</arg>
     79      <arg>--ostype=<replaceable>ostype</replaceable></arg>
     80      <arg>--vmname=<replaceable>name</replaceable></arg>
     81      <arg>--basefolder=<replaceable>folder</replaceable></arg>
     82      <arg>--memory=<replaceable>MB</replaceable></arg>
     83      <arg>--cpus=<replaceable>n</replaceable></arg>
     84      <arg>--description=<replaceable>text</replaceable></arg>
     85      <arg choice="req">--cloudprofile=<replaceable>profile</replaceable></arg>
     86      <arg choice="req">--cloudinstanceid=<replaceable>id</replaceable></arg>
     87      <arg>--cloudbucket=<replaceable>bucket</replaceable></arg>
    5288    </cmdsynopsis>
    5389  </refsynopsisdiv>
    … …  
    5793    <para>
    5894      The <command>VBoxManage import</command> command imports a virtual
    59       appliance in OVF or OVA format by copying virtual disk images and
    60       by creating virtual machines (VMs) in &product-name;. See
    61       <xref linkend="ovf" />.
     95      appliance either in OVF format or from a cloud service such as &oci;.
     96      The import is performed by copying virtual disk images (by default using
     97      the VMDK image format) and by creating virtual machines (VMs) in
     98      &product-name;. See <xref linkend="ovf" />.
    6299    </para>
    63100    <para>
    64101      You must specify the path name of an OVF file or OVA archive to
    65       use as input. Also, ensure that any disk images are in the same
    66       directory as the OVF file or OVA archive.
     102      use as input, or a placeholder for the cloud case. For OVF appliances
     103      ensure that any disk images are in the same directory as the OVF file.
    67104    </para>
    68105    <para>
    69106      Note that any options you specify to control the imported virtual
    70107      appliance or to modify the import parameters rely on the contents
    71       of the OVF file.
     108      of the OVF file or the information from the cloud service.
    72109    </para>
    73110    <para>
    74111      Before you use the import operation to create the VM, perform a
    75       dry run to verify the correctness of your configuration.
     112      dry run to verify the correctness of your configuration. This is more
     113      useful with an OVF or OVA appliance, because with a cloud service even
     114      a dry run needs to perform most of the time consuming steps.
     115    </para>
     116    <para>
     117      The import from a cloud service downloads a temporary file containing
     118      both the boot image and some metadata describing the details of the
     119      VM instance. The temporary file is deleted after successful import.
    76120    </para>
    77121    <refsect2>
    … …  
    82126          <listitem><para>
    83127              Specifies the name of the OVF file or OVA archive that
    84               describes the appliance.
     128              describes the appliance. In the cloud case this is usually
     129              a fixed string such as <literal>OCI://</literal>.
    85130            </para></listitem>
    86131        </varlistentry>
    87132        <varlistentry>
    88133          <term><option>--dry-run</option></term>
     134          <!-- Does this option really work for cloud import? -->
    89135          <listitem><para>
    90136              Performs a dry run of the <command>VBoxManage
    … …  
    107153        </varlistentry>
    108154        <varlistentry>
    109           <term><option>--options keepallmacs | keepnatmacs | keepdisknames | importtovdi</option></term>
     155          <term><option>--options=keepallmacs | keepnatmacs | importtovdi</option></term>
     156          <!-- Does this option really work for cloud import? -->
    110157          <listitem><para>
    111158              Enables you to fine tune the import operation.
    … …  
    124171                </para></listitem>
    125172              <listitem><para>
    126                   <literal>keepdisknames</literal>: Specifies that all
    127                   new disk images are assigned the same names as the
    128                   originals.
    129                 </para></listitem>
    130               <listitem><para>
    131173                  <literal>importtovdi</literal>: Specifies that all new
    132174                  disk images are in VDI file format.
    133175                </para></listitem>
    134176            </itemizedlist></listitem>
     177        </varlistentry>
     178        <varlistentry>
     179          <term><option>--ostype=<replaceable>ostype</replaceable></option></term>
     180          <listitem><para>
     181              Specifies the guest operating system (OS) information for
     182              the VM. Use the <command>VBoxManage list ostypes</command>
     183              command to view the OS type identifiers.
     184            </para></listitem>
     185        </varlistentry>
     186        <varlistentry>
     187          <term><option>--vmname=<replaceable>name</replaceable></option></term>
     188          <listitem><para>
     189              Specifies the name of the VM to be used by &product-name;.
     190            </para></listitem>
     191        </varlistentry>
     192        <varlistentry>
     193          <term><option>--basefolder=<replaceable>folder</replaceable></option></term>
     194          <!-- Does this option really work for cloud import? -->
     195          <listitem><para>
     196              Specifies the folder where the files of the imported VM
     197              are stored.
     198            </para></listitem>
     199        </varlistentry>
     200        <varlistentry>
     201          <term><option>--memory=<replaceable>MB</replaceable></option></term>
     202          <listitem><para>
     203              Specifies the memory size in Megabytes for the imported VM.
     204            </para></listitem>
     205        </varlistentry>
     206        <varlistentry>
     207          <term><option>--cpus=<replaceable>n</replaceable></option></term>
     208          <listitem><para>
     209              Specifies the number of CPUs for the imported VM.
     210            </para></listitem>
     211        </varlistentry>
     212        <varlistentry>
     213          <term><option>--description=<replaceable>text</replaceable></option></term>
     214          <listitem><para>
     215              Specifies the description text visible in the GUI and
     216              CLI when checking the VM details.
     217            </para></listitem>
     218        </varlistentry>
     219      </variablelist>
     220    </refsect2>
     221
     222    <refsect2 id="vboxmanage-import-ovf">
     223      <title>OVF / OVA Import Options</title>
     224      <para>
     225        The following options are specific for importing a virtual appliance
     226        in OVF or OVA format. Such an appliance can contain one or more VMs,
     227        which requires specifying which VM configuration should be adjusted
     228        in case you want to change it. See <xref linkend="ovf-import-appliance" />.
     229      </para>
     230      <remark role="help-copy-synopsis"/>
     231      <variablelist>
     232        <varlistentry>
     233          <term><option>--vsys=<replaceable>n</replaceable></option></term>
     234          <listitem><para>
     235              Specifies the index selecting a specific VM within the
     236              appliance. Affects the following options.
     237            </para></listitem>
     238        </varlistentry>
     239        <varlistentry>
     240          <term><option>--unit=<replaceable>n</replaceable></option></term>
     241          <listitem><para>
     242              Specifies the index selecting a specific unit of a VM
     243              within the appliance. Affects the following options.
     244            </para></listitem>
     245        </varlistentry>
     246        <varlistentry>
     247          <term><option>--settingsfile=<replaceable>file</replaceable></option></term>
     248          <listitem><para>
     249              Specifies the name (with or without path) of the VM config
     250              file which will be created as part of the import. Usually
     251              the preferred way is overriding the VM name with
     252              <option>--vmname</option> and if necessary specify the
     253              folder in which to create the VM with
     254              <option>--basefolder</option>.
     255            </para></listitem>
     256        </varlistentry>
     257        <varlistentry>
     258          <term><option>--group=<replaceable>group</replaceable></option></term>
     259          <listitem><para>
     260              Specifies the primary group of the imported VM.
     261            </para></listitem>
     262        </varlistentry>
     263        <varlistentry>
     264          <term><option>--eula=show | accept</option></term>
     265          <listitem><para>
     266              Enables you to show or accept the license conditions of a
     267              VM within the appliance,
     268            </para><para>
     269              Valid arguments are as follows:
     270            </para><itemizedlist>
     271              <listitem><para>
     272                  <literal>show</literal>: Shows the EULA of a VM.
     273                </para></listitem>
     274              <listitem><para>
     275                  <literal>accepts</literal>: Accepts the EULA of a VM.
     276                  Any VMs in an appliance which have an EULA require
     277                  accepting it, otherwise the import will fail.
     278                </para></listitem>
     279            </itemizedlist></listitem>
     280        </varlistentry>
     281        <varlistentry>
     282          <term><option>--ignore</option></term>
     283          <listitem><para>
     284              Ignores the current unit of an imported VM, effectively
     285              removing the associated hardware.
     286            </para></listitem>
     287        </varlistentry>
     288        <varlistentry>
     289          <term><option>--scsitype=BusLogic | LsiLogic</option></term>
     290          <listitem><para>
     291              Enables you to select the type of the SCSI controller for
     292              the current unit of an imported VM.
     293            </para><para>
     294              Valid arguments are as follows:
     295            </para><itemizedlist>
     296              <listitem><para>
     297                  <literal>BusLogic</literal>: Uses the (very old) BusLogic
     298                  SCSI controller type.
     299                </para></listitem>
     300              <listitem><para>
     301                  <literal>LsiLogic</literal>: Uses the (more modern)
     302                  LsiLogic SCSI controller type.
     303                </para></listitem>
     304            </itemizedlist></listitem>
     305        </varlistentry>
     306      </variablelist>
     307    </refsect2>
     308
     309    <refsect2 id="vboxmanage-import-cloud">
     310      <title>Cloud Import Options</title>
     311      <para>
     312        The following options are specific for importing a VM instance
     313        from a cloud service provider. It always deals with a single VM.
     314        See <xref linkend="cloud-import-oci" />.
     315      </para>
     316      <remark role="help-copy-synopsis"/>
     317      <variablelist>
     318        <varlistentry>
     319          <term><option>--cloud</option></term>
     320          <listitem><para>
     321              Specifies that the import should be from the cloud.
     322            </para></listitem>
     323        </varlistentry>
     324        <varlistentry>
     325          <term><option>--cloudprofile=<replaceable>profile</replaceable></option></term>
     326          <listitem><para>
     327              Specifies the cloud profile which is used to connect to the
     328              cloud service provider. The cloud profile contains your &oci;
     329              account details, such as your user OCID and the fingerprint
     330              for your public key. To use a cloud profile, you must have
     331              the required permissions on &oci;.
     332            </para></listitem>
     333        </varlistentry>
     334        <varlistentry>
     335          <term><option>--cloudinstanceid=<replaceable>id</replaceable></option></term>
     336          <listitem><para>
     337              Specifies the ID of an existing instance in the cloud.
     338            </para></listitem>
     339        </varlistentry>
     340        <varlistentry>
     341          <term><option>--cloudbucket=<replaceable>bucket</replaceable></option></term>
     342          <listitem><para>
     343              Specifies the bucket name in which to store the object created
     344              from the instance. In &oci;, a bucket is a logical container
     345              for storing objects. By default the first bucket available with
     346              the cloud profile is used.
     347            </para></listitem>
    135348        </varlistentry>
    136349      </variablelist>
    … …  
    142355    <remark role="help-scope" condition="GLOBAL"/>
    143356    <para>
    144       The following example performs the dry run of an import operation
     357      The following example performs the dry run of an OVF import operation
    145358      for a sample appliance that contains a Windows 10 guest:
    146359    </para>
    … …  
    164377 6: Number of CPUs: 1
    165378    (change with "--vsys 0 --cpus &lt;n&gt;")
    166  7: Guest memory: 1024 MB (change with "--vsys 0 --memory &lt;MB&gt;")
     379 7: Guest memory: 2048 MB (change with "--vsys 0 --memory &lt;MB&gt;")
    167380 8: Sound card (appliance expects "ensoniq1371", can change on import)
    168381    (disable with "--vsys 0 --unit 5 --ignore")
    … …  
    17939214: Hard disk image: source image=Windows10.vmdk,
    180393      target path=/home/user1/disks/Windows10.vmdk, controller=9;channel=0
    181     (change controller with "--vsys 0 --unit 11 --controller &lt;id&gt;";
     394    (change target path with "--vsys 0 --unit 11 --disk &lt;path&gt;";
    182395    disable with "--vsys 0 --unit 11 --ignore")</screen>
    183396    <para>
    … …  
    202415    <para>
    203416      Item 14 indicates the hard disk image and the
    204       <option>--controller</option> option specifies the device on which
    205       the image resides. The default value is specified in the OVF file.
     417      <option>--disk</option> option specifies the target path where the
     418      image will be stored. The default value is specified in the OVF file.
    206419    </para>
    207420    <para>
    … …  
    210423      For example use the following command to import a machine as
    211424      described in the OVF, exclude the sound card and USB controller
    212       and specify that the disk image is connected to the IDE controller
    213       instead of the SCSI controller.
     425      and specify that the disk image is stored with a different name.
    214426    </para>
    215427<screen>$ VBoxManage import Windows10.ovf --vsys 0 --unit 8 --ignore \
    216   --unit 9 --ignore --unit 14 --controller 13</screen>
     428  --unit 9 --ignore --unit 14 --disk Windows10_disk0.vmdk</screen>
     429    <para>
     430      The following example illustrates how to import a VM from &oci;. To find
     431      the &oci; VM instances and its ID you can list all available instances
     432      with:
     433    </para>
     434<screen>$ VBoxManage cloud --provider=OCI --profile=<replaceable>cloud-profile-name</replaceable> list instances</screen>
     435    <para>
     436      Once you know the ID the following command imports the instance from
     437      &oci;:
     438    </para>
     439<screen>$ VBoxManage import OCI:// --cloud --vmname OCI_FreeBSD_VM --memory 4000 \
     440  --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" \
     441  --cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket</screen>
    217442  </refsect1>
    218443</refentry>

  • trunk/doc/manual/en_US/man_VBoxManage-modifyvm.xml

    r90279 r91204  
    2020<refentry id="vboxmanage-modifyvm" lang="en">
    2121  <refentryinfo>
    22     <pubdate>September 2019</pubdate>
     22    <pubdate>$Date$</pubdate>
    2323    <title>VBoxManage modifyvm</title>
    2424  </refentryinfo>
    … …  
    5858          <arg choice="plain">off</arg>
    5959        </group></arg>
    60       <arg>--pciattach=<replaceable>host-PCI-address</replaceable></arg>
    61       <arg>--pcidetach=<replaceable>host-PCI-address</replaceable></arg>
    6260      <arg>--ioapic=<group choice="plain">
    6361          <arg choice="plain">on</arg>
    … …  
    160158          <arg choice="plain">off</arg>
    161159        </group></arg>
     160      <arg>--nested-hw-virt=<group choice="plain">
     161          <arg choice="plain">on</arg>
     162          <arg choice="plain">off</arg>
     163        </group></arg>
     164      <arg>--virt-vmsave-vmload=<group choice="plain">
     165          <arg choice="plain">on</arg>
     166          <arg choice="plain">off</arg>
     167        </group></arg>
    162168      <arg>--accelerate3d=<group choice="plain">
    163169          <arg choice="plain">on</arg>
    … …  
    239245          <arg choice="plain"><replaceable>name</replaceable></arg>
    240246        </group></arg>
    241       <arg>--nested-hw-virt=<group choice="plain">
    242           <arg choice="plain">on</arg>
    243           <arg choice="plain">off</arg>
    244         </group></arg>
     247<!-- There are currently undocumented options &#45;&#45;iocache and
     248&#45;&#45;iocachesize which are scheduled for removal. Not worth spending
     249time on documenting it. -->
    245250      <arg>--vm-process-priority=<group choice="plain">
    246251          <arg choice="plain">default</arg>
    … …  
    419424          <arg choice="plain">off</arg>
    420425        </group></arg>
    421       <arg>--clipboard=<group choice="plain">
     426      <arg>--clipboard-mode=<group choice="plain">
    422427          <arg choice="plain">disabled</arg>
    423428          <arg choice="plain">hosttoguest</arg>
    … …  
    425430          <arg choice="plain">bidirectional</arg>
    426431        </group></arg>
     432<!-- There is a currently undocumented option &#45;&#45;clipboard-file-transfers.
     433The implementation is not finished, so postpone documenting until it
     434actually is ready for users. -->
    427435      <arg>--draganddrop=<group choice="plain">
    428436          <arg choice="plain">disabled</arg>
    … …  
    532540        </group></arg>
    533541      <arg>--cpuid-portability-level=<replaceable>level</replaceable></arg>
    534       <arg>--cpuid-set=<replaceable>leaf</replaceable> <arg>:<replaceable>subleaf</replaceable></arg> <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></arg>
    535       <arg>--cpuid-remove=<replaceable>leaf</replaceable> <arg>:<replaceable>subleaf</replaceable></arg></arg>
     542      <arg>--cpuid-set=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg> <replaceable>eax</replaceable>&nbsp;<replaceable>ebx</replaceable>&nbsp;<replaceable>ecx</replaceable>&nbsp;<replaceable>edx</replaceable></arg>
     543      <arg>--cpuid-remove=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg></arg>
    536544      <arg>--cpuidremoveall</arg>
    537545    </cmdsynopsis>
    … …  
    577585        </group></arg>
    578586      <arg>--autostart-delay=<replaceable>seconds</replaceable></arg>
     587<!-- There is a currently undocumented option &#45;&#45;autostop-type.
     588Most autostart service implementations either ignore it or rely it is
     589left unchanged due to otherwise running into timeouts established by the
     590host OS, defeating the purpose. Not worth spending time on documenting
     591it unless this changes. -->
     592    </cmdsynopsis>
     593
     594    <cmdsynopsis id="synopsis-vboxmanage-modifyvm-pcipassthrough">
     595      <command>VBoxManage modifyvm</command>
     596      <group choice="req">
     597        <arg choice="plain"><replaceable>uuid</replaceable></arg>
     598        <arg choice="plain"><replaceable>vmname</replaceable></arg>
     599      </group>
     600      <arg>--pciattach=<replaceable>host-PCI-address</replaceable><arg>@<replaceable>guest-PCI-bus-address</replaceable></arg></arg>
     601      <arg>--pcidetach=<replaceable>host-PCI-address</replaceable></arg>
    579602    </cmdsynopsis>
    580603  </refsynopsisdiv>
    … …  
    630653              begin with a slash character (<literal>/</literal>) and
    631654              can be nested. By default, VMs are members of the
    632               <literal>/</literal> group.
     655              <literal>/</literal> group. A VM can be member of multiple
     656              groups, but its primary group determines the directory
     657              structure where the internal VM files are placed by default.
    633658            </para></listitem>
    634659        </varlistentry>
    … …  
    646671          <term><option>--ostype=<replaceable>OS-type</replaceable></option></term>
    647672          <listitem><para>
    648               Specifies the guest operating system (OS) to run in the
    649               VM. Use the <command>VBoxManage list ostypes</command>
     673              Specifies the guest operating system (OS) information for
     674              the VM. Use the <command>VBoxManage list ostypes</command>
    650675              command to view the OS type identifiers.
    651676            </para></listitem>
    … …  
    654679          <term><option>--iconfile=<replaceable>filename</replaceable></option></term>
    655680          <listitem><para>
    656               Specifies the absolute path to the &product-name; icon on
    657               the host system. The icon is shown on the VM.
     681              Specifies the path to the VM icon file in PNG format
     682              on the host system. The icon is shown in the VM manager
     683              UI and when running the VM with UI.
    658684            </para></listitem>
    659685        </varlistentry>
    … …  
    698724        </varlistentry>
    699725        <varlistentry>
    700           <term><option>--pciattach=<replaceable>host-PCI-address</replaceable>[@<replaceable>guest-PCI-host-bus-address</replaceable>]</option></term>
    701           <listitem><para>
    702               Attaches the specified PCI network controller on the host
    703               to the guest VM. You can optionally specify the PCI bus on
    704               the guest VM on which to attach the controller. See
    705               <xref linkend="pcipassthrough" />.
    706             </para></listitem>
    707         </varlistentry>
    708         <varlistentry>
    709           <term><option>--pcidetach=<replaceable>host-PCI-address</replaceable></option></term>
    710           <listitem><para>
    711               Detaches the specified PCI network controller from the
    712               attached PCI bus on the guest VM. See
    713               <xref linkend="pcipassthrough" />.
    714             </para></listitem>
    715         </varlistentry>
    716         <varlistentry>
    717726          <term><option>--hardwareuuid=<replaceable>uuid</replaceable></option></term>
    718727          <listitem><para>
    … …  
    720729              present to the guest VM in memory tables (DMI/SMBIOS),
    721730              hardware, and VM properties. By default this hardware UUID
    722               is the same as the VM UUID. Use this option when cloning a
    723               VM. Note that the teleporting feature automatically
    724               handles the UUID value.
     731              is the same as the VM UUID. Cloning a VM and the teleporting
     732              feature automatically preserve the hardware UUID value.
     733              Likewise for Virtual Appliance export and import, but only
     734              if both operations are done by &product-name;.
    725735            </para></listitem>
    726736        </varlistentry>
    … …  
    892902          <term><option>--apic=on | off</option></term>
    893903          <listitem><para>
    894               Enables or disables I/O APIC. With I/O APIC, OSes can use
     904              Enables or disables APIC. With APIC, OSes can use
    895905              more than 16 interrupt requests (IRQs) to avoid IRQ
    896               sharing and to improve reliability. I/O APIC is enabled by
     906              sharing and to improve reliability. APIC is enabled by
    897907              default. See <xref linkend="settings-motherboard" />.
    898908            </para></listitem>
    … …  
    9921002        </varlistentry>
    9931003        <varlistentry>
     1004          <term><option>--nested-hw-virt=on | off</option></term>
     1005          <listitem><para>
     1006              Enables or disables nested virtualization. Enabling makes
     1007              hardware virtualization features available to the VM. See
     1008              <xref linkend="nested-virt" />.
     1009            </para></listitem>
     1010        </varlistentry>
     1011        <varlistentry>
     1012          <term><option>--virt-vmsave-vmload=on | off</option></term>
     1013          <listitem><para>
     1014              If hardware virtualization is enabled and the host has an
     1015              AMD CPU, this setting enables or disables the use of the
     1016              virtualized vmsave/vmload host feature while executing the
     1017              VM. It is enabled by default. It is recommended to leave it
     1018              enabled as it has a drastic impact on performance while
     1019              executing nested VMs when using the nested hardware
     1020              virtualization feature.
     1021              <xref linkend="nested-virt" />.
     1022            </para></listitem>
     1023        </varlistentry>
     1024        <varlistentry>
    9941025          <term><option>--accelerated3d=on | off</option></term>
    9951026          <listitem><para>
    996               Enables or disables hardware 3D acceleration. This option
    997               is available only when the Guest Additions are installed.
     1027              Enables or disables hardware 3D acceleration for the
     1028              graphics adapter variants which support it. This option
     1029              has an effect only when the Guest Additions are installed.
    9981030              See <xref linkend="guestadd-3d" />.
    9991031            </para></listitem>
    … …  
    10021034          <term><option>--accelerated2dvideo=on | off</option></term>
    10031035          <listitem><para>
    1004               Enables or disables 2D video acceleration. This option is
    1005               available only when the Guest Additions are installed. See
     1036              Enables or disables 2D video acceleration for the graphics
     1037              adapter variants which support it. This option has an effect
     1038              only when the Guest Additions are installed. See
    10061039              <xref linkend="guestadd-2d" />.
    10071040            </para></listitem>
    … …  
    10491082        </varlistentry>
    10501083        <varlistentry>
    1051           <term><option>--bioslogofacein=on | off</option></term>
     1084          <term><option>--bioslogofadein=on | off</option></term>
    10521085          <listitem><para>
    10531086              Specifies whether the BIOS logo fades in on VM startup. By
    … …  
    10561089        </varlistentry>
    10571090        <varlistentry>
    1058           <term><option>--bioslogofacein=on | off</option></term>
     1091          <term><option>--bioslogofadeout=on | off</option></term>
    10591092          <listitem><para>
    10601093              Specifies whether the BIOS logo fades out on VM startup.
    … …  
    10721105          <listitem><para>
    10731106              Replaces the existing BIOS logo with a different image.
    1074               The replacement image must be an uncompressed 256-color
    1075               bitmap file (BMP) that does not contain color space
     1107              The replacement image must be an uncompressed 16, 256 or 16M
     1108              color bitmap file (BMP) that does not contain color space
    10761109              information (Windows 3.0 format). Also ensure that the
    10771110              image is no larger than 640 X 480 pixels.
    … …  
    12211254              the VM is shown in a window on the user's desktop. See
    12221255              <xref linkend="vboxmanage-startvm" />.
    1223             </para></listitem>
    1224         </varlistentry>
    1225         <varlistentry>
    1226           <term><option>--nested-hw-virt=on | off</option></term>
    1227           <listitem><para>
    1228               Enables or disables nested virtualization. See
    1229               <xref linkend="nested-virt" />.
    12301256            </para></listitem>
    12311257        </varlistentry>
    … …  
    13001326              <listitem><para>
    13011327                  <literal>natnetwork</literal> &ndash; Use a NAT
    1302                   metwork
     1328                  network
    13031329                </para></listitem>
    13041330              <listitem><para>
    … …  
    17451771                  serial port output to the specified raw file. Ensure
    17461772                  that <replaceable>filename</replaceable> is the
    1747                   absolute path of the on the host system.
     1773                  absolute path of the file on the host system.
    17481774                </para></listitem>
    17491775              <listitem><para>
    … …  
    17771803          <listitem><para>
    17781804              Specifies the device name of the parallel port to use.
    1779               Ensure that you use this option before using the
    1780               <option>--lpt</option> option.
    17811805            </para><para>
    17821806              For a Windows host system, use a device name such as
    … …  
    17891813          <listitem><para>
    17901814              Specifies the I/O base address and IRQ of the parallel
    1791               port. Ensure that you use this option after using the
    1792               <option>--lptmode</option> option.
     1815              port.
    17931816            </para><para>
    17941817              You can view the I/O base address and IRQ that the VM uses
    … …  
    18451868        </varlistentry>
    18461869        <varlistentry>
    1847           <term><option>--clipboard=<replaceable>value</replaceable></option></term>
     1870          <term><option>--clipboard-mode=<replaceable>value</replaceable></option></term>
    18481871          <listitem><para>
    18491872              Specifies how to share the guest VM or host system OS's
    … …  
    18821905        </varlistentry>
    18831906        <varlistentry>
    1884           <term><option>--usb=on | off</option></term>
    1885           <listitem><para>
    1886               Enables or disables the VM's virtual USB controller. See
    1887               <xref linkend="settings-usb" />.
    1888             </para></listitem>
    1889         </varlistentry>
    1890         <varlistentry>
    18911907          <term><option>--usbohci=on | off</option></term>
    18921908          <listitem><para>
    … …  
    19061922          <listitem><para>
    19071923              Enables or disables the VM's virtual USB 3.0 controller.
     1924              This is the most efficient option if the VM supports it.
    19081925              See <xref linkend="settings-usb" />.
    19091926            </para></listitem>
    … …  
    22442261        </varlistentry>
    22452262        <varlistentry>
    2246           <term><option>--vrdereport=default | <replaceable>port</replaceable></option></term>
     2263          <term><option>--vrdeport=default | <replaceable>port</replaceable></option></term>
    22472264          <listitem><para>
    22482265              <replaceable>port</replaceable> is the port or port range
    … …  
    24222439        </varlistentry>
    24232440        <varlistentry>
    2424           <term><option>--cpuid=<replaceable>leaf</replaceable> <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></option></term>
    2425           <listitem><para>
    2426               For advanced users only.
    2427             </para><para>
     2441          <term><option>--cpuid-portability-level=<replaceable>level</replaceable></option></term>
     2442          <listitem>
     2443            <para>
    24282444              Restricts the virtual CPU capabilities that &product-name;
    2429               presents to the guest VM OS. This option affects what the
    2430               guest VM sees when it executes the
    2431               <literal>CPUID</literal> machine instruction.
    2432             </para><para>
    2433               Run the <command>VBoxManage modifyvm</command> command
    2434               with this option prior to a teleporting operation on both
    2435               the source and the target machines.
    2436             </para><para>
    2437               Use this option if a misbehaving application assumes that
    2438               certain CPU capabilities are present when they are not.
    2439               The meaning of the values is hardware dependent. See the
    2440               AMD or Intel processor documentation.
     2445              presents to the guest OS by using portability rules. Higher
     2446              integer values designate more restrictive behavior. The
     2447              default level of <literal>0</literal> indicates that all
     2448              virtualized features supported by the host are made available
     2449              to the guest. The value <literal>3</literal> supresses most
     2450              features. Values of <literal>1</literal> and <literal>2</literal>
     2451              represent restrictions in between. The behavior may change
     2452              depending on the product version.
     2453            </para></listitem>
     2454        </varlistentry>
     2455        <varlistentry>
     2456          <term><option>--cpuid-set=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>]
     2457              <replaceable>eax</replaceable>&nbsp;<replaceable>ebx</replaceable>&nbsp;<replaceable>ecx</replaceable>&nbsp;<replaceable>edx</replaceable></option></term>
     2458          <listitem>
     2459            <para>
     2460              Advanced users can use this setting before a teleporting
     2461              operation (in fact before starting the VM) to restrict the
     2462              virtual CPU capabilities that &product-name; presents to
     2463              the guest operating system. This must be run on both the
     2464              source and the target machines involved in teleporting and
     2465              will then modify what the guest sees when it executes the
     2466              CPUID machine instruction. This might help with misbehaving
     2467              applications that wrongly assume that certain CPU
     2468              capabilities are present. The meaning of the parameters
     2469              is hardware dependent. Refer to the AMD or Intel processor
     2470              documentation.
     2471            </para><para>
     2472              The values of <replaceable>leaf</replaceable>,
     2473              <replaceable>subleaf</replaceable> (optional),
     2474              <replaceable>eax</replaceable>, <replaceable>ebx</replaceable>,
     2475              <replaceable>ecx</replaceable> and <replaceable>edx</replaceable>
     2476              are integers given in hexadecimal format, i.e. using a radix
     2477              (base) of 16 without requiring any prefix.
     2478            </para></listitem>
     2479        </varlistentry>
     2480        <varlistentry>
     2481          <term><option>--cpuid-remove=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>]</option></term>
     2482          <listitem>
     2483            <para>
     2484              Removes an adjustment established with <option>--cpuid-set</option>.
     2485            </para></listitem>
     2486        </varlistentry>
     2487        <varlistentry>
     2488          <term><option>--cpuidremoveall</option></term>
     2489          <listitem>
     2490            <para>
     2491              Removes all adjustments established with <option>--cpuid-set</option>.
    24412492            </para></listitem>
    24422493        </varlistentry>
    … …  
    25162567              Specifies the number of seconds after host system boot-up
    25172568              to autostart the VM.
     2569            </para></listitem>
     2570        </varlistentry>
     2571      </variablelist>
     2572    </refsect2>
     2573    <refsect2 id="vboxmanage-modifyvm-pcipassthrough">
     2574      <title>PCI Passthrough Settings</title>
     2575      <para>
     2576        The following options enable you to configure the PCI passthrough
     2577        feature, which currently is not available in &product-name;. It is
     2578        planned to bring this functionality back in the future.
     2579      </para>
     2580      <remark role="help-copy-synopsis"/>
     2581      <variablelist>
     2582        <varlistentry>
     2583          <term><option>--pciattach=<replaceable>host-PCI-address</replaceable>[@<replaceable>guest-PCI-bus-address</replaceable>]</option></term>
     2584          <listitem><para>
     2585              Attaches the specified PCI network controller on the host
     2586              to the guest VM. You can optionally specify the PCI bus on
     2587              the guest VM on which to attach the controller.
     2588<!-- See <xref linkend="pcipassthrough" />. -->
     2589            </para></listitem>
     2590        </varlistentry>
     2591        <varlistentry>
     2592          <term><option>--pcidetach=<replaceable>host-PCI-address</replaceable></option></term>
     2593          <listitem><para>
     2594              Detaches the specified PCI network controller from the
     2595              attached PCI bus on the guest VM.
     2596<!-- See <xref linkend="pcipassthrough" />. -->
    25182597            </para></listitem>
    25192598        </varlistentry>

  • trunk/doc/manual/en_US/man_VBoxManage-movevm.xml

    r87075 r91204  
    2020<refentry id="vboxmanage-movevm" lang="en">
    2121  <refentryinfo>
    22     <pubdate>August 2019</pubdate>
     22    <pubdate>$Date$</pubdate>
    2323    <title>VBoxManage movevm</title>
    2424  </refentryinfo>
    … …  
    4343        <arg choice="plain"><replaceable>vmname</replaceable></arg>
    4444      </group>
    45       <arg choice="req">--type=basic</arg>
     45      <arg>--type=basic</arg>
    4646      <arg>--folder=<replaceable>folder-name</replaceable></arg>
    4747    </cmdsynopsis>
    … …  
    7171        <term><option>--type=basic</option></term>
    7272        <listitem><para>
    73             Specifies that the type of the move operation is basic.
     73            Specifies the type of the move operation. So far
     74            <literal>basic</literal> is the only recognized value and also
     75            the default if not specified.
    7476          </para></listitem>
    7577      </varlistentry>
    … …  
    7880        <listitem><para>
    7981            Specifies a full path name or relative path name of the new
    80             location on the host file system.
     82            location on the host file system. Not specifying the option
     83            or specifying the current location is allowed, and moves
     84            disk images and other parts of the VM to this location if
     85            they are currently in other locations.
    8186          </para></listitem>
    8287      </varlistentry>

  • trunk/doc/manual/en_US/user_Frontends.xml

    r82350 r91204  
    11991199        Advanced users can attempt to restrict these virtual CPU
    12001200        capabilities with the <command>VBoxManage modifyvm
    1201         --cpuid</command> command. See
     1201        --cpuid-portability-level</command> command. See
    12021202        <xref linkend="vboxmanage-modifyvm" />.
    12031203      </para>

  • trunk/doc/manual/en_US/user_VBoxManage.xml

    r87077 r91204  
    246246  </sect1>
    247247
     248  <!-- TODO: Figure out how we can generate a file with the includes... The trouble is
     249             that xpointer doesn't seem to allow including multiple elements.
     250
     251             In the mean time, when adding new VBoxManage man pages to Config.kmk,
     252             don't forget to add it here too.
     253   -->
     254
    248255  <sect1 id="vboxmanage-general">
    249256
    … …  
    295302  </sect1>
    296303
    297   <sect1 id="vboxmanage-list">
    298 
    299     <title>VBoxManage list</title>
    300 
    301     <para>
    302       The <command>list</command> command gives relevant information
    303       about your system and information about &product-name;'s current
    304       settings.
    305     </para>
    306 
    307     <para>
    308       The following subcommands are available with <command>VBoxManage
    309       list</command>:
    310     </para>
    311 
    312     <itemizedlist>
    313 
    314       <listitem>
    315         <para>
    316           <command>vms</command>: Lists all virtual machines currently
    317           registered with &product-name;. By default this displays a
    318           compact list with each VM's name and UUID. If you also specify
    319           <option>--long</option> or <option>-l</option>, this will be a
    320           detailed list as with the <command>showvminfo</command>
    321           command, see <xref linkend="vboxmanage-showvminfo"/>.
    322         </para>
    323       </listitem>
    324 
    325       <listitem>
    326         <para>
    327           <command>runningvms</command>: Lists all currently running
    328           virtual machines by their unique identifiers (UUIDs) in the
    329           same format as with <command>vms</command>.
    330         </para>
    331       </listitem>
    332 
    333       <listitem>
    334         <para>
    335           <command>ostypes</command>: Lists all guest operating systems
    336           presently known to &product-name;, along with the identifiers
    337           used to refer to them with the <command>modifyvm</command>
    338           command.
    339         </para>
    340       </listitem>
    341 
    342       <listitem>
    343         <para>
    344           <command>hostdvds</command>, <command>hostfloppies</command>:
    345           Lists the DVD, floppy, bridged networking, and host-only
    346           networking interfaces on the host, along with the name used to
    347           access them from within &product-name;.
    348         </para>
    349       </listitem>
    350 
    351       <listitem>
    352         <para>
    353           <command>intnets</command>: Displays information about the
    354           internal networks.
    355         </para>
    356       </listitem>
    357 
    358       <listitem>
    359         <para>
    360           <command>bridgedifs</command>, <command>hostonlyifs</command>,
    361           <command>natnets</command>, <command>dhcpservers</command>:
    362           Lists the bridged network interfaces, host-only network
    363           interfaces, NAT network interfaces, and DHCP servers currently
    364           available on the host. See
    365           <xref linkend="networkingdetails" />.
    366         </para>
    367       </listitem>
    368 
    369       <listitem>
    370         <para>
    371           <command>hostinfo</command>: Displays information about the
    372           host system, such as CPUs, memory size, and operating system
    373           version.
    374         </para>
    375       </listitem>
    376 
    377       <listitem>
    378         <para>
    379           <command>hostcpuids</command>: Lists the CPUID parameters for
    380           the host CPUs. This can be used for a more fine grained
    381           analyis of the host's virtualization capabilities.
    382         </para>
    383       </listitem>
    384 
    385       <listitem>
    386         <para>
    387           <command>hddbackends</command>: Lists all known virtual disk
    388           back-ends of &product-name;. For each such format, such as
    389           VDI, VMDK, or RAW, this subcommand lists the back-end's
    390           capabilities and configuration.
    391         </para>
    392       </listitem>
    393 
    394       <listitem>
    395         <para>
    396           <command>hdds</command>, <command>dvds</command>,
    397           <command>floppies</command>: Shows information about virtual
    398           disk images currently in use by &product-name;, including all
    399           their settings, the unique identifiers (UUIDs) associated with
    400           them by &product-name; and all files associated with them.
    401           This is the command-line equivalent of the Virtual Media
    402           Manager. See <xref linkend="vdis" />.
    403         </para>
    404       </listitem>
    405 
    406       <listitem>
    407         <para>
    408           <command>usbhost</command>: Shows information about USB
    409           devices attached to the host, including information useful for
    410           constructing USB filters and whether they are currently in use
    411           by the host.
    412         </para>
    413       </listitem>
    414 
    415       <listitem>
    416         <para>
    417           <command>usbfilters</command>: Lists all global USB filters
    418           registered with &product-name; and displays the filter
    419           parameters. Global USB filters are for devices which are
    420           accessible to all virtual machines.
    421         </para>
    422       </listitem>
    423 
    424       <listitem>
    425         <para>
    426           <command>systemproperties</command>: Displays some global
    427           &product-name; settings, such as minimum and maximum guest RAM
    428           and virtual hard disk size, folder settings and the current
    429           authentication library in use.
    430         </para>
    431       </listitem>
    432 
    433       <listitem>
    434         <para>
    435           <command>extpacks</command>: Displays all &product-name;
    436           extension packs that are currently installed. See
    437           <xref linkend="intro-installing" /> and
    438           <xref linkend="vboxmanage-extpack" />.
    439         </para>
    440       </listitem>
    441 
    442       <listitem>
    443         <para>
    444           <command>groups</command>: Displays details of the VM Groups.
    445           See <xref linkend="gui-vmgroups" />.
    446         </para>
    447       </listitem>
    448 
    449       <listitem>
    450         <para>
    451           <command>webcams</command>: Displays a list of webcams
    452           attached to the running VM. The output format is a list of
    453           absolute paths or aliases that were used for attaching the
    454           webcams to the VM using the webcam attach command.
    455         </para>
    456       </listitem>
    457 
    458       <listitem>
    459         <para>
    460           <command>screenshotformats</command>: Displays a list of
    461           available screenshot formats.
    462         </para>
    463       </listitem>
    464 
    465       <listitem>
    466         <para>
    467           <command>cloudproviders</command>: Displays a list of cloud
    468           providers that are supported by &product-name;. &oci; is an
    469           example of a cloud provider.
    470         </para>
    471       </listitem>
    472 
    473       <listitem>
    474         <para>
    475           <command>cloudprofiles</command>: Displays a list of cloud
    476           profiles that have been configured.
    477         </para>
    478 
    479         <para>
    480           Cloud profiles are used when exporting VMs to a cloud service.
    481           See <xref linkend="cloud-export-oci"/>.
    482         </para>
    483       </listitem>
    484 
    485       <listitem>
    486         <para>
    487           <command>hostdrives</command>: Displays a list of host fixed
    488           drives with their partitions.  If you also specify
    489           <option>--long</option> or <option>-l</option> the sizes and
    490           offsets will be in bytes.
    491         </para>
    492       </listitem>
    493 
    494     </itemizedlist>
    495 
    496   </sect1>
    497 
    498   <sect1 id="vboxmanage-showvminfo">
    499 
    500     <title>VBoxManage showvminfo</title>
    501 
    502     <para>
    503       The <command>showvminfo</command> command shows information about
    504       a particular virtual machine. This is the same information as
    505       <command>VBoxManage list vms --long</command> would show for all
    506       virtual machines.
    507     </para>
    508 
    509     <para>
    510       You will see information as shown in the following example.
    511     </para>
    512 
    513 <screen>$ VBoxManage showvminfo "Windows XP"
    514 VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
    515 (C) 2005-2018 Oracle Corporation
    516 All rights reserved.
    517 
    518 Name:            Windows XP
    519 Guest OS:        Other/Unknown
    520 UUID:            1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
    521 Config file:     /home/username/.config/VirtualBox/Machines/Windows XP/Windows XP.xml
    522 Memory size:     512MB
    523 VRAM size:       12MB
    524 Number of CPUs:  2
    525 Boot menu mode:  message and menu
    526 Boot Device (1): DVD
    527 Boot Device (2): HardDisk
    528 Boot Device (3): Not Assigned
    529 Boot Device (4): Not Assigned
    530 ACPI:            on
    531 IOAPIC:          on
    532 ...
    533     </screen>
    534 
    535     <para>
    536       Use the <option>--machinereadable</option> option to produce the
    537       same output, but in machine readable format with a property=value
    538       string on each line. For example:
    539     </para>
    540 
    541 <screen>
    542 ...
    543 groups="/"
    544 ostype="Oracle (64-bit)"
    545 UUID="457af700-bc0a-4258-aa3c-13b03da171f2"
    546 ...
    547  </screen>
    548 
    549   </sect1>
    550 
    551   <sect1 id="vboxmanage-registervm">
    552 
    553     <title>VBoxManage registervm/unregistervm</title>
    554 
    555     <para>
    556       The <computeroutput>registervm</computeroutput> command enables
    557       you to import a virtual machine definition in an XML file into
    558       &product-name;. The machine must not conflict with one already
    559       registered in &product-name; and it may not have any hard or
    560       removable disks attached. It is advisable to place the definition
    561       file in the machines folder before registering it.
    562     </para>
    563 
    564     <note>
    565       <para>
    566         When creating a new virtual machine with <command>VBoxManage
    567         createvm</command>, as shown in
    568         <xref linkend="vboxmanage-createvm"/>, you can directly specify
    569         the <option>--register</option> option to avoid having to
    570         register it separately.
    571       </para>
    572     </note>
    573 
    574     <para>
    575       The <command>unregistervm</command> command unregisters a virtual
    576       machine. If <option>--delete</option> is also specified, the
    577       following files will also be deleted automatically:
    578     </para>
    579 
    580     <itemizedlist>
    581 
    582       <listitem>
    583         <para>
    584           All hard disk image files, including differencing files, which
    585           are used by the machine and not shared with other machines.
    586         </para>
    587       </listitem>
    588 
    589       <listitem>
    590         <para>
    591           Saved state files that the machine created. One if the machine
    592           was in Saved state and one for each online snapshot.
    593         </para>
    594       </listitem>
    595 
    596       <listitem>
    597         <para>
    598           The machine XML file and its backups.
    599         </para>
    600       </listitem>
    601 
    602       <listitem>
    603         <para>
    604           The machine log files.
    605         </para>
    606       </listitem>
    607 
    608       <listitem>
    609         <para>
    610           The machine directory, if it is empty after having deleted all
    611           of the above files.
    612         </para>
    613       </listitem>
    614 
    615     </itemizedlist>
    616 
    617   </sect1>
    618 
    619   <sect1 id="vboxmanage-createvm">
    620 
    621     <title>VBoxManage createvm</title>
    622 
    623     <para>
    624       The <command>VBoxManage createvm</command> command creates a new
    625       XML virtual machine definition file.
    626     </para>
    627 
    628     <para>
    629       You must specify the name of the VM by using <option>--name
    630       <replaceable>name</replaceable></option>. This name is used by
    631       default as the file name of the settings file that has the
    632       <filename>.xml</filename> extension and the machine folder, which
    633       is a subfolder of the
    634       <filename>.config/VirtualBox/Machines</filename> folder. Note that
    635       the machine folder path name varies based on the OS type and the
    636       &product-name; version.
    637     </para>
    638 
    639     <para>
    640       Ensure that the VM name conforms to the host OS's file name
    641       requirements. If you later rename the VM, the file and folder
    642       names will be updated to match the new name automatically.
    643     </para>
    644 
    645     <para>
    646       The <option>--basefolder <replaceable>path</replaceable></option>
    647       option specifies the machine folder path name. Note that the names
    648       of the file and the folder do not change if you rename the VM.
    649     </para>
    650 
    651     <para>
    652       The <option>--group <replaceable>group-ID</replaceable>,
    653       ...</option> option assigns the VM to the specified groups. Note
    654       that group IDs always start with
    655       <computeroutput>/</computeroutput> so that they can be nested. By
    656       default, each VM is assigned membership to the
    657       <computeroutput>/</computeroutput> group.
    658     </para>
    659 
    660     <para>
    661       The <option>--ostype <replaceable>ostype</replaceable></option>
    662       option specifies the guest OS to run in the VM. Run the
    663       <command>VBoxManage list ostypes</command> command to see the
    664       available OS types.
    665     </para>
    666 
    667     <para>
    668       The <option>--uuid <replaceable>uuid</replaceable></option> option
    669       specifies the universal unique identifier (UUID) of the VM. The
    670       UUID must be unique within the namespace of the host or of its VM
    671       group memberships. By default, the <command>VBoxManage</command>
    672       command automatically generates the UUID.
    673     </para>
    674 
    675     <para>
    676       The <computeroutput>--default</computeroutput> option applies a
    677       default hardware configuration for the specified guest OS. By
    678       default, the VM is created with minimal hardware.
    679     </para>
    680 
    681     <para>
    682       The <option>--register</option> option registers the VM with your
    683       &product-name; installation. By default, the <command>VBoxManage
    684       createvm</command> command creates only the XML configuration for
    685       the VM but does not registered the VM. If you do not register the
    686       VM at creation, you can run the <command>VBoxManage
    687       registervm</command> command after you create the VM.
    688     </para>
    689 
    690   </sect1>
    691 
    692   <sect1 id="vboxmanage-modifyvm">
    693 
    694     <title>VBoxManage modifyvm</title>
    695 
    696     <para>
    697       This command changes the properties of a registered virtual
    698       machine which is not running. Most of the properties that this
    699       command makes available correspond to the VM settings that the
    700       VirtualBox Manager displays in each VM's
    701       <emphasis role="bold">Settings</emphasis> dialog. These are
    702       described in <xref linkend="BasicConcepts" />. However, some of
    703       the more advanced settings are only available through the
    704       <command>VBoxManage</command> interface.
    705     </para>
    706 
    707     <para>
    708       These commands require that the machine is powered off, neither
    709       running nor in a Saved state. Some machine settings can also be
    710       changed while a machine is running. Those settings will then have
    711       a corresponding subcommand with the <command>VBoxManage
    712       controlvm</command> subcommand. See
    713       <xref linkend="vboxmanage-controlvm" />.
    714     </para>
    715 
    716     <sect2 id="vboxmanage-modifyvm-general">
    717 
    718       <title>General Settings</title>
    719 
    720       <para>
    721         The following general settings are available through
    722         <command>VBoxManage modifyvm</command>:
    723       </para>
    724 
    725       <itemizedlist>
    726 
    727         <listitem>
    728           <para>
    729             <computeroutput>--name &lt;name&gt;</computeroutput>:
    730             Changes the VM's name and can be used to rename the internal
    731             virtual machine files, as described in
    732             <xref linkend="vboxmanage-createvm"/>.
    733           </para>
    734         </listitem>
    735 
    736         <listitem>
    737           <para>
    738             <computeroutput>--groups &lt;group&gt;,
    739             ...</computeroutput>: Changes the group membership of a VM.
    740             Groups always start with a
    741             <computeroutput>/</computeroutput> and can be nested. By
    742             default VMs are in group <computeroutput>/</computeroutput>.
    743           </para>
    744         </listitem>
    745 
    746         <listitem>
    747           <para>
    748             <computeroutput>--description &lt;desc&gt;</computeroutput>:
    749             Changes the VM's description, which is a way to record
    750             details about the VM in a way which is meaningful for the
    751             user. The GUI interprets HTML formatting, the command line
    752             allows arbitrary strings potentially containing multiple
    753             lines.
    754           </para>
    755         </listitem>
    756 
    757         <listitem>
    758           <para>
    759             <computeroutput>--ostype &lt;ostype&gt;</computeroutput>:
    760             Specifies what guest operating system is supposed to run in
    761             the VM. To learn about the various identifiers that can be
    762             used here, use <command>VBoxManage list ostypes</command>.
    763           </para>
    764         </listitem>
    765 
    766         <listitem>
    767           <para>
    768             <computeroutput>--iconfile
    769             &lt;filename&gt;</computeroutput>: Specifies the absolute
    770             path on the host file system for the &product-name; icon to
    771             be displayed in the VM.
    772           </para>
    773         </listitem>
    774 
    775         <listitem>
    776           <para>
    777             <computeroutput>--memory
    778             &lt;memorysize&gt;</computeroutput>: Sets the amount of RAM,
    779             in MB, that the virtual machine should allocate for itself
    780             from the host. See <xref linkend="gui-createvm" />.
    781           </para>
    782         </listitem>
    783 
    784         <listitem>
    785           <para>
    786             <computeroutput>--pagefusion on|off</computeroutput>:
    787             Enables and disables the Page Fusion feature. Page Fusion is
    788             disabled by default. The Page Fusion feature minimises
    789             memory duplication between VMs with similar configurations
    790             running on the same host. See
    791             <xref linkend="guestadd-pagefusion" />.
    792           </para>
    793         </listitem>
    794 
    795         <listitem>
    796           <para>
    797             <computeroutput>--vram &lt;vramsize&gt;</computeroutput>:
    798             Sets the amount of RAM that the virtual graphics card should
    799             have. See <xref linkend="settings-display" />.
    800           </para>
    801         </listitem>
    802 
    803         <listitem>
    804           <para>
    805             <computeroutput>--acpi on|off</computeroutput> and
    806             <computeroutput>--ioapic on|off</computeroutput>: Determines
    807             whether the VM has ACPI and I/O APIC support. See
    808             <xref linkend="settings-motherboard" />.
    809           </para>
    810         </listitem>
    811 
    812         <listitem>
    813           <para>
    814             <computeroutput>--pciattach &lt;host PCI address [@ guest
    815             PCI bus address]&gt;</computeroutput>: Attaches a specified
    816             PCI network controller on the host to a specified PCI bus on
    817             the guest.
    818 
    819 <!--See <xref linkend="pcipassthrough" />.-->
    820           </para>
    821         </listitem>
    822 
    823         <listitem>
    824           <para>
    825             <computeroutput>--pcidetach &lt;host PCI
    826             address&gt;</computeroutput>: Detaches a specified PCI
    827             network controller on the host from the attached PCI bus on
    828             the guest.
    829 
    830 <!--See <xref linkend="pcipassthrough" />.-->
    831           </para>
    832         </listitem>
    833 
    834         <listitem>
    835           <para>
    836             <computeroutput>--hardwareuuid
    837             &lt;uuid&gt;</computeroutput>: The UUID presented to the
    838             guest through memory tables (DMI/SMBIOS), hardware, and
    839             guest properties. By default this is the same as the VM
    840             UUID. This setting is useful when cloning a VM. Teleporting
    841             takes care of this automatically.
    842           </para>
    843         </listitem>
    844 
    845         <listitem>
    846           <para>
    847             <computeroutput>--cpus &lt;cpucount&gt;</computeroutput>:
    848             Sets the number of virtual CPUs for the virtual machine, see
    849             <xref linkend="settings-processor" />. If CPU hot-plugging
    850             is enabled, this then sets the <emphasis>maximum</emphasis>
    851             number of virtual CPUs that can be plugged into the virtual
    852             machines.
    853           </para>
    854         </listitem>
    855 
    856         <listitem>
    857           <para>
    858             <computeroutput>--cpuhotplug on|off</computeroutput>:
    859             Enables CPU hot-plugging. When enabled, virtual CPUs can be
    860             added to and removed from a virtual machine while it is
    861             running. See <xref linkend="cpuhotplug" />.
    862           </para>
    863         </listitem>
    864 
    865         <listitem>
    866           <para>
    867             <computeroutput>--plugcpu|unplugcpu
    868             &lt;id&gt;</computeroutput>: If CPU hot-plugging is enabled,
    869             this setting adds or removes a virtual CPU on the virtual
    870             machine. <computeroutput>&lt;id&gt;</computeroutput>
    871             specifies the index of the virtual CPU to be added or
    872             removed and must be a number from 0 to the maximum number of
    873             CPUs configured with the
    874             <computeroutput>--cpus</computeroutput> option. CPU 0 can
    875             never be removed.
    876           </para>
    877         </listitem>
    878 
    879         <listitem>
    880           <para>
    881             <computeroutput>--cpuexecutioncap
    882             &lt;1-100&gt;</computeroutput>: Controls how much CPU time a
    883             virtual CPU can use. A value of 50 implies a single virtual
    884             CPU can use up to 50% of a single host CPU.
    885           </para>
    886         </listitem>
    887 
    888         <listitem>
    889           <para>
    890             <computeroutput>--pae on|off</computeroutput>: Enables and
    891             disables PAE. See <xref linkend="settings-processor" />.
    892           </para>
    893         </listitem>
    894 
    895         <listitem>
    896           <para>
    897             <computeroutput>--longmode on|off</computeroutput>: Enables
    898             and disables long mode. See
    899             <xref linkend="settings-processor" />.
    900           </para>
    901         </listitem>
    902 
    903         <listitem>
    904           <para>
    905             <computeroutput>--spec-ctrl on|off</computeroutput>: Enables
    906             and disables the exposure of speculation control interfaces
    907             to the guest, provided they are available on the host.
    908             Depending on the host CPU and workload, enabling speculation
    909             control may significantly reduce performance.
    910           </para>
    911         </listitem>
    912 
    913         <listitem>
    914           <para>
    915             <computeroutput>--cpu-profile &lt;host|intel
    916             80[86|286|386]&gt;</computeroutput>: Enables specification
    917             of a profile for guest CPU emulation. Specify either one
    918             based on the host system CPU (host), or one from a number of
    919             older Intel Micro-architectures: 8086, 80286, 80386.
    920           </para>
    921         </listitem>
    922 
    923         <listitem>
    924           <para>
    925             <computeroutput>--hpet on|off</computeroutput>: Enables and
    926             disables a High Precision Event Timer (HPET) which can
    927             replace the legacy system timers. This is turned off by
    928             default. Note that Windows supports a HPET only from Vista
    929             onwards.
    930           </para>
    931         </listitem>
    932 
    933         <listitem>
    934           <para>
    935             <computeroutput>--hwvirtex on|off</computeroutput>: Enables
    936             and disables the use of hardware virtualization extensions,
    937             such as Intel VT-x or AMD-V, in the processor of your host
    938             system. See <xref linkend="hwvirt" />.
    939           </para>
    940         </listitem>
    941 
    942         <listitem>
    943           <para>
    944             <computeroutput>--triplefaultreset on|off</computeroutput>:
    945             Enables resetting of the guest instead of triggering a Guru
    946             Meditation. Some guests raise a triple fault to reset the
    947             CPU so sometimes this is desired behavior. Works only for
    948             non-SMP guests.
    949           </para>
    950         </listitem>
    951 
    952         <listitem>
    953           <para>
    954             <computeroutput>--apic on|off</computeroutput>: Enables and
    955             disables I/O APIC. With I/O APIC, operating systems can use
    956             more than 16 interrupt requests (IRQs) thus avoiding IRQ
    957             sharing for improved reliability. This setting is enabled by
    958             default. See <xref linkend="settings-motherboard" />.
    959           </para>
    960         </listitem>
    961 
    962         <listitem>
    963           <para>
    964             <computeroutput>--x2apic on|off</computeroutput>: Enables
    965             and disables CPU x2APIC support. CPU x2APIC support helps
    966             operating systems run more efficiently on high core count
    967             configurations, and optimizes interrupt distribution in
    968             virtualized environments. This setting is enabled by
    969             default. Disable this setting when using host or guest
    970             operating systems that are incompatible with x2APIC support.
    971           </para>
    972         </listitem>
    973 
    974         <listitem>
    975           <para>
    976             <computeroutput>--paravirtprovider
    977             none|default|legacy|minimal|hyperv|kvm</computeroutput>:
    978             Specifies which paravirtualization interface to provide to
    979             the guest operating system. Specifying
    980             <computeroutput>none</computeroutput> explicitly turns off
    981             exposing any paravirtualization interface. The option
    982             <computeroutput>default</computeroutput> selects an
    983             appropriate interface when starting the VM, depending on the
    984             guest OS type. This is the default option chosen when
    985             creating new VMs. The
    986             <computeroutput>legacy</computeroutput> option is used for
    987             VMs which were created with older &product-name; versions
    988             and will pick a paravirtualization interface when starting
    989             the VM with &product-name; 5.0 and newer. The
    990             <computeroutput>minimal</computeroutput> provider is
    991             mandatory for Mac OS X guests.
    992             <computeroutput>kvm</computeroutput> and
    993             <computeroutput>hyperv</computeroutput> are recommended for
    994             Linux and Windows guests respectively. These options are
    995             explained in <xref linkend="gimproviders" />.
    996           </para>
    997         </listitem>
    998 
    999         <listitem>
    1000           <para>
    1001             <computeroutput>--paravirtdebug &lt;keyword=value&gt;
    1002             [,&lt;keyword=value&gt; ...]</computeroutput>: Specifies
    1003             debugging options specific to the paravirtualization
    1004             provider configured for this VM. See the provider specific
    1005             options in <xref linkend="gimdebug" /> for a list of
    1006             supported keyword-value pairs for each provider.
    1007           </para>
    1008         </listitem>
    1009 
    1010         <listitem>
    1011           <para>
    1012             <computeroutput>--nestedpaging on|off</computeroutput>: If
    1013             hardware virtualization is enabled, this additional setting
    1014             enables or disables the use of the nested paging feature in
    1015             the processor of your host system. See
    1016             <xref linkend="hwvirt" /> and
    1017             <xref linkend="sec-rec-cve-2018-3646" />.
    1018           </para>
    1019         </listitem>
    1020 
    1021         <listitem>
    1022           <para>
    1023             <computeroutput>--largepages on|off</computeroutput>: If
    1024             hardware virtualization <emphasis>and</emphasis> nested
    1025             paging are enabled, for Intel VT-x only, an additional
    1026             performance improvement of up to 5% can be obtained by
    1027             enabling this setting. This causes the hypervisor to use
    1028             large pages to reduce TLB use and overhead.
    1029           </para>
    1030         </listitem>
    1031 
    1032         <listitem>
    1033           <para>
    1034             <computeroutput>--vtxvpid on|off</computeroutput>: If
    1035             hardware virtualization is enabled, for Intel VT-x only,
    1036             this additional setting enables or disables the use of the
    1037             tagged TLB (VPID) feature in the processor of your host
    1038             system. See <xref linkend="hwvirt" />.
    1039           </para>
    1040         </listitem>
    1041 
    1042         <listitem>
    1043           <para>
    1044             <computeroutput>--vtxux on|off</computeroutput>: If hardware
    1045             virtualization is enabled, for Intel VT-x only, this setting
    1046             enables or disables the use of the unrestricted guest mode
    1047             feature for executing your guest.
    1048           </para>
    1049         </listitem>
    1050 
    1051         <listitem>
    1052           <para>
    1053             <computeroutput>--nested-hw-virt on|off</computeroutput>: If
    1054             hardware virtualization is enabled, this setting enables or
    1055             disables passthrough of hardware virtualization features to
    1056             the guest. See <xref linkend="nested-virt" />.
    1057           </para>
    1058         </listitem>
    1059 
    1060         <listitem>
    1061           <para>
    1062             <computeroutput>--virt-vmsave-vmload on|off</computeroutput>:
    1063             If hardware virtualization is enabled, for AMD-V only, this
    1064             setting enables or disables the use of the virtualized
    1065             vmsave/vmload host feature while executing your guest. It is
    1066             enabled by default. It is recommended to leave enabled as it
    1067             has a drastic impact on performance while executing nested
    1068             guests using the nested hardware virtualization feature.
    1069           </para>
    1070         </listitem>
    1071 
    1072         <listitem>
    1073           <para>
    1074             <computeroutput>--accelerate3d on|off</computeroutput>: If
    1075             the Guest Additions are installed, this setting enables or
    1076             disables hardware 3D acceleration. See
    1077             <xref linkend="guestadd-3d" />.
    1078           </para>
    1079         </listitem>
    1080 
    1081         <listitem>
    1082           <para>
    1083             <computeroutput>--accelerate2dvideo on|off</computeroutput>:
    1084             If the Guest Additions are installed, this setting enables
    1085             or disables 2D video acceleration. See
    1086             <xref linkend="guestadd-2d" />.
    1087           </para>
    1088         </listitem>
    1089 
    1090         <listitem>
    1091           <para>
    1092             <computeroutput>--chipset piix3|ich9</computeroutput>: By
    1093             default, &product-name; emulates an Intel PIIX3 chipset.
    1094             Usually there is no reason to change the default setting
    1095             unless this is required to relax some of its constraints.
    1096             See <xref linkend="settings-motherboard" />.
    1097           </para>
    1098         </listitem>
    1099 
    1100         <listitem>
    1101           <para>
    1102             You can influence the BIOS logo that is displayed when a
    1103             virtual machine starts up with a number of settings. By
    1104             default, an &product-name; logo is displayed.
    1105           </para>
    1106 
    1107           <para>
    1108             With <computeroutput>--bioslogofadein
    1109             on|off</computeroutput> and
    1110             <computeroutput>--bioslogofadeout on|off</computeroutput>,
    1111             you can determine whether the logo should fade in and out,
    1112             respectively.
    1113           </para>
    1114 
    1115           <para>
    1116             With <computeroutput>--bioslogodisplaytime
    1117             &lt;msec&gt;</computeroutput> you can set how long the logo
    1118             should be visible, in milliseconds.
    1119           </para>
    1120 
    1121           <para>
    1122             With <computeroutput>--bioslogoimagepath
    1123             &lt;imagepath&gt;</computeroutput> you can replace the image
    1124             that is shown with your own logo. The image must be an
    1125             uncompressed 256 color BMP file without color space
    1126             information (Windows 3.0 format). The image must not be
    1127             bigger than 640 x 480.
    1128           </para>
    1129         </listitem>
    1130 
    1131         <listitem>
    1132           <para>
    1133             <computeroutput>--biosbootmenu
    1134             disabled|menuonly|messageandmenu</computeroutput>: Specifies
    1135             whether the BIOS enables the user to select a temporary boot
    1136             device. The <computeroutput>menuonly</computeroutput> option
    1137             suppresses the message, but the user can still press F12 to
    1138             select a temporary boot device.
    1139           </para>
    1140         </listitem>
    1141 
    1142         <listitem>
    1143           <para>
    1144             <computeroutput>--biosapic
    1145             x2apic|apic|disabled</computeroutput>: Specifies the
    1146             firmware APIC level to be used. Options are: x2apic, apic or
    1147             disabled (no apic or x2apic) respectively.
    1148           </para>
    1149 
    1150           <para>
    1151             Note that if x2apic is specified and x2APIC is unsupported
    1152             by the VCPU, biosapic downgrades to apic, if supported.
    1153             Otherwise biosapic downgrades to disabled. Similarly, if
    1154             apic is specified, and APIC is unsupported, a downgrade to
    1155             disabled results.
    1156           </para>
    1157         </listitem>
    1158 
    1159         <listitem>
    1160           <para>
    1161             <computeroutput>--biossystemtimeoffset
    1162             &lt;ms&gt;</computeroutput>: Specifies a fixed time offset,
    1163             in milliseconds, of the guest relative to the host time. If
    1164             the offset is positive, the guest time runs ahead of the
    1165             host time.
    1166           </para>
    1167         </listitem>
    1168 
    1169         <listitem>
    1170           <para>
    1171             <computeroutput>--biospxedebug on|off</computeroutput>:
    1172             Enables or disables additional debugging output when using
    1173             the Intel PXE boot ROM. The output is written to the release
    1174             log file. See <xref linkend="collect-debug-info" />.
    1175           </para>
    1176         </listitem>
    1177 
    1178         <listitem>
    1179           <para>
    1180             <computeroutput>--system-uuid-le on|off</computeroutput>:
    1181             Enables or disables representing the system UUID in little
    1182             endian form. The default value is <literal>on</literal> for
    1183             new VMs. For old VMs the setting is <literal>off</literal>
    1184             to keep the content of the DMI/SMBIOS table unchanged, which
    1185             can be important for Windows license activation.
    1186           </para>
    1187         </listitem>
    1188 
    1189         <listitem>
    1190           <para>
    1191             <computeroutput>--boot&lt;1-4&gt;
    1192             none|floppy|dvd|disk|net</computeroutput>: Specifies the
    1193             boot order for the virtual machine. There are four
    1194             <emphasis>slots</emphasis>, which the VM will try to access
    1195             from 1 to 4, and for each of which you can set a device that
    1196             the VM should attempt to boot from.
    1197           </para>
    1198         </listitem>
    1199 
    1200         <listitem>
    1201           <para>
    1202             <computeroutput>--rtcuseutc on|off</computeroutput>: Sets
    1203             the real-time clock (RTC) to operate in UTC time. See
    1204             <xref linkend="settings-motherboard" />.
    1205           </para>
    1206         </listitem>
    1207 
    1208         <listitem>
    1209           <para>
    1210             <computeroutput>--graphicscontroller
    1211             none|vboxvga|vmsvga|vboxsvga</computeroutput>: Specifies the
    1212             use of a graphics controller, with an option to choose a
    1213             specific type. See <xref linkend="settings-screen" />.
    1214           </para>
    1215         </listitem>
    1216 
    1217         <listitem>
    1218           <para>
    1219             <computeroutput>--snapshotfolder
    1220             default|&lt;path&gt;</computeroutput>: Specifies the folder
    1221             where snapshots are kept for a virtual machine.
    1222           </para>
    1223         </listitem>
    1224 
    1225         <listitem>
    1226           <para>
    1227             <computeroutput>--firmware
    1228             bios|efi|efi32|efi64</computeroutput>: Specifies the
    1229             firmware to be used to boot the VM: Available options are:
    1230             BIOS, or one of the EFI options: efi, efi32, or efi64. Use
    1231             EFI options with care.
    1232           </para>
    1233         </listitem>
    1234 
    1235         <listitem>
    1236           <para>
    1237             <computeroutput>--guestmemoryballoon
    1238             &lt;size&gt;</computeroutput> Sets the default size of the
    1239             guest memory balloon. This is the memory allocated by the
    1240             &product-name; Guest Additions from the guest operating
    1241             system and returned to the hypervisor for reuse by other
    1242             virtual machines.
    1243             <computeroutput>&lt;size&gt;</computeroutput> must be
    1244             specified in megabytes. The default size is 0 megabytes. See
    1245             <xref linkend="guestadd-balloon" />.
    1246           </para>
    1247         </listitem>
    1248 
    1249         <listitem>
    1250           <para>
    1251             <computeroutput>--defaultfrontend
    1252             default|&lt;name&gt;</computeroutput>: Specifies the default
    1253             frontend to be used when starting this VM. See
    1254             <xref linkend="vboxmanage-startvm" />.
    1255           </para>
    1256         </listitem>
    1257 
    1258         <listitem>
    1259           <para>
    1260             <computeroutput>--vm-process-priority
    1261             default|flat|low|normal|high</computeroutput>: Specifies the
    1262             priority scheme of the VM process to be used when starting
    1263             this VM and during VM execution. See
    1264             <xref linkend="vboxmanage-startvm" />.
    1265           </para>
    1266         </listitem>
    1267 
    1268       </itemizedlist>
    1269 
    1270     </sect2>
    1271 
    1272     <sect2 id="vboxmanage-modifyvm-networking">
    1273 
    1274       <title>Networking Settings</title>
    1275 
    1276       <para>
    1277         The following networking settings are available through
    1278         <command>VBoxManage modifyvm</command>. With all these settings,
    1279         the decimal number directly following the option name, 1-N in
    1280         the list below, specifies the virtual network adapter whose
    1281         settings should be changed.
    1282       </para>
    1283 
    1284       <itemizedlist>
    1285 
    1286         <listitem>
    1287           <para>
    1288             <computeroutput>--nic&lt;1-N&gt;
    1289             none|null|nat|natnetwork|bridged|intnet|hostonly|generic</computeroutput>:
    1290             Configures the type of networking for each of the VM's
    1291             virtual network cards. Options are: not present
    1292             (<computeroutput>none</computeroutput>), not connected to
    1293             the host (<computeroutput>null</computeroutput>), use
    1294             network address translation
    1295             (<computeroutput>nat</computeroutput>), use the new network
    1296             address translation engine
    1297             (<computeroutput>natnetwork</computeroutput>), bridged
    1298             networking (<computeroutput>bridged</computeroutput>), or
    1299             use internal networking
    1300             (<computeroutput>intnet</computeroutput>), host-only
    1301             networking (<computeroutput>hostonly</computeroutput>), or
    1302             access rarely used sub-modes
    1303             (<computeroutput>generic</computeroutput>). These options
    1304             correspond to the modes described in
    1305             <xref linkend="networkingmodes" />.
    1306           </para>
    1307         </listitem>
    1308 
    1309         <listitem>
    1310           <para>
    1311             <computeroutput>--nictype&lt;1-N&gt;
    1312             Am79C970A|Am79C973|Am79C970|82540EM|82543GC|82545EM|virtio</computeroutput>:
    1313             Enables you to specify the networking hardware that
    1314             &product-name; presents to the guest for a specified VM
    1315             virtual network card. See <xref linkend="nichardware" />.
    1316           </para>
    1317         </listitem>
    1318 
    1319         <listitem>
    1320           <para>
    1321             <computeroutput>--cableconnected&lt;1-N&gt;
    1322             on|off</computeroutput>: Enables you to temporarily
    1323             disconnect a virtual network interface, as if a network
    1324             cable had been pulled from a real network card. This might
    1325             be useful, for example for resetting certain software
    1326             components in the VM.
    1327           </para>
    1328         </listitem>
    1329 
    1330         <listitem>
    1331           <para>
    1332             With the <computeroutput>nictrace</computeroutput> options,
    1333             you can optionally trace network traffic by dumping it to a
    1334             file, for debugging purposes.
    1335           </para>
    1336 
    1337           <para>
    1338             With <computeroutput>--nictrace&lt;1-N&gt;
    1339             on|off</computeroutput>, you can enable network tracing for
    1340             a particular virtual network card.
    1341           </para>
    1342 
    1343           <para>
    1344             If enabled, you must specify with
    1345             <computeroutput>--nictracefile&lt;1-N&gt;
    1346             &lt;filename&gt;</computeroutput> the absolute path of the
    1347             file the trace should be logged to.
    1348           </para>
    1349         </listitem>
    1350 
    1351         <listitem>
    1352           <para>
    1353             <computeroutput>--nicproperty&lt;1-N&gt;
    1354             &lt;paramname&gt;="paramvalue"</computeroutput>: This
    1355             option, in combination with
    1356             <computeroutput>nicgenericdrv</computeroutput> enables you
    1357             to pass parameters to rarely-used network backends.
    1358           </para>
    1359 
    1360           <para>
    1361             These parameters are backend engine-specific, and are
    1362             different between UDP Tunnel and the VDE backend drivers.
    1363             For examples, see <xref linkend="network_udp_tunnel" />.
    1364           </para>
    1365         </listitem>
    1366 
    1367         <listitem>
    1368           <para>
    1369             <computeroutput>--nicspeed&lt;1-N&gt;
    1370             &lt;kbps&gt;</computeroutput>: Only has an effect if generic
    1371             networking has been enabled for a particular virtual network
    1372             card. See the <computeroutput>--nic</computeroutput> option.
    1373             This mode enables access to rarely used networking
    1374             sub-modes, such as VDE network or UDP Tunnel. This option
    1375             specifies the throughput rate in KBps.
    1376           </para>
    1377         </listitem>
    1378 
    1379         <listitem>
    1380           <para>
    1381             <computeroutput>--nicbootprio&lt;1-N&gt;
    1382             &lt;priority&gt;</computeroutput>: Specifies the order in
    1383             which NICs are tried for booting over the network, using
    1384             PXE. The priority is an integer in the 0 to 4 range.
    1385             Priority 1 is the highest, priority 4 is low. Priority 0,
    1386             which is the default unless otherwise specified, is the
    1387             lowest.
    1388           </para>
    1389 
    1390           <para>
    1391             Note that this option only has an effect when the Intel PXE
    1392             boot ROM is used.
    1393           </para>
    1394         </listitem>
    1395 
    1396         <listitem>
    1397           <para>
    1398             <computeroutput>--nicpromisc&lt;1-N&gt;
    1399             deny|allow-vms|allow-all</computeroutput>: Enables you to
    1400             specify how promiscuous mode is handled for the specified VM
    1401             virtual network card. This setting is only relevant for
    1402             bridged networking. <computeroutput>deny</computeroutput>,
    1403             the default setting, hides any traffic not intended for the
    1404             VM. <computeroutput>allow-vms</computeroutput> hides all
    1405             host traffic from the VM, but allows the VM to see traffic
    1406             to and from other VMs.
    1407             <computeroutput>allow-all</computeroutput> removes this
    1408             restriction completely.
    1409           </para>
    1410         </listitem>
    1411 
    1412         <listitem>
    1413           <para>
    1414             <computeroutput>--nicbandwidthgroup&lt;1-N&gt;
    1415             none|&lt;name&gt;</computeroutput>: Adds and removes an
    1416             assignment of a bandwidth group for the specified virtual
    1417             network interface. Specifying
    1418             <computeroutput>none</computeroutput> removes any current
    1419             bandwidth group assignment from the specified virtual
    1420             network interface. Specifying
    1421             <computeroutput>&lt;name&gt;</computeroutput> adds an
    1422             assignment of a bandwidth group to the specified virtual
    1423             network interface.
    1424           </para>
    1425 
    1426           <para>
    1427             See <xref linkend="network_bandwidth_limit" />.
    1428           </para>
    1429         </listitem>
    1430 
    1431         <listitem>
    1432           <para>
    1433             <computeroutput>--bridgeadapter&lt;1-N&gt;
    1434             none|&lt;devicename&gt;</computeroutput>: Only has an effect
    1435             if bridged networking has been enabled for a virtual network
    1436             card. See the <computeroutput>--nic</computeroutput> option.
    1437             Use this option to specify which host interface the given
    1438             virtual network interface will use. See
    1439             <xref linkend="network_bridged" />.
    1440           </para>
    1441         </listitem>
    1442 
    1443         <listitem>
    1444           <para>
    1445             <computeroutput>--hostonlyadapter&lt;1-N&gt;
    1446             none|&lt;devicename&gt;</computeroutput>: Only has an effect
    1447             if host-only networking has been enabled for a virtual
    1448             network card. See the <computeroutput>--nic</computeroutput>
    1449             option. Use this option to specify which host-only
    1450             networking interface the given virtual network interface
    1451             will use. See <xref linkend="network_hostonly" />.
    1452           </para>
    1453         </listitem>
    1454 
    1455         <listitem>
    1456           <para>
    1457             <computeroutput>--intnet&lt;1-N&gt;
    1458             network</computeroutput>: Only has an effect if internal
    1459             networking has been enabled for a virtual network card. See
    1460             the <computeroutput>--nic</computeroutput> option. Use this
    1461             option to specify the name of the internal network. See
    1462             <xref linkend="network_internal" />.
    1463           </para>
    1464         </listitem>
    1465 
    1466         <listitem>
    1467           <para>
    1468             <computeroutput>--nat-network&lt;1-N&gt; &lt;network
    1469             name&gt;</computeroutput>: If the networking type is set to
    1470             <computeroutput>natnetwork</computeroutput>, not
    1471             <computeroutput>nat</computeroutput>, then this setting
    1472             specifies the name of the NAT network this adapter is
    1473             connected to. Optional.
    1474           </para>
    1475         </listitem>
    1476 
    1477         <listitem>
    1478           <para>
    1479             <computeroutput>--nicgenericdrv&lt;1-N&gt; &lt;backend
    1480             driver&gt;</computeroutput>: Only has an effect if generic
    1481             networking has been enabled for a virtual network card. See
    1482             the <computeroutput>--nic</computeroutput> option. This mode
    1483             enables you to access rarely used networking sub-modes, such
    1484             as VDE network or UDP Tunnel.
    1485           </para>
    1486         </listitem>
    1487 
    1488         <listitem>
    1489           <para>
    1490             <computeroutput>--macaddress&lt;1-N&gt;
    1491             auto|&lt;mac&gt;</computeroutput>: With this option you can
    1492             set the MAC address of a particular network adapter on the
    1493             VM. Normally, each network adapter is assigned a random
    1494             address by &product-name; at VM creation.
    1495           </para>
    1496         </listitem>
    1497 
    1498       </itemizedlist>
    1499 
    1500       <sect3 id="vboxmanage-modifyvm-networking-nat">
    1501 
    1502         <title>NAT Networking Settings</title>
    1503 
    1504         <para>
    1505           The following NAT networking settings are available through
    1506           <command>VBoxManage modifyvm</command>. With all these
    1507           settings, the decimal number directly following the option
    1508           name, 1-N in the list below, specifies the virtual network
    1509           adapter whose settings should be changed.
    1510         </para>
    1511 
    1512         <itemizedlist>
    1513 
    1514           <listitem>
    1515             <para>
    1516               <computeroutput>--natnet&lt;1-N&gt;
    1517               &lt;network&gt;|default</computeroutput>: If the
    1518               networking type is set to
    1519               <computeroutput>nat</computeroutput>, not
    1520               <computeroutput>natnetwork</computeroutput>, then this
    1521               setting specifies the IP address range to be used for this
    1522               network. See <xref linkend="changenat" />.
    1523             </para>
    1524           </listitem>
    1525 
    1526           <listitem>
    1527             <para>
    1528               <computeroutput>--natpf&lt;1-N&gt;
    1529               [&lt;name&gt;],tcp|udp,[&lt;hostip&gt;],&lt;hostport&gt;,[&lt;guestip&gt;],
    1530               &lt;guestport&gt;</computeroutput>: Defines a NAT
    1531               port-forwarding rule. See <xref linkend="natforward" />.
    1532             </para>
    1533           </listitem>
    1534 
    1535           <listitem>
    1536             <para>
    1537               <computeroutput>--natpf&lt;1-N&gt; delete
    1538               &lt;name&gt;</computeroutput>: Deletes a NAT
    1539               port-forwarding rule. See <xref linkend="natforward" />.
    1540             </para>
    1541           </listitem>
    1542 
    1543           <listitem>
    1544             <para>
    1545               <computeroutput>--nattftpprefix&lt;1-N&gt;
    1546               &lt;prefix&gt;</computeroutput>: Defines a prefix for the
    1547               built-in TFTP server. For example, where the boot file is
    1548               located. See <xref linkend="nat-tftp" /> and
    1549               <xref linkend="nat-adv-tftp" />.
    1550             </para>
    1551           </listitem>
    1552 
    1553           <listitem>
    1554             <para>
    1555               <computeroutput>--nattftpfile&lt;1-N&gt;
    1556               &lt;bootfile&gt;</computeroutput>: Defines the TFT boot
    1557               file. See <xref linkend="nat-adv-tftp" />.
    1558             </para>
    1559           </listitem>
    1560 
    1561           <listitem>
    1562             <para>
    1563               <computeroutput>--nattftpserver&lt;1-N&gt;
    1564               &lt;tftpserver&gt;</computeroutput>: Defines the TFTP
    1565               server address to boot from. See
    1566               <xref linkend="nat-adv-tftp" />.
    1567             </para>
    1568           </listitem>
    1569 
    1570           <listitem>
    1571             <para>
    1572               <computeroutput>--nattbindip&lt;1-N&gt;
    1573               &lt;ip;&gt;</computeroutput>: &product-name;'s NAT engine
    1574               normally routes TCP/IP packets through the default
    1575               interface assigned by the host's TCP/IP stack. Use this
    1576               setting to instruct the NAT engine to bind to a specified
    1577               IP address instead. See
    1578               <xref linkend="nat-adv-settings" />.
    1579             </para>
    1580           </listitem>
    1581 
    1582           <listitem>
    1583             <para>
    1584               <computeroutput>--natdnspassdomain&lt;1-N&gt;
    1585               on|off</computeroutput>: Specifies whether the built-in
    1586               DHCP server passes the domain name for network name
    1587               resolution.
    1588             </para>
    1589           </listitem>
    1590 
    1591           <listitem>
    1592             <para>
    1593               <computeroutput>--natdnsproxy&lt;1-N&gt;
    1594               on|off</computeroutput>: Makes the NAT engine proxy all
    1595               guest DNS requests to the host's DNS servers. See
    1596               <xref linkend="nat-adv-dns" />.
    1597             </para>
    1598           </listitem>
    1599 
    1600           <listitem>
    1601             <para>
    1602               <computeroutput>--natdnshostresolver&lt;1-N&gt;
    1603               on|off</computeroutput>: Makes the NAT engine use the
    1604               host's resolver mechanisms to handle DNS requests. See
    1605               <xref linkend="nat-adv-dns" />.
    1606             </para>
    1607           </listitem>
    1608 
    1609           <listitem>
    1610             <para>
    1611               <computeroutput>--natsettings&lt;1-N&gt;
    1612               [&lt;mtu&gt;],[&lt;socksnd&gt;],[&lt;sockrcv&gt;],[&lt;tcpsnd&gt;],
    1613               [&lt;tcprcv&gt;]</computeroutput>: Controls several NAT
    1614               settings. See <xref linkend="nat-adv-settings" />.
    1615             </para>
    1616           </listitem>
    1617 
    1618           <listitem>
    1619             <para>
    1620               <computeroutput>--nataliasmode&lt;1-N&gt;
    1621               default|[log],[proxyonly],[sameports]</computeroutput>:
    1622               Defines behaviour of the NAT engine core: log - enables
    1623               logging, proxyonly - switches off aliasing mode and makes
    1624               NAT transparent, sameports - enforces the NAT engine to
    1625               send packets through the same port as they originated on,
    1626               default - disable all aliasing modes. See
    1627               <xref linkend="nat-adv-alias" />.
    1628             </para>
    1629           </listitem>
    1630 
    1631         </itemizedlist>
    1632 
    1633       </sect3>
    1634 
    1635     </sect2>
    1636 
    1637     <sect2 id="vboxmanage-modifyvm-other">
    1638 
    1639       <title>Miscellaneous Settings</title>
    1640 
    1641       <para>
    1642         The following hardware settings, such as serial port, audio,
    1643         clipboard, drag and drop, monitor, and USB settings are
    1644         available through <command>VBoxManage modifyvm</command>:
    1645       </para>
    1646 
    1647       <itemizedlist>
    1648 
    1649         <listitem>
    1650           <para>
    1651             <computeroutput>--mouse
    1652             &lt;ps2|usb|usbtablet|usbmultitouch&gt;</computeroutput>:
    1653             Specifies the mode of the mouse to be used in the VM.
    1654             Available options are: ps2, usb, usbtablet, usbmultitouch.
    1655           </para>
    1656         </listitem>
    1657 
    1658         <listitem>
    1659           <para>
    1660             <computeroutput>--keyboard &lt;ps2|usb&gt;</computeroutput>:
    1661             Specifies the mode of the keyboard to be used in the VM.
    1662             Available options are: ps2, usb.
    1663           </para>
    1664         </listitem>
    1665 
    1666         <listitem>
    1667           <para>
    1668             <computeroutput>--uart&lt;1-N&gt; off|&lt;I/O base&gt;
    1669             &lt;IRQ&gt;</computeroutput>: Configures virtual serial
    1670             ports for the VM. See <xref linkend="serialports" />.
    1671           </para>
    1672         </listitem>
    1673 
    1674         <listitem>
    1675           <para>
    1676             <computeroutput>--uartmode&lt;1-N&gt;
    1677             &lt;arg&gt;</computeroutput>: Controls how &product-name;
    1678             connects a given virtual serial port, configured with the
    1679             <computeroutput>--uartX</computeroutput> setting, to the
    1680             host on which the virtual machine is running. As described
    1681             in <xref linkend="serialports" />, for each such port, you
    1682             can specify <computeroutput>&lt;arg&gt;</computeroutput> as
    1683             one of the following options:
    1684           </para>
    1685 
    1686           <itemizedlist>
    1687 
    1688             <listitem>
    1689               <para>
    1690                 <computeroutput>disconnected</computeroutput>: Even
    1691                 though the serial port is shown to the guest, it has no
    1692                 "other end". This is like a real COM port without a
    1693                 cable.
    1694               </para>
    1695             </listitem>
    1696 
    1697             <listitem>
    1698               <para>
    1699                 <computeroutput>server
    1700                 &lt;pipename&gt;</computeroutput>: On a Windows host,
    1701                 this tells &product-name; to create a named pipe on the
    1702                 host named
    1703                 <computeroutput>&lt;pipename&gt;</computeroutput> and
    1704                 connect the virtual serial device to it. Note that
    1705                 Windows requires that the name of a named pipe begins
    1706                 with <filename>\\.\pipe\</filename>.
    1707               </para>
    1708 
    1709               <para>
    1710                 On a Linux host, instead of a named pipe, a local domain
    1711                 socket is used.
    1712               </para>
    1713             </listitem>
    1714 
    1715             <listitem>
    1716               <para>
    1717                 <computeroutput>client
    1718                 &lt;pipename&gt;</computeroutput>: Operates as for
    1719                 <computeroutput>server</computeroutput>, except that the
    1720                 pipe, or local domain socket, is not created by
    1721                 &product-name; but is assumed to exist already.
    1722               </para>
    1723             </listitem>
    1724 
    1725             <listitem>
    1726               <para>
    1727                 <computeroutput>tcpserver &lt;port&gt;</computeroutput>:
    1728                 Configures &product-name; to create a TCP socket on the
    1729                 host with TCP
    1730                 <computeroutput>&lt;port&gt;</computeroutput> and
    1731                 connect the virtual serial device to it. Note that
    1732                 UNIX-like systems require ports over 1024 for normal
    1733                 users.
    1734               </para>
    1735             </listitem>
    1736 
    1737             <listitem>
    1738               <para>
    1739                 <computeroutput>tcpclient
    1740                 &lt;hostname:port&gt;</computeroutput>: Operates as for
    1741                 <computeroutput>tcpserver</computeroutput>, except that
    1742                 the TCP socket is not created by &product-name;, but is
    1743                 assumed to exist already.
    1744               </para>
    1745             </listitem>
    1746 
    1747             <listitem>
    1748               <para>
    1749                 <computeroutput>file &lt;file&gt;</computeroutput>:
    1750                 Redirects the serial port output to a raw file
    1751                 &lt;file&gt; specified by its absolute path on the host
    1752                 file system.
    1753               </para>
    1754             </listitem>
    1755 
    1756             <listitem>
    1757               <para>
    1758                 <computeroutput>&lt;devicename&gt;</computeroutput>: If,
    1759                 instead of the above options, the device name of a
    1760                 physical hardware serial port of the host is specified,
    1761                 the virtual serial port is connected to that hardware
    1762                 port. On a Windows host, the device name will be a COM
    1763                 port such as <computeroutput>COM1</computeroutput>. On a
    1764                 Linux host, the device name will be
    1765                 <filename>/dev/ttyS0</filename> or similar. This enables
    1766                 you to wire up a real serial port to a virtual machine.
    1767               </para>
    1768             </listitem>
    1769 
    1770           </itemizedlist>
    1771         </listitem>
    1772 
    1773         <listitem>
    1774           <para>
    1775             <computeroutput>uarttype &lt;1-N&gt;
    1776             16450|16550A|16750</computeroutput>: Configures the UART
    1777             type for a virtual serial port. The default UART type is
    1778             16550A.
    1779           </para>
    1780         </listitem>
    1781 
    1782         <listitem>
    1783           <para>
    1784             <computeroutput>--lptmode&lt;1-N&gt;
    1785             &lt;Device&gt;</computeroutput>: Specifies the Device Name
    1786             of the parallel port that the Parallel Port feature will be
    1787             using. Use this <emphasis>before</emphasis>
    1788             <computeroutput>--lpt</computeroutput>. This feature depends
    1789             on the host operating system. For Windows hosts, use a
    1790             device name such as lpt1. On Linux hosts, use a device name
    1791             such as /dev/lp0.
    1792           </para>
    1793         </listitem>
    1794 
    1795         <listitem>
    1796           <para>
    1797             <computeroutput>--lpt&lt;1-N&gt; &lt;I/O base&gt;
    1798             &lt;IRQ&gt;</computeroutput>: Specifies the I/O address of
    1799             the parallel port and the IRQ number that the Parallel Port
    1800             feature will be using. Optional. Use this
    1801             <emphasis>after</emphasis>
    1802             <computeroutput>--lptmod</computeroutput>. I/O base address
    1803             and IRQ are the values that guest sees. For example, the
    1804             values avalable under guest Device Manager.
    1805           </para>
    1806         </listitem>
    1807 
    1808         <listitem>
    1809           <para>
    1810             <computeroutput>--audio
    1811             none|null|dsound|oss|alsa|pulse|coreaudio</computeroutput>:
    1812             Specifies whether the VM should have audio support, and if
    1813             so, which type. The list of supported audio types depends on
    1814             the host and can be determined with <command>VBoxManage
    1815             modifyvm</command>.
    1816           </para>
    1817         </listitem>
    1818 
    1819         <listitem>
    1820           <para>
    1821             <computeroutput>--audiocontroller
    1822             ac97|hda|sb16</computeroutput>: Specifies the audio
    1823             controller to be used with the VM.
    1824           </para>
    1825         </listitem>
    1826 
    1827         <listitem>
    1828           <para>
    1829             <computeroutput>--audiocodec
    1830             stac9700|ad1980|stac9221|sb16</computeroutput>: Specifies
    1831             the audio codec to be used with the VM.
    1832           </para>
    1833         </listitem>
    1834 
    1835         <listitem>
    1836           <para>
    1837             <computeroutput>--audioin on</computeroutput>: Specifies
    1838             whether capturing audio from the host is enabled or
    1839             disabled.
    1840           </para>
    1841         </listitem>
    1842 
    1843         <listitem>
    1844           <para>
    1845             <computeroutput>--audioout on</computeroutput>: Specifies
    1846             whether audio playback from the guest is enabled or
    1847             disabled.
    1848           </para>
    1849         </listitem>
    1850 
    1851         <listitem>
    1852           <para>
    1853             <computeroutput>--clipboard-mode
    1854             disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
    1855             Configues how the guest or host operating system's clipboard
    1856             should be shared with the host or guest. See
    1857             <xref linkend="generalsettings" />. This setting requires
    1858             that the Guest Additions be installed in the virtual
    1859             machine.
    1860           </para>
    1861         </listitem>
    1862 
    1863         <listitem>
    1864           <para>
    1865             <computeroutput>--clipboard-file-transfers
    1866             enabled|disabled</computeroutput>: Specifies if clipboard
    1867             file transfers are allowed between host and guest OSes or
    1868             not.
    1869           </para>
    1870         </listitem>
    1871 
    1872         <listitem>
    1873           <para>
    1874             <computeroutput>--draganddrop
    1875             disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
    1876             Specifies the drag and drop mode to use between the host and
    1877             the virtual machine. See <xref linkend="guestadd-dnd" />.
    1878             This requires that the Guest Additions be installed in the
    1879             virtual machine.
    1880           </para>
    1881         </listitem>
    1882 
    1883         <listitem>
    1884           <para>
    1885             <computeroutput>--monitorcount
    1886             &lt;count&gt;</computeroutput>: Enables multi-monitor
    1887             support. See <xref linkend="settings-display" />.
    1888           </para>
    1889         </listitem>
    1890 
    1891         <listitem>
    1892           <para>
    1893             <computeroutput>--usb on|off</computeroutput>: Enables and
    1894             disables the VM's virtual USB controller. See
    1895             <xref linkend="settings-usb" />.
    1896           </para>
    1897         </listitem>
    1898 
    1899         <listitem>
    1900           <para>
    1901             <computeroutput>--usbehci on|off</computeroutput>: Enables
    1902             and disables the VM's virtual USB 2.0 controller. See
    1903             <xref linkend="settings-usb" />.
    1904           </para>
    1905         </listitem>
    1906 
    1907         <listitem>
    1908           <para>
    1909             <computeroutput>--usbxhci on|off</computeroutput>: Enables
    1910             and disables the VM's virtual USB 3.0 controller. See
    1911             <xref linkend="settings-usb" />.
    1912           </para>
    1913         </listitem>
    1914 
    1915         <listitem>
    1916           <para>
    1917             <computeroutput>--usbrename &lt;oldname&gt;
    1918             &lt;newname&gt;</computeroutput>: Enables renaming of the
    1919             VM's virtual USB controller from &lt;oldname&gt; to
    1920             &lt;newname&gt;.
    1921           </para>
    1922         </listitem>
    1923 
    1924       </itemizedlist>
    1925 
    1926     </sect2>
    1927 
    1928     <sect2 id="vboxmanage-modifyvm-recording">
    1929 
    1930       <title>Recording Settings</title>
    1931 
    1932       <para>
    1933         The <command>VBoxManage modifyvm</command> command enables you
    1934         to modify recording settings for video recording, audio
    1935         recording, or both.
    1936       </para>
    1937 
    1938       <para>
    1939         Use the following options to update the recording settings:
    1940       </para>
    1941 
    1942       <itemizedlist>
    1943 
    1944         <listitem>
    1945           <para>
    1946             <option>--recording on|off</option> enables or disables the
    1947             recording of a VM session into a WebM/VP8 file. When this
    1948             option value is <computeroutput>on</computeroutput>,
    1949             recording begins when the VM session starts.
    1950           </para>
    1951         </listitem>
    1952 
    1953         <listitem>
    1954           <para>
    1955             <option>--recordingscreens
    1956             all|<replaceable>screen-ID</replaceable>
    1957             [<replaceable>screen-ID</replaceable> ...]</option> enables
    1958             you to specify which VM screens to record. The recording for
    1959             each screen that you specify is saved to its own file.
    1960           </para>
    1961         </listitem>
    1962 
    1963         <listitem>
    1964           <para>
    1965             <option>--recordingfile
    1966             <replaceable>filename</replaceable></option> specifies the
    1967             file in which to save the recording.
    1968           </para>
    1969         </listitem>
    1970 
    1971         <listitem>
    1972           <para>
    1973             <option>--recordingmaxsize
    1974             <replaceable>MB</replaceable></option> specifies the maximum
    1975             size of the recorded video file in megabytes. The recording
    1976             stops when the file reaches the specified size. If this
    1977             value is zero, the recording continues until you stop the
    1978             recording.
    1979           </para>
    1980         </listitem>
    1981 
    1982         <listitem>
    1983           <para>
    1984             <option>--recordingmaxtime
    1985             <replaceable>seconds</replaceable></option> specifies the
    1986             maximum amount time to record in seconds. The recording
    1987             stops after the specified number of seconds elapses. If this
    1988             value is zero, the recording continues until you stop the
    1989             recording.
    1990           </para>
    1991         </listitem>
    1992 
    1993         <listitem>
    1994           <para>
    1995             <option>--recordingopts
    1996             <replaceable>keyword</replaceable>=<replaceable>value</replaceable>[,<replaceable>keyword</replaceable>=<replaceable>value</replaceable>
    1997             ...]</option> specifies additional video-recording options
    1998             in a comma-separated keyword-value format. For example,
    1999             <computeroutput>foo=bar,a=b</computeroutput>.
    2000           </para>
    2001 
    2002           <para>
    2003             Only use this option only if you are an advanced user. For
    2004             information about keywords, see <emphasis>Oracle VM
    2005             VirtualBox Programming Guide and Reference</emphasis>.
    2006           </para>
    2007         </listitem>
    2008 
    2009         <listitem>
    2010           <para>
    2011             <option>--recordingvideofps
    2012             <replaceable>fps</replaceable></option> specifies the
    2013             maximum number of video frames per second (FPS) to record.
    2014             Frames that have a higher frequency are skipped. Increasing
    2015             this value reduces the number of skipped frames and
    2016             increases the file size.
    2017           </para>
    2018         </listitem>
    2019 
    2020         <listitem>
    2021           <para>
    2022             <option>--recordingvideorate
    2023             <replaceable>bit-rate</replaceable></option> specifies the
    2024             bit rate of the video in kilobits per second. Increasing
    2025             this value improves the appearance of the video at the cost
    2026             of an increased file size.
    2027           </para>
    2028         </listitem>
    2029 
    2030         <listitem>
    2031           <para>
    2032             <option>--recordingvideores
    2033             <replaceable>width</replaceable>x<replaceable>height</replaceable></option>
    2034             specifies the video resolution of the recorded video in
    2035             pixels.
    2036           </para>
    2037         </listitem>
    2038 
    2039       </itemizedlist>
    2040 
    2041     </sect2>
    2042 
    2043     <sect2 id="vboxmanage-modifyvm-vrde">
    2044 
    2045       <title>Remote Machine Settings</title>
    2046 
    2047       <para>
    2048         The following settings that affect remote machine behavior are
    2049         available through <command>VBoxManage modifyvm</command>:
    2050       </para>
    2051 
    2052       <itemizedlist>
    2053 
    2054         <listitem>
    2055           <para>
    2056             <computeroutput>--vrde on|off</computeroutput>: Enables and
    2057             disables the VirtualBox Remote Desktop Extension (VRDE)
    2058             server.
    2059           </para>
    2060         </listitem>
    2061 
    2062         <listitem>
    2063           <para>
    2064             <computeroutput>--vrdeproperty
    2065             "TCP/Ports|Address=&lt;value&gt;"</computeroutput>: Sets the
    2066             port numbers and IP address on the VM that the VRDE server
    2067             can bind to.
    2068           </para>
    2069 
    2070           <itemizedlist>
    2071 
    2072             <listitem>
    2073               <para>
    2074                 For TCP/Ports, &lt;value&gt; should be a port or a range
    2075                 of ports that the VRDE server can bind to.
    2076                 <computeroutput>default</computeroutput> or
    2077                 <computeroutput>0</computeroutput> means port 3389, the
    2078                 standard port for RDP. See the description for the
    2079                 <computeroutput>--vrdeport</computeroutput> option in
    2080                 <xref linkend="vboxmanage-modifyvm-vrde" />.
    2081               </para>
    2082             </listitem>
    2083 
    2084             <listitem>
    2085               <para>
    2086                 For TCP/Address, &lt;value&gt; should be the IP address
    2087                 of the host network interface that the VRDE server will
    2088                 bind to. If specified, the server will accept
    2089                 connections only on the specified host network
    2090                 interface. See the description for the
    2091                 <computeroutput>--vrdeaddress</computeroutput> option in
    2092                 <xref linkend="vboxmanage-modifyvm-vrde" />.
    2093               </para>
    2094             </listitem>
    2095 
    2096           </itemizedlist>
    2097         </listitem>
    2098 
    2099         <listitem>
    2100           <para>
    2101             <computeroutput>--vrdeproperty
    2102             "VideoChannel/Enabled|Quality|DownscaleProtection=&lt;value&gt;"</computeroutput>:
    2103             Sets the VRDP video redirection properties.
    2104           </para>
    2105 
    2106           <itemizedlist>
    2107 
    2108             <listitem>
    2109               <para>
    2110                 For VideoChannel/Enabled, &lt;value&gt; can be set to
    2111                 "1", switching the VRDP video channel on. See
    2112                 <xref linkend="vrde-videochannel" />.
    2113               </para>
    2114             </listitem>
    2115 
    2116             <listitem>
    2117               <para>
    2118                 For VideoChannel/Quality, &lt;value&gt; should be set
    2119                 between 10 and 100% inclusive, representing a JPEG
    2120                 compression level on the VRDE server video channel.
    2121                 Lower values mean lower quality but higher compression.
    2122                 See <xref linkend="vrde-videochannel" />.
    2123               </para>
    2124             </listitem>
    2125 
    2126             <listitem>
    2127               <para>
    2128                 For VideoChannel/DownscaleProtection, &lt;value&gt; can
    2129                 be set to "1" to enable the videochannel downscale
    2130                 protection feature. When enabled, if a video's size
    2131                 equals the shadow buffer size, then it is regarded as a
    2132                 full screen video, and is displayed. But if its size is
    2133                 between fullscreen and the downscale threshold then it
    2134                 is <emphasis>not</emphasis> displayed, as it could be an
    2135                 application window, which would be unreadable when
    2136                 downscaled. When the downscale protection feature is
    2137                 disabled, an attempt is always made to display videos.
    2138               </para>
    2139             </listitem>
    2140 
    2141           </itemizedlist>
    2142         </listitem>
    2143 
    2144         <listitem>
    2145           <para>
    2146             <computeroutput>--vrdeproperty
    2147             "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1"</computeroutput>:
    2148             Disables one of the VRDE server features: Display, Input,
    2149             Audio or USB respectively. To reenable a feature, use
    2150             "Client/DisableDisplay=" for example. See
    2151             <xref linkend="vrde-customization" />.
    2152           </para>
    2153         </listitem>
    2154 
    2155         <listitem>
    2156           <para>
    2157             <computeroutput>--vrdeproperty
    2158             "Client/DisableClipboard|DisableUpstreamAudio=1"</computeroutput>:
    2159             Disables one of the VRDE server features: Clipboard or
    2160             UpstreamAudio respectively. To reenable a feature, use
    2161             "Client/DisableClipboard=" for example. See
    2162             <xref linkend="vrde-customization" />.
    2163           </para>
    2164         </listitem>
    2165 
    2166         <listitem>
    2167           <para>
    2168             <computeroutput>--vrdeproperty
    2169             "Client/DisableRDPDR=1"</computeroutput>: Disables the VRDE
    2170             server feature: RDP device redirection for smart cards. To
    2171             reenable this feature, use "Client/DisableRDPR=".
    2172           </para>
    2173         </listitem>
    2174 
    2175         <listitem>
    2176           <para>
    2177             <computeroutput>--vrdeproperty
    2178             "H3DRedirect/Enabled=1"</computeroutput>: Enables the VRDE
    2179             server feature: 3D redirection. To disable this feature, use
    2180             "H3DRedirect/Enabled=".
    2181           </para>
    2182         </listitem>
    2183 
    2184         <listitem>
    2185           <para>
    2186             <computeroutput>--vrdeproperty
    2187             "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=&lt;value&gt;"</computeroutput>:
    2188             Sets the desired security method and path of server
    2189             certificate, path of server private key, path of CA
    2190             certificate, that are used for a connection.
    2191           </para>
    2192 
    2193           <itemizedlist>
    2194 
    2195             <listitem>
    2196               <para>
    2197                 <computeroutput>--vrdeproperty
    2198                 "Security/Method=&lt;value&gt;"</computeroutput> sets
    2199                 the desired security method, which is used for a
    2200                 connection. Valid values are:
    2201               </para>
    2202 
    2203               <itemizedlist>
    2204 
    2205                 <listitem>
    2206                   <para>
    2207                     <computeroutput>Negotiate</computeroutput>: Both
    2208                     Enhanced (TLS) and Standard RDP Security connections
    2209                     are allowed. The security method is negotiated with
    2210                     the client. This is the default setting.
    2211                   </para>
    2212                 </listitem>
    2213 
    2214                 <listitem>
    2215                   <para>
    2216                     <computeroutput>RDP</computeroutput>: Only Standard
    2217                     RDP Security is accepted.
    2218                   </para>
    2219                 </listitem>
    2220 
    2221                 <listitem>
    2222                   <para>
    2223                     <computeroutput>TLS</computeroutput>: Only Enhanced
    2224                     RDP Security is accepted. The client must support
    2225                     TLS.
    2226                   </para>
    2227                 </listitem>
    2228 
    2229               </itemizedlist>
    2230 
    2231               <para>
    2232                 See <xref linkend="vrde-crypt" />.
    2233               </para>
    2234             </listitem>
    2235 
    2236             <listitem>
    2237               <para>
    2238                 <computeroutput>--vrdeproperty
    2239                 "Security/ServerCertificate=&lt;value&gt;"</computeroutput>
    2240                 where &lt;value&gt; is the absolute path of the server
    2241                 certificate. See <xref linkend="vrde-crypt" />.
    2242               </para>
    2243             </listitem>
    2244 
    2245             <listitem>
    2246               <para>
    2247                 <computeroutput>--vrdeproperty
    2248                 "Security/ServerPrivateKey=&lt;value&gt;"</computeroutput>
    2249                 where &lt;value&gt; is the absolute path of the server
    2250                 private key. See <xref linkend="vrde-crypt" />.
    2251               </para>
    2252             </listitem>
    2253 
    2254             <listitem>
    2255               <para>
    2256                 <computeroutput>--vrdeproperty
    2257                 "Security/CACertificate=&lt;value&gt;"</computeroutput>
    2258                 where &lt;value&gt; is the absolute path of the CA self
    2259                 signed certificate. See <xref linkend="vrde-crypt" />.
    2260               </para>
    2261             </listitem>
    2262 
    2263           </itemizedlist>
    2264         </listitem>
    2265 
    2266         <listitem>
    2267           <para>
    2268             <computeroutput>--vrdeproperty
    2269             "Audio/RateCorrectionMode|LogPath=&lt;value&gt;"</computeroutput>
    2270             sets the audio connection mode, or path of the audio
    2271             logfile.
    2272           </para>
    2273 
    2274           <itemizedlist>
    2275 
    2276             <listitem>
    2277               <para>
    2278                 <computeroutput>--vrdeproperty
    2279                 "Audio/RateCorrectionMode=&lt;value&gt;"</computeroutput>
    2280                 where &lt;value&gt; is the desired rate correction mode.
    2281                 Allowed values are:
    2282               </para>
    2283 
    2284               <itemizedlist>
    2285 
    2286                 <listitem>
    2287                   <para>
    2288                     <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput>:
    2289                     No mode specified, use to unset any Audio mode
    2290                     already set.
    2291                   </para>
    2292                 </listitem>
    2293 
    2294                 <listitem>
    2295                   <para>
    2296                     <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput>:
    2297                     Rate correction mode.
    2298                   </para>
    2299                 </listitem>
    2300 
    2301                 <listitem>
    2302                   <para>
    2303                     <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput>:
    2304                     Low pass filter mode.
    2305                   </para>
    2306                 </listitem>
    2307 
    2308                 <listitem>
    2309                   <para>
    2310                     <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput>:
    2311                     Client sync mode to prevent underflow or overflow of
    2312                     the client queue.
    2313                   </para>
    2314                 </listitem>
    2315 
    2316               </itemizedlist>
    2317             </listitem>
    2318 
    2319             <listitem>
    2320               <para>
    2321                 <computeroutput>--vrdeproperty
    2322                 "Audio/LogPath=&lt;value&gt;"</computeroutput> where
    2323                 &lt;value&gt; is the absolute path of the Audio log
    2324                 file.
    2325               </para>
    2326             </listitem>
    2327 
    2328           </itemizedlist>
    2329         </listitem>
    2330 
    2331         <listitem>
    2332           <para>
    2333             <computeroutput>--vrdeextpack
    2334             default|&lt;name&gt;</computeroutput>: Specifies the library
    2335             to use for accessing the VM remotely. The default is to use
    2336             the RDP code which is part of the &product-name; Extension
    2337             Pack.
    2338           </para>
    2339         </listitem>
    2340 
    2341         <listitem>
    2342           <para>
    2343             <computeroutput>--vrdeport
    2344             default|&lt;ports&gt;</computeroutput>: A port or a range of
    2345             ports the VRDE server can bind to.
    2346             <computeroutput>default</computeroutput> or
    2347             <computeroutput>0</computeroutput> means port 3389, the
    2348             standard port for RDP. You can specify a comma-separated
    2349             list of ports or ranges of ports. Use a dash between two
    2350             port numbers to specify a range. The VRDE server will bind
    2351             to <emphasis>one</emphasis> of the available ports from the
    2352             specified list. Only one machine can use a given port at a
    2353             time. For example, the option <computeroutput> --vrdeport
    2354             5000,5010-5012</computeroutput> will tell the server to bind
    2355             to one of following ports: 5000, 5010, 5011, or 5012.
    2356           </para>
    2357         </listitem>
    2358 
    2359         <listitem>
    2360           <para>
    2361             <computeroutput>--vrdeaddress &lt;IP
    2362             address&gt;</computeroutput>: The IP address of the host
    2363             network interface the VRDE server will bind to. If
    2364             specified, the server will accept connections only on the
    2365             specified host network interface.
    2366           </para>
    2367 
    2368           <para>
    2369             The setting can be used to specify whether the VRDP server
    2370             should accept either IPv4, IPv6, or both connections:
    2371           </para>
    2372 
    2373           <itemizedlist>
    2374 
    2375             <listitem>
    2376               <para>
    2377                 Only IPv4: <computeroutput>--vrdeaddress
    2378                 "0.0.0.0"</computeroutput>
    2379               </para>
    2380             </listitem>
    2381 
    2382             <listitem>
    2383               <para>
    2384                 Only IPv6: <computeroutput>--vrdeaddress
    2385                 "::"</computeroutput>
    2386               </para>
    2387             </listitem>
    2388 
    2389             <listitem>
    2390               <para>
    2391                 Both IPv6 and IPv4: <computeroutput>--vrdeaddress
    2392                 ""</computeroutput>
    2393               </para>
    2394 
    2395               <para>
    2396                 This is the default setting.
    2397               </para>
    2398             </listitem>
    2399 
    2400           </itemizedlist>
    2401         </listitem>
    2402 
    2403         <listitem>
    2404           <para>
    2405             <computeroutput>--vrdeauthtype
    2406             null|external|guest</computeroutput>: Enables you to
    2407             indicate use of authorization, and specify how authorization
    2408             will be performed. See <xref linkend="vbox-auth" />.
    2409           </para>
    2410         </listitem>
    2411 
    2412         <listitem>
    2413           <para>
    2414             <computeroutput>--vrdeauthlibrary
    2415             default|&lt;name&gt;</computeroutput>: Specifies the library
    2416             used for RDP authentication. See
    2417             <xref linkend="vbox-auth" />.
    2418           </para>
    2419         </listitem>
    2420 
    2421         <listitem>
    2422           <para>
    2423             <computeroutput>--vrdemulticon on|off</computeroutput>:
    2424             Enables multiple connections to be made to the same VRDE
    2425             server, if the server supports this feature. See
    2426             <xref linkend="vrde-multiconnection" />.
    2427           </para>
    2428         </listitem>
    2429 
    2430         <listitem>
    2431           <para>
    2432             <computeroutput>--vrdereusecon on|off</computeroutput>: This
    2433             specifies the VRDE server behavior when multiple connections
    2434             are disabled. When this option is enabled, the server will
    2435             allow a new client to connect and will drop the existing
    2436             connection. When this option is disabled, the default
    2437             setting, a new connection will not be accepted if there is
    2438             already a client connected to the server.
    2439           </para>
    2440         </listitem>
    2441 
    2442         <listitem>
    2443           <para>
    2444             <computeroutput>--vrdevideochannel on|off</computeroutput>:
    2445             Enables video redirection, if it is supported by the VRDE
    2446             server. See <xref linkend="vrde-videochannel" />.
    2447           </para>
    2448         </listitem>
    2449 
    2450         <listitem>
    2451           <para>
    2452             <computeroutput>--vrdevideochannelquality
    2453             &lt;percent&gt;</computeroutput>: Specifies the image
    2454             quality for video redirection. See
    2455             <xref linkend="vrde-videochannel" />.
    2456           </para>
    2457         </listitem>
    2458 
    2459       </itemizedlist>
    2460 
    2461     </sect2>
    2462 
    2463     <sect2 id="vboxmanage-modifyvm-teleport">
    2464 
    2465       <title>Teleporting Settings</title>
    2466 
    2467       <para>
    2468         With the following commands for <command>VBoxManage
    2469         modifyvm</command> you can configure a machine to be a target
    2470         for teleporting. See <xref linkend="teleporting" />.
    2471       </para>
    2472 
    2473       <itemizedlist>
    2474 
    2475         <listitem>
    2476           <para>
    2477             <computeroutput>--teleporter on|off</computeroutput>:
    2478             Enables and disables the teleporter feature whereby when the
    2479             machine is started, it waits to receive a teleporting
    2480             request from the network instead of booting normally.
    2481             Teleporting requests are received on the port and address
    2482             specified using the following parameters.
    2483           </para>
    2484         </listitem>
    2485 
    2486         <listitem>
    2487           <para>
    2488             <computeroutput>--teleporterport
    2489             &lt;port&gt;</computeroutput>,
    2490             <computeroutput>--teleporteraddress
    2491             &lt;address&gt;</computeroutput>: These settings must be
    2492             used with <computeroutput>--teleporter</computeroutput>.
    2493             They specify the port and address the virtual machine should
    2494             listen to in order to receive a teleporting request sent
    2495             from another virtual machine.
    2496             <computeroutput>&lt;port&gt;</computeroutput> can be any
    2497             free TCP/IP port number, such as 6000.
    2498             <computeroutput>&lt;address&gt;</computeroutput> can be any
    2499             IP address or hostname and specifies the TCP/IP socket to
    2500             bind to. The default is 0.0.0.0, which means any address.
    2501           </para>
    2502         </listitem>
    2503 
    2504         <listitem>
    2505           <para>
    2506             <computeroutput>--teleporterpassword
    2507             &lt;password&gt;</computeroutput>: If this optional setting
    2508             is used, then the teleporting request will only succeed if
    2509             the source machine specifies the same password as the one
    2510             given with this command.
    2511           </para>
    2512         </listitem>
    2513 
    2514         <listitem>
    2515           <para>
    2516             <computeroutput>--teleporterpasswordfile
    2517             &lt;password&gt;</computeroutput>: If this optional setting
    2518             is used, then the teleporting request will only succeed if
    2519             the source machine specifies the same password as the one
    2520             specified in the file give with this command. Use
    2521             <computeroutput>stdin</computeroutput> to read the password
    2522             from stdin.
    2523           </para>
    2524         </listitem>
    2525 
    2526         <listitem>
    2527           <para>
    2528             <computeroutput>--cpuid &lt;leaf&gt; &lt;eax&gt; &lt;ebx&gt;
    2529             &lt;ecx&gt; &lt;edx&gt;</computeroutput>: Advanced users can
    2530             use this setting before a teleporting operation, to restrict
    2531             the virtual CPU capabilities that &product-name; presents to
    2532             the guest operating system. This must be run on both the
    2533             source and the target machines involved in the teleporting
    2534             and will then modify what the guest sees when it executes
    2535             the <computeroutput>CPUID</computeroutput> machine
    2536             instruction. This might help with misbehaving applications
    2537             that wrongly assume that certain CPU capabilities are
    2538             present. The meaning of the parameters is hardware
    2539             dependent, refer to the AMD or Intel processor
    2540             documentation.
    2541           </para>
    2542         </listitem>
    2543 
    2544       </itemizedlist>
    2545 
    2546     </sect2>
    2547 
    2548     <sect2 id="vboxmanage-modifyvm-debugging">
    2549 
    2550       <title>Debugging Settings</title>
    2551 
    2552       <para>
    2553         The following settings are only relevant for low-level VM
    2554         debugging. Regular users will never need these settings.
    2555       </para>
    2556 
    2557       <itemizedlist>
    2558 
    2559         <listitem>
    2560           <para>
    2561             <computeroutput>--tracing-enabled on|off</computeroutput>:
    2562             Enables the tracebuffer. This consumes some memory for the
    2563             tracebuffer and adds extra overhead.
    2564           </para>
    2565         </listitem>
    2566 
    2567         <listitem>
    2568           <para>
    2569             <computeroutput>--tracing-config
    2570             &lt;config-string&gt;</computeroutput>: Enables tracing
    2571             configuration. In particular, this defines which group of
    2572             tracepoints are enabled.
    2573           </para>
    2574         </listitem>
    2575 
    2576         <listitem>
    2577           <para>
    2578             <computeroutput>--tracing-allow-vm-access
    2579             on|off</computeroutput>: Enables and disables VM access to
    2580             the tracebuffer. By default, this setting is disabled.
    2581           </para>
    2582         </listitem>
    2583 
    2584       </itemizedlist>
    2585 
    2586     </sect2>
    2587 
    2588     <sect2 id="vboxmanage-usbcardreader">
    2589 
    2590       <title>USB Card Reader Settings</title>
    2591 
    2592       <para>
    2593         The following setting defines access to a USB Card Reader by the
    2594         guest environment. USB card readers are typically used for
    2595         accessing data on memory cards such as CompactFlash (CF), Secure
    2596         Digital (SD), or MultiMediaCard (MMC).
    2597       </para>
    2598 
    2599       <itemizedlist>
    2600 
    2601         <listitem>
    2602           <para>
    2603             <computeroutput>--usbcardreader on|off</computeroutput>:
    2604             Enables and disables the USB card reader interface.
    2605           </para>
    2606         </listitem>
    2607 
    2608       </itemizedlist>
    2609 
    2610     </sect2>
    2611 
    2612     <sect2 id="vboxmanage-autostart">
    2613 
    2614       <title>Autostarting VMs During Host System Boot</title>
    2615 
    2616       <para>
    2617         These settings configure the VM autostart feature, which
    2618         automatically starts the VM at host system boot-up. Note that
    2619         there are prerequisites that need to be addressed before using
    2620         this feature. See <xref linkend="autostart" />.
    2621       </para>
    2622 
    2623       <itemizedlist>
    2624 
    2625         <listitem>
    2626           <para>
    2627             <computeroutput>--autostart-enabled on|off</computeroutput>:
    2628             Enables and disables VM autostart at host system boot-up,
    2629             using the specified user name.
    2630           </para>
    2631         </listitem>
    2632 
    2633         <listitem>
    2634           <para>
    2635             <computeroutput>--autostart-delay
    2636             &lt;seconds&gt;</computeroutput>: Specifies a delay, in
    2637             seconds, following host system boot-up, before the VM
    2638             autostarts.
    2639           </para>
    2640         </listitem>
    2641 
    2642       </itemizedlist>
    2643 
    2644     </sect2>
    2645 
    2646   </sect1>
    2647 
    2648   <sect1 id="vboxmanage-movevm">
    2649 
    2650     <title>VBoxManage movevm</title>
    2651 
    2652     <para>
    2653       This command moves a virtual machine to a new location on the
    2654       host.
    2655     </para>
    2656 
    2657     <para>
    2658       Associated files of the virtual machine, such as settings files
    2659       and disk image files, are moved to the new location. The
    2660       &product-name; configuration is updated automatically.
    2661     </para>
    2662 
    2663     <para>
    2664       The <command>movevm</command> subcommand requires the name of the
    2665       virtual machine which should be moved.
    2666     </para>
    2667 
    2668     <para>
    2669       Also required is the type of move operation, specified by
    2670       <computeroutput>--type basic</computeroutput>. Other types of move
    2671       operation may be supported in future releases.
    2672     </para>
    2673 
    2674     <para>
    2675       The <computeroutput>--folder</computeroutput> setting configures
    2676       the new location on the host file system. Enter a relative
    2677       pathname or a full pathname.
    2678     </para>
    2679 
    2680   </sect1>
    2681 
    2682   <sect1 id="vboxmanage-import">
    2683 
    2684     <title>VBoxManage import</title>
    2685 
    2686     <para>
    2687       This command imports one or more virtual machines into
    2688       &product-name;. You can import from either of the following:
    2689     </para>
    2690 
    2691     <itemizedlist>
    2692 
    2693       <listitem>
    2694         <para>
    2695           A virtual appliance in OVF format.
    2696         </para>
    2697       </listitem>
    2698 
    2699       <listitem>
    2700         <para>
    2701           A cloud service, such as &oci;. Only a single cloud instance
    2702           can be imported.
    2703         </para>
    2704       </listitem>
    2705 
    2706     </itemizedlist>
    2707 
    2708     <para>
    2709       See <xref linkend="ovf" /> for more details on importing VMs into
    2710       &product-name;.
    2711     </para>
    2712 
    2713     <sect2 id="vboxmanage-import-ovf">
    2714 
    2715       <title>Import from OVF</title>
    2716 
    2717       <para>
    2718         The <command>import</command> subcommand takes at least the path
    2719         name of an OVF file as input and expects the disk images, if
    2720         needed, to be in the same directory as the OVF file. Many
    2721         additional command-line options are supported. These enable you
    2722         to control in detail what is being imported and to modify the
    2723         import parameters, depending on the content of the OVF file.
    2724       </para>
    2725 
    2726       <para>
    2727         It is therefore recommended to first run the
    2728         <command>import</command> subcommand with the
    2729         <computeroutput>--dry-run</computeroutput> or
    2730         <computeroutput>-n</computeroutput> option. This will then print
    2731         a description of the appliance's contents to the screen how it
    2732         would be imported into &product-name;, together with the
    2733         optional command-line options to influence the import behavior.
    2734       </para>
    2735 
    2736       <para>
    2737         Use of the <computeroutput>--options
    2738         keepallmacs|keepnatmacs|keepdisknames</computeroutput> option
    2739         enables additional fine tuning of the import operation. The
    2740         first two options enable you to specify how the MAC addresses of
    2741         every virtual network card should be handled. They can either be
    2742         reinitialized, which is the default setting, left unchanged
    2743         (<computeroutput>keepallmacs</computeroutput>) or left unchanged
    2744         when the network type is NAT
    2745         (<computeroutput>keepnatmacs</computeroutput>). If you add
    2746         <computeroutput>keepdisknames</computeroutput> all new disk
    2747         images are assigned the same names as the originals, otherwise
    2748         they are renamed.
    2749       </para>
    2750 
    2751       <para>
    2752         As an example, the following is a screen output for a sample
    2753         appliance containing a Windows XP guest:
    2754       </para>
    2755 
    2756 <screen>VBoxManage import WindowsXp.ovf --dry-run
    2757       Interpreting WindowsXp.ovf...
    2758       OK.
    2759       Virtual system 0:
    2760        0: Suggested OS type: "WindowsXP"
    2761           (change with "--vsys 0 --ostype &lt;type&gt;"; use "list ostypes" to list all)
    2762        1: Suggested VM name "Windows XP Professional_1"
    2763           (change with "--vsys 0 --vmname &lt;name&gt;")
    2764        2: Suggested VM group "/"
    2765           (change with "--vsys 0 --group &lt;group&gt;")
    2766        3: Suggested VM settings file name "/home/klaus/VirtualBox VMs/dummy2 2/dummy2 2.vbox"
    2767           (change with "--vsys 0 --settingsfile &lt;filename&gt;")
    2768        4: Suggested VM base folder "/home/klaus/VirtualBox VMs"
    2769           (change with "--vsys 0 --basefolder &lt;path&gt;")
    2770        5: End-user license agreement
    2771           (display with "--vsys 0 --eula show";
    2772           accept with "--vsys 0 --eula accept")
    2773        6: Number of CPUs: 1
    2774           (change with "--vsys 0 --cpus &lt;n&gt;")
    2775        7: Guest memory: 956 MB (change with "--vsys 0 --memory &lt;MB&gt;")
    2776        8: Sound card (appliance expects "ensoniq1371", can change on import)
    2777           (disable with "--vsys 0 --unit 5 --ignore")
    2778        9: USB controller
    2779           (disable with "--vsys 0 --unit 6 --ignore")
    2780       10: Network adapter: orig bridged, config 2, extra type=bridged
    2781       11: Floppy
    2782           (disable with "--vsys 0 --unit 8 --ignore")
    2783       12: SCSI controller, type BusLogic
    2784           (change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}";
    2785           disable with "--vsys 0 --unit 9 --ignore")
    2786       13: IDE controller, type PIIX4
    2787           (disable with "--vsys 0 --unit 10 --ignore")
    2788       14: Hard disk image: source image=WindowsXp.vmdk,
    2789             target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
    2790           (change controller with "--vsys 0 --unit 11 --controller &lt;id&gt;";
    2791           disable with "--vsys 0 --unit 11 --ignore")</screen>
    2792 
    2793       <para>
    2794         The individual configuration items are numbered, and depending
    2795         on their type support different command-line options. The import
    2796         subcommand can be directed to ignore many such items with a
    2797         <computeroutput>--vsys X --unit Y --ignore</computeroutput>
    2798         option, where X is the number of the virtual system and Y the
    2799         item number, as printed on the screen. X is zero, unless there
    2800         are several virtual system descriptions in the appliance.
    2801       </para>
    2802 
    2803       <para>
    2804         In the above example, Item #1 specifies the name of the target
    2805         machine in &product-name;. Items #12 and #13 specify hard disk
    2806         controllers, respectively. Item #14 describes a hard disk image.
    2807         In this case, the additional
    2808         <computeroutput>--controller</computeroutput> option indicates
    2809         which item the disk image should be connected to, with the
    2810         default coming from the OVF file.
    2811       </para>
    2812 
    2813       <para>
    2814         You can combine several items for the same virtual system using
    2815         the <computeroutput>--vsys</computeroutput> option. For example,
    2816         to import a machine as described in the OVF, but without the
    2817         sound card and without the USB controller, and with the disk
    2818         image connected to the IDE controller instead of the SCSI
    2819         controller, use the following command:
    2820       </para>
    2821 
    2822 <screen>VBoxManage import WindowsXp.ovf
    2823   --vsys 0 --unit 8 --ignore --unit 9 --ignore --unit 14 --controller 13</screen>
    2824 
    2825     </sect2>
    2826 
    2827     <sect2 id="vboxmanage-import-cloud">
    2828 
    2829       <title>Import from &oci;</title>
    2830 
    2831       <para>
    2832         As the result of this operation, a file with the suffix
    2833         <filename>.oci</filename> is downloaded to the local host. This
    2834         file is a TAR archive which contains a bootable instance image
    2835         in QCOW2 format and a JSON file with some metadata related to
    2836         the imported instance.
    2837       </para>
    2838 
    2839       <para>
    2840         The downloaded file is deleted after a successful import. If
    2841         import fails, the downloaded file may not be deleted and the
    2842         VBoxSVC log file may indicate the location where the file was
    2843         stored.
    2844       </para>
    2845 
    2846       <para>
    2847         During import the bootable image is extracted from the archive
    2848         and converted into VMDK format. The JSON file is also extracted
    2849         and stored in the VM machine folder.
    2850       </para>
    2851 
    2852       <para>
    2853         The command syntax for importing an &oci; instance begins with
    2854         <command>VBoxManage import OCI:// --cloud</command>.
    2855       </para>
    2856 
    2857       <para>
    2858         You can list the available &oci; VM instances and their IDs by
    2859         using the following command:
    2860       </para>
    2861 
    2862 <screen>VBoxManage cloud --provider=OCI --profile=<replaceable>cloud-profile-name</replaceable> list instances</screen>
    2863 
    2864       <para>
    2865         To import a VM from a cloud service such as &oci;, use the
    2866         <option>--cloud</option> option to specify the import from the
    2867         Cloud. Some of the following options are settings for the VM,
    2868         for others you must enter an Oracle Cloud Identifier (OCID) for
    2869         a resource. Use the Oracle Cloud Infrastructure Console to view
    2870         OCIDs.
    2871       </para>
    2872 
    2873       <para>
    2874         The following parameters can be specified:
    2875       </para>
    2876 
    2877       <itemizedlist>
    2878 
    2879         <listitem>
    2880           <para>
    2881             <option>--vmname</option>: Specifies a new name for the
    2882             imported VM. This name is used as the VM name by
    2883             &product-name;.
    2884           </para>
    2885         </listitem>
    2886 
    2887         <listitem>
    2888           <para>
    2889             <option>--cloudinstanceid</option>: The ID of an existing
    2890             instance in the Cloud.
    2891           </para>
    2892         </listitem>
    2893 
    2894         <listitem>
    2895           <para>
    2896             <option>--cloudprofile</option>: Specifies the cloud profile
    2897             that is used to connect to the cloud service provider. The
    2898             cloud profile contains your &oci; account details, such as
    2899             your user OCID and the fingerprint for your public key. To
    2900             use a cloud profile, you must have the required permissions
    2901             on &oci;.
    2902           </para>
    2903         </listitem>
    2904 
    2905         <listitem>
    2906           <para>
    2907             <option>--cloudbucket</option>: Specifies the bucket name in
    2908             which to store the object created from an instance bootable
    2909             volume. In &oci;, a bucket is a logical container for
    2910             storing objects.
    2911           </para>
    2912         </listitem>
    2913 
    2914       </itemizedlist>
    2915 
    2916       <para>
    2917         The following import options have the same meaning as for OVF
    2918         import:
    2919       </para>
    2920 
    2921       <itemizedlist>
    2922 
    2923         <listitem>
    2924           <para>
    2925             <option>--ostype</option>: An OS type supported by
    2926             &product-name;. Use the <command>VBoxManage list
    2927             ostypes</command> command to see the whole list of supported
    2928             OSes. If the type was not set, the
    2929             <literal>Unknown</literal> type is used.
    2930           </para>
    2931         </listitem>
    2932 
    2933         <listitem>
    2934           <para>
    2935             <option>--basefolder</option>: The folder where the new VM
    2936             is stored.
    2937           </para>
    2938         </listitem>
    2939 
    2940         <listitem>
    2941           <para>
    2942             <option>--description</option>: A string describing the VM.
    2943           </para>
    2944         </listitem>
    2945 
    2946         <listitem>
    2947           <para>
    2948             <option>--memory</option>: The amount of RAM memory assigned
    2949             for the VM, in MB. If this option is not set either the
    2950             default memory size for the OS type is used, or the value is
    2951             taken from the &oci; instance.
    2952           </para>
    2953         </listitem>
    2954 
    2955         <listitem>
    2956           <para>
    2957             <option>--cpus</option>: the number of virtual CPUs assigned
    2958             for the VM. If this option is not set, either the default
    2959             virtual CPUs setting for the OS type is used, or the value
    2960             is taken from the &oci; instance.
    2961           </para>
    2962         </listitem>
    2963 
    2964       </itemizedlist>
    2965 
    2966       <para>
    2967         The import options <option>--disk</option>,
    2968         <option>--controller</option>, <option>--scsitype</option>,
    2969         <option>--unit</option>, <option>--settingsfile</option> are not
    2970         valid for cloud import.
    2971       </para>
    2972 
    2973       <para>
    2974         The following example shows a typical command line for importing
    2975         an instance from &oci;:
    2976       </para>
    2977 
    2978 <screen># VBoxManage import OCI:// --cloud --vmname import_from_oci --memory 4000
    2979   --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user"
    2980   --cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket</screen>
    2981 
    2982     </sect2>
    2983 
    2984   </sect1>
    2985 
    2986   <sect1 id="vboxmanage-export">
    2987 
    2988     <title>VBoxManage export</title>
    2989 
    2990     <para>
    2991       This command exports one or more virtual machines from
    2992       &product-name;. You can export to either of the following:
    2993     </para>
    2994 
    2995     <itemizedlist>
    2996 
    2997       <listitem>
    2998         <para>
    2999           A virtual appliance in OVF format, including copying their
    3000           virtual disk images to compressed VMDK.
    3001         </para>
    3002       </listitem>
    3003 
    3004       <listitem>
    3005         <para>
    3006           A cloud service, such as &oci;. A single VM can be exported in
    3007           VMDK format.
    3008         </para>
    3009       </listitem>
    3010 
    3011     </itemizedlist>
    3012 
    3013     <para>
    3014       See <xref linkend="ovf" /> for more details on exporting VMs from
    3015       &product-name;.
    3016     </para>
    3017 
    3018     <sect2 id="vboxmanage-export-ovf">
    3019 
    3020       <title>Export to OVF</title>
    3021 
    3022       <para>
    3023         List the machine, or the machines, that you would like to export
    3024         to the same OVF file and specify the target OVF file after an
    3025         additional <computeroutput>--output</computeroutput> or
    3026         <computeroutput>-o</computeroutput> option. Note that the
    3027         directory of the target OVF file will also receive the exported
    3028         disk images in the compressed VMDK format, regardless of the
    3029         original format, and should have enough disk space left for
    3030         them.
    3031       </para>
    3032 
    3033       <para>
    3034         Beside a simple export of a given virtual machine, you can
    3035         append several product information to the appliance file. Use
    3036         <computeroutput>--product</computeroutput>,
    3037         <computeroutput>--producturl</computeroutput>,
    3038         <computeroutput>--vendor</computeroutput>,
    3039         <computeroutput>--vendorurl</computeroutput>,
    3040         <computeroutput>--version</computeroutput> and
    3041         <computeroutput>--description</computeroutput> to specify this
    3042         additional information. For legal reasons you may add a license
    3043         text or the content of a license file by using the
    3044         <computeroutput>--eula</computeroutput> and
    3045         <computeroutput>--eulafile</computeroutput> option respectively.
    3046       </para>
    3047 
    3048       <para>
    3049         As with OVF import, you use the <computeroutput>--vsys
    3050         X</computeroutput> option to apply these options to the correct
    3051         virtual machine.
    3052       </para>
    3053 
    3054       <para>
    3055         For virtualization products which are not fully compatible with
    3056         the OVF standard 1.0 you can enable an OVF 0.9 legacy mode with
    3057         the <computeroutput>--legacy09</computeroutput> option. Other
    3058         options are <computeroutput>--ovf09</computeroutput>,
    3059         <computeroutput>--ovf10</computeroutput>,
    3060         <computeroutput>--ovf20</computeroutput>.
    3061       </para>
    3062 
    3063       <para>
    3064         To specify options controlling the exact content of the
    3065         appliance file, you can use <option>--options</option> to
    3066         request the creation of a manifest file, which enables detection
    3067         of corrupted appliances on import, the additional export of DVD
    3068         images, and the exclusion of MAC addresses. You can specify a
    3069         list of options, such as <option>--options
    3070         manifest,nomacs</option>. For details, check the help output of
    3071         <command>VBoxManage export</command>.
    3072       </para>
    3073 
    3074     </sect2>
    3075 
    3076     <sect2 id="vboxmanage-export-cloud">
    3077 
    3078       <title>Export to &oci;</title>
    3079 
    3080       <para>
    3081         By default, an exported disk image is converted into stream VMDK
    3082         format. This ensures compatibility with &oci;.
    3083       </para>
    3084 
    3085       <para>
    3086         List the machine that you want to export to &oci; and specify
    3087         the target cloud service provider by using the
    3088         <computeroutput>--output</computeroutput> or
    3089         <computeroutput>-o</computeroutput> option.
    3090       </para>
    3091 
    3092       <para>
    3093         To export a VM to a cloud service such as &oci;, use the
    3094         <option>--cloud</option> option to specify the VM to export.
    3095         This option works in the same way as the <option>--vsys</option>
    3096         option for OVF export.
    3097       </para>
    3098 
    3099       <para>
    3100         Some of the following options are settings for the VM instance.
    3101         As a result, you must enter an Oracle Cloud Identifier (OCID)
    3102         for a resource. Use the &oci; Console to view OCIDs.
    3103       </para>
    3104 
    3105       <itemizedlist>
    3106 
    3107         <listitem>
    3108           <para>
    3109             <option>--output/-o</option>: Specifies the short name of
    3110             the cloud service provider to which you export. For &oci;,
    3111             enter <computeroutput>OCI://</computeroutput>.
    3112           </para>
    3113         </listitem>
    3114 
    3115         <listitem>
    3116           <para>
    3117             <option>--cloud</option>
    3118             <replaceable>number-of-virtual-system</replaceable>:
    3119             Specifies a number that identifies the VM that you are
    3120             exporting. Numbering starts at
    3121             <computeroutput>0</computeroutput> for the first VM.
    3122           </para>
    3123         </listitem>
    3124 
    3125         <listitem>
    3126           <para>
    3127             <option>--vmname</option> <replaceable>name</replaceable>:
    3128             Specifies the name of the exported VM. This name is used as
    3129             the VM instance name in &oci;.
    3130           </para>
    3131         </listitem>
    3132 
    3133         <listitem>
    3134           <para>
    3135             <option>--cloudprofile</option>
    3136             <replaceable>cloud-profile-name</replaceable>: Specifies the
    3137             cloud profile that is used to connect to the cloud service
    3138             provider. The cloud profile contains your &oci; account
    3139             details, such as your user OCID and the fingerprint for your
    3140             public key. See <xref linkend="cloud-export-oci"/>.
    3141           </para>
    3142 
    3143           <para>
    3144             To use a cloud profile, you must have the required
    3145             permissions on &oci;.
    3146           </para>
    3147         </listitem>
    3148 
    3149         <listitem>
    3150           <para>
    3151             <option>--cloudshape</option>
    3152             <replaceable>shape</replaceable>: Specifies the shape used
    3153             for the VM instance. The shape defines the number of CPUs
    3154             and the amount of memory allocated to the VM instance. The
    3155             shape must be compatible with the exported image.
    3156           </para>
    3157         </listitem>
    3158 
    3159         <listitem>
    3160           <para>
    3161             <option>--clouddomain</option>
    3162             <replaceable>domain</replaceable>: Specifies the
    3163             availability domain to use for the VM instance. Enter the
    3164             full name of the availability domain.
    3165           </para>
    3166         </listitem>
    3167 
    3168         <listitem>
    3169           <para>
    3170             <option>--clouddisksize</option>
    3171             <replaceable>disk-size-in-GB</replaceable>: Specifies the
    3172             disk size used for the exported disk image in gigabytes. The
    3173             minimum value is 50 GB and the maximum value is 300 GB.
    3174           </para>
    3175         </listitem>
    3176 
    3177         <listitem>
    3178           <para>
    3179             <option>--cloudbucket</option>
    3180             <replaceable>bucket-name</replaceable>: Specifies the bucket
    3181             in which to store the uploaded files. In &oci;, a bucket is
    3182             a logical container for storing objects.
    3183           </para>
    3184         </listitem>
    3185 
    3186         <listitem>
    3187           <para>
    3188             <option>--cloudocivcn</option>
    3189             <replaceable>OCI-vcn-ID</replaceable>: Specifies the virtual
    3190             cloud network (VCN) to use for the VM instance. Enter the
    3191             OCID for the VCN.
    3192           </para>
    3193         </listitem>
    3194 
    3195         <listitem>
    3196           <para>
    3197             <option>--cloudocisubnet</option>
    3198             <replaceable>OCI-subnet-ID</replaceable>: Specifies the
    3199             subnet of the VCN to use for the VM instance. Enter the OCID
    3200             for the subnet.
    3201           </para>
    3202         </listitem>
    3203 
    3204         <listitem>
    3205           <para>
    3206             <option>--cloudkeepobject true | false</option>: Specifies
    3207             whether to store the exported disk image in Oracle Object
    3208             Storage.
    3209           </para>
    3210         </listitem>
    3211 
    3212         <listitem>
    3213           <para>
    3214             <option>--cloudlaunchinstance true | false</option>:
    3215             Specifies whether to start the VM instance after the export
    3216             to &oci; completes.
    3217           </para>
    3218         </listitem>
    3219 
    3220         <listitem>
    3221           <para>
    3222             <option>--cloudpublicip true | false</option>: Specifies
    3223             whether to enable a public IP address for the VM instance.
    3224           </para>
    3225         </listitem>
    3226 
    3227       </itemizedlist>
    3228 
    3229       <para>
    3230         The following example shows a typical command line for exporting
    3231         a VM to &oci;.
    3232       </para>
    3233 
    3234 <screen># VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \
    3235 --cloudprofile "standard user" --cloudbucket myBucket \
    3236 --cloudshape VM.Standard2.1 --clouddomain US-ASHBURN-AD-1 --clouddisksize 50  \
    3237 --cloudocivcn ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet ocid1.subnet.oc1.iad.aaaa... \
    3238 --cloudkeepobject true --cloudlaunchinstance true --cloudpublicip true</screen>
    3239 
    3240     </sect2>
    3241 
    3242   </sect1>
     304  <!-- TODO: Check the overview/common man page -->
     305  <xi:include href="user_man_VBoxManage.xml"                xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     306
     307  <xi:include href="user_man_VBoxManage-list.xml"           xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     308
     309  <xi:include href="user_man_VBoxManage-showvminfo.xml"     xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     310
     311  <xi:include href="user_man_VBoxManage-registervm.xml"     xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     312
     313  <xi:include href="user_man_VBoxManage-unregistervm.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     314
     315  <xi:include href="user_man_VBoxManage-createvm.xml"       xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     316
     317  <xi:include href="user_man_VBoxManage-modifyvm.xml"       xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     318
     319  <xi:include href="user_man_VBoxManage-clonevm.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     320
     321  <xi:include href="user_man_VBoxManage-movevm.xml"         xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     322
     323  <xi:include href="user_man_VBoxManage-cloud.xml"          xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     324
     325  <xi:include href="user_man_VBoxManage-cloudprofile.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     326
     327  <xi:include href="user_man_VBoxManage-import.xml"         xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     328
     329  <xi:include href="user_man_VBoxManage-export.xml"         xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     330
     331  <xi:include href="user_man_VBoxManage-signova.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    3243332
    3244333  <sect1 id="vboxmanage-startvm">
    … …  
    43411430  </sect1>
    43421431
     1432  <xi:include href="user_man_VBoxManage-unattended.xml"     xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     1433
    43431434  <sect1 id="vboxmanage-discardstate">
    43441435
    … …  
    43691460
    43701461  </sect1>
     1462
     1463  <xi:include href="user_man_VBoxManage-snapshot.xml"       xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    43711464
    43721465  <sect1 id="vboxmanage-closemedium">
    … …  
    60163109  </sect1>
    60173110
     3111  <xi:include href="user_man_VBoxManage-mediumio.xml"       xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     3112
    60183113  <sect1 id="vboxmanage-extradata">
    60193114
    … …  
    64303525  </sect1>
    64313526
     3527  <xi:include href="user_man_VBoxManage-sharedfolder.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     3528
    64323529  <sect1 id="vboxmanage-guestproperty">
    64333530
    … …  
    82165313  </sect1>
    82175314
     5315  <xi:include href="user_man_VBoxManage-debugvm.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     5316
    82185317  <sect1 id="vboxmanage-metrics">
    82195318
    … …  
    89166015  </sect1>
    89176016
     6017  <xi:include href="user_man_VBoxManage-dhcpserver.xml"     xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     6018
    89186019  <sect1 id="vboxmanage-usbdevsource">
    89196020
    … …  
    89896090  </sect1>
    89906091
    8991 <!-- TODO: Figure out how we can generate a file with the includes... The trouble is
    8992              that xpointer doesn't seem to allow including multiple elements.
    8993 
    8994              In the mean time, when adding new VBoxManage man pages to Config.kmk,
    8995              don't forget to add it here too.
    8996    -->
    8997 
    8998   <xi:include href="user_man_VBoxManage-unattended.xml"     xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    8999 
    9000   <xi:include href="user_man_VBoxManage-snapshot.xml"       xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    9001 
    9002   <xi:include href="user_man_VBoxManage-clonevm.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    9003 
    9004   <xi:include href="user_man_VBoxManage-sharedfolder.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    9005 
    90066092  <xi:include href="user_man_VBoxManage-extpack.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    90076093
    9008   <xi:include href="user_man_VBoxManage-dhcpserver.xml"     xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    9009 
    9010   <xi:include href="user_man_VBoxManage-debugvm.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    9011 
    9012   <xi:include href="user_man_VBoxManage-cloudprofile.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    9013 
    9014   <xi:include href="user_man_VBoxManage-cloud.xml"          xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    9015 
    9016   <xi:include href="user_man_VBoxManage-signova.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    9017 
    90186094  <xi:include href="user_man_VBoxManage-updatecheck.xml"    xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    90196095
    9020 <!-- TODO: Figure out how we can handle other manpages. The xml is bolted to
     6096  <!-- TODO: Figure out how we can handle other manpages. The xml is bolted to
    90216097             sect1, so it's not possible to have them "in place" -->
    90226098
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette