device nodes:
# cd /dev
-# ./MAKEDEV nb0
+# ./MAKEDEV nbd0
-(if you need more than one NBD device, repeat the above command for nb1,
-nb2, ...)
+(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:
/path/to/file, not ../file. See the nbd-server manpage for details on
any available options.
-Finally, you'll be able to star the client:
+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 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
+<sysconfdir>/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
+<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: "nbd-client" and "nbd-server", since woody.
+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.
-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
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 your nbd-server is writing to needs to be
-emptied, then you've got a deadlock.
+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
+ <linux/types.h>' (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'
+
projects / nbd.git / blobdiff