Wie installiere ich den Qemu Guest Agent

Der QEMU Guest Agent verbindet Ihre virtuelle Maschine mit dem Hypervisor Proxmox VE. Er ermöglicht sauberes Herunterfahren, konsistente Snapshots und Backups mit Dateisystem-Freeze und zeigt die IP-Adressen der VM in der Proxmox-Oberfläche an. Hier finden Sie die Installation für Debian, Ubuntu, AlmaLinux/Rocky Linux und Windows im Überblick, jeweils mit Link zur ausführlichen Anleitung.

Wozu brauche ich den QEMU Guest Agent?

• Sauberes Herunterfahren und Neustarten der VM aus Proxmox heraus
• Konsistente Backups und Snapshots: Vor dem Snapshot werden die Dateisysteme kurz eingefroren (fs-freeze), damit keine halb geschriebenen Daten gesichert werden.
• IP-Adressen in der Übersicht der VM in Proxmox
• Zeitabgleich nach dem Fortsetzen einer pausierten VM

Bei Alpenhost-vServern sorgt der Agent dafür, dass Snapshots und Backups zuverlässig konsistent sind. Wir empfehlen ihn deshalb auf jedem vServer.

Schritt 1: Option in Proxmox aktivieren

Damit der Agent arbeiten kann, braucht die VM einen virtuellen Kommunikationskanal (VirtIO-Serial). Bei eigenem Proxmox aktivieren Sie ihn unter VM → Options → QEMU Guest Agent → Use QEMU Guest Agent. Danach muss die VM vollständig heruntergefahren und neu gestartet werden, ein Neustart aus dem Gastsystem reicht nicht.

Schritt 2: Agent im Gastsystem installieren

Debian und Ubuntu

sudo apt update
sudo apt install -y qemu-guest-agent
sudo systemctl start qemu-guest-agent
systemctl status qemu-guest-agent --no-pager

Ein systemctl enable ist unter Debian und Ubuntu nicht nötig: Der Dienst startet automatisch, sobald das virtuelle Gerät beim Booten erkannt wird. Alle Details, Tests und Fehlerbehebung finden Sie in der Anleitung QEMU Guest Agent unter Debian und Ubuntu installieren.

AlmaLinux, Rocky Linux, CentOS und RHEL

sudo dnf install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

Auf älteren Systemen mit CentOS 7 verwenden Sie yum statt dnf.

Windows Server und Windows 10/11

Unter Windows wird der Agent zusammen mit den VirtIO-Treibern installiert:

1. Öffnen Sie das CD-Laufwerk mit der VirtIO-Treiber-ISO.
2. Führen Sie virtio-win-guest-tools.exe aus. Der Installer richtet alle Treiber und den Guest Agent ein.
3. Prüfen Sie in einer PowerShell den Dienst:

   Get-Service QEMU-GA

Woher Sie die ISO bekommen und wie Sie sie einbinden, zeigt Installation der VirtIO-Treiber für Windows auf Proxmox VMs. Die ausführliche Windows-Anleitung finden Sie unter QEMU Guest Agent unter Windows installieren.

Schritt 3: Funktion prüfen

Im Gastsystem unter Linux sollte das virtuelle Gerät vorhanden sein:

ls -l /dev/virtio-ports/org.qemu.guest_agent.0

Auf dem Proxmox-Node testen Sie die Verbindung, ersetzen Sie 100 durch die ID Ihrer VM:

qm agent 100 ping
qm agent 100 network-get-interfaces

Liefert der zweite Befehl die Netzwerkkarten samt IP-Adressen, ist der Agent eingerichtet. In der Proxmox-Oberfläche erscheinen die IP-Adressen dann im Reiter Summary der VM.

Häufige Probleme

„QEMU guest agent is not running“

• Ist die Option in Proxmox aktiviert, und wurde die VM danach kalt gestartet (Stop und Start)?
• Läuft der Dienst im Gastsystem (systemctl status qemu-guest-agent bzw. Get-Service QEMU-GA)?
• Unter Windows: Ist der VirtIO Serial Driver im Geräte-Manager ohne Warnsymbol installiert?

Der Dienst startet nicht: „Dependency failed“

Das virtuelle Gerät fehlt. Aktivieren Sie die Option in Proxmox und starten Sie die VM vollständig neu.

Backups bleiben beim Einfrieren hängen

Aktualisieren Sie Gastsystem und Agent auf die neueste Version. Unter Windows führen Sie dazu virtio-win-guest-tools.exe aus einer aktuellen ISO erneut aus. Besteht das Problem weiter, melden Sie sich per Ticket bei uns.

Weiterführende Informationen

Die offizielle Dokumentation finden Sie im Proxmox-Wiki unter dem Stichwort Qemu-guest-agent. Allgemeine Informationen zu Snapshots und Backups Ihres vServers lesen Sie im Artikel Alles Wissenswerte über Backups und Snapshots.