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 filesize
294 Optional; integer; default autodetected.
295 Disable autodetection of file or block device size, and forcibly
297 specify a size. Sizes must be specified in bytes. If the multi‐
298 file option is in effect, this option specifies the size of the
299 entire export, not of individual files. If the file is not
300 present, a single file is created of this size.
301 When specified on the command line, this should be the third
303 argument.
304 flush Optional; boolean.
306 When this option is enabled, nbd-server will inform the client
308 that it supports and desires to be sent flush requests when the
309 elevator layer receives them. Receipt of a flush request will
310 cause an fdatasync() (or, if the sync option is set, an fsync())
311 on the backend storage. This increases reliability in the case
312 of an unclean shutdown at the expense of a degradation of per‐
313 formance. This option will have no effect unless supported by
314 the client.
315 force_tls
317 Optional; boolean.
318 Require the use of TLS for this export to be available.
320 When this option has been enabled for an export, clients that do
322 not negotiate TLS will not see the export when they request a
323 list of exports, and will not be able to connect to it.
324 Enabling this option when TLS credentials have not been config‐
326 ured in the [generic] section is possible, but silly.
327 fua Optional; boolean.
329 When this option is enabled, nbd-server will inform the client
331 that it supports and desires to be sent fua (force unit access)
332 commands when the elevator layer receives them. Receipt of a
333 force unit access command will cause the specified command to be
334 synced to backend storage using sync_file_range() if supported,
335 or fdatasync() otherwise. This increases reliability in the case
336 of an unclean shutdown at the expense of a degradation of per‐
337 formance. This option will have no effect unless supported by
338 the client.
339 listenaddr
341 Optional; string
342 Ignored, kept for compatibility with the obsolete 'oldstyle'
344 global parameter.
345 maxconnections
347 Optional; integer
348 If specified, then it limits the number of opened connections
350 for this export.
351 multifile
353 Optional; boolean.
354 If this option is set to true, then nbd-server will search for
356 files of the form exportname.integer, with exportname being the
357 filename that would otherwise have been used (after name trans‐
358 formation for virtualization, if any, has been performed) and
359 integer an integer number, starting with 0 and ending when no
360 more files can be found.
361 The size of the individual files will be autodetected, even if
363 the filesize option has been specified.
364 Corresponds to the -m option on the command line.
366 treefiles
368 Optional; boolean.
369 If this option is set to true, then nbd-server will search for
371 files of the form exportname/TREEXXXX/.../FILEXXXX, with export‐
372 name being the filename that would otherwise have been used
373 (after name transformation for virtualization, if any, has been
374 performed) and TREEXXXX and FILEXXXX being autogenerated direc‐
375 tory and path names for individual block files.
376 Files and directories are automatically created. Files will be
378 deleted if the corresponding block gets marked as unused. The
379 size of the individual block files is fixed to 4096 bytes.
380 There will be at most 1024 files/subdirectories per folder. An
381 apropriate nesting level of subdirectories will be created to
382 create a filesystem of filesize bytes in total forming a virtual
383 block device.
384 This feature is useful to provide a virtual block device on an
386 underlying filesystem that does not handle large files well, for
387 example fuse/ftpfs, davfs or other network filesytems.
388 This feature is mutually exclusive with the -m and will take
390 precedence if both are given. There is no corresponding command
391 line option, since command line control is considered depre‐
392 cated. You can however specify a custom config file with the -C
393 option. The filesize option must be specified when using this
394 feature!
395 postrun
397 Optional; string
398 If specified, then it is assumed to be a command that will be
400 ran when a client has disconnected. This can be useful to clean
401 up whatever prerun has set up, to log something, or similar.
402 If the literal string '%s' is present in the command, it will be
404 replaced by the file name that has just been closed.
405 In contrast to the prerun option, the exit state of postrun is
407 ignored.
408 prerun Optional; string
410 If specified, then this command will be ran after a client has
412 connected to the server (and has been accepted), but before the
413 server starts serving. If the command contains the literal
414 string '%s', then this string will be replaced by the filename
415 of the file which nbd-server wants to export.
416 This is useful to create export files on the fly, or to verify
418 that a file can be used for export, to write something to a log
419 file, or similar.
420 If the command runs with a nonzero exit status, then nbd-server
422 will assume the export will fail, and refuse to serve it.
423 readonly
425 Optional; boolean.
426 Disallow writes to the device. If this option is specified, nbd-
428 server will issue an error to any client that tries to write to
429 the device.
430 Use of this option in conjunction with copyonwrite is possible,
432 but silly.
433 Corresponds to the -r option on the command line.
435 rotational
437 Optional; boolean.
438 When this option is enabled, nbd-server will inform the client
440 that it would prefer it to send requests in elevator (i.e.,
441 optimized) order, perhaps because it has a backing store and no
442 local elevator. By default, the client uses QUEUE_FLAG_NONROT,
443 which effectively restricts the function of the elevator to
444 block merges. By specifying this flag on the server, the client
445 will not use QUEUE_FLAG_NONROT, meaning the client elevator will
446 perform normal elevator ordering of I/O requests. Note that even
447 when the backing store is on rotating media, it is not normally
448 necessary to specify this flag, as the server's elevator algo‐
449 rithm will be used. This flag is only required where the server
450 will not be using an elevator algorithm or where the elevator
451 algorithm is effectively neutered (e.g. with the sync option
452 set). This option will have no effect unless supported by the
453 client.
454 sdp Optional; boolean.
456 When this option is enabled, nbd-server will use the Socket
458 Direct Protocol (SDP) to serve the export, rather than just IP.
459 This is faster, but requires special hardware (usually something
460 like InfiniBand) and support in the kernel.
461 Additionally, support for this option must be enabled at compile
463 time, using the --enable-sdp option to the configure script. If
464 this option is found in a configuration file and nbd-server does
465 not have support for SDP, then nbd-server will exit with an
466 error message.
467 sparse_cow
469 Optional; boolean.
470 When this option is enabled, nbd-server will use sparse files to
472 implement the copy-on-write option; such files take up less
473 space then they appear to, which allows nbd-server to handle the
474 file as if it was just as large as the block device it's for.
475 If this option is disabled, nbd-server will map every newly
477 written block to the end of the copy-on-write file, which means
478 that nbd-server will have to lseek(2) to the right position
479 after every 4096-byte block.
480 Using this option may be faster when much is being written dur‐
482 ing a connection.
483 sync Optional; boolean.
485 When this option is enabled, nbd-server will call an fsync()
487 after every write to the backend storage. Calling fsync()
488 increases reliability in case of an unclean shutdown of nbd-
489 server; but, depending on the file system used on the nbd-server
490 side, may degrade performance. The use of this option isn't
491 always necessary; e.g., on ext3 filesystems, it is recommended
492 that it is not enabled, since it seriously reduces performance
493 on ext3 filesystems while not importantly impacting reliability.
494 temporary
496 Optional; boolean.
497 Create a temporary export with a name based on exportname (this
499 can be used to set the directory). A unique filename is created,
500 which is unlinked as soon as it is created, and therefore the
501 export will not persist between invocations of nbd-server. Set
502 the size of the file using the filesize option. This option is
503 incompatible with the multifile option.
504 When specified on the command line, this should be the third
506 argument.
507 timeout
509 Optional; integer; default 0
510 How many seconds a connection may be idle for this export. When
512 a connection is idle for a longer time, nbd-server will forcibly
513 disconnect the connection. If you specify 0 (the default), then
514 a connection may be idle forever.
515 Corresponds to the -a option on the command line
517 transactionlog
519 Optional; string
520 If specified, then this pathname is used to generate a transac‐
522 tion log. A transaction log is a binary file consisting of the
523 requests sent to and the replies received by the server, but
524 excluding any data (so, for a write command, it records the off‐
525 set and length of the write but not the data written). It is
526 therefore relatively safe to distribute to a third party. Note
527 that the transaction log does not include the negotiation
528 sequence. Transaction logs are mainly useful for debugging. The
529 program nbd-tester-client distributed with the source to this
530 program can reply a transaction log against a server and perform
531 a data integrity test. Note that the transaction log is written
532 to for every client opened. If it is necessary to maintain sepa‐
533 rate transaction logs for each client, the prerun script should
534 rename the transaction log (which will just have been opened in
535 order to avoid transaction logs overwriting eachother. This
536 action should be race-free.
537 trim Optional; boolean
539 When this option is activated, the server announces it supports
541 the NBD_CMD_TRIM command for the export. This command allows the
542 server to discard the data from the disk, but does not require
543 it to.
544 virtstyle
546 Optional; string; default "ipliteral"
547 Defines the style of virtualization. Virtualization allows one
549 to create one export that will serve a different file depending
550 on the IP address that is connecting. When virtualization is
551 active, the exportname parameter needs to contain the string
552 '%s'; this will then be replaced by the IP address of the client
553 connecting, in accordance with the option selected here. The
554 result of this transformation is then used as the filename to be
555 opened.
556 When a client connects over a UNIX domain socket, the literal
558 string "unix" is used in lieu of a client IP address.
559 There are four types of virtualization that nbd-server supports:
561 none No virtualization. Will attempt to open the filename as
563 it was written, even if it contains '%s' in the name.
564 ipliteral
566 The %s is replaced by the IP address of the connecting
567 host is used as-is. For IPv4, this is done in dotted-
568 quad notation; for IPv6, in hexadecimal form with leading
569 zeros omitted.
570 As an example, if a client connects from 192.168.1.100
572 and exportname is specified as /export/%s, then nbd-
573 server will attempt to serve /export/192.168.1.100. For
574 IPv6, with a client connecting from 2001:6f8:32f::39, the
575 filename would be /export/2001:6f8:32f:0:0:0:0:39
576 iphash Same as above, except that nbd-server will replace the
578 dots in the IP address by forward slashes ('/'); in the
579 same example, nbd-server would open /export/192/168/1/100
580 instead.
581 Since there are no dots in most IPv6 addresses, the
583 effect of using this option when IPv6 is in use is indis‐
584 tinguishable from the ipliteral option. It was thought
585 that having to create an eight-deep directory structure
586 would not be as useful.
587 cidrhash
589 This option requires one to add a space and a number
590 after it. nbd-server will use the number as a network
591 mask in CIDR style, and use that as a hash cutoff point.
592 In the above example, if virtstyle has been specified as
593 cidrhash 16, then nbd-server will try to open
594 /export/192.168.0.0/192.168.1.100; if virtstyle were
595 specified as cidrhash 26, then nbd-server will try to
596 open /export/192.168.1.64/192.168.1.100.
597 For IPv6, in the above example, with cidrhash 42, the
599 filename would be
600 /export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39.
601 tlsonly
603 Optional; boolean.
604 When this option is enabled, nbd-server will only serve the
606 export using the TLS extension. If this option is not supplied,
607 TLS is optional, unless tlsonly is set in the generic section.
608 In order for TLS to work at all, the keyfile option must be
609 specified in the generic section.
610 waitfile
612 Optional; string.
613 When this option is set, nbd-server will allow writes to this
615 export, but not reads, until the server is sent a SIGUSR1 com‐
616 mand. Any writes to the export will be stored in a diff file
617 with the same algorithm as for the copy-on-write option. In par‐
618 ticular, this means that the cowdir option is in effect for this
619 option, too.
620 The backend file (as per the exportname parameter) need not
622 exist until the SIGUSR1 signal is sent to the server.
623 Once SIGUSR1 is received, nbd-server will open the main export
625 file, and start merging all outstanding writes into it. Once
626 this operation finishes, the diff file will be removed, and the
627 server will allow normal use of the export.
628 This allows the out-of-band live migration of an export from one
630 server to another.
631 Note that this option cannot be combined with the copy-on-write
633 option itself.
634
636 nbd-server (1), nbd-client (8), nbd-trdump (8)
637
639 The NBD kernel module and the NBD tools were originally written by
640 Pavel Machek (pavel@ucw.cz)
641 The Linux kernel module is now maintained by Paul Clements
643 (Paul.Clements@steeleye.com), while the userland tools are maintained
644 by Wouter Verhelst (<wouter@debian.org>)
645 On The Hurd there is a regular translator available to perform the
647 client side of the protocol, and the use of nbd-client is not required.
648 Please see the relevant documentation for more information.
649 This manual page was written by Wouter Verhelst (<wouter@debian.org>)
651 for the Debian GNU/Linux system (but may be used by others). Permis‐
652 sion is granted to copy, distribute and/or modify this document under
653 the terms of the GNU General Public License, version 2, as published by
654 the Free Software Foundation.
655
657 A simple nbd-server configuration file would look like this:
658 [generic]
660 [export]
661 exportname = /export/blkdev
662 For increased security, one might want to create an authorization file,
665 and set the UID and GID to run as:
666 [generic]
668 user = nbd
669 group = nbd
670 [export]
671 exportname = /export/blkdev
672 authfile = /etc/nbd-server/allow
673 With /etc/nbd-server/allow containing the following:
676 127.0.0.1
678 192.168.0.0/8
679 192.168.1.1
680 : 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $ NBD-SERVER(5)