Plugin management lifecycle — install, configure, update, retire

OPNsense plugins extend the firewall with features the base system does not include: intrusion detection (Suricata), web filtering, VPN variants, monitoring integrations, and dozens of niche utilities. The plugin lifecycle — discovery, vetting, install, configure, update, retire — is the discipline that keeps the firewall maintainable and the upgrade path clean. The operator who installs plugins without vetting, who never updates, who never retires, accumulates technical debt that surfaces during the next major upgrade.

This lesson covers each phase of the lifecycle, the vetting criteria, the configuration migration between plugin versions, and the dependency graph that catches the operator when a plugin depends on another.

The discovery phase

A plugin enters the operator’s awareness through one of four paths:

1. Forum recommendation. Another operator or a community thread mentions the plugin.
2. Documentation reference. The OPNsense docs reference the plugin as the way to achieve a goal.
3. Vendor integration. A vendor (e.g. a SIEM, a backup tool, a monitoring system) publishes an OPNsense integration plugin.
4. Curiosity. The operator browses the plugin repository.

The discovery phase is not a decision. The operator does not install on discovery. The operator files the candidate plugin in a “to evaluate” list and moves to the vetting phase.

The vetting phase

A plugin candidate is vetted against six criteria before it is installed in production:

The vetting answers are recorded. A plugin that fails any of the six is not installed. The exit path is the criterion most operators skip; the plugin that cannot be cleanly removed becomes a permanent fixture whether the operator wants it or not.

The vetting sources:

• The plugin’s GitHub repository (linked from opnsense.org/plugins/) — commit history, issue tracker, release notes.
• The OPNsense forum — operator reports, known issues, version compatibility notes.
• The plugin’s page on opnsense.org — official compatibility matrix.

The install phase

The install phase is performed in the lab first, then in pre-production, then in production. The progression mirrors the firmware upgrade staged rollout.

In the GUI: System → Firmware → Plugins → Search → Install. The CLI equivalent: pkg install os-<plugin-name>.

The install validates:

1. The plugin downloads and verifies. A signed package is the baseline.
2. The plugin’s dependencies install cleanly. A failure here means the plugin requires a system library that is not available — vetting should have caught this.
3. The plugin registers in the GUI. A new menu item appears under the appropriate section (Services, VPN, etc.).
4. The plugin’s service starts. The service runs as a daemon and is reachable from the GUI’s status page.

$ pkg install os-iperf

Updating OPNsense repository catalogue...
OPNsense repository is up to date.
All repositories are up to date.
The following 1 package(s) will be affected (of 0 checked):

New packages to be installed:
os-iperf: 1.2_1

The process will require 8 KiB more space.
44 KiB to be downloaded.
[1/1] Fetching os-iperf-1.2_1.txz: 100%
[1/1] Checking integrity... done (SHA256 verified)
[1/1] Installing os-iperf-1.2_1...
[1/1] Extracting os-iperf-1.2_1: 100%
After install, the iperf service must be enabled under Services → iPerf → Settings before it will start.

The configure phase

The plugin’s GUI exposes its configuration. The configuration is stored in the OPNsense XML under a plugin-specific section (<iperf> for os-iperf, <intrusiondetection> for os-suricata, etc.). The configuration is included in the regular OPNsense backups.

The configuration discipline:

1. Document the configuration in the runbook. Every non-default setting, every rule that references the plugin, every certificate the plugin uses.
2. Take a backup before every configuration change. Same discipline as firmware changes.
3. Test the configuration in lab. Plugin configurations have surprising failure modes (Suricata rules that block legitimate traffic, web filter overrides that exclude too much).
4. Roll out to pre-prod, then production. The staged rollout catches regressions.

The update phase

Plugins update independently of the firmware. The plugin’s package version advances more frequently than OPNsense itself. The update discipline:

1. Subscribe to the plugin’s release notes. GitHub releases, the plugin’s forum thread, the OPNsense blog.
2. Read the changelog before updating. The plugin changelog enumerates breaking changes, new features, and bug fixes.
3. Update in lab first. Same staged rollout as the firmware.
4. Take a backup before every update. The plugin’s configuration may not survive an incompatible update.
5. Roll the update through pre-prod, then production.

A plugin update that breaks the configuration is recoverable from the backup. A plugin update that breaks the firewall (e.g. service fails to start, kernel panic) is recoverable from the boot environment rollback.

The retire phase

A plugin reaches the retire phase when:

• The plugin is no longer maintained. The GitHub repository has been silent for 12+ months.
• The functionality is now built-in. OPNsense has absorbed the plugin’s feature into the base system.
• The business no longer needs the feature. The monitoring tool, the VPN variant, the web filter is decommissioned.
• A security advisory affects the plugin and no fix is forthcoming.

The retire discipline:

1. Document the retirement. Runbook update, change ticket, communication to stakeholders.
2. Disable the plugin’s service. Stop the daemon so it does not restart on reboot.
3. Remove the plugin’s configuration. Clean up aliases, rules, certificates that referenced the plugin.
4. Uninstall the plugin. pkg remove os-<plugin-name> or the GUI’s uninstall.
5. Reboot and verify. Confirm the plugin’s absence does not break other services.
6. Take a post-retirement backup. The backup reflects the firewall without the plugin.

The dependency graph

Some plugins depend on other plugins or on system services. The dependency graph catches the operator when a plugin removal cascades.

Common dependencies:

• Suricata depends on the system’s libnet, libpcap, and on the rule subscription. Removing Suricata does not affect the system, but removing the rule subscription without removing Suricata leaves a non-functional detector.
• HAProxy (os-haproxy) depends on the SSL library and on the certificate store. Removing HAProxy without removing its certificates leaves unused certificates.
• WireGuard plugin (os-wireguard) was the predecessor of the built-in WireGuard. Upgrading to a release that built-in WireGuard means the plugin can be removed; the configuration migration is manual.

The disciplined operator maps the dependency graph before installing or removing a plugin. pkg info -d os-<plugin> lists the dependencies.

Summary

• The plugin lifecycle is discovery → vetting → install → configure → update → retire.
• Vetting catches the plugin that becomes a brick risk later.
• Lab, pre-prod, production. Plugins follow the staged rollout.
• Backup before every plugin change. Rollback path must exist.
• Retire cleanly. Disable, remove configuration, uninstall, verify, backup.
• Map the dependency graph before install or removal.