Provided by: nbd-server_3.20-1ubuntu0.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)