Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
nbdkit(1)			    NBDKIT			     nbdkit(1)

NAME
       nbdkit -	toolkit	for creating NBD servers

SYNOPSIS
	nbdkit [-D|--debug PLUGIN|FILTER|nbdkit.FLAG=N]
	       [-e|--exportname	EXPORTNAME] [--exit-with-parent]
	       [--filter FILTER	...] [-f|--foreground]
	       [-g|--group GROUP] [-i|--ipaddr IPADDR]
	       [--log stderr|syslog|null]
	       [-n|--newstyle] [--mask-handshake MASK] [--no-sr] [-o|--oldstyle]
	       [-P|--pidfile PIDFILE]
	       [-p|--port PORT]	[-r|--readonly]
	       [--run CMD] [-s|--single] [--selinux-label LABEL] [--swap]
	       [-t|--threads THREADS]
	       [--tls off|on|require]
	       [--tls-certificates /path/to/certificates]
	       [--tls-psk /path/to/pskfile] [--tls-verify-peer]
	       [-U|--unix SOCKET] [-u|--user USER]
	       [-v|--verbose] [-V|--version] [--vsock]
	       PLUGIN [[KEY=]VALUE [KEY=VALUE [...]]]

	nbdkit --dump-config

	nbdkit PLUGIN --dump-plugin

	nbdkit --help

DESCRIPTION
       Network Block Device (NBD) is a network protocol	for accessing block
       devices over the	network.  Block	devices	are hard disks and things that
       behave like hard	disks such as disk images and virtual machines.

       nbdkit is both a	toolkit	for creating NBD servers from aunconventionala
       sources,	and the	name of	an NBD server.	nbdkit ships with many plugins
       for performing common tasks like	serving	local files.

   Plugins and filters
       nbdkit is different from	other NBD servers because you can easily
       create new Network Block	Device sources by writing a few	glue
       functions, possibly in C, or perhaps in a high level language like Perl
       or Python.  The liberal licensing of nbdkit is meant to allow you to
       link nbdkit with	proprietary libraries or to include nbdkit in
       proprietary code.

       If you want to write your own nbdkit plugin you should read
       nbdkit-plugin(3).

       nbdkit also has a concept of filters which can be layered on top	of
       plugins.	 Several filters are provided with nbdkit and if you want to
       write your own you should read nbdkit-filter(3).

EXAMPLES
   Basic file serving
       o   Serve file disk.img on port 10809 using nbdkit-file-plugin(1), and
	   connect to it using guestfish(1):

	    nbdkit file	disk.img
	    guestfish --rw --format=raw	-a nbd://localhost

       o   Serve file disk.img on port 10809, requiring	clients	to use
	   encrypted (TLS) connections:

	    nbdkit --tls=require file disk.img

   Other nbdkit	plugins
       o   Create a 1MB	disk with one empty partition entirely on the command
	   line	using nbdkit-data-plugin(1):

	    nbdkit data	size=1M	\
			data="@0x1b8 0xf8 0x21 0xdc 0xeb 0 0 0 0
			      2	0 0x83 0x20 0x20 0 1 0	0 0 0xff 0x7
			      @0x1fe 0x55 0xaa"

       o   Forward an NBD connection to	a remote server	over HTTPS or SSH
	   using nbdkit-curl-plugin(1) or nbdkit-ssh-plugin(1):

	    nbdkit -r curl https://example.com/disk.img

	    nbdkit ssh host=example.com	/var/tmp/disk.img

       o   Create a RAM	disk using nbdkit-memory-plugin(1):

	    nbdkit memory 64M

       o   Create a floppy disk	image containing files from a local directory
	   using nbdkit-floppy-plugin(1):

	    nbdkit floppy dir/

   Combining plugins and filters
       o   Serve only the first	partition from compressed disk image
	   disk.img.xz,	combining nbdkit-partition-filter(1),
	   nbdkit-xz-filter(1) and nbdkit-file-plugin(1).

	    nbdkit --filter=partition --filter=xz file disk.img.xz partition=1

	   To understand this command line:

					plugin name and	plugin parameter
							  a
						  aaaaaaaaa'aaaaaaa
						  a		 a
	    nbdkit --filter=partition --filter=xz file disk.img.xz partition=1
			    a		   a			      a
			    aaaaaaaaaaaaaaaa'aaaaa~aaaaaaaaaaaaaaaaaaaaaa
						a
				   filters and filter parameter

       o   Create a scratch, empty nbdkit device and inject errors and delays,
	   for testing clients,	using nbdkit-memory-plugin(1),
	   nbdkit-error-filter(1) and nbdkit-delay-filter(1):

	    nbdkit --filter=error --filter=delay memory	100M \
		   error-rate=10% rdelay=1 wdelay=1

   Writing plugins in shell script
       o   Write a simple, custom plugin in shell script using
	   nbdkit-sh-plugin(3):

	    nbdkit sh -	<<'EOF'
	      case "$1"	in
		get_size) echo 1M ;;
		pread) dd if=/dev/zero count=$3	iflag=count_bytes ;;
		*) exit	2 ;;
	      esac
	    EOF

       o   The same example as above can be written entirely on	the command
	   line	using nbdkit-eval-plugin(1):

	    nbdkit eval	get_size='echo 1M' \
			pread='dd if=/dev/zero count=$3	iflag=count_bytes'

   Display information
       Display information about nbdkit	or a specific plugin:

	nbdkit --help
	nbdkit --version
	nbdkit --dump-config
	nbdkit example1	--help
	nbdkit example1	--dump-plugin

GLOBAL OPTIONS
       --help
	   Display brief command line usage information	and exit.

       -D PLUGIN.FLAG=N
       -D FILTER.FLAG=N
       --debug PLUGIN.FLAG=N
       --debug FILTER.FLAG=N
	   Set the plugin or filter Debug Flag called "FLAG" to	the integer
	   value "N".  See "Debug Flags" in nbdkit-plugin(3).

       -D nbdkit.FLAG=N
       --debug nbdkit.FLAG=N
	   Set the nbdkit server Debug Flag called "FLAG" to the integer value
	   "N".	 See "SERVER DEBUG FLAGS" below.

       --dump-config
	   Dump	out the	compile-time configuration values and exit.  See
	   nbdkit-probing(1).

       --dump-plugin
	   Dump	out information	about the plugin and exit.  See
	   nbdkit-probing(1).

       --exit-with-parent
	   If the parent process exits,	we exit.  This can be used to avoid
	   complicated cleanup or orphaned nbdkit processes.  There are	some
	   important caveats with this,	see "EXIT WITH PARENT" in
	   nbdkit-captive(1).

	   An alternative to this is "CAPTIVE NBDKIT" in nbdkit-captive(1).

	   This	option implies --foreground.

       -e EXPORTNAME
       --export	EXPORTNAME
       --export-name EXPORTNAME
       --exportname EXPORTNAME
	   Set the exportname.

	   If not set, exportname "" (empty string) is used.  Exportnames are
	   not allowed with the	oldstyle protocol.

       -f
       --foreground
       --no-fork
	   Don't fork into the background.

       --filter	FILTER
	   Add a filter	before the plugin.  This option	may be given one or
	   more	times to stack filters in front	of the plugin.	They are
	   processed in	the order they appear on the command line.  See
	   "FILTERS" and nbdkit-filter(3).

       -g GROUP
       --group GROUP
	   Change group	to "GROUP" after starting up.  A group name or numeric
	   group ID can	be used.

	   The server needs sufficient permissions to be able to do this.
	   Normally this would mean starting the server	up as root.

	   See also -u.

       -i IPADDR
       --ip-addr IPADDR
       --ipaddr	IPADDR
	   Listen on the specified interface.  The default is to listen	on all
	   interfaces.	See also -p.

       --log=stderr
       --log=syslog
       --log=null
	   Send	error messages to standard error (--log=stderr), or to the
	   system log (--log=syslog), or discard them completely (--log=null,
	   not recommended for normal use).

	   The default is to send error	messages to stderr, unless nbdkit
	   forks into the background in	which case they	are sent to syslog.

	   For more details see	"LOGGING" in nbdkit-service(1).

       -n
       --new-style
       --newstyle
	   Use the newstyle NBD	protocol.  This	is the default in nbdkit aY
	   1.3.	 In earlier versions the default was oldstyle.	See
	   nbdkit-protocol(1).

       --no-sr
	   Do not advertise structured replies.	 A client must request
	   structured replies to take advantage	of block status	and potential
	   sparse reads; however, as structured	reads are not a	mandatory part
	   of the newstyle NBD protocol, this option can be used to debug
	   client fallbacks for	dealing	with older servers.  See
	   nbdkit-protocol(1).

       -o
       --old-style
       --oldstyle
	   Use the oldstyle NBD	protocol.  This	was the	default	in nbdkit ax
	   1.2,	but now	the default is newstyle.  Note this is incompatible
	   with	newer features such as export names and	TLS.  See
	   nbdkit-protocol(1).

       -P PIDFILE
       --pid-file PIDFILE
       --pidfile PIDFILE
	   Write "PIDFILE" (containing the process ID of the server) after
	   nbdkit becomes ready	to accept connections.

	   If the file already exists, it is overwritten.  nbdkit does not
	   delete the file when	it exits.

       -p PORT
       --port PORT
	   Change the TCP/IP port number on which nbdkit serves	requests.  The
	   default is 10809.  See also -i.

       -r
       --read-only
       --readonly
	   The export will be read-only.  If a client writes, then it will get
	   an error.

	   Note	that some plugins inherently don't support writes.  With those
	   plugins the -r option is added implicitly.

	   nbdkit-cow-filter(1)	can be placed over read-only plugins to
	   provide copy-on-write (or "snapshot") functionality.	 If you	are
	   using qemu as a client then it also supports	snapshots.

       --run CMD
	   Run nbdkit as a captive subprocess of "CMD".	 When "CMD" exits,
	   nbdkit is killed.  See "CAPTIVE NBDKIT" in nbdkit-captive(1).

	   This	option implies --foreground.

       -s
       --single
       --stdin
	   Don't fork.	Handle a single	NBD connection on stdin/stdout.	 After
	   stdin closes, the server exits.

	   You can use this option to run nbdkit from inetd or similar
	   superservers; or just for testing; or if you	want to	run nbdkit in
	   a non-conventional way.  Note that if you want to run nbdkit	from
	   systemd, then it may	be better to use "SOCKET ACTIVATION" in
	   nbdkit-service(1) instead of	this option.

	   This	option implies --foreground.

       --selinux-label SOCKET-LABEL
	   Apply the SELinux label "SOCKET-LABEL" to the nbdkit	listening
	   socket.

	   The common a	perhaps	only a use of this option is to	allow libvirt
	   guests which	are using SELinux and sVirt confinement	to access
	   nbdkit Unix domain sockets:

	    nbdkit --selinux-label system_u:object_r:svirt_t:s0	...

       --swap
	   Specifies that the NBD device will be used as swap space loop
	   mounted on the same machine which is	running	nbdkit.	 To avoid
	   deadlocks this locks	the whole nbdkit process into memory using
	   mlockall(2).	 This may require additional permissions, such as
	   starting the	server as root or raising the "RLIMIT_MEMLOCK"
	   (ulimit(1) -l) limit	on the process.

       -t THREADS
       --threads THREADS
	   Set the number of threads to	be used	per connection,	which in turn
	   controls the	number of outstanding requests that can	be processed
	   at once.  Only matters for plugins with thread_model=parallel
	   (where it defaults to 16).  To force	serialized behavior (useful if
	   the client is not prepared for out-of-order responses), set this to
	   1.

       --tls=off
       --tls=on
       --tls=require
	   Disable, enable or require TLS (authentication and encryption
	   support).  See nbdkit-tls(1).

       --tls-certificates /path/to/certificates
	   Set the path	to the TLS certificates	directory.  If not specified,
	   some	built-in paths are checked.  See nbdkit-tls(1) for more
	   details.

       --tls-psk /path/to/pskfile
	   Set the path	to the pre-shared keys (PSK) file.  If used, this
	   overrides certificate authentication.  There	is no built-in path.
	   See nbdkit-tls(1) for more details.

       --tls-verify-peer
	   Enables TLS client certificate verification.	 The default is	not to
	   check the client's certificate.

       -U SOCKET
       --unix SOCKET
       -U -
       --unix -
	   Accept connections on the Unix domain socket	"SOCKET" (which	is a
	   path).

	   nbdkit creates this socket, but it will probably have incorrect
	   permissions (too permissive).  If it	is a problem that some
	   unauthorized	user could connect to this socket between the time
	   that	nbdkit starts up and the authorized user connects, then	put
	   the socket into a directory that has	restrictive permissions.

	   nbdkit does not delete the socket file when it exits.  The caller
	   should delete the socket file after use (else if you	try to start
	   nbdkit up again you will get	an "Address already in use" error).

	   If the socket name is - then	nbdkit generates a randomly named
	   private socket.  This is useful with	"CAPTIVE NBDKIT" in
	   nbdkit-captive(1).

       -u USER
       --user USER
	   Change user to "USER" after starting	up.  A user name or numeric
	   user	ID can be used.

	   The server needs sufficient permissions to be able to do this.
	   Normally this would mean starting the server	up as root.

	   See also -g.

       -v
       --verbose
	   Enable verbose messages.

	   It's	a good idea to use -f as well so the process does not fork
	   into	the background (but not	required).

       -V
       --version
	   Print the version number of nbdkit and exit.

	   The --dump-config option provides separate major and	minor numbers
	   and may be easier to	parse from shell scripts.

       --vsock
	   Use the AF_VSOCK protocol (instead of TCP/IP).  You must use	this
	   in conjunction with -p/--port.  See "AF_VSOCK" in
	   nbdkit-service(1).

PLUGIN NAME
       You can give the	full path to the plugin, like this:

	nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]

       but it is usually more convenient to use	this equivalent	syntax:

	nbdkit file [...]

       $libdir is set at compile time.	To print it out, do:

	nbdkit --dump-config

PLUGIN CONFIGURATION
       After specifying	the plugin name	you can	(optionally, it	depends	on the
       plugin) give plugin configuration on the	command	line in	the form of
       "key=value".  For example:

	nbdkit file file=disk.img

       To list all the options supported by a plugin, do:

	nbdkit --help file

       To dump information about a plugin, do:

	nbdkit file --dump-plugin

   Magic parameters
       Some plugins declare a special "magic config key".  This	is a key which
       is assumed if no	"key=" part is present.	 For example:

	nbdkit file disk.img

       is assumed to be	"file=disk.img"	because	the file plugin	declares
       "file" as its magic config key.	There can be ambiguity in the parsing
       of magic	config keys if the value might look like a "key=value".	 If
       there could be ambiguity	then modify the	value, eg. by prefixing	it
       with "./"

       There is	also a special exception for plugins which do not declare a
       magic config key, but where the first plugin argument does not contain
       an '=' character: it is assumed to be "script=value".  This is used by
       scripting language plugins:

	nbdkit perl foo.pl [args...]

       has the same meaning as:

	nbdkit perl script=foo.pl [args...]

   Shebang scripts
       You can use "#!"	to run nbdkit plugins written in most scripting
       languages.  The file should be executable.  For example:

	#!/usr/sbin/nbdkit perl
	sub open {
	  # etc
	}

       (see nbdkit-perl-plugin(3) for a	full example).

SERVER DEBUG FLAGS
       As well as enabling or disabling	debugging in the server	using
       --verbose you can control extra debugging in the	server using the "-D
       nbdkit.*" flags listed in this section.	Note these flags are an
       internal	implementation detail of the server and	may be changed or
       removed at any time in the future.

       -D nbdkit.backend.controlpath=0
       -D nbdkit.backend.controlpath=1
       -D nbdkit.backend.datapath=0
       -D nbdkit.backend.datapath=1
	   These flags control the verbosity of	nbdkit backend debugging
	   messages (the ones which show every request processed by the
	   server).  The default for both settings is 1	(normal	debugging) but
	   you can set them to 0 to suppress these messages.

	   "-D nbdkit.backend.datapath=0" is the more useful setting which
	   lets	you suppress messages about pread, pwrite, zero, trim, etc.
	   commands.  When transferring	large amounts of data these messages
	   are numerous	and not	usually	very interesting.

	   "-D nbdkit.backend.controlpath=0" suppresses	the non-datapath
	   commands (config, open, close, can_write, etc.)

SIGNALS
       nbdkit responds to the following	signals:

       "SIGINT"
       "SIGQUIT"
       "SIGTERM"
	   The server exits cleanly.

       "SIGPIPE"
	   This	signal is ignored.

ENVIRONMENT VARIABLES
       "LISTEN_FDS"
       "LISTEN_PID"
	   If present in the environment when nbdkit starts up,	these trigger
	   "SOCKET ACTIVATION" in nbdkit-service(1).

SEE ALSO
   Other topics
       nbdkit-captive(1) a Run nbdkit under another process and	have it
       reliably	cleaned	up.

       nbdkit-loop(1) a	Use nbdkit with	the Linux kernel client	to create loop
       devices and loop	mounts.

       nbdkit-probing(1) a How to probe	for nbdkit configuration and plugins.

       nbdkit-protocol(1) a Which parts	of the NBD protocol nbdkit supports.

       nbdkit-security(1) a Lists past security	issues in nbdkit.

       nbdkit-service(1) a Running nbdkit as a service,	and systemd socket
       activation.

       nbdkit-tls(1) a Authentication and encryption of	NBD connections
       (sometimes incorrectly called "SSL").

   Plugins
       nbdkit-curl-plugin(1), nbdkit-data-plugin(1), nbdkit-eval-plugin(1),
       nbdkit-example1-plugin(1), nbdkit-example2-plugin(1),
       nbdkit-example3-plugin(1), nbdkit-example4-plugin(1),
       nbdkit-ext2-plugin(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1),
       nbdkit-full-plugin(1), nbdkit-guestfs-plugin(1),	nbdkit-gzip-plugin(1),
       nbdkit-info-plugin(1), nbdkit-iso-plugin(1), nbdkit-libvirt-plugin(1),
       nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
       nbdkit-nbd-plugin(1), nbdkit-null-plugin(1),
       nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1),
       nbdkit-random-plugin(1),	nbdkit-split-plugin(1),	nbdkit-ssh-plugin(1),
       nbdkit-streaming-plugin(1), nbdkit-tar-plugin(1),
       nbdkit-tmpdisk-plugin(1), nbdkit-vddk-plugin(1),	nbdkit-zero-plugin(1)
       ; nbdkit-golang-plugin(3), nbdkit-lua-plugin(3),
       nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
       nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
       nbdkit-tcl-plugin(3) .

   Filters
       nbdkit-blocksize-filter(1), nbdkit-cache-filter(1),
       nbdkit-cacheextents-filter(1), nbdkit-cow-filter(1),
       nbdkit-delay-filter(1), nbdkit-error-filter(1),
       nbdkit-exitlast-filter(1), nbdkit-ext2-filter(1),
       nbdkit-extentlist-filter(1), nbdkit-fua-filter(1), nbdkit-ip-filter(1),
       nbdkit-limit-filter(1), nbdkit-log-filter(1), nbdkit-nocache-filter(1),
       nbdkit-noextents-filter(1), nbdkit-nofilter-filter(1),
       nbdkit-noparallel-filter(1), nbdkit-nozero-filter(1),
       nbdkit-offset-filter(1),	nbdkit-partition-filter(1),
       nbdkit-rate-filter(1), nbdkit-readahead-filter(1),
       nbdkit-retry-filter(1), nbdkit-stats-filter(1),
       nbdkit-truncate-filter(1), nbdkit-xz-filter(1) .

   For developers
       nbdkit-plugin(3), nbdkit-filter(3).

   Writing plugins in other programming	languages
       nbdkit-golang-plugin(3),	nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3),
       nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3),
       nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3)	.

   Release notes for previous releases of nbdkit
       nbdkit-release-notes-1.4(1), nbdkit-release-notes-1.6(1),
       nbdkit-release-notes-1.8(1), nbdkit-release-notes-1.10(1),
       nbdkit-release-notes-1.12(1), nbdkit-release-notes-1.14(1),
       nbdkit-release-notes-1.16(1), nbdkit-release-notes-1.18(1),
       nbdkit-release-notes-1.20(1).

   NBD clients
       guestfish(1), libnbd(3),	nbd-client(1), nbdfuse(1), nbdsh(1), qemu(1).

   nbdkit links
       http://github.com/libguestfs/nbdkit a Source code.

   Other NBD servers
       qemu-nbd(1), nbd-server(1), https://bitbucket.org/hirofuchi/xnbd.

   Documentation for the NBD protocol
       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
       https://nbd.sourceforge.io/.

   Similar protocols
       https://en.wikipedia.org/wiki/iSCSI,
       https://en.wikipedia.org/wiki/ATA_over_Ethernet,
       https://en.wikipedia.org/wiki/Fibre_Channel_over_Ethernet.

   Other manual	pages of interest
       gnutls_priority_init(3),	qemu-img(1), psktool(1), systemd.socket(5).

AUTHORS
       Eric Blake

       Richard W.M. Jones

       Yann E. MORIN

       Nir Soffer

       Pino Toscano

COPYRIGHT
       Copyright (C) 2013-2020 Red Hat Inc.

LICENSE
       Redistribution and use in source	and binary forms, with or without
       modification, are permitted provided that the following conditions are
       met:

       o   Redistributions of source code must retain the above	copyright
	   notice, this	list of	conditions and the following disclaimer.

       o   Redistributions in binary form must reproduce the above copyright
	   notice, this	list of	conditions and the following disclaimer	in the
	   documentation and/or	other materials	provided with the
	   distribution.

       o   Neither the name of Red Hat nor the names of	its contributors may
	   be used to endorse or promote products derived from this software
	   without specific prior written permission.

       THIS SOFTWARE IS	PROVIDED BY RED	HAT AND	CONTRIBUTORS ''AS IS'' AND ANY
       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
       LIABLE FOR ANY DIRECT, INDIRECT,	INCIDENTAL, SPECIAL, EXEMPLARY,	OR
       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
       SUBSTITUTE GOODS	OR SERVICES; LOSS OF USE, DATA,	OR PROFITS; OR
       BUSINESS	INTERRUPTION) HOWEVER CAUSED AND ON ANY	THEORY OF LIABILITY,
       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE	USE OF THIS SOFTWARE, EVEN IF
       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nbdkit-1.20.4			  2021-03-01			     nbdkit(1)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | GLOBAL OPTIONS | PLUGIN NAME | PLUGIN CONFIGURATION | SERVER DEBUG FLAGS | SIGNALS | ENVIRONMENT VARIABLES | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nbdkit&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help