UniFi integration: network devices, Wi-Fi and networks, as part of the dependency map
A UniFi controller (API key on Network 9+, or a read-only local login on any version) is read every five minutes. Its switches, access points and gateways are kept with state, IP, uptime, firmware and uplink; its networks and Wi-Fi names beside them (passphrases are never read). Nothing is written to the controller. Network > Network devices lists them. Devices are a new node type in the dependency map: uplinks become dependencies by themselves, others can be written by hand. A device offline past a limit is an offline alert, folds what depends on it, can be silenced with maintenance and have runbooks. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
73a06ebe63
commit
396e074108
48 files changed
+6893
-102
No files matched your search
+24
-2
@@ -6,10 +6,10 @@ Homelab Manager (Integrations → Add integration, or DNS → Add
|
||||
provider). All credentials are entered in-app and encrypted at rest —
|
||||
nothing is read from environment variables.
|
||||
|
||||
Every adapter listed here performs write actions (starting/stopping
|
||||
Every adapter listed here except UniFi performs write actions (starting/stopping
|
||||
things, editing DNS records, etc.), not just reads — a read-only
|
||||
credential will fail as soon as you use one of those actions, even if
|
||||
the dashboard views themselves load fine.
|
||||
the dashboard views themselves load fine. (UniFi only ever reads.)
|
||||
|
||||
## Integrations
|
||||
|
||||
@@ -224,6 +224,28 @@ the dashboard views themselves load fine.
|
||||
run it against a real phpIPAM yet. If a sync comes back empty or with the wrong fields, tell us what your
|
||||
instance actually returned and we'll adjust.
|
||||
|
||||
### UniFi (Network application)
|
||||
|
||||
- **Config fields:** controller URL; **either** an API key, **or** a username and password; optionally one site; two checkboxes — *self-hosted Network application* and *allow self-signed certificate*.
|
||||
- **Two ways in:**
|
||||
- **API key** (UniFi Network 9 or later). In the controller, **Settings → Control Plane → Integrations → Create API key**. Used with the official Integration API: on a UniFi OS console (UDM, Cloud Gateway,
|
||||
Cloud Key Gen2+) at `https://<console>/proxy/network/integration/v1/…`, on a self-hosted Network application at `https://<host>:8443/integration/v1/…`. The form is found by asking, so the URL is
|
||||
just the console's address; tick *self-hosted* only to skip the first guess.
|
||||
- **Username and password** (any version, including ones from before API keys). Create a **local** user in the controller with **read-only** access to the site (a Ubiquiti cloud/SSO account, or one with
|
||||
two-factor, cannot be used). The classic endpoints are used (`/proxy/network/api/s/<site>/…`, or `/api/s/<site>/…` self-hosted), and the session is logged out after each read.
|
||||
- **Required access:** read only — and, unlike most integrations here, **nothing is ever written** to the controller.
|
||||
- **What it does:** every five minutes (and on **Read now**) the controller is read and kept: each device's name, model, kind (gateway, switch, access point), state, IP address, MAC address, uptime, firmware (and
|
||||
whether an update is waiting), and the device it is connected through; and the networks (VLAN, address range) and Wi-Fi names (security, which network) it has set up. Wi-Fi passphrases are never read into the app.
|
||||
It all appears on **Network → Network devices**.
|
||||
- A device is a **node in the dependency map**, like a server: the *connected through* link is made into a dependency by itself (an access point needs its switch, the switch needs the gateway), and you can write
|
||||
others by hand (a server needs the switch it is plugged into).
|
||||
- A device the controller has not seen online for longer than **Settings → Notifications → Alert when a network device is offline for** (10 minutes) is a critical **offline** alert about it. What needs it, and what
|
||||
it is connected through if that is down too, is folded under it, like a guest under its host. It can be silenced with a maintenance window, and has runbooks like any target.
|
||||
- If the controller cannot be read for twenty minutes its devices are neither raised nor cleared, and the Alerts page says it could not check; the integration itself is raised as failing like any other.
|
||||
- **Not verified against a live controller** — built from Ubiquiti's published Integration API and the long-documented classic API (and tried against a pretend controller that answers the way those documents say),
|
||||
but nobody has run it against real hardware yet. Every field is read defensively, so one a version renames is left blank rather than breaking the read. If a read fails or comes back empty, the **Diagnostic Log** has
|
||||
what the controller answered; tell us and we'll adjust.
|
||||
|
||||
## DNS providers
|
||||
|
||||
### Cloudflare
|
||||
|
||||
Reference in new issue
Block a user