# 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