medium riskservice affecting~60 min

Runbook: Rotate Certificates

1 · Prerequisites

Confirm every item is in place before any state change.

New certificate and private key generated and signed by the CA
Maintenance window scheduled for the affected services
Knowledge of which services depend on the certificate (GUI, IPsec, VPN, web services)
Backup of the current configuration

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

· Confirm the expiry date of the current certificate and the planned rotation date
· Identify all services that depend on the certificate
· Capture the current certificate fingerprint and the chain of trust
· Confirm the new certificate is signed by the same CA and the chain is intact

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1Open System > Trust > Certificates and click Add to import the new certificate and the new chain
2Mark the new certificate as the system default if the old certificate was the default
3For services that depend on the certificate, navigate to the relevant service (e.g. Services > IPsec > Connection Overview) and reload the service
4For the GUI certificate, navigate to System > Settings > Administration and select the new certificate; the GUI will restart on the new certificate
5For IPsec tunnels using certificate-based authentication, re-export the new certificate to the remote peer if necessary
6Verify the new certificate is presented by the service using openssl s_client -connect <host>:443 from a trusted host
7Wait for the rotation window to pass and then remove the old certificate from System > Trust > Certificates
8Update the certificate inventory with the new certificate fingerprint and the rotation date

4 · Verification

Confirm the procedure actually fixed the problem.

✓The new certificate is presented by the affected services
✓The certificate chain is intact and signed by the expected CA
✓No dependent services are failing after the rotation
✓The certificate inventory is updated with the new certificate

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶If the new certificate is not accepted, restore the old certificate from the backup
↶If a service fails to reload, restart the service from the shell with the old certificate
↶If the rotation causes a downstream outage, escalate to the dependent service team

6 · Escalation

When the runbook isn't enough, contact:

· Engage the PKI owner if the new certificate is not signed by the expected CA
· Engage the network team if the GUI certificate rotation causes a management outage
· Engage the security team if the old certificate is suspected of compromise

Purpose

Rotate the certificates used by OPNsense services (GUI, IPsec, VPN, web services) before they expire, without causing a service outage.

When to use this runbook

Use this runbook when a certificate is approaching its expiry date, when a certificate is suspected of compromise, or when a CA is being rotated.

Pre-checks

Before starting the procedure, confirm the prerequisites and pre-checks are met. The structured lists are rendered from the frontmatter by the page layout.

Procedure

Follow the steps from the frontmatter procedure steps. The page layout renders the steps as a checklist with copy-to-clipboard affordances.

Verification

After the procedure, the structured verification items from the frontmatter are rendered as a checklist.

Rollback

If the procedure fails or makes things worse, follow the structured rollback steps from the frontmatter.

Escalation

The structured escalation path is rendered from the frontmatter. Use it if the operator cannot complete the procedure safely.