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 "@sysconfdir@/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. The section name is used as the name
87 for the export in case the client connects with a name rather than
88 a port to specify an export, and must therefore be unique.
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.
147 <term><option>oldstyle</option></term>
153 If this option is set to true, nbd-server will export all
154 exports on a separate port with the old (pre-2.9.17)
155 handshake protocol. In that case, the 'port' option for
156 individual exports is mandatory.
159 If the option is set to false, the 'port' option for
160 individual exports is optional (and will be ignored if
161 specified). The server will only export devices on the
165 For upgrades from pre-2.9.17 versions of nbd, it may be
166 appropriate to enable the oldstyle parameter until all
167 clients have been converted to using name-based exports.
170 Note that exports specified on the command line will
171 always use the old handshake protocol and will not allow
175 Also note that even if this parameter is set to true, all
176 exports will also be made available using the new handshake
177 protocol; it is not possible to switch that off. The reason
178 for this is that the old style protocol will eventually be
179 deprecated, and this option is only available to allow for
185 <term><option>listenaddr</option></term>
190 <para>If this option is set, it should contain the local IP
191 address on which we should listen to
192 <command>nbd-client</command>(8) connections. If it is not
193 set, <command>nbd-server</command> will listen to all
194 local IPv4 and IPv6 addresses. To limit to IPv6, specify the
195 address as "::". To limit to IPv4, specify as "0.0.0.0". It
196 is not possible to specify more than one IP address
203 <title>OPTIONS FOR EXPORT SECTIONS</title>
205 <!-- These are in alphabetical order, please keep it that way -->
208 <term><option>authfile</option></term>
211 Optional; string; default
212 <filename>@sysconfdir@/nbd-server/allow</filename>.
215 The name of the authorization file for this export. This
216 file should contain one line per IP-address, or per
217 network (which must be specified in CIDR-style
218 <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>)
219 and must not contain empty lines. If the file
220 does not exist, everyone is allowed to connect. If the
221 file exists but is empty, nobody is allowed to
222 connect. Otherwise, <command>nbd-server</command> will
223 only allow clients to connect whose IP-adres is listed in
226 <para>Corresponds to the <option>-l</option> option on the
231 <term><option>copyonwrite</option></term>
237 Whether this is a copy-on-write export. If it is, then any
238 writes to this export will not be written to the master
239 file, but to a separate file which will be removed upon
240 disconnect. The result of using this option is that
241 nbd-server will be somewhat slower, and that any writes will
242 be lost upon disconnect.
244 <para>Corresponds to the <option>-c</option> option on the
249 <term><option>exportname</option></term>
251 <para>Required; string.</para>
253 The name of the file (or block device) that will be
254 exported. This must be a fully-qualified path and filename;
255 relative paths are not allowed.
258 Note that <command>nbd-server</command> will only try to
259 find and open the exported file when a client actually
260 connects; as a result, <command>nbd-server</command> must
261 be able to open and read this file
262 <emphasis>after</emphasis> changing to the user and group
263 that have been specified by use of the
264 <option>user</option> and <option>group</option> options;
265 also, <command>nbd-server</command> will only detect
266 errors in this option upon connection of a client.
268 <para>When specified on the command line, this should be the
274 <term><option>filesize</option></term>
276 <para>Optional; integer; default autodetected.</para>
278 Disable autodetection of file or block device size, and
279 forcibly specify a size. Sizes must be specified in
280 bytes. If the <option>multifile</option> option is in
281 effect, this option specifies the size of the
282 <emphasis>entire</emphasis> export, not of individual
285 <para>When specified on the command line, this should be the
291 <term>listenaddr</term>
297 If the 'oldstyle' global parameter is specified, works
298 similarly to the global listenaddr parameter, but for the
299 individual port of this particular export. If the 'oldstyle'
300 parameter is not set, this parameter is ignored.
305 <term><option>multifile</option></term>
307 <para>Optional; boolean.</para>
309 If this option is set to true, then
310 <command>nbd-server</command> will search for files of the
312 <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
313 with <replaceable>exportname</replaceable> being the
314 filename that would otherwise have been used (after name
315 transformation for virtualization, if any, has been
316 performed) and <replaceable>integer</replaceable> an
317 integer number, starting with 0 and ending when no more
321 The size of the individual files will be autodetected,
322 <emphasis>even</emphasis> if the <option>filesize</option>
323 option has been specified.
326 Corresponds to the <option>-m</option> option on the
332 <term><option>port</option></term>
334 <para>Required if 'oldstyle' global parameter is set; integer.</para>
336 The port on which this export is to be served using the
337 old-style handshake protocol.
340 This parameter only makes sense when the 'oldstyle'
341 parameter is set to true in the 'generic' section. If that
342 parameter is not set, but this parameter is found in an
343 export section, then nbd-server will issue a warning upon
344 startup but should otherwise continue to function correctly.
347 It is not possible to combine multiple exports on the same
348 port using the old style handshake. Please use the new style
349 handshake for that purpose.
352 When specified on the command line, this should be the
358 <term><option>readonly</option></term>
360 <para>Optional; boolean.</para>
362 Disallow writes to the device. If this option is
363 specified, <command>nbd-server</command> will issue an
364 error to any client that tries to write to the device.
367 Use of this option in conjunction with
368 <option>copyonwrite</option> is possible, but silly.
370 <para>Corresponds to the <option>-r</option> option on the
375 <term><option>sdp</option></term>
377 <para>Optional; boolean.</para>
379 When this option is enabled, <command>nbd-server</command>
380 will use the Socket Direct Protocol (SDP) to serve the
381 export, rather than just IP. This is faster, but requires
382 special hardware (usually something like InfiniBand) and
383 support in the kernel.
386 Additionally, support for this option must be enabled at
387 compile time, using the <option>--enable-sdp</option> option
388 to the <command>configure</command> script. If this option
389 is found in a configuration file and
390 <command>nbd-server</command> does not have support for SDP,
391 then <command>nbd-server</command> will exit with an error
397 <term><option>sync</option></term>
399 <para>Optional; boolean.</para>
400 <para>When this option is enabled,
401 <command>nbd-server</command> will call an fsync() after every
402 write to the backend storage. Calling fsync() increases
403 reliability in case of an unclean shutdown of nbd-server; but,
404 depending on the file system used on the nbd-server side, may
405 degrade performance. The use of this option isn't always
406 necessary; e.g., on ext3 filesystems, it is recommended that
407 it is <emphasis>not</emphasis> enabled, since it seriously
408 reduces performance on ext3 filesystems while not
409 importantly impacting reliability.
414 <term><option>sparse_cow</option></term>
416 <para>Optional; boolean.</para>
418 When this option is enabled, <command>nbd-server</command>
419 will use sparse files to implement the copy-on-write
420 option; such files take up less space then they appear to,
421 which allows <command>nbd-server</command> to handle the
422 file as if it was just as large as the block device it's
426 If this option is disabled, <command>nbd-server</command>
427 will map every newly written block to the end of the
428 copy-on-write file, which means that
429 <command>nbd-server</command> will have to lseek(2) to the
430 right position after every 4096-byte block.
433 Using this option may be faster when much is being written
439 <term><option>timeout</option></term>
441 <para>Optional; integer; default 0</para>
443 How many seconds a connection may be idle for this
444 export. When a connection is idle for a longer time,
445 <command>nbd-server</command> will forcibly disconnect the
446 connection. If you specify 0 (the default), then a
447 connection may be idle forever.
450 Corresponds to the <option>-a</option> option on the
456 <term><option>virtstyle</option></term>
458 <para>Optional; string; default "ipliteral"</para>
460 Defines the style of virtualization. Virtualization allows
461 one to create one export that will serve a different file
462 depending on the IP address that is connecting. When
463 virtualization is active, the
464 <replaceable>exportname</replaceable> parameter needs to
465 contain the string '%s'; this will then be replaced by the
466 IP address of the client connecting, in accordance with the
467 option selected here. The result of this transformation is
468 then used as the filename to be opened.
471 There are four types of virtualization that
472 <command>nbd-server</command> supports:
476 <term><option>none</option></term>
479 No virtualization. Will attempt to open the filename
480 as it was written, even if it contains '%s' in the
486 <term><option>ipliteral</option></term>
489 The %s is replaced by the IP address of the connecting
490 host is used as-is. For IPv4, this is done in
491 dotted-quad notation; for IPv6, in hexadecimal form
492 with leading zeros omitted.
495 As an example, if a client connects from 192.168.1.100
496 and <option>exportname</option> is specified as
497 <filename>/export/%s</filename>, then nbd-server will
499 <filename>/export/192.168.1.100</filename>. For IPv6,
500 with a client connecting from 2001:6f8:32f::39, the
502 <filename>/export/2001:6f8:32f:0:0:0:0:39</filename>
507 <term><option>iphash</option></term>
510 Same as above, except that
511 <command>nbd-server</command> will replace the dots
512 in the IP address by forward slashes ('/'); in the
513 same example, <command>nbd-server</command> would
514 open <filename>/export/192/168/1/100</filename>
518 Since there are no dots in most IPv6 addresses, the
519 effect of using this option when IPv6 is in use is
520 indistinguishable from the ipliteral option. It was
521 thought that having to create an eight-deep directory
522 structure would not be as useful.
527 <term><option>cidrhash</option></term>
530 This option requires one to add a space and a number
531 after it. <command>nbd-server</command> will use the
532 number as a network mask in CIDR style, and use that
533 as a hash cutoff point. In the above example, if
534 <option>virtstyle</option> has been specified as
535 <constant>cidrhash 16</constant>, then
536 <command>nbd-server</command> will try to open
537 <filename>/export/192.168.0.0/192.168.1.100</filename>;
538 if <option>virtstyle</option> were specified as
539 <constant>cidrhash 26</constant>, then
540 <command>nbd-server</command> will try to open
541 <filename>/export/192.168.1.64/192.168.1.100</filename>.
543 <para>For IPv6, in the above example, with
544 <constant>cidrhash 42</constant>, the filename would
546 <filename>/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39</filename>.</para>
553 <term><option>prerun</option></term>
555 <para>Optional; string</para>
557 If specified, then this command will be ran after a
558 client has connected to the server (and has been
559 accepted), but before the server starts serving. If
560 the command contains the literal string '%s', then
561 this string will be replaced by the filename of the
562 file which nbd-server wants to export.
565 This is useful to create export files on the fly, or
566 to verify that a file can be used for export, to
567 write something to a log file, or similar.
570 If the command runs with a non-zero exit status,
571 then nbd-server will assume the export will fail,
572 and refuse to serve it.
577 <term><option>postrun</option></term>
579 <para>Optional; string</para>
581 If specified, then it is assumed to be a command
582 that will be ran when a client has
583 disconnected. This can be useful to clean up
584 whatever <option>prerun</option> has set up, to log
585 something, or similar.
588 If the literal string '%s' is present in the
589 command, it will be replaced by the file name that
590 has just been closed.
593 In contrast to the <option>prerun</option> option,
594 the exit state of <option>postrun</option> is
595 <emphasis>ignored</emphasis>.
600 <term><option>maxconnections</option></term>
602 <para>Optional; integer</para>
604 If specified, then it limits the number of opened connections for
613 <title>SEE ALSO</title>
615 <para>nbd-server (1), nbd-client (8)</para>
620 <title>AUTHOR</title>
621 <para>The NBD kernel module and the NBD tools were originally
622 written by Pavel Machek (pavel@ucw.cz)</para>
624 <para>The Linux kernel module is now maintained by Paul Clements
625 (Paul.Clements@steeleye.com), while the userland tools are
626 maintained by &dhusername; (&dhemail;)</para>
628 <para>On The Hurd there is a regular translator available to perform the
629 client side of the protocol, and the use of
630 <command>nbd-client</command> is not required. Please see the
631 relevant documentation for more information.</para>
633 <para>This manual page was written by &dhusername; (&dhemail;) for
634 the &debian; system (but may be used by others). Permission is
635 granted to copy, distribute and/or modify this document under
636 the terms of the <acronym>GNU</acronym> General Public License,
637 version 2, as published by the Free Software Foundation.</para>
641 <title>EXAMPLES</title>
642 <para>A simple <command>nbd-server</command> configuration file
643 would look like this:</para>
647 exportname = /export/blkdev
650 <para>For increased security, one might want to create an
651 authorization file, and set the UID and GID to run as:</para>
657 exportname = /export/blkdev
659 authfile = @sysconfdir@/nbd-server/allow
661 <para>With @sysconfdir@/nbd-server/allow containing the following:</para>
670 <!-- Keep this comment at the end of the file
675 sgml-minimize-attributes:nil
676 sgml-always-quote-attributes:t
679 sgml-parent-document:nil
680 sgml-default-dtd-file:nil
681 sgml-exposed-tags:nil
682 sgml-local-catalogs:nil
683 sgml-local-ecat-files:nil