nbd-server.1.in

   1 .\" This manpage has been automatically generated by docbook2man
   2 .\" from a DocBook document.  This tool can be found at:
   3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
   4 .\" Please send any bug reports, improvements, comments, patches,
   5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
   6 .TH "NBD-SERVER" "1" "01 April 2010" "" ""
   7
   8 .SH NAME
   9 nbd-server \- serve a file as a block device to other computers    running the GNU/Linux(tm) or GNU/Hurd Operating    System
  10 .SH SYNOPSIS
  11
  12 \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-l \fIhost list filename\fB\fR ] [ \fB-o \fIsection name\fB\fR ] [ \fB-C \fIconfig file\fB\fR ]
  13
  14 .SH "DESCRIPTION"
  15 .PP
  16 \fBnbd-server\fR is the server for the Linux
  17 Network Block Device (NBD). With NBD, a client can use a file,
  18 exported over the network from a server, as a block device. It can
  19 then be used for whatever purpose a normal block device (harddisk,
  20 CD-ROM, ...) can be used for.
  21 .PP
  22 NBD can be useful for diskless clients that need swapspace,
  23 but you can also create a filesystem on it and use it as though it
  24 were a local filesystem.
  25 .PP
  26 \fBnbd-server\fR implements some security
  27 through a file called "nbd_server.allow" in the current directory (by default; a different file can be chosen with the '-l' option).
  28 This file must list the IP-addresses of clients that are allowed
  29 to connect. If it does not exist, all clients are able to connect.
  30 If the file is empty, no clients can connect.
  31 .SH "OPTIONS"
  32 .TP
  33 \fBip\fR
  34 The ip address the server should listen on. This may
  35 be an IPv4 address, an IPv6 address, or a hostname. In the
  36 latter case, nbd-server will do a hostname lookup for the
  37 name specified, and will listen on the first address that is
  38 returned. For compatibility with past versions of
  39 nbd-server, if an IPv4 address is specified, the @ sign that
  40 serves as separator between the address and port may be
  41 replaced by a colon.
  42
  43 If this parameter is not specified, nbd-server will
  44 listen on all local addresses on both IPv4 and IPv6. To
  45 limit to IPv4, specify the address as 0.0.0.0; to limit to
  46 IPv6, specify it as ::.
  47 .TP
  48 \fBport \fR
  49 The port the server should listen to. A valid port is
  50 any number between 1 and 65536; if 0 is used, nbd-server
  51 will listen on stdin (so that nbd-server can be ran from
  52 inetd)
  53 .TP
  54 \fBfilename\fR
  55 The filename of the file that should be exported. This
  56 can be any file, including "real" blockdevices (i.e. a file
  57 from /dev). If the filename includes the literal string
  58 "%s", then this %s will be substituded with the IP-address
  59 of the client trying to connect.
  60 .TP
  61 \fBsize\fR
  62 The size of the block device at the client side. This
  63 is especially usefull in conjunction with the -m
  64 option
  65
  66 Can optionally be followed by one of K,k,M or
  67 m, in which case the size will be multiplied by 1024 (K
  68 or k) or 1048576 (M or m)
  69 .TP
  70 \fB-r\fR
  71 Export the file read-only. If a client tries to write
  72 to a read-only exported file, it will receive an error, but
  73 the connection will stay up.
  74 .TP
  75 \fB-m\fR
  76 Work with multiple files. This can be used to export
  77 blockdevices that are larger than the maximum allowed
  78 filesize on a given filesystem; i.e. when the filesystem
  79 does not allow files larger than 2GB (which is true for
  80 Linux 2.2 and below), you can use this option to store the
  81 data in multiple files and export a larger filesystem, if
  82 needed.
  83
  84 To use this option, you must create a number of files
  85 with names in the format "name.X", where "name" is given as
  86 the filename argument to nbd-server, and "X" is a number
  87 starting by 0 and going up for each file.
  88
  89 Allowing more flexibility for this option is planned for
  90 future versions.
  91 .TP
  92 \fB-c\fR
  93 Copy on write. When this option is provided,
  94 write-operations are not done to the exported file, but to a
  95 separate file. This separate file is removed when the
  96 connection is closed, which means that serving this way will
  97 make nbd-server slow down (especially on large block devices
  98 with lots of writes), and that after disconnecting and
  99 reconnecting the client or the server, all changes are
 100 lost.
 101 .TP
 102 \fB-C\fR
 103 Specify configuration file. The default configuration
 104 file, if this parameter is not specified, is
 105 \fI@sysconfdir@/nbd-server/config\fR\&.
 106
 107 Note that the configuration file is always parsed and
 108 the entries in the file used, even if an extra server is
 109 specified on the command line. To disable the configuration
 110 file entirely, either move it away or use the -C option to
 111 point \fBnbd-server\fR(1) to a non-existing or
 112 empty configuration file.
 113
 114 Also note that if an empty, incomplete, or invalid
 115 configuration file is specified, nbd-server will produce a
 116 warning about failure to parse the config file. If the
 117 command line contains a fully specified configuration, this
 118 warning is harmless and may be ignored.
 119 .TP
 120 \fBhost list filename\fR
 121 This argument should contain a list of IP-addresses
 122 for hosts that may connect to the server. Wildcards are
 123 \fBnot\fR allowed. If the file does not
 124 exist, it is ignored (and any host can connect); If the file
 125 does exist, but is empty, no host can connect. By default,
 126 the name 'nbd_server.allow' is used, and looked for in the
 127 current directory, unless nbd-server is compiled as a
 128 daemon, in which case it is looked for in the
 129 root-directory.
 130 .TP
 131 \fBsection name\fR
 132 If the \fB-o\fR argument is given on the
 133 command line, then nbd-server will output a configuration
 134 file section with this as the header that is functionally
 135 equivalent to the other options specified on the command line,
 136 and exit. This is useful for migrating pre-2.9 nbd-server
 137 initscript configuration files to the new format.
 138 .SH "EXAMPLES"
 139 .PP
 140 Some examples of nbd-server usage:
 141 .TP 0.2i
 142 \(bu
 143 To export a file /export/nbd/exp-bl-dev on port 2000:
 144
 145 \fBnbd-server 2000 /export/nbd/exp-bl-dev\fR
 146 .TP 0.2i
 147 \(bu
 148 To export a the same file read-only:
 149
 150 \fBnbd-server 2000 /export/nbd/exp-bl-dev -r\fR
 151 .TP 0.2i
 152 \(bu
 153 To export the same file read-write, but make sure
 154 changes are lost after restarting the client or the
 155 server:
 156
 157 \fBnbd-server 2000 /export/nbd/exp-bl-dev
 158 -c\fR
 159 .SH "SEE ALSO"
 160 .PP
 161 nbd-client (8), nbd-server (5), http://nbd.sourceforge.net/roadmap.html
 162 .SH "AUTHOR"
 163 .PP
 164 The NBD kernel module and the NBD tools were originally
 165 written by Pavel Machek (pavel@ucw.cz)
 166 .PP
 167 The Linux kernel module is now maintained by Paul Clements
 168 (Paul.Clements@steeleye.com), while the userland tools are
 169 maintained by Wouter Verhelst (<wouter@debian.org>)
 170 .PP
 171 On The Hurd there is a regular translator available to perform the
 172 client side of the protocol, and the use of
 173 \fBnbd-client\fR is not required. Please see the
 174 relevant documentation for more information.
 175 .PP
 176 This manual page was written by Wouter Verhelst (<wouter@debian.org>) for
 177 the Debian GNU/Linux system (but may be used by others).  Permission is
 178 granted to copy, distribute and/or modify this document under
 179 the terms of the GNU General Public License,
 180 version 2, as published by the Free Software Foundation.