1 ## NBD server with stable plugin ABI and permissive license
3 nbdkit is an NBD server. NBD — Network Block Device — is a protocol
4 for accessing Block Devices (hard disks and disk-like things) over a
7 The key features of nbdkit are:
9 * Multithreaded NBD server written in C with good performance.
10 * Minimal dependencies for the basic server.
11 * Liberal license (BSD) allows nbdkit to be linked to proprietary
12 libraries or included in proprietary code.
13 * Well-documented, simple plugin API with a stable ABI guarantee.
14 Lets you export “unconventional” block devices easily.
15 * You can write plugins in C/C++, Go, Lua, Perl, Python, OCaml, Ruby,
16 Rust, shell script or Tcl.
17 * Filters can be stacked in front of plugins to transform the output.
19 For documentation, see the [docs directory](docs/).
21 For plugins and filters, see the [plugins](plugins/) and
22 [filters](filters/) directories. Example plugins can be found in
25 There are many NBD clients, but the nbdkit project has a companion
26 client library called https://gitlab.com/nbdkit/libnbd
28 https://gitlab.com/nbdkit/nbdkit
32 This software is copyright (C) Red Hat Inc. and licensed under a BSD
33 license. See [LICENSE](LICENSE) for details.
35 ## Building from source
39 * Linux, macOS, Windows, FreeBSD, OpenBSD or Haiku
44 Recommended for TLS (authentication and encryption) support, but it is
45 possible to build without it:
49 For Windows support see [the Windows section below](README.md#windows).
51 For macOS support see [the macOS section below](README.md#macos).
53 ### Optional dependencies
55 To build the man pages, you will optionally need to install:
58 * Pod::Man and Pod::Simple (Perl libraries)
60 For SELinux socket labelling support:
72 For the memory plugin with allocator=zstd:
76 For the curl (HTTP/FTP) plugin:
83 (this is a different library from libssh2 - that will not work)
87 * xorriso or 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:
101 * guestfish (from libguestfs)
108 For the linuxdisk plugin:
110 * mke2fs >= 1.42.10 (from e2fsprogs)
112 For the nbd plugin, to get URI and TLS support, and also to run parts
117 For the bittorrent plugin:
119 * [libtorrent-rasterbar](https://www.libtorrent.org)
121 For the containerized data importer (CDI) plugin:
126 For the Perl and example4 plugins:
129 * perl development libraries
130 * perl modules ExtUtils::Embed
132 For the Python plugin:
134 * python interpreter (version 3 only)
135 * python development libraries
136 * python unittest to run the test suite
137 * boto3 is required to run the S3 plugin written in Python
139 For the OCaml plugin:
145 * Tcl development library and headers
149 * Lua development library and headers
153 * cargo (other dependencies will be downloaded at build time)
155 To be able to write plugins in golang:
159 For bash tab completion:
161 * bash-completion >= 1.99
163 To test for memory leaks (`make check-valgrind`):
165 * valgrind program and development headers
167 For non-essential enhancements to the test suite:
172 * ip, ss (from iproute package)
174 * losetup (from util-linux package)
175 * mke2fs (from e2fsprogs)
176 * nbdcopy, nbdinfo, nbdsh (from libnbd)
177 * qemu-img, qemu-io, qemu-nbd (usually shipped with qemu)
178 * sfdisk (from util-linux)
180 * stat (from coreutils)
185 To build from tarball: To build from git:
188 ./configure ./configure
190 make check make check
193 On FreeBSD and OpenBSD which do not have GNU make by default you must
194 use `gmake` instead of `make`.
196 To run nbdkit from the source directory, use the top level ./nbdkit
197 wrapper. It will run nbdkit and plugins from the locally compiled
201 $ ./nbdkit example1 -f -v
202 ./server/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
206 Optionally run this command as root to install everything:
214 Since nbdkit >= 1.16, only Python >= 3.6 is supported.
216 By default nbdkit uses the Python version of the Python interpreter
217 called “python” on the current $PATH. If you have parallel versions
218 of Python installed then you can choose a different version by setting
219 the PYTHON variable when configuring. For example:
222 ./configure PYTHON=/usr/bin/python3.8
227 Most recent (less than, say, 8 years old) versions of the OCaml
228 compiler should work. By default the configure script should detect
229 the bytecode and native code compilers and enable either one or both.
231 To enable OCaml warnings and turn them into hard errors (developers only):
234 ./configure OCAMLOPTFLAGS="-warn-error +A-3"
237 ### Running the tests
239 To run the test suite:
245 If there is a failure, look at the corresponding `tests/*.log` file
246 for debug information.
248 A few tests require root privileges, and are skipped by default. To
249 run them you must do:
255 If you have the proprietary VDDK library, you can test
256 [nbdkit-vddk-plugin](plugins/vddk/) against the library like this:
259 make check-vddk vddkdir=vmware-vix-disklib-distrib
262 ### Running the benchmarks
272 Tarballs are available from:
273 http://libguestfs.org/download/nbdkit
275 ## Downstream packagers
277 If you are packaging nbdkit, use:
280 ./configure --with-extra='...'
283 providing extra information about the distribution, and/or
284 distro-specific versions. It helps us with troubleshooting bug
285 reports. (Also, talk to us!)
289 Install the valgrind program and development headers.
294 ./configure --enable-gcc-warnings --enable-valgrind
304 For development ideas, see the [TODO](TODO) file.
306 The upstream git repository is:
307 https://gitlab.com/nbdkit/nbdkit
309 Please send patches to the libguestfs mailing list:
310 https://www.redhat.com/mailman/listinfo/libguestfs
312 For further information, see:
313 https://libguestfs.org/
314 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
316 ## Address sanitizer (ASAN)
318 You can compile nbdkit with clang and ASAN with:
321 ./configure CC=clang CXX=clang++ \
322 CFLAGS="-O0 -g -fsanitize=address -fno-omit-frame-pointer" \
323 --disable-linker-script \
327 ASAN_OPTIONS="allocator_may_return_null=1 detect_leaks=false" make check
333 ./configure CFLAGS="--coverage -g" LDFLAGS="--coverage -g"
338 lcov -c -d . -o gcov.info
339 genhtml -o coverage gcov.info
342 Open your browser and examine the `coverage/` directory. At the time
343 of writing (2020-04) test coverage of the server is reasonable, but
344 things are much worse for certain plugins and filters.
348 nbdkit works on macOS and is mostly feature complete. Some tests may
351 We have tested macOS 12 (Monterey) using MacPorts. Other versions of
352 macOS and Homebrew may work too.
354 We installed the following MacPorts packages:
372 We configured nbdkit using:
375 ./configure --enable-gcc-warnings --disable-perl \
376 CFLAGS="-g -O2 -I/opt/local/include" \
377 LDFLAGS="-L/opt/local/lib"
382 Experimentally, the server can be compiled on Windows or
383 cross-compiled from Linux using mingw-w64. Only a small subset of
384 features are available. To find out what is missing read the TODO
387 Note that GCC or Clang is required even if you are compiling on
388 Windows because of some C language extensions we use. MSVC will not
391 ### Cross-compiling from Linux to Windows
393 For the rest of this section we talk about cross-compiling for Windows
394 using Linux and mingw-w64. At a minimum you will need:
398 * mingw-w64 winpthreads
399 * mingw-w64 gnutls (optional, but highly recommended)
400 * wine (if you want to run it on Linux)
402 You may want to patch Wine with this patch which adds support for
403 AF_UNIX sockets. It is needed to get most of the test suite to work,
404 but if you don't care about the -U option then it is not needed.
405 https://www.winehq.org/pipermail/wine-devel/2021-May/187049.html
407 Other mingw-w64 libraries may be installed which will add
408 functionality (see full list of requirements above), but you may end
409 up hitting areas we have not compiled or tested before.
414 mingw64-configure --disable-ocaml --disable-perl --disable-vddk
418 You can test if the server is working by doing:
421 ./nbdkit.exe --dump-config
424 (This usually runs wine automatically. If not, you may need to prefix
425 the command "wine nbdkit.exe ...")
427 To see which plugins and filters were compiled:
430 find plugins filters -name '*.dll'
433 You can run them under Wine without installing using eg:
436 ./nbdkit.exe -f -v memory 1G
439 You can run the test suite in the usual way:
445 ### Running the cross-compiled binary on Windows
447 To test the binary on a real Windows system you will need to copy
448 server/.libs/nbdkit.exe, any plugins and filters you need
449 (`plugins/*/.libs/*.dll` and `filters/*/.libs/*.dll`), and many mingw
450 DLLs (`libdl.dll`, `libgnutls.dll`, `libwinpthread.dll`, etc.).
454 1. libtool creates files called nbdkit.exe in the top level directory
455 and in [server](server/). These are the stripped binaries. The
456 "real" binaries are located in hidden `.libs/` subdirectories.
458 2. The top level `.libs/nbdkit.exe` is the wrapper used to run nbdkit
459 from the build directory, not the server binary. You need
460 `server/.libs/nbdkit.exe` instead.
462 3. To find the list of mingw DLLs I ran nbdkit.exe iteratively until
463 Windows stopped complaining about missing libraries. You could also
464 use a tool like Dependency Walker.
466 If you copy everything into a single directory on the Windows server
467 then you should be able to run nbdkit normally, eg:
470 nbdkit.exe -f -v nbdkit-memory-plugin.dll 1G
473 You will probably need to open port 10809 on the Windows Firewall.