107 lines
2.9 KiB
Markdown
107 lines
2.9 KiB
Markdown
# UniFi network operator access for Doris
|
|
|
|
## Goal
|
|
|
|
Give Doris safe, durable read access to the UniFi Network controller at `https://10.5.0.1` so she can:
|
|
|
|
- verify gateway / switch / AP inventory
|
|
- refresh RackPeek network device data
|
|
- check client/device state during troubleshooting
|
|
- avoid using your full owner account for routine reads
|
|
|
|
## Preferred access model
|
|
|
|
Use a **dedicated local Doris account** on UniFi OS with the **least privilege that still allows Network inventory reads**.
|
|
|
|
Target shape:
|
|
|
|
- Account name: `doris` or `doris-unifi`
|
|
- Scope: **Network application only**
|
|
- Permission: **view-only / read-only** if UniFi exposes that role cleanly
|
|
- Local account: yes
|
|
- Cloud account sharing: no
|
|
|
|
If UniFi's UI forces a broader role for API readability, use the narrowest app-scoped permission available and document the final role here.
|
|
|
|
## Secrets placement
|
|
|
|
Do **not** commit credentials to git.
|
|
|
|
When the Doris UniFi account exists, store the live credential in:
|
|
|
|
- PD live env: `/mnt/docker-ssd/docker/compose/automation/.env`
|
|
- synced encrypted backup: `/mnt/docker-ssd/docker/secrets/env/automation.env`
|
|
|
|
Expected vars:
|
|
|
|
```bash
|
|
UNIFI_BASE_URL=https://10.5.0.1
|
|
UNIFI_USERNAME=doris
|
|
UNIFI_PASSWORD=REPLACE_ME
|
|
UNIFI_SITE=default
|
|
UNIFI_VERIFY_TLS=false
|
|
```
|
|
|
|
After editing the live `.env` on PD, run the normal secrets sync:
|
|
|
|
```bash
|
|
export PATH="/mnt/docker-ssd/bin:$PATH"
|
|
bash /mnt/docker-ssd/docker/compose/scripts/sync-envs-to-secrets.sh
|
|
```
|
|
|
|
## Doris helper
|
|
|
|
Repo helper:
|
|
|
|
- `automation/bin/unifi_network.py`
|
|
|
|
Default behavior:
|
|
|
|
- loads `automation/.env`
|
|
- logs into UniFi OS with cookie auth
|
|
- queries Network app endpoints through `/proxy/network/api/s/<site>/...`
|
|
- prints a JSON inventory summary without exposing the password
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
cd /mnt/docker-ssd/docker/compose
|
|
python3 automation/bin/unifi_network.py
|
|
python3 automation/bin/unifi_network.py --raw
|
|
```
|
|
|
|
## Validation checklist
|
|
|
|
1. Confirm `https://10.5.0.1` is reachable from Doris's host.
|
|
2. Create the dedicated UniFi operator account.
|
|
3. Add the `UNIFI_*` vars to live `automation/.env` on PD.
|
|
4. Sync secrets repo.
|
|
5. Run:
|
|
|
|
```bash
|
|
cd /mnt/docker-ssd/docker/compose
|
|
python3 automation/bin/unifi_network.py
|
|
```
|
|
|
|
Success means Doris can read:
|
|
|
|
- device inventory
|
|
- controller health summary
|
|
- connected client list
|
|
|
|
## Future integration
|
|
|
|
Once access is verified, use the helper as an input for:
|
|
|
|
- RackPeek network device refreshes
|
|
- dashboard network summaries
|
|
- targeted checks like "what AP is this client on" or "is switch X offline"
|
|
|
|
## Current status
|
|
|
|
- UniFi OS front door verified reachable at `https://10.5.0.1`
|
|
- unauthenticated API requests correctly return `401 Unauthorized`
|
|
- Doris helper scaffold exists in the repo
|
|
- dedicated Doris account validated end-to-end against the `default` site from N.O.M.A.D.
|
|
- current verified read scope is sufficient to read device inventory, controller health, and connected clients
|