Opnsense as the gateway

[gnacho]

Hi @gnacho

Just a quick word to say thank you and a request. This tool was very useful for tracking roaming issue between 3 Flint 2s running openwrt 25.

My request is support for opnsense as the gateway. My setup is opnsense as the router and then openwrt for APs

Thanks again John

---

Moved from issue #1050 to keep the issue tracker for bugs and in-flight work. Originally posted by @harpyeagle.

[gnacho]

Short answer: this is already viable without touching the core, and it does not need the ssh deployment mode.

Since the router integration policy in #1575, a vendor family is a pusher in netpulse-integrations, not an adapter in the server. NetPulse resolves the latest release of that repository, verifies the SHA-256 against the published checksums and runs it, so the core only keeps the signed ingest contract. That is exactly what RouterOS and Asuswrt do today.

OPNsense fits that shape better than most, because it exposes its own API over HTTPS. That means the pusher runs in the local mode, as a supervised process on the NetPulse host, talking to the OPNsense API from there. No procd, no /jffs, no dropbear, nothing installed on the firewall. Concretely, the work would be:

• a directory opnsense/ in netpulse-integrations with its poller and its README,
• an entry in the vendor manifest of the core with mode: local and the release tag prefix, which is a few lines because the manifest already supports that combination,
• a opnsense/v0.1.x release so the app can install it from the Integrations section.

What I cannot do honestly is write it blind. Building against an API I cannot run would produce a pusher that compiles, passes its tests and then reports nothing real on the first firewall it meets, which is worse than not having it.

So what would be genuinely useful from someone who runs OPNsense:

1. Confirmation of how the API key and secret are issued and scoped, and which account is the right one for a read-only collector.
2. The endpoints that actually answer a question worth answering: interfaces and their state, ARP and the neighbour table, DHCP leases, aliases, gateways. What is reliable and what is deprecated between versions matters, since OPNsense has moved some of this over the years.
3. How the traffic counters behave, in what units, and whether they reset on a service restart, because that decides whether history comes out right or full of phantom spikes.
4. A real run, so the payload can be checked against what the firewall really reports.

@harpyeagle, you are the person who asked for this and you run exactly that setup, OPNsense as the gateway with Flint 2 access points behind it. Would you be up for it? If you can answer the first three and run a build once, I will open an issue in netpulse-integrations with the contract and a checklist and we work it there. If you would rather only provide captures of the API responses, that works too, and it is already a big part of the job.

No promise on a date from my side. There is one open item ahead of this in the same area, the fingerprint re-derivation in #1691, and the Asuswrt SSH layout in #1681 is half blocked on hardware answers. But nothing in this list blocks OPNsense, which is why it is worth saying out loud that the door is open and what it costs to walk through.

[gnacho]

@harpyeagle, we have published a first OPNsense beta based on your request: opnsense/v0.1.0-beta.1.

This is a read-only integration built from the official OPNsense documentation and synthetic fixtures. It has not been tested on a real OPNsense installation yet, so your feedback would be very valuable.

To try it:

1. Create an API key and secret for an OPNsense user limited to the relevant read-only Diagnostics permissions. See the OPNsense API how-to.
2. In NetPulse, open Settings > Integrations > Add integration. If OPNsense does not appear, use Refresh next to the vendor selector to update the catalog.
3. Select OPNsense, marked Beta in the catalog, use https://<your-opnsense-host> as the host, the API key as username and the API secret as password, then create and start the integration.

The beta should report system identity/version, interface counters and IPv4 ARP neighbors. It never writes configuration to OPNsense.

Two current limitations of the managed installer:

• It sets OPNSENSE_INSECURE=1, so the firewall certificate is not verified. For this first test, use a trusted network. The manual setup supports a CA or certificate fingerprint instead.
• It does not select a WAN interface yet, so WAN rates are not expected through the managed installer. The manual setup supports an explicit OPNSENSE_WAN_INTERFACE.

If it fails or reports something unexpected, please reply with your OPNsense version, the integration error and, if needed, sanitized responses from the relevant API endpoints. Please do not include API keys, secrets, tokens or other sensitive data.

[harpyeagle]

Thanks for this, and for turning it round so quickly. opnsense/v0.1.0-beta.2 is running and pushing every 30s. OPNsense now sits at the top of the topology with the Flint 2s under it.

Environment: NetPulse 2.51.x on Unraid, run as a binary (no systemd), and OPNsense 26.7.

1. Possible secret truncation. The pusher got a 401 on system_information, while the same key and secret worked with curl. The secret is 80 characters and contains + and /, but it was stored in OPNSENSE_PASS as 79 characters. It may have been a paste slip on my side, but it's worth a look. Writing the secret into the .env by hand fixed it.

2. Minimum privileges. Diagnostics: ARP Table, Diagnostics: Netstat and Lobby: Dashboard are enough. System: Firmware isn't needed, even though core/firmware/status returns 403 without it. These might be worth adding to the README.

3. The router record can't be edited. The record is created with host https://, and the edit form rejects that with "host debe ser una IP o hostname válido". I changed it to the bare IP to save, which also let me set it as the gateway.

4. No system metrics yet. CPU, memory and uptime would bring it in line with the other routers.

I'm happy to test further builds. Thanks again.

[harpyeagle]

5. Stale client IPs. The APs (Flint 2s, previously used as routers) kept old client entries in GL.iNet's client cache, some still marked online. NetPulse used those IPs over the OPNsense pusher's live ARP data, so some guest-VLAN devices appeared to be on the trusted LAN. Clearing the cache on the APs fixed it. Suggest giving gateway ARP/lease data priority over the AP's cached IPs.

Workaround: enable Auto Remove Offline Clients in the GL.iNet panel, clear the client cache on each AP, then clear device_seen.ip.

[gnacho]

Thanks for running it, this is exactly what the beta needed. Yes, please open these in netpulse-integrations, one issue per item, so they sit next to the pusher code:

1. System metrics. Uptime is already in the payload, it comes from system_information, so if the card shows a dash for it as well, say so and I will look at the mapping on the server side. CPU, memory, load and temperature are not collected yet. The API reference lists diagnostics/system/system_resources and diagnostics/system/system_temperature, and we have no capture of either response, so a sanitized sample from your 26.7 would save a round trip.
2. Minimum privileges. You are right, the README explains how to create the key but not which permissions are enough. Diagnostics: ARP Table, Diagnostics: Netstat and Lobby: Dashboard go in, plus the note that System: Firmware is not needed even though core/firmware/status answers 403 without it.

The router record is not a pusher problem, so it is tracked in #1968. The integration creates the unit with the host exactly as typed, https://..., and the unit form only accepts an IP or a hostname. The unit should keep the bare host and the URL should stay in the integration.

On the secret: nothing in the path truncates it. The form has no length limit, the env writer escapes and round-trips the whole value, and the parser splits on the first =. A paste that loses the last character is the most likely explanation, as you say. If it happens again, before fixing it by hand, note the length in the form and the length in OPNSENSE_PASS and tell me both. That would turn it into a real bug with a reproduction.

[gnacho]

@harpyeagle thanks for the details, they were enough to reproduce the host problem from the code.

Fixed in main as 648c69c (#1969). What changed: the router unit created by an external integration now stores the bare host, with scheme, port and path stripped, and existing rows are normalized on the next startup. The unit form opens and saves again, and the gateway flag can be set without retyping the host. The integration form itself still accepts the full URL, so nothing changes on the setup side.

This will be in the next NetPulse release. #1968 is closed.

[harpyeagle]

Thanks for the quick fix on #1968, much appreciated.

I've opened the two pusher items in netpulse-integrations:

• System metrics: OPNsense: system metrics (CPU, memory, load, temperature) netpulse-integrations#55
• Minimum API privileges: OPNsense: document minimum API privileges netpulse-integrations#56

I also added a point to my comment above about stale client IPs from the APs' GL.iNet cache. It's a NetPulse issue rather than a pusher one, so let me know if you'd prefer it as a separate issue.

Thanks again.