Provided by: nbd-server_2.9.23-3ubuntu1_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.

       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.

       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.

       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.

       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.

       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
                 port = 12345

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

             [generic]
                 user = nbd
                 group = nbd
             [export]
                 exportname = /export/blkdev
                 port = 12345
                 authfile = /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

                                 22 July 2011                    NBD-SERVER(5)