README

   1 NBD is a protocol for accessing Block Devices (hard disks and
   2 disk-like things) over a Network.
   3
   4 'nbdkit' is a toolkit for creating NBD servers.
   5
   6 The key features are:
   7
   8  * Multithreaded NBD server written in C with good performance.
   9
  10  * Minimal dependencies for the basic server.
  11
  12  * Liberal license (BSD) allows nbdkit to be linked to proprietary
  13    libraries or included in proprietary code.
  14
  15  * Well-documented, simple plugin API with a stable ABI guarantee.
  16    Lets you export "unconventional" block devices easily.
  17
  18  * You can write plugins in C, Perl, Python, OCaml or Ruby.
  19
  20 For documentation, see the docs/ directory.
  21
  22 For plugins and examples, see the plugins/ directory.
  23
  24 License
  25 -------
  26
  27 This software is copyright (C) Red Hat Inc. and licensed under a BSD
  28 license.  See LICENSE for details.
  29
  30 Building from source
  31 --------------------
  32
  33 By default nbdkit needs nothing except Linux and reasonably recent gcc.
  34
  35 To build the man pages, you will need to install:
  36
  37  - pod2man (included with perl)
  38
  39 There are some *optional* libraries you may want to install for
  40 plugins or extra features.
  41
  42 For TLS support:
  43
  44  - gnutls >= 3.3.0
  45
  46 For the gzip plugin:
  47
  48  - zlib
  49
  50 For the xz plugin:
  51
  52  - liblzma
  53
  54 For the curl (HTTP/FTP) plugin:
  55
  56  - libcurl
  57
  58 For the libvirt plugin:
  59
  60  - libvirt
  61
  62 For the libguestfs plugin, and to run the test suite:
  63
  64  - libguestfs
  65
  66  - guestfish (from libguestfs)
  67
  68 For the VDDK plugin:
  69
  70  - VDDK (see plugins/vddk/README.VDDK)
  71
  72 For the Perl, example4 and tar plugins:
  73
  74  - perl development libraries
  75
  76  - perl module ExtUtils::Embed
  77
  78 For the Python plugin:
  79
  80  - python development libraries
  81    (either version 2 or 3 may be used)
  82
  83 For the OCaml plugin:
  84
  85  - OCaml >= 4.02.2 which has support for shared libraries, see:
  86    http://caml.inria.fr/mantis/view.php?id=6693
  87
  88 To run the test suite:
  89
  90  - bash
  91
  92 To test for memory leaks ('make check-valgrind'):
  93
  94  - valgrind
  95
  96 For non-essential enhancements to the test suite:
  97
  98  - socat
  99
 100  - ss (from iproute package)
 101
 102 After installing any dependencies:
 103
 104   To build from tarball:         To build from git:
 105   ----------------------         ------------------
 106                                  autoreconf -i
 107   ./configure                    ./configure
 108   make                           make
 109   make check                     make check
 110   make check-valgrind            make check-valgrind
 111
 112 To run nbdkit from the source directory, use the top level ./nbdkit
 113 script.  It will run nbdkit and plugins from the locally compiled
 114 directory:
 115
 116   $ ./nbdkit example1 -f -v
 117   ./src/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
 118   [etc]
 119
 120 Optionally run this command as root to install everything:
 121
 122   make install
 123
 124 Python
 125 ------
 126
 127 By default nbdkit uses the Python version of the Python interpreter
 128 called "python" on the current $PATH.  To use another version of
 129 Python you may need to set the PYTHON variable when configuring.  For
 130 example:
 131
 132   ./configure PYTHON=/usr/bin/python3
 133
 134 Tests
 135 -----
 136
 137 You will need to install libguestfs to run most of the test suite:
 138
 139   make check
 140
 141 The test suite is fairly comprehensive.  It runs the newly built
 142 nbdkit + plugins as a captive process, and tests them using
 143 libguestfs.  If there is a failure, look at the corresponding
 144 tests/*.log file for debug information.
 145
 146 You can run the tests under valgrind, if it is available, using:
 147
 148   make check-valgrind
 149
 150 Packager information
 151 --------------------
 152
 153 Tarballs are available from:
 154 http://libguestfs.org/download/nbdkit
 155
 156 Developer information
 157 ---------------------
 158
 159 For development ideas, see the TODO file.
 160
 161 The upstream git repository is:
 162 https://github.com/libguestfs/nbdkit
 163
 164 Please send patches to the libguestfs mailing list:
 165 https://www.redhat.com/mailman/listinfo/libguestfs
 166
 167 For further information, see:
 168 http://libguestfs.org/
 169 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md