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.
- 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)
- 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 specify 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 appropriate 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 protocol; it is not possible to
switch that off. The reason for this is that the old style protocol will
eventually be deprecated, 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 connections. 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 /etc/nbd-server/allow.
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) and must
not contain empty lines. 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
- 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
- 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 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.
- 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
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
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.
- 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 handshake 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 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.
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.
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
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