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
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 :|
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
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
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
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
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
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 :|
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
© 2016 - 2024 Red Hat, Inc.