1nbdkit(1) NBDKIT nbdkit(1)
2
6 nbdkit - toolkit for creating NBD servers
7
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]
14 [-n|--newstyle] [-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]
24 PLUGIN [[KEY=]VALUE [KEY=VALUE [...]]]
25 nbdkit --dump-config
27 nbdkit PLUGIN --dump-plugin
29 nbdkit --help
31
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 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 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 If you want to write your own nbdkit plugin you should read
50 nbdkit-plugin(3).
51 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
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 nbdkit file disk.img
62 guestfish --rw --format=raw -a nbd://localhost
63 · Serve file disk.img on port 10809, requiring clients to use
65 encrypted (TLS) connections:
66 nbdkit --tls=require file disk.img
68 Other nbdkit plugins
70 · Create a 1MB disk with one empty partition entirely on the command
71 line using nbdkit-data-plugin(1):
72 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 · Forward an NBD connection to a remote server over HTTPS or SSH
79 using nbdkit-curl-plugin(1) or nbdkit-ssh-plugin(1):
80 nbdkit -r curl https://example.com/disk.img
82 nbdkit ssh host=example.com /var/tmp/disk.img
84 · Create a RAM disk using nbdkit-memory-plugin(1):
86 nbdkit memory size=64M
88 · Create a floppy disk image containing files from a local directory
90 using nbdkit-floppy-plugin(1):
91 nbdkit floppy dir/
93 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 nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
100 To understand this command line:
102 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 · 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 nbdkit --filter=error --filter=delay memory size=100M \
118 error-rate=10% rdelay=1 wdelay=1
119 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 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 Display information
133 Display information about nbdkit or a specific plugin:
134 nbdkit --help
136 nbdkit --version
137 nbdkit --dump-config
138 nbdkit example1 --help
139 nbdkit example1 --dump-plugin
140
142 --help
143 Display brief command line usage information and exit.
144 -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 --dump-config
153 Dump out the compile-time configuration values and exit. See
154 nbdkit-probing(1).
155 --dump-plugin
157 Dump out information about the plugin and exit. See
158 nbdkit-probing(1).
159 --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 An alternative to this is "CAPTIVE NBDKIT" in nbdkit-captive(1).
167 This option implies --foreground.
169 -e EXPORTNAME
171 --export EXPORTNAME
172 --export-name EXPORTNAME
173 --exportname EXPORTNAME
174 Set the exportname.
175 If not set, exportname "" (empty string) is used. Exportnames are
177 not allowed with the oldstyle protocol.
178 -f
180 --foreground
181 --no-fork
182 Don't fork into the background.
183 --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 -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 The server needs sufficient permissions to be able to do this.
196 Normally this would mean starting the server up as root.
197 See also -u.
199 -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 --log=stderr
207 --log=syslog
208 Send error messages to either standard error (--log=stderr) or to
209 the system log (--log=syslog).
210 The default is to send error messages to stderr, unless nbdkit
212 forks into the background in which case they are sent to syslog.
213 For more details see "LOGGING" in nbdkit-service(1).
215 -n
217 --new-style
218 --newstyle
219 Use the newstyle NBD protocol protocol. This is the default in
220 nbdkit ≥ 1.3. In earlier versions the default was oldstyle. See
221 nbdkit-protocol(1).
222 -o
224 --old-style
225 --oldstyle
226 Use the oldstyle NBD protocol. This was the default in nbdkit ≤
227 1.2, but now the default is newstyle. Note this is incompatible
228 with newer features such as export names and TLS. See
229 nbdkit-protocol(1).
230 -P PIDFILE
232 --pid-file PIDFILE
233 --pidfile PIDFILE
234 Write "PIDFILE" (containing the process ID of the server) after
235 nbdkit becomes ready to accept connections.
236 If the file already exists, it is overwritten. nbdkit does not
238 delete the file when it exits.
239 -p PORT
241 --port PORT
242 Change the TCP/IP port number on which nbdkit serves requests. The
243 default is 10809. See also -i.
244 -r
246 --read-only
247 --readonly
248 The export will be read-only. If a client writes, then it will get
249 an error.
250 Note that some plugins inherently don't support writes. With those
252 plugins the -r option is added implicitly.
253 nbdkit-cow-filter(1) can be placed over read-only plugins to
255 provide copy-on-write (or "snapshot") functionality. If you are
256 using qemu as a client then it also supports snapshots.
257 --run CMD
259 Run nbdkit as a captive subprocess of "CMD". When "CMD" exits,
260 nbdkit is killed. See "CAPTIVE NBDKIT" in nbdkit-captive(1).
261 This option implies --foreground.
263 -s
265 --single
266 --stdin
267 Don't fork. Handle a single NBD connection on stdin/stdout. After
268 stdin closes, the server exits.
269 You can use this option to run nbdkit from inetd or similar
271 superservers; or just for testing; or if you want to run nbdkit in
272 a non-conventional way. Note that if you want to run nbdkit from
273 systemd, then it may be better to use "SOCKET ACTIVATION" in
274 nbdkit-service(1) instead of this option.
275 This option implies --foreground.
277 --selinux-label SOCKET-LABEL
279 Apply the SELinux label "SOCKET-LABEL" to the nbdkit listening
280 socket.
281 The common — perhaps only — use of this option is to allow libvirt
283 guests which are using SELinux and sVirt confinement to access
284 nbdkit Unix domain sockets:
285 nbdkit --selinux-label system_u:object_r:svirt_t:s0 ...
287 -t THREADS
289 --threads THREADS
290 Set the number of threads to be used per connection, which in turn
291 controls the number of outstanding requests that can be processed
292 at once. Only matters for plugins with thread_model=parallel
293 (where it defaults to 16). To force serialized behavior (useful if
294 the client is not prepared for out-of-order responses), set this to
295 1.
296 --tls=off
298 --tls=on
299 --tls=require
300 Disable, enable or require TLS (authentication and encryption
301 support). See nbdkit-tls(1).
302 --tls-certificates /path/to/certificates
304 Set the path to the TLS certificates directory. If not specified,
305 some built-in paths are checked. See nbdkit-tls(1) for more
306 details.
307 --tls-psk /path/to/pskfile
309 Set the path to the pre-shared keys (PSK) file. If used, this
310 overrides certificate authentication. There is no built-in path.
311 See nbdkit-tls(1) for more details.
312 --tls-verify-peer
314 Enables TLS client certificate verification. The default is not to
315 check the client's certificate.
316 -U SOCKET
318 --unix SOCKET
319 -U -
320 --unix -
321 Accept connections on the Unix domain socket "SOCKET" (which is a
322 path).
323 nbdkit creates this socket, but it will probably have incorrect
325 permissions (too permissive). If it is a problem that some
326 unauthorized user could connect to this socket between the time
327 that nbdkit starts up and the authorized user connects, then put
328 the socket into a directory that has restrictive permissions.
329 nbdkit does not delete the socket file when it exits. The caller
331 should delete the socket file after use (else if you try to start
332 nbdkit up again you will get an "Address already in use" error).
333 If the socket name is - then nbdkit generates a randomly named
335 private socket. This is useful with "CAPTIVE NBDKIT" in
336 nbdkit-captive(1).
337 -u USER
339 --user USER
340 Change user to "USER" after starting up. A user name or numeric
341 user ID can be used.
342 The server needs sufficient permissions to be able to do this.
344 Normally this would mean starting the server up as root.
345 See also -g.
347 -v
349 --verbose
350 Enable verbose messages.
351 It's a good idea to use -f as well so the process does not fork
353 into the background (but not required).
354 -V
356 --version
357 Print the version number of nbdkit and exit.
358
360 You can give the full path to the plugin, like this:
361 nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]
363 but it is usually more convenient to use this equivalent syntax:
365 nbdkit file [...]
367 $libdir is set at compile time. To print it out, do:
369 nbdkit --dump-config
371
373 After specifying the plugin name you can (optionally, it depends on the
374 plugin) give plugin configuration on the command line in the form of
375 "key=value". For example:
376 nbdkit file file=disk.img
378 To list all the options supported by a plugin, do:
380 nbdkit --help file
382 To dump information about a plugin, do:
384 nbdkit file --dump-plugin
386 Magic parameters
388 Some plugins declare a special "magic config key". This is a key which
389 is assumed if no "key=" part is present. For example:
390 nbdkit file disk.img
392 is assumed to be "file=disk.img" because the file plugin declares
394 "file" as its magic config key. There can be ambiguity in the parsing
395 of magic config keys if the value might look like a "key=value". If
396 there could be ambiguity then modify the value, eg. by prefixing it
397 with "./"
398 There is also a special exception for plugins which do not declare a
400 magic config key, but where the first plugin argument does not contain
401 an '=' character: it is assumed to be "script=value". This is used by
402 scripting language plugins:
403 nbdkit perl foo.pl [args...]
405 has the same meaning as:
407 nbdkit perl script=foo.pl [args...]
409 Shebang scripts
411 You can use "#!" to run nbdkit plugins written in most scripting
412 languages. The file should be executable. For example:
413 #!/usr/sbin/nbdkit perl
415 sub open {
416 # etc
417 }
418 (see nbdkit-perl-plugin(3) for a full example).
420
422 nbdkit responds to the following signals:
423 "SIGINT"
425 "SIGQUIT"
426 "SIGTERM"
427 The server exits cleanly.
428 "SIGPIPE"
430 This signal is ignored.
431
433 "LISTEN_FDS"
434 "LISTEN_PID"
435 If present in the environment when nbdkit starts up, these trigger
436 "SOCKET ACTIVATION" in nbdkit-service(1).
437
439 Other topics
440 nbdkit-captive(1) — Run nbdkit under another process and have it
441 reliably cleaned up.
442 nbdkit-loop(1) — Use nbdkit with the Linux kernel client to create loop
444 devices and loop mounts.
445 nbdkit-probing(1) — How to probe for nbdkit configuration and plugins.
447 nbdkit-protocol(1) — Which parts of the NBD protocol nbdkit supports.
449 nbdkit-service(1) — Running nbdkit as a service, and systemd socket
451 activation.
452 nbdkit-tls(1) — Authentication and encryption of NBD connections
454 (sometimes incorrectly called "SSL").
455 Plugins
457 nbdkit-curl-plugin(1), nbdkit-data-plugin(1),
458 nbdkit-example1-plugin(1), nbdkit-example2-plugin(1),
459 nbdkit-example3-plugin(1), nbdkit-example4-plugin(1),
460 nbdkit-ext2-plugin(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1),
461 nbdkit-full-plugin(1), nbdkit-guestfs-plugin(1), nbdkit-gzip-plugin(1),
462 nbdkit-iso-plugin(1), nbdkit-libvirt-plugin(1),
463 nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
464 nbdkit-nbd-plugin(1), nbdkit-null-plugin(1),
465 nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1),
466 nbdkit-random-plugin(1), nbdkit-split-plugin(1), nbdkit-ssh-plugin(1),
467 nbdkit-streaming-plugin(1), nbdkit-tar-plugin(1),
468 nbdkit-vddk-plugin(1), nbdkit-zero-plugin(1) ; nbdkit-lua-plugin(3),
469 nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
470 nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
471 nbdkit-tcl-plugin(3) .
472 Filters
474 nbdkit-blocksize-filter(1), nbdkit-cache-filter(1),
475 nbdkit-cow-filter(1), nbdkit-delay-filter(1), nbdkit-error-filter(1),
476 nbdkit-fua-filter(1), nbdkit-log-filter(1), nbdkit-noextents-filter(1),
477 nbdkit-nozero-filter(1), nbdkit-offset-filter(1),
478 nbdkit-partition-filter(1), nbdkit-rate-filter(1),
479 nbdkit-readahead-filter(1), nbdkit-truncate-filter(1),
480 nbdkit-xz-filter(1) .
481 For developers
483 nbdkit-plugin(3), nbdkit-filter(3).
484 Writing plugins in other programming languages
486 nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
487 nbdkit-python-plugin(3), nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
488 nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
489 NBD clients
491 qemu(1), nbd-client(1), guestfish(1).
492 nbdkit links
494 http://github.com/libguestfs/nbdkit — Source code.
495 Other NBD servers
497 qemu-nbd(1), nbd-server(1), https://bitbucket.org/hirofuchi/xnbd.
498 Documentation for the NBD protocol
500 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
501 https://nbd.sourceforge.io/.
502 Similar protocols
504 https://en.wikipedia.org/wiki/iSCSI,
505 https://en.wikipedia.org/wiki/ATA_over_Ethernet,
506 https://en.wikipedia.org/wiki/Fibre_Channel_over_Ethernet.
507 Other manual pages of interest
509 gnutls_priority_init(3), qemu-img(1), psktool(1), systemd.socket(5).
510
512 Eric Blake
513 Richard W.M. Jones
515 Yann E. MORIN
517 Nir Soffer
519 Pino Toscano
521
523 Copyright (C) 2013-2018 Red Hat Inc.
524
526 Redistribution and use in source and binary forms, with or without
527 modification, are permitted provided that the following conditions are
528 met:
529 · Redistributions of source code must retain the above copyright
531 notice, this list of conditions and the following disclaimer.
532 · Redistributions in binary form must reproduce the above copyright
534 notice, this list of conditions and the following disclaimer in the
535 documentation and/or other materials provided with the
536 distribution.
537 · Neither the name of Red Hat nor the names of its contributors may
539 be used to endorse or promote products derived from this software
540 without specific prior written permission.
541 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
543 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
544 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
545 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
546 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
547 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
548 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
549 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
550 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
551 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
552 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
553nbdkit-1.12.3 2019-05-22 nbdkit(1)