NBD README
==========

Welcome to the NBD userland support files!

This package contains nbd-server and nbd-client. You'll want to run the
client on a machine where you want to use an NBD device, and the server
on a different machine; although it's technically possible to use
nbd-server and nbd-client on the same machine, you may run into some
deadlock issues if you do that[1].

To install the package, please see the INSTALL file. You'll need to
install it on both the client and the server.

Using NBD is quite easy. First, on the client, you need to create the
device nodes:

# cd /dev
# ./MAKEDEV nb0

(if you need more than one NBD device, repeat the above command for nb1,
nb2, ...)

Next, start the server. You can use a file or a block device for that:

nbd-server <port> <filename>

e.g.,

nbd-server 1234 /home/wouter/nbd-export

Note that the filename must be an absolute path; i.e., something like
/path/to/file, not ../file. See the nbd-server manpage for details on
any available options.

Finally, you'll be able to start the client:

nbd-client <hostname> <port> <nbd device>

e.g.,

nbd-client 10.0.0.1 1234 /dev/nb0

nbd-client must be ran as root; the same is not true for nbd-server (but
do make sure that /var/run is writeable by the server that nbd-server
runs as; otherwise, you won't get a PID file, though the server will
keep running).

Starting with NBD 2.9, there is also support for a configuration file.
This configuration file is expected to be found at
<sysconfdir>/nbd-server/config, and should look something like this:

# This is a comment
[generic]
	# The [generic] section is required, but can not currently
	# contain any options. This section name is reserved for future
	# use.
[export1]
	exportname = /export/nbd/export1-file
	port = 12345
	authfile = /export/nbd/export1-authfile
	timeout = 30
	filesize = 10000000
	readonly = false
	multifile = false
	copyonwrite = false
[otherexport]
	exportname = /export/nbd/experiment
	port = 12346
	# The other options are all optional.

The configuration file is parsed with GLib's GKeyFile, which parses key
files as they are specified in the Freedesktop.org Desktop Entry
Specification, as can be found at
<http://freedesktop.org/Standards/desktop-entry-spec>. While this format
was not intended to be used for configuration files, the glib API is
flexible enough for it to be used as such.

The old command-line syntax is still supported, however.

There are packages (or similar) available for the following operating
systems:

Debian (and derivatives, like Ubuntu): "nbd-client" and "nbd-server",
	since Debian woody.
Gentoo: the "nbd" ebuild in the "sys-block" category, available in
	Portage since 2002.
FreeBSD: "net/nbd-server", available in the ports tree since 2003.
	FreeBSD doesn't have kernel support for NBD, so obviously the
	client isn't built there.
SuSE: "nbd", since SuSE 10.0

If you're packaging NBD for a different operating system that isn't in
the above list, I'd like to know about it.

Thanks, and have fun,

Wouter Verhelst




[1] When you write something to a block device, the kernel will not
immediately write that to the physical block device; instead, your
changes are written to a cache, which is periodically flushed by a
kernel thread, 'kblockd'. If you're using a single-processor system,
then you'll have only one kblockd, meaning, the kernel can't write to
more than one block device at the same time.

If, while your kblockd is emptying the NBD buffer cache, the kernel
decides that the cache of the block device your nbd-server is writing to
needs to be emptied, then you've got a deadlock.