93 lines
2.8 KiB
Markdown
93 lines
2.8 KiB
Markdown
## 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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
docker build -t network-commander .
|
||
```
|
||
|
||
Run the container:
|
||
|
||
```bash
|
||
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
|
||
|