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, and also to run parts
119 For the Perl, example4 and tar plugins:
123 - perl development libraries
125 - perl module ExtUtils::Embed
127 For the Python plugin:
129 - python interpreter (version 3 only)
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 - nbdsh (from libnbd)
169 - qemu-img, qemu-io, qemu-nbd (usually shipped with qemu)
171 - sfdisk (from util-linux)
177 - stat (from coreutils)
182 To build from tarball: To build from git:
183 ---------------------- ------------------
185 ./configure ./configure
187 make check make check
189 To run nbdkit from the source directory, use the top level ./nbdkit
190 wrapper. It will run nbdkit and plugins from the locally compiled
193 $ ./nbdkit example1 -f -v
194 ./server/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
197 Optionally run this command as root to install everything:
204 Since nbdkit >= 1.16, only Python >= 3.3 is supported.
206 By default nbdkit uses the Python version of the Python interpreter
207 called “python” on the current $PATH. If you have parallel versions
208 of Python installed then you can choose a different version by setting
209 the PYTHON variable when configuring. For example:
211 ./configure PYTHON=/usr/bin/python3.8
216 You will need to install libguestfs to run most of the test suite:
220 The test suite is fairly comprehensive. It runs the newly built
221 nbdkit + plugins as a captive process, and tests them using
222 libguestfs. If there is a failure, look at the corresponding
223 ‘tests/*.log’ file for debug information.
225 A few tests require root privileges, and are skipped by default. To
226 run them you must do:
230 If you have the proprietary VDDK library, you can test
231 nbdkit-vddk-plugin against the library like this:
233 make check-vddk vddkdir=vmware-vix-disklib-distrib
238 Tarballs are available from:
239 http://libguestfs.org/download/nbdkit
244 Install the valgrind program and development headers.
248 ./configure --enable-gcc-warnings --enable-valgrind
255 For development ideas, see the TODO file.
257 The upstream git repository is:
258 https://github.com/libguestfs/nbdkit
260 Please send patches to the libguestfs mailing list:
261 https://www.redhat.com/mailman/listinfo/libguestfs
263 For further information, see:
264 http://libguestfs.org/
265 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md