Plugin abandonment and alternatives — when the maintainer walks away

OPNsense plugins are maintained by individual contributors and, in some cases, by the core team. The maintenance is voluntary. When the maintainer’s priorities change, the job changes, or the maintainer loses interest, the plugin is abandoned — not officially, not with a press release, but with a silent GitHub repository that stops accepting commits and a forum thread that goes unanswered. The operator who does not recognise abandonment early is the operator who discovers, at the next major upgrade, that the plugin is incompatible with the new firmware and will not be made compatible.

This lesson covers the signs of abandonment, the risk profile of running an unmaintained plugin, the fork-or-replace decision, and the migration runbook when the replacement is the disciplined choice.

Recognising abandonment

A plugin is in trouble when one or more of the following signals appear:

1. The GitHub repository has no commits in 12+ months. The plugin still installs, but no one is fixing the bugs that surface.
2. The issue tracker fills up with unanswered bug reports. Pull requests sit unmerged.
3. The OPNsense compatibility matrix does not list the latest release. The plugin still claims to support an older release.
4. The forum thread for the plugin goes quiet. Other operators stop posting because the maintainer has stopped responding.
5. The plugin’s package in pkg is not updated alongside the OPNsense firmware. A major OPNsense upgrade ships without a corresponding plugin update.

A plugin showing one of these signals is not yet abandoned. A plugin showing three or more is on the path to abandonment. The operator’s job is to notice the trajectory before the next major upgrade, when the trajectory turns into a brick.

The risk profile of an unmaintained plugin

An unmaintained plugin in production carries three concrete risks:

The risk is bounded for plugins that perform non-critical functions (a UI widget, a logging helper). The risk is unbounded for plugins that sit on the data path (a VPN endpoint, an IDS, a load balancer). The operator’s job is to weight the risk against the cost of migration.

The fork-or-replace decision

When a plugin is on the path to abandonment, the operator faces three choices:

1. Continue running the plugin. Accept the risk. Plan a forced migration at the next major upgrade.
2. Fork the plugin. Take the source code, set up an internal repository, and maintain it in-house.
3. Replace the plugin. Migrate to a built-in feature or to a different plugin that is actively maintained.

The decision matrix:

Forking is a substantial commitment. The forked plugin must be rebuilt against every new OPNsense release, every new FreeBSD base, every PHP runtime change. The operator inherits the maintenance burden the original maintainer walked away from. Forking is the right choice only when the plugin is business-critical and no replacement exists.

Replacing is the right choice when a mature alternative exists. The replacement’s vetting is the same vetting the original plugin went through: maintenance status, compatibility matrix, exit path, footprint. The operator is, in effect, repeating the install lifecycle for the replacement.

Migrating from an abandoned plugin

The migration from an abandoned plugin to a replacement follows the plugin lifecycle’s configure and retire phases, with one additional step: the configuration transfer.

The migration runbook:

1. Document the current configuration. Export the abandoned plugin’s configuration section from the XML (<plugin-name> element). Save it as the migration baseline.
2. Install the replacement plugin. Follow the vetting and install lifecycle. In lab first.
3. Map the configuration. The replacement may not have a 1:1 mapping for every option. Map the abandoned plugin’s settings to the replacement’s settings. Identify any options that do not have an equivalent.
4. Configure the replacement. Apply the mapped configuration in lab.
5. Run parallel for one week. Both plugins active, both feeding the same data. Compare output.
6. Switch the data path. Reconfigure the firewall to use the replacement as the active path.
7. Retire the abandoned plugin. Follow the retire discipline.
8. Take a post-migration backup. The XML reflects the replacement only.

The parallel run is the critical step. The operator who switches the data path without a parallel run discovers incompatibilities only when production traffic hits them.

$ xmllint --xpath '//os-iperf/*' /conf/backup/config-2026-08-15.xml

<port>5201</port>
<enabled>1</enabled>
<restrict>192.0.2.0/24</restrict>

When the plugin is replaced by a built-in feature

The cleanest abandonment is when the OPNsense core team absorbs the plugin into the base system. The operator’s job is to migrate the configuration from the plugin’s XML section to the built-in equivalent.

The pattern:

1. Read the OPNsense release notes for the absorption. The notes describe the migration path.
2. Identify the configuration items in the plugin’s XML section. Each item maps to a built-in option (or does not, in which case the operator chooses a replacement).
3. Apply the built-in configuration through the GUI. The GUI’s standard pages for the absorbed feature.
4. Uninstall the plugin. The plugin’s package can be removed once the built-in configuration is in place.
5. Verify the firewall. The feature should be functionally equivalent after the migration.

A typical example is os-wireguard, which was absorbed into the OPNsense core as built-in WireGuard. The plugin’s configuration (interface, peers, keys) does not migrate automatically; the operator must re-create the built-in WireGuard configuration manually, then uninstall os-wireguard.

Summary

• Plugin abandonment is silent. Watch the signals.
• Unmaintained plugins carry upgrade incompatibility, unpatched vulnerability, and bit rot.
• Fork when critical and irreplaceable. Replace when a mature alternative exists.
• Migrate with a parallel run, not a cutover.
• Built-in absorption requires manual configuration mapping.
• Retire the abandoned plugin only after the replacement is verified.