12:31 p.m.
Hi Eric,
Thanks for the ping; it had slipped my mind.
On Fri, Dec 03, 2021 at 05:14:34PM -0600, Eric Blake wrote:
#### Request message
-The request message, sent by the client, looks as follows:
+The compact request message, sent by the client when extended
+transactions are not negotiated using `NBD_OPT_EXTENDED_HEADERS`,
+looks as follows:
C: 32 bits, 0x25609513, magic (`NBD_REQUEST_MAGIC`)
C: 16 bits, command flags
@@ -353,14 +370,26 @@ C: 64 bits, offset (unsigned)
C: 32 bits, length (unsigned)
C: (*length* bytes of data if the request is of type `NBD_CMD_WRITE`)
+If negotiation agreed on extended transactions with
+`NBD_OPT_EXTENDED_HEADERS`, the client instead uses extended requests:
+
+C: 32 bits, 0x21e41c71, magic (`NBD_REQUEST_EXT_MAGIC`)
+C: 16 bits, command flags
+C: 16 bits, type
+C: 64 bits, handle
+C: 64 bits, offset (unsigned)
+C: 64 bits, length (unsigned)
+C: (*length* bytes of data if the request is of type `NBD_CMD_WRITE`)
+
Perhaps we should decouple the ideas of "effect length" and "payload
length"? As in,
C: 32 bits, 0x21e41c71, magic (`NBD_REQUEST_EXT_MAGIC`)
C: 16 bits, command flags
C: 16 bits, type
C: 64 bits, handle
C: 64 bits, offset
C: 64 bits, effect length
C: 64 bits, payload length
C: (*payload length* bytes of data)
This makes the protocol more context free. With the current set of
commands, only NBD_CMD_WRITE would have payload length be nonzero, but
that doesn't have to remain the case forever; e.g., we could have a
command that extends NBD_CMD_BLOCK_STATUS to only query a subset of the
metadata contexts that we declared (if that is wanted, of course).
Of course, that does have the annoying side effect of no longer fitting
in 32 bytes, requiring a 40-byte header instead. I think it would be
worth it though.
(This is obviously not relevant for reply messages, only for request
messages)
#### Simple reply message
The simple reply message MUST be sent by the server in response to all
requests if structured replies have not been negotiated using
-`NBD_OPT_STRUCTURED_REPLY`. If structured replies have been negotiated, a simple
-reply MAY be used as a reply to any request other than `NBD_CMD_READ`,
-but only if the reply has no data payload. The message looks as
-follows:
+`NBD_OPT_STRUCTURED_REPLY`. If structured replies have been
+negotiated, a simple reply MAY be used as a reply to any request other
+than `NBD_CMD_READ`, but only if the reply has no data payload. If
+extended headers were not negotiated using `NBD_OPT_EXTENDED_HEADERS`,
+the message looks as follows:
S: 32 bits, 0x67446698, magic (`NBD_SIMPLE_REPLY_MAGIC`; used to be
`NBD_REPLY_MAGIC`)
@@ -369,6 +398,16 @@ S: 64 bits, handle
S: (*length* bytes of data if the request is of type `NBD_CMD_READ` and
*error* is zero)
+If extended headers were negotiated using `NBD_OPT_EXTENDED_HEADERS`,
+the message looks like:
+
+S: 32 bits, 0x60d12fd6, magic (`NBD_SIMPLE_REPLY_EXT_MAGIC`)
+S: 32 bits, error (MAY be zero)
+S: 64 bits, handle
+S: 128 bits, padding (MUST be zero)
Should all these requirements about padding not be a SHOULD rather than
a MUST?
[...]
+* `NBD_OPT_EXTENDED_HEADERS` (11)
+
+ The client wishes to use extended headers during the transmission
+ phase. The client MUST NOT send any additional data with the
+ option, and the server SHOULD reject a request that includes data
+ with `NBD_REP_ERR_INVALID`.
+
+ The server replies with the following, or with an error permitted
+ elsewhere in this document:
+
+ - `NBD_REP_ACK`: Extended headers have been negotiated; the client
+ MUST use the 32-byte extended request header, and the server
+ MUST use the 32-byte extended reply header.
+ - For backwards compatibility, clients SHOULD be prepared to also
+ handle `NBD_REP_ERR_UNSUP`; in this case, only the compact
+ transmission headers will be used.
+
+ If the client requests `NBD_OPT_STARTTLS` after this option, it
+ MUST renegotiate extended headers.
+
Two thoughts here:
- We should probably allow NBD_REP_ERR_BLOCK_SIZE_REQD as a reply to
this message; I could imagine a server might not want to talk 64-bit
lengths if it doesn't know that block sizes are going to be
reasonable.
- In the same vein, should we perhaps also add an error message for when
extended headers are negotiated without structured replies? Perhaps a
server implementation might not want to implement the "extended
headers but no structured replies" message format.
On that note, while I know I had said earlier that I would prefer not
making this new extension depend on structured replies, in hindsight
perhaps it *is* a good idea to add that dependency; otherwise we create
an extra message format that is really a degenerate case of "we want to
be modern in one way but not in another", and that screams out to me
"I'm not going to be used much, look at me for security issues!"
Which perhaps is not a very good idea.
[...]
--
w(a)uter.{be,co.za}
wouter(a){grep.be,fosdem.org,debian.org}