[PATCH v2] doc: Define a standard URI syntax for NBD URIs.
For further information about discussion around this standard, see
this thread on the mailing list:
https://lists.debian.org/nbd/2019/05/msg00013.html
Signed-off-by: Richard W.M. Jones <rjones@redhat.com>
---
doc/Makefile.am | 2 +-
doc/uri.md | 183 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 184 insertions(+), 1 deletion(-)
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 7f0284c..fa8a4b0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1 +1 @@
-EXTRA_DIST = README proto.md todo.txt
+EXTRA_DIST = README proto.md todo.txt uri.md
diff --git a/doc/uri.md b/doc/uri.md
new file mode 100644
index 0000000..0326c67
--- /dev/null
+++ b/doc/uri.md
@@ -0,0 +1,183 @@
+# The NBD Uniform Resource Indicator (URI) format
+
+## Introduction
+
+This document describes the standard URI format that clients may use
+to refer to an export located on an NBD server.
+
+## Convention
+
+"NBD" stands for Network Block Device and refers to the protocol
+described in the adjacent protocol document also available online at
+<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md#the-nbd-protocol>
+
+"URI" stands for Uniform Resource Indicator and refers to the standard
+introduced in [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt) and
+subsequent IETF standards.
+
+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.
+
+## Related standards
+
+All NBD URIs MUST also be valid URIs as described in
+[RFC 3986](https://www.ietf.org/rfc/rfc3986.txt) and any subsequent
+IETF standards describing URIs. This means that any parsing, quoting
+or encoding issues that may arise when making or parsing an NBD URI
+must be answered by consulting IETF standards.
+
+This standard defers any question about how the NBD protocol works to
+the NBD protocol document available online at
+<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md#the-nbd-protocol>
+
+## NBD URI components
+
+An NBD URI consists of the following components:
+
+ +------- Scheme (required)
+ |
+ | +------- Authority (optional)
+ | |
+ | | +------- Export name (optional)
+ | | |
+ v v v
+ nbd://example.com:10809/export
+
+ nbd+unix:///export?socket=nbd.sock
+ ^
+ |
+ +---- Query parameters
+
+## NBD URI scheme
+
+One of the following scheme names SHOULD be used to indicate an NBD URI:
+
+* `nbd`: NBD over an unencrypted or opportunistically TLS encrypted
+ TCP/IP connection.
+
+* `nbds`: NBD over a TLS encrypted TCP/IP connection. If encryption
+ cannot be negotiated then the connection MUST fail.
+
+* `nbd+unix`: NBD over a Unix domain socket. The query parameters
+ MUST include a parameter called `socket` which refers to the name of
+ the Unix domain socket.
+
+Other URI scheme names MAY be used but not all NBD clients will
+understand them or even recognize that they refer to NBD.
+
+## NBD URI authority
+
+The authority field SHOULD be used for TCP/IP connections and SHOULD
+NOT be used for Unix domain socket connections.
+
+The authority field MAY contain the `userinfo`, `host` and/or `port`
+fields as defined in [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt)
+section 3.2.
+
+The `host` field may be a host name or IP address. Literal IPv6
+addresses MUST be formatted in the way specified by
+[RFC 2732](https://www.ietf.org/rfc/rfc2732.txt).
+
+If the `port` field is not present then it MUST default to the NBD
+port number assigned by IANA (10809).
+
+The `userinfo` field is used to supply a username for TLS
+authentication. If the `userinfo` field is not present but is needed
+by the client for TLS authentication then it SHOULD default to a local
+operating system credential if one is available.
+
+It is up to the NBD client what should happen if the authority field
+is not present for TCP/IP connections, or present for Unix domain
+socket connections. Options might include failing with an error,
+ignoring it, or using defaults.
+
+## NBD URI export name
+
+The path part of the URI except for the leading `/` character MAY be
+passed to the server as the export name.
+
+For example:
+
+ NBD URI Export name
+ ----------------------------------------------------
+ nbd://example.com/disk disk
+ nbd+unix:///disk disk
+ nbd://example.com/ (empty string)
+ nbd://example.com (empty string)
+ nbd://example.com//disk /disk
+ nbd://example.com/hello%20world hello world
+
+Note that export names are not usually paths, they are free text
+strings. In particular they do not usually start with a `/`
+character, they may be an empty string, and they may contain any
+Unicode character.
+
+NBD servers MAY restrict the export names they are able to parse (for
+example by only accepting 7 bit ASCII names). The reader should refer
+to the NBD protocol.
+
+## NBD URI socket parameter
+
+If the scheme name indicates a Unix domain socket then the query
+parameters MUST include a `socket` key, referring to the Unix domain
+socket which on Unix-like systems is usually a special file on the
+local disk.
+
+On platforms which support Unix domain sockets in the abstract
+namespace, and if the client supports this, the `socket` parameter MAY
+begin with an ASCII NUL character. When the URI is properly encoded
+it will look like this:
+
+ nbd+unix:///?socket=%00/abstract
+
+## NBD URI query parameters related to TLS
+
+If TLS encryption is to be negotiated then the following query
+parameters MAY be present:
+
+* `tls-type`: Possible values include `anon`, `x509` or `psk`. This
+ specifies the desired TLS authentication method. The client MAY
+ default to an authentication method based on which other `tls-*`
+ parameters are present.
+
+* `tls-certificates`: The path to the TLS certificates directory.
+
+* `tls-psk-file`: The path to the TLS-PSK key file.
+
+* `tls-hostname`: The TLS client hostname.
+
+* `tls-verify-peer`: This optional parameter may be `0` or `1` to
+ control whether the client verifies the server's identity. By
+ default clients SHOULD verify the server's identity if TLS is
+ negotiated and if a suitable Certificate Authorty is available.
+
+### TLS certificates directory
+
+The `tls-certificates` parameter (if used) refers to a directory
+containing the Certificate Authority (CA) certificates bundle, client
+certificate, client private key, and CA Certificate Revocation List.
+
+These are all optional except for the CA certificates bundle.
+
+The files in this directory SHOULD use the following names:
+
+ Filename Usage
+ --------------------------------------------------
+ ca-cert.pem CA certificates bundle
+ client-cert.pem Client certificate
+ client-key.pem Client private key
+ ca-crl.pem CA Certificate Revocation List
+
+## Other NBD URI query parameters
+
+Other query parameters SHOULD be ignored by the parser.
+
+## Clients which do not support TLS
+
+Wherever this document refers to encryption, authentication and TLS,
+clients which do not support TLS SHOULD give an error when
+encountering an NBD URI that requires TLS (such as one with a scheme
+name `nbds`).
\ No newline at end of file
--
2.21.0
Reply to: