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>@SCD@/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>@SCD@/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, and must not
 162             contain wildcards of any kind or empty lines. If the file
 163             does not exist, everyone is allowed to connect. If the
 164             file exists but is empty, nobody is allowed to
 165             connect. Otherwise, <command>nbd-server</command> will
 166             only allow clients to connect whose IP-adres is listed in
 167             this file.
 168           </para>
 169           <para>Corresponds to the <option>-l</option> option on the
 170           command line</para>
 171         </listitem>
 172       </varlistentry>
 173       <varlistentry>
 174         <term><option>autoreadonly</option></term>
 175         <listitem>
 176           <para>Optional; boolean.</para>
 177           <para>
 178             If this option is set to true, then
 179             <command>nbd-server</command> will automatically switch to
 180             readonly if it cannot write to the file.
 181           </para>
 182           <para>Does not have a corresponding command-line
 183             argument</para>
 184           <para>TODO: verify whether this option actually works as
 185             documented. I have a feeling I've been terribly
 186             stupid.
 187           </para>
 188         </listitem>
 189       </varlistentry>
 190       <varlistentry>
 191         <term><option>copyonwrite</option></term>
 192         <listitem>
 193           <para>
 194             Optional; boolean.
 195           </para>
 196           <para>
 197             Whether this is a copy-on-write export. If it is, then any
 198             writes to this export will not be written to the master
 199             file, but to a separate file which will be removed upon
 200             disconnect. The result of using this option is that
 201             nbd-server will be slower, and that any writes will be
 202             lost upon disconnect.
 203           </para>
 204           <para>Corresponds to the <option>-c</option> option on the
 205             command line</para>
 206         </listitem>
 207       </varlistentry>
 208       <varlistentry>
 209         <term><option>exportname</option></term>
 210         <listitem>
 211           <para>Required; string.</para>
 212           <para>
 213             The name of the file that will be exported. This must be a
 214             fully-qualified path and filename; relative paths are not
 215             allowed.
 216           </para>
 217           <para>
 218             Note that <command>nbd-server</command> will only try to
 219             find and open the exported file when a client actually
 220             connects; as a result, <command>nbd-server</command> must
 221             be able to open and read this file
 222             <emphasis>after</emphasis> changing to the user and group
 223             that have been specified by use of the
 224             <option>user</option> and <option>group</option> options;
 225             also, <command>nbd-server</command> will only detect
 226             errors in this option upon connection of a client.
 227           </para>
 228           <para>When specified on the command line, this should be the
 229             second argument.
 230           </para>
 231         </listitem>
 232       </varlistentry>
 233       <varlistentry>
 234         <term><option>filesize</option></term>
 235         <listitem>
 236           <para>Optional; integer; default autodetected.</para>
 237           <para>
 238             Disable autodetection of file or block device size, and
 239             forcibly specify a size. Sizes must be specified in
 240             bytes. If the <option>multifile</option> option is in
 241             effect, this option specifies the size of the
 242             <emphasis>entire</emphasis> export, not of individual
 243             files.
 244           </para>
 245           <para>When specified on the command line, this should be the
 246             third argument.
 247           </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
 261             name 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>sparse_cow</option></term>
 314         <listitem>
 315           <para>Optional; boolean.</para>
 316           <para>
 317             When this option is enabled, <command>nbd-server</command>
 318             will use sparse files to implement the copy-on-write
 319             option; such files take up less space then they appear to,
 320             which allows <command>nbd-server</command> to handle the
 321             file as if it was just as large as the block device it's for.
 322           </para>
 323           <para>
 324             If this option is disabled, <command>nbd-server</command>
 325             will map every newly written block to the end of the
 326             copy-on-write file, which means that
 327             <command>nbd-server</command> will have to lseek(2) to the
 328             right position after every 4096-byte block.
 329           </para>
 330           <para>
 331             Using this option may be faster when much is being written
 332             during a connection.
 333           </para>
 334         </listitem>
 335       </varlistentry>
 336       <varlistentry>
 337         <term><option>timeout</option></term>
 338         <listitem>
 339           <para>Optional; integer; default 0</para>
 340           <para>
 341             How many seconds a connection may be idle for this
 342             export. When a connection is idle for a longer time,
 343             <command>nbd-server</command> will forcibly disconnect the
 344             connection. If you specify 0 (the default), then a
 345             connection may be idle forever.
 346           </para>
 347           <para>
 348             Corresponds to the <option>-a</option> option on the
 349             command line
 350           </para>
 351         </listitem>
 352       </varlistentry>
 353       <varlistentry>
 354         <term><option>virtstyle</option></term>
 355         <listitem>
 356           <para>Optional; string; default "ipliteral"</para>
 357           <para>
 358             Defines the style of virtualization. Virtualization allows
 359             one to create one export that will serve a different file
 360             depending on the IP address that is connecting. When
 361             virtualization is There are three types of virtualization
 362             that <command>nbd-server</command> supports:
 363           </para>
 364           <variablelist>
 365             <varlistentry>
 366               <term><option>ipliteral</option></term>
 367               <listitem>
 368                 <para>
 369                   <command>nbd-server</command> will look for the
 370                   literal string '%s' in the
 371                   <option>exportname</option>, and replace it by the
 372                   IP address of the connecting host in dotted-quad
 373                   notation. The string that results from this
 374                   transformation will be used as an absolute pathname
 375                   that <command>nbd-server</command> will attempt to
 376                   open. As an example, if a client connects from
 377                   192.168.1.100 and <option>exportname</option> is
 378                   specified as <filename>/export/%s</filename>, then
 379                   nbd-server will attempt to serve
 380                   <filename>/export/192.168.1.100</filename>
 381                 </para>
 382               </listitem>
 383             </varlistentry>
 384             <varlistentry>
 385               <term><option>iphash</option></term>
 386               <listitem>
 387                 <para>
 388                   Same as above, except that
 389                   <command>nbd-server</command> will replace the dots
 390                   in the IP address by forward slashes ('/'); in the
 391                   same example, <command>nbd-server</command> would
 392                   open <filename>/export/192/168/1/100</filename>
 393                   instead.
 394                 </para>
 395               </listitem>
 396             </varlistentry>
 397             <varlistentry>
 398               <term><option>cidrhash</option></term>
 399               <listitem>
 400                 <para>
 401                   This option requires one to add a space and a number
 402                   after it. <command>nbd-server</command> will use the
 403                   number as a network mask in CIDR style, and use that
 404                   as a hash cutoff point. In the above example, if
 405                   <option>virtstyle</option> has been specified
 406                   as <constant>cidrhash 16</constant>, then
 407                   <command>nbd-server</command> will try to open
 408                   <filename>/export/192.168.0.0/192.168.1.100</filename>; if
 409                   <option>virtstyle</option> were specified as
 410                   <constant>cidrhash 26</constant>, then
 411                   <command>nbd-server</command> will try to open
 412                   <filename>/export/192.168.1.64/192.168.1.100</filename>.
 413                 </para>
 414               </listitem>
 415             </varlistentry>
 416           </variablelist>
 417         </listitem>
 418       </varlistentry>
 419     </variablelist>
 420
 421   </refsect1>
 422   <refsect1>
 423     <title>EXAMPLES</title>
 424     <para>Some examples of nbd-server usage:</para>
 425     <itemizedlist mark="none">
 426       <listitem>
 427         <para>To export a file /export/nbd/exp-bl-dev on port 2000:</para>
 428         <para><command>nbd-server 2000 /export/nbd/exp-bl-dev</command></para>
 429       </listitem>
 430       <listitem>
 431         <para>To export a the same file read-only:</para>
 432         <para><command>nbd-server 2000 /export/nbd/exp-bl-dev -r</command></para>
 433       </listitem>
 434       <listitem>
 435         <para>To export the same file read-write, but make sure
 436           changes are lost after restarting the client or the
 437           server:</para>
 438         <para><command>nbd-server 2000 /export/nbd/exp-bl-dev
 439           -c</command></para>
 440       </listitem>
 441     </itemizedlist>
 442   </refsect1>
 443   <refsect1>
 444     <title>SEE ALSO</title>
 445
 446     <para>nbd-server (1), nbd-client (8),
 447       http://nbd.sourceforge.net/roadmap.html</para>
 448
 449   </refsect1>
 450   <refsect1>
 451     <title>AUTHOR</title>
 452     <para>The NBD kernel module and the NBD tools were originally
 453       written by Pavel Machek (pavel@ucw.cz)</para>
 454
 455     <para>The Linux kernel module is now maintained by Paul Clements
 456       (Paul.Clements@steeleye.com), while the userland tools are
 457       maintained by &dhusername; (&dhemail;)</para>
 458
 459     <para>On The Hurd there is a regular translator available to perform the
 460       client side of the protocol, and the use of
 461       <command>nbd-client</command> is not required. Please see the
 462       relevant documentation for more information.</para>
 463
 464     <para>This manual page was written by &dhusername; (&dhemail;) for
 465       the &debian; system (but may be used by others).  Permission is
 466       granted to copy, distribute and/or modify this document under
 467       the terms of the <acronym>GNU</acronym> General Public License,
 468       version 2, as published by the Free Software Foundation.</para>
 469
 470   </refsect1>
 471 </refentry>
 472
 473 <!-- Keep this comment at the end of the file
 474 Local variables:
 475 mode: sgml
 476 sgml-omittag:t
 477 sgml-shorttag:t
 478 sgml-minimize-attributes:nil
 479 sgml-always-quote-attributes:t
 480 sgml-indent-step:2
 481 sgml-indent-data:t
 482 sgml-parent-document:nil
 483 sgml-default-dtd-file:nil
 484 sgml-exposed-tags:nil
 485 sgml-local-catalogs:nil
 486 sgml-local-ecat-files:nil
 487 End:
 488 -->