Provided by: nbdkit_1.36.3-1ubuntu10_amd64 bug

NAME

       nbdkit-protocol - which parts of the NBD protocol nbdkit supports

SYNOPSIS

        nbdkit [-n|--newstyle] [--mask-handshake MASK] [--no-sr] [-o|--oldstyle]
               [...]

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.

       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
           Partially supported in nbdkit ≥ 1.1.12.  Support for plugins to read the client export
           name added in nbdkit ≥ 1.15.2.

           Versions of nbdkit before 1.16 could advertise a single export name to clients, via a
           now deprecated side effect of the -e option.  In nbdkit 1.15.2, plugins could read the
           client requested export name using nbdkit_export_name() and serve different content.
           In nbdkit 1.21.22, plugins could implement ".list_exports" to answer "NBD_OPT_LIST"
           queries.

       "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.

       "NBD_INFO_NAME", "NBD_INFO_DESCRIPTION"
           Supported in nbdkit ≥ 1.23.6.

           These protocol extensions allow a client to learn more information about an export
           during "NBD_OPT_GO".  The ".default_export" callback can inform a client of a
           canonical non-empty name in place of the default export "", and the
           ".export_description" callback can give a client more details about the export.

       "NBD_INFO_BLOCK_SIZE"
           Supported in nbdkit ≥ 1.30.

       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 Red Hat

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.