1nbdkit-protocol(1)                  NBDKIT                  nbdkit-protocol(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

13       This page documents the level of support in nbdkit for various parts of
14       the NBD protocol.
15

NEW STYLE VS OLD STYLE PROTOCOL

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
22       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
31       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
45       Use the -o or --oldstyle flag to force the oldstyle protocol.  In this
46       mode, --no-sr and --mask-handshake have no effect.
47
48   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
62   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
66        Server requires an export name
67
68       If you use qemu ≤ 2.5 with the exportname field against an oldstyle
69       server, it will give the error:
70
71        Server does not support export names
72
73       If you use the oldstyle protocol with nbd-client ≥ 3.10, it will give
74       the error:
75
76        Error: It looks like you're trying to connect to an oldstyle server.
77
78   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
82       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

NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT

88       newstyle protocol
89           Supported in nbdkit ≥ 1.1.12, and the default in nbdkit ≥ 1.3.
90
91       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
95           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
102       "NBD_FLAG_NO_ZEROES"
103           Supported in nbdkit ≥ 1.1.13.
104
105           This protocol optimization avoids sending a useless block of zero
106           bytes during protocol negotiation.
107
108       "NBD_CMD_WRITE_ZEROES"
109           Supported in nbdkit ≥ 1.1.13.
110
111       TLS with X.509 certificates
112           Supported in nbdkit ≥ 1.1.15.
113
114       TLS with Pre-Shared Keys (PSK)
115           Supported in nbdkit ≥ 1.4.0.
116
117       "NBD_OPT_GO"
118           Supported in nbdkit ≥ 1.5.3.
119
120           This protocol enhancement allows the server to return errors when
121           negotiating the export name.
122
123       "NBD_OPT_INFO"
124           Supported in nbdkit ≥ 1.9.3.
125
126           This protocol enhancement allows a client to inspect details about
127           the export without actually connecting.
128
129       "NBD_FLAG_CAN_MULTI_CONN"
130           Supported in nbdkit ≥ 1.9.9.
131
132       Structured Replies
133           Supported in nbdkit ≥ 1.11.8.
134
135           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
139           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
143       Metadata Querying
144           Supported in nbdkit ≥ 1.11.8.
145
146       Block Status
147           Supported in nbdkit ≥ 1.11.10.
148
149           Only "base:allocation" (ie. querying which parts of an image are
150           sparse) is supported.
151
152           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
156       "NBD_FLAG_DF"
157           Supported in nbdkit ≥ 1.11.11.
158
159           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
164       "NBD_CMD_CACHE"
165           Supported in nbdkit ≥ 1.13.4.
166
167           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
171       "NBD_CMD_FLAG_FAST_ZERO"
172           Supported in nbdkit ≥ 1.15.0.
173
174           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
181       "NBD_INFO_NAME", "NBD_INFO_DESCRIPTION"
182           Supported in nbdkit ≥ 1.23.6.
183
184           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
190       "NBD_INFO_BLOCK_SIZE"
191           Supported in nbdkit ≥ 1.30.
192
193       Resize Extension
194           Not supported.
195

SEE ALSO

197       nbdkit(1),
198       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
199       https://nbd.sourceforge.io/.
200

AUTHORS

202       Eric Blake
203
204       Richard W.M. Jones
205
206       Pino Toscano
207
209       Copyright Red Hat
210

LICENSE

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
216       •   Redistributions of source code must retain the above copyright
217           notice, this list of conditions and the following disclaimer.
218
219       •   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
224       •   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
228       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.
239
240
241
242nbdkit-1.36.2                     2023-11-26                nbdkit-protocol(1)
Impressum