Runbook: certificate expiry
For on-call staff when visitors see a certificate warning, or monitoring reports a certificate close to expiry.
Contents
See what is served
From outside, for the domain the customer reported:
openssl s_client -connect www.example.com:443 -servername www.example.com </dev/null 2>/dev/null \
| openssl x509 -noout -subject -issuer -dates| You see | Meaning |
|---|---|
notAfter in the past | expired |
| an issuer equal to the subject, or a warning about a self-signed certificate | under Velocity: the configured certificate is missing, expired or does not match its key, and Velocity fell back to a self-signed one |
| a certificate for another name | the wrong virtual host or site answers; check the name-based configuration |
Under Velocity
Velocity checks a certificate before using it: "A broken or expired certificate never reaches a visitor: the pair is verified (parses, not expired, key belongs to it) before use, and a self-signed certificate stands in until the real one is usable again" (Velocity HTTPS and certificates).
Show what it serves:
php bin/php/console exp:velocity ssl show --allow-root-userRenew:
php bin/php/console exp:velocity ssl renew --apply www.example.com --allow-root-user"The running server picks a renewal up within a minute, no restart" (
exp:velocity --help).With Let's Encrypt, renewal normally needs nothing: certificates "renew in a background job with growing pauses (5 minutes doubling up to a day) after a failure". If it keeps failing, check that port 80 of the server is reachable from the internet and that DNS points to it.
With your own files (
[HTTPSSettings] CertificateandKey), put the new pair in place and check again withssl show.
Under Apache, nginx or a panel
- Renew with the tool that issued the certificate (certbot or another ACME client, or the panel's certificate feature), then reload the web server.
- Check that the renewal job runs: its timer or cron entry, its log.
- See TLS certificates in panels and TLS and HTTPS.
Note
HSTS: Velocity sends Strict-Transport-Security with HSTSMaxAge=300 by default; "a browser that has seen it
refuses plain HTTP to this host name ... for that long". Do not try to work around an expired certificate by
switching the site to plain HTTP; renew it.
After the incident
- To do: Verify from outside with
openssl s_clientagain. - To do: Add or fix certificate expiry monitoring, with a warning well before the end (Health checks and uptime).
- To do: Note in the site record which source issues the certificate and where it renews.
Related pages
- Velocity HTTPS certificates
- Velocity will not start
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.