README

   1 NBD — Network Block Device — is a protocol for accessing Block Devices
   2 (hard disks and 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, Lua, Perl, Python, OCaml, Ruby, Rust,
  19    shell script or Tcl.
  20
  21  * Filters can be stacked in front of plugins to transform the output.
  22
  23 For documentation, see the ‘docs/’ directory.
  24
  25 For plugins, examples and filters, see the ‘plugins/’ and ‘filters/’
  26 directories.
  27
  28 LICENSE
  29 =======
  30
  31 This software is copyright (C) Red Hat Inc. and licensed under a BSD
  32 license.  See ‘LICENSE’ for details.
  33
  34 BUILDING FROM SOURCE
  35 ====================
  36
  37 Requirements
  38 ------------
  39
  40 To build the basic server and some plugins nbdkit needs nothing except
  41 Linux, FreeBSD or OpenBSD, and:
  42
  43  - GCC or Clang
  44
  45  - bash
  46
  47  - GNU make
  48
  49 Although it is possible to build without it, it’s recommended to
  50 enable TLS (authentication and encryption) support for which you will
  51 need:
  52
  53  - gnutls >= 3.3.0
  54
  55 Optional dependencies
  56 ---------------------
  57
  58 To build the man pages, you will optionally need to install:
  59
  60  - Perl
  61
  62  - Pod::Man and Pod::Simple (Perl library)
  63
  64 For SELinux socket labelling support:
  65
  66  - libselinux
  67
  68 For the gzip plugin:
  69
  70  - zlib
  71
  72 For the xz filter:
  73
  74  - liblzma
  75
  76 For the curl (HTTP/FTP) plugin:
  77
  78  - libcurl
  79
  80 For the ssh plugin:
  81
  82  - libssh >= 0.8.0
  83    (this is a different library from libssh2 - that will not work)
  84
  85 For the iso plugin:
  86
  87  - genisoimage or mkisofs
  88
  89 For the floppy plugin:
  90
  91  - iconv (on Linux this is built into glibc, on other systems
  92    it may be a separate library)
  93
  94 For the libvirt plugin:
  95
  96  - libvirt
  97
  98 For the libguestfs plugin, and to run parts of the test suite:
  99
 100  - libguestfs
 101
 102  - guestfish (from libguestfs)
 103
 104 For the ext2 plugin:
 105
 106  - ext2fs
 107
 108  - com_err
 109
 110 For the linuxdisk plugin:
 111
 112  - mke2fs >= 1.42.10 (from e2fsprogs)
 113
 114 For the Perl, example4 and tar plugins:
 115
 116  - perl interpreter
 117
 118  - perl development libraries
 119
 120  - perl module ExtUtils::Embed
 121
 122 For the Python plugin:
 123
 124  - python interpreter
 125    (either version 2 or 3 may be used)
 126
 127  - python development libraries
 128
 129 For the OCaml plugin:
 130
 131  - OCaml >= 4.02.2
 132
 133 For the Tcl plugin:
 134
 135  - Tcl development library and headers
 136
 137 For the Lua plugin:
 138
 139  - Lua development library and headers
 140
 141 For the Rust plugin:
 142
 143  - cargo (other dependencies will be downloaded at build time)
 144
 145 For bash tab completion:
 146
 147  - bash-completion >= 1.99
 148
 149 To test for memory leaks (‘make check-valgrind’):
 150
 151  - valgrind program and development headers
 152
 153 For non-essential enhancements to the test suite:
 154
 155  - ip, ss (from iproute package)
 156
 157  - jq
 158
 159  - losetup (from util-linux package)
 160
 161  - mke2fs (from e2fsprogs)
 162
 163  - qemu-img, qemu-io, qemu-nbd (usually shipped with qemu)
 164
 165  - sfdisk (from util-linux)
 166
 167  - socat
 168
 169  - ssh-keygen
 170
 171  - stat (from coreutils)
 172
 173 Building
 174 --------
 175
 176     To build from tarball:         To build from git:
 177     ----------------------         ------------------
 178                                    autoreconf -i
 179     ./configure                    ./configure
 180     make                           make
 181     make check                     make check
 182
 183 To run nbdkit from the source directory, use the top level ./nbdkit
 184 wrapper.  It will run nbdkit and plugins from the locally compiled
 185 directory:
 186
 187     $ ./nbdkit example1 -f -v
 188     ./server/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
 189     [etc]
 190
 191 Optionally run this command as root to install everything:
 192
 193     make install
 194
 195 Python
 196 ------
 197
 198 By default nbdkit uses the Python version of the Python interpreter
 199 called “python” on the current $PATH.  To use another version of
 200 Python you may need to set the PYTHON variable when configuring.  For
 201 example:
 202
 203     ./configure PYTHON=/usr/bin/python3
 204
 205 Running the tests
 206 -----------------
 207
 208 You will need to install libguestfs to run most of the test suite:
 209
 210     make check
 211
 212 The test suite is fairly comprehensive.  It runs the newly built
 213 nbdkit + plugins as a captive process, and tests them using
 214 libguestfs.  If there is a failure, look at the corresponding
 215 ‘tests/*.log’ file for debug information.
 216
 217 A few tests require root privileges, and are skipped by default.  To
 218 run them you must do:
 219
 220     sudo make check-root
 221
 222 If you have the proprietary VDDK library, you can test
 223 nbdkit-vddk-plugin against the library like this:
 224
 225     make check-vddk vddkdir=vmware-vix-disklib-distrib
 226
 227 DOWNLOAD TARBALLS
 228 =================
 229
 230 Tarballs are available from:
 231 http://libguestfs.org/download/nbdkit
 232
 233 DEVELOPERS
 234 ==========
 235
 236 Install the valgrind program and development headers.
 237
 238 Use:
 239
 240     ./configure --enable-gcc-warnings --enable-valgrind
 241
 242 When testing use:
 243
 244     make check
 245     make check-valgrind
 246
 247 For development ideas, see the TODO file.
 248
 249 The upstream git repository is:
 250 https://github.com/libguestfs/nbdkit
 251
 252 Please send patches to the libguestfs mailing list:
 253 https://www.redhat.com/mailman/listinfo/libguestfs
 254
 255 For further information, see:
 256 http://libguestfs.org/
 257 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md