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 - python unittest to run the test suite
135 For the OCaml plugin:
141 - Tcl development library and headers
145 - Lua development library and headers
149 - cargo (other dependencies will be downloaded at build time)
151 For bash tab completion:
153 - bash-completion >= 1.99
155 To test for memory leaks (‘make check-valgrind’):
157 - valgrind program and development headers
159 For non-essential enhancements to the test suite:
161 - ip, ss (from iproute package)
165 - losetup (from util-linux package)
167 - mke2fs (from e2fsprogs)
169 - nbdsh (from libnbd)
171 - qemu-img, qemu-io, qemu-nbd (usually shipped with qemu)
173 - sfdisk (from util-linux)
179 - stat (from coreutils)
184 To build from tarball: To build from git:
185 ---------------------- ------------------
187 ./configure ./configure
189 make check make check
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
195 $ ./nbdkit example1 -f -v
196 ./server/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
199 Optionally run this command as root to install everything:
206 Since nbdkit >= 1.16, only Python >= 3.3 is supported.
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:
213 ./configure PYTHON=/usr/bin/python3.8
218 To run the test suite:
222 If there is a failure, look at the corresponding ‘tests/*.log’ file
223 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