nbdkit(1)

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

NAME

6       nbdkit - toolkit for creating NBD servers
7

SYNOPSIS

9        nbdkit [-D|--debug PLUGIN|FILTER|nbdkit.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] [--swap]
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 small disk containing test patterns using
71           nbdkit-data-plugin(1):
72
73            nbdkit data ' ( 0x55 0xAA )*2048 '
74
75       •   Forward an NBD connection to a remote server over HTTPS or SSH
76           using nbdkit-curl-plugin(1) or 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       •   Create a sparse 1 terabyte RAM disk using nbdkit-memory-plugin(1)
83           and use it as a loop device (nbdkit-loop(1)):
84
85            nbdkit memory 1T
86            nbd-client localhost /dev/nbd0
87
88       •   Create a floppy disk image containing files from a local directory
89           using nbdkit-floppy-plugin(1):
90
91            nbdkit floppy dir/
92
93   Combining plugins and filters
94       •   Serve only the first partition from compressed disk image
95           disk.img.xz, combining nbdkit-partition-filter(1),
96           nbdkit-xz-filter(1) and nbdkit-file-plugin(1).
97
98            nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
99
100           To understand this command line:
101
102                                        plugin name and plugin parameter
103                                                          │
104                                                  ┌───────┴──────┐
105                                                  │              │
106            nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
107                            │              │                          │
108                            └──────────────┴────┬─────────────────────┘
109                                                │
110                                   filters and filter parameter
111
112       •   Create a scratch, empty nbdkit device and inject errors and delays,
113           for testing clients, using nbdkit-memory-plugin(1),
114           nbdkit-error-filter(1) and nbdkit-delay-filter(1):
115
116            nbdkit --filter=error --filter=delay memory 100M \
117                   error-rate=10% rdelay=1 wdelay=1
118
119   Writing plugins in shell script
120       •   Write a simple, custom plugin in shell script using
121           nbdkit-sh-plugin(3):
122
123            nbdkit sh - <<'EOF'
124              case "$1" in
125                get_size) echo 1M ;;
126                pread) dd if=/dev/zero count=$3 iflag=count_bytes ;;
127                *) exit 2 ;;
128              esac
129            EOF
130
131       •   The same example as above can be written entirely on the command
132           line using nbdkit-eval-plugin(1):
133
134            nbdkit eval get_size='echo 1M' \
135                        pread='dd if=/dev/zero count=$3 iflag=count_bytes'
136
137   Display information
138       Display information about nbdkit or a specific plugin:
139
140        nbdkit --help
141        nbdkit --version
142        nbdkit --dump-config
143        nbdkit example1 --help
144        nbdkit example1 --dump-plugin
145

GLOBAL OPTIONS

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

PLUGIN NAME

409       You can give the full path to the plugin, like this:
410
411        nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]
412
413       but it is usually more convenient to use this equivalent syntax:
414
415        nbdkit file [...]
416
417       $libdir is set at compile time.  To print it out, do:
418
419        nbdkit --dump-config
420

PLUGIN CONFIGURATION

422       After specifying the plugin name you can (optionally, it depends on the
423       plugin) give plugin configuration on the command line in the form of
424       "key=value".  For example:
425
426        nbdkit file file=disk.img
427
428       To list all the options supported by a plugin, do:
429
430        nbdkit --help file
431
432       To dump information about a plugin, do:
433
434        nbdkit file --dump-plugin
435
436   Magic parameters
437       Some plugins declare a special "magic config key".  This is a key which
438       is assumed if no "key=" part is present.  For example:
439
440        nbdkit file disk.img
441
442       is assumed to be "file=disk.img" because the file plugin declares
443       "file" as its magic config key.  There can be ambiguity in the parsing
444       of magic config keys if the value might look like a "key=value".  If
445       there could be ambiguity then modify the value, eg. by prefixing it
446       with "./"
447
448       There is also a special exception for plugins which do not declare a
449       magic config key, but where the first plugin argument does not contain
450       an '=' character: it is assumed to be "script=value".  This is used by
451       scripting language plugins:
452
453        nbdkit perl foo.pl [args...]
454
455       has the same meaning as:
456
457        nbdkit perl script=foo.pl [args...]
458
459   Shebang scripts
460       You can use "#!" to run nbdkit plugins written in most scripting
461       languages.  The file should be executable.  For example:
462
463        #!/usr/sbin/nbdkit perl
464        sub open {
465          # etc
466        }
467
468       (see nbdkit-perl-plugin(3) for a full example).
469

SERVER DEBUG FLAGS

471       As well as enabling or disabling debugging in the server using
472       --verbose you can control extra debugging in the server using the
473       -D nbdkit.* flags listed in this section.  Note these flags are an
474       internal implementation detail of the server and may be changed or
475       removed at any time in the future.
476
477       -D nbdkit.backend.controlpath=0
478       -D nbdkit.backend.controlpath=1
479       -D nbdkit.backend.datapath=0
480       -D nbdkit.backend.datapath=1
481           These flags control the verbosity of nbdkit backend debugging
482           messages (the ones which show every request processed by the
483           server).  The default for both settings is 1 (normal debugging) but
484           you can set them to 0 to suppress these messages.
485
486           -D nbdkit.backend.datapath=0 is the more useful setting which lets
487           you suppress messages about pread, pwrite, zero, trim, etc.
488           commands.  When transferring large amounts of data these messages
489           are numerous and not usually very interesting.
490
491           -D nbdkit.backend.controlpath=0 suppresses the non-datapath
492           commands (config, open, close, can_write, etc.)
493
494       -D nbdkit.tls.log=N
495           Enable TLS logging.  "N" can be in the range 0 (no logging) to 99.
496           See gnutls_global_set_log_level(3).
497
498       -D nbdkit.tls.session=1
499           Print additional information about the TLS session, such as the
500           type of authentication and encryption, and client certificate
501           information.
502

SIGNALS

504       nbdkit responds to the following signals:
505
506       "SIGINT"
507       "SIGQUIT"
508       "SIGTERM"
509           The server exits cleanly.
510
511       "SIGPIPE"
512           This signal is ignored.
513

ENVIRONMENT VARIABLES

515       "LISTEN_FDS"
516       "LISTEN_PID"
517           If present in the environment when nbdkit starts up, these trigger
518           "SOCKET ACTIVATION" in nbdkit-service(1).
519

AUTHORS

620       Eric Blake
621
622       Richard W.M. Jones
623
624       Yann E. MORIN
625
626       Nir Soffer
627
628       Pino Toscano
629

COPYRIGHT

631       Copyright (C) 2013-2020 Red Hat Inc.
632

LICENSE

634       Redistribution and use in source and binary forms, with or without
635       modification, are permitted provided that the following conditions are
636       met:
637
638       •   Redistributions of source code must retain the above copyright
639           notice, this list of conditions and the following disclaimer.
640
641       •   Redistributions in binary form must reproduce the above copyright
642           notice, this list of conditions and the following disclaimer in the
643           documentation and/or other materials provided with the
644           distribution.
645
646       •   Neither the name of Red Hat nor the names of its contributors may
647           be used to endorse or promote products derived from this software
648           without specific prior written permission.
649
650       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
651       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
652       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
653       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
654       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
655       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
656       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
657       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
658       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
659       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
660       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
661
662
663
664nbdkit-1.28.2                     2021-11-09                         nbdkit(1)