truenas-stacks/docs/operations/UNIFI_NETWORK_ACCESS.md

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:

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:

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:

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:

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