README.md

   1 ## NBD server with stable plugin ABI and permissive license
   2
   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
   5 Network.
   6
   7 The key features of nbdkit are:
   8
   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.
  18
  19 For documentation, see the [docs directory](docs/).
  20
  21 For plugins and filters, see the [plugins](plugins/) and
  22 [filters](filters/) directories.  Example plugins can be found in
  23 `plugins/example*`.
  24
  25 There are many NBD clients, but the nbdkit project has a companion
  26 client library called https://gitlab.com/nbdkit/libnbd
  27
  28 https://gitlab.com/nbdkit/nbdkit
  29
  30 ## License
  31
  32 This software is copyright (C) Red Hat Inc. and licensed under a BSD
  33 license.  See [LICENSE](LICENSE) for details.
  34
  35 ## Building from source
  36
  37 ### Requirements
  38
  39 * Linux, macOS, Windows, FreeBSD, OpenBSD or Haiku
  40 * GCC or Clang
  41 * bash
  42 * GNU make
  43
  44 Recommended for TLS (authentication and encryption) support, but it is
  45 possible to build without it:
  46
  47 * gnutls >= 3.3.0
  48
  49 For Windows support see [the Windows section below](README.md#windows).
  50
  51 For macOS support see [the macOS section below](README.md#macos).
  52
  53 ### Optional dependencies
  54
  55 To build the man pages, you will optionally need to install:
  56
  57 * Perl
  58 * Pod::Man and Pod::Simple (Perl libraries)
  59
  60 For SELinux socket labelling support:
  61
  62 * libselinux
  63
  64 For the gzip filter:
  65
  66 * zlib
  67
  68 For the xz filter:
  69
  70 * liblzma
  71
  72 For the memory plugin with allocator=zstd:
  73
  74 * zstd
  75
  76 For the curl (HTTP/FTP) plugin:
  77
  78 * libcurl
  79
  80 For the ssh plugin:
  81
  82 * libssh >= 0.8.0
  83   (this is a different library from libssh2 - that will not work)
  84
  85 For the iso plugin:
  86
  87 * xorriso or genisoimage or mkisofs
  88
  89 For the floppy plugin:
  90
  91 * iconv (on Linux this is built into glibc, on other systems
  92   it may be a separate library)
  93
  94 For the libvirt plugin:
  95
  96 * libvirt
  97
  98 For the libguestfs plugin, and to run parts of the test suite:
  99
 100 * libguestfs
 101 * guestfish (from libguestfs)
 102
 103 For the ext2 filter:
 104
 105 * ext2fs
 106 * com_err
 107
 108 For the linuxdisk plugin:
 109
 110 * mke2fs >= 1.42.10 (from e2fsprogs)
 111
 112 For the nbd plugin, to get URI and TLS support, and also to run parts
 113 of the test suite:
 114
 115 * libnbd >= 0.9.8
 116
 117 For the bittorrent plugin:
 118
 119 * [libtorrent-rasterbar](https://www.libtorrent.org)
 120
 121 For the containerized data importer (CDI) plugin:
 122
 123 * podman
 124 * jq
 125
 126 For the Perl and example4 plugins:
 127
 128 * perl interpreter
 129 * perl development libraries
 130 * perl modules ExtUtils::Embed
 131
 132 For the Python plugin:
 133
 134 * python interpreter (version 3 only)
 135 * python development libraries
 136 * python unittest to run the test suite
 137 * boto3 is required to run the S3 plugin written in Python
 138
 139 For the OCaml plugin:
 140
 141 * OCaml >= 4.03
 142
 143 For the Tcl plugin:
 144
 145 * Tcl development library and headers
 146
 147 For the Lua plugin:
 148
 149 * Lua development library and headers
 150
 151 For the Rust plugin:
 152
 153 * cargo (other dependencies will be downloaded at build time)
 154
 155 To be able to write plugins in golang:
 156
 157 * go >= 1.13
 158
 159 For bash tab completion:
 160
 161 * bash-completion >= 1.99
 162
 163 To test for memory leaks (`make check-valgrind`):
 164
 165 * valgrind program and development headers
 166
 167 For non-essential enhancements to the test suite:
 168
 169 * expect
 170 * flake8
 171 * hexdump
 172 * ip, ss (from iproute package)
 173 * jq
 174 * losetup (from util-linux package)
 175 * mke2fs (from e2fsprogs)
 176 * nbdcopy, nbdinfo, nbdsh (from libnbd)
 177 * qemu-img, qemu-io, qemu-nbd (usually shipped with qemu)
 178 * sfdisk (from util-linux)
 179 * socat
 180 * stat (from coreutils)
 181
 182 ### Building
 183
 184 ```
 185 To build from tarball:         To build from git:
 186
 187                                autoreconf -i
 188 ./configure                    ./configure
 189 make                           make
 190 make check                     make check
 191 ```
 192
 193 On FreeBSD and OpenBSD which do not have GNU make by default you must
 194 use `gmake` instead of `make`.
 195
 196 To run nbdkit from the source directory, use the top level ./nbdkit
 197 wrapper.  It will run nbdkit and plugins from the locally compiled
 198 directory:
 199
 200 ```
 201 $ ./nbdkit example1 -f -v
 202 ./server/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
 203 [etc]
 204 ```
 205
 206 Optionally run this command as root to install everything:
 207
 208 ```
 209 make install
 210 ```
 211
 212 ### Python
 213
 214 Since nbdkit >= 1.16, only Python >= 3.6 is supported.
 215
 216 By default nbdkit uses the Python version of the Python interpreter
 217 called “python” on the current $PATH.  If you have parallel versions
 218 of Python installed then you can choose a different version by setting
 219 the PYTHON variable when configuring.  For example:
 220
 221 ```
 222 ./configure PYTHON=/usr/bin/python3.8
 223 ```
 224
 225 ### OCaml
 226
 227 Most recent (less than, say, 8 years old) versions of the OCaml
 228 compiler should work.  By default the configure script should detect
 229 the bytecode and native code compilers and enable either one or both.
 230
 231 To enable OCaml warnings and turn them into hard errors (developers only):
 232
 233 ```
 234 ./configure OCAMLOPTFLAGS="-warn-error +A-3"
 235 ```
 236
 237 ### Running the tests
 238
 239 To run the test suite:
 240
 241 ```
 242 make check
 243 ```
 244
 245 If there is a failure, look at the corresponding `tests/*.log` file
 246 for debug information.
 247
 248 A few tests require root privileges, and are skipped by default.  To
 249 run them you must do:
 250
 251 ```
 252 make check-root
 253 ```
 254
 255 If you have the proprietary VDDK library, you can test
 256 [nbdkit-vddk-plugin](plugins/vddk/) against the library like this:
 257
 258 ```
 259 make check-vddk vddkdir=vmware-vix-disklib-distrib
 260 ```
 261
 262 ### Running the benchmarks
 263
 264 To run benchmarks:
 265
 266 ```
 267 make bench
 268 ```
 269
 270 ## Download tarballs
 271
 272 Tarballs are available from:
 273 http://libguestfs.org/download/nbdkit
 274
 275 ## Downstream packagers
 276
 277 If you are packaging nbdkit, use:
 278
 279 ```
 280 ./configure --with-extra='...'
 281 ```
 282
 283 providing extra information about the distribution, and/or
 284 distro-specific versions.  It helps us with troubleshooting bug
 285 reports.  (Also, talk to us!)
 286
 287 ## Developers
 288
 289 Install the valgrind program and development headers.
 290
 291 Use:
 292
 293 ```
 294 ./configure --enable-gcc-warnings --enable-valgrind
 295 ```
 296
 297 When testing use:
 298
 299 ```
 300 make check
 301 make check-valgrind
 302 ```
 303
 304 For development ideas, see the [TODO](TODO) file.
 305
 306 The upstream git repository is:
 307 https://gitlab.com/nbdkit/nbdkit
 308
 309 Please send patches to the libguestfs mailing list:
 310 https://www.redhat.com/mailman/listinfo/libguestfs
 311
 312 For further information, see:
 313 https://libguestfs.org/
 314 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
 315
 316 ## Address sanitizer (ASAN)
 317
 318 You can compile nbdkit with clang and ASAN with:
 319
 320 ```
 321 ./configure CC=clang CXX=clang++ \
 322             CFLAGS="-O0 -g -fsanitize=address -fno-omit-frame-pointer" \
 323             --disable-linker-script \
 324             --disable-golang
 325 make clean
 326 make
 327 ASAN_OPTIONS="allocator_may_return_null=1 detect_leaks=false" make check
 328 ```
 329
 330 ## Test coverage
 331
 332 ```
 333 ./configure CFLAGS="--coverage -g" LDFLAGS="--coverage -g"
 334 make clean
 335 make
 336 make check
 337
 338 lcov -c -d . -o gcov.info
 339 genhtml -o coverage gcov.info
 340 ```
 341
 342 Open your browser and examine the `coverage/` directory.  At the time
 343 of writing (2020-04) test coverage of the server is reasonable, but
 344 things are much worse for certain plugins and filters.
 345
 346 ## macOS
 347
 348 nbdkit works on macOS and is mostly feature complete.  Some tests may
 349 fail or be skipped.
 350
 351 We have tested macOS 12 (Monterey) using MacPorts.  Other versions of
 352 macOS and Homebrew may work too.
 353
 354 We installed the following MacPorts packages:
 355
 356 * autoconf
 357 * autoconf-archive
 358 * automake
 359 * bash
 360 * coreutils
 361 * gcc
 362 * gmake
 363 * gsed
 364 * jq
 365 * libtool
 366 * m4
 367 * ocaml
 368 * pkg-config
 369 * qemu
 370 * ranlib
 371
 372 We configured nbdkit using:
 373
 374 ```
 375 ./configure --enable-gcc-warnings --disable-perl \
 376             CFLAGS="-g -O2 -I/opt/local/include" \
 377             LDFLAGS="-L/opt/local/lib"
 378 ```
 379
 380 ## Windows
 381
 382 Experimentally, the server can be compiled on Windows or
 383 cross-compiled from Linux using mingw-w64.  Only a small subset of
 384 features are available.  To find out what is missing read the TODO
 385 "Windows port".
 386
 387 Note that GCC or Clang is required even if you are compiling on
 388 Windows because of some C language extensions we use.  MSVC will not
 389 work.
 390
 391 ### Cross-compiling from Linux to Windows
 392
 393 For the rest of this section we talk about cross-compiling for Windows
 394 using Linux and mingw-w64.  At a minimum you will need:
 395
 396 * mingw-w64 GCC
 397 * mingw-w64 dlfcn
 398 * mingw-w64 winpthreads
 399 * mingw-w64 gnutls  (optional, but highly recommended)
 400 * wine              (if you want to run it on Linux)
 401
 402 You may want to patch Wine with this patch which adds support for
 403 AF_UNIX sockets.  It is needed to get most of the test suite to work,
 404 but if you don't care about the -U option then it is not needed.
 405 https://www.winehq.org/pipermail/wine-devel/2021-May/187049.html
 406
 407 Other mingw-w64 libraries may be installed which will add
 408 functionality (see full list of requirements above), but you may end
 409 up hitting areas we have not compiled or tested before.
 410
 411 To cross compile do:
 412
 413 ```
 414 mingw64-configure --disable-ocaml --disable-perl --disable-vddk
 415 mingw64-make
 416 ```
 417
 418 You can test if the server is working by doing:
 419
 420 ```
 421 ./nbdkit.exe --dump-config
 422 ```
 423
 424 (This usually runs wine automatically.  If not, you may need to prefix
 425 the command "wine nbdkit.exe ...")
 426
 427 To see which plugins and filters were compiled:
 428
 429 ```
 430 find plugins filters -name '*.dll'
 431 ```
 432
 433 You can run them under Wine without installing using eg:
 434
 435 ```
 436 ./nbdkit.exe -f -v memory 1G
 437 ```
 438
 439 You can run the test suite in the usual way:
 440
 441 ```
 442 mingw64-make check
 443 ```
 444
 445 ### Running the cross-compiled binary on Windows
 446
 447 To test the binary on a real Windows system you will need to copy
 448 server/.libs/nbdkit.exe, any plugins and filters you need
 449 (`plugins/*/.libs/*.dll` and `filters/*/.libs/*.dll`), and many mingw
 450 DLLs (`libdl.dll`, `libgnutls.dll`, `libwinpthread.dll`, etc.).
 451
 452 Notes:
 453
 454 1. libtool creates files called nbdkit.exe in the top level directory
 455 and in [server](server/).  These are the stripped binaries.  The
 456 "real" binaries are located in hidden `.libs/` subdirectories.
 457
 458 2. The top level `.libs/nbdkit.exe` is the wrapper used to run nbdkit
 459 from the build directory, not the server binary.  You need
 460 `server/.libs/nbdkit.exe` instead.
 461
 462 3. To find the list of mingw DLLs I ran nbdkit.exe iteratively until
 463 Windows stopped complaining about missing libraries.  You could also
 464 use a tool like Dependency Walker.
 465
 466 If you copy everything into a single directory on the Windows server
 467 then you should be able to run nbdkit normally, eg:
 468
 469 ```
 470 nbdkit.exe -f -v nbdkit-memory-plugin.dll 1G
 471 ```
 472
 473 You will probably need to open port 10809 on the Windows Firewall.