From patchwork Tue Apr 5 20:42:26 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alex Bligh X-Patchwork-Id: 8755021 Return-Path: X-Original-To: patchwork-qemu-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id C43E89F3D1 for ; Tue, 5 Apr 2016 20:42:40 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 9745D202BE for ; Tue, 5 Apr 2016 20:42:39 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 4014E202AE for ; Tue, 5 Apr 2016 20:42:38 +0000 (UTC) Received: from localhost ([::1]:39187 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1anXo5-00087o-C8 for patchwork-qemu-devel@patchwork.kernel.org; Tue, 05 Apr 2016 16:42:37 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:43290) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1anXnx-00087c-Ia for qemu-devel@nongnu.org; Tue, 05 Apr 2016 16:42:31 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1anXns-0001rO-Ms for qemu-devel@nongnu.org; Tue, 05 Apr 2016 16:42:29 -0400 Received: from mail.avalus.com ([89.16.176.221]:33525) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1anXns-0001qg-BF for qemu-devel@nongnu.org; Tue, 05 Apr 2016 16:42:24 -0400 Received: by mail.avalus.com (Postfix) with ESMTPSA id 39AEDC56099; Tue, 5 Apr 2016 21:42:22 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=alex.org.uk; s=mail; t=1459888942; bh=Z9q0uGF0zyqaj654PUTs8hJw33bZleAb5egMT3X0+sU=; h=From:To:Cc:Subject:Date; b=zQh9g/BfdWKJ3LKLQ4pdK5TpeFbbzQxEH6Cz75/UqKUDpZLvCsiJ/8TIp0Cocpk4P hRsJtUhQrpLaqeJtTMU32ul0oVc7BORnpmCB2KfOoxcPOXQG4/SKe/GYv6wDiL1g6z xyDcB1nQlpwsw2v/FlNHHsv01+02L4GUF1jhMovU= From: Alex Bligh To: Eric Blake , Wouter Verhelst Date: Tue, 5 Apr 2016 21:42:26 +0100 Message-Id: <1459888946-27233-1-git-send-email-alex@alex.org.uk> X-Mailer: git-send-email 1.9.1 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 89.16.176.221 Cc: "nbd-general@lists.sourceforge.net" , "qemu-devel@nongnu.org" , Alex Bligh Subject: [Qemu-devel] [PATCHv2] Amend NBD_OPT_SELECT (now NBD_OPT_INFO) and NBD_OPT_GO documentation X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org X-Spam-Status: No, score=-6.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_HI, T_DKIM_INVALID, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Amend the NBD_OPT_SELECT and NBD_OPT_GO documentation as follows: * Change NBD_OPT_SELECT to be called NBD_OPT_INFO * Remove the 'selection' aspect of that command, so that it now merely returns information. This is to avoid the server storing state. * Allow a name to be specified on NBD_OPT_GO * Make clear the rules for default device selection * Remove the provision concerning TLS resetting device selection * Remove NBD_REP_ERR_INVALID as a reply to NBD_OPT_GO as there is now no necessity for a prior NBD_OPT_INFO * Make it clear NBD_OPT_GO is in effect a better alternative for NBD_OPT_EXPORT_NAME * Make it clear the NBD_OPT_INFO and NBD_OPT_GO are in essence the same command, save that NBD_OPT_GO puts you into transmission mode if successful. * Clarify permitted option returns outside TLS to prevent export enumeration. * Remove 'length' 32 bit quantity from NBD_OPT_SELECT (and don't copy it into NBD_OPT_GO) so it looks exactly like NBD_OPT_EXPORT_NAME bar the reply. This length is unnecessary as it's in the option header anyway. * Reorder the fields of an NBD_OPT_INFO / NBD_OPT_GO reply so the variable length elements are at the end. * Make the documentation much more concise. Signed-off-by: Alex Bligh --- doc/proto.md | 142 ++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 76 insertions(+), 66 deletions(-) Changes since v1: * Change NBD_OPT_SELECT to be called NBD_OPT_INFO * Remove the 'selection' aspect of that command, so that it now merely returns information. This is to avoid the server storing state. * Reorder the fields of an NBD_OPT_INFO / NBD_OPT_GO reply so the variable length elements are at the end. * Make the documentation much more concise. * All Erik Blake's minor modifications diff --git a/doc/proto.md b/doc/proto.md index 35a3266..d5ea465 100644 --- a/doc/proto.md +++ b/doc/proto.md @@ -344,7 +344,7 @@ of the newstyle negotiation. A major problem of this option is that it does not support the return of error messages to the client in case of problems. To - remedy this, the experimental `SELECT` extension has been + remedy this, the experimental `INFO` extension has been introduced; see below. - `NBD_OPT_ABORT` (2) @@ -377,13 +377,13 @@ of the newstyle negotiation. implementation, but was implemented by qemu so has been moved out of the "experimental" section. -- `NBD_OPT_SELECT` (6) +- `NBD_OPT_INFO` (6) - Defined by the experimental `SELECT` extension; see below. + Defined by the experimental `INFO` extension; see below. - `NBD_OPT_GO` (7) - Defined by the experimental `SELECT` extension; see below. + Defined by the experimental `INFO` extension; see below. - `NBD_OPT_STRUCTURED_REPLY` (8) @@ -417,7 +417,7 @@ during option haggling in the fixed newstyle negotiation. encoded data suitable for direct display to a human being; with no embedded or terminating NUL characters. - The experimental `SELECT` extension (see below) is a client + The experimental `INFO` extension (see below) is a client request where the extra data has a definition other than a UTF-8 message. @@ -465,12 +465,12 @@ display to the user, with no embedded or terminating NUL characters. implementation, but was implemented by qemu so has been moved out of the "experimental" section. - The experimental `SELECT` extension makes small but compatible + The experimental `INFO` extension makes small but compatible changes to the semantics of this error message; see below. * `NBD_REP_ERR_UNKNOWN` (2^31 + 6) - defined by the experimental `SELECT` extension; see below. + defined by the experimental `INFO` extension; see below. ### Transmission phase @@ -648,27 +648,42 @@ Therefore, implementors are strongly suggested to contact the fine-tune the specifications in this section before committing to a particular implementation. -### `SELECT` extension +### `INFO` extension A major downside of the `NBD_OPT_EXPORT_NAME` option is that it does not allow for an error message to be returned by the server (or, in fact, any structured message). This is a result of a (misguided) attempt to keep backwards compatibility with non-fixed newstyle negotiation. -To remedy this, a `SELECT` extension is envisioned. This extension adds +To remedy this, an `INFO` extension is envisioned. This extension adds two option requests and one error reply type, and extends one existing option reply type. -* `NBD_OPT_SELECT` +Both options have identical formats for requests and replies. The +only difference is that after a successful reply to `NBD_OPT_GO` +(i.e. an `NBD_REP_SERVER`), transmission mode is entered immediately. +Therefore these commands share common documentation. - The client wishes to select the export with the given name for use - in the transmission phase, but does not yet want to move to the - transmission phase. +* `NBD_OPT_INFO` and `NBD_OPT_GO` - Data: + `NBD_OPT_INFO`: The client wishes to get details about export with the + given name for use in the transmission phase, but does not yet want + to move to the transmission phase. - - 32 bits, length of name (unsigned) - - Name of the export + `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`. + `NBD_OPT_GO` can thus be used as a substitute for `NBD_OPT_EXPORT_NAME` + that returns errors. + + Data (both commands): + + - Name of the export (as with `NBD_OPT_EXPORT_NAME`, the length + comes from the option header). + + If no name is specified (i.e. a zero length string is provided), + this specifies the default export (if any), as with + `NBD_OPT_EXPORT_NAME`. The server replies with one of the following: @@ -676,57 +691,52 @@ option reply type. server. - `NBD_REP_ERR_TLS_REQD`: The server does not wish to export this block device unless the client negotiates TLS first. - - `NBD_REP_SERVER`: The server accepts the chosen export. In this - case, the `NBD_REP_SERVER` message's data takes on a different - 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); this layout is shared with the successful response to - `NBD_OPT_GO`. The option reply length MUST be *length of - name* + 14, and the option data has the following layout: - - - 32 bits, length of name (unsigned) - - Name of the export. This name MAY be different from the one - given in the `NBD_OPT_SELECT` option in case the server has - multiple alternate names for a single export. - - 64 bits, size of the export in bytes (unsigned) - - 16 bits, transmission flags + - `NBD_REP_SERVER`: The server accepts the chosen export. - - For backwards compatibility, clients should be prepared to also - handle `NBD_REP_ERR_UNSUP`. In this case, they should fall back to - using `NBD_OPT_EXPORT_NAME`. - -* `NBD_OPT_GO` - - The client wishes to terminate the negotiation phase and progress to - the transmission phase. Possible replies from the server include: - - - `NBD_REP_SERVER`: The server acknowledges, using the same format - for the reply as in `NBD_OPT_SELECT` (thus allowing the client - to receive the same transmission flags as would have been sent - by `NBD_OPT_EXPORT_NAME`). The values of the transmission flags - MAY differ from what was sent earlier in response to - `NBD_OPT_SELECT`, based on other options that were negotiated in - the meantime. 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 receiving - this reply, the client and the server have both moved to the - transmission phase; therefore, the server MUST NOT send this - particular reply until all other pending option requests have - had their final reply. - - `NBD_REP_ERR_INVALID`: No `NBD_OPT_SELECT` command was - previously issued during this negotiation (there is no default); - or, the most recent `NBD_OPT_SELECT` command resulted in an error - reply (selecting a different export clears the currently selected - export, even if the new export does not exist on the server); or, - the most recent `NBD_OPT_SELECT` command issued during this - negotiation occurred before TLS was successfully negotiated - (negotiating TLS clears the selected export). - - Servers MAY also choose to send `NBD_REP_ERR_TLS_REQD` rather than - `NBD_REP_ERR_INVALID` if no non-TLS exports are supported. - - Servers MUST NOT send `NBD_REP_ERR_UNSUP` as a reply to this - message if they do not also send it as a reply to the - `NBD_OPT_SELECT` message. + 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. + + In the case of `NBD_REP_SERVER`, the message's data takes on a different + 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: + + - 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 + 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 + 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 + 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 + 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 + `NBD_REP_SERVER` data, whether or not the client negotiated the + `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 + other pending option requests have been sent by the server. ### `WRITE_ZEROES` extension