NBD-SERVER

Name

${prefix}/etc/nbd-server/config -- configuration file for nbd-server

Synopsis

${prefix}/etc/nbd-server/config

DESCRIPTION

${prefix}/etc/nbd-server/config allows to configure the nbd-server.

While ${prefix}/etc/nbd-server/config is the default configuration file, this can be varied with the -C option to nbd-server(1).

The configuration file consists of section header lines, comment lines, and option lines.

A section header is a unique name that is enclosed in square brackets ("[" and "]"). A section header denotes the beginning of a section; a section continues until the next section or the end of the file, whichever is first. The first section in the configuration file must be called generic, and is used for global options that apply to more than one export. This section must always be present, even if it holds no options. Every other section defines one export; the names of these sections are not important, except that you should take care to make sure that each section name is unique. The section name is used as the name for the export in case the client connects with a name rather than a port to specify an export, and must therefore be unique.

A comment line is a line that starts with optional whitespace, followed by a pound sign ("#"), and continues until the end of the line. Comments may not be used on option lines or section header lines.

An option line is a line that starts with an option name, followed by an equals sign ("="), followed by the option value. An option can be of type string, of type integer, or of type boolean. The value of a boolean option can be denoted with either true or false (so not yes, no, on, off, 1, or 0). All booleans default to false unless specified otherwise. No value may be quoted; always enter it directly. For a string option, leading whitespace is stripped (but trailing whitespace is not).

OPTIONS FOR SECTION [generic]

group

Optional; string.

The name of the group this server must run as. If this parameter is not specified, then nbd-server will not attempt to change its GID (so the GID it runs as will be the primary group of the user who starts nbd-server). If it is specified, then nbd-server will change its GID after opening ports, but before accepting connections or opening files.

user

Optional; string.

The name of the user this server must run as. If this parameter is not specified, then nbd-server will not attempt to change its UID (so the UID it runs as will be the user who starts nbd-server). If it is specified, then nbd-server will change its UID after opening ports, but before accepting connections or opening files.

oldstyle

Optional; boolean

If this option is set to true, nbd-server will export all exports on a separate port with the old (pre-2.9.17) handshake protocol. In that case, the 'port' option for individual exports is mandatory.

If the option is set to false, the 'port' option for individual exports is optional (and will be ignored if specified). The server will only export devices on the standard port.

For upgrades from pre-2.9.17 versions of nbd, it may be appropriate to enable the oldstyle parameter until all clients have been converted to using name-based exports.

Note that exports specified on the command line will always use the old handshake protocol and will not allow name-based exports.

Also note that even if this parameter is set to true, all exports will also be made available using the new handshake protocol; it is not possible to switch that off. The reason for this is that the old style protocol will eventually be deprecated, and this option is only available to allow for smooth upgrades.

listenaddr

Optional; string

If this option is set, it should contain the local IP address on which we should listen to nbd-client(8) connections. If it is not set, nbd-server will listen to all local IPv4 and IPv6 addresses. To limit to IPv6, specify the address as "::". To limit to IPv4, specify as "0.0.0.0". It is not possible to specify more than one IP address here.

OPTIONS FOR EXPORT SECTIONS

authfile

Optional; string; default ${prefix}/etc/nbd-server/allow.

The name of the authorization file for this export. This file should contain one line per IP-address, or per network (which must be specified in CIDR-style network/masklen) and must not contain empty lines. If the file does not exist, everyone is allowed to connect. If the file exists but is empty, nobody is allowed to connect. Otherwise, nbd-server will only allow clients to connect whose IP-adres is listed in this file.

Corresponds to the -l option on the command line

copyonwrite

Optional; boolean.

Whether this is a copy-on-write export. If it is, then any writes to this export will not be written to the master file, but to a separate file which will be removed upon disconnect. The result of using this option is that nbd-server will be somewhat slower, and that any writes will be lost upon disconnect.

Corresponds to the -c option on the command line

exportname

Required; string.

The name of the file (or block device) that will be exported. This must be a fully-qualified path and filename; relative paths are not allowed.

Note that nbd-server will only try to find and open the exported file when a client actually connects; as a result, nbd-server must be able to open and read this file after changing to the user and group that have been specified by use of the user and group options; also, nbd-server will only detect errors in this option upon connection of a client.

When specified on the command line, this should be the second argument.

filesize

Optional; integer; default autodetected.

Disable autodetection of file or block device size, and forcibly specify a size. Sizes must be specified in bytes. If the multifile option is in effect, this option specifies the size of the entire export, not of individual files.

When specified on the command line, this should be the third argument.

listenaddr

Optional; string

If the 'oldstyle' global parameter is specified, works similarly to the global listenaddr parameter, but for the individual port of this particular export. If the 'oldstyle' parameter is not set, this parameter is ignored.

multifile

Optional; boolean.

If this option is set to true, then nbd-server will search for files of the form exportname.integer, with exportname being the filename that would otherwise have been used (after name transformation for virtualization, if any, has been performed) and integer an integer number, starting with 0 and ending when no more files can be found.

The size of the individual files will be autodetected, even if the filesize option has been specified.

Corresponds to the -m option on the command line.

port

Required if 'oldstyle' global parameter is set; integer.

The port on which this export is to be served using the old-style handshake protocol.

This parameter only makes sense when the 'oldstyle' parameter is set to true in the 'generic' section. If that parameter is not set, but this parameter is found in an export section, then nbd-server will issue a warning upon startup but should otherwise continue to function correctly.

It is not possible to combine multiple exports on the same port using the old style handshake. Please use the new style handshake for that purpose.

When specified on the command line, this should be the first argument.

readonly

Optional; boolean.

Disallow writes to the device. If this option is specified, nbd-server will issue an error to any client that tries to write to the device.

Use of this option in conjunction with copyonwrite is possible, but silly.

Corresponds to the -r option on the command line.

sdp

Optional; boolean.

When this option is enabled, nbd-server will use the Socket Direct Protocol (SDP) to serve the export, rather than just IP. This is faster, but requires special hardware (usually something like InfiniBand) and support in the kernel.

Additionally, support for this option must be enabled at compile time, using the --enable-sdp option to the configure script. If this option is found in a configuration file and nbd-server does not have support for SDP, then nbd-server will exit with an error message.

sync

Optional; boolean.

When this option is enabled, nbd-server will call an fsync() after every write to the backend storage. Calling fsync() increases reliability in case of an unclean shutdown of nbd-server; but, depending on the file system used on the nbd-server side, may degrade performance. The use of this option isn't always necessary; e.g., on ext3 filesystems, it is recommended that it is not enabled, since it seriously reduces performance on ext3 filesystems while not importantly impacting reliability.

sparse_cow

Optional; boolean.

When this option is enabled, nbd-server will use sparse files to implement the copy-on-write option; such files take up less space then they appear to, which allows nbd-server to handle the file as if it was just as large as the block device it's for.

If this option is disabled, nbd-server will map every newly written block to the end of the copy-on-write file, which means that nbd-server will have to lseek(2) to the right position after every 4096-byte block.

Using this option may be faster when much is being written during a connection.

timeout

Optional; integer; default 0

How many seconds a connection may be idle for this export. When a connection is idle for a longer time, nbd-server will forcibly disconnect the connection. If you specify 0 (the default), then a connection may be idle forever.

Corresponds to the -a option on the command line

virtstyle

Optional; string; default "ipliteral"

Defines the style of virtualization. Virtualization allows one to create one export that will serve a different file depending on the IP address that is connecting. When virtualization is active, the exportname parameter needs to contain the string '%s'; this will then be replaced by the IP address of the client connecting, in accordance with the option selected here. The result of this transformation is then used as the filename to be opened.

There are four types of virtualization that nbd-server supports:

none

No virtualization. Will attempt to open the filename as it was written, even if it contains '%s' in the name.

ipliteral

The %s is replaced by the IP address of the connecting host is used as-is. For IPv4, this is done in dotted-quad notation; for IPv6, in hexadecimal form with leading zeros omitted.

As an example, if a client connects from 192.168.1.100 and exportname is specified as /export/%s, then nbd-server will attempt to serve /export/192.168.1.100. For IPv6, with a client connecting from 2001:6f8:32f::39, the filename would be /export/2001:6f8:32f:0:0:0:0:39

iphash

Same as above, except that nbd-server will replace the dots in the IP address by forward slashes ('/'); in the same example, nbd-server would open /export/192/168/1/100 instead.

Since there are no dots in most IPv6 addresses, the effect of using this option when IPv6 is in use is indistinguishable from the ipliteral option. It was thought that having to create an eight-deep directory structure would not be as useful.

cidrhash

This option requires one to add a space and a number after it. nbd-server will use the number as a network mask in CIDR style, and use that as a hash cutoff point. In the above example, if virtstyle has been specified as cidrhash 16, then nbd-server will try to open /export/192.168.0.0/192.168.1.100; if virtstyle were specified as cidrhash 26, then nbd-server will try to open /export/192.168.1.64/192.168.1.100.

For IPv6, in the above example, with cidrhash 42, the filename would be /export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39.

prerun

Optional; string

If specified, then this command will be ran after a client has connected to the server (and has been accepted), but before the server starts serving. If the command contains the literal string '%s', then this string will be replaced by the filename of the file which nbd-server wants to export.

This is useful to create export files on the fly, or to verify that a file can be used for export, to write something to a log file, or similar.

If the command runs with a non-zero exit status, then nbd-server will assume the export will fail, and refuse to serve it.

postrun

Optional; string

If specified, then it is assumed to be a command that will be ran when a client has disconnected. This can be useful to clean up whatever prerun has set up, to log something, or similar.

If the literal string '%s' is present in the command, it will be replaced by the file name that has just been closed.

In contrast to the prerun option, the exit state of postrun is ignored.

maxconnections

Optional; integer

If specified, then it limits the number of opened connections for this export.

SEE ALSO

nbd-server (1), nbd-client (8)

AUTHOR

The NBD kernel module and the NBD tools were originally written by Pavel Machek (pavel@ucw.cz)

The Linux kernel module is now maintained by Paul Clements (Paul.Clements@steeleye.com), while the userland tools are maintained by Wouter Verhelst ()

On The Hurd there is a regular translator available to perform the client side of the protocol, and the use of nbd-client is not required. Please see the relevant documentation for more information.

This manual page was written by Wouter Verhelst () for the Debian GNU/Linux system (but may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation.

EXAMPLES

A simple nbd-server configuration file would look like this:

      [generic]
      [export]
          exportname = /export/blkdev
          port = 12345

For increased security, one might want to create an authorization file, and set the UID and GID to run as:

      [generic]
          user = nbd
          group = nbd
      [export]
          exportname = /export/blkdev
          port = 12345
          authfile = ${prefix}/etc/nbd-server/allow

With ${prefix}/etc/nbd-server/allow containing the following:

      127.0.0.1
      192.168.0.0/8
      192.168.1.1