doc/uri.md

   1 # The NBD Uniform Resource Indicator (URI) format
   2
   3 ## Introduction
   4
   5 This document describes the standard URI format that clients may use
   6 to refer to an export located on an NBD server.
   7
   8 ## Convention
   9
  10 "NBD" stands for Network Block Device and refers to the protocol
  11 described in the adjacent protocol document also available online at
  12 <https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md#the-nbd-protocol>
  13
  14 "URI" stands for Uniform Resource Indicator and refers to the standard
  15 introduced in [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt) and
  16 subsequent IETF standards.
  17
  18 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
  19 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",
  20 "MAY", and "OPTIONAL" in this document are to be interpreted as
  21 described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
  22 The same words in lower case carry their natural meaning.
  23
  24 ## Related standards
  25
  26 All NBD URIs MUST also be valid URIs as described in
  27 [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt) and any subsequent
  28 IETF standards describing URIs.  This means that any parsing, quoting
  29 or encoding issues that may arise when making or parsing an NBD URI
  30 must be answered by consulting IETF standards.
  31
  32 This standard defers any question about how the NBD protocol works to
  33 the NBD protocol document available online at
  34 <https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md#the-nbd-protocol>
  35
  36 ## NBD URI components
  37
  38 An NBD URI consists of the following components:
  39
  40      +------- Scheme (required)
  41      |
  42      |            +------- Authority (optional)
  43      |            |
  44      |            |           +------- Export name (optional)
  45      |            |           |
  46      v            v           v
  47     nbd://example.com:10809/export
  48
  49     nbd+unix:///export?socket=nbd.sock
  50                            ^
  51                            |
  52                            +---- Query parameters
  53
  54 ## NBD URI scheme
  55
  56 One of the following scheme names SHOULD be used to indicate an NBD URI:
  57
  58 * `nbd`: NBD over an unencrypted or opportunistically TLS encrypted
  59   TCP/IP connection.
  60
  61 * `nbds`: NBD over a TLS encrypted TCP/IP connection.  If encryption
  62   cannot be negotiated then the connection MUST fail.
  63
  64 * `nbd+unix`: NBD over a Unix domain socket.  The query parameters
  65   MUST include a parameter called `socket` which refers to the name of
  66   the Unix domain socket.
  67
  68 * `nbds+unix`: NBD over a TLS encrypted Unix domain socket.  If
  69   encryption cannot be negotiated then the connection MUST fail.  The
  70   query parameters MUST include a parameter called `socket` which
  71   refers to the name of the Unix domain socket.
  72
  73 Other URI scheme names MAY be used but not all NBD clients will
  74 understand them or even recognize that they refer to NBD.
  75
  76 Note that using opportunistically encrypted connections (via the `nbd`
  77 or `nbd+unix` scheme) risks a protocol downgrade attack; whereas
  78 requests for a secure connection (via the `nbds` or `nbds+unix`
  79 scheme) MUST use TLS to connect.  For more details, see
  80 <https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md#security-considerations>
  81
  82 ## NBD URI authority
  83
  84 The authority field SHOULD be used for TCP/IP connections and SHOULD
  85 NOT be used for Unix domain socket connections.
  86
  87 The authority field MAY contain the `userinfo`, `host` and/or `port`
  88 fields as defined in [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt)
  89 section 3.2.
  90
  91 The `host` field may be a host name or IP address.  Literal IPv6
  92 addresses MUST be formatted in the way specified by
  93 [RFC 2732](https://www.ietf.org/rfc/rfc2732.txt).
  94
  95 If the `port` field is not present then it MUST default to the NBD
  96 port number assigned by IANA (10809).
  97
  98 The `userinfo` field is used to supply a username for certain less
  99 common sorts of TLS authentication.  If the `userinfo` field is not
 100 present but is needed by the client for TLS authentication then it
 101 SHOULD default to a local operating system credential if one is
 102 available.
 103
 104 It is up to the NBD client what should happen if the authority field
 105 is not present for TCP/IP connections, or present for Unix domain
 106 socket connections.  Options might include failing with an error,
 107 ignoring it, or using defaults.
 108
 109 ## NBD URI export name
 110
 111 If the version of the NBD protocol in use needs an export name, then
 112 the path part of the URI except for the leading `/` character MUST be
 113 passed to the server as the export name.
 114
 115 For example:
 116
 117     NBD URI                          Export name
 118     ----------------------------------------------------
 119     nbd://example.com/disk           disk
 120     nbd+unix:///disk?socket=sock     disk
 121     nbd://example.com/               (empty string)
 122     nbd://example.com                (empty string)
 123     nbd://example.com//disk          /disk
 124     nbd://example.com/hello%20world  hello world
 125
 126 Note that export names are not usually paths, they are free text
 127 strings.  In particular they do not usually start with a `/`
 128 character, they may be an empty string, and they may contain any
 129 Unicode character except NUL.
 130
 131 ## NBD URI socket parameter
 132
 133 If the scheme name indicates a Unix domain socket then the query
 134 parameters MUST include a `socket` key, referring to the Unix domain
 135 socket which on Unix-like systems is usually a special file on the
 136 local disk.
 137
 138 On platforms which support Unix domain sockets in the abstract
 139 namespace, and if the client supports this, the `socket` parameter MAY
 140 begin with an ASCII NUL character.  When the URI is properly encoded
 141 it will look like this:
 142
 143     nbd+unix:///?socket=%00/abstract
 144
 145 ## NBD URI query parameters related to TLS
 146
 147 If TLS encryption is to be negotiated then the following query
 148 parameters MAY be present:
 149
 150 * `tls-type`: Possible values include `anon`, `x509` or `psk`.  This
 151   specifies the desired TLS authentication method.
 152
 153 * `tls-hostname`: The optional TLS hostname to use for certificate
 154   verification.  This can be used when connecting over a Unix domain
 155   socket since there is no hostname available in the URI authority
 156   field; or when DNS does not properly resolve the server's hostname.
 157
 158 * `tls-verify-peer`: This optional parameter may be `0` or `1` to
 159   control whether the client verifies the server's identity.  By
 160   default clients SHOULD verify the server's identity if TLS is
 161   negotiated and if a suitable Certificate Authority is available.
 162
 163 ## Other NBD URI query parameters
 164
 165 Clients SHOULD prefix experimental query parameters using `x-`.  This
 166 SHOULD NOT be used for query parameters which are expected to be
 167 widely used.
 168
 169 Any other query parameters which the client does not understand SHOULD
 170 be diagnosed by the parser.
 171
 172 ## Clients which do not support TLS
 173
 174 Wherever this document refers to encryption, authentication and TLS,
 175 clients which do not support TLS SHOULD give an error when
 176 encountering an NBD URI that requires TLS (such as one with a scheme
 177 name `nbds` or `nbds+unix`).