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