OPNsense plugins: a package collection where the list itself tells you what is dying

An optional package mechanism, not a fork

The plugins collection offers users and developers a way to quickly build additions for OPNsense that can be optionally installed. As soon as they are upstreamed they will become available to everyone through the firmware GUI pages.

That sentence describes the whole model, and it is worth slowing down on the second half. A plugin is not installed by a user copying files onto a firewall. It is built in this repository, upstreamed, and then it appears in the OPNsense firmware's graphical installer. The user experience is a package manager, and the difference between an upstreamed plugin and a local one is whether everyone gets it.

The list of what a plugin may do is the API surface of the system, and it reads like a summary of the operating system's extension points.

Plugins can modify the menu, access control lists and look and feel, through themes. They can add additional server software and their respective GUI pages. They can create new authentication methods to be used within other subsystems, which is the interesting one, because that means a plugin can be a login backend for the firewall itself. They can provide other types of devices and interfaces to the firewall, which is how a plugin adds a new kind of network interface. They can pull in additional packages that will update automatically, which is the dependency management story. They can enhance the backend services with additional work tasks, allow custom start, stop and early scripts, and make persistent /boot/loader.conf modifications. And they can add additional themes for the web GUI.

The last item on that list is a good illustration of the philosophy. A plugin that writes to /boot/loader.conf is making a persistent change to the boot process of a firewall, and the collection explicitly supports that. This is a system where the extension mechanism is trusted to that degree, which is also why the licensing and review of individual plugins matters more here than it would for a typical application plugin.

Reading the list, because the annotations are the interesting part

The README carries a full inventory of currently available plugins, organised by category, and the categories are directories in the repository itself: benchmarks, databases, devel, dns, emulators, ftp, mail, misc, net, net-mgmt, security, sysutils, vendor and www.

The value of that list is not the plugins themselves, which are mostly well known software, but the annotations attached to them. Several carry an explicit not maintained marker: net/igmp-proxy, whose entry says the IGMP-Proxy Service is not maintained, net/wol for Wake on LAN, net/zerotier for Virtual Networks That Just Work, sysutils/dmidecode for displaying hardware information on the dashboard, sysutils/lcdproc-sdeclcd, sysutils/nextcloud-backup, sysutils/smart for SMART tools, www/OPNProxy for proxy additions, www/squid for the caching proxy, and www/web-proxy-sso for Kerberos authentication.

Other entries carry a dependency on something you have to buy. security/intrusion-detection-content-et-pro is the IDS Proofpoint ET Pro ruleset and needs a valid subscription, and security/intrusion-detection-content-snort-vrt is the IDS Snort VRT ruleset and needs registration or subscription. security/intrusion-detection-content-et-open is the complementary open subset for the ET Pro telemetry edition, and there are parallel packages for the Positive Technologies ESC ruleset and for anti-phishing rules.

The content packages are where a firewall admin has to be careful, because the difference between a maintained ruleset and an unsupported one is a security property rather than a convenience.

A few more entries are worth reading for what they reveal about the collection's scope. devel/grid_example and devel/helloworld are both described as a sample framework application, so there is an example skeleton for writing one. vendor/sunnyvalley is a vendor repository for Zenarmor, described as an enterprise SASE and SSE platform with NGFW, SWG, CASB, ZTNA and SD-WAN, so the collection is not limited to upstream free software. www/c-icap connects the web proxy with a virus scanner, www/caddy is a modern reverse proxy with automatic HTTPS, dynamic DNS and Layer 4 routing, and security/tailscale is a VPN mesh securely connecting clients using WireGuard, with security/netbird as a peer-to-peer alternative and security/tor and security/openconnect alongside.

A bmake Makefile that discovers the plugins itself

The build system in the repository is unusual, and it tells you the shape of the project better than any documentation would.

The Makefile is not GNU make. It uses the .for loop syntax of bmake, the BSD make, and it discovers the plugin directories by listing the tree at build time.

_CATEGORIES!=	ls -1d [a-z0-9]*
CATEGORIES?=	${_CATEGORIES}

.for CATEGORY in ${CATEGORIES}
_${CATEGORY}!=	ls -1d ${CATEGORY}/*
PLUGIN_DIRS+=	${_${CATEGORY}}
.endfor

The categories are the top level directories, and the plugin directories are their children. A new plugin is therefore added by creating a directory, and the build picks it up, with no manifest to edit at the top level. The list target then walks the plugin directories and asks each one for its description.

list:
.for PLUGIN_DIR in ${PLUGIN_DIRS}
	@echo ${PLUGIN_DIR} -- $$(${MAKE} -C ${PLUGIN_DIR} -v PLUGIN_COMMENT)

Each plugin directory is a self-contained build that exposes a PLUGIN_COMMENT variable, and the list target reads it. That is why the README inventory reads the way it does, in path, dash dash, description form, and it is generated rather than written by hand.

The rest of the tree follows the same logic. Mk/ holds the included make fragments, with defaults.mk, common.mk and git.mk pulled in, and the top level also has Keywords/, Scripts/ and Templates/, which are the shared assets that plugins draw on. The presence of a Templates/ directory is the clue to how a plugin adds a GUI page: there is a template for it rather than each plugin inventing its own.

The copyright header in the Makefile is by Franco Fichtner, and it carries the two clause BSD text that matches the BSD-2-Clause licence recorded for the repository.

Themes and web proxies, the parts people notice first

The theme plugins are the most visible category and they are worth reading as a group, because they show how the look and feel extension point works.

There are six of them. misc/theme-advanced is a theme based on the AdvancedTomato GUI, misc/theme-cicada is described as the cicada theme with dark grey onyx, misc/theme-flexcolor is a theme with three different colour schemes, black as default plus light and dark-light, misc/theme-rebellion is a suitably dark theme, misc/theme-tukan is the tukan theme in blue and white, and misc/theme-vicuna is the vicuna theme in blue sapphire.

The descriptions read as one line each, which is the point of the plugin model. A theme plugin changes the look and feel and nothing else, and it does so through the extension point rather than by replacing the interface. A firewall with a web GUI is a product surface that a lot of users care about, and the fact that six independent themes exist and can be switched is evidence that the mechanism works.

The web proxy category is the other place where the collection meets daily administration. www/nginx is the Nginx HTTP server and reverse proxy, www/squid is the caching proxy for the web and is marked not maintained, www/caddy is the modern reverse proxy with automatic HTTPS, dynamic DNS and Layer 4 routing, www/cache is a webserver cache, www/OPNProxy provides proxy additions and is marked not maintained, and www/web-proxy-sso is a Kerberos authentication module that is also marked not maintained.

The pattern across both categories is the same. The list tells you what state each piece is in, and the state varies. A theme is cheap to maintain and safe to install. A reverse proxy in front of your web traffic is not, and three of the proxy related entries are explicitly not maintained.

Where installing a package on a firewall is a different decision

The usual argument for putting a feature in a firewall is that the traffic never leaves. The usual argument against is that the firewall is the one box you cannot take offline to debug.

Plugins in this collection make that trade explicit. Some are small and self contained, a network traffic monitor, a Wake on LAN service, a DNS proxy. Some are substantial, a full mail relay in Postfix, a web server, a RADIUS server, a Hypervisor guest agent, a TURN server, a collector for Elasticsearch, and a real time monitoring stack in netdata.

That range is the point of the collection and also its risk. A plugin that adds a package which updates automatically is a plugin that will pull new versions of that package onto your firewall without you reading a changelog, and the README lists that as a supported capability rather than a caveat.

Two entries in the list are worth reading closely for that reason. security/clamav is an antivirus engine for detecting malicious threats, and security/crowdsec is a lightweight and collaborative security engine, whose value depends on its blocklists and its community feed rather than on the plugin code. And vendor/sunnyvalley is not a set of upstream packages at all but a vendor repository for a commercial SASE product, which is a different kind of relationship from the rest of the list.

The honest framing is that this collection is a convenience and a community contribution channel. It is not a supply chain you should treat as the same as the base firmware, and the annotations in the list are the only tool the project gives you for telling the two apart.

Editorial conclusion

OPNsense plugins fit an OPNsense administrator who needs a specific piece of software on the firewall and does not want to build a package for it, and it fits a developer who wants to add a capability to OPNsense without maintaining a fork of the whole system. It does not fit a team that wants a supported product, since the collection is community maintained and the repository has no releases to pin. Check three things before you install anything from it. Check the annotation on the specific plugin, because several are explicitly marked not maintained, including net/zerotier, net/wol, net/igmp-proxy, sysutils/smart, sysutils/dmidecode, www/squid and www/web-proxy-sso, and an unmaintained package on a firewall is a liability. Check whether the plugin needs a subscription, since the intrusion detection content packages for the Proofpoint ET Pro ruleset and the Snort VRT ruleset both require a valid subscription or registration. And check the licence, which is BSD-2-Clause for the collection, while the software each plugin pulls in carries its own terms. The last push was on 2026-10-14, the repository has no GitHub releases, and the default branch is master.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-2-Clause
3. opnsense/plugins on GitHub
4. Project website
5. README