Network-Commander/README.md

Network Commander - UniFi Diagnostics

Network Commander is a small UniFi controller helper that exposes useful diagnostics over HTTP and is designed to run as a container.

It connects to a UniFi Network Controller (or UniFi OS / UDM) and summarizes:

• Latency: average ping to one or more targets
• VLANs: number of configured VLAN networks
• Clients: how many clients are currently connected
• Throughput (approx): aggregate traffic counters from clients
• Site health: basic status from the controller

You deploy this as a Docker container and point it at your existing UniFi controller.

---

Configuration

The service is configured entirely via environment variables:

• UNIFI_CONTROLLER_URL: Base URL to your controller, e.g. https://unifi.example.com:8443
• UNIFI_USERNAME: Controller username (local admin account is recommended)
• UNIFI_PASSWORD: Controller password
• UNIFI_SITE: Site name / ID, defaults to default
• UNIFI_IS_UDM_PRO: true if using UniFi OS / UDM / Dream Machine, else false
• UNIFI_VERIFY_SSL: true to validate SSL certs, false to skip verification
• PING_TARGETS: Comma‑separated hosts to ping for latency, e.g. 1.1.1.1,8.8.8.8

All credentials should be supplied via environment variables or container secrets, never committed to Git.

---

Running locally

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export UNIFI_CONTROLLER_URL="https://unifi.example.com:8443"
export UNIFI_USERNAME="your_user"
export UNIFI_PASSWORD="your_password"
export UNIFI_SITE="default"
export UNIFI_IS_UDM_PRO="false"
export UNIFI_VERIFY_SSL="true"
export PING_TARGETS="1.1.1.1,8.8.8.8"

uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload

Once running, hit:

• GET /health – controller connectivity + basic site info
• GET /diagnostics/summary – high‑level metrics (latency, VLANs, clients, throughput)
• GET /diagnostics/clients – list of connected clients
• GET /diagnostics/vlans – list of VLAN/network definitions

---

Docker usage

Build the image:

docker build -t network-commander .

Run the container:

docker run --rm -p 8080:8080 \
  -e UNIFI_CONTROLLER_URL="https://unifi.example.com:8443" \
  -e UNIFI_USERNAME="your_user" \
  -e UNIFI_PASSWORD="your_password" \
  -e UNIFI_SITE="default" \
  -e UNIFI_IS_UDM_PRO="false" \
  -e UNIFI_VERIFY_SSL="true" \
  -e PING_TARGETS="1.1.1.1,8.8.8.8" \
  network-commander

You can then browse to http://localhost:8080/docs for the interactive Swagger UI.

---

Notes / ideas for future expansion

• Historical trends by periodically sampling and storing stats
• Prometheus metrics endpoint for easy scraping
• Alerting hooks (webhooks, Slack, etc.) for threshold breaches
• Multi‑site support exposed in the API