Perch

Perch started because managing three access points meant three browser windows plus iftop. I wanted one dashboard that shows where the traffic goes, per device, per protocol and per access point, the way UniFi does for its own hardware. It now runs my home network and a friend's.

Three parts

Each part has its own repository.

• The controller is an AdonisJS app on MariaDB. It takes in what the agents report, keeps the history, serves the API and serves the React dashboard. The scheduler and the agent sessions live in the same process, so you run exactly one.
• The collector is written in Go. It captures packets with libpcap and names the protocols with nDPI. It ships as an OpenWrt package, and on the router it also reports conntrack, load, memory and WAN rate from /proc. Nothing else has to run on the router, not even node_exporter.
• The AP daemon runs on each OpenWrt access point. It replaces the Prometheus exporter and gives the controller a way to kick or steer a client, blink an AP to find it, or reboot it, all without SSH.

Agents dial out

The collector and the AP daemon both open a WebSocket to the controller and speak JSON-RPC over it. The controller tells each one how often to report, and the agent pushes its numbers on that schedule.

Nothing on the router or the access points listens on a port. A new collector shows up in the dashboard as pending, and it sends nothing until you adopt it, much like a device joining a UniFi controller. An access point joins with a token you create in the dashboard, which then shows the install command.

History

Traffic lands in buckets of about 5 seconds, kept for 30 days. Rollups to 5 minutes, hours and days are kept for two to five years. Every window is configurable.

Running it

The controller and its database come up with one compose file:

curl -fsSLO https://raw.githubusercontent.com/capthndsme/perch-controller/main/docker-compose.yml
docker compose up -d

Open port 8080, create the admin account, then install the collector package on the router and adopt it. Access points can join in any order after that.

Plain HTTP works, but it encrypts nothing, so anything that can intercept LAN traffic can read what the agents send. The README explains how to put the controller and the devices' management addresses on a VLAN of their own, or serve it over HTTPS.

Perch is at v1.0 under the MIT license. The images are on GHCR, and the collector has packages for five router architectures, MIPS included.