-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 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.
projects / nbd.git / blobdiff