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