[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Simplified protocol?

On 11/15/18 8:41 AM, Wouter Verhelst wrote:

I've been thinking about adding a "baseline" to the spec that any basic
implementation should include. The above sounds like a good start,

So, I gave this some more thought today and came up with the below. Any

diff --git a/doc/proto.md b/doc/proto.md
index b4fca69..7ff897c 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -2169,6 +2169,75 @@ written as branches which can be merged into master if and
  when those extensions are promoted to the normative version
  of the document in the master branch.
+## Compatibility and interoperability
+Originally, the NBD protocol was a fairly simple protocol with few
+options. While the basic protocol is still reasonably simple, a growing
+number of extensions has been implemented that may make the protocol
+description seem overwhelming at first.
+In an effort to not overwhelm first-time implementors with various
+options and features that may or may not be important for their use
+case, while at the same time desiring maximum interoperability, this
+section tries to clarify what is optional and what is expected to be
+available in all implementations.
+All protocol options and messages not explicitly mentioned below should
+be considered optional features that MAY be negotiated between client
+and server, but are not required to be available.
+### Baseline
+The following MUST be implemented by all implementations, and should be
+considered a baseline:
+- NOTLS mode
+- The fixed newstyle handshake
+- During the handshake:
+    - the `NBD_OPT_INFO` and `NBD_OPT_GO` messages, with the
+      `NBD_INFO_EXPORT` response.

Of the required items, this is probably the most recent addition to the standard (and therefore the most likely to be missing from older implementations); should we mention that clients should be prepared to fall back to NBD_OPT_EXPORT_NAME, or are we sufficiently long enough into the existence of this addition (and with multiple implementations that DO support it) to now make it mandatory?

+    - Servers that receive messages which they do not implement MUST
+      reply to them with `NBD_OPT_UNSUP`, and MUST NOT fail to parse
+      the next message received.
+    - the `NBD_OPT_ABORT` message, and its response.
+    - the `NBD_OPT_LIST` message and its response.
+- During the transmission phase:
+    - Simple replies
+    - the `NBD_CMD_READ` message (and its response)
+    - the `NBD_CMD_WRITE` message (and its response)

I'd add clarification: NBD_CMD_WRITE is optional if the server only exports read-only images.

+    - the `NBD_CMD_DISC` message

Do we want to require that servers SHOULD fail unknown commands with EINVAL? Or are okay with stating that a client sending a non-negotiated command is the client's fault, and it deserves whatever happens at the server.

+### Maximum interoperability
+Clients and servers that desire maximum interoperability SHOULD
+implement the following features:
+- TLS-encrypted communication, which may be required by some
+  implementations or configurations;
+- Servers that implement block constraints through `NBD_INFO_BLOCK_SIZE`
+  and desire maximum interoperability SHOULD NOT require them.
+  Similarly, clients that desire maximum interoperability SHOULD
+  implement querying for block size constraints. Since some older
+  clients default to a block size of 1024 bytes, implementations


+  desiring maximum interoperability MAY default to that size.
+- Clients or servers that desire interoperability with older
+  implementations SHOULD implement the `NBD_OPT_EXPORT_NAME` message in
+  addition to `NBD_OPT_INFO` and `NBD_OPT_GO`.
+- For data safety, implementing `NBD_CMD_FLUSH` and the
+  `NBD_CMD_FLAG_FUA` flag to `NBD_CMD_WRITE` is strongly recommended.

Is it worth mentioning 32M as a reasonable max packet size to NBD_CMD_READ/WRITE?

+### Future considerations
+The following may be moved to the "Maximum interoperability" or
+"Baseline" sections at some point in the future, but some significant
+implementations are not yet ready to support them:
+- Structured replies; the Linux kernel currently does not yet implement
+  them.
  ## About this file
This file tries to document the NBD protocol as it is currently

Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Reply to: