Zurück zum Blog

Proxmox Benachrichtigungen aufs Handy: Backups, Fencing, Replikation und Festplattenfehler

Proxmox Benachrichtigungen aufs Handy: Backups, Fencing, Replikation und Festplattenfehler

Die meisten Proxmox-Hosts schicken ihre Benachrichtigungen an root@pam, also an eine E-Mail-Adresse, die vor Jahren im Installer eingetippt wurde, zugestellt von einem Postfix, dem nie ein Relay eingerichtet wurde. Das nächtliche Backup schlägt fehl, die Mail landet in einer lokalen Warteschlange, und du erfährst es drei Wochen später, wenn du eine VM wiederherstellen musst.

Das andere übliche Setup funktioniert, wird aber ignoriert. Jeder Backup-Job schickt jede Nacht eine lange E-Mail, alle sagen „erfolgreich“, und die eine, die „fehlgeschlagen“ sagt, sieht genauso aus wie die anderen dreißig im Ordner.

Seit Proxmox VE 8.3 und Proxmox Backup Server 3.3 hat das Benachrichtigungssystem ein generisches Webhook-Ziel. Es kann jede HTTP-API mit einem Body aufrufen, den du selbst schreibst, und so eine Push-Benachrichtigung direkt aufs Handy schicken, mit unterschiedlicher Priorität für Fehler und Erfolge. Kein Skript auf dem Host und kein Relay, das du warten musst.

Was du brauchst

  • Proxmox VE 8.3 oder neuer (jede 9.x-Version funktioniert) oder Proxmox Backup Server 3.3 oder neuer. Ältere Versionen werden weiter unten behandelt.
  • Die Pocket-Alert-App auf iPhone oder Android und ein API-Schlüssel aus API-Schlüssel.
  • Zugriff auf Datacenter → Notifications als root@pam oder einen Benutzer mit Mapping.Modify auf /mapping/notifications.

Was Proxmox dir melden kann

Proxmox VE sendet diese Ereignisse, jeweils mit einem type, einem Schweregrad und ein paar Metadatenfeldern:

EreignistypeSchweregrad
Backup erfolgreichvzdumpinfo
Backup fehlgeschlagenvzdumperror
Storage-Replikationsjob fehlgeschlagenreplicationerror
Cluster-Node gefencedfencingerror
System-Updates verfügbarpackage-updatesinfo
Mail für root (smartd, ZFS ZED und andere)system-mailunknown

Die letzte Zeile ist wichtiger, als sie aussieht. smartd prüft deine Festplatten alle 30 Minuten und mailt an root, sobald eine zu versagen beginnt, und der ZFS-Event-Daemon mailt an root bei degradierten Pools und Scrub-Fehlern (ZED_EMAIL_ADDR="root" ist der Standard). Proxmox macht aus diesen Mails system-mail-Ereignisse, also meldet derselbe Webhook, der Backups meldet, auch eine sterbende Festplatte.

Das Webhook-Ziel einrichten

In der Web-UI gehst du zu Datacenter → Notifications und klickst unter Notification Targets auf Add → Webhook. Fülle es so aus:

  • Endpoint Name: pocketalert
  • Method/URL: POST und https://api.pocketalert.app/v1/messages
  • Headers: Content-Type = application/json, und Token = {{ secrets.token }}
  • Secrets: token = dein Pocket-Alert-API-Schlüssel

Und den Body:

{
  "title": {{ json title }},
  "message": {{ json message }},
  "level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}

Hier passieren ein paar Dinge:

  • {{ json title }} gibt den Wert als vollständigen JSON-String aus, inklusive Anführungszeichen. Backup-Berichte sind mehrzeilige Tabellen, und wenn du {{ message }} zwischen Anführungszeichen setzt, bricht das JSON beim ersten Zeilenumbruch. Proxmox hat außerdem {{ escape message }}, was dasselbe ohne umgebende Anführungszeichen macht.
  • Der Schlüssel ist ein Secret. Secrets werden in /etc/pve/priv/notifications.cfg gespeichert, nur für root lesbar, und die API gibt ihre Werte nie zurück. Proxmox maskiert sie außerdem in Fehlermeldungen.
  • Die Stufe folgt dem Schweregrad. Proxmox rendert den Body mit Handlebars, das if, eq und or kennt. Fehlgeschlagene Backups, fehlgeschlagene Replikation, Fencing und Festplattenmails kommen als high, was auf dem iPhone durch den Fokus-Modus durchdringt. Erfolgreiche Backups und Update-Hinweise kommen als low: Sie sind im Verlauf, wenn du sie willst, aber sie vibrieren nicht.

Speichere das Ziel und klicke auf Test. Eine Testbenachrichtigung sollte innerhalb weniger Sekunden ankommen.

Das Ziel tut nichts, solange kein Matcher Ereignisse dorthin leitet. Klicke unter Notification Matchers auf Add, nenne ihn pocketalert-all und setze im Tab Targets to notify ein Häkchen bei pocketalert. Ein Matcher ohne Regeln trifft jedes Ereignis.

Dasselbe von der Shell

Wenn du die CLI bevorzugst oder mehrere Cluster verwaltest, macht pvesh dasselbe. Header-Werte, Body und Secrets werden base64-kodiert übergeben:

PA_KEY='your-api-key'
BODY='{
  "title": {{ json title }},
  "message": {{ json message }},
  "level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}'
b64() { printf '%s' "$1" | base64 -w0; }

pvesh create /cluster/notifications/endpoints/webhook \
  --name pocketalert --method post \
  --url https://api.pocketalert.app/v1/messages \
  --header "name=Content-Type,value=$(b64 application/json)" \
  --header "name=Token,value=$(b64 '{{ secrets.token }}')" \
  --secret "name=token,value=$(b64 "$PA_KEY")" \
  --body "$(b64 "$BODY")"

pvesh create /cluster/notifications/matchers --name pocketalert-all --target pocketalert
pvesh create /cluster/notifications/targets/pocketalert/test

Das Ergebnis landet in /etc/pve/notifications.cfg, die über den Cluster hinweg geteilt wird, sodass ein Setup jeden Node abdeckt (der base64-Body ist hier gekürzt):

webhook: pocketalert
	method post
	url https://api.pocketalert.app/v1/messages
	header name=Content-Type,value=YXBwbGljYXRpb24vanNvbg==
	header name=Token,value=e3sgc2VjcmV0cy50b2tlbiB9fQ==
	body ewogICJ0aXRsZSI6IHt7IGpzb24gdGl0bGUgfX0s...

matcher: pocketalert-all
	target pocketalert

Der Schlüssel selbst liegt in /etc/pve/priv/notifications.cfg als secret name=token,value=<base64>.

Zweite Stufe: ein gefencter Node soll dich wecken

Ein fehlgeschlagenes Backup kann bis zum Morgen warten. Ein gefencter Node heißt, dass HA gerade einen Host beendet hat, und das ist eine critical-Push wert, die durch Nicht stören kommt. Matcher können das erledigen, ohne das Body-Template anzufassen.

Lege ein zweites Webhook-Ziel pocketalert-critical an, identisch mit dem ersten, nur mit einer Zeile im Body anders:

  "level": "critical"

Ersetze dann den Sammel-Matcher durch zwei, die nach Ereignistyp trennen:

matcher: pocketalert-all
	match-field exact:type=fencing
	invert-match true
	target pocketalert

matcher: pocketalert-fencing
	match-field exact:type=fencing
	target pocketalert-critical

invert-match dreht den ersten Matcher um, sodass Fencing nur an das kritische Ziel geht und du nicht zwei Pushes für ein Ereignis bekommst. critical-Zustellung durch Nicht stören ist eine Funktion des bezahlten Tarifs; im kostenlosen Tarif kommt sie als high an. Was jede Stufe auf iOS und Android bewirkt, steht unter Prioritätsstufen.

Weitere Dinge, für die Matcher gut sind:

  • Nur Fehler. Füge match-severity error,unknown zu pocketalert-all hinzu, und erfolgreiche Backups senden nichts mehr. Wir würden sie als low behalten: Ein leises „Backup erfolgreich“ jede Nacht ist die einfachste Art zu merken, wenn es aufhört anzukommen.
  • Ein Job. match-field exact:job-id=backup-abc123 beschränkt einen Matcher auf einen geplanten Job. Backups, die mit Run now gestartet werden, haben keine job-id und treffen daher nicht.
  • Ruhezeiten. match-calendar mon..fri 9-17 beschränkt einen Matcher auf Arbeitszeiten, und invert-match liefert dir den Rest.

Ein Button, der die Web-UI öffnet

Pocket-Alert-Pushes können bis zu drei Aktionsbuttons tragen. Füge einen zum Body hinzu, und ein fehlgeschlagenes Backup öffnet die Proxmox-UI mit einem Tipp:

  "actions": [
    {"type": "view", "label": "Open Proxmox", "value": "https://pve1.lan:8006"}
  ]

Das Handy öffnet die URL selbst, sodass eine lokale Adresse funktioniert, sobald du im Heimnetz oder im VPN bist.

Proxmox Backup Server

PBS 3.3 und neuer haben dasselbe Benachrichtigungssystem unter Configuration → Notifications, mit demselben Webhook-Ziel, demselben Body und denselben Handlebars-Helfern. Die Konfiguration liegt in notifications.cfg und notifications-priv.cfg unter /etc/proxmox-backup/.

Die Ereignisse unterscheiden sich und sind für einen Backup-Server nützlicher: Garbage Collection (gc), prune, sync, verification, tape-backup und tape-load, dazu Fehlschläge bei der acme-Zertifikatserneuerung und package-updates. acme meldet nur Fehler, und tape-load ist eine notice; der Rest kommt in info- und error-Varianten, sodass dasselbe if im Body unverändert funktioniert. Die Datastore-Ereignisse (gc, prune, sync, verification, tape-backup) tragen außerdem ein Feld datastore, sodass match-field regex:datastore=^offsite-.*$ Offsite-Datastores an ein anderes Ziel schicken kann.

Zwei PBS-Details solltest du prüfen. Datastores, die vor dem Benachrichtigungssystem angelegt wurden, haben einen notification-mode, der noch legacy-sendmail sein kann; stelle ihn in den Datastore-Optionen auf das Benachrichtigungssystem um. Und PBS sendet package-updates-Benachrichtigungen nur auf Hosts mit aktivem Abonnement.

Ehrliche Grenzen

  • Der Host muss online sein, um zu melden. Der Webhook wird vom Proxmox-Host selbst gesendet. Wenn er die Verbindung verloren hat oder ausgeschaltet ist, geht nichts raus. Für „der ganze Kasten ist down“ brauchst du eine Prüfung von außen, etwa ein Uptime-Monitoring auf einem anderen Rechner.
  • Lange Backup-Berichte werden im Push gekürzt. Ein Backup mit zwanzig Gästen erzeugt eine lange Tabelle. Der Push zeigt ungefähr die ersten 3 KB; der vollständige Text steht im Nachrichtenverlauf in der App.
  • system-mail ist alles, was an root geht. Dazu gehören smartd und ZFS, aber auch Cron-Ausgaben und alles andere, was auf deinem System an root mailt. Wenn es zu laut wird, gib diesen Ereignissen mit match-field exact:type=system-mail einen eigenen Matcher und ein ruhigeres Ziel.
  • Keine Gotify-Kompatibilität. Proxmox hat außerdem ein eingebautes Gotify-Ziel, und ältere Anleitungen nutzen es für Handy-Pushes. Pocket Alert implementiert die Gotify-API nicht, daher kann dieses Ziel nicht auf uns zeigen. Nutze das oben beschriebene Webhook-Ziel oder lies wie sich Pocket Alert von Gotify unterscheidet.

Auf Proxmox VE 8.2 und älter

Ein Upgrade ist die beste Lösung, da das Webhook-Ziel 8.3 voraussetzt. Wenn du noch nicht upgraden kannst, deckt ein vzdump-Hook-Skript den wichtigsten Fall ab, die Backups. Installiere die Pocket-Alert-CLI auf dem Node als root, führe pocketalert auth aus und speichere dies als /usr/local/bin/vzdump-pocketalert:

#!/bin/sh
case "$1" in
  backup-abort) pocketalert send -t "Backup failed: $3 on $(hostname)" -m "Mode: $2" -l high ;;
  job-end)      pocketalert send -t "Backup job finished on $(hostname)" -m "Check the task log for details" -l low ;;
esac
exit 0

Mache es ausführbar und füge script: /usr/local/bin/vzdump-pocketalert zu /etc/vzdump.conf hinzu. vzdump ruft es in jeder Phase auf; bei backup-abort sind das zweite und dritte Argument der Backup-Modus und die VM-ID.

Wenn nichts ankommt

  • Erst Test ausführen. Kommt der Test-Push an, die echten Ereignisse aber nicht, ist das Ziel in Ordnung und das Problem liegt beim Routing: Prüfe, ob ein Matcher das Ziel nennt und ob seine Regeln passen.
  • Den Benachrichtigungsmodus des Backup-Jobs prüfen. Ein Job mit einer E-Mail-Adresse in den Benachrichtigungseinstellungen und dem Standardmodus auto nutzt das alte Sendmail und umgeht das Benachrichtigungssystem komplett. Entferne die Adresse oder stelle den Modus auf das Benachrichtigungssystem; in /etc/pve/jobs.cfg steht dafür notification-mode notification-system.
  • Das Journal lesen. journalctl --since "1 hour ago" | grep -i notif zeigt fehlgeschlagene Anfragen. Ein 401 heißt, der Schlüssel ist falsch; ein 400 bedeutet meist, dass der Body kein gültiges JSON ist: Prüfe, ob du {{ json message }} verwendet hast und nicht ein nacktes {{ message }}.
  • Den Verlauf in der App prüfen. low-Pushes machen keinen Ton, daher kann ein erfolgreiches Backup so aussehen, als wäre es nie angekommen. Es steht im Nachrichtenverlauf.

FAQ

Brauche ich ein Proxmox-Abonnement?

Nein. Das Benachrichtigungssystem und das Webhook-Ziel gehören zu den kostenlosen Repositories. Das einzige abonnementabhängige Teil ist die package-updates-Benachrichtigung von PBS.

Funktioniert das für einen einzelnen Node ohne Cluster?

Ja. Ein einzelner Node liest dieselbe /etc/pve/notifications.cfg. In einem Cluster wird die Datei geteilt, du richtest es also einmal ein.

Kann ich das auch als E-Mail bekommen?

Ja. Behalte das Standardziel mail-to-root in seinem Matcher und füge pocketalert daneben hinzu. Ein Matcher kann mehrere Ziele benachrichtigen, und jedes Ziel bekommt höchstens eine Benachrichtigung.

Wie viele Pushes verbraucht das?

Eine pro Ereignis. Ein nächtlicher Backup-Job ist eine Benachrichtigung für den ganzen Job, nicht eine pro Gast, sodass ein typisches Homelab ein paar am Tag verschickt. Der kostenlose Tarif deckt 50 Nachrichten am Tag auf einem Gerät ab.

Was ist mit TrueNAS, USV-Ereignissen oder Uptime Kuma?

Gleiche Idee, anderer Absender. Die Seite Homelab-Benachrichtigungen behandelt die üblichen Bestandteile eines Heimservers, und Backup-Benachrichtigungen deckt Backup-Tools außerhalb von Proxmox ab.

Erstelle ein kostenloses Konto, füge den Body in ein Webhook-Ziel ein und lass den nächsten fehlgeschlagenen Backup-Lauf dich finden, statt dein Postfach.

Artikel teilen