NBD-SERVER(5)NBD-SERVER(5)NAME
/etc/nbd-server/config - configuration file for nbd-serverSYNOPSIS
/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, which‐
ever 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. Com‐
ments 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 bool‐
ean 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 oth‐
erwise. 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.
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 connec‐
tions 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 configura‐
tion 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 config‐
ured, in which case it will exit with an appropriate error mes‐
sage)
listenaddr
Optional; string
If this option is set, it should contain the local IP address on
which we should listen to nbd-client(8) connections. If it is
not set, nbd-server will 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". It is not possible to spec‐
ify more than one IP address here.
oldstyle
Optional; boolean
If this option is set to true, nbd-server will 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
is mandatory.
If the option is set to false, the 'port' option for individual
exports is optional (and will be ignored if specified). The
server will only export devices on the standard port.
For upgrades from pre-2.9.17 versions of nbd, it may be appro‐
priate to enable the oldstyle parameter until all clients have
been converted to using name-based exports.
Note that exports specified on the command line will always use
the old handshake protocol and will not allow name-based
exports.
Also note that even if this parameter is set to true, all
exports will also be made available using the new handshake pro‐
tocol; it is not possible to switch that off. The reason for
this is that the old style protocol will eventually be depre‐
cated, and this option is only available to allow for smooth
upgrades.
port Optional; string
The port on which to listen for new-style nbd-client connec‐
tions. If not specified, the IANA-assigned port of 10809 is
used.
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.
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. Oth‐
erwise, 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 some‐
what slower, and that any writes will be lost upon disconnect.
Corresponds to the -c option on the command line
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.
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 multi‐
file 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 per‐
formance. This option will have no effect unless supported by
the client.
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 per‐
formance. This option will have no effect unless supported by
the client.
listenaddr
Optional; string
If the 'oldstyle' global parameter is specified, works similarly
to the global listenaddr parameter, but for the individual port
of this particular export. If the 'oldstyle' parameter is not
set, this parameter is ignored.
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 trans‐
formation 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.
port Required if 'oldstyle' global parameter is set; integer.
The port on which this export is to be served using the old-
style handshake protocol.
This parameter only makes sense when the 'oldstyle' parameter is
set to true in the 'generic' section. If that parameter is not
set, but this parameter is found in an export section, then nbd-
server will issue a warning upon startup but should otherwise
continue to function correctly.
It is not possible to combine multiple exports on the same port
using the old style handshake. Please use the new style hand‐
shake for that purpose.
When specified on the command line, this should be the first
argument.
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 non-zero 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 algo‐
rithm 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 dur‐
ing 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 transac‐
tion 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 off‐
set 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 sepa‐
rate 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.
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 indis‐
tinguishable 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.
SEE ALSOnbd-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). Permis‐
sion 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
To be compatible with older nbd-client systems, one might wish to
enable the old-style, port-based, negotation:
[generic]
oldstyle = true
[export]
exportname = /export/blkdev
port = 12345
: 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $ NBD-SERVER(5)
