feat(server): Verbindungstest mit Fähigkeitserkennung

Der Test liest Version, Cluster, Nodes, Storages, Bridges, VNets und die
effektiven Rechte des Tokens und leitet daraus ab, welcher Vorgang per
API, per SSH oder gar nicht geht – je PVE-Version: Template-Bau per API
erst ab 8.4 mit import-Storage, Snippets und LXC-Exec nur per SSH.

Fehlende Rechte erscheinen einzeln mit Pfad und Zweck; die Rollenliste
in docs/proxmox-rechte.md prüft ein Test gegen den Code. SSH-Host-Keys
werden wie Zertifikate erst nach Bestätigung genutzt, und bestätigt
werden kann nur ein Schlüssel, den der letzte Test gesehen hat.

Statussymbole in der GUI sind jetzt gezeichnet: ◐ und ○ fehlen im
Web-Subset von JetBrains Mono.

Refs #003

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-12 09:44:27 +02:00
co-authored by Claude Opus 5.5
parent 48e2a5cb8f
commit 86b650e20a
26 changed files with 2094 additions and 18 deletions
+94
View File
@@ -0,0 +1,94 @@
# Proxmox-Rechte für das API-Token
ProxDeploy braucht auf jedem Proxmox-Server ein API-Token. Es sollte **nicht** `root@pam` gehören,
sondern einem eigenen Benutzer mit einer eigenen Rolle `ProxDeploy`, die nur das Nötige erlaubt.
Der Verbindungstest in ProxDeploy vergleicht die tatsächlichen Rechte mit dieser Liste und nennt
fehlende Rechte einzeln, mit Pfad und Zweck.
## Rolle anlegen (PVE 9.x)
Auf einem Node des Clusters als root:
```bash
pveum role add ProxDeploy --privs "VM.Allocate VM.Clone VM.Audit VM.Config.Disk VM.Config.CDROM VM.Config.CPU VM.Config.Memory VM.Config.Network VM.Config.HWType VM.Config.Options VM.Config.Cloudinit VM.PowerMgmt VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit SDN.Use Sys.Audit Sys.AccessNetwork"
```
## Rolle anlegen (PVE 8.x)
```bash
pveum role add ProxDeploy --privs "VM.Allocate VM.Clone VM.Audit VM.Config.Disk VM.Config.CDROM VM.Config.CPU VM.Config.Memory VM.Config.Network VM.Config.HWType VM.Config.Options VM.Config.Cloudinit VM.PowerMgmt VM.Monitor Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit SDN.Use Sys.Audit Sys.AccessNetwork"
```
Vor PVE 8.2 gibt es `Sys.AccessNetwork` noch nicht; dort statt dessen `Sys.Modify` eintragen.
Nach einem Upgrade von 8 auf 9 die Rolle anpassen: `VM.Monitor` gibt es in PVE 9 nicht mehr, der
Guest-Agent hat eigene Rechte bekommen.
```bash
pveum role modify ProxDeploy --privs "…Liste für PVE 9.x…"
```
## Benutzer, Rechte und Token
```bash
pveum user add proxdeploy@pve --comment "ProxDeploy"
pveum acl modify / --users proxdeploy@pve --roles ProxDeploy
pveum user token add proxdeploy@pve deploy --privsep 0
```
Die letzte Zeile gibt das Secret **einmal** aus – zusammen mit der Token-ID
`proxdeploy@pve!deploy` in ProxDeploy unter *Server → Server anlegen* eintragen.
`--privsep 0` lässt das Token die Rechte seines Benutzers erben. Mit Privilege Separation
(`--privsep 1`, Standard in der Oberfläche) braucht das Token die Rolle selbst:
`pveum acl modify / --tokens 'proxdeploy@pve!deploy' --roles ProxDeploy`.
## Enger gefasst
Statt der Rolle auf `/` genügen diese Pfade:
| Pfad | Wofür |
|---|---|
| `/vms` (oder ein Pool `/pool/<name>`) | VMs und Container anlegen, konfigurieren, starten, Guest-Agent |
| `/storage/<id>` je Storage für Gäste und Images | Disks anlegen, Images und LXC-Templates laden |
| `/sdn/zones/localnetwork` (bzw. die genutzten SDN-Zonen) | Bridges und VNets an Gäste hängen |
| `/nodes/<node>` | `Sys.AccessNetwork` für `download-url` |
| `/` | `Sys.Audit` – Cluster-Status und Rechte lesen |
## Wozu welches Recht
| Recht | Wofür |
|---|---|
| `VM.Allocate` | VMs und Container anlegen und (beim Aufräumen) löschen |
| `VM.Clone` | Templates klonen |
| `VM.Audit` | Konfiguration lesen |
| `VM.Config.Disk` | Disks anlegen, importieren, vergrößern |
| `VM.Config.CDROM` | cloud-init-Laufwerk |
| `VM.Config.CPU`, `VM.Config.Memory` | Ressourcen |
| `VM.Config.Network` | Netzwerkkarten |
| `VM.Config.HWType` | Maschinentyp q35, UEFI, SCSI-Controller |
| `VM.Config.Options` | Name, Tags, Guest-Agent, Start bei Boot |
| `VM.Config.Cloudinit` | Benutzer, SSH-Keys, IP-Konfiguration |
| `VM.PowerMgmt` | Starten und Stoppen |
| `VM.GuestAgent.Audit` (9.x) | IP-Adressen über den Guest-Agent |
| `VM.GuestAgent.Unrestricted` (9.x) | Provisionierung über den Guest-Agent (`exec`, `file-write`) |
| `VM.Monitor` (8.x) | Guest-Agent in PVE 8 |
| `Datastore.AllocateSpace` | Disks auf dem Storage |
| `Datastore.AllocateTemplate` | Cloud-Images und LXC-Templates herunterladen |
| `Datastore.Audit` | Storage-Inhalt lesen |
| `SDN.Use` | Bridges und VNets nutzen |
| `Sys.Audit` | Cluster-Status, Rechte |
| `Sys.AccessNetwork` (ab 8.2) | `download-url` |
**Optional:** `Datastore.Allocate` (heruntergeladene Images beim Aufräumen löschen), `SDN.Audit`
(VNets anzeigen), `VM.Console` (Konsole), `Sys.Modify` (privilegierte Container ab PVE 9).
## Was ein Token grundsätzlich nicht kann
Diese Dinge erlaubt Proxmox nur `root@pam` mit Passwort-Anmeldung, nie einem Token. ProxDeploy
erledigt sie deshalb per SSH, wenn SSH für den Server eingerichtet ist:
- Container-Features außer `nesting` (`keyctl`, `fuse`, `mknod`)
- cloud-init-Snippets schreiben (es gibt dafür keine API)
- Befehle in Containern ausführen (`pct exec`; es gibt keine Exec-API für Container)
- Disk-Images von einem absoluten Pfad importieren (vor PVE 8.4 nötig)