3 nbdkit - toolkit for creating NBD servers
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.
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
20 =head2 Plugins and filters
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
29 If you want to write your own nbdkit plugin you should read
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)>.
38 =head2 Basic file serving
44 Serve file F<disk.img> on port 10809 using L<nbdkit-file-plugin(1)>,
45 and connect to it using L<guestfish(1)>:
48 guestfish --rw --format=raw -a nbd://localhost
52 Serve file F<disk.img> on port 10809, requiring clients to use
53 encrypted (TLS) connections:
55 nbdkit --tls=require file disk.img
59 =head2 Other nbdkit plugins
65 Create a 1MB disk with one empty partition entirely on the command
66 line using L<nbdkit-data-plugin(1)>:
69 data="@0x1b8 0xf8 0x21 0xdc 0xeb 0 0 0 0
70 2 0 0x83 0x20 0x20 0 1 0 0 0 0xff 0x7
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)>:
78 nbdkit -r curl https://example.com/disk.img
80 nbdkit ssh host=example.com /var/tmp/disk.img
84 Create a RAM disk using L<nbdkit-memory-plugin(1)>:
90 Create a floppy disk image containing files from a local directory
91 using L<nbdkit-floppy-plugin(1)>:
97 =head2 Combining plugins and filters
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)>.
107 nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
109 To understand this command line:
111 plugin name and plugin parameter
115 nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
117 └──────────────┴────┬─────────────────────┘
119 filters and filter parameter
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)>:
127 nbdkit --filter=error --filter=delay memory 100M \
128 error-rate=10% rdelay=1 wdelay=1
132 =head2 Writing plugins in scripting languages
138 Write a simple, custom plugin entirely on the command line in shell
139 script using L<nbdkit-sh-plugin(3)>:
144 pread) dd if=/dev/zero count=$3 iflag=count_bytes ;;
151 =head2 Display information
153 Display information about nbdkit or a specific plugin:
158 nbdkit example1 --help
159 nbdkit example1 --dump-plugin
161 =head1 GLOBAL OPTIONS
167 Display brief command line usage information and exit.
169 =item B<-D> PLUGIN.FLAG=N
171 =item B<-D> FILTER.FLAG=N
173 =item B<--debug> PLUGIN.FLAG=N
175 =item B<--debug> FILTER.FLAG=N
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>.
180 =item B<--dump-config>
182 Dump out the compile-time configuration values and exit.
183 See L<nbdkit-probing(1)>.
185 =item B<--dump-plugin>
187 Dump out information about the plugin and exit.
188 See L<nbdkit-probing(1)>.
190 =item B<--exit-with-parent>
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>.
196 An alternative to this is L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
198 This option implies I<--foreground>.
200 =item B<-e> EXPORTNAME
202 =item B<--export> EXPORTNAME
204 =item B<--export-name> EXPORTNAME
206 =item B<--exportname> EXPORTNAME
210 If not set, exportname C<""> (empty string) is used. Exportnames are
211 not allowed with the oldstyle protocol.
215 =item B<--foreground>
219 I<Don't> fork into the background.
221 =item B<--filter> FILTER
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
230 =item B<--group> GROUP
232 Change group to C<GROUP> after starting up. A group name or numeric
233 group ID can be used.
235 The server needs sufficient permissions to be able to do this.
236 Normally this would mean starting the server up as root.
242 =item B<--ip-addr> IPADDR
244 =item B<--ipaddr> IPADDR
246 Listen on the specified interface. The default is to listen on all
247 interfaces. See also I<-p>.
249 =item B<--log=stderr>
251 =item B<--log=syslog>
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).
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.
262 For more details see L<nbdkit-service(1)/LOGGING>.
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)>.
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)>.
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)>.
295 =item B<--pid-file> PIDFILE
297 =item B<--pidfile> PIDFILE
299 Write C<PIDFILE> (containing the process ID of the server) after
300 nbdkit becomes ready to accept connections.
302 If the file already exists, it is overwritten. nbdkit I<does not>
303 delete the file when it exits.
309 Change the TCP/IP port number on which nbdkit serves requests.
310 The default is C<10809>. See also I<-i>.
318 The export will be read-only. If a client writes, then it will get an
321 Note that some plugins inherently don't support writes. With those
322 plugins the I<-r> option is added implicitly.
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.
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>.
333 This option implies I<--foreground>.
341 Don't fork. Handle a single NBD connection on stdin/stdout. After
342 stdin closes, the server exits.
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.
350 This option implies I<--foreground>.
352 =item B<--selinux-label> SOCKET-LABEL
354 Apply the SELinux label C<SOCKET-LABEL> to the nbdkit listening
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
361 nbdkit --selinux-label system_u:object_r:svirt_t:s0 ...
365 Specifies that the NBD device will be used as swap space loop mounted
366 on the same machine which is running nbdkit. To avoid deadlocks this
367 locks the whole nbdkit process into memory using L<mlockall(2)>. This
368 may require additional permissions, such as starting the server as
369 root or raising the C<RLIMIT_MEMLOCK> (L<ulimit(1)> I<-l>) limit on
374 =item B<--threads> THREADS
376 Set the number of threads to be used per connection, which in turn
377 controls the number of outstanding requests that can be processed at
378 once. Only matters for plugins with thread_model=parallel (where it
379 defaults to 16). To force serialized behavior (useful if the client
380 is not prepared for out-of-order responses), set this to 1.
386 =item B<--tls=require>
388 Disable, enable or require TLS (authentication and encryption
389 support). See L<nbdkit-tls(1)>.
391 =item B<--tls-certificates> /path/to/certificates
393 Set the path to the TLS certificates directory. If not specified,
394 some built-in paths are checked. See L<nbdkit-tls(1)> for more
397 =item B<--tls-psk> /path/to/pskfile
399 Set the path to the pre-shared keys (PSK) file. If used, this
400 overrides certificate authentication. There is no built-in path. See
401 L<nbdkit-tls(1)> for more details.
403 =item B<--tls-verify-peer>
405 Enables TLS client certificate verification. The default is I<not> to
406 check the client's certificate.
410 =item B<--unix> SOCKET
416 Accept connections on the Unix domain socket C<SOCKET> (which is a
419 nbdkit creates this socket, but it will probably have incorrect
420 permissions (too permissive). If it is a problem that some
421 unauthorized user could connect to this socket between the time that
422 nbdkit starts up and the authorized user connects, then put the socket
423 into a directory that has restrictive permissions.
425 nbdkit does B<not> delete the socket file when it exits. The caller
426 should delete the socket file after use (else if you try to start
427 nbdkit up again you will get an C<Address already in use> error).
429 If the socket name is I<-> then nbdkit generates a randomly named
430 private socket. This is useful with L<nbdkit-captive(1)/CAPTIVE NBDKIT>.
436 Change user to C<USER> after starting up. A user name or numeric user
439 The server needs sufficient permissions to be able to do this.
440 Normally this would mean starting the server up as root.
448 Enable verbose messages.
450 It's a good idea to use I<-f> as well so the process does not fork
451 into the background (but not required).
457 Print the version number of nbdkit and exit.
461 Use the AF_VSOCK protocol (instead of TCP/IP). You must use this in
462 conjunction with I<-p>/I<--port>. See L<nbdkit-service(1)/AF_VSOCK>.
468 You can give the full path to the plugin, like this:
470 nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]
472 but it is usually more convenient to use this equivalent syntax:
476 C<$libdir> is set at compile time. To print it out, do:
480 =head1 PLUGIN CONFIGURATION
482 After specifying the plugin name you can (optionally, it depends
483 on the plugin) give plugin configuration on the command line in
484 the form of C<key=value>. For example:
486 nbdkit file file=disk.img
488 To list all the options supported by a plugin, do:
492 To dump information about a plugin, do:
494 nbdkit file --dump-plugin
496 =head2 Magic parameters
498 Some plugins declare a special "magic config key". This is a key
499 which is assumed if no C<key=> part is present. For example:
503 is assumed to be C<file=disk.img> because the file plugin declares
504 C<file> as its magic config key. There can be ambiguity in the
505 parsing of magic config keys if the value might look like a
506 C<key=value>. If there could be ambiguity then modify the value,
507 eg. by prefixing it with C<./>
509 There is also a special exception for plugins which do not declare a
510 magic config key, but where the first plugin argument does not contain
511 an C<'='> character: it is assumed to be C<script=value>. This is
512 used by scripting language plugins:
514 nbdkit perl foo.pl [args...]
516 has the same meaning as:
518 nbdkit perl script=foo.pl [args...]
520 =head2 Shebang scripts
522 You can use C<#!> to run nbdkit plugins written in most scripting
523 languages. The file should be executable. For example:
525 #!/usr/sbin/nbdkit perl
530 (see L<nbdkit-perl-plugin(3)> for a full example).
534 nbdkit responds to the following signals:
544 The server exits cleanly.
548 This signal is ignored.
552 =head1 ENVIRONMENT VARIABLES
560 If present in the environment when nbdkit starts up, these trigger
561 L<nbdkit-service(1)/SOCKET ACTIVATION>.
569 L<nbdkit-captive(1)> — Run nbdkit under another process and have it
572 L<nbdkit-loop(1)> — Use nbdkit with the Linux kernel client to create
573 loop devices and loop mounts.
575 L<nbdkit-probing(1)> — How to probe for nbdkit configuration and plugins.
577 L<nbdkit-protocol(1)> — Which parts of the NBD protocol nbdkit supports.
579 L<nbdkit-security(1)> — Lists past security issues in nbdkit.
581 L<nbdkit-service(1)> — Running nbdkit as a service, and systemd socket
584 L<nbdkit-tls(1)> — Authentication and encryption of NBD connections
585 (sometimes incorrectly called "SSL").
595 =head2 For developers
600 =head2 Writing plugins in other programming languages
602 __LANG_PLUGIN_LINKS__.
604 =head2 Release notes for previous releases of nbdkit
606 L<nbdkit-release-notes-1.4(1)>,
607 L<nbdkit-release-notes-1.6(1)>,
608 L<nbdkit-release-notes-1.8(1)>,
609 L<nbdkit-release-notes-1.10(1)>,
610 L<nbdkit-release-notes-1.12(1)>,
611 L<nbdkit-release-notes-1.14(1)>,
612 L<nbdkit-release-notes-1.16(1)>.
625 L<http://github.com/libguestfs/nbdkit> — Source code.
627 =head2 Other NBD servers
631 L<https://bitbucket.org/hirofuchi/xnbd>.
633 =head2 Documentation for the NBD protocol
635 L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>,
636 L<https://nbd.sourceforge.io/>.
638 =head2 Similar protocols
640 L<https://en.wikipedia.org/wiki/iSCSI>,
641 L<https://en.wikipedia.org/wiki/ATA_over_Ethernet>,
642 L<https://en.wikipedia.org/wiki/Fibre_Channel_over_Ethernet>.
644 =head2 Other manual pages of interest
646 L<gnutls_priority_init(3)>,
649 L<systemd.socket(5)>.
665 Copyright (C) 2013-2019 Red Hat Inc.