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 This file 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 allowlist
48 Optional; boolean
49 Whether to allow the client to fetch a list of exports from this
51 server. If enabled, the client can run nbd-client -l to get a
52 list of exports on this server.
53 cacertfile
55 Optional; string
56 If this option is set, it should contain a path to a PEM format
58 X.509 CA certificate used for validating client certificates
59 supplied by the client. If this option is not set then client
60 certificates will not be checked.
61 certfile
63 Optional; string
64 If this option is set, it should contain a path to a PEM format
66 X.509 public certificate used for TLS negotiation with the
67 client. If keyfile is set but certfile is not set, then the
68 server will attempt to read the certificate from the path speci‐
69 fied by keyfile.
70 force_tls
72 Optional; boolean.
73 Switch the server to FORCEDTLS mode.
75 Note: this is not the same as enabling the force_tls option for
77 each and every export individually. The latter will allow cer‐
78 tain options to be issued during negotiation (e.g., the "list
79 exports" option, even if that would return an empty result set),
80 whereas enabling this option will disallow the use of any option
81 to be issued during negotiation, apart from the STARTTLS option
82 itself (to switch the transport to TLS).
83 Using FORCEDTLS mode should result in a safer environment, as
85 the server will not allow any communication to take place unless
86 and until TLS has been negotiated. However, it also makes it
87 impossible to set up a nonencrypted export for the benefit of
88 older clients, or for clients that want to swap and not dead‐
89 lock.
90 Using this parameter without also specifying a value for the
92 other TLS-related parameters is possible, but silly.
93 group Optional; string.
95 The name of the group this server must run as. If this parameter
97 is not specified, then nbd-server will not attempt to change its
98 GID (so the GID it runs as will be the primary group of the user
99 who starts nbd-server). If it is specified, then nbd-server will
100 change its GID after opening ports, but before accepting connec‐
101 tions or opening files.
102 includedir
104 Optional; string
105 The argument should be a directory containing files with the
107 '.conf' extension; these files will be parsed as if they were
108 part of the configuration file. Note that these extra configura‐
109 tion files cannot contain a [generic] section; any configuration
110 that should go in the generic section must be placed in the main
111 configuration file.
112 If this argument is not specified, then no directory will be
114 searched. If it is specified but the directory does not exist,
115 then nbd-server will exit with an appropriate error message; if
116 it is specified but the given directory is empty, nbd-server
117 will continue (unless no exports whatsoever have been config‐
118 ured, in which case it will exit with an appropriate error mes‐
119 sage)
120 keyfile
122 Optional; string
123 If this option is set, it should contain a path to a PEM format
125 X.509 private key used for TLS negotiation with the client. This
126 option must be set to enable TLS.
127 listenaddr
129 Optional; string
130 If this option is set, it should contain a comma-separated lis
132 of the local IP addresses on which we should listen to nbd-
133 client(8) connections. If it is not set, nbd-server will listen
134 to "::, 0.0.0.0", which causes nbd-server to listen to all local
135 IPv4 and IPv6 addresses. To limit to IPv6, specify the address
136 as "::". To limit to IPv4, specify as "0.0.0.0".
137 max_threads
139 Optional; integer; default 4
140 Since NBD 3.12, nbd-server will read requests in a main thread,
142 but do the handling of these requests, and the sending of the
143 reply, in a number of separate worker threads, which are shared
144 among all exports. With this parameter, you can configure the
145 number of these worker threads.
146 The default should be reasonable for a dual-core single-disk
148 server. You might want to increase it if you have a powerful
149 server that does little else than serving NBD.
150 oldstyle
152 Optional; boolean
153 In versions of nbd-server between 2.9.17 and 3.9.1, when this
155 option was set to true, nbd-server would export all exports on a
156 separate port with the old (pre-2.9.17) handshake protocol. In
157 that case, the 'port' option for individual exports was manda‐
158 tory.
159 Since version 3.10 of nbd-server, however, this option is no
161 longer supported, and any attempt to use it will result in nbd-
162 server exiting with an appropriate error message.
163 port Optional; string
165 The port on which to listen for new-style nbd-client connec‐
167 tions. If not specified, the IANA-assigned port of 10809 is
168 used.
169 splice Optional; boolean
171 Allow the server to use the splice() system call to handle read
173 or write calls when possible. Using splice can speed up handling
174 of such calls significantly. Unfortunately, splice cannot be
175 used in combination with TLS or the copyonwrite mode, and will
176 only work for requests smaller than 1MiB.
177 To handle these situations, the server will exit with an appro‐
179 priate error message if splice and copyonwrite are both enabled
180 for an export; it will silently ignore the splice option if TLS
181 is enabled, falling back on normal reads and writes; and it will
182 similarly fall back on normal reads when the request size
183 exceeds 1MiB.
184 user Optional; string.
186 The name of the user this server must run as. If this parameter
188 is not specified, then nbd-server will not attempt to change its
189 UID (so the UID it runs as will be the user who starts nbd-
190 server). If it is specified, then nbd-server will change its UID
191 after opening ports, but before accepting connections or opening
192 files.
193 unixsock
195 Optional; string
196 Path for a UNIX domain socket.
198 If specified, the server will listen on a UNIX domain socket
200 with the specified name. Only newstyle negotiation is supported
201 on UNIX domain sockets. If a UNIX domain socket is, then the
202 server will not listen for TCP connections.
203 duallisten
205 Optional; boolean
206 If true, and unixsock is specified, the the server will listen
208 on both the configured UNIX domain socket and any configured TCP
209 or SDP socket. Defaults to false.
210 tlsprio
212 Optional; string; default NORMAL:-VERS-TLS-ALL:+VERS-
213 TLS1.2:%SERVER_PRECEDENCE
214 This option allows to configure the GnuTLS priority string,
216 which is used to select the algorithms which GnuTLS will allow
217 to be negotiated with the client. The NBD STARTTLS specification
218 requires that clients and servers require TLS1.2 or higher by
219 default, so the default string disables all older versions of
220 the TLS protocol.
221 Not all versions of GnuTLS support the %SERVER_PRECEDENCE flag,
223 which exists to signal that the server should pay no attention
224 to the algorithm preferences selected by the client. If you're
225 using an older version of GnuTLS (e.g., 2.12), it may be neces‐
226 sary to specify a priority string that does not include the
227 %SERVER_PRECEDENCE flag.
228 For an explanation of the possible values of this option, see
230 the "Priority strings" chapter in the GnuTLS documentation.
231
233 authfile
234 Optional; string; default empty
235 The name of the authorization file for this export. This file
237 should contain one line per IP-address, or per network (which
238 must be specified in CIDR-style network/masklen). Empty lines
239 are skipped, as is any content behind a hashmark ('#') on any
240 line.
241 If the file does not exist, everyone is allowed to connect. If
243 the file exists but is empty, nobody is allowed to connect. Oth‐
244 erwise, nbd-server will only allow clients to connect whose IP-
245 adres is listed in this file.
246 Corresponds to the -l option on the command line. However, note
248 that for the command line, the default is /etc/nbd-server/allow.
249 copyonwrite
251 Optional; boolean.
252 Whether this is a copy-on-write export. If it is, then any
254 writes to this export will not be written to the master file,
255 but to a separate file which will be removed upon disconnect.
256 The result of using this option is that nbd-server will be some‐
257 what slower, and that any writes will be lost upon disconnect.
258 Corresponds to the -c option on the command line
260 cowdir Optional; string.
262 Specifies where to write copy-on-write diff files. If this
264 option is absent, copy-on-write files will be written in the
265 same directory as the base export file. Useful for exporting
266 files in copy-on-write mode from a directory that the user run‐
267 ning nbd-server has no write access to.
268 If the copy-on-write mode is not active, this option has no
270 effect.
271 exportname
273 Required; string.
274 The name of the file (or block device) that will be exported.
276 This must be a fully-qualified path and filename; relative paths
277 are not allowed. If used in conjunction with the temporary, this
278 specifies a template for the temporary file concerned, and thus
279 can be used to control the directory it is created in. If the
280 file does not exist, but filesize is set, then the file will be
281 created.
282 Note that nbd-server will only try to find and open the exported
284 file when a client actually connects; as a result, nbd-server
285 must be able to open and read this file after changing to the
286 user and group that have been specified by use of the user and
287 group options; also, nbd-server will only detect errors in this
288 option upon connection of a client.
289 When specified on the command line, this should be the second
291 argument.
292 Note: this is not the "exportname" as defined in the protocol
294 document, and which is the name that nbd-client needs to pass to
295 select the correct export; the section name is used for that.
296 The name of the file to be exported is called the exportname in
297 the configuration file for historical reasons, and cannot easily
298 be changed.
299 filesize
301 Optional; integer; default autodetected.
302 Disable autodetection of file or block device size, and forcibly
304 specify a size. Sizes must be specified in bytes. If the multi‐
305 file option is in effect, this option specifies the size of the
306 entire export, not of individual files. If the file is not
307 present, a single file is created of this size.
308 When specified on the command line, this should be the third
310 argument.
311 flush Optional; boolean.
313 When this option is enabled, nbd-server will inform the client
315 that it supports and desires to be sent flush requests when the
316 elevator layer receives them. Receipt of a flush request will
317 cause an fdatasync() (or, if the sync option is set, an fsync())
318 on the backend storage. This increases reliability in the case
319 of an unclean shutdown at the expense of a degradation of per‐
320 formance. This option will have no effect unless supported by
321 the client.
322 force_tls
324 Optional; boolean.
325 Require the use of TLS for this export to be available.
327 When this option has been enabled for an export, clients that do
329 not negotiate TLS will not see the export when they request a
330 list of exports, and will not be able to connect to it.
331 Enabling this option when TLS credentials have not been config‐
333 ured in the [generic] section is possible, but silly.
334 fua Optional; boolean.
336 When this option is enabled, nbd-server will inform the client
338 that it supports and desires to be sent fua (force unit access)
339 commands when the elevator layer receives them. Receipt of a
340 force unit access command will cause the specified command to be
341 synced to backend storage using sync_file_range() if supported,
342 or fdatasync() otherwise. This increases reliability in the case
343 of an unclean shutdown at the expense of a degradation of per‐
344 formance. This option will have no effect unless supported by
345 the client.
346 listenaddr
348 Optional; string
349 Ignored, kept for compatibility with the obsolete 'oldstyle'
351 global parameter.
352 maxconnections
354 Optional; integer
355 If specified, then it limits the number of opened connections
357 for this export.
358 multifile
360 Optional; boolean.
361 If this option is set to true, then nbd-server will search for
363 files of the form exportname.integer, with exportname being the
364 filename that would otherwise have been used (after name trans‐
365 formation for virtualization, if any, has been performed) and
366 integer an integer number, starting with 0 and ending when no
367 more files can be found.
368 The size of the individual files will be autodetected, even if
370 the filesize option has been specified.
371 Corresponds to the -m option on the command line.
373 treefiles
375 Optional; boolean.
376 If this option is set to true, then nbd-server will search for
378 files of the form exportname/TREEXXXX/.../FILEXXXX, with export‐
379 name being the filename that would otherwise have been used
380 (after name transformation for virtualization, if any, has been
381 performed) and TREEXXXX and FILEXXXX being autogenerated direc‐
382 tory and path names for individual block files.
383 Files and directories are automatically created. Files will be
385 deleted if the corresponding block gets marked as unused. The
386 size of the individual block files is fixed to 4096 bytes.
387 There will be at most 1024 files/subdirectories per folder. An
388 apropriate nesting level of subdirectories will be created to
389 create a filesystem of filesize bytes in total forming a virtual
390 block device.
391 This feature is useful to provide a virtual block device on an
393 underlying filesystem that does not handle large files well, for
394 example fuse/ftpfs, davfs or other network filesytems.
395 This feature is mutually exclusive with the -m and will take
397 precedence if both are given. There is no corresponding command
398 line option, since command line control is considered depre‐
399 cated. You can however specify a custom config file with the -C
400 option. The filesize option must be specified when using this
401 feature!
402 postrun
404 Optional; string
405 If specified, then it is assumed to be a command that will be
407 ran when a client has disconnected. This can be useful to clean
408 up whatever prerun has set up, to log something, or similar.
409 If the literal string '%s' is present in the command, it will be
411 replaced by the file name that has just been closed.
412 In contrast to the prerun option, the exit state of postrun is
414 ignored.
415 prerun Optional; string
417 If specified, then this command will be ran after a client has
419 connected to the server (and has been accepted), but before the
420 server starts serving. If the command contains the literal
421 string '%s', then this string will be replaced by the filename
422 of the file which nbd-server wants to export.
423 This is useful to create export files on the fly, or to verify
425 that a file can be used for export, to write something to a log
426 file, or similar.
427 If the command runs with a nonzero exit status, then nbd-server
429 will assume the export will fail, and refuse to serve it.
430 readonly
432 Optional; boolean.
433 Disallow writes to the device. If this option is specified, nbd-
435 server will issue an error to any client that tries to write to
436 the device.
437 Use of this option in conjunction with copyonwrite is possible,
439 but silly.
440 Corresponds to the -r option on the command line.
442 rotational
444 Optional; boolean.
445 When this option is enabled, nbd-server will inform the client
447 that it would prefer it to send requests in elevator (i.e.,
448 optimized) order, perhaps because it has a backing store and no
449 local elevator. By default, the client uses QUEUE_FLAG_NONROT,
450 which effectively restricts the function of the elevator to
451 block merges. By specifying this flag on the server, the client
452 will not use QUEUE_FLAG_NONROT, meaning the client elevator will
453 perform normal elevator ordering of I/O requests. Note that even
454 when the backing store is on rotating media, it is not normally
455 necessary to specify this flag, as the server's elevator algo‐
456 rithm will be used. This flag is only required where the server
457 will not be using an elevator algorithm or where the elevator
458 algorithm is effectively neutered (e.g. with the sync option
459 set). This option will have no effect unless supported by the
460 client.
461 sdp Optional; boolean.
463 When this option is enabled, nbd-server will use the Socket
465 Direct Protocol (SDP) to serve the export, rather than just IP.
466 This is faster, but requires special hardware (usually something
467 like InfiniBand) and support in the kernel.
468 Additionally, support for this option must be enabled at compile
470 time, using the --enable-sdp option to the configure script. If
471 this option is found in a configuration file and nbd-server does
472 not have support for SDP, then nbd-server will exit with an
473 error message.
474 sparse_cow
476 Optional; boolean.
477 When this option is enabled, nbd-server will use sparse files to
479 implement the copy-on-write option; such files take up less
480 space then they appear to, which allows nbd-server to handle the
481 file as if it was just as large as the block device it's for.
482 If this option is disabled, nbd-server will map every newly
484 written block to the end of the copy-on-write file, which means
485 that nbd-server will have to lseek(2) to the right position
486 after every 4096-byte block.
487 Using this option may be faster when much is being written dur‐
489 ing a connection.
490 sync Optional; boolean.
492 When this option is enabled, nbd-server will call an fsync()
494 after every write to the backend storage. Calling fsync()
495 increases reliability in case of an unclean shutdown of nbd-
496 server; but, depending on the file system used on the nbd-server
497 side, may degrade performance. The use of this option isn't
498 always necessary; e.g., on ext3 filesystems, it is recommended
499 that it is not enabled, since it seriously reduces performance
500 on ext3 filesystems while not importantly impacting reliability.
501 temporary
503 Optional; boolean.
504 Create a temporary export with a name based on exportname (this
506 can be used to set the directory). A unique filename is created,
507 which is unlinked as soon as it is created, and therefore the
508 export will not persist between invocations of nbd-server. Set
509 the size of the file using the filesize option. This option is
510 incompatible with the multifile option.
511 When specified on the command line, this should be the third
513 argument.
514 timeout
516 Optional; integer; default 0
517 How many seconds a connection may be idle for this export. When
519 a connection is idle for a longer time, nbd-server will forcibly
520 disconnect the connection. If you specify 0 (the default), then
521 a connection may be idle forever.
522 Corresponds to the -a option on the command line
524 transactionlog
526 Optional; string
527 If specified, then this pathname is used to generate a transac‐
529 tion log. A transaction log is a binary file consisting of the
530 requests sent to and the replies received by the server, but
531 excluding any data (so, for a write command, it records the off‐
532 set and length of the write but not the data written). It is
533 therefore relatively safe to distribute to a third party. Note
534 that the transaction log does not include the negotiation
535 sequence. Transaction logs are mainly useful for debugging. The
536 program nbd-tester-client distributed with the source to this
537 program can reply a transaction log against a server and perform
538 a data integrity test. Note that the transaction log is written
539 to for every client opened. If it is necessary to maintain sepa‐
540 rate transaction logs for each client, the prerun script should
541 rename the transaction log (which will just have been opened in
542 order to avoid transaction logs overwriting eachother. This
543 action should be race-free.
544 trim Optional; boolean
546 When this option is activated, the server announces it supports
548 the NBD_CMD_TRIM command for the export. This command allows the
549 server to discard the data from the disk, but does not require
550 it to.
551 virtstyle
553 Optional; string; default "ipliteral"
554 Defines the style of virtualization. Virtualization allows one
556 to create one export that will serve a different file depending
557 on the IP address that is connecting. When virtualization is
558 active, the exportname parameter needs to contain the string
559 '%s'; this will then be replaced by the IP address of the client
560 connecting, in accordance with the option selected here. The
561 result of this transformation is then used as the filename to be
562 opened.
563 When a client connects over a UNIX domain socket, the literal
565 string "unix" is used in lieu of a client IP address.
566 There are four types of virtualization that nbd-server supports:
568 none No virtualization. Will attempt to open the filename as
570 it was written, even if it contains '%s' in the name.
571 ipliteral
573 The %s is replaced by the IP address of the connecting
574 host is used as-is. For IPv4, this is done in dotted-
575 quad notation; for IPv6, in hexadecimal form with leading
576 zeros omitted.
577 As an example, if a client connects from 192.168.1.100
579 and exportname is specified as /export/%s, then nbd-
580 server will attempt to serve /export/192.168.1.100. For
581 IPv6, with a client connecting from 2001:6f8:32f::39, the
582 filename would be /export/2001:6f8:32f:0:0:0:0:39
583 iphash Same as above, except that nbd-server will replace the
585 dots in the IP address by forward slashes ('/'); in the
586 same example, nbd-server would open /export/192/168/1/100
587 instead.
588 Since there are no dots in most IPv6 addresses, the
590 effect of using this option when IPv6 is in use is indis‐
591 tinguishable from the ipliteral option. It was thought
592 that having to create an eight-deep directory structure
593 would not be as useful.
594 cidrhash
596 This option requires one to add a space and a number
597 after it. nbd-server will use the number as a network
598 mask in CIDR style, and use that as a hash cutoff point.
599 In the above example, if virtstyle has been specified as
600 cidrhash 16, then nbd-server will try to open
601 /export/192.168.0.0/192.168.1.100; if virtstyle were
602 specified as cidrhash 26, then nbd-server will try to
603 open /export/192.168.1.64/192.168.1.100.
604 For IPv6, in the above example, with cidrhash 42, the
606 filename would be
607 /export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39.
608 tlsonly
610 Optional; boolean.
611 When this option is enabled, nbd-server will only serve the
613 export using the TLS extension. If this option is not supplied,
614 TLS is optional, unless tlsonly is set in the generic section.
615 In order for TLS to work at all, the keyfile option must be
616 specified in the generic section.
617 waitfile
619 Optional; string.
620 When this option is set, nbd-server will allow writes to this
622 export, but not reads, until the server is sent a SIGUSR1 com‐
623 mand. Any writes to the export will be stored in a diff file
624 with the same algorithm as for the copy-on-write option. In par‐
625 ticular, this means that the cowdir option is in effect for this
626 option, too.
627 The backend file (as per the exportname parameter) need not
629 exist until the SIGUSR1 signal is sent to the server.
630 Once SIGUSR1 is received, nbd-server will open the main export
632 file, and start merging all outstanding writes into it. Once
633 this operation finishes, the diff file will be removed, and the
634 server will allow normal use of the export.
635 This allows the out-of-band live migration of an export from one
637 server to another.
638 Note that this option cannot be combined with the copy-on-write
640 option itself.
641
643 nbd-server (1), nbd-client (8), nbd-trdump (8)
644
646 The NBD kernel module and the NBD tools were originally written by
647 Pavel Machek (pavel@ucw.cz)
648 The Linux kernel module is now maintained by Paul Clements
650 (Paul.Clements@steeleye.com), while the userland tools are maintained
651 by Wouter Verhelst (<wouter@debian.org>)
652 On The Hurd there is a regular translator available to perform the
654 client side of the protocol, and the use of nbd-client is not required.
655 Please see the relevant documentation for more information.
656 This manual page was written by Wouter Verhelst (<wouter@debian.org>)
658 for the Debian GNU/Linux system (but may be used by others). Permis‐
659 sion is granted to copy, distribute and/or modify this document under
660 the terms of the GNU General Public License, version 2, as published by
661 the Free Software Foundation.
662
664 A simple nbd-server configuration file would look like this:
665 [generic]
667 [export]
668 exportname = /export/blkdev
669 For increased security, one might want to create an authorization file,
672 and set the UID and GID to run as:
673 [generic]
675 user = nbd
676 group = nbd
677 [export]
678 exportname = /export/blkdev
679 authfile = /etc/nbd-server/allow
680 With /etc/nbd-server/allow containing the following:
683 127.0.0.1
685 192.168.0.0/8
686 192.168.1.1
687 : 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $ NBD-SERVER(5)