docs/nbdkit.pod

   1 =head1 NAME
   2
   3 nbdkit - toolkit for creating NBD servers
   4
   5 =head1 SYNOPSIS
   6
   7 __SYNOPSIS__
   8
   9 =head1 DESCRIPTION
  10
  11 Network Block Device (NBD) is a network protocol for accessing block
  12 devices over the network.  Block devices are hard disks and things
  13 that behave like hard disks such as disk images and virtual machines.
  14
  15 nbdkit is both a toolkit for creating NBD servers from
  16 “unconventional” sources, and the name of an NBD server.  nbdkit ships
  17 with many plugins for performing common tasks like serving local
  18 files.
  19
  20 =head2 Plugins and filters
  21
  22 nbdkit is different from other NBD servers because you can easily
  23 create new Network Block Device sources by writing a few glue
  24 functions, possibly in C, or perhaps in a high level language like
  25 Perl or Python.  The liberal licensing of nbdkit is meant to allow you
  26 to link nbdkit with proprietary libraries or to include nbdkit in
  27 proprietary code.
  28
  29 If you want to write your own nbdkit plugin you should read
  30 L<nbdkit-plugin(3)>.
  31
  32 nbdkit also has a concept of filters which can be layered on top of
  33 plugins.  Several filters are provided with nbdkit and if you want to
  34 write your own you should read L<nbdkit-filter(3)>.
  35
  36 =head1 EXAMPLES
  37
  38 =head2 Basic file serving
  39
  40 =over 4
  41
  42 =item *
  43
  44 Serve file F<disk.img> on port 10809 using L<nbdkit-file-plugin(1)>,
  45 and connect to it using L<guestfish(1)>:
  46
  47  nbdkit file disk.img
  48  guestfish --rw --format=raw -a nbd://localhost
  49
  50 =item *
  51
  52 Serve file F<disk.img> on port 10809, requiring clients to use
  53 encrypted (TLS) connections:
  54
  55  nbdkit --tls=require file disk.img
  56
  57 =back
  58
  59 =head2 Other nbdkit plugins
  60
  61 =over 4
  62
  63 =item *
  64
  65 Create a 1MB disk with one empty partition entirely on the command
  66 line using L<nbdkit-data-plugin(1)>:
  67
  68  nbdkit data size=1M \
  69              data="@0x1b8 0xf8 0x21 0xdc 0xeb 0 0 0 0
  70                    2 0 0x83 0x20 0x20 0 1 0  0 0 0xff 0x7
  71                    @0x1fe 0x55 0xaa"
  72
  73 =item *
  74
  75 Forward an NBD connection to a remote server over HTTPS or SSH using
  76 L<nbdkit-curl-plugin(1)> or L<nbdkit-ssh-plugin(1)>:
  77
  78  nbdkit -r curl https://example.com/disk.img
  79
  80  nbdkit ssh host=example.com /var/tmp/disk.img
  81
  82 =item *
  83
  84 Create a RAM disk using L<nbdkit-memory-plugin(1)>:
  85
  86  nbdkit memory 64M
  87
  88 =item *
  89
  90 Create a floppy disk image containing files from a local directory
  91 using L<nbdkit-floppy-plugin(1)>:
  92
  93  nbdkit floppy dir/
  94
  95 =back
  96
  97 =head2 Combining plugins and filters
  98
  99 =over 4
 100
 101 =item *
 102
 103 Serve only the first partition from compressed disk image
 104 F<disk.img.xz>, combining L<nbdkit-partition-filter(1)>,
 105 L<nbdkit-xz-filter(1)> and L<nbdkit-file-plugin(1)>.
 106
 107  nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
 108
 109 To understand this command line:
 110
 111                              plugin name and plugin parameter
 112                                                │
 113                                        ┌───────┴──────┐
 114                                        │              │
 115  nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
 116                  │              │                          │
 117                  └──────────────┴────┬─────────────────────┘
 118                                      │
 119                         filters and filter parameter
 120
 121 =item *
 122
 123 Create a scratch, empty nbdkit device and inject errors and delays,
 124 for testing clients, using L<nbdkit-memory-plugin(1)>,
 125 L<nbdkit-error-filter(1)> and L<nbdkit-delay-filter(1)>:
 126
 127  nbdkit --filter=error --filter=delay memory 100M \
 128         error-rate=10% rdelay=1 wdelay=1
 129
 130 =back
 131
 132 =head2 Writing plugins in scripting languages
 133
 134 =over 4
 135
 136 =item *
 137
 138 Write a simple, custom plugin entirely on the command line in shell
 139 script using L<nbdkit-sh-plugin(3)>:
 140
 141  nbdkit sh - <<'EOF'
 142    case "$1" in
 143      get_size) echo 1M ;;
 144      pread) dd if=/dev/zero count=$3 iflag=count_bytes ;;
 145      *) exit 2 ;;
 146    esac
 147  EOF
 148
 149 =back
 150
 151 =head2 Display information
 152
 153 Display information about nbdkit or a specific plugin:
 154
 155  nbdkit --help
 156  nbdkit --version
 157  nbdkit --dump-config
 158  nbdkit example1 --help
 159  nbdkit example1 --dump-plugin
 160
 161 =head1 GLOBAL OPTIONS
 162
 163 =over 4
 164
 165 =item B<--help>
 166
 167 Display brief command line usage information and exit.
 168
 169 =item B<-D> PLUGIN.FLAG=N
 170
 171 =item B<-D> FILTER.FLAG=N
 172
 173 =item B<--debug> PLUGIN.FLAG=N
 174
 175 =item B<--debug> FILTER.FLAG=N
 176
 177 Set the plugin or filter Debug Flag called C<FLAG> to the integer
 178 value C<N>.  See L<nbdkit-plugin(3)/Debug Flags>.
 179
 180 =item B<--dump-config>
 181
 182 Dump out the compile-time configuration values and exit.
 183 See L<nbdkit-probing(1)>.
 184
 185 =item B<--dump-plugin>
 186
 187 Dump out information about the plugin and exit.
 188 See L<nbdkit-probing(1)>.
 189
 190 =item B<--exit-with-parent>
 191
 192 If the parent process exits, we exit.  This can be used to avoid
 193 complicated cleanup or orphaned nbdkit processes.  There are some
 194 important caveats with this, see L<nbdkit-captive(1)/EXIT WITH PARENT>.
 195
 196 An alternative to this is L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
 197
 198 This option implies I<--foreground>.
 199
 200 =item B<-e> EXPORTNAME
 201
 202 =item B<--export> EXPORTNAME
 203
 204 =item B<--export-name> EXPORTNAME
 205
 206 =item B<--exportname> EXPORTNAME
 207
 208 Set the exportname.
 209
 210 If not set, exportname C<""> (empty string) is used.  Exportnames are
 211 not allowed with the oldstyle protocol.
 212
 213 =item B<-f>
 214
 215 =item B<--foreground>
 216
 217 =item B<--no-fork>
 218
 219 I<Don't> fork into the background.
 220
 221 =item B<--filter> FILTER
 222
 223 Add a filter before the plugin.  This option may be given one or more
 224 times to stack filters in front of the plugin.  They are processed in
 225 the order they appear on the command line.  See L</FILTERS> and
 226 L<nbdkit-filter(3)>.
 227
 228 =item B<-g> GROUP
 229
 230 =item B<--group> GROUP
 231
 232 Change group to C<GROUP> after starting up.  A group name or numeric
 233 group ID can be used.
 234
 235 The server needs sufficient permissions to be able to do this.
 236 Normally this would mean starting the server up as root.
 237
 238 See also I<-u>.
 239
 240 =item B<-i> IPADDR
 241
 242 =item B<--ip-addr> IPADDR
 243
 244 =item B<--ipaddr> IPADDR
 245
 246 Listen on the specified interface.  The default is to listen on all
 247 interfaces.  See also I<-p>.
 248
 249 =item B<--log=stderr>
 250
 251 =item B<--log=syslog>
 252
 253 =item B<--log=null>
 254
 255 Send error messages to standard error (I<--log=stderr>), or to the
 256 system log (I<--log=syslog>), or discard them completely
 257 (I<--log=null>, not recommended for normal use).
 258
 259 The default is to send error messages to stderr, unless nbdkit
 260 forks into the background in which case they are sent to syslog.
 261
 262 For more details see L<nbdkit-service(1)/LOGGING>.
 263
 264 =item B<-n>
 265
 266 =item B<--new-style>
 267
 268 =item B<--newstyle>
 269
 270 Use the newstyle NBD protocol.  This is the default in nbdkit
 271 E<ge> 1.3.  In earlier versions the default was oldstyle.
 272 See L<nbdkit-protocol(1)>.
 273
 274 =item B<--no-sr>
 275
 276 Do not advertise structured replies.  A client must request structured
 277 replies to take advantage of block status and potential sparse reads;
 278 however, as structured reads are not a mandatory part of the newstyle
 279 NBD protocol, this option can be used to debug client fallbacks for
 280 dealing with older servers.  See L<nbdkit-protocol(1)>.
 281
 282 =item B<-o>
 283
 284 =item B<--old-style>
 285
 286 =item B<--oldstyle>
 287
 288 Use the oldstyle NBD protocol.  This I<was> the default in nbdkit
 289 E<le> 1.2, but now the default is newstyle.  Note this is incompatible
 290 with newer features such as export names and TLS.
 291 See L<nbdkit-protocol(1)>.
 292
 293 =item B<-P> PIDFILE
 294
 295 =item B<--pid-file> PIDFILE
 296
 297 =item B<--pidfile> PIDFILE
 298
 299 Write C<PIDFILE> (containing the process ID of the server) after
 300 nbdkit becomes ready to accept connections.
 301
 302 If the file already exists, it is overwritten.  nbdkit I<does not>
 303 delete the file when it exits.
 304
 305 =item B<-p> PORT
 306
 307 =item B<--port> PORT
 308
 309 Change the TCP/IP port number on which nbdkit serves requests.
 310 The default is C<10809>.  See also I<-i>.
 311
 312 =item B<-r>
 313
 314 =item B<--read-only>
 315
 316 =item B<--readonly>
 317
 318 The export will be read-only.  If a client writes, then it will get an
 319 error.
 320
 321 Note that some plugins inherently don't support writes.  With those
 322 plugins the I<-r> option is added implicitly.
 323
 324 L<nbdkit-cow-filter(1)> can be placed over read-only plugins to
 325 provide copy-on-write (or "snapshot") functionality.  If you are using
 326 qemu as a client then it also supports snapshots.
 327
 328 =item B<--run> CMD
 329
 330 Run nbdkit as a captive subprocess of C<CMD>.  When C<CMD> exits,
 331 nbdkit is killed.  See L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
 332
 333 This option implies I<--foreground>.
 334
 335 =item B<-s>
 336
 337 =item B<--single>
 338
 339 =item B<--stdin>
 340
 341 Don't fork.  Handle a single NBD connection on stdin/stdout.  After
 342 stdin closes, the server exits.
 343
 344 You can use this option to run nbdkit from inetd or similar
 345 superservers; or just for testing; or if you want to run nbdkit in a
 346 non-conventional way.  Note that if you want to run nbdkit from
 347 systemd, then it may be better to use
 348 L<nbdkit-service(1)/SOCKET ACTIVATION> instead of this option.
 349
 350 This option implies I<--foreground>.
 351
 352 =item B<--selinux-label> SOCKET-LABEL
 353
 354 Apply the SELinux label C<SOCKET-LABEL> to the nbdkit listening
 355 socket.
 356
 357 The common — perhaps only — use of this option is to allow libvirt
 358 guests which are using SELinux and sVirt confinement to access nbdkit
 359 Unix domain sockets:
 360
 361  nbdkit --selinux-label system_u:object_r:svirt_t:s0 ...
 362
 363 =item B<-t> THREADS
 364
 365 =item B<--threads> THREADS
 366
 367 Set the number of threads to be used per connection, which in turn
 368 controls the number of outstanding requests that can be processed at
 369 once.  Only matters for plugins with thread_model=parallel (where it
 370 defaults to 16).  To force serialized behavior (useful if the client
 371 is not prepared for out-of-order responses), set this to 1.
 372
 373 =item B<--tls=off>
 374
 375 =item B<--tls=on>
 376
 377 =item B<--tls=require>
 378
 379 Disable, enable or require TLS (authentication and encryption
 380 support).  See L<nbdkit-tls(1)>.
 381
 382 =item B<--tls-certificates> /path/to/certificates
 383
 384 Set the path to the TLS certificates directory.  If not specified,
 385 some built-in paths are checked.  See L<nbdkit-tls(1)> for more
 386 details.
 387
 388 =item B<--tls-psk> /path/to/pskfile
 389
 390 Set the path to the pre-shared keys (PSK) file.  If used, this
 391 overrides certificate authentication.  There is no built-in path.  See
 392 L<nbdkit-tls(1)> for more details.
 393
 394 =item B<--tls-verify-peer>
 395
 396 Enables TLS client certificate verification.  The default is I<not> to
 397 check the client's certificate.
 398
 399 =item B<-U> SOCKET
 400
 401 =item B<--unix> SOCKET
 402
 403 =item B<-U ->
 404
 405 =item B<--unix ->
 406
 407 Accept connections on the Unix domain socket C<SOCKET> (which is a
 408 path).
 409
 410 nbdkit creates this socket, but it will probably have incorrect
 411 permissions (too permissive).  If it is a problem that some
 412 unauthorized user could connect to this socket between the time that
 413 nbdkit starts up and the authorized user connects, then put the socket
 414 into a directory that has restrictive permissions.
 415
 416 nbdkit does B<not> delete the socket file when it exits.  The caller
 417 should delete the socket file after use (else if you try to start
 418 nbdkit up again you will get an C<Address already in use> error).
 419
 420 If the socket name is I<-> then nbdkit generates a randomly named
 421 private socket.  This is useful with L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
 422
 423 =item B<-u> USER
 424
 425 =item B<--user> USER
 426
 427 Change user to C<USER> after starting up.  A user name or numeric user
 428 ID can be used.
 429
 430 The server needs sufficient permissions to be able to do this.
 431 Normally this would mean starting the server up as root.
 432
 433 See also I<-g>.
 434
 435 =item B<-v>
 436
 437 =item B<--verbose>
 438
 439 Enable verbose messages.
 440
 441 It's a good idea to use I<-f> as well so the process does not fork
 442 into the background (but not required).
 443
 444 =item B<-V>
 445
 446 =item B<--version>
 447
 448 Print the version number of nbdkit and exit.
 449
 450 =item B<--vsock>
 451
 452 Use the AF_VSOCK protocol (instead of TCP/IP).  You must use this in
 453 conjunction with I<-p>/I<--port>.  See L<nbdkit-service(1)/AF_VSOCK>.
 454
 455 =back
 456
 457 =head1 PLUGIN NAME
 458
 459 You can give the full path to the plugin, like this:
 460
 461  nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]
 462
 463 but it is usually more convenient to use this equivalent syntax:
 464
 465  nbdkit file [...]
 466
 467 C<$libdir> is set at compile time.  To print it out, do:
 468
 469  nbdkit --dump-config
 470
 471 =head1 PLUGIN CONFIGURATION
 472
 473 After specifying the plugin name you can (optionally, it depends
 474 on the plugin) give plugin configuration on the command line in
 475 the form of C<key=value>.  For example:
 476
 477  nbdkit file file=disk.img
 478
 479 To list all the options supported by a plugin, do:
 480
 481  nbdkit --help file
 482
 483 To dump information about a plugin, do:
 484
 485  nbdkit file --dump-plugin
 486
 487 =head2 Magic parameters
 488
 489 Some plugins declare a special "magic config key".  This is a key
 490 which is assumed if no C<key=> part is present.  For example:
 491
 492  nbdkit file disk.img
 493
 494 is assumed to be C<file=disk.img> because the file plugin declares
 495 C<file> as its magic config key.  There can be ambiguity in the
 496 parsing of magic config keys if the value might look like a
 497 C<key=value>.  If there could be ambiguity then modify the value,
 498 eg. by prefixing it with C<./>
 499
 500 There is also a special exception for plugins which do not declare a
 501 magic config key, but where the first plugin argument does not contain
 502 an C<'='> character: it is assumed to be C<script=value>.  This is
 503 used by scripting language plugins:
 504
 505  nbdkit perl foo.pl [args...]
 506
 507 has the same meaning as:
 508
 509  nbdkit perl script=foo.pl [args...]
 510
 511 =head2 Shebang scripts
 512
 513 You can use C<#!> to run nbdkit plugins written in most scripting
 514 languages.  The file should be executable.  For example:
 515
 516  #!/usr/sbin/nbdkit perl
 517  sub open {
 518    # etc
 519  }
 520
 521 (see L<nbdkit-perl-plugin(3)> for a full example).
 522
 523 =head1 SIGNALS
 524
 525 nbdkit responds to the following signals:
 526
 527 =over 4
 528
 529 =item C<SIGINT>
 530
 531 =item C<SIGQUIT>
 532
 533 =item C<SIGTERM>
 534
 535 The server exits cleanly.
 536
 537 =item C<SIGPIPE>
 538
 539 This signal is ignored.
 540
 541 =back
 542
 543 =head1 ENVIRONMENT VARIABLES
 544
 545 =over 4
 546
 547 =item C<LISTEN_FDS>
 548
 549 =item C<LISTEN_PID>
 550
 551 If present in the environment when nbdkit starts up, these trigger
 552 L<nbdkit-service(1)/SOCKET ACTIVATION>.
 553
 554 =back
 555
 556 =head1 SEE ALSO
 557
 558 =head2 Other topics
 559
 560 L<nbdkit-captive(1)> — Run nbdkit under another process and have it
 561 reliably cleaned up.
 562
 563 L<nbdkit-loop(1)> — Use nbdkit with the Linux kernel client to create
 564 loop devices and loop mounts.
 565
 566 L<nbdkit-probing(1)> — How to probe for nbdkit configuration and plugins.
 567
 568 L<nbdkit-protocol(1)> — Which parts of the NBD protocol nbdkit supports.
 569
 570 L<nbdkit-security(1)> — Lists past security issues in nbdkit.
 571
 572 L<nbdkit-service(1)> — Running nbdkit as a service, and systemd socket
 573 activation.
 574
 575 L<nbdkit-tls(1)> — Authentication and encryption of NBD connections
 576 (sometimes incorrectly called "SSL").
 577
 578 =head2 Plugins
 579
 580 __PLUGIN_LINKS__.
 581
 582 =head2 Filters
 583
 584 __FILTER_LINKS__.
 585
 586 =head2 For developers
 587
 588 L<nbdkit-plugin(3)>,
 589 L<nbdkit-filter(3)>.
 590
 591 =head2 Writing plugins in other programming languages
 592
 593 __LANG_PLUGIN_LINKS__.
 594
 595 =head2 Release notes for previous releases of nbdkit
 596
 597 L<nbdkit-release-notes-1.4(1)>,
 598 L<nbdkit-release-notes-1.6(1)>,
 599 L<nbdkit-release-notes-1.8(1)>,
 600 L<nbdkit-release-notes-1.10(1)>,
 601 L<nbdkit-release-notes-1.12(1)>,
 602 L<nbdkit-release-notes-1.14(1)>,
 603 L<nbdkit-release-notes-1.16(1)>.
 604
 605 =head2 NBD clients
 606
 607 L<guestfish(1)>,
 608 L<libnbd(3)>,
 609 L<nbd-client(1)>,
 610 L<nbdfuse(1)>,
 611 L<nbdsh(1)>,
 612 L<qemu(1)>.
 613
 614 =head2 nbdkit links
 615
 616 L<http://github.com/libguestfs/nbdkit> — Source code.
 617
 618 =head2 Other NBD servers
 619
 620 L<qemu-nbd(1)>,
 621 L<nbd-server(1)>,
 622 L<https://bitbucket.org/hirofuchi/xnbd>.
 623
 624 =head2 Documentation for the NBD protocol
 625
 626 L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>,
 627 L<https://nbd.sourceforge.io/>.
 628
 629 =head2 Similar protocols
 630
 631 L<https://en.wikipedia.org/wiki/iSCSI>,
 632 L<https://en.wikipedia.org/wiki/ATA_over_Ethernet>,
 633 L<https://en.wikipedia.org/wiki/Fibre_Channel_over_Ethernet>.
 634
 635 =head2 Other manual pages of interest
 636
 637 L<gnutls_priority_init(3)>,
 638 L<qemu-img(1)>,
 639 L<psktool(1)>,
 640 L<systemd.socket(5)>.
 641
 642 =head1 AUTHORS
 643
 644 Eric Blake
 645
 646 Richard W.M. Jones
 647
 648 Yann E. MORIN
 649
 650 Nir Soffer
 651
 652 Pino Toscano
 653
 654 =head1 COPYRIGHT
 655
 656 Copyright (C) 2013-2019 Red Hat Inc.