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 Send error messages to either standard error (I<--log=stderr>) or to
 254 the system log (I<--log=syslog>).
 255
 256 The default is to send error messages to stderr, unless nbdkit
 257 forks into the background in which case they are sent to syslog.
 258
 259 For more details see L<nbdkit-service(1)/LOGGING>.
 260
 261 =item B<-n>
 262
 263 =item B<--new-style>
 264
 265 =item B<--newstyle>
 266
 267 Use the newstyle NBD protocol.  This is the default in nbdkit
 268 E<ge> 1.3.  In earlier versions the default was oldstyle.
 269 See L<nbdkit-protocol(1)>.
 270
 271 =item B<--no-sr>
 272
 273 Do not advertise structured replies.  A client must request structured
 274 replies to take advantage of block status and potential sparse reads;
 275 however, as structured reads are not a mandatory part of the newstyle
 276 NBD protocol, this option can be used to debug client fallbacks for
 277 dealing with older servers.  See L<nbdkit-protocol(1)>.
 278
 279 =item B<-o>
 280
 281 =item B<--old-style>
 282
 283 =item B<--oldstyle>
 284
 285 Use the oldstyle NBD protocol.  This I<was> the default in nbdkit
 286 E<le> 1.2, but now the default is newstyle.  Note this is incompatible
 287 with newer features such as export names and TLS.
 288 See L<nbdkit-protocol(1)>.
 289
 290 =item B<-P> PIDFILE
 291
 292 =item B<--pid-file> PIDFILE
 293
 294 =item B<--pidfile> PIDFILE
 295
 296 Write C<PIDFILE> (containing the process ID of the server) after
 297 nbdkit becomes ready to accept connections.
 298
 299 If the file already exists, it is overwritten.  nbdkit I<does not>
 300 delete the file when it exits.
 301
 302 =item B<-p> PORT
 303
 304 =item B<--port> PORT
 305
 306 Change the TCP/IP port number on which nbdkit serves requests.
 307 The default is C<10809>.  See also I<-i>.
 308
 309 =item B<-r>
 310
 311 =item B<--read-only>
 312
 313 =item B<--readonly>
 314
 315 The export will be read-only.  If a client writes, then it will get an
 316 error.
 317
 318 Note that some plugins inherently don't support writes.  With those
 319 plugins the I<-r> option is added implicitly.
 320
 321 L<nbdkit-cow-filter(1)> can be placed over read-only plugins to
 322 provide copy-on-write (or "snapshot") functionality.  If you are using
 323 qemu as a client then it also supports snapshots.
 324
 325 =item B<--run> CMD
 326
 327 Run nbdkit as a captive subprocess of C<CMD>.  When C<CMD> exits,
 328 nbdkit is killed.  See L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
 329
 330 This option implies I<--foreground>.
 331
 332 =item B<-s>
 333
 334 =item B<--single>
 335
 336 =item B<--stdin>
 337
 338 Don't fork.  Handle a single NBD connection on stdin/stdout.  After
 339 stdin closes, the server exits.
 340
 341 You can use this option to run nbdkit from inetd or similar
 342 superservers; or just for testing; or if you want to run nbdkit in a
 343 non-conventional way.  Note that if you want to run nbdkit from
 344 systemd, then it may be better to use
 345 L<nbdkit-service(1)/SOCKET ACTIVATION> instead of this option.
 346
 347 This option implies I<--foreground>.
 348
 349 =item B<--selinux-label> SOCKET-LABEL
 350
 351 Apply the SELinux label C<SOCKET-LABEL> to the nbdkit listening
 352 socket.
 353
 354 The common — perhaps only — use of this option is to allow libvirt
 355 guests which are using SELinux and sVirt confinement to access nbdkit
 356 Unix domain sockets:
 357
 358  nbdkit --selinux-label system_u:object_r:svirt_t:s0 ...
 359
 360 =item B<-t> THREADS
 361
 362 =item B<--threads> THREADS
 363
 364 Set the number of threads to be used per connection, which in turn
 365 controls the number of outstanding requests that can be processed at
 366 once.  Only matters for plugins with thread_model=parallel (where it
 367 defaults to 16).  To force serialized behavior (useful if the client
 368 is not prepared for out-of-order responses), set this to 1.
 369
 370 =item B<--tls=off>
 371
 372 =item B<--tls=on>
 373
 374 =item B<--tls=require>
 375
 376 Disable, enable or require TLS (authentication and encryption
 377 support).  See L<nbdkit-tls(1)>.
 378
 379 =item B<--tls-certificates> /path/to/certificates
 380
 381 Set the path to the TLS certificates directory.  If not specified,
 382 some built-in paths are checked.  See L<nbdkit-tls(1)> for more
 383 details.
 384
 385 =item B<--tls-psk> /path/to/pskfile
 386
 387 Set the path to the pre-shared keys (PSK) file.  If used, this
 388 overrides certificate authentication.  There is no built-in path.  See
 389 L<nbdkit-tls(1)> for more details.
 390
 391 =item B<--tls-verify-peer>
 392
 393 Enables TLS client certificate verification.  The default is I<not> to
 394 check the client's certificate.
 395
 396 =item B<-U> SOCKET
 397
 398 =item B<--unix> SOCKET
 399
 400 =item B<-U ->
 401
 402 =item B<--unix ->
 403
 404 Accept connections on the Unix domain socket C<SOCKET> (which is a
 405 path).
 406
 407 nbdkit creates this socket, but it will probably have incorrect
 408 permissions (too permissive).  If it is a problem that some
 409 unauthorized user could connect to this socket between the time that
 410 nbdkit starts up and the authorized user connects, then put the socket
 411 into a directory that has restrictive permissions.
 412
 413 nbdkit does B<not> delete the socket file when it exits.  The caller
 414 should delete the socket file after use (else if you try to start
 415 nbdkit up again you will get an C<Address already in use> error).
 416
 417 If the socket name is I<-> then nbdkit generates a randomly named
 418 private socket.  This is useful with L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
 419
 420 =item B<-u> USER
 421
 422 =item B<--user> USER
 423
 424 Change user to C<USER> after starting up.  A user name or numeric user
 425 ID can be used.
 426
 427 The server needs sufficient permissions to be able to do this.
 428 Normally this would mean starting the server up as root.
 429
 430 See also I<-g>.
 431
 432 =item B<-v>
 433
 434 =item B<--verbose>
 435
 436 Enable verbose messages.
 437
 438 It's a good idea to use I<-f> as well so the process does not fork
 439 into the background (but not required).
 440
 441 =item B<-V>
 442
 443 =item B<--version>
 444
 445 Print the version number of nbdkit and exit.
 446
 447 =item B<--vsock>
 448
 449 Use the AF_VSOCK protocol (instead of TCP/IP).  You must use this in
 450 conjunction with I<-p>/I<--port>.  See L<nbdkit-service(1)/AF_VSOCK>.
 451
 452 =back
 453
 454 =head1 PLUGIN NAME
 455
 456 You can give the full path to the plugin, like this:
 457
 458  nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]
 459
 460 but it is usually more convenient to use this equivalent syntax:
 461
 462  nbdkit file [...]
 463
 464 C<$libdir> is set at compile time.  To print it out, do:
 465
 466  nbdkit --dump-config
 467
 468 =head1 PLUGIN CONFIGURATION
 469
 470 After specifying the plugin name you can (optionally, it depends
 471 on the plugin) give plugin configuration on the command line in
 472 the form of C<key=value>.  For example:
 473
 474  nbdkit file file=disk.img
 475
 476 To list all the options supported by a plugin, do:
 477
 478  nbdkit --help file
 479
 480 To dump information about a plugin, do:
 481
 482  nbdkit file --dump-plugin
 483
 484 =head2 Magic parameters
 485
 486 Some plugins declare a special "magic config key".  This is a key
 487 which is assumed if no C<key=> part is present.  For example:
 488
 489  nbdkit file disk.img
 490
 491 is assumed to be C<file=disk.img> because the file plugin declares
 492 C<file> as its magic config key.  There can be ambiguity in the
 493 parsing of magic config keys if the value might look like a
 494 C<key=value>.  If there could be ambiguity then modify the value,
 495 eg. by prefixing it with C<./>
 496
 497 There is also a special exception for plugins which do not declare a
 498 magic config key, but where the first plugin argument does not contain
 499 an C<'='> character: it is assumed to be C<script=value>.  This is
 500 used by scripting language plugins:
 501
 502  nbdkit perl foo.pl [args...]
 503
 504 has the same meaning as:
 505
 506  nbdkit perl script=foo.pl [args...]
 507
 508 =head2 Shebang scripts
 509
 510 You can use C<#!> to run nbdkit plugins written in most scripting
 511 languages.  The file should be executable.  For example:
 512
 513  #!/usr/sbin/nbdkit perl
 514  sub open {
 515    # etc
 516  }
 517
 518 (see L<nbdkit-perl-plugin(3)> for a full example).
 519
 520 =head1 SIGNALS
 521
 522 nbdkit responds to the following signals:
 523
 524 =over 4
 525
 526 =item C<SIGINT>
 527
 528 =item C<SIGQUIT>
 529
 530 =item C<SIGTERM>
 531
 532 The server exits cleanly.
 533
 534 =item C<SIGPIPE>
 535
 536 This signal is ignored.
 537
 538 =back
 539
 540 =head1 ENVIRONMENT VARIABLES
 541
 542 =over 4
 543
 544 =item C<LISTEN_FDS>
 545
 546 =item C<LISTEN_PID>
 547
 548 If present in the environment when nbdkit starts up, these trigger
 549 L<nbdkit-service(1)/SOCKET ACTIVATION>.
 550
 551 =back
 552
 553 =head1 SEE ALSO
 554
 555 =head2 Other topics
 556
 557 L<nbdkit-captive(1)> — Run nbdkit under another process and have it
 558 reliably cleaned up.
 559
 560 L<nbdkit-loop(1)> — Use nbdkit with the Linux kernel client to create
 561 loop devices and loop mounts.
 562
 563 L<nbdkit-probing(1)> — How to probe for nbdkit configuration and plugins.
 564
 565 L<nbdkit-protocol(1)> — Which parts of the NBD protocol nbdkit supports.
 566
 567 L<nbdkit-security(1)> — Lists past security issues in nbdkit.
 568
 569 L<nbdkit-service(1)> — Running nbdkit as a service, and systemd socket
 570 activation.
 571
 572 L<nbdkit-tls(1)> — Authentication and encryption of NBD connections
 573 (sometimes incorrectly called "SSL").
 574
 575 =head2 Plugins
 576
 577 __PLUGIN_LINKS__.
 578
 579 =head2 Filters
 580
 581 __FILTER_LINKS__.
 582
 583 =head2 For developers
 584
 585 L<nbdkit-plugin(3)>,
 586 L<nbdkit-filter(3)>.
 587
 588 =head2 Writing plugins in other programming languages
 589
 590 __LANG_PLUGIN_LINKS__.
 591
 592 =head2 NBD clients
 593
 594 L<guestfish(1)>,
 595 L<libnbd(3)>,
 596 L<nbd-client(1)>,
 597 L<nbdfuse(1)>,
 598 L<nbdsh(1)>,
 599 L<qemu(1)>.
 600
 601 =head2 nbdkit links
 602
 603 L<http://github.com/libguestfs/nbdkit> — Source code.
 604
 605 =head2 Other NBD servers
 606
 607 L<qemu-nbd(1)>,
 608 L<nbd-server(1)>,
 609 L<https://bitbucket.org/hirofuchi/xnbd>.
 610
 611 =head2 Documentation for the NBD protocol
 612
 613 L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>,
 614 L<https://nbd.sourceforge.io/>.
 615
 616 =head2 Similar protocols
 617
 618 L<https://en.wikipedia.org/wiki/iSCSI>,
 619 L<https://en.wikipedia.org/wiki/ATA_over_Ethernet>,
 620 L<https://en.wikipedia.org/wiki/Fibre_Channel_over_Ethernet>.
 621
 622 =head2 Other manual pages of interest
 623
 624 L<gnutls_priority_init(3)>,
 625 L<qemu-img(1)>,
 626 L<psktool(1)>,
 627 L<systemd.socket(5)>.
 628
 629 =head1 AUTHORS
 630
 631 Eric Blake
 632
 633 Richard W.M. Jones
 634
 635 Yann E. MORIN
 636
 637 Nir Soffer
 638
 639 Pino Toscano
 640
 641 =head1 COPYRIGHT
 642
 643 Copyright (C) 2013-2019 Red Hat Inc.