Der QEMU Guest Agent verbindet eine virtuelle Maschine mit ihrem Hypervisor. Unter Proxmox VE ermöglicht er ein sauberes Herunterfahren, konsistente Backups und die Anzeige der IP-Adressen in der Weboberfläche. Unter Debian und Ubuntu ist die Installation in wenigen Minuten erledigt. Diese Anleitung zeigt Ihnen alle Schritte inklusive Test und Fehlerbehebung.
Was macht der Guest Agent genau?
Der Agent ist ein kleiner Dienst, der im Gastsystem läuft und über einen virtuellen seriellen Port Befehle vom Host entgegennimmt. Die wichtigsten Funktionen:
- Shutdown und Reboot über den Agenten statt über ein ACPI-Signal
- fs-freeze/fs-thaw: Dateisysteme werden vor einem Snapshot-Backup kurz eingefroren, damit das Backup konsistent ist
- Netzwerkinformationen: Proxmox zeigt die IP-Adressen der VM in der Übersicht an
- Zeitabgleich nach dem Fortsetzen einer pausierten VM
Schritt 1: Den Agenten in Proxmox aktivieren
Wenn Sie selbst Zugriff auf Proxmox haben:
- VM auswählen → Options → QEMU Guest Agent doppelklicken.
- Use QEMU Guest Agent aktivieren und bestätigen.
- Die VM vollständig herunterfahren und wieder starten. Ein Reboot aus dem Gastsystem heraus reicht nicht, weil das neue virtuelle Gerät erst beim Kaltstart angelegt wird.
Schritt 2: Paket im Gastsystem installieren
Melden Sie sich per SSH an der VM an und installieren Sie das Paket:
sudo apt update
sudo apt install -y qemu-guest-agentFür RHEL-basierte Systeme wie AlmaLinux oder Rocky Linux lautet der Befehl:
sudo dnf install -y qemu-guest-agentSchritt 3: Dienst starten
sudo systemctl start qemu-guest-agent
sudo systemctl status qemu-guest-agentDie Statusausgabe sollte active (running) zeigen.
Hinweis zu systemctl enable: Unter Debian und Ubuntu ist der Dienst als static markiert. Er wird automatisch gestartet, sobald das passende virtuelle Gerät beim Booten erkannt wird. Ein systemctl enable ist deshalb nicht nötig und gibt nur einen Hinweis aus. Das ist kein Fehler.
Schritt 4: Funktion prüfen
Im Gastsystem können Sie prüfen, ob der virtuelle Port vorhanden ist:
ls -l /dev/virtio-ports/Dort sollte ein Eintrag org.qemu.guest_agent.0 erscheinen.
Auf dem Proxmox-Node testen Sie die Verbindung. Ersetzen Sie 100 durch die ID Ihrer VM:
qm agent 100 ping
qm agent 100 get-osinfoLiefert get-osinfo den Namen und die Version Ihrer Distribution zurück, funktioniert der Agent.
Fehlerbehebung
Der Dienst startet nicht: „Dependency failed“
Der Dienst wartet auf das Gerät /dev/virtio-ports/org.qemu.guest_agent.0. Fehlt es, ist die Option in Proxmox nicht aktiviert oder die VM wurde danach nicht kalt gestartet. Aktivieren Sie die Option, fahren Sie die VM herunter und starten Sie sie neu.
Proxmox meldet „QEMU guest agent is not running“
- Prüfen Sie mit
systemctl status qemu-guest-agent, ob der Dienst läuft. - Prüfen Sie, ob
/dev/virtio-ports/org.qemu.guest_agent.0existiert. - Bei Minimal-Images wurde das Paket eventuell nie installiert. Installieren Sie es nach Schritt 2.
Backups hängen beim Einfrieren des Dateisystems
Das passiert gelegentlich bei Datenbanken mit sehr vielen Schreibvorgängen. Aktualisieren Sie das System mit sudo apt full-upgrade. Bleibt das Problem bestehen, kann der Freeze für einzelne VMs deaktiviert werden. Sprechen Sie uns in diesem Fall gerne an.
Mehrere VMs auf einmal prüfen
Wer viele VMs betreibt, kann auf dem Proxmox-Node schnell feststellen, auf welchen der Agent antwortet:
for id in $(qm list | awk 'NR>1 {print $1}'); do
printf "%s: " "$id"
qm agent "$id" ping >/dev/null 2>&1 && echo ok || echo "kein Agent"
doneAusgeschaltete VMs erscheinen dabei ebenfalls als „kein Agent“.
Kurzfassung
sudo apt update
sudo apt install -y qemu-guest-agent
sudo systemctl start qemu-guest-agent
systemctl is-active qemu-guest-agentGut zu wissen
Viele aktuelle Cloud-Images bringen den Agenten bereits mit. Ein kurzer Blick mit systemctl status qemu-guest-agent nach der Bereitstellung lohnt sich trotzdem.
Sie möchten sich nicht um Hypervisor und Treiber kümmern? Unsere vServer laufen auf Proxmox-Clustern in Österreich, Sie verwalten nur Ihr Betriebssystem.
