1nbdkit-protocol(1) NBDKIT nbdkit-protocol(1)
2
6 nbdkit - which parts of the NBD protocol nbdkit supports
7
9 nbdkit [-n|--newstyle] [-o|--oldstyle] [-e|--exportname EXPORTNAME]
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.
25 Use the -e or --exportname flag to set the optional exportname for the
27 newstyle protocol.
28 Use the -o or --oldstyle flag to force the oldstyle protocol.
30 Common clients and the protocol they require
32 Client Protocol
33 ------------------------------------------------------------
34 qemu <= 2.5 without exportname oldstyle
35 qemu <= 2.5 with exportname newstyle
36 qemu >= 2.6 client can talk either protocol
37 nbd-client < 3.10 client can talk either protocol
38 nbd-client >= 3.10 newstyle
39 any TLS (encrypted) client newstyle
40 nbdkit nbd plugin client can talk either protocol
41 Errors seen if using the wrong protocol
43 If you use qemu ≤ 2.5 without the exportname field against a newstyle
44 server, it will give the error:
45 Server requires an export name
47 If you use qemu ≤ 2.5 with the exportname field against an oldstyle
49 server, it will give the error:
50 Server does not support export names
52 If you use the oldstyle protocol with nbd-client ≥ 3.10, it will give
54 the error:
55 Error: It looks like you're trying to connect to an oldstyle server.
57 NBD protocol and port number
59 Port 10809/tcp is reserved by IANA for the NBD protocol, but you can
60 use nbdkit on any port or on Unix domain sockets.
61 The NBD protocol specification claims that you should always use
63 newstyle when using port 10809, and use oldstyle on all other ports,
64 but this claim is not based on the reality of what NBD servers do, and
65 nbdkit does not require or encourage this.
66
68 newstyle protocol
69 Supported in nbdkit ≥ 1.1.12, and the default in nbdkit ≥ 1.3.
70 export names
72 Supported in nbdkit ≥ 1.1.12.
73 nbdkit can advertise an export name, but ignores any export name
75 sent by the client. nbdkit does not support serving different data
76 on different export names.
77 "NBD_FLAG_NO_ZEROES"
79 Supported in nbdkit ≥ 1.1.13.
80 This protocol optimization avoids sending a useless block of zero
82 bytes during protocol negotiation.
83 "NBD_CMD_WRITE_ZEROES"
85 Supported in nbdkit ≥ 1.1.13.
86 TLS with X.509 certificates
88 Supported in nbdkit ≥ 1.1.15.
89 TLS with Pre-Shared Keys (PSK)
91 Supported in nbdkit ≥ 1.4.0.
92 "NBD_OPT_GO"
94 Supported in nbdkit ≥ 1.5.3.
95 This protocol enhancement allows the server to return errors when
97 negotiating the export name.
98 "NBD_OPT_INFO"
100 Supported in nbdkit ≥ 1.9.3.
101 This protocol enhancement allows a client to inspect details about
103 the export without actually connecting.
104 "NBD_FLAG_CAN_MULTI_CONN"
106 Supported in nbdkit ≥ 1.9.9.
107 Structured Replies
109 Supported in nbdkit ≥ 1.11.8.
110 However we don’t expose the capability to send structured replies
112 to plugins yet, nor do we send human-readable error messages using
113 this facility.
114 Metadata Querying
116 Supported in nbdkit ≥ 1.11.8.
117 Block Status
119 Supported in nbdkit ≥ 1.11.10.
120 Only "base:allocation" (ie. querying which parts of an image are
122 sparse) is supported.
123 Sparse reads (using "NBD_REPLY_TYPE_OFFSET_HOLE" are not directly
125 supported, but a client can use block status to infer which
126 portions of the export do not need to be read.
127 "NBD_FLAG_DF"
129 Supported in nbdkit ≥ 1.11.11.
130 This protocol extension allows a client to force an all-or-none
132 read when structured replies are in effect. However, the flag is a
133 no-op until we extend the plugin API to allow a fragmented read in
134 the first place.
135 Resize Extension
137 Not supported.
138
140 nbdkit(1),
141 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
142 https://nbd.sourceforge.io/.
143
145 Eric Blake
146 Richard W.M. Jones
148 Pino Toscano
150
152 Copyright (C) 2013-2018 Red Hat Inc.
153
155 Redistribution and use in source and binary forms, with or without
156 modification, are permitted provided that the following conditions are
157 met:
158 · Redistributions of source code must retain the above copyright
160 notice, this list of conditions and the following disclaimer.
161 · Redistributions in binary form must reproduce the above copyright
163 notice, this list of conditions and the following disclaimer in the
164 documentation and/or other materials provided with the
165 distribution.
166 · Neither the name of Red Hat nor the names of its contributors may
168 be used to endorse or promote products derived from this software
169 without specific prior written permission.
170 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
172 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
173 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
174 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
175 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
176 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
177 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
178 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
179 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
180 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
181 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
182nbdkit-1.12.3 2019-05-22 nbdkit-protocol(1)