QEMU Guest Agent – Installation auf Ubuntu 24.04 in Proxmox

Übersicht

Der QEMU Guest Agent ermöglicht die Kommunikation zwischen dem Proxmox-Hypervisor und der virtuellen Maschine. Er ermöglicht unter anderem saubere Shutdowns, konsistente Snapshots und die Anzeige von IP-Adressen direkt im Proxmox-Webinterface.

---

Voraussetzungen

• Proxmox VE (beliebige aktuelle Version)
• Ubuntu 24.04 LTS als Gast-VM
• Root-Zugriff auf die VM

---

Schritt 1: QEMU Guest Agent in Proxmox aktivieren

Bevor der Agent in der VM installiert wird, muss das virtio-serial-Gerät im Hypervisor aktiviert werden.

1. Proxmox-Webinterface öffnen
2. Die gewünschte VM auswählen
3. Oben auf „Optionen" klicken
4. „QEMU Guest Agent" → doppelklicken → „Aktiviert" anhaken → speichern

⚠️ Die VM muss danach kalt gestartet werden (Stop + Start), nicht nur neu gebootet. Nur so wird das virtio-Gerät der VM hinzugefügt.

---

Schritt 2: QEMU Guest Agent in der VM installieren

Per SSH in die VM einloggen und das Paket installieren:

sudo apt-get install qemu-guest-agent

---

Schritt 3: VM herunterfahren und neu starten

sudo poweroff

Anschließend in Proxmox die VM über den Start-Button neu starten.

⚠️ Kein reboot verwenden – nur ein Kaltstart (Stop + Start) fügt das virtio-Gerät der VM hinzu.

---

Schritt 4: Dienst starten und Status prüfen

Nach dem Neustart per SSH einloggen:

sudo systemctl start qemu-guest-agent
sudo systemctl status qemu-guest-agent

Der Dienst sollte nun active (running) anzeigen:

● qemu-guest-agent.service - QEMU Guest Agent
     Active: active (running) since ...

Proxmox pingt den Agent regelmäßig (guest-ping called), was die erfolgreiche Kommunikation bestätigt.

---

Fehlerbehebung

Problem: Dependency failed – Dienst startet nicht

Dependency failed for qemu-guest-agent.service

Ursache: Das virtio-Gerät fehlt – Schritt 1 wurde nicht durchgeführt oder die VM wurde nur neu gebootet statt kalt gestartet.

Lösung: Virtio-Ports prüfen:

ls /dev/virtio-ports/ 2>/dev/null || echo "Kein virtio-ports Verzeichnis"
ls /dev/vport* 2>/dev/null || echo "Keine vport Geräte"

Wenn beide Befehle nichts zurückgeben → Schritt 1 wiederholen und VM kalt starten (Stop + Start in Proxmox).

Problem: static unit Warnung bei systemctl enable

The unit files have no installation config ...

Das ist kein Fehler. Der QEMU Guest Agent ist als „static unit" konzipiert und wird automatisch durch die Präsenz des virtio-Geräts aktiviert – ein manuelles enable ist nicht nötig.

---

Vorteile nach erfolgreicher Installation

• Sauberer Shutdown über Proxmox (kein hartes Abschalten)
• Konsistente Snapshots (Dateisystem wird eingefroren)
• IP-Adressen-Anzeige direkt im Proxmox-Webinterface
• Freeze/Thaw für backup-konsistente Zustände

---

Zusammenfassung der Befehle

# 1. Paket installieren
sudo apt-get install qemu-guest-agent

# 2. Dienst starten
sudo systemctl start qemu-guest-agent

# 3. Status prüfen
sudo systemctl status qemu-guest-agent

# 4. Virtio-Gerät prüfen (Fehlerdiagnose)
ls /dev/virtio-ports/