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.debian.org/nbd)
  23
  24 Security issues
  25 ---------------
  26
  27 If you think you found a security problem in NBD, please contact the
  28 mailinglist. Do *not* just file an issue for this (although you may do
  29 so too if you prefer).
  30
  31 For embargoed issues, please contact Wouter Verhelst <wouter@debian.org>
  32
  33 Using NBD
  34 ---------
  35
  36 NBD is quite easy to use. First, on the client, you need to load the module
  37 and, if you're not using udev, to create the device nodes:
  38
  39     # modprobe nbd
  40     # cd /dev
  41     # ./MAKEDEV nbd0
  42
  43 (if you need more than one NBD device, repeat the above command for nbd1,
  44 nbd2, ...)
  45
  46 Next, write a configuration file for the server. An example looks like
  47 this:
  48
  49     # This is a comment
  50     [generic]
  51         # The [generic] section is required, even if nothing is specified
  52         # there.
  53         # When either of these options are specified, nbd-server drops
  54         # privileges to the given user and group after opening ports, but
  55         # _before_ opening files.
  56         user = nbd
  57         group = nbd
  58     [export1]
  59         exportname = /export/nbd/export1-file
  60         authfile = /export/nbd/export1-authfile
  61         timeout = 30
  62         filesize = 10000000
  63         readonly = false
  64         multifile = false
  65         copyonwrite = false
  66         prerun = dd if=/dev/zero of=%s bs=1k count=500
  67         postrun = rm -f %s
  68     [otherexport]
  69         exportname = /export/nbd/experiment
  70         # The other options are all optional
  71
  72 The configuration file is parsed with GLib's GKeyFile, which parses key
  73 files as they are specified in the Freedesktop.org Desktop Entry
  74 Specification, as can be found at
  75 <http://freedesktop.org/Standards/desktop-entry-spec>. While this format
  76 was not intended to be used for configuration files, the glib API is
  77 flexible enough for it to be used as such.
  78
  79 Now start the server:
  80
  81     nbd-server -C /path/to/configfile
  82
  83 Note that the filename must be an absolute path; i.e., something like
  84 `/path/to/file`, not `../file`. See the nbd-server manpage for details
  85 on any available options.
  86
  87 Finally, you'll be able to start the client:
  88
  89     nbd-client <hostname> -N <export name> <nbd device>
  90
  91 e.g.,
  92
  93     nbd-client 10.0.0.1 -N otherexport /dev/nbd0
  94
  95 will use the second export in the above example (the one that exports
  96 `/export/nbd/experiment`)
  97
  98 `nbd-client` must be ran as root; the same is not true for nbd-server
  99 (but do make sure that /var/run is writeable by the server that
 100 `nbd-server` runs as; otherwise, you won't get a PID file, though the
 101 server will keep running).
 102
 103 There are packages (or similar) available for most current operating
 104 systems; see the "Packaging status" badge below for details.
 105
 106 For questions, please use the [nbd@other.debian.org](mailto:nbd@other.debian.org) mailinglist.
 107
 108 Alternate implementations
 109 =========================
 110
 111 Besides this project, the NBD protocol has been implemented by various
 112 other people. A (probably incomplete) list follows:
 113
 114 * [nbdkit](https://gitlab.com/nbdkit/nbdkit) is a multithreaded NBD
 115   server with a plugin architecture.
 116 * [libnbd](https://gitlab.com/nbdkit/libnbd) is a library to aid in
 117   writing NBD clients
 118 * [qemu](https://www.qemu.org) contains an embedded NBD server, an
 119   embedded NBD client, and a standalone NBD server (`qemu-nbd`). They
 120   maintain a [status
 121   document](https://gitlab.com/qemu-project/qemu/-/blob/master/docs/interop/nbd.txt)
 122   of their NBD implementation.
 123 * A [GEOM gate-based client implementation for
 124   FreeBSD](https://github.com/freqlabs/nbd-client) exists. It has not
 125   seen any updates since 2018, and only implements the client side
 126   (any server should run on FreeBSD unmodified, however).
 127 * A Windows client implementation exists as part of the [RBD
 128   implementation](https://docs.ceph.com/en/latest/rbd/rbd-windows/) of
 129   [Ceph for Windows](https://cloudbase.it/ceph-for-windows/).
 130 * [lwNBD](https://github.com/bignaux/lwNBD) is a NBD server library,
 131   targetting bare metal or OS embedded system. It has a plugin architecture.
 132
 133 Additionally, these implementations once existed but are now no longer
 134 maintained:
 135
 136 * xnbd: This was an NBD implementation with a few extra protocol
 137   messages that allowed for live migration. Its code repository has
 138   disappeared.
 139 * enbd: This was an NBD implementation with a few extra protocol
 140   messages that allowed extra ioctl calls to be passed on (e.g., the
 141   "eject" message for a CD-ROM device that was being exported through
 142   NBD). It appears to no longer be maintained.
 143 * Hurd translator: There was a [proof-of-concept
 144   implementation](https://lists.debian.org/debian-hurd/2001/09/msg00174.html)
 145   of the NBD protocol once as a translator for The Hurd. We do not know
 146   what its current status is.
 147 * Christoph Lohmann once wrote a client implementation for Plan 9. The
 148   link he provided us is now stale; we do not know what its current
 149   status is.
 150
 151 Badges
 152 ======
 153
 154 [![Download Network Block Device](https://img.shields.io/sourceforge/dm/nbd.svg)](https://sourceforge.net/projects/nbd/files/latest/download)
 155 [![Coverity Scan Build Status](https://scan.coverity.com/projects/1243/badge.svg)](https://scan.coverity.com/projects/1243)
 156 [![CII badge](https://bestpractices.coreinfrastructure.org/projects/281/badge)](https://bestpractices.coreinfrastructure.org/projects/281)
 157 [![Travis](https://img.shields.io/travis/NetworkBlockDevice/nbd.svg)](https://travis-ci.org/NetworkBlockDevice/nbd)
 158
 159 [![Packaging status](https://repology.org/badge/vertical-allrepos/nbd.svg)](https://repology.org/metapackage/nbd)