Skip to content

About

External router integrations for NetPulse: MikroTik RouterOS, Asuswrt and Asuswrt-Merlin agents that push signed snapshots to a self-hosted network dashboard.

Topics

Resources

Stars

14 stars

Watchers

0 watching

Forks

Repository files navigation

netpulse-integrations

External agents for router families that do not belong in the NetPulse core.

NetPulse supports two router sources in its own code: the native OpenWrt agent and generic SNMP. Vendor APIs, credentials and firmware quirks live here instead, one directory per family. A small supervisor runs one or more vendor pollers and sends signed data to POST /api/ingest/agent.

This keeps the NetPulse server small and avoids shipping code for hardware the core maintainers cannot test. An integration can be released on its own schedule without forcing every NetPulse user to carry it.

Integrations

Directory Transport Coverage
routeros/ RouterOS binary API on port 8728, REST fallback RouterOS 7+: system, Ethernet ports, DHCP, ARP, bridge FDB, temperature, flash, firmware state and WAN rates
bbox/ Bbox local HTTPS API System, WAN, active hosts and Ethernet port rates
opnsense/ OPNsense HTTPS API, read-only, beta System, interface counters announced as ports, IPv4 ARP, WAN rates with an explicitly selected interface, per-client traffic, memory, the hottest temperature sensor, uptime, load average and CPU usage. Validated against OPNsense 26.7 in a VM and on a user unit
asuswrt/ Local Asuswrt/Merlin probes System, wireless, DHCP, ARP, FDB, LLDP, interfaces and WAN data exposed by the firmware
unifi/ UniFi controller REST API, read-only Gateways, switches and APs of one site: FDB ports and uplink attachments, wireless clients, ARP identities and gateway uptime
fn/ Switch web JSON backend (/cgi/get.cgi?cmd=...) plus its SSH CLI Realtek RTL930x SDK managed switches (FN SWITCH 8 PRO and siblings): CPU load, port speeds, octet counters, FDB, LLDP neighbors, model, firmware, uptime; fan temperature and memory bytes from the CLI

All integrations are read-only: they read router data and do not change configuration or install or upgrade firmware.

Vendor catalog

vendors.json is the machine-readable catalog NetPulse core fetches to discover integrations, so adding a vendor never requires a NetPulse release. It holds one entry per vendor directory and CI keeps it in sync with the repository: .github/validate_vendors.py (stdlib only) runs on every push and pull request and fails on drift between the catalog, the vendor directories and the release workflow.

Field Meaning
id Vendor directory name: lowercase, unique, entries sorted by it
mode How NetPulse runs the agent: local (managed child on the NetPulse host) or ssh (installed on the router itself)
arches Linux architectures the release workflow builds for this vendor
tagPrefix Release tag prefix, <id>/v; the workflow listens on <tagPrefix>* tags
binary Name of the published binary for this vendor
target Go build target directory (<target>/main.go) compiled for the tag
description One-line summary shown by NetPulse

Why a separate repository

  • Different lifecycles. Router integrations follow vendor firmware releases, not NetPulse releases.
  • Isolated credentials. Router passwords and API tokens stay inside the integration config, never in the NetPulse server.
  • Hardware-specific ownership. Each integration has its own maintainer, who can validate it on supported hardware.

Install

Build the shared supervisor. It runs configured vendor pollers in one process and does not require Docker. The Asuswrt poller uses local shell probes, so the supervisor must run on the Asuswrt/Merlin device when that integration is configured.

go build -trimpath -o netpulse-integrations ./cmd/integrations-supervisor

Create each router in NetPulse as type external, obtain its agent token and add its vendor connection details to the supervisor JSON config. Keep the config readable only by the service account; it contains passwords and agent tokens. Install the shared unit from deploy/netpulse-integrations.service.

The supervisor accepts multiple vendor entries in one JSON config. Each integration keeps its own directory, poller and documentation while sharing the process, service unit and update path.

The server trust settings apply to every supervisor integration. Use the root-level server_fp for NetPulse's self-signed HTTPS certificate or when the certificate name does not match the server URL; use ca_file for a private CA when the certificate name matches. Configure one or the other. Standalone pushers use the same delivery client and accept the equivalent NETPULSE_SERVER_FP or NETPULSE_CA_FILE environment variable.

A fingerprint is the SHA-256 SPKI hash of the certificate the server presents, which is normally the leaf. Pinning a CA only matches a CA that the server actually sends in its chain, so a pin computed from a root CA fails when the server omits that root, as most servers do. The failure is an ordinary TLS verification error, with no hint that the pin format is the problem.

The delivery client follows a redirect only when it stays on the same scheme, host and port, and only when the request keeps its POST method and body, which in practice means 307 and 308. A 301, 302 or 303 is refused with an explicit error because the ingest endpoint accepts only a signed POST, and a redirect to another origin is always refused so the token and the signature never leave the configured server.

Every push is a signed HTTP request to POST /api/ingest/agent. The ingest contract, authentication, payload semantics and contribution rules are in the NetPulse guide:

https://github.com/gnacho/netpulse/blob/main/docs/external-integrations.md

Development

Go 1.26 or newer.

gofmt -l .
go vet ./...
go test ./...

CI runs the same checks, race-enabled tests and static builds for every pull request. Tags such as routeros/v0.1.0 and asuswrt/v0.1.0 run the tests and publish a static Linux binary tarball with its SHA-256 file. RouterOS releases currently target amd64 and Asuswrt releases target ARM64. Tags for integrations running under the supervisor publish the supervisor binary for amd64 and arm64.

Adding an integration

  1. Open an issue in the NetPulse repository with the router model, firmware, API documentation, available data and a read-only first scope.
  2. Add a directory named after the family, with README.md and CHANGELOG.md; keep its poller and vendor-specific details inside that directory.
  3. Add a poller constructor to the shared supervisor. Keep vendor credentials and parsing inside that directory. Ask NetPulse maintainers for neutral contract fields before depending on them.
  4. Include fixtures and tests. Real-hardware evidence is required before stable support; a docs-based beta must say so explicitly and list its unverified behavior.
  5. Add a CODEOWNERS entry for the directory. The owner of the hardware maintains it and validates releases.
  6. Add an entry to vendors.json with the release values and a short description. CI validates the catalog against the release workflow and fails on drift.
  7. Tag releases per integration, for example routeros/v0.1.0. The release workflow tests the repository and publishes the documented platform asset. Validate the integration on real hardware before calling it stable. A beta tag for community validation must be labeled beta in the catalog and documentation, with its limitations and evidence gaps stated.

The maintainer of this repository decides who owns each directory. Directory ownership is not transferred by sending a pull request.

Links

License

GNU Affero General Public License v3.0. See LICENSE.

About

External router integrations for NetPulse: MikroTik RouterOS, Asuswrt and Asuswrt-Merlin agents that push signed snapshots to a self-hosted network dashboard.

Topics

Resources

Stars

14 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages