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 nbd plugin, to get URI and TLS support:
 115
 116  - libnbd >= 0.9.6
 117
 118 For the Perl, example4 and tar plugins:
 119
 120  - perl interpreter
 121
 122  - perl development libraries
 123
 124  - perl module ExtUtils::Embed
 125
 126 For the Python plugin:
 127
 128  - python interpreter
 129    (either version 2 or 3 may be used)
 130
 131  - python development libraries
 132
 133 For the OCaml plugin:
 134
 135  - OCaml >= 4.02.2
 136
 137 For the Tcl plugin:
 138
 139  - Tcl development library and headers
 140
 141 For the Lua plugin:
 142
 143  - Lua development library and headers
 144
 145 For the Rust plugin:
 146
 147  - cargo (other dependencies will be downloaded at build time)
 148
 149 For bash tab completion:
 150
 151  - bash-completion >= 1.99
 152
 153 To test for memory leaks (‘make check-valgrind’):
 154
 155  - valgrind program and development headers
 156
 157 For non-essential enhancements to the test suite:
 158
 159  - ip, ss (from iproute package)
 160
 161  - jq
 162
 163  - losetup (from util-linux package)
 164
 165  - mke2fs (from e2fsprogs)
 166
 167  - qemu-img, qemu-io, qemu-nbd (usually shipped with qemu)
 168
 169  - sfdisk (from util-linux)
 170
 171  - socat
 172
 173  - ssh-keygen
 174
 175  - stat (from coreutils)
 176
 177 Building
 178 --------
 179
 180     To build from tarball:         To build from git:
 181     ----------------------         ------------------
 182                                    autoreconf -i
 183     ./configure                    ./configure
 184     make                           make
 185     make check                     make check
 186
 187 To run nbdkit from the source directory, use the top level ./nbdkit
 188 wrapper.  It will run nbdkit and plugins from the locally compiled
 189 directory:
 190
 191     $ ./nbdkit example1 -f -v
 192     ./server/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
 193     [etc]
 194
 195 Optionally run this command as root to install everything:
 196
 197     make install
 198
 199 Python
 200 ------
 201
 202 By default nbdkit uses the Python version of the Python interpreter
 203 called “python” on the current $PATH.  To use another version of
 204 Python you may need to set the PYTHON variable when configuring.  For
 205 example:
 206
 207     ./configure PYTHON=/usr/bin/python3
 208
 209 Running the tests
 210 -----------------
 211
 212 You will need to install libguestfs to run most of the test suite:
 213
 214     make check
 215
 216 The test suite is fairly comprehensive.  It runs the newly built
 217 nbdkit + plugins as a captive process, and tests them using
 218 libguestfs.  If there is a failure, look at the corresponding
 219 ‘tests/*.log’ file for debug information.
 220
 221 A few tests require root privileges, and are skipped by default.  To
 222 run them you must do:
 223
 224     sudo make check-root
 225
 226 If you have the proprietary VDDK library, you can test
 227 nbdkit-vddk-plugin against the library like this:
 228
 229     make check-vddk vddkdir=vmware-vix-disklib-distrib
 230
 231 DOWNLOAD TARBALLS
 232 =================
 233
 234 Tarballs are available from:
 235 http://libguestfs.org/download/nbdkit
 236
 237 DEVELOPERS
 238 ==========
 239
 240 Install the valgrind program and development headers.
 241
 242 Use:
 243
 244     ./configure --enable-gcc-warnings --enable-valgrind
 245
 246 When testing use:
 247
 248     make check
 249     make check-valgrind
 250
 251 For development ideas, see the TODO file.
 252
 253 The upstream git repository is:
 254 https://github.com/libguestfs/nbdkit
 255
 256 Please send patches to the libguestfs mailing list:
 257 https://www.redhat.com/mailman/listinfo/libguestfs
 258
 259 For further information, see:
 260 http://libguestfs.org/
 261 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md