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" "03 January 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 \fBsparse_cow\fR
 216 Optional; boolean.
 217
 218 When this option is enabled, \fBnbd-server\fR
 219 will use sparse files to implement the copy-on-write
 220 option; such files take up less space then they appear to,
 221 which allows \fBnbd-server\fR to handle the
 222 file as if it was just as large as the block device it's
 223 for.
 224
 225 If this option is disabled, \fBnbd-server\fR
 226 will map every newly written block to the end of the
 227 copy-on-write file, which means that
 228 \fBnbd-server\fR will have to lseek(2) to the
 229 right position after every 4096-byte block.
 230
 231 Using this option may be faster when much is being written
 232 during a connection.
 233 .TP
 234 \fBtimeout\fR
 235 Optional; integer; default 0
 236
 237 How many seconds a connection may be idle for this
 238 export. When a connection is idle for a longer time,
 239 \fBnbd-server\fR will forcibly disconnect the
 240 connection. If you specify 0 (the default), then a
 241 connection may be idle forever.
 242
 243 Corresponds to the \fB-a\fR option on the
 244 command line
 245 .TP
 246 \fBvirtstyle\fR
 247 Optional; string; default "ipliteral"
 248
 249 Defines the style of virtualization. Virtualization allows
 250 one to create one export that will serve a different file
 251 depending on the IP address that is connecting. When
 252 virtualization is There are three types of virtualization
 253 that \fBnbd-server\fR supports:
 254 .RS
 255 .TP
 256 \fBnone\fR
 257 No virtualization. Will attempt to open the filename
 258 as it was written, even if it contains '%s' in the
 259 name.
 260 .TP
 261 \fBipliteral\fR
 262 \fBnbd-server\fR will look for the
 263 literal string '%s' in the
 264 \fBexportname\fR, and replace it by the
 265 IP address of the connecting host in dotted-quad
 266 notation. The string that results from this
 267 transformation will be used as an absolute pathname
 268 that \fBnbd-server\fR will attempt to
 269 open. As an example, if a client connects from
 270 192.168.1.100 and \fBexportname\fR is
 271 specified as \fI/export/%s\fR, then
 272 nbd-server will attempt to serve
 273 \fI/export/192.168.1.100\fR
 274 .TP
 275 \fBiphash\fR
 276 Same as above, except that
 277 \fBnbd-server\fR will replace the dots
 278 in the IP address by forward slashes ('/'); in the
 279 same example, \fBnbd-server\fR would
 280 open \fI/export/192/168/1/100\fR
 281 instead.
 282 .TP
 283 \fBcidrhash\fR
 284 This option requires one to add a space and a number
 285 after it. \fBnbd-server\fR will use the
 286 number as a network mask in CIDR style, and use that
 287 as a hash cutoff point. In the above example, if
 288 \fBvirtstyle\fR has been specified as
 289 cidrhash 16, then
 290 \fBnbd-server\fR will try to open
 291 \fI/export/192.168.0.0/192.168.1.100\fR;
 292 if \fBvirtstyle\fR were specified as
 293 cidrhash 26, then
 294 \fBnbd-server\fR will try to open
 295 \fI/export/192.168.1.64/192.168.1.100\fR\&.
 296 .RE
 297 .TP
 298 \fBprerun\fR
 299 Optional; string
 300
 301 If specified, then this command will be ran after a
 302 client has connected to the server (and has been
 303 accepted), but before the server starts serving. If
 304 the command contains the literal string '%s', then
 305 this string will be replaced by the filename of the
 306 file which nbd-server wants to export.
 307
 308 This is useful to create export files on the fly, or
 309 to verify that a file can be used for export, to
 310 write something to a log file, or similar.
 311
 312 If the command runs with a non-zero exit status,
 313 then nbd-server will assume the export will fail,
 314 and refuse to serve it.
 315 .TP
 316 \fBpostrun\fR
 317 Optional; string
 318
 319 If specified, then it is assumed to be a command
 320 that will be ran when a client has
 321 disconnected. This can be useful to clean up
 322 whatever \fBprerun\fR has set up, to log
 323 something, or similar.
 324
 325 If the literal string '%s' is present in the
 326 command, it will be replaced by the file name that
 327 has just been closed.
 328
 329 In contrast to the \fBprerun\fR option,
 330 the exit state of \fBpostrun\fR is
 331 \fBignored\fR\&.
 332 .SH "SEE ALSO"
 333 .PP
 334 nbd-server (1), nbd-client (8),
 335 http://nbd.sourceforge.net/roadmap.html
 336 .SH "AUTHOR"
 337 .PP
 338 The NBD kernel module and the NBD tools were originally
 339 written by Pavel Machek (pavel@ucw.cz)
 340 .PP
 341 The Linux kernel module is now maintained by Paul Clements
 342 (Paul.Clements@steeleye.com), while the userland tools are
 343 maintained by Wouter Verhelst (<wouter@debian.org>)
 344 .PP
 345 On The Hurd there is a regular translator available to perform the
 346 client side of the protocol, and the use of
 347 \fBnbd-client\fR is not required. Please see the
 348 relevant documentation for more information.
 349 .PP
 350 This manual page was written by Wouter Verhelst (<wouter@debian.org>) for
 351 the Debian GNU/Linux system (but may be used by others).  Permission is
 352 granted to copy, distribute and/or modify this document under
 353 the terms of the GNU General Public License,
 354 version 2, as published by the Free Software Foundation.
 355 .SH "EXAMPLES"
 356 .PP
 357 A simple \fBnbd-server\fR configuration file
 358 would look like this:
 359
 360 .nf
 361       [generic]
 362       [export]
 363           exportname = /export/blkdev
 364           port = 12345
 365
 366 .fi
 367 .PP
 368 For increased security, one might want to create an
 369 authorization file, and set the UID and GID to run as:
 370
 371 .nf
 372       [generic]
 373           user = nbd
 374           group = nbd
 375       [export]
 376           exportname = /export/blkdev
 377           port = 12345
 378           authfile = /etc/nbd-server/allow
 379
 380 .fi
 381 .PP
 382 With /etc/nbd-server/allow containing the following:
 383
 384 .nf
 385       127.0.0.1
 386       192.168.0.0/8
 387       192.168.1.1
 388
 389 .fi