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>user</option></term>
 131         <listitem>
 132           <para>
 133             Optional; string.
 134           </para>
 135           <para>
 136             The name of the user this server must run as. If this
 137             parameter is not specified, then nbd-server will not
 138             attempt to change its UID (so the UID it runs as will be
 139             the user who starts nbd-server). If it is specified, then
 140             nbd-server will change its UID after opening ports, but
 141             before accepting connections or opening files.
 142           </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>listenaddr</option></term>
 185         <listitem>
 186           <para>
 187             Optional; string
 188           </para>
 189           <para>If this option is set, it should contain the local IP
 190           address on which we should listen to
 191           <command>nbd-client</command>(8) connections. If it is not
 192             set, <command>nbd-server</command> will listen to all
 193           local IPv4 and IPv6 addresses. To limit to IPv6, specify the
 194           address as "::". To limit to IPv4, specify as "0.0.0.0". It
 195           is not possible to specify more than one IP address
 196           here.</para>
 197         </listitem>
 198       </varlistentry
 199     </variablelist>
 200   </refsect1>
 201   <refsect1>
 202     <title>OPTIONS FOR EXPORT SECTIONS</title>
 203
 204     <!-- These are in alphabetical order, please keep it that way -->
 205     <variablelist>
 206       <varlistentry>
 207         <term><option>authfile</option></term>
 208         <listitem>
 209           <para>
 210             Optional; string; default
 211             <filename>$sysconfdir/nbd-server/allow</filename>.
 212           </para>
 213           <para>
 214             The name of the authorization file for this export. This
 215             file should contain one line per IP-address, or per
 216             network (which must be specified in CIDR-style
 217             <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>)
 218             and must not contain empty lines. If the file
 219             does not exist, everyone is allowed to connect. If the
 220             file exists but is empty, nobody is allowed to
 221             connect. Otherwise, <command>nbd-server</command> will
 222             only allow clients to connect whose IP-adres is listed in
 223             this file.
 224           </para>
 225           <para>Corresponds to the <option>-l</option> option on the
 226           command line</para>
 227         </listitem>
 228       </varlistentry>
 229       <varlistentry>
 230         <term><option>copyonwrite</option></term>
 231         <listitem>
 232           <para>
 233             Optional; boolean.
 234           </para>
 235           <para>
 236             Whether this is a copy-on-write export. If it is, then any
 237             writes to this export will not be written to the master
 238             file, but to a separate file which will be removed upon
 239             disconnect. The result of using this option is that
 240             nbd-server will be somewhat slower, and that any writes will
 241             be lost upon disconnect.
 242           </para>
 243           <para>Corresponds to the <option>-c</option> option on the
 244             command line</para>
 245         </listitem>
 246       </varlistentry>
 247       <varlistentry>
 248         <term><option>exportname</option></term>
 249         <listitem>
 250           <para>Required; string.</para>
 251           <para>
 252             The name of the file (or block device) that will be
 253             exported. This must be a fully-qualified path and filename;
 254             relative paths are not allowed.
 255           </para>
 256           <para>
 257             Note that <command>nbd-server</command> will only try to
 258             find and open the exported file when a client actually
 259             connects; as a result, <command>nbd-server</command> must
 260             be able to open and read this file
 261             <emphasis>after</emphasis> changing to the user and group
 262             that have been specified by use of the
 263             <option>user</option> and <option>group</option> options;
 264             also, <command>nbd-server</command> will only detect
 265             errors in this option upon connection of a client.
 266           </para>
 267           <para>When specified on the command line, this should be the
 268             second argument.
 269           </para>
 270         </listitem>
 271       </varlistentry>
 272       <varlistentry>
 273         <term><option>filesize</option></term>
 274         <listitem>
 275           <para>Optional; integer; default autodetected.</para>
 276           <para>
 277             Disable autodetection of file or block device size, and
 278             forcibly specify a size. Sizes must be specified in
 279             bytes. If the <option>multifile</option> option is in
 280             effect, this option specifies the size of the
 281             <emphasis>entire</emphasis> export, not of individual
 282             files.
 283           </para>
 284           <para>When specified on the command line, this should be the
 285             third argument.
 286           </para>
 287         </listitem>
 288       </varlistentry>
 289       <varlistentry>
 290         <term>listenaddr</term>
 291         <listitem>
 292           <para>
 293             Optional; string
 294           </para>
 295           <para>
 296             If the 'oldstyle' global parameter is specified, works
 297             similarly to the global listenaddr parameter, but for the
 298             individual port of this particular export. If the 'oldstyle'
 299             parameter is not set, this parameter is ignored.
 300           </para>
 301         </listitem>
 302       </varlistentry>
 303       <varlistentry>
 304         <term><option>multifile</option></term>
 305         <listitem>
 306           <para>Optional; boolean.</para>
 307           <para>
 308             If this option is set to true, then
 309             <command>nbd-server</command> will search for files of the
 310             form
 311             <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
 312             with <replaceable>exportname</replaceable> being the
 313             filename that would otherwise have been used (after name
 314             transformation for virtualization, if any, has been
 315             performed) and <replaceable>integer</replaceable> an
 316             integer number, starting with 0 and ending when no more
 317             files can be found.
 318           </para>
 319           <para>
 320             The size of the individual files will be autodetected,
 321             <emphasis>even</emphasis> if the <option>filesize</option>
 322             option has been specified.
 323           </para>
 324           <para>
 325             Corresponds to the <option>-m</option> option on the
 326             command line.
 327           </para>
 328         </listitem>
 329       </varlistentry>
 330       <varlistentry>
 331         <term><option>port</option></term>
 332         <listitem>
 333           <para>Required if 'oldstyle' global parameter is set; integer.</para>
 334           <para>
 335             The port on which this export is to be served using the
 336             old-style handshake protocol.
 337           </para>
 338           <para>
 339             This parameter only makes sense when the 'oldstyle'
 340             parameter is set to true in the 'generic' section. If that
 341             parameter is not set, but this parameter is found in an
 342             export section, then nbd-server will issue a warning upon
 343             startup but should otherwise continue to function correctly.
 344           </para>
 345           <para>
 346             It is not possible to combine multiple exports on the same
 347             port using the old style handshake. Please use the new style
 348             handshake for that purpose.
 349           </para>
 350           <para>
 351             When specified on the command line, this should be the
 352             first argument.
 353           </para>
 354         </listitem>
 355       </varlistentry>
 356       <varlistentry>
 357         <term><option>readonly</option></term>
 358         <listitem>
 359           <para>Optional; boolean.</para>
 360           <para>
 361             Disallow writes to the device. If this option is
 362             specified, <command>nbd-server</command> will issue an
 363             error to any client that tries to write to the device.
 364           </para>
 365           <para>
 366             Use of this option in conjunction with
 367             <option>copyonwrite</option> is possible, but silly.
 368           </para>
 369           <para>Corresponds to the <option>-r</option> option on the
 370           command line.</para>
 371         </listitem>
 372       </varlistentry>
 373       <varlistentry>
 374         <term><option>sdp</option></term>
 375         <listitem>
 376           <para>Optional; boolean.</para>
 377           <para>
 378             When this option is enabled, <command>nbd-server</command>
 379             will use the Socket Direct Protocol (SDP) to serve the
 380             export, rather than just IP. This is faster, but requires
 381             special hardware (usually something like InfiniBand) and
 382             support in the kernel.
 383           </para>
 384           <para>
 385             Additionally, support for this option must be enabled at
 386             compile time, using the <option>--enable-sdp</option> option
 387             to the <command>configure</command> script. If this option
 388             is found in a configuration file and
 389             <command>nbd-server</command> does not have support for SDP,
 390             then <command>nbd-server</command> will exit with an error
 391             message.
 392           </para>
 393         </listitem>
 394       </varlistentry>
 395       <varlistentry>
 396         <term><option>sync</option></term>
 397         <listitem>
 398           <para>Optional; boolean.</para>
 399           <para>When this option is enabled,
 400             <command>nbd-server</command> will call an fsync() after every
 401             write to the backend storage. Calling fsync() increases
 402             reliability in case of an unclean shutdown of nbd-server; but,
 403             depending on the file system used on the nbd-server side, may
 404             degrade performance. The use of this option isn't always
 405             necessary; e.g., on ext3 filesystems, it is recommended that
 406             it is <emphasis>not</emphasis> enabled, since it seriously
 407             reduces performance on ext3 filesystems while not
 408             importantly impacting reliability.
 409           </para>
 410         </listitem>
 411       </varlistentry>
 412       <varlistentry>
 413         <term><option>sparse_cow</option></term>
 414         <listitem>
 415           <para>Optional; boolean.</para>
 416           <para>
 417             When this option is enabled, <command>nbd-server</command>
 418             will use sparse files to implement the copy-on-write
 419             option; such files take up less space then they appear to,
 420             which allows <command>nbd-server</command> to handle the
 421             file as if it was just as large as the block device it's
 422             for.
 423           </para>
 424           <para>
 425             If this option is disabled, <command>nbd-server</command>
 426             will map every newly written block to the end of the
 427             copy-on-write file, which means that
 428             <command>nbd-server</command> will have to lseek(2) to the
 429             right position after every 4096-byte block.
 430           </para>
 431           <para>
 432             Using this option may be faster when much is being written
 433             during a connection.
 434           </para>
 435         </listitem>
 436       </varlistentry>
 437       <varlistentry>
 438         <term><option>timeout</option></term>
 439         <listitem>
 440           <para>Optional; integer; default 0</para>
 441           <para>
 442             How many seconds a connection may be idle for this
 443             export. When a connection is idle for a longer time,
 444             <command>nbd-server</command> will forcibly disconnect the
 445             connection. If you specify 0 (the default), then a
 446             connection may be idle forever.
 447           </para>
 448           <para>
 449             Corresponds to the <option>-a</option> option on the
 450             command line
 451           </para>
 452         </listitem>
 453       </varlistentry>
 454       <varlistentry>
 455         <term><option>virtstyle</option></term>
 456         <listitem>
 457           <para>Optional; string; default "ipliteral"</para>
 458           <para>
 459             Defines the style of virtualization. Virtualization allows
 460             one to create one export that will serve a different file
 461             depending on the IP address that is connecting. When
 462             virtualization is active, the
 463             <replaceable>exportname</replaceable> parameter needs to
 464             contain the string '%s'; this will then be replaced by the
 465             IP address of the client connecting, in accordance with the
 466             option selected here. The result of this transformation is
 467             then used as the filename to be opened.
 468           </para>
 469           <para>
 470             There are four types of virtualization that
 471             <command>nbd-server</command> supports:
 472           </para>
 473           <variablelist>
 474             <varlistentry>
 475               <term><option>none</option></term>
 476               <listitem>
 477                 <para>
 478                   No virtualization. Will attempt to open the filename
 479                   as it was written, even if it contains '%s' in the
 480                   name.
 481                 </para>
 482               </listitem>
 483             </varlistentry>
 484             <varlistentry>
 485               <term><option>ipliteral</option></term>
 486               <listitem>
 487                 <para>
 488                   The %s is replaced by the IP address of the connecting
 489                   host is used as-is.  For IPv4, this is done in
 490                   dotted-quad notation; for IPv6, in hexadecimal form
 491                   with leading zeros omitted.
 492                 </para>
 493                 <para>
 494                   As an example, if a client connects from 192.168.1.100
 495                   and <option>exportname</option> is specified as
 496                   <filename>/export/%s</filename>, then nbd-server will
 497                   attempt to serve
 498                   <filename>/export/192.168.1.100</filename>. For IPv6,
 499                   with a client connecting from 2001:6f8:32f::39, the
 500                   filename would be
 501                   <filename>/export/2001:6f8:32f:0:0:0:0:39</filename>
 502                 </para>
 503               </listitem>
 504             </varlistentry>
 505             <varlistentry>
 506               <term><option>iphash</option></term>
 507               <listitem>
 508                 <para>
 509                   Same as above, except that
 510                   <command>nbd-server</command> will replace the dots
 511                   in the IP address by forward slashes ('/'); in the
 512                   same example, <command>nbd-server</command> would
 513                   open <filename>/export/192/168/1/100</filename>
 514                   instead.
 515                 </para>
 516                 <para>
 517                   Since there are no dots in most IPv6 addresses, the
 518                   effect of using this option when IPv6 is in use is
 519                   indistinguishable from the ipliteral option. It was
 520                   thought that having to create an eight-deep directory
 521                   structure would not be as useful.
 522                 </para>
 523               </listitem>
 524             </varlistentry>
 525             <varlistentry>
 526               <term><option>cidrhash</option></term>
 527               <listitem>
 528                 <para>
 529                   This option requires one to add a space and a number
 530                   after it. <command>nbd-server</command> will use the
 531                   number as a network mask in CIDR style, and use that
 532                   as a hash cutoff point. In the above example, if
 533                   <option>virtstyle</option> has been specified as
 534                   <constant>cidrhash 16</constant>, then
 535                   <command>nbd-server</command> will try to open
 536                   <filename>/export/192.168.0.0/192.168.1.100</filename>;
 537                   if <option>virtstyle</option> were specified as
 538                   <constant>cidrhash 26</constant>, then
 539                   <command>nbd-server</command> will try to open
 540                   <filename>/export/192.168.1.64/192.168.1.100</filename>.
 541                 </para>
 542                 <para>For IPv6, in the above example, with
 543                 <constant>cidrhash 42</constant>, the filename would
 544                 be
 545                 <filename>/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39</filename>.</para>
 546               </listitem>
 547             </varlistentry>
 548           </variablelist>
 549         </listitem>
 550       </varlistentry>
 551       <varlistentry>
 552         <term><option>prerun</option></term>
 553         <listitem>
 554           <para>Optional; string</para>
 555           <para>
 556             If specified, then this command will be ran after a
 557             client has connected to the server (and has been
 558             accepted), but before the server starts serving. If
 559             the command contains the literal string '%s', then
 560             this string will be replaced by the filename of the
 561             file which nbd-server wants to export.
 562           </para>
 563           <para>
 564             This is useful to create export files on the fly, or
 565             to verify that a file can be used for export, to
 566             write something to a log file, or similar.
 567           </para>
 568           <para>
 569             If the command runs with a non-zero exit status,
 570             then nbd-server will assume the export will fail,
 571             and refuse to serve it.
 572           </para>
 573         </listitem>
 574       </varlistentry>
 575       <varlistentry>
 576         <term><option>postrun</option></term>
 577         <listitem>
 578           <para>Optional; string</para>
 579           <para>
 580             If specified, then it is assumed to be a command
 581             that will be ran when a client has
 582             disconnected. This can be useful to clean up
 583             whatever <option>prerun</option> has set up, to log
 584             something, or similar.
 585           </para>
 586           <para>
 587             If the literal string '%s' is present in the
 588             command, it will be replaced by the file name that
 589             has just been closed.
 590           </para>
 591           <para>
 592             In contrast to the <option>prerun</option> option,
 593             the exit state of <option>postrun</option> is
 594             <emphasis>ignored</emphasis>.
 595           </para>
 596         </listitem>
 597       </varlistentry>
 598       <varlistentry>
 599         <term><option>maxconnections</option></term>
 600         <listitem>
 601           <para>Optional; integer</para>
 602           <para>
 603             If specified, then it limits the number of opened connections for
 604             this export.
 605           </para>
 606         </listitem>
 607       </varlistentry>
 608     </variablelist>
 609
 610   </refsect1>
 611   <refsect1>
 612     <title>SEE ALSO</title>
 613
 614     <para>nbd-server (1), nbd-client (8)</para>
 615
 616
 617   </refsect1>
 618   <refsect1>
 619     <title>AUTHOR</title>
 620     <para>The NBD kernel module and the NBD tools were originally
 621       written by Pavel Machek (pavel@ucw.cz)</para>
 622
 623     <para>The Linux kernel module is now maintained by Paul Clements
 624       (Paul.Clements@steeleye.com), while the userland tools are
 625       maintained by &dhusername; (&dhemail;)</para>
 626
 627     <para>On The Hurd there is a regular translator available to perform the
 628       client side of the protocol, and the use of
 629       <command>nbd-client</command> is not required. Please see the
 630       relevant documentation for more information.</para>
 631
 632     <para>This manual page was written by &dhusername; (&dhemail;) for
 633       the &debian; system (but may be used by others).  Permission is
 634       granted to copy, distribute and/or modify this document under
 635       the terms of the <acronym>GNU</acronym> General Public License,
 636       version 2, as published by the Free Software Foundation.</para>
 637
 638   </refsect1>
 639   <refsect1>
 640     <title>EXAMPLES</title>
 641     <para>A simple <command>nbd-server</command> configuration file
 642       would look like this:</para>
 643     <programlisting>
 644       [generic]
 645       [export]
 646           exportname = /export/blkdev
 647           port = 12345
 648     </programlisting>
 649     <para>For increased security, one might want to create an
 650       authorization file, and set the UID and GID to run as:</para>
 651     <programlisting>
 652       [generic]
 653           user = nbd
 654           group = nbd
 655       [export]
 656           exportname = /export/blkdev
 657           port = 12345
 658           authfile = $sysconfdir/nbd-server/allow
 659     </programlisting>
 660     <para>With $sysconfdir/nbd-server/allow containing the following:</para>
 661     <programlisting>
 662       127.0.0.1
 663       192.168.0.0/8
 664       192.168.1.1
 665     </programlisting>
 666   </refsect1>
 667 </refentry>
 668
 669 <!-- Keep this comment at the end of the file
 670 Local variables:
 671 mode: sgml
 672 sgml-omittag:t
 673 sgml-shorttag:t
 674 sgml-minimize-attributes:nil
 675 sgml-always-quote-attributes:t
 676 sgml-indent-step:2
 677 sgml-indent-data:t
 678 sgml-parent-document:nil
 679 sgml-default-dtd-file:nil
 680 sgml-exposed-tags:nil
 681 sgml-local-catalogs:nil
 682 sgml-local-ecat-files:nil
 683 End:
 684 -->