VirtualBox

Changeset 93708 in vbox


Ignore:
Timestamp:
Feb 11, 2022 8:46:11 PM (3 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
149879
Message:

include/iprt/message.h: Max out the available bits for the scope, we need a lot for the VBoxManage controlvm docs.

docs, VBoxManage: Integrate refman (and fix some content) for VBoxManage startvm and VBoxManage controlvm. Needs about 60 scopes (do RT_BIT_64 is a must have), and for protection against exceeding the limit there are now checks (as AssertCompile).

Location:
trunk
Files:
13 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/Config.kmk

    r93115 r93708  
    4343        man_VBoxManage-createvm.xml \
    4444        man_VBoxManage-modifyvm.xml \
     45        man_VBoxManage-snapshot.xml \
    4546        man_VBoxManage-clonevm.xml \
    4647        man_VBoxManage-movevm.xml \
     48        man_VBoxManage-startvm.xml \
     49        man_VBoxManage-controlvm.xml \
    4750        man_VBoxManage-import.xml \
    4851        man_VBoxManage-export.xml \
    49         man_VBoxManage-snapshot.xml \
    5052        man_VBoxManage-mediumio.xml \
    5153        man_VBoxManage-sharedfolder.xml \
    … …  
    176178                '' \
    177179                '#include <iprt/message.h>' \
     180                '#include <iprt/assertcompile.h>' \
    178181                '' \
    179182               'typedef enum HELP_CMD_$(3)' \

  • trunk/doc/manual/docbook-refentry-to-H-help.xsl

    r82969 r93708  
    6565        <xsl:value-of select="$sBaseNm"/>
    6666        <xsl:value-of select="substring('                                               ',1,56 - string-length($sBaseNm) - 11)"/>
    67         <xsl:text> RT_BIT_32(HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_BIT)
     67        <xsl:text> RT_BIT_64(HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_BIT)
    6868        HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_BIT = 0</xsl:text>
    6969
    … …  
    8080          <xsl:value-of select="$sSubNm"/>
    8181          <xsl:value-of select="substring('                                               ',1,56 - string-length($sSubNm))"/>
    82           <xsl:text> RT_BIT_32(</xsl:text><xsl:value-of select="$sSubNm"/><xsl:text>_BIT)
     82          <xsl:text> RT_BIT_64(</xsl:text><xsl:value-of select="$sSubNm"/><xsl:text>_BIT)
    8383        </xsl:text>
    8484          <xsl:value-of select="$sSubNm"/><xsl:text>_BIT</xsl:text>
    8585        </xsl:for-each>
    8686
    87         <!-- Add scoping info for refsect1, refsect2 and refsect3 IDs that aren't part of the synopsis. -->
    88         <xsl:for-each select=".//refsect1[@id] | .//refsect2[@id] | .//refsect3[@id]">
     87        <!-- Add scoping info for refsect1 and refsect2 IDs that aren't part of the synopsis. -->
     88        <xsl:for-each select=".//refsect1[@id] | .//refsect2[@id]">
    8989          <xsl:variable name="sThisId" select="@id"/>
    9090          <xsl:if test="not($RefEntry[@id = $sThisId]) and not($RefEntry/refsynopsisdiv/cmdsynopsis[@id = concat('synopsis-', $sThisId)])">
    … …  
    108108            <xsl:value-of select="$sSubNm"/>
    109109            <xsl:value-of select="substring('                                               ',1,56 - string-length($sSubNm))"/>
    110             <xsl:text> RT_BIT_32(</xsl:text><xsl:value-of select="$sSubNm"/><xsl:text>_BIT)
     110            <xsl:text> RT_BIT_64(</xsl:text><xsl:value-of select="$sSubNm"/><xsl:text>_BIT)
    111111        </xsl:text>
    112112            <xsl:value-of select="$sSubNm"/><xsl:text>_BIT</xsl:text>
    … …  
    118118        HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_END
    119119};
     120AssertCompile((int)HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_END &gt;= 1);
     121AssertCompile((int)HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_END &lt; 64);
     122AssertCompile(RT_BIT_64(HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_END - 1) &amp; RTMSGREFENTRYSTR_SCOPE_MASK);
    120123</xsl:text>
    121124      </xsl:when>

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

    r92534 r93708  
    2020<refentry id="vboxmanage-controlvm" lang="en">
    2121  <refentryinfo>
    22     <pubdate>September 2019</pubdate>
     22    <pubdate>$Date$</pubdate>
    2323    <title>VBoxManage controlvm</title>
    2424  </refentryinfo>
    … …  
    3232    <refname>VBoxManage-controlvm</refname>
    3333    <refpurpose>change state and settings for a running virtual machine</refpurpose>
    34     <refclass>Oracle VM VirtualBox</refclass>
     34    <refclass>&product-name;</refclass>
    3535  </refnamediv>
    3636
    … …  
    116116      </group>
    117117      <arg choice="plain">shutdown</arg>
     118      <arg choice="opt">--force</arg>
    118119    </cmdsynopsis>
    119120
    … …  
    316317    </cmdsynopsis>
    317318
    318     <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard">
    319       <command>VBoxManage controlvm</command>
    320       <group choice="req">
    321         <arg choice="plain"><replaceable>uuid</replaceable></arg>
    322         <arg choice="plain"><replaceable>vmname</replaceable></arg>
    323       </group>
    324       <arg choice="plain">clipboard</arg>
     319    <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-mode">
     320      <command>VBoxManage controlvm</command>
     321      <group choice="req">
     322        <arg choice="plain"><replaceable>uuid</replaceable></arg>
     323        <arg choice="plain"><replaceable>vmname</replaceable></arg>
     324      </group>
     325      <arg choice="plain">clipboard mode</arg>
    325326      <group choice="req">
    326327        <arg choice="plain">disabled</arg>
    … …  
    330331      </group>
    331332    </cmdsynopsis>
     333
     334    <!--
     335    <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-filetransfers">
     336      <command>VBoxManage controlvm</command>
     337      <group choice="req">
     338        <arg choice="plain"><replaceable>uuid</replaceable></arg>
     339        <arg choice="plain"><replaceable>vmname</replaceable></arg>
     340      </group>
     341      <arg choice="plain">clipboard filetransfers</arg>
     342      <group choice="req">
     343        <arg choice="plain">on</arg>
     344        <arg choice="plain">off</arg>
     345      </group>
     346    </cmdsynopsis>
     347    -->
    332348
    333349    <cmdsynopsis id="synopsis-vboxmanage-controlvm-draganddrop">
    … …  
    444460    </cmdsynopsis>
    445461
    446     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingscreens">
     462    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-screens">
    447463      <command>VBoxManage controlvm</command>
    448464      <group choice="req">
    … …  
    454470        <arg choice="plain">all</arg>
    455471        <arg choice="plain">none</arg>
    456         <arg choice="plain"><replaceable>screen</replaceable>,[<replaceable>screen</replaceable>...]</arg>
    457       </group>
    458     </cmdsynopsis>
    459 
    460     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingfilename">
     472        <arg choice="plain"><replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...]</arg>
     473      </group>
     474    </cmdsynopsis>
     475
     476    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-filename">
    461477      <command>VBoxManage controlvm</command>
    462478      <group choice="req">
    … …  
    468484    </cmdsynopsis>
    469485
    470     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingvideores">
     486    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videores">
    471487      <command>VBoxManage controlvm</command>
    472488      <group choice="req">
    … …  
    478494    </cmdsynopsis>
    479495
    480     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingvideorate">
     496    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videorate">
    481497      <command>VBoxManage controlvm</command>
    482498      <group choice="req">
    … …  
    488504    </cmdsynopsis>
    489505
    490     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingvideofps">
     506    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videofps">
    491507      <command>VBoxManage controlvm</command>
    492508      <group choice="req">
    … …  
    498514    </cmdsynopsis>
    499515
    500     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingmaxtime">
     516    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxtime">
    501517      <command>VBoxManage controlvm</command>
    502518      <group choice="req">
    … …  
    508524    </cmdsynopsis>
    509525
    510     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingmaxfilesize">
     526    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxfilesize">
    511527      <command>VBoxManage controlvm</command>
    512528      <group choice="req">
    … …  
    517533      <arg choice="req"><replaceable>MB</replaceable></arg>
    518534    </cmdsynopsis>
     535
     536    <!--
     537    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-opts">
     538      <command>VBoxManage controlvm</command>
     539      <group choice="req">
     540        <arg choice="plain"><replaceable>uuid</replaceable></arg>
     541        <arg choice="plain"><replaceable>vmname</replaceable></arg>
     542      </group>
     543      <arg choice="plain">recording opts</arg>
     544      <arg choice="req"><replaceable>key</replaceable>=<arg><replaceable>value</replaceable></arg></arg>
     545    </cmdsynopsis>
     546    -->
    519547
    520548    <cmdsynopsis id="synopsis-vboxmanage-controlvm-setcredentials">
    … …  
    583611    </cmdsynopsis>
    584612
    585     <cmdsynopsis id="synopsis-vboxmanage-controlvm-vmprocesspriority">
     613    <cmdsynopsis id="synopsis-vboxmanage-controlvm-vm-process-priority">
    586614      <command>VBoxManage controlvm</command>
    587615      <group choice="req">
    … …  
    683711    </cmdsynopsis>
    684712
    685     <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostartenabled">
     713    <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-enabled">
    686714      <command>VBoxManage controlvm</command>
    687715      <group choice="req">
    … …  
    696724    </cmdsynopsis>
    697725
    698     <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostartdelay">
     726    <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-delay">
    699727      <command>VBoxManage controlvm</command>
    700728      <group choice="req">
    … …  
    796824      </para>
    797825      <para>
    798         When in the powered off state, you can restart the VM.
     826        When in the saved state, you can restart the VM. It will continue
     827        exactly in the state you saved.
    799828      </para>
    800829    </refsect2>
    … …  
    810839      </para>
    811840      <para>
    812         So long as the VM runs a guest OS that provides ACPI support,
    813         this command triggers a proper shutdown mechanism from within
    814         the VM.
     841        So long as the VM runs a guest OS that provides appropriately
     842        configured ACPI support, this command triggers an operating
     843        system shutdown from within the VM.
    815844      </para>
    816845    </refsect2>
    … …  
    824853      </para>
    825854      <para>
    826         So long as the VM runs a guest OS that provides ACPI support,
    827         this command triggers a proper sleep mechanism from within the
    828         VM.
     855        So long as the VM runs a guest OS that provides appropriately
     856        configured ACPI support, this command triggers a sleep mechanism
     857        from within the VM.
    829858      </para>
    830859    </refsect2>
    … …  
    838867      </para>
    839868      <para>
    840         This commands new recent Guest Additions installed.
     869        This commands requires Guest Additions to be installed in the VM.
    841870      </para>
    842871    </refsect2>
    … …  
    847876        The <command>VBoxManage controlvm
    848877        <replaceable>vmname</replaceable> shutdown</command>
    849         command asks the guest OS to halt + shutdown.
    850       </para>
    851       <para>
    852         This commands new recent Guest Additions installed.
     878        command asks the guest OS to halt + shutdown, optionally forcing
     879        the shutdown.
     880      </para>
     881      <para>
     882        This commands requires Guest Additions to be installed in the VM.
    853883      </para>
    854884    </refsect2>
    … …  
    883913        command sends a file to the VM.
    884914      </para>
     915    </refsect2>
     916    <refsect2 id="vboxmanage-controlvm-setlinkstate">
     917      <title>Set the Link State for a Virtual Machine</title>
     918      <remark role="help-copy-synopsis"/>
     919      <para>
     920        <command>VBoxManage controlvm <replaceable>vmname</replaceable>
     921        setlinkstate<replaceable>N</replaceable></command> command
     922        enables you to connect or disconnect the virtual network cable
     923        from the network interface instance
     924        (<replaceable>N</replaceable>). Valid values are
     925        <literal>on</literal> and <literal>off</literal>. The default
     926        value is <literal>on</literal>.
     927      </para>
     928    </refsect2>
     929    <refsect2 id="vboxmanage-controlvm-nic">
     930      <title>Set the Type of Networking to Use for a Virtual Machine</title>
     931      <remark role="help-copy-synopsis"/>
     932      <para>
     933        The <command>VBoxManage controlvm
     934        <replaceable>vmname</replaceable>
     935        nic<replaceable>N</replaceable></command> command specifies the
     936        type of networking to use on the specified VM's virtual network
     937        card. <replaceable>N</replaceable> numbering begins with
     938        <literal>1</literal>.
     939      </para>
     940      <para>
     941        The following valid network types are also described in
     942        <xref linkend="networkingmodes" />:
     943      </para>
     944      <itemizedlist>
     945        <listitem><para>
     946            <literal>null</literal> specifies that the VM is is not
     947            connected to the host system.
     948          </para></listitem>
     949        <listitem><para>
     950            <literal>nat</literal> specifies that the VM uses network
     951            address translation (NAT).
     952          </para></listitem>
     953        <listitem><para>
     954            <literal>bridged</literal> specifies that the VM uses
     955            bridged networking.
     956          </para></listitem>
     957        <listitem><para>
     958            <literal>intnet</literal> specifies that the VM communicates
     959            with other VMs by using internal networking.
     960          </para></listitem>
     961        <listitem><para>
     962            <literal>hostonly</literal> specifies that the VM uses
     963            host-only networking.
     964          </para></listitem>
     965        <listitem><para>
     966            <literal>natnetwork</literal> specifies that the VM uses NAT
     967            networking.
     968          </para></listitem>
     969        <listitem><para>
     970            <literal>generic</literal> specifies that the VM has access
     971            to rarely used submodes
     972          </para></listitem>
     973      </itemizedlist>
     974    </refsect2>
     975    <refsect2 id="vboxmanage-controlvm-nictrace">
     976      <title>Trace the Network Traffic of a Virtual Machine</title>
     977      <remark role="help-copy-synopsis"/>
     978      <para>
     979        The <command>VBoxManage controlvm
     980        <replaceable>vmname</replaceable>
     981        nictrace<replaceable>N</replaceable></command> command enables
     982        you to trace the network traffic on the specified virtual
     983        network card (<replaceable>N</replaceable>).
     984        <replaceable>N</replaceable> numbering begins with
     985        <literal>1</literal>. Valid values are <literal>on</literal> and
     986        <literal>off</literal>. The default value is
     987        <literal>off</literal>.
     988      </para>
     989      <para>
     990        If you did not configure a file name for the trace file then
     991        a default one is used, placing it in the VM subdirectory.
     992      </para>
     993    </refsect2>
     994    <refsect2 id="vboxmanage-controlvm-nictracefile">
     995      <title>Specify the Network Traffic Trace Log File for a Virtual Machine</title>
     996      <remark role="help-copy-synopsis"/>
     997      <para>
     998        The <command>VBoxManage controlvm
     999        <replaceable>vmname</replaceable>
     1000        nictracefile<replaceable>N</replaceable></command> command
     1001        enables you to specify the name of the network traffic trace log
     1002        file for the specified virtual network card
     1003        (<replaceable>N</replaceable>). <replaceable>N</replaceable>
     1004        numbering begins with <literal>1</literal>.
     1005      </para>
     1006    </refsect2>
     1007    <refsect2 id="vboxmanage-controlvm-nicpromisc">
     1008      <title>Specify the Promiscuous Mode to Use for a Virtual Machine</title>
     1009      <remark role="help-copy-synopsis"/>
     1010      <para>
     1011        The <command>VBoxManage controlvm
     1012        <replaceable>vmname</replaceable>
     1013        nicpromisc<replaceable>N</replaceable></command> command enables
     1014        you to specify how to handle promiscuous mode for a bridged
     1015        network. The default value of <literal>deny</literal> hides any
     1016        traffic that is not intended for this VM. The
     1017        <literal>allow-vms</literal> value hides all host traffic from
     1018        this VM but enables the VM to see traffic to and from other VMs.
     1019        The <literal>allow-all</literal> value removes this restriction
     1020        completely.
     1021      </para>
     1022    </refsect2>
     1023    <refsect2 id="vboxmanage-controlvm-nicproperty">
     1024      <title>Specify the Network Backend Property Values for a Virtual Machine</title>
     1025      <remark role="help-copy-synopsis"/>
     1026      <para>
     1027        The <command>VBoxManage controlvm
     1028        <replaceable>vmname</replaceable>
     1029        nicproperty<replaceable>N</replaceable>
     1030        <replaceable>prop-name</replaceable>="<replaceable>prop-value</replaceable>"</command>
     1031        command, in combination with <literal>nicgenericdrv</literal>,
     1032        enables you to pass property values to rarely-used network
     1033        backends.
     1034      </para>
     1035      <para>
     1036        Those properties are backend engine-specific, and are different
     1037        between UDP Tunnel and the VDE backend drivers. See
     1038        <xref linkend="network_udp_tunnel" />.
     1039      </para>
     1040    </refsect2>
     1041    <refsect2 id="vboxmanage-controlvm-natpf">
     1042      <title>Specify a NAT Port Forwarding Rule for a Virtual Machine</title>
     1043      <remark role="help-copy-synopsis"/>
     1044      <para>
     1045        The <command>VBoxManage controlvm
     1046        <replaceable>vmname</replaceable>
     1047        natpf<replaceable>N</replaceable></command> command specifies a
     1048        NAT port-forwarding rule. See <xref linkend="natforward"/>.
     1049      </para>
     1050    </refsect2>
     1051    <refsect2 id="vboxmanage-controlvm-natpf-delete">
     1052      <title>Delete a NAT Port Forwarding Rule for a Virtual Machine</title>
     1053      <remark role="help-copy-synopsis"/>
     1054      <para>
     1055        The <command>VBoxManage controlvm
     1056        <replaceable>vmname</replaceable>
     1057        natpf<replaceable>N</replaceable> delete</command> command deletes
     1058        the specified NAT port-forwarding rule. See
     1059        <xref linkend="natforward"/>.
     1060      </para>
     1061    </refsect2>
     1062    <refsect2 id="vboxmanage-controlvm-guestmemoryballoon">
     1063      <title>Change Size of a Virtual Machine's Guest Memory Balloon</title>
     1064      <remark role="help-copy-synopsis"/>
     1065      <para>
     1066        The <command>VBoxManage controlvm
     1067        <replaceable>vmname</replaceable> guestmemoryballoon</command>
     1068        command changes the size of the guest memory balloon. The guest
     1069        memory balloon is the memory allocated by the &product-name;
     1070        Guest Additions from the guest OS and returned to the hypervisor
     1071        for reuse by other VMs. The value you specify is in megabytes.
     1072        See <xref linkend="guestadd-balloon" />.
     1073      </para>
     1074    </refsect2>
     1075    <refsect2 id="vboxmanage-controlvm-usbattach">
     1076      <title>Make a Host System USB Device Visible to a Virtual Machine</title>
     1077      <remark role="help-copy-synopsis"/>
     1078      <para>
     1079        The <command>VBoxManage controlvm
     1080        <replaceable>vmname</replaceable> usbattach</command> command
     1081        dynamically attaches a host USB device to the VM, which makes it
     1082        visible. You do not need to create a filter.
     1083      </para>
     1084      <para>
     1085        Specify a USB device by its Universally Unique Identifier (UUID)
     1086        or by its address on the host system. Use the
     1087        <command>VBoxManage list usbhost</command> command to obtain
     1088        information about USB devices on the host system.
     1089      </para>
     1090      <para>
     1091        Use the <option>--capturefile</option> option to specify the
     1092        absolute path of a file in which to write logging data.
     1093      </para>
     1094    </refsect2>
     1095    <refsect2 id="vboxmanage-controlvm-usbdetach">
     1096      <title>Make a Host System USB Device Invisible to a Virtual Machine</title>
     1097      <remark role="help-copy-synopsis"/>
     1098      <para>
     1099        The <command>VBoxManage controlvm
     1100        <replaceable>vmname</replaceable> usbdetach</command> command
     1101        dynamically detaches a host USB device from the VM, which makes
     1102        it invisible. You do not need to create a filter.
     1103      </para>
     1104      <para>
     1105        Specify a USB device by its UUID or by its address on the host
     1106        system. Use the <command>VBoxManage list usbhost</command>
     1107        command to obtain information about USB devices on the host
     1108        system.
     1109      </para>
     1110    </refsect2>
     1111    <refsect2 id="vboxmanage-controlvm-audioin">
     1112      <title>Enable or Disable Audio Capture From the Host System</title>
     1113      <remark role="help-copy-synopsis"/>
     1114      <para>
     1115        The <command>VBoxManage controlvm
     1116        <replaceable>vmname</replaceable> audioin</command> command
     1117        specifies whether to enable or disable audio capture from the
     1118        host system. Valid values are <literal>on</literal>, which
     1119        enables audio capture and <literal>off</literal>, which disables
     1120        audio capture. The default value is <literal>off</literal>.
     1121      </para>
     1122    </refsect2>
     1123    <refsect2 id="vboxmanage-controlvm-audioout">
     1124      <title>Enable or Disable Audio Playback From a Virtual Machine</title>
     1125      <remark role="help-copy-synopsis"/>
     1126      <para>
     1127        The <command>VBoxManage controlvm
     1128        <replaceable>vmname</replaceable> audioout</command> command
     1129        specifies whether to enable or disable audio playback from the
     1130        guest VM. Valid values are <literal>on</literal>, which enables
     1131        audio playback and <literal>off</literal>, which disables audio
     1132        playback. The default value is <literal>off</literal>.
     1133      </para>
     1134    </refsect2>
     1135    <refsect2 id="vboxmanage-controlvm-clipboard-mode">
     1136      <title>Specify How to Share the Host OS or Guest OS Clipboard</title>
     1137      <remark role="help-copy-synopsis"/>
     1138      <para>
     1139        The <command>VBoxManage controlvm
     1140        <replaceable>vmname</replaceable> clipboard mode</command> command
     1141        specifies how to share the guest or host OS's clipboard with the
     1142        host system or VM. Valid values are <literal>disabled</literal>,
     1143        <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
     1144        and <literal>bidirectional</literal>. The default value is
     1145        <literal>disabled</literal>. See
     1146        <xref linkend="generalsettings" />.
     1147      </para>
     1148      <para>
     1149        This feature requires that the &product-name; Guest Additions
     1150        are installed in the VM.
     1151      </para>
     1152    </refsect2>
     1153    <!--
     1154    <refsect2 id="vboxmanage-controlvm-clipboard-filetransfers">
     1155      <title>Specify If Files Can Be Transferred Through the Clipboard</title>
     1156      <remark role="help-copy-synopsis"/>
     1157      <para>
     1158        The <command>VBoxManage controlvm
     1159        <replaceable>vmname</replaceable> clipboard filetransfers</command>
     1160        command specifies if it is possible to transfer files through the
     1161        clipboard between the host and VM, in the direction which is allowed.
     1162        Valid values are <literal>off</literal> and <literal>on</literal>.
     1163        The default value is <literal>off</literal>.
     1164      </para>
     1165      <para>
     1166        This feature requires that the &product-name; Guest Additions
     1167        are installed in the VM.
     1168      </para>
     1169    </refsect2>
     1170    -->
     1171    <refsect2 id="vboxmanage-controlvm-draganddrop">
     1172      <title>Set the Drag and Drop Mode Between the Host System and a Virtual Machine</title>
     1173      <remark role="help-copy-synopsis"/>
     1174      <para>
     1175        The <command>VBoxManage controlvm
     1176        <replaceable>vmname</replaceable> draganddrop</command> command
     1177        specifies the current drag and drop mode to use between the host
     1178        system and the VM. Valid values are <literal>disabled</literal>,
     1179        <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
     1180        and <literal>bidirectional</literal>. The default value is
     1181        <literal>disabled</literal>. See
     1182        <xref linkend="guestadd-dnd" />.
     1183      </para>
     1184      <para>
     1185        This feature requires that the &product-name; Guest Additions
     1186        are installed in the VM.
     1187      </para>
     1188    </refsect2>
     1189    <refsect2 id="vboxmanage-controlvm-vrde">
     1190      <title>Enable or Disable the VRDE Server</title>
     1191      <remark role="help-copy-synopsis"/>
     1192      <para>
     1193        The <command>VBoxManage controlvm
     1194        <replaceable>vmname</replaceable> vrde</command> command enables
     1195        or disables the VirtualBox Remote Desktop Extension (VRDE)
     1196        server, if installed. Valid values are <literal>on</literal> and
     1197        <literal>off</literal>. The default value is
     1198        <literal>off</literal>.
     1199      </para>
     1200    </refsect2>
     1201    <refsect2 id="vboxmanage-controlvm-vrdeport">
     1202      <title>Specify VRDE Server Ports</title>
     1203      <remark role="help-copy-synopsis"/>
     1204      <para>
     1205        The <command>VBoxManage controlvm
     1206        <replaceable>vmname</replaceable> vrdeport</command> command
     1207        specifies the port or range of ports to which the VRDE server
     1208        can bind. The default value is <literal>default</literal> or
     1209        <literal>0</literal>, which is the standard RDP port,
     1210        <literal>3389</literal>.
     1211      </para>
     1212      <para>
     1213        Also see the <option>--vrde-port</option> option description in
     1214        <xref linkend="vboxmanage-modifyvm-vrde" />.
     1215      </para>
     1216    </refsect2>
     1217    <refsect2 id="vboxmanage-controlvm-vrdeproperty">
     1218      <title>Specify VRDE Server Port Numbers and IP Addresses</title>
     1219      <remark role="help-copy-synopsis"/>
     1220      <para>
     1221        The <command>VBoxManage controlvm
     1222        <replaceable>vmname</replaceable> vrdeproperty</command> command
     1223        specifies the port numbers and IP address on the VM to which the
     1224        VRDE server can bind.
     1225      </para>
     1226      <itemizedlist>
     1227        <listitem><para>
     1228            <literal>TCP/Ports</literal> specifies a port or a range of
     1229            ports to which the VRDE server can bind. The default value
     1230            is <literal>default</literal> or <literal>0</literal>, which
     1231            is the standard RDP port, <literal>3389</literal>.
     1232          </para><para>
     1233            Also see the <option>--vrde-port</option> option description
     1234            in <xref linkend="vboxmanage-modifyvm-vrde" />.
     1235          </para></listitem>
     1236        <listitem><para>
     1237            <literal>TCP/Address</literal> specifies the IP address of
     1238            the host network interface to which the VRDE server binds.
     1239            When specified, the server accepts to connect only on the
     1240            specified host network interface.
     1241          </para><para>
     1242            Also see the <option>--vrde-address</option> option
     1243            description in <xref linkend="vboxmanage-modifyvm-vrde" />.
     1244          </para></listitem>
     1245        <listitem><para>
     1246            <literal>VideoChannel/Enabled</literal> specifies whether to
     1247            enable the VirtualBox Remote Desktop Protocol (VRDP) video
     1248            channel. Valid values are <literal>1</literal> to enable the
     1249            video channel and <literal>0</literal> to disable the video
     1250            channel. The default value is <literal>off</literal>. See
     1251            <xref linkend="vrde-videochannel" />.
     1252          </para></listitem>
     1253        <listitem><para>
     1254            <literal>VideoChannel/Quality</literal> specifies the JPEG
     1255            compression level on the VRDE server video channel. Valid
     1256            values are between 10% and 100%, inclusive. Lower values
     1257            mean lower quality but higher compression. The default value
     1258            is <literal>100</literal>. See
     1259            <xref linkend="vrde-videochannel" />.
     1260          </para></listitem>
     1261        <listitem><para>
     1262            <literal>VideoChannel/DownscaleProtection</literal>
     1263            specifies whether to enable the video channel downscale
     1264            protection feature. Specify <literal>1</literal> to enable
     1265            the feature. This feature is disabled by default.
     1266          </para><para>
     1267            When enabled, if the video's size equals the shadow buffer
     1268            size, the video is shown in full-screen mode. If the video's
     1269            size is between full-screen mode and the downscale
     1270            threshold, the video is not shown as it might be an
     1271            application window that is unreadable when downscaled. When
     1272            disabled, the downscale protection feature always attempts
     1273            to show videos.
     1274          </para></listitem>
     1275        <listitem><para>
     1276            <literal>Client/DisableDisplay</literal> specifies whether
     1277            to disable the VRDE server display feature. Valid values are
     1278            <literal>1</literal> to disable the feature and null
     1279            (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
     1280            The default value is null. See
     1281            <xref linkend="vrde-customization"/>.
     1282          </para></listitem>
     1283        <listitem><para>
     1284            <literal>Client/DisableInput</literal> specifies whether to
     1285            disable the VRDE server input feature. Valid values are
     1286            <literal>1</literal> to disable the feature and null
     1287            (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
     1288            The default value is <literal>1</literal>. See
     1289            <xref linkend="vrde-customization"/>.
     1290          </para></listitem>
     1291        <listitem><para>
     1292            <literal>Client/DisableAudio</literal> specifies whether to
     1293            disable the VRDE server audio feature. Valid values are
     1294            <literal>1</literal> to disable the feature and null
     1295            (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
     1296            The default value is <literal>1</literal>. See
     1297            <xref linkend="vrde-customization"/>.
     1298          </para></listitem>
     1299        <listitem><para>
     1300            <literal>Client/DisableUSB</literal> specifies whether to
     1301            disable the VRDE server USB feature. Valid values are
     1302            <literal>1</literal> to disable the feature and null
     1303            (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
     1304            The default value is <literal>1</literal>. See
     1305            <xref linkend="vrde-customization"/>.
     1306          </para></listitem>
     1307        <listitem><para>
     1308            <literal>Client/DisableClipboard</literal> specifies whether
     1309            to disable the VRDE clipboard feature. Valid values are
     1310            <literal>1</literal> to disable the feature and null
     1311            (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
     1312            To reenable the feature, use
     1313            <literal>Client/DisableClipboard=</literal>. The default
     1314            value is <literal>1</literal>. See
     1315            <xref linkend="vrde-customization"/>.
     1316          </para></listitem>
     1317        <listitem><para>
     1318            <literal>Client/DisableUpstreamAudio</literal> specifies
     1319            whether to disable the VRDE upstream audio feature. Valid
     1320            values are <literal>1</literal> to disable the feature and
     1321            null (<literal>&ldquo;&rdquo;</literal>) to enable the
     1322            feature. To reenable the feature, use
     1323            <literal>Client/DisableUpstreamAudio=</literal>. The default
     1324            value is <literal>1</literal>. See
     1325            <xref linkend="vrde-customization"/>.
     1326          </para></listitem>
     1327        <listitem><para>
     1328            <literal>Client/DisableRDPDR</literal> specifies whether to
     1329            disable the RDP Device Redirection For Smart Cards feature
     1330            on the VRDE server. Valid values are <literal>1</literal> to
     1331            disable the feature and null
     1332            (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
     1333            The default value is <literal>1</literal>. See
     1334            <xref linkend="vrde-customization"/>.
     1335          </para></listitem>
     1336        <listitem><para>
     1337            <literal>H3DRedirect/Enabled</literal> specifies whether to
     1338            enable the VRDE server 3D redirection feature. Valid values
     1339            are <literal>1</literal> to enable the feature and null
     1340            (<literal>&ldquo;&rdquo;</literal>) to disable the feature.
     1341            See <xref linkend="vrde-customization"/>.
     1342          </para></listitem>
     1343        <listitem><para>
     1344            <literal>Security/Method</literal> specifies the security
     1345            method to use for a connection. See
     1346            <xref linkend="vrde-crypt" />.
     1347          </para><itemizedlist>
     1348            <listitem><para>
     1349                <literal>Negotiate</literal> accepts both enhanced (TLS)
     1350                and standard RDP security connections. The security
     1351                method is negotiated with the client. This is the
     1352                default value.
     1353              </para></listitem>
     1354            <listitem><para>
     1355                <literal>RDP</literal> accepts only standard RDP
     1356                security connections.
     1357              </para></listitem>
     1358            <listitem><para>
     1359                <literal>TLS</literal> accepts only enhanced RDP
     1360                security connections. The client must support TLS.
     1361              </para></listitem>
     1362          </itemizedlist></listitem>
     1363        <listitem><para>
     1364            <literal>Security/ServerCertificate</literal> specifies the
     1365            absolute path of the server certificate to use for a
     1366            connection. See <xref linkend="vrde-crypt" />.
     1367          </para></listitem>
     1368        <listitem><para>
     1369            <literal>Security/ServerPrivateKey</literal> specifies the
     1370            absolute path of the server private key. See
     1371            <xref linkend="vrde-crypt" />.
     1372          </para></listitem>
     1373        <listitem><para>
     1374            <literal>Security/CACertificate</literal> specifies the
     1375            absolute path of the CA self-signed certificate. See
     1376            <xref linkend="vrde-crypt" />.
     1377          </para></listitem>
     1378        <listitem><para>
     1379            <literal>Audio/RateCorrectionMode</literal> specifies the
     1380            rate correction mode to use.
     1381          </para><itemizedlist>
     1382            <listitem><para>
     1383                <literal>VRDP_AUDIO_MODE_VOID</literal> indicates that
     1384                no mode is specified. Use this value to unset any audio
     1385                mode that is already set.
     1386              </para></listitem>
     1387            <listitem><para>
     1388                <literal>VRDP_AUDIO_MODE_RC</literal> specifies to use
     1389                the rate correction mode.
     1390              </para></listitem>
     1391            <listitem><para>
     1392                <literal>VRDP_AUDIO_MODE_LPF</literal> specifies to use
     1393                the low pass filter mode.
     1394              </para></listitem>
     1395            <listitem><para>
     1396                <literal>VRDP_AUDIO_MODE_CS</literal> specifies to use
     1397                the client sync mode to prevent underflow or overflow of
     1398                the client queue.
     1399              </para></listitem>
     1400          </itemizedlist></listitem>
     1401        <listitem><para>
     1402            <literal>Audio/LogPath</literal> specifies the absolute path
     1403            of the audio log file.
     1404          </para></listitem>
     1405      </itemizedlist>
     1406    </refsect2>
     1407    <refsect2 id="vboxmanage-controlvm-vrdevideochannelquality">
     1408      <title>Specify the Image Quality for VRDP Video Redirection</title>
     1409      <remark role="help-copy-synopsis"/>
     1410      <para>
     1411        The <command>VBoxManage controlvm
     1412        <replaceable>vmname</replaceable>
     1413        vrdevideochannelquality</command> command sets the image
     1414        quality, as a JPEG compression level value, for video
     1415        redirection. Valid values are between 10% and 100%, inclusive.
     1416        Lower values mean lower quality but higher compression. See
     1417        <xref linkend="vrde-videochannel" />.
     1418      </para>
     1419    </refsect2>
     1420    <refsect2 id="vboxmanage-controlvm-setvideomodehint">
     1421      <title>Specify the Video Mode for the Guest VM</title>
     1422      <remark role="help-copy-synopsis"/>
     1423      <para>
     1424        The <command>VBoxManage controlvm
     1425        <replaceable>vmname</replaceable> setvideomodehint</command>
     1426        command specifies the video mode for the guest VM to use. You
     1427        must have the &product-name; Guest Additions installed. Note
     1428        that this feature does not work for all guest systems.
     1429      </para>
     1430    </refsect2>
     1431    <refsect2 id="vboxmanage-controlvm-setscreenlayout">
     1432      <title>Specify the Screen Layout for a Display on the Guest VM</title>
     1433      <remark role="help-copy-synopsis"/>
     1434      <para>
     1435        The <command>VBoxManage controlvm
     1436        <replaceable>vmname</replaceable> setscreenlayout</command>
     1437        command can be used to configure multiscreen displays. The
     1438        specified screen on the guest VM can be enabled or disabled, or
     1439        a custom screen layout can be configured.
     1440      </para>
     1441    </refsect2>
     1442    <refsect2 id="vboxmanage-controlvm-screenshotpng">
     1443      <title>Take a Screen Shot of the Virtual Machine Display</title>
     1444      <remark role="help-copy-synopsis"/>
     1445      <para>
     1446        The <command>VBoxManage controlvm
     1447        <replaceable>vmname</replaceable> screenshotpng</command>
     1448        command takes a screenshot of the guest display and saves it as
     1449        PNG in the specified file.
     1450      </para>
     1451      <itemizedlist>
     1452        <listitem><para>
     1453            <replaceable>filename</replaceable> specifies the name of
     1454            the PNG file to create.
     1455          </para></listitem>
     1456        <listitem><para>
     1457            <replaceable>display</replaceable> specifies the display
     1458            number for the screen shot. For a single monitor guest
     1459            display, this is <literal>0</literal>.
     1460          </para></listitem>
     1461      </itemizedlist>
     1462    </refsect2>
     1463    <refsect2 id="vboxmanage-controlvm-recording">
     1464      <title>Enable or Disable the Recording of a Virtual Machine Session</title>
     1465      <remark role="help-copy-synopsis"/>
     1466      <para>
     1467        The <command>VBoxManage controlvm
     1468        <replaceable>vmname</replaceable> recording</command> command
     1469        enables or disables the recording of a VM session into a
     1470        WebM/VP8 file. Valid values are <literal>on</literal>, which
     1471        begins recording when the VM session starts and
     1472        <literal>off</literal>, which disables recording. The default
     1473        value is <literal>off</literal>.
     1474      </para>
     1475    </refsect2>
     1476    <refsect2 id="vboxmanage-controlvm-recording-screens">
     1477      <title>Specify the Virtual Machine Screens to Record</title>
     1478      <remark role="help-copy-synopsis"/>
     1479      <para>
     1480        The <command>VBoxManage controlvm
     1481        <replaceable>vmname</replaceable> recording screens</command>
     1482        command enables you to specify which VM screens to record. The
     1483        recording for each screen that you specify is saved to its own
     1484        file in the machine folder. You cannot modify this setting while
     1485        recording is enabled.
     1486      </para>
     1487      <itemizedlist>
     1488        <listitem><para>
     1489            <literal>all</literal> specifies that you record all VM
     1490            screens.
     1491          </para></listitem>
     1492        <listitem><para>
     1493            <literal>none</literal> specifies that you do not record any
     1494            VM screens.
     1495          </para></listitem>
     1496        <listitem><para>
     1497            <replaceable>screen-ID</replaceable> specifies one or more
     1498            VM screens to record.
     1499          </para></listitem>
     1500      </itemizedlist>
     1501    </refsect2>
     1502    <refsect2 id="vboxmanage-controlvm-recording-filename">
     1503      <title>Specify the File in Which to Save Virtual Machine Recording</title>
     1504      <remark role="help-copy-synopsis"/>
     1505      <para>
     1506        The <command>VBoxManage controlvm
     1507        <replaceable>vmname</replaceable> recording filename</command>
     1508        command specifies the file in which to save the recording. You
     1509        cannot modify this setting while recording is enabled.
     1510      </para>
     1511      <para>
     1512        The default setting is to store a recording in the machine
     1513        folder, using the VM name as the file name, with a
     1514        <filename>webm</filename> file name extension.
     1515      </para>
     1516    </refsect2>
     1517    <refsect2 id="vboxmanage-controlvm-recording-videores">
     1518      <title>Specify the Resolution of the Recorded Video</title>
     1519      <remark role="help-copy-synopsis"/>
     1520      <para>
     1521        <command>VBoxManage controlvm <replaceable>vmname</replaceable>
     1522        recording videores</command> command specifies the resolution of
     1523        the recorded video in pixels. You cannot modify this setting
     1524        while recording is enabled.
     1525      </para>
     1526      <para>
     1527        Use the Settings tool to view the video recording settings,
     1528        which are based on the resolution (frame size). See the Frame
     1529        Size field on the Recording tab of the Display page to view the
     1530        default value.
     1531      </para>
     1532      <para>
     1533        Specify the resolution as
     1534        <replaceable>width</replaceable><literal>x</literal><replaceable>height</replaceable>:
     1535      </para>
     1536      <itemizedlist>
     1537        <listitem><para>
     1538            <replaceable>width</replaceable> specifies the width in
     1539            pixels.
     1540          </para></listitem>
     1541        <listitem><para>
     1542            <replaceable>height</replaceable> specifies the height in
     1543            pixels.
     1544          </para></listitem>
     1545      </itemizedlist>
     1546    </refsect2>
     1547    <refsect2 id="vboxmanage-controlvm-recording-videorate">
     1548      <title>Specify the Bit Rate of the Video</title>
     1549      <remark role="help-copy-synopsis"/>
     1550<!-- @todo r=andy Clarify rate. -->
     1551      <para>
     1552        The <command>VBoxManage controlvm
     1553        <replaceable>vmname</replaceable> recording videorate</command>
     1554        command specifies the bit rate,
     1555        <replaceable>bit-rate</replaceable>, of the video in kilobits
     1556        per second. Increasing this value improves the appearance of the
     1557        video at the cost of an increased file size. You cannot modify
     1558        this setting while recording is enabled.
     1559      </para>
     1560      <para>
     1561        Use the Settings tool to view the video recording settings,
     1562        which are based on the frame size. See the Video Quality field
     1563        on the Recording tab of the Display page to view the default
     1564        value.
     1565      </para>
     1566    </refsect2>
     1567    <refsect2 id="vboxmanage-controlvm-recording-videofps">
     1568      <title>Specify the Maximum Frequency of the Video</title>
     1569      <remark role="help-copy-synopsis"/>
     1570      <para>
     1571        The <command>VBoxManage controlvm
     1572        <replaceable>vmname</replaceable> recording videofps</command>
     1573        command specifies the maximum frequency of the video to record.
     1574        Video frequency is measured in frames per second (FPS). The
     1575        recording skips any frames that have a frequency higher than the
     1576        specified maximum. Increasing the frequency reduces the number
     1577        of skipped frames and increases the file size. You cannot modify
     1578        this setting while recording is enabled.
     1579      </para>
     1580      <para>
     1581        Use the Settings tool to view the video recording settings,
     1582        which are based on the frame size. See the Frame Rate field on
     1583        the Recording tab of the Display page to view the default value.
     1584      </para>
     1585    </refsect2>
     1586    <refsect2 id="vboxmanage-controlvm-recording-maxtime">
     1587      <title>Specify the Maximum Amount of Time to Record Video</title>
     1588      <remark role="help-copy-synopsis"/>
     1589<!-- @todo r=andy Clarify time format. -->
     1590      <para>
     1591        The <command>VBoxManage controlvm
     1592        <replaceable>vmname</replaceable> recording maxtime</command>
     1593        command specifies the maximum amount time to record in seconds.
     1594        The recording stops after the specified number of seconds
     1595        elapses. If this value is zero, the recording continues until
     1596        you stop the recording.
     1597      </para>
     1598    </refsect2>
     1599    <refsect2 id="vboxmanage-controlvm-recording-maxfilesize">
     1600      <title>Specify the Maximum Size of the Recorded Video</title>
     1601      <remark role="help-copy-synopsis"/>
     1602      <para>
     1603        The <command>VBoxManage controlvm
     1604        <replaceable>vmname</replaceable> recording
     1605        maxfilesize</command> command specifies the maximum size of the
     1606        recorded video file in megabytes. The recording stops when the
     1607        file reaches the specified size. If this value is zero, the
     1608        recording continues until you stop the recording. You cannot
     1609        modify this setting while recording is enabled.
     1610      </para>
     1611    </refsect2>
     1612    <!--
     1613    <refsect2 id="vboxmanage-controlvm-recording-opts">
     1614      <title>Specify Custom Options for Recording Video and/or Audio</title>
     1615      <remark role="help-copy-synopsis"/>
     1616      <para>
     1617        The <command>VBoxManage controlvm
     1618        <replaceable>vmname</replaceable> recording
     1619        opts</command> command specifies additional recording options
     1620        in a comma-separated keyword-value format. For example,
     1621        <computeroutput>foo=bar,a=b</computeroutput>. You cannot
     1622        modify this setting while recording is enabled.
     1623      </para>
     1624      <para>
     1625        Use this option if you are an advanced user only. For
     1626        information about keywords, see <emphasis>&product-name;
     1627        Programming Guide and Reference</emphasis>.
     1628      </para>
     1629    </refsect2>
     1630    -->
     1631    <refsect2 id="vboxmanage-controlvm-setcredentials">
     1632      <title>Specify Credentials for Remote Logins on Windows Virtual Machines</title>
     1633      <remark role="help-copy-synopsis"/>
     1634      <para>
     1635        The <command>setcredentials</command> command enables you to
     1636        specify the credentials for remotely logging in to Windows VMs.
     1637        See <xref linkend="autologon" />.
     1638      </para>
     1639      <itemizedlist>
     1640        <listitem><para>
     1641            <replaceable>username</replaceable> specifies the user name
     1642            with which to log in to the Windows VM.
     1643          </para></listitem>
     1644        <listitem><para>
     1645            <option>--passwordfile=<replaceable>filename</replaceable></option>
     1646            specifies the file from which to obtain the password for
     1647            <replaceable>username</replaceable>.
     1648          </para><para>
     1649            The <option>--passwordfile</option> is mutually exclusive
     1650            with the <option>--password</option> option.
     1651          </para></listitem>
     1652        <listitem><para>
     1653            <option>--password=<replaceable>password</replaceable></option>
     1654            specifies the password for
     1655            <replaceable>username</replaceable>.
     1656          </para><remark>
     1657            This design does not conform to Oracle's security
     1658            guidelines. You should not be able to specify a password on
     1659            the command line because the password can be seen in a
     1660            process listing.
     1661          </remark><para>
     1662            The <option>--password</option> is mutually exclusive with
     1663            the <option>--passwordfile</option> option.
     1664          </para></listitem>
     1665        <listitem><para>
     1666            <option>--allowlocallogin</option> specifies whether to
     1667            enable or disable local logins. Valid values are
     1668            <literal>on</literal> to enable local logins and
     1669            <literal>off</literal> to disable local logins.
     1670          </para></listitem>
     1671      </itemizedlist>
    8851672    </refsect2>
    8861673    <refsect2 id="vboxmanage-controlvm-teleport">
    … …  
    9541741      </variablelist>
    9551742    </refsect2>
    956     <refsect2 id="vboxmanage-controlvm-setlinkstate">
    957       <title>Set the Link State for a Virtual Machine</title>
    958       <remark role="help-copy-synopsis"/>
    959       <para>
    960         <command>VBoxManage controlvm <replaceable>vmname</replaceable>
    961         setlinkstate<replaceable>N</replaceable></command> command
    962         enables you to connect or disconnect the virtual network cable
    963         from the network interface instance
    964         (<replaceable>N</replaceable>). Valid values are
    965         <literal>on</literal> and <literal>off</literal>. The default
    966         value is <literal>on</literal>.
    967       </para>
    968       <para>
    969         Before connecting the virtual network cable, use the
    970         <command>VBoxManage controlvm
    971         nictracefile<replaceable>N</replaceable></command> command at
    972         runtime to specify the name of the file in which to log the
    973         trace. Otherwise, use the <command>VBoxManage modifyvm
    974         --nic-trace-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></command>
    975         command to specify the name of the file.
    976       </para>
    977       <para>
    978         This subcommand does not affect the VM's running state directly.
    979       </para>
    980     </refsect2>
    981     <refsect2 id="vboxmanage-controlvm-nic">
    982       <title>Set the Type of Networking to Use for a Virtual Machine</title>
    983       <remark role="help-copy-synopsis"/>
    984       <para>
    985         The <command>VBoxManage controlvm
    986         <replaceable>vmname</replaceable>
    987         nic<replaceable>N</replaceable></command> command specifies the
    988         type of networking to use on the specified VM's virtual network
    989         card. <replaceable>N</replaceable> numbering begins with
    990         <literal>1</literal>.
    991       </para>
    992       <para>
    993         The following valid network types are also described in
    994         <xref linkend="networkingmodes" />:
    995       </para>
    996       <itemizedlist>
    997         <listitem><para>
    998             <literal>null</literal> specifies that the VM is is not
    999             connected to the host system.
    1000           </para></listitem>
    1001         <listitem><para>
    1002             <literal>nat</literal> specifies that the VM uses network
    1003             address translation (NAT).
    1004           </para></listitem>
    1005         <listitem><para>
    1006             <literal>bridged</literal> specifies that the VM uses
    1007             bridged networking.
    1008           </para></listitem>
    1009         <listitem><para>
    1010             <literal>intnet</literal> specifies that the VM communicates
    1011             with other VMs by using internal networking.
    1012           </para></listitem>
    1013         <listitem><para>
    1014             <literal>hostonly</literal> specifies that the VM uses
    1015             host-only networking.
    1016           </para></listitem>
    1017         <listitem><para>
    1018             <literal>natnetwork</literal> specifies that the VM uses NAT
    1019             networking.
    1020           </para></listitem>
    1021         <listitem><para>
    1022             <literal>generic</literal> specifies that the VM has access
    1023             to rarely used submodes
    1024           </para></listitem>
    1025       </itemizedlist>
    1026       <para>
    1027         This subcommand does not affect the VM's running state directly.
    1028       </para>
    1029     </refsect2>
    1030     <refsect2 id="vboxmanage-controlvm-nictrace">
    1031       <title>Trace the Network Traffic of a Virtual Machine</title>
    1032       <remark role="help-copy-synopsis"/>
    1033       <para>
    1034         The <command>VBoxManage controlvm
    1035         <replaceable>vmname</replaceable>
    1036         nictrace<replaceable>N</replaceable></command> command enables
    1037         you to trace the network traffic on the specified virtual
    1038         network card (<replaceable>N</replaceable>).
    1039         <replaceable>N</replaceable> numbering begins with
    1040         <literal>1</literal>. Valid values are <literal>on</literal> and
    1041         <literal>off</literal>. The default value is
    1042         <literal>off</literal>.
    1043       </para>
    1044       <para>
    1045         When set to <literal>on</literal>, use the same value of
    1046         <replaceable>N</replaceable> for the <command>VBoxManage
    1047         controlvm <replaceable>vmname</replaceable>
    1048         nictracefile<replaceable>N</replaceable></command> command that
    1049         you use to specify the path name to the log file in which to
    1050         write trace output.
    1051       </para>
    1052       <para>
    1053         This subcommand does not affect the VM's running state directly.
    1054       </para>
    1055     </refsect2>
    1056     <refsect2 id="vboxmanage-controlvm-nictracefile">
    1057       <title>Specify the Network Traffic Trace Log File for a Virtual Machine</title>
    1058       <remark role="help-copy-synopsis"/>
    1059       <para>
    1060         The <command>VBoxManage controlvm
    1061         <replaceable>vmname</replaceable>
    1062         nictracefile<replaceable>N</replaceable></command> command
    1063         enables you to specify the name of the network traffic trace log
    1064         file for the specified virtual network card
    1065         (<replaceable>N</replaceable>). <replaceable>N</replaceable>
    1066         numbering begins with <literal>1</literal>. Ensure that you use
    1067         the same value of <replaceable>N</replaceable> as you used for
    1068         the <command>VBoxManage controlvm
    1069         <replaceable>vmname</replaceable>
    1070         nic<replaceable>N</replaceable></command> and
    1071         <command>VBoxManage controlvm <replaceable>vmname</replaceable>
    1072         nictrace<replaceable>N</replaceable></command> commands.
    1073       </para>
    1074       <para>
    1075         This subcommand does not affect the VM's running state directly.
    1076       </para>
    1077     </refsect2>
    1078     <refsect2 id="vboxmanage-controlvm-nicpromisc">
    1079       <title>Specify the Promiscuous Mode to Use for a Virtual Machine</title>
    1080       <remark role="help-copy-synopsis"/>
    1081       <para>
    1082         The <command>VBoxManage controlvm
    1083         <replaceable>vmname</replaceable>
    1084         nicpromisc<replaceable>N</replaceable></command> command enables
    1085         you to specify how to handle promiscuous mode for a bridged
    1086         network. The default value of <literal>deny</literal> hides any
    1087         traffic that is not intended for this VM. The
    1088         <literal>allow-vms</literal> value hides all host traffic from
    1089         this VM but enables the VM to see traffic to and from other VMs.
    1090         The <literal>allow-all</literal> value removes this restriction
    1091         completely.
    1092       </para>
    1093       <para>
    1094         This subcommand does not affect the VM's running state directly.
    1095       </para>
    1096     </refsect2>
    1097     <refsect2 id="vboxmanage-controlvm-nicproperty">
    1098       <title>Specify the Network Backend Property Values for a Virtual Machine</title>
    1099       <remark role="help-copy-synopsis"/>
    1100       <para>
    1101         The <command>VBoxManage controlvm
    1102         <replaceable>vmname</replaceable>
    1103         nicproperty<replaceable>N</replaceable>
    1104         <replaceable>prop-name</replaceable>="<replaceable>prop-value</replaceable>"</command>
    1105         command, in combination with <literal>nicgenericdrv</literal>,
    1106         enables you to pass property values to rarely-used network
    1107         backends.
    1108       </para>
    1109       <para>
    1110         Those properties are backend engine-specific, and are different
    1111         between UDP Tunnel and the VDE backend drivers. See
    1112         <xref linkend="network_udp_tunnel" />.
    1113       </para>
    1114       <para>
    1115         This subcommand does not affect the VM's running state directly.
    1116       </para>
    1117     </refsect2>
    1118     <refsect2 id="vboxmanage-controlvm-natpf">
    1119       <title>Specify a NAT Port Forwarding Rule for a Virtual Machine</title>
    1120       <remark role="help-copy-synopsis"/>
    1121       <para>
    1122         The <command>VBoxManage controlvm
    1123         <replaceable>vmname</replaceable>
    1124         natpf<replaceable>N</replaceable></command> command specifies a
    1125         NAT port-forwarding rule. See <xref linkend="natforward"/>.
    1126       </para>
    1127       <para>
    1128         This subcommand does not affect the VM's running state directly.
    1129       </para>
    1130     </refsect2>
    1131     <refsect2 id="vboxmanage-controlvm-natpf-delete">
    1132       <title>Delete a NAT Port Forwarding Rule for a Virtual Machine</title>
    1133       <remark role="help-copy-synopsis"/>
    1134       <para>
    1135         The <command>VBoxManage controlvm
    1136         <replaceable>vmname</replaceable>
    1137         natpf<replaceable>N</replaceable> delete</command> deletes the
    1138         specified NAT port-forwarding rule. See
    1139         <xref linkend="natforward"/>.
    1140       </para>
    1141       <para>
    1142         This subcommand does not affect the VM's running state directly.
    1143       </para>
    1144     </refsect2>
    1145     <refsect2 id="vboxmanage-controlvm-guestmemoryballoon">
    1146       <title>Change Size of a Virtual Machine's Guest Memory Balloon</title>
    1147       <remark role="help-copy-synopsis"/>
    1148       <para>
    1149         The <command>VBoxManage controlvm
    1150         <replaceable>vmname</replaceable> guestmemoryballoon</command>
    1151         command changes the size of the guest memory balloon. The guest
    1152         memory balloon is the memory allocated by the &product-name;
    1153         Guest Additions from the guest OS and returned to the hypervisor
    1154         for reuse by other VMs. The value you specify is in megabytes.
    1155         See <xref linkend="guestadd-balloon" />.
    1156       </para>
    1157       <para>
    1158         This subcommand does not affect the VM's running state directly.
    1159       </para>
    1160     </refsect2>
    1161     <refsect2 id="vboxmanage-controlvm-usbattach">
    1162       <title>Make a Host System USB Device Visible to a Virtual Machine</title>
    1163       <remark role="help-copy-synopsis"/>
    1164       <para>
    1165         The <command>VBoxManage controlvm
    1166         <replaceable>vmname</replaceable> usbattach</command> command
    1167         dynamically attaches a host USB device to the VM, which makes it
    1168         visible. You do not need to create a filter.
    1169       </para>
    1170       <para>
    1171         Specify a USB device by its Universally Unique Identifier (UUID)
    1172         or by its address on the host system. Use the
    1173         <command>VBoxManage list usbhost</command> command to obtain
    1174         information about USB devices on the host system.
    1175       </para>
    1176       <para>
    1177         Use the <option>--capturefile</option> option to specify the
    1178         absolute path of a file in which to write logging data.
    1179       </para>
    1180       <para>
    1181         This subcommand does not affect the VM's running state directly.
    1182       </para>
    1183     </refsect2>
    1184     <refsect2 id="vboxmanage-controlvm-usbdetach">
    1185       <title>Make a Host System USB Device Invisible to a Virtual Machine</title>
    1186       <remark role="help-copy-synopsis"/>
    1187       <para>
    1188         The <command>VBoxManage controlvm
    1189         <replaceable>vmname</replaceable> usbdetach</command> command
    1190         dynamically detaches a host USB device from the VM, which makes
    1191         it invisible. You do not need to create a filter.
    1192       </para>
    1193       <para>
    1194         Specify a USB device by its UUID or by its address on the host
    1195         system. Use the <command>VBoxManage list usbhost</command>
    1196         command to obtain information about USB devices on the host
    1197         system.
    1198       </para>
    1199       <para>
    1200         This subcommand does not affect the VM's running state directly.
    1201       </para>
    1202     </refsect2>
    1203     <refsect2 id="vboxmanage-controlvm-audioin">
    1204       <title>Enable or Disable Audio Capture From the Host System</title>
    1205       <remark role="help-copy-synopsis"/>
    1206       <para>
    1207         The <command>VBoxManage controlvm
    1208         <replaceable>vmname</replaceable> audioin</command> command
    1209         specifies whether to enable or disable audio capture from the
    1210         host system. Valid values are <literal>on</literal>, which
    1211         enables audio capture and <literal>off</literal>, which disables
    1212         audio capture. The default value is <literal>off</literal>.
    1213       </para>
    1214       <para>
    1215         This subcommand does not affect the VM's running state directly.
    1216       </para>
    1217     </refsect2>
    1218     <refsect2 id="vboxmanage-controlvm-audioout">
    1219       <title>Enable or Disable Audio Playback From a Virtual Machine</title>
    1220       <remark role="help-copy-synopsis"/>
    1221       <para>
    1222         The <command>VBoxManage controlvm
    1223         <replaceable>vmname</replaceable> audioout</command> command
    1224         specifies whether to enable or disable audio playback from the
    1225         guest VM. Valid values are <literal>on</literal>, which enables
    1226         audio playback and <literal>off</literal>, which disables audio
    1227         playback. The default value is <literal>off</literal>.
    1228       </para>
    1229       <para>
    1230         This subcommand does not affect the VM's running state directly.
    1231       </para>
    1232     </refsect2>
    1233     <refsect2 id="vboxmanage-controlvm-clipboard">
    1234       <title>Specify How to Share The Host OS or Guest OS Clipboard</title>
    1235       <remark role="help-copy-synopsis"/>
    1236       <para>
    1237         The <command>VBoxManage controlvm
    1238         <replaceable>vmname</replaceable> clipboard</command> command
    1239         specifies how to share the guest or host OS's clipboard with the
    1240         host system or VM. Valid values are <literal>disabled</literal>,
    1241         <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
    1242         and <literal>bidirectional</literal>. The default value is
    1243         <literal>disabled</literal>. See
    1244         <xref linkend="generalsettings" />.
    1245       </para>
    1246       <para>
    1247         This feature requires that the &product-name; Guest Additions
    1248         are installed in the VM.
    1249       </para>
    1250       <para>
    1251         This subcommand does not affect the VM's running state directly.
    1252       </para>
    1253     </refsect2>
    1254     <refsect2 id="vboxmanage-controlvm-draganddrop">
    1255       <title>Set the Drag and Drop Mode Between the Host System and a Virtual Machine</title>
    1256       <remark role="help-copy-synopsis"/>
    1257       <para>
    1258         The <command>VBoxManage controlvm
    1259         <replaceable>vmname</replaceable> draganddrop</command> command
    1260         specifies the current drag and drop mode to use between the host
    1261         system and the VM. Valid values are <literal>disabled</literal>,
    1262         <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
    1263         and <literal>bidirectional</literal>. The default value is
    1264         <literal>disabled</literal>. See
    1265         <xref linkend="guestadd-dnd" />.
    1266       </para>
    1267       <para>
    1268         This feature requires that the &product-name; Guest Additions
    1269         are installed in the VM.
    1270       </para>
    1271       <para>
    1272         This subcommand does not affect the VM's running state directly.
    1273       </para>
    1274     </refsect2>
    1275     <refsect2 id="vboxmanage-controlvm-vrde">
    1276       <title>Enable or Disable the VRDE Server</title>
    1277       <remark role="help-copy-synopsis"/>
    1278       <para>
    1279         The <command>VBoxManage controlvm
    1280         <replaceable>vmname</replaceable> vrde</command> command enables
    1281         or disables the VirtualBox Remote Desktop Extension (VRDE)
    1282         server, if installed. Valid values are <literal>on</literal> and
    1283         <literal>off</literal>. The default value is
    1284         <literal>off</literal>.
    1285       </para>
    1286       <para>
    1287         This subcommand does not affect the VM's running state directly.
    1288       </para>
    1289     </refsect2>
    1290     <refsect2 id="vboxmanage-controlvm-vrdeport">
    1291       <title>Specify VRDE Server Ports</title>
    1292       <remark role="help-copy-synopsis"/>
    1293       <para>
    1294         The <command>VBoxManage controlvm
    1295         <replaceable>vmname</replaceable> vrdeport</command> command
    1296         specifies the port or range of ports to which the VRDE server
    1297         can bind. The default value is <literal>default</literal> or
    1298         <literal>0</literal>, which is the standard RDP port,
    1299         <literal>3389</literal>.
    1300       </para>
    1301       <para>
    1302         Also see the <option>--vrde-port</option> option description in
    1303         <xref linkend="vboxmanage-modifyvm" />.
    1304       </para>
    1305       <para>
    1306         This subcommand does not affect the VM's running state directly.
    1307       </para>
    1308     </refsect2>
    1309     <refsect2 id="vboxmanage-controlvm-vrdeproperty">
    1310       <title>Specify VRDE Server Port Numbers and IP Addresses</title>
    1311       <remark role="help-copy-synopsis"/>
    1312       <para>
    1313         The <command>VBoxManage controlvm
    1314         <replaceable>vmname</replaceable> vrdeproperty</command> command
    1315         specifies the port numbers and IP address on the VM to which the
    1316         VRDE server can bind.
    1317       </para>
    1318       <para>
    1319         This subcommand does not affect the VM's running state directly.
    1320       </para>
    1321       <itemizedlist>
    1322         <listitem><para>
    1323             <literal>TCP/Ports</literal> specifies a port or a range of
    1324             ports to which the VRDE server can bind. The default value
    1325             is <literal>default</literal> or <literal>0</literal>, which
    1326             is the standard RDP port, <literal>3389</literal>.
    1327           </para><para>
    1328             Also see the <option>--vrde-port</option> option description
    1329             in <xref linkend="vboxmanage-modifyvm" />.
    1330           </para></listitem>
    1331         <listitem><para>
    1332             <literal>TCP/Address</literal> specifies the IP address of
    1333             the host network interface to which the VRDE server binds.
    1334             When specified, the server accepts to connect only on the
    1335             specified host network interface.
    1336           </para><para>
    1337             Also see the <option>--vrde-address</option> option
    1338             description in <xref linkend="vboxmanage-modifyvm" />.
    1339           </para></listitem>
    1340         <listitem><para>
    1341             <literal>VideoChannel/Enabled</literal> specifies whether to
    1342             enable the VirtualBox Remote Desktop Protocol (VRDP) video
    1343             channel. Valid values are <literal>1</literal> to enable the
    1344             video channel and <literal>0</literal> to disable the video
    1345             channel. The default value is <literal>off</literal>. See
    1346             <xref linkend="vrde-videochannel" />.
    1347           </para></listitem>
    1348         <listitem><para>
    1349             <literal>VideoChannel/Quality</literal> specifies the JPEG
    1350             compression level on the VRDE server video channel. Valid
    1351             values are between 10% and 100%, inclusive. Lower values
    1352             mean lower quality but higher compression. The default value
    1353             is <literal>100</literal>. See
    1354             <xref linkend="vrde-videochannel" />.
    1355           </para></listitem>
    1356         <listitem><para>
    1357             <literal>VideoChannel/DownscaleProtection</literal>
    1358             specifies whether to enable the video channel downscale
    1359             protection feature. Specify <literal>1</literal> to enable
    1360             the feature. This feature is disabled by default.
    1361           </para><para>
    1362             When enabled, if the video's size equals the shadow buffer
    1363             size, the video is shown in full-screen mode. If the video's
    1364             size is between full-screen mode and the downscale
    1365             threshold, the video is not shown as it might be an
    1366             application window that is unreadable when downscaled. When
    1367             disabled, the downscale protection feature always attempts
    1368             to show videos.
    1369           </para></listitem>
    1370         <listitem><para>
    1371             <literal>Client/DisableDisplay</literal> specifies whether
    1372             to disable the VRDE server display feature. Valid values are
    1373             <literal>1</literal> to disable the feature and null
    1374             (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
    1375             The default value is null. See
    1376             <xref linkend="vrde-customization"/>.
    1377           </para></listitem>
    1378         <listitem><para>
    1379             <literal>Client/DisableInput</literal> specifies whether to
    1380             disable the VRDE server input feature. Valid values are
    1381             <literal>1</literal> to disable the feature and null
    1382             (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
    1383             The default value is <literal>1</literal>. See
    1384             <xref linkend="vrde-customization"/>.
    1385           </para></listitem>
    1386         <listitem><para>
    1387             <literal>Client/DisableAudio</literal> specifies whether to
    1388             disable the VRDE server audio feature. Valid values are
    1389             <literal>1</literal> to disable the feature and null
    1390             (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
    1391             The default value is <literal>1</literal>. See
    1392             <xref linkend="vrde-customization"/>.
    1393           </para></listitem>
    1394         <listitem><para>
    1395             <literal>Client/DisableUSB</literal> specifies whether to
    1396             disable the VRDE server USB feature. Valid values are
    1397             <literal>1</literal> to disable the feature and null
    1398             (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
    1399             The default value is <literal>1</literal>. See
    1400             <xref linkend="vrde-customization"/>.
    1401           </para></listitem>
    1402         <listitem><para>
    1403             <literal>Client/DisableClipboard</literal> specifies whether
    1404             to disable the VRDE clipboard feature. Valid values are
    1405             <literal>1</literal> to disable the feature and null
    1406             (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
    1407             To reenable the feature, use
    1408             <literal>Client/DisableClipboard=</literal>. The default
    1409             value is <literal>1</literal>. See
    1410             <xref linkend="vrde-customization"/>.
    1411           </para></listitem>
    1412         <listitem><para>
    1413             <literal>Client/DisableUpstreamAudio</literal> specifies
    1414             whether to disable the VRDE upstream audio feature. Valid
    1415             values are <literal>1</literal> to disable the feature and
    1416             null (<literal>&ldquo;&rdquo;</literal>) to enable the
    1417             feature. To reenable the feature, use
    1418             <literal>Client/DisableUpstreamAudio=</literal>. The default
    1419             value is <literal>1</literal>. See
    1420             <xref linkend="vrde-customization"/>.
    1421           </para></listitem>
    1422         <listitem><para>
    1423             <literal>Client/DisableRDPDR</literal> specifies whether to
    1424             disable the RDP Device Redirection For Smart Cards feature
    1425             on the VRDE server. Valid values are <literal>1</literal> to
    1426             disable the feature and null
    1427             (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
    1428             The default value is <literal>1</literal>. See
    1429             <xref linkend="vrde-customization"/>.
    1430           </para></listitem>
    1431         <listitem><para>
    1432             <literal>H3DRedirect/Enabled</literal> specifies whether to
    1433             enable the VRDE server 3D redirection feature. Valid values
    1434             are <literal>1</literal> to enable the feature and null
    1435             (<literal>&ldquo;&rdquo;</literal>) to disable the feature.
    1436             See <xref linkend="vrde-customization"/>.
    1437           </para></listitem>
    1438         <listitem><para>
    1439             <literal>Security/Method</literal> specifies the security
    1440             method to use for a connection. See
    1441             <xref linkend="vrde-crypt" />.
    1442           </para><itemizedlist>
    1443             <listitem><para>
    1444                 <literal>Negotiate</literal> accepts both enhanced (TLS)
    1445                 and standard RDP security connections. The security
    1446                 method is negotiated with the client. This is the
    1447                 default value.
    1448               </para></listitem>
    1449             <listitem><para>
    1450                 <literal>RDP</literal> accepts only standard RDP
    1451                 security connections.
    1452               </para></listitem>
    1453             <listitem><para>
    1454                 <literal>TLS</literal> accepts only enhanced RDP
    1455                 security connections. The client must support TLS.
    1456               </para></listitem>
    1457           </itemizedlist></listitem>
    1458         <listitem><para>
    1459             <literal>Security/ServerCertificate</literal> specifies the
    1460             absolute path of the server certificate to use for a
    1461             connection. See <xref linkend="vrde-crypt" />.
    1462           </para></listitem>
    1463         <listitem><para>
    1464             <literal>Security/ServerPrivateKey</literal> specifies the
    1465             absolute path of the server private key. See
    1466             <xref linkend="vrde-crypt" />.
    1467           </para></listitem>
    1468         <listitem><para>
    1469             <literal>Security/CACertificate</literal> specifies the
    1470             absolute path of the CA self-signed certificate. See
    1471             <xref linkend="vrde-crypt" />.
    1472           </para></listitem>
    1473         <listitem><para>
    1474             <literal>Audio/RateCorrectionMode</literal> specifies the
    1475             rate correction mode to use.
    1476           </para><itemizedlist>
    1477             <listitem><para>
    1478                 <literal>VRDP_AUDIO_MODE_VOID</literal> indicates that
    1479                 no mode is specified. Use this value to unset any audio
    1480                 mode that is already set.
    1481               </para></listitem>
    1482             <listitem><para>
    1483                 <literal>VRDP_AUDIO_MODE_RC</literal> specifies to use
    1484                 the rate correction mode.
    1485               </para></listitem>
    1486             <listitem><para>
    1487                 <literal>VRDP_AUDIO_MODE_LPF</literal> specifies to use
    1488                 the low pass filter mode.
    1489               </para></listitem>
    1490             <listitem><para>
    1491                 <literal>VRDP_AUDIO_MODE_CS</literal> specifies to use
    1492                 the client sync mode to prevent underflow or overflow of
    1493                 the client queue.
    1494               </para></listitem>
    1495           </itemizedlist></listitem>
    1496         <listitem><para>
    1497             <literal>Audio/LogPath</literal> specifies the absolute path
    1498             of the audio log file.
    1499           </para></listitem>
    1500       </itemizedlist>
    1501     </refsect2>
    1502     <refsect2 id="vboxmanage-controlvm-vrdevideochannelquality">
    1503       <title>Specify the Image Quality for VRDP Video Redirection</title>
    1504       <remark role="help-copy-synopsis"/>
    1505       <para>
    1506         The <command>VBoxManage controlvm
    1507         <replaceable>vmname</replaceable>
    1508         vrdevideochannelquality</command> command sets the image
    1509         quality, as a JPEG compression level value, for video
    1510         redirection. Valid values are between 10% and 100%, inclusive.
    1511         Lower values mean lower quality but higher compression. See
    1512         <xref linkend="vrde-videochannel" />.
    1513       </para>
    1514       <para>
    1515         This subcommand does not affect the VM's running state directly.
    1516       </para>
    1517     </refsect2>
    1518     <refsect2 id="vboxmanage-controlvm-setvideomodehint">
    1519       <title>Specify the Video Mode for the Guest VM</title>
    1520       <remark role="help-copy-synopsis"/>
    1521       <para>
    1522         The <command>VBoxManage controlvm
    1523         <replaceable>vmname</replaceable> setvideomodehint</command>
    1524         command specifies the video mode for the guest VM to use. You
    1525         must have the &product-name; Guest Additions installed. Note
    1526         that this feature does not work for all guest systems.
    1527       </para>
    1528       <para>
    1529         This subcommand does not affect the VM's running state directly.
    1530       </para>
    1531     </refsect2>
    1532     <refsect2 id="vboxmanage-controlvm-setscreenlayout">
    1533       <title>Specify the Screen Layout for a Display on the Guest VM</title>
    1534       <remark role="help-copy-synopsis"/>
    1535       <para>
    1536         The <command>VBoxManage controlvm
    1537         <replaceable>vmname</replaceable> setscreenlayout</command>
    1538         command can be used to configure multiscreen displays. The
    1539         specified screen on the guest VM can be enabled or disabled, or
    1540         a custom screen layout can be configured.
    1541       </para>
    1542       <para>
    1543         This subcommand does not affect the VM's running state directly.
    1544       </para>
    1545     </refsect2>
    1546     <refsect2 id="vboxmanage-controlvm-screenshotpng">
    1547       <title>Take a Screen Shot of the Virtual Machine Display</title>
    1548       <remark role="help-copy-synopsis"/>
    1549       <para>
    1550         The <command>VBoxManage controlvm
    1551         <replaceable>vmname</replaceable> screenshotpng</command>
    1552         command takes a screenshot of the guest display and saves it as
    1553         PNG in the specified file.
    1554       </para>
    1555       <para>
    1556         This subcommand does not affect the VM's running state directly.
    1557       </para>
    1558       <itemizedlist>
    1559         <listitem><para>
    1560             <replaceable>filename</replaceable> specifies the name of
    1561             the PNG file to create.
    1562           </para></listitem>
    1563         <listitem><para>
    1564             <replaceable>display</replaceable> specifies the display
    1565             number for the screen shot. For a single monitor guest
    1566             display, this is <literal>0</literal>.
    1567           </para></listitem>
    1568       </itemizedlist>
    1569     </refsect2>
    1570     <refsect2 id="vboxmanage-controlvm-recording">
    1571       <title>Enable or Disable the Recording of a Virtual Machine Session</title>
    1572       <remark role="help-copy-synopsis"/>
    1573       <para>
    1574         The <command>VBoxManage controlvm
    1575         <replaceable>vmname</replaceable> recording</command> command
    1576         enables or disables the recording of a VM session into a
    1577         WebM/VP8 file. Valid values are <literal>on</literal>, which
    1578         begins recording when the VM session starts and
    1579         <literal>off</literal>, which disables recording. The default
    1580         value is <literal>off</literal>.
    1581       </para>
    1582       <para>
    1583         This subcommand does not affect the VM's running state directly.
    1584       </para>
    1585     </refsect2>
    1586     <refsect2 id="vboxmanage-controlvm-recordingscreens">
    1587       <title>Specify the Virtual Machine Screens to Record</title>
    1588       <remark role="help-copy-synopsis"/>
    1589       <para>
    1590         The <command>VBoxManage controlvm
    1591         <replaceable>vmname</replaceable> recording screens</command>
    1592         command enables you to specify which VM screens to record. The
    1593         recording for each screen that you specify is saved to its own
    1594         file in the machine folder. You cannot modify this setting while
    1595         recording is enabled.
    1596       </para>
    1597       <para>
    1598         This subcommand does not affect the VM's running state directly.
    1599       </para>
    1600       <itemizedlist>
    1601         <listitem><para>
    1602             <literal>all</literal> specifies that you record all VM
    1603             screens.
    1604           </para></listitem>
    1605         <listitem><para>
    1606             <literal>none</literal> specifies that you do not record any
    1607             VM screens.
    1608           </para></listitem>
    1609         <listitem><para>
    1610             <replaceable>screen-ID</replaceable> specifies one or more
    1611             VM screens to record.
    1612           </para></listitem>
    1613       </itemizedlist>
    1614     </refsect2>
    1615     <refsect2 id="vboxmanage-controlvm-recordingfilename">
    1616       <title>Specify the File in Which to Save Virtual Machine Recording</title>
    1617       <remark role="help-copy-synopsis"/>
    1618       <para>
    1619         The <command>VBoxManage controlvm
    1620         <replaceable>vmname</replaceable> recording filename</command>
    1621         command specifies the file in which to save the recording. You
    1622         cannot modify this setting while recording is enabled.
    1623       </para>
    1624       <para>
    1625         The default setting is to store a recording in the machine
    1626         folder, using the VM name as the file name, with a
    1627         <filename>webm</filename> file name extension.
    1628       </para>
    1629       <para>
    1630         This subcommand does not affect the VM's running state directly.
    1631       </para>
    1632     </refsect2>
    1633     <refsect2 id="vboxmanage-controlvm-recordingvideores">
    1634       <title>Specify the Resolution of the Recorded Video</title>
    1635       <remark role="help-copy-synopsis"/>
    1636       <para>
    1637         <command>VBoxManage controlvm <replaceable>vmname</replaceable>
    1638         recording videores</command> command specifies the resolution of
    1639         the recorded video in pixels. You cannot modify this setting
    1640         while recording is enabled.
    1641       </para>
    1642       <para>
    1643         Use the Settings tool to view the video recording settings,
    1644         which are based on the resolution (frame size). See the Frame
    1645         Size field on the Recording tab of the Display page to view the
    1646         default value.
    1647       </para>
    1648       <para>
    1649         This subcommand does not affect the VM's running state directly.
    1650       </para>
    1651       <para>
    1652         Specify the resolution as
    1653         <replaceable>width</replaceable><literal>x</literal><replaceable>height</replaceable>:
    1654       </para>
    1655       <itemizedlist>
    1656         <listitem><para>
    1657             <replaceable>width</replaceable> specifies the width in
    1658             pixels.
    1659           </para></listitem>
    1660         <listitem><para>
    1661             <replaceable>height</replaceable> specifies the height in
    1662             pixels.
    1663           </para></listitem>
    1664       </itemizedlist>
    1665     </refsect2>
    1666     <refsect2 id="vboxmanage-controlvm-recordingvideorate">
    1667       <title>Specify the Bit Rate of the Video</title>
    1668       <remark role="help-copy-synopsis"/>
    1669 <!-- @todo r=andy Clarify rate. -->
    1670       <para>
    1671         The <command>VBoxManage controlvm
    1672         <replaceable>vmname</replaceable> recording videorate</command>
    1673         command specifies the bit rate,
    1674         <replaceable>bit-rate</replaceable>, of the video in kilobits
    1675         per second. Increasing this value improves the appearance of the
    1676         video at the cost of an increased file size. You cannot modify
    1677         this setting while recording is enabled.
    1678       </para>
    1679       <para>
    1680         Use the Settings tool to view the video recording settings,
    1681         which are based on the frame size. See the Video Quality field
    1682         on the Recording tab of the Display page to view the default
    1683         value.
    1684       </para>
    1685       <para>
    1686         This subcommand does not affect the VM's running state directly.
    1687       </para>
    1688     </refsect2>
    1689     <refsect2 id="vboxmanage-controlvm-recordingvideofps">
    1690       <title>Specify the Maximum Frequency of the Video</title>
    1691       <remark role="help-copy-synopsis"/>
    1692       <para>
    1693         The <command>VBoxManage controlvm
    1694         <replaceable>vmname</replaceable> recording videofps</command>
    1695         command specifies the maximum frequency of the video to record.
    1696         Video frequency is measured in frames per second (FPS). The
    1697         recording skips any frames that have a frequency higher than the
    1698         specified maximum. Increasing the frequency reduces the number
    1699         of skipped frames and increases the file size. You cannot modify
    1700         this setting while recording is enabled.
    1701       </para>
    1702       <para>
    1703         Use the Settings tool to view the video recording settings,
    1704         which are based on the frame size. See the Frame Rate field on
    1705         the Recording tab of the Display page to view the default value.
    1706       </para>
    1707       <para>
    1708         This subcommand does not affect the VM's running state directly.
    1709       </para>
    1710     </refsect2>
    1711     <refsect2 id="vboxmanage-controlvm-recordingmaxtime">
    1712       <title>Specify the Maximum Amount of Time to Record Video</title>
    1713       <remark role="help-copy-synopsis"/>
    1714 <!-- @todo r=andy Clarify time format. -->
    1715       <para>
    1716         The <command>VBoxManage controlvm
    1717         <replaceable>vmname</replaceable> recording maxtime</command>
    1718         command specifies the maximum amount time to record in seconds.
    1719         The recording stops after the specified number of seconds
    1720         elapses. If this value is zero, the recording continues until
    1721         you stop the recording.
    1722       </para>
    1723       <para>
    1724         This subcommand does not affect the VM's running state directly.
    1725       </para>
    1726     </refsect2>
    1727     <refsect2 id="vboxmanage-controlvm-recordingmaxfilesize">
    1728       <title>Specify the Maximum Size of the Recorded Video</title>
    1729       <remark role="help-copy-synopsis"/>
    1730       <para>
    1731         The <command>VBoxManage controlvm
    1732         <replaceable>vmname</replaceable> recording
    1733         maxfilesize</command> command specifies the maximum size of the
    1734         recorded video file in megabytes. The recording stops when the
    1735         file reaches the specified size. If this value is zero, the
    1736         recording continues until you stop the recording. You cannot
    1737         modify this setting while recording is enabled.
    1738       </para>
    1739       <para>
    1740         This subcommand does not affect the VM's running state directly.
    1741       </para>
    1742     </refsect2>
    1743     <refsect2 id="vboxmanage-controlvm-setcredentials">
    1744       <title>Specify Credentials for Remote Logins on Windows Virtual Machines</title>
    1745       <remark role="help-copy-synopsis"/>
    1746       <para>
    1747         The <command>setcredentials</command> command enables you to
    1748         specify the credentials for remotely logging in to Windows VMs.
    1749         See <xref linkend="autologon" />.
    1750       </para>
    1751       <para>
    1752         This subcommand does not affect the VM's running state directly.
    1753       </para>
    1754       <itemizedlist>
    1755         <listitem><para>
    1756             <replaceable>username</replaceable> specifies the user name
    1757             with which to log in to the Windows VM.
    1758           </para></listitem>
    1759         <listitem><para>
    1760             <option>--passwordfile=<replaceable>filename</replaceable></option>
    1761             specifies the file from which to obtain the password for
    1762             <replaceable>username</replaceable>.
    1763           </para><para>
    1764             The <option>--passwordfile</option> is mutually exclusive
    1765             with the <option>--password</option> option.
    1766           </para></listitem>
    1767         <listitem><para>
    1768             <option>--password=<replaceable>password</replaceable></option>
    1769             specifies the password for
    1770             <replaceable>username</replaceable>.
    1771           </para><remark>
    1772             This design does not conform to Oracle's security
    1773             guidelines. You should not be able to specify a password on
    1774             the command line because the password can be seen in a
    1775             process listing.
    1776           </remark><para>
    1777             The <option>--password</option> is mutually exclusive with
    1778             the <option>--passwordfile</option> option.
    1779           </para></listitem>
    1780         <listitem><para>
    1781             <option>--allowlocallogin</option> specifies whether to
    1782             enable or disable local logins. Valid values are
    1783             <literal>on</literal> to enable local logins and
    1784             <literal>off</literal> to disable local logins.
    1785           </para></listitem>
    1786       </itemizedlist>
    1787     </refsect2>
    17881743    <refsect2 id="vboxmanage-controlvm-plugcpu">
    17891744      <title>Add a Virtual CPU to a Virtual Machine</title>
    … …  
    17971752        maximum number of CPUs configured.
    17981753      </para>
    1799       <para>
    1800         This subcommand does not affect the VM's running state directly.
    1801       </para>
    18021754    </refsect2>
    18031755    <refsect2 id="vboxmanage-controlvm-unplugcpu">
    … …  
    18111763        the virtual CPU to be removed and must be a number from 0 to the
    18121764        maximum number of CPUs configured. You cannot remove CPU 0.
    1813       </para>
    1814       <para>
    1815         This subcommand does not affect the VM's running state directly.
    18161765      </para>
    18171766    </refsect2>
    … …  
    18301779      </para>
    18311780      <para>
    1832         This subcommand does not affect the VM's running state directly.
    1833       </para>
    1834     </refsect2>
    1835     <refsect2 id="vboxmanage-controlvm-vmprocesspriority">
     1781        Use this feature with caution, it can have unexpected results
     1782        including timekeeping problems and lower performance than
     1783        specified. If you want to limit the resource usage of a VM
     1784        it is more reliable to pick an appropriate number of VCPUs.
     1785      </para>
     1786    </refsect2>
     1787    <refsect2 id="vboxmanage-controlvm-vm-process-priority">
    18361788      <title>Change the Priority of a VM Process</title>
    18371789      <remark role="help-copy-synopsis"/>
    … …  
    18731825          </para></listitem>
    18741826      </itemizedlist>
    1875       <para>
    1876         This subcommand does not affect the VM's running state directly.
    1877       </para>
    18781827    </refsect2>
    18791828    <refsect2 id="vboxmanage-controlvm-webcam-attach">
    … …  
    19291878        </varlistentry>
    19301879      </variablelist>
    1931       <para>
    1932         This subcommand does not affect the VM's running state directly.
    1933       </para>
    19341880    </refsect2>
    19351881    <refsect2 id="vboxmanage-controlvm-webcam-detach">
    … …  
    19701916          </para></listitem>
    19711917      </itemizedlist>
    1972       <para>
    1973         This subcommand does not affect the VM's running state directly.
    1974       </para>
    19751918    </refsect2>
    19761919    <refsect2 id="vboxmanage-controlvm-webcam-list">
    … …  
    19851928        <replaceable>vmname</replaceable> webcam attach</command>
    19861929        command.
    1987       </para>
    1988       <para>
    1989         This subcommand does not affect the VM's running state directly.
    19901930      </para>
    19911931    </refsect2>
    … …  
    20501990          Password: <replaceable>encryption-password</replaceable>
    20511991        </screen>
    2052       <para>
    2053         This subcommand does not affect the VM's running state directly.
    2054       </para>
    20551992    </refsect2>
    20561993    <refsect2 id="vboxmanage-controlvm-removeencpassword">
    … …  
    20672004        encryption password that you want to disable.
    20682005      </para>
    2069       <para>
    2070         This subcommand does not affect the VM's running state directly.
    2071       </para>
    20722006    </refsect2>
    20732007    <refsect2 id="vboxmanage-controlvm-removeallencpasswords">
    … …  
    20792013        removeallencpasswords</command> command disables all encryption
    20802014        passwords for all encrypted media attached to the VM.
    2081       </para>
    2082       <para>
    2083         This subcommand does not affect the VM's running state directly.
    20842015      </para>
    20852016    </refsect2>
    … …  
    20942025        serial port. Valid serial port values are integers that start
    20952026        from <literal>1</literal>.
    2096       </para>
    2097       <para>
    2098         This subcommand does not affect the VM's running state directly.
    20992027      </para>
    21002028      <variablelist>
    … …  
    21432071      </variablelist>
    21442072    </refsect2>
    2145     <refsect2 id="vboxmanage-controlvm-autostartenabled">
     2073    <refsect2 id="vboxmanage-controlvm-autostart-enabled">
    21462074      <title>Enabling autostart the VM during host system boot</title>
    21472075      <remark role="help-copy-synopsis"/>
    … …  
    21582086      </para>
    21592087    </refsect2>
    2160     <refsect2 id="vboxmanage-controlvm-autostartdelay">
     2088    <refsect2 id="vboxmanage-controlvm-autostart-delay">
    21612089      <title>Setting the delay of starting the VM on host system boot</title>
    21622090      <remark role="help-copy-synopsis"/>
    … …  
    21832111      allowed in both directions between the host and guest.
    21842112    </para>
    2185 <screen>$ VBoxManage controlvm ol7 clipboard bidirectional</screen>
     2113<screen>$ VBoxManage controlvm ol7 clipboard mode bidirectional</screen>
    21862114  </refsect1>
    21872115

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

    r87075 r93708  
    2020<refentry id="vboxmanage-startvm" lang="en">
    2121  <refentryinfo>
    22     <pubdate>August 2019</pubdate>
     22    <pubdate>$Date$</pubdate>
    2323    <title>VBoxManage startvm</title>
    2424  </refentryinfo>
    … …  
    3232    <refname>VBoxManage-startvm</refname>
    3333    <refpurpose>start a virtual machine</refpurpose>
    34     <refclass>Oracle VM VirtualBox</refclass>
     34    <refclass>&product-name;</refclass>
    3535  </refnamediv>
    3636
    … …  
    3939<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
    4040      <command>VBoxManage startvm</command>
    41       <group choice="req">
     41      <group choice="req" rep="repeat">
    4242        <arg choice="plain"><replaceable>uuid</replaceable></arg>
    4343        <arg choice="plain"><replaceable>vmname</replaceable></arg>

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

    r92946 r93708  
    331331  <xi:include href="user_man_VBoxManage-signova.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    332332
    333   <sect1 id="vboxmanage-startvm">
    334 
    335     <title>VBoxManage startvm</title>
    336 
    337     <para>
    338       This command starts a virtual machine that is currently in the
    339       Powered Off or Saved states.
    340     </para>
    341 
    342     <para>
    343       The optional <computeroutput>--type</computeroutput> specifier
    344       determines whether the machine will be started in a window or
    345       whether the output should go through
    346       <command>VBoxHeadless</command>, with VRDE enabled or not. See
    347       <xref linkend="vboxheadless" />. The list of types is subject to
    348       change, and it is not guaranteed that all types are accepted by
    349       any product variant.
    350     </para>
    351 
    352     <para>
    353       The global or per-VM default value for the VM frontend type will
    354       be taken if the type is not explicitly specified. If none of these
    355       are set, the GUI variant will be started.
    356     </para>
    357 
    358     <para>
    359       The following values are allowed:
    360     </para>
    361 
    362     <variablelist>
    363 
    364       <varlistentry>
    365         <term>
    366           <computeroutput>gui</computeroutput>
    367         </term>
    368 
    369         <listitem>
    370           <para>
    371             Starts a VM showing a GUI window. This is the default.
    372           </para>
    373         </listitem>
    374       </varlistentry>
    375 
    376       <varlistentry>
    377         <term>
    378           <computeroutput>headless</computeroutput>
    379         </term>
    380 
    381         <listitem>
    382           <para>
    383             Starts a VM without a window for remote display only.
    384           </para>
    385         </listitem>
    386       </varlistentry>
    387 
    388       <varlistentry>
    389         <term>
    390           <computeroutput>separate</computeroutput>
    391         </term>
    392 
    393         <listitem>
    394           <para>
    395             Starts a VM with a detachable UI. Technically, it is a
    396             headless VM with user interface in a separate process. This
    397             is an experimental feature as it lacks certain
    398             functionality, such as 3D acceleration.
    399           </para>
    400         </listitem>
    401       </varlistentry>
    402 
    403     </variablelist>
    404 
    405     <note>
    406       <para>
    407         If you experience problems with starting virtual machines with
    408         particular frontends and there is no conclusive error
    409         information, consider starting virtual machines directly by
    410         running the respective front-end, as this can give additional
    411         error information.
    412       </para>
    413     </note>
    414 
    415   </sect1>
    416 
    417   <sect1 id="vboxmanage-controlvm">
    418 
    419     <title>VBoxManage controlvm</title>
    420 
    421     <para>
    422       The <command>controlvm</command> subcommand enables you to change
    423       the state of a virtual machine that is currently running. The
    424       following can be specified:
    425     </para>
    426 
    427     <itemizedlist>
    428 
    429       <listitem>
    430         <para>
    431           <command>VBoxManage controlvm &lt;vm&gt; pause</command>:
    432           Temporarily puts a virtual machine on hold, without
    433           permanently changing its state. The VM window is gray, to
    434           indicate that the VM is currently paused. This is equivalent
    435           to selecting the <emphasis role="bold">Pause</emphasis> item
    436           in the <emphasis role="bold">Machine</emphasis> menu of the
    437           GUI.
    438         </para>
    439       </listitem>
    440 
    441       <listitem>
    442         <para>
    443           Use <command>VBoxManage controlvm &lt;vm&gt; resume</command>:
    444           Undoes a previous <command>pause</command> command. This is
    445           equivalent to selecting the
    446           <emphasis role="bold">Resume</emphasis> item in the
    447           <emphasis role="bold">Machine</emphasis> menu of the GUI.
    448         </para>
    449       </listitem>
    450 
    451       <listitem>
    452         <para>
    453           <command>VBoxManage controlvm &lt;vm&gt; reset</command>: Has
    454           the same effect on a virtual machine as pressing the Reset
    455           button on a real computer. A cold reboot of the virtual
    456           machine is done, which immediately restarts and reboots the
    457           guest operating system. The state of the VM is not saved
    458           beforehand, and data may be lost. This is equivalent to
    459           selecting the <emphasis role="bold">Reset</emphasis> item in
    460           the <emphasis role="bold">Machine</emphasis> menu of the GUI.
    461         </para>
    462       </listitem>
    463 
    464       <listitem>
    465         <para>
    466           <command>VBoxManage controlvm &lt;vm&gt; poweroff</command>:
    467           Has the same effect on a virtual machine as pulling the power
    468           cable on a real computer. The state of the VM is not saved
    469           beforehand, and data may be lost. This is equivalent to
    470           selecting the <emphasis role="bold">Close</emphasis> item in
    471           the <emphasis role="bold">Machine</emphasis> menu of the GUI,
    472           or clicking the VM window's close button, and then selecting
    473           <emphasis role="bold">Power Off the Machine</emphasis> in the
    474           displayed dialog.
    475         </para>
    476 
    477         <para>
    478           After this, the VM's state will be Powered Off. From that
    479           state, it can be started again. See
    480           <xref
    481           linkend="vboxmanage-startvm" />.
    482         </para>
    483       </listitem>
    484 
    485       <listitem>
    486         <para>
    487           <command>VBoxManage controlvm &lt;vm&gt; savestate</command>:
    488           Saves the current state of the VM to disk and then stops the
    489           VM. This is equivalent to selecting the
    490           <emphasis role="bold">Close</emphasis> item in the
    491           <emphasis role="bold">Machine</emphasis> menu of the GUI or
    492           clicking the VM window's close button, and then selecting
    493           <emphasis role="bold">Save the Machine State</emphasis> in the
    494           displayed dialog.
    495         </para>
    496 
    497         <para>
    498           After this, the VM's state will be Saved. From this state, it
    499           can be started again. See
    500           <xref linkend="vboxmanage-startvm" />.
    501         </para>
    502       </listitem>
    503 
    504       <listitem>
    505         <para>
    506           <command>VBoxManage controlvm &lt;vm&gt;
    507           acpipowerbutton</command>: Sends an ACPI shutdown signal to
    508           the VM, as if the power button on a real computer had been
    509           pressed. So long as the VM is running a fairly modern guest
    510           operating system providing ACPI support, this should trigger a
    511           proper shutdown mechanism from within the VM.
    512         </para>
    513       </listitem>
    514 
    515       <listitem>
    516         <para>
    517           <command>VBoxManage controlvm &lt;vm&gt; keyboardputscancode
    518           &lt;hex&gt; [&lt;hex&gt;...]</command>: Sends commands using
    519           keycodes to the VM. Keycodes are documented in the public
    520           domain. For example:
    521           http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html.
    522         </para>
    523       </listitem>
    524 
    525       <listitem>
    526         <para>
    527           <command>VBoxManage controlvm "VM name" teleport --hostname
    528           &lt;name&gt; --port &lt;port&gt; [--passwordfile &lt;file&gt;
    529           | --password &lt;password&gt;]</command>: Makes the machine
    530           the source of a teleporting operation and initiates a teleport
    531           to the given target. See <xref linkend="teleporting" />. If
    532           the optional password is specified, it must match the password
    533           that was given to the <command>modifyvm</command> command for
    534           the target machine. See
    535           <xref linkend="vboxmanage-modifyvm-teleport" />.
    536         </para>
    537       </listitem>
    538 
    539     </itemizedlist>
    540 
    541     <para>
    542       The following extra options are available with
    543       <command>controlvm</command> that do not directly affect the VM's
    544       running state:
    545     </para>
    546 
    547     <itemizedlist>
    548 
    549       <listitem>
    550         <para>
    551           <computeroutput>setlinkstate&lt;1-N&gt;
    552           on|off</computeroutput>: Connects or disconnects virtual
    553           network cables from their network interfaces.
    554         </para>
    555       </listitem>
    556 
    557       <listitem>
    558         <para>
    559           <computeroutput>nic&lt;1-N&gt;
    560           null|nat|bridged|intnet|hostonly|generic|natnetwork[&lt;devicename&gt;]</computeroutput>:
    561           Specifies the type of networking that should be made available
    562           on the specified VM virtual network card. They available types
    563           are: not connected to the host
    564           (<computeroutput>null</computeroutput>), use network address
    565           translation (<computeroutput>nat</computeroutput>), bridged
    566           networking (<computeroutput>bridged</computeroutput>),
    567           communicate with other virtual machines using internal
    568           networking (<computeroutput>intnet</computeroutput>),
    569           host-only networking
    570           (<computeroutput>hostonly</computeroutput>), natnetwork
    571           networking (<computeroutput>natnetwork</computeroutput>), or
    572           access to rarely used submodes
    573           (<computeroutput>generic</computeroutput>). These options
    574           correspond to the modes which are described in detail in
    575           <xref linkend="networkingmodes" />.
    576         </para>
    577       </listitem>
    578 
    579       <listitem>
    580         <para>
    581           With the <computeroutput>nictrace</computeroutput> options,
    582           you can optionally trace network traffic by dumping it to a
    583           file, for debugging purposes.
    584         </para>
    585 
    586         <para>
    587           <computeroutput>nictrace&lt;1-N&gt; on|off</computeroutput>:
    588           Enables network tracing for a particular virtual network card.
    589         </para>
    590 
    591         <para>
    592           Before enabling you should specify a file name to which the
    593           trace should be logged. This can be done with the
    594           <computeroutput>nictracefile&lt;1-N&gt;
    595           &lt;filename&gt;</computeroutput> option to
    596           <command>VBoxManage controlvm</command> at runtime or with the
    597           <computeroutput>&lt;filename&gt;</computeroutput> option to
    598           <command>VBoxManage modifyvm</command> otherwise.
    599         </para>
    600       </listitem>
    601 
    602       <listitem>
    603         <para>
    604           <computeroutput>nicpromisc&lt;1-N&gt;
    605           deny|allow-vms|allow-all</computeroutput>: Specifies how the
    606           promiscious mode is handled for the specified VM virtual
    607           network card. This setting is only relevant for bridged
    608           networking. The default setting of
    609           <computeroutput>deny</computeroutput> hides any traffic not
    610           intended for this VM.
    611           <computeroutput>allow-vms</computeroutput> hides all host
    612           traffic from this VM but enables the VM to see traffic to and
    613           from other VMs. <computeroutput>allow-all</computeroutput>
    614           removes this restriction completely.
    615         </para>
    616       </listitem>
    617 
    618       <listitem>
    619         <para>
    620           <computeroutput>nicproperty&lt;1-N&gt;
    621           &lt;paramname&gt;="paramvalue"</computeroutput>: This option,
    622           in combination with
    623           <computeroutput>nicgenericdrv</computeroutput> enables you to
    624           pass parameters to rarely-used network backends.
    625         </para>
    626 
    627         <para>
    628           Those parameters are backend engine-specific, and are
    629           different between UDP Tunnel and the VDE backend drivers. See
    630           <xref linkend="network_udp_tunnel" />.
    631         </para>
    632       </listitem>
    633 
    634       <listitem>
    635         <para>
    636           <computeroutput>natpf&lt;1-N&gt;
    637           [&lt;name&gt;],tcp|udp,[&lt;hostip&gt;],&lt;hostport&gt;,[&lt;guestip&gt;],
    638           &lt;guestport&gt;</computeroutput>: Specifies a NAT
    639           port-forwarding rule. See <xref linkend="natforward"/>.
    640         </para>
    641       </listitem>
    642 
    643       <listitem>
    644         <para>
    645           <computeroutput>natpf&lt;1-N&gt; delete
    646           &lt;name&gt;</computeroutput>: Deletes a NAT port-forwarding
    647           rule. See <xref linkend="natforward"/>.
    648         </para>
    649       </listitem>
    650 
    651       <listitem>
    652         <para>
    653           The <computeroutput>guestmemoryballoon&lt;balloon size in
    654           MB&gt;</computeroutput>: Changes the size of the guest memory
    655           balloon. This is the memory allocated by the &product-name;
    656           Guest Additions from the guest operating system and returned
    657           to the hypervisor for reuse by other virtual machines. This
    658           must be specified in megabytes. See
    659           <xref linkend="guestadd-balloon" />.
    660         </para>
    661       </listitem>
    662 
    663       <listitem>
    664         <para>
    665           <computeroutput>usbattach&lt;uuid|address&gt; [--capturefile
    666           &lt;filename&gt;]</computeroutput>
    667         </para>
    668 
    669         <para>
    670           and <computeroutput>usbdetach &lt;uuid|address&gt;
    671           [--capturefile &lt;filename&gt;]</computeroutput>: Makes host
    672           USB devices visible or invisible to the virtual machine on the
    673           fly, without the need for creating filters first. The USB
    674           devices can be specified by UUID (unique identifier) or by
    675           address on the host system. Use the
    676           <computeroutput>--capturefile</computeroutput> option to
    677           specify the absolute path of a file for writing activity
    678           logging data.
    679         </para>
    680 
    681         <para>
    682           You can use <command>VBoxManage list usbhost</command> to
    683           locate this information.
    684         </para>
    685       </listitem>
    686 
    687       <listitem>
    688         <para>
    689           <computeroutput>audioin on</computeroutput>: Selects whether
    690           capturing audio from the host is enabled or disabled.
    691         </para>
    692       </listitem>
    693 
    694       <listitem>
    695         <para>
    696           <computeroutput>audioout on</computeroutput>: Selects whether
    697           audio playback from the guest is enabled or disabled.
    698         </para>
    699       </listitem>
    700 
    701       <listitem>
    702         <para>
    703           <computeroutput>clipboard mode
    704           disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
    705           Selects how the guest or host operating system's clipboard
    706           should be shared with the host or guest. See
    707           <xref linkend="generalsettings" />. This requires that the
    708           Guest Additions be installed in the virtual machine.
    709         </para>
    710       </listitem>
    711 
    712       <listitem>
    713         <para>
    714           <computeroutput>clipboard filetransfers
    715           enabled|disabled</computeroutput>: Specifies if clipboard file
    716           transfers are allowed between host and guest OSes or not.
    717         </para>
    718       </listitem>
    719 
    720       <listitem>
    721         <para>
    722           <computeroutput>draganddrop
    723           disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
    724           Selects the current drag and drop mode being used between the
    725           host and the virtual machine. See
    726           <xref linkend="guestadd-dnd" />. This requires that the Guest
    727           Additions be installed in the virtual machine.
    728         </para>
    729       </listitem>
    730 
    731       <listitem>
    732         <para>
    733           <computeroutput>vrde on|off</computeroutput>: Enables and
    734           disables the VRDE server, if it is installed.
    735         </para>
    736       </listitem>
    737 
    738       <listitem>
    739         <para>
    740           <computeroutput>vrdeport
    741           default|&lt;ports&gt;</computeroutput>: Changes the port or a
    742           range of ports that the VRDE server can bind to.
    743           <computeroutput>default</computeroutput> or
    744           <computeroutput>0</computeroutput> means port 3389, the
    745           standard port for RDP. See the description for the
    746           <computeroutput>--vrde-port</computeroutput> option in
    747           <xref  linkend="vboxmanage-modifyvm-vrde" />.
    748         </para>
    749       </listitem>
    750 
    751       <listitem>
    752         <para>
    753           <computeroutput>vrdeproperty
    754           "TCP/Ports|Address=&lt;value&gt;"</computeroutput>: Sets the
    755           port numbers and IP address on the VM to which the VRDE server
    756           can bind.
    757         </para>
    758 
    759         <itemizedlist>
    760 
    761           <listitem>
    762             <para>
    763               For TCP/Ports, &lt;value&gt; should be a port or a range
    764               of ports to which the VRDE server can bind.
    765               <computeroutput>default</computeroutput> or
    766               <computeroutput>0</computeroutput> means port 3389, the
    767               standard port for RDP. See the description for the
    768               <computeroutput>--vrde-port</computeroutput> option in
    769               <xref linkend="vboxmanage-modifyvm-vrde" />.
    770             </para>
    771           </listitem>
    772 
    773           <listitem>
    774             <para>
    775               For TCP/Address, &lt;value&gt;: The IP address of the host
    776               network interface that the VRDE server will bind to. If
    777               specified, the server will accept connections only on the
    778               specified host network interface. See the description for
    779               the <computeroutput>--vrde-address</computeroutput> option
    780               in <xref linkend="vboxmanage-modifyvm-vrde" />.
    781             </para>
    782           </listitem>
    783 
    784         </itemizedlist>
    785       </listitem>
    786 
    787       <listitem>
    788         <para>
    789           <computeroutput>vrdeproperty
    790           "VideoChannel/Enabled|Quality|DownscaleProtection=&lt;value&gt;"</computeroutput>:
    791           Sets the VRDP video redirection properties.
    792         </para>
    793 
    794         <itemizedlist>
    795 
    796           <listitem>
    797             <para>
    798               For VideoChannel/Enabled, &lt;value&gt; can be set to "1"
    799               switching the VRDP video channel on. See
    800               <xref linkend="vrde-videochannel" />.
    801             </para>
    802           </listitem>
    803 
    804           <listitem>
    805             <para>
    806               For VideoChannel/Quality, &lt;value&gt; should be set
    807               between 10 and 100% inclusive, representing a JPEG
    808               compression level on the VRDE server video channel. Lower
    809               values mean lower quality but higher compression. See
    810               <xref linkend="vrde-videochannel" />.
    811             </para>
    812           </listitem>
    813 
    814           <listitem>
    815             <para>
    816               For VideoChannel/DownscaleProtection, &lt;value&gt; can be
    817               set to "1" to enable the videochannel downscale protection
    818               feature. When enabled, if a video's size equals the shadow
    819               buffer size, then it is regarded as a full screen video,
    820               and is displayed. If its size is between fullscreen and
    821               the downscale threshold it is not displayed, as it could
    822               be an application window, which would be unreadable when
    823               downscaled. When the downscale protection feature is
    824               disabled, an attempt is always made to display videos.
    825             </para>
    826           </listitem>
    827 
    828         </itemizedlist>
    829       </listitem>
    830 
    831       <listitem>
    832         <para>
    833           <computeroutput>vrdeproperty
    834           "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1"</computeroutput>:
    835           Disables one of the VRDE server features: Display, Input,
    836           Audio, or USB. To reenable a feature, use
    837           "Client/DisableDisplay=" for example. See
    838           <xref linkend="vrde-customization" />.
    839         </para>
    840       </listitem>
    841 
    842       <listitem>
    843         <para>
    844           <computeroutput>vrdeproperty
    845           "Client/DisableClipboard|DisableUpstreamAudio=1"</computeroutput>.
    846           Disables one of the VRDE server features: Clipboard or
    847           UpstreamAudio. To reenable a feature, use
    848           "Client/DisableClipboard=" for example. See
    849           <xref linkend="vrde-customization" />.
    850         </para>
    851       </listitem>
    852 
    853       <listitem>
    854         <para>
    855           <computeroutput>vrdeproperty
    856           "Client/DisableRDPDR=1"</computeroutput>: Disables the VRDE
    857           server feature: RDP device redirection for smart cards. To
    858           reenable this feature, use "Client/DisableRDPR=".
    859         </para>
    860       </listitem>
    861 
    862       <listitem>
    863         <para>
    864           <computeroutput>vrdeproperty
    865           "H3DRedirect/Enabled=1"</computeroutput>: Enables the VRDE
    866           server feature: 3D redirection. To disable this feature, use
    867           "H3DRedirect/Enabled=".
    868         </para>
    869       </listitem>
    870 
    871       <listitem>
    872         <para>
    873           <computeroutput>vrdeproperty
    874           "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=&lt;value&gt;"</computeroutput>:
    875           Sets the desired security method, path of the server
    876           certificate, path of the server private key, and path of CA
    877           certificate, used for a connection.
    878         </para>
    879 
    880         <itemizedlist>
    881 
    882           <listitem>
    883             <para>
    884               <computeroutput>vrdeproperty
    885               "Security/Method=&lt;value&gt;"</computeroutput>: Sets the
    886               desired security method, which is used for a connection.
    887               Valid values are as follows:
    888             </para>
    889 
    890             <itemizedlist>
    891 
    892               <listitem>
    893                 <para>
    894                   <computeroutput>Negotiate</computeroutput>: Both
    895                   Enhanced (TLS) and Standard RDP Security connections
    896                   are allowed. The security method is negotiated with
    897                   the client. This is the default setting.
    898                 </para>
    899               </listitem>
    900 
    901               <listitem>
    902                 <para>
    903                   <computeroutput>RDP</computeroutput>: Only Standard
    904                   RDP Security is accepted.
    905                 </para>
    906               </listitem>
    907 
    908               <listitem>
    909                 <para>
    910                   <computeroutput>TLS</computeroutput>: Only Enhanced
    911                   RDP Security is accepted. The client must support TLS.
    912                 </para>
    913               </listitem>
    914 
    915             </itemizedlist>
    916 
    917             <para>
    918               See <xref linkend="vrde-crypt" />.
    919             </para>
    920           </listitem>
    921 
    922           <listitem>
    923             <para>
    924               <computeroutput>vrdeproperty
    925               "Security/ServerCertificate=&lt;value&gt;"</computeroutput>
    926               where &lt;value&gt; is the absolute path of the server
    927               certificate. See <xref linkend="vrde-crypt" />.
    928             </para>
    929           </listitem>
    930 
    931           <listitem>
    932             <para>
    933               <computeroutput>vrdeproperty
    934               "Security/ServerPrivateKey=&lt;value&gt;"</computeroutput>
    935               where &lt;value&gt; is the absolute path of the server
    936               private key. See <xref linkend="vrde-crypt" />.
    937             </para>
    938           </listitem>
    939 
    940           <listitem>
    941             <para>
    942               <computeroutput>vrdeproperty
    943               "Security/CACertificate=&lt;value&gt;"</computeroutput>
    944               where &lt;value&gt; is the absolute path of the CA self
    945               signed certificate. See <xref linkend="vrde-crypt" />.
    946             </para>
    947           </listitem>
    948 
    949         </itemizedlist>
    950       </listitem>
    951 
    952       <listitem>
    953         <para>
    954           <computeroutput>vrdeproperty
    955           "Audio/RateCorrectionMode|LogPath=&lt;value&gt;"</computeroutput>:
    956           Sets the audio connection mode, or path of the audio logfile.
    957         </para>
    958 
    959         <itemizedlist>
    960 
    961           <listitem>
    962             <para>
    963               <computeroutput>vrdeproperty
    964               "Audio/RateCorrectionMode=&lt;value&gt;"</computeroutput>
    965               where &lt;value&gt; is the desired rate correction mode,
    966               allowed values are:
    967             </para>
    968 
    969             <itemizedlist>
    970 
    971               <listitem>
    972                 <para>
    973                   <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput>:
    974                   No mode specified, use to unset any Audio mode already
    975                   set.
    976                 </para>
    977               </listitem>
    978 
    979               <listitem>
    980                 <para>
    981                   <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput>:
    982                   Rate correction mode.
    983                 </para>
    984               </listitem>
    985 
    986               <listitem>
    987                 <para>
    988                   <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput>:
    989                   Low pass filter mode.
    990                 </para>
    991               </listitem>
    992 
    993               <listitem>
    994                 <para>
    995                   <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput>:
    996                   Client sync mode to prevent underflow or overflow of
    997                   the client queue.
    998                 </para>
    999               </listitem>
    1000 
    1001             </itemizedlist>
    1002           </listitem>
    1003 
    1004           <listitem>
    1005             <para>
    1006               <computeroutput>vrdeproperty
    1007               "Audio/LogPath=&lt;value&gt;"</computeroutput> where
    1008               &lt;value&gt; is the absolute path of the audio log file.
    1009             </para>
    1010           </listitem>
    1011 
    1012         </itemizedlist>
    1013       </listitem>
    1014 
    1015       <listitem>
    1016         <para>
    1017           <computeroutput>vrdevideochannelquality
    1018           &lt;percent&gt;</computeroutput>: Sets the image quality for
    1019           video redirection. See <xref linkend="vrde-videochannel" />.
    1020         </para>
    1021       </listitem>
    1022 
    1023       <listitem>
    1024         <para>
    1025           <computeroutput>setvideomodehint</computeroutput>: Requests
    1026           that the guest system change to a particular video mode. This
    1027           requires that the Guest Additions be installed, and will not
    1028           work for all guest systems.
    1029         </para>
    1030       </listitem>
    1031 
    1032       <listitem>
    1033         <para>
    1034           <computeroutput>screenshotpng</computeroutput>: Takes a
    1035           screenshot of the guest display and saves it in PNG format.
    1036         </para>
    1037       </listitem>
    1038 
    1039       <listitem>
    1040         <para>
    1041           <computeroutput>recording on|off</computeroutput> enables or
    1042           disables the recording of a VM session into a WebM/VP8 file.
    1043           When this option value is <computeroutput>on</computeroutput>,
    1044           recording begins when the VM session starts.
    1045         </para>
    1046       </listitem>
    1047 
    1048       <listitem>
    1049         <para>
    1050           <computeroutput>recordingscreens
    1051           all|<replaceable>screen-ID</replaceable>
    1052           [<replaceable>screen-ID</replaceable> ...]</computeroutput>
    1053           enables you to specify which VM screens to record. The
    1054           recording for each screen that you specify is saved to its own
    1055           file. You cannot modify this setting while recording is
    1056           enabled.
    1057         </para>
    1058       </listitem>
    1059 
    1060       <listitem>
    1061         <para>
    1062           <computeroutput>recordingfile
    1063           <replaceable>filename</replaceable></computeroutput> specifies
    1064           the file in which to save the recording. You cannot modify
    1065           this setting while recording is enabled.
    1066         </para>
    1067       </listitem>
    1068 
    1069       <listitem>
    1070         <para>
    1071           <computeroutput>recordingvideores
    1072           <replaceable>width</replaceable>x<replaceable>height</replaceable></computeroutput>
    1073           specifies the resolution of the recorded video in pixels. You
    1074           cannot modify this setting while recording is enabled.
    1075         </para>
    1076       </listitem>
    1077 
    1078       <listitem>
    1079 <!-- @todo r=andy Clarify rate. -->
    1080 
    1081         <para>
    1082           <computeroutput>recordingvideorate
    1083           <replaceable>bit-rate</replaceable></computeroutput> specifies
    1084           the bit rate of the video in kilobits per second. Increasing
    1085           this value improves the appearance of the video at the cost of
    1086           an increased file size. You cannot modify this setting while
    1087           recording is enabled.
    1088         </para>
    1089       </listitem>
    1090 
    1091       <listitem>
    1092         <para>
    1093           <computeroutput>recordingvideofps
    1094           <replaceable>fps</replaceable></computeroutput> specifies the
    1095           maximum number of video frames per second (FPS) to record.
    1096           Frames that have a higher frequency are skipped. Increasing
    1097           this value reduces the number of skipped frames and increases
    1098           the file size. You cannot modify this setting while recording
    1099           is enabled.
    1100         </para>
    1101       </listitem>
    1102 
    1103       <listitem>
    1104 <!-- @todo r=andy Clarify time format. -->
    1105 
    1106         <para>
    1107           <computeroutput>recordingmaxtime
    1108           <replaceable>seconds</replaceable></computeroutput> specifies
    1109           the maximum amount time to record in seconds. The recording
    1110           stops after the specified number of seconds elapses. If this
    1111           value is zero, the recording continues until you stop the
    1112           recording.
    1113         </para>
    1114       </listitem>
    1115 
    1116       <listitem>
    1117         <para>
    1118           <computeroutput>recordingmaxsize
    1119           <replaceable>MB</replaceable></computeroutput> specifies the
    1120           maximum size of the recorded video file in megabytes. The
    1121           recording stops when the file reaches the specified size. If
    1122           this value is zero, the recording continues until you stop the
    1123           recording. You cannot modify this setting while recording is
    1124           enabled.
    1125         </para>
    1126       </listitem>
    1127 
    1128       <listitem>
    1129         <para>
    1130           <computeroutput>recordingopts
    1131           <replaceable>keyword</replaceable>=<replaceable>value</replaceable>[,<replaceable>keyword</replaceable>=<replaceable>value</replaceable>
    1132           ...]</computeroutput> specifies additional recording options
    1133           in a comma-separated keyword-value format. For example,
    1134           <computeroutput>foo=bar,a=b</computeroutput>. You cannot
    1135           modify this setting while recording is enabled.
    1136         </para>
    1137 
    1138         <para>
    1139           Only use this option only if you are an advanced user. For
    1140           information about keywords, see <emphasis>Oracle VM VirtualBox
    1141           Programming Guide and Reference</emphasis>.
    1142         </para>
    1143       </listitem>
    1144 
    1145       <listitem>
    1146         <para>
    1147           <computeroutput>setcredentials</computeroutput>: Used for
    1148           remote logins on Windows guests. See
    1149           <xref linkend="autologon" />.
    1150         </para>
    1151       </listitem>
    1152 
    1153       <listitem>
    1154         <para>
    1155           <computeroutput>teleport --host &lt;name&gt; --port
    1156           &lt;port&gt;</computeroutput>: Configures a VM as a target for
    1157           teleporting. &lt;name&gt; specifies the virtual machine name.
    1158           &lt;port&gt; specifies the port on the virtual machine which
    1159           should listen for teleporting requests from other virtual
    1160           machines. It can be any free TCP/IP port number, such as 6000.
    1161           See <xref linkend="teleporting" />.
    1162         </para>
    1163 
    1164         <itemizedlist>
    1165 
    1166           <listitem>
    1167             <para>
    1168               <computeroutput>--maxdowntime
    1169               &lt;msec&gt;</computeroutput>: Specifies the maximum
    1170               downtime, in milliseconds, for the teleporting target VM.
    1171               Optional.
    1172             </para>
    1173           </listitem>
    1174 
    1175           <listitem>
    1176             <para>
    1177               <computeroutput>--password
    1178               &lt;password&gt;</computeroutput>: The teleporting request
    1179               will only succeed if the source machine specifies the same
    1180               password as the one given with this command. Optional.
    1181             </para>
    1182           </listitem>
    1183 
    1184           <listitem>
    1185             <para>
    1186               <computeroutput>--passwordfile &lt;password
    1187               file&gt;</computeroutput>: The teleporting request will
    1188               only succeed if the source machine specifies the same
    1189               password as the one specified in the password file with
    1190               the path specified with this command. Use
    1191               <computeroutput>stdin</computeroutput> to read the
    1192               password from stdin. Optional.
    1193             </para>
    1194           </listitem>
    1195 
    1196         </itemizedlist>
    1197       </listitem>
    1198 
    1199       <listitem>
    1200         <para>
    1201           <computeroutput>plugcpu|unplugcpu &lt;id&gt;</computeroutput>:
    1202           If CPU hot-plugging is enabled, this setting adds and removes
    1203           a virtual CPU to the virtual machine.
    1204           <computeroutput>&lt;id&gt;</computeroutput> specifies the
    1205           index of the virtual CPU to be added or removed and must be a
    1206           number from 0 to the maximum number of CPUs configured. CPU 0
    1207           can never be removed.
    1208         </para>
    1209       </listitem>
    1210 
    1211       <listitem>
    1212         <para>
    1213           The <computeroutput>cpuexecutioncap
    1214           &lt;1-100&gt;</computeroutput>: Controls how much CPU time a
    1215           virtual CPU can use. A value of 50 implies a single virtual
    1216           CPU can use up to 50% of a single host CPU.
    1217         </para>
    1218       </listitem>
    1219 
    1220       <listitem>
    1221         <para>
    1222           <computeroutput>vm-process-priority
    1223           default|flat|low|normal|high</computeroutput>: Changes the
    1224           priority scheme of the VM process. See
    1225           <xref linkend="vboxmanage-startvm" />.
    1226         </para>
    1227       </listitem>
    1228 
    1229       <listitem>
    1230         <para>
    1231           <computeroutput>webcam attach &lt;path|alias&gt;
    1232           [&lt;keyword=value&gt;[;&lt;keyword=value&gt;...]]</computeroutput>:
    1233           Attaches a webcam to a running VM. Specify the absolute path
    1234           of the webcam on the host operating system, or use its alias,
    1235           obtained by using the command: <command>VBoxManage list
    1236           webcams</command>.
    1237         </para>
    1238 
    1239         <para>
    1240           Note that alias '.0' means the default video input device on
    1241           the host operating system, '.1', '.2', etc. mean first,
    1242           second, etc. video input device. The device order is
    1243           host-specific.
    1244         </para>
    1245 
    1246         <para>
    1247           The optional settings parameter is a
    1248           <computeroutput>;</computeroutput> delimited list of
    1249           name-value pairs, enabling configuration of the emulated
    1250           webcam device.
    1251         </para>
    1252 
    1253         <para>
    1254           The following settings are supported:
    1255         </para>
    1256 
    1257         <para>
    1258           MaxFramerate: Specifies the highest rate in frames per second,
    1259           at which video frames are sent to the guest. Higher frame
    1260           rates increase CPU load, so this setting can be useful when
    1261           there is a need to reduce CPU load. The default setting is
    1262           <computeroutput>no maximum limit</computeroutput>, thus
    1263           enabling the guest to use all frame rates supported by the
    1264           host webcam.
    1265         </para>
    1266 
    1267         <para>
    1268           MaxPayloadTransferSize: Specifies the maximum number of bytes
    1269           the emulated webcam can send to the guest in one buffer. The
    1270           default setting is 3060 bytes, which is used by some webcams.
    1271           Higher values can slightly reduce CPU load, if the guest is
    1272           able to use larger buffers. Note that higher
    1273           MaxPayloadTransferSize values may be not supported by some
    1274           guest operating systems.
    1275         </para>
    1276       </listitem>
    1277 
    1278       <listitem>
    1279         <para>
    1280           <computeroutput>webcam detach
    1281           &lt;path|alias&gt;</computeroutput>: Detaches a webcam from a
    1282           running VM. Specify the absolute path of the webcam on the
    1283           host, or use its alias obtained from the <command>webcam
    1284           list</command> command.
    1285         </para>
    1286 
    1287         <para>
    1288           Please note the following points, relating to specific host
    1289           operating systems:
    1290         </para>
    1291 
    1292         <itemizedlist>
    1293 
    1294           <listitem>
    1295             <para>
    1296               Windows hosts: When the webcam device is detached from the
    1297               host, the emulated webcam device is automatically detached
    1298               from the guest.
    1299             </para>
    1300           </listitem>
    1301 
    1302           <listitem>
    1303             <para>
    1304               Mac OS X hosts: OS X version 10.7 or newer is required.
    1305             </para>
    1306 
    1307             <para>
    1308               When the webcam device is detached from the host, the
    1309               emulated webcam device remains attached to the guest and
    1310               must be manually detached using the <command>VBoxManage
    1311               controlvm webcam detach</command> command.
    1312             </para>
    1313           </listitem>
    1314 
    1315           <listitem>
    1316             <para>
    1317               Linux hosts: When the webcam is detached from the host,
    1318               the emulated webcam device is automatically detached from
    1319               the guest only if the webcam is streaming video. If the
    1320               emulated webcam is inactive, it should be manually
    1321               detached using the <command>VBoxManage controlvm webcam
    1322               detach</command> command.
    1323             </para>
    1324           </listitem>
    1325 
    1326         </itemizedlist>
    1327       </listitem>
    1328 
    1329       <listitem>
    1330         <para>
    1331           <computeroutput>webcam list</computeroutput>: Lists webcams
    1332           attached to the running VM. The output is a list of absolute
    1333           paths or aliases that were used for attaching the webcams to
    1334           the VM using the <command>webcam attach</command> command.
    1335         </para>
    1336       </listitem>
    1337 
    1338       <listitem>
    1339         <para>
    1340           <computeroutput>addencpassword &lt;id&gt; &lt;password
    1341           file&gt;|- [--removeonsuspend
    1342           &lt;yes|no&gt;]</computeroutput>: Supplies an encrypted VM
    1343           specified by &lt;id&gt; with the encryption password to enable
    1344           a headless start. Either specify the absolute path of a
    1345           password file on the host file system: &lt;password file&gt;,
    1346           or use <option>-</option> to instruct
    1347           <command>VBoxManage</command> to prompt the user for the
    1348           encryption password.
    1349         </para>
    1350 
    1351         <para>
    1352           <computeroutput>--removeonsuspend
    1353           &lt;yes|no&gt;</computeroutput>: Specifies whether to remove
    1354           the passsword or keep the password in VM memory when the VM is
    1355           suspended. If the VM has been suspended and the password has
    1356           been removed, the user needs to resupply the password before
    1357           the VM can be resumed. This feature is useful in cases where
    1358           the user does not want the password to be stored in VM memory,
    1359           and the VM is suspended by a host suspend event.
    1360         </para>
    1361 
    1362         <note>
    1363           <para>
    1364             On &product-name; versions 5.0 and later, data stored on
    1365             hard disk images can be transparently encrypted for the
    1366             guest. &product-name; uses the AES algorithm in XTS mode and
    1367             supports 128 or 256 bit data encryption keys (DEK). The DEK
    1368             is stored encrypted in the medium properties, and is
    1369             decrypted during VM startup by supplying the encryption
    1370             password.
    1371           </para>
    1372         </note>
    1373 
    1374         <para>
    1375           The <command>VBoxManage encryptmedium</command> command is
    1376           used to create a DEK encrypted medium. See
    1377           <xref linkend="diskencryption-encryption" />. When starting an
    1378           encrypted VM from the &product-name; GUI, the user will be
    1379           prompted for the encryption password.
    1380         </para>
    1381 
    1382         <para>
    1383           For a headless encrypted VM start, use the following command:
    1384         </para>
    1385 
    1386 <screen>
    1387           VBoxManage startvm "vmname" --type headless
    1388         </screen>
    1389 
    1390         <para>
    1391           Then supply the required encryption password as follows:
    1392         </para>
    1393 
    1394 <screen>
    1395           VBoxManage "vmname" controlvm "vmname" addencpassword ...
    1396         </screen>
    1397 
    1398         <para></para>
    1399       </listitem>
    1400 
    1401       <listitem>
    1402         <para>
    1403           <computeroutput>removeencpassword &lt;id&gt;</computeroutput>:
    1404           Removes encryption password authorization for password
    1405           &lt;id&gt; for all encrypted media attached to the VM.
    1406         </para>
    1407       </listitem>
    1408 
    1409       <listitem>
    1410         <para>
    1411           <computeroutput>removeallencpasswords</computeroutput>:
    1412           Removes encryption password authorization for all passwords
    1413           for all encrypted media attached to the VM.
    1414         </para>
    1415       </listitem>
    1416 
    1417       <listitem>
    1418         <para>
    1419           <computeroutput>changeuartmode &lt;1-N&gt;</computeroutput>:
    1420           Changes the connection mode for a given virtual serial port.
    1421         </para>
    1422       </listitem>
    1423 
    1424     </itemizedlist>
    1425 
    1426   </sect1>
     333  <xi:include href="user_man_VBoxManage-startvm.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     334
     335  <xi:include href="user_man_VBoxManage-controlvm.xml"      xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    1427336
    1428337  <xi:include href="user_man_VBoxManage-unattended.xml"     xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />

  • trunk/doc/manual/ru_RU/man_VBoxManage-controlvm.xml

    r93478 r93708  
    319319    </cmdsynopsis>
    320320
    321     <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard">
    322       <command>VBoxManage controlvm</command>
    323       <group choice="req">
    324         <arg choice="plain"><replaceable>uuid</replaceable></arg>
    325         <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg>
    326       </group>
    327       <arg choice="plain">clipboard</arg>
     321    <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-mode">
     322      <command>VBoxManage controlvm</command>
     323      <group choice="req">
     324        <arg choice="plain"><replaceable>uuid</replaceable></arg>
     325        <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg>
     326      </group>
     327      <arg choice="plain">clipboard mode</arg>
    328328      <group choice="req">
    329329        <arg choice="plain">disabled</arg>
    … …  
    447447    </cmdsynopsis>
    448448
    449     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingscreens">
     449    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-screens">
    450450      <command>VBoxManage controlvm</command>
    451451      <group choice="req">
    … …  
    461461    </cmdsynopsis>
    462462
    463     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingfilename">
     463    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-filename">
    464464      <command>VBoxManage controlvm</command>
    465465      <group choice="req">
    … …  
    471471    </cmdsynopsis>
    472472
    473     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingvideores">
     473    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videores">
    474474      <command>VBoxManage controlvm</command>
    475475      <group choice="req">
    … …  
    481481    </cmdsynopsis>
    482482
    483     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingvideorate">
     483    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videorate">
    484484      <command>VBoxManage controlvm</command>
    485485      <group choice="req">
    … …  
    491491    </cmdsynopsis>
    492492
    493     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingvideofps">
     493    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videofps">
    494494      <command>VBoxManage controlvm</command>
    495495      <group choice="req">
    … …  
    501501    </cmdsynopsis>
    502502
    503     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingmaxtime">
     503    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxtime">
    504504      <command>VBoxManage controlvm</command>
    505505      <group choice="req">
    … …  
    511511    </cmdsynopsis>
    512512
    513     <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingmaxfilesize">
     513    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxfilesize">
    514514      <command>VBoxManage controlvm</command>
    515515      <group choice="req">
    … …  
    586586    </cmdsynopsis>
    587587
    588     <cmdsynopsis id="synopsis-vboxmanage-controlvm-vmprocesspriority">
     588    <cmdsynopsis id="synopsis-vboxmanage-controlvm-vm-process-priority">
    589589      <command>VBoxManage controlvm</command>
    590590      <group choice="req">
    … …  
    686686    </cmdsynopsis>
    687687
    688     <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostartenabled">
     688    <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-enabled">
    689689      <command>VBoxManage controlvm</command>
    690690      <group choice="req">
    … …  
    699699    </cmdsynopsis>
    700700
    701     <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostartdelay">
     701    <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-delay">
    702702      <command>VBoxManage controlvm</command>
    703703      <group choice="req">
    … …  
    12171217      </para>
    12181218    </refsect2>
    1219     <refsect2 id="vboxmanage-controlvm-clipboard">
     1219    <refsect2 id="vboxmanage-controlvm-clipboard-mode">
    12201220      <title>Задать как предоставить общий доступ к буферам обмена хост ОС или гостевой ОС</title>
    12211221      <remark role="help-copy-synopsis"/>
    12221222      <para>
    12231223        Команда <command>VBoxManage controlvm
    1224         <replaceable>имя-ВМ</replaceable> clipboard</command> задает
     1224        <replaceable>имя-ВМ</replaceable> clipboard mode</command> задает
    12251225        как предоставить общий доступ к буферам обмена гостевой системы
    12261226        или хоста хост-системе или ВМ. Допустимые значения:
    … …  
    15561556      </para>
    15571557    </refsect2>
    1558     <refsect2 id="vboxmanage-controlvm-recordingscreens">
     1558    <refsect2 id="vboxmanage-controlvm-recording-screens">
    15591559      <title>Задать экран виртуальной машины для записи</title>
    15601560      <remark role="help-copy-synopsis"/>
    … …  
    15821582      </itemizedlist>
    15831583    </refsect2>
    1584     <refsect2 id="vboxmanage-controlvm-recordingfilename">
     1584    <refsect2 id="vboxmanage-controlvm-recording-filename">
    15851585      <title>Задать файл для сохранения записанной сессии виртуальной машины</title>
    15861586      <remark role="help-copy-synopsis"/>
    … …  
    16001600      </para>
    16011601    </refsect2>
    1602     <refsect2 id="vboxmanage-controlvm-recordingvideores">
     1602    <refsect2 id="vboxmanage-controlvm-recording-videores">
    16031603      <title>Задать разрешение записанного видео</title>
    16041604      <remark role="help-copy-synopsis"/>
    … …  
    16291629      </itemizedlist>
    16301630    </refsect2>
    1631     <refsect2 id="vboxmanage-controlvm-recordingvideorate">
     1631    <refsect2 id="vboxmanage-controlvm-recording-videorate">
    16321632      <title>Задать битрейт видео</title>
    16331633      <remark role="help-copy-synopsis"/>
    … …  
    16501650      </para>
    16511651    </refsect2>
    1652     <refsect2 id="vboxmanage-controlvm-recordingvideofps">
     1652    <refsect2 id="vboxmanage-controlvm-recording-videofps">
    16531653      <title>Задать максимальную частоту видео</title>
    16541654      <remark role="help-copy-synopsis"/>
    … …  
    16731673      </para>
    16741674    </refsect2>
    1675     <refsect2 id="vboxmanage-controlvm-recordingmaxtime">
     1675    <refsect2 id="vboxmanage-controlvm-recording-maxtime">
    16761676      <title>Задать максимальное время записи видео</title>
    16771677      <remark role="help-copy-synopsis"/>
    … …  
    16891689      </para>
    16901690    </refsect2>
    1691     <refsect2 id="vboxmanage-controlvm-recordingmaxfilesize">
     1691    <refsect2 id="vboxmanage-controlvm-recording-maxfilesize">
    16921692      <title>Задать максимальный размер записанного видео</title>
    16931693      <remark role="help-copy-synopsis"/>
    … …  
    17991799      </para>
    18001800    </refsect2>
    1801     <refsect2 id="vboxmanage-controlvm-vmprocesspriority">
     1801    <refsect2 id="vboxmanage-controlvm-vm-process-priority">
    18021802      <title>Изменить приоритет процесса ВМ</title>
    18031803      <remark role="help-copy-synopsis"/>
    … …  
    21082108      </variablelist>
    21092109    </refsect2>
    2110     <refsect2 id="vboxmanage-controlvm-autostartenabled">
     2110    <refsect2 id="vboxmanage-controlvm-autostart-enabled">
    21112111      <title>Включить автостарт ВМ во время загрузки хост-системы</title>
    21122112      <remark role="help-copy-synopsis"/>
    … …  
    21232123      </para>
    21242124    </refsect2>
    2125     <refsect2 id="vboxmanage-controlvm-autostartdelay">
     2125    <refsect2 id="vboxmanage-controlvm-autostart-delay">
    21262126      <title>Установить задержку старта ВМ во время загрузки хост-системы</title>
    21272127      <remark role="help-copy-synopsis"/>
    … …  
    21502150      системой.
    21512151    </para>
    2152 <screen>$ VBoxManage controlvm ol7 clipboard bidirectional</screen>
     2152<screen>$ VBoxManage controlvm ol7 clipboard mode bidirectional</screen>
    21532153  </refsect1>
    21542154

  • trunk/include/iprt/message.h

    r93115 r93708  
    234234#define RTMSGREFENTRYSTR_SCOPE_SAME     UINT64_C(0)
    235235/** Global scope. */
    236 #define RTMSGREFENTRYSTR_SCOPE_GLOBAL   UINT64_C(0x00ffffffffffffff)
     236#define RTMSGREFENTRYSTR_SCOPE_GLOBAL   UINT64_C(0x0fffffffffffffff)
    237237/** Scope mask. */
    238 #define RTMSGREFENTRYSTR_SCOPE_MASK     UINT64_C(0x00ffffffffffffff)
     238#define RTMSGREFENTRYSTR_SCOPE_MASK     UINT64_C(0x0fffffffffffffff)
    239239/** Flags mask. */
    240 #define RTMSGREFENTRYSTR_FLAGS_MASK     UINT64_C(0xff00000000000000)
     240#define RTMSGREFENTRYSTR_FLAGS_MASK     UINT64_C(0xf000000000000000)
    241241/** Command synopsis, special hanging indent rules applies. */
    242242#define RTMSGREFENTRYSTR_FLAGS_SYNOPSIS RT_BIT_64(63)

  • trunk/src/VBox/Frontends/VBoxManage/Makefile.kmk

    r93424 r93708  
    337337                '' \
    338338                '#include <iprt/message.h>' \
     339                '#include <iprt/assertcompile.h>' \
    339340                '' \
    340341                'RT_C_DECLS_BEGIN' \

  • trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp

    r93115 r93708  
    213213    { "createvm",           USAGE_S_NEWCMD,     HELP_CMD_CREATEVM, handleCreateVM,             0 },
    214214    { "modifyvm",           USAGE_S_NEWCMD,     HELP_CMD_MODIFYVM, handleModifyVM,             0 },
    215     { "startvm",            USAGE_STARTVM,          VBMG_CMD_TODO, handleStartVM,              0 },
    216     { "controlvm",          USAGE_CONTROLVM,        VBMG_CMD_TODO, handleControlVM,            0 },
     215    { "startvm",            USAGE_S_NEWCMD,      HELP_CMD_STARTVM, handleStartVM,              0 },
     216    { "controlvm",          USAGE_S_NEWCMD,    HELP_CMD_CONTROLVM, handleControlVM,            0 },
    217217    { "unattended",         USAGE_S_NEWCMD,   HELP_CMD_UNATTENDED, handleUnattended,           0 },
    218218    { "discardstate",       USAGE_DISCARDSTATE,     VBMG_CMD_TODO, handleDiscardState,         0 },

  • trunk/src/VBox/Frontends/VBoxManage/VBoxManage.h

    r93706 r93708  
    9898{
    9999    USAGE_INVALID = 0,
    100     USAGE_STARTVM,
    101     USAGE_CONTROLVM,
    102100    USAGE_DISCARDSTATE,
    103101    USAGE_CLOSEMEDIUM,

  • trunk/src/VBox/Frontends/VBoxManage/VBoxManageControlVM.cpp

    r93115 r93708  
    4242#include <list>
    4343
    44 DECLARE_TRANSLATION_CONTEXT(CloudVM);
     44DECLARE_TRANSLATION_CONTEXT(ControlVM);
    4545
    4646VMProcPriority_T nameToVMProcPriority(const char *pszName);
    … …  
    6363        &&  u32 <= cMaxNum)
    6464        return (unsigned)u32;
    65     errorArgument(CloudVM::tr("Invalid %s number '%s'"), name, psz);
     65    errorArgument(ControlVM::tr("Invalid %s number '%s'."), name, psz);
    6666    return 0;
    6767}
    … …  
    213213    com::SafeArray<LONG> saScancodes(llScancodes);
    214214
    215 #if 1
    216215    HRESULT rc = S_OK;
    217216    size_t i;
    … …  
    221220        if (FAILED(rc))
    222221        {
    223             RTMsgError(CloudVM::tr("Failed to send a scancode"));
     222            RTMsgError(ControlVM::tr("Failed to send a scancode."));
    224223            break;
    225224        }
    … …  
    227226        RTThreadSleep(10); /* "Typing" too fast causes lost characters. */
    228227    }
    229 #else
    230     /** @todo PutScancodes does not deliver more than 20 scancodes. */
    231     ULONG codesStored = 0;
    232     HRESULT rc = pKeyboard->PutScancodes(ComSafeArrayAsInParam(saScancodes),
    233                                          &codesStored);
    234     if (SUCCEEDED(rc) && codesStored < saScancodes.size())
    235     {
    236         RTMsgError(CloudVM::tr("Only %d scancodes were stored", "", codesStored), codesStored);
    237         rc = E_FAIL;
    238     }
    239 #endif
    240228
    241229    return rc;
    … …  
    333321                }
    334322                else
    335                     RTMsgError(CloudVM::tr("Out of memory allocating %d bytes", "", cbBuffer), cbBuffer);
     323                    RTMsgError(ControlVM::tr("Out of memory allocating %d bytes.", "", cbBuffer), cbBuffer);
    336324            }
    337325            else
    338                 RTMsgError(CloudVM::tr("File size %RI64 is greater than %RI64: '%s'"), cbFile, cbFileMax, pszFilename);
     326                RTMsgError(ControlVM::tr("File size %RI64 is greater than %RI64: '%s'."), cbFile, cbFileMax, pszFilename);
    339327        }
    340328        else
    341             RTMsgError(CloudVM::tr("Cannot get size of file '%s': %Rrc"), pszFilename, vrc);
     329            RTMsgError(ControlVM::tr("Cannot get size of file '%s': %Rrc."), pszFilename, vrc);
    342330
    343331        RTFileClose(File);
    344332    }
    345333    else
    346         RTMsgError(CloudVM::tr("Cannot open file '%s': %Rrc"), pszFilename, vrc);
     334        RTMsgError(ControlVM::tr("Cannot open file '%s': %Rrc."), pszFilename, vrc);
    347335
    348336    /* Release SHIFT if pressed. */
    … …  
    361349
    362350    if (a->argc < 2)
    363         return errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Not enough parameters"));
     351        return errorSyntax(ControlVM::tr("Not enough parameters."));
    364352
    365353    /* try to find the given machine */
    … …  
    381369        CHECK_ERROR_BREAK(a->session, COMGETTER(Console)(console.asOutParam()));
    382370        if (!console)
    383             return RTMsgErrorExit(RTEXITCODE_FAILURE, CloudVM::tr("Machine '%s' is not currently running"), a->argv[0]);
     371            return RTMsgErrorExit(RTEXITCODE_FAILURE, ControlVM::tr("Machine '%s' is not currently running."), a->argv[0]);
    384372
    385373        /* ... and session machine */
    … …  
    389377        if (!strcmp(a->argv[1], "pause"))
    390378        {
     379            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_PAUSE);
    391380            CHECK_ERROR_BREAK(console, Pause());
    392381        }
    393382        else if (!strcmp(a->argv[1], "resume"))
    394383        {
     384            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RESUME);
    395385            CHECK_ERROR_BREAK(console, Resume());
    396386        }
    397387        else if (!strcmp(a->argv[1], "reset"))
    398388        {
     389            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RESET);
    399390            CHECK_ERROR_BREAK(console, Reset());
    400391        }
    401392        else if (!strcmp(a->argv[1], "unplugcpu"))
    402393        {
     394            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_UNPLUGCPU);
    403395            if (a->argc <= 1 + 1)
    404396            {
    405                 errorArgument(CloudVM::tr("Missing argument to '%s'. Expected CPU number."), a->argv[1]);
     397                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    406398                rc = E_FAIL;
    407399                break;
    … …  
    414406        else if (!strcmp(a->argv[1], "plugcpu"))
    415407        {
     408            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_PLUGCPU);
    416409            if (a->argc <= 1 + 1)
    417410            {
    418                 errorArgument(CloudVM::tr("Missing argument to '%s'. Expected CPU number."), a->argv[1]);
     411                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    419412                rc = E_FAIL;
    420413                break;
    … …  
    427420        else if (!strcmp(a->argv[1], "cpuexecutioncap"))
    428421        {
     422            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_CPUEXECUTIONCAP);
    429423            if (a->argc <= 1 + 1)
    430424            {
    431                 errorArgument(CloudVM::tr("Missing argument to '%s'. Expected execution cap number."), a->argv[1]);
     425                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    432426                rc = E_FAIL;
    433427                break;
    … …  
    440434        else if (!strcmp(a->argv[1], "audioin"))
    441435        {
     436            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_AUDIOIN);
    442437            ComPtr<IAudioAdapter> adapter;
    443438            CHECK_ERROR_BREAK(sessionMachine, COMGETTER(AudioAdapter)(adapter.asOutParam()));
    444439            if (adapter)
    445440            {
    446                 if (!strcmp(a->argv[2], "on"))
    447                 {
    448                     CHECK_ERROR_RET(adapter, COMSETTER(EnabledIn)(TRUE), RTEXITCODE_FAILURE);
    449                 }
    450                 else if (!strcmp(a->argv[2], "off"))
    451                 {
    452                     CHECK_ERROR_RET(adapter, COMSETTER(EnabledIn)(FALSE), RTEXITCODE_FAILURE);
    453                 }
    454                 else
    455                 {
    456                     errorArgument(CloudVM::tr("Invalid value '%s'"), Utf8Str(a->argv[2]).c_str());
    457                     rc = E_FAIL;
    458                     break;
    459                 }
    460                 if (SUCCEEDED(rc))
    461                     fNeedsSaving = true;
     441                bool fEnabled;
     442                if (RT_FAILURE(parseBool(a->argv[2], &fEnabled)))
     443                {
     444                    errorSyntax(ControlVM::tr("Invalid value '%s'."), a->argv[2]);
     445                    rc = E_FAIL;
     446                    break;
     447                }
     448                CHECK_ERROR_RET(adapter, COMSETTER(EnabledIn)(fEnabled), RTEXITCODE_FAILURE);
     449                fNeedsSaving = true;
    462450            }
    463451            else
    464452            {
    465                 errorArgument(CloudVM::tr("audio adapter not enabled in VM configuration"));
     453                errorSyntax(ControlVM::tr("Audio adapter not enabled in VM configuration."));
    466454                rc = E_FAIL;
    467455                break;
    … …  
    470458        else if (!strcmp(a->argv[1], "audioout"))
    471459        {
     460            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_AUDIOOUT);
    472461            ComPtr<IAudioAdapter> adapter;
    473462            CHECK_ERROR_BREAK(sessionMachine, COMGETTER(AudioAdapter)(adapter.asOutParam()));
    474463            if (adapter)
    475464            {
    476                 if (!strcmp(a->argv[2], "on"))
    477                 {
    478                     CHECK_ERROR_RET(adapter, COMSETTER(EnabledOut)(TRUE), RTEXITCODE_FAILURE);
    479                 }
    480                 else if (!strcmp(a->argv[2], "off"))
    481                 {
    482                     CHECK_ERROR_RET(adapter, COMSETTER(EnabledOut)(FALSE), RTEXITCODE_FAILURE);
    483                 }
    484                 else
    485                 {
    486                     errorArgument(CloudVM::tr("Invalid value '%s'"), Utf8Str(a->argv[2]).c_str());
    487                     rc = E_FAIL;
    488                     break;
    489                 }
    490                 if (SUCCEEDED(rc))
    491                     fNeedsSaving = true;
     465                bool fEnabled;
     466                if (RT_FAILURE(parseBool(a->argv[2], &fEnabled)))
     467                {
     468                    errorSyntax(ControlVM::tr("Invalid value '%s'."), a->argv[2]);
     469                    rc = E_FAIL;
     470                    break;
     471                }
     472                CHECK_ERROR_RET(adapter, COMSETTER(EnabledOut)(fEnabled), RTEXITCODE_FAILURE);
     473                fNeedsSaving = true;
    492474            }
    493475            else
    494476            {
    495                 errorArgument(CloudVM::tr("audio adapter not enabled in VM configuration"));
     477                errorSyntax(ControlVM::tr("Audio adapter not enabled in VM configuration."));
    496478                rc = E_FAIL;
    497479                break;
    … …  
    503485            if (a->argc <= 1 + 1)
    504486            {
    505                 errorArgument(CloudVM::tr("Missing argument to '%s'."), a->argv[1]);
     487                errorArgument(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    506488                rc = E_FAIL;
    507489                break;
    … …  
    511493            if (!strcmp(a->argv[2], "mode"))
    512494            {
     495                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_CLIPBOARD_MODE);
     496                if (a->argc <= 1 + 2)
     497                {
     498                    errorSyntax(ControlVM::tr("Missing argument to '%s %s'."), a->argv[1], a->argv[2]);
     499                    rc = E_FAIL;
     500                    break;
     501                }
     502
    513503                if (!strcmp(a->argv[3], "disabled"))
    514504                    mode = ClipboardMode_Disabled;
    … …  
    521511                else
    522512                {
    523                     errorArgument(CloudVM::tr("Invalid '%s' argument '%s'."), a->argv[2], a->argv[3]);
     513                    errorSyntax(ControlVM::tr("Invalid '%s %s' argument '%s'."), a->argv[1], a->argv[2], a->argv[3]);
    524514                    rc = E_FAIL;
    525515                    break;
    … …  
    533523            else if (!strcmp(a->argv[2], "filetransfers"))
    534524            {
     525                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_CLIPBOARD_FILETRANSFERS);
    535526                if (a->argc <= 1 + 2)
    536527                {
    537                     errorArgument(CloudVM::tr("Missing argument to '%s'. Expected enabled / disabled."), a->argv[2]);
    538                     rc = E_FAIL;
    539                     break;
    540                 }
    541 
    542                 BOOL fEnabled;
    543                 if (!strcmp(a->argv[3], "enabled"))
    544                 {
    545                     fEnabled = TRUE;
    546                 }
    547                 else if (!strcmp(a->argv[3], "disabled"))
    548                 {
    549                     fEnabled = FALSE;
    550                 }
    551                 else
    552                 {
    553                     errorArgument(CloudVM::tr("Invalid '%s' argument '%s'."), a->argv[2], a->argv[3]);
     528                    errorSyntax(ControlVM::tr("Missing argument to '%s %s'."), a->argv[1], a->argv[2]);
     529                    rc = E_FAIL;
     530                    break;
     531                }
     532
     533                bool fEnabled;
     534                if (RT_FAILURE(parseBool(a->argv[3], &fEnabled)))
     535                {
     536                    errorSyntax(ControlVM::tr("Invalid '%s %s' argument '%s'."), a->argv[1], a->argv[2], a->argv[3]);
    554537                    rc = E_FAIL;
    555538                    break;
    … …  
    557540
    558541                CHECK_ERROR_BREAK(sessionMachine, COMSETTER(ClipboardFileTransfersEnabled)(fEnabled));
    559                 if (SUCCEEDED(rc))
    560                     fNeedsSaving = true;
     542                fNeedsSaving = true;
    561543            }
    562544# endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS */
    563545            else
    564546            {
    565                 errorArgument(CloudVM::tr("Invalid '%s' argument '%s'."), a->argv[1], a->argv[2]);
     547                errorArgument(ControlVM::tr("Invalid '%s' argument '%s'."), a->argv[1], a->argv[2]);
    566548                rc = E_FAIL;
    567549                break;
    … …  
    571553        else if (!strcmp(a->argv[1], "draganddrop"))
    572554        {
     555            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_DRAGANDDROP);
    573556            if (a->argc <= 1 + 1)
    574557            {
    575                 errorArgument(CloudVM::tr("Missing argument to '%s'. Expected drag and drop mode."), a->argv[1]);
     558                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    576559                rc = E_FAIL;
    577560                break;
    … …  
    589572            else
    590573            {
    591                 errorArgument(CloudVM::tr("Invalid '%s' argument '%s'."), a->argv[1], a->argv[2]);
     574                errorSyntax(ControlVM::tr("Invalid '%s' argument '%s'."), a->argv[1], a->argv[2]);
    592575                rc = E_FAIL;
    593576            }
    … …  
    601584        else if (!strcmp(a->argv[1], "poweroff"))
    602585        {
     586            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_POWEROFF);
    603587            ComPtr<IProgress> progress;
    604588            CHECK_ERROR_BREAK(console, PowerDown(progress.asOutParam()));
    605589
    606590            rc = showProgress(progress);
    607             CHECK_PROGRESS_ERROR(progress, (CloudVM::tr("Failed to power off machine")));
     591            CHECK_PROGRESS_ERROR(progress, (ControlVM::tr("Failed to power off machine.")));
    608592        }
    609593        else if (!strcmp(a->argv[1], "savestate"))
    610594        {
     595            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_SAVESTATE);
    611596            /* first pause so we don't trigger a live save which needs more time/resources */
    612597            bool fPaused = false;
    … …  
    624609                    if (machineState != MachineState_Paused)
    625610                    {
    626                         RTMsgError(CloudVM::tr("Machine in invalid state %d -- %s\n"),
     611                        RTMsgError(ControlVM::tr("Machine in invalid state %d -- %s."),
    627612                                   machineState, machineStateToName(machineState, false));
    628613                    }
    … …  
    647632
    648633            rc = showProgress(progress);
    649             CHECK_PROGRESS_ERROR(progress, (CloudVM::tr("Failed to save machine state")));
     634            CHECK_PROGRESS_ERROR(progress, (ControlVM::tr("Failed to save machine state.")));
    650635            if (FAILED(rc))
    651636            {
    … …  
    656641        else if (!strcmp(a->argv[1], "acpipowerbutton"))
    657642        {
     643            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_ACPIPOWERBUTTON);
    658644            CHECK_ERROR_BREAK(console, PowerButton());
    659645        }
    660646        else if (!strcmp(a->argv[1], "acpisleepbutton"))
    661647        {
     648            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_ACPISLEEPBUTTON);
    662649            CHECK_ERROR_BREAK(console, SleepButton());
    663650        }
    … …  
    666653                 || !strcmp(a->argv[1], "shutdown")) /* With shutdown we mean gracefully powering off the VM by letting the guest OS do its thing. */
    667654        {
     655            const bool fReboot = !strcmp(a->argv[1], "reboot");
     656            if (fReboot)
     657                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_REBOOT);
     658            else
     659                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_SHUTDOWN);
     660
    668661            ComPtr<IGuest> pGuest;
    669662            CHECK_ERROR_BREAK(console, COMGETTER(Guest)(pGuest.asOutParam()));
    670663            if (!pGuest)
    671664            {
    672                 RTMsgError(CloudVM::tr("Guest not running"));
    673                 rc = E_FAIL;
    674                 break;
    675             }
    676 
    677             const bool fReboot = !strcmp(a->argv[1], "reboot");
     665                RTMsgError(ControlVM::tr("Guest not running."));
     666                rc = E_FAIL;
     667                break;
     668            }
    678669
    679670            com::SafeArray<GuestShutdownFlag_T> aShutdownFlags;
    … …  
    691682            {
    692683                if (rc == VBOX_E_NOT_SUPPORTED)
    693                     RTPrintf(CloudVM::tr("Current installed Guest Additions don't support %s the guest."),
    694                              fReboot ? CloudVM::tr("rebooting") : CloudVM::tr("shutting down"));
     684                {
     685                    if (fReboot)
     686                        RTMsgError(ControlVM::tr("Current installed Guest Additions don't support rebooting the guest."));
     687                    else
     688                        RTMsgError(ControlVM::tr("Current installed Guest Additions don't support shutting down the guest."));
     689                }
    695690            }
    696691        }
    … …  
    698693        else if (!strcmp(a->argv[1], "keyboardputscancode"))
    699694        {
     695            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_KEYBOARDPUTSCANCODE);
    700696            ComPtr<IKeyboard> pKeyboard;
    701697            CHECK_ERROR_BREAK(console, COMGETTER(Keyboard)(pKeyboard.asOutParam()));
    702698            if (!pKeyboard)
    703699            {
    704                 RTMsgError(CloudVM::tr("Guest not running"));
     700                RTMsgError(ControlVM::tr("Guest not running."));
    705701                rc = E_FAIL;
    706702                break;
    … …  
    709705            if (a->argc <= 1 + 1)
    710706            {
    711                 errorArgument(CloudVM::tr("Missing argument to '%s'. Expected IBM PC AT set 2 keyboard scancode(s) as hex byte(s)."),
     707                errorSyntax(ControlVM::tr("Missing argument to '%s'. Expected IBM PC AT set 2 keyboard scancode(s)."),
    712708                              a->argv[1]);
    713709                rc = E_FAIL;
    … …  
    729725                    if (RT_FAILURE (irc))
    730726                    {
    731                         RTMsgError(CloudVM::tr("Converting '%s' returned %Rrc!"), a->argv[i], rc);
     727                        RTMsgError(ControlVM::tr("Converting '%s' returned %Rrc!"), a->argv[i], rc);
    732728                        rc = E_FAIL;
    733729                        break;
    … …  
    738734                else
    739735                {
    740                     RTMsgError(CloudVM::tr("Error: '%s' is not a hex byte!"), a->argv[i]);
     736                    RTMsgError(ControlVM::tr("'%s' is not a hex byte!"), a->argv[i]);
    741737                    rc = E_FAIL;
    742738                    break;
    … …  
    751747        else if (!strcmp(a->argv[1], "keyboardputstring"))
    752748        {
     749            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_KEYBOARDPUTSTRING);
    753750            ComPtr<IKeyboard> pKeyboard;
    754751            CHECK_ERROR_BREAK(console, COMGETTER(Keyboard)(pKeyboard.asOutParam()));
    755752            if (!pKeyboard)
    756753            {
    757                 RTMsgError(CloudVM::tr("Guest not running"));
     754                RTMsgError(ControlVM::tr("Guest not running."));
    758755                rc = E_FAIL;
    759756                break;
    … …  
    762759            if (a->argc <= 1 + 1)
    763760            {
    764                 errorArgument(CloudVM::tr("Missing argument to '%s'. Expected ASCII string(s)."), a->argv[1]);
     761                errorSyntax(ControlVM::tr("Missing argument to '%s'. Expected ASCII string(s)."), a->argv[1]);
    765762                rc = E_FAIL;
    766763                break;
    … …  
    771768        else if (!strcmp(a->argv[1], "keyboardputfile"))
    772769        {
     770            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_KEYBOARDPUTFILE);
    773771            ComPtr<IKeyboard> pKeyboard;
    774772            CHECK_ERROR_BREAK(console, COMGETTER(Keyboard)(pKeyboard.asOutParam()));
    775773            if (!pKeyboard)
    776774            {
    777                 RTMsgError(CloudVM::tr("Guest not running"));
     775                RTMsgError(ControlVM::tr("Guest not running."));
    778776                rc = E_FAIL;
    779777                break;
    … …  
    782780            if (a->argc <= 1 + 1)
    783781            {
    784                 errorArgument(CloudVM::tr("Missing argument to '%s'. Expected file name."), a->argv[1]);
     782                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    785783                rc = E_FAIL;
    786784                break;
    … …  
    791789        else if (!strncmp(a->argv[1], "setlinkstate", 12))
    792790        {
     791            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_SETLINKSTATE);
    793792            /* Get the number of network adapters */
    794793            ULONG NetworkAdapterCount = getMaxNics(a->virtualBox, sessionMachine);
    … …  
    801800            if (a->argc <= 1 + 1)
    802801            {
    803                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     802                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    804803                rc = E_FAIL;
    805804                break;
    … …  
    810809            if (adapter)
    811810            {
    812                 if (!strcmp(a->argv[2], "on"))
    813                 {
    814                     CHECK_ERROR_BREAK(adapter, COMSETTER(CableConnected)(TRUE));
    815                 }
    816                 else if (!strcmp(a->argv[2], "off"))
    817                 {
    818                     CHECK_ERROR_BREAK(adapter, COMSETTER(CableConnected)(FALSE));
    819                 }
    820                 else
    821                 {
    822                     errorArgument(CloudVM::tr("Invalid link state '%s'"), Utf8Str(a->argv[2]).c_str());
    823                     rc = E_FAIL;
    824                     break;
    825                 }
    826                 if (SUCCEEDED(rc))
    827                     fNeedsSaving = true;
     811                bool fEnabled;
     812                if (RT_FAILURE(parseBool(a->argv[3], &fEnabled)))
     813                {
     814                    errorSyntax(ControlVM::tr("Invalid link state '%s'."), a->argv[2]);
     815                    rc = E_FAIL;
     816                    break;
     817                }
     818                CHECK_ERROR_BREAK(adapter, COMSETTER(CableConnected)(fEnabled));
     819                fNeedsSaving = true;
    828820            }
    829821        }
    … …  
    835827        else if (!strncmp(a->argv[1], "nictracefile", 12))
    836828        {
     829            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_NICTRACEFILE);
    837830            /* Get the number of network adapters */
    838831            ULONG NetworkAdapterCount = getMaxNics(a->virtualBox, sessionMachine);
    … …  
    845838            if (a->argc <= 2)
    846839            {
    847                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     840                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    848841                rc = E_FAIL;
    849842                break;
    … …  
    865858                    else
    866859                    {
    867                         errorArgument(CloudVM::tr("Invalid filename or filename not specified for NIC %lu"), n);
     860                        errorSyntax(ControlVM::tr("Filename not specified for NIC %lu."), n);
    868861                        rc = E_FAIL;
    869862                        break;
    … …  
    873866                }
    874867                else
    875                     RTMsgError(CloudVM::tr("The NIC %d is currently disabled and thus its tracefile can't be changed"), n);
     868                    RTMsgError(ControlVM::tr("The NIC %d is currently disabled and thus its tracefile can't be changed."), n);
    876869            }
    877870        }
    878871        else if (!strncmp(a->argv[1], "nictrace", 8))
    879872        {
     873            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_NICTRACE);
    880874            /* Get the number of network adapters */
    881875            ULONG NetworkAdapterCount = getMaxNics(a->virtualBox, sessionMachine);
    … …  
    888882            if (a->argc <= 2)
    889883            {
    890                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     884                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    891885                rc = E_FAIL;
    892886                break;
    … …  
    902896                if (fEnabled)
    903897                {
    904                     if (!strcmp(a->argv[2], "on"))
     898                    bool fTraceEnabled;
     899                    if (RT_FAILURE(parseBool(a->argv[3], &fTraceEnabled)))
    905900                    {
    906                         CHECK_ERROR_RET(adapter, COMSETTER(TraceEnabled)(TRUE), RTEXITCODE_FAILURE);
    907                     }
    908                     else if (!strcmp(a->argv[2], "off"))
    909                     {
    910                         CHECK_ERROR_RET(adapter, COMSETTER(TraceEnabled)(FALSE), RTEXITCODE_FAILURE);
    911                     }
    912                     else
    913                     {
    914                         errorArgument(CloudVM::tr("Invalid nictrace%lu argument '%s'"), n, Utf8Str(a->argv[2]).c_str());
     901                        errorSyntax(ControlVM::tr("Invalid nictrace%lu argument '%s'."), n, a->argv[2]);
    915902                        rc = E_FAIL;
    916903                        break;
    917904                    }
    918                     if (SUCCEEDED(rc))
    919                         fNeedsSaving = true;
     905                    CHECK_ERROR_RET(adapter, COMSETTER(TraceEnabled)(fTraceEnabled), RTEXITCODE_FAILURE);
     906                    fNeedsSaving = true;
    920907                }
    921908                else
    922                     RTMsgError(CloudVM::tr("The NIC %d is currently disabled and thus its trace flag can't be changed"), n);
     909                    RTMsgError(ControlVM::tr("The NIC %d is currently disabled and thus its trace flag can't be changed."), n);
    923910            }
    924911        }
    … …  
    936923            if (a->argc <= 2)
    937924            {
    938                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     925                errorArgument(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    939926                rc = E_FAIL;
    940927                break;
    … …  
    959946            if (!strcmp(a->argv[2], "delete"))
    960947            {
     948                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_NATPF_DELETE);
    961949                if (a->argc >= 3)
    962950                    CHECK_ERROR(engine, RemoveRedirect(Bstr(a->argv[3]).raw()));
    … …  
    964952            else
    965953            {
     954                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_NATPF);
    966955#define ITERATE_TO_NEXT_TERM(ch)                                                        \
    967956    do {                                                                                \
    … …  
    970959            if (*ch == 0)                                                               \
    971960            {                                                                           \
    972                 return errorSyntax(USAGE_CONTROLVM,                                     \
    973                                    CloudVM::tr("Missing or invalid argument to '%s'"),  \
    974                                     a->argv[1]);                                        \
     961                return errorSyntax(ControlVM::tr("Missing or invalid argument to '%s'."), \
     962                                   a->argv[1]);                                         \
    975963            }                                                                           \
    976964            ch++;                                                                       \
    … …  
    1006994                else
    1007995                {
    1008                     return errorSyntax(USAGE_CONTROLVM,
    1009                                        CloudVM::tr("Wrong rule proto '%s' specified -- only 'udp' and 'tcp' are allowed."),
     996                    return errorSyntax(ControlVM::tr("Wrong rule proto '%s' specified -- only 'udp' and 'tcp' are allowed."),
    1010997                                       strProto);
    1011998                }
    … …  
    10191006        else if (!strncmp(a->argv[1], "nicproperty", 11))
    10201007        {
     1008            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_NICPROPERTY);
    10211009            /* Get the number of network adapters */
    10221010            ULONG NetworkAdapterCount = getMaxNics(a->virtualBox, sessionMachine);
    … …  
    10291017            if (a->argc <= 2)
    10301018            {
    1031                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     1019                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    10321020                rc = E_FAIL;
    10331021                break;
    … …  
    10601048                        else
    10611049                        {
    1062                             errorArgument(CloudVM::tr("Invalid nicproperty%d argument '%s'"), n, a->argv[2]);
     1050                            errorSyntax(ControlVM::tr("Invalid nicproperty%d argument '%s'."), n, a->argv[2]);
    10631051                            rc = E_FAIL;
    10641052                        }
    … …  
    10671055                    else
    10681056                    {
    1069                         RTStrmPrintf(g_pStdErr, CloudVM::tr("Error: Failed to allocate memory for nicproperty%d '%s'\n"),
     1057                        RTMsgError(ControlVM::tr("Failed to allocate memory for nicproperty%d '%s'."),
    10701058                                     n, a->argv[2]);
    10711059                        rc = E_FAIL;
    … …  
    10751063                }
    10761064                else
    1077                     RTMsgError(CloudVM::tr("The NIC %d is currently disabled and thus its properties can't be changed"), n);
     1065                    RTMsgError(ControlVM::tr("The NIC %d is currently disabled and thus its properties can't be changed."), n);
    10781066            }
    10791067        }
    10801068        else if (!strncmp(a->argv[1], "nicpromisc", 10))
    10811069        {
     1070            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_NICPROMISC);
    10821071            /* Get the number of network adapters */
    10831072            ULONG NetworkAdapterCount = getMaxNics(a->virtualBox, sessionMachine);
    … …  
    10901079            if (a->argc <= 2)
    10911080            {
    1092                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     1081                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    10931082                rc = E_FAIL;
    10941083                break;
    … …  
    11141103                    else
    11151104                    {
    1116                         errorArgument(CloudVM::tr("Unknown promiscuous mode policy '%s'"), a->argv[2]);
     1105                        errorSyntax(ControlVM::tr("Unknown promiscuous mode policy '%s'."), a->argv[2]);
    11171106                        rc = E_INVALIDARG;
    11181107                        break;
    … …  
    11241113                }
    11251114                else
    1126                     RTMsgError(CloudVM::tr("The NIC %d is currently disabled and thus its promiscuous mode can't be changed"), n);
     1115                    RTMsgError(ControlVM::tr("The NIC %d is currently disabled and thus its promiscuous mode can't be changed."), n);
    11271116            }
    11281117        }
    11291118        else if (!strncmp(a->argv[1], "nic", 3))
    11301119        {
     1120            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_NIC);
    11311121            /* Get the number of network adapters */
    11321122            ULONG NetworkAdapterCount = getMaxNics(a->virtualBox, sessionMachine);
    … …  
    11391129            if (a->argc <= 2)
    11401130            {
    1141                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     1131                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    11421132                rc = E_FAIL;
    11431133                break;
    … …  
    11681158                        if (a->argc <= 3)
    11691159                        {
    1170                             errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[2]);
     1160                            errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[2]);
    11711161                            rc = E_FAIL;
    11721162                            break;
    … …  
    11801170                        if (a->argc <= 3)
    11811171                        {
    1182                             errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[2]);
     1172                            errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[2]);
    11831173                            rc = E_FAIL;
    11841174                            break;
    … …  
    11921182                        if (a->argc <= 3)
    11931183                        {
    1194                             errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[2]);
     1184                            errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[2]);
    11951185                            rc = E_FAIL;
    11961186                            break;
    … …  
    12051195                        if (a->argc <= 3)
    12061196                        {
    1207                             errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[2]);
     1197                            errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[2]);
    12081198                            rc = E_FAIL;
    12091199                            break;
    … …  
    12161206                        if (a->argc <= 3)
    12171207                        {
    1218                             errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[2]);
     1208                            errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[2]);
    12191209                            rc = E_FAIL;
    12201210                            break;
    … …  
    12231213                        CHECK_ERROR_RET(adapter, COMSETTER(AttachmentType)(NetworkAttachmentType_NATNetwork), RTEXITCODE_FAILURE);
    12241214                    }
    1225                     /** @todo obsolete, remove eventually */
    1226                     else if (!strcmp(a->argv[2], "vde"))
    1227                     {
    1228                         if (a->argc <= 3)
    1229                         {
    1230                             errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[2]);
    1231                             rc = E_FAIL;
    1232                             break;
    1233                         }
    1234                         CHECK_ERROR_RET(adapter, COMSETTER(AttachmentType)(NetworkAttachmentType_Generic), RTEXITCODE_FAILURE);
    1235                         CHECK_ERROR_RET(adapter, SetProperty(Bstr("name").raw(), Bstr(a->argv[3]).raw()), RTEXITCODE_FAILURE);
    1236                     }
    12371215                    else
    12381216                    {
    1239                         errorArgument(CloudVM::tr("Invalid type '%s' specfied for NIC %lu"), Utf8Str(a->argv[2]).c_str(), n);
     1217                        errorSyntax(ControlVM::tr("Invalid type '%s' specfied for NIC %lu."), a->argv[2], n);
    12401218                        rc = E_FAIL;
    12411219                        break;
    … …  
    12451223                }
    12461224                else
    1247                     RTMsgError(CloudVM::tr("The NIC %d is currently disabled and thus its attachment type can't be changed"), n);
     1225                    RTMsgError(ControlVM::tr("The NIC %d is currently disabled and thus its attachment type can't be changed."), n);
    12481226            }
    12491227        }
    … …  
    12511229                 || !strcmp(a->argv[1], "vrdp"))
    12521230        {
     1231            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_VRDE);
    12531232            if (!strcmp(a->argv[1], "vrdp"))
    1254                 RTStrmPrintf(g_pStdErr, CloudVM::tr("Warning: 'vrdp' is deprecated. Use 'vrde'.\n"));
     1233                RTMsgWarning(ControlVM::tr("'vrdp' is deprecated. Use 'vrde'."));
    12551234
    12561235            if (a->argc <= 1 + 1)
    12571236            {
    1258                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     1237                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    12591238                rc = E_FAIL;
    12601239                break;
    … …  
    12651244            if (vrdeServer)
    12661245            {
    1267                 if (!strcmp(a->argv[2], "on"))
    1268                 {
    1269                     CHECK_ERROR_BREAK(vrdeServer, COMSETTER(Enabled)(TRUE));
    1270                 }
    1271                 else if (!strcmp(a->argv[2], "off"))
    1272                 {
    1273                     CHECK_ERROR_BREAK(vrdeServer, COMSETTER(Enabled)(FALSE));
    1274                 }
    1275                 else
    1276                 {
    1277                     errorArgument(CloudVM::tr("Invalid remote desktop server state '%s'"), Utf8Str(a->argv[2]).c_str());
    1278                     rc = E_FAIL;
    1279                     break;
    1280                 }
    1281                 if (SUCCEEDED(rc))
    1282                     fNeedsSaving = true;
     1246                bool fEnabled;
     1247                if (RT_FAILURE(parseBool(a->argv[2], &fEnabled)))
     1248                {
     1249                    errorSyntax(ControlVM::tr("Invalid remote desktop server state '%s'."), a->argv[2]);
     1250                    rc = E_FAIL;
     1251                    break;
     1252                }
     1253                CHECK_ERROR_BREAK(vrdeServer, COMSETTER(Enabled)(fEnabled));
     1254                fNeedsSaving = true;
    12831255            }
    12841256        }
    … …  
    12861258                 || !strcmp(a->argv[1], "vrdpport"))
    12871259        {
     1260            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_VRDEPORT);
    12881261            if (!strcmp(a->argv[1], "vrdpport"))
    1289                 RTStrmPrintf(g_pStdErr, CloudVM::tr("Warning: 'vrdpport' is deprecated. Use 'vrdeport'.\n"));
     1262                RTMsgWarning(ControlVM::tr("'vrdpport' is deprecated. Use 'vrdeport'."));
    12901263
    12911264            if (a->argc <= 1 + 1)
    12921265            {
    1293                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     1266                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    12941267                rc = E_FAIL;
    12951268                break;
    … …  
    13161289                 || !strcmp(a->argv[1], "vrdpvideochannelquality"))
    13171290        {
     1291            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_VRDEVIDEOCHANNELQUALITY);
    13181292            if (!strcmp(a->argv[1], "vrdpvideochannelquality"))
    1319                 RTStrmPrintf(g_pStdErr,
    1320                              CloudVM::tr("Warning: 'vrdpvideochannelquality' is deprecated. Use 'vrdevideochannelquality'.\n"));
     1293                RTMsgWarning(ControlVM::tr("'vrdpvideochannelquality' is deprecated. Use 'vrdevideochannelquality'."));
    13211294
    13221295            if (a->argc <= 1 + 1)
    13231296            {
    1324                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     1297                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    13251298                rc = E_FAIL;
    13261299                break;
    … …  
    13401313        else if (!strcmp(a->argv[1], "vrdeproperty"))
    13411314        {
     1315            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_VRDEPROPERTY);
    13421316            if (a->argc <= 1 + 1)
    13431317            {
    1344                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     1318                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    13451319                rc = E_FAIL;
    13461320                break;
    … …  
    13681342                    else
    13691343                    {
    1370                         errorArgument(CloudVM::tr("Invalid vrdeproperty argument '%s'"), a->argv[2]);
     1344                        errorSyntax(ControlVM::tr("Invalid vrdeproperty argument '%s'."), a->argv[2]);
    13711345                        rc = E_FAIL;
    13721346                    }
    … …  
    13751349                else
    13761350                {
    1377                     RTStrmPrintf(g_pStdErr, CloudVM::tr("Error: Failed to allocate memory for VRDE property '%s'\n"),
     1351                    RTMsgError(ControlVM::tr("Failed to allocate memory for VRDE property '%s'."),
    13781352                                 a->argv[2]);
    13791353                    rc = E_FAIL;
    … …  
    13881362                 || !strcmp(a->argv[1], "usbdetach"))
    13891363        {
     1364            bool attach = !strcmp(a->argv[1], "usbattach");
     1365            if (attach)
     1366                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_USBATTACH);
     1367            else
     1368                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_USBDETACH);
     1369
    13901370            if (a->argc < 3)
    13911371            {
    1392                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Not enough parameters"));
     1372                errorSyntax(ControlVM::tr("Not enough parameters."));
    13931373                rc = E_FAIL;
    13941374                break;
    … …  
    13961376            else if (a->argc == 4 || a->argc > 5)
    13971377            {
    1398                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Wrong number of arguments"));
    1399                 rc = E_FAIL;
    1400                 break;
    1401             }
    1402 
    1403             bool attach = !strcmp(a->argv[1], "usbattach");
     1378                errorSyntax(ControlVM::tr("Wrong number of arguments."));
     1379                rc = E_FAIL;
     1380                break;
     1381            }
    14041382
    14051383            Bstr usbId = a->argv[2];
    … …  
    14121390                else
    14131391                {
    1414                     errorArgument(CloudVM::tr("Invalid parameter '%s'"), a->argv[3]);
     1392                    errorSyntax(ControlVM::tr("Invalid parameter '%s'."), a->argv[3]);
    14151393                    rc = E_FAIL;
    14161394                    break;
    … …  
    14451423            else if (guid.isZero())
    14461424            {
    1447                 errorArgument(CloudVM::tr("Zero UUID argument '%s'"), a->argv[2]);
     1425                errorSyntax(ControlVM::tr("Zero UUID argument '%s'."), a->argv[2]);
    14481426                rc = E_FAIL;
    14491427                break;
    … …  
    14611439        else if (!strcmp(a->argv[1], "setvideomodehint"))
    14621440        {
     1441            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_SETVIDEOMODEHINT);
    14631442            if (a->argc != 5 && a->argc != 6 && a->argc != 7 && a->argc != 9)
    14641443            {
    1465                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1444                errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    14661445                rc = E_FAIL;
    14671446                break;
    … …  
    14791458            if (a->argc >= 7)
    14801459            {
    1481                 int vrc = parseBool(a->argv[6], &fEnabled);
    1482                 if (RT_FAILURE(vrc))
    1483                 {
    1484                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Either \"yes\" or \"no\" is expected"));
    1485                     rc = E_FAIL;
    1486                     break;
    1487                 }
    1488                 fEnabled = !RTStrICmp(a->argv[6], "yes");
     1460                if (RT_FAILURE(parseBool(a->argv[6], &fEnabled)))
     1461                {
     1462                    errorSyntax(ControlVM::tr("Either \"yes\" or \"no\" is expected."));
     1463                    rc = E_FAIL;
     1464                    break;
     1465                }
    14891466            }
    14901467            if (a->argc == 9)
    … …  
    14991476            if (!pDisplay)
    15001477            {
    1501                 RTMsgError(CloudVM::tr("Guest not running"));
     1478                RTMsgError(ControlVM::tr("Guest not running."));
    15021479                rc = E_FAIL;
    15031480                break;
    … …  
    15091486        else if (!strcmp(a->argv[1], "setscreenlayout"))
    15101487        {
     1488            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_SETSCREENLAYOUT);
    15111489            if (a->argc < 4)
    15121490            {
    1513                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1491                errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    15141492                rc = E_FAIL;
    15151493                break;
    … …  
    15201498            if (!pDisplay)
    15211499            {
    1522                 RTMsgError(CloudVM::tr("Guest not running"));
     1500                RTMsgError(ControlVM::tr("Guest not running."));
    15231501                rc = E_FAIL;
    15241502                break;
    … …  
    15471525                else
    15481526                {
    1549                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Display status must be <on> or <off>"));
     1527                    errorSyntax(ControlVM::tr("Display status must be <on> or <off>."));
    15501528                    rc = E_FAIL;
    15511529                    break;
    … …  
    15621540                    if (argc < 7)
    15631541                    {
    1564                         errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1542                        errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    15651543                        rc = E_FAIL;
    15661544                        break;
    … …  
    15971575        else if (!strcmp(a->argv[1], "setcredentials"))
    15981576        {
     1577            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_SETCREDENTIALS);
    15991578            bool fAllowLocalLogon = true;
    16001579            if (   a->argc == 7
    … …  
    16061585                    && strcmp(a->argv[5 + (a->argc - 7)], "-allowlocallogon"))
    16071586                {
    1608                     errorArgument(CloudVM::tr("Invalid parameter '%s'"), a->argv[5]);
     1587                    errorSyntax(ControlVM::tr("Invalid parameter '%s'."), a->argv[5]);
    16091588                    rc = E_FAIL;
    16101589                    break;
    … …  
    16181597                             && strcmp(a->argv[3], "--passwordfile"))))
    16191598            {
    1620                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1599                errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    16211600                rc = E_FAIL;
    16221601                break;
    … …  
    16431622            if (!pGuest)
    16441623            {
    1645                 RTMsgError(CloudVM::tr("Guest not running"));
     1624                RTMsgError(ControlVM::tr("Guest not running."));
    16461625                rc = E_FAIL;
    16471626                break;
    … …  
    16521631                                                     fAllowLocalLogon));
    16531632        }
    1654 #if 0 /** @todo review & remove */
    1655         else if (!strcmp(a->argv[1], "dvdattach"))
    1656         {
    1657             Bstr uuid;
     1633        else if (!strcmp(a->argv[1], "guestmemoryballoon"))
     1634        {
     1635            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_GUESTMEMORYBALLOON);
    16581636            if (a->argc != 3)
    16591637            {
    1660                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
    1661                 rc = E_FAIL;
    1662                 break;
    1663             }
    1664 
    1665             ComPtr<IMedium> dvdMedium;
    1666 
    1667             /* unmount? */
    1668             if (!strcmp(a->argv[2], "none"))
    1669             {
    1670                 /* nothing to do, NULL object will cause unmount */
    1671             }
    1672             /* host drive? */
    1673             else if (!strncmp(a->argv[2], "host:", 5))
    1674             {
    1675                 ComPtr<IHost> host;
    1676                 CHECK_ERROR(a->virtualBox, COMGETTER(Host)(host.asOutParam()));
    1677 
    1678                 rc = host->FindHostDVDDrive(Bstr(a->argv[2] + 5), dvdMedium.asOutParam());
    1679                 if (!dvdMedium)
    1680                 {
    1681                     errorArgument(CloudVM::tr("Invalid host DVD drive name \"%s\""),
    1682                                   a->argv[2] + 5);
    1683                     rc = E_FAIL;
    1684                     break;
    1685                 }
    1686             }
    1687             else
    1688             {
    1689                 /* first assume it's a UUID */
    1690                 uuid = a->argv[2];
    1691                 rc = a->virtualBox->GetDVDImage(uuid, dvdMedium.asOutParam());
    1692                 if (FAILED(rc) || !dvdMedium)
    1693                 {
    1694                     /* must be a filename, check if it's in the collection */
    1695                     rc = a->virtualBox->FindDVDImage(Bstr(a->argv[2]), dvdMedium.asOutParam());
    1696                     /* not registered, do that on the fly */
    1697                     if (!dvdMedium)
    1698                     {
    1699                         Bstr emptyUUID;
    1700                         CHECK_ERROR(a->virtualBox, OpenDVDImage(Bstr(a->argv[2]), emptyUUID, dvdMedium.asOutParam()));
    1701                     }
    1702                 }
    1703                 if (!dvdMedium)
    1704                 {
    1705                     rc = E_FAIL;
    1706                     break;
    1707                 }
    1708             }
    1709 
    1710             /** @todo generalize this, allow arbitrary number of DVD drives
    1711              * and as a consequence multiple attachments and different
    1712              * storage controllers. */
    1713             if (dvdMedium)
    1714                 dvdMedium->COMGETTER(Id)(uuid.asOutParam());
    1715             else
    1716                 uuid = Guid().toString();
    1717             CHECK_ERROR(sessionMachine, MountMedium(Bstr(CloudVM::tr("IDE Controller")), 1, 0, uuid, FALSE /* aForce */));
    1718         }
    1719         else if (!strcmp(a->argv[1], "floppyattach"))
    1720         {
    1721             Bstr uuid;
    1722             if (a->argc != 3)
    1723             {
    1724                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
    1725                 rc = E_FAIL;
    1726                 break;
    1727             }
    1728 
    1729             ComPtr<IMedium> floppyMedium;
    1730 
    1731             /* unmount? */
    1732             if (!strcmp(a->argv[2], "none"))
    1733             {
    1734                 /* nothing to do, NULL object will cause unmount */
    1735             }
    1736             /* host drive? */
    1737             else if (!strncmp(a->argv[2], "host:", 5))
    1738             {
    1739                 ComPtr<IHost> host;
    1740                 CHECK_ERROR(a->virtualBox, COMGETTER(Host)(host.asOutParam()));
    1741                 host->FindHostFloppyDrive(Bstr(a->argv[2] + 5), floppyMedium.asOutParam());
    1742                 if (!floppyMedium)
    1743                 {
    1744                     errorArgument(CloudVM::tr("Invalid host floppy drive name \"%s\""),
    1745                                   a->argv[2] + 5);
    1746                     rc = E_FAIL;
    1747                     break;
    1748                 }
    1749             }
    1750             else
    1751             {
    1752                 /* first assume it's a UUID */
    1753                 uuid = a->argv[2];
    1754                 rc = a->virtualBox->GetFloppyImage(uuid, floppyMedium.asOutParam());
    1755                 if (FAILED(rc) || !floppyMedium)
    1756                 {
    1757                     /* must be a filename, check if it's in the collection */
    1758                     rc = a->virtualBox->FindFloppyImage(Bstr(a->argv[2]), floppyMedium.asOutParam());
    1759                     /* not registered, do that on the fly */
    1760                     if (!floppyMedium)
    1761                     {
    1762                         Bstr emptyUUID;
    1763                         CHECK_ERROR(a->virtualBox, OpenFloppyImage(Bstr(a->argv[2]), emptyUUID, floppyMedium.asOutParam()));
    1764                     }
    1765                 }
    1766                 if (!floppyMedium)
    1767                 {
    1768                     rc = E_FAIL;
    1769                     break;
    1770                 }
    1771             }
    1772             floppyMedium->COMGETTER(Id)(uuid.asOutParam());
    1773             CHECK_ERROR(sessionMachine, MountMedium(Bstr(CloudVM::tr("Floppy Controller")), 0, 0, uuid, FALSE /* aForce */));
    1774         }
    1775 #endif /* obsolete dvdattach/floppyattach */
    1776         else if (!strcmp(a->argv[1], "guestmemoryballoon"))
    1777         {
    1778             if (a->argc != 3)
    1779             {
    1780                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1638                errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    17811639                rc = E_FAIL;
    17821640                break;
    … …  
    17871645            if (vrc != VINF_SUCCESS)
    17881646            {
    1789                 errorArgument(CloudVM::tr("Error parsing guest memory balloon size '%s'"), a->argv[2]);
     1647                errorSyntax(ControlVM::tr("Error parsing guest memory balloon size '%s'."), a->argv[2]);
    17901648                rc = E_FAIL;
    17911649                break;
    … …  
    17981656                if (!pGuest)
    17991657                {
    1800                     RTMsgError(CloudVM::tr("Guest not running"));
     1658                    RTMsgError(ControlVM::tr("Guest not running."));
    18011659                    rc = E_FAIL;
    18021660                    break;
    … …  
    18151673            {
    18161674                { "--host",              'h', RTGETOPT_REQ_STRING }, /** @todo RTGETOPT_FLAG_MANDATORY */
    1817                 { "--hostname",          'h', RTGETOPT_REQ_STRING }, /** @todo remove this */
    18181675                { "--maxdowntime",       'd', RTGETOPT_REQ_UINT32 },
    18191676                { "--port",              'P', RTGETOPT_REQ_UINT32 }, /** @todo RTGETOPT_FLAG_MANDATORY */
    … …  
    18251682            RTGETOPTSTATE GetOptState;
    18261683            RTGetOptInit(&GetOptState, a->argc, a->argv, s_aTeleportOptions, RT_ELEMENTS(s_aTeleportOptions), 2, RTGETOPTINIT_FLAGS_NO_STD_OPTS);
     1684            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_TELEPORT);
    18271685            int ch;
    18281686            RTGETOPTUNION Value;
    … …  
    18461704                    case 't': cMsTimeout    = Value.u32; break;
    18471705                    default:
    1848                         errorGetOpt(USAGE_CONTROLVM, ch, &Value);
     1706                        errorGetOpt(ch, &Value);
    18491707                        rc = E_FAIL;
    18501708                        break;
    … …  
    18681726
    18691727            rc = showProgress(progress);
    1870             CHECK_PROGRESS_ERROR(progress, (CloudVM::tr("Teleportation failed")));
     1728            CHECK_PROGRESS_ERROR(progress, (ControlVM::tr("Teleportation failed")));
    18711729        }
    18721730        else if (!strcmp(a->argv[1], "screenshotpng"))
    18731731        {
     1732            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_SCREENSHOTPNG);
    18741733            if (a->argc <= 2 || a->argc > 4)
    18751734            {
    1876                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1735                errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    18771736                rc = E_FAIL;
    18781737                break;
    … …  
    18851744                if (vrc != VINF_SUCCESS)
    18861745                {
    1887                     errorArgument(CloudVM::tr("Error parsing display number '%s'"), a->argv[3]);
     1746                    errorSyntax(ControlVM::tr("Error parsing display number '%s'."), a->argv[3]);
    18881747                    rc = E_FAIL;
    18891748                    break;
    … …  
    18941753            if (!pDisplay)
    18951754            {
    1896                 RTMsgError(CloudVM::tr("Guest not running"));
     1755                RTMsgError(ControlVM::tr("Guest not running."));
    18971756                rc = E_FAIL;
    18981757                break;
    … …  
    19081767            if (RT_FAILURE(vrc))
    19091768            {
    1910                 RTMsgError(CloudVM::tr("Failed to create file '%s' (%Rrc)"), a->argv[2], vrc);
     1769                RTMsgError(ControlVM::tr("Failed to create file '%s' (%Rrc)."), a->argv[2], vrc);
    19111770                rc = E_FAIL;
    19121771                break;
    … …  
    19151774            if (RT_FAILURE(vrc))
    19161775            {
    1917                 RTMsgError(CloudVM::tr("Failed to write screenshot to file '%s' (%Rrc)"), a->argv[2], vrc);
     1776                RTMsgError(ControlVM::tr("Failed to write screenshot to file '%s' (%Rrc)."), a->argv[2], vrc);
    19181777                rc = E_FAIL;
    19191778            }
    … …  
    19261785            if (a->argc < 3)
    19271786            {
    1928                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1787                errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    19291788                rc = E_FAIL;
    19301789                break;
    … …  
    19461805             *       kept to ensure backwards compatibility.
    19471806             */
    1948             if (!strcmp(a->argv[2], "on"))
    1949             {
    1950                 CHECK_ERROR_RET(recordingSettings, COMSETTER(Enabled)(TRUE), RTEXITCODE_FAILURE);
    1951             }
    1952             else if (!strcmp(a->argv[2], "off"))
    1953             {
    1954                 CHECK_ERROR_RET(recordingSettings, COMSETTER(Enabled)(FALSE), RTEXITCODE_FAILURE);
     1807            bool fEnabled;
     1808            if (RT_SUCCESS(parseBool(a->argv[2], &fEnabled)))
     1809            {
     1810                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RECORDING);
     1811                CHECK_ERROR_RET(recordingSettings, COMSETTER(Enabled)(fEnabled), RTEXITCODE_FAILURE);
    19551812            }
    19561813            else if (!strcmp(a->argv[2], "screens"))
    19571814            {
     1815                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RECORDING_SCREENS);
    19581816                ULONG cMonitors = 64;
    19591817                CHECK_ERROR_BREAK(pGraphicsAdapter, COMGETTER(MonitorCount)(&cMonitors));
    19601818                com::SafeArray<BOOL> saScreens(cMonitors);
    1961                 if (   a->argc == 4
    1962                     && !strcmp(a->argv[3], "all"))
    1963                 {
    1964                     /* enable all screens */
    1965                     for (unsigned i = 0; i < cMonitors; i++)
    1966                         saScreens[i] = true;
    1967                 }
    1968                 else if (   a->argc == 4
    1969                          && !strcmp(a->argv[3], "none"))
    1970                 {
    1971                     /* disable all screens */
    1972                     for (unsigned i = 0; i < cMonitors; i++)
    1973                         saScreens[i] = false;
    1974 
    1975                     /** @todo r=andy What if this is specified? */
    1976                 }
    1977                 else
    1978                 {
    1979                     /* enable selected screens */
    1980                     for (unsigned i = 0; i < cMonitors; i++)
    1981                         saScreens[i] = false;
    1982                     for (int i = 3; SUCCEEDED(rc) && i < a->argc; i++)
    1983                     {
    1984                         uint32_t iScreen;
    1985                         int vrc = RTStrToUInt32Ex(a->argv[i], NULL, 0, &iScreen);
    1986                         if (vrc != VINF_SUCCESS)
    1987                         {
    1988                             errorArgument(CloudVM::tr("Error parsing display number '%s'"), a->argv[i]);
    1989                             rc = E_FAIL;
    1990                             break;
    1991                         }
    1992                         if (iScreen >= cMonitors)
    1993                         {
    1994                             errorArgument(CloudVM::tr("Invalid screen ID specified '%u'"), iScreen);
    1995                             rc = E_FAIL;
    1996                             break;
    1997                         }
    1998                         saScreens[iScreen] = true;
    1999                     }
     1819                if (a->argc != 4)
     1820                {
     1821                    errorSyntax(ControlVM::tr("Incorrect number of parameters."));
     1822                    rc = E_FAIL;
     1823                    break;
     1824                }
     1825                if (RT_FAILURE(parseScreens(a->argv[3], &saScreens)))
     1826                {
     1827                    errorSyntax(ControlVM::tr("Error parsing list of screen IDs '%s'."), a->argv[3]);
     1828                    rc = E_FAIL;
     1829                    break;
    20001830                }
    20011831
    … …  
    20051835            else if (!strcmp(a->argv[2], "filename"))
    20061836            {
     1837                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RECORDING_FILENAME);
    20071838                if (a->argc != 4)
    20081839                {
    2009                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1840                    errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    20101841                    rc = E_FAIL;
    20111842                    break;
    … …  
    20181849                     || !strcmp(a->argv[2], "videoresolution"))
    20191850            {
     1851                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RECORDING_VIDEORES);
    20201852                if (a->argc != 5)
    20211853                {
    2022                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1854                    errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    20231855                    rc = E_FAIL;
    20241856                    break;
    … …  
    20291861                if (RT_FAILURE(vrc))
    20301862                {
    2031                     errorArgument(CloudVM::tr("Error parsing video width '%s'"), a->argv[3]);
     1863                    errorSyntax(ControlVM::tr("Error parsing video width '%s'."), a->argv[3]);
    20321864                    rc = E_FAIL;
    20331865                    break;
    … …  
    20381870                if (RT_FAILURE(vrc))
    20391871                {
    2040                     errorArgument(CloudVM::tr("Error parsing video height '%s'"), a->argv[4]);
     1872                    errorSyntax(ControlVM::tr("Error parsing video height '%s'."), a->argv[4]);
    20411873                    rc = E_FAIL;
    20421874                    break;
    … …  
    20511883            else if (!strcmp(a->argv[2], "videorate"))
    20521884            {
     1885                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RECORDING_VIDEORATE);
    20531886                if (a->argc != 4)
    20541887                {
    2055                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1888                    errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    20561889                    rc = E_FAIL;
    20571890                    break;
    … …  
    20621895                if (RT_FAILURE(vrc))
    20631896                {
    2064                     errorArgument(CloudVM::tr("Error parsing video rate '%s'"), a->argv[3]);
     1897                    errorSyntax(ControlVM::tr("Error parsing video rate '%s'."), a->argv[3]);
    20651898                    rc = E_FAIL;
    20661899                    break;
    … …  
    20721905            else if (!strcmp(a->argv[2], "videofps"))
    20731906            {
     1907                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RECORDING_VIDEOFPS);
    20741908                if (a->argc != 4)
    20751909                {
    2076                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1910                    errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    20771911                    rc = E_FAIL;
    20781912                    break;
    … …  
    20831917                if (RT_FAILURE(vrc))
    20841918                {
    2085                     errorArgument(CloudVM::tr("Error parsing video FPS '%s'"), a->argv[3]);
     1919                    errorSyntax(ControlVM::tr("Error parsing video FPS '%s'."), a->argv[3]);
    20861920                    rc = E_FAIL;
    20871921                    break;
    … …  
    20931927            else if (!strcmp(a->argv[2], "maxtime"))
    20941928            {
     1929                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RECORDING_MAXTIME);
    20951930                if (a->argc != 4)
    20961931                {
    2097                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1932                    errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    20981933                    rc = E_FAIL;
    20991934                    break;
    … …  
    21041939                if (RT_FAILURE(vrc))
    21051940                {
    2106                     errorArgument(CloudVM::tr("Error parsing maximum time '%s'"), a->argv[3]);
     1941                    errorSyntax(ControlVM::tr("Error parsing maximum time '%s'."), a->argv[3]);
    21071942                    rc = E_FAIL;
    21081943                    break;
    … …  
    21141949            else if (!strcmp(a->argv[2], "maxfilesize"))
    21151950            {
     1951                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RECORDING_MAXFILESIZE);
    21161952                if (a->argc != 4)
    21171953                {
    2118                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1954                    errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    21191955                    rc = E_FAIL;
    21201956                    break;
    … …  
    21251961                if (RT_FAILURE(vrc))
    21261962                {
    2127                     errorArgument(CloudVM::tr("Error parsing maximum file size '%s'"), a->argv[3]);
     1963                    errorSyntax(ControlVM::tr("Error parsing maximum file size '%s'."), a->argv[3]);
    21281964                    rc = E_FAIL;
    21291965                    break;
    … …  
    21351971            else if (!strcmp(a->argv[2], "opts"))
    21361972            {
     1973#if 0 /* Add when the corresponding documentation is enabled. */
     1974                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_RECORDING_OPTS);
     1975#endif
    21371976                if (a->argc != 4)
    21381977                {
    2139                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     1978                    errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    21401979                    rc = E_FAIL;
    21411980                    break;
    … …  
    21511990            if (a->argc < 3)
    21521991            {
    2153                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     1992                errorArgument(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    21541993                rc = E_FAIL;
    21551994                break;
    … …  
    21601999            if (!pEmulatedUSB)
    21612000            {
    2162                 RTMsgError(CloudVM::tr("Guest not running"));
     2001                RTMsgError(ControlVM::tr("Guest not running."));
    21632002                rc = E_FAIL;
    21642003                break;
    … …  
    21672006            if (!strcmp(a->argv[2], "attach"))
    21682007            {
     2008                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_WEBCAM_ATTACH);
    21692009                Bstr path("");
    21702010                if (a->argc >= 4)
    … …  
    21772017            else if (!strcmp(a->argv[2], "detach"))
    21782018            {
     2019                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_WEBCAM_DETACH);
    21792020                Bstr path("");
    21802021                if (a->argc >= 4)
    … …  
    21842025            else if (!strcmp(a->argv[2], "list"))
    21852026            {
     2027                setCurrentSubcommand(HELP_SCOPE_CONTROLVM_WEBCAM_LIST);
    21862028                com::SafeArray <BSTR> webcams;
    21872029                CHECK_ERROR_BREAK(pEmulatedUSB, COMGETTER(Webcams)(ComSafeArrayAsOutParam(webcams)));
    … …  
    21932035            else
    21942036            {
    2195                 errorArgument(CloudVM::tr("Invalid argument to '%s'"), a->argv[1]);
     2037                errorArgument(ControlVM::tr("Invalid argument to '%s'."), a->argv[1]);
    21962038                rc = E_FAIL;
    21972039                break;
    … …  
    22002042        else if (!strcmp(a->argv[1], "addencpassword"))
    22012043        {
     2044            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_ADDENCPASSWORD);
    22022045            if (   a->argc != 4
    22032046                && a->argc != 6)
    22042047            {
    2205                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     2048                errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    22062049                break;
    22072050            }
    … …  
    22142057                        && strcmp(a->argv[5], "no")))
    22152058                {
    2216                     errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Invalid parameters"));
     2059                    errorSyntax(ControlVM::tr("Invalid parameters."));
    22172060                    break;
    22182061                }
    … …  
    22272070            {
    22282071                /* Get password from console. */
    2229                 RTEXITCODE rcExit = readPasswordFromConsole(&strPassword, CloudVM::tr("Enter password:"));
     2072                RTEXITCODE rcExit = readPasswordFromConsole(&strPassword, ControlVM::tr("Enter password:"));
    22302073                if (rcExit == RTEXITCODE_FAILURE)
    22312074                    break;
    … …  
    22362079                if (rcExit == RTEXITCODE_FAILURE)
    22372080                {
    2238                     RTMsgError(CloudVM::tr("Failed to read new password from file"));
     2081                    RTMsgError(ControlVM::tr("Failed to read new password from file."));
    22392082                    break;
    22402083                }
    … …  
    22452088        else if (!strcmp(a->argv[1], "removeencpassword"))
    22462089        {
     2090            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_REMOVEENCPASSWORD);
    22472091            if (a->argc != 3)
    22482092            {
    2249                 errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Incorrect number of parameters"));
     2093                errorSyntax(ControlVM::tr("Incorrect number of parameters."));
    22502094                break;
    22512095            }
    … …  
    22552099        else if (!strcmp(a->argv[1], "removeallencpasswords"))
    22562100        {
     2101            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_REMOVEALLENCPASSWORDS);
    22572102            CHECK_ERROR_BREAK(console, ClearAllDiskEncryptionPasswords());
    22582103        }
    22592104        else if (!strncmp(a->argv[1], "changeuartmode", 14))
    22602105        {
     2106            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_CHANGEUARTMODE);
    22612107            unsigned n = parseNum(&a->argv[1][14], 4, "UART");
    22622108            if (!n)
    … …  
    22672113            if (a->argc < 3)
    22682114            {
    2269                 errorArgument(CloudVM::tr("Missing argument to '%s'"), a->argv[1]);
     2115                errorSyntax(ControlVM::tr("Missing argument to '%s'."), a->argv[1]);
    22702116                rc = E_FAIL;
    22712117                break;
    … …  
    22812127                if (a->argc != 3)
    22822128                {
    2283                     errorArgument(CloudVM::tr("Incorrect arguments to '%s'"), a->argv[1]);
     2129                    errorSyntax(ControlVM::tr("Incorrect arguments to '%s'."), a->argv[1]);
    22842130                    rc = E_FAIL;
    22852131                    break;
    … …  
    22962142                if (a->argc != 4)
    22972143                {
    2298                     errorArgument(CloudVM::tr("Incorrect arguments to '%s'"), a->argv[1]);
     2144                    errorSyntax(ControlVM::tr("Incorrect arguments to '%s'."), a->argv[1]);
    22992145                    rc = E_FAIL;
    23002146                    break;
    … …  
    23372183                if (a->argc != 3)
    23382184                {
    2339                     errorArgument(CloudVM::tr("Incorrect arguments to '%s'"), a->argv[1]);
     2185                    errorSyntax(ControlVM::tr("Incorrect arguments to '%s'."), a->argv[1]);
    23402186                    rc = E_FAIL;
    23412187                    break;
    … …  
    23472193        else if (!strncmp(a->argv[1], "vm-process-priority", 14))
    23482194        {
     2195            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_VM_PROCESS_PRIORITY);
    23492196            if (a->argc != 3)
    23502197            {
    2351                 errorArgument(CloudVM::tr("Incorrect arguments to '%s'"), a->argv[1]);
     2198                errorSyntax(ControlVM::tr("Incorrect arguments to '%s'."), a->argv[1]);
    23522199                rc = E_FAIL;
    23532200                break;
    … …  
    23562203            if (enmPriority == VMProcPriority_Invalid)
    23572204            {
    2358                 errorArgument(CloudVM::tr("Invalid vm-process-priority '%s'"), a->argv[2]);
     2205                errorSyntax(ControlVM::tr("Invalid vm-process-priority '%s'."), a->argv[2]);
    23592206                rc = E_FAIL;
    23602207            }
    … …  
    23672214        else if (!strncmp(a->argv[1], "autostart-enabled", 17))
    23682215        {
     2216            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_AUTOSTART_ENABLED);
    23692217            if (a->argc != 3)
    23702218            {
    2371                 errorArgument(CloudVM::tr("Incorrect arguments to '%s'"), a->argv[1]);
    2372                 rc = E_FAIL;
    2373                 break;
    2374             }
    2375             if (!strcmp(a->argv[2], "on"))
    2376             {
    2377                 CHECK_ERROR(sessionMachine, COMSETTER(AutostartEnabled)(TRUE));
    2378             }
    2379             else if (!strcmp(a->argv[2], "off"))
    2380             {
    2381                 CHECK_ERROR(sessionMachine, COMSETTER(AutostartEnabled)(FALSE));
    2382             }
    2383             else
    2384             {
    2385                 errorArgument(CloudVM::tr("Invalid value '%s'"), Utf8Str(a->argv[2]).c_str());
    2386                 rc = E_FAIL;
    2387                 break;
    2388             }
    2389             if (SUCCEEDED(rc))
    2390                 fNeedsSaving = true;
     2219                errorSyntax(ControlVM::tr("Incorrect arguments to '%s'."), a->argv[1]);
     2220                rc = E_FAIL;
     2221                break;
     2222            }
     2223            bool fEnabled;
     2224            if (RT_FAILURE(parseBool(a->argv[2], &fEnabled)))
     2225            {
     2226                errorSyntax(ControlVM::tr("Invalid value '%s'."), a->argv[2]);
     2227                rc = E_FAIL;
     2228                break;
     2229            }
     2230            CHECK_ERROR(sessionMachine, COMSETTER(AutostartEnabled)(TRUE));
     2231            fNeedsSaving = true;
    23912232            break;
    23922233        }
    23932234        else if (!strncmp(a->argv[1], "autostart-delay", 15))
    23942235        {
     2236            setCurrentSubcommand(HELP_SCOPE_CONTROLVM_AUTOSTART_DELAY);
    23952237            if (a->argc != 3)
    23962238            {
    2397                 errorArgument(CloudVM::tr("Incorrect arguments to '%s'"), a->argv[1]);
     2239                errorSyntax(ControlVM::tr("Incorrect arguments to '%s'."), a->argv[1]);
    23982240                rc = E_FAIL;
    23992241                break;
    … …  
    24042246            if (RT_FAILURE(vrc) || *pszNext != '\0')
    24052247            {
    2406                 errorArgument(CloudVM::tr("Invalid autostart delay number '%s'"), a->argv[2]);
     2248                errorSyntax(ControlVM::tr("Invalid autostart delay number '%s'."), a->argv[2]);
    24072249                rc = E_FAIL;
    24082250                break;
    … …  
    24152257        else
    24162258        {
    2417             errorSyntax(USAGE_CONTROLVM, CloudVM::tr("Invalid parameter '%s'"), a->argv[1]);
     2259            errorSyntax(ControlVM::tr("Invalid parameter '%s'."), a->argv[1]);
    24182260            rc = E_FAIL;
    24192261        }

  • trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp

    r93347 r93708  
    591591
    592592#define SEP pcszSep1, pcszSep2
    593 
    594     if (enmCommand == USAGE_STARTVM || enmCommand == USAGE_S_ALL)
    595     {
    596         RTStrmPrintf(pStrm,
    597                            "%s startvm %s         <uuid|vmname>...\n"
    598                      "                            [--type gui", SEP);
    599         if (fVBoxSDL)
    600             RTStrmPrintf(pStrm, "|sdl");
    601         RTStrmPrintf(pStrm, "|headless|separate]\n");
    602         RTStrmPrintf(pStrm,
    603                      "                            [-E|--putenv <NAME>[=<VALUE>]]\n"
    604                      "\n");
    605     }
    606 
    607     if (enmCommand == USAGE_CONTROLVM || enmCommand == USAGE_S_ALL)
    608     {
    609         RTStrmPrintf(pStrm,
    610                            "%s controlvm %s       <uuid|vmname>\n"
    611                      "                            pause|resume|reset|poweroff|savestate|\n", SEP);
    612 #ifdef VBOX_WITH_GUEST_CONTROL
    613         RTStrmPrintf(pStrm,
    614                        "                            reboot|shutdown [--force]|\n");
    615 #endif
    616         RTStrmPrintf(pStrm,
    617                      "                            acpipowerbutton|acpisleepbutton|\n"
    618                      "                            keyboardputscancode <hex> [<hex> ...]|\n"
    619                      "                            keyboardputstring <string1> [<string2> ...]|\n"
    620                      "                            keyboardputfile <filename>|\n"
    621                      "                            setlinkstate<1-N> on|off |\n");
    622 #if defined(VBOX_WITH_NETFLT)
    623         RTStrmPrintf(pStrm,
    624                      "                            nic<1-N> null|nat|bridged|intnet|hostonly|generic|\n"
    625                      "                                     natnetwork [<devicename>] |\n");
    626 #else /* !VBOX_WITH_NETFLT */
    627         RTStrmPrintf(pStrm,
    628                      "                            nic<1-N> null|nat|bridged|intnet|generic|natnetwork\n"
    629                      "                                     [<devicename>] |\n");
    630 #endif /* !VBOX_WITH_NETFLT */
    631         RTStrmPrintf(pStrm,
    632                      "                            nictrace<1-N> on|off |\n"
    633                      "                            nictracefile<1-N> <filename> |\n"
    634                      "                            nicproperty<1-N> name=[value] |\n"
    635                      "                            nicpromisc<1-N> deny|allow-vms|allow-all |\n"
    636                      "                            natpf<1-N> [<rulename>],tcp|udp,[<hostip>],\n"
    637                      "                                        <hostport>,[<guestip>],<guestport> |\n"
    638                      "                            natpf<1-N> delete <rulename> |\n"
    639                      "                            guestmemoryballoon <balloonsize in MB> |\n"
    640                      "                            usbattach <uuid>|<address>\n"
    641                      "                                      [--capturefile <filename>] |\n"
    642                      "                            usbdetach <uuid>|<address> |\n"
    643                      "                            audioin on|off |\n"
    644                      "                            audioout on|off |\n");
    645 #ifdef VBOX_WITH_SHARED_CLIPBOARD
    646         RTStrmPrintf(pStrm,
    647                      "                            clipboard mode disabled|hosttoguest|guesttohost|\n"
    648                      "                                           bidirectional |\n");
    649 # ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
    650         RTStrmPrintf(pStrm,
    651                        "                            clipboard filetransfers enabled|disabled |\n");
    652 # endif
    653 #endif
    654         RTStrmPrintf(pStrm,
    655                      "                            draganddrop disabled|hosttoguest|guesttohost|\n"
    656                      "                                        bidirectional |\n"
    657                      "                            vrde on|off |\n"
    658                      "                            vrdeport <port> |\n"
    659                      "                            vrdeproperty <name=[value]> |\n"
    660                      "                            vrdevideochannelquality <percent> |\n"
    661                      "                            setvideomodehint <xres> <yres> <bpp>\n"
    662                      "                                            [[<display>] [<enabled:yes|no> |\n"
    663                      "                                              [<xorigin> <yorigin>]]] |\n"
    664                      "                            setscreenlayout <display> on|primary <xorigin> <yorigin> <xres> <yres> <bpp> | off\n"
    665                      "                            screenshotpng <file> [display] |\n");
    666 #ifdef VBOX_WITH_RECORDING
    667         RTStrmPrintf(pStrm,
    668                      "                            recording on|off |\n"
    669                      "                            recording screens all|none|<screen>,[<screen>...] |\n"
    670                      "                            recording filename <file> |\n"
    671                      "                            recording videores <width>x<height> |\n"
    672                      "                            recording videorate <rate> |\n"
    673                      "                            recording videofps <fps> |\n"
    674                      "                            recording maxtime <s> |\n"
    675                      "                            recording maxfilesize <MB> |\n");
    676 #endif /* VBOX_WITH_RECORDING */
    677         RTStrmPrintf(pStrm,
    678                      "                            setcredentials <username>\n"
    679                      "                                           --passwordfile <file> | <password>\n"
    680                      "                                           <domain>\n"
    681                      "                                           [--allowlocallogon <yes|no>] |\n"
    682                      "                            teleport --host <name> --port <port>\n"
    683                      "                                     [--maxdowntime <msec>]\n"
    684                      "                                     [--passwordfile <file> |\n"
    685                      "                                      --password <password>] |\n"
    686                      "                            plugcpu <id> |\n"
    687                      "                            unplugcpu <id> |\n"
    688                      "                            cpuexecutioncap <1-100>\n"
    689                      "                            webcam <attach [path [settings]]> | <detach [path]> | <list>\n"
    690                      "                            addencpassword <id>\n"
    691                      "                                           <password file>|-\n"
    692                      "                                           [--removeonsuspend <yes|no>]\n"
    693                      "                            removeencpassword <id>\n"
    694                      "                            removeallencpasswords\n"
    695                      "                            changeuartmode<1-N> disconnected|\n"
    696                      "                                                server <pipe>|\n"
    697                      "                                                client <pipe>|\n"
    698                      "                                                tcpserver <port>|\n"
    699                      "                                                tcpclient <hostname:port>|\n"
    700                      "                                                file <file>|\n"
    701                      "                                                <devicename>\n"
    702                      "                            vm-process-priority default|flat|low|normal|high\n"
    703                      "                            autostart-enabled on|off\n"
    704                      "                            autostart-delay <seconds>\n"
    705                      "\n");
    706     }
    707593
    708594    if (enmCommand == USAGE_DISCARDSTATE || enmCommand == USAGE_S_ALL)

  • trunk/src/VBox/Frontends/VBoxManage/VBoxManageMisc.cpp

    r93706 r93708  
    672672                    aBstrEnv.push_back(Bstr(ValueUnion.psz).raw());
    673673                else
    674                     return errorSyntax(USAGE_STARTVM,
    675                                        Misc::tr("Parameter to option --putenv must not contain any newline character"));
     674                    return errorSyntax(Misc::tr("Parameter to option --putenv must not contain any newline character"));
    676675                break;
    677676
    … …  
    684683                {
    685684                    if (RT_C_IS_PRINT(c))
    686                         return errorSyntax(USAGE_STARTVM, Misc::tr("Invalid option -%c"), c);
     685                        return errorSyntax(Misc::tr("Invalid option -%c"), c);
    687686                    else
    688                         return errorSyntax(USAGE_STARTVM, Misc::tr("Invalid option case %i"), c);
     687                        return errorSyntax(Misc::tr("Invalid option case %i"), c);
    689688                }
    690689                else if (c == VERR_GETOPT_UNKNOWN_OPTION)
    691                     return errorSyntax(USAGE_STARTVM, Misc::tr("unknown option: %s\n"), ValueUnion.psz);
     690                    return errorSyntax(Misc::tr("unknown option: %s\n"), ValueUnion.psz);
    692691                else if (ValueUnion.pDef)
    693                     return errorSyntax(USAGE_STARTVM, "%s: %Rrs", ValueUnion.pDef->pszLong, c);
     692                    return errorSyntax("%s: %Rrs", ValueUnion.pDef->pszLong, c);
    694693                else
    695                     return errorSyntax(USAGE_STARTVM, Misc::tr("error: %Rrs"), c);
     694                    return errorSyntax(Misc::tr("error: %Rrs"), c);
    696695        }
    697696    }
    … …  
    699698    /* check for required options */
    700699    if (VMs.empty())
    701         return errorSyntax(USAGE_STARTVM, Misc::tr("at least one VM name or uuid required"));
     700        return errorSyntax(Misc::tr("at least one VM name or uuid required"));
    702701
    703702    for (std::list<const char *>::const_iterator it = VMs.begin();
Note: See TracChangeset for help on using the changeset viewer.

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