Pre-upgrade validation — the checklist before the reboot

The upgrade does not start when the GUI shows “Firmware update available”. The upgrade starts when the operator begins the validation. A skipped validation is the difference between a 30-minute maintenance window and a 4-hour incident.

This lesson covers the pre-upgrade validation checklist in execution order: the backup, the plugin compatibility review, the hardware headroom check, the dependency review, and the boot-environment confirmation. Every item has a pass/fail signal. The operator does not click “Upgrade” until every item passes.

The validation order

The checklist is ordered by what fails most often and what costs the most when it fails:

1. Backup restorable. A backup file that cannot be restored is not a backup.
2. Boot environment exists. The rollback path must be intact before the upgrade begins.
3. Plugin compatibility. An incompatible plugin bricks the firewall after reboot.
4. Hardware headroom. A disk that is 95% full cannot install the new firmware.
5. Dependency review. API consumers, monitoring, and external automation that depend on the firewall must be ready.
6. Change ticket open. The upgrade must be tracked.

The order matters: the operator validates the rollback path before validating anything else, because the rollback is the safety net. A failed validation at step 1 aborts the upgrade before any state is changed.

Step 1 — Backup restorable

A backup file exists on the firewall (/conf/backup/) and an off-host copy has been taken. The validation:

1. The file is not zero bytes. ls -l /conf/backup/config-*.xml | tail -1 shows a non-trivial size.
2. The XML is well-formed. xmllint /conf/backup/config-*.xml parses without errors.
3. The version tag matches. The backup’s <version> element matches the current running version.
4. The off-host copy is reachable. ssh backup-host ls -l /backups/fw-name/ shows the file.
5. The checksum matches. sha256sum of the local and remote copies produces the same hash.

A backup that fails any of the five is not a valid rollback target. The operator fixes the backup procedure (or takes a fresh backup) before proceeding.

Step 2 — Boot environment exists

OPNsense uses ZFS boot environments for rollback. The validation:

beadm list

The output shows the current boot environment (default) and any previous boot environments (25.7.2_1, etc.). The validation:

1. At least one boot environment exists. A new installation has only one. An upgraded installation has at least two.
2. The current boot environment is marked “active now”. The active BE is the one the firewall booted from.
3. The previous boot environment is mounted but not active. The previous BE is the rollback target.

If only one BE exists, the upgrade cannot rely on the BE rollback. The operator must take a manual snapshot (beadm create pre-upgrade) before proceeding.

$ beadm list

BE                  Active Mount   Space  Created
default             NR      /      2.1G  2026-07-15 09:14
25.7.2_1            -       -      1.8G  2026-07-01 14:22

Step 3 — Plugin compatibility

OPNsense plugins (os-*, intrusion-detection, etc.) are versioned against the firmware. A plugin that is not compatible with the target firmware will fail to load after the upgrade and may prevent the firewall from reaching a usable state.

The validation:

1. List installed plugins. configctl firmware list (or the GUI’s System → Firmware → Plugins page) shows every plugin with its version.
2. Compare to the target release’s plugin compatibility list. Each plugin’s page on opnsense.org lists the firmware versions it supports.
3. Identify incompatible plugins. If a plugin does not list the target firmware as supported, the upgrade must either remove the plugin first or be postponed.
4. Plan the plugin sequence. Some plugins must be removed before the upgrade and reinstalled after (e.g. os-wireguard was deprecated in favour of the built-in WireGuard in some versions).

A plugin that is installed but incompatible is a brick risk. The operator removes or postpones the upgrade.

Step 4 — Hardware headroom

The firmware upgrade downloads packages, expands them, and installs them into the new boot environment. A disk that is too full cannot complete the upgrade.

The validation:

A resource that fails the threshold is a stop signal. The operator cleans up (old boot environments, old log archives, large RRD databases) before proceeding.

Step 5 — Dependency review

The firewall is part of a system. The upgrade affects the system, not just the firewall.

The review checklist:

1. API consumers. Every script, dashboard, or tool that calls the OPNsense API must be checked against the target release’s API changelog. A removed endpoint or a renamed parameter will break the consumer.
2. Monitoring. The monitoring system (Zabbix, Prometheus, LibreNMS) polls the firewall. The polling must be paused or its thresholds adjusted for the upgrade window.
3. RADIUS/TACACS. If the firewall uses centralised authentication, the authentication server must be reachable during the upgrade. The upgrade does not change authentication, but a misconfiguration during the post-upgrade verification could lock the operator out.
4. VPN peers. IPsec and WireGuard peers must be notified of the window. A peer that is mid-tunnel during the reboot sees a brief drop. The notification avoids an investigation.
5. Logging destinations. If logs are forwarded to a remote syslog server, the upgrade does not affect the forwarding. The validation confirms the destination is still reachable.

Step 6 — Change ticket open

The upgrade must be tracked. The change ticket records:

• The target version
• The window
• The operators
• The rollback plan (boot environment + backup file)
• The validation evidence
• The post-upgrade verification results

The ticket is opened before the upgrade, updated during, and closed after the post-upgrade verification. A upgrade without a ticket is an undocumented change. The operator who runs undocumented changes cannot reconstruct the timeline when the next incident happens.

Summary

• Validation runs before the upgrade, not during.
• The backup must be reachable, well-formed, and recently drill-tested.
• The boot environment is the rollback path. Confirm it exists before upgrading.
• Incompatible plugins are a brick risk. Validate before upgrading.
• Disk space and memory headroom must be confirmed.
• Dependencies (API consumers, monitoring, peers) must be coordinated.
• Every upgrade has a change ticket.