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>This file allows to configure the nbd-server.</para>
66 <filename>$sysconfdir/nbd-server/config</filename> is the default
67 configuration file, this can be varied with the <option>-C</option>
68 option to <command>nbd-server</command>(1).
71 The configuration file consists of section header lines, comment
72 lines, and option lines.
75 A section header is a unique name that
76 is enclosed in square brackets ("[" and "]"). A section header
77 denotes the beginning of a section; a section continues until
78 the next section or the end of the file, whichever is first. The
79 first section in the configuration file must be called
80 <option>generic</option>, and is used for global options that
81 apply to more than one export. This section must always be
82 present, even if it holds no options. Every other section
83 defines one export; the names of these sections are not
84 important, except that you should take care to make sure that
85 each section name is unique. The section name is used as the name
86 for the export in case the client connects with a name rather than
87 a port to specify an export, and must therefore be unique.
90 A comment line is a line that starts with optional whitespace,
91 followed by a pound sign ("#"), and continues until the end of
92 the line. Comments may <emphasis>not</emphasis> be used on
93 option lines or section header lines.
96 An option line is a line that starts with an option name,
97 followed by an equals sign ("="), followed by the option
98 value. An option can be of type string, of type integer, or of
99 type boolean. The value of a boolean option can be denoted with
100 either true or false (so not yes, no, on, off, 1, or 0). All
101 booleans default to false unless specified otherwise. No value
102 may be quoted; always enter it directly. For a string option,
103 leading whitespace is stripped (but trailing whitespace is not).
108 <title>OPTIONS FOR SECTION [generic]</title>
110 <!-- These are in alphabetical order, please keep it that way -->
113 <term><option>group</option></term>
119 The name of the group this server must run as. If this
120 parameter is not specified, then nbd-server will not
121 attempt to change its GID (so the GID it runs as will be
122 the primary group of the user who starts nbd-server). If
123 it is specified, then nbd-server will change its GID after
124 opening ports, but before accepting connections or opening
130 <term><option>user</option></term>
136 The name of the user this server must run as. If this
137 parameter is not specified, then nbd-server will not
138 attempt to change its UID (so the UID it runs as will be
139 the user who starts nbd-server). If it is specified, then
140 nbd-server will change its UID after opening ports, but
141 before accepting connections or opening files.
146 <term><option>oldstyle</option></term>
152 If this option is set to true, nbd-server will export all
153 exports on a separate port with the old (pre-2.9.17)
154 handshake protocol. In that case, the 'port' option for
155 individual exports is mandatory.
158 If the option is set to false, the 'port' option for
159 individual exports is optional (and will be ignored if
160 specified). The server will only export devices on the
164 For upgrades from pre-2.9.17 versions of nbd, it may be
165 appropriate to enable the oldstyle parameter until all
166 clients have been converted to using name-based exports.
169 Note that exports specified on the command line will
170 always use the old handshake protocol and will not allow
174 Also note that even if this parameter is set to true, all
175 exports will also be made available using the new handshake
176 protocol; it is not possible to switch that off. The reason
177 for this is that the old style protocol will eventually be
178 deprecated, and this option is only available to allow for
184 <term><option>listenaddr</option></term>
189 <para>If this option is set, it should contain the local IP
190 address on which we should listen to
191 <command>nbd-client</command>(8) connections. If it is not
192 set, <command>nbd-server</command> will listen to all
193 local IPv4 and IPv6 addresses. To limit to IPv6, specify the
194 address as "::". To limit to IPv4, specify as "0.0.0.0". It
195 is not possible to specify more than one IP address
202 <title>OPTIONS FOR EXPORT SECTIONS</title>
204 <!-- These are in alphabetical order, please keep it that way -->
207 <term><option>authfile</option></term>
210 Optional; string; default
211 <filename>$sysconfdir/nbd-server/allow</filename>.
214 The name of the authorization file for this export. This
215 file should contain one line per IP-address, or per
216 network (which must be specified in CIDR-style
217 <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>)
218 and must not contain empty lines. If the file
219 does not exist, everyone is allowed to connect. If the
220 file exists but is empty, nobody is allowed to
221 connect. Otherwise, <command>nbd-server</command> will
222 only allow clients to connect whose IP-adres is listed in
225 <para>Corresponds to the <option>-l</option> option on the
230 <term><option>copyonwrite</option></term>
236 Whether this is a copy-on-write export. If it is, then any
237 writes to this export will not be written to the master
238 file, but to a separate file which will be removed upon
239 disconnect. The result of using this option is that
240 nbd-server will be somewhat slower, and that any writes will
241 be lost upon disconnect.
243 <para>Corresponds to the <option>-c</option> option on the
248 <term><option>exportname</option></term>
250 <para>Required; string.</para>
252 The name of the file (or block device) that will be
253 exported. This must be a fully-qualified path and filename;
254 relative paths are not allowed.
257 Note that <command>nbd-server</command> will only try to
258 find and open the exported file when a client actually
259 connects; as a result, <command>nbd-server</command> must
260 be able to open and read this file
261 <emphasis>after</emphasis> changing to the user and group
262 that have been specified by use of the
263 <option>user</option> and <option>group</option> options;
264 also, <command>nbd-server</command> will only detect
265 errors in this option upon connection of a client.
267 <para>When specified on the command line, this should be the
273 <term><option>filesize</option></term>
275 <para>Optional; integer; default autodetected.</para>
277 Disable autodetection of file or block device size, and
278 forcibly specify a size. Sizes must be specified in
279 bytes. If the <option>multifile</option> option is in
280 effect, this option specifies the size of the
281 <emphasis>entire</emphasis> export, not of individual
284 <para>When specified on the command line, this should be the
290 <term>listenaddr</term>
296 If the 'oldstyle' global parameter is specified, works
297 similarly to the global listenaddr parameter, but for the
298 individual port of this particular export. If the 'oldstyle'
299 parameter is not set, this parameter is ignored.
304 <term><option>multifile</option></term>
306 <para>Optional; boolean.</para>
308 If this option is set to true, then
309 <command>nbd-server</command> will search for files of the
311 <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
312 with <replaceable>exportname</replaceable> being the
313 filename that would otherwise have been used (after name
314 transformation for virtualization, if any, has been
315 performed) and <replaceable>integer</replaceable> an
316 integer number, starting with 0 and ending when no more
320 The size of the individual files will be autodetected,
321 <emphasis>even</emphasis> if the <option>filesize</option>
322 option has been specified.
325 Corresponds to the <option>-m</option> option on the
331 <term><option>port</option></term>
333 <para>Required if 'oldstyle' global parameter is set; integer.</para>
335 The port on which this export is to be served using the
336 old-style handshake protocol.
339 This parameter only makes sense when the 'oldstyle'
340 parameter is set to true in the 'generic' section. If that
341 parameter is not set, but this parameter is found in an
342 export section, then nbd-server will issue a warning upon
343 startup but should otherwise continue to function correctly.
346 It is not possible to combine multiple exports on the same
347 port using the old style handshake. Please use the new style
348 handshake for that purpose.
351 When specified on the command line, this should be the
357 <term><option>readonly</option></term>
359 <para>Optional; boolean.</para>
361 Disallow writes to the device. If this option is
362 specified, <command>nbd-server</command> will issue an
363 error to any client that tries to write to the device.
366 Use of this option in conjunction with
367 <option>copyonwrite</option> is possible, but silly.
369 <para>Corresponds to the <option>-r</option> option on the
374 <term><option>sdp</option></term>
376 <para>Optional; boolean.</para>
378 When this option is enabled, <command>nbd-server</command>
379 will use the Socket Direct Protocol (SDP) to serve the
380 export, rather than just IP. This is faster, but requires
381 special hardware (usually something like InfiniBand) and
382 support in the kernel.
385 Additionally, support for this option must be enabled at
386 compile time, using the <option>--enable-sdp</option> option
387 to the <command>configure</command> script. If this option
388 is found in a configuration file and
389 <command>nbd-server</command> does not have support for SDP,
390 then <command>nbd-server</command> will exit with an error
396 <term><option>sync</option></term>
398 <para>Optional; boolean.</para>
399 <para>When this option is enabled,
400 <command>nbd-server</command> will call an fsync() after every
401 write to the backend storage. Calling fsync() increases
402 reliability in case of an unclean shutdown of nbd-server; but,
403 depending on the file system used on the nbd-server side, may
404 degrade performance. The use of this option isn't always
405 necessary; e.g., on ext3 filesystems, it is recommended that
406 it is <emphasis>not</emphasis> enabled, since it seriously
407 reduces performance on ext3 filesystems while not
408 importantly impacting reliability.
413 <term><option>sparse_cow</option></term>
415 <para>Optional; boolean.</para>
417 When this option is enabled, <command>nbd-server</command>
418 will use sparse files to implement the copy-on-write
419 option; such files take up less space then they appear to,
420 which allows <command>nbd-server</command> to handle the
421 file as if it was just as large as the block device it's
425 If this option is disabled, <command>nbd-server</command>
426 will map every newly written block to the end of the
427 copy-on-write file, which means that
428 <command>nbd-server</command> will have to lseek(2) to the
429 right position after every 4096-byte block.
432 Using this option may be faster when much is being written
438 <term><option>timeout</option></term>
440 <para>Optional; integer; default 0</para>
442 How many seconds a connection may be idle for this
443 export. When a connection is idle for a longer time,
444 <command>nbd-server</command> will forcibly disconnect the
445 connection. If you specify 0 (the default), then a
446 connection may be idle forever.
449 Corresponds to the <option>-a</option> option on the
455 <term><option>virtstyle</option></term>
457 <para>Optional; string; default "ipliteral"</para>
459 Defines the style of virtualization. Virtualization allows
460 one to create one export that will serve a different file
461 depending on the IP address that is connecting. When
462 virtualization is active, the
463 <replaceable>exportname</replaceable> parameter needs to
464 contain the string '%s'; this will then be replaced by the
465 IP address of the client connecting, in accordance with the
466 option selected here. The result of this transformation is
467 then used as the filename to be opened.
470 There are four types of virtualization that
471 <command>nbd-server</command> supports:
475 <term><option>none</option></term>
478 No virtualization. Will attempt to open the filename
479 as it was written, even if it contains '%s' in the
485 <term><option>ipliteral</option></term>
488 The %s is replaced by the IP address of the connecting
489 host is used as-is. For IPv4, this is done in
490 dotted-quad notation; for IPv6, in hexadecimal form
491 with leading zeros omitted.
494 As an example, if a client connects from 192.168.1.100
495 and <option>exportname</option> is specified as
496 <filename>/export/%s</filename>, then nbd-server will
498 <filename>/export/192.168.1.100</filename>. For IPv6,
499 with a client connecting from 2001:6f8:32f::39, the
501 <filename>/export/2001:6f8:32f:0:0:0:0:39</filename>
506 <term><option>iphash</option></term>
509 Same as above, except that
510 <command>nbd-server</command> will replace the dots
511 in the IP address by forward slashes ('/'); in the
512 same example, <command>nbd-server</command> would
513 open <filename>/export/192/168/1/100</filename>
517 Since there are no dots in most IPv6 addresses, the
518 effect of using this option when IPv6 is in use is
519 indistinguishable from the ipliteral option. It was
520 thought that having to create an eight-deep directory
521 structure would not be as useful.
526 <term><option>cidrhash</option></term>
529 This option requires one to add a space and a number
530 after it. <command>nbd-server</command> will use the
531 number as a network mask in CIDR style, and use that
532 as a hash cutoff point. In the above example, if
533 <option>virtstyle</option> has been specified as
534 <constant>cidrhash 16</constant>, then
535 <command>nbd-server</command> will try to open
536 <filename>/export/192.168.0.0/192.168.1.100</filename>;
537 if <option>virtstyle</option> were specified as
538 <constant>cidrhash 26</constant>, then
539 <command>nbd-server</command> will try to open
540 <filename>/export/192.168.1.64/192.168.1.100</filename>.
542 <para>For IPv6, in the above example, with
543 <constant>cidrhash 42</constant>, the filename would
545 <filename>/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39</filename>.</para>
552 <term><option>prerun</option></term>
554 <para>Optional; string</para>
556 If specified, then this command will be ran after a
557 client has connected to the server (and has been
558 accepted), but before the server starts serving. If
559 the command contains the literal string '%s', then
560 this string will be replaced by the filename of the
561 file which nbd-server wants to export.
564 This is useful to create export files on the fly, or
565 to verify that a file can be used for export, to
566 write something to a log file, or similar.
569 If the command runs with a non-zero exit status,
570 then nbd-server will assume the export will fail,
571 and refuse to serve it.
576 <term><option>postrun</option></term>
578 <para>Optional; string</para>
580 If specified, then it is assumed to be a command
581 that will be ran when a client has
582 disconnected. This can be useful to clean up
583 whatever <option>prerun</option> has set up, to log
584 something, or similar.
587 If the literal string '%s' is present in the
588 command, it will be replaced by the file name that
589 has just been closed.
592 In contrast to the <option>prerun</option> option,
593 the exit state of <option>postrun</option> is
594 <emphasis>ignored</emphasis>.
599 <term><option>maxconnections</option></term>
601 <para>Optional; integer</para>
603 If specified, then it limits the number of opened connections for
612 <title>SEE ALSO</title>
614 <para>nbd-server (1), nbd-client (8)</para>
619 <title>AUTHOR</title>
620 <para>The NBD kernel module and the NBD tools were originally
621 written by Pavel Machek (pavel@ucw.cz)</para>
623 <para>The Linux kernel module is now maintained by Paul Clements
624 (Paul.Clements@steeleye.com), while the userland tools are
625 maintained by &dhusername; (&dhemail;)</para>
627 <para>On The Hurd there is a regular translator available to perform the
628 client side of the protocol, and the use of
629 <command>nbd-client</command> is not required. Please see the
630 relevant documentation for more information.</para>
632 <para>This manual page was written by &dhusername; (&dhemail;) for
633 the &debian; system (but may be used by others). Permission is
634 granted to copy, distribute and/or modify this document under
635 the terms of the <acronym>GNU</acronym> General Public License,
636 version 2, as published by the Free Software Foundation.</para>
640 <title>EXAMPLES</title>
641 <para>A simple <command>nbd-server</command> configuration file
642 would look like this:</para>
646 exportname = /export/blkdev
649 <para>For increased security, one might want to create an
650 authorization file, and set the UID and GID to run as:</para>
656 exportname = /export/blkdev
658 authfile = $sysconfdir/nbd-server/allow
660 <para>With $sysconfdir/nbd-server/allow containing the following:</para>
669 <!-- Keep this comment at the end of the file
674 sgml-minimize-attributes:nil
675 sgml-always-quote-attributes:t
678 sgml-parent-document:nil
679 sgml-default-dtd-file:nil
680 sgml-exposed-tags:nil
681 sgml-local-catalogs:nil
682 sgml-local-ecat-files:nil