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