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