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.
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
177 <term><option>listenaddr</option></term>
182 <para>If this option is set, it should contain the local IP
183 address on which we should listen to
184 <command>nbd-client</command>(8) connections. If it is not
185 set, <command>nbd-server</command> will listen to all
186 local IPv4 and IPv6 addresses. To limit to IPv6, specify the
187 address as "::". To limit to IPv4, specify as "0.0.0.0". It
188 is not possible to specify more than one IP address
195 <title>OPTIONS FOR EXPORT SECTIONS</title>
197 <!-- These are in alphabetical order, please keep it that way -->
200 <term><option>authfile</option></term>
203 Optional; string; default
204 <filename>@sysconfdir@/nbd-server/allow</filename>.
207 The name of the authorization file for this export. This
208 file should contain one line per IP-address, or per
209 network (which must be specified in CIDR-style
210 <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>)
211 and must not contain empty lines. If the file
212 does not exist, everyone is allowed to connect. If the
213 file exists but is empty, nobody is allowed to
214 connect. Otherwise, <command>nbd-server</command> will
215 only allow clients to connect whose IP-adres is listed in
218 <para>Corresponds to the <option>-l</option> option on the
223 <term><option>copyonwrite</option></term>
229 Whether this is a copy-on-write export. If it is, then any
230 writes to this export will not be written to the master
231 file, but to a separate file which will be removed upon
232 disconnect. The result of using this option is that
233 nbd-server will be slower, and that any writes will be
234 lost upon disconnect.
236 <para>Corresponds to the <option>-c</option> option on the
241 <term><option>exportname</option></term>
243 <para>Required; string.</para>
245 The name of the file (or block device) that will be
246 exported. This must be a fully-qualified path and filename;
247 relative paths are not allowed.
250 Note that <command>nbd-server</command> will only try to
251 find and open the exported file when a client actually
252 connects; as a result, <command>nbd-server</command> must
253 be able to open and read this file
254 <emphasis>after</emphasis> changing to the user and group
255 that have been specified by use of the
256 <option>user</option> and <option>group</option> options;
257 also, <command>nbd-server</command> will only detect
258 errors in this option upon connection of a client.
260 <para>When specified on the command line, this should be the
266 <term><option>filesize</option></term>
268 <para>Optional; integer; default autodetected.</para>
270 Disable autodetection of file or block device size, and
271 forcibly specify a size. Sizes must be specified in
272 bytes. If the <option>multifile</option> option is in
273 effect, this option specifies the size of the
274 <emphasis>entire</emphasis> export, not of individual
277 <para>When specified on the command line, this should be the
283 <term>listenaddr</term>
289 If the 'oldstyle' global parameter is specified, works
290 similarly to the global listenaddr parameter, but for the
291 individual port of this particular export. If the 'oldstyle'
292 parameter is not set, this parameter is ignored.
297 <term><option>multifile</option></term>
299 <para>Optional; boolean.</para>
301 If this option is set to true, then
302 <command>nbd-server</command> will search for files of the
304 <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
305 with <replaceable>exportname</replaceable> being the
306 filename that would otherwise have been used (after name
307 transformation for virtualization, if any, has been
308 performed) and <replaceable>integer</replaceable> an
309 integer number, starting with 0 and ending when no more
313 The size of the individual files will be autodetected,
314 <emphasis>even</emphasis> if the <option>filesize</option>
315 option has been specified. See the documentation for the
316 <option>multifile</option> for details.
319 Corresponds to the <option>-m</option> option on the
325 <term><option>port</option></term>
327 <para>Required if 'oldstyle' global parameter is set; integer.</para>
329 The port on which this export is to be served. Currently
330 it is not possible to export multiple block devices on the
331 same port unless virtualization is used; future versions
332 of <command>nbd-server</command> may add this
336 When specified on the command line, this should be the
342 <term><option>readonly</option></term>
344 <para>Optional; boolean.</para>
346 Disallow writes to the device. If this option is
347 specified, <command>nbd-server</command> will issue an
348 error to any client that tries to write to the device.
351 Use of this option in conjunction with
352 <option>copyonwrite</option> is possible, but silly.
354 <para>Corresponds to the <option>-r</option> option on the
359 <term><option>sdp</option></term>
361 <para>Optional; boolean.</para>
363 When this option is enabled, <command>nbd-server</command>
364 will use the Socket Direct Protocol (SDP) to serve the
365 export, rather than just IP. This is faster, but requires
366 special hardware (usually something like InfiniBand) and
367 support in the kernel.
370 Additionally, support for this option must be enabled at
371 compile time, using the <option>--enable-sdp</option> option
372 to the <command>configure</command> script. If this option
373 is found in a configuration file and
374 <command>nbd-server</command> does not have support for SDP,
375 then <command>nbd-server</command> will exit with an error
381 <term><option>sync</option></term>
383 <para>Optional; boolean.</para>
384 <para>When this option is enabled,
385 <command>nbd-server</command> will call an fsync() after every
386 write to the backend storage. Calling fsync() increases
387 reliability in case of an unclean shutdown of nbd-server; but,
388 depending on the file system used on the nbd-server side, may
389 degrade performance. The use of this option isn't always
390 necessary; e.g., on ext3 filesystems, it is recommended that
391 it is <emphasis>not</emphasis> enabled, since it seriously
392 reduces performance on ext3 filesystems while not
393 importantly impacting reliability.
398 <term><option>sparse_cow</option></term>
400 <para>Optional; boolean.</para>
402 When this option is enabled, <command>nbd-server</command>
403 will use sparse files to implement the copy-on-write
404 option; such files take up less space then they appear to,
405 which allows <command>nbd-server</command> to handle the
406 file as if it was just as large as the block device it's
410 If this option is disabled, <command>nbd-server</command>
411 will map every newly written block to the end of the
412 copy-on-write file, which means that
413 <command>nbd-server</command> will have to lseek(2) to the
414 right position after every 4096-byte block.
417 Using this option may be faster when much is being written
423 <term><option>timeout</option></term>
425 <para>Optional; integer; default 0</para>
427 How many seconds a connection may be idle for this
428 export. When a connection is idle for a longer time,
429 <command>nbd-server</command> will forcibly disconnect the
430 connection. If you specify 0 (the default), then a
431 connection may be idle forever.
434 Corresponds to the <option>-a</option> option on the
440 <term><option>virtstyle</option></term>
442 <para>Optional; string; default "ipliteral"</para>
444 Defines the style of virtualization. Virtualization allows
445 one to create one export that will serve a different file
446 depending on the IP address that is connecting. When
447 virtualization is There are three types of virtualization
448 that <command>nbd-server</command> supports:
452 <term><option>none</option></term>
455 No virtualization. Will attempt to open the filename
456 as it was written, even if it contains '%s' in the
462 <term><option>ipliteral</option></term>
465 <command>nbd-server</command> will look for the
466 literal string '%s' in the
467 <option>exportname</option>, and replace it by the
468 address of the connecting host. The string that
469 results from this transformation will be used as an
470 absolute pathname that <command>nbd-server</command>
471 will attempt to open. As an example, if a client
472 connects from 192.168.1.100 and
473 <option>exportname</option> is specified as
474 <filename>/export/%s</filename>, then nbd-server
475 will attempt to serve
476 <filename>/export/192.168.1.100</filename>
481 <term><option>iphash</option></term>
484 Same as above, except that
485 <command>nbd-server</command> will replace the dots
486 in the IP address by forward slashes ('/'); in the
487 same example, <command>nbd-server</command> would
488 open <filename>/export/192/168/1/100</filename>
492 Since there are no dots in most IPv6 addresses, the
493 effect of using this option when IPv6 is in use is
494 indistinguishable from the ipliteral option.
499 <term><option>cidrhash</option></term>
502 This option requires one to add a space and a number
503 after it. <command>nbd-server</command> will use the
504 number as a network mask in CIDR style, and use that
505 as a hash cutoff point. In the above example, if
506 <option>virtstyle</option> has been specified as
507 <constant>cidrhash 16</constant>, then
508 <command>nbd-server</command> will try to open
509 <filename>/export/192.168.0.0/192.168.1.100</filename>;
510 if <option>virtstyle</option> were specified as
511 <constant>cidrhash 26</constant>, then
512 <command>nbd-server</command> will try to open
513 <filename>/export/192.168.1.64/192.168.1.100</filename>.
515 <para>This option works as expected for IPv6.</para>
522 <term><option>prerun</option></term>
524 <para>Optional; string</para>
526 If specified, then this command will be ran after a
527 client has connected to the server (and has been
528 accepted), but before the server starts serving. If
529 the command contains the literal string '%s', then
530 this string will be replaced by the filename of the
531 file which nbd-server wants to export.
534 This is useful to create export files on the fly, or
535 to verify that a file can be used for export, to
536 write something to a log file, or similar.
539 If the command runs with a non-zero exit status,
540 then nbd-server will assume the export will fail,
541 and refuse to serve it.
546 <term><option>postrun</option></term>
548 <para>Optional; string</para>
550 If specified, then it is assumed to be a command
551 that will be ran when a client has
552 disconnected. This can be useful to clean up
553 whatever <option>prerun</option> has set up, to log
554 something, or similar.
557 If the literal string '%s' is present in the
558 command, it will be replaced by the file name that
559 has just been closed.
562 In contrast to the <option>prerun</option> option,
563 the exit state of <option>postrun</option> is
564 <emphasis>ignored</emphasis>.
572 <title>SEE ALSO</title>
574 <para>nbd-server (1), nbd-client (8),
575 http://nbd.sourceforge.net/roadmap.html</para>
579 <title>AUTHOR</title>
580 <para>The NBD kernel module and the NBD tools were originally
581 written by Pavel Machek (pavel@ucw.cz)</para>
583 <para>The Linux kernel module is now maintained by Paul Clements
584 (Paul.Clements@steeleye.com), while the userland tools are
585 maintained by &dhusername; (&dhemail;)</para>
587 <para>On The Hurd there is a regular translator available to perform the
588 client side of the protocol, and the use of
589 <command>nbd-client</command> is not required. Please see the
590 relevant documentation for more information.</para>
592 <para>This manual page was written by &dhusername; (&dhemail;) for
593 the &debian; system (but may be used by others). Permission is
594 granted to copy, distribute and/or modify this document under
595 the terms of the <acronym>GNU</acronym> General Public License,
596 version 2, as published by the Free Software Foundation.</para>
600 <title>EXAMPLES</title>
601 <para>A simple <command>nbd-server</command> configuration file
602 would look like this:</para>
606 exportname = /export/blkdev
609 <para>For increased security, one might want to create an
610 authorization file, and set the UID and GID to run as:</para>
616 exportname = /export/blkdev
618 authfile = /etc/nbd-server/allow
620 <para>With /etc/nbd-server/allow containing the following:</para>
629 <!-- Keep this comment at the end of the file
634 sgml-minimize-attributes:nil
635 sgml-always-quote-attributes:t
638 sgml-parent-document:nil
639 sgml-default-dtd-file:nil
640 sgml-exposed-tags:nil
641 sgml-local-catalogs:nil
642 sgml-local-ecat-files:nil