81 lines
2.9 KiB
Markdown
81 lines
2.9 KiB
Markdown
# ubnt — UniFi Network Controller
|
|
|
|
## Role and access
|
|
|
|
| Item | Value |
|
|
|---|---|
|
|
| Role | UniFi Network Controller host |
|
|
| IPv4 | `192.168.66.46` |
|
|
| SSH | `ssh -4 windy@192.168.66.46` |
|
|
| Hostname | `ubnt` |
|
|
| **Host** | **PVE VM 160 (`ubnt`)** — not a separate physical host (verified 2026-08-09) |
|
|
| Privilege | `windy` has passwordless sudo and is in the `docker` group |
|
|
|
|
The current SSH ED25519 host-key fingerprint is
|
|
`SHA256:TTZtonJnnnNS6vk4xqo+CJPuZGXwwkf46wR1SLmqc10` (verified 2026-08-03).
|
|
Verify a changed key out of band before accepting it.
|
|
|
|
## UniFi stack
|
|
|
|
| Item | Value |
|
|
|---|---|
|
|
| Compose directory | `/home/windy/unifi-9` |
|
|
| Compose file | `/home/windy/unifi-9/compose.yml` |
|
|
| Compose service | `unifi` |
|
|
| Container | `unifi-controller` |
|
|
| Image | `jacobalberty/unifi:v9.5.21` |
|
|
| Network mode | host |
|
|
| HTTPS UI | `https://192.168.66.46:8443` |
|
|
| Device inform endpoint | `http://192.168.66.46:9080/inform` |
|
|
|
|
The controller binds `*:8443`. A local HTTPS request to
|
|
`https://127.0.0.1:8443/` is the primary quick health check.
|
|
|
|
## Proxy contract
|
|
|
|
The container has HTTP/HTTPS proxy environment variables. Its Compose
|
|
`environment` list must keep **both** `NO_PROXY` and `no_proxy` enabled and
|
|
include at least:
|
|
|
|
```text
|
|
localhost,127.0.0.1,::1,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12
|
|
```
|
|
|
|
Without this bypass, a controller request to `localhost:8443` can be sent to
|
|
the OpenClash gateway instead of remaining local. Details and verification are
|
|
in [the UniFi localhost proxy note](../docs/unifi-openclash-localhost.md).
|
|
|
|
## Managed access points
|
|
|
|
The controller manages the APs listed in [the UniFi network record](../docs/unifi-network.md).
|
|
The inform endpoint is deliberately on port `9080`, not UniFi's common default
|
|
of `8080`. During adoption or recovery, use the documented `:9080/inform` URL;
|
|
an AP left on `:8080` can remain reachable by ping and SSH while showing
|
|
offline in the controller.
|
|
|
|
## Safe reconciliation and verification
|
|
|
|
```bash
|
|
cd /home/windy/unifi-9
|
|
docker compose config -q
|
|
docker compose up -d --force-recreate unifi
|
|
docker inspect --format '{{.State.Health.Status}}' unifi-controller
|
|
curl -k -sS -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8443/
|
|
```
|
|
|
|
Recreating the service briefly interrupts the controller. Do not use `docker
|
|
compose down -v`; it can remove persistent data.
|
|
|
|
## Ansible management
|
|
|
|
The host is in the Ansible `unifi` group (inventory `ansible/inventory/hosts.yml`),
|
|
deliberately outside `managed` so the generic health report does not run here.
|
|
|
|
- SSO login setting (idempotent, gated): `cd ansible && ansible-playbook
|
|
playbooks/unifi-sso.yml --limit unifi` — see
|
|
[runbooks/ansible-operations.md](../runbooks/ansible-operations.md).
|
|
- Login/MFA state: SSO login disabled 2026-08-08; local accounts
|
|
(`windy`, `zhiqiangf`) use local passwords, no MFA. `unifi-network-mcp`
|
|
works for read and write operations. See
|
|
[docs/unifi-network.md](../docs/unifi-network.md).
|