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
Permalink
Failed to load latest commit information.
bash bash: Don't define bashcompdir twice. Jul 10, 2018
common common: Make macro more robust Sep 19, 2018
docs docs: Fix language links so they link to section 3 of the manual. Sep 13, 2018
filters partition filter: Handle > 128 GPT partitions. Oct 16, 2018
html docs: Add podwrapper from libguestfs. Jul 15, 2018
include plugins: Implement magic config key. Sep 10, 2018
m4 ocaml: New plugin lets you write plugins as natively compiled OCaml p… Dec 6, 2014
plugins partitioning: Miscellaneous improvements to the wording of the man page. Oct 16, 2018
src core: Unload plugins and filters in --help, --version and --dump-plugin. Sep 10, 2018
tests partitioning: Allow unlimited number of GPT partitions. Oct 16, 2018
.dir-locals.el maint: Add emacs hint file Nov 14, 2017
.gitignore tests: Move common code for testing every plugin to tests/functions.sh. Sep 13, 2018
LICENSE Update copyright dates. Aug 18, 2018
Makefile.am memory: Factor out sparse array support into a separate library. Aug 27, 2018
OTHER_PLUGINS Add top level document listing out-of-tree plugins. Nov 30, 2017
README Add shell script plugin, for writing plugins in shell or scripting la… Sep 8, 2018
TODO todo: Remove Glance and Cinder suggestions. Sep 1, 2018
common-rules.mk build: Move list of plugins and filters to the configure script. Sep 13, 2018
configure.ac Version 1.7.5. Oct 16, 2018
nbdkit.in freebsd: In scripts use 'env bash' instead of '/bin/bash'. Aug 12, 2018
podwrapper.pl.in docs: Use "NBDKIT" as the center title on man pages. Sep 15, 2018
valgrind-suppressions valgrind: Yet more suppressions. Aug 13, 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, 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 or FreeBSD, 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 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 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)

 - 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.

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