Re: [PATCH v3] doc: Define a standard URI syntax for NBD URIs.
On Tue, Sep 03, 2019 at 09:42:05AM -0500, Eric Blake wrote:
> On 6/11/19 6:53 AM, Richard W.M. Jones wrote:
> > 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 | 171 ++++++++++++++++++++++++++++++++++++++++++++++++
> > 2 files changed, 172 insertions(+), 1 deletion(-)
>
> Are we ready to commit this? There were some discussions about whether
> to recognize/reserve any additional query parameters, but consensus
> seemed to be that was just over-engineering at this point.
This has been on my to-do for too long. I think we really should drop
all the tls parameter stuff to keep it simple (can add it back later
of course).
I'll share the current commit with you in a moment and you can
run with it if you have time.
Rich.
> > +++ b/doc/uri.md
>
> > +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.
>
> Well, not the NUL character.
>
> Do we need to worry about normalization issues? That is, a server with
> an export named 'a//b/../c' might be normalized by URI parsers into
> 'a/c'. Maybe we should adjust the NBD spec to recommend against the
> use of export names that could be altered during traditional file name
> normalization?
>
>
> > +## 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.
> > +
> > +* `tls-hostname`: The optional TLS hostname to use for certificate
> > + verification. This can be used when connecting over a Unix domain
> > + socket since there is no hostname available in the URI authority
> > + field; or when DNS does not properly resolve the server's 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.
>
> Authority
>
> > +
> > +## Other NBD URI query parameters
> > +
> > +Clients SHOULD prefix experimental query parameters using `x-`. This
> > +SHOULD NOT be used for query parameters which are expected to be
> > +widely used.
> > +
> > +Any other query parameters which the client does not understand 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` or `nbds+unix`).
> >
>
> --
> Eric Blake, Principal Software Engineer
> Red Hat, Inc. +1-919-301-3226
> Virtualization: qemu.org | libvirt.org
>
--
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-df lists disk usage of guests without needing to install any
software inside the virtual machine. Supports Linux and Windows.
http://people.redhat.com/~rjones/virt-df/
Reply to: