Provided by: nbd-server_3.19-3_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.

       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)