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