Automated Renewal & Expiry Alerts
Renew deployed certificates and push the replacement without an operator, and warn your teams before anything expires.
Renewal and redeploy policies
A renewal policy is bound to one deploy target: an F5 BIG-IP, a FortiGate, an agent-managed Windows IIS or Active Directory LDAPS host, or another target of the deployment connectors. Once a certificate has been deployed to that target, Cockpit renews it before it expires and pushes the replacement through the same connector.
What happens every hour
Find the deployed certificate
The latest successful deployment to the target gives the certificate it serves and the configuration used to push it. If nothing has been deployed yet, the policy waits.
Decide whether it is due
The certificate is due when it expires within the policy's threshold (1 to 365 days). The threshold is capped at half the certificate's lifetime: a 30-day threshold on a 47-day certificate acts as 23.5 days, on a 7-day certificate as 3.5 days, so a short-lived replacement is never immediately due again. Revoked certificates are never renewed; expired ones that are still deployed are.
Wait for deployments in flight
If a deployment to the target is still running (for example a Windows agent has not collected it yet), the renewal waits instead of issuing another certificate.
Issue the replacement
The policy's CA issues a certificate with the same subject, SANs and validity span, and the same key type (or the key algorithm set on the policy).
Redeploy
The replacement is pushed through the original path: the F5 or FortiGate connector, a new agent job for Windows targets, or the generic connector.
Record and alert
Success is recorded in the activity log and the audit log (with the certificate it replaces). A failure is recorded with its error and retried after 1 hour, then 2, 4, … up to 24 hours. After the policy's maximum number of retries (1 to 10), the policy is paused for manual intervention and a "renewal needs attention" alert goes to the tenant's alert channels (and to ServiceNow as an incident when that connector is configured). Saving the policy again resumes it.
Several Cockpit replicas can run the same schedule: each attempt is claimed atomically, so a certificate is renewed once.
Configure a policy
On PKI > Deploy, click the auto-renew badge of a target. The dialog shows the certificate currently deployed, when its renewal becomes due, whether the threshold was capped, whether a deployment is in flight and, after failures, when the next attempt may run.
| Field | Range | Meaning |
|---|---|---|
| Enabled | on / off | A disabled policy is kept but ignored |
| Renew threshold (days) | 1 to 365 | Renew when the certificate expires within this many days (capped at half its lifetime) |
| Max retries | 1 to 10 | Failed attempts before the policy pauses |
| Issuing CA | a CA of the tenant | CA that signs the replacement |
| Replacement key type | same as current, ECDSA P-256 / P-384 / secp256k1, RSA-2048 / 4096 | Key algorithm of the replacement |
Rollback
A renewal is an ordinary deployment job, so it can be rolled back from PKI > Deploy > Deployment jobs like a manual deployment (permission Operations.Pki.Deploy.Rollback): F5 re-binds the previous certificate, FortiGate restores the previous binding, and Windows targets get an agent job that removes the deployed certificate. If the older certificate is still due, the next run renews it again: disable the policy first.
Limits
- Only certificates issued by a Cockpit CA with a platform-managed key are renewed (the deployment needs the private key). Certificates from external issuers and certificates issued over ACME are renewed by their client or issuer, not by this worker.
- The superseded certificate is neither removed from the target nor revoked.
- Post-quantum and composite certificates are not renewed by policies.
- Renewal history is shown in the activity and audit logs, not in a dedicated panel.
API
| Method and path | Permission |
|---|---|
GET /api/pki/deploy/renewal-policies | Operations.Pki.Deploy.Read |
GET /api/pki/deploy/targets/{id}/renewal-policy | Operations.Pki.Deploy.Read |
PUT /api/pki/deploy/targets/{id}/renewal-policy | Operations.Pki.Deploy.ConfigureTarget |
DELETE /api/pki/deploy/targets/{id}/renewal-policy | Operations.Pki.Deploy.ConfigureTarget |
GET .../renewal-policy returns the policy and a preview of the deployed certificate (expiry, effective threshold, due date, in-flight deployment, next attempt).
Expiry alerts
Each tenant can warn its teams before certificates expire, by e-mail and through its webhooks (Microsoft Teams, Slack, Rocket.Chat or a generic JSON endpoint). Alerts are off until a tenant administrator enables them on PKI > Alerts.
What is watched
- Issued certificates: every active, unrevoked certificate issued by the tenant's CAs.
- Discovered certificates (optional, on by default): certificates found by the network scanners and agents, tracked by fingerprint, so a certificate seen on many hosts or in many scans alerts once.
Certificates that have already expired are shown on the dashboards, not alerted.
Thresholds
Thresholds are days before expiry, by default 30, 14, 7, 1 (up to 8 values between 1 and 365). The check runs every hour. Each certificate is alerted once per threshold, at the tightest threshold already crossed: a certificate first seen 5 days before expiry alerts once (7-day threshold), not also for 30 and 14. A renewed certificate has a new expiry date, so its own thresholds alert again. A restart, a re-run or several replicas never re-send an alert.
Channels
| Channel | How |
|---|---|
| One digest per run to up to 20 recipients (up to 200 certificates listed, the rest counted). Sent through the tenant's own SMTP relay; without one, the platform relay delivers only to users of the tenant | |
| Microsoft Teams, Slack, Rocket.Chat, generic webhook | Event cert.expiry_warning, delivered to every webhook of the tenant that subscribes to "Certificate expiring soon" (Administration > Webhooks). Teams and Slack receive a card; generic webhooks receive JSON, HMAC-signed when a secret is set |
| Renewal failures | When a renewal policy pauses, the same recipients and webhooks receive a "renewal needs attention" alert (event cert.renewal_failed) |
Up to 25 per-certificate webhook events are sent per run, the rest in one summary event. A per-certificate event carries:
{
"title": "Certificate expires in 6 day(s): www.example.com",
"common_name": "www.example.com",
"source": "issued",
"certificate_id": "…",
"serial_number": "…",
"host": null,
"not_after": "2026-10-21T10:00:00+00:00",
"days_remaining": 6,
"threshold_days": 7
}Webhook addresses are checked against private, loopback, link-local and cloud-metadata targets when they are saved and again before each delivery (on-premises installations can allow internal targets explicitly). Teams and Slack webhooks must use HTTPS, redirects are not followed, and webhook addresses and secrets are never written to logs. Each delivery attempt appears in the webhook's delivery history.
Settings and permissions
Viewing needs Operations.Pki.ExpiryAlerts.Read; changing settings or sending a test alert needs Operations.Pki.ExpiryAlerts.Configure. Both are granted to the Admin role and can be given to other roles.
{
"is_enabled": true,
"thresholds_days": [30, 14, 7, 1],
"email_enabled": true,
"email_recipients": ["[email protected]"],
"webhook_enabled": true,
"include_discovered": true
}| Method and path | Purpose |
|---|---|
GET / PUT /api/pki/expiry-alerts/settings | Read / change the settings |
POST /api/pki/expiry-alerts/test | Send a test alert |
GET /api/pki/expiry-alerts/history | The 100 most recent alerts |
Limits
- Recipients are per tenant, not per certificate owner or per CA.
- Up to 5,000 certificates per source are examined per run, soonest expiry first.
- A webhook event published just before a restart can be lost (the alert is still recorded as sent).
- Certificates issued over ACME are not yet covered (see Short-Lived Certificates).