QEMU Guest Agent in Proxmox VE: Installation, Funktionen und Troubleshooting

Der QEMU Guest Agent (QGA) ist ein kleiner Daemon, der innerhalb einer virtuellen Maschine läuft und über einen VirtIO-Serial-Kanal mit dem Proxmox-VE-Host kommuniziert. Ohne den Guest Agent fehlen Proxmox wichtige Informationen über den Zustand der VM — und Funktionen wie konsistente Snapshots funktionieren nicht korrekt.

Was der Guest Agent leistet

Der QEMU Guest Agent bietet vier zentrale Funktionen:

1. Freeze/Thaw für konsistente Snapshots

Die wichtigste Funktion: Bevor Proxmox einen Snapshot erstellt, sendet es über den Guest Agent einen Freeze-Befehl an das Gastbetriebssystem. Dieser friert alle Dateisystem-I/O-Operationen ein, sodass der Snapshot einen konsistenten Zustand abbildet. Nach dem Snapshot wird das Dateisystem mit Thaw wieder freigegeben.

Proxmox VE                    Guest Agent (in VM)
    |                              |
    |--- guest-fsfreeze-freeze --> |
    |                              | (Dateisystem eingefroren)
    |--- Snapshot erstellen -----> |
    |--- guest-fsfreeze-thaw ----> |
    |                              | (I/O fortgesetzt)

Ohne Guest Agent erstellt Proxmox sogenannte Crash-konsistente Snapshots — vergleichbar mit dem Zustand nach einem Stromausfall. Datenbanken und Anwendungen mit offenen Schreibvorgängen können nach der Wiederherstellung inkonsistent sein.

2. IP-Adress-Anzeige

Im Proxmox-Dashboard zeigt die Spalte IPs die Netzwerkadressen der VM an — aber nur, wenn der Guest Agent installiert ist. Ohne ihn bleibt das Feld leer. Besonders in Umgebungen mit DHCP und vielen VMs ist die IP-Anzeige unverzichtbar.

3. Sauberer Shutdown

Der Guest Agent ermöglicht einen ordnungsgemäßen Shutdown der VM über die Proxmox-GUI. Ohne Guest Agent kann Proxmox nur ein ACPI-Shutdown-Signal senden, das nicht von allen Betriebssystemen zuverlässig verarbeitet wird. Mit dem Guest Agent wird ein echtes Shutdown-Kommando im Gastsystem ausgeführt.

4. Zeitübernahme nach Suspend/Resume

Nach einem Suspend/Resume oder einer Live-Migration synchronisiert der Guest Agent die Systemzeit der VM mit der Host-Zeit. Das verhindert Zeitdrift, die Probleme mit Kerberos-Authentifizierung, TLS-Zertifikaten und Logging verursachen kann.

Installation unter Linux

Debian/Ubuntu

# Guest Agent installieren
apt update
apt install -y qemu-guest-agent

# Dienst starten und aktivieren
systemctl enable --now qemu-guest-agent

# Status prüfen
systemctl status qemu-guest-agent

RHEL/AlmaLinux/Rocky Linux

# Guest Agent installieren
dnf install -y qemu-guest-agent

# Dienst starten und aktivieren
systemctl enable --now qemu-guest-agent

# Status prüfen
systemctl status qemu-guest-agent

Alpine Linux (LXC-Host oder leichte VMs)

# Guest Agent installieren
apk add qemu-guest-agent

# In /etc/conf.d/qemu-guest-agent den Channel konfigurieren
echo 'GA_PATH="/dev/virtio-ports/org.qemu.guest_agent.0"' > /etc/conf.d/qemu-guest-agent

# Dienst starten und aktivieren
rc-update add qemu-guest-agent default
service qemu-guest-agent start

Arch Linux

pacman -S qemu-guest-agent
systemctl enable --now qemu-guest-agent

Installation unter Windows

Voraussetzungen

Der QEMU Guest Agent für Windows ist Teil des VirtIO-Treiberpakets. Wenn die VirtIO-Treiber bereits installiert sind, fehlt möglicherweise nur der Guest Agent.

Installation über den VirtIO-Installer

1. VirtIO-ISO herunterladen: Die aktuelle Version von fedorapeople.org/groups/virt/virtio-win/direct-downloads/
2. ISO in die VM einbinden: Hardware > CD/DVD > ISO Image auswählen
3. Installer ausführen: virtio-win-guest-tools.exe auf dem ISO starten
4. Der Installer installiert alle VirtIO-Treiber und den Guest Agent

Manuelle Installation

Falls nur der Guest Agent benötigt wird:

# Im gemounteten VirtIO-ISO
cd D:\guest-agent\

# 64-Bit-Version installieren
msiexec /i qemu-ga-x86_64.msi /quiet /norestart

# Dienst prüfen
Get-Service QEMU-GA

Dienst-Status prüfen

# Status des QEMU Guest Agent
Get-Service QEMU-GA | Format-List Name, Status, StartType

# Erwartete Ausgabe:
# Name      : QEMU-GA
# Status    : Running
# StartType : Automatic

Proxmox-seitige Konfiguration

Guest Agent in der VM-Konfiguration aktivieren

Der Guest Agent muss in den VM-Optionen von Proxmox VE explizit aktiviert werden:

Web-GUI: VM > Options > QEMU Guest Agent > Edit > Häkchen setzen

CLI:

# Guest Agent aktivieren
qm set <VMID> --agent enabled=1

# Mit Freeze/Thaw für Snapshots (empfohlen)
qm set <VMID> --agent enabled=1,fstrim_cloned_disks=1

# Konfiguration prüfen
qm config <VMID> | grep agent

Die Option fstrim_cloned_disks=1 führt nach einem Klon-Vorgang automatisch ein TRIM auf den Disks der neuen VM aus — wichtig für Thin-Provisioning.

VirtIO-Serial-Port

Proxmox erstellt automatisch einen VirtIO-Serial-Port (/dev/virtio-ports/org.qemu.guest_agent.0), wenn der Guest Agent aktiviert ist. Dieser Kanal dient als Kommunikationsweg zwischen Host und Gast.

# Auf dem Proxmox-Host: Kommunikation testen
qm agent <VMID> ping

# Netzwerkinformationen abrufen
qm agent <VMID> network-get-interfaces

# Dateisystem-Informationen
qm agent <VMID> get-fsinfo

Guest-Agent-Befehle im Detail

Der Guest Agent unterstützt zahlreiche Befehle, die über qm agent oder direkt via QMP aufgerufen werden können:

# Dateisysteme einfrieren (vor Snapshot)
qm agent <VMID> fsfreeze-freeze

# Status prüfen
qm agent <VMID> fsfreeze-status

# Dateisysteme wieder freigeben
qm agent <VMID> fsfreeze-thaw

# Hostname abrufen
qm agent <VMID> get-host-name

# OS-Informationen
qm agent <VMID> get-osinfo

# Zeitinformationen
qm agent <VMID> get-time

# Netzwerk-Interfaces
qm agent <VMID> network-get-interfaces

# TRIM ausführen (SSD-Optimierung)
qm agent <VMID> fstrim

Troubleshooting

Problem: Guest Agent antwortet nicht

Symptom: qm agent <VMID> ping gibt einen Timeout-Fehler zurück.

Checkliste:

# 1. Ist der Guest Agent in Proxmox aktiviert?
qm config <VMID> | grep agent
# Erwartet: agent: enabled=1

# 2. Läuft der Dienst in der VM?
# Linux:
systemctl status qemu-guest-agent
# Windows:
# Get-Service QEMU-GA

# 3. Existiert der VirtIO-Serial-Port in der VM?
ls -la /dev/virtio-ports/
# Erwartet: org.qemu.guest_agent.0

# 4. Firewall blockiert den Kanal?
# Der Guest Agent nutzt keinen Netzwerk-Port, sondern einen
# VirtIO-Serial-Kanal. Firewalls sind hier nicht das Problem.

# 5. VM neu starten (nach Aktivierung des Guest Agent in Proxmox)
qm reboot <VMID>

Problem: IP-Adressen werden nicht angezeigt

Ursache: Der Guest Agent läuft, aber Proxmox zeigt keine IPs an.

# Direkte Abfrage der Netzwerk-Interfaces
qm agent <VMID> network-get-interfaces

# Falls der Befehl funktioniert, aber die GUI keine IPs zeigt:
# Proxmox VE GUI neu laden (Ctrl+Shift+R im Browser)
# Oder kurz warten — die GUI aktualisiert die Daten periodisch

Problem: Freeze/Thaw schlägt fehl

# Manuelles Freeze testen
qm agent <VMID> fsfreeze-freeze

# Häufige Ursache: NFS- oder CIFS-Mounts
# Netzwerk-Dateisysteme können den Freeze blockieren
# Lösung: Mounts in /etc/fstab mit "nofail" und ggf. exclude

# Status prüfen (sollte "frozen" zurückgeben)
qm agent <VMID> fsfreeze-status

# Wichtig: Thaw nicht vergessen!
qm agent <VMID> fsfreeze-thaw

Problem: Guest Agent unter Windows startet nicht

# Dienst-Details prüfen
Get-WmiObject Win32_Service | Where-Object {$_.Name -eq "QEMU-GA"} |
  Select-Object Name, State, StartMode, PathName

# Häufige Ursache: VirtIO-Serial-Treiber fehlt
# Im Geräte-Manager prüfen: "PCI Simple Communications Controller"
# muss als VirtIO Serial Driver erkannt werden

# Treiber nachinstallieren
pnputil /add-driver "D:\vioserial\2k22\amd64\vioser.inf" /install

# Dienst neu starten
Restart-Service QEMU-GA

Best Practices

Automatische Installation per Cloud-Init

Für neue Linux-VMs kann der Guest Agent automatisch über Cloud-Init installiert werden:

# Cloud-Init User-Data
#cloud-config
packages:
  - qemu-guest-agent
runcmd:
  - systemctl enable --now qemu-guest-agent

Monitoring der Guest-Agent-Verbindung

# Script: Guest Agent Status aller VMs prüfen
for vmid in $(qm list | awk 'NR>1 {print $1}'); do
  name=$(qm config $vmid | grep '^name:' | awk '{print $2}')
  if qm agent $vmid ping 2>/dev/null; then
    echo "VM $vmid ($name): Guest Agent OK"
  else
    echo "VM $vmid ($name): Guest Agent NICHT erreichbar"
  fi
done

Backup-Konsistenz sicherstellen

Für Produktivumgebungen mit Datenbanken empfiehlt sich zusätzlich zum Freeze/Thaw ein Pre-Freeze-Script innerhalb der VM:

# /etc/qemu/fsfreeze-hook.d/10-mysql-flush.sh
#!/bin/bash
case "$1" in
  freeze)
    mysql -e "FLUSH TABLES WITH READ LOCK; SYSTEM sync;"
    ;;
  thaw)
    mysql -e "UNLOCK TABLES;"
    ;;
esac

Das Hook-Script wird automatisch vom Guest Agent vor dem Freeze bzw. nach dem Thaw aufgerufen und sorgt für datenbankskonsistente Snapshots.

Fazit

Der QEMU Guest Agent ist ein kleines Werkzeug mit großer Wirkung. Konsistente Snapshots, IP-Anzeige und saubere Shutdowns sind in Produktivumgebungen unverzichtbar. Die Installation dauert wenige Minuten, und mit den Freeze-Hook-Scripts lässt sich die Backup-Konsistenz auch für anspruchsvolle Datenbank-Workloads sicherstellen. In jeder Proxmox-Umgebung sollte der Guest Agent zur Standardkonfiguration jeder VM gehören.