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