Proxmox Permissions
PegaProx talks to your Proxmox VE cluster over its API, and to the nodes over SSH for the features that need a shell. There are two ways to connect a cluster:
- An account or API token of its own with a least-privilege role. The role holds only what PegaProx uses over the API, and PegaProx builds the commands for you. It narrows the API only: the features that need a shell still log in to the nodes over SSH as root or as a user with
sudo(see below). - The simple way:
root@pamwith its password. Everything works, nothing to set up.
Least-privilege role for the API
New in 1.4.0
The role ready to copy, in Add Cluster and in Check connection, comes with 1.4.0. On 1.3.0, create the role by hand from the privileges below.
PegaProx shows the role ready to copy in two places:
- Settings → Clusters → Add Cluster, Proxmox VE tab: Least-privilege role for the API (account or token)
- Check connection of a cluster: Least-privilege role for PegaProx
Pick your Proxmox VE release (8 or 9), API token or account, and the optional features you want. Run the commands as root on one node of the cluster.
Always in the role
These are the features that only use the Proxmox API:
| Feature | Privileges |
|---|---|
| Node and cluster status | Sys.Audit |
| Guest list | VM.Audit |
| Start, stop and reboot | VM.PowerMgmt |
| Migration, load balancing, maintenance mode | VM.Migrate |
| Consoles | VM.Console |
| Snapshots | VM.Snapshot, VM.Snapshot.Rollback |
| Backups | VM.Backup |
| Creating and deleting guests | VM.Allocate |
| Cloning and templates | VM.Clone |
| Hardware changes | VM.Config.CPU, VM.Config.Memory, VM.Config.Disk, VM.Config.Network, VM.Config.Options, VM.Config.CDROM, VM.Config.HWType, VM.Config.Cloudinit |
| Guest agent data (IP addresses) | VM.GuestAgent.Audit (PVE 9), VM.Monitor (PVE 8) |
| Storage view | Datastore.Audit |
| Adding and moving disks | Datastore.AllocateSpace |
| Guest network cards on bridges and vnets | SDN.Use |
| Resource pools and pool-based access | Pool.Audit |
Optional features
Each one adds to the role:
| Feature | Privileges |
|---|---|
| ISO and template uploads | Datastore.AllocateTemplate |
| Node network and settings, apt refresh | Sys.Modify |
| Node reboot and shutdown | Sys.PowerMgmt |
| Node syslog | Sys.Syslog |
| SDN view | SDN.Audit |
| Resource mappings (PCI, USB, directories) | Mapping.Audit, Mapping.Use |
| Storage replication jobs | VM.Replicate |
| Proxmox HA resources and rules | Sys.Console |
With an API token
For PVE 9 with every optional feature:
pveum role add PegaProx --privs "Sys.Audit,VM.Audit,VM.PowerMgmt,VM.Migrate,VM.Console,VM.Snapshot,VM.Snapshot.Rollback,VM.Backup,VM.Allocate,VM.Clone,VM.Config.CPU,VM.Config.Memory,VM.Config.Disk,VM.Config.Network,VM.Config.Options,VM.Config.CDROM,VM.Config.HWType,VM.Config.Cloudinit,VM.GuestAgent.Audit,Datastore.Audit,Datastore.AllocateSpace,Datastore.AllocateTemplate,VM.Replicate,SDN.Use,Pool.Audit,Mapping.Audit,Mapping.Use,Sys.PowerMgmt,Sys.Modify,Sys.Syslog,Sys.Console,SDN.Audit"
pveum user add pegaprox@pve --comment "PegaProx"
pveum aclmod / --users pegaprox@pve --roles PegaProx
pveum user token add pegaprox@pve pegaprox --privsep 1 --comment "PegaProx"
pveum aclmod / --tokens 'pegaprox@pve!pegaprox' --roles PegaProx
The token keeps privilege separation: it can do what both the user and its own ACL allow, so both get the role. pveum user token add prints the secret once.
In PegaProx: Add Cluster, user name pegaprox@pve!pegaprox, password the token secret.
On PVE 8 write VM.Monitor instead of VM.GuestAgent.Audit. If the role exists already, pveum role modify PegaProx --privs "..." sets the new list.
With an account and password
pveum role add PegaProx --privs "..."
pveum user add pegaprox@pve --comment "PegaProx"
pveum passwd pegaprox@pve
pveum aclmod / --users pegaprox@pve --roles PegaProx
In PegaProx: Add Cluster, user name pegaprox@pve and the password you set. PegaProx creates an API token of its own at the first login and keeps the password for what a token cannot do.
What no role can give
- SSH to the nodes: node shell, rolling updates, SMBIOS auto configuration, custom node scripts, hardening and CVE checks, the self-fence agents of the 2-node HA, the transfer network check, file restore into containers and ESXi migration. Store an SSH key in the cluster settings (for root, or a user with
sudo), or give single nodes a root password of their own under Node credentials. ESXi migration signs in by password only. - root@pam: raw PCI and USB devices on a VM, most LXC feature flags, creating and removing Ceph OSDs. Proxmox keeps these to
root@pamand refuses them to every API token,root@pam's own included. PegaProx needs theroot@pampassword for them. - A password instead of a token typed in as user name: the text terminal of guests (xterm.js), and cross-cluster migration, replication and Site Recovery into this cluster (PegaProx creates a temporary API token on the target).
SSH as a user other than root
For an SSH user other than root, PegaProx sends each node command as one script and runs it with sudo -n bash. The script comes in on standard input, so its redirects and heredocs run as root as well. sudoers only sees /bin/bash, so a rule that allows it allows everything, the same as:
pegaprox ALL=(root) NOPASSWD: ALL
A sudoers file that lists single commands does not work today: sudo refuses the shell, and the feature fails with a sudo error. -n means sudo must not ask for a password. If root over SSH is not acceptable where you run PegaProx, leave the SSH credentials out. Everything that goes over the API keeps working, and Check connection lists the features that need SSH.
What works with your connection
Check what the connection can do
Check connection on a cluster compares its privileges against what PegaProx needs and lists what is missing, together with the API and fallback hosts, the TLS fingerprint, versions, clock, quorum and SSH. It changes nothing on the cluster.
Below the check, What works with this connection lists every feature that depends on the connection, from consoles to Site Recovery, as available, partly available or not available, and what each one still needs: a privilege on a path, SSH, a password login or root@pam. Showing the list sends nothing to the cluster; Read the privileges asks it once more. The same list is in the cluster's Re-configure dialog.
Using root@pam (the simple way)
root@pam with its password gives PegaProx full access: every feature works, the SSH features included (with the same password, or an SSH key you add). It is the quickest way to get started; for production prefer the least-privilege role above.
- Add Cluster
Enter Credentials
Enter root@pam as username and your Proxmox root password as password.
Connect
Enter your Proxmox host address and port (default: 8006), then save. PegaProx will connect with full permissions.
An API token of root@pam
You can also give PegaProx a token of root@pam:
Open API Token Panel
Proxmox Web UI → Datacenter → Permissions → API Tokens
Create Token
Click Add. Select user (e.g. root@pam), enter Token ID (e.g. pegaprox), uncheck “Privilege Separation” for full access.
Copy Secret
Format: user@realm!tokenid=secret-value. Shown once only.
Add in PegaProx
Settings → Clusters → Add Cluster. Enter root@pam!pegaprox as username, paste secret as password.
Warning: If Privilege Separation is enabled, the token gets its own ACL - you must assign permissions separately in Proxmox.
A token has no shell: the SSH features need an SSH key in the cluster settings, and what Proxmox keeps to root@pam (see above) stays out of reach of every token.
From 1.3, clusters connected with only an API token open VNC consoles, and PCI and USB passthrough work through resource mappings.