man/nbd-server.5.in.sgml

   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   "$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>$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>group</option></term>
 114         <listitem>
 115           <para>
 116             Optional; string.
 117           </para>
 118           <para>
 119             The name of the group this server must run as. If this
 120             parameter is not specified, then nbd-server will not
 121             attempt to change its GID (so the GID it runs as will be
 122             the primary group of the user who starts nbd-server). If
 123             it is specified, then nbd-server will change its GID after
 124             opening ports, but before accepting connections or opening
 125             files.
 126           </para>
 127         </listitem>
 128       </varlistentry>
 129       <varlistentry>
 130         <term><option>listenaddr</option></term>
 131         <listitem>
 132           <para>
 133             Optional; string
 134           </para>
 135           <para>If this option is set, it should contain the local IP
 136           address on which we should listen to
 137           <command>nbd-client</command>(8) connections. If it is not
 138             set, <command>nbd-server</command> will listen to all
 139           local IPv4 and IPv6 addresses. To limit to IPv6, specify the
 140           address as "::". To limit to IPv4, specify as "0.0.0.0". It
 141           is not possible to specify more than one IP address
 142           here.</para>
 143         </listitem>
 144       </varlistentry>
 145       <varlistentry>
 146         <term><option>oldstyle</option></term>
 147         <listitem>
 148           <para>
 149             Optional; boolean
 150           </para>
 151           <para>
 152             If this option is set to true, nbd-server will export all
 153             exports on a separate port with the old (pre-2.9.17)
 154             handshake protocol. In that case, the 'port' option for
 155             individual exports is mandatory.
 156           </para>
 157           <para>
 158             If the option is set to false, the 'port' option for
 159             individual exports is optional (and will be ignored if
 160             specified). The server will only export devices on the
 161             standard port.
 162           </para>
 163           <para>
 164             For upgrades from pre-2.9.17 versions of nbd, it may be
 165             appropriate to enable the oldstyle parameter until all
 166             clients have been converted to using name-based exports.
 167           </para>
 168           <para>
 169             Note that exports specified on the command line will
 170             always use the old handshake protocol and will not allow
 171             name-based exports.
 172           </para>
 173           <para>
 174             Also note that even if this parameter is set to true, all
 175             exports will also be made available using the new handshake
 176             protocol; it is not possible to switch that off. The reason
 177             for this is that the old style protocol will eventually be
 178             deprecated, and this option is only available to allow for
 179             smooth upgrades.
 180           </para>
 181         </listitem>
 182       </varlistentry>
 183       <varlistentry>
 184         <term><option>port</option></term>
 185         <listitem>
 186           <para>
 187             Optional; string
 188           </para>
 189           <para>
 190             The port on which to listen for new-style nbd-client
 191             connections. If not specified, the IANA-assigned port of
 192             10809 is used.
 193           </para>
 194         </listitem>
 195       </varlistentry>
 196       <varlistentry>
 197         <term><option>user</option></term>
 198         <listitem>
 199           <para>
 200             Optional; string.
 201           </para>
 202           <para>
 203             The name of the user this server must run as. If this
 204             parameter is not specified, then nbd-server will not
 205             attempt to change its UID (so the UID it runs as will be
 206             the user who starts nbd-server). If it is specified, then
 207             nbd-server will change its UID after opening ports, but
 208             before accepting connections or opening files.
 209           </para>
 210         </listitem>
 211       </varlistentry>
 212     </variablelist>
 213   </refsect1>
 214   <refsect1>
 215     <title>OPTIONS FOR EXPORT SECTIONS</title>
 216
 217     <!-- These are in alphabetical order, please keep it that way -->
 218     <variablelist>
 219       <varlistentry>
 220         <term><option>authfile</option></term>
 221         <listitem>
 222           <para>
 223             Optional; string; default
 224             <filename>$sysconfdir/nbd-server/allow</filename>.
 225           </para>
 226           <para>
 227             The name of the authorization file for this export. This
 228             file should contain one line per IP-address, or per
 229             network (which must be specified in CIDR-style
 230             <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>)
 231             and must not contain empty lines. If the file
 232             does not exist, everyone is allowed to connect. If the
 233             file exists but is empty, nobody is allowed to
 234             connect. Otherwise, <command>nbd-server</command> will
 235             only allow clients to connect whose IP-adres is listed in
 236             this file.
 237           </para>
 238           <para>Corresponds to the <option>-l</option> option on the
 239           command line</para>
 240         </listitem>
 241       </varlistentry>
 242       <varlistentry>
 243         <term><option>copyonwrite</option></term>
 244         <listitem>
 245           <para>
 246             Optional; boolean.
 247           </para>
 248           <para>
 249             Whether this is a copy-on-write export. If it is, then any
 250             writes to this export will not be written to the master
 251             file, but to a separate file which will be removed upon
 252             disconnect. The result of using this option is that
 253             nbd-server will be somewhat slower, and that any writes will
 254             be lost upon disconnect.
 255           </para>
 256           <para>Corresponds to the <option>-c</option> option on the
 257             command line</para>
 258         </listitem>
 259       </varlistentry>
 260       <varlistentry>
 261         <term><option>exportname</option></term>
 262         <listitem>
 263           <para>Required; string.</para>
 264           <para>
 265             The name of the file (or block device) that will be
 266             exported. This must be a fully-qualified path and filename;
 267             relative paths are not allowed. If used in conjunction with
 268             the <option>temporary</option>, this specifies a template
 269             for the temporary file concerned, and thus can be used
 270             to control the directory it is created in. If the file
 271             does not exist, but <option>filesize</option> is set, then
 272             the file will be created.
 273           </para>
 274           <para>
 275             Note that <command>nbd-server</command> will only try to
 276             find and open the exported file when a client actually
 277             connects; as a result, <command>nbd-server</command> must
 278             be able to open and read this file
 279             <emphasis>after</emphasis> changing to the user and group
 280             that have been specified by use of the
 281             <option>user</option> and <option>group</option> options;
 282             also, <command>nbd-server</command> will only detect
 283             errors in this option upon connection of a client.
 284           </para>
 285           <para>When specified on the command line, this should be the
 286             second argument.
 287           </para>
 288         </listitem>
 289       </varlistentry>
 290       <varlistentry>
 291         <term><option>filesize</option></term>
 292         <listitem>
 293           <para>Optional; integer; default autodetected.</para>
 294           <para>
 295             Disable autodetection of file or block device size, and
 296             forcibly specify a size. Sizes must be specified in
 297             bytes. If the <option>multifile</option> option is in
 298             effect, this option specifies the size of the
 299             <emphasis>entire</emphasis> export, not of individual
 300             files. If the file is not present, a single file is
 301             created of this size.
 302           </para>
 303           <para>When specified on the command line, this should be the
 304             third argument.
 305           </para>
 306         </listitem>
 307       </varlistentry>
 308       <varlistentry>
 309         <term><option>temporary</option></term>
 310         <listitem>
 311           <para>Optional; boolean.</para>
 312           <para>
 313             Create a temporary export with a name based on exportname
 314             (this can be used to set the directory). A unique filename
 315             is created, which is unlinked as soon as it is created,
 316             and therefore the export will not persist between
 317             invocations of <command>nbd-server</command>. Set the
 318             size of the file using the <command>filesize</command>
 319             option. This option is incompatible with the
 320             <option>multifile</option> option.
 321           </para>
 322           <para>When specified on the command line, this should be the
 323             third argument.
 324           </para>
 325         </listitem>
 326       </varlistentry>
 327       <varlistentry>
 328         <term><option>flush</option></term>
 329         <listitem>
 330           <para>Optional; boolean.</para>
 331           <para>When this option is enabled,
 332             <command>nbd-server</command> will inform the client that it
 333             supports and desires to be sent flush requests when the
 334             elevator layer receives them. Receipt of a flush request
 335             will cause an fdatasync() (or, if the sync option is set,
 336             an fsync()) on the backend storage. This increases
 337             reliability in the case of an unclean shutdown at
 338             the expense of a degradation of performance. This option
 339             will have no effect unless supported by the client.
 340           </para>
 341         </listitem>
 342       </varlistentry>
 343       <varlistentry>
 344         <term><option>fua</option></term>
 345         <listitem>
 346           <para>Optional; boolean.</para>
 347           <para>When this option is enabled,
 348             <command>nbd-server</command> will inform the client that it
 349             supports and desires to be sent fua (force unit access) commands
 350             when the elevator layer receives them. Receipt of a force unit
 351             access command will cause the specified command to be synced
 352             to backend storage using sync_file_range() if supported, or
 353             fdatasync() otherwise. This increases
 354             reliability in the case of an unclean shutdown at
 355             the expense of a degradation of performance. This option
 356             will have no effect unless supported by the client.
 357           </para>
 358         </listitem>
 359       </varlistentry>
 360       <varlistentry>
 361         <term>listenaddr</term>
 362         <listitem>
 363           <para>
 364             Optional; string
 365           </para>
 366           <para>
 367             If the 'oldstyle' global parameter is specified, works
 368             similarly to the global listenaddr parameter, but for the
 369             individual port of this particular export. If the 'oldstyle'
 370             parameter is not set, this parameter is ignored.
 371           </para>
 372         </listitem>
 373       </varlistentry>
 374       <varlistentry>
 375         <term><option>maxconnections</option></term>
 376         <listitem>
 377           <para>Optional; integer</para>
 378           <para>
 379             If specified, then it limits the number of opened connections for
 380             this export.
 381           </para>
 382         </listitem>
 383       </varlistentry>
 384       <varlistentry>
 385         <term><option>multifile</option></term>
 386         <listitem>
 387           <para>Optional; boolean.</para>
 388           <para>
 389             If this option is set to true, then
 390             <command>nbd-server</command> will search for files of the
 391             form
 392             <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
 393             with <replaceable>exportname</replaceable> being the
 394             filename that would otherwise have been used (after name
 395             transformation for virtualization, if any, has been
 396             performed) and <replaceable>integer</replaceable> an
 397             integer number, starting with 0 and ending when no more
 398             files can be found.
 399           </para>
 400           <para>
 401             The size of the individual files will be autodetected,
 402             <emphasis>even</emphasis> if the <option>filesize</option>
 403             option has been specified.
 404           </para>
 405           <para>
 406             Corresponds to the <option>-m</option> option on the
 407             command line.
 408           </para>
 409         </listitem>
 410       </varlistentry>
 411       <varlistentry>
 412         <term><option>port</option></term>
 413         <listitem>
 414           <para>Required if 'oldstyle' global parameter is set; integer.</para>
 415           <para>
 416             The port on which this export is to be served using the
 417             old-style handshake protocol.
 418           </para>
 419           <para>
 420             This parameter only makes sense when the 'oldstyle'
 421             parameter is set to true in the 'generic' section. If that
 422             parameter is not set, but this parameter is found in an
 423             export section, then nbd-server will issue a warning upon
 424             startup but should otherwise continue to function correctly.
 425           </para>
 426           <para>
 427             It is not possible to combine multiple exports on the same
 428             port using the old style handshake. Please use the new style
 429             handshake for that purpose.
 430           </para>
 431           <para>
 432             When specified on the command line, this should be the
 433             first argument.
 434           </para>
 435         </listitem>
 436       </varlistentry>
 437       <varlistentry>
 438         <term><option>postrun</option></term>
 439         <listitem>
 440           <para>Optional; string</para>
 441           <para>
 442             If specified, then it is assumed to be a command
 443             that will be ran when a client has
 444             disconnected. This can be useful to clean up
 445             whatever <option>prerun</option> has set up, to log
 446             something, or similar.
 447           </para>
 448           <para>
 449             If the literal string '%s' is present in the
 450             command, it will be replaced by the file name that
 451             has just been closed.
 452           </para>
 453           <para>
 454             In contrast to the <option>prerun</option> option,
 455             the exit state of <option>postrun</option> is
 456             <emphasis>ignored</emphasis>.
 457           </para>
 458         </listitem>
 459       </varlistentry>
 460       <varlistentry>
 461         <term><option>prerun</option></term>
 462         <listitem>
 463           <para>Optional; string</para>
 464           <para>
 465             If specified, then this command will be ran after a
 466             client has connected to the server (and has been
 467             accepted), but before the server starts serving. If
 468             the command contains the literal string '%s', then
 469             this string will be replaced by the filename of the
 470             file which nbd-server wants to export.
 471           </para>
 472           <para>
 473             This is useful to create export files on the fly, or
 474             to verify that a file can be used for export, to
 475             write something to a log file, or similar.
 476           </para>
 477           <para>
 478             If the command runs with a non-zero exit status,
 479             then nbd-server will assume the export will fail,
 480             and refuse to serve it.
 481           </para>
 482         </listitem>
 483       </varlistentry>
 484       <varlistentry>
 485         <term><option>readonly</option></term>
 486         <listitem>
 487           <para>Optional; boolean.</para>
 488           <para>
 489             Disallow writes to the device. If this option is
 490             specified, <command>nbd-server</command> will issue an
 491             error to any client that tries to write to the device.
 492           </para>
 493           <para>
 494             Use of this option in conjunction with
 495             <option>copyonwrite</option> is possible, but silly.
 496           </para>
 497           <para>Corresponds to the <option>-r</option> option on the
 498           command line.</para>
 499         </listitem>
 500       </varlistentry>
 501       <varlistentry>
 502         <term><option>rotational</option></term>
 503         <listitem>
 504           <para>Optional; boolean.</para>
 505           <para>When this option is enabled,
 506             <command>nbd-server</command> will inform the client that
 507             it would prefer it to send requests in elevator (i.e., optimized) order, perhaps
 508             because it has a backing store and no local elevator. By
 509             default, the client uses QUEUE_FLAG_NONROT, which effectively
 510             restricts the function of the elevator to block merges. By
 511             specifying this flag on the server, the client will not use
 512             QUEUE_FLAG_NONROT, meaning the client elevator will perform
 513             normal elevator ordering of I/O requests. Note that even when
 514             the backing store is on rotating media, it is not normally
 515             necessary to specify this flag, as the server's elevator
 516             algorithm will be used. This flag is only required where
 517             the server will not be using an elevator algorithm or where
 518             the elevator algorithm is effectively neutered (e.g. with
 519             the sync option set). This option will have no effect unless
 520             supported by the client.
 521           </para>
 522         </listitem>
 523       </varlistentry>
 524       <varlistentry>
 525         <term><option>sdp</option></term>
 526         <listitem>
 527           <para>Optional; boolean.</para>
 528           <para>
 529             When this option is enabled, <command>nbd-server</command>
 530             will use the Socket Direct Protocol (SDP) to serve the
 531             export, rather than just IP. This is faster, but requires
 532             special hardware (usually something like InfiniBand) and
 533             support in the kernel.
 534           </para>
 535           <para>
 536             Additionally, support for this option must be enabled at
 537             compile time, using the <option>--enable-sdp</option> option
 538             to the <command>configure</command> script. If this option
 539             is found in a configuration file and
 540             <command>nbd-server</command> does not have support for SDP,
 541             then <command>nbd-server</command> will exit with an error
 542             message.
 543           </para>
 544         </listitem>
 545       </varlistentry>
 546       <varlistentry>
 547         <term><option>sparse_cow</option></term>
 548         <listitem>
 549           <para>Optional; boolean.</para>
 550           <para>
 551             When this option is enabled, <command>nbd-server</command>
 552             will use sparse files to implement the copy-on-write
 553             option; such files take up less space then they appear to,
 554             which allows <command>nbd-server</command> to handle the
 555             file as if it was just as large as the block device it's
 556             for.
 557           </para>
 558           <para>
 559             If this option is disabled, <command>nbd-server</command>
 560             will map every newly written block to the end of the
 561             copy-on-write file, which means that
 562             <command>nbd-server</command> will have to lseek(2) to the
 563             right position after every 4096-byte block.
 564           </para>
 565           <para>
 566             Using this option may be faster when much is being written
 567             during a connection.
 568           </para>
 569         </listitem>
 570       </varlistentry>
 571       <varlistentry>
 572         <term><option>sync</option></term>
 573         <listitem>
 574           <para>Optional; boolean.</para>
 575           <para>When this option is enabled,
 576             <command>nbd-server</command> will call an fsync() after every
 577             write to the backend storage. Calling fsync() increases
 578             reliability in case of an unclean shutdown of nbd-server; but,
 579             depending on the file system used on the nbd-server side, may
 580             degrade performance. The use of this option isn't always
 581             necessary; e.g., on ext3 filesystems, it is recommended that
 582             it is <emphasis>not</emphasis> enabled, since it seriously
 583             reduces performance on ext3 filesystems while not
 584             importantly impacting reliability.
 585           </para>
 586         </listitem>
 587       </varlistentry>
 588       <varlistentry>
 589         <term><option>timeout</option></term>
 590         <listitem>
 591           <para>Optional; integer; default 0</para>
 592           <para>
 593             How many seconds a connection may be idle for this
 594             export. When a connection is idle for a longer time,
 595             <command>nbd-server</command> will forcibly disconnect the
 596             connection. If you specify 0 (the default), then a
 597             connection may be idle forever.
 598           </para>
 599           <para>
 600             Corresponds to the <option>-a</option> option on the
 601             command line
 602           </para>
 603         </listitem>
 604       </varlistentry>
 605       <varlistentry>
 606         <term><option>transactionlog</option></term>
 607         <listitem>
 608           <para>Optional; string</para>
 609           <para>
 610             If specified, then this pathname is used to generate a transaction
 611             log. A transaction log is a binary file consisting of the requests
 612             sent to and the replies received by the server, but excluding any
 613             data (so, for a write command, it records the offset and length
 614             of the write but not the data written). It is therefore relatively
 615             safe to distribute to a third party. Note that the transaction log
 616             does not include the negotiation sequence. Transaction logs are
 617             mainly useful for debugging. The program
 618             <emphasis>nbd-tester-client</emphasis> distributed with the source
 619             to this program can reply a transaction log against a server and
 620             perform a data integrity test. Note that the transaction log is
 621             written to for every client opened. If it is necessary to maintain
 622             separate transaction logs for each client, the
 623             <emphasis>prerun</emphasis> script should rename the transaction log
 624             (which will just have been opened in order to avoid transaction logs
 625             overwriting eachother. This action should be race-free.
 626           </para>
 627         </listitem>
 628       </varlistentry>
 629       <varlistentry>
 630         <term><option>virtstyle</option></term>
 631         <listitem>
 632           <para>Optional; string; default "ipliteral"</para>
 633           <para>
 634             Defines the style of virtualization. Virtualization allows
 635             one to create one export that will serve a different file
 636             depending on the IP address that is connecting. When
 637             virtualization is active, the
 638             <replaceable>exportname</replaceable> parameter needs to
 639             contain the string '%s'; this will then be replaced by the
 640             IP address of the client connecting, in accordance with the
 641             option selected here. The result of this transformation is
 642             then used as the filename to be opened.
 643           </para>
 644           <para>
 645             There are four types of virtualization that
 646             <command>nbd-server</command> supports:
 647           </para>
 648           <variablelist>
 649             <varlistentry>
 650               <term><option>none</option></term>
 651               <listitem>
 652                 <para>
 653                   No virtualization. Will attempt to open the filename
 654                   as it was written, even if it contains '%s' in the
 655                   name.
 656                 </para>
 657               </listitem>
 658             </varlistentry>
 659             <varlistentry>
 660               <term><option>ipliteral</option></term>
 661               <listitem>
 662                 <para>
 663                   The %s is replaced by the IP address of the connecting
 664                   host is used as-is.  For IPv4, this is done in
 665                   dotted-quad notation; for IPv6, in hexadecimal form
 666                   with leading zeros omitted.
 667                 </para>
 668                 <para>
 669                   As an example, if a client connects from 192.168.1.100
 670                   and <option>exportname</option> is specified as
 671                   <filename>/export/%s</filename>, then nbd-server will
 672                   attempt to serve
 673                   <filename>/export/192.168.1.100</filename>. For IPv6,
 674                   with a client connecting from 2001:6f8:32f::39, the
 675                   filename would be
 676                   <filename>/export/2001:6f8:32f:0:0:0:0:39</filename>
 677                 </para>
 678               </listitem>
 679             </varlistentry>
 680             <varlistentry>
 681               <term><option>iphash</option></term>
 682               <listitem>
 683                 <para>
 684                   Same as above, except that
 685                   <command>nbd-server</command> will replace the dots
 686                   in the IP address by forward slashes ('/'); in the
 687                   same example, <command>nbd-server</command> would
 688                   open <filename>/export/192/168/1/100</filename>
 689                   instead.
 690                 </para>
 691                 <para>
 692                   Since there are no dots in most IPv6 addresses, the
 693                   effect of using this option when IPv6 is in use is
 694                   indistinguishable from the ipliteral option. It was
 695                   thought that having to create an eight-deep directory
 696                   structure would not be as useful.
 697                 </para>
 698               </listitem>
 699             </varlistentry>
 700             <varlistentry>
 701               <term><option>cidrhash</option></term>
 702               <listitem>
 703                 <para>
 704                   This option requires one to add a space and a number
 705                   after it. <command>nbd-server</command> will use the
 706                   number as a network mask in CIDR style, and use that
 707                   as a hash cutoff point. In the above example, if
 708                   <option>virtstyle</option> has been specified as
 709                   <constant>cidrhash 16</constant>, then
 710                   <command>nbd-server</command> will try to open
 711                   <filename>/export/192.168.0.0/192.168.1.100</filename>;
 712                   if <option>virtstyle</option> were specified as
 713                   <constant>cidrhash 26</constant>, then
 714                   <command>nbd-server</command> will try to open
 715                   <filename>/export/192.168.1.64/192.168.1.100</filename>.
 716                 </para>
 717                 <para>For IPv6, in the above example, with
 718                 <constant>cidrhash 42</constant>, the filename would
 719                 be
 720                 <filename>/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39</filename>.</para>
 721               </listitem>
 722             </varlistentry>
 723           </variablelist>
 724         </listitem>
 725       </varlistentry>
 726     </variablelist>
 727
 728   </refsect1>
 729   <refsect1>
 730     <title>SEE ALSO</title>
 731
 732     <para>nbd-server (1), nbd-client (8), nbd-trdump (8)</para>
 733
 734
 735   </refsect1>
 736   <refsect1>
 737     <title>AUTHOR</title>
 738     <para>The NBD kernel module and the NBD tools were originally
 739       written by Pavel Machek (pavel@ucw.cz)</para>
 740
 741     <para>The Linux kernel module is now maintained by Paul Clements
 742       (Paul.Clements@steeleye.com), while the userland tools are
 743       maintained by &dhusername; (&dhemail;)</para>
 744
 745     <para>On The Hurd there is a regular translator available to perform the
 746       client side of the protocol, and the use of
 747       <command>nbd-client</command> is not required. Please see the
 748       relevant documentation for more information.</para>
 749
 750     <para>This manual page was written by &dhusername; (&dhemail;) for
 751       the &debian; system (but may be used by others).  Permission is
 752       granted to copy, distribute and/or modify this document under
 753       the terms of the <acronym>GNU</acronym> General Public License,
 754       version 2, as published by the Free Software Foundation.</para>
 755
 756   </refsect1>
 757   <refsect1>
 758     <title>EXAMPLES</title>
 759     <para>A simple <command>nbd-server</command> configuration file
 760       would look like this:</para>
 761     <programlisting>
 762       [generic]
 763       [export]
 764           exportname = /export/blkdev
 765           port = 12345
 766     </programlisting>
 767     <para>For increased security, one might want to create an
 768       authorization file, and set the UID and GID to run as:</para>
 769     <programlisting>
 770       [generic]
 771           user = nbd
 772           group = nbd
 773       [export]
 774           exportname = /export/blkdev
 775           port = 12345
 776           authfile = $sysconfdir/nbd-server/allow
 777     </programlisting>
 778     <para>With $sysconfdir/nbd-server/allow containing the following:</para>
 779     <programlisting>
 780       127.0.0.1
 781       192.168.0.0/8
 782       192.168.1.1
 783     </programlisting>
 784   </refsect1>
 785 </refentry>
 786
 787 <!-- Keep this comment at the end of the file
 788 Local variables:
 789 mode: sgml
 790 sgml-omittag:t
 791 sgml-shorttag:t
 792 sgml-minimize-attributes:nil
 793 sgml-always-quote-attributes:t
 794 sgml-indent-step:2
 795 sgml-indent-data:t
 796 sgml-parent-document:nil
 797 sgml-default-dtd-file:nil
 798 sgml-exposed-tags:nil
 799 sgml-local-catalogs:nil
 800 sgml-local-ecat-files:nil
 801 End:
 802 -->