Major version upgrades — the 25.x to 26.x leap and what it carries · OPNsense

A major OPNsense release is a different beast from a patch. The kernel changes, the PHP version changes, the plugin API shifts, the defaults can move, and the migration is rarely one-click. The operator who treats a major upgrade as a routine patch turns a quarterly maintenance task into a multi-day migration.

This lesson covers what changes between major releases, the long-form migration plan, the rollback strategy when the major upgrade fails, and the post-upgrade verification that catches the regressions that surface days or weeks later.

What changes between major releases

A major OPNsense release (e.g. 25.x → 26.x) carries four classes of change. Each class has a different risk profile and a different test requirement.

Class	Example	Risk profile
FreeBSD base bump	14.x → 15.x	Kernel change, driver updates, possibly removed drivers, possible ABI breaks
PHP runtime upgrade	PHP 8.3 → 8.4	Plugin compatibility breaks, API changes, deprecated function removals
Plugin API breakage	Removed endpoints, renamed parameters, restructured responses	API consumers break; dashboard widgets may fail to load
Default changes	New default firewall rule, new default logging, new default NTP source	Behaviour changes silently if the operator does not read the notes

The FreeBSD bump is the highest-risk change. A new kernel can drop support for a NIC, change the IRQ handling, or alter the network stack in ways that surface as throughput regressions or interface flapping. The disciplined operator reads the FreeBSD release notes alongside the OPNsense notes for any major OPNsense release that bumps the FreeBSD base.

The PHP upgrade is the second-highest-risk. OPNsense plugins are PHP. A removed function or a stricter type check can break a plugin’s logic in ways that are not visible until the firewall is in production. The disciplined operator checks every installed plugin’s compatibility with the target PHP version before upgrading.

The long-form migration plan

A major upgrade is not a 30-minute window. It is a multi-week migration with explicit phases:

Phase	Duration	Goal
1. Read and assess	1-2 weeks	Release notes read, plugin compatibility checked, breaking changes documented
2. Lab upgrade	1 week	Full upgrade in lab, every feature tested, regressions documented
3. Pre-prod upgrade	1 week	Upgrade on non-critical firewall, smoke test against production traffic patterns
4. HA standby upgrade	1 week	Upgrade the standby node, failover drill, monitor for regressions
5. Production upgrade	Scheduled window	Primary upgrade during announced window with full operator coverage
6. Post-upgrade monitoring	4 weeks	Daily health checks, regression sweep, rollback readiness maintained

The total elapsed time is 6-8 weeks. The discipline is that the production upgrade does not happen until the same release has been running on every other appliance for at least one week without issue.

DestructiveMajor upgrade — CLI— The CLI sequence to perform a major upgrade from 25.x to 26.x. The opnsense-update -t flag specifies the target release; -c confirms; the bootstrap script re-installs all packages against the new release. The reboot is required. The pre-upgrade validation has already confirmed the backup, the boot environment, the plugin compatibility, and the dependency coordination.

$ opnsense-update -t 26.1 && opnsense-update -c && /usr/local/sbin/opnsense-bootstrap.sh

Updating to OPNsense 26.1 ...
Downloading packages... done
Verifying signatures... done
Applying upgrade... done
Reboot required.

The actual GUI-driven flow uses System → Firmware → Updates → Upgrade.

Illustrative output

Rollback checkpoints

A major upgrade can fail at any of three points:

Pre-reboot failure. The upgrade packages download or verify, but the install fails (e.g. incompatible plugin, full disk). Rollback: remove the offending plugin or free disk space, re-run the upgrade.
Post-reboot failure. The firewall reboots but does not reach a usable state (e.g. interface down, GUI unreachable, ruleset failed to load). Rollback: boot menu → Boot previous. Returns to the previous BE in seconds.
Late regression. The firewall is up, traffic flows, but a feature regressed (e.g. monitoring target unreachable, IPsec tunnel re-keying fails, IDS rule no longer fires). Rollback: investigate, fix forward if possible; if not, boot menu → Boot previous.

The rollback at checkpoint 2 is the most reliable. The boot menu returns to the previous BE with the previous firmware and the previous configuration. The current BE is preserved; the operator can return to it later if the issue is resolved.

The rollback at checkpoint 3 is the hardest. The firewall is in production; rolling back means another reboot window; the regression may be intermittent and hard to attribute. The disciplined pattern is to keep the previous BE available for at least 30 days after a major upgrade, so the rollback is always an option.

Post-upgrade verification — the four-week sweep

A major upgrade is not “successful” when the firewall comes back up. It is successful when the four-week sweep finds no regressions. The sweep:

Week	Check
1	Daily: interface errors, routing table, state-table utilisation, log spam, GUI reachable
2	Every other day: IPsec tunnel re-keying, WireGuard handshake, IDS rules firing, monitoring targets responding
3	Weekly: backup verify, plugin update check, certificate expiry, NTP drift
4	Final: full DR runbook review, runbook updates, lessons-learned document

A regression that surfaces in week 2 or week 3 is the reason the sweep exists. The operator who declares success after week 1 and walks away misses the late regressions.

The migration lessons from past major upgrades

Past major OPNsense upgrades have taught the operator community several lessons:

The first patch release is safer than the first minor. 26.1.1 is more stable than 26.1.0. If the business allows, wait for the first patch before upgrading production.
Plugins lag by weeks. A major release ships with some plugins incompatible. The plugin authors catch up. Upgrading the day after the release means running on incompatible plugins.
The default changes are silent. A new default rule, a new default NTP source, a new default log retention — these do not announce themselves. The post-upgrade sweep is what catches them.
The rollback is finite. The previous BE is eventually pruned for disk space. The window for rollback is 30 days; after that, the operator must re-install.

Summary

A major release carries FreeBSD, PHP, plugin API, and default changes.
The migration plan is 6-8 weeks long, not 30 minutes.
Read both the OPNsense and FreeBSD release notes.
The boot environment is the rollback target. Keep it for 30 days.
The four-week post-upgrade sweep catches the interactions that surface late.
Wait for the first patch release if the business allows.