Provided by: nbdkit_1.16.2-1ubuntu3_amd64 
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 ≥ 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 ≤ 2.5 without the exportname field against a newstyle server, it will give the error:
Server requires an export name
If you use qemu ≤ 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 ≥ 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 ≥ 1.1.12, and the default in nbdkit ≥ 1.3.
export names
Supported in nbdkit ≥ 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 ≥ 1.1.13.
This protocol optimization avoids sending a useless block of zero bytes during protocol negotiation.
"NBD_CMD_WRITE_ZEROES"
Supported in nbdkit ≥ 1.1.13.
TLS with X.509 certificates
Supported in nbdkit ≥ 1.1.15.
TLS with Pre-Shared Keys (PSK)
Supported in nbdkit ≥ 1.4.0.
"NBD_OPT_GO"
Supported in nbdkit ≥ 1.5.3.
This protocol enhancement allows the server to return errors when negotiating the export name.
"NBD_OPT_INFO"
Supported in nbdkit ≥ 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 ≥ 1.9.9.
Structured Replies
Supported in nbdkit ≥ 1.11.8.
However we don’t expose the capability to send structured replies to plugins yet, nor do we send
human-readable error messages using this facility.
In nbdkit ≥ 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 ≥ 1.11.8.
Block Status
Supported in nbdkit ≥ 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 ≥ 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 ≥ 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 ≥ 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-2019 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:
• Redistributions of source code must retain the above copyright notice, this list of conditions and
the following disclaimer.
• 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.
• 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.16.2 2020-01-28 nbdkit-protocol(1)