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