--- /dev/null
+.\" 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" "25 oktober 2006" "" ""
+
+.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
+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).
+.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
+\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.
+
+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
+\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
+\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
+.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
projects / nbd.git / commitdiff