Shelly Monitoring mit Uptime Kuma und Python-Skript

Dieser Artikel zeigt, wie man Shelly-Geräte mit einem Python-Skript automatisch in Uptime Kuma als HTTP-Monitore anlegen. Alle Shellys aus einer IP-Liste werden in Uptime Kuma registriert, optional in einer eigenen Monitor-Gruppe gebündelt und regelmäßig über die Shelly-Status-API überwacht. Ideal, um Shelly-Ausfälle frühzeitig zu erkennen und zentral zu überwachen.

Einleitung

Mit Uptime Kuma lassen sich HTTP-Checks, Pings und andere Überwachungen sehr komfortabel über eine Weboberfläche verwalten. Wer viele Shelly-Geräte im Netzwerk betreibt, möchte diese aber nicht alle von Hand anlegen.

Dieses Python-Skript liest eine Liste von Shelly-IP-Adressen ein und legt für jedes Gerät automatisch einen HTTP-Monitor in Uptime Kuma an. Dabei wird die Shelly-Status-API unter der URL

http://<IP>/rpc/Shelly.GetStatus

abgefragt. Optional können alle Shellys in eine gemeinsame Monitor-Gruppe einsortiert werden, damit die Übersicht in Uptime Kuma erhalten bleibt.

Funktionsumfang des Skripts

Liest eine Datei mit Shelly-IP-Adressen (oder Hostnamen), eine Adresse pro Zeile.
Ignoriert leere Zeilen und Kommentarzeilen, die mit # beginnen.
Erstellt bei Bedarf automatisch eine Monitor-Gruppe in Uptime Kuma (z. B. „Shelly Devices“).
Legt für jede IP einen HTTP-Monitor an:
- Name: Shelly <IP>
- URL: http://<IP>/rpc/Shelly.GetStatus
Prüft vorher, ob bereits ein Monitor mit exakt dieser URL existiert und überspringt doppelte Einträge.
Unterstützt konfigurierbare Werte für:
- Prüfintervall (interval)
- Retry-Intervall (retry-interval)
- maximale Anzahl von Retries (maxretries)
Verwendet die offizielle Python-Bibliothek uptime-kuma-api zur Kommunikation mit Uptime Kuma.

Voraussetzungen

Installierte Python-Version (empfohlen: Python 3.8 oder höher)
Laufende Uptime-Kuma-Instanz (z. B. http://127.0.0.1:3001)
Zugangsdaten (Benutzername und Passwort) für Uptime Kuma
Liste der Shelly-Geräte (IP-Adressen oder Hostnamen)
Internetzugang oder Zugriff auf das GitHub-Repository zum Download des Skripts

Download des Skripts aus GitHub

Das Python-Skript steht als Rohdatei (Raw-Download) im folgenden GitHub-Repository zur Verfügung:

https://raw.githubusercontent.com/alaub81/shelly/refs/heads/main/create_shelly_monitors.py

Typischer Download unter Linux/Unix mit wget:

wget -O create_shelly_monitors.py \
  https://raw.githubusercontent.com/alaub81/shelly/refs/heads/main/create_shelly_monitors.py

chmod +x create_shelly_monitors.py

Alternativ mit curl:

curl -L \
  https://raw.githubusercontent.com/alaub81/shelly/refs/heads/main/create_shelly_monitors.py \
  -o create_shelly_monitors.py
  
chmod +x create_shelly_monitors.py

Installation der benötigten Python-Bibliothek

Das Skript nutzt die offizielle Python-Bibliothek uptime-kuma-api, die per pip installiert werden kann:

pip install uptime-kuma-api

Je nach Systemkonfiguration kann auch pip3 erforderlich sein:

pip3 install uptime-kuma-api

Bei System-Python unter Debian/Ubuntu kann ggf. ein vorheriges

apt install python3-pip

notwendig sein.

Aufbau der Shelly-Liste (IP-Datei)

Standardmäßig erwartet das Skript eine Datei namens shellies.txt im aktuellen Verzeichnis. Über den Parameter --file kann ein anderer Pfad angegeben werden.

Beispielinhalt der Datei:

# Shelly Geräte im Heimnetz 

192.168.1.10
192.168.1.11 

# 192.168.1.12 (aktuell außer Betrieb)
# oder Hostnamen wenn sie auflösbar sind
shelly-livingroom.local
shelly-bedroom.local

Eine IP-Adresse bzw. ein Hostname pro Zeile
Leerzeilen sind erlaubt und werden ignoriert
Zeilen, die mit # beginnen, gelten als Kommentar

Liste aus Netzwerkscan erstellen

Wenn ihr wie ich alle Shellys in einem Netz habt und alle im Hostnamen "shelly" haben, könnt ihr diesen nmap Befehl verwenden:

nmap -sP 192.168.10.0/24 | grep "shelly" | awk '/Nmap scan report/ {print $5}' > shellies.txt

Aufruf des Skripts

Typischer Aufruf (z. B. auf einem Raspberry Pi oder Linux-Server):

python3 create_shelly_monitors.py \
  --kuma-url http://127.0.0.1:3001 \
  --username admin \
  --password 'Your$Secure!Password' \
  --file /pfad/zu/shellies.txt \
  --interval 600 \
  --retry-interval 60 \
  --maxretries 0 \
  --group-name "Shelly Devices"

Parameterbeschreibung

--kuma-url: Basis-URL der Uptime-Kuma-Instanz (z. B. http://127.0.0.1:3001).

--username: Uptime-Kuma-Benutzername, mit dem sich das Skript einloggt.

--password: Passwort für den angegebenen Uptime-Kuma-Benutzer.; Achtung bei Sonderzeichen wie $ und ! in der Shell – ggf. in einfache Anführungszeichen setzen (z. B. 'Your$Secure!Password').

--file: Pfad zur Datei mit den Shelly-IP-Adressen (Standard: shellies.txt).

--interval: Prüfintervall in Sekunden (Standard: 60).; Wert sollte in Uptime Kuma mindestens 20 Sekunden betragen.

--retry-interval: Retry-Intervall in Sekunden (Standard: 60).

--maxretries: Anzahl der Wiederholungsversuche, bevor der Monitor als DOWN markiert wird (Standard: 0).

--group-name: Name der Monitor-Gruppe in Uptime Kuma, in die alle Shelly-Monitore einsortiert werden.; Existiert die Gruppe noch nicht, legt das Skript automatisch einen Gruppen-Monitor mit diesem Namen an.; Wird der Parameter leer gelassen, werden die Monitore keiner Gruppe zugeordnet.

Sicherheitshinweise

Passwörter nach Möglichkeit nicht dauerhaft in Shell-History oder Skripten im Klartext speichern.
Wo möglich, sollten Umgebungsvariablen oder eine interaktive Passwortabfrage im Skript genutzt werden.
Der Zugriff auf Uptime Kuma sollte über sichere Netzwerke oder VPN erfolgen, insbesondere bei extern erreichbaren Instanzen.
Shelly-Geräte sollten sich in einem geschützten internen Netz befinden; externe Erreichbarkeit ist nur mit entsprechender Absicherung zu empfehlen.

Fehlersuche

Fehler: authIncorrectCreds

Prüfen, ob Benutzername und Passwort für Uptime Kuma korrekt sind (Login in der Weboberfläche testen).

Monitor wird nicht angelegt

Mögliche Ursache: Es existiert bereits ein Monitor mit exakt derselben URL. Das Skript prüft vor dem Anlegen, ob ein Monitor mit dieser URL vorhanden ist, und überspringt ihn dann.

Python-Importfehler (ModuleNotFoundError: No module named 'uptime_kuma_api')

Prüfen, ob uptime-kuma-api in der verwendeten Python-Umgebung installiert ist.

Fazit

Das hier beschriebene Python-Skript erleichtert die automatische Einbindung von vielen Shelly-Geräten in Uptime Kuma erheblich. Statt jeden Monitor manuell über die Oberfläche anzulegen, genügt eine gepflegte Liste von IP-Adressen und ein einziger Skriptaufruf.

Durch die optionale Gruppierung in Uptime Kuma behalten Administratoren jederzeit den Überblick über den Status sämtlicher Shelly-Geräte und können Ausfälle schnell erkennen und analysieren.