Re: Simplified protocol?
On Thu, Oct 18, 2018 at 11:53:15AM +0200, Wouter Verhelst wrote:
> On Tue, Oct 16, 2018 at 11:35:45AM +0100, Richard W.M. Jones wrote:
> > On Mon, Oct 15, 2018 at 03:54:45PM -0500, Greg Gabelmann wrote:
> > > Hello,
> > >
> > > I'm interested in implementing a server for the NBD protocol (fixed
> > > newstyle) as a learning exercise. I've been reading about the protocol on
> > > NBD's github site and what I'm wondering is if there's a "simplified"
> > > version that I could implement. For example, no parallel connections, no
> > > TLS, etc. But the document is lengthy and I'm not sure which other features
> > > I can ignore safely...
> >
> > The basic newstyle protocol is quite simple, and you can definitely
> > ignore both parallel connections and TLS. Also all of the following
> > can be *ignored* in an initial implementation: NBD_CMD_DISC,
> > NBD_CMD_FLUSH, NBD_CMD_TRIM, NBD_CMD_WRITE_ZEROES, NBD_CMD_FLAG_*,
> > NBD_OPT_STARTTLS, NBD_OPT_GO, Structured Replies, Block Status,
> > Resize.
>
> I've been thinking about adding a "baseline" to the spec that any basic
> implementation should include. The above sounds like a good start,
> indeed.
So, I gave this some more thought today and came up with the below. Any
comments?
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.
+ - 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)
+ - the `NBD_CMD_DISC` message
+
+### 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.
+
+### 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
--
To the thief who stole my anti-depressants: I hope you're happy
-- seen somewhere on the Internet on a photo of a billboard
Reply to: