1NBD-SERVER(1)                                                    NBD-SERVER(1)
2
3
4

NAME

6       nbd-server  - serve a file as a block device to other computers    run‐
7       ning the GNU/Linux(tm) or GNU/Hurd Operating    System
8

SYNOPSIS

10       nbd-server  [ip@]port filename [ size ] [ -r ] [ -m ] [ -c ] [ -l  host
11       list filename ] [ -o section name ] [ -C config file ] [ -M max connec‐
12       tions ] [ -V ] [ -d ]
13
14

DESCRIPTION

16       nbd-server is the server for the Linux Network Block Device (NBD). With
17       NBD,  a client can use a file, exported over the network from a server,
18       as a block device. It can then be used for whatever  purpose  a  normal
19       block device (harddisk, CD-ROM, ...) can be used for.
20
21       NBD can be useful for diskless clients that need swapspace, but you can
22       also create a filesystem on it and use it as though  it  were  a  local
23       filesystem.
24
25       nbd-server  implements  some  security through a file called "/etc/nbd-
26       server/allow" (by default; a different file can be chosen with the '-l'
27       option or through a config file specification). This file must list the
28       IP-addresses or network masks of clients that are allowed  to  connect.
29       If  it  does not exist, all clients are able to connect. If the file is
30       empty, no clients can connect.
31
32       Note that while the command line allows for specifying an  export,  the
33       use of this option is deprecated. It is preferred to make use of a con‐
34       figuration file instead,  the  format  of  which  is  defined  in  nbd-
35       server(5).
36
37       While  nbd-server  is  running,  new exports can be added by re-writing
38       configuration files and  then  sending  SIGHUP  to  nbd-server.  SIGHUP
39       causes nbd-server to re-read its configuration files and to start serv‐
40       ing all new exports which were not served earlier. Reconfiguration does
41       not modify any existing export, it only appends new ones.
42

OPTIONS

44       ip     The  ip address the server should listen on. This may be an IPv4
45              address, an IPv6 address, or a hostname.  In  the  latter  case,
46              nbd-server will do a hostname lookup for the name specified, and
47              will listen on the first address that is returned. For  compati‐
48              bility  with  past versions of nbd-server, if an IPv4 address is
49              specified, the @ sign  that  serves  as  separator  between  the
50              address and port may be replaced by a colon.
51
52              If  this  parameter  is not specified, nbd-server will listen on
53              all local addresses on both IPv4 and IPv6.  To  limit  to  IPv4,
54              specify  the address as 0.0.0.0; to limit to IPv6, specify it as
55              ::.
56
57       port   The port the server should listen to. A valid port is any number
58              between  1  and  65536;  if 0 is used, nbd-server will listen on
59              stdin (so that nbd-server can be ran from inetd)
60
61       filename
62              The filename of the file that should be exported.  This  can  be
63              any file, including "real" blockdevices (i.e. a file from /dev).
64              If the filename includes the literal string "%s", then  this  %s
65              will  be substituded with the IP-address of the client trying to
66              connect.
67
68       size   The size of the block device at the client side. This  is  espe‐
69              cially useful in conjunction with the -m option
70
71              Can  optionally  be followed by one of K,k,M or m, in which case
72              the size will be multiplied by 1024 (K or k) or 1048576 (M or m)
73
74       -r     Export the file read-only. If a client tries to write to a read-
75              only exported file, it will receive an error, but the connection
76              will stay up.
77
78       -m     Work with multiple files. This can be used  to  export  blockde‐
79              vices  that  are  larger  than the maximum allowed filesize on a
80              given filesystem; i.e. when the filesystem does not allow  files
81              larger than 2GB (which is true for Linux 2.2 and below), you can
82              use this option to store the data in multiple files and export a
83              larger filesystem, if needed.
84
85              To use this option, you must create a number of files with names
86              in the format "name.X", where "name" is given  as  the  filename
87              argument  to  nbd-server,  and "X" is a number starting by 0 and
88              going up for each file.
89
90              Allowing more flexibility for this option is planned for  future
91              versions.
92
93       -c     Copy  on  write.  When this option is provided, write-operations
94              are not done to the exported file, but to a separate file.  This
95              separate  file  is  removed when the connection is closed, which
96              means that serving this  way  will  make  nbd-server  slow  down
97              (especially  on  large  block  devices with lots of writes), and
98              that after disconnecting and  reconnecting  the  client  or  the
99              server, all changes are lost.
100
101       -C     Specify  configuration  file. The default configuration file, if
102              this parameter is not specified, is /etc/nbd-server/config.
103
104              Note that the  configuration  file  is  always  parsed  and  the
105              entries  in  the file used, even if an extra server is specified
106              on the command line. To disable the configuration file entirely,
107              either  move it away or use the -C option to point nbd-server(1)
108              to a non-existing or empty configuration file.
109
110              Also note that if an empty, incomplete, or invalid configuration
111              file is specified, nbd-server will produce a warning about fail‐
112              ure to parse the config file. If the  command  line  contains  a
113              fully  specified configuration, this warning is harmless and may
114              be ignored.
115
116       -M     Specify the maximum number of opened connections. If this param‐
117              eter is not specified, no limit is set.
118
119       -V     Output the version of nbd-server, and exit.
120
121       -d     Do not fork. Useful for debugging.
122
123       host list filename
124              This  argument  should  contain a list of IP-addresses for hosts
125              that may connect to the server. Wildcards are  not  allowed.  If
126              the  file  does  not exist, it is ignored (and any host can con‐
127              nect); If the file does exist, but is empty, no  host  can  con‐
128              nect.  By  default,  the  name  'nbd_server.allow'  is used, and
129              looked for in the current directory, unless nbd-server  is  com‐
130              piled  as  a daemon, in which case it is looked for in the root-
131              directory.
132
133       section name
134              If the -o argument is given on the command line, then nbd-server
135              will output a configuration file section with this as the header
136              that is functionally equivalent to the other  options  specified
137              on  the  command  line,  and  exit. This is useful for migrating
138              pre-2.9 nbd-server initscript configuration  files  to  the  new
139              format.
140

EXAMPLES

142       Some examples of nbd-server usage:
143
144       · To export a file /export/nbd/exp-bl-dev on port 2000:
145
146         nbd-server 2000 /export/nbd/exp-bl-dev
147
148       · To export a the same file read-only:
149
150         nbd-server 2000 /export/nbd/exp-bl-dev -r
151
152       · To  export  the  same file read-write, but make sure changes are lost
153         after restarting the client or the server:
154
155         nbd-server 2000 /export/nbd/exp-bl-dev -c
156

SEE ALSO

158       nbd-client (8), nbd-server (5), nbd-trdump (8)
159

AUTHOR

161       The NBD kernel module and the NBD  tools  were  originally  written  by
162       Pavel Machek (pavel@ucw.cz)
163
164       The   Linux   kernel   module   is  now  maintained  by  Paul  Clements
165       (Paul.Clements@steeleye.com), while the userland tools  are  maintained
166       by Wouter Verhelst (<wouter@debian.org>)
167
168       On  The  Hurd  there  is  a regular translator available to perform the
169       client side of the protocol, and the use of nbd-client is not required.
170       Please see the relevant documentation for more information.
171
172       This  manual  page was written by Wouter Verhelst (<wouter@debian.org>)
173       for the Debian GNU/Linux system (but may be used by  others).   Permis‐
174       sion  is  granted to copy, distribute and/or modify this document under
175       the terms of the GNU General Public License, version 2, as published by
176       the Free Software Foundation.
177
178
179
180                                       $                         NBD-SERVER(1)
Impressum