Provided by: nbd-server_3.23-3ubuntu1.22.04.1_amd64 
NAME
/etc/nbd-server/config - configuration file for nbd-server
SYNOPSIS
/etc/nbd-server/config
DESCRIPTION
This file allows to configure the nbd-server.
While /etc/nbd-server/config is the default configuration file, this can be varied with the -C option to
nbd-server(1).
The configuration file consists of section header lines, comment lines, and option lines.
A section header is a unique name that is enclosed in square brackets ("[" and "]"). A section header
denotes the beginning of a section; a section continues until the next section or the end of the file,
whichever is first. The first section in the configuration file must be called generic, and is used for
global options that apply to more than one export. This section must always be present, even if it holds
no options. Every other section defines one export; the names of these sections are not important, except
that you should take care to make sure that each section name is unique. The section name is used as the
name for the export in case the client connects with a name rather than a port to specify an export, and
must therefore be unique.
A comment line is a line that starts with optional whitespace, followed by a pound sign ("#"), and
continues until the end of the line. Comments may not be used on option lines or section header lines.
An option line is a line that starts with an option name, followed by an equals sign ("="), followed by
the option value. An option can be of type string, of type integer, or of type boolean. The value of a
boolean option can be denoted with either true or false (so not yes, no, on, off, 1, or 0). All booleans
default to false unless specified otherwise. No value may be quoted; always enter it directly. For a
string option, leading whitespace is stripped (but trailing whitespace is not).
OPTIONS FOR SECTION [GENERIC]
allowlist
Optional; boolean
Whether to allow the client to fetch a list of exports from this server. If enabled, the client
can run nbd-client -l to get a list of exports on this server.
cacertfile
Optional; string
If this option is set, it should contain a path to a PEM format X.509 CA certificate used for
validating client certificates supplied by the client. If this option is not set then client
certificates will not be checked.
certfile
Optional; string
If this option is set, it should contain a path to a PEM format X.509 public certificate used for
TLS negotiation with the client. If keyfile is set but certfile is not set, then the server will
attempt to read the certificate from the path specified by keyfile.
force_tls
Optional; boolean.
Switch the server to FORCEDTLS mode.
Note: this is not the same as enabling the force_tls option for each and every export
individually. The latter will allow certain options to be issued during negotiation (e.g., the
"list exports" option, even if that would return an empty result set), whereas enabling this
option will disallow the use of any option to be issued during negotiation, apart from the
STARTTLS option itself (to switch the transport to TLS).
Using FORCEDTLS mode should result in a safer environment, as the server will not allow any
communication to take place unless and until TLS has been negotiated. However, it also makes it
impossible to set up a nonencrypted export for the benefit of older clients, or for clients that
want to swap and not deadlock.
Using this parameter without also specifying a value for the other TLS-related parameters is
possible, but silly.
group Optional; string.
The name of the group this server must run as. If this parameter is not specified, then nbd-server
will not attempt to change its GID (so the GID it runs as will be the primary group of the user
who starts nbd-server). If it is specified, then nbd-server will change its GID after opening
ports, but before accepting connections or opening files.
includedir
Optional; string
The argument should be a directory containing files with the '.conf' extension; these files will
be parsed as if they were part of the configuration file. Note that these extra configuration
files cannot contain a [generic] section; any configuration that should go in the generic section
must be placed in the main configuration file.
If this argument is not specified, then no directory will be searched. If it is specified but the
directory does not exist, then nbd-server will exit with an appropriate error message; if it is
specified but the given directory is empty, nbd-server will continue (unless no exports whatsoever
have been configured, in which case it will exit with an appropriate error message)
keyfile
Optional; string
If this option is set, it should contain a path to a PEM format X.509 private key used for TLS
negotiation with the client. This option must be set to enable TLS.
listenaddr
Optional; string
If this option is set, it should contain a comma-separated lis of the local IP addresses on which
we should listen to nbd-client(8) connections. If it is not set, nbd-server will listen to "::,
0.0.0.0", which causes nbd-server to listen to all local IPv4 and IPv6 addresses. To limit to
IPv6, specify the address as "::". To limit to IPv4, specify as "0.0.0.0".
max_threads
Optional; integer; default 4
Since NBD 3.12, nbd-server will read requests in a main thread, but do the handling of these
requests, and the sending of the reply, in a number of separate worker threads, which are shared
among all exports. With this parameter, you can configure the number of these worker threads.
The default should be reasonable for a dual-core single-disk server. You might want to increase it
if you have a powerful server that does little else than serving NBD.
oldstyle
Optional; boolean
In versions of nbd-server between 2.9.17 and 3.9.1, when this option was set to true, nbd-server
would export all exports on a separate port with the old (pre-2.9.17) handshake protocol. In that
case, the 'port' option for individual exports was mandatory.
Since version 3.10 of nbd-server, however, this option is no longer supported, and any attempt to
use it will result in nbd-server exiting with an appropriate error message.
port Optional; string
The port on which to listen for new-style nbd-client connections. If not specified, the IANA-
assigned port of 10809 is used.
splice Optional; boolean
Allow the server to use the splice() system call to handle read or write calls when possible.
Using splice can speed up handling of such calls significantly. Unfortunately, splice cannot be
used in combination with TLS or the copyonwrite mode, and will only work for requests smaller than
1MiB.
To handle these situations, the server will exit with an appropriate error message if splice and
copyonwrite are both enabled for an export; it will silently ignore the splice option if TLS is
enabled, falling back on normal reads and writes; and it will similarly fall back on normal reads
when the request size exceeds 1MiB.
user Optional; string.
The name of the user this server must run as. If this parameter is not specified, then nbd-server
will not attempt to change its UID (so the UID it runs as will be the user who starts nbd-server).
If it is specified, then nbd-server will change its UID after opening ports, but before accepting
connections or opening files.
unixsock
Optional; string
Path for a UNIX domain socket.
If specified, the server will listen on a UNIX domain socket with the specified name. Only
newstyle negotiation is supported on UNIX domain sockets. If a UNIX domain socket is, then the
server will not listen for TCP connections.
duallisten
Optional; boolean
If true, and unixsock is specified, the the server will listen on both the configured UNIX domain
socket and any configured TCP or SDP socket. Defaults to false.
tlsprio
Optional; string; default NORMAL:-VERS-TLS-ALL:+VERS-TLS1.2:%SERVER_PRECEDENCE
This option allows to configure the GnuTLS priority string, which is used to select the algorithms
which GnuTLS will allow to be negotiated with the client. The NBD STARTTLS specification requires
that clients and servers require TLS1.2 or higher by default, so the default string disables all
older versions of the TLS protocol.
Not all versions of GnuTLS support the %SERVER_PRECEDENCE flag, which exists to signal that the
server should pay no attention to the algorithm preferences selected by the client. If you're
using an older version of GnuTLS (e.g., 2.12), it may be necessary to specify a priority string
that does not include the %SERVER_PRECEDENCE flag.
For an explanation of the possible values of this option, see the "Priority strings" chapter in
the GnuTLS documentation.
OPTIONS FOR EXPORT SECTIONS
authfile
Optional; string; default empty
The name of the authorization file for this export. This file should contain one line per IP-
address, or per network (which must be specified in CIDR-style network/masklen). Empty lines are
skipped, as is any content behind a hashmark ('#') on any line.
If the file does not exist, everyone is allowed to connect. If the file exists but is empty,
nobody is allowed to connect. Otherwise, nbd-server will only allow clients to connect whose IP-
adres is listed in this file.
Corresponds to the -l option on the command line. However, note that for the command line, the
default is /etc/nbd-server/allow.
copyonwrite
Optional; boolean.
Whether this is a copy-on-write export. If it is, then any writes to this export will not be
written to the master file, but to a separate file which will be removed upon disconnect. The
result of using this option is that nbd-server will be somewhat slower, and that any writes will
be lost upon disconnect.
Corresponds to the -c option on the command line
cowdir Optional; string.
Specifies where to write copy-on-write diff files. If this option is absent, copy-on-write files
will be written in the same directory as the base export file. Useful for exporting files in copy-
on-write mode from a directory that the user running nbd-server has no write access to.
If the copy-on-write mode is not active, this option has no effect.
exportname
Required; string.
The name of the file (or block device) that will be exported. This must be a fully-qualified path
and filename; relative paths are not allowed. If used in conjunction with the temporary, this
specifies a template for the temporary file concerned, and thus can be used to control the
directory it is created in. If the file does not exist, but filesize is set, then the file will be
created.
Note that nbd-server will only try to find and open the exported file when a client actually
connects; as a result, nbd-server must be able to open and read this file after changing to the
user and group that have been specified by use of the user and group options; also, nbd-server
will only detect errors in this option upon connection of a client.
When specified on the command line, this should be the second argument.
Note: this is not the "exportname" as defined in the protocol document, and which is the name that
nbd-client needs to pass to select the correct export; the section name is used for that. The name
of the file to be exported is called the exportname in the configuration file for historical
reasons, and cannot easily be changed.
filesize
Optional; integer; default autodetected.
Disable autodetection of file or block device size, and forcibly specify a size. Sizes must be
specified in bytes. If the multifile option is in effect, this option specifies the size of the
entire export, not of individual files. If the file is not present, a single file is created of
this size.
When specified on the command line, this should be the third argument.
flush Optional; boolean.
When this option is enabled, nbd-server will inform the client that it supports and desires to be
sent flush requests when the elevator layer receives them. Receipt of a flush request will cause
an fdatasync() (or, if the sync option is set, an fsync()) on the backend storage. This increases
reliability in the case of an unclean shutdown at the expense of a degradation of performance.
This option will have no effect unless supported by the client.
force_tls
Optional; boolean.
Require the use of TLS for this export to be available.
When this option has been enabled for an export, clients that do not negotiate TLS will not see
the export when they request a list of exports, and will not be able to connect to it.
Enabling this option when TLS credentials have not been configured in the [generic] section is
possible, but silly.
fua Optional; boolean.
When this option is enabled, nbd-server will inform the client that it supports and desires to be
sent fua (force unit access) commands when the elevator layer receives them. Receipt of a force
unit access command will cause the specified command to be synced to backend storage using
sync_file_range() if supported, or fdatasync() otherwise. This increases reliability in the case
of an unclean shutdown at the expense of a degradation of performance. This option will have no
effect unless supported by the client.
listenaddr
Optional; string
Ignored, kept for compatibility with the obsolete 'oldstyle' global parameter.
maxconnections
Optional; integer
If specified, then it limits the number of opened connections for this export.
multifile
Optional; boolean.
If this option is set to true, then nbd-server will search for files of the form
exportname.integer, with exportname being the filename that would otherwise have been used (after
name transformation for virtualization, if any, has been performed) and integer an integer number,
starting with 0 and ending when no more files can be found.
The size of the individual files will be autodetected, even if the filesize option has been
specified.
Corresponds to the -m option on the command line.
treefiles
Optional; boolean.
If this option is set to true, then nbd-server will search for files of the form
exportname/TREEXXXX/.../FILEXXXX, with exportname being the filename that would otherwise have
been used (after name transformation for virtualization, if any, has been performed) and TREEXXXX
and FILEXXXX being autogenerated directory and path names for individual block files.
Files and directories are automatically created. Files will be deleted if the corresponding block
gets marked as unused. The size of the individual block files is fixed to 4096 bytes. There will
be at most 1024 files/subdirectories per folder. An apropriate nesting level of subdirectories
will be created to create a filesystem of filesize bytes in total forming a virtual block device.
This feature is useful to provide a virtual block device on an underlying filesystem that does not
handle large files well, for example fuse/ftpfs, davfs or other network filesytems.
This feature is mutually exclusive with the -m and will take precedence if both are given. There
is no corresponding command line option, since command line control is considered deprecated. You
can however specify a custom config file with the -C option. The filesize option must be
specified when using this feature!
postrun
Optional; string
If specified, then it is assumed to be a command that will be ran when a client has disconnected.
This can be useful to clean up whatever prerun has set up, to log something, or similar.
If the literal string '%s' is present in the command, it will be replaced by the file name that
has just been closed.
In contrast to the prerun option, the exit state of postrun is ignored.
prerun Optional; string
If specified, then this command will be ran after a client has connected to the server (and has
been accepted), but before the server starts serving. If the command contains the literal string
'%s', then this string will be replaced by the filename of the file which nbd-server wants to
export.
This is useful to create export files on the fly, or to verify that a file can be used for export,
to write something to a log file, or similar.
If the command runs with a nonzero exit status, then nbd-server will assume the export will fail,
and refuse to serve it.
readonly
Optional; boolean.
Disallow writes to the device. If this option is specified, nbd-server will issue an error to any
client that tries to write to the device.
Use of this option in conjunction with copyonwrite is possible, but silly.
Corresponds to the -r option on the command line.
rotational
Optional; boolean.
When this option is enabled, nbd-server will inform the client that it would prefer it to send
requests in elevator (i.e., optimized) order, perhaps because it has a backing store and no local
elevator. By default, the client uses QUEUE_FLAG_NONROT, which effectively restricts the function
of the elevator to block merges. By specifying this flag on the server, the client will not use
QUEUE_FLAG_NONROT, meaning the client elevator will perform normal elevator ordering of I/O
requests. Note that even when the backing store is on rotating media, it is not normally necessary
to specify this flag, as the server's elevator algorithm will be used. This flag is only required
where the server will not be using an elevator algorithm or where the elevator algorithm is
effectively neutered (e.g. with the sync option set). This option will have no effect unless
supported by the client.
sdp Optional; boolean.
When this option is enabled, nbd-server will use the Socket Direct Protocol (SDP) to serve the
export, rather than just IP. This is faster, but requires special hardware (usually something like
InfiniBand) and support in the kernel.
Additionally, support for this option must be enabled at compile time, using the --enable-sdp
option to the configure script. If this option is found in a configuration file and nbd-server
does not have support for SDP, then nbd-server will exit with an error message.
sparse_cow
Optional; boolean.
When this option is enabled, nbd-server will use sparse files to implement the copy-on-write
option; such files take up less space then they appear to, which allows nbd-server to handle the
file as if it was just as large as the block device it's for.
If this option is disabled, nbd-server will map every newly written block to the end of the copy-
on-write file, which means that nbd-server will have to lseek(2) to the right position after every
4096-byte block.
Using this option may be faster when much is being written during a connection.
sync Optional; boolean.
When this option is enabled, nbd-server will call an fsync() after every write to the backend
storage. Calling fsync() increases reliability in case of an unclean shutdown of nbd-server; but,
depending on the file system used on the nbd-server side, may degrade performance. The use of this
option isn't always necessary; e.g., on ext3 filesystems, it is recommended that it is not
enabled, since it seriously reduces performance on ext3 filesystems while not importantly
impacting reliability.
temporary
Optional; boolean.
Create a temporary export with a name based on exportname (this can be used to set the directory).
A unique filename is created, which is unlinked as soon as it is created, and therefore the export
will not persist between invocations of nbd-server. Set the size of the file using the filesize
option. This option is incompatible with the multifile option.
When specified on the command line, this should be the third argument.
timeout
Optional; integer; default 0
How many seconds a connection may be idle for this export. When a connection is idle for a longer
time, nbd-server will forcibly disconnect the connection. If you specify 0 (the default), then a
connection may be idle forever.
Corresponds to the -a option on the command line
transactionlog
Optional; string
If specified, then this pathname is used to generate a transaction log. A transaction log is a
binary file consisting of the requests sent to and the replies received by the server, but
excluding any data (so, for a write command, it records the offset and length of the write but not
the data written). It is therefore relatively safe to distribute to a third party. Note that the
transaction log does not include the negotiation sequence. Transaction logs are mainly useful for
debugging. The program nbd-tester-client distributed with the source to this program can reply a
transaction log against a server and perform a data integrity test. Note that the transaction log
is written to for every client opened. If it is necessary to maintain separate transaction logs
for each client, the prerun script should rename the transaction log (which will just have been
opened in order to avoid transaction logs overwriting eachother. This action should be race-free.
trim Optional; boolean
When this option is activated, the server announces it supports the NBD_CMD_TRIM command for the
export. This command allows the server to discard the data from the disk, but does not require it
to.
virtstyle
Optional; string; default "ipliteral"
Defines the style of virtualization. Virtualization allows one to create one export that will
serve a different file depending on the IP address that is connecting. When virtualization is
active, the exportname parameter needs to contain the string '%s'; this will then be replaced by
the IP address of the client connecting, in accordance with the option selected here. The result
of this transformation is then used as the filename to be opened.
When a client connects over a UNIX domain socket, the literal string "unix" is used in lieu of a
client IP address.
There are four types of virtualization that nbd-server supports:
none No virtualization. Will attempt to open the filename as it was written, even if it contains
'%s' in the name.
ipliteral
The %s is replaced by the IP address of the connecting host is used as-is. For IPv4, this
is done in dotted-quad notation; for IPv6, in hexadecimal form with leading zeros omitted.
As an example, if a client connects from 192.168.1.100 and exportname is specified as
/export/%s, then nbd-server will attempt to serve /export/192.168.1.100. For IPv6, with a
client connecting from 2001:6f8:32f::39, the filename would be
/export/2001:6f8:32f:0:0:0:0:39
iphash Same as above, except that nbd-server will replace the dots in the IP address by forward
slashes ('/'); in the same example, nbd-server would open /export/192/168/1/100 instead.
Since there are no dots in most IPv6 addresses, the effect of using this option when IPv6
is in use is indistinguishable from the ipliteral option. It was thought that having to
create an eight-deep directory structure would not be as useful.
cidrhash
This option requires one to add a space and a number after it. nbd-server will use the
number as a network mask in CIDR style, and use that as a hash cutoff point. In the above
example, if virtstyle has been specified as cidrhash 16, then nbd-server will try to open
/export/192.168.0.0/192.168.1.100; if virtstyle were specified as cidrhash 26, then nbd-
server will try to open /export/192.168.1.64/192.168.1.100.
For IPv6, in the above example, with cidrhash 42, the filename would be
/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39.
tlsonly
Optional; boolean.
When this option is enabled, nbd-server will only serve the export using the TLS extension. If
this option is not supplied, TLS is optional, unless tlsonly is set in the generic section. In
order for TLS to work at all, the keyfile option must be specified in the generic section.
waitfile
Optional; string.
When this option is set, nbd-server will allow writes to this export, but not reads, until the
server is sent a SIGUSR1 command. Any writes to the export will be stored in a diff file with the
same algorithm as for the copy-on-write option. In particular, this means that the cowdir option
is in effect for this option, too.
The backend file (as per the exportname parameter) need not exist until the SIGUSR1 signal is sent
to the server.
Once SIGUSR1 is received, nbd-server will open the main export file, and start merging all
outstanding writes into it. Once this operation finishes, the diff file will be removed, and the
server will allow normal use of the export.
This allows the out-of-band live migration of an export from one server to another.
Note that this option cannot be combined with the copy-on-write option itself.
SEE ALSO
nbd-server (1), nbd-client (8), nbd-trdump (8)
AUTHOR
The NBD kernel module and the NBD tools were originally written by Pavel Machek (pavel@ucw.cz)
The Linux kernel module is now maintained by Paul Clements (Paul.Clements@steeleye.com), while the
userland tools are maintained by Wouter Verhelst (<wouter@debian.org>)
On The Hurd there is a regular translator available to perform the client side of the protocol, and the
use of nbd-client is not required. Please see the relevant documentation for more information.
This manual page was written by Wouter Verhelst (<wouter@debian.org>) for the Debian GNU/Linux system
(but may be used by others). Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU General Public License, version 2, as published by the Free Software Foundation.
EXAMPLES
A simple nbd-server configuration file would look like this:
[generic]
[export]
exportname = /export/blkdev
For increased security, one might want to create an authorization file, and set the UID and GID to run
as:
[generic]
user = nbd
group = nbd
[export]
exportname = /export/blkdev
authfile = /etc/nbd-server/allow
With /etc/nbd-server/allow containing the following:
127.0.0.1
192.168.0.0/8
192.168.1.1
: 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $ NBD-SERVER(5)