# 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:

```bash
sudo apt-get install qemu-guest-agent
```

---

## Schritt 3: VM herunterfahren und neu starten

```bash
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:

```bash
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:

```bash
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

```bash
# 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/
```