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 | 124 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 125 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..143954c
--- /dev/null
+++ b/doc/uri.md
@@ -0,0 +1,124 @@
+# 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.
+
+## 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 encrypted TCP/IP
+ connection.
+
+* `nbds`: NBD over an 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 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:
Testing how existing url parser treat the urls:
+
+ NBD URI export name
+ ----------------------------------------------------
+ nbd://example.com/disk disk
ParseResult(scheme='nbd', netloc='
example.com', path='/disk', params='', query='', fragment='')
+ nbd+unix:///disk disk
>>> urlparse("nbd+unix:///disk")
ParseResult(scheme='nbd+unix', netloc='', path='/disk', params='', query='', fragment='')
+ nbd://example.com/ (empty string)
ParseResult(scheme='nbd', netloc='
example.com', path='/', params='', query='', fragment='')
+ nbd://example.com (empty string)
+ nbd://example.com//disk /disk
+ nbd://example.com/hello%20world hello world
So it seems that we need to teach url parsers about removing / from nbd urls,
otherwise all users will have do this after parsing the url.
Testing how this works with qemu-nbd/qemu-img 4.0.0:
nbd+unix:
$ qemu-nbd -t -r -k /tmp/nbd.sock -x disk test.qcow2
$ qemu-img info nbd+unix:///disk?socket=/tmp/nbd.sock
(works)
nbd:
$ qemu-nbd -t -r -x disk test.qcow2
$ qemu-img info nbd://localhost/disk
(works)
But this also works:
$ qemu-img info nbd://localhost///disk
image: nbd://localhost:10809/disk
So qemu-nbd seems to normalize leading "///" to "", and there
is no way to use export name with leading /.
$ qemu-nbd -t -r -x /disk test.qcow2
$ qemu-img info nbd://localhost//disk
qemu-img: Could not open 'nbd://localhost//disk': Requested export not available
server reported: export 'disk' not present
I think we can treat this a qemu bug.
+
+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 query parameters
+
+The query part of the URI is used when connecting to Unix domain
+sockets (when the scheme name is `nbd+unix`). In this case it 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.
+
+Query parameters other than `socket` SHOULD be ignored by the parser.
--
2.21.0