+.\" 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.
projects / nbd.git / blobdiff