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