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" "18 July 2009" "" ""
   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 While
  20 \fI@sysconfdir@/nbd-server/config\fR is the default
  21 configuration file, this can be varied with the \fB-C\fR
  22 option to \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 \fBcopyonwrite\fR
  97 Optional; boolean.
  98
  99 Whether this is a copy-on-write export. If it is, then any
 100 writes to this export will not be written to the master
 101 file, but to a separate file which will be removed upon
 102 disconnect. The result of using this option is that
 103 nbd-server will be slower, and that any writes will be
 104 lost upon disconnect.
 105
 106 Corresponds to the \fB-c\fR option on the
 107 command line
 108 .TP
 109 \fBexportname\fR
 110 Required; string.
 111
 112 The name of the file that will be exported. This must be a
 113 fully-qualified path and filename; relative paths are not
 114 allowed.
 115
 116 Note that \fBnbd-server\fR will only try to
 117 find and open the exported file when a client actually
 118 connects; as a result, \fBnbd-server\fR must
 119 be able to open and read this file
 120 \fBafter\fR changing to the user and group
 121 that have been specified by use of the
 122 \fBuser\fR and \fBgroup\fR options;
 123 also, \fBnbd-server\fR will only detect
 124 errors in this option upon connection of a client.
 125
 126 When specified on the command line, this should be the
 127 second argument.
 128 .TP
 129 \fBfilesize\fR
 130 Optional; integer; default autodetected.
 131
 132 Disable autodetection of file or block device size, and
 133 forcibly specify a size. Sizes must be specified in
 134 bytes. If the \fBmultifile\fR option is in
 135 effect, this option specifies the size of the
 136 \fBentire\fR export, not of individual
 137 files.
 138
 139 When specified on the command line, this should be the
 140 third argument.
 141 .TP
 142 \fBlistenaddr\fR
 143 Optional; string
 144
 145 If this option is set, it should contain the local IP
 146 address (in "dotted-quad" notation) on which we should
 147 listen to \fBnbd-client\fR(8) connections. If
 148 it is not set, 0.0.0.0 is used (i.e., "listen on all local
 149 IP addresses")
 150 .TP
 151 \fBmultifile\fR
 152 Optional; boolean.
 153
 154 If this option is set to true, then
 155 \fBnbd-server\fR will search for files of the
 156 form
 157 \fIexportname\fR\&.\fIinteger\fR,
 158 with \fIexportname\fR being the
 159 filename that would otherwise have been used (after
 160 name transformation for virtualization, if any, has been
 161 performed) and \fIinteger\fR an
 162 integer number, starting with 0 and ending when no more
 163 files can be found.
 164
 165 The size of the individual files will be autodetected,
 166 \fBeven\fR if the \fBfilesize\fR
 167 option has been specified. See the documentation for the
 168 \fBmultifile\fR for details.
 169
 170 Corresponds to the \fB-m\fR option on the
 171 command line.
 172 .TP
 173 \fBport\fR
 174 Required; integer.
 175
 176 The port on which this export is to be served. Currently
 177 it is not possible to export multiple block devices on the
 178 same port unless virtualization is used; future versions
 179 of \fBnbd-server\fR may add this
 180 functionality.
 181
 182 When specified on the command line, this should be the
 183 first argument.
 184 .TP
 185 \fBreadonly\fR
 186 Optional; boolean.
 187
 188 Disallow writes to the device. If this option is
 189 specified, \fBnbd-server\fR will issue an
 190 error to any client that tries to write to the device.
 191
 192 Use of this option in conjunction with
 193 \fBcopyonwrite\fR is possible, but silly.
 194
 195 Corresponds to the \fB-r\fR option on the
 196 command line.
 197 .TP
 198 \fBsdp\fR
 199 Optional; boolean.
 200
 201 When this option is enabled, \fBnbd-server\fR
 202 will use the Socket Direct Protocol (SDP) to serve the
 203 export, rather than just IP. This is faster, but requires
 204 special hardware (usually something like InfiniBand) and
 205 support in the kernel.
 206
 207 Additionally, support for this option must be enabled at
 208 compile time, using the \fB--enable-sdp\fR option
 209 to the \fBconfigure\fR script. If this option
 210 is found in a configuration file and
 211 \fBnbd-server\fR does not have support for SDP,
 212 then \fBnbd-server\fR will exit with an error
 213 message.
 214 .TP
 215 \fBsync\fR
 216 Optional; boolean.
 217
 218 When this option is enabled,
 219 \fBnbd-server\fR will call an fsync() after every
 220 write to the backend storage. Calling fsync() increases
 221 reliability in case of an unclean shutdown of nbd-server; but,
 222 depending on the file system used on the nbd-server side, may
 223 degrade performance. The use of this option isn't always
 224 necessary; e.g., on ext3 filesystems, it is recommended that
 225 it is \fBnot\fR enabled, since it seriously
 226 reduces performance on ext3 filesystems while not
 227 importantly impacting reliability.
 228 .TP
 229 \fBsparse_cow\fR
 230 Optional; boolean.
 231
 232 When this option is enabled, \fBnbd-server\fR
 233 will use sparse files to implement the copy-on-write
 234 option; such files take up less space then they appear to,
 235 which allows \fBnbd-server\fR to handle the
 236 file as if it was just as large as the block device it's
 237 for.
 238
 239 If this option is disabled, \fBnbd-server\fR
 240 will map every newly written block to the end of the
 241 copy-on-write file, which means that
 242 \fBnbd-server\fR will have to lseek(2) to the
 243 right position after every 4096-byte block.
 244
 245 Using this option may be faster when much is being written
 246 during a connection.
 247 .TP
 248 \fBtimeout\fR
 249 Optional; integer; default 0
 250
 251 How many seconds a connection may be idle for this
 252 export. When a connection is idle for a longer time,
 253 \fBnbd-server\fR will forcibly disconnect the
 254 connection. If you specify 0 (the default), then a
 255 connection may be idle forever.
 256
 257 Corresponds to the \fB-a\fR option on the
 258 command line
 259 .TP
 260 \fBvirtstyle\fR
 261 Optional; string; default "ipliteral"
 262
 263 Defines the style of virtualization. Virtualization allows
 264 one to create one export that will serve a different file
 265 depending on the IP address that is connecting. When
 266 virtualization is There are three types of virtualization
 267 that \fBnbd-server\fR supports:
 268 .RS
 269 .TP
 270 \fBnone\fR
 271 No virtualization. Will attempt to open the filename
 272 as it was written, even if it contains '%s' in the
 273 name.
 274 .TP
 275 \fBipliteral\fR
 276 \fBnbd-server\fR will look for the
 277 literal string '%s' in the
 278 \fBexportname\fR, and replace it by the
 279 IP address of the connecting host in dotted-quad
 280 notation. The string that results from this
 281 transformation will be used as an absolute pathname
 282 that \fBnbd-server\fR will attempt to
 283 open. As an example, if a client connects from
 284 192.168.1.100 and \fBexportname\fR is
 285 specified as \fI/export/%s\fR, then
 286 nbd-server will attempt to serve
 287 \fI/export/192.168.1.100\fR
 288 .TP
 289 \fBiphash\fR
 290 Same as above, except that
 291 \fBnbd-server\fR will replace the dots
 292 in the IP address by forward slashes ('/'); in the
 293 same example, \fBnbd-server\fR would
 294 open \fI/export/192/168/1/100\fR
 295 instead.
 296 .TP
 297 \fBcidrhash\fR
 298 This option requires one to add a space and a number
 299 after it. \fBnbd-server\fR will use the
 300 number as a network mask in CIDR style, and use that
 301 as a hash cutoff point. In the above example, if
 302 \fBvirtstyle\fR has been specified as
 303 cidrhash 16, then
 304 \fBnbd-server\fR will try to open
 305 \fI/export/192.168.0.0/192.168.1.100\fR;
 306 if \fBvirtstyle\fR were specified as
 307 cidrhash 26, then
 308 \fBnbd-server\fR will try to open
 309 \fI/export/192.168.1.64/192.168.1.100\fR\&.
 310 .RE
 311 .TP
 312 \fBprerun\fR
 313 Optional; string
 314
 315 If specified, then this command will be ran after a
 316 client has connected to the server (and has been
 317 accepted), but before the server starts serving. If
 318 the command contains the literal string '%s', then
 319 this string will be replaced by the filename of the
 320 file which nbd-server wants to export.
 321
 322 This is useful to create export files on the fly, or
 323 to verify that a file can be used for export, to
 324 write something to a log file, or similar.
 325
 326 If the command runs with a non-zero exit status,
 327 then nbd-server will assume the export will fail,
 328 and refuse to serve it.
 329 .TP
 330 \fBpostrun\fR
 331 Optional; string
 332
 333 If specified, then it is assumed to be a command
 334 that will be ran when a client has
 335 disconnected. This can be useful to clean up
 336 whatever \fBprerun\fR has set up, to log
 337 something, or similar.
 338
 339 If the literal string '%s' is present in the
 340 command, it will be replaced by the file name that
 341 has just been closed.
 342
 343 In contrast to the \fBprerun\fR option,
 344 the exit state of \fBpostrun\fR is
 345 \fBignored\fR\&.
 346 .SH "SEE ALSO"
 347 .PP
 348 nbd-server (1), nbd-client (8),
 349 http://nbd.sourceforge.net/roadmap.html
 350 .SH "AUTHOR"
 351 .PP
 352 The NBD kernel module and the NBD tools were originally
 353 written by Pavel Machek (pavel@ucw.cz)
 354 .PP
 355 The Linux kernel module is now maintained by Paul Clements
 356 (Paul.Clements@steeleye.com), while the userland tools are
 357 maintained by Wouter Verhelst (<wouter@debian.org>)
 358 .PP
 359 On The Hurd there is a regular translator available to perform the
 360 client side of the protocol, and the use of
 361 \fBnbd-client\fR is not required. Please see the
 362 relevant documentation for more information.
 363 .PP
 364 This manual page was written by Wouter Verhelst (<wouter@debian.org>) for
 365 the Debian GNU/Linux system (but may be used by others).  Permission is
 366 granted to copy, distribute and/or modify this document under
 367 the terms of the GNU General Public License,
 368 version 2, as published by the Free Software Foundation.
 369 .SH "EXAMPLES"
 370 .PP
 371 A simple \fBnbd-server\fR configuration file
 372 would look like this:
 373
 374 .nf
 375       [generic]
 376       [export]
 377           exportname = /export/blkdev
 378           port = 12345
 379
 380 .fi
 381 .PP
 382 For increased security, one might want to create an
 383 authorization file, and set the UID and GID to run as:
 384
 385 .nf
 386       [generic]
 387           user = nbd
 388           group = nbd
 389       [export]
 390           exportname = /export/blkdev
 391           port = 12345
 392           authfile = /etc/nbd-server/allow
 393
 394 .fi
 395 .PP
 396 With /etc/nbd-server/allow containing the following:
 397
 398 .nf
 399       127.0.0.1
 400       192.168.0.0/8
 401       192.168.1.1
 402
 403 .fi