r295: Last bits from Corey; also, apply patch to set listenaddr (documentation follows)

[nbd.git] / README

diff --git a/README b/README
index af9252d..70018ed 100644 (file)
--- a/README
+++ b/README
@@ -21,6 +21,14 @@ device nodes:
 (if you need more than one NBD device, repeat the above command for nb1,
 nb2, ...)
 
+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 <port> <filename>
@@ -33,7 +41,7 @@ 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 star the client:
+Finally, you'll be able to start the client:
 
 nbd-client <hostname> <port> <nbd device>
 
@@ -46,10 +54,49 @@ 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.
@@ -75,5 +122,5 @@ 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 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.