Provided by: nbd-server_2.9.25-2ubuntu1_i386 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)