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