README.md aktualisiert

README.md

@@ -1,2 +1,124 @@
-# QEMU-Guest-Agent
+# 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/
+```