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" "23 May 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-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 \fBhost list filename\fR
 104 This argument should contain a list of IP-addresses
 105 for hosts that may connect to the server. Wildcards are
 106 \fBnot\fR allowed. If the file does not
 107 exist, it is ignored (and any host can connect); If the file
 108 does exist, but is empty, no host can connect. By default,
 109 the name 'nbd_server.allow' is used, and looked for in the
 110 current directory, unless nbd-server is compiled as a
 111 daemon, in which case it is looked for in the
 112 root-directory.
 113 .TP
 114 \fBsection name\fR
 115 If the \fB-o\fR argument is given on the
 116 command line, then nbd-server will output a configuration
 117 file section with this as the header that is functionally
 118 equivalent to the other options specified on the command line,
 119 and exit. This is useful for migrating pre-2.9 nbd-server
 120 initscript configuration files to the new format.
 121 .SH "EXAMPLES"
 122 .PP
 123 Some examples of nbd-server usage:
 124 .TP 0.2i
 125 \(bu
 126 To export a file /export/nbd/exp-bl-dev on port 2000:
 127
 128 \fBnbd-server 2000 /export/nbd/exp-bl-dev\fR
 129 .TP 0.2i
 130 \(bu
 131 To export a the same file read-only:
 132
 133 \fBnbd-server 2000 /export/nbd/exp-bl-dev -r\fR
 134 .TP 0.2i
 135 \(bu
 136 To export the same file read-write, but make sure
 137 changes are lost after restarting the client or the
 138 server:
 139
 140 \fBnbd-server 2000 /export/nbd/exp-bl-dev
 141 -c\fR
 142 .SH "SEE ALSO"
 143 .PP
 144 nbd-client (8), nbd-server (5), http://nbd.sourceforge.net/roadmap.html
 145 .SH "AUTHOR"
 146 .PP
 147 The NBD kernel module and the NBD tools were originally
 148 written by Pavel Machek (pavel@ucw.cz)
 149 .PP
 150 The Linux kernel module is now maintained by Paul Clements
 151 (Paul.Clements@steeleye.com), while the userland tools are
 152 maintained by Wouter Verhelst (<wouter@debian.org>)
 153 .PP
 154 On The Hurd there is a regular translator available to perform the
 155 client side of the protocol, and the use of
 156 \fBnbd-client\fR is not required. Please see the
 157 relevant documentation for more information.
 158 .PP
 159 This manual page was written by Wouter Verhelst (<wouter@debian.org>) for
 160 the Debian GNU/Linux system (but may be used by others).  Permission is
 161 granted to copy, distribute and/or modify this document under
 162 the terms of the GNU General Public License,
 163 version 2, as published by the Free Software Foundation.