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, please see the INSTALL file. You'll need to
  13 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 nb0
  20
  21 (if you need more than one NBD device, repeat the above command for nb1,
  22 nb2, ...)
  23
  24 Next, start the server. You can use a file or a block device for that:
  25
  26 nbd-server <port> <filename>
  27
  28 e.g.,
  29
  30 nbd-server 1234 /home/wouter/nbd-export
  31
  32 Note that the filename must be an absolute path; i.e., something like
  33 /path/to/file, not ../file. See the nbd-server manpage for details on
  34 any available options.
  35
  36 Finally, you'll be able to star the client:
  37
  38 nbd-client <hostname> <port> <nbd device>
  39
  40 e.g.,
  41
  42 nbd-client 10.0.0.1 1234 /dev/nb0
  43
  44 nbd-client must be ran as root; the same is not true for nbd-server (but
  45 do make sure that /var/run is writeable by the server that nbd-server
  46 runs as; otherwise, you won't get a PID file, though the server will
  47 keep running).
  48
  49 There are packages (or similar) available for the following operating
  50 systems:
  51
  52 Debian: "nbd-client" and "nbd-server", since woody.
  53 Gentoo: the "nbd" ebuild in the "sys-block" category, available in
  54         Portage since 2002.
  55 FreeBSD: "net/nbd-server", available in the ports tree since 2003.
  56         FreeBSD doesn't have kernel support for NBD, so obviously the
  57         client isn't built there.
  58 SuSE: "nbd", since SuSE 10.0
  59
  60 If you're packaging NBD for a different operating system that isn't in
  61 the above list, I'd like to know about it.
  62
  63 Thanks, and have fun,
  64
  65 Wouter Verhelst
  66
  67 [1] When you write something to a block device, the kernel will not
  68 immediately write that to the physical block device; instead, your
  69 changes are written to a cache, which is periodically flushed by a
  70 kernel thread, 'kblockd'. If you're using a single-processor system,
  71 then you'll have only one kblockd, meaning, the kernel can't write to
  72 more than one block device at the same time.
  73
  74 If, while your kblockd is emptying the NBD buffer cache, the kernel
  75 decides that the cache your nbd-server is writing to needs to be
  76 emptied, then you've got a deadlock.
  77
  78 COMMON COMPILE PROBLEMS
  79 =======================
  80
  81 if ./configure fails for you with a message like
  82
  83 checking where to find a working nbd.h... configure: error: Could not find an nbd.h from kernel 2.6 or above.
  84
  85 then check whether /usr/include/linux/nbd.h
  86 * exists
  87 * contains the following enum:
  88         enum {
  89                 NBD_CMD_READ = 0,
  90                 NBD_CMD_WRITE = 1,
  91                 NBD_CMD_DISC = 2
  92         };
  93
  94 if it doesn't, then fetch the kernel sources from a kernel.org mirror,
  95 fish the nbd.h from those sources (you'll find it in the include/linux
  96 directory), and put it in the nbd userland directory. If you now re-run
  97 configure, it will work.