Re: [Qemu-devel] [PATCH v2] docs: update information for TLS certificate management

[Eric Blake]

On 01/25/2018 11:09 AM, Daniel P. Berrangé wrote:
> From: "Daniel P. Berrange" <address@hidden>
> 
> The current docs for TLS assume only VNC is using TLS. Some of the information
> is also outdated (ie lacking subject alt name info for certs). Rewrite it to
> more accurately reflect the current situation.
> 
> Signed-off-by: Daniel P. Berrange <address@hidden>
> ---
> 
> Changed in v2:
> 
>  - Much content editting  / fixes (Eric)

Does it count if I find "editing" typos in the part that doesn't land in
git? :)

> address@hidden Configuring SASL mechanisms
> +
> +The following documentation assumes use of the Cyrus SASL implementation on a
> +Linux host, but the principals should apply to any other SASL implementation
> +or host. When SASL is enabled, the mechanism configuration will be loaded 
> from
> +system default SASL service config /etc/sasl2/qemu.conf. If running QEMU as 
> an
> +unprivileged user, an environment variable SASL_CONF_PATH can be used to make
> +behaviour suddenly changedit search alternate locations for the service 
> config.

s/suddenly changedit/change to/?  Not sure if that's what you meant
there, or if you omitted words in addition to the space

> +The saslpasswd2 program can be used to populate the passwd.db file with
> +accounts.
> +
> +Other SASL configurations will be left as an exercise for the reader. Note 
> that
> +all mechanisms except GSSAPI, should be combined with use of TLS to ensure a

either "mechanisms, except GSSAPI," or "mechanisms except GSSAPI" (using
just one comma is wrong; the choice between the other two forms depend
on whether you want a pause for emphasis)

> +
> +Almost all network services in QEMU have the ability to use TLS for
> +session data encryption, along with x509 certificates for simple
> +client authentication. What follows is a description of how to
> +generate certificates suitable for usage with QEMU, and applies to
> +the VNC server, character devices with the TCP backend, NBD server
> +and client, and migration sever and client.

s/sever/server/


> address@hidden tls_creds_setup
> address@hidden TLS x509 credential configuration
>  
> address@hidden vnc_setup_sasl
> +QEMU has a standard mechanism for loading x509 credentials that will be
> +used for network services and clients. It requires specifying the
> address@hidden class name to the @code{-object} command line

Note that qemu accepts both -object and --object,...

> +argument for the system emulators. This also works for the helper tools
> +like @code{qemu-nbd} and @code{qemu-img}, but is named @code{--object}.

...while you are correct that other tools do not accept -object.  I
argue, as one of our bite-sized tasks, that we should just use
@code{--object} everywhere and not bother documenting the single-dash
crutch that qemu has.

https://wiki.qemu.org/BiteSizedTasks#Consistent_option_usage_in_documentation

Getting closer, and when it comes to documentation, anything is better
than nothing, so I trust that you'll fix my comments and can add:
Reviewed-by: Eric Blake <address@hidden>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

signature.asc
Description: OpenPGP digital signature