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:
bobbanandClaude Sonnet 5.5 committed 2026-10-20 00:35:48 +02:00
1 parent 73a06ebe63
commit 396e074108
48 files changed
+6893 -102

No files matched your search

+46 -4
View File
@@ -55,6 +55,8 @@ erDiagram
endpoint_checks ||--o{ endpoint_results : "cascade"
heartbeats ||--o{ heartbeat_pings : "cascade"
integration_credentials ||--o{ integrations : "credential (set null)"
integrations ||--o{ network_devices : "cascade"
integrations ||--o{ network_segments : "cascade"
integration_credentials ||--o{ dns_providers : "credential (set null)"
dns_providers ||--o{ dns_zones_cache : "cascade"
dns_providers ||--o{ dns_records_cache : "cascade"
@@ -148,7 +150,7 @@ required, so a forgotten window can't silence real problems forever.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `target_type` | text NOT NULL | `server` \| `integration` \| `dns_provider`. |
| `target_type` | text NOT NULL | `server` \| `integration` \| `dns_provider` \| `device`. |
| `target_id` | integer NOT NULL | The ID in the table `target_type` names. **Not a foreign key**; a window whose target was deleted is simply ignored. |
| `reason` | text | |
| `started_at`, `ends_at` | text NOT NULL | ISO. |
@@ -456,6 +458,8 @@ JSON) plus a few internal bookkeeping rows. Details under
| `value` | text NOT NULL | JSON (or a plain date/time for internal flags). |
| `updated_at` | text NOT NULL | |
Internal flag `unifiSync`: a JSON object keyed by integration id, `{ at (ISO — the last *successful* read), ok, error, sites, mode, devices, networks, ssids }`. A controller whose `at` is older than twenty minutes is not judged for offline devices.
Internal flag `flapState`: a JSON object keyed by alert key, `{ raises: number[] (epoch ms of raises in the last hour), flapping: boolean, since, lastEvent, message }`. It is what lets a restart remember which alerts are being held as flapping; entries are dropped once an alert has been calm for an hour.
#### `tag_definitions`
@@ -641,17 +645,55 @@ The hardware inventory.
#### `dependencies`
"A needs B" between servers and integrations: when B is down, A's alert is folded under B's. The "runs on" links of servers are part of the same graph but live on `servers`.
"A needs B" between servers, network devices and integrations: when B is down, A's alert is folded under B's. The "runs on" links of servers are part of the same graph but live on `servers`, and the "connected through" links of network devices on `network_devices`.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `from_type`, `from_id` | text, integer NOT NULL | The thing that needs: `server` or `integration`, and its id. |
| `from_type`, `from_id` | text, integer NOT NULL | The thing that needs: `server`, `integration` or `device`, and its id. |
| `to_type`, `to_id` | text, integer NOT NULL | The thing it needs. Unique together with the pair above. |
| `created_at` | text NOT NULL | ISO. |
No foreign keys (like `maintenance_windows`): a row whose server or integration is gone is ignored, not an error.
#### `network_devices`
Switches, access points and gateways read from a UniFi controller (see INTEGRATIONS.md), refreshed every five minutes. A device is a node of the dependency map as `device:<id>`.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `integration_id` | integer NOT NULL → `integrations.id`, **cascade** | The controller. Unique together with `external_id`. |
| `external_id` | text NOT NULL | The MAC address, lower case with colons. |
| `site_name`, `name`, `model` | text | |
| `kind` | text NOT NULL | `gateway` \| `switch` \| `access_point` \| `other`. |
| `ip`, `mac` | text | |
| `state` | text NOT NULL | `online` \| `offline` \| `updating` \| `pending` \| `other`. Only `offline` raises an alert. |
| `uptime_seconds` | integer | |
| `firmware` | text | |
| `firmware_updatable` | bool NOT NULL | |
| `uplink_external_id` | text | The MAC of the device this one is connected through; what makes it depend on that device. |
| `offline_since` | text | ISO. When the controller first stopped seeing it online; null while online. The offline alert counts from here. |
| `last_online_at`, `first_seen_at`, `updated_at` | text | ISO. |
A device the controller no longer lists is deleted on the next read. Dependencies written by hand that mention a removed device are ignored.
#### `network_segments`
The networks (VLANs) and Wi-Fi names of a UniFi controller, replaced as a whole on every read. Passphrases are never stored.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `integration_id` | integer NOT NULL → `integrations.id`, **cascade** | Unique together with `kind` and `external_id`. |
| `kind` | text NOT NULL | `network` \| `ssid`. |
| `external_id`, `site_name`, `name` | text | |
| `enabled` | bool NOT NULL | |
| `vlan_id` | integer | |
| `subnet`, `purpose` | text | A network's address range and what it is for. |
| `security`, `network_name` | text | A Wi-Fi name's security, and the network its clients land on. |
| `updated_at` | text NOT NULL | ISO. |
#### `push_subscriptions`
A browser or phone that asked for push notifications, one row per device.
@@ -855,7 +897,7 @@ that were never changed aren't stored; the app fills in defaults when reading.
| `inventory` | `currency` (a short name, may be blank) and `pricePerKwh` (null) — what the inventory's running cost is worked out with. |
| `monthlyReport` | The monthly report: `enabled` (false), `day` (1–28, default 1) and `time` (`HH:MM`, default `08:00`), in the notification time zone. |
| `digest` | The weekly digest: `enabled` (false), `day` (0 = Sunday … 6; default 1, Monday) and `time` (`HH:MM`, default `08:00`), in the notification time zone. |
| `healthChecks` | `restoreTestDays` (0 = off — how long a guest's last passing restore test counts; a failed one is always raised), `serverOfflineMinutes` (60), `diskUsagePercent` (90), `domainWarnDays` (30), `diskForecastDays` (14; 0 = off — how far ahead a filling disk is flagged on the Alerts page), `backupStaleHours` (48; 0 = off — how old a Proxmox guest's newest backup may be), `newPortAlerts` (true — warn when a server starts listening on a TCP port that is not in its baseline and not noted), `flapRaises` (3; 0 = off — raises of one alert within an hour that make it "flapping" so its messages are held; see NOTIFICATIONS.md). A server can override each of these (see `servers.thresholds`). |
| `healthChecks` | `restoreTestDays` (0 = off — how long a guest's last passing restore test counts; a failed one is always raised), `serverOfflineMinutes` (60), `diskUsagePercent` (90), `domainWarnDays` (30), `diskForecastDays` (14; 0 = off — how far ahead a filling disk is flagged on the Alerts page), `backupStaleHours` (48; 0 = off — how old a Proxmox guest's newest backup may be), `newPortAlerts` (true — warn when a server starts listening on a TCP port that is not in its baseline and not noted), `flapRaises` (3; 0 = off — raises of one alert within an hour that make it "flapping" so its messages are held; see NOTIFICATIONS.md), `deviceOfflineMinutes` (10 — how long a UniFi device may be offline before it is raised). A server can override each of these (see `servers.thresholds`). |
| `logRetention` | `enabled`, `retentionDays` (90), `intervalHours` (24). |
| `display` | `dateFormat`, `timeFormat`, `pageSize`. |
| `providerColors`, `integrationColors` | Badge colours, by provider / integration type. |