Provided by: nbd-server_2.9.25-2ubuntu1_amd64 bug

NAME

       /etc/nbd-server/config - configuration file for nbd-server

SYNOPSIS

       /etc/nbd-server/config

DESCRIPTION

       This file allows to configure the nbd-server.

       While  /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.

       includedir
              Optional; string

              The  argument  should  be  a directory containing files with the '.conf' extension;
              these files will be parsed as if they were part of  the  configuration  file.  Note
              that  these  extra  configuration  files  cannot  contain  a [generic] section; any
              configuration that should go in the generic section must  be  placed  in  the  main
              configuration file.

              If  this  argument  is  not specified, then no directory will be searched. If it is
              specified but the directory does not exist,  then  nbd-server  will  exit  with  an
              appropriate  error  message;  if  it is specified but the given directory is empty,
              nbd-server will continue (unless no exports whatsoever  have  been  configured,  in
              which case it will exit with an appropriate error message)

       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.

       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.

       port   Optional; string

              The port on which to listen for new-style nbd-client connections. If not specified,
              the IANA-assigned port of 10809 is used.

       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.

OPTIONS FOR EXPORT SECTIONS

       authfile
              Optional; string; default /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. If used in conjunction
              with the temporary, this specifies a template for the temporary file concerned, and
              thus can be used to control the directory it is created in. If the  file  does  not
              exist, but filesize is set, then the file will be created.

              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. If the file is
              not present, a single file is created of this size.

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

       flush  Optional; boolean.

              When this option is enabled, nbd-server will inform the client that it supports and
              desires to be sent flush requests when the elevator layer receives them. Receipt of
              a flush request will cause an fdatasync() (or,  if  the  sync  option  is  set,  an
              fsync())  on  the  backend  storage.  This  increases reliability in the case of an
              unclean shutdown at the expense of a degradation of performance. This  option  will
              have no effect unless supported by the client.

       fua    Optional; boolean.

              When this option is enabled, nbd-server will inform the client that it supports and
              desires to be sent fua  (force  unit  access)  commands  when  the  elevator  layer
              receives  them.  Receipt  of  a  force unit access command will cause the specified
              command to be synced to backend storage using sync_file_range()  if  supported,  or
              fdatasync()  otherwise.  This  increases  reliability  in  the  case  of an unclean
              shutdown at the expense of a degradation of performance. This option will  have  no
              effect unless supported by the client.

       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.

       maxconnections
              Optional; integer

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

       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.

       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.

       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.

       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.

       rotational
              Optional; boolean.

              When this option is enabled, nbd-server will inform the client that it would prefer
              it  to  send requests in elevator (i.e., optimized) order, perhaps because it has a
              backing store and no local elevator. By default, the client uses QUEUE_FLAG_NONROT,
              which  effectively  restricts  the  function  of  the  elevator to block merges. By
              specifying this flag on the server, the  client  will  not  use  QUEUE_FLAG_NONROT,
              meaning  the client elevator will perform normal elevator ordering of I/O requests.
              Note that even when the backing store is on rotating  media,  it  is  not  normally
              necessary  to  specify  this flag, as the server's elevator algorithm will be used.
              This flag is only required where the server will not be using an elevator algorithm
              or  where the elevator algorithm is effectively neutered (e.g. with the sync option
              set). This option will have no effect unless supported by the client.

       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.

       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.

       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.

       temporary
              Optional; boolean.

              Create a temporary export with a name based on exportname (this can be used to  set
              the  directory).  A  unique filename is created, which is unlinked as soon as it is
              created, and therefore the export will not  persist  between  invocations  of  nbd-
              server.  Set  the  size  of  the  file  using  the  filesize option. This option is
              incompatible with the multifile option.

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

       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

       transactionlog
              Optional; string

              If specified, then  this  pathname  is  used  to  generate  a  transaction  log.  A
              transaction log is a binary file consisting of the requests sent to and the replies
              received by the server, but excluding any data (so, for a write command, it records
              the  offset  and  length  of  the  write but not the data written). It is therefore
              relatively safe to distribute to a third party. Note that the transaction log  does
              not  include  the  negotiation  sequence.  Transaction  logs  are mainly useful for
              debugging. The program  nbd-tester-client  distributed  with  the  source  to  this
              program  can  reply a transaction log against a server and perform a data integrity
              test. Note that the transaction log is written to for every client opened. If it is
              necessary  to maintain separate transaction logs for each client, the prerun script
              should rename the transaction log (which will just have been  opened  in  order  to
              avoid transaction logs overwriting eachother. This action should be race-free.

       trim   Optional; boolean

              When  this  option  is activated, the server announces it supports the NBD_CMD_TRIM
              command for the export. This command allows the server to discard the data from the
              disk, but does not require it to.

              Since nbd-server does not currently implement discarding data yet, this option does
              nothing (beyond allowing the client to send extra data to the server that it  can't
              do anything useful with).

       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.

SEE ALSO

       nbd-server (1), nbd-client (8), nbd-trdump (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 (<wouter@debian.org>)

       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 (<wouter@debian.org>) 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

       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
                 authfile = /etc/nbd-server/allow

       With /etc/nbd-server/allow containing the following:

             127.0.0.1
             192.168.0.0/8
             192.168.1.1

       To  be  compatible  with older nbd-client systems, one might wish to enable the old-style,
       port-based, negotation:

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

                                         29 November 2011                           NBD-SERVER(5)