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

NAME

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

SYNOPSIS

9        nbdkit [-n|--newstyle] [--mask-handshake MASK] [--no-sr] [-o|--oldstyle]
10               [-e|--exportname EXPORTNAME] [...]
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       Use the -e or --exportname flag to set the optional exportname for the
32       newstyle protocol.
33
34       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
48       Use the -o or --oldstyle flag to force the oldstyle protocol.  In this
49       mode, --no-sr and --mask-handshake have no effect.
50
51   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
65   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
69        Server requires an export name
70
71       If you use qemu ≤ 2.5 with the exportname field against an oldstyle
72       server, it will give the error:
73
74        Server does not support export names
75
76       If you use the oldstyle protocol with nbd-client ≥ 3.10, it will give
77       the error:
78
79        Error: It looks like you're trying to connect to an oldstyle server.
80
81   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
85       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

NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT

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

SEE ALSO

184       nbdkit(1),
185       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
186       https://nbd.sourceforge.io/.
187

AUTHORS

189       Eric Blake
190
191       Richard W.M. Jones
192
193       Pino Toscano
194
196       Copyright (C) 2013-2019 Red Hat Inc.
197

LICENSE

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
203       ·   Redistributions of source code must retain the above copyright
204           notice, this list of conditions and the following disclaimer.
205
206       ·   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
211       ·   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
215       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.
226
227
228
229nbdkit-1.16.1                     2019-12-03                nbdkit-protocol(1)
Impressum