Proxmox VE über die API überwachen¶

Vesana überwacht einen Proxmox-VE-Node über dessen REST-API auf Port 8006. Auf dem Proxmox-Host läuft kein Agent und es wird keine Shell gebraucht — ein Token mit Lese-Rolle genügt.

Seit Profil-Version v11 liest ein editierbares Python-Script den Node (Check-Typ „Script (API)"). Das Script steht in deiner Scripts-Bibliothek unter „Proxmox VE — API": du kannst es öffnen, lesen und erweitern. Der Collector führt es aus, das Script spricht selbst mit der API.

Überwacht werden: Node-CPU/-RAM/-Root-Dateisystem/-Swap/-Last/-Uptime, Storage-Füllstände und nicht erreichbare Storages, Cluster-Quorum und Node-Ausfälle, VMs/Container, Backups (Alter des ältesten Backups, Fehlschläge und Warnungen in einem echten Zeitfenster, ungesicherte Gäste), Dienste, ZFS-Pools, SMART und offene Paket-Updates.

1. API-Token in Proxmox anlegen¶

Im Proxmox-Web-UI:

Datacenter → Permissions → API Tokens → Add.
Einen Benutzer wählen (z. B. monitoring@pve) und dem Token eine ID geben (z. B. vesana). Der vollständige Bezeichner hat damit die Form benutzer@realm!tokenid, also z. B. monitoring@pve!vesana.
Das einmalig angezeigte Secret kopieren.

Der Token braucht Lese-Rechte: Datacenter → Permissions → Add → API Token Permission, Pfad /, dein Token, Rolle PVEAuditor.

Privilege Separation

Ist beim Token „Privilege Separation" aktiv (Standard), braucht der Token einen eigenen Permission-Eintrag wie oben. Ist sie deaktiviert, erbt der Token die Rechte seines Benutzers.

Statt eines Tokens funktioniert auch ein Konto mit Passwort (benutzer@realm + Passwort) — das Script meldet sich dann per Ticket an. Ein Token ist der sauberere Weg, weil er sich einzeln zurückziehen lässt.

2. Proxmox-Profil in Vesana holen¶

Das Profil „Proxmox VE (API)" liegt in der Vesana-Bibliothek. Öffne Profile → Reiter Verfügbar, suche nach „Proxmox" und installiere es.

3. Host anlegen und API-Zugang hinterlegen¶

Lege einen Host an:

Als Ziel die IP-Adresse oder den DNS-Namen des Proxmox-Node eintragen.
Als Profil „Proxmox VE (API)" wählen.
Den Bereich API-Zugang öffnen (im Host-Assistenten; bei einem bestehenden Host in den Host-Einstellungen im Reiter Verbindung):
Benutzer: die Token-ID, benutzer@realm!tokenid
Passwort / Geheimnis: das Token-Secret

Der Zugang wird verschlüsselt gespeichert und steht nie in einem Profil oder Export.

Der Gerätename darf jetzt frei gewählt werden

Bis Profil-Version v10 mussten die Node-Checks über den Vesana-Gerätenamen auf den Proxmox-Node zeigen — hieß das Gerät in Vesana anders als der Node in Proxmox (z. B. „Dell Optiplex" statt pve1), antwortete Proxmox mit HTTP 500 und CPU, RAM und Root-FS standen dauerhaft auf CRITICAL. Ab v11 fragt das Script Proxmox selbst, welcher Node antwortet. Der Gerätename ist damit frei; nur wenn du von einem Host aus einen anderen Node des Clusters messen willst, trägst du den Node-Namen am Check ein.

Was die Checks messen¶

Node¶

Check	Bedeutung
CPU usage / Memory usage	Auslastung des Nodes. Auf ZFS-Hosts zählt der ARC-Cache als belegter Speicher — deshalb liegen die Vorgaben höher als bei einem normalen Server.
Root filesystem usage	Füllstand von `/`. Läuft das voll, kann Proxmox seine Konfiguration nicht mehr schreiben.
Swap usage · Load per core	Speicher-Überbuchung und Last pro Thread. „Load per core" ist standardmäßig aus (ein Hypervisor ist von Natur aus bursty).
Uptime	Reine Statistik (Info-Modus, Einheit Tage). Für einen Alarm nach einem ungeplanten Neustart: Info-Modus ausschalten, Einheit Stunden wählen und einen unteren Schwellwert setzen (warn 2 = „vor weniger als 2 Stunden gestartet").

Storage¶

Storage usage (fullest) — Füllstand des vollsten Storages; alle Storages stehen mit Typ, Größe und freiem Platz in den Check-Details.
Storages not reachable — Storages, die in Proxmox aktiviert sind, aber nicht antworten. Eine verschwundene NFS-Freigabe fällt hier auf, bevor das nächste Backup daran scheitert.

Einstellbar am Check: Storages ausschließen, einem Storage eigene Grenzen geben (NAME:warn:crit), kleine ISO-/Template-Freigaben über eine Mindestgröße ausblenden und — im Cluster — geteilte Storages überspringen, damit ein gemeinsames NFS einmal alarmiert statt einmal pro Node.

Backups¶

Check	Bedeutung
Oldest backup age	Alter des jüngsten Backups des Gasts, der am längsten nicht gesichert wurde — die Frage „ist das Backup von heute Nacht durch?" als Zahl. Gelesen werden die Backup-Storages dieses Nodes; ein hier eingebundener Proxmox Backup Server ist damit abgedeckt. Vorgaben: WARNING ab 26 h, CRITICAL ab 50 h.
Backup failures	vzdump-Läufe, die in einem echten Zeitfenster (Vorgabe 26 h) fehlgeschlagen sind.
Backup warnings	Läufe, die MIT Warnungen fertig wurden — im Info-Modus, also sichtbar ohne Alarm.
Guests without backup job	Gäste, die kein vzdump-Job erfasst.
Backup jobs configured	Anzahl der Jobs mit Zeitplan und nächstem Lauf — reine Anzeige.

Warum „mit Warnungen" kein Fehlschlag ist

Proxmox schließt einen Backup-Task mit OK, mit WARNINGS: n oder mit einem Fehlertext ab. Als Fehler zählt Proxmox nur das Dritte — ein Lauf mit Warnungen steht in der Task-Liste orange als „Warning: n", nicht rot. Vesana zieht dieselbe Grenze. Typische Ursachen: ein nicht antwortender Gast-Agent, ein übersprungenes Volume, ein Hook-Script, das etwas meldet — das Backup selbst ist gelaufen.

Backups auf einem Proxmox Backup Server

„Oldest backup age" sieht ein PBS-Ziel, das als Storage am Node hängt. Ob die Backups dort noch gültig sind (Verify), ob die Garbage Collection läuft und wie lange der Datastore noch reicht, beantwortet das eigene Profil Proxmox Backup Server (API).

Cluster, Hardware, Wartung¶

Quorum und Node-Ausfälle; Proxmox-Dienste; Zahl laufender Gäste (Info-Modus); offene Paket-Updates (Info-Modus). Standardmäßig nicht angelegt und bei Bedarf am Gerät hinzuzufügen: „VMs not running", „Containers not running", ZFS-Pool-Zustand, SMART und „SSD life left" (nicht jede Installation hat ZFS oder echte Platten) sowie der Subscription-Status. „SSD life left" ist die verbleibende Lebensdauer der am stärksten abgenutzten SSD laut Proxmox (wearout, 100 % = neu): gelb ab 20 %, rot ab 10 %. Die Details listen jede Platte mit Seriennummer und Restlebensdauer.

Anpassen¶

Jeder Check hat unter der Script-Auswahl einstellbare Werte — Ausnahmelisten, Zeitfenster, Einheiten. Ausnahmelisten sind präfix-fähig: test-* trifft alles, was so anfängt. Nimmt eine Ausnahme alle Objekte weg, meldet der Check UNKNOWN statt eines wertlosen „0 = in Ordnung".

Grenzwerte gehören nicht zu den einstellbaren Werten, sondern in die Schwellwert-Felder des Checks — dort wirken sie sofort und lassen sich pro Gerät überschreiben.

Reicht dir eine Messgröße nicht, öffne das Script in der Bibliothek und erweitere es: eine neue Messgröße steht danach in der Auswahl jedes Checks dieses Profils.

Umstieg von Profil-Version v10¶

Version v11 ersetzt die alten http_json-Checks durch Script-Checks mit neuen Namen (Proxmox — …). Nach dem Profil-Update:

Die neuen Checks werden angelegt (Aktualisieren an der Profil-Zeile, mit „Verbundene Hosts ebenfalls mit den neuen Checks versorgen").
Die alten Checks bietet der Update-Dialog einem Super-Admin zum Wegräumen in den Papierkorb an — dort auswählen. Besonders CPU usage (node), RAM usage (node), Root FS usage (node) und Uptime (node): genau die waren vom Node-Namen abhängig.

Verlauf und Schwellwerte der alten Checks bleiben bis zum Entfernen erhalten.

Troubleshooting¶

HTTP 500 — hostname lookup '…' failed (alte Checks): Der Node-Name in der URL ist falsch. Auf Profil v11 wechseln oder den Node-Namen fest in die URL schreiben.
HTTP 595 / 596 / 599: Das sind Proxmox-eigene Statuscodes; der Fehler kommt aus dem Cluster, nicht aus Vesana. 595: der Proxmox-Proxy erreicht den angefragten Node nicht (Node aus, Name/DNS falsch). 596: er kommt nicht bis zum Node (TLS/Zertifikat zwischen den Nodes). 599: interner Fehler des Proxys (oft Überlast).
HTTP 401/403: Token-ID (inklusive !tokenid), Secret und Rolle prüfen — PVEAuditor am Pfad /, bei aktiver „Privilege Separation" am Token selbst.
Check meldet „Node not reachable": Der Vesana-Server bzw. der Collector muss den Node auf Port 8006 erreichen.
Der Check bleibt UNKNOWN mit „Server-side plugins are not enabled for this tenant": Script-Checks auf dem Aktiven Collector brauchen die Freigabe „Eigene Plugins auf dem Server" für den Mandanten unter Admin → Agents & Collectors → Active-Checker. Checks, die ein Super-Admin gespeichert hat, laufen unabhängig davon.
Self-signed-Zertifikat: Proxmox nutzt ab Werk eins; die Checks des Profils akzeptieren das bewusst.