Revisit documentation

[nbd.git] / nbd-server.5.sgml

diff --git a/nbd-server.5.sgml b/nbd-server.5.sgml
index 52378f3..bf245e3 100644 (file)
--- a/nbd-server.5.sgml
+++ b/nbd-server.5.sgml
@@ -63,10 +63,10 @@ manpage.1: manpage.sgml
     <para><command>&dhpackage;</command> allows to configure the
     nbd-server.</para>
 
     <para><command>&dhpackage;</command> allows to configure the
     nbd-server.</para>
 

-    <para>The default configuration file is
-      <filename>@SCD@/nbd-server/config</filename>, but this
-      can be varied with the <option>-C</option> option to
-      <command>nbd-server</command>(1).
+    <para>While
+      <filename>@sysconfdir@/nbd-server/config</filename> is the default
+      configuration file, this can be varied with the <option>-C</option>
+      option to <command>nbd-server</command>(1).

     </para>
     <para>
       The configuration file consists of section header lines, comment
     </para>
     <para>
       The configuration file consists of section header lines, comment

@@ -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,

@@ -98,9 +98,9 @@ manpage.1: manpage.sgml
       followed by an equals sign ("="), followed by the option
       value. An option can be of type string, of type integer, or of
       type boolean. The value of a boolean option can be denoted with
       followed by an equals sign ("="), followed by the option
       value. An option can be of type string, of type integer, or of
       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,
+      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,

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

@@ -143,7 +143,62 @@ manpage.1: manpage.sgml
          </para>
         </listitem>
       </varlistentry>
          </para>
         </listitem>
       </varlistentry>

+      <varlistentry>
+       <term><option>oldstyle</option></term>
+       <listitem>
+         <para>
+           Optional; boolean
+         </para>
+         <para>
+           If this option is set to true, nbd-server will export all
+           exports on a separate port with the old (pre-2.9.17)
+           handshake protocol. In that case, the 'port' option for
+           individual exports is mandatory.
+         </para>
+         <para>
+           If the option is set to false, the 'port' option for
+           individual exports is optional (and will be ignored if
+           specified). The server will only export devices on the
+           standard port.
+         </para>
+         <para>
+           For upgrades from pre-2.9.17 versions of nbd, it may be
+           appropriate to enable the oldstyle parameter until all
+           clients have been converted to using name-based exports.
+         </para>
+         <para>
+           Note that exports specified on the command line will
+           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>
+       <listitem>
+         <para>
+           Optional; string
+         </para>
+         <para>If this option is set, it should contain the local IP
+         address on which we should listen to
+         <command>nbd-client</command>(8) connections. If it is not
+           set, <command>nbd-server</command> will listen to all
+         local IPv4 and IPv6 addresses. To limit to IPv6, specify the
+         address as "::". To limit to IPv4, specify as "0.0.0.0". It
+         is not possible to specify more than one IP address
+         here.</para>
+       </listitem>
+      </varlistentry

     </variablelist>
     </variablelist>

+  </refsect1>

   <refsect1>
     <title>OPTIONS FOR EXPORT SECTIONS</title>
 
   <refsect1>
     <title>OPTIONS FOR EXPORT SECTIONS</title>
 

@@ -154,12 +209,14 @@ manpage.1: manpage.sgml
        <listitem>
          <para>
            Optional; string; default
        <listitem>
          <para>
            Optional; string; default

-           <filename>@SCD@/nbd-server/allow</filename>.
+           <filename>@sysconfdir@/nbd-server/allow</filename>.

          </para>
          <para>
            The name of the authorization file for this export. This
          </para>
          <para>
            The name of the authorization file for this export. This

-           file should contain one line per IP-address, and must not
-           contain wildcards of any kind or empty lines. If the file
+           file should contain one line per IP-address, or per
+           network (which must be specified in CIDR-style
+           <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>)
+           and must not contain empty lines. If the file

            does not exist, everyone is allowed to connect. If the
            file exists but is empty, nobody is allowed to
            connect. Otherwise, <command>nbd-server</command> will
            does not exist, everyone is allowed to connect. If the
            file exists but is empty, nobody is allowed to
            connect. Otherwise, <command>nbd-server</command> will

@@ -171,23 +228,6 @@ manpage.1: manpage.sgml
        </listitem>
       </varlistentry>
       <varlistentry>
        </listitem>
       </varlistentry>
       <varlistentry>

-       <term><option>autoreadonly</option></term>
-       <listitem>
-         <para>Optional; boolean.</para>
-         <para>
-           If this option is set to true, then
-           <command>nbd-server</command> will automatically switch to
-           readonly if it cannot write to the file.
-         </para>
-         <para>Does not have a corresponding command-line
-           argument</para>
-         <para>TODO: verify whether this option actually works as
-           documented. I have a feeling I've been terribly
-           stupid.
-         </para>
-       </listitem>
-      </varlistentry>
-      <varlistentry>

        <term><option>copyonwrite</option></term>
        <listitem>
          <para>
        <term><option>copyonwrite</option></term>
        <listitem>
          <para>

@@ -198,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>

@@ -210,9 +250,9 @@ manpage.1: manpage.sgml
        <listitem>
          <para>Required; string.</para>
          <para>
        <listitem>
          <para>Required; string.</para>
          <para>

-           The name of the file that will be exported. This must be a
-           fully-qualified path and filename; relative paths are not
-           allowed.
+           The name of the file (or block device) that will be
+           exported. This must be a fully-qualified path and filename;
+           relative paths are not allowed.

          </para>
          <para>
            Note that <command>nbd-server</command> will only try to
          </para>
          <para>
            Note that <command>nbd-server</command> will only try to

@@ -248,6 +288,20 @@ manpage.1: manpage.sgml
        </listitem>
       </varlistentry>
       <varlistentry>
        </listitem>
       </varlistentry>
       <varlistentry>

+       <term>listenaddr</term>
+       <listitem>
+         <para>
+           Optional; string
+         </para>
+         <para>
+           If the 'oldstyle' global parameter is specified, works
+           similarly to the global listenaddr parameter, but for the
+           individual port of this particular export. If the 'oldstyle'
+           parameter is not set, this parameter is ignored.
+         </para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>

        <term><option>multifile</option></term>
        <listitem>
          <para>Optional; boolean.</para>
        <term><option>multifile</option></term>
        <listitem>
          <para>Optional; boolean.</para>

@@ -257,8 +311,8 @@ manpage.1: manpage.sgml
            form
            <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
            with <replaceable>exportname</replaceable> being the
            form
            <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
            with <replaceable>exportname</replaceable> being the

-           filename that would otherwise have been used (after
-           name transformation for virtualization, if any, has been
+           filename that would otherwise have been used (after name
+           transformation for virtualization, if any, has been

            performed) and <replaceable>integer</replaceable> an
            integer number, starting with 0 and ending when no more
            files can be found.
            performed) and <replaceable>integer</replaceable> an
            integer number, starting with 0 and ending when no more
            files can be found.

@@ -266,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

@@ -278,13 +331,22 @@ manpage.1: manpage.sgml
       <varlistentry>
        <term><option>port</option></term>
        <listitem>
       <varlistentry>
        <term><option>port</option></term>
        <listitem>

-         <para>Required; integer.</para>
+         <para>Required if 'oldstyle' global parameter is set; integer.</para>

          <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

@@ -310,6 +372,45 @@ manpage.1: manpage.sgml
        </listitem>
       </varlistentry>
       <varlistentry>
        </listitem>
       </varlistentry>
       <varlistentry>

+       <term><option>sdp</option></term>
+       <listitem>
+         <para>Optional; boolean.</para>
+         <para>
+           When this option is enabled, <command>nbd-server</command>
+           will use the Socket Direct Protocol (SDP) to serve the
+           export, rather than just IP. This is faster, but requires
+           special hardware (usually something like InfiniBand) and
+           support in the kernel.
+         </para>
+         <para>
+           Additionally, support for this option must be enabled at
+           compile time, using the <option>--enable-sdp</option> option
+           to the <command>configure</command> script. If this option
+           is found in a configuration file and
+           <command>nbd-server</command> does not have support for SDP,
+           then <command>nbd-server</command> will exit with an error
+           message.
+         </para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>sync</option></term>
+       <listitem>
+         <para>Optional; boolean.</para>
+         <para>When this option is enabled,
+           <command>nbd-server</command> will call an fsync() after every
+           write to the backend storage. Calling fsync() increases
+           reliability in case of an unclean shutdown of nbd-server; but,
+           depending on the file system used on the nbd-server side, may
+           degrade performance. The use of this option isn't always
+           necessary; e.g., on ext3 filesystems, it is recommended that
+           it is <emphasis>not</emphasis> enabled, since it seriously
+           reduces performance on ext3 filesystems while not
+           importantly impacting reliability.
+         </para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>

        <term><option>sparse_cow</option></term>
        <listitem>
          <para>Optional; boolean.</para>
        <term><option>sparse_cow</option></term>
        <listitem>
          <para>Optional; boolean.</para>

@@ -318,7 +419,8 @@ manpage.1: manpage.sgml
            will use sparse files to implement the copy-on-write
            option; such files take up less space then they appear to,
            which allows <command>nbd-server</command> to handle the
            will use sparse files to implement the copy-on-write
            option; such files take up less space then they appear to,
            which allows <command>nbd-server</command> to handle the

-           file as if it was just as large as the block device it's for.
+           file as if it was just as large as the block device it's
+           for.

          </para>
          <para>
            If this option is disabled, <command>nbd-server</command>
          </para>
          <para>
            If this option is disabled, <command>nbd-server</command>

@@ -358,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>

@@ -376,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
-                 IP address of the connecting host in dotted-quad
-                 notation. 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>

@@ -402,6 +514,13 @@ manpage.1: manpage.sgml
                  open <filename>/export/192/168/1/100</filename>
                  instead.
                </para>
                  open <filename>/export/192/168/1/100</filename>
                  instead.
                </para>

+               <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. It was
+                 thought that having to create an eight-deep directory
+                 structure would not be as useful.
+               </para>

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

@@ -412,22 +531,73 @@ manpage.1: manpage.sgml
                  after it. <command>nbd-server</command> will use the
                  number as a network mask in CIDR style, and use that
                  as a hash cutoff point. In the above example, if
                  after it. <command>nbd-server</command> will use the
                  number as a network mask in CIDR style, and use that
                  as a hash cutoff point. In the above example, if

-                 <option>virtstyle</option> has been specified
-                 as <constant>cidrhash 16</constant>, then
+                 <option>virtstyle</option> has been specified as
+                 <constant>cidrhash 16</constant>, then

                  <command>nbd-server</command> will try to open
                  <command>nbd-server</command> will try to open

-                 <filename>/export/192.168.0.0/192.168.1.100</filename>; if
-                 <option>virtstyle</option> were specified as
+                 <filename>/export/192.168.0.0/192.168.1.100</filename>;
+                 if <option>virtstyle</option> were specified as

                  <constant>cidrhash 26</constant>, then
                  <command>nbd-server</command> will try to open
                  <filename>/export/192.168.1.64/192.168.1.100</filename>.
                </para>
                  <constant>cidrhash 26</constant>, then
                  <command>nbd-server</command> will try to open
                  <filename>/export/192.168.1.64/192.168.1.100</filename>.
                </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>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
       </varlistentry>

+      <varlistentry>
+       <term><option>prerun</option></term>
+       <listitem>
+         <para>Optional; string</para>
+         <para>
+           If specified, then this command will be ran after a
+           client has connected to the server (and has been
+           accepted), but before the server starts serving. If
+           the command contains the literal string '%s', then
+           this string will be replaced by the filename of the
+           file which nbd-server wants to export.
+         </para>
+         <para>
+           This is useful to create export files on the fly, or
+           to verify that a file can be used for export, to
+           write something to a log file, or similar.
+         </para>
+         <para>
+           If the command runs with a non-zero exit status,
+           then nbd-server will assume the export will fail,
+           and refuse to serve it.
+         </para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><option>postrun</option></term>
+       <listitem>
+         <para>Optional; string</para>
+         <para>
+           If specified, then it is assumed to be a command
+           that will be ran when a client has
+           disconnected. This can be useful to clean up
+           whatever <option>prerun</option> has set up, to log
+           something, or similar.
+         </para>
+         <para>
+           If the literal string '%s' is present in the
+           command, it will be replaced by the file name that
+           has just been closed.
+         </para>
+         <para>
+           In contrast to the <option>prerun</option> option,
+           the exit state of <option>postrun</option> is
+           <emphasis>ignored</emphasis>.
+         </para>
+       </listitem>
+      </varlistentry>

     </variablelist>
     </variablelist>

-
+    

   </refsect1>
   <refsect1>
     <title>SEE ALSO</title>
   </refsect1>
   <refsect1>
     <title>SEE ALSO</title>

@@ -457,6 +627,34 @@ manpage.1: manpage.sgml
       version 2, as published by the Free Software Foundation.</para>
 
   </refsect1>
       version 2, as published by the Free Software Foundation.</para>
 
   </refsect1>

+  <refsect1>
+    <title>EXAMPLES</title>
+    <para>A simple <command>nbd-server</command> configuration file
+      would look like this:</para>
+    <programlisting>
+      [generic]
+      [export]
+          exportname = /export/blkdev
+          port = 12345
+    </programlisting>
+    <para>For increased security, one might want to create an
+      authorization file, and set the UID and GID to run as:</para>
+    <programlisting>
+      [generic]
+          user = nbd
+          group = nbd
+      [export]
+          exportname = /export/blkdev
+          port = 12345
+          authfile = /etc/nbd-server/allow
+    </programlisting>
+    <para>With /etc/nbd-server/allow containing the following:</para>
+    <programlisting>
+      127.0.0.1
+      192.168.0.0/8
+      192.168.1.1
+    </programlisting>
+  </refsect1>

 </refentry>
 
 <!-- Keep this comment at the end of the file
 </refentry>
 
 <!-- Keep this comment at the end of the file