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 =back
 448
 449 =head1 PLUGIN NAME
 450
 451 You can give the full path to the plugin, like this:
 452
 453  nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]
 454
 455 but it is usually more convenient to use this equivalent syntax:
 456
 457  nbdkit file [...]
 458
 459 C<$libdir> is set at compile time.  To print it out, do:
 460
 461  nbdkit --dump-config
 462
 463 =head1 PLUGIN CONFIGURATION
 464
 465 After specifying the plugin name you can (optionally, it depends
 466 on the plugin) give plugin configuration on the command line in
 467 the form of C<key=value>.  For example:
 468
 469  nbdkit file file=disk.img
 470
 471 To list all the options supported by a plugin, do:
 472
 473  nbdkit --help file
 474
 475 To dump information about a plugin, do:
 476
 477  nbdkit file --dump-plugin
 478
 479 =head2 Magic parameters
 480
 481 Some plugins declare a special "magic config key".  This is a key
 482 which is assumed if no C<key=> part is present.  For example:
 483
 484  nbdkit file disk.img
 485
 486 is assumed to be C<file=disk.img> because the file plugin declares
 487 C<file> as its magic config key.  There can be ambiguity in the
 488 parsing of magic config keys if the value might look like a
 489 C<key=value>.  If there could be ambiguity then modify the value,
 490 eg. by prefixing it with C<./>
 491
 492 There is also a special exception for plugins which do not declare a
 493 magic config key, but where the first plugin argument does not contain
 494 an C<'='> character: it is assumed to be C<script=value>.  This is
 495 used by scripting language plugins:
 496
 497  nbdkit perl foo.pl [args...]
 498
 499 has the same meaning as:
 500
 501  nbdkit perl script=foo.pl [args...]
 502
 503 =head2 Shebang scripts
 504
 505 You can use C<#!> to run nbdkit plugins written in most scripting
 506 languages.  The file should be executable.  For example:
 507
 508  #!/usr/sbin/nbdkit perl
 509  sub open {
 510    # etc
 511  }
 512
 513 (see L<nbdkit-perl-plugin(3)> for a full example).
 514
 515 =head1 SIGNALS
 516
 517 nbdkit responds to the following signals:
 518
 519 =over 4
 520
 521 =item C<SIGINT>
 522
 523 =item C<SIGQUIT>
 524
 525 =item C<SIGTERM>
 526
 527 The server exits cleanly.
 528
 529 =item C<SIGPIPE>
 530
 531 This signal is ignored.
 532
 533 =back
 534
 535 =head1 ENVIRONMENT VARIABLES
 536
 537 =over 4
 538
 539 =item C<LISTEN_FDS>
 540
 541 =item C<LISTEN_PID>
 542
 543 If present in the environment when nbdkit starts up, these trigger
 544 L<nbdkit-service(1)/SOCKET ACTIVATION>.
 545
 546 =back
 547
 548 =head1 SEE ALSO
 549
 550 =head2 Other topics
 551
 552 L<nbdkit-captive(1)> — Run nbdkit under another process and have it
 553 reliably cleaned up.
 554
 555 L<nbdkit-loop(1)> — Use nbdkit with the Linux kernel client to create
 556 loop devices and loop mounts.
 557
 558 L<nbdkit-probing(1)> — How to probe for nbdkit configuration and plugins.
 559
 560 L<nbdkit-protocol(1)> — Which parts of the NBD protocol nbdkit supports.
 561
 562 L<nbdkit-service(1)> — Running nbdkit as a service, and systemd socket
 563 activation.
 564
 565 L<nbdkit-tls(1)> — Authentication and encryption of NBD connections
 566 (sometimes incorrectly called "SSL").
 567
 568 =head2 Plugins
 569
 570 __PLUGIN_LINKS__.
 571
 572 =head2 Filters
 573
 574 __FILTER_LINKS__.
 575
 576 =head2 For developers
 577
 578 L<nbdkit-plugin(3)>,
 579 L<nbdkit-filter(3)>.
 580
 581 =head2 Writing plugins in other programming languages
 582
 583 __LANG_PLUGIN_LINKS__.
 584
 585 =head2 NBD clients
 586
 587 L<qemu(1)>,
 588 L<nbd-client(1)>,
 589 L<guestfish(1)>.
 590
 591 =head2 nbdkit links
 592
 593 L<http://github.com/libguestfs/nbdkit> — Source code.
 594
 595 =head2 Other NBD servers
 596
 597 L<qemu-nbd(1)>,
 598 L<nbd-server(1)>,
 599 L<https://bitbucket.org/hirofuchi/xnbd>.
 600
 601 =head2 Documentation for the NBD protocol
 602
 603 L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>,
 604 L<https://nbd.sourceforge.io/>.
 605
 606 =head2 Similar protocols
 607
 608 L<https://en.wikipedia.org/wiki/iSCSI>,
 609 L<https://en.wikipedia.org/wiki/ATA_over_Ethernet>,
 610 L<https://en.wikipedia.org/wiki/Fibre_Channel_over_Ethernet>.
 611
 612 =head2 Other manual pages of interest
 613
 614 L<gnutls_priority_init(3)>,
 615 L<qemu-img(1)>,
 616 L<psktool(1)>,
 617 L<systemd.socket(5)>.
 618
 619 =head1 AUTHORS
 620
 621 Eric Blake
 622
 623 Richard W.M. Jones
 624
 625 Yann E. MORIN
 626
 627 Nir Soffer
 628
 629 Pino Toscano
 630
 631 =head1 COPYRIGHT
 632
 633 Copyright (C) 2013-2019 Red Hat Inc.