1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
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:
8 manpage.1: manpage.sgml
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">
25 <!ENTITY debian "<productname>Debian GNU/Linux</productname>">
26 <!ENTITY gnu "<acronym>GNU</acronym>">
40 <holder>&dhusername;</holder>
50 <refname>&dhpackage;</refname>
52 <refpurpose>configuration file for nbd-server</refpurpose>
56 <command>&dhpackage; </command>
61 <title>DESCRIPTION</title>
63 <para><command>&dhpackage;</command> allows to configure the
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).
72 The configuration file consists of section header lines, comment
73 lines, and option lines.
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
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.
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).
109 <title>OPTIONS FOR SECTION [generic]</title>
111 <!-- These are in alphabetical order, please keep it that way -->
114 <term><option>group</option></term>
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
131 <term><option>user</option></term>
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.
148 <title>OPTIONS FOR EXPORT SECTIONS</title>
150 <!-- These are in alphabetical order, please keep it that way -->
153 <term><option>authfile</option></term>
156 Optional; string; default
157 <filename>@sysconfdir@/nbd-server/allow</filename>.
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
171 <para>Corresponds to the <option>-l</option> option on the
176 <term><option>autoreadonly</option></term>
178 <para>Optional; boolean.</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.
184 <para>Does not have a corresponding command-line
186 <para>TODO: verify whether this option actually works as
187 documented. I have a feeling I've been terribly
193 <term><option>copyonwrite</option></term>
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.
206 <para>Corresponds to the <option>-c</option> option on the
211 <term><option>exportname</option></term>
213 <para>Required; string.</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
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.
230 <para>When specified on the command line, this should be the
236 <term><option>filesize</option></term>
238 <para>Optional; integer; default autodetected.</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
247 <para>When specified on the command line, this should be the
253 <term>listenaddr</term>
255 <para>Optional; string</para>
256 <para>If this option is set, it should contain the local IP
257 address (in "dotted-quad" notation) on which we should
258 listen to <command>nbd-client</command>(8) connections. If
259 it is not set, 0.0.0.0 is used (i.e., "listen on all local
260 IP addresses")</para>
264 <term><option>multifile</option></term>
266 <para>Optional; boolean.</para>
268 If this option is set to true, then
269 <command>nbd-server</command> will search for files of the
271 <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
272 with <replaceable>exportname</replaceable> being the
273 filename that would otherwise have been used (after
274 name transformation for virtualization, if any, has been
275 performed) and <replaceable>integer</replaceable> an
276 integer number, starting with 0 and ending when no more
280 The size of the individual files will be autodetected,
281 <emphasis>even</emphasis> if the <option>filesize</option>
282 option has been specified. See the documentation for the
283 <option>multifile</option> for details.
286 Corresponds to the <option>-m</option> option on the
292 <term><option>port</option></term>
294 <para>Required; integer.</para>
296 The port on which this export is to be served. Currently
297 it is not possible to export multiple block devices on the
298 same port unless virtualization is used; future versions
299 of <command>nbd-server</command> may add this
303 When specified on the command line, this should be the
309 <term><option>readonly</option></term>
311 <para>Optional; boolean.</para>
313 Disallow writes to the device. If this option is
314 specified, <command>nbd-server</command> will issue an
315 error to any client that tries to write to the device.
318 Use of this option in conjunction with
319 <option>copyonwrite</option> is possible, but silly.
321 <para>Corresponds to the <option>-r</option> option on the
326 <term><option>sdp</option></term>
328 <para>Optional; boolean.</para>
330 When this option is enabled, <command>nbd-server</command>
331 will use the Socket Direct Protocol (SDP) to serve the
332 export, rather than just IP. This is faster, but requires
333 special hardware (usually something like InfiniBand) and
334 support in the kernel.
337 Additionally, support for this option must be enabled at
338 compile time, using the <option>--enable-sdp</option> option
339 to the <command>configure</command> script. If this option
340 is found in a configuration file and
341 <command>nbd-server</command> does not have support for SDP,
342 then <command>nbd-server</command> will exit with an error
347 <term><option>sparse_cow</option></term>
349 <para>Optional; boolean.</para>
351 When this option is enabled, <command>nbd-server</command>
352 will use sparse files to implement the copy-on-write
353 option; such files take up less space then they appear to,
354 which allows <command>nbd-server</command> to handle the
355 file as if it was just as large as the block device it's
359 If this option is disabled, <command>nbd-server</command>
360 will map every newly written block to the end of the
361 copy-on-write file, which means that
362 <command>nbd-server</command> will have to lseek(2) to the
363 right position after every 4096-byte block.
366 Using this option may be faster when much is being written
372 <term><option>timeout</option></term>
374 <para>Optional; integer; default 0</para>
376 How many seconds a connection may be idle for this
377 export. When a connection is idle for a longer time,
378 <command>nbd-server</command> will forcibly disconnect the
379 connection. If you specify 0 (the default), then a
380 connection may be idle forever.
383 Corresponds to the <option>-a</option> option on the
389 <term><option>virtstyle</option></term>
391 <para>Optional; string; default "ipliteral"</para>
393 Defines the style of virtualization. Virtualization allows
394 one to create one export that will serve a different file
395 depending on the IP address that is connecting. When
396 virtualization is There are three types of virtualization
397 that <command>nbd-server</command> supports:
401 <term><option>none</option></term>
404 No virtualization. Will attempt to open the filename
405 as it was written, even if it contains '%s' in the
411 <term><option>ipliteral</option></term>
414 <command>nbd-server</command> will look for the
415 literal string '%s' in the
416 <option>exportname</option>, and replace it by the
417 IP address of the connecting host in dotted-quad
418 notation. The string that results from this
419 transformation will be used as an absolute pathname
420 that <command>nbd-server</command> will attempt to
421 open. As an example, if a client connects from
422 192.168.1.100 and <option>exportname</option> is
423 specified as <filename>/export/%s</filename>, then
424 nbd-server will attempt to serve
425 <filename>/export/192.168.1.100</filename>
430 <term><option>iphash</option></term>
433 Same as above, except that
434 <command>nbd-server</command> will replace the dots
435 in the IP address by forward slashes ('/'); in the
436 same example, <command>nbd-server</command> would
437 open <filename>/export/192/168/1/100</filename>
443 <term><option>cidrhash</option></term>
446 This option requires one to add a space and a number
447 after it. <command>nbd-server</command> will use the
448 number as a network mask in CIDR style, and use that
449 as a hash cutoff point. In the above example, if
450 <option>virtstyle</option> has been specified as
451 <constant>cidrhash 16</constant>, then
452 <command>nbd-server</command> will try to open
453 <filename>/export/192.168.0.0/192.168.1.100</filename>;
454 if <option>virtstyle</option> were specified as
455 <constant>cidrhash 26</constant>, then
456 <command>nbd-server</command> will try to open
457 <filename>/export/192.168.1.64/192.168.1.100</filename>.
465 <term><option>prerun</option></term>
467 <para>Optional; string</para>
469 If specified, then this command will be ran after a
470 client has connected to the server (and has been
471 accepted), but before the server starts serving. If
472 the command contains the literal string '%s', then
473 this string will be replaced by the filename of the
474 file which nbd-server wants to export.
477 This is useful to create export files on the fly, or
478 to verify that a file can be used for export, to
479 write something to a log file, or similar.
482 If the command runs with a non-zero exit status,
483 then nbd-server will assume the export will fail,
484 and refuse to serve it.
489 <term><option>postrun</option></term>
491 <para>Optional; string</para>
493 If specified, then it is assumed to be a command
494 that will be ran when a client has
495 disconnected. This can be useful to clean up
496 whatever <option>prerun</option> has set up, to log
497 something, or similar.
500 If the literal string '%s' is present in the
501 command, it will be replaced by the file name that
502 has just been closed.
505 In contrast to the <option>prerun</option> option,
506 the exit state of <option>postrun</option> is
507 <emphasis>ignored</emphasis>.
515 <title>SEE ALSO</title>
517 <para>nbd-server (1), nbd-client (8),
518 http://nbd.sourceforge.net/roadmap.html</para>
522 <title>AUTHOR</title>
523 <para>The NBD kernel module and the NBD tools were originally
524 written by Pavel Machek (pavel@ucw.cz)</para>
526 <para>The Linux kernel module is now maintained by Paul Clements
527 (Paul.Clements@steeleye.com), while the userland tools are
528 maintained by &dhusername; (&dhemail;)</para>
530 <para>On The Hurd there is a regular translator available to perform the
531 client side of the protocol, and the use of
532 <command>nbd-client</command> is not required. Please see the
533 relevant documentation for more information.</para>
535 <para>This manual page was written by &dhusername; (&dhemail;) for
536 the &debian; system (but may be used by others). Permission is
537 granted to copy, distribute and/or modify this document under
538 the terms of the <acronym>GNU</acronym> General Public License,
539 version 2, as published by the Free Software Foundation.</para>
543 <title>EXAMPLES</title>
544 <para>A simple <command>nbd-server</command> configuration file
545 would look like this:</para>
549 exportname = /export/blkdev
552 <para>For increased security, one might want to create an
553 authorization file, and set the UID and GID to run as:</para>
559 exportname = /export/blkdev
561 authfile = /etc/nbd-server/allow
563 <para>With /etc/nbd-server/allow containing the following:</para>
572 <!-- Keep this comment at the end of the file
577 sgml-minimize-attributes:nil
578 sgml-always-quote-attributes:t
581 sgml-parent-document:nil
582 sgml-default-dtd-file:nil
583 sgml-exposed-tags:nil
584 sgml-local-catalogs:nil
585 sgml-local-ecat-files:nil