Backups, Updates & Maintenance¶

The router is the one box where a bad change takes the whole network down. A recent config backup turns "rebuild from scratch" into "restore and reboot." This page covers backing up, updating, and keeping OPNsense healthy.

Configuration backup¶

The entire OPNsense config is a single XML file — no databases, no scattered state.

System → Configuration → Backups.

• Download — saves config-<hostname>-<date>.xml. Do this before every significant change (firewall rules, interface changes, updates).
• Encrypt — tick the box and set a password; the download is encrypted. Do this if you store backups anywhere off-box — the config contains secrets (VPN keys, RADIUS passwords, certificates).
• Restore — upload a backup on the same page. You can restore specific areas (just firewall, just interfaces) from the "Restore areas" dropdown, or the whole config. A full restore reboots.

Snapshots (ZFS)¶

If you installed OPNsense on ZFS (the default in recent versions), you can take boot environment snapshots of the whole OS. Make one before every firmware update and every big rule or interface change. If it goes wrong, activate the previous one and reboot (or pick it at the boot menu) — separate from, and complementary to, config backups.

System → Snapshots manages them (ZFS installs only). Name them so you know what they're for later (e.g. pre-update-26.7.7) and prune old ones now and then.

Firmware updates¶

System → Firmware → Status.

Check for updates → review changelog → Update

• Minor updates (e.g. 26.7.6 → 26.7.7) — routine; apply after reading the notes. They often carry FreeBSD security fixes, so don't let them pile up. Some require a reboot (it tells you).
• Major upgrades (e.g. 26.1 → 26.7) — released twice a year, in January and July. Back up first, read the release notes for breaking changes, and do it when you can tolerate a reboot. Use the Upgrade button that appears when a major release is available.
• Plugins update from the same page (Plugins tab) — keep os-* plugins current with the base system.

How I run updates¶

Updates are not automatic here. A firewall that reboots itself at a bad moment takes the whole network with it. Instead:

1. A small poller on one of the servers checks for a newer OPNsense release every few hours and posts to my notification topic.
2. I run the update by hand with a script that refuses major versions, takes a pre-update-<version> snapshot, updates, waits for the reboot, and then checks DNS, the WAN path, Tailscale and the nightly config backup before reporting success.
3. Majors get read-the-release-notes treatment and a planned window.

Rollback: System → Snapshots → activate the pre-update-… snapshot → reboot.

Health & monitoring¶

• Dashboard — at-a-glance CPU, memory, interfaces, gateway status, services.
• Reporting → Insight — long-term traffic graphs per interface.
• Reporting → Health — system metrics (CPU, memory, disk, temperature) over time.
• Firewall → Log Files → Live View — real-time allow/deny (see Firewall).
• Interfaces → Overview — link state, throughput, and the Tailscale interface IP.

For homelab-wide monitoring I don't run a metrics stack for the firewall. A poller on a server, using a read-only API user (dashboard, system status, firewall statistics), checks every few minutes and only reports on a change: an unexpected reboot, WAN down (pinging public IPs through the firewall), System Status errors, disk / memory / pf state table filling up, the GUI certificate nearing expiry, and the firewall's Tailscale node going offline. It also pushes to an Uptime Kuma push monitor, so a dead poller is noticed too. Firewall logs go to a remote syslog receiver for history.

Console menu (out-of-band)¶

Physical console or SSH gives the emergency menu — useful when the web UI is unreachable:

A sane maintenance rhythm¶

• Before any change: download a config backup (or rely on os-git-backup).
• Monthly: apply minor firmware + plugin updates during a quiet window.
• Twice a year: plan the major-version upgrade after reading release notes.
• Off-box: keep at least one recent encrypted backup somewhere that survives the router dying.

Here, a server pulls config.xml every night through the API (a dedicated user that can only read the configuration history) plus the AdGuard Home config file, and both ride along in the normal encrypted server backups.

Lessons learned¶

Things that were easy to miss until they bit.

• Not everything is in config.xml. Some plugins, especially third-party ones such as the AdGuard Home plugin, keep their settings in their own files under /usr/local/, so a config backup (and os-git-backup) doesn't include them. Find out where each plugin stores its config and back that up separately, or export it from the plugin's own UI.
• Turn gateway monitoring on. With monitoring disabled on the WAN gateway, OPNsense can't tell you the uplink is down (and can't fail over). Enable it under System → Gateways → Configuration and pick a reliable monitor IP.
• Don't log the default pass rule. Logging every allowed packet fills the filter log so fast that only the last hour or so is kept, and the blocks you actually want to see get buried. Log block rules and the few pass rules you care about, and send logs to a remote syslog server (System → Settings → Logging → Remote) if you want history.
• Give monitoring scripts their own read-only user. Create a dedicated user with only the privileges the script needs and an API key for it, instead of reusing the root key. If the key leaks it can read status, not change your firewall.
• Scripts can lock you out. Repeated failed logins (a script with a wrong password in a retry loop) trigger the login lockout. Make scripts log in once and stop on failure.
• Remove what you don't use. Every plugin is attack surface and RAM. If you tried something (traffic analysers with their own databases, old DHCP backends, trial security plugins) and stopped using it, uninstall it rather than just disabling it.
• Snapshot before you change rules, not only before updates. On ZFS installs, create a boot environment snapshot (System → Snapshots) before a big firewall or interface change, so a mistake that cuts off your access can be rolled back from the console.
• Plan for power loss. A firewall that cold-boots several times in a day (rack-wide power blips) is a hint you need a UPS, and a check that everything comes back by itself.

Sources & further reading¶

• OPNsense — Backups
• OPNsense — Updates
• OPNsense — Snapshots (boot environments)