From 8787304f0b5b3df6ced9219ac10a98dafb0e34d5 Mon Sep 17 00:00:00 2001 From: duffyduck Date: Sun, 9 Aug 2026 10:47:14 +0200 Subject: [PATCH] README: SPICE, USB-Weiterleitung und Dongle nachgetragen Beim Abgleich Code gegen README fehlten der Unterbefehl "spice", die Parameter --spice/--usb/--iso und das ganze Thema dahinter. Jetzt drin, mit dem Grund: eine abgeschottete Maschine erreicht keinen USB-Server im Netz, ueber SPICE kommt das Geraet dagegen vom Rechner des Bedieners. Dazu die beiden Fallen, beide am laufenden System gemessen: USB ohne SPICE ist wirkungslos ("no spice port"), und SPICE vertraegt sich nicht mit geladenem Arbeitsspeicher, solange im Original nicht schon 'vga: qxl' steht. Mit der Empfehlung, genau das auf Produktivmaschinen einmal zu setzen. Ausserdem nachgetragen: das nachtraegliche Umstellen mit Taste p samt sauberem Neustart, --no-install-deps, das Verzeichnis der Transfer-Laufwerke, tools/get-guest-tools.sh und dass der noVNC-Verweis die IP traegt. Eine Zeile war schlicht falsch: transfer_ui.py sei "auch aus dem Explorer erreichbar" - die Anbindung steht noch aus. Falsche Doku ist schlimmer als keine. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 93 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5a99957..178c5f0 100644 --- a/README.md +++ b/README.md @@ -38,8 +38,14 @@ git clone pvesnap && cd pvesnap | `--port ` | Port der Web-Oberfläche | | `--bind ` | Adresse, auf der sie lauscht (Vorgabe `0.0.0.0`) | | `--no-start` | installieren, aber Dienste nicht starten | +| `--no-install-deps` | fehlende Werkzeuge (`parted`, `exfatprogs`) nicht nachinstallieren | | `--force` | auch ohne erkanntes Proxmox VE installieren | +Läuft die Web-Oberfläche bereits, wird sie vor dem Austausch des Codes sauber +angehalten und danach wieder gestartet — sie könnte noch Snapshots eingebunden +haben. Nur wenn ein **fremder** Prozess auf dem Port sitzt, gibt es eine +Warnung samt PID. + Das Skript legt an: | Pfad | Inhalt | @@ -49,6 +55,7 @@ Das Skript legt an: | `/usr/local/bin/pvesnap-explorer` | Zwei-Fenster-Explorer | | `/usr/local/bin/pvesnap-web` | Web-Oberfläche | | `/usr/local/bin/pvesnap-recovery` | Snapshot als Maschine starten | +| `/var/lib/pvesnap/transfer/` | Transfer-Laufwerke (Abbilddateien) | | `/etc/pvesnap/pvesnap.conf` | Konfiguration (wird bei Updates **nicht** überschrieben) | | `/var/lib/pvesnap/state.json` | merkt sich die letzten Läufe | | `/etc/systemd/system/pvesnap.service` | systemd-Unit des Snapshot-Dienstes | @@ -846,7 +853,7 @@ einklinken → zurück in denselben Steckplatz, VM läuft durchgehend ### An die Konsole kommen ``` -https://:8006/?console=kvm&novnc=1&vmid=9802&node=&resize=off&cmd= +https://172.0.4.1:8006/?console=kvm&novnc=1&vmid=9802&node=pvetest01&resize=off&cmd= ``` Diese Adresse gibt `pvesnap-recovery` nach dem Anlegen aus, ebenso @@ -854,6 +861,80 @@ Diese Adresse gibt `pvesnap-recovery` nach dem Anlegen aus, ebenso Proxmox — die Maschine taucht auch in der Weboberfläche auf, markiert mit dem Tag `pvesnap-recovery`. Bei Containern geht zusätzlich `pct enter `. +> Vorne steht bewusst die **IP-Adresse**, nicht der Node-Name: Auf dem +> Proxmox-Host löst der Name auf, am Arbeitsplatz meist nicht. Sie kommt aus +> `/etc/pve/.members`. Der Node hinter `node=` bleibt der Name — so erwartet +> Proxmox ihn. + +### Dongle und andere USB-Geräte — SPICE + +Eine abgeschottete Maschine hat kein Netzwerk. Ein Software-Schutzmodul hängt +sonst an einem USB-Server im Netz — der ist damit unerreichbar. + +SPICE löst das: Die USB-Weiterleitung kommt **vom Rechner des Bedieners**, nicht +über das Gastnetz. Die Maschine bleibt also abgeschottet und hat trotzdem ihren +Dongle. + +```bash +pvesnap-recovery live 802 --usb 2 --no-resume +pvesnap-recovery spice 9802 -o vm.vv +scp root@172.0.4.1:vm.vv . && remote-viewer vm.vv +``` + +Im remote-viewer dann unter **USB-Geräteauswahl** das Gerät anhaken. In der +Oberfläche liegt das alles auf Taste `p` — auch nachträglich bei einer schon +laufenden Maschine. + +**Guest-Tools braucht es dafür nicht.** Der Dongle taucht im Gast als +gewöhnliches USB-Gerät auf; QEMU und der SPICE-Client machen die Arbeit. Die +Tools (`tools/get-guest-tools.sh` holt virtio-win) sind nur für Zwischenablage, +automatische Auflösung und Mauszeiger. + +Zwei Dinge, die man vorher wissen sollte: + +**USB braucht SPICE.** Ohne `vga: qxl` legt QEMU die Weiterleitungen zwar an, +aber es gibt keinen Kanal, der sie transportiert (`no spice port`). `--usb` +schaltet die Anzeige deshalb automatisch mit ein. + +**SPICE und geladener Arbeitsspeicher schließen sich aus** — je nachdem, was im +Original steht: + +| Original | warmer RAM-Zustand | SPICE + Dongle | +|---|---|---| +| `vga: std` (Vorgabe) | ✅ | nur mit `--no-resume` | +| `vga: qxl` | ✅ | ✅ gleichzeitig | + +`qxl` hat 64 MB Grafikspeicher, die Vorgabe 16. Der gespeicherte Zustand passt +dann nicht mehr, das Laden bricht mit `Size mismatch: vga.vram` ab — und die +Maschine bleibt angehalten stehen, während Proxmox `TASK OK` meldet. +`pvesnap-recovery` lehnt die Kombination deshalb ab und nennt die Auswege. + +> **Für Produktivmaschinen:** Setz dort einmal `vga: qxl`. Dann tragen alle +> künftigen Snapshots es mit, und im Ernstfall gibt es warmen RAM-Zustand +> **und** Dongle gleichzeitig. Nachträglich lässt sich das bei einem +> vorhandenen Snapshot nicht mehr reparieren. + +### Nachträglich umstellen + +Taste `p` in der Detailansicht ändert SPICE und USB auch an einer bestehenden +Maschine: + +| | | +|---|---| +| SPICE ein/aus | **Neustart nötig** — die Grafikkarte lässt sich im Betrieb nicht wechseln | +| USB dazu oder weg | sofort, solange der SPICE-Kanal schon steht | + +Der Neustart läuft sauber über Proxmox' `reboot`: ACPI-Herunterfahren, der Gast +hängt seine Dateisysteme selbst aus, danach geht er wieder hoch — kein +Stromausfall. Antwortet er nicht, schlägt es fehl, statt hart abzuschalten. + +Ein Neustart **im Gast** hilft dagegen nicht: Dabei setzt sich nur die Maschine +zurück, der QEMU-Prozess läuft mit der alten Grafikkarte weiter. + +> Bei einer Maschine mit geladenem Arbeitsspeicher ist der nach einem Neustart +> **endgültig weg** — Proxmox gibt ihn schon beim ersten Start frei. Offene +> Programme und ungespeicherte Daten sind dann verloren. + ### Wiederherstellung mit Netzwerk ```bash @@ -890,6 +971,9 @@ Karte erst zuschalten, wenn klar ist, dass die Luft rein ist. | `--net none\|down\|on` | keine Karte / Karte ohne Leitung / voll am Netz | | `--resume` / `--no-resume` | Arbeitsspeicher laden bzw. bewusst kalt starten | | `--transfer ` | vorbereitetes Transfer-Laufwerk anhängen (mehrfach möglich) | +| `--spice` | SPICE-Anzeige (`vga: qxl`), zusätzlich zu noVNC | +| `--usb ` | so viele USB-Weiterleitungen über SPICE (schaltet `--spice` mit ein) | +| `--iso ` | Abbild als CD einlegen, z. B. `local:iso/virtio-win.iso` | | `--memory `, `--cores ` | abweichende Ausstattung (nicht mit `--resume`) | | `--name ` | Name der neuen Maschine | | `--keep-binds` | durchgereichte Host-Verzeichnisse des Originals übernehmen | @@ -903,6 +987,7 @@ Karte erst zuschalten, wenn klar ist, dass die Luft rein ist. | `list` | vorhandene Wiederherstellungen anzeigen | | `start` / `stop` | hoch- bzw. herunterfahren | | `console ` | noVNC-Adresse ausgeben | +| `spice ` | Verbindungsdatei für remote-viewer (`-o datei.vv`) | | `flatten ` | vom Quell-Snapshot lösen (für den Dauerbetrieb) | | `cleanup` | Klone entfernen, zu denen es keinen Gast mehr gibt | | `destroy ` | restlos verwerfen | @@ -946,15 +1031,17 @@ pvesnap/ recovery.py Snapshot als Maschine starten (Klone, Konfiguration, Aufräumen) recovery_ui.py ncurses-Oberfläche und Kommandozeile dazu transfer.py Transfer-Laufwerke: anlegen, ein-/aushängen, Verriegelung - transfer_ui.py deren Bildschirm, auch aus dem Explorer erreichbar + transfer_ui.py deren Bildschirm (Taste v in pvesnap-recovery) web/ Web-Oberfläche zum Herunterladen server.py HTTP-Server, ZIP im Strom, Zugangsschlüssel assets.py Stylesheet und HTML-Gerüst config/pvesnap.conf.example -systemd/pvesnap.service +systemd/pvesnap.service systemd/pvesnap-web.service +tools/get-guest-tools.sh holt virtio-win auf einen ISO-Storage install.sh uninstall.sh ``` -Der Dienst (`pvesnap`) und die beiden Explorer teilen sich `proxmox.py`; -`snapfs.py` liefert beiden Oberflächen einen ganz gewöhnlichen Pfad, sodass -Explorer und Web-Oberfläche nichts über Ceph, ZFS oder LVM wissen müssen. +Alle vier Werkzeuge teilen sich `proxmox.py`. `snapfs.py` liefert Explorer und +Web-Oberfläche einen ganz gewöhnlichen Pfad, sodass sie nichts über Ceph, ZFS +oder LVM wissen müssen; `recovery.py` geht den anderen Weg und überlässt das +Klonen der Storage-Schicht von Proxmox selbst.