.\" <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" "25 oktober 2006" "" ""
+.TH "NBD-SERVER" "5" "01 April 2010" "" ""
.SH NAME
/etc/nbd-server/config \- configuration file for nbd-server
\fB/etc/nbd-server/config\fR allows to configure the
nbd-server.
.PP
-The default configuration file is
-\fI@sysconfdir@/nbd-server/config\fR, but this
-can be varied with the \fB-C\fR option to
-\fBnbd-server\fR(1).
+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.
Corresponds to the \fB-l\fR option on the
command line
.TP
-\fBautoreadonly\fR
-Optional; boolean.
-
-If this option is set to true, then
-\fBnbd-server\fR will automatically switch to
-readonly if it cannot write to the file.
-
-Does not have a corresponding command-line
-argument
-
-TODO: verify whether this option actually works as
-documented. I have a feeling I've been terribly
-stupid.
-.TP
\fBcopyonwrite\fR
Optional; boolean.
\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.
+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 \fBnbd-server\fR will only try to
find and open the exported file when a client actually
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 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
\fBmultifile\fR
Optional; boolean.
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
+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.
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
+\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
\fBsparse_cow\fR
Optional; boolean.
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.
+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
\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
+address of the connecting host. 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 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.
.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
+\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
+\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\&.
+
+This option works as expected for IPv6.
.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),
projects / nbd.git / blobdiff