man/nbd-server.5.sgml.in

   1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2
   3 <!-- Process this file with docbook-to-man to generate an nroff manual
   4      page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
   5      the manual page with: `docbook-to-man manpage.sgml | nroff -man |
   6      less'.  A typical entry in a Makefile or Makefile.am is:
   7
   8 manpage.1: manpage.sgml
   9         docbook-to-man $< > $@
  10   -->
  11
  12   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  13   <!ENTITY dhfirstname "<firstname>Wouter</firstname>">
  14   <!ENTITY dhsurname   "<surname>Verhelst</surname>">
  15   <!-- Please adjust the date whenever revising the manpage. -->
  16   <!ENTITY dhdate      "<date>$Date: 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $</date>">
  17   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
  18        allowed: see man(7), man(1). -->
  19   <!ENTITY dhsection   "<manvolnum>5</manvolnum>">
  20   <!ENTITY dhemail     "<email>wouter@debian.org</email>">
  21   <!ENTITY dhusername  "Wouter Verhelst">
  22   <!ENTITY dhucpackage "<refentrytitle>nbd-server</refentrytitle>">
  23   <!ENTITY dhpackage   "@MAN_SYSCONFDIR@/nbd-server/config">
  24
  25   <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  26   <!ENTITY gnu         "<acronym>GNU</acronym>">
  27 ]>
  28
  29 <refentry>
  30   <refentryinfo>
  31     <address>
  32       &dhemail;
  33     </address>
  34     <author>
  35       &dhfirstname;
  36       &dhsurname;
  37     </author>
  38     <copyright>
  39       <year>2006</year>
  40       <holder>&dhusername;</holder>
  41     </copyright>
  42     &dhdate;
  43   </refentryinfo>
  44   <refmeta>
  45     &dhucpackage;
  46
  47     &dhsection;
  48   </refmeta>
  49   <refnamediv>
  50     <refname>&dhpackage;</refname>
  51
  52     <refpurpose>configuration file for nbd-server</refpurpose>
  53   </refnamediv>
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>&dhpackage; </command>
  57
  58     </cmdsynopsis>
  59   </refsynopsisdiv>
  60   <refsect1>
  61     <title>DESCRIPTION</title>
  62
  63     <para>This file allows to configure the nbd-server.</para>
  64
  65     <para>While
  66       <filename>@MAN_SYSCONFDIR@/nbd-server/config</filename> is the default
  67       configuration file, this can be varied with the <option>-C</option>
  68       option to <command>nbd-server</command>(1).
  69     </para>
  70     <para>
  71       The configuration file consists of section header lines, comment
  72       lines, and option lines.
  73     </para>
  74     <para>
  75       A section header is a unique name that
  76       is enclosed in square brackets ("[" and "]"). A section header
  77       denotes the beginning of a section; a section continues until
  78       the next section or the end of the file, whichever is first. The
  79       first section in the configuration file must be called
  80       <option>generic</option>, and is used for global options that
  81       apply to more than one export. This section must always be
  82       present, even if it holds no options. Every other section
  83       defines one export; the names of these sections are not
  84       important, except that you should take care to make sure that
  85       each section name is unique. The section name is used as the name
  86       for the export in case the client connects with a name rather than
  87       a port to specify an export, and must therefore be unique.
  88     </para>
  89     <para>
  90       A comment line is a line that starts with optional whitespace,
  91       followed by a pound sign ("#"), and continues until the end of
  92       the line. Comments may <emphasis>not</emphasis> be used on
  93       option lines or section header lines.
  94     </para>
  95     <para>
  96       An option line is a line that starts with an option name,
  97       followed by an equals sign ("="), followed by the option
  98       value. An option can be of type string, of type integer, or of
  99       type boolean. The value of a boolean option can be denoted with
 100       either true or false (so not yes, no, on, off, 1, or 0). All
 101       booleans default to false unless specified otherwise. No value
 102       may be quoted; always enter it directly. For a string option,
 103       leading whitespace is stripped (but trailing whitespace is not).
 104     </para>
 105
 106   </refsect1>
 107   <refsect1>
 108     <title>OPTIONS FOR SECTION [generic]</title>
 109
 110     <!-- These are in alphabetical order, please keep it that way -->
 111     <variablelist>
 112       <varlistentry>
 113         <term><option>allowlist</option></term>
 114         <listitem>
 115           <para>
 116             Optional; boolean
 117           </para>
 118           <para>
 119             Whether to allow the client to fetch a list of exports from
 120             this server. If enabled, the client can run
 121             <command>nbd-client -l</command> to get a list of exports
 122             on this server.
 123           </para>
 124         </listitem>
 125       </varlistentry>
 126       <varlistentry>
 127         <term><option>cacertfile</option></term>
 128         <listitem>
 129           <para>
 130             Optional; string
 131           </para>
 132           <para>If this option is set, it should contain a path to
 133           a PEM format X.509 CA certificate used for validating client
 134           certificates supplied by the client. If this option is not
 135           set then client certificates will not be checked.</para>
 136         </listitem>
 137       </varlistentry>
 138       <varlistentry>
 139         <term><option>certfile</option></term>
 140         <listitem>
 141           <para>
 142             Optional; string
 143           </para>
 144           <para>If this option is set, it should contain a path to
 145           a PEM format X.509 public certificate used for TLS negotiation
 146           with the client. If <option>keyfile</option> is set but
 147           <option>certfile</option> is not set, then the server will
 148           attempt to read the certificate from the path specified
 149           by <option>keyfile</option>.</para>
 150         </listitem>
 151       </varlistentry>
 152       <varlistentry>
 153         <term><option>force_tls</option></term>
 154         <listitem>
 155           <para>
 156             Optional; boolean.
 157           </para>
 158           <para>
 159             Switch the server to FORCEDTLS mode.
 160           </para>
 161           <para>
 162             Note: this is <emphasis>not</emphasis> the same as enabling
 163             the force_tls option for each and every export individually.
 164             The latter will allow certain options to be issued during
 165             negotiation (e.g., the "list exports" option, even if that
 166             would return an empty result set), whereas enabling this
 167             option will disallow the use of <emphasis>any</emphasis>
 168             option to be issued during negotiation, apart from the
 169             STARTTLS option itself (to switch the transport to TLS).
 170           </para>
 171           <para>
 172             Using FORCEDTLS mode should result in a safer environment,
 173             as the server will not allow any communication to take place
 174             unless and until TLS has been negotiated. However, it also
 175             makes it impossible to set up a nonencrypted export for the
 176             benefit of older clients, or for clients that want to swap
 177             and not deadlock.
 178           </para>
 179           <para>
 180             Using this parameter without also specifying a value for the
 181             other TLS-related parameters is possible, but silly.
 182           </para>
 183         </listitem>
 184       </varlistentry>
 185       <varlistentry>
 186         <term><option>group</option></term>
 187         <listitem>
 188           <para>
 189             Optional; string.
 190           </para>
 191           <para>
 192             The name of the group this server must run as. If this
 193             parameter is not specified, then nbd-server will not
 194             attempt to change its GID (so the GID it runs as will be
 195             the primary group of the user who starts nbd-server). If
 196             it is specified, then nbd-server will change its GID after
 197             opening ports, but before accepting connections or opening
 198             files.
 199           </para>
 200         </listitem>
 201       </varlistentry>
 202       <varlistentry>
 203         <term><option>includedir</option></term>
 204         <listitem>
 205           <para>
 206             Optional; string
 207           </para>
 208           <para>
 209             The argument should be a directory containing files with
 210             the '.conf' extension; these files will be parsed as if
 211             they were part of the configuration file. Note that these
 212             extra configuration files cannot contain a [generic]
 213             section; any configuration that should go in the generic
 214             section must be placed in the main configuration file.
 215           </para>
 216           <para>
 217             If this argument is not specified, then no directory will
 218             be searched. If it is specified but the directory does not
 219             exist, then nbd-server will exit with an appropriate error
 220             message; if it is specified but the given directory is
 221             empty, nbd-server will continue (unless no exports
 222             whatsoever have been configured, in which case it will
 223             exit with an appropriate error message)
 224           </para>
 225         </listitem>
 226       </varlistentry>
 227       <varlistentry>
 228         <term><option>keyfile</option></term>
 229         <listitem>
 230           <para>
 231             Optional; string
 232           </para>
 233           <para>If this option is set, it should contain a path to
 234           a PEM format X.509 private key used for TLS negotiation
 235           with the client. This option must be set to enable TLS.</para>
 236         </listitem>
 237       </varlistentry>
 238       <varlistentry>
 239         <term><option>listenaddr</option></term>
 240         <listitem>
 241           <para>
 242             Optional; string
 243           </para>
 244           <para>If this option is set, it should contain a comma-separated lis
 245           of the local IP addresses on which we should listen to
 246           <command>nbd-client</command>(8) connections. If it is not set,
 247           <command>nbd-server</command> will listen to "::, 0.0.0.0", which
 248           causes nbd-server to listen to all local IPv4 and IPv6 addresses. To
 249           limit to IPv6, specify the address as "::". To limit to IPv4, specify
 250           as "0.0.0.0".</para>
 251         </listitem>
 252       </varlistentry>
 253       <varlistentry>
 254         <term><option>max_threads</option></term>
 255         <listitem>
 256           <para>
 257             Optional; integer; default 4
 258           </para>
 259           <para>
 260             Since NBD 3.12, nbd-server will read requests in a main
 261             thread, but do the handling of these requests, and the
 262             sending of the reply, in a number of separate worker
 263             threads, which are shared among all exports. With this
 264             parameter, you can configure the number of these worker
 265             threads.
 266           </para>
 267           <para>
 268             The default should be reasonable for a dual-core single-disk
 269             server. You might want to increase it if you have a powerful
 270             server that does little else than serving NBD.
 271           </para>
 272         </listitem>
 273       </varlistentry>
 274       <varlistentry>
 275         <term><option>oldstyle</option></term>
 276         <listitem>
 277           <para>
 278             Optional; boolean
 279           </para>
 280           <para>
 281             In versions of nbd-server between 2.9.17 and 3.9.1, when this
 282             option was set to true, nbd-server would export all exports
 283             on a separate port with the old (pre-2.9.17) handshake
 284             protocol. In that case, the 'port' option for individual
 285             exports was mandatory.
 286           </para>
 287           <para>
 288             Since version 3.10 of nbd-server, however, this option is no
 289             longer supported, and any attempt to use it will result in
 290             nbd-server exiting with an appropriate error message.
 291           </para>
 292         </listitem>
 293       </varlistentry>
 294       <varlistentry>
 295         <term><option>port</option></term>
 296         <listitem>
 297           <para>
 298             Optional; string
 299           </para>
 300           <para>
 301             The port on which to listen for new-style nbd-client
 302             connections. If not specified, the IANA-assigned port of
 303             10809 is used.
 304           </para>
 305         </listitem>
 306       </varlistentry>
 307       <varlistentry>
 308         <term><option>splice</option></term>
 309         <listitem>
 310           <para>Optional; boolean</para>
 311           <para>Allow the server to use the splice() system call to
 312           handle read or write calls when possible. Using splice can
 313           speed up handling of such calls significantly. Unfortunately,
 314           splice cannot be used in combination with TLS or the copyonwrite
 315           mode, and will only work for requests smaller than
 316           1MiB.</para>
 317           <para>To handle these situations, the server will exit with an
 318           appropriate error message if splice and copyonwrite are both
 319           enabled for an export; it will silently ignore the splice
 320           option if TLS is enabled, falling back on normal reads and
 321           writes; and it will similarly fall back on normal reads when
 322           the request size exceeds 1MiB.</para>
 323         </listitem>
 324       </varlistentry>
 325       <varlistentry>
 326         <term><option>user</option></term>
 327         <listitem>
 328           <para>
 329             Optional; string.
 330           </para>
 331           <para>
 332             The name of the user this server must run as. If this
 333             parameter is not specified, then nbd-server will not
 334             attempt to change its UID (so the UID it runs as will be
 335             the user who starts nbd-server). If it is specified, then
 336             nbd-server will change its UID after opening ports, but
 337             before accepting connections or opening files.
 338           </para>
 339         </listitem>
 340       </varlistentry>
 341       <varlistentry>
 342         <term><option>unixsock</option></term>
 343         <listitem>
 344           <para>
 345             Optional; string
 346           </para>
 347           <para>
 348             Path for a UNIX domain socket.
 349           </para>
 350           <para>
 351             If specified, the server will listen on a UNIX domain socket
 352             with the specified name. Only newstyle negotiation is
 353             supported on UNIX domain sockets. If a UNIX domain socket is,
 354             then the server will not listen for TCP connections.
 355           </para>
 356         </listitem>
 357       </varlistentry>
 358       <varlistentry>
 359         <term><option>duallisten</option></term>
 360         <listitem>
 361           <para>
 362             Optional; boolean
 363           </para>
 364           <para>
 365             If true, and <option>unixsock</option> is specified, the the
 366             server will listen on both the configured UNIX domain socket
 367             and any configured TCP or SDP socket.  Defaults to false.
 368           </para>
 369         </listitem>
 370       </varlistentry>
 371       <varlistentry>
 372         <term><option>tlsprio</option></term>
 373         <listitem>
 374           <para>Optional; string; default NORMAL:+VERS-TLS-ALL:-VERS-TLS1.0:-VERS-TLS1.1:%SERVER_PRECEDENCE</para>
 375           <para>This option allows to configure the GnuTLS priority
 376             string, which is used to select the algorithms which GnuTLS
 377             will allow to be negotiated with the client. The NBD
 378             STARTTLS specification requires that clients and servers
 379             require TLS1.2 or higher by default, so the default string
 380             disables all older versions of the TLS protocol.</para>
 381           <para>Not all versions of GnuTLS support the
 382             %SERVER_PRECEDENCE flag, which exists to signal that the
 383             server should pay no attention to the algorithm preferences
 384             selected by the client. If you're using an older version of
 385             GnuTLS (e.g., 2.12), it may be necessary to specify a
 386             priority string that does not include the %SERVER_PRECEDENCE
 387             flag.</para>
 388           <para>For an explanation of the possible values of this
 389             option, see the "Priority strings" chapter in the GnuTLS
 390             documentation.</para>
 391         </listitem>
 392       </varlistentry>
 393     </variablelist>
 394   </refsect1>
 395   <refsect1>
 396     <title>OPTIONS FOR EXPORT SECTIONS</title>
 397
 398     <!-- These are in alphabetical order, please keep it that way -->
 399     <variablelist>
 400       <varlistentry>
 401         <term><option>authfile</option></term>
 402         <listitem>
 403           <para>
 404             Optional; string; default empty
 405           </para>
 406           <para>
 407             The name of the authorization file for this export. This
 408             file should contain one line per IP-address, or per network
 409             (which must be specified in CIDR-style
 410             <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>).
 411             Empty lines are skipped, as is any content behind a hashmark
 412             ('#') on any line.
 413           </para>
 414           <para>
 415             If the file does not exist, everyone is allowed to connect.
 416             If the file exists but is empty, nobody is allowed to
 417             connect. Otherwise, <command>nbd-server</command> will only
 418             allow clients to connect whose IP-adres is listed in this
 419             file.
 420           </para>
 421           <para>Corresponds to the <option>-l</option> option on the
 422             command line. However, note that for the command line, the
 423             default is
 424             <filename>@MAN_SYSCONFDIR@/nbd-server/allow</filename>.
 425           </para>
 426         </listitem>
 427       </varlistentry>
 428       <varlistentry>
 429         <term><option>copyonwrite</option></term>
 430         <listitem>
 431           <para>
 432             Optional; boolean.
 433           </para>
 434           <para>
 435             Whether this is a copy-on-write export. If it is, then any
 436             writes to this export will not be written to the master
 437             file, but to a separate file which will be removed upon
 438             disconnect. The result of using this option is that
 439             nbd-server will be somewhat slower, and that any writes will
 440             be lost upon disconnect.
 441           </para>
 442           <para>Corresponds to the <option>-c</option> option on the
 443             command line</para>
 444         </listitem>
 445       </varlistentry>
 446       <varlistentry>
 447         <term><option>cowdir</option></term>
 448         <listitem>
 449           <para>
 450             Optional; string.
 451           </para>
 452           <para>
 453             Specifies where to write copy-on-write diff files. If this
 454             option is absent, copy-on-write files will be written in the
 455             same directory as the base export file. Useful for exporting
 456             files in copy-on-write mode from a directory that the user
 457             running nbd-server has no write access to.
 458           </para>
 459           <para>
 460             If the copy-on-write mode is not active, this option has no
 461             effect.
 462           </para>
 463         </listitem>
 464       </varlistentry>
 465       <varlistentry>
 466         <term><option>exportname</option></term>
 467         <listitem>
 468           <para>Required; string.</para>
 469           <para>
 470             The name of the file (or block device) that will be
 471             exported. This must be a fully-qualified path and filename;
 472             relative paths are not allowed. If used in conjunction with
 473             the <option>temporary</option>, this specifies a template
 474             for the temporary file concerned, and thus can be used
 475             to control the directory it is created in. If the file
 476             does not exist, but <option>filesize</option> is set, then
 477             the file will be created.
 478           </para>
 479           <para>
 480             Note that <command>nbd-server</command> will only try to
 481             find and open the exported file when a client actually
 482             connects; as a result, <command>nbd-server</command> must
 483             be able to open and read this file
 484             <emphasis>after</emphasis> changing to the user and group
 485             that have been specified by use of the
 486             <option>user</option> and <option>group</option> options;
 487             also, <command>nbd-server</command> will only detect
 488             errors in this option upon connection of a client.
 489           </para>
 490           <para>When specified on the command line, this should be the
 491             second argument.
 492           </para>
 493           <para><emphasis>Note:</emphasis> this is <emphasis>not</emphasis>
 494           the "exportname" as defined in the protocol document, and
 495           which is the name that <command>nbd-client</command> needs to
 496           pass to select the correct export; the section name is used
 497           for that. The name of the file to be exported is called the
 498           exportname in the configuration file for historical reasons,
 499           and cannot easily be changed.</para>
 500         </listitem>
 501       </varlistentry>
 502       <varlistentry>
 503         <term><option>filesize</option></term>
 504         <listitem>
 505           <para>Optional; integer; default autodetected.</para>
 506           <para>
 507             Disable autodetection of file or block device size, and
 508             forcibly specify a size. Sizes must be specified in
 509             bytes. If the <option>multifile</option> option is in
 510             effect, this option specifies the size of the
 511             <emphasis>entire</emphasis> export, not of individual
 512             files. If the file is not present, a single file is
 513             created of this size.
 514           </para>
 515           <para>When specified on the command line, this should be the
 516             third argument.
 517           </para>
 518         </listitem>
 519       </varlistentry>
 520       <varlistentry>
 521         <term><option>flush</option></term>
 522         <listitem>
 523           <para>Optional; boolean.</para>
 524           <para>When this option is enabled,
 525             <command>nbd-server</command> will inform the client that it
 526             supports and desires to be sent flush requests when the
 527             elevator layer receives them. Receipt of a flush request
 528             will cause an fdatasync() (or, if the sync option is set,
 529             an fsync()) on the backend storage. This increases
 530             reliability in the case of an unclean shutdown at
 531             the expense of a degradation of performance. This option
 532             will have no effect unless supported by the client.
 533           </para>
 534         </listitem>
 535       </varlistentry>
 536       <varlistentry>
 537         <term><option>force_tls</option></term>
 538         <listitem>
 539           <para>Optional; boolean.</para>
 540           <para>Require the use of TLS for this export to be available.</para>
 541           <para>When this option has been enabled for an export, clients
 542             that do not negotiate TLS will not see the export when they
 543             request a list of exports, and will not be able to connect to
 544             it.</para>
 545           <para>
 546             Enabling this option when TLS credentials have not been
 547             configured in the [generic] section is possible, but silly.
 548           </para>
 549         </listitem>
 550       </varlistentry>
 551       <varlistentry>
 552         <term><option>fua</option></term>
 553         <listitem>
 554           <para>Optional; boolean.</para>
 555           <para>When this option is enabled,
 556             <command>nbd-server</command> will inform the client that it
 557             supports and desires to be sent fua (force unit access) commands
 558             when the elevator layer receives them. Receipt of a force unit
 559             access command will cause the specified command to be synced
 560             to backend storage using sync_file_range() if supported, or
 561             fdatasync() otherwise. This increases
 562             reliability in the case of an unclean shutdown at
 563             the expense of a degradation of performance. This option
 564             will have no effect unless supported by the client.
 565           </para>
 566         </listitem>
 567       </varlistentry>
 568       <varlistentry>
 569         <term>listenaddr</term>
 570         <listitem>
 571           <para>
 572             Optional; string
 573           </para>
 574           <para>
 575             Ignored, kept for compatibility with the obsolete
 576             'oldstyle' global parameter.
 577           </para>
 578         </listitem>
 579       </varlistentry>
 580       <varlistentry>
 581         <term><option>maxconnections</option></term>
 582         <listitem>
 583           <para>Optional; integer</para>
 584           <para>
 585             If specified, then it limits the number of opened connections for
 586             this export.
 587           </para>
 588         </listitem>
 589       </varlistentry>
 590       <varlistentry>
 591         <term><option>multifile</option></term>
 592         <listitem>
 593           <para>Optional; boolean.</para>
 594           <para>
 595             If this option is set to true, then
 596             <command>nbd-server</command> will search for files of the
 597             form
 598             <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
 599             with <replaceable>exportname</replaceable> being the
 600             filename that would otherwise have been used (after name
 601             transformation for virtualization, if any, has been
 602             performed) and <replaceable>integer</replaceable> an
 603             integer number, starting with 0 and ending when no more
 604             files can be found.
 605           </para>
 606           <para>
 607             The size of the individual files will be autodetected,
 608             <emphasis>even</emphasis> if the <option>filesize</option>
 609             option has been specified.
 610           </para>
 611           <para>
 612             Corresponds to the <option>-m</option> option on the
 613             command line.
 614           </para>
 615         </listitem>
 616       </varlistentry>
 617       <varlistentry>
 618         <term><option>treefiles</option></term>
 619         <listitem>
 620           <para>Optional; boolean.</para>
 621           <para>
 622             If this option is set to true, then
 623             <command>nbd-server</command> will search for files of the
 624             form
 625             <replaceable>exportname</replaceable>/<replaceable>TREEXXXX</replaceable>/.../<replaceable>FILEXXXX</replaceable>,
 626             with <replaceable>exportname</replaceable> being the
 627             filename that would otherwise have been used (after name
 628             transformation for virtualization, if any, has been
 629             performed) and <replaceable>TREEXXXX</replaceable> and
 630             <replaceable>FILEXXXX</replaceable> being autogenerated directory
 631             and path names for individual block files.
 632           </para>
 633           <para>
 634             Files and directories are automatically created.
 635             Files will be deleted if the corresponding block gets marked as unused.
 636             The size of the individual block files is fixed to 4096 bytes.
 637             There will be at most 1024 files/subdirectories per folder.
 638             An apropriate nesting level of subdirectories will be created to
 639             create a filesystem of <option>filesize</option> bytes in total
 640             forming a virtual block device.
 641           </para>
 642           <para>
 643             This feature is useful to provide a virtual block device on an underlying
 644             filesystem that does not handle large files well, for example fuse/ftpfs, davfs
 645             or other network filesytems.
 646           </para>
 647           <para>
 648             This feature is mutually exclusive with the
 649             <option>-m</option> and will take precedence if both are given.
 650             There is no corresponding command line option, since command line control is considered
 651             deprecated. You can however specify a custom config file with the <option>-C</option> option.
 652             The <option>filesize</option> option <emphasis>must</emphasis> be specified when using this feature!
 653           </para>
 654         </listitem>
 655       </varlistentry>
 656       <varlistentry>
 657         <term><option>postrun</option></term>
 658         <listitem>
 659           <para>Optional; string</para>
 660           <para>
 661             If specified, then it is assumed to be a command
 662             that will be ran when a client has
 663             disconnected. This can be useful to clean up
 664             whatever <option>prerun</option> has set up, to log
 665             something, or similar.
 666           </para>
 667           <para>
 668             If the literal string '%s' is present in the
 669             command, it will be replaced by the file name that
 670             has just been closed.
 671           </para>
 672           <para>
 673             In contrast to the <option>prerun</option> option,
 674             the exit state of <option>postrun</option> is
 675             <emphasis>ignored</emphasis>.
 676           </para>
 677         </listitem>
 678       </varlistentry>
 679       <varlistentry>
 680         <term><option>prerun</option></term>
 681         <listitem>
 682           <para>Optional; string</para>
 683           <para>
 684             If specified, then this command will be ran after a
 685             client has connected to the server (and has been
 686             accepted), but before the server starts serving. If
 687             the command contains the literal string '%s', then
 688             this string will be replaced by the filename of the
 689             file which nbd-server wants to export.
 690           </para>
 691           <para>
 692             This is useful to create export files on the fly, or
 693             to verify that a file can be used for export, to
 694             write something to a log file, or similar.
 695           </para>
 696           <para>
 697             If the command runs with a nonzero exit status,
 698             then nbd-server will assume the export will fail,
 699             and refuse to serve it.
 700           </para>
 701         </listitem>
 702       </varlistentry>
 703       <varlistentry>
 704         <term><option>readonly</option></term>
 705         <listitem>
 706           <para>Optional; boolean.</para>
 707           <para>
 708             Disallow writes to the device. If this option is
 709             specified, <command>nbd-server</command> will issue an
 710             error to any client that tries to write to the device.
 711           </para>
 712           <para>
 713             Use of this option in conjunction with
 714             <option>copyonwrite</option> is possible, but silly.
 715           </para>
 716           <para>Corresponds to the <option>-r</option> option on the
 717           command line.</para>
 718         </listitem>
 719       </varlistentry>
 720       <varlistentry>
 721         <term><option>rotational</option></term>
 722         <listitem>
 723           <para>Optional; boolean.</para>
 724           <para>When this option is enabled,
 725             <command>nbd-server</command> will inform the client that
 726             it would prefer it to send requests in elevator (i.e., optimized) order, perhaps
 727             because it has a backing store and no local elevator. By
 728             default, the client uses QUEUE_FLAG_NONROT, which effectively
 729             restricts the function of the elevator to block merges. By
 730             specifying this flag on the server, the client will not use
 731             QUEUE_FLAG_NONROT, meaning the client elevator will perform
 732             normal elevator ordering of I/O requests. Note that even when
 733             the backing store is on rotating media, it is not normally
 734             necessary to specify this flag, as the server's elevator
 735             algorithm will be used. This flag is only required where
 736             the server will not be using an elevator algorithm or where
 737             the elevator algorithm is effectively neutered (e.g. with
 738             the sync option set). This option will have no effect unless
 739             supported by the client.
 740           </para>
 741         </listitem>
 742       </varlistentry>
 743       <varlistentry>
 744         <term><option>sdp</option></term>
 745         <listitem>
 746           <para>Optional; boolean.</para>
 747           <para>
 748             When this option is enabled, <command>nbd-server</command>
 749             will use the Socket Direct Protocol (SDP) to serve the
 750             export, rather than just IP. This is faster, but requires
 751             special hardware (usually something like InfiniBand) and
 752             support in the kernel.
 753           </para>
 754           <para>
 755             Additionally, support for this option must be enabled at
 756             compile time, using the <option>--enable-sdp</option> option
 757             to the <command>configure</command> script. If this option
 758             is found in a configuration file and
 759             <command>nbd-server</command> does not have support for SDP,
 760             then <command>nbd-server</command> will exit with an error
 761             message.
 762           </para>
 763         </listitem>
 764       </varlistentry>
 765       <varlistentry>
 766         <term><option>sparse_cow</option></term>
 767         <listitem>
 768           <para>Optional; boolean.</para>
 769           <para>
 770             When this option is enabled, <command>nbd-server</command>
 771             will use sparse files to implement the copy-on-write
 772             option; such files take up less space then they appear to,
 773             which allows <command>nbd-server</command> to handle the
 774             file as if it was just as large as the block device it's
 775             for.
 776           </para>
 777           <para>
 778             If this option is disabled, <command>nbd-server</command>
 779             will map every newly written block to the end of the
 780             copy-on-write file, which means that
 781             <command>nbd-server</command> will have to lseek(2) to the
 782             right position after every 4096-byte block.
 783           </para>
 784           <para>
 785             Using this option may be faster when much is being written
 786             during a connection.
 787           </para>
 788         </listitem>
 789       </varlistentry>
 790       <varlistentry>
 791         <term><option>sync</option></term>
 792         <listitem>
 793           <para>Optional; boolean.</para>
 794           <para>When this option is enabled,
 795             <command>nbd-server</command> will call an fsync() after every
 796             write to the backend storage. Calling fsync() increases
 797             reliability in case of an unclean shutdown of nbd-server; but,
 798             depending on the file system used on the nbd-server side, may
 799             degrade performance. The use of this option isn't always
 800             necessary; e.g., on ext3 filesystems, it is recommended that
 801             it is <emphasis>not</emphasis> enabled, since it seriously
 802             reduces performance on ext3 filesystems while not
 803             importantly impacting reliability.
 804           </para>
 805         </listitem>
 806       </varlistentry>
 807       <varlistentry>
 808         <term><option>temporary</option></term>
 809         <listitem>
 810           <para>Optional; boolean.</para>
 811           <para>
 812             Create a temporary export with a name based on exportname
 813             (this can be used to set the directory). A unique filename
 814             is created, which is unlinked as soon as it is created,
 815             and therefore the export will not persist between
 816             invocations of <command>nbd-server</command>. Set the
 817             size of the file using the <command>filesize</command>
 818             option. This option is incompatible with the
 819             <option>multifile</option> option.
 820           </para>
 821           <para>When specified on the command line, this should be the
 822             third argument.
 823           </para>
 824         </listitem>
 825       </varlistentry>
 826       <varlistentry>
 827         <term><option>timeout</option></term>
 828         <listitem>
 829           <para>Optional; integer; default 0</para>
 830           <para>
 831             How many seconds a connection may be idle for this
 832             export. When a connection is idle for a longer time,
 833             <command>nbd-server</command> will forcibly disconnect the
 834             connection. If you specify 0 (the default), then a
 835             connection may be idle forever.
 836           </para>
 837           <para>
 838             Corresponds to the <option>-a</option> option on the
 839             command line
 840           </para>
 841         </listitem>
 842       </varlistentry>
 843       <varlistentry>
 844         <term><option>transactionlog</option></term>
 845         <listitem>
 846           <para>Optional; string</para>
 847           <para>
 848             If specified, then this pathname is used to generate a transaction
 849             log. A transaction log is a binary file consisting of the requests
 850             sent to and the replies received by the server, but excluding any
 851             data (so, for a write command, it records the offset and length
 852             of the write but not the data written). It is therefore relatively
 853             safe to distribute to a third party. Note that the transaction log
 854             does not include the negotiation sequence. Transaction logs are
 855             mainly useful for debugging. The program
 856             <emphasis>nbd-tester-client</emphasis> distributed with the source
 857             to this program can reply a transaction log against a server and
 858             perform a data integrity test. Note that the transaction log is
 859             written to for every client opened. If it is necessary to maintain
 860             separate transaction logs for each client, the
 861             <emphasis>prerun</emphasis> script should rename the transaction log
 862             (which will just have been opened in order to avoid transaction logs
 863             overwriting eachother. This action should be race-free.
 864           </para>
 865         </listitem>
 866       </varlistentry>
 867       <varlistentry>
 868         <term><option>trim</option></term>
 869         <listitem>
 870           <para>Optional; boolean</para>
 871           <para>When this option is activated, the server announces it
 872             supports the NBD_CMD_TRIM command for the export. This
 873             command allows the server to discard the data from the disk,
 874             but does not require it to.
 875           </para>
 876         </listitem>
 877       </varlistentry>
 878       <varlistentry>
 879         <term><option>virtstyle</option></term>
 880         <listitem>
 881           <para>Optional; string; default "ipliteral"</para>
 882           <para>
 883             Defines the style of virtualization. Virtualization allows
 884             one to create one export that will serve a different file
 885             depending on the IP address that is connecting. When
 886             virtualization is active, the
 887             <replaceable>exportname</replaceable> parameter needs to
 888             contain the string '%s'; this will then be replaced by the
 889             IP address of the client connecting, in accordance with the
 890             option selected here. The result of this transformation is
 891             then used as the filename to be opened.
 892           </para>
 893           <para>
 894             When a client connects over a UNIX domain socket, the
 895             literal string "unix" is used in lieu of a client IP
 896             address.
 897           </para>
 898           <para>
 899             There are four types of virtualization that
 900             <command>nbd-server</command> supports:
 901           </para>
 902           <variablelist>
 903             <varlistentry>
 904               <term><option>none</option></term>
 905               <listitem>
 906                 <para>
 907                   No virtualization. Will attempt to open the filename
 908                   as it was written, even if it contains '%s' in the
 909                   name.
 910                 </para>
 911               </listitem>
 912             </varlistentry>
 913             <varlistentry>
 914               <term><option>ipliteral</option></term>
 915               <listitem>
 916                 <para>
 917                   The %s is replaced by the IP address of the connecting
 918                   host is used as-is.  For IPv4, this is done in
 919                   dotted-quad notation; for IPv6, in hexadecimal form
 920                   with leading zeros omitted.
 921                 </para>
 922                 <para>
 923                   As an example, if a client connects from 192.168.1.100
 924                   and <option>exportname</option> is specified as
 925                   <filename>/export/%s</filename>, then nbd-server will
 926                   attempt to serve
 927                   <filename>/export/192.168.1.100</filename>. For IPv6,
 928                   with a client connecting from 2001:6f8:32f::39, the
 929                   filename would be
 930                   <filename>/export/2001:6f8:32f:0:0:0:0:39</filename>
 931                 </para>
 932               </listitem>
 933             </varlistentry>
 934             <varlistentry>
 935               <term><option>iphash</option></term>
 936               <listitem>
 937                 <para>
 938                   Same as above, except that
 939                   <command>nbd-server</command> will replace the dots
 940                   in the IP address by forward slashes ('/'); in the
 941                   same example, <command>nbd-server</command> would
 942                   open <filename>/export/192/168/1/100</filename>
 943                   instead.
 944                 </para>
 945                 <para>
 946                   Since there are no dots in most IPv6 addresses, the
 947                   effect of using this option when IPv6 is in use is
 948                   indistinguishable from the ipliteral option. It was
 949                   thought that having to create an eight-deep directory
 950                   structure would not be as useful.
 951                 </para>
 952               </listitem>
 953             </varlistentry>
 954             <varlistentry>
 955               <term><option>cidrhash</option></term>
 956               <listitem>
 957                 <para>
 958                   This option requires one to add a space and a number
 959                   after it. <command>nbd-server</command> will use the
 960                   number as a network mask in CIDR style, and use that
 961                   as a hash cutoff point. In the above example, if
 962                   <option>virtstyle</option> has been specified as
 963                   <constant>cidrhash 16</constant>, then
 964                   <command>nbd-server</command> will try to open
 965                   <filename>/export/192.168.0.0/192.168.1.100</filename>;
 966                   if <option>virtstyle</option> were specified as
 967                   <constant>cidrhash 26</constant>, then
 968                   <command>nbd-server</command> will try to open
 969                   <filename>/export/192.168.1.64/192.168.1.100</filename>.
 970                 </para>
 971                 <para>For IPv6, in the above example, with
 972                 <constant>cidrhash 42</constant>, the filename would
 973                 be
 974                 <filename>/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39</filename>.</para>
 975               </listitem>
 976             </varlistentry>
 977           </variablelist>
 978         </listitem>
 979       </varlistentry>
 980       <varlistentry>
 981         <term><option>tlsonly</option></term>
 982         <listitem>
 983           <para>Optional; boolean.</para>
 984           <para>When this option is enabled,
 985             <command>nbd-server</command> will only serve the export
 986             using the TLS extension. If this option is not supplied,
 987             TLS is optional, unless <option>tlsonly</option> is set
 988             in the generic section. In order for TLS to work at all,
 989             the <option>keyfile</option> option must be specified in
 990             the generic section.
 991           </para>
 992         </listitem>
 993       </varlistentry>
 994       <varlistentry>
 995         <term><option>waitfile</option></term>
 996         <listitem>
 997           <para>Optional; string.</para>
 998           <para>When this option is set, <command>nbd-server</command>
 999             will allow writes to this export, but not reads, until the
1000             server is sent a SIGUSR1 command. Any writes to the export
1001             will be stored in a diff file with the same algorithm as for
1002             the copy-on-write option. In particular, this means that the
1003             <option>cowdir</option> option is in effect for this option,
1004             too.</para>
1005           <para>The backend file (as per the exportname parameter) need
1006             not exist until the SIGUSR1 signal is sent to the
1007             server.</para>
1008           <para>Once SIGUSR1 is received, <command>nbd-server</command>
1009             will open the main export file, and start merging all
1010             outstanding writes into it. Once this operation finishes,
1011             the diff file will be removed, and the server will allow
1012             normal use of the export.</para>
1013           <para>This allows the out-of-band live migration of an export
1014             from one server to another.</para>
1015           <para>Note that this option cannot be combined with the
1016             copy-on-write option itself.</para>
1017         </listitem>
1018       </varlistentry>
1019     </variablelist>
1020
1021   </refsect1>
1022   <refsect1>
1023     <title>SEE ALSO</title>
1024
1025     <para>nbd-server (1), nbd-client (8), nbd-trdump (8)</para>
1026
1027
1028   </refsect1>
1029   <refsect1>
1030     <title>AUTHOR</title>
1031     <para>The NBD kernel module and the NBD tools were originally
1032       written by Pavel Machek (pavel@ucw.cz)</para>
1033
1034     <para>The Linux kernel module is now maintained by Paul Clements
1035       (Paul.Clements@steeleye.com), while the userland tools are
1036       maintained by &dhusername; (&dhemail;)</para>
1037
1038     <para>On The Hurd there is a regular translator available to perform the
1039       client side of the protocol, and the use of
1040       <command>nbd-client</command> is not required. Please see the
1041       relevant documentation for more information.</para>
1042
1043     <para>This manual page was written by &dhusername; (&dhemail;) for
1044       the &debian; system (but may be used by others).  Permission is
1045       granted to copy, distribute and/or modify this document under
1046       the terms of the <acronym>GNU</acronym> General Public License,
1047       version 2, as published by the Free Software Foundation.</para>
1048
1049   </refsect1>
1050   <refsect1>
1051     <title>EXAMPLES</title>
1052     <para>A simple <command>nbd-server</command> configuration file
1053       would look like this:</para>
1054     <programlisting>
1055       [generic]
1056       [export]
1057           exportname = /export/blkdev
1058     </programlisting>
1059     <para>For increased security, one might want to create an
1060       authorization file, and set the UID and GID to run as:</para>
1061     <programlisting>
1062       [generic]
1063           user = nbd
1064           group = nbd
1065       [export]
1066           exportname = /export/blkdev
1067           authfile = @MAN_SYSCONFDIR@/nbd-server/allow
1068     </programlisting>
1069     <para>With @MAN_SYSCONFDIR@/nbd-server/allow containing the following:</para>
1070     <programlisting>
1071       127.0.0.1
1072       192.168.0.0/8
1073       192.168.1.1
1074     </programlisting>
1075   </refsect1>
1076 </refentry>
1077
1078 <!-- Keep this comment at the end of the file
1079 Local variables:
1080 mode: sgml
1081 sgml-omittag:t
1082 sgml-shorttag:t
1083 sgml-minimize-attributes:nil
1084 sgml-always-quote-attributes:t
1085 sgml-indent-step:2
1086 sgml-indent-data:t
1087 sgml-parent-document:nil
1088 sgml-default-dtd-file:nil
1089 sgml-exposed-tags:nil
1090 sgml-local-catalogs:nil
1091 sgml-local-ecat-files:nil
1092 End:
1093 -->