A UPS in the map: read over NUT or SNMP, alerts, shutdown order

New UPS integration (NUT or SNMP v2c, read only). Monitoring -> UPS shows charge,
runtime, load and mains voltage with history and the times mains power was lost.
Mains lost and a nearly empty battery are critical alerts; battery to be replaced
and a heavy load are warnings. The UPS is a node in the dependency map and counts
as down while on battery, so servers that go offline with it are folded under its
alert; the page lists what is on it in the order to shut it down. /metrics series
and docs added.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-21 21:47:31 +02:00
1 parent 3cb3e4988f
commit 232a5661ab
38 files changed
+8049 -16

No files matched your search

+22 -2
View File
@@ -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 except UniFi, Nginx Proxy Manager and Home Assistant performs write actions (starting/stopping
Every adapter listed here except UniFi, Nginx Proxy Manager, Home Assistant and the UPS 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. (UniFi, Nginx Proxy Manager and Home Assistant only ever read.)
the dashboard views themselves load fine. (UniFi, Nginx Proxy Manager, Home Assistant and the UPS only ever read.)
## Integrations
@@ -276,6 +276,26 @@ the dashboard views themselves load fine. (UniFi, Nginx Proxy Manager and Home A
- A service reached at a server's address (the integration's URL) is offered as a suggested dependency on that server.
- **Not verified against a live Home Assistant** — built from its published REST API and tried against a pretend one. Every field is read defensively. If a read fails, the **Diagnostic Log** has what it answered.
### UPS (NUT or SNMP)
- **Config fields:** the **host** (the machine running NUT's `upsd`, or the UPS's own network card), a checkbox to read it **over SNMP instead of NUT**, and optionally the **port** (3493 for NUT, 161 for SNMP), the UPS's **name** on the NUT
server (the first one it lists when blank) and the SNMP **read community** (`public` when blank; stored encrypted).
- **Required access:** read only. **NUT:** `upsd` must listen on an address this server can reach (`LISTEN` in `upsd.conf`; the default is only the machine itself) and, if `upsd.users`/`ACL` limit who may ask, allow
this host. Only `LIST UPS` and `LIST VAR <ups>` are sent — no command, no login. **SNMP:** version 2c, a `GET` of the standard UPS-MIB (RFC 1628, `1.3.6.1.2.1.33`), which most UPSs and their network cards answer;
APC-only or other private objects are not used. **Nothing is ever set.** The host is checked like an endpoint check's: not this machine itself, not the cloud metadata address; your own network is fine.
- **What it does:** every **minute** the UPS is read and stored — its state, and a point for the charts (every five minutes, and every minute while on battery; kept 35 days): battery charge, runtime left, load, mains
voltage in and out, model and maker. **Monitoring → UPS** shows it, with the history and the times mains power was lost.
- **Alerts** (category *Monitoring*, source *UPS*; announced and recovered like the other health problems, held back by maintenance on the integration): **mains power has failed — running on battery** (critical;
NUT `OB`, SNMP output source *on battery*), **the battery is nearly empty** (critical; NUT `LB`, SNMP battery low or depleted), **the UPS asks for its battery to be replaced** (warning; NUT `RB`), and **a load of 90 %
or more, or an overload** (warning; NUT `OVER`).
- **It is a node in the dependency map** (`integration:<id>`): say what it powers under **Map → Dependencies**. While it runs on battery it counts as *down*, so servers that go offline with it are folded under its
alert (which says "also takes down …") instead of each being announced. The UPS page lists what needs it in the **order to shut it down** — what nothing else needs first, then what that needed — so nothing is
switched off while something that depends on it is still running.
- If the UPS cannot be read for five minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other.
- `/metrics` has `homelab_ups_on_battery`, `homelab_ups_battery_charge_percent`, `homelab_ups_runtime_seconds`, `homelab_ups_load_percent` and `homelab_ups_input_volts` for each UPS that was read lately.
- **Not verified against a real UPS** — NUT's protocol and the UPS-MIB are as published, and both readers are tried against pretend servers. Some UPSs leave out objects (the page then shows a dash), and some
network cards number the load or voltage tables differently; if a value is missing, the **Diagnostic Log** has what was asked and answered.
## DNS providers
### Cloudflare