[Nbd] [PATCH] docs/proto.md: Clarify SHOULD / MUST / MAY etc
* Clarify that SHOULD / MUST / MAY etc. when in capitals have an
RFC 2119 meaning using the wording within that RFC.
* Put the above terms in bold.
* 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.
Signed-off-by: Alex Bligh <alex@...872...>
---
doc/proto.md | 410 ++++++++++++++++++++++++++++++-----------------------------
1 file changed, 208 insertions(+), 202 deletions(-)
diff --git a/doc/proto.md b/doc/proto.md
index 4d63b23..7cc1101 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. 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
@@ -87,12 +93,12 @@ no longer supported.
#### Newstyle negotiation
-A client who wants to use the new style negotiation SHOULD connect on
-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
+A client who wants to use the new style negotiation **SHOULD** connect on
+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
production purposes.
The initial few exchanges in newstyle negotiation look as follows:
@@ -106,8 +112,8 @@ C: 32 bits, flags
This completes the initial phase of negotiation; the client and server
now both know they understand the first version of the newstyle
-handshake, with no options. The client SHOULD ignore any handshake flags
-it does not recognize, while the server MUST close the connection if
+handshake, with no options. The client **SHOULD** ignore any handshake flags
+it does not recognize, while the server **MUST** close the connection if
it does not recognize the client's flags. What follows is a repeating
group of options. In non-fixed newstyle only one option can be set
(`NBD_OPT_EXPORT_NAME`), and it is not optional.
@@ -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,11 +166,11 @@ 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
+- The server **MUST NOT** send a response to `NBD_OPT_EXPORT_NAME` until all
other pending option requests have had their final reply.
- The server will reply to any option apart from `NBD_OPT_EXPORT_NAME`
with reply packets in the following format:
@@ -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`)
@@ -182,7 +188,7 @@ S: any data as required by the reply (e.g., an export name in the case
As there is no unique number for client requests, clients who want to
differentiate between answers to two instances of the same option during
any negotiation must make sure they've seen the answer to an outstanding
-request before sending the next one of the same type. The server MAY
+request before sending the next one of the same type. The server **MAY**
send replies in the order that the requests were received, but is not
required to.
@@ -196,7 +202,7 @@ with either a single simple reply or a series of one or more
structured reply chunks per request. The phase continues until either
side closes the connection.
-Note that without client negotiation, the server MUST use only simple
+Note that without client negotiation, the server **MUST** use only simple
replies, and that it is impossible to tell by reading the server
traffic in isolation whether a data field will be present; the simple
reply is also problematic for error handling of the `NBD_CMD_READ`
@@ -209,29 +215,29 @@ may be handled by the server asynchronously), and structured reply
chunks from one request may be interleaved with reply messages from
other requests; however, there may be constraints that prevent
arbitrary reordering of structured reply chunks within a given reply.
-Clients SHOULD use a handle that is distinct from all other currently
-pending transactions, but MAY reuse handles that are no longer in
+Clients **SHOULD** use a handle that is distinct from all other currently
+pending transactions, but **MAY** reuse handles that are no longer in
flight; handles need not be consecutive. In each reply message
-(whether simple or structured), the server MUST use the same value for
+(whether simple or structured), the server **MUST** use the same value for
handle as was sent by the client in the corresponding request. In
this way, the client can correlate which request is receiving a
response.
#### Ordering of messages and writes
-The server MAY process commands out of order, and MAY reply out of
+The server **MAY** process commands out of order, and **MAY** reply out of
order, except that:
* All write commands (that includes `NBD_CMD_WRITE`,
`NBD_WRITE_ZEROES` and `NBD_CMD_TRIM`) that the server
completes (i.e. replies to) prior to processing to a
- `NBD_CMD_FLUSH` MUST be written to non-volatile
+ `NBD_CMD_FLUSH` **MUST** be written to non-volatile
storage prior to replying to that `NBD_CMD_FLUSH`. This
paragraph only applies if `NBD_FLAG_SEND_FLUSH` is set within
the transmission flags, as otherwise `NBD_CMD_FLUSH` will never
be sent by the client to the server.
-* A server MUST NOT reply to a command that has `NBD_CMD_FLAG_FUA` set
+* A server **MUST NOT** reply to a command that has `NBD_CMD_FLAG_FUA` set
in its command flags until the data (if any) written by that command
is persisted to non-volatile storage. This only applies if
`NBD_FLAG_SEND_FUA` is set within the transmission flags, as otherwise
@@ -259,22 +265,22 @@ C: (*length* bytes of data if the request is of type `NBD_CMD_WRITE`)
#### Simple reply message
-The simple reply message MUST be sent by the server in response to all
+The simple reply message **MUST** be sent by the server in response to all
requests if the experimental `STRUCTURED_REPLY` extension was not
negotiated. If structured replies have been negotiated, a simple
-reply MAY be used as a reply to any request other than `NBD_CMD_READ`,
+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:
S: 32 bits, 0x67446698, magic (`NBD_SIMPLE_REPLY_MAGIC`; used to be
`NBD_REPLY_MAGIC`)
-S: 32 bits, error (MAY be zero)
+S: 32 bits, error (**MAY** be zero)
S: 64 bits, handle
S: (*length* bytes of data if the request is of type `NBD_CMD_READ`)
#### Structured reply chunk message
-This reply type MUST NOT be used except as documented by the
+This reply type **MUST NOT** be used except as documented by the
experimental `STRUCTURED_REPLY` extension; see below.
## Values
@@ -294,53 +300,53 @@ 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
+ `NBD_FLAG_C_NO_ZEROES` in the client flags field, the server **MUST NOT**
send the 124 bytes of zero at the end of the negotiation.
-The server MUST NOT set any other flags, and SHOULD NOT change behaviour
-unless the client responds with a corresponding flag. The server MUST
-NOT set any of these flags during oldstyle negotiation.
+The server **MUST NOT** set any other flags, and **SHOULD NOT** change behaviour
+unless the client responds with a corresponding flag. The server **MUST
+NOT** set any of these flags during oldstyle negotiation.
##### Transmission flags
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
+- bit 0, `NBD_FLAG_HAS_FLAGS`; **MUST** always be 1
+- bit 1, `NBD_FLAG_READ_ONLY`; **MUST** be set to 1 if the export is
read-only
-- bit 2, `NBD_FLAG_SEND_FLUSH`; should be set to 1 if the server
+- bit 2, `NBD_FLAG_SEND_FLUSH`; **MUST** 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
+- bit 3, `NBD_FLAG_SEND_FUA`; **MUST** 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
+- bit 4, `NBD_FLAG_ROTATIONAL`; **MUST** 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
+- bit 5, `NBD_FLAG_SEND_TRIM`; **MUST** be set to 1 if the server supports
`NBD_CMD_TRIM` commands
- 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`
extension; see below.
-Clients SHOULD ignore unknown flags.
+Clients **SHOULD** ignore unknown flags.
##### Client flags
This field of 32 bits is sent after initial connection and after
receiving the handshake flags from the server.
-- bit 0, `NBD_FLAG_C_FIXED_NEWSTYLE`; SHOULD be set by clients that
- support the fixed newstyle protocol. Servers MAY choose to honour
+- bit 0, `NBD_FLAG_C_FIXED_NEWSTYLE`; **SHOULD** be set by clients that
+ support the fixed newstyle protocol. Servers **MAY** choose to honour
fixed newstyle from clients that didn't set this bit, but relying on
this isn't recommended.
-- bit 1, `NBD_FLAG_C_NO_ZEROES`; MUST NOT be set if the server did not
- set `NBD_FLAG_NO_ZEROES`. If set, the server MUST NOT send the 124
+- bit 1, `NBD_FLAG_C_NO_ZEROES`; **MUST NOT** be set if the server did not
+ set `NBD_FLAG_NO_ZEROES`. If set, the server **MUST NOT** send the 124
bytes of zeroes at the end of the negotiation.
-Clients MUST NOT set any other flags; the server MUST drop the
+Clients **MUST NOT** set any other flags; the server **MUST** drop the
connection if the client sets an unknown flag, or a flag that does
not match something advertised by the server.
@@ -355,11 +361,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
@@ -367,7 +373,7 @@ of the newstyle negotiation.
where explicitly specifying an export name makes no sense.
This is the only valid option in nonfixed newstyle negotiation. A
- server which wishes to use any other option MUST support fixed
+ server which wishes to use any other option **MUST** support fixed
newstyle.
A major problem of this option is that it does not support the
@@ -393,12 +399,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 **SHOULD**
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`.
This functionality has not yet been implemented by the reference
@@ -432,7 +438,7 @@ during option haggling in the fixed newstyle negotiation.
A description of an export. Data:
- - 32 bits, length of name (unsigned); MUST be no larger than the
+ - 32 bits, length of name (unsigned); **MUST** be no larger than the
reply packet header length - 4
- Name of the export, as expected by `NBD_OPT_EXPORT_NAME` (note
that the length of name does NOT include a NUL terminator)
@@ -450,7 +456,7 @@ during option haggling in the fixed newstyle negotiation.
UTF-8 message.
There are a number of error reply types, all of which are denoted by
-having bit 31 set. All error replies MAY have some data set, in which
+having bit 31 set. All error replies **MAY** have some data set, in which
case that data is an error message in UTF-8 encoding suitable for
display to the user, with no embedded or terminating NUL characters.
@@ -481,12 +487,12 @@ display to the user, with no embedded or terminating NUL characters.
* `NBD_REP_ERR_TLS_REQD` (2^31 + 5)
The server is unwilling to continue negotiation unless TLS is
- negotiated first. A server MUST NOT send this error if it has one or
+ negotiated first. A server **MUST NOT** send this error if it has one or
more exports that do not require TLS; not even if the client indicated
interest (by way of `NBD_OPT_PEEK_EXPORT`) in an export which requires
TLS.
- If this reply is used, servers SHOULD send it in reply to each and every
+ If this reply is used, servers **SHOULD** send it in reply to each and every
unencrypted `NBD_OPT_*` message (apart from `NBD_OPT_STARTTLS`).
This functionality has not yet been implemented by the reference
@@ -507,25 +513,25 @@ display to the user, with no embedded or terminating NUL characters.
This field of 16 bits is sent by the client with every request and provides
additional information to the server to execute the command. Refer to
the "Request types" section below for more details about how a given flag
-affects a particular command. Clients MUST NOT set a command flag bit
+affects a particular command. Clients **MUST NOT** set a command flag bit
that is not documented for the particular command; and whether a flag is
valid may depend on negotiation during the handshake phase.
- bit 0, `NBD_CMD_FLAG_FUA`; This flag is valid for all commands, provided
- `NBD_FLAG_SEND_FUA` has been negotiated, in which case the server MUST
+ `NBD_FLAG_SEND_FUA` has been negotiated, in which case the server **MUST**
accept all commands with this bit set (even by ignoring the bit). The
- client SHOULD NOT set this bit unless the command has the potential of
+ client **SHOULD NOT** set this bit unless the command has the potential of
writing data (current commands are `NBD_CMD_WRITE`, `NBD_CMD_WRITE_ZEROES`
and `NBD_CMD_TRIM`), however note that existing clients are known to set this
bit on other commands. Subject to that, and provided `NBD_FLAG_SEND_FUA`
- is negotiated, the client MAY set this bit on all, no or some commands
+ is negotiated, the client **MAY** set this bit on all, no or some commands
as it wishes (see the section on Ordering of messages and writes for
details). If the server receives a command with `NBD_CMD_FLAG_FUA`
- set it MUST NOT send its reply to that command until all write
+ set it **MUST NOT** send its reply to that command until all write
operations (if any) associated with that command have been
completed and persisted to non-volatile storage. If the command does
not in fact write data (for instance on an `NBD_CMD_TRIM` in a situation
- where the command as a whole is ignored), the server MAY ignore this bit
+ where the command as a whole is ignored), the server **MAY** ignore this bit
being set on such a command.
- bit 1, `NBD_CMD_NO_HOLE`; defined by the experimental `WRITE_ZEROES`
extension; see below.
@@ -539,26 +545,26 @@ The following request types exist:
* `NBD_CMD_READ` (0)
A read request. Length and offset define the data to be read. The
- server MUST reply with either a simple reply or a structured
+ server **MUST** reply with either a simple reply or a structured
reply, according to whether the experimental `STRUCTURED_REPLY`
extension was negotiated.
- If structured replies were not negotiated, the server MUST reply
+ If structured replies were not negotiated, the server **MUST** reply
with a simple reply header, followed immediately by *length* bytes
of data, read from *offset* bytes into the file, unless an error
condition has occurred.
- If an error occurs, the server SHOULD set the appropriate error
- code in the error field. The server MUST then either close the
- connection, or send *length* bytes of data (these bytes MAY be
- invalid, in which case they SHOULD be zero); this is true even if
+ If an error occurs, the server **SHOULD** set the appropriate error
+ code in the error field. The server **MUST** then either close the
+ connection, or send *length* bytes of data (these bytes **MAY** be
+ invalid, in which case they **SHOULD** be zero); this is true even if
the error is `EINVAL` for bad flags detected before even
attempting to read.
If an error occurs while reading after the server has already sent
out the reply header with an error field set to zero (i.e.,
- signalling no error), the server MUST immediately close the
- connection; it MUST NOT send any further data to the client.
+ signalling no error), the server **MUST** immediately close the
+ connection; it **MUST NOT** send any further data to the client.
The experimental `STRUCTURED_REPLY` extension changes the reply
from a simple reply to a structured reply, in part to allow
@@ -568,20 +574,20 @@ The following request types exist:
* `NBD_CMD_WRITE` (1)
A write request. Length and offset define the location and amount of
- data to be written. The client MUST follow the request header with
+ data to be written. The client **MUST** follow the request header with
*length* number of bytes to be written to the device.
- The server MUST write the data to disk, and then send the reply
- message. The server MAY send the reply message before the data has
+ The server **MUST** write the data to disk, and then send the reply
+ message. The server **MAY** send the reply message before the data has
reached permanent storage.
- If an error occurs, the server SHOULD set the appropriate error code
- in the error field. The server MAY then close the connection.
+ If an error occurs, the server **SHOULD** set the appropriate error code
+ in the error field. The server **MAY** then close the connection.
* `NBD_CMD_DISC` (2)
- A disconnect request. The server MUST handle all outstanding
- requests, and then close the connection. A client MUST NOT send
+ A disconnect request. The server **MUST** handle all outstanding
+ requests, and then close the connection. A client **MUST NOT** send
anything to the server after sending an `NBD_CMD_DISC` command.
The values of the length and offset fields in a disconnect request
@@ -589,28 +595,28 @@ The following request types exist:
* `NBD_CMD_FLUSH` (3)
- A flush request; a write barrier. The server MUST NOT send a
+ A flush request; a write barrier. The server **MUST NOT** send a
successful reply header for this request before all write requests
for which a reply has already been sent to the client have reached
permanent storage (using fsync() or similar).
- A client MUST NOT send a flush request unless `NBD_FLAG_SEND_FLUSH`
+ A client **MUST NOT** send a flush request unless `NBD_FLAG_SEND_FLUSH`
was set in the transmission flags field.
- For a flush request, *length* and *offset* are reserved, and MUST be
+ For a flush request, *length* and *offset* are reserved, and **MUST** be
set to all-zero.
* `NBD_CMD_TRIM` (4)
A hint to the server that the data defined by len and offset is no
- longer needed. A server MAY discard len bytes starting at offset, but
+ longer needed. A server **MAY** discard len bytes starting at offset, but
is not required to.
- After issuing this command, a client MUST NOT make any assumptions
+ After issuing this command, a client **MUST NOT** make any assumptions
about the contents of the export affected by this command, until
overwriting it again with `NBD_CMD_WRITE`.
- A client MUST NOT send a trim request unless `NBD_FLAG_SEND_TRIM`
+ A client **MUST NOT** send a trim request unless `NBD_FLAG_SEND_TRIM`
was set in the transmission flags field.
* `NBD_CMD_WRITE_ZEROES` (6)
@@ -621,7 +627,7 @@ The following request types exist:
Some third-party implementations may require additional protocol
messages which are not described in this document. In the interest of
- interoperability, authors of such implementations SHOULD contact the
+ interoperability, authors of such implementations **SHOULD** contact the
maintainer of this document, so that these messages can be listed here
to avoid conflicting implementations.
@@ -648,26 +654,26 @@ The following error values are defined:
* `ENOMEM` (12), Cannot allocate memory.
* `EINVAL` (22), Invalid argument.
* `ENOSPC` (28), No space left on device.
-* `EOVERFLOW` (75), Value too large; SHOULD NOT be sent outside of the
+* `EOVERFLOW` (75), Value too large; **SHOULD NOT** be sent outside of the
experimental `STRUCTURED_REPLY` extension; see below.
-The server SHOULD return `ENOSPC` if it receives a write request
-including one or more sectors beyond the size of the device. It SHOULD
+The server **SHOULD** return `ENOSPC` if it receives a write request
+including one or more sectors beyond the size of the device. It **SHOULD**
return `EINVAL` if it receives a read or trim request including one or
-more sectors beyond the size of the device. It also SHOULD map the
-`EDQUOT` and `EFBIG` errors to `ENOSPC`. Finally, it SHOULD return
+more sectors beyond the size of the device. It also **SHOULD** map the
+`EDQUOT` and `EFBIG` errors to `ENOSPC`. Finally, it **SHOULD** return
`EPERM` if it receives a write or trim request on a read-only export.
-The server SHOULD return `EINVAL` if it receives an unknown command.
+The server **SHOULD** return `EINVAL` if it receives an unknown command.
-The server SHOULD return `EINVAL` if it receives an unknown command flag. It
-also SHOULD return `EINVAL` if it receives a request with a flag not explicitly
+The server **SHOULD** return `EINVAL` if it receives an unknown command flag. It
+also **SHOULD** return `EINVAL` if it receives a request with a flag not explicitly
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** AVOID returning ENOMEM if at all possible.
## Experimental extensions
@@ -705,8 +711,8 @@ Therefore these commands share common documentation.
to move to the transmission phase.
`NBD_OPT_GO`: The client wishes to terminate the negotiation phase and
- progress to the transmission phase. This client MAY issue this command after
- an `NBD_OPT_INFO`, or MAY issue it without a previous `NBD_OPT_INFO`.
+ progress to the transmission phase. This client **MAY** issue this command after
+ an `NBD_OPT_INFO`, or **MAY** issue it without a previous `NBD_OPT_INFO`.
`NBD_OPT_GO` can thus be used as a substitute for `NBD_OPT_EXPORT_NAME`
that returns errors.
@@ -727,7 +733,7 @@ Therefore these commands share common documentation.
block device unless the client negotiates TLS first.
- `NBD_REP_SERVER`: The server accepts the chosen export.
- Additionally, if TLS has not been negotiated, the server MAY reply
+ Additionally, if TLS has not been negotiated, the server **MAY** reply
with `NBD_REP_ERR_TLS_REQD` (instead of `NBD_REP_ERR_UNKNOWN`)
to requests for exports that are unknown. This is so that clients
that have not negotiated TLS cannot enumerate exports.
@@ -736,40 +742,40 @@ Therefore these commands share common documentation.
interpretation than the default (so as to provide additional
binary information normally sent in reply to `NBD_OPT_EXPORT_NAME`,
in place of the default UTF-8 free-form string). The option reply length
- MUST be *length of name* + 14, and the option data has the following layout:
+ **MUST** be *length of name* + 14, and the option data has the following layout:
- 64 bits, size of the export in bytes (unsigned)
- 16 bits, transmission flags.
- 32 bits, length of name (unsigned)
- - Name of the export. This name MAY be different from the one
+ - Name of the export. This name **MAY** be different from the one
given in the `NBD_OPT_INFO` or `NBD_OPT_GO` option in case the 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
+ 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
+ negotiated other options. The server **MUST** return the same transmission
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
+ 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
+ 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`
save that if the reply indicates success (i.e. is `NBD_REP_SERVER`),
the client and the server both immediatedly enter the transmission
- phase. The server MUST NOT send any zero padding bytes after the
+ phase. The server **MUST NOT** send any zero padding bytes after the
`NBD_REP_SERVER` data, whether or not the client negotiated the
- `NBD_FLAG_C_NO_ZEROES` flag. After sending this reply the server MUST
+ `NBD_FLAG_C_NO_ZEROES` flag. After sending this reply the server **MUST**
immediately move to the transmission phase, and after receiving this
- reply, the client MUST immediately move to the transmission phase;
- therefore, the server MUST NOT send this particular reply until all
+ reply, the client **MUST** immediately move to the transmission phase;
+ therefore, the server **MUST NOT** send this particular reply until all
other pending option requests have been sent by the server.
### `WRITE_ZEROES` extension
@@ -789,33 +795,33 @@ one new command and one new command flag.
A write request with no payload. Length and offset define the location
and amount of data to be zeroed.
- The server MUST zero out the data on disk, and then send the reply
- message. The server MAY send the reply message before the data has
+ The server **MUST** zero out the data on disk, and then send the reply
+ message. The server **MAY** send the reply message before the data has
reached permanent storage.
- A client MUST NOT send a write zeroes request unless
+ A client **MUST NOT** send a write zeroes request unless
`NBD_FLAG_SEND_WRITE_ZEROES` was set in the transmission flags field.
- By default, the server MAY use trimming to zero out the area, even
- if it did not advertise `NBD_FLAG_SEND_TRIM`; but it MUST ensure
- that the data reads back as zero. However, the client MAY set the
+ By default, the server **MAY** use trimming to zero out the area, even
+ if it did not advertise `NBD_FLAG_SEND_TRIM`; but it **MUST** ensure
+ that the data reads back as zero. However, the client **MAY** set the
command flag `NBD_CMD_FLAG_NO_HOLE` to inform the server that the
- area MUST be fully provisioned, ensuring that future writes to the
+ area **MUST** be fully provisioned, ensuring that future writes to the
same area will not cause fragmentation or cause failure due to
insufficient space.
- If an error occurs, the server SHOULD set the appropriate error code
- in the error field. The server MAY then close the connection.
+ If an error occurs, the server **SHOULD** set the appropriate error code
+ in the error field. The server **MAY** then close the connection.
-The server SHOULD return `ENOSPC` if it receives a write zeroes request
-including one or more sectors beyond the size of the device. It SHOULD
+The server **SHOULD** return `ENOSPC` if it receives a write zeroes request
+including one or more sectors beyond the size of the device. It **SHOULD**
return `EPERM` if it receives a write zeroes request on a read-only export.
The extension adds the following new command flag:
- `NBD_CMD_FLAG_NO_HOLE`; valid during `NBD_CMD_WRITE_ZEROES`.
- SHOULD be set to 1 if the client wants to ensure that the server does
- not create a hole. The client MAY send `NBD_CMD_FLAG_NO_HOLE` even
+ **SHOULD** be set to 1 if the client wants to ensure that the server does
+ not create a hole. The client **MAY** send `NBD_CMD_FLAG_NO_HOLE` even
if `NBD_FLAG_SEND_TRIM` was not set in the transmission flags field.
### `STRUCTURED_REPLY` extension
@@ -838,31 +844,31 @@ error, and alters the reply to the `NBD_CMD_READ` request.
* Transmission phase
A structured reply in the transmission phase consists of one or
- more structured reply chunk messages. The server MUST NOT send
+ more structured reply chunk messages. The server **MUST NOT** send
this reply type unless the client has successfully negotiated
structured replies via `NBD_OPT_STRUCTURED_REPLY`. Conversely, if
- structured replies are negotiated, the server MUST use a
- structured reply for any response with a payload, and MUST NOT use
+ structured replies are negotiated, the server **MUST** use a
+ structured reply for any response with a payload, and **MUST NOT** use
a simple reply for `NBD_CMD_READ` (even for the case of an early
- `EINVAL` due to bad flags), but MAY use either a simple reply or a
- structured reply to all other requests. The server SHOULD prefer
+ `EINVAL` due to bad flags), but **MAY** use either a simple reply or a
+ structured reply to all other requests. The server **SHOULD** prefer
sending errors via a structured reply, as the error can then be
accompanied by a UTF-8 text payload to present to a human user.
- A structured reply MAY occupy multiple structured chunk messages
+ A structured reply **MAY** occupy multiple structured chunk messages
(all with the same value for "handle"), and the
`NBD_REPLY_FLAG_DONE` reply flag is used to identify the final
chunk. Unless further documented by individual requests below,
- the chunks MAY be sent in any order, except that the chunk with
- the flag `NBD_REPLY_FLAG_DONE` MUST be sent last. Even when a
+ the chunks **MAY** be sent in any order, except that the chunk with
+ the flag `NBD_REPLY_FLAG_DONE` **MUST** be sent last. Even when a
command documents further constraints between chunks of one reply,
it is always safe to interleave chunks of that reply with messages
- related to other requests. A server SHOULD try to minimize the
- number of chunks sent in a reply, but MUST NOT mark a chunk as
+ related to other requests. A server **SHOULD** try to minimize the
+ number of chunks sent in a reply, but **MUST NOT** mark a chunk as
final if there is still a possibility of detecting an error before
transmission of that chunk completes. A structured reply is
considered successful only if it did not contain any error chunks,
- although the client MAY be able to determine partial success based
+ although the client **MAY** be able to determine partial success based
on the chunks received.
A structured reply chunk message looks as follows:
@@ -883,17 +889,17 @@ error, and alters the reply to the `NBD_CMD_READ` request.
This field of 16 bits is sent by the server as part of every
structured reply.
- - bit 0, `NBD_REPLY_FLAG_DONE`; the server MUST clear this bit if
+ - bit 0, `NBD_REPLY_FLAG_DONE`; the server **MUST** clear this bit if
more structured reply chunks will be sent for the same client
- request, and MUST set this bit if this is the final reply. This
- bit MUST always be set for the `NBD_REPLY_TYPE_NONE` chunk,
+ request, and **MUST** set this bit if this is the final reply. This
+ bit **MUST** always be set for the `NBD_REPLY_TYPE_NONE` chunk,
although any other chunk type can also be used as the final
chunk.
- The server MUST NOT set any other flags without first negotiating
+ The server **MUST NOT** set any other flags without first negotiating
the extension with the client, unless the client can usefully
react to the response without interpreting the flag (for instance
- if the flag is some form of hint). Clients MUST ignore
+ if the flag is some form of hint). Clients **MUST** ignore
unrecognized flags.
* Structured Reply types
@@ -902,12 +908,12 @@ error, and alters the reply to the `NBD_CMD_READ` request.
Some chunk types can additionally be categorized by role, such as
*error chunks* or *content chunks*. Each type determines how to
interpret the "length" bytes of payload. If the client receives
- an unknown or unexpected type, it MUST close the connection.
+ an unknown or unexpected type, it **MUST** close the connection.
- `NBD_REPLY_TYPE_NONE` (0)
- *length* MUST be 0 (and the payload field omitted). This chunk
- type MUST always be used with the `NBD_REPLY_FLAG_DONE` bit set
+ *length* **MUST** be 0 (and the payload field omitted). This chunk
+ type **MUST** always be used with the `NBD_REPLY_FLAG_DONE` bit set
(that is, it may appear at most once in a structured reply, and
is only useful as the final reply chunk). If no earlier error
chunks were sent, then this type implies that the overall client
@@ -915,29 +921,29 @@ error, and alters the reply to the `NBD_CMD_READ` request.
- `NBD_REPLY_TYPE_ERROR` (1)
- This chunk type is in the error chunk category. *length* MUST
+ This chunk type is in the error chunk category. *length* **MUST**
be at least 4. This chunk represents that an error occurred,
- and the client MAY NOT make any assumptions about partial
- success. This type SHOULD NOT be used more than once in a
+ and the client **MAY NOT** make any assumptions about partial
+ success. This type **SHOULD NOT** be used more than once in a
structured reply. Valid as a reply to any request.
The payload is structured as:
- 32 bits: error (MUST be nonzero)
+ 32 bits: error (**MUST** be nonzero)
*length - 4* bytes: (optional UTF-8 encoded data suitable for
direct display to a human being, with no embedded or
terminating NUL characters)
- `NBD_REPLY_TYPE_ERROR_OFFSET` (2)
- This chunk type is in the error chunk category. *length* MUST
+ This chunk type is in the error chunk category. *length* **MUST**
be at least 12. This reply represents that an error occurred at
- a given offset, which MUST lie within the original offset and
+ a given offset, which **MUST** lie within the original offset and
length of the request; the client can use this offset to
determine if request had any partial success. This chunk type
- MAY appear multiple times in a structured reply, although the
- same offset SHOULD NOT be repeated. Likewise, if content chunks
- were sent earlier in the structured reply, the server SHOULD NOT
+ **MAY** appear multiple times in a structured reply, although the
+ same offset **SHOULD NOT** be repeated. Likewise, if content chunks
+ were sent earlier in the structured reply, the server **SHOULD NOT**
send multiple distinct offsets that lie within the bounds of a
single content chunk. Valid as a reply to `NBD_CMD_READ`,
`NBD_CMD_WRITE`, `NBD_CMD_WRITE_ZEROES`, and `NBD_CMD_TRIM`.
@@ -952,12 +958,12 @@ error, and alters the reply to the `NBD_CMD_READ` request.
- `NBD_REPLY_TYPE_OFFSET_DATA` (3)
- This chunk type is in the content chunk category. *length* MUST
+ This chunk type is in the content chunk category. *length* **MUST**
be at least 9. It represents the contents of *length - 8* bytes
- of the file, starting at *offset*. The data MUST lie within the
+ 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
+ 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 `NBD_CMD_FLAG_DF`
flag was set. Valid as a reply to `NBD_CMD_READ`.
@@ -968,20 +974,20 @@ error, and alters the reply to the `NBD_CMD_READ` request.
- `NBD_REPLY_TYPE_OFFSET_HOLE` (4)
- This chunk type is in the content chunk category. *length* MUST
+ This chunk type is in the content chunk category. *length* **MUST**
be exactly 12. It represents that the contents of *hole size*
- bytes starting at *offset* read as all zeroes. The hole MUST
+ bytes starting at *offset* read as all zeroes. The hole **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
+ 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`.
The payload is structured as:
64 bits: offset (unsigned)
- 32 bits: hole size (unsigned, MUST be nonzero)
+ 32 bits: hole size (unsigned, **MUST** be nonzero)
* `NBD_OPT_STRUCTURED_REPLY`
@@ -991,124 +997,124 @@ error, and alters the reply to the `NBD_CMD_READ` request.
The server replies with the following:
- `NBD_REP_ACK`: Structured replies have been negotiated; the
- server MUST use structured replies to the `NBD_CMD_READ`
+ 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.
It is envisioned that future extensions will add other new
requests that may require a data payload in the reply. A server
- that supports such extensions SHOULD NOT advertise those
+ that supports such extensions **SHOULD NOT** advertise those
extensions until the client negotiates structured replies; and a
- client MUST NOT make use of those extensions without first
+ client **MUST NOT** make use of those extensions without first
enabling the `NBD_OPT_STRUCTURED_REPLY` extension.
* `NBD_FLAG_SEND_DF`
- The server MUST set this transmission flag to 1 if the
+ The server **MUST** set this transmission flag to 1 if the
`NBD_CMD_READ` request supports the `NBD_CMD_FLAG_DF` flag, and
- MUST leave this flag clear if structured replies have not been
- negotiated. Clients MUST NOT set the `NBD_CMD_FLAG_DF` request
+ **MUST** leave this flag clear if structured replies have not been
+ negotiated. Clients **MUST NOT** set the `NBD_CMD_FLAG_DF` request
flag unless this transmission flag is set.
* `NBD_CMD_FLAG_DF`
- The "don't fragment" flag, valid during `NBD_CMD_READ`. SHOULD be
+ The "don't fragment" flag, valid during `NBD_CMD_READ`. **SHOULD** be
set to 1 if the client requires the server to send at most one
- content chunk in reply. MUST NOT be set unless the transmission
- flags include `NBD_FLAG_SEND_DF`. Use of this flag MAY trigger an
+ content chunk in reply. **MUST NOT** be set unless the transmission
+ flags include `NBD_FLAG_SEND_DF`. Use of this flag **MAY** trigger an
`EOVERFLOW` error chunk, if the request length is too large.
* `EOVERFLOW`
- The server SHOULD return `EOVERFLOW`, rather than `EINVAL`, when a
+ The server **SHOULD** return `EOVERFLOW`, rather than `EINVAL`, when a
client has requested `NBD_CMD_FLAG_DF` for a length that is too
- large to read without fragmentation. The server MUST NOT return
+ large to read without fragmentation. The server **MUST NOT** return
this error if the read request did not exceed 65,536 bytes, and
- SHOULD NOT return this error if `NBD_CMD_FLAG_DF` is not set.
+ **SHOULD NOT** return this error if `NBD_CMD_FLAG_DF` is not set.
* `NBD_CMD_READ`
If structured replies were not negotiated, then a read request
- MUST always be answered by a simple reply, as documented above
+ **MUST** always be answered by a simple reply, as documented above
(using magic 0x67446698 `NBD_SIMPLE_REPLY_MAGIC`, and containing
length bytes of data according to the client's request, although
- those bytes MAY be invalid if an error is returned, and the
- connection MUST be closed if an error occurs after a header
+ those bytes **MAY** be invalid if an error is returned, and the
+ connection **MUST** be closed if an error occurs after a header
claiming no error).
- If structured replies are negotiated, then a read request MUST
+ If structured replies are negotiated, then a read request **MUST**
result in a structured reply with one or more chunks (each using
magic 0x668e33ef `NBD_STRUCTURED_REPLY_MAGIC`), where the final
chunk has the flag `NBD_REPLY_FLAG_DONE`, and with the following
additional constraints.
- The server MAY split the reply into any number of content chunks;
- each chunk MUST describe at least one byte, although to minimize
- overhead, the server SHOULD use chunks with lengths and offsets as
+ The server **MAY** split the reply into any number of content chunks;
+ each chunk **MUST** describe at least one byte, although to minimize
+ overhead, the server **SHOULD** use chunks with lengths and offsets as
an integer multiple of 512 bytes, where possible (the first and
last chunk of an unaligned read being the most obvious places for
- an exception). The server MUST NOT send content chunks that
- overlap with any earlier content or error chunk, and MUST NOT send
+ an exception). The server **MUST NOT** send content chunks that
+ overlap with any earlier content or error chunk, and **MUST NOT** send
chunks that describe data outside the offset and length of the
- request, but MAY send the content chunks in any order (the client
- MUST reassemble content chunks into the correct order), and MAY
+ request, but **MAY** send the content chunks in any order (the client
+ **MUST** reassemble content chunks into the correct order), and **MAY**
send additional content chunks even after reporting an error chunk.
- Note that a request for more than 2^32 - 8 bytes MUST be split
+ Note that a request for more than 2^32 - 8 bytes **MUST** be split
into at least two chunks, so as not to overflow the length field
of a reply while still allowing space for the offset of each
- chunk. When no error is detected, the server MUST send enough
+ chunk. When no error is detected, the server **MUST** send enough
data chunks to cover the entire region described by the offset and
length of the client's request.
- To minimize traffic, the server MAY use a content or error chunk
+ To minimize traffic, the server **MAY** use a content or error chunk
as the final chunk by setting the `NBD_REPLY_FLAG_DONE` flag, but
- MUST NOT do so for a content chunk if it would still be possible
+ **MUST NOT** do so for a content chunk if it would still be possible
to detect an error while transmitting the chunk. The
`NBD_REPLY_TYPE_NONE` chunk is always acceptable as the final
chunk.
- If an error is detected, the server MUST still complete the
- transmission of any current chunk (it MUST use padding bytes which
- SHOULD be zero, for any remaining data portion of a chunk with
- type `NBD_REPLY_TYPE_OFFSET_DATA`), but MAY omit further content
- chunks. The server MUST include an error chunk as one of the
- subsequent chunks, but MAY defer the error reporting behind other
+ If an error is detected, the server **MUST** still complete the
+ transmission of any current chunk (it **MUST** use padding bytes which
+ **SHOULD** be zero, for any remaining data portion of a chunk with
+ type `NBD_REPLY_TYPE_OFFSET_DATA`), but **MAY** omit further content
+ chunks. The server **MUST** include an error chunk as one of the
+ subsequent chunks, but **MAY** defer the error reporting behind other
queued chunks. An error chunk of type `NBD_REPLY_TYPE_ERROR`
- implies that the client MAY NOT make any assumptions about
+ implies that the client **MAY NOT** make any assumptions about
validity of data chunks (whether sent before or after the error
- chunk), and if used, SHOULD be the only error chunk in the reply.
+ chunk), and if used, **SHOULD** be the only error chunk in the reply.
On the other hand, an error chunk of type
`NBD_REPLY_TYPE_ERROR_OFFSET` gives fine-grained information about
which earlier data chunk(s) encountered a failure; as such, a
- server MAY still usefully follow it with further non-overlapping
+ server **MAY** still usefully follow it with further non-overlapping
content chunks or with error offsets for other content chunks.
- The server MAY send an error chunk with no corresponding content
- chunk, but MUST ensure that the content chunk is sent first if a
+ The server **MAY** send an error chunk with no corresponding content
+ chunk, but **MUST** ensure that the content chunk is sent first if a
content and error chunk cover the same offset. Generally, a
- server SHOULD NOT mix errors with offsets with a generic error.
- As long as all errors are accompanied by offsets, the client MAY
+ server **SHOULD NOT** mix errors with offsets with a generic error.
+ As long as all errors are accompanied by offsets, the client **MAY**
assume that any data chunks with no subsequent error offset are
valid, that chunks with an overlapping error offset errors are
valid up until the reported offset, and that portions of the read
that do not have a corresponding content chunk are not valid.
- A client MAY close the connection if it detects that the server
+ A client **MAY** close the connection if it detects that the server
has sent invalid chunks (such as overlapping data, or not enough
data before claiming success).
- In order to avoid the burden of reassembly, the client MAY set the
+ In order to avoid the burden of reassembly, the client **MAY** set the
`NBD_CMD_FLAG_DF` flag ("don't fragment"). If this flag is set,
- the server MUST send at most one content chunk, although it MAY
+ the server **MUST** send at most one content chunk, although it **MAY**
still send multiple chunks (the remaining chunks would be error
chunks or a final type of `NBD_REPLY_TYPE_NONE`). If the area
- being read contains both data and a hole, the server MUST use
+ being read contains both data and a hole, the server **MUST** use
`NBD_REPLY_TYPE_OFFSET_DATA` with the zeroes explicitly present.
- A server MAY reject a client's request with the error `EOVERFLOW`
+ A server **MAY** reject a client's request with the error `EOVERFLOW`
if the length is too large to send without fragmentation, in which
- case it MUST NOT send a content chunk; however, the server MUST
+ case it **MUST NOT** send a content chunk; however, the server **MUST**
support unfragmented reads in which the client's request length
does not exceed 65,536 bytes.
--
1.9.1
Reply to: