Problem
We have essentially no documentation for certificate lifecycle problems, even though they hit every deployment on a predictable schedule: host certificates signed by the running CA default to 5 years (the ca_ttl setting in puppet.conf, despite the name), while the CA certificate itself is created with a 15-year validity (openvox-server's ca CLI falls back to 15y when ca_ttl is unset in puppet.conf at puppetserver ca setup time). So host certs expire long before the CA. A user in the community Slack just hit exactly this ("expired MoM cert at 5 years") and there is no docs page to point them to.
Current coverage is limited to:
- The CA API reference for the renewal endpoint (
docs/_openvox-server_8x/ca-api/v1/http_certificate_renewal.md)
- A passing mention of
ca_ttl in docs/_openvox_8x/config_important_settings.markdown
Neither answers "my server/agent cert expired, what do I do?"
Proposed page
A "Renewing and regenerating certificates" how-to in the openvox-server collection covering:
- Diagnosing which cert expired — inspecting certs with
openssl x509 -in <cert>.pem -text -noout (or -enddate -noout) to compare host cert vs CA cert expiry, and why a 5-year expiry means the host cert, not the CA. This is also the place to untangle the ca_ttl naming trap: the puppet.conf setting (default 5y) controls the TTL of certs the CA signs, while the CA certificate's own 15-year validity is a fallback inside the ca CLI that is currently documented nowhere.
- Regenerating the primary server's host cert when it is also the CA — stop puppetserver, back up the ssl dir, remove the old cert/key and the copy in
ca/signed/, then puppetserver ca generate --certname <fqdn> --ca-client (works offline, signs with the existing CA, so agents are unaffected). Include the --subject-alt-names caveat for load-balanced/CNAME setups, and a note on refreshing OpenVoxDB's copies under /etc/puppetlabs/puppetdb/ssl/ when it shares the host.
- Regenerating a compiler/agent cert when the CA is elsewhere —
puppet ssl clean on the agent, revoke/clean the old cert on the CA (puppetserver ca clean), then request a fresh cert from the agent with puppet ssl bootstrap (or puppet agent -t), and sign it on the CA (with the allow-subject-alt-names note for ca.conf when alt names are present).
- Preventing recurrence with automatic renewal —
allow-auto-renewal: true and auto-renewal-cert-ttl in the certificate-authority section of ca.conf, and which agent versions support transparent renewal.
- Extending an expired (or expiring) CA without reissuing agent certs — re-sign the existing CA key with a new validity via
openssl x509 -x509toreq plus a re-sign with the CA extensions, keeping the same key and subject so existing agent certs remain valid; then distribute the refreshed ca.pem to agents and OpenVoxDB and regenerate the server's host cert. bastelfreak has a working walkthrough of this at https://gist.github.com/bastelfreak/ed874f03e7849d35eb8ec832a58da8f3 that the page can adapt (AGPL-3.0 licensed, so adapt with permission/attribution rather than copying verbatim).
Nav entry in _data/nav/ for the server collection alongside the other SSL/CA pages.
(Points 1, 3, and 5 incorporate suggestions from bastelfreak in the community Slack thread.)
Problem
We have essentially no documentation for certificate lifecycle problems, even though they hit every deployment on a predictable schedule: host certificates signed by the running CA default to 5 years (the
ca_ttlsetting in puppet.conf, despite the name), while the CA certificate itself is created with a 15-year validity (openvox-server's ca CLI falls back to15ywhenca_ttlis unset in puppet.conf atpuppetserver ca setuptime). So host certs expire long before the CA. A user in the community Slack just hit exactly this ("expired MoM cert at 5 years") and there is no docs page to point them to.Current coverage is limited to:
docs/_openvox-server_8x/ca-api/v1/http_certificate_renewal.md)ca_ttlindocs/_openvox_8x/config_important_settings.markdownNeither answers "my server/agent cert expired, what do I do?"
Proposed page
A "Renewing and regenerating certificates" how-to in the openvox-server collection covering:
openssl x509 -in <cert>.pem -text -noout(or-enddate -noout) to compare host cert vs CA cert expiry, and why a 5-year expiry means the host cert, not the CA. This is also the place to untangle theca_ttlnaming trap: the puppet.conf setting (default5y) controls the TTL of certs the CA signs, while the CA certificate's own 15-year validity is a fallback inside the ca CLI that is currently documented nowhere.ca/signed/, thenpuppetserver ca generate --certname <fqdn> --ca-client(works offline, signs with the existing CA, so agents are unaffected). Include the--subject-alt-namescaveat for load-balanced/CNAME setups, and a note on refreshing OpenVoxDB's copies under/etc/puppetlabs/puppetdb/ssl/when it shares the host.puppet ssl cleanon the agent, revoke/clean the old cert on the CA (puppetserver ca clean), then request a fresh cert from the agent withpuppet ssl bootstrap(orpuppet agent -t), and sign it on the CA (with theallow-subject-alt-namesnote forca.confwhen alt names are present).allow-auto-renewal: trueandauto-renewal-cert-ttlin thecertificate-authoritysection ofca.conf, and which agent versions support transparent renewal.openssl x509 -x509toreqplus a re-sign with the CA extensions, keeping the same key and subject so existing agent certs remain valid; then distribute the refreshedca.pemto agents and OpenVoxDB and regenerate the server's host cert. bastelfreak has a working walkthrough of this at https://gist.github.com/bastelfreak/ed874f03e7849d35eb8ec832a58da8f3 that the page can adapt (AGPL-3.0 licensed, so adapt with permission/attribution rather than copying verbatim).Nav entry in
_data/nav/for the server collection alongside the other SSL/CA pages.(Points 1, 3, and 5 incorporate suggestions from bastelfreak in the community Slack thread.)