[Nbd] [PATCHv4] docs/proto.md: Clarify SHOULD / MUST / MAY etc
These are changes which possibly have semantic effect
* Clarify that SHOULD / MUST / MAY etc. when in capitals have an
RFC 2119 meaning using the wording within that RFC.
* Fix some lowercase use of these words which actually were
meant to be uppercase.
* Fix some lowercase 'should' which clearly meant 'MUST'; where
it's not obvious, I've made them 'SHOULD' or left them as is.
* Fix wording on transmission flags to be clearer.
Signed-off-by: Alex Bligh <alex@...872...>
---
doc/proto.md | 96 ++++++++++++++++++++++++++++++++++++------------------------
1 file changed, 58 insertions(+), 38 deletions(-)
Changes since v3:
* Consensus is that bolding is permanently dead
* Fixed the transmission flags section by pretty much rewriting it.
* Fixed provisions for back-compatibility. They are now all a MUST.
The client can always disconnect if it doesn't want to be
back compatible.
* Various other nits from Eric & Wouter
Changes since v2:
* Remove bolding for now (may do separately)
* Remove NUL => `NUL` for now (will do separately) so easier to see
possibly semantic changes
Changes since v1:
* Added an http link to RFC2119 per Eric Blake
* Corrected a couple more MUST entries
* Put NUL in monospace
diff --git a/doc/proto.md b/doc/proto.md
index 94f440f..3cef259 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -25,6 +25,12 @@ comments) constant names, `0xdeadbeef` is used for literal hex numbers
(which are always sent in network byte order), and (brackets) are used
for comments. Anything else is a description of the data that is sent.
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
+"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",
+"MAY", and "OPTIONAL" in this document are to be interpreted as
+described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+The same words in lower case carry their natural meaning.
+
## Protocol phases
The NBD protocol has two phases: the handshake and the transmission. During the
@@ -92,7 +98,7 @@ the IANA-reserved port for NBD, 10809. The server MAY listen on other
ports as well, but it SHOULD use the old style handshake on those. The
server SHOULD refuse to allow oldstyle negotiations on the newstyle
port. For debugging purposes, the server MAY change the port on which to
-listen for newstyle negotiation, but this should not happen for
+listen for newstyle negotiation, but this SHOULD NOT happen for
production purposes.
The initial few exchanges in newstyle negotiation look as follows:
@@ -135,7 +141,7 @@ S: 16 bits, transmission flags
S: 124 bytes, zeroes (reserved) (unless `NBD_FLAG_C_NO_ZEROES` was
negotiated by the client)
-If the server is unwilling to allow the export, it should close the
+If the server is unwilling to allow the export, it SHOULD close the
connection.
The reason that the flags field is 16 bits large and not 32 as in the
@@ -160,9 +166,9 @@ To fix these two issues, the following changes were implemented:
- The server will set the handshake flag `NBD_FLAG_FIXED_NEWSTYLE`, to
signal that it supports fixed newstyle negotiation.
-- The client should reply with `NBD_FLAG_C_FIXED_NEWSTYLE` set in its flags
+- The client SHOULD reply with `NBD_FLAG_C_FIXED_NEWSTYLE` set in its flags
field too, though its side of the protocol does not change incompatibly.
-- The client may now send other options to the server as appropriate, in
+- The client MAY now send other options to the server as appropriate, in
the generic format for sending an option as described above.
- The server MUST NOT send a response to `NBD_OPT_EXPORT_NAME` until all
other pending option requests have had their final reply.
@@ -174,7 +180,7 @@ S: 32 bits, the option as sent by the client to which this is a reply
S: 32 bits, reply type (e.g., `NBD_REP_ACK` for successful completion,
or `NBD_REP_ERR_UNSUP` to mark use of an option not known by this
server
-S: 32 bits, length of the reply. This may be zero for some replies, in
+S: 32 bits, length of the reply. This MAY be zero for some replies, in
which case the next field is not sent
S: any data as required by the reply (e.g., an export name in the case
of `NBD_REP_SERVER`)
@@ -294,7 +300,7 @@ order.
This field of 16 bits is sent by the server after the `INIT_PASSWD` and
the first magic number.
-- bit 0, `NBD_FLAG_FIXED_NEWSTYLE`; should be set by servers that
+- bit 0, `NBD_FLAG_FIXED_NEWSTYLE`; MUST be set by servers that
support the fixed newstyle protocol
- bit 1, `NBD_FLAG_NO_ZEROES`; if set, and if the client replies with
`NBD_FLAG_C_NO_ZEROES` in the client flags field, the server MUST NOT
@@ -309,20 +315,31 @@ NOT set any of these flags during oldstyle negotiation.
This field of 16 bits is sent by the server after option haggling, or
immediately after the handshake flags field in oldstyle negotiation:
-- bit 0, `NBD_FLAG_HAS_FLAGS`; should always be 1
-- bit 1, `NBD_FLAG_READ_ONLY`; should be set to 1 if the export is
- read-only
-- bit 2, `NBD_FLAG_SEND_FLUSH`; should be set to 1 if the server
- supports `NBD_CMD_FLUSH` commands
-- bit 3, `NBD_FLAG_SEND_FUA`; should be set to 1 if the server supports
- the `NBD_CMD_FLAG_FUA` flag
-- bit 4, `NBD_FLAG_ROTATIONAL`; should be set to 1 to let the client
- schedule I/O accesses as for a rotational medium
-- bit 5, `NBD_FLAG_SEND_TRIM`; should be set to 1 if the server supports
- `NBD_CMD_TRIM` commands
-- bit 6, `NBD_FLAG_SEND_WRITE_ZEROES`; defined by the experimental
+- bit 0, `NBD_FLAG_HAS_FLAGS`: MUST always be 1
+- bit 1, `NBD_FLAG_READ_ONLY`: The server MAY set this flag to indicate
+ to the client that the export is read-only (exports might be read-only
+ in a manner undetectable to the server, for instance because of
+ permissions). If this flag is set, the server MUST error subsequent
+ write operations to the export.
+- bit 2, `NBD_FLAG_SEND_FLUSH`: the server MAY set this flag to indicate
+ that it supports the `NBD_CMD_FLUSH` command. The server MUST NOT set this
+ flag if it does not support the `NBD_CMD_FLUSH` command. The client MUST
+ NOT send `NBD_CMD_FLUSH` commands if this flag is not set.
+- bit 3, `NBD_FLAG_SEND_FUA`: the server MAY set this flag to indicate
+ that it supports the `NBD_CMD_FLAG_FUA` flag. The server MUST NOT set
+ this flag if it does not support the `NBD_CMD_FLAG_FUA` flag. The client
+ MUST NOT set the `NBD_CMD_FLAG_FUA` flag if this flag is not set.
+- bit 4, `NBD_FLAG_ROTATIONAL`: the server MAY set this flag to 1 to
+ inform the client that the export has the characteristics of a rotational
+ medium, and the client MAY schedule I/O accesses in a manner corresponding
+ to the setting of this flag.
+- bit 5, `NBD_FLAG_SEND_TRIM`: the server MAY set this flag to indicate
+ that it supports the `NBD_CMD_TRIM` command. The server MUST NOT set this
+ flag if it does not support the `NBD_CMD_TRIM` command. The client MUST
+ NOT send `NBD_CMD_FLUSH` commands if this flag is not set.
+- bit 6, `NBD_FLAG_SEND_WRITE_ZEROES`: defined by the experimental
`WRITE_ZEROES` extension; see below.
-- bit 7, `NBD_FLAG_SEND_DF`; defined by the experimental `STRUCTURED_REPLY`
+- bit 7, `NBD_FLAG_SEND_DF`: defined by the experimental `STRUCTURED_REPLY`
extension; see below.
Clients SHOULD ignore unknown flags.
@@ -355,11 +372,11 @@ of the newstyle negotiation.
haggling, and proceed to the transmission phase. Data: name of the
export, free-form UTF-8 text (subject to limitations by server
implementation). The length of the name is determined from the
- option header. The name is not NUL terminated, and may not
+ option header. The name is not NUL terminated, and MUST NOT
contain embedded NUL characters. If the
chosen export does not exist or requirements for the chosen export
are not met (e.g., the client did not negotiate TLS for an export
- where the server requires it), the server should close the
+ where the server requires it), the server MUST close the
connection.
A special, "empty", name (i.e., the length field is zero and no name
@@ -393,12 +410,12 @@ of the newstyle negotiation.
- `NBD_OPT_STARTTLS` (5)
The client wishes to initiate TLS. If the server replies with
- `NBD_REP_ACK`, then the client should immediately initiate a TLS
+ `NBD_REP_ACK`, then the client MUST immediately initiate a TLS
handshake and continue the negotiation in the encrypted channel. If
- the server is unwilling to perform TLS, it should reply with
- `NBD_REP_ERR_POLICY`. For backwards compatibility, a client should
+ the server is unwilling to perform TLS, it SHOULD reply with
+ `NBD_REP_ERR_POLICY`. For backwards compatibility, a client MUST
also be prepared to handle `NBD_REP_ERR_UNSUP`. If the client sent
- along any data with the request, the server should send back
+ along any data with the request, the server SHOULD send back
`NBD_REP_ERR_INVALID`. The client MUST NOT send this option if
it has already negotiated TLS; if the server receives
`NBD_OPT_STARTTLS` when TLS has already been negotiated, the server
@@ -670,7 +687,7 @@ documented as applicable to the given request.
Which error to return in any other case is not specified by the NBD
protocol.
-The server SHOULD AVOID returning ENOMEM if at all possible.
+The server SHOULD NOT return `ENOMEM` if at all possible.
## Experimental extensions
@@ -752,19 +769,19 @@ Therefore these commands share common documentation.
server has multiple alternate names for a single export, or a
default export was specified.
- The server MUST NOT fail an NDB_OPT_GO sent with the same parameters
- as a previous NBD_OPT_INFO which returned successfully (i.e. with
+ The server MUST NOT fail an `NDB_OPT_GO` sent with the same parameters
+ as a previous `NBD_OPT_INFO` which returned successfully (i.e. with
`NBD_REP_SERVER`) unless in the intervening time the client has
negotiated other options. The server MUST return the same transmission
- flags with NDB_OPT_GO as a previous NDB_OPT_INFO unless in the
+ flags with `NDB_OPT_GO` as a previous `NDB_OPT_INFO` unless in the
intervening time the client has negotiated other options.
The values of the transmission flags MAY differ from what was sent
earlier in response to an earlier `NBD_OPT_INFO` (if any), and/or
the server MAY fail the request, based on other options that were
negotiated in the meantime.
- For backwards compatibility, clients should be prepared to also
- handle `NBD_REP_ERR_UNSUP`. In this case, they should fall back to
+ For backwards compatibility, clients MUST be prepared to also
+ handle `NBD_REP_ERR_UNSUP`. In this case, they MUST fall back to
using `NBD_OPT_EXPORT_NAME`.
The reply to an `NBD_OPT_GO` is identical to the reply to `NBD_OPT_INFO`
@@ -793,12 +810,15 @@ command flag.
* `NBD_FLAG_SEND_WRITE_ZEROES`
- The server SHOULD set this transmission flag to 1 if the
- `NBD_CMD_WRITE_ZEROES` request is supported.
+ The server MAY set this transmission flag to indicate that it
+ supports the `NBD_CMD_WRITE_ZEROES` command. The server MUST NOT
+ set this flag if it does not support the `NBD_CMD_WRITE_ZEROES` command.
+ The client MUST NOT send `NBD_CMD_WRITE_ZEROES` commands if this flag
+ is not set.
* `NBD_CMD_WRITE_ZEROES`
- A write request with no payload. Length and offset define the location
+ A write request with no payload. *Offset* and *length* define the location
and amount of data to be zeroed.
The server MUST zero out the data on disk, and then send the reply
@@ -958,7 +978,7 @@ error, and alters the reply to the `NBD_CMD_READ` request.
The payload is structured as:
- 32 bits: error (MUST be nonzero)
+ 32 bits: error (MUST be non-zero)
64 bits: offset (unsigned)
*length - 12* bytes: (optional UTF-8 encoded data suitable for
direct display to a human being, with no embedded or
@@ -971,7 +991,7 @@ error, and alters the reply to the `NBD_CMD_READ` request.
of the file, starting at *offset*. The data MUST lie within the
bounds of the original offset and length of the client's
request, and MUST NOT overlap with the bounds of any earlier
- content chunk or error chunk in the same reply. This chunk may
+ content chunk or error chunk in the same reply. This chunk MAY
be used more than once in a reply, unless the `NBD_CMD_FLAG_DF`
flag was set. Valid as a reply to `NBD_CMD_READ`.
@@ -988,7 +1008,7 @@ error, and alters the reply to the `NBD_CMD_READ` request.
lie within the bounds of the original offset and length of the
client's request, and MUST NOT overlap with the bounds of any
earlier content chunk or error chunk in the same reply. This
- chunk may be used more than once in a reply, unless the
+ chunk MAY be used more than once in a reply, unless the
`NBD_CMD_FLAG_DF` flag was set. Valid as a reply to
`NBD_CMD_READ`.
@@ -1008,7 +1028,7 @@ error, and alters the reply to the `NBD_CMD_READ` request.
server MUST use structured replies to the `NBD_CMD_READ`
transmission request. Other extensions that require structured
replies may now be negotiated.
- - For backwards compatibility, clients should be prepared to also
+ - For backwards compatibility, clients MUST be prepared to also
handle `NBD_REP_ERR_UNSUP`; in this case, no structured replies
will be sent.
--
1.9.1
Reply to: