Document network operations and WireGuard maintenance

2026-08-06 10:20:43 +08:00
parent 64484cd484
commit 29bdf06383
14 changed files with 678 additions and 4 deletions
@@ -0,0 +1,129 @@
+# UniFi network configuration
+
+## Controller
+
+| Item | Value |
+|---|---|
+| Host | [ubnt](../hosts/ubnt.md) |
+| Address | `192.168.66.46` |
+| Deployment | Docker, `jacobalberty/unifi:v9.5.21`, host networking |
+| Inform endpoint | `http://192.168.66.46:9080/inform` |
+| MongoDB database / port | `ace` / `27117` |
+
+Although `8080` is a common UniFi inform port, this controller uses `9080`.
+All AP adoption and recovery procedures must use the endpoint above.
+
+## Inter-VLAN reachability
+
+The AP management networks are routed by [gw](../hosts/gw.md),
+`192.168.66.254`. On 2026-08-05, a probe sourced from the LAN55 gateway
+(`192.168.55.254`) reached the controller (`192.168.66.46`) with 3/3 ICMP
+replies. The UAP-AC-Lite is online through the `:9080/inform` endpoint, which
+also confirms the required application path in practice.
+
+`LAN_IN` contains explicit allow rules for `192.168.55.0/24 ↔
+192.168.66.0/24`, but the firewall set is currently inactive (not attached to
+an interface). Treat the networks as bidirectionally reachable by default;
+do not rely on those inactive rules as an access boundary. Recheck this after
+attaching any LAN firewall policy or changing VLAN routing.
+
+To inspect device records from the controller host:
+
+```bash
+docker exec -it unifi-controller bash
+mongo --port 27117
+```
+
+```javascript
+use ace
+db.device.find(
+  { type: "uap" },
+  { name: 1, ip: 1, model: 1, inform_url: 1 }
+).pretty()
+```
+
+## Managed access points
+
+| Name | Model | Management IP | Firmware | Management network | Inform port |
+|---|---|---|---|---|---|
+| U6 Lite | U6 Lite (`UAL6`) | `192.168.66.6` | `6.7.54.15663` | LAN66 (`192.168.66.0/24`, gateway `192.168.66.254`) | `9080` |
+| UAP-AC-Lite | `U7LT` | `192.168.55.5` | `6.8.2.15592` | LAN55 (`192.168.55.0/24`, gateway `192.168.55.254`) | `9080` |
+
+AP MAC addresses are recorded only where operationally needed: U6 Lite
+`78:45:58:4d:cc:30`; UAP-AC-Lite `f0:9f:c2:20:04:e9`.
+
+## SSH administration
+
+Adopted APs use the SSH account configured in the controller, rather than the
+factory `ubnt/ubnt` credential. The password is stored in the password manager
+and must not be added to this repository.
+
+In UniFi Network `9.5.21`, configure it at:
+
+```text
+Devices → Device Updates and Settings → Device SSH Settings
+→ Device SSH Authentication
+```
+
+Use `ssh zhiqiangf@AP_IP` for the adopted-device account. Do not query or copy
+the controller's `mgmt` database setting into logs or documentation: it can
+contain the managed SSH password.
+
+On 2026-08-06, key-only IPv4 SSH was verified for both managed APs using the
+`zhiqiangf` account. Verify future access without permitting password or
+keyboard-interactive fallback:
+
+```bash
+ssh -4 -o BatchMode=yes -o PasswordAuthentication=no \
+  -o KbdInteractiveAuthentication=no -o StrictHostKeyChecking=yes \
+  zhiqiangf@192.168.66.6 'mca-cli-op info'
+ssh -4 -o BatchMode=yes -o PasswordAuthentication=no \
+  -o KbdInteractiveAuthentication=no -o StrictHostKeyChecking=yes \
+  zhiqiangf@192.168.55.5 'mca-cli-op info'
+```
+
+Both devices reported `Connected` to
+`http://192.168.66.46:9080/inform` during that verification. The AP shell maps
+this management account to UID 0, so treat it as administrative access.
+
+## Offline AP recovery
+
+An AP can be reachable via ICMP and SSH but offline in the controller when its
+saved inform URL still points to port `8080`. This occurred for UAP-AC-Lite
+after its inform configuration had diverged from the controller endpoint.
+
+From the AP, inspect the active endpoint and test controller reachability:
+
+```bash
+info
+nc 192.168.66.46 9080
+```
+
+The AP's BusyBox `nc` may not support `-zv`; use the plain `nc` invocation
+above when testing the TCP path.
+
+If `info` reports `http://192.168.66.46:8080/inform` (or another obsolete
+endpoint), correct it. UniFi devices commonly require the command twice while
+adoption is completed:
+
+```bash
+set-inform http://192.168.66.46:9080/inform
+set-inform http://192.168.66.46:9080/inform
+```
+
+Verify that the AP changes to connected/online in the controller.
+
+## Controller migration check
+
+After a controller migration or restore, inspect stored device records for a
+stale default-port endpoint before treating an AP as faulty:
+
+```javascript
+use ace
+db.device.find(
+  { inform_url: /8080/ },
+  { name: 1, ip: 1, inform_url: 1 }
+)
+```
+
+Do not include credentials or controller database dumps in incident notes.