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"/>
9 <a href='http://barbershop.grep.be:8010/'>
10 <img alt='build status' src='http://barbershop.grep.be/cgi-bin/buildstatus'>
13 Welcome to the NBD userland support files!
15 This package contains nbd-server and nbd-client.
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.
20 Note that released nbd tarballs are found on
21 [sourceforge](http://sourceforge.net/projects/nbd/files/nbd/).
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:
30 (if you need more than one NBD device, repeat the above command for nbd1,
33 Next, write a configuration file for the server. An example looks like
38 # The [generic] section is required, even if nothing is specified
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.
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:
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
57 authfile = /export/nbd/export1-authfile
63 prerun = dd if=/dev/zero of=%s bs=1k count=500
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]:
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.
80 nbd-server -C /path/to/configfile
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.
86 Finally, you'll be able to start the client:
88 nbd-client <hostname> -N <export name> <nbd device>
92 nbd-client 10.0.0.1 -N otherexport /dev/nbd0
94 will use the second export in the above example (the one that exports
95 `/export/nbd/experiment`)
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).
102 The old command-line port-only way of exporting something is still
103 supported, but it is deprecated.
105 There are packages (or similar) available for the following operating
108 - Debian (and derivatives, like Ubuntu): `nbd-client` and `nbd-server`,
110 - Gentoo: the `nbd` ebuild in the `sys-block` category, available in
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
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.
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.
122 For questions, please use the `nbd-general@lists.sourceforge.net` mailinglist.