1nbdkit(1)                           NBDKIT                           nbdkit(1)
2
3
4

NAME

6       nbdkit - toolkit for creating NBD servers
7

SYNOPSIS

9        nbdkit [-D|--debug PLUGIN|FILTER.FLAG=N]
10               [-e|--exportname EXPORTNAME] [--exit-with-parent]
11               [--filter FILTER ...] [-f|--foreground]
12               [-g|--group GROUP] [-i|--ipaddr IPADDR]
13               [--log stderr|syslog|null]
14               [-n|--newstyle] [--mask-handshake MASK] [--no-sr] [-o|--oldstyle]
15               [-P|--pidfile PIDFILE]
16               [-p|--port PORT] [-r|--readonly]
17               [--run CMD] [-s|--single] [--selinux-label LABEL]
18               [-t|--threads THREADS]
19               [--tls off|on|require]
20               [--tls-certificates /path/to/certificates]
21               [--tls-psk /path/to/pskfile] [--tls-verify-peer]
22               [-U|--unix SOCKET] [-u|--user USER]
23               [-v|--verbose] [-V|--version] [--vsock]
24               PLUGIN [[KEY=]VALUE [KEY=VALUE [...]]]
25
26        nbdkit --dump-config
27
28        nbdkit PLUGIN --dump-plugin
29
30        nbdkit --help
31

DESCRIPTION

33       Network Block Device (NBD) is a network protocol for accessing block
34       devices over the network.  Block devices are hard disks and things that
35       behave like hard disks such as disk images and virtual machines.
36
37       nbdkit is both a toolkit for creating NBD servers from “unconventional”
38       sources, and the name of an NBD server.  nbdkit ships with many plugins
39       for performing common tasks like serving local files.
40
41   Plugins and filters
42       nbdkit is different from other NBD servers because you can easily
43       create new Network Block Device sources by writing a few glue
44       functions, possibly in C, or perhaps in a high level language like Perl
45       or Python.  The liberal licensing of nbdkit is meant to allow you to
46       link nbdkit with proprietary libraries or to include nbdkit in
47       proprietary code.
48
49       If you want to write your own nbdkit plugin you should read
50       nbdkit-plugin(3).
51
52       nbdkit also has a concept of filters which can be layered on top of
53       plugins.  Several filters are provided with nbdkit and if you want to
54       write your own you should read nbdkit-filter(3).
55

EXAMPLES

57   Basic file serving
58       ·   Serve file disk.img on port 10809 using nbdkit-file-plugin(1), and
59           connect to it using guestfish(1):
60
61            nbdkit file disk.img
62            guestfish --rw --format=raw -a nbd://localhost
63
64       ·   Serve file disk.img on port 10809, requiring clients to use
65           encrypted (TLS) connections:
66
67            nbdkit --tls=require file disk.img
68
69   Other nbdkit plugins
70       ·   Create a 1MB disk with one empty partition entirely on the command
71           line using nbdkit-data-plugin(1):
72
73            nbdkit data size=1M \
74                        data="@0x1b8 0xf8 0x21 0xdc 0xeb 0 0 0 0
75                              2 0 0x83 0x20 0x20 0 1 0  0 0 0xff 0x7
76                              @0x1fe 0x55 0xaa"
77
78       ·   Forward an NBD connection to a remote server over HTTPS or SSH
79           using nbdkit-curl-plugin(1) or nbdkit-ssh-plugin(1):
80
81            nbdkit -r curl https://example.com/disk.img
82
83            nbdkit ssh host=example.com /var/tmp/disk.img
84
85       ·   Create a RAM disk using nbdkit-memory-plugin(1):
86
87            nbdkit memory 64M
88
89       ·   Create a floppy disk image containing files from a local directory
90           using nbdkit-floppy-plugin(1):
91
92            nbdkit floppy dir/
93
94   Combining plugins and filters
95       ·   Serve only the first partition from compressed disk image
96           disk.img.xz, combining nbdkit-partition-filter(1),
97           nbdkit-xz-filter(1) and nbdkit-file-plugin(1).
98
99            nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
100
101           To understand this command line:
102
103                                        plugin name and plugin parameter
104
105                                                  ┌───────┴──────┐
106                                                  │              │
107            nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
108                            │              │                          │
109                            └──────────────┴────┬─────────────────────┘
110
111                                   filters and filter parameter
112
113       ·   Create a scratch, empty nbdkit device and inject errors and delays,
114           for testing clients, using nbdkit-memory-plugin(1),
115           nbdkit-error-filter(1) and nbdkit-delay-filter(1):
116
117            nbdkit --filter=error --filter=delay memory 100M \
118                   error-rate=10% rdelay=1 wdelay=1
119
120   Writing plugins in scripting languages
121       ·   Write a simple, custom plugin entirely on the command line in shell
122           script using nbdkit-sh-plugin(3):
123
124            nbdkit sh - <<'EOF'
125              case "$1" in
126                get_size) echo 1M ;;
127                pread) dd if=/dev/zero count=$3 iflag=count_bytes ;;
128                *) exit 2 ;;
129              esac
130            EOF
131
132   Display information
133       Display information about nbdkit or a specific plugin:
134
135        nbdkit --help
136        nbdkit --version
137        nbdkit --dump-config
138        nbdkit example1 --help
139        nbdkit example1 --dump-plugin
140

GLOBAL OPTIONS

142       --help
143           Display brief command line usage information and exit.
144
145       -D PLUGIN.FLAG=N
146       -D FILTER.FLAG=N
147       --debug PLUGIN.FLAG=N
148       --debug FILTER.FLAG=N
149           Set the plugin or filter Debug Flag called "FLAG" to the integer
150           value "N".  See "Debug Flags" in nbdkit-plugin(3).
151
152       --dump-config
153           Dump out the compile-time configuration values and exit.  See
154           nbdkit-probing(1).
155
156       --dump-plugin
157           Dump out information about the plugin and exit.  See
158           nbdkit-probing(1).
159
160       --exit-with-parent
161           If the parent process exits, we exit.  This can be used to avoid
162           complicated cleanup or orphaned nbdkit processes.  There are some
163           important caveats with this, see "EXIT WITH PARENT" in
164           nbdkit-captive(1).
165
166           An alternative to this is "CAPTIVE NBDKIT" in nbdkit-captive(1).
167
168           This option implies --foreground.
169
170       -e EXPORTNAME
171       --export EXPORTNAME
172       --export-name EXPORTNAME
173       --exportname EXPORTNAME
174           Set the exportname.
175
176           If not set, exportname "" (empty string) is used.  Exportnames are
177           not allowed with the oldstyle protocol.
178
179       -f
180       --foreground
181       --no-fork
182           Don't fork into the background.
183
184       --filter FILTER
185           Add a filter before the plugin.  This option may be given one or
186           more times to stack filters in front of the plugin.  They are
187           processed in the order they appear on the command line.  See
188           "FILTERS" and nbdkit-filter(3).
189
190       -g GROUP
191       --group GROUP
192           Change group to "GROUP" after starting up.  A group name or numeric
193           group ID can be used.
194
195           The server needs sufficient permissions to be able to do this.
196           Normally this would mean starting the server up as root.
197
198           See also -u.
199
200       -i IPADDR
201       --ip-addr IPADDR
202       --ipaddr IPADDR
203           Listen on the specified interface.  The default is to listen on all
204           interfaces.  See also -p.
205
206       --log=stderr
207       --log=syslog
208       --log=null
209           Send error messages to standard error (--log=stderr), or to the
210           system log (--log=syslog), or discard them completely (--log=null,
211           not recommended for normal use).
212
213           The default is to send error messages to stderr, unless nbdkit
214           forks into the background in which case they are sent to syslog.
215
216           For more details see "LOGGING" in nbdkit-service(1).
217
218       -n
219       --new-style
220       --newstyle
221           Use the newstyle NBD protocol.  This is the default in nbdkit ≥
222           1.3.  In earlier versions the default was oldstyle.  See
223           nbdkit-protocol(1).
224
225       --no-sr
226           Do not advertise structured replies.  A client must request
227           structured replies to take advantage of block status and potential
228           sparse reads; however, as structured reads are not a mandatory part
229           of the newstyle NBD protocol, this option can be used to debug
230           client fallbacks for dealing with older servers.  See
231           nbdkit-protocol(1).
232
233       -o
234       --old-style
235       --oldstyle
236           Use the oldstyle NBD protocol.  This was the default in nbdkit ≤
237           1.2, but now the default is newstyle.  Note this is incompatible
238           with newer features such as export names and TLS.  See
239           nbdkit-protocol(1).
240
241       -P PIDFILE
242       --pid-file PIDFILE
243       --pidfile PIDFILE
244           Write "PIDFILE" (containing the process ID of the server) after
245           nbdkit becomes ready to accept connections.
246
247           If the file already exists, it is overwritten.  nbdkit does not
248           delete the file when it exits.
249
250       -p PORT
251       --port PORT
252           Change the TCP/IP port number on which nbdkit serves requests.  The
253           default is 10809.  See also -i.
254
255       -r
256       --read-only
257       --readonly
258           The export will be read-only.  If a client writes, then it will get
259           an error.
260
261           Note that some plugins inherently don't support writes.  With those
262           plugins the -r option is added implicitly.
263
264           nbdkit-cow-filter(1) can be placed over read-only plugins to
265           provide copy-on-write (or "snapshot") functionality.  If you are
266           using qemu as a client then it also supports snapshots.
267
268       --run CMD
269           Run nbdkit as a captive subprocess of "CMD".  When "CMD" exits,
270           nbdkit is killed.  See "CAPTIVE NBDKIT" in nbdkit-captive(1).
271
272           This option implies --foreground.
273
274       -s
275       --single
276       --stdin
277           Don't fork.  Handle a single NBD connection on stdin/stdout.  After
278           stdin closes, the server exits.
279
280           You can use this option to run nbdkit from inetd or similar
281           superservers; or just for testing; or if you want to run nbdkit in
282           a non-conventional way.  Note that if you want to run nbdkit from
283           systemd, then it may be better to use "SOCKET ACTIVATION" in
284           nbdkit-service(1) instead of this option.
285
286           This option implies --foreground.
287
288       --selinux-label SOCKET-LABEL
289           Apply the SELinux label "SOCKET-LABEL" to the nbdkit listening
290           socket.
291
292           The common — perhaps only — use of this option is to allow libvirt
293           guests which are using SELinux and sVirt confinement to access
294           nbdkit Unix domain sockets:
295
296            nbdkit --selinux-label system_u:object_r:svirt_t:s0 ...
297
298       -t THREADS
299       --threads THREADS
300           Set the number of threads to be used per connection, which in turn
301           controls the number of outstanding requests that can be processed
302           at once.  Only matters for plugins with thread_model=parallel
303           (where it defaults to 16).  To force serialized behavior (useful if
304           the client is not prepared for out-of-order responses), set this to
305           1.
306
307       --tls=off
308       --tls=on
309       --tls=require
310           Disable, enable or require TLS (authentication and encryption
311           support).  See nbdkit-tls(1).
312
313       --tls-certificates /path/to/certificates
314           Set the path to the TLS certificates directory.  If not specified,
315           some built-in paths are checked.  See nbdkit-tls(1) for more
316           details.
317
318       --tls-psk /path/to/pskfile
319           Set the path to the pre-shared keys (PSK) file.  If used, this
320           overrides certificate authentication.  There is no built-in path.
321           See nbdkit-tls(1) for more details.
322
323       --tls-verify-peer
324           Enables TLS client certificate verification.  The default is not to
325           check the client's certificate.
326
327       -U SOCKET
328       --unix SOCKET
329       -U -
330       --unix -
331           Accept connections on the Unix domain socket "SOCKET" (which is a
332           path).
333
334           nbdkit creates this socket, but it will probably have incorrect
335           permissions (too permissive).  If it is a problem that some
336           unauthorized user could connect to this socket between the time
337           that nbdkit starts up and the authorized user connects, then put
338           the socket into a directory that has restrictive permissions.
339
340           nbdkit does not delete the socket file when it exits.  The caller
341           should delete the socket file after use (else if you try to start
342           nbdkit up again you will get an "Address already in use" error).
343
344           If the socket name is - then nbdkit generates a randomly named
345           private socket.  This is useful with "CAPTIVE NBDKIT" in
346           nbdkit-captive(1).
347
348       -u USER
349       --user USER
350           Change user to "USER" after starting up.  A user name or numeric
351           user ID can be used.
352
353           The server needs sufficient permissions to be able to do this.
354           Normally this would mean starting the server up as root.
355
356           See also -g.
357
358       -v
359       --verbose
360           Enable verbose messages.
361
362           It's a good idea to use -f as well so the process does not fork
363           into the background (but not required).
364
365       -V
366       --version
367           Print the version number of nbdkit and exit.
368
369       --vsock
370           Use the AF_VSOCK protocol (instead of TCP/IP).  You must use this
371           in conjunction with -p/--port.  See "AF_VSOCK" in
372           nbdkit-service(1).
373

PLUGIN NAME

375       You can give the full path to the plugin, like this:
376
377        nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]
378
379       but it is usually more convenient to use this equivalent syntax:
380
381        nbdkit file [...]
382
383       $libdir is set at compile time.  To print it out, do:
384
385        nbdkit --dump-config
386

PLUGIN CONFIGURATION

388       After specifying the plugin name you can (optionally, it depends on the
389       plugin) give plugin configuration on the command line in the form of
390       "key=value".  For example:
391
392        nbdkit file file=disk.img
393
394       To list all the options supported by a plugin, do:
395
396        nbdkit --help file
397
398       To dump information about a plugin, do:
399
400        nbdkit file --dump-plugin
401
402   Magic parameters
403       Some plugins declare a special "magic config key".  This is a key which
404       is assumed if no "key=" part is present.  For example:
405
406        nbdkit file disk.img
407
408       is assumed to be "file=disk.img" because the file plugin declares
409       "file" as its magic config key.  There can be ambiguity in the parsing
410       of magic config keys if the value might look like a "key=value".  If
411       there could be ambiguity then modify the value, eg. by prefixing it
412       with "./"
413
414       There is also a special exception for plugins which do not declare a
415       magic config key, but where the first plugin argument does not contain
416       an '=' character: it is assumed to be "script=value".  This is used by
417       scripting language plugins:
418
419        nbdkit perl foo.pl [args...]
420
421       has the same meaning as:
422
423        nbdkit perl script=foo.pl [args...]
424
425   Shebang scripts
426       You can use "#!" to run nbdkit plugins written in most scripting
427       languages.  The file should be executable.  For example:
428
429        #!/usr/sbin/nbdkit perl
430        sub open {
431          # etc
432        }
433
434       (see nbdkit-perl-plugin(3) for a full example).
435

SIGNALS

437       nbdkit responds to the following signals:
438
439       "SIGINT"
440       "SIGQUIT"
441       "SIGTERM"
442           The server exits cleanly.
443
444       "SIGPIPE"
445           This signal is ignored.
446

ENVIRONMENT VARIABLES

448       "LISTEN_FDS"
449       "LISTEN_PID"
450           If present in the environment when nbdkit starts up, these trigger
451           "SOCKET ACTIVATION" in nbdkit-service(1).
452

SEE ALSO

454   Other topics
455       nbdkit-captive(1) — Run nbdkit under another process and have it
456       reliably cleaned up.
457
458       nbdkit-loop(1) — Use nbdkit with the Linux kernel client to create loop
459       devices and loop mounts.
460
461       nbdkit-probing(1) — How to probe for nbdkit configuration and plugins.
462
463       nbdkit-protocol(1) — Which parts of the NBD protocol nbdkit supports.
464
465       nbdkit-security(1) — Lists past security issues in nbdkit.
466
467       nbdkit-service(1) — Running nbdkit as a service, and systemd socket
468       activation.
469
470       nbdkit-tls(1) — Authentication and encryption of NBD connections
471       (sometimes incorrectly called "SSL").
472
473   Plugins
474       nbdkit-curl-plugin(1), nbdkit-data-plugin(1),
475       nbdkit-example1-plugin(1), nbdkit-example2-plugin(1),
476       nbdkit-example3-plugin(1), nbdkit-example4-plugin(1),
477       nbdkit-ext2-plugin(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1),
478       nbdkit-full-plugin(1), nbdkit-guestfs-plugin(1), nbdkit-gzip-plugin(1),
479       nbdkit-info-plugin(1), nbdkit-iso-plugin(1), nbdkit-libvirt-plugin(1),
480       nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
481       nbdkit-nbd-plugin(1), nbdkit-null-plugin(1),
482       nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1),
483       nbdkit-random-plugin(1), nbdkit-split-plugin(1), nbdkit-ssh-plugin(1),
484       nbdkit-streaming-plugin(1), nbdkit-tar-plugin(1),
485       nbdkit-vddk-plugin(1), nbdkit-zero-plugin(1) ; nbdkit-lua-plugin(3),
486       nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
487       nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
488       nbdkit-tcl-plugin(3) .
489
490   Filters
491       nbdkit-blocksize-filter(1), nbdkit-cache-filter(1),
492       nbdkit-cacheextents-filter(1), nbdkit-cow-filter(1),
493       nbdkit-delay-filter(1), nbdkit-error-filter(1), nbdkit-fua-filter(1),
494       nbdkit-log-filter(1), nbdkit-nocache-filter(1),
495       nbdkit-noextents-filter(1), nbdkit-noparallel-filter(1),
496       nbdkit-nozero-filter(1), nbdkit-offset-filter(1),
497       nbdkit-partition-filter(1), nbdkit-rate-filter(1),
498       nbdkit-readahead-filter(1), nbdkit-retry-filter(1),
499       nbdkit-stats-filter(1), nbdkit-truncate-filter(1), nbdkit-xz-filter(1)
500       .
501
502   For developers
503       nbdkit-plugin(3), nbdkit-filter(3).
504
505   Writing plugins in other programming languages
506       nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
507       nbdkit-python-plugin(3), nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
508       nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
509
510   Release notes for previous releases of nbdkit
511       nbdkit-release-notes-1.4(1), nbdkit-release-notes-1.6(1),
512       nbdkit-release-notes-1.8(1), nbdkit-release-notes-1.10(1),
513       nbdkit-release-notes-1.12(1), nbdkit-release-notes-1.14(1),
514       nbdkit-release-notes-1.16(1).
515
516   NBD clients
517       guestfish(1), libnbd(3), nbd-client(1), nbdfuse(1), nbdsh(1), qemu(1).
518
519   nbdkit links
520       http://github.com/libguestfs/nbdkit — Source code.
521
522   Other NBD servers
523       qemu-nbd(1), nbd-server(1), https://bitbucket.org/hirofuchi/xnbd.
524
525   Documentation for the NBD protocol
526       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
527       https://nbd.sourceforge.io/.
528
529   Similar protocols
530       https://en.wikipedia.org/wiki/iSCSI,
531       https://en.wikipedia.org/wiki/ATA_over_Ethernet,
532       https://en.wikipedia.org/wiki/Fibre_Channel_over_Ethernet.
533
534   Other manual pages of interest
535       gnutls_priority_init(3), qemu-img(1), psktool(1), systemd.socket(5).
536

AUTHORS

538       Eric Blake
539
540       Richard W.M. Jones
541
542       Yann E. MORIN
543
544       Nir Soffer
545
546       Pino Toscano
547
549       Copyright (C) 2013-2019 Red Hat Inc.
550

LICENSE

552       Redistribution and use in source and binary forms, with or without
553       modification, are permitted provided that the following conditions are
554       met:
555
556       ·   Redistributions of source code must retain the above copyright
557           notice, this list of conditions and the following disclaimer.
558
559       ·   Redistributions in binary form must reproduce the above copyright
560           notice, this list of conditions and the following disclaimer in the
561           documentation and/or other materials provided with the
562           distribution.
563
564       ·   Neither the name of Red Hat nor the names of its contributors may
565           be used to endorse or promote products derived from this software
566           without specific prior written permission.
567
568       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
569       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
570       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
571       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
572       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
573       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
574       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
575       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
576       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
577       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
578       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
579
580
581
582nbdkit-1.16.1                     2019-12-03                         nbdkit(1)
Impressum