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