nbdkit-protocol(1) NBDKIT nbdkit-protocol(1) NAME nbdkit-protocol - which parts of the NBD protocol nbdkit supports SYNOPSIS nbdkit [-n|--newstyle] [--mask-handshake MASK] [--no-mc|--no-meta-contexts] [--no-sr|--no-structured-replies] [-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 aY 1.3 (the command line flag -n or --newstyle 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 pro- tocol 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 adver- tised 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. The fol- lowing options intentionally disable optional parts of the NBD protocol, with successively larger impacts: --no-mc --no-meta-contexts Force the newstyle protocol to treat all requests for meta context ne- gotiation 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 "base:al- location" context (possibly by synthesizing a context that represents an all-data disk when the plugin lacks support for extents); but treat- ing meta contexts as unsupported is useful for emulating nbd-server 3.25. --no-sr --no-structured-replies Force the newstyle protocol to decline any client request for struc- tured replies; this is stronger than --no-meta-contexts in that it also disables the opportunity for sparse reads. This is useful for emulat- ing nbd-server 3.24. --mask-handshake=MASK Alter the mask of which particular global features are advertised dur- ing new-style handshake (defaulting to all supported bits set). Clear- ing bit 0 (the low order bit) limits a client to using just "NBD_OPT_EXPORT_NAME" (incompatible with TLS, and includes all effects of --no-sr); 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. -o --oldstyle Force the oldstyle protocol. In this mode, --no-meta-contexts, --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 re- quire 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 Partially supported in nbdkit aY 1.1.12. Support for plugins to read the client export name added in nbdkit aY 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 nbd- kit_export_name(3) 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 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 nego- tiating 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 fall- backs; disabling structured replies also disables features like block status queries that depend on structured replies. Metadata Querying Supported in nbdkit aY 1.11.8. In nbdkit aY 1.37.9, the command-line option --no-meta-contexts can be used to disable server support for meta contexts, for testing client fallbacks. 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 sup- ported, 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 un- til 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 in- tent to access a portion of the export, to allow the server an opportu- nity 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 re- quests still benefit from compressed network traffic regardless of the time taken. "NBD_INFO_NAME", "NBD_INFO_DESCRIPTION" Supported in nbdkit aY 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 de- fault export "", and the ".export_description" callback can give a client more details about the export. "NBD_INFO_BLOCK_SIZE" Supported in nbdkit aY 1.30. Resize Extension Not supported. Extended Headers Extension Not supported. EXPORT-SAFE FILTERS When a plugin supports NBD export names, it may serve different content (eg. different disk images) on each export. Some nbdkit filters do not work properly in this case. Filter Export safe? blocksize Yes blocksize-policy Yes bzip2 No cache No checkwrite Yes count Yes cow Yes, since 1.44 delay Yes error Yes evil Yes exitlast Yes exitwhen Yes exportname Yes ext2 No extentlist Not useful with exports fua Yes gzip No ip Yes limit Yes log Yes luks No lzip No multi-conn Yes nocache Yes noextents Yes nofilter Yes noparallel Yes nozero Yes offset Yes, but unlikely to be useful openonce Yes partition No pause Yes protect Yes, but unlikely to be useful qcow2dec No rate Yes readahead Yes, since 1.32 readonly Yes retry Yes retry-request Yes rotational Yes scan Yes spinning Yes stats Yes swab Yes tar No time-limit Yes tls-fallback Yes truncate Yes, but unlikely to be useful xz No SEE ALSO nbdkit(1), https://github.com/NetworkBlockDevice/nbd/blob/mas- ter/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 modifi- cation, 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 no- tice, this list of conditions and the following disclaimer in the docu- mentation 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 EX- PRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DIS- CLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DI- RECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SER- VICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABIL- ITY, 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 DAM- AGE. nbdkit-1.46.2 2026-08-30 nbdkit-protocol(1)
NAME | SYNOPSIS | DESCRIPTION | NEW STYLE VS OLD STYLE PROTOCOL | NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT | EXPORT-SAFE FILTERS | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nbdkit-protocol&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>