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] [-o|--oldstyle] [-e|--exportname EXPORTNAME]
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.
25
26       Use the -e or --exportname flag to set the optional exportname for the
27       newstyle protocol.
28
29       Use the -o or --oldstyle flag to force the oldstyle protocol.
30
31   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
42   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
46        Server requires an export name
47
48       If you use qemu ≤ 2.5 with the exportname field against an oldstyle
49       server, it will give the error:
50
51        Server does not support export names
52
53       If you use the oldstyle protocol with nbd-client ≥ 3.10, it will give
54       the error:
55
56        Error: It looks like you're trying to connect to an oldstyle server.
57
58   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
62       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

NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT

68       newstyle protocol
69           Supported in nbdkit ≥ 1.1.12, and the default in nbdkit ≥ 1.3.
70
71       export names
72           Supported in nbdkit ≥ 1.1.12.
73
74           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
78       "NBD_FLAG_NO_ZEROES"
79           Supported in nbdkit ≥ 1.1.13.
80
81           This protocol optimization avoids sending a useless block of zero
82           bytes during protocol negotiation.
83
84       "NBD_CMD_WRITE_ZEROES"
85           Supported in nbdkit ≥ 1.1.13.
86
87       TLS with X.509 certificates
88           Supported in nbdkit ≥ 1.1.15.
89
90       TLS with Pre-Shared Keys (PSK)
91           Supported in nbdkit ≥ 1.4.0.
92
93       "NBD_OPT_GO"
94           Supported in nbdkit ≥ 1.5.3.
95
96           This protocol enhancement allows the server to return errors when
97           negotiating the export name.
98
99       "NBD_OPT_INFO"
100           Supported in nbdkit ≥ 1.9.3.
101
102           This protocol enhancement allows a client to inspect details about
103           the export without actually connecting.
104
105       "NBD_FLAG_CAN_MULTI_CONN"
106           Supported in nbdkit ≥ 1.9.9.
107
108       Structured Replies
109           Supported in nbdkit ≥ 1.11.8.
110
111           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
115       Metadata Querying
116           Supported in nbdkit ≥ 1.11.8.
117
118       Block Status
119           Supported in nbdkit ≥ 1.11.10.
120
121           Only "base:allocation" (ie. querying which parts of an image are
122           sparse) is supported.
123
124           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
128       "NBD_FLAG_DF"
129           Supported in nbdkit ≥ 1.11.11.
130
131           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
136       Resize Extension
137           Not supported.
138

SEE ALSO

140       nbdkit(1),
141       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
142       https://nbd.sourceforge.io/.
143

AUTHORS

145       Eric Blake
146
147       Richard W.M. Jones
148
149       Pino Toscano
150
152       Copyright (C) 2013-2018 Red Hat Inc.
153

LICENSE

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
159       ·   Redistributions of source code must retain the above copyright
160           notice, this list of conditions and the following disclaimer.
161
162       ·   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
167       ·   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
171       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.
182
183
184
185nbdkit-1.12.3                     2019-05-22                nbdkit-protocol(1)
Impressum