+.\" 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" "1" "03 January 2009" "" ""
+
+.SH NAME
+nbd-server \- serve a file as a block device to other computers running the GNU/Linux(tm) or GNU/Hurd Operating System
+.SH SYNOPSIS
+
+\fBnbd-server \fR \fB\fI[ip:]port\fB\fR \fB\fIfilename\fB\fR [ \fB\fIsize\fB\fR ] [ \fB-r\fR ] [ \fB-m\fR ] [ \fB-c\fR ] [ \fB-a \fItimeout\fB\fR ] [ \fB-l \fIhost list filename\fB\fR ] [ \fB-o \fIsection name\fB\fR ] [ \fB-C \fIconfig file\fB\fR ]
+
+.SH "DESCRIPTION"
+.PP
+\fBnbd-server\fR is the server for the Linux
+Network Block Device (NBD). With NBD, a client can use a file,
+exported over the network from a server, as a block device. It can
+then be used for whatever purpose a normal block device (harddisk,
+CD-ROM, ...) can be used for.
+.PP
+NBD can be useful for diskless clients that need swapspace,
+but you can also create a filesystem on it and use it as though it
+were a local filesystem.
+.PP
+\fBnbd-server\fR implements some security
+through a file called "nbd_server.allow" in the current directory (by default; a different file can be chosen with the '-l' option).
+This file must list the IP-addresses of clients that are allowed
+to connect. If it does not exist, all clients are able to connect.
+If the file is empty, no clients can connect.
+.SH "OPTIONS"
+.TP
+\fBip\fR
+The ip address the server should listen on. If
+omitted, 0.0.0.0 (aka "any address") is used.
+.TP
+\fBport \fR
+The port the server should listen to. A valid port is
+any number between 1 and 65536; if 0 is used, nbd-server
+will listen on stdin (so that nbd-server can be ran from
+inetd)
+.TP
+\fBfilename\fR
+The filename of the file that should be exported. This
+can be any file, including "real" blockdevices (i.e. a file
+from /dev). If the filename includes the literal string
+"%s", then this %s will be substituded with the IP-address
+of the client trying to connect.
+.TP
+\fBsize\fR
+The size of the block device at the client side. This
+is especially usefull in conjunction with the -m
+option
+
+Can optionally be followed by one of K,k,M or
+m, in which case the size will be multiplied by 1024 (K
+or k) or 1048576 (M or m)
+.TP
+\fB-r\fR
+Export the file read-only. If a client tries to write
+to a read-only exported file, it will receive an error, but
+the connection will stay up.
+.TP
+\fB-m\fR
+Work with multiple files. This can be used to export
+blockdevices that are larger than the maximum allowed
+filesize on a given filesystem; i.e. when the filesystem
+does not allow files larger than 2GB (which is true for
+Linux 2.2 and below), you can use this option to store the
+data in multiple files and export a larger filesystem, if
+needed.
+
+To use this option, you must create a number of files
+with names in the format "name.X", where "name" is given as
+the filename argument to nbd-server, and "X" is a number
+starting by 0 and going up for each file.
+
+Allowing more flexibility for this option is planned for
+future versions.
+.TP
+\fB-c\fR
+Copy on write. When this option is provided,
+write-operations are not done to the exported file, but to a
+separate file. This separate file is removed when the
+connection is closed, which means that serving this way will
+make nbd-server slow down (especially on large block devices
+with lots of writes), and that after disconnecting and
+reconnecting the client or the server, all changes are
+lost.
+.TP
+\fB-C\fR
+Specify configuration file. The default configuration
+file, if this parameter is not specified, is
+\fI@sysconfdir@/nbd-server/config\fR\&.
+
+Note that the configuration file is always parsed and
+the entries in the file used, even if an extra server is
+specified on the command line. To disable the configuration
+file entirely, either move it away or use the -C option to
+point \fBnbd-server\fR(1) to a non-existing or
+empty configuration file.
+.TP
+\fBtimeout\fR
+Maximum number of idle seconds. If a connection is
+inactive for this amount of time, it is terminated; this is to
+avoid stale nbd-server processes staying in memory. Use of
+this option is strongly recommended.
+.TP
+\fBhost list filename\fR
+This argument should contain a list of IP-addresses
+for hosts that may connect to the server. Wildcards are
+\fBnot\fR allowed. If the file does not
+exist, it is ignored (and any host can connect); If the file
+does exist, but is empty, no host can connect. By default,
+the name 'nbd_server.allow' is used, and looked for in the
+current directory, unless nbd-server is compiled as a
+daemon, in which case it is looked for in the
+root-directory.
+.TP
+\fBsection name\fR
+If the \fB-o\fR argument is given on the
+command line, then nbd-server will output a configuration
+file section with this as the header that is functionally
+equivalent to the other options specified on the command line,
+and exit. This is useful for migrating pre-2.9 nbd-server
+initscript configuration files to the new format.
+.SH "EXAMPLES"
+.PP
+Some examples of nbd-server usage:
+.TP 0.2i
+\(bu
+To export a file /export/nbd/exp-bl-dev on port 2000:
+
+\fBnbd-server 2000 /export/nbd/exp-bl-dev\fR
+.TP 0.2i
+\(bu
+To export a the same file read-only:
+
+\fBnbd-server 2000 /export/nbd/exp-bl-dev -r\fR
+.TP 0.2i
+\(bu
+To export the same file read-write, but make sure
+changes are lost after restarting the client or the
+server:
+
+\fBnbd-server 2000 /export/nbd/exp-bl-dev
+-c\fR
+.SH "SEE ALSO"
+.PP
+nbd-client (8), nbd-server (5), 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.
+.\" 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
projects / nbd.git / commitdiff