Network UPS Tools (NUT) Smart-Home-Integration, kostenlos und Open Source
Überwache Status, Last und Restlaufzeit der USV-Geräte deiner NUT-Server.
Veröffentlicht von prohand
- Geräte
- Version 2.3.1
- Erfordert Gladys >=5.1.0
- ★ 0
Mit der Integration Network UPS Tools (NUT) ruft Gladys Werte und Zustände von USV-Geräten ab, die ein im lokalen Netzwerk erreichbarer NUT-Server upsd bereitstellt.
Diese Integration dient der Überwachung. Sie sendet keine Befehle zum Herunterfahren, Neustarten oder Konfigurieren an die USV-Geräte.
Voraussetzungen
Deine USV muss bereits in NUT funktionieren. Von dem Rechner aus, auf dem Gladys läuft, sollte der NUT-Server auf den folgenden Befehl antworten, nachdem du die Platzhalter durch deine eigenen Werte ersetzt hast:
upsc <ups-name>@<server-address>
Standardmäßig lauscht upsd auf dem TCP-Port 3493. Stelle sicher, dass sowohl die Netzwerkregeln als auch die NUT-ACLs den Zugriff von Gladys erlauben.
Zugangsdaten werden im Klartext übertragen
Die Integration verwendet kein TLS (STARTTLS): Der NUT-Benutzername und das Passwort sowie alle Messwerte gehen im Klartext über das Netzwerk. Betreibe sie daher in einem vertrauenswürdigen Netzwerk:
- lass
upsdnur auf der Schnittstelle lauschen, über die Gladys ihn erreicht (LISTENinupsd.conf), und filtere den Port 3493, sodass sich nur der Gladys-Host verbinden kann; - lege in
upsd.userseinen eigenen Benutzer für Gladys an, ohneactionsund ohneinstcmds: Die Integration liest nur und braucht sie daher nie; - verwende dieses Passwort nirgendwo sonst.
Konfiguration
- Öffne Integrationen und dann Network UPS Tools (NUT).
- Trage im Tab Konfiguration den ersten
upsd-Server ein; sein Host ist erforderlich. - Füge bei Bedarf in den optionalen Feldern bis zu vier weitere Server hinzu.
- Behalte für jeden Server den Port
3493bei, sofern deine Installation keinen anderen Port verwendet. Gib NUT-Zugangsdaten ein, wenn eine Authentifizierung erforderlich ist. - Wähle ein Aktualisierungsintervall. Der Standardwert von 300 Sekunden passt für die meisten Installationen. Gladys fragt Geräte höchstens einmal pro Minute ab: Ein längeres Intervall wird beim nächstgelegenen Abfragezeitpunkt angewendet.
- Klicke auf Konfiguration speichern und verwende dann NUT-Verbindungen testen.
Das Aktualisierungsintervall wählen
Jeder veröffentlichte Wert wird im Gladys-Verlauf gespeichert, und eine USV stellt bis zu zwölf Werte bereit. Ein kurzes Intervall lässt die Datenbank daher schnell wachsen: Bei 60 Sekunden schreibt eine einzelne USV rund 17.000 Zeilen pro Tag, beim Standardintervall von 300 Sekunden rund 3.500.
Um dieses Volumen weiter zu verringern, veröffentlicht die Integration nur die Werte, die sich seit der vorherigen Messung geändert haben; ein stabil gebliebener Wert wird mindestens einmal pro Stunde erneut veröffentlicht, damit er nie als veraltet angezeigt wird. Geh nur dann auf 60 Sekunden herunter, wenn du eine feine Überwachung benötigst – etwa der Restlaufzeit während eines Stromausfalls –, und erhöhe das Intervall auf bis zu 86.400 Sekunden, wenn du die Datenbank lieber schonen möchtest.
Sobald die Verbindung steht, erkennt Gladys jede USV, die der NUT-Server meldet. Jede USV erscheint unter Entdeckte Geräte als eigenes Gladys-Gerät. Klicke im Tab Entdecken bei jeder USV, die du einbinden möchtest, auf Zu Gladys hinzufügen: Du kannst mehrere Geräte unabhängig voneinander hinzufügen. Die Liste wird bei jedem Scan (Scannen) aus dem NUT-Befehl LIST UPS neu aufgebaut.
Verfügbare Informationen
NUT-Treiber melden nicht alle dieselben Variablen, daher legt die Integration nur Sensoren für Informationen an, die die jeweilige USV tatsächlich liefert.
| Bereich | Mögliche Werte |
|---|---|
| Batterie | Ladung, Restlaufzeit, Spannung und Temperatur |
| Strom | Eingangs-/Ausgangsspannung und -strom |
| Last | Lastprozentsatz, Wirkleistung und Scheinleistung |
| USV | Temperatur, Status und Alarme |
Werte werden nur veröffentlicht, wenn sie numerisch sind und vom Treiber tatsächlich gemeldet werden. Die Textstatus von NUT werden bei der Kommunikation gelesen, aber nicht als Gladys-Funktionen veröffentlicht. So bleibt die Erkennungsnutzlast mit Core-Versionen kompatibel, die die Kategorie text noch nicht kennen.
Widget, Szenen und Aktionen (Gladys 5.1)
Die Integration erfordert Gladys 5.1 oder neuer.
Widget „USV“
Wähle unter Dashboard → Bearbeiten → Neues Widget im Abschnitt Integrations-Widgets das Widget USV und anschließend die anzuzeigende USV. Das Widget zeigt:
- die Batterieladung (Anzeige) und die Restlaufzeit;
- die USV-Last und die Eingangsspannung;
- ein 24-Stunden-Diagramm (Batterieladung und Last);
- den Status (Netzbetrieb, Batteriebetrieb, Batterie schwach …), die NUT-Alarme, die Leistung und den Server;
- eine Schaltfläche Aktualisieren, die die USV sofort liest. Sie sendet niemals einen Befehl an die USV.
Das Widget zeigt die letzte Messung der Integration (höchstens 3 Minuten alt). Antwortet die USV langsam, zeigt es „USV wird gelesen …“ und aktualisiert sich wenige Sekunden später.
Szenen-Auslöser
In einer Szene Auslöser hinzufügen → Integrationen:
| Auslöser | Wann |
|---|---|
| USV: Stromausfall, Batteriebetrieb | die USV wechselt in den Batteriebetrieb (OB) |
| USV: Netzstrom wiederhergestellt | die USV ist wieder am Netz (OL) |
| USV: Batterie schwach | NUT meldet eine schwache Batterie (LB) |
| USV: Batterie austauschen | NUT verlangt einen Austausch (RB) |
- Lass das Feld USV leer, um auf jede USV zu reagieren.
- Der Status wird unabhängig vom Aktualisierungsintervall jede Minute geprüft: Ein Stromausfall wird innerhalb einer Minute erkannt.
- In der Szene verfügbare Variablen:
ups_name,status,battery_charge(%),battery_runtime(min),load(%). - Beim Start der Integration dient die erste Messung als Referenz: Für eine USV, die bereits im Batteriebetrieb ist, wird kein Ereignis gesendet.
Szenen-Aktion „Status einer USV lesen“
In einer Szene Neue Aktion → Integrationen. Sie liest die gewählte USV und gibt an die folgenden Aktionen zurück: ups_name, status (online, on_battery, low_battery, forced_shutdown, off, bypass, unknown), on_battery, low_battery, replace_battery, battery_charge, battery_runtime (min), load, input_voltage. Ein Messwert, den die USV nicht meldet, wird weggelassen.
Beispiel: Jeden Morgen den USV-Status lesen und dann eine Nachricht mit der Restlaufzeit senden.
Fehlerbehebung
| Symptom | Empfohlene Prüfungen |
|---|---|
| Es wird keine USV gefunden | Prüfe jeden Host, jeden Port, die Firewall und ob in jeder ups.conf mindestens eine USV konfiguriert ist. |
| Zugriffs- oder Authentifizierungsfehler | Prüfe die ACLs in upsd.conf und die in upsd.users definierten Zugangsdaten. |
| Einige Werte fehlen | Führe upsc <ups>@<server> aus; Gladys kann nur Variablen anlegen, die dein NUT-Treiber bereitstellt. |
| Veraltete Daten | Ein stabiler Wert wird nur einmal pro Stunde neu geschrieben, das ist normal. Prüfe darüber hinaus, ob der NUT-Treiber noch mit der Hardware kommuniziert, und sieh dir die upsd-Protokolle an. |
| Die Gladys-Datenbank wächst zu schnell | Erhöhe das Aktualisierungsintervall: Die Menge des Verlaufs ist direkt proportional dazu. Jede hinzugefügte USV schreibt ihren eigenen Verlauf. |
| Das Hinzufügen einer USV scheitert mit „unvollständiges oder ungültiges Gerät“ | Aktualisiere die Integration. Diese Ablehnung (HTTP 422) kam von Funktionen, die ohne ihre Grenzen min und max veröffentlicht wurden; diese werden jetzt immer angegeben. |
| Die Werte ändern sich nach dem Hinzufügen des Geräts nie | Aktualisiere die Integration: Geräte werden jetzt mit aktivierter periodischer Abfrage veröffentlicht. |
| Einige Funktionen werden ohne Namen oder Symbol angezeigt | Aktualisiere die Integration und füge die USV dann erneut über den Tab Entdecken hinzu, damit ihre bestehenden Funktionen aktualisiert werden: Last und Scheinleistung wurden mit einem Kategorie/Typ-Paar veröffentlicht, das das Gladys-Frontend nicht darstellen kann. |
| Der Verbindungsstatus lautet „Verbunden, aber 1 von 2 NUT-Servern antworten nicht“ | Die USV der anderen Server werden weiterhin gelesen. Prüfe den genannten Server (Host, Port, Firewall, läuft upsd); der Status kehrt bei seiner nächsten Antwort zu einfachem „verbunden“ zurück. |
| Eine USV wird nicht mehr aktualisiert, nachdem ein Server aus der Konfiguration entfernt wurde | Ihr Server wird nicht mehr abgefragt, was die Protokolle einmal melden. Füge den Server wieder hinzu oder lösche das Gerät in Gladys. |
| Die USV-Last wird als „Unbekannt“ angezeigt | Aktualisiere die Integration und füge die USV dann erneut über den Tab Entdecken hinzu: Die Last (ups.load) wird jetzt in einer Kategorie veröffentlicht, mit der Gladys ihren Namen „Load“ anzeigen kann. |
Ausführliche Fehler findest du im Tab Protokolle der Integration in Gladys. Du kannst auch LOG_LEVEL=debug setzen, um detailliertere Protokolle zu erhalten.
Ressourcen
Die offizielle Spezifikation des NUT-Netzwerkprotokolls beschreibt die Erkennungs- und Lesebefehle, die diese Integration verwendet.
Konfigurationseinstellungen
Diese Einstellungen fragt Network UPS Tools (NUT) in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| NUT-Server | section | Nein | Konfiguriere einen oder mehrere erreichbare upsd-Server. Jede USV, die ein konfigurierter Server bereitstellt, wird als eigenes Gladys-Gerät erkannt. |
| Host von Server 1 | string | Ja | IP-Adresse oder DNS-Name des ersten NUT-upsd-Servers. |
| Port von Server 1 | number | Nein | Der Standard-TCP-Port von NUT ist 3493. |
| Benutzername von Server 1 (optional) | string | Nein | |
| Passwort von Server 1 (optional) | secret | Nein | Erforderlich, wenn ein Benutzername eingetragen ist. |
| Host von Server 2 (optional) | string | Nein | |
| Port von Server 2 | number | Nein | |
| Benutzername von Server 2 | string | Nein | |
| Passwort von Server 2 | secret | Nein | |
| Host von Server 3 (optional) | string | Nein | |
| Port von Server 3 | number | Nein | |
| Benutzername von Server 3 | string | Nein | |
| Passwort von Server 3 | secret | Nein | |
| Host von Server 4 (optional) | string | Nein | |
| Port von Server 4 | number | Nein | |
| Benutzername von Server 4 | string | Nein | |
| Passwort von Server 4 | secret | Nein | |
| Host von Server 5 (optional) | string | Nein | |
| Port von Server 5 | number | Nein | |
| Benutzername von Server 5 | string | Nein | |
| Passwort von Server 5 | secret | Nein | |
| Aktualisierungsintervall (s) | number | Nein | Wie oft die Messwerte in den Gladys-Verlauf geschrieben werden. Jeder Messwert ist eine Zeile in der Datenbank: Behalte 300 s bei, sofern du keine feineren Messungen benötigst. Der USV-Status wird für die Szenen weiterhin jede Minute geprüft. |
So installierst du Network UPS Tools (NUT) in Gladys
- Öffne in Gladys Integrationen: Network UPS Tools (NUT) erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/prohand/gladys-nut:2.3.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/prohand/gladys-nut.
Network UPS Tools (NUT) benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
Network UPS Tools (NUT) ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von prohand veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation