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" "03 January 2009" "" ""
   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-a \fItimeout\fB\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. If
  35 omitted, 0.0.0.0 (aka "any address") is used.
  36 .TP
  37 \fBport \fR
  38 The port the server should listen to. A valid port is
  39 any number between 1 and 65536; if 0 is used, nbd-server
  40 will listen on stdin (so that nbd-server can be ran from
  41 inetd)
  42 .TP
  43 \fBfilename\fR
  44 The filename of the file that should be exported. This
  45 can be any file, including "real" blockdevices (i.e. a file
  46 from /dev). If the filename includes the literal string
  47 "%s", then this %s will be substituded with the IP-address
  48 of the client trying to connect.
  49 .TP
  50 \fBsize\fR
  51 The size of the block device at the client side. This
  52 is especially usefull in conjunction with the -m
  53 option
  54
  55 Can optionally be followed by one of K,k,M or
  56 m, in which case the size will be multiplied by 1024 (K
  57 or k) or 1048576 (M or m)
  58 .TP
  59 \fB-r\fR
  60 Export the file read-only. If a client tries to write
  61 to a read-only exported file, it will receive an error, but
  62 the connection will stay up.
  63 .TP
  64 \fB-m\fR
  65 Work with multiple files. This can be used to export
  66 blockdevices that are larger than the maximum allowed
  67 filesize on a given filesystem; i.e. when the filesystem
  68 does not allow files larger than 2GB (which is true for
  69 Linux 2.2 and below), you can use this option to store the
  70 data in multiple files and export a larger filesystem, if
  71 needed.
  72
  73 To use this option, you must create a number of files
  74 with names in the format "name.X", where "name" is given as
  75 the filename argument to nbd-server, and "X" is a number
  76 starting by 0 and going up for each file.
  77
  78 Allowing more flexibility for this option is planned for
  79 future versions.
  80 .TP
  81 \fB-c\fR
  82 Copy on write. When this option is provided,
  83 write-operations are not done to the exported file, but to a
  84 separate file. This separate file is removed when the
  85 connection is closed, which means that serving this way will
  86 make nbd-server slow down (especially on large block devices
  87 with lots of writes), and that after disconnecting and
  88 reconnecting the client or the server, all changes are
  89 lost.
  90 .TP
  91 \fB-C\fR
  92 Specify configuration file. The default configuration
  93 file, if this parameter is not specified, is
  94 \fI@sysconfdir@/nbd-server/config\fR\&.
  95
  96 Note that the configuration file is always parsed and
  97 the entries in the file used, even if an extra server is
  98 specified on the command line. To disable the configuration
  99 file entirely, either move it away or use the -C option to
 100 point \fBnbd-server\fR(1) to a non-existing or
 101 empty configuration file.
 102 .TP
 103 \fBtimeout\fR
 104 Maximum number of idle seconds. If a connection is
 105 inactive for this amount of time, it is terminated; this is to
 106 avoid stale nbd-server processes staying in memory. Use of
 107 this option is strongly recommended.
 108 .TP
 109 \fBhost list filename\fR
 110 This argument should contain a list of IP-addresses
 111 for hosts that may connect to the server. Wildcards are
 112 \fBnot\fR allowed. If the file does not
 113 exist, it is ignored (and any host can connect); If the file
 114 does exist, but is empty, no host can connect. By default,
 115 the name 'nbd_server.allow' is used, and looked for in the
 116 current directory, unless nbd-server is compiled as a
 117 daemon, in which case it is looked for in the
 118 root-directory.
 119 .TP
 120 \fBsection name\fR
 121 If the \fB-o\fR argument is given on the
 122 command line, then nbd-server will output a configuration
 123 file section with this as the header that is functionally
 124 equivalent to the other options specified on the command line,
 125 and exit. This is useful for migrating pre-2.9 nbd-server
 126 initscript configuration files to the new format.
 127 .SH "EXAMPLES"
 128 .PP
 129 Some examples of nbd-server usage:
 130 .TP 0.2i
 131 \(bu
 132 To export a file /export/nbd/exp-bl-dev on port 2000:
 133
 134 \fBnbd-server 2000 /export/nbd/exp-bl-dev\fR
 135 .TP 0.2i
 136 \(bu
 137 To export a the same file read-only:
 138
 139 \fBnbd-server 2000 /export/nbd/exp-bl-dev -r\fR
 140 .TP 0.2i
 141 \(bu
 142 To export the same file read-write, but make sure
 143 changes are lost after restarting the client or the
 144 server:
 145
 146 \fBnbd-server 2000 /export/nbd/exp-bl-dev
 147 -c\fR
 148 .SH "SEE ALSO"
 149 .PP
 150 nbd-client (8), nbd-server (5), http://nbd.sourceforge.net/roadmap.html
 151 .SH "AUTHOR"
 152 .PP
 153 The NBD kernel module and the NBD tools were originally
 154 written by Pavel Machek (pavel@ucw.cz)
 155 .PP
 156 The Linux kernel module is now maintained by Paul Clements
 157 (Paul.Clements@steeleye.com), while the userland tools are
 158 maintained by Wouter Verhelst (<wouter@debian.org>)
 159 .PP
 160 On The Hurd there is a regular translator available to perform the
 161 client side of the protocol, and the use of
 162 \fBnbd-client\fR is not required. Please see the
 163 relevant documentation for more information.
 164 .PP
 165 This manual page was written by Wouter Verhelst (<wouter@debian.org>) for
 166 the Debian GNU/Linux system (but may be used by others).  Permission is
 167 granted to copy, distribute and/or modify this document under
 168 the terms of the GNU General Public License,
 169 version 2, as published by the Free Software Foundation.