README.md

   1 NBD README
   2 ==========
   3
   4 Welcome to the NBD userland support files!
   5
   6 This package contains nbd-server and nbd-client.
   7
   8 To install the package, download the source and do the normal
   9 `configure`/`make`/`make install` dance. You'll need to install it on both the
  10 client and the server. Note that released nbd tarballs are found on
  11 [sourceforge](http://sourceforge.net/projects/nbd/files/nbd/).
  12
  13 For compiling from git, do a checkout, install the SGML tools
  14 (docbook2man), and then run './autogen.sh' while inside your checkout.
  15 Then, see above.
  16
  17 Contributing
  18 ------------
  19
  20 If you want to send a patch, please do not open a pull request; instead, send
  21 it to the
  22 [mailinglist](https://lists.sourceforge.net/lists/listinfo/nbd-general)
  23
  24 Using NBD
  25 ---------
  26
  27 NBD is quite easy to use. First, on the client, you need to load the module
  28 and, if you're not using udev, to create the device nodes:
  29
  30     # modprobe nbd
  31     # cd /dev
  32     # ./MAKEDEV nbd0
  33
  34 (if you need more than one NBD device, repeat the above command for nbd1,
  35 nbd2, ...)
  36
  37 Next, write a configuration file for the server. An example looks like
  38 this:
  39
  40     # This is a comment
  41     [generic]
  42         # The [generic] section is required, even if nothing is specified
  43         # there.
  44         # When either of these options are specified, nbd-server drops
  45         # privileges to the given user and group after opening ports, but
  46         # _before_ opening files.
  47         user = nbd
  48         group = nbd
  49     [export1]
  50         exportname = /export/nbd/export1-file
  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
  62
  63 The configuration file is parsed with GLib's GKeyFile, which parses key
  64 files as they are specified in the Freedesktop.org Desktop Entry
  65 Specification, as can be found at
  66 <http://freedesktop.org/Standards/desktop-entry-spec>. While this format
  67 was not intended to be used for configuration files, the glib API is
  68 flexible enough for it to be used as such.
  69
  70 Now start the server:
  71
  72     nbd-server -C /path/to/configfile
  73
  74 Note that the filename must be an absolute path; i.e., something like
  75 `/path/to/file`, not `../file`. See the nbd-server manpage for details
  76 on any available options.
  77
  78 Finally, you'll be able to start the client:
  79
  80     nbd-client <hostname> -N <export name> <nbd device>
  81
  82 e.g.,
  83
  84     nbd-client 10.0.0.1 -N otherexport /dev/nbd0
  85
  86 will use the second export in the above example (the one that exports
  87 `/export/nbd/experiment`)
  88
  89 `nbd-client` must be ran as root; the same is not true for nbd-server
  90 (but do make sure that /var/run is writeable by the server that
  91 `nbd-server` runs as; otherwise, you won't get a PID file, though the
  92 server will keep running).
  93
  94 There are packages (or similar) available for the following operating
  95 systems:
  96
  97 - Debian (and derivatives, like Ubuntu): `nbd-client` and `nbd-server`,
  98   since Debian woody.
  99 - Gentoo: the `nbd` ebuild in the `sys-block` category, available in
 100   Portage since 2002.
 101 - FreeBSD: `net/nbd-server`, available in the ports tree since 2003.
 102   FreeBSD doesn't have kernel support for NBD, so obviously the client
 103   isn't built there.
 104 - SuSE: `nbd`, in SuSE 10.0
 105 - Fedora: `nbd`, since Fedora 7
 106 - uClibc's `buildroot` script also seems to have support for NBD.
 107
 108 If you're packaging NBD for a different operating system that isn't in
 109 the above list, I'd like to know about it.
 110
 111 For questions, please use the `nbd-general@lists.sourceforge.net` mailinglist.
 112
 113 Badges
 114 ======
 115
 116 [![Download Network Block Device](https://img.shields.io/sourceforge/dm/nbd.svg)](https://sourceforge.net/projects/nbd/files/latest/download)
 117 [![Coverity Scan Build Status](https://scan.coverity.com/projects/1243/badge.svg)](https://scan.coverity.com/projects/1243)
 118 [![CII badge](https://bestpractices.coreinfrastructure.org/projects/281/badge)](https://bestpractices.coreinfrastructure.org/projects/281)
 119 [![Travis](https://img.shields.io/travis/NetworkBlockDevice/nbd.svg)](https://travis-ci.org/NetworkBlockDevice/nbd)
 120
 121 [![Packaging status](https://repology.org/badge/vertical-allrepos/nbd.svg)](https://repology.org/metapackage/nbd)