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<-D> nbdkit.FLAG=N
 181
 182 =item B<--debug> nbdkit.FLAG=N
 183
 184 Set the nbdkit server Debug Flag called C<FLAG> to the integer value
 185 C<N>.  See L</SERVER DEBUG FLAGS> below.
 186
 187 =item B<--dump-config>
 188
 189 Dump out the compile-time configuration values and exit.
 190 See L<nbdkit-probing(1)>.
 191
 192 =item B<--dump-plugin>
 193
 194 Dump out information about the plugin and exit.
 195 See L<nbdkit-probing(1)>.
 196
 197 =item B<--exit-with-parent>
 198
 199 If the parent process exits, we exit.  This can be used to avoid
 200 complicated cleanup or orphaned nbdkit processes.  There are some
 201 important caveats with this, see L<nbdkit-captive(1)/EXIT WITH PARENT>.
 202
 203 An alternative to this is L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
 204
 205 This option implies I<--foreground>.
 206
 207 =item B<-e> EXPORTNAME
 208
 209 =item B<--export> EXPORTNAME
 210
 211 =item B<--export-name> EXPORTNAME
 212
 213 =item B<--exportname> EXPORTNAME
 214
 215 Set the exportname.
 216
 217 If not set, exportname C<""> (empty string) is used.  Exportnames are
 218 not allowed with the oldstyle protocol.
 219
 220 =item B<-f>
 221
 222 =item B<--foreground>
 223
 224 =item B<--no-fork>
 225
 226 I<Don't> fork into the background.
 227
 228 =item B<--filter> FILTER
 229
 230 Add a filter before the plugin.  This option may be given one or more
 231 times to stack filters in front of the plugin.  They are processed in
 232 the order they appear on the command line.  See L</FILTERS> and
 233 L<nbdkit-filter(3)>.
 234
 235 =item B<-g> GROUP
 236
 237 =item B<--group> GROUP
 238
 239 Change group to C<GROUP> after starting up.  A group name or numeric
 240 group ID can be used.
 241
 242 The server needs sufficient permissions to be able to do this.
 243 Normally this would mean starting the server up as root.
 244
 245 See also I<-u>.
 246
 247 =item B<-i> IPADDR
 248
 249 =item B<--ip-addr> IPADDR
 250
 251 =item B<--ipaddr> IPADDR
 252
 253 Listen on the specified interface.  The default is to listen on all
 254 interfaces.  See also I<-p>.
 255
 256 =item B<--log=stderr>
 257
 258 =item B<--log=syslog>
 259
 260 =item B<--log=null>
 261
 262 Send error messages to standard error (I<--log=stderr>), or to the
 263 system log (I<--log=syslog>), or discard them completely
 264 (I<--log=null>, not recommended for normal use).
 265
 266 The default is to send error messages to stderr, unless nbdkit
 267 forks into the background in which case they are sent to syslog.
 268
 269 For more details see L<nbdkit-service(1)/LOGGING>.
 270
 271 =item B<-n>
 272
 273 =item B<--new-style>
 274
 275 =item B<--newstyle>
 276
 277 Use the newstyle NBD protocol.  This is the default in nbdkit
 278 E<ge> 1.3.  In earlier versions the default was oldstyle.
 279 See L<nbdkit-protocol(1)>.
 280
 281 =item B<--no-sr>
 282
 283 Do not advertise structured replies.  A client must request structured
 284 replies to take advantage of block status and potential sparse reads;
 285 however, as structured reads are not a mandatory part of the newstyle
 286 NBD protocol, this option can be used to debug client fallbacks for
 287 dealing with older servers.  See L<nbdkit-protocol(1)>.
 288
 289 =item B<-o>
 290
 291 =item B<--old-style>
 292
 293 =item B<--oldstyle>
 294
 295 Use the oldstyle NBD protocol.  This I<was> the default in nbdkit
 296 E<le> 1.2, but now the default is newstyle.  Note this is incompatible
 297 with newer features such as export names and TLS.
 298 See L<nbdkit-protocol(1)>.
 299
 300 =item B<-P> PIDFILE
 301
 302 =item B<--pid-file> PIDFILE
 303
 304 =item B<--pidfile> PIDFILE
 305
 306 Write C<PIDFILE> (containing the process ID of the server) after
 307 nbdkit becomes ready to accept connections.
 308
 309 If the file already exists, it is overwritten.  nbdkit I<does not>
 310 delete the file when it exits.
 311
 312 =item B<-p> PORT
 313
 314 =item B<--port> PORT
 315
 316 Change the TCP/IP port number on which nbdkit serves requests.
 317 The default is C<10809>.  See also I<-i>.
 318
 319 =item B<-r>
 320
 321 =item B<--read-only>
 322
 323 =item B<--readonly>
 324
 325 The export will be read-only.  If a client writes, then it will get an
 326 error.
 327
 328 Note that some plugins inherently don't support writes.  With those
 329 plugins the I<-r> option is added implicitly.
 330
 331 L<nbdkit-cow-filter(1)> can be placed over read-only plugins to
 332 provide copy-on-write (or "snapshot") functionality.  If you are using
 333 qemu as a client then it also supports snapshots.
 334
 335 =item B<--run> CMD
 336
 337 Run nbdkit as a captive subprocess of C<CMD>.  When C<CMD> exits,
 338 nbdkit is killed.  See L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
 339
 340 This option implies I<--foreground>.
 341
 342 =item B<-s>
 343
 344 =item B<--single>
 345
 346 =item B<--stdin>
 347
 348 Don't fork.  Handle a single NBD connection on stdin/stdout.  After
 349 stdin closes, the server exits.
 350
 351 You can use this option to run nbdkit from inetd or similar
 352 superservers; or just for testing; or if you want to run nbdkit in a
 353 non-conventional way.  Note that if you want to run nbdkit from
 354 systemd, then it may be better to use
 355 L<nbdkit-service(1)/SOCKET ACTIVATION> instead of this option.
 356
 357 This option implies I<--foreground>.
 358
 359 =item B<--selinux-label> SOCKET-LABEL
 360
 361 Apply the SELinux label C<SOCKET-LABEL> to the nbdkit listening
 362 socket.
 363
 364 The common — perhaps only — use of this option is to allow libvirt
 365 guests which are using SELinux and sVirt confinement to access nbdkit
 366 Unix domain sockets:
 367
 368  nbdkit --selinux-label system_u:object_r:svirt_t:s0 ...
 369
 370 =item B<--swap>
 371
 372 Specifies that the NBD device will be used as swap space loop mounted
 373 on the same machine which is running nbdkit.  To avoid deadlocks this
 374 locks the whole nbdkit process into memory using L<mlockall(2)>.  This
 375 may require additional permissions, such as starting the server as
 376 root or raising the C<RLIMIT_MEMLOCK> (L<ulimit(1)> I<-l>) limit on
 377 the process.
 378
 379 =item B<-t> THREADS
 380
 381 =item B<--threads> THREADS
 382
 383 Set the number of threads to be used per connection, which in turn
 384 controls the number of outstanding requests that can be processed at
 385 once.  Only matters for plugins with thread_model=parallel (where it
 386 defaults to 16).  To force serialized behavior (useful if the client
 387 is not prepared for out-of-order responses), set this to 1.
 388
 389 =item B<--tls=off>
 390
 391 =item B<--tls=on>
 392
 393 =item B<--tls=require>
 394
 395 Disable, enable or require TLS (authentication and encryption
 396 support).  See L<nbdkit-tls(1)>.
 397
 398 =item B<--tls-certificates> /path/to/certificates
 399
 400 Set the path to the TLS certificates directory.  If not specified,
 401 some built-in paths are checked.  See L<nbdkit-tls(1)> for more
 402 details.
 403
 404 =item B<--tls-psk> /path/to/pskfile
 405
 406 Set the path to the pre-shared keys (PSK) file.  If used, this
 407 overrides certificate authentication.  There is no built-in path.  See
 408 L<nbdkit-tls(1)> for more details.
 409
 410 =item B<--tls-verify-peer>
 411
 412 Enables TLS client certificate verification.  The default is I<not> to
 413 check the client's certificate.
 414
 415 =item B<-U> SOCKET
 416
 417 =item B<--unix> SOCKET
 418
 419 =item B<-U ->
 420
 421 =item B<--unix ->
 422
 423 Accept connections on the Unix domain socket C<SOCKET> (which is a
 424 path).
 425
 426 nbdkit creates this socket, but it will probably have incorrect
 427 permissions (too permissive).  If it is a problem that some
 428 unauthorized user could connect to this socket between the time that
 429 nbdkit starts up and the authorized user connects, then put the socket
 430 into a directory that has restrictive permissions.
 431
 432 nbdkit does B<not> delete the socket file when it exits.  The caller
 433 should delete the socket file after use (else if you try to start
 434 nbdkit up again you will get an C<Address already in use> error).
 435
 436 If the socket name is I<-> then nbdkit generates a randomly named
 437 private socket.  This is useful with L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
 438
 439 =item B<-u> USER
 440
 441 =item B<--user> USER
 442
 443 Change user to C<USER> after starting up.  A user name or numeric user
 444 ID can be used.
 445
 446 The server needs sufficient permissions to be able to do this.
 447 Normally this would mean starting the server up as root.
 448
 449 See also I<-g>.
 450
 451 =item B<-v>
 452
 453 =item B<--verbose>
 454
 455 Enable verbose messages.
 456
 457 It's a good idea to use I<-f> as well so the process does not fork
 458 into the background (but not required).
 459
 460 =item B<-V>
 461
 462 =item B<--version>
 463
 464 Print the version number of nbdkit and exit.
 465
 466 =item B<--vsock>
 467
 468 Use the AF_VSOCK protocol (instead of TCP/IP).  You must use this in
 469 conjunction with I<-p>/I<--port>.  See L<nbdkit-service(1)/AF_VSOCK>.
 470
 471 =back
 472
 473 =head1 PLUGIN NAME
 474
 475 You can give the full path to the plugin, like this:
 476
 477  nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]
 478
 479 but it is usually more convenient to use this equivalent syntax:
 480
 481  nbdkit file [...]
 482
 483 C<$libdir> is set at compile time.  To print it out, do:
 484
 485  nbdkit --dump-config
 486
 487 =head1 PLUGIN CONFIGURATION
 488
 489 After specifying the plugin name you can (optionally, it depends
 490 on the plugin) give plugin configuration on the command line in
 491 the form of C<key=value>.  For example:
 492
 493  nbdkit file file=disk.img
 494
 495 To list all the options supported by a plugin, do:
 496
 497  nbdkit --help file
 498
 499 To dump information about a plugin, do:
 500
 501  nbdkit file --dump-plugin
 502
 503 =head2 Magic parameters
 504
 505 Some plugins declare a special "magic config key".  This is a key
 506 which is assumed if no C<key=> part is present.  For example:
 507
 508  nbdkit file disk.img
 509
 510 is assumed to be C<file=disk.img> because the file plugin declares
 511 C<file> as its magic config key.  There can be ambiguity in the
 512 parsing of magic config keys if the value might look like a
 513 C<key=value>.  If there could be ambiguity then modify the value,
 514 eg. by prefixing it with C<./>
 515
 516 There is also a special exception for plugins which do not declare a
 517 magic config key, but where the first plugin argument does not contain
 518 an C<'='> character: it is assumed to be C<script=value>.  This is
 519 used by scripting language plugins:
 520
 521  nbdkit perl foo.pl [args...]
 522
 523 has the same meaning as:
 524
 525  nbdkit perl script=foo.pl [args...]
 526
 527 =head2 Shebang scripts
 528
 529 You can use C<#!> to run nbdkit plugins written in most scripting
 530 languages.  The file should be executable.  For example:
 531
 532  #!/usr/sbin/nbdkit perl
 533  sub open {
 534    # etc
 535  }
 536
 537 (see L<nbdkit-perl-plugin(3)> for a full example).
 538
 539 =head1 SERVER DEBUG FLAGS
 540
 541 As well as enabling or disabling debugging in the server using
 542 I<--verbose> you can control extra debugging in the server using the
 543 C<-D nbdkit.*> flags listed in this section.  Note these flags are an
 544 internal implementation detail of the server and may be changed or
 545 removed at any time in the future.
 546
 547 =over 4
 548
 549 =item B<-D nbdkit.backend.controlpath=0>
 550
 551 =item B<-D nbdkit.backend.controlpath=1>
 552
 553 =item B<-D nbdkit.backend.datapath=0>
 554
 555 =item B<-D nbdkit.backend.datapath=1>
 556
 557 These flags control the verbosity of nbdkit backend debugging messages
 558 (the ones which show every request processed by the server).  The
 559 default for both settings is C<1> (normal debugging) but you can set
 560 them to C<0> to suppress these messages.
 561
 562 C<-D nbdkit.backend.datapath=0> is the more useful setting which lets you
 563 suppress messages about pread, pwrite, zero, trim, etc. commands.
 564 When transferring large amounts of data these messages are numerous
 565 and not usually very interesting.
 566
 567 C<-D nbdkit.backend.controlpath=0> suppresses the non-datapath
 568 commands (config, open, close, can_write, etc.)
 569
 570 =back
 571
 572 =head1 SIGNALS
 573
 574 nbdkit responds to the following signals:
 575
 576 =over 4
 577
 578 =item C<SIGINT>
 579
 580 =item C<SIGQUIT>
 581
 582 =item C<SIGTERM>
 583
 584 The server exits cleanly.
 585
 586 =item C<SIGPIPE>
 587
 588 This signal is ignored.
 589
 590 =back
 591
 592 =head1 ENVIRONMENT VARIABLES
 593
 594 =over 4
 595
 596 =item C<LISTEN_FDS>
 597
 598 =item C<LISTEN_PID>
 599
 600 If present in the environment when nbdkit starts up, these trigger
 601 L<nbdkit-service(1)/SOCKET ACTIVATION>.
 602
 603 =back
 604
 605 =head1 SEE ALSO
 606
 607 =head2 Other topics
 608
 609 L<nbdkit-captive(1)> — Run nbdkit under another process and have it
 610 reliably cleaned up.
 611
 612 L<nbdkit-loop(1)> — Use nbdkit with the Linux kernel client to create
 613 loop devices and loop mounts.
 614
 615 L<nbdkit-probing(1)> — How to probe for nbdkit configuration and plugins.
 616
 617 L<nbdkit-protocol(1)> — Which parts of the NBD protocol nbdkit supports.
 618
 619 L<nbdkit-security(1)> — Lists past security issues in nbdkit.
 620
 621 L<nbdkit-service(1)> — Running nbdkit as a service, and systemd socket
 622 activation.
 623
 624 L<nbdkit-tls(1)> — Authentication and encryption of NBD connections
 625 (sometimes incorrectly called "SSL").
 626
 627 =head2 Plugins
 628
 629 __PLUGIN_LINKS__.
 630
 631 =head2 Filters
 632
 633 __FILTER_LINKS__.
 634
 635 =head2 For developers
 636
 637 L<nbdkit-plugin(3)>,
 638 L<nbdkit-filter(3)>.
 639
 640 =head2 Writing plugins in other programming languages
 641
 642 __LANG_PLUGIN_LINKS__.
 643
 644 =head2 Release notes for previous releases of nbdkit
 645
 646 L<nbdkit-release-notes-1.4(1)>,
 647 L<nbdkit-release-notes-1.6(1)>,
 648 L<nbdkit-release-notes-1.8(1)>,
 649 L<nbdkit-release-notes-1.10(1)>,
 650 L<nbdkit-release-notes-1.12(1)>,
 651 L<nbdkit-release-notes-1.14(1)>,
 652 L<nbdkit-release-notes-1.16(1)>.
 653
 654 =head2 NBD clients
 655
 656 L<guestfish(1)>,
 657 L<libnbd(3)>,
 658 L<nbd-client(1)>,
 659 L<nbdfuse(1)>,
 660 L<nbdsh(1)>,
 661 L<qemu(1)>.
 662
 663 =head2 nbdkit links
 664
 665 L<http://github.com/libguestfs/nbdkit> — Source code.
 666
 667 =head2 Other NBD servers
 668
 669 L<qemu-nbd(1)>,
 670 L<nbd-server(1)>,
 671 L<https://bitbucket.org/hirofuchi/xnbd>.
 672
 673 =head2 Documentation for the NBD protocol
 674
 675 L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>,
 676 L<https://nbd.sourceforge.io/>.
 677
 678 =head2 Similar protocols
 679
 680 L<https://en.wikipedia.org/wiki/iSCSI>,
 681 L<https://en.wikipedia.org/wiki/ATA_over_Ethernet>,
 682 L<https://en.wikipedia.org/wiki/Fibre_Channel_over_Ethernet>.
 683
 684 =head2 Other manual pages of interest
 685
 686 L<gnutls_priority_init(3)>,
 687 L<qemu-img(1)>,
 688 L<psktool(1)>,
 689 L<systemd.socket(5)>.
 690
 691 =head1 AUTHORS
 692
 693 Eric Blake
 694
 695 Richard W.M. Jones
 696
 697 Yann E. MORIN
 698
 699 Nir Soffer
 700
 701 Pino Toscano
 702
 703 =head1 COPYRIGHT
 704
 705 Copyright (C) 2013-2019 Red Hat Inc.