Firmware updates and the plugin model · OPNsense

OPNsense’s update and plugin model is one of its operational strengths. Two major releases a year, signed packages, plugins that are versioned against a specific OPNsense release line, and an upgrade path that does not require a re-install. An operator who understands the model upgrades with confidence; one who does not gets surprised by ABI mismatches and botched upgrades.

This lesson covers how releases and plugins are versioned, how the plugin ABI ties a plugin to an OPNsense release, how to plan and execute a safe upgrade, and how to recover when an upgrade goes wrong.

Releases: two majors a year, signed, public

OPNsense publishes major releases in January and July. The release model:

Major releases. Numbered 25.1, 25.7, 26.1, … Each major bumps the OPNsense version, picks up a new FreeBSD base when one is available, refreshes the bundled package set, and may include GUI changes. Major releases are announced with release notes listing every behaviour change.
Security and bugfix updates. Between majors, OPNsense publishes signed security updates to the current release line (25.7.x). These updates patch the FreeBSD base, the bundled daemons, and the OPNsense framework. Security updates are cumulative within a release line.
End of life. A release line is supported for roughly six months after the next major — that is, 25.1 is supported through 25.7, and 25.7 is supported through 26.1. After that, the release receives no further security updates.

The release cadence is public, the roadmap is public, and the end-of-life dates are announced in advance. An operator plans upgrades on a quarterly schedule that aligns with the release calendar; emergency upgrades are reserved for security-critical advisories.

Read-only / Safeopnsense-update -c— opnsense-update -c checks the running release against the latest available on the configured repository. No updates available means the firewall is on the latest within its release line. To move between major releases, use opnsense-update -t opnsense-26.1 to switch the upgrade track, then opnsense-update -l 26.1 to download and apply. The -c check is safe to run at any time.

$ opnsense-update -c

Currently running: OPNsense 25.7.4
Latest stable:     OPNsense 25.7.4
Updates available: none

Illustrative output

The plugin model

OPNsense’s major optional features ship as plugins, not as part of the base image. The plugin model is deliberate: the base install is small, and an operator who enables a plugin is making a deliberate choice with an understood upgrade path.

The categories of plugin the operator encounters:

Category	Examples
VPN	`os-wireguard`, `os-strongswan` (IPsec), `os-openvpn`
Routing	`os-frr`
IDS / IPS	`os-suricata`
DNS extensions	`os-bind` (authoritative), `os-dnscrypt-proxy`
Monitoring	`os-netdata`, `os-telegraf`, `os-zabbix-agent`
Web filtering	`os-acme-client`, `os-crowdsec`, `os-url-rewrite`
Authentication	`os-totp` (MFA), `os-ldapauth`
High availability	`os-haproxy`

The plugin package name follows the convention os-<feature>. The package is installed via the GUI (System → Firmware → Plugins) or the API, and uninstalls cleanly by removing the package and the corresponding config XML entries.

Plugin ABI compatibility is per release line

A plugin is compiled against a specific OPNsense release line. The FreeBSD base version, the OPNsense framework version, and the PHP module versions all matter. When OPNsense moves to a new major release, the plugins are rebuilt against the new base. Plugins compiled against 25.7 will not load on 26.1.

When you upgrade the firewall, you must also upgrade the plugins. The OPNsense firmware update flow handles this automatically — opnsense-update and the GUI upgrade both refresh plugins as part of the same apply.

The failure mode to remember: an operator who upgrades the firewall manually but leaves a plugin on the old ABI sees the plugin refuse to start after the reboot. The fix is to upgrade the plugin package alongside the firmware. The lesson on plugin lifecycle covers this in detail.

The upgrade path in detail

A firmware upgrade follows a deterministic path. The course’s dedicated upgrade lesson covers the operational discipline; this section describes the mechanics.

Pre-flight. The framework checks free disk space (a upgrade needs space for the new root filesystem plus the running one), checks that no config apply is in progress, and verifies that the current state is consistent.
Download. The new release and the updated plugins are downloaded from the configured repository. Packages are signed; the framework verifies the signature before proceeding.
Apply. A new root filesystem (the new release) is installed alongside the current one. The boot environment is updated so the next reboot boots into the new release. The running release is unchanged at this point.
Reboot. The operator triggers a reboot (or schedules one for a maintenance window). On boot, the firewall starts the new release, runs opnsense-bootstrap, applies the configuration, and resumes forwarding.

Read-only / Safeopnsense-update -bk— opnsense-update with -b bundles and -k kernel installs a specific release. The command downloads, verifies signatures, installs into a new boot environment, and reports that a reboot is required. The running firewall is unchanged until the reboot. An operator who wants to test the upgrade without committing runs opnsense-update -bk and reboots only when ready.

$ opnsense-update -bk 25.7.5

Fetching metadata... done.
Fetching packages... done.
Installing base files... done.
Verifying checksums... done.
Updating boot environment... done.
Reboot required to apply changes.

Illustrative output

The boot environment model is a FreeBSD feature (ZFS boot environments) that OPNsense inherits. The firewall always has two root filesystems: the running one and the previous one. If the new release fails to boot, the operator can boot back into the previous one from the boot menu. This is the foundation of safe upgrades — the operator can always roll back to the last known good state.

Plugin ABI in detail

The plugin ABI is the contract between OPNsense’s framework and a plugin’s PHP code. When OPNsense’s framework changes (a new PHP version, a new MVC pattern, a renamed API endpoint), the plugin must be rebuilt. The OPNsense project maintains a plugins repository alongside the core, and rebuilds plugins against each major release.

For the operator, the consequences are:

Within a release line, plugins are compatible with the base. Security updates to the base are accompanied by security updates to the plugins.
Across release lines, plugins may need to be reinstalled (the GUI upgrade handles this). A plugin that has no release for the new OPNsense version is incompatible and will refuse to load.
A plugin that lags the base is the operator’s problem to notice. The GUI surfaces plugin compatibility state under System → Firmware → Plugins; a plugin marked “incompatible” must not be relied on until the upstream package catches up.

How opnsense-update chooses what to install

opnsense-update reads /usr/local/opnsense/version (the running version) and compares it against the configured repository’s manifest. The manifest lists every package with its version, signature, and dependencies. opnsense-update downloads the delta between the running set and the target set, verifies signatures, and lays the new packages onto a new boot environment.

The repository configuration is at /usr/local/etc/pkg/repos/ and is signed by the OPNsense project. An operator who changes the repository is opting into a different release line (e.g. switching from opnsense to opnsense-devel for the development stream) and accepts the instability that comes with it.

The plugin repository is a separate config; the OPNsense framework merges plugin updates into the same apply as the base update, so an operator sees a single coherent upgrade.

Operational discipline for safe upgrades

Five rules the course enforces:

Back up before upgrading. The GUI’s System → Configuration → Backups → Download exports the full config XML (with secrets), which is the rollback artefact. The upgrade path is otherwise forward-only; if the new release breaks the firewall in a way the operator cannot recover from in-band, the backup is the recovery path.
Read the release notes. Every major release includes behaviour changes that may affect production. The course’s upgrade lesson walks through the review checklist.
Check plugin compatibility. System → Firmware → Plugins shows the state of every installed plugin against the target release. Incompatible plugins block the upgrade until the operator uninstalls them or waits for the plugin to be rebuilt.
Test in a lab. For estates that have a lab, the operator upgrades the lab firewall first, runs the production config, and verifies behaviour before touching production.
For HA, upgrade the secondary first. The HA pair upgrade is a separate discipline covered in the HA lessons: upgrade secondary, validate, fail over, upgrade primary, fail back.

What to do when an upgrade goes wrong

Three failure modes and their recovery:

The new release fails to boot. The operator connects to the serial console or IPMI and selects the previous boot environment from the boot menu. The firewall boots into the last known good state. The operator can then investigate the new release in a lab before retrying.
The new release boots but a service fails. The operator reads the system log for the failing service, checks the release notes for the affected service, and either reconfigures the service for the new release’s expectations or rolls back to the previous boot environment.
The new release boots, services start, but production behaviour changes. The operator diffs the running config XML against the backup taken before the upgrade, identifies what changed (release notes + diff), and either adapts the config or rolls back. Rolling back is always the right default until the operator understands the change.

Summary

OPNsense releases twice a year; security updates flow within a release line. The release calendar is public.
Plugins are versioned against a specific OPNsense release line. ABI mismatches happen when a plugin lags the base.
Upgrades use ZFS boot environments. The previous release is always available as a rollback target.
The operational discipline: back up, read notes, check plugin compatibility, test in a lab, schedule the maintenance window with rollback time.