VirtualBox

Changeset 79611 in vbox for trunk/doc


Ignore:
Timestamp:
Jul 8, 2019 11:33:59 PM (6 years ago)
Author:
vboxsync
Message:

VBoxManage,manual: Added the dhcpserver subcommand findlease for testing IDHCPServer::FindLeaseByMAC(). Wrote a man page for the dhcpserver command and converted the help to the new style. Also took a shot at simplifying the option handling of the existing dhcpserver subcommands while retaining a somewhat more flexible compatibility with the old syntax (not advertised) - not really tested. bugref:9288 bugref:9151

Location:
trunk/doc/manual
Files:
2 edited
1 copied

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/Config.kmk

    r78734 r79611  
    3939        man_VBoxManage-clonevm.xml \
    4040        man_VBoxManage-mediumio.xml \
     41        man_VBoxManage-dhcpserver.xml \
    4142        man_VBoxManage-debugvm.xml \
    4243        man_VBoxManage-extpack.xml \

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

    r79528 r79611  
    11<?xml version="1.0" encoding="UTF-8"?>
    22<!--
    3     manpage, user manual, usage: VBoxManage extpack
     3    manpage, user manual, usage: VBoxManage dhcpserver
    44
    55    Copyright (C) 2006-2015 Oracle Corporation
    … …  
    1414 -->
    1515<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
    16 <refentry id="vboxmanage-extpack" lang="en">
     16<refentry id="vboxmanage-dhcpserver" lang="en">
    1717
    1818  <refentryinfo>
    1919    <pubdate>$Date$</pubdate>
    20     <title>VBoxManage extpack</title>
     20    <title>VBoxManage dhcpserver</title>
    2121  </refentryinfo>
    2222
    2323  <refmeta>
    24     <refentrytitle>VBoxManage-extpack</refentrytitle>
     24    <refentrytitle>VBoxManage-dhcpserver</refentrytitle>
    2525    <manvolnum>1</manvolnum>
    2626  </refmeta>
    2727
    2828  <refnamediv>
    29     <refname>VBoxManage-extpack</refname>
    30     <refpurpose>extension package management</refpurpose>
     29    <refname>VBoxManage-dhcpserver</refname>
     30    <refpurpose>DHCP server management</refpurpose>
    3131    <refclass>Oracle VM VirtualBox</refclass>
    3232  </refnamediv>
    3333
    3434  <refsynopsisdiv>
    35     <cmdsynopsis id="synopsis-vboxmanage-extpack-install"> <!-- The 'id' is mandatory and must start with 'synopsis-'. -->
    36       <command>VBoxManage extpack install</command>
    37       <arg>--replace</arg>
    38       <arg choice="req"><replaceable>tarball</replaceable></arg>
    39     </cmdsynopsis>
    40     <cmdsynopsis id="synopsis-vboxmanage-extpack-uninstall">
    41       <command>VBoxManage extpack uninstall</command>
    42       <arg>--force</arg>
    43       <arg choice="req"><replaceable>name</replaceable></arg>
    44     </cmdsynopsis>
    45     <cmdsynopsis id="synopsis-vboxmanage-extpack-cleanup">
    46       <command>VBoxManage extpack cleanup</command>
     35    <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-add">
     36      <command>VBoxManage dhcpserver add</command>
     37      <group choice="req">
     38        <arg choice="plain">--network=<replaceable>netname</replaceable></arg>
     39        <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg>
     40      </group>
     41      <arg choice="req">--ip=<replaceable>dhcpd-address</replaceable></arg>
     42      <arg choice="req">--netmask=<replaceable>mask</replaceable></arg>
     43      <arg choice="req">--lower-ip=<replaceable>address</replaceable></arg>
     44      <arg choice="req">--upper-ip=<replaceable>address</replaceable></arg>
     45      <group choice="req">
     46        <arg choice="plain">--enable</arg>
     47        <arg choice="plain">--disable</arg>
     48      </group>
     49      <sbr/>
     50      <arg choice="opt" rep="repeat">
     51        <arg choice="opt">--global</arg>
     52        <arg choice="opt" rep="repeat">--add-opt=<replaceable>dhcp-opt-no hex-string</replaceable></arg>
     53      </arg>
     54      <sbr/>
     55      <arg choice="opt" rep="repeat">
     56        <arg choice="req">--vm=<replaceable>name|uuid</replaceable></arg>
     57        <arg choice="opt">--nic=<replaceable>1-N</replaceable></arg>
     58        <arg choice="opt" rep="repeat">--add-opt=<replaceable>dhcp-opt-no hex-string</replaceable></arg>
     59      </arg>
     60    </cmdsynopsis>
     61    <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-modify">
     62      <command>VBoxManage dhcpserver modify</command>
     63      <group choice="req">
     64        <arg choice="plain">--network=<replaceable>netname</replaceable></arg>
     65        <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg>
     66      </group>
     67      <arg choice="opt">--ip=<replaceable>dhcpd-address</replaceable></arg>
     68      <arg choice="opt">--netmask=<replaceable>mask</replaceable></arg>
     69      <arg choice="opt">--lower-ip=<replaceable>address</replaceable></arg>
     70      <arg choice="opt">--upper-ip=<replaceable>address</replaceable></arg>
     71      <group choice="opt">
     72        <arg choice="plain">--enable</arg>
     73        <arg choice="plain">--disable</arg>
     74      </group>
     75      <sbr/>
     76      <arg choice="opt" rep="repeat">
     77        <arg choice="opt">--global</arg>
     78        <arg choice="plain">--del-opt=<replaceable>dhcp-opt-no</replaceable></arg>
     79        <arg choice="plain">--add-opt=<replaceable>dhcp-opt-no hex-string</replaceable></arg>
     80      </arg>
     81      <sbr/>
     82      <arg choice="opt" rep="repeat">
     83        <arg choice="req">--vm=<replaceable>name|uuid</replaceable></arg>
     84        <arg choice="opt">--nic=<replaceable>1-N</replaceable></arg>
     85        <arg choice="opt" rep="repeat">--del-opt=<replaceable>dhcp-opt-no</replaceable></arg>
     86        <arg choice="opt" rep="repeat">--add-opt=<replaceable>dhcp-opt-no hex-string</replaceable></arg>
     87      </arg>
     88    </cmdsynopsis>
     89    <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-remove">
     90      <command>VBoxManage dhcpserver remove</command>
     91      <group choice="req">
     92        <arg choice="plain">--network=<replaceable>netname</replaceable></arg>
     93        <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg>
     94      </group>
     95    </cmdsynopsis>
     96    <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-restart">
     97      <command>VBoxManage dhcpserver restart</command>
     98      <group choice="req">
     99        <arg choice="plain">--network=<replaceable>netname</replaceable></arg>
     100        <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg>
     101      </group>
     102    </cmdsynopsis>
     103    <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-findlease">
     104      <command>VBoxManage dhcpserver findlease</command>
     105      <group choice="req">
     106        <arg choice="plain">--network=<replaceable>netname</replaceable></arg>
     107        <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg>
     108      </group>
     109      <arg choice="req">--mac-address=<replaceable>mac</replaceable></arg>
    47110    </cmdsynopsis>
    48111  </refsynopsisdiv>
    … …  
    51114    <title>Description</title>
    52115
    53     <refsect2 id="vboxmanage-extpack-install">
    54       <title>extpack install</title>
    55       <remark role="help-copy-synopsis"/>
    56       <para>
    57         Installs a new extension pack on the system.  This command will fail if an older
    58         version of the same extension pack is already installed.  The
    59         <option>--replace</option> option can be used to uninstall any
    60         old package before the new one is installed.
    61       </para>
    62       <variablelist>
    63         <varlistentry>
    64           <term><option>--replace</option></term><listitem><para>Uninstall existing extension pack version.</para></listitem>
    65         </varlistentry>
    66         <varlistentry>
    67           <term><replaceable>tarball</replaceable></term>
    68           <listitem>
    69             <para>The file containing the extension pack to be installed.</para>
    70           </listitem>
    71         </varlistentry>
    72       </variablelist>
    73     </refsect2>
    74 
    75     <refsect2 id="vboxmanage-extpack-uninstall">
    76       <title>extpack uninstall</title>
    77       <remark role="help-copy-synopsis"/>
    78       <para>
    79         Uninstalls an extension pack from the system.  The subcommand will also succeed
    80         in the case where the specified extension pack is not present on the system.
    81         You can use <computeroutput>VBoxManage list extpacks</computeroutput> to show
    82         the names of the extension packs which are currently installed.
    83       </para>
    84       <variablelist>
    85         <varlistentry>
    86           <term><option>--force</option></term>
    87           <listitem>
    88             <para>Overrides most refusals to uninstall an extension pack</para>
    89           </listitem>
    90         </varlistentry>
    91         <varlistentry>
    92           <term><replaceable>name</replaceable></term>
    93           <listitem>
    94             <para>The name of the extension pack to be uninstalled.</para>
    95           </listitem>
    96         </varlistentry>
    97       </variablelist>
    98     </refsect2>
    99 
    100     <refsect2 id="vboxmanage-extpack-cleanup">
    101       <title>extpack cleanup</title>
    102       <remark role="help-copy-synopsis"/>
    103       <para>
    104         Used to remove temporary files and directories that may have been left behind
    105         if a previous install or uninstall command failed.
    106       </para>
     116    <para>
     117      The <command>dhcpserver</command> commands enable you to control the DHCP
     118       server that is built into VirtualBox.  You may find this useful when
     119       using internal or host-only networking.  Theoretically, you can also
     120       enable it for a bridged network, but that may cause conflicts with other
     121       DHCP servers in your physical network.
     122    </para>
     123
     124    <refsect2 id="vboxmanage-dhcpserver-common-options">
     125      <title>Common options</title>
     126      <remark role="help-scope" condition="GLOBAL"/>
     127      <para>The subcommands of <command>dhcpserver</command> all operate on an
     128        internal network that can be identified via its name or in the host-only
     129        case via the host-only interface name:</para>
     130      <variablelist>
     131        <varlistentry>
     132          <term>--network=<replaceable>netname</replaceable></term>
     133          <listitem><para>The internal network name.  This is the same as you
     134            would use as value to the <command>VBoxManage modifyvm --intnet</command>
     135            option when configuring a VM for internal networking.  Or you see as
     136            VBoxNetworkName in the output from
     137            <command>VBoxManage list intnets</command>,
     138            <command>VBoxManage list natnets</command>, or
     139            <command>VBoxManage list hostonlyifs</command>.
     140          </para></listitem>
     141        </varlistentry>
     142        <varlistentry>
     143          <term>--interface=<replaceable>ifname</replaceable></term>
     144          <listitem><para>The host only interface name.  This would be same value
     145            as you would use for the <command>VBoxManage modifyvm --hostonlyadapter</command>
     146            option when configuring a VM to use a host-only network.  The value
     147            can also be found in the Name row in <command>VBoxManage list hostonlyifs</command>.
     148          </para></listitem>
     149        </varlistentry>
     150      </variablelist>
     151    </refsect2>
     152
     153    <refsect2 id="vboxmanage-dhcpserver-add">
     154      <title>dhcpserver add</title>
     155      <remark role="help-copy-synopsis"/>
     156      <para>
     157        Adds a new DHCP server to a network or host-only interface.
     158      </para>
     159      <variablelist>
     160        <varlistentry>
     161          <term><option>--ip=<replaceable>dhcpd-address</replaceable></option></term>
     162          <listitem><para>The IP address the DHCP server should use.</para></listitem>
     163        </varlistentry>
     164        <varlistentry>
     165          <term><option>--netmask=<replaceable>mask</replaceable></option></term>
     166          <listitem><para>The network mask.  Typically 255.255.255.0.</para></listitem>
     167        </varlistentry>
     168        <varlistentry>
     169          <term><option>--lower-ip=<replaceable>address</replaceable></option>, <option>--upper-ip=<replaceable>address</replaceable></option></term>
     170          <listitem><para>The IP address range for the DHCP server to manage.  This
     171            should not include the address of the DHCP server itself, but it must be
     172            in the same network as it is.  The boundraries are inclusive, so both the
     173            lower and upper addresses will be handed out to clients.</para></listitem>
     174        </varlistentry>
     175        <varlistentry>
     176          <term><option>--enable</option>, --disable</term>
     177          <listitem><para>Whether to enable the DHCP server or disable it.  If not specified,
     178            the server will be created in disabled state and no IP addresses handed out.</para></listitem>
     179        </varlistentry>
     180        <varlistentry>
     181          <term><option>--global</option></term>
     182          <listitem><para>Set the option scope to global.  Any subsequent <option>--add-opt</option>
     183            options will be apply to all the DHCP clients.</para></listitem>
     184        </varlistentry>
     185        <varlistentry>
     186          <term><option>--vm=<replaceable>vmname|uuid</replaceable></option></term>
     187          <listitem><para>Set the option scope to the first NIC of the specified VM.  Any
     188            subsequent <option>-add-opt</option> options will apply just to that interface,
     189            nothing else.</para></listitem>
     190        </varlistentry>
     191        <varlistentry>
     192          <term><option>--nic=<replaceable>1-N</replaceable></option></term>
     193          <listitem><para>Set the option scope to a NIC other than first of the VM specified
     194            the in <option>--vm</option>.</para></listitem>
     195        </varlistentry>
     196        <varlistentry>
     197          <term><option>--add-opt=<replaceable>dhcp-opt-no hex-string</replaceable></option></term>
     198          <listitem><para>Adds the specified DHCP option number (0-255) and value.  The scope of
     199            the option is decided by the <option>--vm</option> and <option>global</option> options.
     200          </para></listitem>
     201        </varlistentry>
     202      </variablelist>
     203    </refsect2>
     204
     205    <refsect2 id="vboxmanage-dhcpserver-modify">
     206      <title>dhcpserver modify</title>
     207      <remark role="help-copy-synopsis"/>
     208      <para>
     209        This modifies an existing DHCP server configuration.  It takes the same
     210        options as the <command>add</command> command with the addition of:
     211      </para>
     212      <variablelist>
     213        <varlistentry>
     214          <term><option>--del-opt=<replaceable>dhcp-opt-no</replaceable></option></term>
     215          <listitem><para>Counterpart to <option>--add-opt</option> that will cause the specified
     216            DHCP option number (0-255) to be deleted from the server settings.  Like with
     217            <option>--add-opt</option> the scope of the deletion is governed by the
     218            <option>--vm</option> and <option>global</option> options.
     219          </para></listitem>
     220        </varlistentry>
     221      </variablelist>
     222    </refsect2>
     223
     224    <refsect2 id="vboxmanage-dhcpserver-remove">
     225      <title>dhcpserver remove</title>
     226      <remark role="help-copy-synopsis"/>
     227      <para>
     228        Removes the specified DHCP server.
     229      </para>
     230    </refsect2>
     231
     232    <refsect2 id="vboxmanage-dhcpserver-restart">
     233      <title>dhcpserver restart</title>
     234      <remark role="help-copy-synopsis"/>
     235      <para>
     236        Restarts the specified DHCP server.  The DHCP server must be running.
     237      </para>
     238    </refsect2>
     239
     240    <refsect2 id="vboxmanage-dhcpserver-findlease">
     241      <title>dhcpserver findlease</title>
     242      <remark role="help-copy-synopsis"/>
     243      <para>
     244        Performs a lease database lookup.  This is mainly for getting the IP
     245        address of a running VM.
     246      </para>
     247      <variablelist>
     248        <varlistentry>
     249          <term><option>--mac-address=<replaceable>mac</replaceable></option></term>
     250          <listitem><para>The MAC address to lookup in the lease database.</para></listitem>
     251        </varlistentry>
     252      </variablelist>
    107253    </refsect2>
    108254
    109255  </refsect1>
    110256
    111   <refsect1>
    112     <title>Examples</title>
    113     <remark role="help-scope" condition="EXTPACK_UNINSTALL,EXTPACK"/>
    114     <para>
    115           How to list extension packs:
    116 <screen>$ VBoxManage list extpacks
    117 Extension Packs: 1
    118 Pack no. 0:   Oracle VM VirtualBox Extension Pack
    119 Version:      4.1.12
    120 Revision:     77218
    121 Edition:
    122 Description:  USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support.
    123 VRDE Module:  VBoxVRDP
    124 Usable:       true
    125 Why unusable:</screen></para>
    126 
    127     <para>How to remove an extension pack:
    128 <screen>$ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack"
    129 0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
    130 Successfully uninstalled "Oracle VM VirtualBox Extension Pack".</screen></para>
    131   </refsect1>
    132 
    133257</refentry>
    134258

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

    r78734 r79611  
    87908790  </sect1>
    87918791
    8792   <sect1 id="vboxmanage-dhcpserver">
    8793 
    8794     <title>VBoxManage dhcpserver</title>
    8795 
    8796     <para>
    8797       The <command>dhcpserver</command> commands enable you to control
    8798       the DHCP server that is built into &product-name;. You may find
    8799       this useful when using internal or host-only networking.
    8800       Theoretically, you can also enable it for a bridged network, but
    8801       that may cause conflicts with other DHCP servers in your physical
    8802       network.
    8803     </para>
    8804 
    8805     <para>
    8806       Use the following command line options:
    8807     </para>
    8808 
    8809     <itemizedlist>
    8810 
    8811       <listitem>
    8812         <para>
    8813           If you use internal networking for a virtual network adapter
    8814           of a virtual machine, use <computeroutput>VBoxManage
    8815           dhcpserver add --netname
    8816           &lt;network_name&gt;</computeroutput>, where
    8817           <computeroutput>&lt;network_name&gt;</computeroutput> is the
    8818           same network name you used with <computeroutput>VBoxManage
    8819           modifyvm &lt;vmname&gt; --intnet&lt;X&gt;
    8820           &lt;network_name&gt;</computeroutput>.
    8821         </para>
    8822       </listitem>
    8823 
    8824       <listitem>
    8825         <para>
    8826           If you use host-only networking for a virtual network adapter
    8827           of a virtual machine, use <computeroutput>VBoxManage
    8828           dhcpserver add --ifname
    8829           &lt;hostonly_if_name&gt;</computeroutput> instead, where
    8830           <computeroutput>&lt;hostonly_if_name&gt;</computeroutput> is
    8831           the same host-only interface name you used with
    8832           <computeroutput>VBoxManage modifyvm &lt;vmname&gt;
    8833           --hostonlyadapter&lt;X&gt;
    8834           &lt;hostonly_if_name&gt;</computeroutput>.
    8835         </para>
    8836 
    8837         <para>
    8838           Alternatively, you can also use the <option>--netname</option>
    8839           option as with internal networks if you know the host-only
    8840           network's name. You can see the names with <command>VBoxManage
    8841           list hostonlyifs</command>. See
    8842           <xref linkend="vboxmanage-list" />.
    8843         </para>
    8844       </listitem>
    8845 
    8846     </itemizedlist>
    8847 
    8848     <para>
    8849       The following additional parameters are required when first adding
    8850       a DHCP server:
    8851     </para>
    8852 
    8853     <itemizedlist>
    8854 
    8855       <listitem>
    8856         <para>
    8857           With <computeroutput>--ip</computeroutput>, specify the IP
    8858           address of the DHCP server.
    8859         </para>
    8860       </listitem>
    8861 
    8862       <listitem>
    8863         <para>
    8864           With <computeroutput>--netmask</computeroutput>, specify the
    8865           netmask of the network.
    8866         </para>
    8867       </listitem>
    8868 
    8869       <listitem>
    8870         <para>
    8871           With <computeroutput>--lowerip</computeroutput> and
    8872           <computeroutput>--upperip</computeroutput>, you can specify
    8873           the lowest and highest IP address that the DHCP server will
    8874           assign to clients.
    8875         </para>
    8876       </listitem>
    8877 
    8878     </itemizedlist>
    8879 
    8880     <para>
    8881       You can specify additional DHCP options with the
    8882       <computeroutput>--options</computeroutput> command option. Use
    8883       <computeroutput>--id</computeroutput> and
    8884       <computeroutput>--value</computeroutput> to configure a number and
    8885       string pair corresponding to the DHCP option. Use
    8886       <computeroutput>--remove</computeroutput> to remove a DHCP option.
    8887     </para>
    8888 
    8889     <para>
    8890       The <computeroutput>--vm</computeroutput> and
    8891       <computeroutput>--nic</computeroutput> settings enable you to
    8892       configure DHCP options for a specific network adapter used by the
    8893       named VM.
    8894     </para>
    8895 
    8896     <para>
    8897       Finally, you must specify
    8898       <computeroutput>--enable</computeroutput> or the DHCP server will
    8899       be created in the disabled state and will not be running.
    8900     </para>
    8901 
    8902     <para>
    8903       After this, &product-name; will automatically start the DHCP
    8904       server for the specified internal network or host-only network as
    8905       soon as the first virtual machine which uses that network is
    8906       started.
    8907     </para>
    8908 
    8909     <para>
    8910       Use <command>VBoxManage dhcpserver remove</command> with the given
    8911       <computeroutput>--netname &lt;network_name&gt;</computeroutput> or
    8912       <computeroutput>--ifname &lt;hostonly_if_name&gt;</computeroutput>
    8913       to remove the DHCP server for the specified internal network or
    8914       host-only network.
    8915     </para>
    8916 
    8917     <para>
    8918       To modify the settings of a DHCP server created using
    8919       <command>VBoxManage dhcpserver add</command>, you can use
    8920       <command>VBoxManage dhcpserver modify</command> for a given
    8921       network or host-only interface name. This has the same parameters
    8922       as <command>VBoxManage dhcpserver add</command>.
    8923     </para>
    8924 
    8925   </sect1>
    8926 
    89278792  <sect1 id="vboxmanage-usbdevsource">
    89288793
    … …  
    90088873  <xi:include href="user_man_VBoxManage-clonevm.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    90098874  <xi:include href="user_man_VBoxManage-extpack.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     8875  <xi:include href="user_man_VBoxManage-dhcpserver.xml"     xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    90108876  <xi:include href="user_man_VBoxManage-cloudprofile.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    90118877  <xi:include href="user_man_VBoxManage-cloudlist.xml"      xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
Note: See TracChangeset for help on using the changeset viewer.

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