Network Block Device  @PACKAGE_VERSION@
README.md
Go to the documentation of this file.
1 NBD README
2 ==========
3 
4 <a href="https://scan.coverity.com/projects/1243">
5  <img alt="Coverity Scan Build Status"
6  src="https://scan.coverity.com/projects/1243/badge.svg"/>
7 </a>
8 
9 <a href='http://barbershop.grep.be:8010/'>
10  <img alt='build status' src='http://barbershop.grep.be/cgi-bin/buildstatus'>
11 </a>
12 
13 Welcome to the NBD userland support files!
14 
15 This package contains nbd-server and nbd-client.
16 
17 To install the package, do the normal `configure`/`make`/`make install`
18 dance. You'll need to install it on both the client and the server.
19 
20 Note that released nbd tarballs are found on
21 [sourceforge](http://sourceforge.net/projects/nbd/files/nbd/).
22 
23 Using NBD is quite easy. First, on the client, you need to load the
24 module and, if you're not using udev, to create the device nodes:
25 
26  # modprobe nbd
27  # cd /dev
28  # ./MAKEDEV nbd0
29 
30 (if you need more than one NBD device, repeat the above command for nbd1,
31 nbd2, ...)
32 
33 Next, write a configuration file for the server. An example looks like
34 this:
35 
36  # This is a comment
37  [generic]
38  # The [generic] section is required, even if nothing is specified
39  # there.
40  # When either of these options are specified, nbd-server drops
41  # privileges to the given user and group after opening ports, but
42  # _before_ opening files.
43  user = nbd
44  group = nbd
45  # Since version 2.9.17, nbd-server will do exports on a name
46  # basis (the used name is the name of the section in which the
47  # export is specified). This however required an incompatible
48  # protocol change. To enable backwards-compatible port-based
49  # exports, uncomment the following line:
50  # oldstyle = true
51  [export1]
52  exportname = /export/nbd/export1-file
53  # The following line will be ignored unless the
54  # "oldstyle = true" line in the generic section above is
55  # enabled.
56  port = 12345
57  authfile = /export/nbd/export1-authfile
58  timeout = 30
59  filesize = 10000000
60  readonly = false
61  multifile = false
62  copyonwrite = false
63  prerun = dd if=/dev/zero of=%s bs=1k count=500
64  postrun = rm -f %s
65  [otherexport]
66  exportname = /export/nbd/experiment
67  # The other options are all optional, except this one in case
68  # the oldstyle option is used in [generic]:
69  # port = 12346
70 
71 The configuration file is parsed with GLib's GKeyFile, which parses key
72 files as they are specified in the Freedesktop.org Desktop Entry
73 Specification, as can be found at
74 <http://freedesktop.org/Standards/desktop-entry-spec>. While this format
75 was not intended to be used for configuration files, the glib API is
76 flexible enough for it to be used as such.
77 
78 Now start the server:
79 
80  nbd-server -C /path/to/configfile
81 
82 Note that the filename must be an absolute path; i.e., something like
83 `/path/to/file`, not `../file`. See the nbd-server manpage for details
84 on any available options.
85 
86 Finally, you'll be able to start the client:
87 
88  nbd-client <hostname> -N <export name> <nbd device>
89 
90 e.g.,
91 
92  nbd-client 10.0.0.1 -N otherexport /dev/nbd0
93 
94 will use the second export in the above example (the one that exports
95 `/export/nbd/experiment`)
96 
97 `nbd-client` must be ran as root; the same is not true for nbd-server
98 (but do make sure that /var/run is writeable by the server that
99 `nbd-server` runs as; otherwise, you won't get a PID file, though the
100 server will keep running).
101 
102 The old command-line port-only way of exporting something is still
103 supported, but it is deprecated.
104 
105 There are packages (or similar) available for the following operating
106 systems:
107 
108 - Debian (and derivatives, like Ubuntu): `nbd-client` and `nbd-server`,
109  since Debian woody.
110 - Gentoo: the `nbd` ebuild in the `sys-block` category, available in
111  Portage since 2002.
112 - FreeBSD: `net/nbd-server`, available in the ports tree since 2003.
113  FreeBSD doesn't have kernel support for NBD, so obviously the client
114  isn't built there.
115 - SuSE: `nbd`, in SuSE 10.0
116 - Fedora: `nbd`, since Fedora 7
117 - uClibc's `buildroot` script also seems to have support for NBD.
118 
119 If you're packaging NBD for a different operating system that isn't in
120 the above list, I'd like to know about it.
121 
122 For questions, please use the `nbd-general@lists.sourceforge.net` mailinglist.