Provided by: nbd-server_2.9.9-1ubuntu1_i386 bug

NAME

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

SYNOPSIS

       /etc/nbd-server/config

DESCRIPTION

       /etc/nbd-server/config 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 (future versions of nbd-server
       may use the section name to refer to an export)

       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.

       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

       autoreadonly
              Optional; boolean.

              If   this   option   is   set  to  true,  then  nbd-server  will
              automatically switch to readonly if it cannot write to the file.

              Does not have a corresponding command-line argument

              TODO: verify whether this option actually works as documented. I
              have a feeling I’ve been terribly stupid.

       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
              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 that will  be  exported.  This  must  be  a
              fully-qualified  path  and  filename;  relative  paths  are  not
              allowed.

              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.

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

       listenaddr
              Optional; string

              If this option is set, it should contain the  local  IP  address
              (in  "dotted-quad"  notation)  on which we should listen to nbd-
              client(8) connections. If it is not set, 0.0.0.0 is used  (i.e.,
              "listen on all local IP addresses")

       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. See the documentation
              for the multifile for details.

              Corresponds to the -m option on the command line.

       port   Required; integer.

              The port on which this export is to be served. Currently  it  is
              not  possible  to export multiple block devices on the same port
              unless virtualization is used; future versions of nbd-server may
              add this functionality.

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

       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.

       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.

       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

       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
              There  are  three  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
                     nbd-server will look for the literal string ’%s’  in  the
                     exportname,  and  replace  it  by  the  IP address of the
                     connecting host in dotted-quad notation. The string  that
                     results  from  this  transformation  will  be  used as an
                     absolute pathname that nbd-server will attempt  to  open.
                     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

              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.

              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.

       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.

       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.

SEE ALSO

       nbd-server (1), nbd-client (8), http://nbd.sourceforge.net/roadmap.html

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

                                26 oktober 2007                  NBD-SERVER(5)