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
167 <term><option>listenaddr</option></term>
172 <para>If this option is set, it should contain the local IP
173 address on which we should listen to
174 <command>nbd-client</command>(8) connections. If it is not
175 set, <command>nbd-server</command> will listen to all
176 local IPv4 and IPv6 addresses. To limit to IPv6, specify the
177 address as "::". To limit to IPv4, specify as "0.0.0.0". It
178 is not possible to specify more than one IP address
185 <title>OPTIONS FOR EXPORT SECTIONS</title>
187 <!-- These are in alphabetical order, please keep it that way -->
190 <term><option>authfile</option></term>
193 Optional; string; default
194 <filename>@sysconfdir@/nbd-server/allow</filename>.
197 The name of the authorization file for this export. This
198 file should contain one line per IP-address, or per
199 network (which must be specified in CIDR-style
200 <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>)
201 and must not contain empty lines. If the file
202 does not exist, everyone is allowed to connect. If the
203 file exists but is empty, nobody is allowed to
204 connect. Otherwise, <command>nbd-server</command> will
205 only allow clients to connect whose IP-adres is listed in
208 <para>Corresponds to the <option>-l</option> option on the
213 <term><option>copyonwrite</option></term>
219 Whether this is a copy-on-write export. If it is, then any
220 writes to this export will not be written to the master
221 file, but to a separate file which will be removed upon
222 disconnect. The result of using this option is that
223 nbd-server will be slower, and that any writes will be
224 lost upon disconnect.
226 <para>Corresponds to the <option>-c</option> option on the
231 <term><option>exportname</option></term>
233 <para>Required; string.</para>
235 The name of the file (or block device) that will be
236 exported. This must be a fully-qualified path and filename;
237 relative paths are not allowed.
240 Note that <command>nbd-server</command> will only try to
241 find and open the exported file when a client actually
242 connects; as a result, <command>nbd-server</command> must
243 be able to open and read this file
244 <emphasis>after</emphasis> changing to the user and group
245 that have been specified by use of the
246 <option>user</option> and <option>group</option> options;
247 also, <command>nbd-server</command> will only detect
248 errors in this option upon connection of a client.
250 <para>When specified on the command line, this should be the
256 <term><option>filesize</option></term>
258 <para>Optional; integer; default autodetected.</para>
260 Disable autodetection of file or block device size, and
261 forcibly specify a size. Sizes must be specified in
262 bytes. If the <option>multifile</option> option is in
263 effect, this option specifies the size of the
264 <emphasis>entire</emphasis> export, not of individual
267 <para>When specified on the command line, this should be the
273 <term>listenaddr</term>
279 If the 'oldstyle' global parameter is specified, works
280 similarly to the global listenaddr parameter, but for the
281 individual port of this particular export. If the 'oldstyle'
282 parameter is not set, this parameter is ignored.
287 <term><option>multifile</option></term>
289 <para>Optional; boolean.</para>
291 If this option is set to true, then
292 <command>nbd-server</command> will search for files of the
294 <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
295 with <replaceable>exportname</replaceable> being the
296 filename that would otherwise have been used (after name
297 transformation for virtualization, if any, has been
298 performed) and <replaceable>integer</replaceable> an
299 integer number, starting with 0 and ending when no more
303 The size of the individual files will be autodetected,
304 <emphasis>even</emphasis> if the <option>filesize</option>
305 option has been specified. See the documentation for the
306 <option>multifile</option> for details.
309 Corresponds to the <option>-m</option> option on the
315 <term><option>port</option></term>
317 <para>Required if 'oldstyle' global parameter is set; integer.</para>
319 The port on which this export is to be served. Currently
320 it is not possible to export multiple block devices on the
321 same port unless virtualization is used; future versions
322 of <command>nbd-server</command> may add this
326 When specified on the command line, this should be the
332 <term><option>readonly</option></term>
334 <para>Optional; boolean.</para>
336 Disallow writes to the device. If this option is
337 specified, <command>nbd-server</command> will issue an
338 error to any client that tries to write to the device.
341 Use of this option in conjunction with
342 <option>copyonwrite</option> is possible, but silly.
344 <para>Corresponds to the <option>-r</option> option on the
349 <term><option>sdp</option></term>
351 <para>Optional; boolean.</para>
353 When this option is enabled, <command>nbd-server</command>
354 will use the Socket Direct Protocol (SDP) to serve the
355 export, rather than just IP. This is faster, but requires
356 special hardware (usually something like InfiniBand) and
357 support in the kernel.
360 Additionally, support for this option must be enabled at
361 compile time, using the <option>--enable-sdp</option> option
362 to the <command>configure</command> script. If this option
363 is found in a configuration file and
364 <command>nbd-server</command> does not have support for SDP,
365 then <command>nbd-server</command> will exit with an error
371 <term><option>sync</option></term>
373 <para>Optional; boolean.</para>
374 <para>When this option is enabled,
375 <command>nbd-server</command> will call an fsync() after every
376 write to the backend storage. Calling fsync() increases
377 reliability in case of an unclean shutdown of nbd-server; but,
378 depending on the file system used on the nbd-server side, may
379 degrade performance. The use of this option isn't always
380 necessary; e.g., on ext3 filesystems, it is recommended that
381 it is <emphasis>not</emphasis> enabled, since it seriously
382 reduces performance on ext3 filesystems while not
383 importantly impacting reliability.
388 <term><option>sparse_cow</option></term>
390 <para>Optional; boolean.</para>
392 When this option is enabled, <command>nbd-server</command>
393 will use sparse files to implement the copy-on-write
394 option; such files take up less space then they appear to,
395 which allows <command>nbd-server</command> to handle the
396 file as if it was just as large as the block device it's
400 If this option is disabled, <command>nbd-server</command>
401 will map every newly written block to the end of the
402 copy-on-write file, which means that
403 <command>nbd-server</command> will have to lseek(2) to the
404 right position after every 4096-byte block.
407 Using this option may be faster when much is being written
413 <term><option>timeout</option></term>
415 <para>Optional; integer; default 0</para>
417 How many seconds a connection may be idle for this
418 export. When a connection is idle for a longer time,
419 <command>nbd-server</command> will forcibly disconnect the
420 connection. If you specify 0 (the default), then a
421 connection may be idle forever.
424 Corresponds to the <option>-a</option> option on the
430 <term><option>virtstyle</option></term>
432 <para>Optional; string; default "ipliteral"</para>
434 Defines the style of virtualization. Virtualization allows
435 one to create one export that will serve a different file
436 depending on the IP address that is connecting. When
437 virtualization is There are three types of virtualization
438 that <command>nbd-server</command> supports:
442 <term><option>none</option></term>
445 No virtualization. Will attempt to open the filename
446 as it was written, even if it contains '%s' in the
452 <term><option>ipliteral</option></term>
455 <command>nbd-server</command> will look for the
456 literal string '%s' in the
457 <option>exportname</option>, and replace it by the
458 address of the connecting host. The string that
459 results from this transformation will be used as an
460 absolute pathname that <command>nbd-server</command>
461 will attempt to open. As an example, if a client
462 connects from 192.168.1.100 and
463 <option>exportname</option> is specified as
464 <filename>/export/%s</filename>, then nbd-server
465 will attempt to serve
466 <filename>/export/192.168.1.100</filename>
471 <term><option>iphash</option></term>
474 Same as above, except that
475 <command>nbd-server</command> will replace the dots
476 in the IP address by forward slashes ('/'); in the
477 same example, <command>nbd-server</command> would
478 open <filename>/export/192/168/1/100</filename>
482 Since there are no dots in most IPv6 addresses, the
483 effect of using this option when IPv6 is in use is
484 indistinguishable from the ipliteral option.
489 <term><option>cidrhash</option></term>
492 This option requires one to add a space and a number
493 after it. <command>nbd-server</command> will use the
494 number as a network mask in CIDR style, and use that
495 as a hash cutoff point. In the above example, if
496 <option>virtstyle</option> has been specified as
497 <constant>cidrhash 16</constant>, then
498 <command>nbd-server</command> will try to open
499 <filename>/export/192.168.0.0/192.168.1.100</filename>;
500 if <option>virtstyle</option> were specified as
501 <constant>cidrhash 26</constant>, then
502 <command>nbd-server</command> will try to open
503 <filename>/export/192.168.1.64/192.168.1.100</filename>.
505 <para>This option works as expected for IPv6.</para>
512 <term><option>prerun</option></term>
514 <para>Optional; string</para>
516 If specified, then this command will be ran after a
517 client has connected to the server (and has been
518 accepted), but before the server starts serving. If
519 the command contains the literal string '%s', then
520 this string will be replaced by the filename of the
521 file which nbd-server wants to export.
524 This is useful to create export files on the fly, or
525 to verify that a file can be used for export, to
526 write something to a log file, or similar.
529 If the command runs with a non-zero exit status,
530 then nbd-server will assume the export will fail,
531 and refuse to serve it.
536 <term><option>postrun</option></term>
538 <para>Optional; string</para>
540 If specified, then it is assumed to be a command
541 that will be ran when a client has
542 disconnected. This can be useful to clean up
543 whatever <option>prerun</option> has set up, to log
544 something, or similar.
547 If the literal string '%s' is present in the
548 command, it will be replaced by the file name that
549 has just been closed.
552 In contrast to the <option>prerun</option> option,
553 the exit state of <option>postrun</option> is
554 <emphasis>ignored</emphasis>.
562 <title>SEE ALSO</title>
564 <para>nbd-server (1), nbd-client (8),
565 http://nbd.sourceforge.net/roadmap.html</para>
569 <title>AUTHOR</title>
570 <para>The NBD kernel module and the NBD tools were originally
571 written by Pavel Machek (pavel@ucw.cz)</para>
573 <para>The Linux kernel module is now maintained by Paul Clements
574 (Paul.Clements@steeleye.com), while the userland tools are
575 maintained by &dhusername; (&dhemail;)</para>
577 <para>On The Hurd there is a regular translator available to perform the
578 client side of the protocol, and the use of
579 <command>nbd-client</command> is not required. Please see the
580 relevant documentation for more information.</para>
582 <para>This manual page was written by &dhusername; (&dhemail;) for
583 the &debian; system (but may be used by others). Permission is
584 granted to copy, distribute and/or modify this document under
585 the terms of the <acronym>GNU</acronym> General Public License,
586 version 2, as published by the Free Software Foundation.</para>
590 <title>EXAMPLES</title>
591 <para>A simple <command>nbd-server</command> configuration file
592 would look like this:</para>
596 exportname = /export/blkdev
599 <para>For increased security, one might want to create an
600 authorization file, and set the UID and GID to run as:</para>
606 exportname = /export/blkdev
608 authfile = /etc/nbd-server/allow
610 <para>With /etc/nbd-server/allow containing the following:</para>
619 <!-- Keep this comment at the end of the file
624 sgml-minimize-attributes:nil
625 sgml-always-quote-attributes:t
628 sgml-parent-document:nil
629 sgml-default-dtd-file:nil
630 sgml-exposed-tags:nil
631 sgml-local-catalogs:nil
632 sgml-local-ecat-files:nil