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