Revisit documentation

There were a few issues with the documentation, where it grew some hairy
and weird phrasing. Fix those.

diff --git a/nbd-client.8.sgml b/nbd-client.8.sgml
index 421397d..af19bbc 100644 (file)
--- a/nbd-client.8.sgml
+++ b/nbd-client.8.sgml
@@ -201,6 +201,11 @@ manpage.1: manpage.sgml
        <listitem>
          <para>Specifies that the NBD client should not detach and
          daemonize itself. This is mostly useful for debugging.</para>
        <listitem>
          <para>Specifies that the NBD client should not detach and
          daemonize itself. This is mostly useful for debugging.</para>

+         <para>
+           Note that nbd-client will still fork once to trigger an
+           update to the device node's partition table. It is not
+           possible to disable this.
+         </para>

        </listitem>
       </varlistentry>
       <varlistentry>
        </listitem>
       </varlistentry>
       <varlistentry>

@@ -230,14 +235,14 @@ manpage.1: manpage.sgml
       <listitem>
        <para>To connect to a server running on port 2001 at host
          "swapserver.domain.com", using the client's block special
       <listitem>
        <para>To connect to a server running on port 2001 at host
          "swapserver.domain.com", using the client's block special

-         file "/dev/nb1", for swap purposes:</para>
-       <para><command>nbd-client swapserver.domain.com 2001 /dev/nb1
+         file "/dev/nbd1", for swap purposes:</para>
+       <para><command>nbd-client swapserver.domain.com 2001 /dev/nbd1

          -swap</command></para>
       </listitem>
       <listitem>
        <para>To disconnect the above connection again (after making
          sure the block special file is not in use anymore):</para>
          -swap</command></para>
       </listitem>
       <listitem>
        <para>To disconnect the above connection again (after making
          sure the block special file is not in use anymore):</para>

-       <para><command>nbd-client -d /dev/nb1</command></para>
+       <para><command>nbd-client -d /dev/nbd1</command></para>

       </listitem>
     </itemizedlist>
   </refsect1>
       </listitem>
     </itemizedlist>
   </refsect1>

@@ -264,20 +269,3 @@ manpage.1: manpage.sgml
 
   </refsect1>
 </refentry>
 
   </refsect1>
 </refentry>

-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:2
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:nil
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
--->

diff --git a/nbd-server.1.sgml b/nbd-server.1.sgml
index 008176d..c9190b0 100644 (file)
--- a/nbd-server.1.sgml
+++ b/nbd-server.1.sgml
@@ -82,10 +82,12 @@ manpage.1: manpage.sgml
     were a local filesystem.</para>
 
     <para><command>&dhpackage;</command> implements some security
     were a local filesystem.</para>
 
     <para><command>&dhpackage;</command> implements some security

-    through a file called "nbd_server.allow" in the current directory (by default; a different file can be chosen with the '-l' option).
-    This file must list the IP-addresses of clients that are allowed
-    to connect. If it does not exist, all clients are able to connect.
-    If the file is empty, no clients can connect.</para>
+    through a file called "@sysconfdir@/nbd-server/allow" (by default; a
+    different file can be chosen with the '-l' option or through a
+    config file specification). This file must list the IP-addresses or
+    network masks of clients that are allowed to connect. If it does not
+    exist, all clients are able to connect. If the file is empty, no
+    clients can connect.</para>

 
     <para>Note that while the command line allows for specifying an
     export, the use of this option is deprecated. It is preferred to
 
     <para>Note that while the command line allows for specifying an
     export, the use of this option is deprecated. It is preferred to

@@ -114,14 +116,14 @@ manpage.1: manpage.sgml
        </listitem>
       </varlistentry>
       <varlistentry>
        </listitem>
       </varlistentry>
       <varlistentry>

-        <term><option>port</option>
-        </term>
-        <listitem>
-          <para>The port the server should listen to. A valid port is
+       <term><option>port</option>
+       </term>
+       <listitem>
+         <para>The port the server should listen to. A valid port is

            any number between 1 and 65536; if 0 is used, nbd-server
            will listen on stdin (so that nbd-server can be ran from
            inetd)</para>
            any number between 1 and 65536; if 0 is used, nbd-server
            will listen on stdin (so that nbd-server can be ran from
            inetd)</para>

-        </listitem>
+       </listitem>

       </varlistentry>
       <varlistentry>
        <term><option>filename</option></term>
       </varlistentry>
       <varlistentry>
        <term><option>filename</option></term>

@@ -137,7 +139,7 @@ manpage.1: manpage.sgml
        <term><option>size</option></term>
        <listitem>
          <para>The size of the block device at the client side. This
        <term><option>size</option></term>
        <listitem>
          <para>The size of the block device at the client side. This

-           is especially usefull in conjunction with the -m
+           is especially useful in conjunction with the -m

            option</para>
          <para>Can optionally be followed by one of K,k,M or
            m, in which case the size will be multiplied by 1024 (K
            option</para>
          <para>Can optionally be followed by one of K,k,M or
            m, in which case the size will be multiplied by 1024 (K

@@ -187,7 +189,7 @@ manpage.1: manpage.sgml
        </listitem>
       </varlistentry>
       <varlistentry>
        </listitem>
       </varlistentry>
       <varlistentry>

-        <term><option>-C</option></term>
+       <term><option>-C</option></term>

        <listitem>
          <para>Specify configuration file. The default configuration
            file, if this parameter is not specified, is
        <listitem>
          <para>Specify configuration file. The default configuration
            file, if this parameter is not specified, is

@@ -220,7 +222,7 @@ manpage.1: manpage.sgml
        </listitem>
       </varlistentry>
       <varlistentry>
        </listitem>
       </varlistentry>
       <varlistentry>

-       <term><option>section name</option></term>
+       <term><option>section name</option></term>

        <listitem>
          <para>If the <option>-o</option> argument is given on the
          command line, then &dhpackage; will output a configuration
        <listitem>
          <para>If the <option>-o</option> argument is given on the
          command line, then &dhpackage; will output a configuration

@@ -282,20 +284,3 @@ manpage.1: manpage.sgml
 
   </refsect1>
 </refentry>
 
   </refsect1>
 </refentry>

-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:2
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:nil
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
--->

diff --git a/nbd-server.5.sgml b/nbd-server.5.sgml
index cfa07f3..bf245e3 100644 (file)
--- a/nbd-server.5.sgml
+++ b/nbd-server.5.sgml
@@ -83,9 +83,9 @@ manpage.1: manpage.sgml
       present, even if it holds no options. Every other section
       defines one export; the names of these sections are not
       important, except that you should take care to make sure that
       present, even if it holds no options. Every other section
       defines one export; the names of these sections are not
       important, except that you should take care to make sure that

-      each section name is unique (future versions of
-      <command>nbd-server</command> may use the section name to refer
-      to an export)
+      each section name is unique. The section name is used as the name
+      for the export in case the client connects with a name rather than
+      a port to specify an export, and must therefore be unique.

     </para>
     <para>
       A comment line is a line that starts with optional whitespace,
     </para>
     <para>
       A comment line is a line that starts with optional whitespace,

@@ -100,7 +100,7 @@ manpage.1: manpage.sgml
       type boolean. The value of a boolean option can be denoted with
       either true or false (so not yes, no, on, off, 1, or 0). All
       booleans default to false unless specified otherwise. No value
       type boolean. The value of a boolean option can be denoted with
       either true or false (so not yes, no, on, off, 1, or 0). All
       booleans default to false unless specified otherwise. No value

-      may be quoted (always enter it directly). For a string option,
+      may be quoted; always enter it directly. For a string option,

       leading whitespace is stripped (but trailing whitespace is not).
     </para>
 
       leading whitespace is stripped (but trailing whitespace is not).
     </para>
 

@@ -144,7 +144,7 @@ manpage.1: manpage.sgml
         </listitem>
       </varlistentry>
       <varlistentry>
         </listitem>
       </varlistentry>
       <varlistentry>

-        <term><option>oldstyle</option></term>
+       <term><option>oldstyle</option></term>

        <listitem>
          <para>
            Optional; boolean
        <listitem>
          <para>
            Optional; boolean

@@ -171,10 +171,18 @@ manpage.1: manpage.sgml
            always use the old handshake protocol and will not allow
            name-based exports.
          </para>
            always use the old handshake protocol and will not allow
            name-based exports.
          </para>

+         <para>
+           Also note that even if this parameter is set to true, all
+           exports will also be made available using the new handshake
+           protocol; it is not possible to switch that off. The reason
+           for this is that the old style protocol will eventually be
+           deprecated, and this option is only available to allow for
+           smooth upgrades.
+         </para>

        </listitem>
       </varlistentry>
       <varlistentry>
        </listitem>
       </varlistentry>
       <varlistentry>

-        <term><option>listenaddr</option></term>
+       <term><option>listenaddr</option></term>

        <listitem>
          <para>
            Optional; string
        <listitem>
          <para>
            Optional; string

@@ -230,8 +238,8 @@ manpage.1: manpage.sgml
            writes to this export will not be written to the master
            file, but to a separate file which will be removed upon
            disconnect. The result of using this option is that
            writes to this export will not be written to the master
            file, but to a separate file which will be removed upon
            disconnect. The result of using this option is that

-           nbd-server will be slower, and that any writes will be
-           lost upon disconnect.
+           nbd-server will be somewhat slower, and that any writes will
+           be lost upon disconnect.

          </para>
          <para>Corresponds to the <option>-c</option> option on the
            command line</para>
          </para>
          <para>Corresponds to the <option>-c</option> option on the
            command line</para>

@@ -312,8 +320,7 @@ manpage.1: manpage.sgml
          <para>
            The size of the individual files will be autodetected,
            <emphasis>even</emphasis> if the <option>filesize</option>
          <para>
            The size of the individual files will be autodetected,
            <emphasis>even</emphasis> if the <option>filesize</option>

-           option has been specified. See the documentation for the
-           <option>multifile</option> for details.
+           option has been specified.

          </para>
          <para>
            Corresponds to the <option>-m</option> option on the
          </para>
          <para>
            Corresponds to the <option>-m</option> option on the

@@ -326,11 +333,20 @@ manpage.1: manpage.sgml
        <listitem>
          <para>Required if 'oldstyle' global parameter is set; integer.</para>
          <para>
        <listitem>
          <para>Required if 'oldstyle' global parameter is set; integer.</para>
          <para>

-           The port on which this export is to be served. Currently
-           it is not possible to export multiple block devices on the
-           same port unless virtualization is used; future versions
-           of <command>nbd-server</command> may add this
-           functionality.
+           The port on which this export is to be served using the
+           old-style handshake protocol.
+         </para>
+         <para>
+           This parameter only makes sense when the 'oldstyle'
+           parameter is set to true in the 'generic' section. If that
+           parameter is not set, but this parameter is found in an
+           export section, then nbd-server will issue a warning upon
+           startup but should otherwise continue to function correctly.
+         </para>
+         <para>
+           It is not possible to combine multiple exports on the same
+           port using the old style handshake. Please use the new style
+           handshake for that purpose.

          </para>
          <para>
            When specified on the command line, this should be the
          </para>
          <para>
            When specified on the command line, this should be the

@@ -356,7 +372,7 @@ manpage.1: manpage.sgml
        </listitem>
       </varlistentry>
       <varlistentry>
        </listitem>
       </varlistentry>
       <varlistentry>

-        <term><option>sdp</option></term>
+       <term><option>sdp</option></term>

        <listitem>
          <para>Optional; boolean.</para>
          <para>
        <listitem>
          <para>Optional; boolean.</para>
          <para>

@@ -444,8 +460,16 @@ manpage.1: manpage.sgml
            Defines the style of virtualization. Virtualization allows
            one to create one export that will serve a different file
            depending on the IP address that is connecting. When
            Defines the style of virtualization. Virtualization allows
            one to create one export that will serve a different file
            depending on the IP address that is connecting. When

-           virtualization is There are three types of virtualization
-           that <command>nbd-server</command> supports:
+           virtualization is active, the
+           <replaceable>exportname</replaceable> parameter needs to
+           contain the string '%s'; this will then be replaced by the
+           IP address of the client connecting, in accordance with the
+           option selected here. The result of this transformation is
+           then used as the filename to be opened.
+         </para>
+         <para>
+           There are four types of virtualization that
+           <command>nbd-server</command> supports:

          </para>
          <variablelist>
            <varlistentry>
          </para>
          <variablelist>
            <varlistentry>

@@ -462,18 +486,20 @@ manpage.1: manpage.sgml
              <term><option>ipliteral</option></term>
              <listitem>
                <para>
              <term><option>ipliteral</option></term>
              <listitem>
                <para>

-                 <command>nbd-server</command> will look for the
-                 literal string '%s' in the
-                 <option>exportname</option>, and replace it by the
-                 address of the connecting host. The string that
-                 results from this transformation will be used as an
-                 absolute pathname that <command>nbd-server</command>
-                 will attempt to open. As an example, if a client
-                 connects from 192.168.1.100 and
-                 <option>exportname</option> is specified as
-                 <filename>/export/%s</filename>, then nbd-server
-                 will attempt to serve
-                 <filename>/export/192.168.1.100</filename>
+                 The %s is replaced by the IP address of the connecting
+                 host is used as-is.  For IPv4, this is done in
+                 dotted-quad notation; for IPv6, in hexadecimal form
+                 with leading zeros omitted.
+               </para>
+               <para>
+                 As an example, if a client connects from 192.168.1.100
+                 and <option>exportname</option> is specified as
+                 <filename>/export/%s</filename>, then nbd-server will
+                 attempt to serve
+                 <filename>/export/192.168.1.100</filename>. For IPv6,
+                 with a client connecting from 2001:6f8:32f::39, the
+                 filename would be
+                 <filename>/export/2001:6f8:32f:0:0:0:0:39</filename>

                </para>
              </listitem>
            </varlistentry>
                </para>
              </listitem>
            </varlistentry>

@@ -491,7 +517,9 @@ manpage.1: manpage.sgml
                <para>
                  Since there are no dots in most IPv6 addresses, the
                  effect of using this option when IPv6 is in use is
                <para>
                  Since there are no dots in most IPv6 addresses, the
                  effect of using this option when IPv6 is in use is

-                 indistinguishable from the ipliteral option.
+                 indistinguishable from the ipliteral option. It was
+                 thought that having to create an eight-deep directory
+                 structure would not be as useful.

                </para>
              </listitem>
            </varlistentry>
                </para>
              </listitem>
            </varlistentry>

@@ -512,7 +540,10 @@ manpage.1: manpage.sgml
                  <command>nbd-server</command> will try to open
                  <filename>/export/192.168.1.64/192.168.1.100</filename>.
                </para>
                  <command>nbd-server</command> will try to open
                  <filename>/export/192.168.1.64/192.168.1.100</filename>.
                </para>

-               <para>This option works as expected for IPv6.</para>
+               <para>For IPv6, in the above example, with
+               <constant>cidrhash 42</constant>, the filename would
+               be
+               <filename>/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39</filename>.</para>

              </listitem>
            </varlistentry>
          </variablelist>
              </listitem>
            </varlistentry>
          </variablelist>