Re: [PATCH] docs: kbase/tlscerts: mention dropped 'encryption_key'

[Sebastian Mitterle via Devel]

On Tue, Aug 5, 2025 at 1:54 PM Daniel P. Berrangé <berra...@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 <smitt...@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 :|
>