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