1nbdkit-protocol(1) NBDKIT nbdkit-protocol(1)
2
6 nbdkit-protocol - which parts of the NBD protocol nbdkit supports
7
9 nbdkit [-n|--newstyle] [--mask-handshake MASK] [--no-sr] [-o|--oldstyle]
10 [...]
11
13 This page documents the level of support in nbdkit for various parts of
14 the NBD protocol.
15
17 The NBD protocol comes in two incompatible forms that we call
18 "oldstyle" and "newstyle". Unfortunately which protocol you should use
19 depends on the client and cannot be known in advance, nor can it be
20 negotiated from the server side.
21 nbdkit defaults to the newstyle protocol since nbdkit ≥ 1.3. The
23 newstyle protocol is better in every respect than the oldstyle protocol
24 and you should prefer it if possible. The newstyle protocol also
25 includes an extension where a client may request structured replies for
26 even more capabilities, such as sparse reads or obtaining block status.
27 By default, nbdkit advertises as many features as it can support (in
28 some cases, this can be limited by what callbacks the plugin handles),
29 even if the client does not negotiate to use all advertised features.
30 Nbdkit also includes some options that are useful mainly when
32 performing integration tests, for proving whether clients have sane
33 fallback behavior when dealing various older servers permitted by the
34 NBD protocol. Use the --no-sr flag to force the newstyle protocol to
35 decline any client request for structured replies. Use the
36 --mask-handshake parameter to mask off particular global features which
37 are advertised during new-style handshake (defaulting to all supported
38 bits set). Clearing bit 0 (the low order bit) limits a client to using
39 just "NBD_OPT_EXPORT_NAME" (and is incompatible with TLS or structured
40 replies); clearing bit 1 causes the handshake to send more padding
41 bytes in response to "NBD_OPT_EXPORT_NAME". Other bits in the mask
42 will only have an effect if the NBD protocol is extended in the future
43 to define other global bits.
44 Use the -o or --oldstyle flag to force the oldstyle protocol. In this
46 mode, --no-sr and --mask-handshake have no effect.
47 Common clients and the protocol they require
49 Client Protocol
50 ------------------------------------------------------------
51 qemu <= 2.5 without exportname oldstyle
52 qemu <= 2.5 with exportname newstyle
53 qemu >= 2.6 client can talk either protocol
54 qemu >= 2.11 client tries structured replies
55 nbd-client < 3.10 client can talk either protocol
56 nbd-client >= 3.10 newstyle, no structured replies
57 any TLS (encrypted) client newstyle
58 nbdkit nbd plugin client can talk either protocol
59 nbdkit >= 1.13.3 nbd plugin tries structured replies
60 libnbd either protocol, tries structured replies
61 Errors seen if using the wrong protocol
63 If you use qemu ≤ 2.5 without the exportname field against a newstyle
64 server, it will give the error:
65 Server requires an export name
67 If you use qemu ≤ 2.5 with the exportname field against an oldstyle
69 server, it will give the error:
70 Server does not support export names
72 If you use the oldstyle protocol with nbd-client ≥ 3.10, it will give
74 the error:
75 Error: It looks like you're trying to connect to an oldstyle server.
77 NBD protocol and port number
79 Port 10809/tcp is reserved by IANA for the NBD protocol, but you can
80 use nbdkit on any port or on Unix domain sockets.
81 The NBD protocol specification claims that you should always use
83 newstyle when using port 10809, and use oldstyle on all other ports,
84 but this claim is not based on the reality of what NBD servers do, and
85 nbdkit does not require or encourage this.
86
88 newstyle protocol
89 Supported in nbdkit ≥ 1.1.12, and the default in nbdkit ≥ 1.3.
90 export names
92 Partially supported in nbdkit ≥ 1.1.12. Support for plugins to
93 read the client export name added in nbdkit ≥ 1.15.2.
94 Versions of nbdkit before 1.16 could advertise a single export name
96 to clients, via a now deprecated side effect of the -e option. In
97 nbdkit 1.15.2, plugins could read the client requested export name
98 using nbdkit_export_name() and serve different content. In nbdkit
99 1.21.22, plugins could implement ".list_exports" to answer
100 "NBD_OPT_LIST" queries.
101 "NBD_FLAG_NO_ZEROES"
103 Supported in nbdkit ≥ 1.1.13.
104 This protocol optimization avoids sending a useless block of zero
106 bytes during protocol negotiation.
107 "NBD_CMD_WRITE_ZEROES"
109 Supported in nbdkit ≥ 1.1.13.
110 TLS with X.509 certificates
112 Supported in nbdkit ≥ 1.1.15.
113 TLS with Pre-Shared Keys (PSK)
115 Supported in nbdkit ≥ 1.4.0.
116 "NBD_OPT_GO"
118 Supported in nbdkit ≥ 1.5.3.
119 This protocol enhancement allows the server to return errors when
121 negotiating the export name.
122 "NBD_OPT_INFO"
124 Supported in nbdkit ≥ 1.9.3.
125 This protocol enhancement allows a client to inspect details about
127 the export without actually connecting.
128 "NBD_FLAG_CAN_MULTI_CONN"
130 Supported in nbdkit ≥ 1.9.9.
131 Structured Replies
133 Supported in nbdkit ≥ 1.11.8.
134 However we don’t expose the capability to send structured replies
136 to plugins yet, nor do we send human-readable error messages using
137 this facility.
138 In nbdkit ≥ 1.13.9, the command-line option --no-sr can be used to
140 disable server support for structured replies, for testing client
141 fallbacks.
142 Metadata Querying
144 Supported in nbdkit ≥ 1.11.8.
145 Block Status
147 Supported in nbdkit ≥ 1.11.10.
148 Only "base:allocation" (ie. querying which parts of an image are
150 sparse) is supported.
151 Sparse reads (using "NBD_REPLY_TYPE_OFFSET_HOLE" are not directly
153 supported, but a client can use block status to infer which
154 portions of the export do not need to be read.
155 "NBD_FLAG_DF"
157 Supported in nbdkit ≥ 1.11.11.
158 This protocol extension allows a client to force an all-or-none
160 read when structured replies are in effect. However, the flag is a
161 no-op until we extend the plugin API to allow a fragmented read in
162 the first place.
163 "NBD_CMD_CACHE"
165 Supported in nbdkit ≥ 1.13.4.
166 This protocol extension allows a client to inform the server about
168 intent to access a portion of the export, to allow the server an
169 opportunity to cache things appropriately.
170 "NBD_CMD_FLAG_FAST_ZERO"
172 Supported in nbdkit ≥ 1.15.0.
173 This protocol extension allows a server to advertise that it can
175 rank all zero requests as fast or slow, at which point the client
176 can make fast zero requests which fail immediately with "ENOTSUP"
177 if the request is no faster than a counterpart write would be,
178 while normal zero requests still benefit from compressed network
179 traffic regardless of the time taken.
180 "NBD_INFO_NAME", "NBD_INFO_DESCRIPTION"
182 Supported in nbdkit ≥ 1.23.6.
183 These protocol extensions allow a client to learn more information
185 about an export during "NBD_OPT_GO". The ".default_export"
186 callback can inform a client of a canonical non-empty name in place
187 of the default export "", and the ".export_description" callback
188 can give a client more details about the export.
189 "NBD_INFO_BLOCK_SIZE"
191 Supported in nbdkit ≥ 1.30.
192 Resize Extension
194 Not supported.
195
197 nbdkit(1),
198 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
199 https://nbd.sourceforge.io/.
200
202 Eric Blake
203 Richard W.M. Jones
205 Pino Toscano
207
209 Copyright Red Hat
210
212 Redistribution and use in source and binary forms, with or without
213 modification, are permitted provided that the following conditions are
214 met:
215 • Redistributions of source code must retain the above copyright
217 notice, this list of conditions and the following disclaimer.
218 • Redistributions in binary form must reproduce the above copyright
220 notice, this list of conditions and the following disclaimer in the
221 documentation and/or other materials provided with the
222 distribution.
223 • Neither the name of Red Hat nor the names of its contributors may
225 be used to endorse or promote products derived from this software
226 without specific prior written permission.
227 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
229 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
230 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
231 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
232 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
233 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
234 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
235 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
236 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
237 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
238 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
239nbdkit-1.36.2 2023-11-26 nbdkit-protocol(1)