docs/nbdkit-protocol.pod

   1 =head1 NAME
   2
   3 nbdkit - which parts of the NBD protocol nbdkit supports
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit [-n|--newstyle] [--mask-handshake MASK] [--no-sr] [-o|--oldstyle]
   8         [...]
   9
  10 =head1 DESCRIPTION
  11
  12 This page documents the level of support in nbdkit for various parts
  13 of the NBD protocol.
  14
  15 =head1 NEW STYLE VS OLD STYLE PROTOCOL
  16
  17 The NBD protocol comes in two incompatible forms that we call
  18 "oldstyle" and "newstyle".  Unfortunately which protocol you should
  19 use depends on the client and cannot be known in advance, nor can it
  20 be negotiated from the server side.
  21
  22 nbdkit defaults to the newstyle protocol since nbdkit E<ge> 1.3.  The
  23 newstyle protocol is better in every respect than the oldstyle
  24 protocol and you should prefer it if possible.  The newstyle protocol
  25 also includes an extension where a client may request structured
  26 replies for even more capabilities, such as sparse reads or obtaining
  27 block status.  By default, nbdkit advertises as many features as it
  28 can support (in some cases, this can be limited by what callbacks the
  29 plugin handles), even if the client does not negotiate to use all
  30 advertised features.
  31
  32 Nbdkit also includes some options that are useful mainly when
  33 performing integration tests, for proving whether clients have sane
  34 fallback behavior when dealing various older servers permitted by the
  35 NBD protocol.  Use the I<--no-sr> flag to force the newstyle protocol
  36 to decline any client request for structured replies.  Use the
  37 I<--mask-handshake> parameter to mask off particular global features
  38 which are advertised during new-style handshake (defaulting to all
  39 supported bits set).  Clearing bit 0 (the low order bit) limits a
  40 client to using just C<NBD_OPT_EXPORT_NAME> (and is incompatible with
  41 TLS or structured replies); clearing bit 1 causes the handshake to
  42 send more padding bytes in response to C<NBD_OPT_EXPORT_NAME>.  Other
  43 bits in the mask will only have an effect if the NBD protocol is
  44 extended in the future to define other global bits.
  45
  46 Use the I<-o> or I<--oldstyle> flag to force the oldstyle protocol.
  47 In this mode, I<--no-sr> and I<--mask-handshake> have no effect.
  48
  49 =head2 Common clients and the protocol they require
  50
  51  Client                          Protocol
  52  ------------------------------------------------------------
  53  qemu <= 2.5 without exportname  oldstyle
  54  qemu <= 2.5 with exportname     newstyle
  55  qemu >= 2.6                     client can talk either protocol
  56  qemu >= 2.11                    client tries structured replies
  57  nbd-client < 3.10               client can talk either protocol
  58  nbd-client >= 3.10              newstyle, no structured replies
  59  any TLS (encrypted) client      newstyle
  60  nbdkit nbd plugin               client can talk either protocol
  61  nbdkit >= 1.13.3                nbd plugin tries structured replies
  62  libnbd                          either protocol, tries structured replies
  63
  64 =head2 Errors seen if using the wrong protocol
  65
  66 If you use qemu E<le> 2.5 without the exportname field against a
  67 newstyle server, it will give the error:
  68
  69  Server requires an export name
  70
  71 If you use qemu E<le> 2.5 with the exportname field against an
  72 oldstyle 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 E<ge> 3.10, it will
  77 give the error:
  78
  79  Error: It looks like you're trying to connect to an oldstyle server.
  80
  81 =head2 NBD protocol and port number
  82
  83 Port 10809/tcp is reserved by IANA for the NBD protocol, but you can
  84 use nbdkit on any port or on Unix domain sockets.
  85
  86 The NBD protocol specification claims that you should always use
  87 newstyle when using port 10809, and use oldstyle on all other ports,
  88 but this claim is not based on the reality of what NBD servers do, and
  89 nbdkit does not require or encourage this.
  90
  91 =head1 NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT
  92
  93 =over 4
  94
  95 =item newstyle protocol
  96
  97 Supported in nbdkit E<ge> 1.1.12, and the default in nbdkit E<ge> 1.3.
  98
  99 =item export names
 100
 101 Partially supported in nbdkit E<ge> 1.1.12.  Support for plugins to
 102 read the client export name added in nbdkit E<ge> 1.15.2.
 103
 104 Versions of nbdkit before 1.16 could advertise a single export name to
 105 clients, via a now deprecated side effect of the I<-e> option.  In nbdkit
 106 1.15.2, plugins could read the client requested export name using
 107 C<nbdkit_export_name()> and serve different content.  In nbdkit
 108 1.21.22, plugins could implement C<.list_exports> to answer
 109 C<NBD_OPT_LIST> queries.
 110
 111 =item C<NBD_FLAG_NO_ZEROES>
 112
 113 Supported in nbdkit E<ge> 1.1.13.
 114
 115 This protocol optimization avoids sending a useless block of zero
 116 bytes during protocol negotiation.
 117
 118 =item C<NBD_CMD_WRITE_ZEROES>
 119
 120 Supported in nbdkit E<ge> 1.1.13.
 121
 122 =item TLS with X.509 certificates
 123
 124 Supported in nbdkit E<ge> 1.1.15.
 125
 126 =item TLS with Pre-Shared Keys (PSK)
 127
 128 Supported in nbdkit E<ge> 1.4.0.
 129
 130 =item C<NBD_OPT_GO>
 131
 132 Supported in nbdkit E<ge> 1.5.3.
 133
 134 This protocol enhancement allows the server to return errors when
 135 negotiating the export name.
 136
 137 =item C<NBD_OPT_INFO>
 138
 139 Supported in nbdkit E<ge> 1.9.3.
 140
 141 This protocol enhancement allows a client to inspect details about
 142 the export without actually connecting.
 143
 144 =item C<NBD_FLAG_CAN_MULTI_CONN>
 145
 146 Supported in nbdkit E<ge> 1.9.9.
 147
 148 =item Structured Replies
 149
 150 Supported in nbdkit E<ge> 1.11.8.
 151
 152 However we don’t expose the capability to send structured replies to
 153 plugins yet, nor do we send human-readable error messages using this
 154 facility.
 155
 156 In nbdkit E<ge> 1.13.9, the command-line option I<--no-sr> can be
 157 used to disable server support for structured replies, for testing
 158 client fallbacks.
 159
 160 =item Metadata Querying
 161
 162 Supported in nbdkit E<ge> 1.11.8.
 163
 164 =item Block Status
 165
 166 Supported in nbdkit E<ge> 1.11.10.
 167
 168 Only C<base:allocation> (ie. querying which parts of an image are
 169 sparse) is supported.
 170
 171 Sparse reads (using C<NBD_REPLY_TYPE_OFFSET_HOLE> are not directly
 172 supported, but a client can use block status to infer which portions
 173 of the export do not need to be read.
 174
 175 =item C<NBD_FLAG_DF>
 176
 177 Supported in nbdkit E<ge> 1.11.11.
 178
 179 This protocol extension allows a client to force an all-or-none read
 180 when structured replies are in effect. However, the flag is a no-op
 181 until we extend the plugin API to allow a fragmented read in the first
 182 place.
 183
 184 =item C<NBD_CMD_CACHE>
 185
 186 Supported in nbdkit E<ge> 1.13.4.
 187
 188 This protocol extension allows a client to inform the server about
 189 intent to access a portion of the export, to allow the server an
 190 opportunity to cache things appropriately.
 191
 192 =item C<NBD_CMD_FLAG_FAST_ZERO>
 193
 194 Supported in nbdkit E<ge> 1.15.0.
 195
 196 This protocol extension allows a server to advertise that it can rank
 197 all zero requests as fast or slow, at which point the client can make
 198 fast zero requests which fail immediately with C<ENOTSUP> if the
 199 request is no faster than a counterpart write would be, while normal
 200 zero requests still benefit from compressed network traffic regardless
 201 of the time taken.
 202
 203 =item C<NBD_INFO_NAME>, C<NBD_INFO_DESCRIPTION>
 204
 205 Supported in nbdkit E<ge> 1.23.6.
 206
 207 These protocol extensions allow a client to learn more information
 208 about an export during C<NBD_OPT_GO>.  The C<.default_export> callback
 209 can inform a client of a canonical non-empty name in place of the
 210 default export C<"">, and the C<.export_description> callback can give
 211 a client more details about the export.
 212
 213 =item C<NBD_INFO_BLOCK_SIZE>
 214
 215 Supported in nbdkit E<ge> 1.30.
 216
 217 =item Resize Extension
 218
 219 I<Not supported>.
 220
 221 =back
 222
 223 =head1 SEE ALSO
 224
 225 L<nbdkit(1)>,
 226 L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>,
 227 L<https://nbd.sourceforge.io/>.
 228
 229 =head1 AUTHORS
 230
 231 Eric Blake
 232
 233 Richard W.M. Jones
 234
 235 Pino Toscano
 236
 237 =head1 COPYRIGHT
 238
 239 Copyright Red Hat