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 Note that released nbd tarballs are found on
  21 [sourceforge](http://sourceforge.net/projects/nbd/files/nbd/).
  22
  23 Contributing
  24 ------------
  25
  26 If you want to send a patch, please do not open a pull request; instead, send
  27 it to the
  28 [mailinglist](https://lists.sourceforge.net/lists/listinfo/nbd-general)
  29
  30 Using NBD
  31 ---------
  32
  33 NBD is quite easy to use. First, on the client, you need to load the module
  34 and, if you're not using udev, to create the device nodes:
  35
  36     # modprobe nbd
  37     # cd /dev
  38     # ./MAKEDEV nbd0
  39
  40 (if you need more than one NBD device, repeat the above command for nbd1,
  41 nbd2, ...)
  42
  43 Next, write a configuration file for the server. An example looks like
  44 this:
  45
  46     # This is a comment
  47     [generic]
  48         # The [generic] section is required, even if nothing is specified
  49         # there.
  50         # When either of these options are specified, nbd-server drops
  51         # privileges to the given user and group after opening ports, but
  52         # _before_ opening files.
  53         user = nbd
  54         group = nbd
  55     [export1]
  56         exportname = /export/nbd/export1-file
  57         authfile = /export/nbd/export1-authfile
  58         timeout = 30
  59         filesize = 10000000
  60         readonly = false
  61         multifile = false
  62         copyonwrite = false
  63         prerun = dd if=/dev/zero of=%s bs=1k count=500
  64         postrun = rm -f %s
  65     [otherexport]
  66         exportname = /export/nbd/experiment
  67         # The other options are all optional
  68
  69 The configuration file is parsed with GLib's GKeyFile, which parses key
  70 files as they are specified in the Freedesktop.org Desktop Entry
  71 Specification, as can be found at
  72 <http://freedesktop.org/Standards/desktop-entry-spec>. While this format
  73 was not intended to be used for configuration files, the glib API is
  74 flexible enough for it to be used as such.
  75
  76 Now start the server:
  77
  78     nbd-server -C /path/to/configfile
  79
  80 Note that the filename must be an absolute path; i.e., something like
  81 `/path/to/file`, not `../file`. See the nbd-server manpage for details
  82 on any available options.
  83
  84 Finally, you'll be able to start the client:
  85
  86     nbd-client <hostname> -N <export name> <nbd device>
  87
  88 e.g.,
  89
  90     nbd-client 10.0.0.1 -N otherexport /dev/nbd0
  91
  92 will use the second export in the above example (the one that exports
  93 `/export/nbd/experiment`)
  94
  95 `nbd-client` must be ran as root; the same is not true for nbd-server
  96 (but do make sure that /var/run is writeable by the server that
  97 `nbd-server` runs as; otherwise, you won't get a PID file, though the
  98 server will keep running).
  99
 100 There are packages (or similar) available for the following operating
 101 systems:
 102
 103 - Debian (and derivatives, like Ubuntu): `nbd-client` and `nbd-server`,
 104   since Debian woody.
 105 - Gentoo: the `nbd` ebuild in the `sys-block` category, available in
 106   Portage since 2002.
 107 - FreeBSD: `net/nbd-server`, available in the ports tree since 2003.
 108   FreeBSD doesn't have kernel support for NBD, so obviously the client
 109   isn't built there.
 110 - SuSE: `nbd`, in SuSE 10.0
 111 - Fedora: `nbd`, since Fedora 7
 112 - uClibc's `buildroot` script also seems to have support for NBD.
 113
 114 If you're packaging NBD for a different operating system that isn't in
 115 the above list, I'd like to know about it.
 116
 117 For questions, please use the `nbd-general@lists.sourceforge.net` mailinglist.