[PATCH] docs: kbase/tlscerts: mention dropped 'encryption_key'
Older libvirt versions still only work if 'encryption_key' is enabled in the server and client certificates. Add a note. While at it, also add a note that after setting the certificates up, the TLS ports need to be restarted because I haven't found a mention of it elsewhere. Signed-off-by: Sebastian Mitterle <smitterl@redhat.com> --- docs/kbase/tlscerts.rst | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/kbase/tlscerts.rst b/docs/kbase/tlscerts.rst index 215d454998..a1ea4d5f21 100644 --- a/docs/kbase/tlscerts.rst +++ b/docs/kbase/tlscerts.rst @@ -213,6 +213,10 @@ clients to reach the server, both with and without domain name qualifiers. If clients are likely to connect to the server by IP address, then one or more 'ip_address' fields should also be added. +Important: If you're running a libvirt version before 11.6.0 you need to also add +``encryption_key`` to the template. Previous versions required this. + + Use the template file as input to a ``certtool`` command to sign the server certificate: @@ -299,7 +303,11 @@ briefly cover the steps. tls_www_client signing_key - and sign by doing: + + Important: If you're running a libvirt version before 11.6.0 you need to also add + ``encryption_key`` to the template. Previous versions required this. + + Create the certificate by running: :: @@ -317,10 +325,17 @@ briefly cover the steps. Troubleshooting TLS certificate problems ---------------------------------------- -failed to verify client's certificate - On the server side, run the libvirtd server with the '--listen' and - '--verbose' options while the client is connecting. The verbose log messages - should tell you enough to diagnose the problem. +* TLS socket + + After setting up your server certificates you'll have to restart the TLS socket + ``systemctl restart virtproxyd-tls.socket`` for modular daemon setup, or + ``systemctl restart libvirtd-tls.socket`` for the monolithic daemon setup. + +* failed to verify client's certificate + + On the server side, run the libvirtd server with the '--listen' and + '--verbose' options while the client is connecting. The verbose log messages + should tell you enough to diagnose the problem. You can use the virt-pki-validate shell script to analyze the setup on the client or server machines, preferably as root. It will try to point out the -- 2.50.1
On Mon, Aug 04, 2025 at 06:31:14PM +0200, Sebastian Mitterle via Devel wrote:
Older libvirt versions still only work if 'encryption_key' is enabled in the server and client certificates. Add a note.
While at it, also add a note that after setting the certificates up, the TLS ports need to be restarted because I haven't found a mention of it elsewhere.
Do this bit in a separate patch, since it is logically independant of the other change.
Signed-off-by: Sebastian Mitterle <smitterl@redhat.com> --- docs/kbase/tlscerts.rst | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-)
diff --git a/docs/kbase/tlscerts.rst b/docs/kbase/tlscerts.rst index 215d454998..a1ea4d5f21 100644 --- a/docs/kbase/tlscerts.rst +++ b/docs/kbase/tlscerts.rst @@ -213,6 +213,10 @@ clients to reach the server, both with and without domain name qualifiers. If clients are likely to connect to the server by IP address, then one or more 'ip_address' fields should also be added.
+Important: If you're running a libvirt version before 11.6.0 you need to also add +``encryption_key`` to the template. Previous versions required this.
Can we expand this Important: versions of libvirt before 11.6.0 also required the ``encryption_key`` flag in the template. This is no longer mandated since it is not applicable for use with many modern cryptographic algorithms, but it is harmless if present as it will be ignored. If compatibility with both old and new libvirt versions is required, then this extra flag must be added when creating the certificate. and likewise below
+ + Use the template file as input to a ``certtool`` command to sign the server certificate:
@@ -299,7 +303,11 @@ briefly cover the steps. tls_www_client signing_key
- and sign by doing: + + Important: If you're running a libvirt version before 11.6.0 you need to also add + ``encryption_key`` to the template. Previous versions required this. + + Create the certificate by running:
::
@@ -317,10 +325,17 @@ briefly cover the steps. Troubleshooting TLS certificate problems ----------------------------------------
-failed to verify client's certificate - On the server side, run the libvirtd server with the '--listen' and - '--verbose' options while the client is connecting. The verbose log messages - should tell you enough to diagnose the problem. +* TLS socket + + After setting up your server certificates you'll have to restart the TLS socket + ``systemctl restart virtproxyd-tls.socket`` for modular daemon setup, or + ``systemctl restart libvirtd-tls.socket`` for the monolithic daemon setup.
Simply 'start' should be sufficient, not 'restart', in terms of the .socket unit The service, however, must be restarted to pick up the new socket *if-and-only-if* it was already running ie systemctl start virtproxyd-tls.socket systemctl try-restart virtproxyd.service
+ +* failed to verify client's certificate + + On the server side, run the libvirtd server with the '--listen' and + '--verbose' options while the client is connecting. The verbose log messages + should tell you enough to diagnose the problem.
You can use the virt-pki-validate shell script to analyze the setup on the client or server machines, preferably as root. It will try to point out the -- 2.50.1
With 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 Tue, Aug 5, 2025 at 1:54 PM Daniel P. Berrangé <berrange@redhat.com> wrote:
On Mon, Aug 04, 2025 at 06:31:14PM +0200, Sebastian Mitterle via Devel wrote:
Older libvirt versions still only work if 'encryption_key' is enabled in the server and client certificates. Add a note.
While at it, also add a note that after setting the certificates up, the TLS ports need to be restarted because I haven't found a mention of it elsewhere.
Do this bit in a separate patch, since it is logically independant of the other change.
You're right, I was lazy.
Signed-off-by: Sebastian Mitterle <smitterl@redhat.com> --- docs/kbase/tlscerts.rst | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-)
diff --git a/docs/kbase/tlscerts.rst b/docs/kbase/tlscerts.rst index 215d454998..a1ea4d5f21 100644 --- a/docs/kbase/tlscerts.rst +++ b/docs/kbase/tlscerts.rst @@ -213,6 +213,10 @@ clients to reach the server, both with and without domain name qualifiers. If clients are likely to connect to the server by IP address, then one or more 'ip_address' fields should also be added.
+Important: If you're running a libvirt version before 11.6.0 you need to also add +``encryption_key`` to the template. Previous versions required this.
Can we expand this
Important: versions of libvirt before 11.6.0 also required the ``encryption_key`` flag in the template. This is no longer mandated since it is not applicable for use with many modern cryptographic algorithms, but it is harmless if present as it will be ignored. If compatibility with both old and new libvirt versions is required, then this extra flag must be added when creating the certificate.
and likewise below
I wonder, with this expanded note, would it make sense to remove this from the "Issuing server/client certificates" sections and instead move it up to the previous section "Background to TLS certificates"?
+ + Use the template file as input to a ``certtool`` command to sign the server certificate:
@@ -299,7 +303,11 @@ briefly cover the steps. tls_www_client signing_key
- and sign by doing: + + Important: If you're running a libvirt version before 11.6.0 you need to also add + ``encryption_key`` to the template. Previous versions required this. + + Create the certificate by running:
::
@@ -317,10 +325,17 @@ briefly cover the steps. Troubleshooting TLS certificate problems ----------------------------------------
-failed to verify client's certificate - On the server side, run the libvirtd server with the '--listen' and - '--verbose' options while the client is connecting. The verbose log messages - should tell you enough to diagnose the problem. +* TLS socket + + After setting up your server certificates you'll have to restart the TLS socket + ``systemctl restart virtproxyd-tls.socket`` for modular daemon setup, or + ``systemctl restart libvirtd-tls.socket`` for the monolithic daemon setup.
Simply 'start' should be sufficient, not 'restart', in terms of the .socket unit
The service, however, must be restarted to pick up the new socket *if-and-only-if* it was already running
ie
systemctl start virtproxyd-tls.socket systemctl try-restart virtproxyd.service
Perfect, I didn't know, thanks!
+ +* failed to verify client's certificate + + On the server side, run the libvirtd server with the '--listen' and + '--verbose' options while the client is connecting. The verbose log messages + should tell you enough to diagnose the problem.
You can use the virt-pki-validate shell script to analyze the setup on the client or server machines, preferably as root. It will try to point out the -- 2.50.1
With 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 Wed, Aug 06, 2025 at 12:39:34PM +0200, Sebastian Mitterle wrote:
On Tue, Aug 5, 2025 at 1:54 PM Daniel P. Berrangé <berrange@redhat.com> wrote:
On Mon, Aug 04, 2025 at 06:31:14PM +0200, Sebastian Mitterle via Devel wrote:
Older libvirt versions still only work if 'encryption_key' is enabled in the server and client certificates. Add a note.
While at it, also add a note that after setting the certificates up, the TLS ports need to be restarted because I haven't found a mention of it elsewhere.
Do this bit in a separate patch, since it is logically independant of the other change.
You're right, I was lazy.
Signed-off-by: Sebastian Mitterle <smitterl@redhat.com> --- docs/kbase/tlscerts.rst | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-)
diff --git a/docs/kbase/tlscerts.rst b/docs/kbase/tlscerts.rst index 215d454998..a1ea4d5f21 100644 --- a/docs/kbase/tlscerts.rst +++ b/docs/kbase/tlscerts.rst @@ -213,6 +213,10 @@ clients to reach the server, both with and without domain name qualifiers. If clients are likely to connect to the server by IP address, then one or more 'ip_address' fields should also be added.
+Important: If you're running a libvirt version before 11.6.0 you need to also add +``encryption_key`` to the template. Previous versions required this.
Can we expand this
Important: versions of libvirt before 11.6.0 also required the ``encryption_key`` flag in the template. This is no longer mandated since it is not applicable for use with many modern cryptographic algorithms, but it is harmless if present as it will be ignored. If compatibility with both old and new libvirt versions is required, then this extra flag must be added when creating the certificate.
and likewise below
I wonder, with this expanded note, would it make sense to remove this from the "Issuing server/client certificates" sections and instead move it up to the previous section "Background to TLS certificates"?
Yes, that would avoid the duplication. 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 :|
participants (2)
-
Daniel P. Berrangé -
Sebastian Mitterle