OPNsense Plugin Development

Konten ini belum tersedia dalam bahasa Anda.

Artikel ini belum diterjemahkan. Isi berikut berbahasa Inggris. Buka versi asli bahasa Inggris.

OPNsense Plugin Development

Build and package OPNsense plugins using the MVC framework (Phalcon/PHP) and the configd backend (Python). This guide walks through creating a plugin from scratch, enhancing existing plugins, and submitting pull requests.

Source material: This guide synthesizes @mimugmail’s plugin development series (LLDP and FreeRADIUS examples) and the official OPNsense HelloWorld documentation. Updated for OPNsense 26.x (FreeBSD 14.x).

When to Build a Plugin vs. Install a Package

Approach	Use case	Complexity
Community Repo	Pre-built software (AdGuard, Grafana, Caddy)	Zero — `pkg install`
Build from Ports	Custom software, not in any repo	Medium — `tools.git`
Build a Plugin	Native OPNsense UI integration, config management, service control	Medium-High

A plugin gives you: native OPNsense web UI, config.xml integration, service start/stop/reload, and API endpoints accessible from other tools.

Architecture

┌──────────────────────────────────────────────────┐
│                 Frontend (PHP/Phalcon MVC)        │
│  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
│  │ Models   │  │ Views    │  │ Controllers    │  │
│  │ XML+PHP  │  │ .volt    │  │ Index, Api/*   │  │
│  │ (config  │  │ (HTML    │  │ (routing, JSON │  │
│  │  schema) │  │  render) │  │  API endpoints)│  │
│  └──────────┘  └──────────┘  └───────┬────────┘  │
│                                      │            │
├──────────────────────────────────────┼────────────┤
│                          Unix socket │            │
│  ┌───────────────────────────────────┴─────────┐  │
│  │          Backend (configd / Python)          │  │
│  │  ┌──────────┐  ┌────────────┐  ┌─────────┐ │  │
│  │  │ Actions  │  │ Templates  │  │ Scripts │ │  │
│  │  │ .conf    │  │ Jinja2     │  │ .py/.sh │ │  │
│  │  │ (daemon  │  │ (config    │  │ (custom │ │  │
│  │  │  control)│  │  generation)│  │  logic) │ │  │
│  │  └──────────┘  └────────────┘  └─────────┘ │  │
│  └─────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

Key principles:

PHP never calls shell commands directly. All backend work goes through configd actions.
Backend templates (Jinja2) ≠ frontend templates (Volt). They serve different layers.
Models define the data schema in config.xml. Forms define the UI. Templates generate service config files.

Prerequisites

# On your dev machine:
git clone https://github.com/opnsense/tools          # Build toolkit
git clone https://github.com/<your-user>/plugins     # Your fork of the plugins repo

# On your OPNsense test box: nothing extra needed.
# All dev files live at /usr/local/opnsense/ on the firewall.

Directory Structure

Every plugin follows this canonical layout. The package name is always prefixed os- (e.g., os-helloworld-1.4_2.pkg).

/usr/plugins/<category>/<pluginname>/
├── Makefile
├── pkg-descr
└── src/
    └── opnsense/
        ├── mvc/app/
        │   ├── controllers/OPNsense/<PluginName>/
        │   │   ├── IndexController.php          # Page routing
        │   │   ├── Api/
        │   │   │   ├── SettingsController.php    # get/set config via API
        │   │   │   └── ServiceController.php     # start/stop/reload service
        │   │   └── forms/
        │   │       └── general.xml               # UI field definitions
        │   ├── models/OPNsense/<PluginName>/
        │   │   ├── <PluginName>.php              # Model class (PHP)
        │   │   ├── <PluginName>.xml              # Data schema (config.xml mount)
        │   │   ├── ACL/ACL.xml                   # Access control list
        │   │   └── Menu/Menu.xml                 # Sidebar menu placement
        │   └── views/OPNsense/<PluginName>/
        │       └── index.volt                    # UI template (Volt)
        ├── scripts/<pluginname>/                 # Shell/Python utilities
        └── service/
            ├── conf/actions.d/
            │   └── actions_<pluginname>.conf     # configd command registry
            └── templates/OPNsense/<PluginName>/
                ├── +TARGETS                      # Template output mappings
                └── <configfile>.conf             # Jinja2 config generator

Naming convention: OPNsense/<PluginName> — VendorName/ModuleName. Case matters everywhere. PHP namespaces match directory paths exactly.

Step-by-Step: New Plugin from Scratch

1. Pick a Template Plugin

Don’t start from nothing — copy a plugin similar to what you’re building:

If you need…	Copy from…	Why
Single page, some fields	`collectd`	Simplest structure, just one form page
Multi-entry CRUD (list + add/edit/delete)	`freeradius`, `siproxd`	Grid-based with user management pattern
Diagnostics/dashboard tab	`quagga` (Diagnostics section)	Shows command output in the UI
Service with daemon control	`lldpd`	Has service start/stop + config generation

cd plugins
# Example: building a simple plugin with one config page
cp -r net-mgmt/collectd net-mgmt/mynewplugin

2. Search & Replace — The Core Loop

This is where most of the work happens. Replace ALL occurrences, case-sensitive:

Find	Replace with	Notes
`collectd` (lowercase)	`mynewplugin`	File/directory names, URLs, config paths
`Collectd` (CamelCase)	`Mynewplugin`	Class names, namespace segments

Files to check:

src/opnsense/mvc/app/models/OPNsense/Mynewplugin/*.php, *.xml
src/opnsense/mvc/app/controllers/OPNsense/Mynewplugin/*.php, Api/*.php
src/opnsense/mvc/app/views/OPNsense/Mynewplugin/*.volt
src/opnsense/service/templates/OPNsense/Mynewplugin/+TARGETS, *.conf
src/opnsense/service/conf/actions.d/actions_*.conf
src/opnsense/scripts/OPNsense/Mynewplugin/setup.sh

From mimugmail: “No knowledge of PHP needed — just search & replace. That’s all.”

3. Makefile

PLUGIN_NAME=        mynewplugin
PLUGIN_VERSION=     0.1
PLUGIN_REVISION=    1
PLUGIN_COMMENT=     My New Plugin — does something useful
PLUGIN_MAINTAINER=  [email protected]
PLUGIN_DEVEL=       YES       # Remove before submitting PR

.include "../../Mk/plugins.mk"

PLUGIN_DEVEL=YES skips ports dependency checks during development. Remove before PR.
Final package: os-mynewplugin-0.1_1.pkg

4. Model — Data Schema

<PluginName>.php — boilerplate class:

<?php
namespace OPNsense\Mynewplugin;

use OPNsense\Base\BaseModel;

class Mynewplugin extends BaseModel
{
}

<PluginName>.xml — defines where data lives in config.xml and what fields exist.

Each model should include a <version> tag (current convention):

<model>
    <mount>//OPNsense/mynewplugin</mount>
    <description>
        My New Plugin — manages something useful
    </description>
    <version>1.0.0</version>
    <items>
        <general>
            <Enabled type="BooleanField">
                <Default>1</Default>
                <Required>Y</Required>
            </Enabled>
            <ServerAddress type="NetworkField">
                <Required>Y</Required>
                <ValidationMessage>Please enter a valid IP address.</ValidationMessage>
            </ServerAddress>
            <Port type="PortField">
                <Default>8080</Default>
                <Required>Y</Required>
            </Port>
            <Protocol type="OptionField">
                <Required>Y</Required>
                <Default>http</Default>
                <OptionValues>
                    <http>HTTP</http>
                    <https>HTTPS</https>
                </OptionValues>
            </Protocol>
        </general>
    </items>
</model>

Note: <Default> uses a capital D. <Required> can be Y or N. The <version> tag is optional but present in all current plugins.

Available field types from /usr/local/opnsense/mvc/app/models/OPNsense/Base/FieldTypes/:

Field Type	Use for
`TextField`	Free-text strings
`BooleanField`	Checkboxes (on/off)
`IntegerField`	Whole numbers
`NetworkField`	IP addresses (v4/v6)
`EmailField`	Email addresses (validated)
`PortField`	TCP/UDP port numbers
`OptionField`	Dropdown select menus
`CSVListField`	Comma-separated lists
`CertificateField`	Certificate references
`InterfaceField`	Network interface references

5. Forms — UI Layout

forms/general.xml defines what the user sees. Field <id> paths are relative to the model mount point:

Mount path	Form ID example	Resolves to
`//OPNsense/mynewplugin`	`mynewplugin.general.Enabled`	`//OPNsense/mynewplugin/general/Enabled`
`//OPNsense/lldpd/general`	`general.cdp`	`//OPNsense/lldpd/general/cdp`

<form>
    <field>
        <id>mynewplugin.general.Enabled</id>
        <label>Enable My Plugin</label>
        <type>checkbox</type>
        <help>Enable or disable this feature.</help>
    </field>
    <field>
        <id>mynewplugin.general.ServerAddress</id>
        <label>Server Address</label>
        <type>text</type>
        <help>IP address of the target server.</help>
        <hint>e.g. 192.168.1.100</hint>
    </field>
    <field>
        <id>mynewplugin.general.Port</id>
        <label>Port</label>
        <type>text</type>
    </field>
    <field>
        <id>mynewplugin.general.Protocol</id>
        <label>Protocol</label>
        <type>dropdown</type>
    </field>
</form>

The <id> must match the path in the model: pluginname.container.field.

6. Controllers

IndexController.php — handles page routing:

<?php
namespace OPNsense\Mynewplugin;

class IndexController extends \OPNsense\Base\IndexController
{
    public function indexAction()
    {
        // Pass the form definition to the view
        $this->view->generalForm = $this->getForm("general");
        // Pick the Volt template to render
        $this->view->pick('OPNsense/Mynewplugin/index');
    }
}

Api/SettingsController.php — REST API for loading/saving config:

<?php
namespace OPNsense\Mynewplugin\Api;

use \OPNsense\Base\ApiMutableModelControllerBase;

class SettingsController extends ApiMutableModelControllerBase
{
    protected static $internalModelClass = 'OPNsense\Mynewplugin\Mynewplugin';
    protected static $internalModelName = 'mynewplugin';
}

This automatically provides get and set API endpoints at:

GET/POST /api/mynewplugin/settings/get
POST /api/mynewplugin/settings/set

Test it (as root): curl -k -u root:password https://<firewall>/api/mynewplugin/settings/get

Api/ServiceController.php — backend actions (reload, start, stop):

<?php
namespace OPNsense\Mynewplugin\Api;

use \OPNsense\Base\ApiMutableServiceControllerBase;
use \OPNsense\Core\Backend;

class ServiceController extends ApiMutableServiceControllerBase
{
    protected static $internalServiceClass = '\OPNsense\Mynewplugin\Mynewplugin';
    protected static $internalServiceTemplate = 'OPNsense/Mynewplugin';
    protected static $internalServiceEnabled = 'general.Enabled';  // path relative to model mount
    protected static $internalServiceName = 'mynewplugin';

    public function reloadAction()
    {
        if ($this->request->isPost()) {
            $status = strtolower(trim(
                (new Backend())->configdRun('template reload OPNsense/Mynewplugin')
            ));
            return ["status" => $status];
        }
        return ["status" => "failed"];
    }
}

7. View — Volt Template

index.volt renders the page. Start simple:

<script type="text/javascript">
    $( document ).ready(function() {
        // Load saved data into the form
        mapDataToFormUI({'frm_GeneralSettings':"/api/mynewplugin/settings/get"});

        // Wire up the Save button
        $("#saveAct").click(function(){
            saveFormToEndpoint("/api/mynewplugin/settings/set",'frm_GeneralSettings',function(){
                // After save, tell the backend to regenerate config
                ajaxCall(url="/api/mynewplugin/service/reload", sendData={},callback=function(data,status) {});
            });
        });
    });
</script>

<div class="col-md-12">
    <button class="btn btn-primary" id="saveAct" type="button">
        <b>{{ lang._('Save') }}</b>
    </button>
</div>

{{ partial("layout_partials/base_form",['fields':generalForm,'id':'frm_GeneralSettings'])}}

Multi-tab pages (like LLDP with General + Neighbors tabs):

<ul class="nav nav-tabs" data-tabs="tabs" id="maintabs">
    <li class="active"><a data-toggle="tab" href="#general">{{ lang._('General') }}</a></li>
    <li><a data-toggle="tab" href="#status">{{ lang._('Status') }}</a></li>
</ul>

<div class="tab-content">
    <div id="general" class="tab-pane fade in active">
        <!-- form content here -->
    </div>
    <div id="status" class="tab-pane fade in">
        <pre id="outputArea"></pre>
    </div>
</div>

For the status tab, add an API endpoint in ServiceController that calls a configd action and returns output:

public function statusAction()
{
    if ($this->request->isPost()) {
        $response = (new Backend())->configdRun("mynewplugin status");
        return ["response" => $response];
    }
    return ["response" => ""];
}

ajaxCall(url="/api/mynewplugin/service/status", sendData={}, callback=function(data,status) {
    $("#outputArea").text(data['response']);
});

8. ACL — Access Control

ACL/ACL.xml — who can access the plugin. Without this, only root can see it.

<acl>
    <page-services-mynewplugin>
        <name>WebCfg - Services: My New Plugin</name>
        <description>Allow access to My New Plugin configuration</description>
        <patterns>
            <pattern>ui/mynewplugin/*</pattern>
            <pattern>api/mynewplugin/*</pattern>
        </patterns>
    </page-services-mynewplugin>
</acl>

Clear cache after changes: rm -f /tmp/opnsense_acl_cache.json

Menu/Menu.xml — where it appears in the left sidebar:

<menu>
    <Services order="50">
        <Mynewplugin
            VisibleName="My New Plugin"
            url="/ui/mynewplugin/"
            cssClass="fa fa-cog fa-fw"
        />
    </Services>
</menu>

Available menu sections: Services, VPN, Interfaces, Firewall, System, Reporting, User, Diagnostics.

Clear cache: rm -f /tmp/opnsense_menu_cache.xml

10. Backend Templates — Config File Generation

Templates live in service/templates/OPNsense/<PluginName>/. They use Jinja2 to read config.xml values and generate service configuration files.

+TARGETS — maps template source to output file on the filesystem:

mynewplugin.conf:/usr/local/etc/mynewplugin/mynewplugin.conf

Template file (mynewplugin.conf):

{% if helpers.exists('OPNsense.mynewplugin.general.Enabled') and OPNsense.mynewplugin.general.Enabled == '1' %}
[server]
address={{ OPNsense.mynewplugin.general.ServerAddress|default("") }}
port={{ OPNsense.mynewplugin.general.Port|default("8080") }}
protocol={{ OPNsense.mynewplugin.general.Protocol }}
{% endif %}

Template helpers:

Expression	Meaning
`helpers.exists('path')`	Check if config path exists
`OPNsense.plugin.field`	Read value from config.xml
`	default(“fallback”)`
`!= ""`	Check for text/string fields
`== '1'`	Check for checkbox/BooleanField
`{% raw %}...{% endraw %}`	Escape everything inside (pass through literally)

Gotcha: If your service config contains }} or {% (common in FreeRADIUS ldap.conf), wrap that section in {% raw %}...{% endraw %} or the Jinja2 parser will choke.

11. configd Actions — Daemon Control

service/conf/actions.d/actions_mynewplugin.conf registers commands that configd can execute:

[start]
command:/usr/local/etc/rc.d/mynewplugin start
parameters:
type:script
message:starting mynewplugin daemon

[stop]
command:/usr/local/etc/rc.d/mynewplugin stop
parameters:
type:script

[restart]
command:/usr/local/etc/rc.d/mynewplugin restart
parameters:
type:script

[status]
command:/usr/local/sbin/mynewpluginctl status
parameters:
type:script_output
message:checking mynewplugin status

Action types:

Type	Use for	Returns
`script`	RC scripts, service control	OK/Fail
`script_output`	Commands that produce output (diagnostics)	stdout as text
`stream_output`	Long-running streams	Stream handle
`inline`	Template generation (built-in)	Template engine output

Test from CLI: configctl mynewplugin status

12. setup.sh — /var Ramdisk Support

OPNsense often runs /var as a tmpfs (ramdisk). Directories under /var/ vanish on reboot. setup.sh recreates them:

#!/bin/sh
mkdir -p /var/run/mynewplugin
chown mynewplugin:mynewplugin /var/run/mynewplugin

Place at src/opnsense/scripts/OPNsense/Mynewplugin/setup.sh.

13. Service RC Template

For plugins that control a daemon, add the rc.d file to your templates. In +TARGETS:

mynewplugin:/usr/local/etc/rc.d/mynewplugin
mynewplugin.conf:/usr/local/etc/mynewplugin/mynewplugin.conf

The mynewplugin template generates the FreeBSD rc.d script with proper start/stop commands.

Build & Test Cycle

Build the package

cd plugins/net-mgmt/mynewplugin
make package

Install on test OPNsense

# From the build machine:
scp work/pkg/os-*.pkg root@firewall:/tmp/
ssh root@firewall pkg install /tmp/os-*.pkg

# Or build directly on the OPNsense box:
pkg install git
git clone https://github.com/<user>/plugins
cd plugins/net-mgmt/mynewplugin
make package
pkg install work/pkg/os-*.pkg

Replace an existing plugin

pkg remove os-mynewplugin
# Then install the new version

Test via API (as root)

# Read current config
curl -k -u root:password https://<firewall>/api/mynewplugin/settings/get

# Watch configd log
tail -f /var/log/system.log | grep configd

Debugging

Problem	Check
Template generation fails	Jinja2 syntax error. Run `configctl template reload OPNsense/Mynewplugin` manually. Check `/var/log/system.log` for traceback.
Page 404 after creating controller	URL is `/ui/mynewplugin/` (lowercase). Clear `opnsense_menu_cache.xml`.
Form fields empty	Check model mount path + form IDs match. Test API endpoint directly.
Save button does nothing	Check browser console for JS errors. Verify API endpoint responds.
ACL not showing in user manager	`rm /tmp/opnsense_acl_cache.json`
Menu item not appearing	`rm /tmp/opnsense_menu_cache.xml`
`make package` fails with cryptic error	Usually an XML syntax issue (mismatched tags, unescaped chars). Check model/form XML.
`tag name expected` error	You have `}}` or `{%` in literal config content. Wrap in `{% raw %}...{% endraw %}`.
API functions not found	Action methods MUST end with `Action` (e.g., `neighborAction()`, NOT `neighbor()`).

Walkthrough A: LLDP Plugin from Scratch

This 4-part walkthrough follows @mimugmail’s original series. The LLDP daemon plugin was built by copying the collectd plugin and adapting it. It was merged into official plugins.

Part 1: Copy & Rename

Strategy: LLDP needs one config page (like collectd) and one diagnostics tab to show neighbors (like quagga — Diagnostics → Show running-config). Both collectd and lldpd live in net-mgmt in the ports tree, so we stay in that category.

cd plugins
cp -r net-mgmt/collectd net-mgmt/lldpd

Now rename everything, case-sensitive:

# Files and directories
find net-mgmt/lldpd -name '*collectd*' -exec rename collectd lldpd {} \;
find net-mgmt/lldpd -name '*Collectd*' -exec rename Collectd Lldpd {} \;

# File contents
find net-mgmt/lldpd -type f -exec sed -i '' 's/collectd/lldpd/g' {} \;
find net-mgmt/lldpd -type f -exec sed -i '' 's/Collectd/Lldpd/g' {} \;

Makefile:

PLUGIN_NAME=        lldpd
PLUGIN_VERSION=     0.1
PLUGIN_REVISION=    1
PLUGIN_COMMENT=     LLDP daemon configuration
PLUGIN_MAINTAINER=  [email protected]
PLUGIN_DEVEL=       YES

.include "../../Mk/plugins.mk"

pkg-descr: Copy the LLDPD project description from its website.

Service control (src/etc/inc/plugins.inc.d/lldpd.inc): Check the correct PID file location for lldpd. Replace all collectd references.

setup.sh (src/opnsense/scripts/OPNsense/Lldpd/setup.sh): Check the ports tree’s pkg-* files for /var directories that lldpd creates. Add them so they survive reboot when /var is a ramdisk.

Part 2: Templates, Actions, MVC Files

src/opnsense/service/templates/OPNsense/Lldpd/+TARGETS:

lldpd:/usr/local/etc/rc.d/lldpd
lldpd.conf:/usr/local/etc/lldpd.conf

The lldpd file controls auto start/stop of the daemon. Remove everything between the first if and last endif, replace collectd with lldpd.

src/opnsense/service/conf/actions.d/actions_lldpd.conf: Rename from actions_collectd.conf. This registers the daemon in configd:

[start]
command:/usr/local/etc/rc.d/lldpd start
parameters:
type:script
message:starting lldpd

[stop]
command:/usr/local/etc/rc.d/lldpd stop
parameters:
type:script
message:stopping lldpd

MVC files — search & replace in every file under src/opnsense/mvc/app/:

Directory	Key Files	What to do
`views/OPNsense/Lldpd/`	`general.volt`	UI content — just search & replace
`models/OPNsense/Lldpd/`	`General.php`, `General.xml`	Replace `Collectd` → `Lldpd`; model XML done in part 3
`models/OPNsense/Lldpd/ACL/`	`ACL.xml`	Defines URLs for access control
`models/OPNsense/Lldpd/Menu/`	`Menu.xml`	Sidebar placement + icon (use Font Awesome)
`controllers/OPNsense/Lldpd/`	`GeneralController.php`	Page definition — search & replace
`controllers/OPNsense/Lldpd/Api/`	`*Controller.php`	API + service actions — search & replace
`controllers/OPNsense/Lldpd/forms/`	`general.xml`	Field definitions — done in part 3

Part 3: Forms, Model, and Templating

LLDPD works via CLI arguments (e.g., -c enables CDP). No traditional .conf file — just command-line flags.

forms/general.xml — checkboxes for each protocol (IDs relative to mount //OPNsense/lldpd/general):

<form>
    <field>
        <id>general.enabled</id>
        <label>Enable LLDP Daemon</label>
        <type>checkbox</type>
        <help>This will activate the LLDPD service.</help>
    </field>
    <field>
        <id>general.cdp</id>
        <label>Enable CDP</label>
        <type>checkbox</type>
        <help>This will activate the Cisco Discovery Protocol.</help>
    </field>
    <field>
        <id>general.sonmp</id>
        <label>Enable SONMP</label>
        <type>checkbox</type>
    </field>
    <field>
        <id>general.edp</id>
        <label>Enable EDP</label>
        <type>checkbox</type>
    </field>
    <field>
        <id>general.fdp</id>
        <label>Enable FDP</label>
        <type>checkbox</type>
    </field>
</form>

Model General.xml:

<model>
    <mount>//OPNsense/lldpd/general</mount>
    <description>LLDP daemon configuration</description>
    <version>1.0.1</version>
    <items>
        <enabled type="BooleanField">
            <Default>1</Default>
            <Required>Y</Required>
        </enabled>
        <cdp type="BooleanField">
            <Default>0</Default>
            <Required>Y</Required>
        </cdp>
        <sonmp type="BooleanField">
            <Default>0</Default>
            <Required>Y</Required>
        </sonmp>
        <edp type="BooleanField">
            <Default>0</Default>
            <Required>Y</Required>
        </edp>
        <fdp type="BooleanField">
            <Default>0</Default>
            <Required>Y</Required>
        </fdp>
    </items>
</model>

Note: Fields sit directly under <items> (no <general> container) because the mount path itself ends at general. Form IDs use general.cdp (relative to mount), not lldpd.general.cdp.

Template lldpd.conf — generates CLI arguments (all on one line):

{% if helpers.exists('OPNsense.lldpd.general.cdp') and OPNsense.lldpd.general.cdp == '1' %}-c {% endif %}
{% if helpers.exists('OPNsense.lldpd.general.sonmp') and OPNsense.lldpd.general.sonmp == '1' %}-s {% endif %}
{% if helpers.exists('OPNsense.lldpd.general.edp') and OPNsense.lldpd.general.edp == '1' %}-e {% endif %}
{% if helpers.exists('OPNsense.lldpd.general.fdp') and OPNsense.lldpd.general.fdp == '1' %}-f {% endif %}

Verification: After saving, check System > Log Files > General:

Dec 27 13:44:23 OPNsense lldpd[22894]: protocol LLDP enabled
Dec 27 13:44:23 OPNsense lldpd[22894]: protocol CDPv1 enabled
Dec 27 13:44:23 OPNsense lldpd[22894]: protocol CDPv2 enabled
Dec 27 13:44:23 OPNsense lldpd[22894]: protocol SONMP enabled
Dec 27 13:44:23 OPNsense lldpd[22894]: protocol EDP enabled
Dec 27 13:44:23 OPNsense lldpd[22894]: protocol FDP disabled

Part 4: Adding a Diagnostics Tab

Now we want a tab showing lldpcli show neighbors output — similar to how the Quagga plugin shows “Show running-config” in a text box.

Step 1: Register the command in actions_lldpd.conf:

[neighbor]
command:/usr/local/sbin/lldpcli show neighbors
parameters:
type:script_output
message:show lldp neighbors

Step 2: Create API endpoint in Api/ServiceController.php (exact code from the merged plugin):

namespace OPNsense\Lldpd\Api;

use OPNsense\Base\ApiMutableServiceControllerBase;
use OPNsense\Core\Backend;

class ServiceController extends ApiMutableServiceControllerBase
{
    protected static $internalServiceClass = '\OPNsense\Lldpd\General';
    protected static $internalServiceTemplate = 'OPNsense/Lldpd';
    protected static $internalServiceEnabled = 'enabled';
    protected static $internalServiceName = 'lldpd';

    /**
     * show lldpd neighbors
     * @return array
     */
    public function neighborAction()
    {
        $backend = new Backend();
        $response = $backend->configdRun("lldpd neighbor");
        return array("response" => $response);
    }
}

Pattern: Look at existing plugins for reference. This was copied from plugins/net/quagga/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/DiagnosticsController.php (line 63). Method names MUST end with Action.

Step 3: Wire up the UI in general.volt:

Add Bootstrap tabs:

<ul class="nav nav-tabs" data-tabs="tabs" id="maintabs">
    <li class="active"><a data-toggle="tab" href="#general">{{ lang._('General') }}</a></li>
    <li><a data-toggle="tab" href="#neighbor">{{ lang._('Neighbors') }}</a></li>
</ul>

Add the API call:

ajaxCall(url="/api/lldpd/service/neighbor", sendData={}, callback=function(data,status) {
    $("#listneighbor").text(data['response']);
});

Add the output container:

<div id="neighbor" class="tab-pane fade in">
    <pre id="listneighbor"></pre>
</div>

Step 4: Build and test:

git clone https://github.com/<user>/plugins
cd plugins
git checkout lldpd        # if using a branch
cd net-mgmt/lldpd
make package
pkg install work/pkg/os-*.txz

Result: A plugin with two tabs — General (config) and Neighbors (live output from lldpcli). View the final merged code.

From mimugmail: “If you’re wondering how I figured out the API call pattern — I just looked at the Quagga controller code. And when I was stuck on templating the daemon CLI arguments, I asked in a GitHub issue.”

Walkthrough B: Enhancing FreeRADIUS with LDAP Support

This 4-part walkthrough follows @mimugmail’s original series. The goal: add an LDAP submenu to the existing FreeRADIUS plugin with full UI configuration.

Part 1: Verify Dependencies & Scaffold the MVC

First, verify LDAP works with FreeRADIUS on the system:

cd /usr/local/etc/raddb/mods-enabled
ln -s ../mods-available/ldap .
service radiusd stop
radiusd -X

Output shows the LDAP module loads correctly (just can’t connect since no server configured yet):

rlm_ldap (ldap): Initialising connection pool
rlm_ldap (ldap): Bind with (anonymous) to ldap://localhost:389 failed: Can't contact LDAP server

Good — all FreeRADIUS LDAP dependencies are met.

Add the menu entry in models/OPNsense/Freeradius/Menu/Menu.xml:

<LDAP url="/ui/freeradius/ldap/index" order="50"/>

Scaffold the Model: Copy Eap.xml and Eap.php → Ldap.xml and Ldap.php. Replace EAP → LDAP, eap → ldap, Eap → Ldap (case-sensitive).

Scaffold the Controllers:

Copy controllers/OPNsense/Freeradius/EapController.php → LdapController.php
Copy controllers/OPNsense/Freeradius/Api/EapController.php → Api/LdapController.php
Replace Eap → Ldap everywhere

Scaffold the View: Copy views/OPNsense/Freeradius/eap.volt → ldap.volt. Search & replace.

Now you have the (M)odel, (C)ontroller, and (V)iew skeleton.

From mimugmail: “No PHP knowledge needed. Just search & replace FTW!”

Part 2: Define Fields (Forms + Model)

Looking at /usr/local/etc/raddb/mods-enabled/ldap, the interesting config values are: server, port, identity, password, base_dn.

Since the server config supports both ldap:// and ldaps:// URIs, we can combine protocol+host into a dropdown + text field instead of a separate port field.

forms/ldap.xml:

<form>
    <field>
        <id>freeradius.ldap.protocol</id>
        <label>Protocol</label>
        <type>dropdown</type>
    </field>
    <field>
        <id>freeradius.ldap.server</id>
        <label>Server</label>
        <type>text</type>
        <help>IP address or hostname of LDAP server</help>
    </field>
    <field>
        <id>freeradius.ldap.identity</id>
        <label>Identity</label>
        <type>text</type>
        <help>Bind DN for LDAP connection</help>
    </field>
    <field>
        <id>freeradius.ldap.password</id>
        <label>Password</label>
        <type>password</type>
    </field>
    <field>
        <id>freeradius.ldap.base_dn</id>
        <label>Base DN</label>
        <type>text</type>
        <help>Search base for user lookups</help>
    </field>
</form>

Model Ldap.xml:

<model>
    <mount>//OPNsense/freeradius/ldap</mount>
    <description>FreeRADIUS LDAP configuration</description>
    <version>1.0.0</version>
    <items>
        <protocol type="OptionField">
            <Default>ldap</Default>
            <Required>Y</Required>
            <OptionValues>
                <ldap>LDAP</ldap>
                <ldaps>LDAPS</ldaps>
            </OptionValues>
        </protocol>
        <server type="TextField">
            <Required>Y</Required>
        </server>
        <identity type="TextField">
            <Required>Y</Required>
        </identity>
        <password type="TextField">
            <Required>Y</Required>
        </password>
        <base_dn type="TextField">
            <Required>Y</Required>
        </base_dn>
    </items>
</model>

Part 3: Configuration Template

The LDAP module config at /usr/local/etc/raddb/mods-enabled/ldap needs to be generated from the UI values. Copy the existing mods-enabled/ldap content into templates/OPNsense/Freeradius/mods-enabled-ldap.

+TARGETS:

mods-enabled-ldap:/usr/local/etc/raddb/mods-enabled/ldap

Template logic — use Jinja2 conditionals to only output values when set:

{% if helpers.exists('OPNsense.freeradius.general.enabled') and OPNsense.freeradius.general.enabled == '1' %}
{%   if helpers.exists('OPNsense.freeradius.general.ldap_enabled') and OPNsense.freeradius.general.ldap_enabled == '1' %}

{% if helpers.exists('OPNsense.freeradius.ldap.server') and OPNsense.freeradius.ldap.server != "" %}
server = '{{ OPNsense.freeradius.ldap.protocol }}://{{ OPNsense.freeradius.ldap.server }}'
{% endif %}

{% if helpers.exists('OPNsense.freeradius.ldap.identity') and OPNsense.freeradius.ldap.identity != "" %}
identity = '{{ OPNsense.freeradius.ldap.identity }}'
{% endif %}

{% if helpers.exists('OPNsense.freeradius.ldap.password') and OPNsense.freeradius.ldap.password != "" %}
password = {{ OPNsense.freeradius.ldap.password }}
{% endif %}

{% if helpers.exists('OPNsense.freeradius.ldap.base_dn') and OPNsense.freeradius.ldap.base_dn != "" %}
base_dn = '{{ OPNsense.freeradius.ldap.base_dn }}'
{% endif %}

{%   endif %}
{% endif %}

Template pattern:

!= "" for text fields → only output when user filled something in
== '1' for checkboxes → only output when enabled
The outer if checks FreeRADIUS is enabled; inner if checks LDAP sub-feature is enabled

Part 4: Add Enable Checkbox, Build, and Debug

We need a checkbox in the General tab to toggle LDAP on/off, so LDAP config is only generated when the user explicitly enables it.

Add field to forms/general.xml (third field):

<field>
    <id>freeradius.general.ldap_enabled</id>
    <label>Enable LDAP</label>
    <type>checkbox</type>
    <help>This allows you to bind to an external LDAP server. Use the LDAP submenu for configuration.</help>
</field>

Add to model General.xml (third field):

<ldap_enabled type="BooleanField">
    <Default>0</Default>
    <Required>N</Required>
</ldap_enabled>

No Volt template changes needed for a simple checkbox.

Build and install:

pkg install git
git clone https://github.com/mimugmail/plugins
cd plugins
git checkout frldap                    # if using a branch
cd net/freeradius
make package
pkg install work/pkg/os-*.txz

If the stable os-freeradius package is already installed, remove it first: pkg remove os-freeradius

Common error during make package:

OPNsense configd.py: Inline action failed with OPNsense/Freeradius
OPNsense/Freeradius/mods-enabled-ldap tag name expected

Cause: The original mods-enabled/ldap contains }} in its config:

user {
    base_dn = "${..base_dn}"
    filter = "(uid=%{%{Stripped-User-Name}:-%{User-Name}})"
}

The }} is interpreted as a Jinja2 closing tag. Fix: Wrap the entire default config content in {% raw %}...{% endraw %} — but keep the conditional if/endif blocks outside the raw block:

{% if helpers.exists('OPNsense.freeradius.general.ldap_enabled') and OPNsense.freeradius.general.ldap_enabled == '1' %}
{% raw %}
ldap {
    server = ...
    # ... all the standard FreeRADIUS LDAP module config ...
}
{% endraw %}
{% endif %}

After this fix, make package succeeds and the plugin installs cleanly.

Final result: FreeRADIUS now has a working LDAP submenu with protocol, server, identity, password, and base_dn fields. All values are persisted to config.xml and templated into /usr/local/etc/raddb/mods-enabled/ldap on save.

Submitting a Pull Request

Remove PLUGIN_DEVEL=YES from Makefile
Bump PLUGIN_VERSION appropriately, set PLUGIN_REVISION=1
Write a meaningful pkg-descr (copy from the project’s description page)
Test on a clean OPNsense install
Push to your fork
Create PR against opnsense/plugins

From mimugmail: “If you are nearly complete, you can also create a PR and ask the guys via GitHub to help. I had no idea how to manage templating either — here’s the issue where I asked: https://github.com/opnsense/core/issues/2022. As you can see, it doesn’t have to be perfect from the beginning.”

Multi-language Support

OPNsense uses gettext for translations. Wrap user-visible strings:

In Volt templates:

{{ lang._('Save') }}
{{ lang._('Enable this feature') }}

In PHP:

<?= gettext('Configuration saved') ?>

In PHP with variables:

<?= sprintf(gettext('Restarted %s processes'), $count) ?>

Package Naming & Versioning

All OPNsense plugins follow the os- prefix convention. The versioning scheme:

os-helloworld-1.4_2.pkg
│             │ │
│             │ └─ PLUGIN_REVISION (packaging revision)
│             └─── PLUGIN_VERSION (plugin version)
└───────────────── Always os- prefixed (handled by build system)

PLUGIN_VERSION: Your plugin version. Semantic versioning encouraged.
PLUGIN_REVISION: Bump when the packaging changes but code is the same. Reset to 1 on version bump.

Hosting Your Own Plugin Repository

You don’t need to submit your plugin to the official opnsense/plugins repo. You can manage everything in your own Git repository and distribute it via a custom package repository — just like mimugmail’s community repo.

Three approaches, from simplest to most production-ready:

Option A: Manual Install (No Repo)

Build and install directly — best for single firewalls or testing.

# On your build machine
cd your-plugins-repo/net-mgmt/myplugin
make package
# Copy to firewall
scp work/pkg/os-*.pkg root@firewall:/tmp/
ssh root@firewall pkg install /tmp/os-*.pkg

Pros: Zero infrastructure. Cons: Manual updates, no version tracking.

Option B: Self-Hosted pkg Repository

Create a proper FreeBSD package repository that users add to their OPNsense. This is the standard approach.

Step 1: Build all your plugin packages

# In your plugins repo
cd /path/to/your-plugins
for dir in category/*/; do
    make -C "$dir" package
done

# Collect all built packages
mkdir -p /tmp/repo-packages
find . -name 'os-*.pkg' -exec cp {} /tmp/repo-packages/ \;

Step 2: Generate the repository metadata

pkg repo /tmp/repo-packages

This creates:

/tmp/repo-packages/
├── packagesite.txz     # Package catalog
├── packagesite.yaml    # Human-readable index
├── meta.txz            # Repository metadata
├── meta.conf            # Repo config
├── digests.txz          # Package checksums
├── filesite.txz         # File listing
└── All/                 # All .pkg files
    └── os-myplugin-0.1_1.pkg

Step 3: Host on a web server

Upload the entire directory to any static file host:

Host	Example URL
Nginx/Apache on your server	`https://repo.example.com/opnsense/`
Cloudflare R2	`https://pub-xxx.r2.dev/opnsense/`
GitHub Releases	Upload as release assets
AWS S3 + CloudFront	`https://cdn.example.com/opnsense/`

Critical: The server MUST support HTTP range requests (for partial package downloads).

Step 4: Create a repo config file

Create myrepo.conf:

myrepo: {
  url: "https://repo.example.com/opnsense/${ABI}",
  priority: 5,
  enabled: yes
}

${ABI} resolves to the OPNsense ABI string (e.g., FreeBSD:14:amd64)
Place packages at https://repo.example.com/opnsense/FreeBSD:14:amd64/

Step 5: Users install the repo

# On the OPNsense firewall
fetch -o /usr/local/etc/pkg/repos/myrepo.conf https://repo.example.com/myrepo.conf
pkg update

Step 6: Install your plugin

pkg install os-myplugin

Your plugin now appears in the OPNsense UI immediately after install — no reboot needed.

Keeping your repo updated:

# 1. Rebuild packages with new PLUGIN_VERSION
make package

# 2. Copy new .pkg to repo directory, remove old versions
cp work/pkg/os-myplugin-1.0_1.pkg /var/www/repo/FreeBSD:14:amd64/All/
rm /var/www/repo/FreeBSD:14:amd64/All/os-myplugin-0.9_*.pkg

# 3. Regenerate repo metadata
pkg repo /var/www/repo/FreeBSD:14:amd64/

Real-world example: mimugmail’s opn-repo uses this exact pattern. Their repo config: https://www.routerperformance.net/mimugmail.conf. Install command: fetch -o /usr/local/etc/pkg/repos/mimugmail.conf https://www.routerperformance.net/mimugmail.conf

Option C: Keep Source in Your Own Git Repo

You don’t need to fork opnsense/plugins at all. Structure your own repo following the same layout:

your-opnsense-plugins/
├── Makefile              # Root Makefile (optional, for batch builds)
├── README.md
├── Mk/
│   └── plugins.mk        # Copy from opnsense/plugins
├── net-mgmt/
│   └── myplugin/
│       ├── Makefile
│       ├── pkg-descr
│       └── src/opnsense/...
├── security/
│   └── myfirewall/
│       ├── Makefile
│       └── src/opnsense/...
└── www/
    └── myproxy/
        ├── Makefile
        └── src/opnsense/...

Build with OPNsense tools:

The Mk/plugins.mk from opnsense/plugins includes all the build logic. Copy it to your repo. To build, you still need the OPNsense build environment (FreeBSD 14 VM with opnsense/tools).

CI/CD approach:

If you set up a FreeBSD build VM, you can automate the entire pipeline:

# .github/workflows/build.yml (runs on self-hosted FreeBSD runner)
steps:
  - run: |
      cd your-plugins
      for dir in */*/; do make -C "$dir" package; done
  - run: |
      mkdir -p repo/FreeBSD:14:amd64
      find . -name 'os-*.pkg' -exec cp {} repo/FreeBSD:14:amd64/All/ \;
      pkg repo repo/FreeBSD:14:amd64/
  - uses: actions/upload-artifact@v4
    with:
      path: repo/

Then sync the artifacts to your web server or serve directly from GitHub Releases.

GitHub Actions on FreeBSD note: You’ll need a self-hosted runner on FreeBSD since GitHub’s hosted runners are Linux/macOS/Windows only. Alternatively, build in a FreeBSD VM and upload manually.

Quick Comparison

Approach	Setup time	Maintenance	Best for
Manual install	5 min	Manual every update	1-2 firewalls, internal tools
Self-hosted repo	30 min	Update + `pkg repo` per release	Team/department deployment
Git repo + CI/CD	2-3 hours	Push → build → deploy	Production, multiple users/customers
Official PR	Days (review)	Zero (OPNsense team maintains)	General-purpose plugins

Walkthrough C: Repository Manager Plugin

A plugin that lets you manage custom pkg repositories from the OPNsense web UI — no SSH needed. Inspired by the m.a.x. it professional plugins. This is a practical project that ties together everything from the guide above.

What it does: Instead of manually creating /usr/local/etc/pkg/repos/*.conf files and running pkg update via SSH, you get a UI panel to add, edit, enable/disable, and remove custom repos.

Design

This plugin is simpler than LLDP or FreeRADIUS — no daemon to control, no complex config generation. Just:

Form — name, URL, priority, enabled toggle
Model — stores repo list in config.xml
Template — generates .conf files from model data
configd action — runs pkg update after changes

┌─────────────────────────────────────┐
│  Services → Repo Manager            │
│                                      │
│  ┌──────────────────────────────┐   │
│  │ [+] Add Repository           │   │
│  │                               │   │
│  │  ☑ myrepo    https://...  [✎] │   │
│  │  ☐ testrepo  https://...  [✎] │   │
│  │                               │   │
│  │  [Save]  [Update All Repos]   │   │
│  └──────────────────────────────┘   │
│                                      │
│  ┌─ Output ─────────────────────┐   │
│  │ pkg update output here...    │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘

Step 1: Directory Setup

mkdir -p src/opnsense/mvc/app/{controllers,models,views}/OPNsense/RepoManager
mkdir -p src/opnsense/mvc/app/controllers/OPNsense/RepoManager/{Api,forms}
mkdir -p src/opnsense/mvc/app/models/OPNsense/RepoManager/{ACL,Menu}
mkdir -p src/opnsense/service/{conf/actions.d,templates/OPNsense/RepoManager}

Step 2: Model

models/OPNsense/RepoManager/RepoManager.php:

<?php
namespace OPNsense\RepoManager;

use OPNsense\Base\BaseModel;

class RepoManager extends BaseModel
{
}

models/OPNsense/RepoManager/RepoManager.xml:

<model>
    <mount>//OPNsense/repomanager</mount>
    <description>Custom pkg repository manager</description>
    <version>1.0.0</version>
    <items>
        <repos>
            <repo type="ArrayField">
                <Required>N</Required>
                <enabled type="BooleanField">
                    <Default>1</Default>
                    <Required>Y</Required>
                </enabled>
                <name type="TextField">
                    <Required>Y</Required>
                    <mask>/^[a-zA-Z0-9_-]{1,32}$/u</mask>
                    <ValidationMessage>Only alphanumeric, dash, underscore. Max 32 chars.</ValidationMessage>
                </name>
                <url type="TextField">
                    <Required>Y</Required>
                    <mask>/^https?:\/\/.+/u</mask>
                    <ValidationMessage>Must be a valid HTTP(S) URL.</ValidationMessage>
                </url>
                <priority type="IntegerField">
                    <Default>5</Default>
                    <Required>Y</Required>
                    <MinimumValue>1</MinimumValue>
                    <MaximumValue>20</MaximumValue>
                </priority>
            </repo>
        </repos>
    </items>
</model>

This creates a repeatable array of repo entries. Each entry has: name, URL, priority, enabled toggle, and optional authentication credentials.

Private repo support: Add a credentials container for repos that require authentication:

<credentials type="ContainerField">
    <Required>N</Required>
    <username type="TextField">
        <Required>N</Required>
    </username>
    <password type="TextField">
        <Required>N</Required>
    </password>
</credentials>

The Python script then embeds credentials in the URL if provided:

if creds.find('username') is not None and creds.find('username').text:
    from urllib.parse import quote
    user = creds.find('username').text
    pw = creds.find('password').text if creds.find('password') is not None else ''
    # Embed in URL for basic auth
    url_text = url_text.replace('://', f'://{quote(user)}:{quote(pw)}@')

Step 3: Forms

controllers/OPNsense/RepoManager/forms/general.xml:

<form>
    <field>
        <id>repomanager.repos.repo.enabled</id>
        <label>Enabled</label>
        <type>checkbox</type>
        <help>Enable or disable this repository.</help>
    </field>
    <field>
        <id>repomanager.repos.repo.name</id>
        <label>Name</label>
        <type>text</type>
        <help>Short name for the repo (used as the .conf filename).</help>
        <hint>e.g. myrepo</hint>
    </field>
    <field>
        <id>repomanager.repos.repo.url</id>
        <label>URL</label>
        <type>text</type>
        <help>Repository URL. Use ${ABI} for ABI-dependent paths.</help>
        <hint>https://repo.example.com/opnsense/${ABI}</hint>
    </field>
    <field>
        <id>repomanager.repos.repo.priority</id>
        <label>Priority</label>
        <type>text</type>
        <help>Lower number = higher priority. Default is 5.</help>
    </field>
    <field>
        <id>repomanager.repos.repo.credentials.username</id>
        <label>Username (optional)</label>
        <type>text</type>
        <help>For private/authenticated repos. Leave empty for public repos.</help>
    </field>
    <field>
        <id>repomanager.repos.repo.credentials.password</id>
        <label>Password (optional)</label>
        <type>password</type>
        <help>Repo password or access token.</help>
    </field>
</form>

Step 4: Template — Generate .conf Files

Since we need dynamic filenames (one .conf per repo), the standard +TARGETS approach won’t work. We use a configd Python script instead that reads config.xml and writes each .conf file directly.

service/conf/actions.d/actions_repomanager.conf:

[generate]
command:/usr/local/opnsense/scripts/repomanager/generate_repos.py
parameters:
type:script_output
message:generating repo config files

[update]
command:/usr/sbin/pkg update
parameters:
type:script_output
message:updating pkg repositories

scripts/repomanager/generate_repos.py:

#!/usr/local/bin/python3
"""Generate /usr/local/etc/pkg/repos/*.conf from config.xml"""
import xml.etree.ElementTree as ET
import json
import os

CONFIG = '/conf/config.xml'
REPO_DIR = '/usr/local/etc/pkg/repos'

# Parse config.xml
tree = ET.parse(CONFIG)
root = tree.getroot()

# Find repomanager section
repos = root.findall(".//repomanager/repos/repo")

# Remove old conf files
for f in os.listdir(REPO_DIR):
    if f.endswith('.conf') and f not in ['OPNsense.conf']:
        # Only remove files that match our managed repos
        pass  # Be careful here

# Generate new ones
for repo in repos:
    enabled = repo.find('enabled')
    name = repo.find('name')
    url = repo.find('url')
    priority = repo.find('priority')
    creds = repo.find('credentials')

    if enabled is None or name is None or url is None:
        continue
    if enabled.text != '1':
        continue

    url_text = url.text
    # Embed credentials if provided (for private repos)
    if creds is not None:
        cred_user = creds.find('username')
        cred_pass = creds.find('password')
        if cred_user is not None and cred_user.text:
            from urllib.parse import quote
            user = quote(cred_user.text, safe='')
            pw = quote(cred_pass.text, safe='') if cred_pass is not None and cred_pass.text else ''
            url_text = url_text.replace('://', f'://{user}:{pw}@')

    conf_path = os.path.join(REPO_DIR, f"{name.text}.conf")
    content = f"""{name.text}: {{
  url: "{url_text}",
  priority: {priority.text or '5'},
  enabled: yes
}}
"""
    with open(conf_path, 'w') as f:
        f.write(content)

print(json.dumps({"status": "ok", "generated": len(repos)}))

Step 5: Controllers

controllers/OPNsense/RepoManager/IndexController.php:

<?php
namespace OPNsense\RepoManager;

class IndexController extends \OPNsense\Base\IndexController
{
    public function indexAction()
    {
        $this->view->generalForm = $this->getForm("general");
        $this->view->pick('OPNsense/RepoManager/index');
    }
}

controllers/OPNsense/RepoManager/Api/SettingsController.php:

<?php
namespace OPNsense\RepoManager\Api;

use \OPNsense\Base\ApiMutableModelControllerBase;

class SettingsController extends ApiMutableModelControllerBase
{
    protected static $internalModelClass = '\OPNsense\RepoManager\RepoManager';
    protected static $internalModelName = 'repomanager';
}

controllers/OPNsense/RepoManager/Api/ServiceController.php:

<?php
namespace OPNsense\RepoManager\Api;

use \OPNsense\Base\ApiControllerBase;
use \OPNsense\Core\Backend;

class ServiceController extends ApiControllerBase
{
    public function generateAction()
    {
        if ($this->request->isPost()) {
            $backend = new Backend();
            $response = $backend->configdRun("repomanager generate");
            return json_decode($response, true) ?: ["status" => "error"];
        }
        return ["status" => "failed"];
    }

    public function updateAction()
    {
        if ($this->request->isPost()) {
            $backend = new Backend();
            $response = $backend->configdRun("repomanager update");
            return ["output" => $response];
        }
        return ["output" => ""];
    }
}

Step 6: View

views/OPNsense/RepoManager/index.volt:

<script type="text/javascript">
    $( document ).ready(function() {
        // Load repo list
        mapDataToFormUI({'frm_repos':"/api/repomanager/settings/get"});

        // Save to config.xml
        $("#saveAct").click(function(){
            saveFormToEndpoint("/api/repomanager/settings/set",'frm_repos',function(){
                // After save, regenerate .conf files
                ajaxCall(url="/api/repomanager/service/generate", sendData={},callback=function(data,status) {
                    $("#genStatus").html(data['status'] == 'ok' ? '✓ Configs generated' : '✗ Error');
                });
            });
        });

        // Update pkg repos
        $("#updateAct").click(function(){
            $("#updateOutput").html("Running pkg update...");
            ajaxCall(url="/api/repomanager/service/update", sendData={},callback=function(data,status) {
                $("#updateOutput").text(data['output']);
            });
        });
    });
</script>

<div class="col-md-12">
    <button class="btn btn-primary" id="saveAct" type="button">
        <b>{{ lang._('Save') }}</b>
    </button>
    <button class="btn btn-default" id="updateAct" type="button">
        <b>{{ lang._('Update Repositories') }}</b>
    </button>
    <span id="genStatus" style="margin-left:10px;"></span>
</div>

<br/>
{{ partial("layout_partials/base_form",['fields':generalForm,'id':'frm_repos'])}}

<br/>
<div><pre id="updateOutput" style="max-height:300px;overflow-y:scroll;"></pre></div>

models/OPNsense/RepoManager/Menu/Menu.xml:

<menu>
    <System order="60">
        <RepoManager VisibleName="Repo Manager" url="/ui/repomanager/" cssClass="fa fa-database fa-fw"/>
    </System>
</menu>

models/OPNsense/RepoManager/ACL/ACL.xml:

<acl>
    <page-system-repomanager>
        <name>WebCfg - System: Repo Manager</name>
        <description>Allow access to the custom repository manager</description>
        <patterns>
            <pattern>ui/repomanager/*</pattern>
            <pattern>api/repomanager/*</pattern>
        </patterns>
    </page-system-repomanager>
</acl>

Step 8: Makefile

PLUGIN_NAME=        repomanager
PLUGIN_VERSION=     1.0
PLUGIN_REVISION=    1
PLUGIN_COMMENT=     Manage custom pkg repositories from the web UI
PLUGIN_MAINTAINER=  [email protected]
PLUGIN_DEVEL=       YES

.include "../../Mk/plugins.mk"

Result

After installing os-repomanager, users get:

Add/remove custom repos from the web UI
Enable/disable repos without deleting them
Regenerate .conf files on save
Run pkg update with one click and see output inline
No SSH needed for repo management

This is a ~200 line plugin. The core logic is the Python script that reads config.xml and writes .conf files — the rest is standard MVC boilerplate.

Extension ideas: Add a “Test connection” button, show last pkg update timestamp, support for repo fingerprints/signing keys, batch enable/disable.

Appendix: Hello World Plugin — Full Source Listing

Complete, build-ready source for a minimal OPNsense plugin. Every file shown in full — copy into your plugins directory, fetch the real Mk/plugins.mk, and make package. This is the simplest possible plugin with the entire MVC + configd stack working end-to-end.

File Tree

plugins/devel/helloworld/
├── Makefile
├── pkg-descr
└── src/opnsense/
    ├── mvc/app/
    │   ├── controllers/OPNsense/HelloWorld/
    │   │   ├── IndexController.php
    │   │   ├── Api/
    │   │   │   ├── SettingsController.php
    │   │   │   └── ServiceController.php
    │   │   └── forms/general.xml
    │   ├── models/OPNsense/HelloWorld/
    │   │   ├── HelloWorld.php
    │   │   ├── HelloWorld.xml
    │   │   ├── ACL/ACL.xml
    │   │   └── Menu/Menu.xml
    │   └── views/OPNsense/HelloWorld/
    │       └── index.volt
    ├── scripts/helloworld/
    │   └── test_message.py
    └── service/
        ├── conf/actions.d/
        │   └── actions_helloworld.conf
        └── templates/OPNsense/HelloWorld/
            ├── +TARGETS
            └── helloworld.conf

Source Code

Makefile — plugin metadata:

PLUGIN_NAME=        helloworld
PLUGIN_VERSION=     1.0
PLUGIN_REVISION=    1
PLUGIN_COMMENT=     Hello World test plugin — says hello from configd
PLUGIN_MAINTAINER=  [email protected]
PLUGIN_DEVEL=       YES

.include "../../Mk/plugins.mk"

pkg-descr — package description:

A simple Hello World plugin for OPNsense, demonstrating the MVC + configd
architecture. Includes a form, service control, and a configd-powered action
that returns JSON.

src/opnsense/mvc/app/models/OPNsense/HelloWorld/HelloWorld.php — model class:

<?php
namespace OPNsense\HelloWorld;

use OPNsense\Base\BaseModel;

class HelloWorld extends BaseModel
{
}

src/opnsense/mvc/app/models/OPNsense/HelloWorld/HelloWorld.xml — data schema:

<model>
    <mount>//OPNsense/helloworld</mount>
    <description>Hello World test plugin</description>
    <version>1.0.0</version>
    <items>
        <general>
            <Enabled type="BooleanField">
                <Default>1</Default>
                <Required>Y</Required>
            </Enabled>
            <Greeting type="TextField">
                <Default>Hello from OPNsense!</Default>
                <Required>Y</Required>
            </Greeting>
            <Mood type="OptionField">
                <Default>happy</Default>
                <Required>Y</Required>
                <OptionValues>
                    <happy>😊 Happy</happy>
                    <excited>🚀 Excited</excited>
                    <debugging>🐛 Debugging</debugging>
                </OptionValues>
            </Mood>
        </general>
    </items>
</model>

src/opnsense/mvc/app/models/OPNsense/HelloWorld/ACL/ACL.xml — access control:

<acl>
    <page-user-helloworld>
        <name>WebCfg - Users: Hello World!</name>
        <description>Allow access to the Hello World module</description>
        <patterns>
            <pattern>ui/helloworld/*</pattern>
            <pattern>api/helloworld/*</pattern>
        </patterns>
    </page-user-helloworld>
</acl>

src/opnsense/mvc/app/models/OPNsense/HelloWorld/Menu/Menu.xml — sidebar entry:

<menu>
    <User order="99">
        <HelloWorld
            VisibleName="Hello World"
            url="/ui/helloworld/"
            cssClass="fa fa-smile-o fa-fw"
        />
    </User>
</menu>

src/opnsense/mvc/app/controllers/OPNsense/HelloWorld/IndexController.php — page routing:

<?php
namespace OPNsense\HelloWorld;

class IndexController extends \OPNsense\Base\IndexController
{
    public function indexAction()
    {
        $this->view->generalForm = $this->getForm("general");
        $this->view->pick('OPNsense/HelloWorld/index');
    }
}

src/opnsense/mvc/app/controllers/OPNsense/HelloWorld/forms/general.xml — UI form:

<form>
    <field>
        <id>helloworld.general.Enabled</id>
        <label>Enabled</label>
        <type>checkbox</type>
        <help>Enable the Hello World service.</help>
    </field>
    <field>
        <id>helloworld.general.Greeting</id>
        <label>Greeting Message</label>
        <type>text</type>
        <help>The message to greet with.</help>
    </field>
    <field>
        <id>helloworld.general.Mood</id>
        <label>Mood</label>
        <type>dropdown</type>
        <help>Current developer mood.</help>
    </field>
</form>

src/opnsense/mvc/app/controllers/OPNsense/HelloWorld/Api/SettingsController.php — config get/set:

<?php
namespace OPNsense\HelloWorld\Api;

use \OPNsense\Base\ApiMutableModelControllerBase;

class SettingsController extends ApiMutableModelControllerBase
{
    protected static $internalModelClass = '\OPNsense\HelloWorld\HelloWorld';
    protected static $internalModelName = 'helloworld';
}

src/opnsense/mvc/app/controllers/OPNsense/HelloWorld/Api/ServiceController.php — backend actions:

<?php
namespace OPNsense\HelloWorld\Api;

use \OPNsense\Base\ApiControllerBase;
use \OPNsense\Core\Backend;

class ServiceController extends ApiControllerBase
{
    /**
     * reload template
     */
    public function reloadAction()
    {
        $status = "failed";
        if ($this->request->isPost()) {
            $status = strtolower(trim(
                (new Backend())->configdRun('template reload OPNsense/HelloWorld')
            ));
        }
        return ["status" => $status];
    }

    /**
     * run the test action via configd
     */
    public function testAction()
    {
        if ($this->request->isPost()) {
            $result = json_decode(
                trim((new Backend())->configdRun("helloworld test")),
                true
            );
            if ($result !== null) {
                return $result;
            }
        }
        return ["message" => "unable to run config action"];
    }
}

src/opnsense/mvc/app/views/OPNsense/HelloWorld/index.volt — page template:

<script type="text/javascript">
    $( document ).ready(function() {
        // Load saved data into form
        mapDataToFormUI({'frm_GeneralSettings':"/api/helloworld/settings/get"});

        // Save button
        $("#saveAct").click(function(){
            saveFormToEndpoint("/api/helloworld/settings/set",'frm_GeneralSettings',function(){
                ajaxCall(url="/api/helloworld/service/reload", sendData={},callback=function(data,status) {
                    console.log("Template reload: " + data['status']);
                });
            });
        });

        // Test button — runs configd action and displays JSON result
        $("#testAct").SimpleActionButton({
            onAction: function(data) {
                $("#responseMsg").removeClass("hidden").html(
                    "<strong>" + data['message'] + "</strong><br/>" +
                    "Greeting: " + data['greeting'] + "<br/>" +
                    "Mood: " + data['mood']
                );
            }
        });
    });
</script>

<div class="col-md-12">
    <button class="btn btn-primary" id="saveAct" type="button">
        <b>{{ lang._('Save') }}</b>
    </button>
    <button class="btn btn-default" id="testAct"
        data-endpoint="/api/helloworld/service/test"
        data-label="{{ lang._('Test') }}">
    </button>
</div>

<br/>
<div class="alert alert-info hidden" role="alert" id="responseMsg"></div>

{{ partial("layout_partials/base_form",['fields':generalForm,'id':'frm_GeneralSettings'])}}

src/opnsense/scripts/helloworld/test_message.py — configd worker that reads config and returns JSON:

#!/usr/local/bin/python3
"""Hello World test script — reads config and returns JSON."""
import xml.etree.ElementTree as ET
import json

CONFIG = '/conf/config.xml'

tree = ET.parse(CONFIG)
root = tree.getroot()

# Defaults
enabled = "0"
greeting = "Hello from OPNsense!"
mood = "unknown"

# Read our config from config.xml
node = root.find(".//helloworld/general")
if node is not None:
    e = node.find("Enabled")
    if e is not None and e.text:
        enabled = e.text
    g = node.find("Greeting")
    if g is not None and g.text:
        greeting = g.text
    m = node.find("Mood")
    if m is not None and m.text:
        mood = m.text

result = {
    "message": f"Hello World plugin is {'enabled' if enabled == '1' else 'disabled'}!",
    "greeting": greeting,
    "mood": mood
}

print(json.dumps(result))

src/opnsense/service/conf/actions.d/actions_helloworld.conf — configd action registry:

[test]
command:/usr/local/opnsense/scripts/helloworld/test_message.py
parameters:
type:script_output
message:hello world test action

src/opnsense/service/templates/OPNsense/HelloWorld/+TARGETS — template output mapping:

helloworld.conf:/usr/local/etc/helloworld/helloworld.conf

src/opnsense/service/templates/OPNsense/HelloWorld/helloworld.conf — Jinja2 config generator:

{% if helpers.exists('OPNsense.helloworld.general.Enabled') and OPNsense.helloworld.general.Enabled == '1' %}
# HelloWorld Configuration
# Generated by OPNsense configd
enabled=1
greeting={{ OPNsense.helloworld.general.Greeting|default("Hello!") }}
mood={{ OPNsense.helloworld.general.Mood|default("happy") }}
{% endif %}

Setup on First Use

# Clone (or copy these files) into your plugins directory
mkdir -p /usr/plugins/devel/helloworld
# ... copy all files above ...

# One-time: get the real build infrastructure
fetch -o /usr/plugins/Mk/plugins.mk \
  https://raw.githubusercontent.com/opnsense/plugins/master/Mk/plugins.mk

# Build
cd /usr/plugins/devel/helloworld
make package

# Install
pkg install work/pkg/os-helloworld-*.pkg

# Clear caches (first install only)
rm -f /tmp/opnsense_menu_cache.xml
rm -f /tmp/opnsense_acl_cache.json

Browse to https://<firewall>/ui/helloworld/. You’ll see:

A form with Enabled (checkbox), Greeting (text), Mood (dropdown 😊🚀🐛)
Save button — persists to config.xml, triggers template regeneration
Test button — fires the configd action, displays JSON result inline

What This Plugin Demonstrates

Layer	File(s)	What it shows
Model	`HelloWorld.php` + `.xml`	Minimal `BaseModel`, mount path, field types (`BooleanField`, `TextField`, `OptionField` with values)
View	`index.volt`	Standard OPNsense JS patterns: `mapDataToFormUI`, `saveFormToEndpoint`, `SimpleActionButton`
Controller	`IndexController.php`	Page routing, form injection
API — Settings	`SettingsController.php`	`ApiMutableModelControllerBase` auto-generates get/set endpoints
API — Service	`ServiceController.php`	Manual actions: template reload + configd invocation with JSON parsing
Forms	`general.xml`	Field IDs matching model mount path
ACL	`ACL.xml`	URL patterns for UI + API, unique ACL key
Menu	`Menu.xml`	Sidebar placement, Font Awesome icon
configd	`actions_helloworld.conf`	Action type `script_output`, registering Python scripts
Script	`test_message.py`	Reading `config.xml` from disk, parsing XML, returning JSON to configd
Template	`helloworld.conf` + `+TARGETS`	Jinja2 conditionals, `helpers.exists()`, `

From here, you can adapt this exact skeleton to build your real plugin:

Add more fields to the form and model
Replace test_message.py with your actual backend logic
Switch ApiControllerBase → ApiMutableServiceControllerBase if you need daemon control
Add more tabs to the volt template for multi-page plugins

OPNsense Plugin Development

OPNsense Plugin Development

When to Build a Plugin vs. Install a Package

Architecture

Prerequisites

Directory Structure

Step-by-Step: New Plugin from Scratch

1. Pick a Template Plugin

2. Search & Replace — The Core Loop

3. Makefile

4. Model — Data Schema

5. Forms — UI Layout

6. Controllers

7. View — Volt Template

8. ACL — Access Control

9. Menu — Sidebar Entry

10. Backend Templates — Config File Generation

11. configd Actions — Daemon Control

12. setup.sh — /var Ramdisk Support

13. Service RC Template

Build & Test Cycle

Build the package

Install on test OPNsense

Replace an existing plugin

Test via API (as root)

Debugging

Walkthrough A: LLDP Plugin from Scratch

Part 1: Copy & Rename

Part 2: Templates, Actions, MVC Files

Part 3: Forms, Model, and Templating

Part 4: Adding a Diagnostics Tab

Walkthrough B: Enhancing FreeRADIUS with LDAP Support

Part 1: Verify Dependencies & Scaffold the MVC

Part 2: Define Fields (Forms + Model)

Part 3: Configuration Template

Part 4: Add Enable Checkbox, Build, and Debug

Submitting a Pull Request

Multi-language Support

Package Naming & Versioning

Hosting Your Own Plugin Repository

Option A: Manual Install (No Repo)

Option B: Self-Hosted pkg Repository

Option C: Keep Source in Your Own Git Repo

Quick Comparison

Walkthrough C: Repository Manager Plugin

Design

Step 1: Directory Setup

Step 2: Model

Step 3: Forms

Step 4: Template — Generate .conf Files

Step 5: Controllers

Step 6: View

Step 7: Menu & ACL

Step 8: Makefile

Result

Appendix: Hello World Plugin — Full Source Listing

File Tree

Source Code

Setup on First Use

What This Plugin Demonstrates

References