.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.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
\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
\fBlistenaddr\fR
Optional; string

If this option is set, it should contain the local IP
address on which we should listen to
\fBnbd-client\fR(8) connections. If it is not
set, \fBnbd-server\fR 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.
.TP
\fBoldstyle\fR
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.
.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
\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.
.SH "OPTIONS FOR EXPORT SECTIONS"
.TP
\fBauthfile\fR
Optional; string; default
\fI/etc/nbd-server/allow\fR\&.

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)
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, \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
.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
\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.
.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
\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

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.
.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
\fBport\fR
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.
.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 non-zero 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.

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
.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 (<wouter@debian.org>)
.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 (<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.
.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
.PP
To be compatible with older nbd-client systems, one might wish
to enable the old-style, port-based, negotation:

.nf
      [generic]
          oldstyle = true
      [export]
          exportname = /export/blkdev
	  port = 12345
    
.fi