4 Welcome to the NBD userland support files!
6 This package contains nbd-server and nbd-client. You'll want to run the
7 client on a machine where you want to use an NBD device, and the server
8 on a different machine; although it's technically possible to use
9 nbd-server and nbd-client on the same machine, you may run into some
10 deadlock issues if you do that[1].
12 To install the package, please see the INSTALL file. You'll need to
13 install it on both the client and the server.
15 Using NBD is quite easy. First, on the client, you need to create the
21 (if you need more than one NBD device, repeat the above command for nb1,
24 Next, start the server. You can use a file or a block device for that:
26 nbd-server <port> <filename>
30 nbd-server 1234 /home/wouter/nbd-export
32 Note that the filename must be an absolute path; i.e., something like
33 /path/to/file, not ../file. See the nbd-server manpage for details on
34 any available options.
36 Finally, you'll be able to start the client:
38 nbd-client <hostname> <port> <nbd device>
42 nbd-client 10.0.0.1 1234 /dev/nb0
44 nbd-client must be ran as root; the same is not true for nbd-server (but
45 do make sure that /var/run is writeable by the server that nbd-server
46 runs as; otherwise, you won't get a PID file, though the server will
49 Starting with NBD 2.9, there is also support for a configuration file.
50 This configuration file is expected to be found at
51 <sysconfdir>/nbd-server/config, and should look something like this:
55 # The [generic] section is required, even if nothing is specified
57 # When either of these options are specified, nbd-server drops
58 # privileges to the given user and group after opening ports, but
59 # _before_ opening files.
63 exportname = /export/nbd/export1-file
65 authfile = /export/nbd/export1-authfile
71 prerun = dd if=/dev/zero of=%s bs=1k count=500
74 exportname = /export/nbd/experiment
76 # The other options are all optional.
78 The configuration file is parsed with GLib's GKeyFile, which parses key
79 files as they are specified in the Freedesktop.org Desktop Entry
80 Specification, as can be found at
81 <http://freedesktop.org/Standards/desktop-entry-spec>. While this format
82 was not intended to be used for configuration files, the glib API is
83 flexible enough for it to be used as such.
85 The old command-line syntax is still supported, however.
87 There are packages (or similar) available for the following operating
90 Debian (and derivatives, like Ubuntu): "nbd-client" and "nbd-server",
92 Gentoo: the "nbd" ebuild in the "sys-block" category, available in
94 FreeBSD: "net/nbd-server", available in the ports tree since 2003.
95 FreeBSD doesn't have kernel support for NBD, so obviously the
96 client isn't built there.
97 SuSE: "nbd", since SuSE 10.0
99 If you're packaging NBD for a different operating system that isn't in
100 the above list, I'd like to know about it.
102 Thanks, and have fun,
109 [1] When you write something to a block device, the kernel will not
110 immediately write that to the physical block device; instead, your
111 changes are written to a cache, which is periodically flushed by a
112 kernel thread, 'kblockd'. If you're using a single-processor system,
113 then you'll have only one kblockd, meaning, the kernel can't write to
114 more than one block device at the same time.
116 If, while your kblockd is emptying the NBD buffer cache, the kernel
117 decides that the cache of the block device your nbd-server is writing to
118 needs to be emptied, then you've got a deadlock.