Provided by: nbd-server_3.24-1.1ubuntu1_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]

       allowlist
              Optional; boolean

              Whether  to  allow  the  client  to  fetch  a  list of exports from this server. If
              enabled, the client can run nbd-client -l to get a list of exports on this server.

       cacertfile
              Optional; string

              If this option is set,  it  should  contain  a  path  to  a  PEM  format  X.509  CA
              certificate used for validating client certificates supplied by the client. If this
              option is not set then client certificates will not be checked.

       certfile
              Optional; string

              If this option is set, it should contain a  path  to  a  PEM  format  X.509  public
              certificate  used  for  TLS  negotiation  with  the  client.  If keyfile is set but
              certfile is not set, then the server will attempt to read the certificate from  the
              path specified by keyfile.

       force_tls
              Optional; boolean.

              Switch the server to FORCEDTLS mode.

              Note:  this  is  not  the  same as enabling the force_tls option for each and every
              export individually.  The latter will allow certain options  to  be  issued  during
              negotiation  (e.g.,  the  "list exports" option, even if that would return an empty
              result set), whereas enabling this option will disallow the use of any option to be
              issued  during  negotiation,  apart  from the STARTTLS option itself (to switch the
              transport to TLS).

              Using FORCEDTLS mode should result in a safer environment, as the server  will  not
              allow  any  communication  to  take place unless and until TLS has been negotiated.
              However, it also makes it impossible to  set  up  a  nonencrypted  export  for  the
              benefit of older clients, or for clients that want to swap and not deadlock.

              Using  this  parameter  without  also  specifying a value for the other TLS-related
              parameters is possible, but silly.

       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)

       keyfile
              Optional; string

              If this option is set, it should contain a path to a PEM format X.509  private  key
              used for TLS negotiation with the client. This option must be set to enable TLS.

       listenaddr
              Optional; string

              If  this  option  is  set,  it should contain a comma-separated lis of the local IP
              addresses on which we should listen to nbd-client(8) connections. If it is not set,
              nbd-server  will  listen to "::, 0.0.0.0", which causes nbd-server to 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".

       max_threads
              Optional; integer; default 4

              Since NBD 3.12, nbd-server will read requests in a main thread, but do the handling
              of these requests, and the sending of the reply, in a  number  of  separate  worker
              threads, which are shared among all exports. With this parameter, you can configure
              the number of these worker threads.

              The default should be reasonable for a dual-core single-disk server. You might want
              to  increase  it  if  you have a powerful server that does little else than serving
              NBD.

       oldstyle
              Optional; boolean

              In versions of nbd-server between 2.9.17 and 3.9.1, when this  option  was  set  to
              true,  nbd-server  would  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 was mandatory.

              Since  version 3.10 of nbd-server, however, this option is no longer supported, and
              any attempt to use it will result in nbd-server exiting with an  appropriate  error
              message.

       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.

       splice Optional; boolean

              Allow the server to use the splice() system call to handle read or write calls when
              possible.  Using  splice  can  speed  up  handling  of  such  calls  significantly.
              Unfortunately, splice cannot be used in combination with  TLS  or  the  copyonwrite
              mode, and will only work for requests smaller than 1MiB.

              To  handle these situations, the server will exit with an appropriate error message
              if splice and copyonwrite are both enabled for an export; it will  silently  ignore
              the  splice  option if TLS is enabled, falling back on normal reads and writes; and
              it will similarly fall back on normal reads when the request size exceeds 1MiB.

       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.

       unixsock
              Optional; string

              Path for a UNIX domain socket.

              If  specified,  the  server  will listen on a UNIX domain socket with the specified
              name. Only newstyle negotiation is supported on UNIX  domain  sockets.  If  a  UNIX
              domain socket is, then the server will not listen for TCP connections.

       duallisten
              Optional; boolean

              If  true,  and  unixsock  is  specified,  the  the  server  will listen on both the
              configured UNIX domain socket and any configured TCP or SDP  socket.   Defaults  to
              false.

       tlsprio
              Optional; string; default NORMAL:-VERS-TLS-ALL:+VERS-TLS1.2:%SERVER_PRECEDENCE

              This option allows to configure the GnuTLS priority string, which is used to select
              the algorithms which GnuTLS will allow to be negotiated with the  client.  The  NBD
              STARTTLS  specification  requires that clients and servers require TLS1.2 or higher
              by default, so the default string disables all older versions of the TLS protocol.

              Not all versions of GnuTLS support the %SERVER_PRECEDENCE  flag,  which  exists  to
              signal  that  the  server  should  pay  no  attention  to the algorithm preferences
              selected by the client. If you're using an older version of GnuTLS (e.g., 2.12), it
              may  be  necessary  to  specify  a  priority  string  that  does  not  include  the
              %SERVER_PRECEDENCE flag.

              For an explanation of the  possible  values  of  this  option,  see  the  "Priority
              strings" chapter in the GnuTLS documentation.

OPTIONS FOR EXPORT SECTIONS

       authfile
              Optional; string; default empty

              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).   Empty  lines  are  skipped, as is any content behind a hashmark
              ('#') on any line.

              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.  However,  note  that  for  the
              command line, the default is /etc/nbd-server/allow.

       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

       cowdir Optional; string.

              Specifies where to write copy-on-write diff files. If this option is absent,  copy-
              on-write  files  will  be  written  in  the same directory as the base export file.
              Useful for exporting files in copy-on-write mode from a  directory  that  the  user
              running nbd-server has no write access to.

              If the copy-on-write mode is not active, this option has no effect.

       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.

              Note:  this  is not the "exportname" as defined in the protocol document, and which
              is the name that nbd-client needs to pass to select the correct export; the section
              name is used for that. The name of the file to be exported is called the exportname
              in the configuration file for historical reasons, and cannot easily be changed.

       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.

       force_tls
              Optional; boolean.

              Require the use of TLS for this export to be available.

              When this option has been enabled for an export, clients that do not negotiate  TLS
              will  not  see the export when they request a list of exports, and will not be able
              to connect to it.

              Enabling this option when TLS credentials have not been configured in the [generic]
              section is possible, but silly.

       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

              Ignored, kept for compatibility with the obsolete 'oldstyle' global parameter.

       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.

       treefiles
              Optional; boolean.

              If this option is set to true, then nbd-server will search for files  of  the  form
              exportname/TREEXXXX/.../FILEXXXX,  with  exportname  being  the filename that would
              otherwise have been used (after name transformation for virtualization, if any, has
              been  performed)  and  TREEXXXX and FILEXXXX being autogenerated directory and path
              names for individual block files.

              Files and directories are automatically created.  Files  will  be  deleted  if  the
              corresponding  block gets marked as unused.  The size of the individual block files
              is fixed to 4096 bytes.  There  will  be  at  most  1024  files/subdirectories  per
              folder.   An apropriate nesting level of subdirectories will be created to create a
              filesystem of filesize bytes in total forming a virtual block device.

              This feature is  useful  to  provide  a  virtual  block  device  on  an  underlying
              filesystem  that does not handle large files well, for example fuse/ftpfs, davfs or
              other network filesytems.

              This feature is mutually exclusive with the -m and will take precedence if both are
              given.   There  is no corresponding command line option, since command line control
              is considered deprecated. You can however specify a custom config file with the  -C
              option.  The filesize option must be specified when using this feature!

       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 nonzero 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.

       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.

              When a client connects over a UNIX domain socket, the literal string "unix" is used
              in lieu of a client IP address.

              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.

       tlsonly
              Optional; boolean.

              When this option is enabled, nbd-server will only serve the export  using  the  TLS
              extension.  If  this option is not supplied, TLS is optional, unless tlsonly is set
              in the generic section. In order for TLS to work at all, the keyfile option must be
              specified in the generic section.

       waitfile
              Optional; string.

              When  this  option  is  set,  nbd-server  will allow writes to this export, but not
              reads, until the server is sent a SIGUSR1 command. Any writes to the export will be
              stored  in  a diff file with the same algorithm as for the copy-on-write option. In
              particular, this means that the cowdir option is in effect for this option, too.

              The backend file (as per the exportname parameter) need not exist until the SIGUSR1
              signal is sent to the server.

              Once  SIGUSR1  is  received,  nbd-server  will open the main export file, and start
              merging all outstanding writes into it. Once this operation finishes, the diff file
              will be removed, and the server will allow normal use of the export.

              This allows the out-of-band live migration of an export from one server to another.

              Note that this option cannot be combined with the copy-on-write option itself.

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

                         : 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $            NBD-SERVER(5)