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
66 <para>The default configuration file is
67 <filename>@SCD@/nbd-server/config</filename>, but this
68 can be varied with the <option>-C</option> option to
69 <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>@SCD@/nbd-server/allow</filename>.
160 The name of the authorization file for this export. This
161 file should contain one line per IP-address, and must not
162 contain wildcards of any kind or empty lines. If the file
163 does not exist, everyone is allowed to connect. If the
164 file exists but is empty, nobody is allowed to
165 connect. Otherwise, <command>nbd-server</command> will
166 only allow clients to connect whose IP-adres is listed in
169 <para>Corresponds to the <option>-l</option> option on the
174 <term><option>autoreadonly</option></term>
176 <para>Optional; boolean.</para>
178 If this option is set to true, then
179 <command>nbd-server</command> will automatically switch to
180 readonly if it cannot write to the file.
182 <para>Does not have a corresponding command-line
184 <para>TODO: verify whether this option actually works as
185 documented. I have a feeling I've been terribly
191 <term><option>copyonwrite</option></term>
197 Whether this is a copy-on-write export. If it is, then any
198 writes to this export will not be written to the master
199 file, but to a separate file which will be removed upon
200 disconnect. The result of using this option is that
201 nbd-server will be slower, and that any writes will be
202 lost upon disconnect.
204 <para>Corresponds to the <option>-c</option> option on the
209 <term><option>exportname</option></term>
211 <para>Required; string.</para>
213 The name of the file that will be exported. This must be a
214 fully-qualified path and filename; relative paths are not
218 Note that <command>nbd-server</command> will only try to
219 find and open the exported file when a client actually
220 connects; as a result, <command>nbd-server</command> must
221 be able to open and read this file
222 <emphasis>after</emphasis> changing to the user and group
223 that have been specified by use of the
224 <option>user</option> and <option>group</option> options;
225 also, <command>nbd-server</command> will only detect
226 errors in this option upon connection of a client.
228 <para>When specified on the command line, this should be the
234 <term><option>filesize</option></term>
236 <para>Optional; integer; default autodetected.</para>
238 Disable autodetection of file or block device size, and
239 forcibly specify a size. Sizes must be specified in
240 bytes. If the <option>multifile</option> option is in
241 effect, this option specifies the size of the
242 <emphasis>entire</emphasis> export, not of individual
245 <para>When specified on the command line, this should be the
251 <term><option>multifile</option></term>
253 <para>Optional; boolean.</para>
255 If this option is set to true, then
256 <command>nbd-server</command> will search for files of the
258 <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
259 with <replaceable>exportname</replaceable> being the
260 filename that would otherwise have been used (after
261 name transformation for virtualization, if any, has been
262 performed) and <replaceable>integer</replaceable> an
263 integer number, starting with 0 and ending when no more
267 The size of the individual files will be autodetected,
268 <emphasis>even</emphasis> if the <option>filesize</option>
269 option has been specified. See the documentation for the
270 <option>multifile</option> for details.
273 Corresponds to the <option>-m</option> option on the
279 <term><option>port</option></term>
281 <para>Required; integer.</para>
283 The port on which this export is to be served. Currently
284 it is not possible to export multiple block devices on the
285 same port unless virtualization is used; future versions
286 of <command>nbd-server</command> may add this
290 When specified on the command line, this should be the
296 <term><option>readonly</option></term>
298 <para>Optional; boolean.</para>
300 Disallow writes to the device. If this option is
301 specified, <command>nbd-server</command> will issue an
302 error to any client that tries to write to the device.
305 Use of this option in conjunction with
306 <option>copyonwrite</option> is possible, but silly.
308 <para>Corresponds to the <option>-r</option> option on the
313 <term><option>sparse_cow</option></term>
315 <para>Optional; boolean.</para>
317 When this option is enabled, <command>nbd-server</command>
318 will use sparse files to implement the copy-on-write
319 option; such files take up less space then they appear to,
320 which allows <command>nbd-server</command> to handle the
321 file as if it was just as large as the block device it's for.
324 If this option is disabled, <command>nbd-server</command>
325 will map every newly written block to the end of the
326 copy-on-write file, which means that
327 <command>nbd-server</command> will have to lseek(2) to the
328 right position after every 4096-byte block.
331 Using this option may be faster when much is being written
337 <term><option>timeout</option></term>
339 <para>Optional; integer; default 0</para>
341 How many seconds a connection may be idle for this
342 export. When a connection is idle for a longer time,
343 <command>nbd-server</command> will forcibly disconnect the
344 connection. If you specify 0 (the default), then a
345 connection may be idle forever.
348 Corresponds to the <option>-a</option> option on the
354 <term><option>virtstyle</option></term>
356 <para>Optional; string; default "ipliteral"</para>
358 Defines the style of virtualization. Virtualization allows
359 one to create one export that will serve a different file
360 depending on the IP address that is connecting. When
361 virtualization is There are three types of virtualization
362 that <command>nbd-server</command> supports:
366 <term><option>ipliteral</option></term>
369 <command>nbd-server</command> will look for the
370 literal string '%s' in the
371 <option>exportname</option>, and replace it by the
372 IP address of the connecting host in dotted-quad
373 notation. The string that results from this
374 transformation will be used as an absolute pathname
375 that <command>nbd-server</command> will attempt to
376 open. As an example, if a client connects from
377 192.168.1.100 and <option>exportname</option> is
378 specified as <filename>/export/%s</filename>, then
379 nbd-server will attempt to serve
380 <filename>/export/192.168.1.100</filename>
385 <term><option>iphash</option></term>
388 Same as above, except that
389 <command>nbd-server</command> will replace the dots
390 in the IP address by forward slashes ('/'); in the
391 same example, <command>nbd-server</command> would
392 open <filename>/export/192/168/1/100</filename>
398 <term><option>cidrhash</option></term>
401 This option requires one to add a space and a number
402 after it. <command>nbd-server</command> will use the
403 number as a network mask in CIDR style, and use that
404 as a hash cutoff point. In the above example, if
405 <option>virtstyle</option> has been specified
406 as <constant>cidrhash 16</constant>, then
407 <command>nbd-server</command> will try to open
408 <filename>/export/192.168.0.0/192.168.1.100</filename>; if
409 <option>virtstyle</option> were specified as
410 <constant>cidrhash 26</constant>, then
411 <command>nbd-server</command> will try to open
412 <filename>/export/192.168.1.64/192.168.1.100</filename>.
423 <title>EXAMPLES</title>
424 <para>Some examples of nbd-server usage:</para>
425 <itemizedlist mark="none">
427 <para>To export a file /export/nbd/exp-bl-dev on port 2000:</para>
428 <para><command>nbd-server 2000 /export/nbd/exp-bl-dev</command></para>
431 <para>To export a the same file read-only:</para>
432 <para><command>nbd-server 2000 /export/nbd/exp-bl-dev -r</command></para>
435 <para>To export the same file read-write, but make sure
436 changes are lost after restarting the client or the
438 <para><command>nbd-server 2000 /export/nbd/exp-bl-dev
444 <title>SEE ALSO</title>
446 <para>nbd-server (1), nbd-client (8),
447 http://nbd.sourceforge.net/roadmap.html</para>
451 <title>AUTHOR</title>
452 <para>The NBD kernel module and the NBD tools were originally
453 written by Pavel Machek (pavel@ucw.cz)</para>
455 <para>The Linux kernel module is now maintained by Paul Clements
456 (Paul.Clements@steeleye.com), while the userland tools are
457 maintained by &dhusername; (&dhemail;)</para>
459 <para>On The Hurd there is a regular translator available to perform the
460 client side of the protocol, and the use of
461 <command>nbd-client</command> is not required. Please see the
462 relevant documentation for more information.</para>
464 <para>This manual page was written by &dhusername; (&dhemail;) for
465 the &debian; system (but may be used by others). Permission is
466 granted to copy, distribute and/or modify this document under
467 the terms of the <acronym>GNU</acronym> General Public License,
468 version 2, as published by the Free Software Foundation.</para>
473 <!-- Keep this comment at the end of the file
478 sgml-minimize-attributes:nil
479 sgml-always-quote-attributes:t
482 sgml-parent-document:nil
483 sgml-default-dtd-file:nil
484 sgml-exposed-tags:nil
485 sgml-local-catalogs:nil
486 sgml-local-ecat-files:nil