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>
+         <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>
@@ -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
-         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>
-       <para><command>nbd-client -d /dev/nb1</command></para>
+       <para><command>nbd-client -d /dev/nbd1</command></para>
       </listitem>
     </itemizedlist>
   </refsect1>
@@ -264,20 +269,3 @@ manpage.1: manpage.sgml
 
   </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
-    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
@@ -114,14 +116,14 @@ manpage.1: manpage.sgml
        </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>
-        </listitem>
+       </listitem>
       </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
-           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
@@ -187,7 +189,7 @@ manpage.1: manpage.sgml
        </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
@@ -220,7 +222,7 @@ manpage.1: manpage.sgml
        </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
@@ -282,20 +284,3 @@ manpage.1: manpage.sgml
 
   </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
-      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,
@@ -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
-      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>
 
@@ -144,7 +144,7 @@ manpage.1: manpage.sgml
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>oldstyle</option></term>
+       <term><option>oldstyle</option></term>
        <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>
+         <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>
-        <term><option>listenaddr</option></term>
+       <term><option>listenaddr</option></term>
        <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
-           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>
@@ -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>
-           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
@@ -326,11 +333,20 @@ manpage.1: manpage.sgml
        <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
@@ -356,7 +372,7 @@ manpage.1: manpage.sgml
        </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>sdp</option></term>
+       <term><option>sdp</option></term>
        <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
-           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>
@@ -462,18 +486,20 @@ manpage.1: manpage.sgml
              <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>
@@ -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
-                 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>
@@ -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>
-               <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>