DEV Community

ZeroTrust Architect
ZeroTrust Architect

Posted on • Edited on • Originally published at cacheguard.com

OPNsense Plugin Compatibility on FreeBSD: What Breaks and Why

#security #networking #opensource #bsd

OPNsense is a FreeBSD-based firewall. Reaching UTM functionality requires plugins maintained by the OPNsense community and third parties. Here is the technical picture of how those plugins integrate and where compatibility breaks down.

OPNsense Alternative

The OPNsense plugin model

OPNsense plugins are FreeBSD packages distributed via the OPNsense repository. They integrate with the core via:

  • XML configuration merging: Plugins add their configuration schema to OPNsense's central XML config file (/conf/config.xml)
  • Python backend (configd): Plugins register backend services that the PHP GUI frontend calls via a Unix socket
  • Service management: Plugins register with OPNsense's service framework for start/stop/restart operations

This is a clean integration model. The problem is that each layer can break independently.

Squid on OPNsense: the proxy stack

The os-squid plugin installs Squid from FreeBSD ports. The OPNsense GUI provides configuration for basic proxy settings. Advanced Squid features (custom ACLs, cache tuning, ssl-bump configuration) require editing Squid's config files directly — OPNsense's GUI does not expose them.

URL filtering with SquidGuard or web filtering: The primary URL filtering option is os-squidguard, which uses SquidGuard for category-based filtering. SquidGuard is a Squid URL redirector that has had limited active development in recent years. Alternatively, os-web-proxy-useracl provides some per-user ACL support.

Version coupling issue: When OPNsense updates its FreeBSD base (e.g., 13.x → 14.x), the Squid port in FreeBSD repositories may lag or have breaking changes. The OPNsense team maintains their package repository to address this, but update lag between base OS releases and plugin availability is a recurring operational concern.

ClamAV integration: the ICAP chain

ClamAV does not integrate directly with Squid. The integration path:

Squid → ICAP protocol → c-icap daemon → ClamAV daemon
Enter fullscreen mode Exit fullscreen mode

On OPNsense, this requires:

  • os-clamav: installs ClamAV
  • Manual c-icap configuration (no official OPNsense c-icap plugin — community approaches vary)
  • Squid ICAP configuration via custom options in the GUI's "Advanced" field

This is the most fragile point in the UTM stack. The c-icap → ClamAV boundary has version sensitivity: ClamAV API changes between major versions may require c-icap updates. If c-icap is not maintained for the installed ClamAV version, antivirus scanning silently fails — Squid returns 200 to ICAP requests that return errors, treating them as "scan passed."

Detecting silent ICAP failure:

# Check ICAP response on OPNsense
echo "OPTIONS icap://127.0.0.1:1344/squid_clamav ICAP/1.0\r\nHost: 127.0.0.1\r\n\r\n" | nc 127.0.0.1 1344
Enter fullscreen mode Exit fullscreen mode

A healthy response returns ICAP/1.0 200 OK. An error or no response means antivirus is not scanning traffic despite Squid believing it is.

ModSecurity: the absent plugin

OPNsense does not have an officially maintained ModSecurity plugin. Community attempts exist but are not in the official repository and have inconsistent maintenance status. WAF capability on OPNsense essentially requires running a separate Apache or Nginx instance outside the OPNsense management framework.

SSL inspection: ssl-bump complexity

OPNsense's Squid plugin supports ssl-bump (TLS interception) via the GUI, but the CA certificate management — generating the proxy CA, distributing it to clients — is manual. There is no integrated PKI in OPNsense for this purpose.

The ssl-bump configuration in Squid requires careful step ordering to handle different certificate scenarios (valid cert, expired cert, self-signed cert, pinned cert) correctly. Misconfiguration causes either security gaps (blocking too little) or browsing failures (blocking too much).

The integrated alternative

CacheGuard eliminates each of these integration points: Squid, ClamAV, the ICAP chain, ssl-bump, ModSecurity, and the PKI are all pre-integrated and version-locked in a single LFS-based OS image. There is no c-icap compatibility to manage, no FreeBSD package lag to track, no separate CA management step.

The trade-off: you cannot customise individual components. If your requirements fit the standard UTM feature set, this trades flexibility for operational reliability.

→ https://www.cacheguard.com/opnsense-alternative/

Originally published on the CacheGuard Blog. CacheGuard is free and open source — GitHub.

Top comments (0)