.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.38.2 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-protocol 1"
.TH nbdkit-protocol 1 2024-05-10 nbdkit-1.38.2 NBDKIT
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdkit\-protocol \- which parts of the NBD protocol nbdkit supports
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& nbdkit [\-n|\-\-newstyle] [\-\-mask\-handshake MASK] [\-\-no\-mc|\-\-no\-meta\-contexts]
\&        [\-\-no\-sr|\-\-no\-structured\-replies] [\-o|\-\-oldstyle] [...]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This page documents the level of support in nbdkit for various parts
of the NBD protocol.
.SH "NEW STYLE VS OLD STYLE PROTOCOL"
.IX Header "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.
.PP
nbdkit defaults to the newstyle protocol since nbdkit ≥ 1.3 (the
command line flag \fI\-n\fR or \fI\-\-newstyle\fR is ignored for backwards
compatibility with older versions).  The newstyle protocol is better
in every respect than the oldstyle protocol and you should prefer it
if possible.  The newstyle protocol also includes extensions where a
client may request structured replies for even more capabilities, such
as sparse reads or meta contexts for 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.
.PP
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.  The following options intentionally disable optional
parts of the NBD protocol, with successively larger impacts:
.IP \fB\-\-no\-mc\fR 4
.IX Item "--no-mc"
.PD 0
.IP \fB\-\-no\-meta\-contexts\fR 4
.IX Item "--no-meta-contexts"
.PD
Force the newstyle protocol to treat all requests for meta context
negotiation from the client as unsupported; the client will be unable
to query block status.  By default, nbdkit gracefully handles all meta
context requests, even though it currently supports only the
\&\f(CW\*(C`base:allocation\*(C'\fR context (possibly by synthesizing a context that
represents an all-data disk when the plugin lacks support for
extents); but treating meta contexts as unsupported is useful for
emulating nbd-server 3.25.
.IP \fB\-\-no\-sr\fR 4
.IX Item "--no-sr"
.PD 0
.IP \fB\-\-no\-structured\-replies\fR 4
.IX Item "--no-structured-replies"
.PD
Force the newstyle protocol to decline any client request for
structured replies; this is stronger than \fI\-\-no\-meta\-contexts\fR in
that it also disables the opportunity for sparse reads.  This is
useful for emulating nbd-server 3.24.
.IP \fB\-\-mask\-handshake=\fRMASK 4
.IX Item "--mask-handshake=MASK"
Alter the mask of which particular global features 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
\&\f(CW\*(C`NBD_OPT_EXPORT_NAME\*(C'\fR (incompatible with TLS, and includes all
effects of \fI\-\-no\-sr\fR); clearing bit 1 causes the handshake to send
more padding bytes in response to \f(CW\*(C`NBD_OPT_EXPORT_NAME\*(C'\fR.  Other bits
in the mask will only have an effect if the NBD protocol is extended
in the future to define other global bits.
.IP \fB\-o\fR 4
.IX Item "-o"
.PD 0
.IP \fB\-\-oldstyle\fR 4
.IX Item "--oldstyle"
.PD
Force the oldstyle protocol.  In this mode, \fI\-\-no\-meta\-contexts\fR,
\&\fI\-\-no\-sr\fR and \fI\-\-mask\-handshake\fR have no effect.
.SS "Common clients and the protocol they require"
.IX Subsection "Common clients and the protocol they require"
.Vb 12
\& 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
.Ve
.SS "Errors seen if using the wrong protocol"
.IX Subsection "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:
.PP
.Vb 1
\& Server requires an export name
.Ve
.PP
If you use qemu ≤ 2.5 with the exportname field against an
oldstyle server, it will give the error:
.PP
.Vb 1
\& Server does not support export names
.Ve
.PP
If you use the oldstyle protocol with nbd-client ≥ 3.10, it will
give the error:
.PP
.Vb 1
\& Error: It looks like you\*(Aqre trying to connect to an oldstyle server.
.Ve
.SS "NBD protocol and port number"
.IX Subsection "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.
.PP
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.
.SH "NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT"
.IX Header "NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT"
.IP "newstyle protocol" 4
.IX Item "newstyle protocol"
Supported in nbdkit ≥ 1.1.12, and the default in nbdkit ≥ 1.3.
.IP "export names" 4
.IX Item "export names"
Partially supported in nbdkit ≥ 1.1.12.  Support for plugins to
read the client export name added in nbdkit ≥ 1.15.2.
.Sp
Versions of nbdkit before 1.16 could advertise a single export name to
clients, via a now deprecated side effect of the \fI\-e\fR option.  In nbdkit
1.15.2, plugins could read the client requested export name using
\&\f(CWnbdkit_export_name()\fR and serve different content.  In nbdkit
1.21.22, plugins could implement \f(CW\*(C`.list_exports\*(C'\fR to answer
\&\f(CW\*(C`NBD_OPT_LIST\*(C'\fR queries.
.ie n .IP """NBD_FLAG_NO_ZEROES""" 4
.el .IP \f(CWNBD_FLAG_NO_ZEROES\fR 4
.IX Item "NBD_FLAG_NO_ZEROES"
Supported in nbdkit ≥ 1.1.13.
.Sp
This protocol optimization avoids sending a useless block of zero
bytes during protocol negotiation.
.ie n .IP """NBD_CMD_WRITE_ZEROES""" 4
.el .IP \f(CWNBD_CMD_WRITE_ZEROES\fR 4
.IX Item "NBD_CMD_WRITE_ZEROES"
Supported in nbdkit ≥ 1.1.13.
.IP "TLS with X.509 certificates" 4
.IX Item "TLS with X.509 certificates"
Supported in nbdkit ≥ 1.1.15.
.IP "TLS with Pre-Shared Keys (PSK)" 4
.IX Item "TLS with Pre-Shared Keys (PSK)"
Supported in nbdkit ≥ 1.4.0.
.ie n .IP """NBD_OPT_GO""" 4
.el .IP \f(CWNBD_OPT_GO\fR 4
.IX Item "NBD_OPT_GO"
Supported in nbdkit ≥ 1.5.3.
.Sp
This protocol enhancement allows the server to return errors when
negotiating the export name.
.ie n .IP """NBD_OPT_INFO""" 4
.el .IP \f(CWNBD_OPT_INFO\fR 4
.IX Item "NBD_OPT_INFO"
Supported in nbdkit ≥ 1.9.3.
.Sp
This protocol enhancement allows a client to inspect details about
the export without actually connecting.
.ie n .IP """NBD_FLAG_CAN_MULTI_CONN""" 4
.el .IP \f(CWNBD_FLAG_CAN_MULTI_CONN\fR 4
.IX Item "NBD_FLAG_CAN_MULTI_CONN"
Supported in nbdkit ≥ 1.9.9.
.IP "Structured Replies" 4
.IX Item "Structured Replies"
Supported in nbdkit ≥ 1.11.8.
.Sp
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.
.Sp
In nbdkit ≥ 1.13.9, the command-line option \fI\-\-no\-sr\fR can be used
to disable server support for structured replies, for testing client
fallbacks; disabling structured replies also disables features like
block status queries that depend on structured replies.
.IP "Metadata Querying" 4
.IX Item "Metadata Querying"
Supported in nbdkit ≥ 1.11.8.
.Sp
In nbdkit ≥ 1.37.9, the command-line option \fI\-\-no\-meta\-contexts\fR
can be used to disable server support for meta contexts, for testing
client fallbacks.
.IP "Block Status" 4
.IX Item "Block Status"
Supported in nbdkit ≥ 1.11.10.
.Sp
Only \f(CW\*(C`base:allocation\*(C'\fR (ie. querying which parts of an image are
sparse) is supported.
.Sp
Sparse reads (using \f(CW\*(C`NBD_REPLY_TYPE_OFFSET_HOLE\*(C'\fR are not directly
supported, but a client can use block status to infer which portions
of the export do not need to be read.
.ie n .IP """NBD_FLAG_DF""" 4
.el .IP \f(CWNBD_FLAG_DF\fR 4
.IX Item "NBD_FLAG_DF"
Supported in nbdkit ≥ 1.11.11.
.Sp
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.
.ie n .IP """NBD_CMD_CACHE""" 4
.el .IP \f(CWNBD_CMD_CACHE\fR 4
.IX Item "NBD_CMD_CACHE"
Supported in nbdkit ≥ 1.13.4.
.Sp
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.
.ie n .IP """NBD_CMD_FLAG_FAST_ZERO""" 4
.el .IP \f(CWNBD_CMD_FLAG_FAST_ZERO\fR 4
.IX Item "NBD_CMD_FLAG_FAST_ZERO"
Supported in nbdkit ≥ 1.15.0.
.Sp
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 \f(CW\*(C`ENOTSUP\*(C'\fR 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.
.ie n .IP """NBD_INFO_NAME"", ""NBD_INFO_DESCRIPTION""" 4
.el .IP "\f(CWNBD_INFO_NAME\fR, \f(CWNBD_INFO_DESCRIPTION\fR" 4
.IX Item "NBD_INFO_NAME, NBD_INFO_DESCRIPTION"
Supported in nbdkit ≥ 1.23.6.
.Sp
These protocol extensions allow a client to learn more information
about an export during \f(CW\*(C`NBD_OPT_GO\*(C'\fR.  The \f(CW\*(C`.default_export\*(C'\fR callback
can inform a client of a canonical non-empty name in place of the
default export \f(CW""\fR, and the \f(CW\*(C`.export_description\*(C'\fR callback can give
a client more details about the export.
.ie n .IP """NBD_INFO_BLOCK_SIZE""" 4
.el .IP \f(CWNBD_INFO_BLOCK_SIZE\fR 4
.IX Item "NBD_INFO_BLOCK_SIZE"
Supported in nbdkit ≥ 1.30.
.IP "Resize Extension" 4
.IX Item "Resize Extension"
\&\fINot supported\fR.
.IP "Extended Headers Extension" 4
.IX Item "Extended Headers Extension"
\&\fINot supported\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
https://nbd.sourceforge.io/.
.SH AUTHORS
.IX Header "AUTHORS"
Eric Blake
.PP
Richard W.M. Jones
.PP
Pino Toscano
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP \(bu 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP \(bu 4
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.
.IP \(bu 4
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.
.PP
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.