Proxmox VE Role-Based Access Control: Users, Groups, Roles, and Permissions Explained

Proxmox VE ships with a single all-powerful root@pam account, and for a homelab that is usually all you ever touch. The moment more than one person needs access — a co-worker who only manages backups, a junior admin who should be able to restart a handful of VMs but not touch storage, or a read-only account for a monitoring dashboard — handing out the root password stops being an option. Proxmox VE's built-in role-based access control (RBAC) system exists exactly for this: it lets you create separate identities and grant each one precisely the privileges it needs, on precisely the objects it needs them for, and nothing else.

This guide walks through how Proxmox VE's permission model actually works — users, groups, roles, privileges, and access control paths — and then builds several real delegation scenarios from scratch using both the web UI and the pveum command-line tool. By the end you'll be able to hand a teammate exactly the access they need without ever sharing the root credentials.

How Proxmox VE Permissions Fit Together

Before creating anything, it helps to understand the four building blocks Proxmox VE combines to decide whether a given account can perform a given action. They are evaluated together every time an API call is made, whether it comes from the web UI, pvesh, or a third-party tool.

1. Users and Realms

A user in Proxmox VE is always written as name@realm. The realm tells Proxmox where to authenticate that account:

• pam — a Linux system account on the host itself (this is what root@pam is). Password changes happen at the OS level.
• pve — an account that exists only inside Proxmox's own user database, with its own password stored and managed by Proxmox VE. This is the realm you'll use for almost every delegated user you create.
• LDAP / Active Directory / OpenID Connect — external directory realms you can add under Datacenter → Realms if you want centralized authentication.

Creating a user only gives them an identity — by itself it grants zero privileges. Permissions are added separately.

2. Groups

Groups are simple containers of users. They don't do anything on their own, but assigning a permission to a group applies it to every member, which makes onboarding and offboarding much less error-prone than managing permissions per individual user.

3. Roles and Privileges

A privilege is a single, granular capability, such as VM.PowerMgmt (start/stop/reset a VM), VM.Console (open the console), Datastore.AllocateSpace, or Sys.Audit. There are well over 100 of these covering every corner of the API.

A role is simply a named bundle of privileges. Proxmox VE ships with a set of built-in roles you'll use constantly:

Role	Typical use
Administrator	Full control, equivalent to root over the assigned path
PVEAdmin	Full VM/CT and storage management, no ability to alter users/permissions or system config
PVEVMAdmin	Full control over specific VMs/CTs (start, stop, snapshot, console, config), no storage/datacenter changes
PVEVMUser	Power management and console access to specific VMs/CTs, no configuration changes
PVEDatastoreAdmin	Full control of a storage/datastore, including allocating space and managing backups on it
PVEDatastoreUser	Allocate space and browse backups on a datastore, without administering it
PVEAuditor	Read-only access — can view configuration and status but change nothing
PVEPoolAdmin	Manage resource pools
PVESysAdmin	System-level administration (network, time, DNS) without VM/storage rights

If none of the built-in roles fit, you can create your own custom role from any combination of individual privileges — this is covered below.

4. Access Control Paths

This is the piece people find least intuitive coming from simpler permission systems: a role assignment is always made against a specific path in Proxmox's object hierarchy, not globally. Paths look like filesystem paths and mirror the resource tree:

• / — the entire Proxmox VE installation (everything)
• /nodes/pve1 — a specific cluster node
• /vms — every VM/CT in the cluster
• /vms/101 — one specific VM or container by ID
• /storage/local-zfs — one specific storage
• /pool/webteam — a resource pool (a named group of VMs/CTs/storages you define yourself)
• /access/groups — user/group/permission management itself

Assigning the PVEVMAdmin role at /vms/101 gives full VM-admin rights to VM 101 only. Assign the same role at / and it applies everywhere. Permissions defined on a parent path are inherited by everything beneath it unless you explicitly stop propagation, which is exactly what makes resource pools so useful — group a set of VMs into one pool and grant access once, at the pool level, instead of once per VM.

Planning Before You Touch the GUI

Three delegation scenarios cover the vast majority of real-world needs, and we'll build all three in this guide:

1. VM Operator — can start, stop, and open the console of a defined set of VMs, but cannot change their configuration, delete them, or touch anything else in the cluster.
2. Read-Only Auditor — can view every node, VM, and storage in the cluster for monitoring/reporting purposes, but cannot change or delete anything.
3. Backup Operator — can run and restore backups on a specific storage, without being able to power-manage VMs or alter the cluster.

Scenario 1: Creating a Restricted VM Operator

Step 1 — Create the user

In the web UI: Datacenter → Permissions → Users → Add. Set:

• User name: jdoe
• Realm: Proxmox VE authentication server (the pve realm)
• Set a password, and optionally an expiration date

Equivalently, from the shell on any cluster node:

pveum user add jdoe@pve --password 'ChangeMe!23' --comment "VM operator - web team"

Step 2 — Group the VMs into a pool

Rather than granting permission on each VM individually, put them in a pool first (Datacenter → Permissions → Pools → Create, or via CLI):

pveum pool add webteam --comment "Web team VMs"
pveum pool modify webteam --vms 101,102,103

Step 3 — Create a group and add the user

pveum group add vm-operators --comment "Can power-manage and console web team VMs"
pveum user modify jdoe@pve --group vm-operators

Step 4 — Assign the role at the pool path

In the GUI: Datacenter → Permissions → Add → Group Permission, set Path to /pool/webteam, Group to vm-operators, Role to PVEVMUser, and leave Propagate checked so the permission flows down to every VM currently in the pool (and any VM you add to it later).

Equivalently:

pveum acl modify /pool/webteam --groups vm-operators --roles PVEVMUser

Log in as jdoe@pve and you'll see only VMs 101–103 in the tree, with Start/Stop/Shutdown/Console available and every configuration tab greyed out. Nodes, storage, and other VMs are entirely invisible to this account — Proxmox VE doesn't just block actions on objects the user can't reach, it hides them from the UI as well.

Scenario 2: A Read-Only Auditor Account

This one is simpler because it applies at the root of the tree. Create the user and assign the built-in PVEAuditor role at /:

pveum user add auditor@pve --password 'ReadOnlyPass!1' --comment "Monitoring / reporting account"
pveum acl modify / --users auditor@pve --roles PVEAuditor

This account can browse every node, VM, container, storage, and cluster log, and it's the identity you'd hand to a Grafana/Zabbix integration or an external auditor who needs visibility without any risk of accidental changes. Because PVEAuditor excludes every write privilege, there is no action this account can take that changes cluster state — it's a safe default for any "just needs to look" use case.

Scenario 3: A Backup-Only Operator

Backup operators need two things: the ability to run/list/restore backup jobs, and access to the storage those backups live on, without touching VM power state or configuration. Proxmox doesn't ship a perfect single built-in role for this, so we'll build a custom one.

Step 1 — Create a custom role

Go to Datacenter → Permissions → Roles → Create, name it BackupOperator, and select these privileges:

• VM.Backup
• Datastore.AllocateSpace
• Datastore.Audit
• VM.Audit

Or from the CLI in one line:

pveum role add BackupOperator -privs "VM.Backup,Datastore.AllocateSpace,Datastore.Audit,VM.Audit"

Step 2 — Assign it on both the VMs and the storage

Backup permission needs to be granted on the VM path (so the account can trigger a backup of that VM) and separately on the storage path (so it can write the backup file):

pveum user add backupbot@pve --password 'BackupBot!42'
pveum acl modify /vms --users backupbot@pve --roles BackupOperator
pveum acl modify /storage/backup-nfs --users backupbot@pve --roles BackupOperator

This account can now run and restore backups cluster-wide against the backup-nfs storage, but has no power over VM start/stop/console and no rights on any other storage in the cluster. This is also a reasonable identity to pair with an API token if you're driving backups from an external scheduler rather than logging in interactively.

Understanding Propagation and Negative Permissions

Two checkboxes on the permission-assignment form change behavior in ways worth understanding before you rely on them:

• Propagate — when checked (the default), the permission is inherited by every object beneath the assigned path. Uncheck it if you want a role to apply only to the exact path and nothing nested under it — useful, for example, if you want someone to see that a storage exists without being able to browse the backups stored on it.
• Negative permission — instead of granting a role, this explicitly revokes it at that path, overriding anything inherited from a parent path. This is how you carve out an exception, such as giving a group admin rights across /vms but then explicitly denying access to one sensitive VM by adding a negative permission at /vms/999.

When a user's effective rights come from multiple sources (their own permissions plus every group they belong to), Proxmox VE combines them additively — except that a negative permission at a more specific path always wins over a positive one inherited from a parent, regardless of which group granted it.

Verifying What a User Can Actually Do

Rather than guessing, you can ask Proxmox directly what the effective permission set is for a given user:

pveum user permissions jdoe@pve

This prints every path the user has access to and the privileges resolved at each one, after propagation and any negative overrides have been applied — the single most useful command for debugging "why can this account do X" or "why can't this account do Y" questions.

To list every role assignment cluster-wide (handy for a periodic access review):

pveum acl list

Troubleshooting Common Permission Problems

"User can log in but sees an empty datacenter tree"

No permission has been assigned to that user or any group they belong to on any path. Run pveum user permissions <user> to confirm — an empty result means the account authenticated successfully but has zero privileges anywhere.

"Permission was granted but the user still can't see a newly added VM"

Check whether the permission was assigned directly to the VM path or inherited via a pool/parent path with Propagate enabled. If the VM was created after the permission was set and it isn't in the pool the permission targets, it won't inherit anything — add it to the pool with pveum pool modify <pool> --vms <vmid>.

"User has PVEVMUser but the Console button is greyed out"

Confirm the role actually includes VM.Console — if you built a custom role and forgot it, the power-management buttons will work but the console will stay disabled. Add the privilege with pveum role modify <role> -privs +VM.Console.

"Changes to permissions don't seem to take effect immediately"

The web UI caches a ticket that includes the user's permission set at login time. Ask the user to log out and back in (or wait for their session ticket to expire, roughly two hours by default) after you change their access.

"pveum acl modify succeeds but nothing changes"

Double-check the path syntax — a trailing slash, a missing leading slash, or a typo in a VM ID will silently create a rule on a path that doesn't match anything real. Run pveum acl list immediately after to confirm the entry looks like you expect.

"A pam realm user can't be restricted the way a pve realm user can"

PAM accounts are real Linux users on the host and their password/existence is managed by the OS, not Proxmox — but the RBAC permissions layered on top work identically for both realms. If you don't need OS-level shell access for that person, create them as a pve realm user instead; it keeps user management entirely inside Proxmox and avoids creating unnecessary Linux accounts on your hosts.

Removing or Downgrading Access

To revoke a specific role assignment without deleting the user:

pveum acl delete /pool/webteam --groups vm-operators --roles PVEVMUser

To disable a user entirely (keeps the account and its history but blocks login):

pveum user modify jdoe@pve --enable 0

To remove the account completely:

pveum user delete jdoe@pve

Disabling rather than deleting is usually the safer choice when someone leaves a team temporarily, since it preserves the audit trail of who the account was and what it had access to.

Frequently Asked Questions

What's the difference between the pam and pve realms for permissions?

None, once the account exists — RBAC works identically regardless of realm. The realm only determines where the username/password is validated: pam checks the host's Linux accounts, pve checks Proxmox's own internal database. For delegated, non-shell accounts, prefer pve so you're not creating Linux logins you don't need.

Is the Administrator role the same as root?

root@pam is always treated as a superuser and bypasses the permission system entirely — it cannot be restricted. Assigning the Administrator role to another account at / gets that account equivalent practical rights, but unlike root it's still a normal, revocable ACL entry and can be scoped to a narrower path if you change your mind later.

Can I sync users from Active Directory or LDAP instead of creating them manually?

Yes — add an LDAP or Active Directory realm under Datacenter → Realms → Add, then use Sync to pull in users and groups. RBAC assignment works the same way afterward: you still grant roles to the synced users or groups on whatever paths make sense.

Can I limit what an account can do even to a role it was granted, without creating a whole new role?

Yes, with a negative permission. Grant the broader role at a parent path, then add a negative permission for that same user/group at the specific child path you want excluded.

Do API tokens inherit a user's permissions automatically?

By default an API token has the same permissions as the user it belongs to, but you can also mark a token as "privilege separated" and assign it a narrower ACL of its own — useful when an automation script should have less access than the human account it's attached to.

What's the minimum role I should give someone who "just needs to restart their own VMs"?

PVEVMUser assigned at the specific VM path (or a pool containing just their VMs) is the closest built-in fit — it includes power management and console access without any configuration or deletion rights.

Closing Thoughts

Proxmox VE's permission model looks like it has a lot of moving parts the first time you open the Permissions tab, but in practice it reduces to one idea: decide the smallest set of privileges an account needs, decide the smallest set of objects it needs them on, and connect the two with a role assignment. Resource pools make the "smallest set of objects" part painless to maintain as your infrastructure grows, and the built-in roles cover the majority of real delegation needs without ever requiring a custom role. Once you've set up even one or two accounts this way, sharing the root password for day-to-day work stops making sense.