# Proxmox Custom Plugins: Den Hypervisor individuell erweitern

TL;DR / Management Summary Proxmox VE ist durch seine Architektur auf Basis von Perl-Modulen extrem modular. Wenn Standard-Lösungen für Storage oder Netzwerk nicht ausreichen, können wir Custom Plugins nutzen. Ein Senior Admin nutzt dieses Wissen, um proprietäre Storage-Systeme anzubinden oder eigene Hooks für das VM-Lifecycle-Management zu schreiben. Da Plugins tief in den Hypervisor-Prozess eingreifen, ist hier höchste Sorgfalt beim Coding und Testen geboten.

# 1. Einführung in die Plugin-Architektur

Die Welt der Perl-Module.

Proxmox nutzt spezialisierte Plugin-Klassen für verschiedene Subsysteme:

# 2. Storage Plugins erstellen

Neue Datenquellen erschließen.

Wenn Sie ein Storage-System haben, das Proxmox nicht nativ unterstützt (z.B. ein spezielles Cloud-Backend):

  1. Erstellen Sie ein neues Perl-Modul in /usr/share/perl5/PVE/Storage/Custom/.
  2. Erben Sie von PVE::Storage::Plugin.
  3. Implementieren Sie die Methoden check_config, activate_storage und alloc_image.

# Registrierung

Damit Proxmox das Plugin erkennt, muss es in der Plugin.pm registriert werden:

use PVE::Storage::Custom::MyPlugin;
PVE::Storage::Custom::MyPlugin->register();

# 3. Deep Dive: Hook-Scripts für VMs

Automatisierung bei Statusänderungen.

Hook-Scripts sind die einfachste Form, Proxmox zu erweitern, ohne tief in den Core-Code einzugreifen.

#!/bin/bash
VMID=$1
PHASE=$2
if [ "$PHASE" == "pre-start" ]; then
    echo "Bereite Umgebung für VM $VMID vor..."
fi

# 4. Day-2 Operations: Plugin-Updates & Stabilität

Den Cluster nicht gefährden.

Eigene Plugins laufen im Kontext des pvedaemon. Ein Absturz im Plugin kann die gesamte Web-GUI lahmlegen.

# 5. Troubleshooting & “War Stories”

Wenn die Erweiterung den Host blockiert.

# Top 3 Fehlerbilder

  1. Symptom: Proxmox-GUI zeigt nur noch einen “White Screen”.

    • Ursache: Syntaxfehler im geladenen Custom Plugin blockiert das Laden des gesamten Frameworks.
    • Lösung: Plugin via SSH aus der Plugin.pm entfernen und Dienst pveproxy neustarten.

  2. Symptom: VM-Start dauert 2 Minuten.

    • Ursache: Ein Hook-Script hängt in einer Endlosschleife oder wartet auf einen Netzwerk-Timeout.
    • Fix: Nutzen Sie Timeouts in Ihren Bash-Skripten.

  3. Symptom: Storage-Plugin findet keine Volumes.

    • Ursache: API-Token für das Backend ist abgelaufen.

# “War Story”: Der “Zirkuläre” Hook

Ein Admin schrieb ein Hook-Script, das beim Start einer VM ein Backup der gleichen VM via API anstieß. Das Ergebnis: Die VM startete -> Hook triggerte Backup -> Backup sperrte die VM (Lock) -> VM-Start schlug fehl -> Hook triggerte Error-Log -> Backup-Dienst versuchte den Lock zu lösen. Das Ergebnis: Der Host war für 30 Minuten mit tausenden hängenden Prozessen beschäftigt. Lehre: Hook-Scripts müssen atomar und unabhängig sein. Starten Sie niemals langlaufende oder blockierende Tasks direkt im Hook-Pfad. Nutzen Sie stattdessen systemd-run oder at.

# 6. Monitoring & Reporting

Performance-Audit.

# Plugin-Latenz messen

Überwachen Sie die Zeit, die der pvedaemon für API-Antworten braucht.

# 7. Fazit & Empfehlung

Custom Plugins machen Proxmox zum flexibelsten Hypervisor am Markt.

# Anhang: Cheatsheet (Hook Phasen)

Phase Zeitpunkt
pre-start Vor dem QEMU Start
post-start Sobald die VM läuft
pre-stop Vor dem Shutdown
post-stop Nachdem die VM aus ist

# Referenzen