NBD server toolkit with stable ABI and permissive license. PLEASE DO NOT USE GITHUB FOR ISSUES OR PULL REQUESTS. See the website for how to file a bug or contact us. http://libguestfs.org
C Shell Makefile M4 Perl OCaml Other
Clone or download
Latest commit 30b1cb3 Jul 20, 2018

README

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 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 and reasonably recent gcc or clang.

Although it is possible to build without it, it’s recommended to
enable TLS 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 the gzip plugin:

 - zlib

For the xz plugin:

 - liblzma

For the curl (HTTP/FTP) plugin:

 - libcurl

For the libvirt plugin:

 - libvirt

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

 - libguestfs

 - guestfish (from libguestfs)

For the ext2 plugin:

 - ext2fs

 - com_err

For the VDDK plugin:

 - VDDK (see plugins/vddk/README.VDDK)

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 run the test suite:

 - bash

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

 - valgrind program and development headers

For non-essential enhancements to the test suite:

 - 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
script.  It will run nbdkit and plugins from the locally compiled
directory:

    $ ./nbdkit example1 -f -v
    ./src/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.

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