From 9fa6c05af7a84189424c68457616b48524a3fb65 Mon Sep 17 00:00:00 2001 From: Kevin Janssen Date: Fri, 20 Nov 2026 12:17:23 +0100 Subject: [PATCH] Document the Proxmox host, its read-only access and the local Proxmox test VM Co-Authored-By: Claude Opus 5.5 --- Rust_RMM_Implementierungsspezifikation.md | 2 + deploy/proxmox/README.md | 45 +++++++++++++++++++++++ docs/handover.md | 1 + docs/operations-access.md | 3 +- tools/dev_stage.py | 9 ++++- 5 files changed, 57 insertions(+), 3 deletions(-) create mode 100644 deploy/proxmox/README.md diff --git a/Rust_RMM_Implementierungsspezifikation.md b/Rust_RMM_Implementierungsspezifikation.md index 778339e..5cd15a2 100644 --- a/Rust_RMM_Implementierungsspezifikation.md +++ b/Rust_RMM_Implementierungsspezifikation.md @@ -12,6 +12,8 @@ Der Agent meldet den Gerätetyp mit dem passiven Hardwareinventar. `physical` be Für aktuelle virtuelle Geräte kann die WebUI einen registrierten Hypervisor aus demselben Kundenbestand zuordnen. Die Geräteübersicht zeigt diese Verbindung unter dem Hostnamen der VM und verlinkt auf die Gerätedetails des Hypervisors. Die Zuordnung gilt, solange der verknüpfte Host im Bestand ist und sich als Hypervisor meldet. Eine VM mit gemeldetem Hersteller Hetzner erhält bei fehlendem konkreten Host den Anzeigeplatzhalter „Hetzner Cloud“. Der Platzhalter hat keine Kopplung und zählt nicht als registriertes Gerät. +Ein aufgenommener Proxmox-VE-Host meldet über einen vom Installer eingerichteten, nur lesenden API-Token (`PVEAuditor`) die Gäste seines Nodes, die geplanten vzdump-Backupjobs und die Läufe der letzten acht Tage. Die Gerätedetails des Hosts listen VMs und Container mit Status, Ressourcen, zugeordnetem Gerät und letzter erfolgreicher Sicherung. Darunter folgen die Backupjobs mit Zeitplan, Storage, gesicherten Gästen, letztem fälligen Zeitpunkt, Ergebnis und nächstem Lauf sowie die Gäste ohne Backupjob. Der Server bewertet jeden aktiven Job als gelaufen, fehlgeschlagen, verpasst, laufend oder noch nicht fällig. Er beantwortet damit, ob alle geplanten Backups gelaufen sind. Ein virtuelles Gerät, dessen MAC-Adresse eindeutig in der Gastliste eines Proxmox-Hosts desselben Kunden steht, wird diesem Host automatisch als Hypervisor zugeordnet und so gekennzeichnet. Eine manuelle Zuordnung hat Vorrang und lässt sich wieder an die automatische Erkennung zurückgeben. [Proxmox-Host](deploy/proxmox/README.md) + Ab Windows-Client `0.1.27` zeigt die Spalte **Speicher belegt / gesamt** jedes lokale Festplattenvolume mit Laufwerksbuchstaben separat an, das Systemlaufwerk zuerst. Ein Laufwerk mit unbekannter Kapazität behält seinen Buchstaben ohne Belegungsbalken. Die Zuordnung erfolgt pro logischem Volume, nicht pro physischem Datenträger. Netzlaufwerke, optische Medien und Volumes ohne Laufwerksbuchstaben gehören nicht zu dieser Liste. Bei älteren Inventarmeldungen bleibt die vorhandene Systemlaufwerkskapazität sichtbar. Unter Linux zeigt die Übersicht die vom Kernel erkannten ganzen Festplatten bzw. virtuellen Gastplatten mit Gerätename, Modell (falls verfügbar) und Rohkapazität. Für direkt zuordenbare lokale Dateisysteme zählt sie belegte und für Anwendungen verfügbare Bytes über alle Partitionen, dasselbe Dateisystem nur einmal. Rot bezeichnet nachgewiesene Belegung, Grün verfügbaren Dateisystemplatz und Grau den Rest, einschließlich Reserven, unpartitioniertem Platz und nicht messbarer Belegung. Ein vollständig unbekannter Wert ist kein Nullwert. Bei gestapelten Blockgeräten und plattenübergreifenden Dateisystemen erscheint die logische Belegung separat mit den ermittelbaren Mitgliedern; sie wird nicht auf physische Platten verteilt. ZFS meldet die gemeinsame Belegung des Pools bei lesbaren ZFS-Eigenschaften, nicht die Summe der freien Bytes seiner Datasets. Alte Clients weisen den Wert für `/` als Root-Dateisystem aus. diff --git a/deploy/proxmox/README.md b/deploy/proxmox/README.md new file mode 100644 index 0000000..7b9c6bd --- /dev/null +++ b/deploy/proxmox/README.md @@ -0,0 +1,45 @@ +# Proxmox-VE-Host + +Ein Proxmox-VE-Host ist ein Debian-System. Er verwendet deshalb den regulären Linux-Agenten, seinen Helper und seinen Updater. Zusätzlich liest der Agent über die lokale Proxmox-API die gehosteten Gäste, die geplanten Backupjobs und die Ergebnisse der letzten vzdump-Läufe. Er meldet sie als Inventarbereich `linux.proxmox`. Die WebUI zeigt diese Daten in den Gerätedetails des Hosts. Der Agent ordnet die gemeldeten VMs automatisch dem Host zu. [Sammelmodul](../../crates/agent-linux/src/inventory/proxmox.rs) · [API-Zugriff](../../crates/agent/src/proxmox_api.rs) + +## Aufnahme + +Für die Aufnahme den gemeinsamen [HTTPS-Installer](../../docs/development.md#linux-gerät-per-https-aufnehmen) als `root` auf dem Proxmox-Host ausführen. Der Installer erkennt Proxmox VE an `pveversion` und `pveum` und richtet einen nur lesenden Zugang ein: + +- Proxmox-Benutzer `rmm-discovery@pve` und das privilegiengetrennte API-Token `rmm-discovery@pve!inventory`. Beide erhalten auf `/` ausschließlich die Rolle `PVEAuditor`. Bei einem privilegiengetrennten Token gilt die Schnittmenge aus Benutzer- und Tokenrechten. Deshalb braucht auch der Benutzer die Rolle. +- Den Tokenwert schreibt er nach `/opt/rust-discovery-client/proxmox-token` (Eigentümer root, Modus 0600). Die Cluster-CA landet als `/opt/rust-discovery-client/pve-ca.pem`. +- Das systemd-Drop-in `rmm-discovery-agent.service.d/41-proxmox-api.conf` übergibt den Token mit `LoadCredential=rmm-proxmox-token` an den Dienst und setzt `RMM_PROXMOX_CA_FILE`. + +Der Agent läuft weiter unprivilegiert als `rmm-discovery`. Er verbindet sich nur mit `https://127.0.0.1:8006` und prüft das Zertifikat ausschließlich gegen die kopierte Cluster-CA. Token und Tokenwert erscheinen weder im Inventar noch im Log. Bei einer erneuten Installation bleiben ein vorhandener Token und die Geräteidentität erhalten. Fehlt die lokale Kopie, erzeugt der Installer das Token neu, weil Proxmox den Wert nur bei der Erstellung ausgibt. + +## Gemeldete Daten + +- **Gäste des lokalen Nodes:** VMID, Name, VM oder Container, Status, Vorlage, vCPU, RAM, Disk, Pool, MAC-Adressen der `netN`-Schnittstellen und für QEMU die SMBIOS-UUID. Höchstens 512 Gäste. Gäste auf anderen Cluster-Nodes meldet der Agent des jeweiligen Nodes. +- **Backupjobs** aus `/cluster/backup`: Zeitplan, Storage, Modus, Auswahl (alle, Pool oder VMIDs, abzüglich Ausnahmen) und die danach gesicherten lokalen Gäste. Den letzten fälligen Zeitpunkt berechnet der Proxmox-Scheduler selbst über `/cluster/jobs/schedule-analyze`. +- **vzdump-Läufe** der letzten acht Tage (höchstens 64) mit Start, Ende und Gesamtstatus. Das Ergebnis je Gast stammt aus den Zeilen `Finished Backup of VM` bzw. `Backup of VM … failed` des Tasklogs. +- **Gäste ohne Backupjob** aus `/cluster/backup-info/not-backed-up`. + +Der Server bewertet jeden aktiven Job: **Gelaufen**, wenn jeder gesicherte Gast seit dem letzten fälligen Zeitpunkt (zwei Minuten Toleranz) erfolgreich gesichert wurde. **Fehlgeschlagen** bei einem gemeldeten Fehler, **Verpasst** ohne Lauf, **Läuft** bei aktivem vzdump. Ein Job, der in den letzten acht Tagen noch nicht fällig war, gilt als **Noch nicht fällig**. „Alle geplanten Backups sind gelaufen“ steht nur, wenn kein aktiver Job fehlgeschlagen oder verpasst ist. [Bewertung](../../crates/domain/src/inventory_document/proxmox.rs) + +## Zuordnung der VMs + +Nach jeder Linux- oder Windows-Inventarmeldung vergleicht der Server die MAC-Adressen der aktuellen Proxmox-Gastlisten mit den Netzwerkkarten der aktuellen virtuellen Geräte desselben Kunden. Bei einem eindeutigen Treffer trägt er den Proxmox-Host als Hypervisor ein (`hypervisor_source = proxmox`) und auditiert `device_hypervisor_detected`. Eine MAC, die mehrere Geräte oder mehrere Hosts melden, führt zu keiner Zuordnung. Verschwindet der Gast aus der gültigen Gastliste seines Hosts, wird die automatische Zuordnung gelöst. Eine manuelle Auswahl unter **Gerät verwalten → Hypervisor zuordnen** hat Vorrang. Die Option **Automatisch (Proxmox-Gastliste)** gibt die Entscheidung an die Erkennung zurück. [Abgleich](../../crates/server/src/proxmox_links.sql) + +## Diagnose + +| Anzeige im Gerätedetail | Ursache | +| --- | --- | +| „kein Lesezugang eingerichtet“ (`PROXMOX_NOT_CONFIGURED`) | Credential fehlt. HTTPS-Installer erneut als root ausführen und den Agentdienst neu starten. | +| `PROXMOX_TOKEN_REJECTED` | Token gelöscht oder abgelaufen. `/opt/rust-discovery-client/proxmox-token` entfernen und den Installer erneut ausführen. | +| `PROXMOX_PERMISSION_DENIED` | Der Benutzer oder das Token hat keine Rolle `PVEAuditor` auf `/`. | +| `PROXMOX_CA_UNAVAILABLE`, `PROXMOX_UNREACHABLE` | CA-Kopie fehlt bzw. `pveproxy` ist auf Port 8006 nicht erreichbar. | + +Zum Widerrufen `pveum user token remove rmm-discovery@pve inventory` ausführen. Die übrige Inventur läuft dann weiter, der Proxmox-Bereich meldet einen Fehler. + +## Testhost auf dem Entwicklungsnotebook + +VM `proxmox` auf `qemu:///system`: 4 vCPU (`host-passthrough`, verschachtelte Virtualisierung), 4 GiB RAM, 64 GiB qcow2 im Pool `default`, Netz `default` mit fester DHCP-Reservierung `192.168.122.50` (MAC `52:54:00:50:7e:01`). Basis ist das offizielle `proxmox-ve_9.2-1.iso` (SHA-256 `4e88fe416df9b527624a175f24c9aa07c714d3332afb1ee3dbf3879573ef2c6c`). Die Installation erfolgte unbeaufsichtigt mit dem `proxmox-auto-install-assistant` aus dem Proxmox-Repository. Die Paketquelle ist `pve-no-subscription`. FQDN `pve.discovery.lan`, WebUI `https://192.168.122.50:8006`. + +Testobjekte: VM 100 `debian-guest` (Debian-13-Cloud-Image, 1 GiB, cloud-init) und Container 101 `alpine-ct` (Alpine 3.24, ohne Backupjob). Der Backupjob `backup-debian` sichert VM 100 alle zwei Stunden (`*/2:00`) nach `local`. + +SSH-Zugang, Root-Passwort und Hostpin liegen im privaten Zugangsverzeichnis (`proxmox-vm.conf`, `proxmox-dev-key`, `proxmox-dev-root`, `proxmox-dev.known_hosts`). `tools/dev_stage.py proxmox …` verwendet diese Dateien. Start bei Bedarf: `virsh -c qemu:///system start proxmox`. diff --git a/docs/handover.md b/docs/handover.md index 4371963..933aea8 100644 --- a/docs/handover.md +++ b/docs/handover.md @@ -12,6 +12,7 @@ | MCP und Administrator-Skripte | [Werkzeuge](../crates/server/src/mcp.rs), [Tokenrechte](../crates/server/src/mcp_tokens.rs), [Helper und zentrale Geräteregel](../crates/server/src/managed_scripts.rs) | | Geräteaufnahme und Releasewechsel | [HTTPS-Installer und Lebenszyklus](../crates/server/src/bootstrap), [Releasekatalog](../crates/server/src/agent_updates.rs), [Signaturprüfung](../crates/updater/src/manifest.rs) | | Native Laufzeiten | [Linux-Agent](../crates/agent/src/main.rs), [Linux-Inventar und Skripte](../crates/agent-linux/src), [Windows-Agent](../crates/agent-windows/src/runtime.rs), [Agentprotokoll](../proto/BACKEND_CONTRACT.md) | +| Proxmox-Host und VM-Zuordnung | [Sammelmodul](../crates/agent-linux/src/inventory/proxmox.rs), [Validierung und Backupbewertung](../crates/domain/src/inventory_document/proxmox.rs), [automatische Zuordnung](../crates/server/src/proxmox_links.sql), [Detailansicht](../web/src/proxmox.tsx), [Betrieb](../deploy/proxmox/README.md) | ## Einen vorhandenen Auftrag nachvollziehen diff --git a/docs/operations-access.md b/docs/operations-access.md index bfe9b51..e779d45 100644 --- a/docs/operations-access.md +++ b/docs/operations-access.md @@ -11,6 +11,7 @@ Die Werkzeuge werden im Repository als Eigentümer der lokalen Entwicklungsprofi | `server` | Dedizierter ARM64-Host `discovery.ease-technologies.de` | `server.conf`, vorhandener SSH-Schlüssel und geprüfter Hostkey | | `linux` | Cloud-Linux-Gast `dev-znuny-db` | `linux-vm.conf`, vorhandener SSH-Schlüssel und geprüfter Hostkey | | `windows` | Windows-11-Gast `discwindowstest` | `windows-dev-access.json`, `windows-dev.known_hosts`, Alias `rmm-windows-dev` und SSH-Rückkanal über den Server | +| `proxmox` | Lokale Proxmox-VE-9.2-VM `pve.discovery.lan` (`192.168.122.50`) auf dem Notebook | `proxmox-vm.conf`, eigener Schlüssel `proxmox-dev-key`, Hostpin `proxmox-dev.known_hosts` (beim ersten Start im NAT-Netz `default` der frisch installierten VM erfasst) | Der folgende Befehl liest vom Wurzelverzeichnis des Worktrees aus den Hostnamen der Linux-Test-VM. @@ -23,7 +24,7 @@ subprocess.run([*ssh_prefix("linux"), "hostname"], check=True, timeout=20) PY ``` -`ssh_prefix` verwendet Batchbetrieb, bestehende Schlüssel und strikte Hostprüfung. Die Hostpins für Server und Linux stehen im vorhandenen SSH-Truststore des Benutzers (`~/.ssh/known_hosts`). Windows verwendet die oben genannte separate Hostpindatei. Für Windows wird der geprüfte Proxyweg mit dem gespeicherten Profil abgeglichen. Vor Änderungen an einem Pin den neuen Fingerabdruck unabhängig mit dem Zieladministrator bestätigen. [SSH-Auflösung und Staging](../tools/dev_stage.py) +`ssh_prefix` verwendet Batchbetrieb, bestehende Schlüssel und strikte Hostprüfung. Die Hostpins für Server und Linux stehen im vorhandenen SSH-Truststore des Benutzers (`~/.ssh/known_hosts`). Windows und Proxmox verwenden die oben genannten separaten Hostpindateien. [Proxmox-Testhost](../deploy/proxmox/README.md#testhost-auf-dem-entwicklungsnotebook) Für Windows wird der geprüfte Proxyweg mit dem gespeicherten Profil abgeglichen. Vor Änderungen an einem Pin den neuen Fingerabdruck unabhängig mit dem Zieladministrator bestätigen. [SSH-Auflösung und Staging](../tools/dev_stage.py) ## Interne Test-WebUI diff --git a/tools/dev_stage.py b/tools/dev_stage.py index 110653e..8f75792 100644 --- a/tools/dev_stage.py +++ b/tools/dev_stage.py @@ -30,12 +30,17 @@ def credentials_directory(): def ssh_prefix(target): credentials = credentials_directory() - config = load_config(credentials / ("linux-vm.conf" if target == "linux" else "server.conf")) + profile = {"linux": "linux-vm.conf", "proxmox": "proxmox-vm.conf"}.get(target, "server.conf") + config = load_config(credentials / profile) host = config["username"] + "@" + config["address"] key = str(Path(config["ssh_key_path"]).expanduser()) base = ["ssh", "-F", "/dev/null", "-T"] direct = [*base, "-p", config.get("port", "22"), "-i", key, "-o", "StrictHostKeyChecking=yes", "-o", "BatchMode=yes", "-o", "ForwardAgent=no", "-o", "IdentitiesOnly=yes"] + if target == "proxmox": + # Local test host: its own pin file, not the user's global known_hosts. + return [*direct, "-o", "UserKnownHostsFile=" + str(credentials / "proxmox-dev.known_hosts"), + "-o", "GlobalKnownHostsFile=/dev/null", "-o", "ConnectTimeout=10", host] if target != "windows": return [*direct, "-o", "ConnectTimeout=10", host] # Match the pinned access registered by deploy/windows/prepare_dev_access.py. @@ -154,7 +159,7 @@ def main(): "Ziel: rmm-dev-stage// im SSH-Benutzerprofil. " "Identische Dateien werden wiederverwendet. Dienste und Releases werden separat aktiviert.")) parser.add_argument("--plan", action="store_true", help="Nur lokale Hashes und Zielpfade anzeigen") - parser.add_argument("target", choices=("server", "linux", "windows"), help="Entwicklungsziel") + parser.add_argument("target", choices=("server", "linux", "windows", "proxmox"), help="Entwicklungsziel") parser.add_argument("files", nargs="+", type=Path, metavar="DATEI", help="Vorhandene lokale Artefakte") args = parser.parse_args() for path in args.files: