.\" This manpage has been automatically generated by docbook2man
.\" from a DocBook document. This tool can be found at:
.\"
.\" Please send any bug reports, improvements, comments, patches,
.\" etc. to Steve Cheng .
.TH "NBD-SERVER" "5" ": 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $" "" ""
.SH NAME
/etc/nbd-server/config \- configuration file for nbd-server
.SH SYNOPSIS
\fB/etc/nbd-server/config \fR
.SH "DESCRIPTION"
.PP
This file allows to configure the nbd-server.
.PP
While
\fI/etc/nbd-server/config\fR is the default
configuration file, this can be varied with the \fB-C\fR
option to \fBnbd-server\fR(1).
.PP
The configuration file consists of section header lines, comment
lines, and option lines.
.PP
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
\fBgeneric\fR, 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.
.PP
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 \fBnot\fR be used on
option lines or section header lines.
.PP
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).
.SH "OPTIONS FOR SECTION [GENERIC]"
.TP
\fBallowlist\fR
Optional; boolean
Whether to allow the client to fetch a list of exports from
this server. If enabled, the client can run
\fBnbd-client -l\fR to get a list of exports
on this server.
.TP
\fBcacertfile\fR
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.
.TP
\fBcertfile\fR
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 \fBkeyfile\fR is set but
\fBcertfile\fR is not set, then the server will
attempt to read the certificate from the path specified
by \fBkeyfile\fR\&.
.TP
\fBforce_tls\fR
Optional; boolean.
Switch the server to FORCEDTLS mode.
Note: this is \fBnot\fR 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 \fBany\fR
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.
.TP
\fBgroup\fR
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.
.TP
\fBincludedir\fR
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)
.TP
\fBkeyfile\fR
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.
.TP
\fBlistenaddr\fR
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
\fBnbd-client\fR(8) connections. If it is not set,
\fBnbd-server\fR 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".
.TP
\fBmax_threads\fR
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.
.TP
\fBoldstyle\fR
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.
.TP
\fBport\fR
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.
.TP
\fBsplice\fR
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.
.TP
\fBuser\fR
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.
.TP
\fBunixsock\fR
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.
.TP
\fBduallisten\fR
Optional; boolean
If true, and \fBunixsock\fR is specified, the the
server will listen on both the configured UNIX domain socket
and any configured TCP or SDP socket. Defaults to false.
.TP
\fBtlsprio\fR
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.
.SH "OPTIONS FOR EXPORT SECTIONS"
.TP
\fBauthfile\fR
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
\fB\fInetwork\fB/\fImasklen\fB\fR).
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, \fBnbd-server\fR will only
allow clients to connect whose IP-adres is listed in this
file.
Corresponds to the \fB-l\fR option on the
command line. However, note that for the command line, the
default is
\fI/etc/nbd-server/allow\fR\&.
.TP
\fBcopyonwrite\fR
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 \fB-c\fR option on the
command line
.TP
\fBcowdir\fR
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.
.TP
\fBexportname\fR
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 \fBtemporary\fR, 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 \fBfilesize\fR is set, then
the file will be created.
Note that \fBnbd-server\fR will only try to
find and open the exported file when a client actually
connects; as a result, \fBnbd-server\fR must
be able to open and read this file
\fBafter\fR changing to the user and group
that have been specified by use of the
\fBuser\fR and \fBgroup\fR options;
also, \fBnbd-server\fR will only detect
errors in this option upon connection of a client.
When specified on the command line, this should be the
second argument.
\fBNote:\fR this is \fBnot\fR
the "exportname" as defined in the protocol document, and
which is the name that \fBnbd-client\fR 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.
.TP
\fBfilesize\fR
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 \fBmultifile\fR option is in
effect, this option specifies the size of the
\fBentire\fR 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.
.TP
\fBflush\fR
Optional; boolean.
When this option is enabled,
\fBnbd-server\fR 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.
.TP
\fBforce_tls\fR
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.
.TP
\fBfua\fR
Optional; boolean.
When this option is enabled,
\fBnbd-server\fR 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.
.TP
\fBlistenaddr\fR
Optional; string
Ignored, kept for compatibility with the obsolete
\&'oldstyle' global parameter.
.TP
\fBmaxconnections\fR
Optional; integer
If specified, then it limits the number of opened connections for
this export.
.TP
\fBmultifile\fR
Optional; boolean.
If this option is set to true, then
\fBnbd-server\fR will search for files of the
form
\fIexportname\fR\&.\fIinteger\fR,
with \fIexportname\fR being the
filename that would otherwise have been used (after name
transformation for virtualization, if any, has been
performed) and \fIinteger\fR an
integer number, starting with 0 and ending when no more
files can be found.
The size of the individual files will be autodetected,
\fBeven\fR if the \fBfilesize\fR
option has been specified.
Corresponds to the \fB-m\fR option on the
command line.
.TP
\fBtreefiles\fR
Optional; boolean.
If this option is set to true, then
\fBnbd-server\fR will search for files of the
form
\fIexportname\fR/\fITREEXXXX\fR/.../\fIFILEXXXX\fR,
with \fIexportname\fR being the
filename that would otherwise have been used (after name
transformation for virtualization, if any, has been
performed) and \fITREEXXXX\fR and
\fIFILEXXXX\fR 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 \fBfilesize\fR 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
\fB-m\fR 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 \fB-C\fR option.
The \fBfilesize\fR option \fBmust\fR be specified when using this feature!
.TP
\fBpostrun\fR
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 \fBprerun\fR 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 \fBprerun\fR option,
the exit state of \fBpostrun\fR is
\fBignored\fR\&.
.TP
\fBprerun\fR
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.
.TP
\fBreadonly\fR
Optional; boolean.
Disallow writes to the device. If this option is
specified, \fBnbd-server\fR will issue an
error to any client that tries to write to the device.
Use of this option in conjunction with
\fBcopyonwrite\fR is possible, but silly.
Corresponds to the \fB-r\fR option on the
command line.
.TP
\fBrotational\fR
Optional; boolean.
When this option is enabled,
\fBnbd-server\fR 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.
.TP
\fBsdp\fR
Optional; boolean.
When this option is enabled, \fBnbd-server\fR
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 \fB--enable-sdp\fR option
to the \fBconfigure\fR script. If this option
is found in a configuration file and
\fBnbd-server\fR does not have support for SDP,
then \fBnbd-server\fR will exit with an error
message.
.TP
\fBsparse_cow\fR
Optional; boolean.
When this option is enabled, \fBnbd-server\fR
will use sparse files to implement the copy-on-write
option; such files take up less space then they appear to,
which allows \fBnbd-server\fR to handle the
file as if it was just as large as the block device it's
for.
If this option is disabled, \fBnbd-server\fR
will map every newly written block to the end of the
copy-on-write file, which means that
\fBnbd-server\fR 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.
.TP
\fBsync\fR
Optional; boolean.
When this option is enabled,
\fBnbd-server\fR 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 \fBnot\fR enabled, since it seriously
reduces performance on ext3 filesystems while not
importantly impacting reliability.
.TP
\fBtemporary\fR
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 \fBnbd-server\fR\&. Set the
size of the file using the \fBfilesize\fR
option. This option is incompatible with the
\fBmultifile\fR option.
When specified on the command line, this should be the
third argument.
.TP
\fBtimeout\fR
Optional; integer; default 0
How many seconds a connection may be idle for this
export. When a connection is idle for a longer time,
\fBnbd-server\fR will forcibly disconnect the
connection. If you specify 0 (the default), then a
connection may be idle forever.
Corresponds to the \fB-a\fR option on the
command line
.TP
\fBtransactionlog\fR
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
\fBnbd-tester-client\fR 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
\fBprerun\fR 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.
.TP
\fBtrim\fR
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.
.TP
\fBvirtstyle\fR
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
\fIexportname\fR 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
\fBnbd-server\fR supports:
.RS
.TP
\fBnone\fR
No virtualization. Will attempt to open the filename
as it was written, even if it contains '%s' in the
name.
.TP
\fBipliteral\fR
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 \fBexportname\fR is specified as
\fI/export/%s\fR, then nbd-server will
attempt to serve
\fI/export/192.168.1.100\fR\&. For IPv6,
with a client connecting from 2001:6f8:32f::39, the
filename would be
\fI/export/2001:6f8:32f:0:0:0:0:39\fR
.TP
\fBiphash\fR
Same as above, except that
\fBnbd-server\fR will replace the dots
in the IP address by forward slashes ('/'); in the
same example, \fBnbd-server\fR would
open \fI/export/192/168/1/100\fR
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.
.TP
\fBcidrhash\fR
This option requires one to add a space and a number
after it. \fBnbd-server\fR will use the
number as a network mask in CIDR style, and use that
as a hash cutoff point. In the above example, if
\fBvirtstyle\fR has been specified as
cidrhash 16, then
\fBnbd-server\fR will try to open
\fI/export/192.168.0.0/192.168.1.100\fR;
if \fBvirtstyle\fR were specified as
cidrhash 26, then
\fBnbd-server\fR will try to open
\fI/export/192.168.1.64/192.168.1.100\fR\&.
For IPv6, in the above example, with
cidrhash 42, the filename would
be
\fI/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39\fR\&.
.RE
.TP
\fBtlsonly\fR
Optional; boolean.
When this option is enabled,
\fBnbd-server\fR will only serve the export
using the TLS extension. If this option is not supplied,
TLS is optional, unless \fBtlsonly\fR is set
in the generic section. In order for TLS to work at all,
the \fBkeyfile\fR option must be specified in
the generic section.
.TP
\fBwaitfile\fR
Optional; string.
When this option is set, \fBnbd-server\fR
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
\fBcowdir\fR 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, \fBnbd-server\fR
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.
.SH "SEE ALSO"
.PP
nbd-server (1), nbd-client (8), nbd-trdump (8)
.SH "AUTHOR"
.PP
The NBD kernel module and the NBD tools were originally
written by Pavel Machek (pavel@ucw.cz)
.PP
The Linux kernel module is now maintained by Paul Clements
(Paul.Clements@steeleye.com), while the userland tools are
maintained by Wouter Verhelst ()
.PP
On The Hurd there is a regular translator available to perform the
client side of the protocol, and the use of
\fBnbd-client\fR is not required. Please see the
relevant documentation for more information.
.PP
This manual page was written by Wouter Verhelst () 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.
.SH "EXAMPLES"
.PP
A simple \fBnbd-server\fR configuration file
would look like this:
.nf
[generic]
[export]
exportname = /export/blkdev
.fi
.PP
For increased security, one might want to create an
authorization file, and set the UID and GID to run as:
.nf
[generic]
user = nbd
group = nbd
[export]
exportname = /export/blkdev
authfile = /etc/nbd-server/allow
.fi
.PP
With /etc/nbd-server/allow containing the following:
.nf
127.0.0.1
192.168.0.0/8
192.168.1.1
.fi