OPNsense Plugins

OPNsense plugins allow developers to extend the firewall's functionality. Once upstreamed, these additions become available via the firmware's GUI.

Plugins can be used to:

• Modify the menu, access control lists, and themes.
• Add additional server software and corresponding GUI pages.
• Create new authentication methods for use in other subsystems.
• Provide new device types or interfaces to the firewall.
• Pull in additional packages that support automatic updates.
• Enhance backend services with additional work tasks.
• Implement custom start, stop, or early scripts.
• Apply persistent /boot/loader.conf modifications.
• Provide additional themes for the web GUI.

The nginx plugin provides an inclusion mechanism for other plugins that need to serve data via HTTP or TCP (e.g., traffic stats, FastCGI services, or converting Unix sockets to TCP) without managing the Nginx configuration themselves.

Nginx automatically includes all .conf files located in the following directories:

• /usr/local/etc/nginx/opnsense_http_vhost_plugins/*.conf (for HTTP)
• /usr/local/etc/nginx/opnsense_stream_vhost_plugins/*.conf (for TCP/Stream)

Warning: Ensure your plugin generates valid Nginx configuration files, as invalid syntax will prevent Nginx from starting.

By default, sslh sends logs to the syslog facility. On OPNsense 22.1, these logs are sent to the audit facility.

To view logs clearly during manual execution, use the foreground option. If running as a service, you may need to use the built-in log API with a filter for sslh to isolate relevant messages. There is also a configuration setting syslog_facility: "auth"; which can be used to change the syslog destination.

While most backend endpoints follow standard OPNsense patterns, some endpoints implement custom mapping logic for features like Nginx maps (which are not supported by OPNsense core).

These specialized endpoints follow a specific lifecycle:

1. Intercept the incoming request.
2. Map the internal data.
3. Forward the resulting UUIDs to the standard *base methods.

To inject custom Nginx configuration into a specific server block, use the plugin's directory-based hooking mechanism. You can place .conf files in directories named after the server object's UUID.

Supported directory patterns:

• {UUID}_pre: Files in this directory are included before the main server block configuration.
• {UUID}_post: Files in this directory are included after the main server block configuration.

Replace {UUID} with the actual UUID of the server object.

The nginx plugin frontend uses ES6 modules and requires webpack to build. The source files include .html files which are converted into JavaScript functions using lodash templates.

To build the assets:

1. Navigate to www/nginx/src/opnsense/www/js/nginx.
2. Run npm install to install build tools and dependencies.
3. Run the webpack build command.

To debug, modify webpack.conf.js to switch the mode from production to development.

cd www/nginx/src/opnsense/www/js/nginx
npm install
node_modules/.bin/webpack-cli --config webpack.conf.js

The send_telemetry.py script sends anonymized telemetry data extracted from Suricata eve.json log files.

Anonymization Logic: To protect privacy, the script uses EventCollector._get_local_networks() and EventCollector.push() to identify local attached networks and strip the first segments of IP addresses before transmission.

Configuration: The script depends on a rule-updater.config file, which must contain the device registration token (e.g., et_telemetry.token=...) provided by OPNsense.

Default State: Persistent state and locking information are saved to /usr/local/var/run/et_telemetry.state by default.

# Example: Test telemetry using supplied test data
python send_telemetry.py -i -d 9999 -e https://endpoint -c testdata/rule-updater.config -l testdata/log/

The send_heartbeat.py script sends a small heartbeat to Proofpoint to signal that the device is still active. It can be run in --test mode to output the request and response directly to stdout.

# Example usage (replace placeholders with actual values)
python send_heartbeat.py -e <ENDPOINT_URL> -c <CONFIG_PATH>

Before running the telemetry scripts, ensure all Python dependencies are installed. The requirements are listed in requires.txt and are typically available on OPNsense by default.

pip install -r requires.txt

The SSLH plugin provides a front-end UI to manage the sslh protocol multiplexer. You can access the management interface by navigating to Services -> SSLH in the OPNsense web interface.

To successfully configure the service, you must:

1. Enable SSLH.
2. Define at least one Listen Address.
3. Define at least one Protocol Target.