NUT (USV-Monitoring)¶

Ueberwacht die CyberPower OR650ERM1U USV und triggert eine geordnete Abschaltkette fuer alle Rack-Geraete, wenn die Batterie zur Neige geht. NUT Project

Zugriff¶


Port	3493 (nur intern auf Host)
Netzwerk	Host-Netzwerk (via Port-Mapping)
Traefik	Nein (interner Dienst)

Container¶

Container	Image	Funktion
`nut-upsd`	`instantlinux/nut-upsd:latest`	`upsd`-Daemon, spricht via `usbhid-ups` mit der USV

Der upsmon- und upssched-Client laeuft als System-Service auf dem NUC-Host (nicht im Container), damit Shutdowns das Host-System direkt erreichen.

Architektur¶

  CyberPower OR650ERM1U (USB)
           │
           │ usbhid-ups (VendorID 0764)
           │
  ┌────────▼─────────┐
  │ nut-upsd (Docker)│  :3493
  └────────┬─────────┘
           │ MONITOR serverups@localhost
  ┌────────▼─────────┐
  │ upsmon  (Host)   │──── NOTIFYCMD ───► upssched (Host)
  └──────────────────┘                        │
                                              │ AT ONBATT / LOWBATT
                                              │
                                        shutdown-chain.sh
                                              │
                ┌─────────────────────────────┼─────────────────────────┐
                ▼                             ▼                         ▼
          UNAS Pro (NAS)              UDM Pro (Router)           NUC (localhost)
          ssh unas-pro                ssh udm-pro                shutdown -h now

Konfigurationsbesonderheiten¶

Primary-Modus: Der NUC steuert die USV (MONITOR serverups@localhost:3493 1 upsmon <pw> primary)
Low-Battery-Schwelle: override.battery.runtime.low = 300 in ups.conf — LOWBATT feuert bei < 5 Minuten Restlaufzeit
Shutdown-Trigger: Primaer LOWBATT (Runtime < 5 min). Safety-Net: onbatt-shutdown-Timer nach 15 min ONBATT
Geordnete Abschaltkette (scripts/shutdown-chain.sh): UNAS Pro → UDM Pro → NUC in dieser Reihenfolge. NUC zuletzt, da lokal
SSH-Schluessel: /root/.ssh/config auf dem NUC enthaelt Hosts unas-pro und udm-pro mit Key-basiertem Login. Siehe SSH_SETUP.md im Repo
ntfy-Benachrichtigungen: Alle USV-Events (ONBATT, ONLINE, LOWBATT) gehen an homelab-critical Topic auf ntfy.homelab-external.robinwerner.net
USB-Durchreichung: Container benoetigt /dev/bus/usb und die VendorID 0764 (CyberPower)

Wichtige Pfade¶

Pfad	Zweck
`/etc/nut/upsmon.conf`	upsmon-Konfiguration (Host)
`/etc/nut/upssched.conf`	Timer-Definitionen (Host)
`/opt/containers/homeserver/nut/scripts/`	shutdown-chain.sh, upssched-cmd.sh
`/var/log/nut/shutdown-chain.log`	Shutdown-Protokoll
`/etc/killpower`	Power-Down-Flag (von upsmon gesetzt)

Timer-Logik (`upssched.conf`)¶

Event	Aktion
`ONBATT`	Sofortige ntfy-Benachrichtigung + Start Timer `onbatt-shutdown` (900s = 15 min)
`ONLINE`	Timer canceln + ntfy "Power returned"
`LOWBATT`	Sofortiger Shutdown ueber `lowbatt-shutdown` (Primaer-Trigger)

Setup (Kurz)¶

Das Host-Setup (upsmon/upssched auf dem NUC) wird vom Script scripts/setup-host.sh im Repo provisioniert. Details dort und in CLAUDE.md.

cd /opt/containers/homeserver/nut

# Container starten (spricht mit der USV via USB)
docker compose up -d

# Host-Seite einrichten (upsmon, upssched, systemd-Unit)
sudo ./scripts/setup-host.sh

Troubleshooting¶

upsc serverups@localhost zeigt den aktuellen USV-Status (Runtime, Battery, Load)
journalctl -u nut-monitor -f zeigt upsmon-Events live
Test-Shutdown: upsmon -c fsd triggert einen Forced Shutdown (Vorsicht: fuehrt den Chain aus!)
Logs: /var/log/nut/shutdown-chain.log protokolliert jede Kette mit Zeitstempeln