NBD client library in userspace NBD — Network Block Device — is a protocol for accessing Block Devices (hard disks and disk-like things) over a Network. This is the NBD client library in userspace, a simple library for writing NBD clients. The key features are: * Synchronous API for ease of use. * Asynchronous API for writing non-blocking, multithreaded clients. You can mix both APIs freely. * High performance. * Minimal dependencies for the basic library. * Well-documented, stable API. * Bindings in several programming languages. * Shell (nbdsh) for command line and scripting. * Copying tool (nbdcopy) for high performance copying and streaming. * Query tool (nbdinfo) to query NBD servers. * FUSE support (nbdfuse) to mount NBD in the local filesystem. For documentation, see the ‘docs/’ and ‘examples/’ subdirectories. LICENSE ======= The software is copyright © Red Hat Inc. and licensed under the GNU Lesser General Public License version 2 or above (LGPLv2+). See the file ‘COPYING.LIB’ for details. The examples are under a very liberal license. BUILDING FROM SOURCE ==================== To build from git: autoreconf -i ./configure make make check To build from tarball: ./configure make make check To run the tests under valgrind: make check-valgrind To run benchmarks: make bench Some tests require root permissions (and are therefore risky). If you want to run these tests, do: sudo make check-root Requirements: * Linux, FreeBSD or OpenBSD. Other OSes may also work but we have only tested these three. * GCC or Clang * GNU make * bash Required for building from git, optional for building from tarballs: * OCaml (ocamlc, the bytecode compiler) is required to generate some source files, which is needed to build from git. However ocamlc is _not_ needed if building from the official tarballs from http://download.libguestfs.org/libnbd/ because those contain the generated files. Recommended - if not present, some features will be disabled: * GnuTLS is recommended for TLS support. If not available then you will not be able to access encrypted servers and some APIs related to TLS will always return an error. * libxml2 is recommended for NBD URI support. If not available then a few APIs related to URIs will always return an error, and the nbdinfo tool is not built. Optional: * Perl Pod::Man and Pod::Simple to generate the documentation. * OCaml and ocamlfind are both needed to generate the OCaml bindings. * Python >= 3.3 to build the Python 3 bindings and NBD shell (nbdsh). * FUSE 3 to build the nbdfuse program. * go and cgo, for compiling the golang bindings and tests. * bash-completion >= 1.99 for tab completion. Optional, only needed to run the test suite: * nbdkit >= 1.12, the nbdkit basic plugins and the nbdkit basic filters are recommended as they are needed to run the test suite. * nbdkit, nbd-server, qemu-nbd and qemu-storage-daemon if you want to do interoperability testing against these servers. * A C++ compiler is needed if you want to test that the library works from C++. * coreutils or standard Unix tools such as cmp, dd, stat, truncate. * libdl (dlopen, dlclose etc) to test this functionality. * qemu, qemu-io, qemu-img for interoperability testing. * certtool and psktool (part of GnuTLS) for testing TLS support. * valgrind if you want to run the tests under valgrind. * nbd-client and Linux nbd.ko for testing nbdcopy to/from devices. * flake8 to keep Python code formatted uniformly. * ss (from iproute) for TCP-based tests. Optional, only needed to run some examples: * glib2 for examples that interoperate with the glib main loop. * libev for examples that interoperate with the libev library. DOWNLOAD TARBALLS ================= Tarballs are available from: http://libguestfs.org/download/libnbd DEVELOPERS ========== Install the valgrind program and development headers. Use: ./configure --enable-gcc-warnings --enable-python-code-style When testing use: make check make check-valgrind For development ideas, see the TODO file. The upstream git repository is: https://gitlab.com/nbdkit/libnbd Patches are accepted either by email to the upstream mailing list: https://www.redhat.com/mailman/listinfo/libguestfs or by Merge Request on gitlab.com If you want to fuzz the library see fuzzing/README. OTHER LINKS =========== http://libguestfs.org/ https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md https://gitlab.com/nbdkit/nbdkit