# 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.

IPv6 is enabled on the controller's `Default` network (`ipv6_enabled: true`,
client assignment SLAAC; RA is served by `gw`, so `ipv6_interface_type` is
`none`); both managed APs hold global SLAAC addresses — verified 2026-08-20.
See [docs/unifi-network.md](../docs/unifi-network.md).

## 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).