1NBD-SERVER(5) NBD-SERVER(5)
2
6 /etc/nbd-server/config - configuration file for nbd-server
7
9 /etc/nbd-server/config
10
13 /etc/nbd-server/config allows to configure the nbd-server.
14 While /etc/nbd-server/config is the default configuration file, this
16 can be varied with the -C option to nbd-server(1).
17 The configuration file consists of section header lines, comment lines,
19 and option lines.
20 A section header is a unique name that is enclosed in square brackets
22 ("[" and "]"). A section header denotes the beginning of a section; a
23 section continues until the next section or the end of the file, which‐
24 ever is first. The first section in the configuration file must be
25 called generic, and is used for global options that apply to more than
26 one export. This section must always be present, even if it holds no
27 options. Every other section defines one export; the names of these
28 sections are not important, except that you should take care to make
29 sure that each section name is unique. The section name is used as the
30 name for the export in case the client connects with a name rather than
31 a port to specify an export, and must therefore be unique.
32 A comment line is a line that starts with optional whitespace, followed
34 by a pound sign ("#"), and continues until the end of the line. Com‐
35 ments may not be used on option lines or section header lines.
36 An option line is a line that starts with an option name, followed by
38 an equals sign ("="), followed by the option value. An option can be of
39 type string, of type integer, or of type boolean. The value of a bool‐
40 ean option can be denoted with either true or false (so not yes, no,
41 on, off, 1, or 0). All booleans default to false unless specified oth‐
42 erwise. No value may be quoted; always enter it directly. For a string
43 option, leading whitespace is stripped (but trailing whitespace is
44 not).
45
47 group Optional; string.
48 The name of the group this server must run as. If this parameter
50 is not specified, then nbd-server will not attempt to change its
51 GID (so the GID it runs as will be the primary group of the user
52 who starts nbd-server). If it is specified, then nbd-server will
53 change its GID after opening ports, but before accepting connec‐
54 tions or opening files.
55 user Optional; string.
57 The name of the user this server must run as. If this parameter
59 is not specified, then nbd-server will not attempt to change its
60 UID (so the UID it runs as will be the user who starts nbd-
61 server). If it is specified, then nbd-server will change its UID
62 after opening ports, but before accepting connections or opening
63 files.
64 oldstyle
66 Optional; boolean
67 If this option is set to true, nbd-server will export all
69 exports on a separate port with the old (pre-2.9.17) handshake
70 protocol. In that case, the 'port' option for individual exports
71 is mandatory.
72 If the option is set to false, the 'port' option for individual
74 exports is optional (and will be ignored if specified). The
75 server will only export devices on the standard port.
76 For upgrades from pre-2.9.17 versions of nbd, it may be appro‐
78 priate to enable the oldstyle parameter until all clients have
79 been converted to using name-based exports.
80 Note that exports specified on the command line will always use
82 the old handshake protocol and will not allow name-based
83 exports.
84 Also note that even if this parameter is set to true, all
86 exports will also be made available using the new handshake pro‐
87 tocol; it is not possible to switch that off. The reason for
88 this is that the old style protocol will eventually be depre‐
89 cated, and this option is only available to allow for smooth
90 upgrades.
91 listenaddr
93 Optional; string
94 If this option is set, it should contain the local IP address on
96 which we should listen to nbd-client(8) connections. If it is
97 not set, nbd-server will listen to all local IPv4 and IPv6
98 addresses. To limit to IPv6, specify the address as "::". To
99 limit to IPv4, specify as "0.0.0.0". It is not possible to spec‐
100 ify more than one IP address here.
101
103 authfile
104 Optional; string; default /etc/nbd-server/allow.
105 The name of the authorization file for this export. This file
107 should contain one line per IP-address, or per network (which
108 must be specified in CIDR-style network/masklen) and must not
109 contain empty lines. If the file does not exist, everyone is
110 allowed to connect. If the file exists but is empty, nobody is
111 allowed to connect. Otherwise, nbd-server will only allow
112 clients to connect whose IP-adres is listed in this file.
113 Corresponds to the -l option on the command line
115 copyonwrite
117 Optional; boolean.
118 Whether this is a copy-on-write export. If it is, then any
120 writes to this export will not be written to the master file,
121 but to a separate file which will be removed upon disconnect.
122 The result of using this option is that nbd-server will be some‐
123 what slower, and that any writes will be lost upon disconnect.
124 Corresponds to the -c option on the command line
126 exportname
128 Required; string.
129 The name of the file (or block device) that will be exported.
131 This must be a fully-qualified path and filename; relative paths
132 are not allowed.
133 Note that nbd-server will only try to find and open the exported
135 file when a client actually connects; as a result, nbd-server
136 must be able to open and read this file after changing to the
137 user and group that have been specified by use of the user and
138 group options; also, nbd-server will only detect errors in this
139 option upon connection of a client.
140 When specified on the command line, this should be the second
142 argument.
143 filesize
145 Optional; integer; default autodetected.
146 Disable autodetection of file or block device size, and forcibly
148 specify a size. Sizes must be specified in bytes. If the multi‐
149 file option is in effect, this option specifies the size of the
150 entire export, not of individual files.
151 When specified on the command line, this should be the third
153 argument.
154 listenaddr
156 Optional; string
157 If the 'oldstyle' global parameter is specified, works similarly
159 to the global listenaddr parameter, but for the individual port
160 of this particular export. If the 'oldstyle' parameter is not
161 set, this parameter is ignored.
162 multifile
164 Optional; boolean.
165 If this option is set to true, then nbd-server will search for
167 files of the form exportname.integer, with exportname being the
168 filename that would otherwise have been used (after name trans‐
169 formation for virtualization, if any, has been performed) and
170 integer an integer number, starting with 0 and ending when no
171 more files can be found.
172 The size of the individual files will be autodetected, even if
174 the filesize option has been specified.
175 Corresponds to the -m option on the command line.
177 port Required if 'oldstyle' global parameter is set; integer.
179 The port on which this export is to be served using the old-
181 style handshake protocol.
182 This parameter only makes sense when the 'oldstyle' parameter is
184 set to true in the 'generic' section. If that parameter is not
185 set, but this parameter is found in an export section, then nbd-
186 server will issue a warning upon startup but should otherwise
187 continue to function correctly.
188 It is not possible to combine multiple exports on the same port
190 using the old style handshake. Please use the new style hand‐
191 shake for that purpose.
192 When specified on the command line, this should be the first
194 argument.
195 readonly
197 Optional; boolean.
198 Disallow writes to the device. If this option is specified, nbd-
200 server will issue an error to any client that tries to write to
201 the device.
202 Use of this option in conjunction with copyonwrite is possible,
204 but silly.
205 Corresponds to the -r option on the command line.
207 sdp Optional; boolean.
209 When this option is enabled, nbd-server will use the Socket
211 Direct Protocol (SDP) to serve the export, rather than just IP.
212 This is faster, but requires special hardware (usually something
213 like InfiniBand) and support in the kernel.
214 Additionally, support for this option must be enabled at compile
216 time, using the --enable-sdp option to the configure script. If
217 this option is found in a configuration file and nbd-server does
218 not have support for SDP, then nbd-server will exit with an
219 error message.
220 sync Optional; boolean.
222 When this option is enabled, nbd-server will call an fsync()
224 after every write to the backend storage. Calling fsync()
225 increases reliability in case of an unclean shutdown of nbd-
226 server; but, depending on the file system used on the nbd-server
227 side, may degrade performance. The use of this option isn't
228 always necessary; e.g., on ext3 filesystems, it is recommended
229 that it is not enabled, since it seriously reduces performance
230 on ext3 filesystems while not importantly impacting reliability.
231 sparse_cow
233 Optional; boolean.
234 When this option is enabled, nbd-server will use sparse files to
236 implement the copy-on-write option; such files take up less
237 space then they appear to, which allows nbd-server to handle the
238 file as if it was just as large as the block device it's for.
239 If this option is disabled, nbd-server will map every newly
241 written block to the end of the copy-on-write file, which means
242 that nbd-server will have to lseek(2) to the right position
243 after every 4096-byte block.
244 Using this option may be faster when much is being written dur‐
246 ing a connection.
247 timeout
249 Optional; integer; default 0
250 How many seconds a connection may be idle for this export. When
252 a connection is idle for a longer time, nbd-server will forcibly
253 disconnect the connection. If you specify 0 (the default), then
254 a connection may be idle forever.
255 Corresponds to the -a option on the command line
257 virtstyle
259 Optional; string; default "ipliteral"
260 Defines the style of virtualization. Virtualization allows one
262 to create one export that will serve a different file depending
263 on the IP address that is connecting. When virtualization is
264 active, the exportname parameter needs to contain the string
265 '%s'; this will then be replaced by the IP address of the client
266 connecting, in accordance with the option selected here. The
267 result of this transformation is then used as the filename to be
268 opened.
269 There are four types of virtualization that nbd-server supports:
271 none No virtualization. Will attempt to open the filename as
273 it was written, even if it contains '%s' in the name.
274 ipliteral
276 The %s is replaced by the IP address of the connecting
277 host is used as-is. For IPv4, this is done in dotted-
278 quad notation; for IPv6, in hexadecimal form with leading
279 zeros omitted.
280 As an example, if a client connects from 192.168.1.100
282 and exportname is specified as /export/%s, then nbd-
283 server will attempt to serve /export/192.168.1.100. For
284 IPv6, with a client connecting from 2001:6f8:32f::39, the
285 filename would be /export/2001:6f8:32f:0:0:0:0:39
286 iphash Same as above, except that nbd-server will replace the
288 dots in the IP address by forward slashes ('/'); in the
289 same example, nbd-server would open /export/192/168/1/100
290 instead.
291 Since there are no dots in most IPv6 addresses, the
293 effect of using this option when IPv6 is in use is indis‐
294 tinguishable from the ipliteral option. It was thought
295 that having to create an eight-deep directory structure
296 would not be as useful.
297 cidrhash
299 This option requires one to add a space and a number
300 after it. nbd-server will use the number as a network
301 mask in CIDR style, and use that as a hash cutoff point.
302 In the above example, if virtstyle has been specified as
303 cidrhash 16, then nbd-server will try to open
304 /export/192.168.0.0/192.168.1.100; if virtstyle were
305 specified as cidrhash 26, then nbd-server will try to
306 open /export/192.168.1.64/192.168.1.100.
307 For IPv6, in the above example, with cidrhash 42, the
309 filename would be
310 /export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39.
311 prerun Optional; string
313 If specified, then this command will be ran after a client has
315 connected to the server (and has been accepted), but before the
316 server starts serving. If the command contains the literal
317 string '%s', then this string will be replaced by the filename
318 of the file which nbd-server wants to export.
319 This is useful to create export files on the fly, or to verify
321 that a file can be used for export, to write something to a log
322 file, or similar.
323 If the command runs with a non-zero exit status, then nbd-server
325 will assume the export will fail, and refuse to serve it.
326 postrun
328 Optional; string
329 If specified, then it is assumed to be a command that will be
331 ran when a client has disconnected. This can be useful to clean
332 up whatever prerun has set up, to log something, or similar.
333 If the literal string '%s' is present in the command, it will be
335 replaced by the file name that has just been closed.
336 In contrast to the prerun option, the exit state of postrun is
338 ignored.
339 maxconnections
341 Optional; integer
342 If specified, then it limits the number of opened connections
344 for this export.
345
347 nbd-server (1), nbd-client (8)
348
350 The NBD kernel module and the NBD tools were originally written by
351 Pavel Machek (pavel@ucw.cz)
352 The Linux kernel module is now maintained by Paul Clements
354 (Paul.Clements@steeleye.com), while the userland tools are maintained
355 by Wouter Verhelst (<wouter@debian.org>)
356 On The Hurd there is a regular translator available to perform the
358 client side of the protocol, and the use of nbd-client is not required.
359 Please see the relevant documentation for more information.
360 This manual page was written by Wouter Verhelst (<wouter@debian.org>)
362 for the Debian GNU/Linux system (but may be used by others). Permis‐
363 sion is granted to copy, distribute and/or modify this document under
364 the terms of the GNU General Public License, version 2, as published by
365 the Free Software Foundation.
366
368 A simple nbd-server configuration file would look like this:
369 [generic]
371 [export]
372 exportname = /export/blkdev
373 port = 12345
374 For increased security, one might want to create an authorization file,
377 and set the UID and GID to run as:
378 [generic]
380 user = nbd
381 group = nbd
382 [export]
383 exportname = /export/blkdev
384 port = 12345
385 authfile = /etc/nbd-server/allow
386 With /etc/nbd-server/allow containing the following:
389 127.0.0.1
391 192.168.0.0/8
392 192.168.1.1
393 27 January 2011 NBD-SERVER(5)