NBD — Network Block Device — is a protocol for accessing Block Devices
(hard disks and disk-like things) over a Network.

nbdkit is a toolkit for creating NBD servers.

The key features are:

 * Multithreaded NBD server written in C with good performance.

 * Minimal dependencies for the basic server.

 * Liberal license (BSD) allows nbdkit to be linked to proprietary
   libraries or included in proprietary code.

 * Well-documented, simple plugin API with a stable ABI guarantee.
   Lets you export “unconventional” block devices easily.

 * You can write plugins in C, Lua, Perl, Python, OCaml, Ruby, shell
   script or Tcl.

 * Filters can be stacked in front of plugins to transform the output.

For documentation, see the ‘docs/’ directory.

For plugins, examples and filters, see the ‘plugins/’ and ‘filters/’
directories.

LICENSE
=======

This software is copyright (C) Red Hat Inc. and licensed under a BSD
license.  See ‘LICENSE’ for details.

BUILDING FROM SOURCE
====================

Requirements
------------

To build the basic server and some plugins nbdkit needs nothing except
Linux, FreeBSD or OpenBSD, and:

 - GCC or Clang

 - bash

 - GNU make

Although it is possible to build without it, it’s recommended to
enable TLS (authentication and encryption) support for which you will
need:

 - gnutls >= 3.3.0

Optional dependencies
---------------------

To build the man pages, you will optionally need to install:

 - Perl

 - Pod::Man and Pod::Simple (Perl library)

For SELinux socket labelling support:

 - libselinux

To run the tests:

 - GNU coreutils (for ‘seq’ and some other programs)

For the gzip plugin:

 - zlib

For the xz plugin:

 - liblzma

For the curl (HTTP/FTP) plugin:

 - libcurl

For the iso plugin:

 - genisoimage or mkisofs

For the floppy plugin:

 - iconv (on Linux this is built into glibc, on other systems
   it may be a separate library)

For the libvirt plugin:

 - libvirt

For the libguestfs plugin, and to run parts of the test suite:

 - libguestfs

 - guestfish (from libguestfs)

For the ext2 plugin:

 - ext2fs

 - com_err

For the Perl, example4 and tar plugins:

 - perl interpreter

 - perl development libraries

 - perl module ExtUtils::Embed

For the Python plugin:

 - python interpreter
   (either version 2 or 3 may be used)

 - python development libraries

For the OCaml plugin:

 - OCaml >= 4.02.2

For the Tcl plugin:

 - Tcl development library and headers

For the Lua plugin:

 - Lua development library and headers

For bash tab completion:

 - bash-completion >= 1.99

To test for memory leaks (‘make check-valgrind’):

 - valgrind program and development headers

For non-essential enhancements to the test suite:

 - losetup (from util-linux package)

 - od (from coreutils)

 - qemu-io (usually shipped with qemu)

 - socat

 - ss (from iproute package)

Building
--------

    To build from tarball:         To build from git:
    ----------------------         ------------------
                                   autoreconf -i
    ./configure                    ./configure
    make                           make
    make check                     make check

To run nbdkit from the source directory, use the top level ./nbdkit
wrapper.  It will run nbdkit and plugins from the locally compiled
directory:

    $ ./nbdkit example1 -f -v
    ./server/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
    [etc]

Optionally run this command as root to install everything:

    make install

Python
------

By default nbdkit uses the Python version of the Python interpreter
called “python” on the current $PATH.  To use another version of
Python you may need to set the PYTHON variable when configuring.  For
example:

    ./configure PYTHON=/usr/bin/python3

Running the tests
-----------------

You will need to install libguestfs to run most of the test suite:

    make check

The test suite is fairly comprehensive.  It runs the newly built
nbdkit + plugins as a captive process, and tests them using
libguestfs.  If there is a failure, look at the corresponding
‘tests/*.log’ file for debug information.

A few tests require root privileges, and are skipped by default.  To
run them you must do:

    sudo make check-root

DOWNLOAD TARBALLS
=================

Tarballs are available from:
http://libguestfs.org/download/nbdkit

DEVELOPERS
==========

Install the valgrind program and development headers.

Use:

    ./configure --enable-gcc-warnings --enable-valgrind

When testing use:

    make check
    make check-valgrind

For development ideas, see the TODO file.

The upstream git repository is:
https://github.com/libguestfs/nbdkit

Please send patches to the libguestfs mailing list:
https://www.redhat.com/mailman/listinfo/libguestfs

For further information, see:
http://libguestfs.org/
https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md