doc: switch to modern syntx for VNC TLS setup
PATCH 1/1 doc: switch to modern syntx for VNC TLS setup
The use of 'tls', 'x509' and 'x509verify' properties is the legacy backcompat syntx, replaced by use of TLS creds objects.
--- qemu-doc.texi | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-)
qemu-doc.texi +15 -5
@@ -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
Signature · 1 line
2.17.0
Ping, anyone have comments on this, besides the typo in $SUBJECT, also repeated in commit msg
Quoted 65 lines · 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é <[email protected]>--- qemu-doc.texi | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-)qemu-doc.texi +15
-5@@ -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_saslSignature · 1 line
2.17.0
Regards,
Daniel
Signature · 3 lines
|: 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 :|
Quoted 2 lines · Daniel P. Berrangé
Ping, anyone have comments on this, besides the typo in $SUBJECT, also repeated in commit msg
Not at all.
Thanks,
Paolo
Quoted 19 lines · Daniel P. Berrangé
Ping, anyone have comments on this, besides the typo in $SUBJECT, also repeated in commit msg
Quoted 15 lines · 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é <[email protected]>--- qemu-doc.texi | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-)qemu-doc.texi +0
-0@@ -1097,7 +1097,9 @@ support provides a secure session, but no authentication. This allows any client to connect, and provides an encrypted session.
Quoted 4 lines
qemu-doc.texi support provides a secure session, but no authentication. This allows any · line 1101
Quoted 4 lines
qemu-doc.texi +2
-1@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).
Quoted 13 lines
Quoted 13 lines
qemu-doc.texi +4
-1+ -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.
Quoted 4 lines
qemu-doc.texi only be readable by the user owning it. · line 1123
Quoted 4 lines
qemu-doc.texi +2
-1@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.
Signature · 3 lines
Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org
Quoted 10 lines · Eric Blake
Quoted 7 lines
Quoted 7 lines
(quoted diff) +2
-2-qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] \ + -objecttls-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
Quoted 1 line
Quoted 1 line
Quoted 1 line
+ -vnc :1,tls-creds=tls0 -monitor stdio
Quoted 12 lines · Paolo Bonzini
Quoted 10 lines · Eric Blake
Quoted 7 lines
Quoted 7 lines
(quoted diff) +2
-2-qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] \ + -objecttls-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).
Quoted 3 lines
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.
Signature · 3 lines
Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org
Quoted 26 lines · Eric Blake
Quoted 8 lines · Paolo Bonzini
Quoted 7 lines · Eric Blake
Quoted 7 lines
Quoted 7 lines
(quoted diff) +2
-2-qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] \ + -objecttls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no
Quoted 8 lines
Quoted 4 lines
Quoted 1 line
Quoted 1 line
\
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
Quoted 7 lines
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
Quoted 12 lines · Paolo Bonzini
Quoted 10 lines · Eric Blake
Quoted 7 lines
Quoted 7 lines
(quoted diff) +2
-2-qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] \ + -objecttls-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).
Quoted 1 line
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.
Quoted 1 line
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
Signature · 3 lines
|: 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 :|
Quoted 6 lines · Daniel P. Berrangé
Yeah, in this case I'd rather stick with single dash, for consistency, since this example is not applicable to non-system emulators anyway.
Quoted 1 line
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