README

   1 NBD README
   2 ==========
   3
   4 Welcome to the NBD userland support files!
   5
   6 This package contains nbd-server and nbd-client. You'll want to run the
   7 client on a machine where you want to use an NBD device, and the server
   8 on a different machine; although it's technically possible to use
   9 nbd-server and nbd-client on the same machine, you may run into some
  10 deadlock issues if you do that[1].
  11
  12 To install the package, do the normal configure/make/make install dance.
  13 You'll need to install it on both the client and the server.
  14
  15 Using NBD is quite easy. First, on the client, you need to create the
  16 device nodes:
  17
  18 # cd /dev
  19 # ./MAKEDEV nbd0
  20
  21 (if you need more than one NBD device, repeat the above command for nbd1,
  22 nbd2, ...)
  23
  24 Since there's a problem with nbd and the (default) cfq I/O scheduler,
  25 you may want to set it to deadline:
  26
  27 echo 'deadline' > /sys/block/nbd0/queue/scheduler
  28
  29 (again, repeat the above for nbd1, nbd2, etc, if you need more than one
  30 device)
  31
  32 Next, start the server. You can use a file or a block device for that:
  33
  34 nbd-server <port> <filename>
  35
  36 e.g.,
  37
  38 nbd-server 1234 /home/wouter/nbd-export
  39
  40 Note that the filename must be an absolute path; i.e., something like
  41 /path/to/file, not ../file. See the nbd-server manpage for details on
  42 any available options.
  43
  44 Finally, you'll be able to start the client:
  45
  46 nbd-client <hostname> <port> <nbd device>
  47
  48 e.g.,
  49
  50 nbd-client 10.0.0.1 1234 /dev/nbd0
  51
  52 nbd-client must be ran as root; the same is not true for nbd-server (but
  53 do make sure that /var/run is writeable by the server that nbd-server
  54 runs as; otherwise, you won't get a PID file, though the server will
  55 keep running).
  56
  57 Starting with NBD 2.9, there is also support for a configuration file.
  58 This configuration file is expected to be found at
  59 <sysconfdir>/nbd-server/config, and should look something like this:
  60
  61 # This is a comment
  62 [generic]
  63         # The [generic] section is required, even if nothing is specified
  64         # there.
  65         # When either of these options are specified, nbd-server drops
  66         # privileges to the given user and group after opening ports, but
  67         # _before_ opening files.
  68         user = nbd
  69         group = nbd
  70         # Since version 2.9.17, nbd-server will do exports on a name
  71         # basis (the used name is the name of the section in which the
  72         # export is specified). This however required an incompatible
  73         # protocol change. To enable backwards-compatible port-based
  74         # exports, uncomment the following line:
  75         # oldstyle = true
  76 [export1]
  77         exportname = /export/nbd/export1-file
  78         # The following line will be ignored unless the
  79         # "oldstyle = true" line in the generic section above is
  80         # enabled.
  81         port = 12345
  82         authfile = /export/nbd/export1-authfile
  83         timeout = 30
  84         filesize = 10000000
  85         readonly = false
  86         multifile = false
  87         copyonwrite = false
  88         prerun = dd if=/dev/zero of=%s bs=1k count=500
  89         postrun = rm -f %s
  90 [otherexport]
  91         exportname = /export/nbd/experiment
  92         # The other options are all optional, except this one in case
  93         # the oldstyle option is used in [generic]:
  94         # port = 12346
  95
  96 The configuration file is parsed with GLib's GKeyFile, which parses key
  97 files as they are specified in the Freedesktop.org Desktop Entry
  98 Specification, as can be found at
  99 <http://freedesktop.org/Standards/desktop-entry-spec>. While this format
 100 was not intended to be used for configuration files, the glib API is
 101 flexible enough for it to be used as such.
 102
 103 The old command-line syntax is still supported, however.
 104
 105 There are packages (or similar) available for the following operating
 106 systems:
 107
 108 Debian (and derivatives, like Ubuntu): "nbd-client" and "nbd-server",
 109         since Debian woody.
 110 Gentoo: the "nbd" ebuild in the "sys-block" category, available in
 111         Portage since 2002.
 112 FreeBSD: "net/nbd-server", available in the ports tree since 2003.
 113         FreeBSD doesn't have kernel support for NBD, so obviously the
 114         client isn't built there.
 115 SuSE: "nbd", since SuSE 10.0
 116 Fedora: "nbd", since Fedora 7
 117 uClibc's "buildroot" script also seems to have support for NBD.
 118
 119 If you're packaging NBD for a different operating system that isn't in
 120 the above list, I'd like to know about it.
 121
 122 [1] When you write something to a block device, the kernel will not
 123 immediately write that to the physical block device; instead, your
 124 changes are written to a cache, which is periodically flushed by a
 125 kernel thread, 'kblockd'. If you're using a single-processor system,
 126 then you'll have only one kblockd, meaning, the kernel can't write to
 127 more than one block device at the same time.
 128
 129 If, while your kblockd is emptying the NBD buffer cache, the kernel
 130 decides that the cache of the block device your nbd-server is writing to
 131 needs to be emptied, then you've got a deadlock.
 132
 133 A kernel patch exists to create a separate kernel thread for NBD writes
 134 which woul fix this problem; however, it has not made it into mainline
 135 yet.
 136
 137 BUILDING THE SERVER FOR NON-LINUX OPERATING SYSTEMS
 138 ===================================================
 139
 140 Since the client requires kernel-side support, you can't just compile
 141 nbd-client on a non-Linux kernel and hope it'll work; you'd have to
 142 write a kernel-space driver before that would be possible.
 143
 144 However, nbd-server assumes nothing more than POSIX and one headerfile
 145 from the Linux kernel. Compiling it can be done as follows:
 146 - Fetch the nbd userland sources, and unpack them. Since you're reading
 147   this README file, you have already done this step.
 148 - Fetch the "nbd.h" file from /usr/include/linux on a Linux system, or
 149   from include/linux in the Linux source tree, and store it in the
 150   toplevel directory of the nbd userland sources
 151 - Edit the headerfile, and remove the line that says '#include
 152   <linux/types.h>' (on non-Linux systems, the userland source is smart
 153   enough to figure out how this works by itself)
 154 - now it's just a regular './configure && make && sudo make install'
 155