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, FreeBSD, OpenBSD or Haiku
44 Recommended for TLS (authentication and encryption) support, but it is
45 possible to build without it:
49 nbdkit also works on Windows, but dependencies are more complicated.
50 See the separate section at the end of this document.
52 ### Optional dependencies
54 To build the man pages, you will optionally need to install:
57 * Pod::Man and Pod::Simple (Perl libraries)
59 For SELinux socket labelling support:
71 For the memory plugin with allocator=zstd:
75 For the curl (HTTP/FTP) plugin:
82 (this is a different library from libssh2 - that will not work)
86 * xorriso or genisoimage or mkisofs
88 For the floppy plugin:
90 * iconv (on Linux this is built into glibc, on other systems
91 it may be a separate library)
93 For the libvirt plugin:
97 For the libguestfs plugin, and to run parts of the test suite:
100 * guestfish (from libguestfs)
107 For the linuxdisk plugin:
109 * mke2fs >= 1.42.10 (from e2fsprogs)
111 For the nbd plugin, to get URI and TLS support, and also to run parts
116 For the bittorrent plugin:
118 * [libtorrent-rasterbar](https://www.libtorrent.org)
120 For the containerized data importer (CDI) plugin:
125 For the Perl and example4 plugins:
128 * perl development libraries
129 * perl modules ExtUtils::Embed
131 For the Python plugin:
133 * python interpreter (version 3 only)
134 * python development libraries
135 * python unittest to run the test suite
136 * boto3 is required to run the S3 plugin written in Python
138 For the OCaml plugin:
144 * Tcl development library and headers
148 * Lua development library and headers
152 * cargo (other dependencies will be downloaded at build time)
154 To be able to write plugins in golang:
158 For bash tab completion:
160 * bash-completion >= 1.99
162 To test for memory leaks (`make check-valgrind`):
164 * valgrind program and development headers
166 For non-essential enhancements to the test suite:
171 * ip, ss (from iproute package)
173 * losetup (from util-linux package)
174 * mke2fs (from e2fsprogs)
175 * nbdcopy, nbdinfo, nbdsh (from libnbd)
176 * qemu-img, qemu-io, qemu-nbd (usually shipped with qemu)
177 * sfdisk (from util-linux)
179 * stat (from coreutils)
184 To build from tarball: To build from git:
187 ./configure ./configure
189 make check make check
192 To run nbdkit from the source directory, use the top level ./nbdkit
193 wrapper. It will run nbdkit and plugins from the locally compiled
197 $ ./nbdkit example1 -f -v
198 ./server/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
202 Optionally run this command as root to install everything:
210 Since nbdkit >= 1.16, only Python >= 3.6 is supported.
212 By default nbdkit uses the Python version of the Python interpreter
213 called “python” on the current $PATH. If you have parallel versions
214 of Python installed then you can choose a different version by setting
215 the PYTHON variable when configuring. For example:
218 ./configure PYTHON=/usr/bin/python3.8
223 Most recent (less than, say, 8 years old) versions of the OCaml
224 compiler should work. By default the configure script should detect
225 the bytecode and native code compilers and enable either one or both.
227 To enable OCaml warnings and turn them into hard errors (developers only):
230 ./configure OCAMLOPTFLAGS="-warn-error +A-3"
233 ### Running the tests
235 To run the test suite:
241 If there is a failure, look at the corresponding `tests/*.log` file
242 for debug information.
244 A few tests require root privileges, and are skipped by default. To
245 run them you must do:
251 If you have the proprietary VDDK library, you can test
252 [nbdkit-vddk-plugin](plugins/vddk/) against the library like this:
255 make check-vddk vddkdir=vmware-vix-disklib-distrib
258 ### Running the benchmarks
268 Tarballs are available from:
269 http://libguestfs.org/download/nbdkit
271 ## Downstream packagers
273 If you are packaging nbdkit, use:
276 ./configure --with-extra='...'
279 providing extra information about the distribution, and/or
280 distro-specific versions. It helps us with troubleshooting bug
281 reports. (Also, talk to us!)
285 Install the valgrind program and development headers.
290 ./configure --enable-gcc-warnings --enable-valgrind
300 For development ideas, see the [TODO](TODO) file.
302 The upstream git repository is:
303 https://gitlab.com/nbdkit/nbdkit
305 Please send patches to the libguestfs mailing list:
306 https://www.redhat.com/mailman/listinfo/libguestfs
308 For further information, see:
309 https://libguestfs.org/
310 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
312 ## Address sanitizer (ASAN)
314 You can compile nbdkit with clang and ASAN with:
317 ./configure CC=clang CXX=clang++ \
318 CFLAGS="-O0 -g -fsanitize=address -fno-omit-frame-pointer" \
319 --disable-linker-script \
323 ASAN_OPTIONS="allocator_may_return_null=1 detect_leaks=false" make check
329 ./configure CFLAGS="--coverage -g" LDFLAGS="--coverage -g"
334 lcov -c -d . -o gcov.info
335 genhtml -o coverage gcov.info
338 Open your browser and examine the `coverage/` directory. At the time
339 of writing (2020-04) test coverage of the server is reasonable, but
340 things are much worse for certain plugins and filters.
344 Experimentally, the server can be compiled on Windows or
345 cross-compiled from Linux using mingw-w64. Only a small subset of
346 features are available. To find out what is missing read the TODO
349 Note that GCC or Clang is required even if you are compiling on
350 Windows because of some C language extensions we use. MSVC will not
353 ### Cross-compiling from Linux to Windows
355 For the rest of this section we talk about cross-compiling for Windows
356 using Linux and mingw-w64. At a minimum you will need:
360 * mingw-w64 winpthreads
361 * mingw-w64 gnutls (optional, but highly recommended)
362 * wine (if you want to run it on Linux)
364 You may want to patch Wine with this patch which adds support for
365 AF_UNIX sockets. It is needed to get most of the test suite to work,
366 but if you don't care about the -U option then it is not needed.
367 https://www.winehq.org/pipermail/wine-devel/2021-May/187049.html
369 Other mingw-w64 libraries may be installed which will add
370 functionality (see full list of requirements above), but you may end
371 up hitting areas we have not compiled or tested before.
376 mingw64-configure --disable-ocaml --disable-perl --disable-vddk
380 You can test if the server is working by doing:
383 ./nbdkit.exe --dump-config
386 (This usually runs wine automatically. If not, you may need to prefix
387 the command "wine nbdkit.exe ...")
389 To see which plugins and filters were compiled:
392 find plugins filters -name '*.dll'
395 You can run them under Wine without installing using eg:
398 ./nbdkit.exe -f -v memory 1G
401 You can run the test suite in the usual way:
407 ### Running the cross-compiled binary on Windows
409 To test the binary on a real Windows system you will need to copy
410 server/.libs/nbdkit.exe, any plugins and filters you need
411 (`plugins/*/.libs/*.dll` and `filters/*/.libs/*.dll`), and many mingw
412 DLLs (`libdl.dll`, `libgnutls.dll`, `libwinpthread.dll`, etc.).
416 1. libtool creates files called nbdkit.exe in the top level directory
417 and in [server](server/). These are the stripped binaries. The
418 "real" binaries are located in hidden `.libs/` subdirectories.
420 2. The top level `.libs/nbdkit.exe` is the wrapper used to run nbdkit
421 from the build directory, not the server binary. You need
422 `server/.libs/nbdkit.exe` instead.
424 3. To find the list of mingw DLLs I ran nbdkit.exe iteratively until
425 Windows stopped complaining about missing libraries. You could also
426 use a tool like Dependency Walker.
428 If you copy everything into a single directory on the Windows server
429 then you should be able to run nbdkit normally, eg:
432 nbdkit.exe -f -v nbdkit-memory-plugin.dll 1G
435 You will probably need to open port 10809 on the Windows Firewall.