Skip to content

Latest commit

 

History

History
239 lines (158 loc) · 7.46 KB

nbdkit-protocol.pod

File metadata and controls

239 lines (158 loc) · 7.46 KB
Raw

NAME

nbdkit - 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 (C) 2013-2020 Red Hat Inc.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 152:

Non-ASCII character seen before =encoding in 'don’t'. Assuming UTF-8