Before deploymentpre-upgrade

Pre-Upgrade Checklist

15 items ·10 critical ·4 warn ·1 info

An OPNsense firmware upgrade is a controlled reboot that touches the control plane of the network. A failed upgrade is recoverable if the rollback has been dry-run, the configuration is backed up off-box, and the change has been rehearsed on a staging firewall. This checklist covers the pre-upgrade work that turns a hopeful reboot into a planned one.

When to use

Use this checklist before every OPNsense firmware upgrade — minor, major, and security releases. It is the right checklist for the upgrade of an HA pair and for a single firewall; the HA sequencing is the only meaningful difference.

How to use

Walk the list, capture the release notes summary in the change record, take the off-box backup, schedule the maintenance window, dry-run the rollback in staging, and confirm go / no-go criteria. Anything with severity critical must be satisfied before the upgrade begins.

Critical10 items

Release notes for the target OPNsense version have been read end to end; breaking changes and migrations are noted.
```
https://docs.opnsense.org/releases.html and the per-release notes.
```
Known issues / advisories for the target version are reviewed; the operator mailing list and GitHub issues are scanned.
A full configuration backup / XML export has been taken and stored off-box.
```
System > Configuration > Backups > Download configuration.
```
A staging firewall on the same firmware version has been upgraded to the target version and validated.
Plugin compatibility: each installed plugin has a version available for the target firmware.
```
System > Firmware > Plugins; cross-check with the plugin release notes.
```
A documented rollback procedure exists: reinstall the prior image from USB / ISO and restore the prior XML export.
Maintenance window is scheduled for the production upgrade with stakeholders notified.
HA pairs: planned upgrade order is documented — primary first, validate, then secondary.
A go / no-go criterion is explicit: which tests must pass after the upgrade to consider it complete.
Console / iKVM / iLO access is available in case the post-upgrade GUI is unreachable.

Warning4 items

Backup includes plugin state and certificate store (typically captured by the same XML export).
API consumers (Ansible, monitoring, automation) are aware of API changes between versions.
Captive portal users, active VPN sessions, and long-lived flows have been notified about the reboot window.
For major upgrades (e.g. 24 → 25), a documented review of custom rule aliases and NAT entries is included.

Info1 item

Pre-upgrade baseline metrics are captured: state table, CPU, memory, interface counters, log volume.
```
pfctl -ss | wc -l; top -b -n 1; netstat -I.
```