README.md

   1 NBD README
   2 ==========
   3
   4 <a href="https://scan.coverity.com/projects/1243">
   5   <img alt="Coverity Scan Build Status"
   6          src="https://scan.coverity.com/projects/1243/badge.svg"/>
   7 </a>
   8
   9 <a href='http://barbershop.grep.be:8010/'>
  10   <img alt='build status' src='http://barbershop.grep.be/cgi-bin/buildstatus'>
  11 </a>
  12
  13 Welcome to the NBD userland support files!
  14
  15 This package contains nbd-server and nbd-client.
  16
  17 To install the package, do the normal `configure`/`make`/`make install`
  18 dance. You'll need to install it on both the client and the server.
  19
  20 Using NBD is quite easy. First, on the client, you need to create the
  21 device nodes:
  22
  23     # cd /dev
  24     # ./MAKEDEV nbd0
  25
  26 (if you need more than one NBD device, repeat the above command for nbd1,
  27 nbd2, ...)
  28
  29 Since there's a problem with nbd and the (default) cfq I/O scheduler,
  30 you may want to set it to deadline:
  31
  32     echo 'deadline' > /sys/block/nbd0/queue/scheduler
  33
  34 Note that this is done by default on recent kernels.
  35
  36 (again, repeat the above for nbd1, nbd2, etc, if you need more than one
  37 device)
  38
  39 Next, start the server. You can use a file or a block device for that:
  40
  41     nbd-server <port> <filename>
  42
  43 e.g.,
  44
  45     nbd-server 1234 /home/wouter/nbd-export
  46
  47 Note that the filename must be an absolute path; i.e., something like
  48 `/path/to/file`, not `../file`. See the nbd-server manpage for details
  49 on any available options.
  50
  51 Finally, you'll be able to start the client:
  52
  53     nbd-client <hostname> <port> <nbd device>
  54
  55 e.g.,
  56
  57     nbd-client 10.0.0.1 1234 /dev/nbd0
  58
  59 `nbd-client` must be ran as root; the same is not true for nbd-server
  60 (but do make sure that /var/run is writeable by the server that
  61 `nbd-server` runs as; otherwise, you won't get a PID file, though the
  62 server will keep running).
  63
  64 Starting with NBD 2.9, there is also support for a configuration file.
  65 This configuration file is expected to be found at
  66 `<sysconfdir>/nbd-server/config`, and should look something like this:
  67
  68     # This is a comment
  69     [generic]
  70            # The [generic] section is required, even if nothing is specified
  71         # there.
  72         # When either of these options are specified, nbd-server drops
  73         # privileges to the given user and group after opening ports, but
  74         # _before_ opening files.
  75         user = nbd
  76         group = nbd
  77         # Since version 2.9.17, nbd-server will do exports on a name
  78         # basis (the used name is the name of the section in which the
  79         # export is specified). This however required an incompatible
  80         # protocol change. To enable backwards-compatible port-based
  81         # exports, uncomment the following line:
  82         # oldstyle = true
  83     [export1]
  84         exportname = /export/nbd/export1-file
  85         # The following line will be ignored unless the
  86         # "oldstyle = true" line in the generic section above is
  87         # enabled.
  88         port = 12345
  89         authfile = /export/nbd/export1-authfile
  90         timeout = 30
  91         filesize = 10000000
  92         readonly = false
  93         multifile = false
  94         copyonwrite = false
  95         prerun = dd if=/dev/zero of=%s bs=1k count=500
  96         postrun = rm -f %s
  97     [otherexport]
  98         exportname = /export/nbd/experiment
  99         # The other options are all optional, except this one in case
 100         # the oldstyle option is used in [generic]:
 101         # port = 12346
 102
 103 The configuration file is parsed with GLib's GKeyFile, which parses key
 104 files as they are specified in the Freedesktop.org Desktop Entry
 105 Specification, as can be found at
 106 <http://freedesktop.org/Standards/desktop-entry-spec>. While this format
 107 was not intended to be used for configuration files, the glib API is
 108 flexible enough for it to be used as such.
 109
 110 The old command-line syntax is still supported, however.
 111
 112 There are packages (or similar) available for the following operating
 113 systems:
 114
 115 - Debian (and derivatives, like Ubuntu): `nbd-client` and `nbd-server`,
 116   since Debian woody.
 117 - Gentoo: the `nbd` ebuild in the `sys-block` category, available in
 118   Portage since 2002.
 119 - FreeBSD: `net/nbd-server`, available in the ports tree since 2003.
 120   FreeBSD doesn't have kernel support for NBD, so obviously the client
 121   isn't built there.
 122 - SuSE: `nbd`, in SuSE 10.0
 123 - Fedora: `nbd`, since Fedora 7
 124 - uClibc's `buildroot` script also seems to have support for NBD.
 125
 126 If you're packaging NBD for a different operating system that isn't in
 127 the above list, I'd like to know about it.