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