Man Linux: Main Page and Category List

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

       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 (or block device) 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.

       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.

       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

                                18 August 2009