NAME
/etc/nbd-server/config - configuration file for nbd-server
SYNOPSIS
/etc/nbd-server/config
DESCRIPTION
/etc/nbd-server/config 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 (future versions of nbd-server
may use the section name to refer to an export)
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]
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.
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
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.
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.
When specified on the command line, this should be the third
argument.
listenaddr
Optional; string
If this option is set, it should contain the local IP address
(in "dotted-quad" notation) on which we should listen to nbd-
client(8) connections. If it is not set, 0.0.0.0 is used (i.e.,
"listen on all local IP addresses")
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. See the documentation
for the multifile for details.
Corresponds to the -m option on the command line.
port Required; integer.
The port on which this export is to be served. Currently it is
not possible to export multiple block devices on the same port
unless virtualization is used; future versions of nbd-server may
add this functionality.
When specified on the command line, this should be the first
argument.
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.
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.
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.
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.
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
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
There are three 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
nbd-server will look for the literal string ’%s’ in the
exportname, and replace it by the IP address of the
connecting host in dotted-quad notation. The string that
results from this transformation will be used as an
absolute pathname that nbd-server will attempt to open.
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
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.
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.
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.
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.
SEE ALSO
nbd-server (1), nbd-client (8), http://nbd.sourceforge.net/roadmap.html
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
port = 12345
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
port = 12345
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
18 August 2009