Upgrade process and cadence — when to upgrade, how often, and what to read first · OPNsense

OPNsense ships releases on a predictable cadence. The cadence exists to give operators a window for testing, to bound the time a known vulnerability stays unpatched, and to make upgrades boring. The operator who treats upgrades as ad-hoc — upgrading when reminded by an email, upgrading without reading the notes, upgrading all appliances on the same weekend — turns a boring maintenance task into a production incident.

This lesson covers the release cadence, the security vs feature release distinction, the staged rollout pattern, and the reading every operator must do before the upgrade button is clicked.

The OPNsense release cadence

OPNsense publishes:

Business editions (formerly “LTS” lineage) — supported for an extended window, focused on stability. Updated monthly with security and bug fixes.
Community editions — released more frequently, with newer features and kernel updates. Updated weekly to monthly.

A release carries a version (e.g. 25.7), a release date, and a set of release notes. The notes enumerate:

Security fixes (CVE references, severity, affected versions)
New features
Changed defaults
Removed features
Plugin compatibility notes
Known issues at release time
Migration steps (when a release requires manual action)

The disciplined operator reads the release notes before upgrading. The notes are the operator’s first signal of what to test, what to avoid, and what to roll back if the upgrade breaks things.

Security releases vs feature releases

Not every release carries the same risk. The disciplined cadence treats security releases and feature releases differently.

Release type	Window	Risk profile	Operator action
Security advisory	Within 7-14 days	Targeted fix, narrow scope, low regression risk	Test in pre-prod, deploy within the window
Patch release (`25.7.x`)	Within 30 days	Bug fixes, low regression risk	Test in pre-prod, deploy quarterly
Minor release (`25.x` → `25.x+1`)	Within 60-90 days	New features, possible default changes	Read release notes, test in pre-prod, deploy in staging window
Major release (`25.x` → `26.x`)	Within 90-180 days	New kernel, new PHP versions, possible breaking changes	Read release notes, full DR test, staged rollout

The 7-day security window is the floor. A disclosed CVE with public exploit code is a 7-day window regardless of the operator’s normal cadence. The 90-day minor-release window is the ceiling for features that do not block business work.

Read-only / Safeopnsense-version— The opnsense-version command prints the running version, the FreeBSD version, and the build timestamp. The operator compares this to the latest available release on opnsense.org to decide whether an upgrade is needed. The FreeBSD version is significant: a major FreeBSD version change is a kernel change and carries more risk than a patch-level OPNsense change.

$ opnsense-version -v

OPNsense 25.7.3 (amd64)
FreeBSD 14.3
Built: Fri Aug  1 12:14:02 UTC 2026

Illustrative output

The staged rollout pattern

The disciplined operator does not upgrade all appliances on the same weekend. The staged rollout catches regressions before they hit the production firewall:

Lab appliance first. The operator’s personal lab or a dedicated test bench. Full upgrade. Full test. Document any issue.
Pre-production appliance. A non-critical firewall (a branch-office appliance, a DMZ front-end) that exercises the same configuration patterns. Full upgrade. Smoke test.
Secondary production appliance. The standby node in an HA pair. Upgrade it. Confirm the HA pair stays in sync. Failover test.
Primary production appliance. After 7-14 days of stable operation on the previous appliances. Upgrade during a maintenance window. Watch the monitoring closely for 24 hours.

The staged rollout takes weeks. The discipline is that the upgrade does not land on the primary production firewall until the same release has run cleanly on every other appliance in the fleet.

Scheduling the upgrade window

The upgrade window is when the firewall is expected to be briefly unavailable. The window is sized by the upgrade type:

Upgrade type	Window length
Patch (`25.7.3` → `25.7.4`)	15-30 minutes
Minor (`25.7` → `25.7.5`)	30-60 minutes
Major (`25.x` → `26.x`)	60-120 minutes

The window is announced in advance, scheduled to avoid business-critical hours, and staffed by at least two operators — one to drive the upgrade, one to monitor the network and handle a rollback if the upgrade fails. The backup is taken immediately before the upgrade begins (see Part XL on backup strategy). The boot environment snapshot is the rollback target.

The reading checklist

Before every upgrade, the operator reads:

Release notes. The migration notes, the known issues, the breaking changes.
Security advisories. If the release is a security release, the CVE details and the affected configurations.
Plugin compatibility list. Each installed plugin’s compatibility with the new release.
Forum threads. The OPNsense forum often surfaces real-world upgrade issues before the release notes are updated.
Backwards-incompatible API changes. If the operator’s automation depends on the API, the API changelog must be checked.

The reading is the operator’s insurance. The upgrade that proceeds without reading the notes is the upgrade that turns a 30-minute maintenance window into a 4-hour incident.

Summary

OPNsense has a predictable release cadence. Security releases within 7-14 days, minor releases within 60-90 days, major releases within 90-180 days.
The release notes are part of the upgrade artefact. Read them.
The staged rollout catches regressions before production.
The upgrade window is sized by the upgrade type and staffed by two operators.
A backup is taken before every upgrade. The boot environment is the rollback target.