1 NBD — Network Block Device — is a protocol for accessing Block Devices
2 (hard disks and disk-like things) over a Network.
4 nbdkit is a toolkit for creating NBD servers.
8 * Multithreaded NBD server written in C with good performance.
10 * Minimal dependencies for the basic server.
12 * Liberal license (BSD) allows nbdkit to be linked to proprietary
13 libraries or included in proprietary code.
15 * Well-documented, simple plugin API with a stable ABI guarantee.
16 Lets you export “unconventional” block devices easily.
18 * You can write plugins in C, Lua, Perl, Python, OCaml, Ruby, Rust,
21 * Filters can be stacked in front of plugins to transform the output.
23 For documentation, see the ‘docs/’ directory.
25 For plugins, examples and filters, see the ‘plugins/’ and ‘filters/’
31 This software is copyright (C) Red Hat Inc. and licensed under a BSD
32 license. See ‘LICENSE’ for details.
40 To build the basic server and some plugins nbdkit needs nothing except
41 Linux, FreeBSD or OpenBSD, and:
49 Although it is possible to build without it, it’s recommended to
50 enable TLS (authentication and encryption) support for which you will
58 To build the man pages, you will optionally need to install:
62 - Pod::Man and Pod::Simple (Perl library)
64 For SELinux socket labelling support:
76 For the curl (HTTP/FTP) plugin:
83 (this is a different library from libssh2 - that will not work)
87 - genisoimage or mkisofs
89 For the floppy plugin:
91 - iconv (on Linux this is built into glibc, on other systems
92 it may be a separate library)
94 For the libvirt plugin:
98 For the libguestfs plugin, and to run parts of the test suite:
102 - guestfish (from libguestfs)
110 For the linuxdisk plugin:
112 - mke2fs >= 1.42.10 (from e2fsprogs)
114 For the nbd plugin, to get URI and TLS support:
118 For the Perl, example4 and tar plugins:
122 - perl development libraries
124 - perl module ExtUtils::Embed
126 For the Python plugin:
129 (either version 2 or 3 may be used)
131 - python development libraries
133 For the OCaml plugin:
139 - Tcl development library and headers
143 - Lua development library and headers
147 - cargo (other dependencies will be downloaded at build time)
149 For bash tab completion:
151 - bash-completion >= 1.99
153 To test for memory leaks (‘make check-valgrind’):
155 - valgrind program and development headers
157 For non-essential enhancements to the test suite:
159 - ip, ss (from iproute package)
163 - losetup (from util-linux package)
165 - mke2fs (from e2fsprogs)
167 - qemu-img, qemu-io, qemu-nbd (usually shipped with qemu)
169 - sfdisk (from util-linux)
175 - stat (from coreutils)
180 To build from tarball: To build from git:
181 ---------------------- ------------------
183 ./configure ./configure
185 make check make check
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
191 $ ./nbdkit example1 -f -v
192 ./server/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
195 Optionally run this command as root to install everything:
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
207 ./configure PYTHON=/usr/bin/python3
212 You will need to install libguestfs to run most of the test suite:
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.
221 A few tests require root privileges, and are skipped by default. To
222 run them you must do:
226 If you have the proprietary VDDK library, you can test
227 nbdkit-vddk-plugin against the library like this:
229 make check-vddk vddkdir=vmware-vix-disklib-distrib
234 Tarballs are available from:
235 http://libguestfs.org/download/nbdkit
240 Install the valgrind program and development headers.
244 ./configure --enable-gcc-warnings --enable-valgrind
251 For development ideas, see the TODO file.
253 The upstream git repository is:
254 https://github.com/libguestfs/nbdkit
256 Please send patches to the libguestfs mailing list:
257 https://www.redhat.com/mailman/listinfo/libguestfs
259 For further information, see:
260 http://libguestfs.org/
261 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md