From 5cd3f47d658dba36e0eddefe32d8ea1a6169cc5a Mon Sep 17 00:00:00 2001
From: Alex Tau <alex@lego>
Date: Sun, 18 Jan 2026 15:33:56 +0300
Subject: [PATCH] add docs for ups

---
 README.md             |  4 ++
 docs/nixos-options.md | 45 ++++++++++++++++++++++-
 docs/ups.md           | 85 +++++++++++++++++++++++++++++++++++++++++++
 modules/options.nix   |  1 +
 4 files changed, 134 insertions(+), 1 deletion(-)
 create mode 100644 docs/ups.md

diff --git a/README.md b/README.md
index 4d642a8..fa48578 100644
--- a/README.md
+++ b/README.md
@@ -65,3 +65,7 @@ Then enable and start the service:
 ln -s /opt/lego-monitoring/lego-monitoring.service /etc/systemd/system/lego-monitoring.service
 systemctl enable --now lego-monitoring
 ```
+
+### UPS monitoring
+
+See [docs/ups.md](docs/ups.md) for instructions.
diff --git a/docs/nixos-options.md b/docs/nixos-options.md
index bf01a66..a18d24a 100644
--- a/docs/nixos-options.md
+++ b/docs/nixos-options.md
@@ -36,12 +36,13 @@ List of enabled check sets\. Each check set is a module which checks something a
  - ram – alerts when RAM usage is above threshold
  - temp – alerts when temperature readings are above thresholds
  - net – alerts when network usage is above threshold
+ - ups – alerts on UPS events
  - vulnix – periodically scans system for known CVEs, alerts if any are found (NixOS only)
 
 
 
 *Type:*
-list of (one of “self”, “remind”, “cpu”, “ram”, “temp”, “net”, “vulnix”)
+list of (one of “self”, “remind”, “cpu”, “ram”, “temp”, “net”, “ups”, “vulnix”)
 
 
 
@@ -635,6 +636,48 @@ null or (positive integer or floating point number, meaning >0)
 
 
 
+## services\.lego-monitoring\.checks\.ups\.upsToCheck
+
+
+
+List of UPS’s to monitor, in ` upsc `-compatible format\. If null, all UPS’s connected to localhost are checked\.
+
+
+
+*Type:*
+null or (list of string)
+
+
+
+*Default:*
+` null `
+
+*Declared by:*
+ - [modules/options\.nix](../modules/options.nix)
+
+
+
+## services\.lego-monitoring\.checks\.ups\.upsmonGroup
+
+
+
+Group to allow to send UPS status updates\. This should usually include the user upsmon runs as\.
+
+
+
+*Type:*
+string
+
+
+
+*Default:*
+` config.power.ups.upsmon.user `
+
+*Declared by:*
+ - [modules/options\.nix](../modules/options.nix)
+
+
+
 ## services\.lego-monitoring\.checks\.vulnix\.whitelist
 
 
diff --git a/docs/ups.md b/docs/ups.md
new file mode 100644
index 0000000..003401a
--- /dev/null
+++ b/docs/ups.md
@@ -0,0 +1,85 @@
+# UPS monitoring
+
+Both steps require configuring upsmon at least to the point of outputting UPS updates to upsmon's logs.
+
+## NixOS
+
+NOTIFYCMD is set automatically. Make sure to set NOTIFYFLAGs to include EXEC for events that are to be reported.
+The following snippet enables all events to be reported to wall, system's log and lego-monitoring:
+
+```nix
+{
+  power.ups.upsmon.settings.NOTIFYFLAG = (map (ntype: [ntype "SYSLOG+WALL+EXEC"]) [
+    "ONLINE"
+    "ONBATT"
+    "LOWBATT"
+    "FSD"
+    "COMMOK"
+    "COMMBAD"
+    "SHUTDOWN"
+    "SHUTDOWN_HOSTSYNC"
+    "REPLBATT"
+    "NOCOMM"
+    "NOPARENT"
+    "CAL"
+    "NOTCAL"
+    "OFF"
+    "NOTOFF"
+    "BYPASS"
+    "NOTBYPASS"
+    "ECO"
+    "NOTECO"
+    "ALARM"
+    "NOTALARM"
+    "OVER"
+    "NOTOVER"
+    "TRIM"
+    "NOTTRIM"
+    "BOOST"
+    "NOTBOOST"
+    "OTHER"
+    "NOTOTHER"
+    "SUSPEND_STARTING"
+    "SUSPEND_FINISHED"
+  ]);
+}
+```
+
+## Non-NixOS
+
+* NOTIFYCMD should be set to `/opt/lego-monitoring/.venv/bin/write-ups-status`.
+* As above, NOTIFYFLAGs should include EXEC. Example for all events:
+
+```
+NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC
+NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
+NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
+NOTIFYFLAG FSD SYSLOG+WALL+EXEC
+NOTIFYFLAG COMMOK SYSLOG+WALL+EXEC
+NOTIFYFLAG COMMBAD SYSLOG+WALL+EXEC
+NOTIFYFLAG SHUTDOWN SYSLOG+WALL+EXEC
+NOTIFYFLAG SHUTDOWN_HOSTSYNC SYSLOG+WALL+EXEC
+NOTIFYFLAG REPLBATT SYSLOG+WALL+EXEC
+NOTIFYFLAG NOCOMM SYSLOG+WALL+EXEC
+NOTIFYFLAG NOPARENT SYSLOG+WALL+EXEC
+NOTIFYFLAG CAL SYSLOG+WALL+EXEC
+NOTIFYFLAG NOTCAL SYSLOG+WALL+EXEC
+NOTIFYFLAG OFF SYSLOG+WALL+EXEC
+NOTIFYFLAG NOTOFF SYSLOG+WALL+EXEC
+NOTIFYFLAG BYPASS SYSLOG+WALL+EXEC
+NOTIFYFLAG NOTBYPASS SYSLOG+WALL+EXEC
+NOTIFYFLAG ECO SYSLOG+WALL+EXEC
+NOTIFYFLAG NOTECO SYSLOG+WALL+EXEC
+NOTIFYFLAG ALARM SYSLOG+WALL+EXEC
+NOTIFYFLAG NOTALARM SYSLOG+WALL+EXEC
+NOTIFYFLAG OVER SYSLOG+WALL+EXEC
+NOTIFYFLAG NOTOVER SYSLOG+WALL+EXEC
+NOTIFYFLAG TRIM SYSLOG+WALL+EXEC
+NOTIFYFLAG NOTTRIM SYSLOG+WALL+EXEC
+NOTIFYFLAG BOOST SYSLOG+WALL+EXEC
+NOTIFYFLAG NOTBOOST SYSLOG+WALL+EXEC
+NOTIFYFLAG OTHER SYSLOG+WALL+EXEC
+NOTIFYFLAG NOTOTHER SYSLOG+WALL+EXEC
+NOTIFYFLAG SUSPEND_STARTING SYSLOG+WALL+EXEC
+NOTIFYFLAG SUSPEND_FINISHED SYSLOG+WALL+EXEC
+```
diff --git a/modules/options.nix b/modules/options.nix
index 82538c7..ad78efe 100644
--- a/modules/options.nix
+++ b/modules/options.nix
@@ -183,6 +183,7 @@ in
         upsmonGroup = lib.mkOption {
           type = lib.types.str;
           default = config.power.ups.upsmon.user;
+          defaultText = lib.literalExpression "config.power.ups.upsmon.user";
           description = "Group to allow to send UPS status updates. This should usually include the user upsmon runs as.";
         };
       };