.\" 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" "03 January 2009" "" ""

.SH NAME
/etc/nbd-server/config \- configuration file for nbd-server
.SH SYNOPSIS

\fB/etc/nbd-server/config \fR

.SH "DESCRIPTION"
.PP
\fB/etc/nbd-server/config\fR allows to configure the
nbd-server.
.PP
While
\fI@sysconfdir@/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 (future versions of
\fBnbd-server\fR may use the section name to refer
to an export)
.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
\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
\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@sysconfdir@/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 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 that will be exported. This must be a
fully-qualified path and filename; relative paths are not
allowed.

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.

When specified on the command line, this should be the
third argument.
.TP
\fBlistenaddr\fR
Optional; string

If this option is set, it should contain the local IP
address (in "dotted-quad" notation) on which we should
listen to \fBnbd-client\fR(8) connections. If
it is not set, 0.0.0.0 is used (i.e., "listen on all local
IP addresses")
.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. See the documentation for the
\fBmultifile\fR for details.

Corresponds to the \fB-m\fR option on the
command line.
.TP
\fBport\fR
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 \fBnbd-server\fR may add this
functionality.

When specified on the command line, this should be the
first argument.
.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
\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
\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
\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 There are three 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
\fBnbd-server\fR will look for the
literal string '%s' in the
\fBexportname\fR, 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 \fBnbd-server\fR will attempt to
open. 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
.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.
.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\&.
.RE
.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
\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\&.
.SH "SEE ALSO"
.PP
nbd-server (1), nbd-client (8),
http://nbd.sourceforge.net/roadmap.html
.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
          port = 12345
    
.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
          port = 12345
          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