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 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/nb0
  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 [export1]
  71         exportname = /export/nbd/export1-file
  72         port = 12345
  73         authfile = /export/nbd/export1-authfile
  74         timeout = 30
  75         filesize = 10000000
  76         readonly = false
  77         multifile = false
  78         copyonwrite = false
  79         prerun = dd if=/dev/zero of=%s bs=1k count=500
  80         postrun = rm -f %s
  81 [otherexport]
  82         exportname = /export/nbd/experiment
  83         port = 12346
  84         # The other options are all optional.
  85
  86 The configuration file is parsed with GLib's GKeyFile, which parses key
  87 files as they are specified in the Freedesktop.org Desktop Entry
  88 Specification, as can be found at
  89 <http://freedesktop.org/Standards/desktop-entry-spec>. While this format
  90 was not intended to be used for configuration files, the glib API is
  91 flexible enough for it to be used as such.
  92
  93 The old command-line syntax is still supported, however.
  94
  95 There are packages (or similar) available for the following operating
  96 systems:
  97
  98 Debian (and derivatives, like Ubuntu): "nbd-client" and "nbd-server",
  99         since Debian woody.
 100 Gentoo: the "nbd" ebuild in the "sys-block" category, available in
 101         Portage since 2002.
 102 FreeBSD: "net/nbd-server", available in the ports tree since 2003.
 103         FreeBSD doesn't have kernel support for NBD, so obviously the
 104         client isn't built there.
 105 SuSE: "nbd", since SuSE 10.0
 106 Fedora: "nbd", since Fedora 7
 107 uClibc's "buildroot" script also seems to have support for NBD.
 108
 109 If you're packaging NBD for a different operating system that isn't in
 110 the above list, I'd like to know about it.
 111
 112 Thanks, and have fun,
 113
 114 Wouter Verhelst
 115
 116
 117
 118
 119 [1] When you write something to a block device, the kernel will not
 120 immediately write that to the physical block device; instead, your
 121 changes are written to a cache, which is periodically flushed by a
 122 kernel thread, 'kblockd'. If you're using a single-processor system,
 123 then you'll have only one kblockd, meaning, the kernel can't write to
 124 more than one block device at the same time.
 125
 126 If, while your kblockd is emptying the NBD buffer cache, the kernel
 127 decides that the cache of the block device your nbd-server is writing to
 128 needs to be emptied, then you've got a deadlock.
 129
 130 A kernel patch exists[2] to create a separate kernel thread for NBD
 131 writes which woul fix this problem; however, it has not made it into
 132 mainline yet.