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

FreeBSD Manual Pages

  
 
  

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

NAME
       nbdkit -	which parts of the NBD protocol	nbdkit supports

SYNOPSIS
	nbdkit [-n|--newstyle] [--mask-handshake MASK] [--no-sr] [-o|--oldstyle]
	       [-e|--exportname	EXPORTNAME] [...]

DESCRIPTION
       This page documents the level of	support	in nbdkit for various parts of
       the NBD protocol.

NEW STYLE VS OLD STYLE PROTOCOL
       The NBD protocol	comes in two incompatible forms	that we	call
       "oldstyle" and "newstyle".  Unfortunately which protocol	you should use
       depends on the client and cannot	be known in advance, nor can it	be
       negotiated from the server side.

       nbdkit defaults to the newstyle protocol	since nbdkit aY	1.3.  The
       newstyle	protocol is better in every respect than the oldstyle protocol
       and you should prefer it	if possible.  The newstyle protocol also
       includes	an extension where a client may	request	structured replies for
       even more capabilities, such as sparse reads or obtaining block status.
       By default, nbdkit advertises as	many features as it can	support	(in
       some cases, this	can be limited by what callbacks the plugin handles),
       even if the client does not negotiate to	use all	advertised features.

       Use the -e or --exportname flag to set the optional exportname for the
       newstyle	protocol.

       Nbdkit also includes some options that are useful mainly	when
       performing integration tests, for proving whether clients have sane
       fallback	behavior when dealing various older servers permitted by the
       NBD protocol.  Use the --no-sr flag to force the	newstyle protocol to
       decline any client request for structured replies.  Use the
       --mask-handshake	parameter to mask off particular global	features which
       are advertised during new-style handshake (defaulting to	all supported
       bits set).  Clearing bit	0 (the low order bit) limits a client to using
       just "NBD_OPT_EXPORT_NAME" (and is incompatible with TLS	or structured
       replies); clearing bit 1	causes the handshake to	send more padding
       bytes in	response to "NBD_OPT_EXPORT_NAME".  Other bits in the mask
       will only have an effect	if the NBD protocol is extended	in the future
       to define other global bits.

       Use the -o or --oldstyle	flag to	force the oldstyle protocol.  In this
       mode, --no-sr and --mask-handshake have no effect.

   Common clients and the protocol they	require
	Client				Protocol
	------------------------------------------------------------
	qemu <=	2.5 without exportname	oldstyle
	qemu <=	2.5 with exportname	newstyle
	qemu >=	2.6			client can talk	either protocol
	qemu >=	2.11			client tries structured	replies
	nbd-client < 3.10		client can talk	either protocol
	nbd-client >= 3.10		newstyle, no structured	replies
	any TLS	(encrypted) client	newstyle
	nbdkit nbd plugin		client can talk	either protocol
	nbdkit >= 1.13.3		nbd plugin tries structured replies
	libnbd				either protocol, tries structured replies

   Errors seen if using	the wrong protocol
       If you use qemu ax 2.5 without the exportname field against a newstyle
       server, it will give the	error:

	Server requires	an export name

       If you use qemu ax 2.5 with the exportname field	against	an oldstyle
       server, it will give the	error:

	Server does not	support	export names

       If you use the oldstyle protocol	with nbd-client	aY 3.10, it will give
       the error:

	Error: It looks	like you're trying to connect to an oldstyle server.

   NBD protocol	and port number
       Port 10809/tcp is reserved by IANA for the NBD protocol,	but you	can
       use nbdkit on any port or on Unix domain	sockets.

       The NBD protocol	specification claims that you should always use
       newstyle	when using port	10809, and use oldstyle	on all other ports,
       but this	claim is not based on the reality of what NBD servers do, and
       nbdkit does not require or encourage this.

NBD PROTOCOL FEATURES SUPPORTED	BY NBDKIT
       newstyle	protocol
	   Supported in	nbdkit aY 1.1.12, and the default in nbdkit aY 1.3.

       export names
	   Supported in	nbdkit aY 1.1.12.

	   nbdkit can advertise	an export name,	but ignores any	export name
	   sent	by the client.	nbdkit does not	support	serving	different data
	   on different	export names.

       "NBD_FLAG_NO_ZEROES"
	   Supported in	nbdkit aY 1.1.13.

	   This	protocol optimization avoids sending a useless block of	zero
	   bytes during	protocol negotiation.

       "NBD_CMD_WRITE_ZEROES"
	   Supported in	nbdkit aY 1.1.13.

       TLS with	X.509 certificates
	   Supported in	nbdkit aY 1.1.15.

       TLS with	Pre-Shared Keys	(PSK)
	   Supported in	nbdkit aY 1.4.0.

       "NBD_OPT_GO"
	   Supported in	nbdkit aY 1.5.3.

	   This	protocol enhancement allows the	server to return errors	when
	   negotiating the export name.

       "NBD_OPT_INFO"
	   Supported in	nbdkit aY 1.9.3.

	   This	protocol enhancement allows a client to	inspect	details	about
	   the export without actually connecting.

       "NBD_FLAG_CAN_MULTI_CONN"
	   Supported in	nbdkit aY 1.9.9.

       Structured Replies
	   Supported in	nbdkit aY 1.11.8.

	   However we donat expose the capability to send structured replies
	   to plugins yet, nor do we send human-readable error messages	using
	   this	facility.

	   In nbdkit aY	1.13.9>, the command-line option --no-sr can be	used
	   to disable server support for structured replies, for testing
	   client fallbacks.

       Metadata	Querying
	   Supported in	nbdkit aY 1.11.8.

       Block Status
	   Supported in	nbdkit aY 1.11.10.

	   Only	"base:allocation" (ie. querying	which parts of an image	are
	   sparse) is supported.

	   Sparse reads	(using "NBD_REPLY_TYPE_OFFSET_HOLE" are	not directly
	   supported, but a client can use block status	to infer which
	   portions of the export do not need to be read.

       "NBD_FLAG_DF"
	   Supported in	nbdkit aY 1.11.11.

	   This	protocol extension allows a client to force an all-or-none
	   read	when structured	replies	are in effect. However,	the flag is a
	   no-op until we extend the plugin API	to allow a fragmented read in
	   the first place.

       "NBD_CMD_CACHE"
	   Supported in	nbdkit aY 1.13.4.

	   This	protocol extension allows a client to inform the server	about
	   intent to access a portion of the export, to	allow the server an
	   opportunity to cache	things appropriately.

       "NBD_CMD_FLAG_FAST_ZERO"
	   Supported in	nbdkit aY 1.15.0.

	   This	protocol extension allows a server to advertise	that it	can
	   rank	all zero requests as fast or slow, at which point the client
	   can make fast zero requests which fail immediately with "ENOTSUP"
	   if the request is no	faster than a counterpart write	would be,
	   while normal	zero requests still benefit from compressed network
	   traffic regardless of the time taken.

       Resize Extension
	   Not supported.

SEE ALSO
       nbdkit(1),
       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
       https://nbd.sourceforge.io/.

AUTHORS
       Eric Blake

       Richard W.M. Jones

       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-09-21		    nbdkit-protocol(1)

NAME | SYNOPSIS | DESCRIPTION | NEW STYLE VS OLD STYLE PROTOCOL | NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

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

home | help