1nbdkit-protocol(1) NBDKIT nbdkit-protocol(1)
2
6 nbdkit - which parts of the NBD protocol nbdkit supports
7
9 nbdkit [-n|--newstyle] [--mask-handshake MASK] [--no-sr] [-o|--oldstyle]
10 [-e|--exportname EXPORTNAME] [...]
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 Use the -e or --exportname flag to set the optional exportname for the
32 newstyle protocol.
33 Nbdkit also includes some options that are useful mainly when
35 performing integration tests, for proving whether clients have sane
36 fallback behavior when dealing various older servers permitted by the
37 NBD protocol. Use the --no-sr flag to force the newstyle protocol to
38 decline any client request for structured replies. Use the
39 --mask-handshake parameter to mask off particular global features which
40 are advertised during new-style handshake (defaulting to all supported
41 bits set). Clearing bit 0 (the low order bit) limits a client to using
42 just "NBD_OPT_EXPORT_NAME" (and is incompatible with TLS or structured
43 replies); clearing bit 1 causes the handshake to send more padding
44 bytes in response to "NBD_OPT_EXPORT_NAME". Other bits in the mask
45 will only have an effect if the NBD protocol is extended in the future
46 to define other global bits.
47 Use the -o or --oldstyle flag to force the oldstyle protocol. In this
49 mode, --no-sr and --mask-handshake have no effect.
50 Common clients and the protocol they require
52 Client Protocol
53 ------------------------------------------------------------
54 qemu <= 2.5 without exportname oldstyle
55 qemu <= 2.5 with exportname newstyle
56 qemu >= 2.6 client can talk either protocol
57 qemu >= 2.11 client tries structured replies
58 nbd-client < 3.10 client can talk either protocol
59 nbd-client >= 3.10 newstyle, no structured replies
60 any TLS (encrypted) client newstyle
61 nbdkit nbd plugin client can talk either protocol
62 nbdkit >= 1.13.3 nbd plugin tries structured replies
63 libnbd either protocol, tries structured replies
64 Errors seen if using the wrong protocol
66 If you use qemu ≤ 2.5 without the exportname field against a newstyle
67 server, it will give the error:
68 Server requires an export name
70 If you use qemu ≤ 2.5 with the exportname field against an oldstyle
72 server, it will give the error:
73 Server does not support export names
75 If you use the oldstyle protocol with nbd-client ≥ 3.10, it will give
77 the error:
78 Error: It looks like you're trying to connect to an oldstyle server.
80 NBD protocol and port number
82 Port 10809/tcp is reserved by IANA for the NBD protocol, but you can
83 use nbdkit on any port or on Unix domain sockets.
84 The NBD protocol specification claims that you should always use
86 newstyle when using port 10809, and use oldstyle on all other ports,
87 but this claim is not based on the reality of what NBD servers do, and
88 nbdkit does not require or encourage this.
89
91 newstyle protocol
92 Supported in nbdkit ≥ 1.1.12, and the default in nbdkit ≥ 1.3.
93 export names
95 Supported in nbdkit ≥ 1.1.12.
96 nbdkit can advertise an export name, but ignores any export name
98 sent by the client. nbdkit does not support serving different data
99 on different export names.
100 "NBD_FLAG_NO_ZEROES"
102 Supported in nbdkit ≥ 1.1.13.
103 This protocol optimization avoids sending a useless block of zero
105 bytes during protocol negotiation.
106 "NBD_CMD_WRITE_ZEROES"
108 Supported in nbdkit ≥ 1.1.13.
109 TLS with X.509 certificates
111 Supported in nbdkit ≥ 1.1.15.
112 TLS with Pre-Shared Keys (PSK)
114 Supported in nbdkit ≥ 1.4.0.
115 "NBD_OPT_GO"
117 Supported in nbdkit ≥ 1.5.3.
118 This protocol enhancement allows the server to return errors when
120 negotiating the export name.
121 "NBD_OPT_INFO"
123 Supported in nbdkit ≥ 1.9.3.
124 This protocol enhancement allows a client to inspect details about
126 the export without actually connecting.
127 "NBD_FLAG_CAN_MULTI_CONN"
129 Supported in nbdkit ≥ 1.9.9.
130 Structured Replies
132 Supported in nbdkit ≥ 1.11.8.
133 However we don’t expose the capability to send structured replies
135 to plugins yet, nor do we send human-readable error messages using
136 this facility.
137 In nbdkit ≥ 1.13.9>, the command-line option --no-sr can be used to
139 disable server support for structured replies, for testing client
140 fallbacks.
141 Metadata Querying
143 Supported in nbdkit ≥ 1.11.8.
144 Block Status
146 Supported in nbdkit ≥ 1.11.10.
147 Only "base:allocation" (ie. querying which parts of an image are
149 sparse) is supported.
150 Sparse reads (using "NBD_REPLY_TYPE_OFFSET_HOLE" are not directly
152 supported, but a client can use block status to infer which
153 portions of the export do not need to be read.
154 "NBD_FLAG_DF"
156 Supported in nbdkit ≥ 1.11.11.
157 This protocol extension allows a client to force an all-or-none
159 read when structured replies are in effect. However, the flag is a
160 no-op until we extend the plugin API to allow a fragmented read in
161 the first place.
162 "NBD_CMD_CACHE"
164 Supported in nbdkit ≥ 1.13.4.
165 This protocol extension allows a client to inform the server about
167 intent to access a portion of the export, to allow the server an
168 opportunity to cache things appropriately.
169 "NBD_CMD_FLAG_FAST_ZERO"
171 Supported in nbdkit ≥ 1.15.0.
172 This protocol extension allows a server to advertise that it can
174 rank all zero requests as fast or slow, at which point the client
175 can make fast zero requests which fail immediately with "ENOTSUP"
176 if the request is no faster than a counterpart write would be,
177 while normal zero requests still benefit from compressed network
178 traffic regardless of the time taken.
179 Resize Extension
181 Not supported.
182
184 nbdkit(1),
185 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
186 https://nbd.sourceforge.io/.
187
189 Eric Blake
190 Richard W.M. Jones
192 Pino Toscano
194
196 Copyright (C) 2013-2019 Red Hat Inc.
197
199 Redistribution and use in source and binary forms, with or without
200 modification, are permitted provided that the following conditions are
201 met:
202 · Redistributions of source code must retain the above copyright
204 notice, this list of conditions and the following disclaimer.
205 · Redistributions in binary form must reproduce the above copyright
207 notice, this list of conditions and the following disclaimer in the
208 documentation and/or other materials provided with the
209 distribution.
210 · Neither the name of Red Hat nor the names of its contributors may
212 be used to endorse or promote products derived from this software
213 without specific prior written permission.
214 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
216 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
217 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
218 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
219 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
220 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
221 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
222 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
223 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
224 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
225 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
226nbdkit-1.16.1 2019-12-03 nbdkit-protocol(1)