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