nbd-server.5.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" "5" "25 oktober 2006" "" ""
   7
   8 .SH NAME
   9 /etc/nbd-server/config \- configuration file for nbd-server
  10 .SH SYNOPSIS
  11
  12 \fB/etc/nbd-server/config \fR
  13
  14 .SH "DESCRIPTION"
  15 .PP
  16 \fB/etc/nbd-server/config\fR allows to configure the
  17 nbd-server.
  18 .PP
  19 The default configuration file is
  20 \fI@sysconfdir@/nbd-server/config\fR, but this
  21 can be varied with the \fB-C\fR option to
  22 \fBnbd-server\fR(1).
  23 .PP
  24 The configuration file consists of section header lines, comment
  25 lines, and option lines.
  26 .PP
  27 A section header is a unique name that
  28 is enclosed in square brackets ("[" and "]"). A section header
  29 denotes the beginning of a section; a section continues until
  30 the next section or the end of the file, whichever is first. The
  31 first section in the configuration file must be called
  32 \fBgeneric\fR, and is used for global options that
  33 apply to more than one export. This section must always be
  34 present, even if it holds no options. Every other section
  35 defines one export; the names of these sections are not
  36 important, except that you should take care to make sure that
  37 each section name is unique (future versions of
  38 \fBnbd-server\fR may use the section name to refer
  39 to an export)
  40 .PP
  41 A comment line is a line that starts with optional whitespace,
  42 followed by a pound sign ("#"), and continues until the end of
  43 the line. Comments may \fBnot\fR be used on
  44 option lines or section header lines.
  45 .PP
  46 An option line is a line that starts with an option name,
  47 followed by an equals sign ("="), followed by the option
  48 value. An option can be of type string, of type integer, or of
  49 type boolean. The value of a boolean option can be denoted with
  50 either true or false (so not yes, no, on, off, 1, or 0); all
  51 booleans default to false unless specified otherwise; no value
  52 may be quoted (always enter it directly); for a string option,
  53 leading whitespace is stripped (but trailing whitespace is not).
  54 .SH "OPTIONS FOR SECTION [GENERIC]"
  55 .TP
  56 \fBgroup\fR
  57 Optional; string.
  58
  59 The name of the group this server must run as. If this
  60 parameter is not specified, then nbd-server will not
  61 attempt to change its GID (so the GID it runs as will be
  62 the primary group of the user who starts nbd-server). If
  63 it is specified, then nbd-server will change its GID after
  64 opening ports, but before accepting connections or opening
  65 files.
  66 .TP
  67 \fBuser\fR
  68 Optional; string.
  69
  70 The name of the user this server must run as. If this
  71 parameter is not specified, then nbd-server will not
  72 attempt to change its UID (so the UID it runs as will be
  73 the user who starts nbd-server). If it is specified, then
  74 nbd-server will change its UID after opening ports, but
  75 before accepting connections or opening files.
  76 .SH "OPTIONS FOR EXPORT SECTIONS"
  77 .TP
  78 \fBauthfile\fR
  79 Optional; string; default
  80 \fI@sysconfdir@/nbd-server/allow\fR\&.
  81
  82 The name of the authorization file for this export. This
  83 file should contain one line per IP-address, or per
  84 network (which must be specified in CIDR-style
  85 \fB\fInetwork\fB/\fImasklen\fB\fR)
  86 and must not contain empty lines. If the file
  87 does not exist, everyone is allowed to connect. If the
  88 file exists but is empty, nobody is allowed to
  89 connect. Otherwise, \fBnbd-server\fR will
  90 only allow clients to connect whose IP-adres is listed in
  91 this file.
  92
  93 Corresponds to the \fB-l\fR option on the
  94 command line
  95 .TP
  96 \fBautoreadonly\fR
  97 Optional; boolean.
  98
  99 If this option is set to true, then
 100 \fBnbd-server\fR will automatically switch to
 101 readonly if it cannot write to the file.
 102
 103 Does not have a corresponding command-line
 104 argument
 105
 106 TODO: verify whether this option actually works as
 107 documented. I have a feeling I've been terribly
 108 stupid.
 109 .TP
 110 \fBcopyonwrite\fR
 111 Optional; boolean.
 112
 113 Whether this is a copy-on-write export. If it is, then any
 114 writes to this export will not be written to the master
 115 file, but to a separate file which will be removed upon
 116 disconnect. The result of using this option is that
 117 nbd-server will be slower, and that any writes will be
 118 lost upon disconnect.
 119
 120 Corresponds to the \fB-c\fR option on the
 121 command line
 122 .TP
 123 \fBexportname\fR
 124 Required; string.
 125
 126 The name of the file that will be exported. This must be a
 127 fully-qualified path and filename; relative paths are not
 128 allowed.
 129
 130 Note that \fBnbd-server\fR will only try to
 131 find and open the exported file when a client actually
 132 connects; as a result, \fBnbd-server\fR must
 133 be able to open and read this file
 134 \fBafter\fR changing to the user and group
 135 that have been specified by use of the
 136 \fBuser\fR and \fBgroup\fR options;
 137 also, \fBnbd-server\fR will only detect
 138 errors in this option upon connection of a client.
 139
 140 When specified on the command line, this should be the
 141 second argument.
 142 .TP
 143 \fBfilesize\fR
 144 Optional; integer; default autodetected.
 145
 146 Disable autodetection of file or block device size, and
 147 forcibly specify a size. Sizes must be specified in
 148 bytes. If the \fBmultifile\fR option is in
 149 effect, this option specifies the size of the
 150 \fBentire\fR export, not of individual
 151 files.
 152
 153 When specified on the command line, this should be the
 154 third argument.
 155 .TP
 156 \fBmultifile\fR
 157 Optional; boolean.
 158
 159 If this option is set to true, then
 160 \fBnbd-server\fR will search for files of the
 161 form
 162 \fIexportname\fR\&.\fIinteger\fR,
 163 with \fIexportname\fR being the
 164 filename that would otherwise have been used (after
 165 name transformation for virtualization, if any, has been
 166 performed) and \fIinteger\fR an
 167 integer number, starting with 0 and ending when no more
 168 files can be found.
 169
 170 The size of the individual files will be autodetected,
 171 \fBeven\fR if the \fBfilesize\fR
 172 option has been specified. See the documentation for the
 173 \fBmultifile\fR for details.
 174
 175 Corresponds to the \fB-m\fR option on the
 176 command line.
 177 .TP
 178 \fBport\fR
 179 Required; integer.
 180
 181 The port on which this export is to be served. Currently
 182 it is not possible to export multiple block devices on the
 183 same port unless virtualization is used; future versions
 184 of \fBnbd-server\fR may add this
 185 functionality.
 186
 187 When specified on the command line, this should be the
 188 first argument.
 189 .TP
 190 \fBreadonly\fR
 191 Optional; boolean.
 192
 193 Disallow writes to the device. If this option is
 194 specified, \fBnbd-server\fR will issue an
 195 error to any client that tries to write to the device.
 196
 197 Use of this option in conjunction with
 198 \fBcopyonwrite\fR is possible, but silly.
 199
 200 Corresponds to the \fB-r\fR option on the
 201 command line.
 202 .TP
 203 \fBsparse_cow\fR
 204 Optional; boolean.
 205
 206 When this option is enabled, \fBnbd-server\fR
 207 will use sparse files to implement the copy-on-write
 208 option; such files take up less space then they appear to,
 209 which allows \fBnbd-server\fR to handle the
 210 file as if it was just as large as the block device it's for.
 211
 212 If this option is disabled, \fBnbd-server\fR
 213 will map every newly written block to the end of the
 214 copy-on-write file, which means that
 215 \fBnbd-server\fR will have to lseek(2) to the
 216 right position after every 4096-byte block.
 217
 218 Using this option may be faster when much is being written
 219 during a connection.
 220 .TP
 221 \fBtimeout\fR
 222 Optional; integer; default 0
 223
 224 How many seconds a connection may be idle for this
 225 export. When a connection is idle for a longer time,
 226 \fBnbd-server\fR will forcibly disconnect the
 227 connection. If you specify 0 (the default), then a
 228 connection may be idle forever.
 229
 230 Corresponds to the \fB-a\fR option on the
 231 command line
 232 .TP
 233 \fBvirtstyle\fR
 234 Optional; string; default "ipliteral"
 235
 236 Defines the style of virtualization. Virtualization allows
 237 one to create one export that will serve a different file
 238 depending on the IP address that is connecting. When
 239 virtualization is There are three types of virtualization
 240 that \fBnbd-server\fR supports:
 241 .RS
 242 .TP
 243 \fBnone\fR
 244 No virtualization. Will attempt to open the filename
 245 as it was written, even if it contains '%s' in the
 246 name.
 247 .TP
 248 \fBipliteral\fR
 249 \fBnbd-server\fR will look for the
 250 literal string '%s' in the
 251 \fBexportname\fR, and replace it by the
 252 IP address of the connecting host in dotted-quad
 253 notation. The string that results from this
 254 transformation will be used as an absolute pathname
 255 that \fBnbd-server\fR will attempt to
 256 open. As an example, if a client connects from
 257 192.168.1.100 and \fBexportname\fR is
 258 specified as \fI/export/%s\fR, then
 259 nbd-server will attempt to serve
 260 \fI/export/192.168.1.100\fR
 261 .TP
 262 \fBiphash\fR
 263 Same as above, except that
 264 \fBnbd-server\fR will replace the dots
 265 in the IP address by forward slashes ('/'); in the
 266 same example, \fBnbd-server\fR would
 267 open \fI/export/192/168/1/100\fR
 268 instead.
 269 .TP
 270 \fBcidrhash\fR
 271 This option requires one to add a space and a number
 272 after it. \fBnbd-server\fR will use the
 273 number as a network mask in CIDR style, and use that
 274 as a hash cutoff point. In the above example, if
 275 \fBvirtstyle\fR has been specified
 276 as cidrhash 16, then
 277 \fBnbd-server\fR will try to open
 278 \fI/export/192.168.0.0/192.168.1.100\fR; if
 279 \fBvirtstyle\fR were specified as
 280 cidrhash 26, then
 281 \fBnbd-server\fR will try to open
 282 \fI/export/192.168.1.64/192.168.1.100\fR\&.
 283 .RE
 284 .SH "SEE ALSO"
 285 .PP
 286 nbd-server (1), nbd-client (8),
 287 http://nbd.sourceforge.net/roadmap.html
 288 .SH "AUTHOR"
 289 .PP
 290 The NBD kernel module and the NBD tools were originally
 291 written by Pavel Machek (pavel@ucw.cz)
 292 .PP
 293 The Linux kernel module is now maintained by Paul Clements
 294 (Paul.Clements@steeleye.com), while the userland tools are
 295 maintained by Wouter Verhelst (<wouter@debian.org>)
 296 .PP
 297 On The Hurd there is a regular translator available to perform the
 298 client side of the protocol, and the use of
 299 \fBnbd-client\fR is not required. Please see the
 300 relevant documentation for more information.
 301 .PP
 302 This manual page was written by Wouter Verhelst (<wouter@debian.org>) for
 303 the Debian GNU/Linux system (but may be used by others).  Permission is
 304 granted to copy, distribute and/or modify this document under
 305 the terms of the GNU General Public License,
 306 version 2, as published by the Free Software Foundation.
 307 .SH "EXAMPLES"
 308 .PP
 309 A simple \fBnbd-server\fR configuration file
 310 would look like this:
 311
 312 .nf
 313       [generic]
 314       [export]
 315           exportname = /export/blkdev
 316           port = 12345
 317
 318 .fi
 319 .PP
 320 For increased security, one might want to create an
 321 authorization file, and set the UID and GID to run as:
 322
 323 .nf
 324       [generic]
 325           user = nbd
 326           group = nbd
 327       [export]
 328           exportname = /export/blkdev
 329           port = 12345
 330           authfile = /etc/nbd-server/allow
 331
 332 .fi
 333 .PP
 334 With /etc/nbd-server/allow containing the following:
 335
 336 .nf
 337       127.0.0.1
 338       192.168.0.0/8
 339       192.168.1.1
 340
 341 .fi