Certificate Sync for OPNsense: Renew Once, Every Firewall Follows

Renewing a wildcard certificate across twelve OPNsense firewalls takes an afternoon. On each box you import the new certificate, point the web GUI, the OpenVPN server and the IPsec tunnel at it, and restart what needs restarting, copying the private key from machine to machine along the way. Miss one firewall and it serves an expired certificate until someone notices. Internal CAs have the same problem: the root CA that your directory’s LDAPS or your VPN clients depend on gets imported by hand, box by box, and nobody can say which firewalls have the current one.

NetDefense now syncs CAs and certificates into the trust store of every firewall you manage, and renews them in place.

One wildcard certificate on every firewall

Put the private key in a secret variable. Redirect the file into it: the CLI’s no-echo prompt reads a single line, so it can’t take a PEM key.

Build the snippet. jq -Rs reads the certificate file as one string and escapes its line breaks for JSON. key names the variable, never the key itself.

Attach it to a template and sync:

Every firewall the template reaches now lists Wildcard example.com under System > Trust > Certificates. Select it once on each box for the web GUI, the OpenVPN server or the IPsec connection. NetDefense doesn’t bind services; it keeps what you bound current.

In the web app, the same snippet comes from Snippets → + Create Snippet → Create from scratch, type Trust Certificate. Paste the PEM, name the key variable, and the form writes the JSON.

Renewal: two updates, no re-binding

When the certificate is renewed with a new key, update the key variable and the certificate back to back:

A sync that runs between the two updates fails with TRUST_KEY_MISMATCH, and every firewall keeps its current certificate and key. A half-renewed pair never reaches a box. In the web app, Replace certificate (PEM) on the snippet’s page swaps in the new certificate; then edit the key variable.

On the next sync, each firewall replaces the certificate in place. OPNsense keeps the certificate’s internal reference (its refid), so the web GUI, OpenVPN and IPsec stay bound without anyone touching them. The agent then reloads what uses the certificate. We checked each one on lab firewalls:

Captive portal zones restart too. A setting that NetDefense doesn’t know how to reload is reported, so you can restart it yourself. A sync with nothing new reloads nothing.

A certificate of its own for each firewall

Hostname certificates take one snippet and an override per firewall. Create the organization-level variables first, because an override can only exist under one, then override both for each device:

Each firewall gets its own pair under the same name, and an override of the secret key variable is secret too. A firewall without overrides gets the organization’s pair. Overrides at OU or template scope work the same way, for one certificate per site.

Override both variables wherever you override one. A firewall with only a new certificate fails its build with TRUST_KEY_MISMATCH instead of receiving a mismatched pair.

An internal CA, trusted everywhere

Sync the root and the issuing CA as two TRUST_CA snippets. A CA is synced without its private key.

Each change rebuilds the firewall’s system trust store, so LDAPS to your directory, and anything else on the firewall that verifies against that store, trusts what the root signs. Intermediate CAs join the store only when OPNsense’s Store intermediate setting is on, so the root is the one that matters there.

A CA renews in place only with the same subject and key. Moving to a new CA needs a new subject name, such as Corp Root CA G2, in a new snippet. OPNsense matches a certificate to its issuer by name, so two CAs with the same name and different keys can’t coexist, and NetDefense refuses the pair with TRUST_CA_DN_CONFLICT.

Guardrails

• Only a Superuser writes. Creating, changing or deleting a certificate snippet takes a Superuser signed in interactively, and so does saving any variable it uses. A personal access token is refused even when a Superuser created it, so a leaked CI token can’t swap a certificate or slip in a CA.
• The key stays where you put it. A private key pasted into snippet content is refused, certificates can’t be pulled from a firewall into a snippet, and errors, task results and logs carry names, never key material. After our lab run, a sweep of device logs, task results and control-plane logs found zero traces of the test keys. Once deployed, the key sits in the firewall’s configuration like any OPNsense certificate key: anyone with root on the box, a full-access remote session included, can read it, and the firewall’s configuration backups carry it.
• Bad material is refused before it reaches a firewall. NetDefense checks every certificate and key when it builds a device’s configuration. A key that doesn’t belong to its certificate fails with TRUST_KEY_MISMATCH, and the firewall keeps what it has. The same happens to an encrypted key, an RSA-1024 key, or a certificate posing as a CA.
• Hand-made objects are never touched. NetDefense changes only what it created. A certificate someone added by hand under the same name is reported with NAME_COLLISION_UNMANAGED and left as it is.
• The agent never trusts a CA you sync. The firewall’s services trust it; the agent’s own connection to NetDefense is checked only against roots built into the agent. In our lab, an endpoint posing as NetDefense with a certificate from a synced CA was refused.

Limits

• Unencrypted private keys only. openssl pkey removes a passphrase.
• RSA from 2048 to 4096 bits (CAs up to 8192), or EC on P-256, P-384 or P-521.
• No CRLs, and no issuing or ACME: bring certificates issued elsewhere.
• Binding a service to a certificate stays on the firewall.

Getting started

Each firewall needs agent 1.21.0 or later, OPNsense 26.1.11 or later, and Allow All Snippet Content turned on (Services → NetDefense → Settings, Advanced Settings, Configuration Sync, then Apply). Authoring takes a Superuser. From the command line, use the CLI 1.37.0 or later; the web app already has it.

The Certificates guide covers the rest: removal, high availability and every error code.