[Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Daniel P. Berrangé]

The use of 'tls', 'x509' and 'x509verify' properties is the legacy
backcompat syntx, replaced by use of TLS creds objects.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 qemu-doc.texi | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/qemu-doc.texi b/qemu-doc.texi
index f00706b999..d526870479 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -1097,7 +1097,9 @@ support provides a secure session, but no authentication. This allows any
 client to connect, and provides an encrypted session.
 
 @example
-qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
+qemu-system-i386 [...OPTIONS...] \
+  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \
+  -vnc :1,tls-creds=tls0 -monitor stdio
 @end example
 
 In the above example @code{/etc/pki/qemu} should contain at least three files,
@@ -1112,10 +1114,14 @@ only be readable by the user owning it.
 Certificates can also provide a means to authenticate the client connecting.
 The server will request that the client provide a certificate, which it will
 then validate against the CA certificate. This is a good choice if deploying
-in an environment with a private internal certificate authority.
+in an environment with a private internal certificate authority. It uses the
+same syntax as previously, but with @code{verify-peer} set to @code{yes}
+instead.
 
 @example
-qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
+qemu-system-i386 [...OPTIONS...] \
+  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
+  -vnc :1,tls-creds=tls0 -monitor stdio
 @end example
 
 
@@ -1126,7 +1132,9 @@ Finally, the previous method can be combined with VNC password authentication
 to provide two layers of authentication for clients.
 
 @example
-qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
+qemu-system-i386 [...OPTIONS...] \
+  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
+  -vnc :1,tls-creds=tls0,password -monitor stdio
 (qemu) change vnc password
 Password: ********
 (qemu)
@@ -1163,7 +1171,9 @@ credentials. This can be enabled, by combining the 'sasl' option
 with the aforementioned TLS + x509 options:
 
 @example
-qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
+qemu-system-i386 [...OPTIONS...] \
+  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
+  -vnc :1,tls-creds=tls0,sasl -monitor stdio
 @end example
 
 @node vnc_setup_sasl
-- 
2.17.0

Re: [Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Daniel P. Berrangé]

Ping, anyone have comments on this, besides the typo in $SUBJECT,
also repeated in commit msg

On Thu, Jun 07, 2018 at 11:10:19AM +0100, Daniel P. Berrangé wrote:
> The use of 'tls', 'x509' and 'x509verify' properties is the legacy
> backcompat syntx, replaced by use of TLS creds objects.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  qemu-doc.texi | 20 +++++++++++++++-----
>  1 file changed, 15 insertions(+), 5 deletions(-)
> 
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index f00706b999..d526870479 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -1097,7 +1097,9 @@ support provides a secure session, but no authentication. This allows any
>  client to connect, and provides an encrypted session.
>  
>  @example
> -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
> +qemu-system-i386 [...OPTIONS...] \
> +  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \
> +  -vnc :1,tls-creds=tls0 -monitor stdio
>  @end example
>  
>  In the above example @code{/etc/pki/qemu} should contain at least three files,
> @@ -1112,10 +1114,14 @@ only be readable by the user owning it.
>  Certificates can also provide a means to authenticate the client connecting.
>  The server will request that the client provide a certificate, which it will
>  then validate against the CA certificate. This is a good choice if deploying
> -in an environment with a private internal certificate authority.
> +in an environment with a private internal certificate authority. It uses the
> +same syntax as previously, but with @code{verify-peer} set to @code{yes}
> +instead.
>  
>  @example
> -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
> +qemu-system-i386 [...OPTIONS...] \
> +  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
> +  -vnc :1,tls-creds=tls0 -monitor stdio
>  @end example
>  
>  
> @@ -1126,7 +1132,9 @@ Finally, the previous method can be combined with VNC password authentication
>  to provide two layers of authentication for clients.
>  
>  @example
> -qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
> +qemu-system-i386 [...OPTIONS...] \
> +  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
> +  -vnc :1,tls-creds=tls0,password -monitor stdio
>  (qemu) change vnc password
>  Password: ********
>  (qemu)
> @@ -1163,7 +1171,9 @@ credentials. This can be enabled, by combining the 'sasl' option
>  with the aforementioned TLS + x509 options:
>  
>  @example
> -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
> +qemu-system-i386 [...OPTIONS...] \
> +  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
> +  -vnc :1,tls-creds=tls0,sasl -monitor stdio
>  @end example
>  
>  @node vnc_setup_sasl
> -- 
> 2.17.0
> 

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Paolo Bonzini]

On 28/06/2018 15:17, Daniel P. Berrangé wrote:
> Ping, anyone have comments on this, besides the typo in $SUBJECT,
> also repeated in commit msg

Not at all.

Thanks,

Paolo

Re: [Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Eric Blake]

On 06/28/2018 08:17 AM, Daniel P. Berrangé wrote:
> Ping, anyone have comments on this, besides the typo in $SUBJECT,
> also repeated in commit msg
> 
> On Thu, Jun 07, 2018 at 11:10:19AM +0100, Daniel P. Berrangé wrote:
>> The use of 'tls', 'x509' and 'x509verify' properties is the legacy
>> backcompat syntx, replaced by use of TLS creds objects.
>>
>> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
>> ---
>>   qemu-doc.texi | 20 +++++++++++++++-----
>>   1 file changed, 15 insertions(+), 5 deletions(-)
>>
>> diff --git a/qemu-doc.texi b/qemu-doc.texi
>> index f00706b999..d526870479 100644
>> --- a/qemu-doc.texi
>> +++ b/qemu-doc.texi
>> @@ -1097,7 +1097,9 @@ support provides a secure session, but no authentication. This allows any
>>   client to connect, and provides an encrypted session.
>>   
>>   @example
>> -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
>> +qemu-system-i386 [...OPTIONS...] \
>> +  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \

I'd use --object here (especially since -object cannot be used on 
qemu-nbd, but --object tls-creds-x509 can).

>> +  -vnc :1,tls-creds=tls0 -monitor stdio
>>   @end example
>>   
>>   In the above example @code{/etc/pki/qemu} should contain at least three files,
>> @@ -1112,10 +1114,14 @@ only be readable by the user owning it.
>>   Certificates can also provide a means to authenticate the client connecting.
>>   The server will request that the client provide a certificate, which it will
>>   then validate against the CA certificate. This is a good choice if deploying
>> -in an environment with a private internal certificate authority.
>> +in an environment with a private internal certificate authority. It uses the
>> +same syntax as previously, but with @code{verify-peer} set to @code{yes}
>> +instead.
>>   
>>   @example
>> -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
>> +qemu-system-i386 [...OPTIONS...] \
>> +  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \

multiple times in this patch.

Otherwise looks good to me.

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

Re: [Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Paolo Bonzini]

On 28/06/2018 15:22, Eric Blake wrote:
>>>
>>> -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu
>>> -monitor stdio
>>> +qemu-system-i386 [...OPTIONS...] \
>>> +  -object
>>> tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no
>>> \
> 
> I'd use --object here (especially since -object cannot be used on
> qemu-nbd, but --object tls-creds-x509 can).

But that would be inconsistent with -vnc.

I honestly don't understand the crusade against single-dashed options.

Paolo

>>> +  -vnc :1,tls-creds=tls0 -monitor stdio 

Re: [Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Eric Blake]

On 06/28/2018 08:28 AM, Paolo Bonzini wrote:
> On 28/06/2018 15:22, Eric Blake wrote:
>>>>
>>>> -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu
>>>> -monitor stdio
>>>> +qemu-system-i386 [...OPTIONS...] \
>>>> +  -object
>>>> tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no
>>>> \
>>
>> I'd use --object here (especially since -object cannot be used on
>> qemu-nbd, but --object tls-creds-x509 can).
> 
> But that would be inconsistent with -vnc.
> 
> I honestly don't understand the crusade against single-dashed options.

Rather, it's a crusade FOR the use of --object, for consistency reasons:

These work:

qemu-system-i386 -object foo
qemu-system-i386 --object foo
qemu-nbd --object foo

but this fails:

qemu-nbd -object foo

And since --object blurbs can a) be quite long, and b) be quite useful 
for pasting between apps, then it stands to reason that our 
documentation should prefer the form that is easiest to reuse everywhere.

Meanwhile, these both work:
qemu-system-i386 -vnc
qemu-system-i386 --vnc

but as no other qemu-* binaries (currently) take a --vnc argument, it's 
a moot point as to which form the documentation should prefer for the 
purpose of pasting into other binaries.  But at the same time, 
consistency argues that if we're going to spell --object everywhere, 
then we might as well spell --vnc everywhere too.

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

Re: [Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Paolo Bonzini]

On 28/06/2018 16:46, Eric Blake wrote:
> On 06/28/2018 08:28 AM, Paolo Bonzini wrote:
>> On 28/06/2018 15:22, Eric Blake wrote:
>>>>>
>>>>> -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu
>>>>> -monitor stdio
>>>>> +qemu-system-i386 [...OPTIONS...] \
>>>>> +  -object
>>>>> tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no
>>>>>
>>>>> \
>>>
>>> I'd use --object here (especially since -object cannot be used on
>>> qemu-nbd, but --object tls-creds-x509 can).
>>
>> But that would be inconsistent with -vnc.
>>
>> I honestly don't understand the crusade against single-dashed options.
> 
> Rather, it's a crusade FOR the use of --object, for consistency reasons:
> 
> These work:
> 
> qemu-system-i386 -object foo
> qemu-system-i386 --object foo
> qemu-nbd --object foo
> 
> but this fails:
> 
> qemu-nbd -object foo
> 
> And since --object blurbs can a) be quite long, and b) be quite useful
> for pasting between apps, then it stands to reason that our
> documentation should prefer the form that is easiest to reuse everywhere.

It's also inconsistent with the rest of the command line, though, and it
may wrongly give the impression that single-character options can be
combined.

Paolo

Re: [Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Daniel P. Berrangé]

On Thu, Jun 28, 2018 at 03:28:06PM +0200, Paolo Bonzini wrote:
> On 28/06/2018 15:22, Eric Blake wrote:
> >>>
> >>> -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu
> >>> -monitor stdio
> >>> +qemu-system-i386 [...OPTIONS...] \
> >>> +  -object
> >>> tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no
> >>> \
> > 
> > I'd use --object here (especially since -object cannot be used on
> > qemu-nbd, but --object tls-creds-x509 can).
> 
> But that would be inconsistent with -vnc.

Yeah, in this case I'd rather stick with single dash, for consistency,
since this example is not applicable to non-system emulators anyway.

> I honestly don't understand the crusade against single-dashed options.

It does cause confusion in some documentation contexts with -object,
since qemu-nbd/qemu-img/qemu-io all mandated --object instead.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [Qemu-devel] [PATCH] doc: switch to modern syntx for VNC TLS setup

[Paolo Bonzini]

On 28/06/2018 18:29, Daniel P. Berrangé wrote:
> Yeah, in this case I'd rather stick with single dash, for consistency,
> since this example is not applicable to non-system emulators anyway.
> 
>> I honestly don't understand the crusade against single-dashed options.
> It does cause confusion in some documentation contexts with -object,
> since qemu-nbd/qemu-img/qemu-io all mandated --object instead.

It's okay if you're documenting --object.  But I think consistency
should win when you are showing examples for QEMU; then all options
should use either single or double dashes.

Paolo