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.

Proxmox-Webinterface öffnen
Die gewünschte VM auswählen
Oben auf „Optionen" klicken
„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/

3.2 KiB Raw Blame History Unescape Escape