X-Git-Url: http://git.alex.org.uk diff --git a/README b/README index d3d1073..e2e7291 100644 --- a/README +++ b/README @@ -1 +1,145 @@ -Initial README +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 nbd0 + +(if you need more than one NBD device, repeat the above command for nbd1, +nbd2, ...) + +Since there's a problem with nbd and the (default) cfq I/O scheduler, +you may want to set it to deadline: + +echo 'deadline' > /sys/block/nbd0/queue/scheduler + +(again, repeat the above for nbd1, nbd2, etc, if you need more than one +device) + +Next, start the server. You can use a file or a block device for that: + +nbd-server + +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 + +e.g., + +nbd-client 10.0.0.1 1234 /dev/nbd0 + +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 +/nbd-server/config, and should look something like this: + +# This is a comment +[generic] + # The [generic] section is required, even if nothing is specified + # there. + # When either of these options are specified, nbd-server drops + # privileges to the given user and group after opening ports, but + # _before_ opening files. + user = nbd + group = nbd +[export1] + exportname = /export/nbd/export1-file + port = 12345 + authfile = /export/nbd/export1-authfile + timeout = 30 + filesize = 10000000 + readonly = false + multifile = false + copyonwrite = false + prerun = dd if=/dev/zero of=%s bs=1k count=500 + postrun = rm -f %s +[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 +. 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 +Fedora: "nbd", since Fedora 7 +uClibc's "buildroot" script also seems to have support for NBD. + +If you're packaging NBD for a different operating system that isn't in +the above list, I'd like to know about it. + +[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. + +A kernel patch exists to create a separate kernel thread for NBD writes +which woul fix this problem; however, it has not made it into mainline +yet. + +BUILDING THE SERVER FOR NON-LINUX OPERATING SYSTEMS +=================================================== + +Since the client requires kernel-side support, you can't just compile +nbd-client on a non-Linux kernel and hope it'll work; you'd have to +write a kernel-space driver before that would be possible. + +However, nbd-server assumes nothing more than POSIX and one headerfile +from the Linux kernel. Compiling it can be done as follows: +- Fetch the nbd userland sources, and unpack them. Since you're reading + this README file, you have already done this step. +- Fetch the "nbd.h" file from /usr/include/linux on a Linux system, or + from include/linux in the Linux source tree, and store it in the + toplevel directory of the nbd userland sources +- Edit the headerfile, and remove the line that says '#include + ' (on non-Linux systems, the userland source is smart + enough to figure out how this works by itself) +- now it's just a regular './configure && make && sudo make install' +