Proxmox User Permissions and Roles Guide

Understanding Proxmox Access Control

Proxmox VE uses a role-based access control (RBAC) system that determines what each user can see and do. The system consists of four core components: users (and API tokens), roles (sets of privileges), paths (objects in the resource tree), and ACLs (rules that bind users to roles on specific paths). Understanding how these pieces fit together is essential for running a secure multi-user environment.

The default installation has a single root@pam user with full administrative privileges. Running everything as root is convenient for a homelab with one administrator, but it becomes a liability when multiple people need access or when you integrate automation through the API.

Users and Realms

Every Proxmox user belongs to a realm, which determines how authentication is handled. The two built-in realms are pam (Linux system users) and pve (Proxmox's own authentication database).

# Create a user in the Proxmox authentication realm
pveum user add john@pve --password "securepassword" \
    --firstname John --lastname Smith \
    --email john@example.com \
    --comment "VM administrator"

# Create a user in the PAM realm (must also exist as a Linux user)
useradd -m sarah
pveum user add sarah@pam --comment "Backup operator"

# List all users
pveum user list

# Modify a user
pveum user modify john@pve --email newemail@example.com

# Disable a user without deleting them
pveum user modify john@pve --enable 0

# Delete a user
pveum user delete john@pve

Roles and Privileges

A role is a named collection of privileges. Proxmox includes several built-in roles, and you can create custom ones. Each privilege controls a specific action, such as VM.PowerMgmt (start/stop VMs) or Datastore.AllocateSpace (create disks).

# List all available roles
pveum role list

# View privileges in a specific role
pveum role list --output-format json | python3 -m json.tool

# Create a custom role for VM operators (can use VMs but not modify config)
pveum role add VMOperator --privs "VM.PowerMgmt,VM.Console,VM.Monitor,VM.Audit"

# Create a role for read-only monitoring
pveum role add Auditor --privs "VM.Audit,Datastore.Audit,Sys.Audit,SDN.Audit"

# Modify a role to add privileges
pveum role modify VMOperator --privs "VM.PowerMgmt,VM.Console,VM.Monitor,VM.Audit,VM.Snapshot,VM.Snapshot.Rollback"

# Delete a custom role
pveum role delete VMOperator

Key built-in roles to know:

• Administrator – all privileges, equivalent to root.
• PVEAdmin – nearly all privileges except some system-level operations.
• PVEVMAdmin – full VM management but no node or storage admin.
• PVEVMUser – basic VM usage: power management, console, backup.
• PVEAuditor – read-only access to configuration and status.
• NoAccess – explicitly deny all access (useful for overriding inherited permissions).

Groups

Groups simplify permission management by letting you assign roles to a group rather than individual users. When you add a user to a group, they inherit all ACLs assigned to that group.

# Create groups for different teams
pveum group add admins --comment "Infrastructure administrators"
pveum group add developers --comment "Development team"
pveum group add monitoring --comment "Monitoring and auditing"

# Add users to groups
pveum user modify john@pve --groups admins
pveum user modify sarah@pam --groups monitoring
pveum user modify dev1@pve --groups developers

# List groups
pveum group list

ACLs: Binding It All Together

Access Control Lists (ACLs) tie users or groups to roles at specific paths in the resource tree. The path determines what objects the permissions apply to.

# Grant the admins group full admin access to everything
pveum acl modify / --roles Administrator --groups admins

# Give the developers group VM admin access only to a specific VM
pveum acl modify /vms/101 --roles PVEVMAdmin --groups developers

# Give a user VM user access to a pool of VMs
pveum acl modify /pool/devpool --roles PVEVMUser --users dev1@pve

# Grant read-only access to the entire cluster for monitoring
pveum acl modify / --roles PVEAuditor --groups monitoring

# Remove an ACL entry
pveum acl delete / --roles Administrator --groups admins

# List all ACLs
pveum acl list

Common path patterns:

• / – entire cluster (all objects).
• /vms/<vmid> – a specific VM or container.
• /storage/<storageid> – a specific storage.
• /pool/<poolname> – a resource pool and all its members.
• /nodes/<nodename> – a specific cluster node.

Pools

Pools group VMs and storage together so you can assign permissions to a logical set of resources rather than individual objects. This is ideal for multi-tenant environments or team-based access.

# Create a pool for the development team
pveum pool add devpool --comment "Development VMs and storage"

# Add VMs and storage to the pool
pveum pool modify devpool --vms 101,102,103
pveum pool modify devpool --storage local-lvm

# Grant the developers group access to the pool
pveum acl modify /pool/devpool --roles PVEVMAdmin --groups developers

# List pools
pveum pool list

API Tokens

API tokens provide authentication for automated scripts and third-party tools without using a user's password. Each token is tied to a user and can optionally have its own restricted permissions.

# Create an API token for a user
pveum user token add john@pve automation \
    --comment "CI/CD pipeline token" \
    --privsep 1

# The output includes the token secret - save it immediately
# Format: john@pve!automation=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# If privsep=1, the token needs its own ACLs (separate from the user)
pveum acl modify /vms/101 --roles PVEVMAdmin --tokens john@pve!automation

# If privsep=0, the token inherits the user's permissions

# List tokens for a user
pveum user token list john@pve

# Remove a token
pveum user token remove john@pve automation

Practical Example: Least Privilege Setup

Here is a complete example setting up access for a small team following the principle of least privilege:

# Create users
pveum user add admin1@pve --password "strongpass1" --comment "Senior admin"
pveum user add dev1@pve --password "strongpass2" --comment "Developer"
pveum user add monitor1@pve --password "strongpass3" --comment "Monitoring"

# Create groups
pveum group add sysadmins --comment "System administrators"
pveum group add devteam --comment "Development team"

# Assign users to groups
pveum user modify admin1@pve --groups sysadmins
pveum user modify dev1@pve --groups devteam

# Create a pool for dev resources
pveum pool add dev-resources --comment "Development VMs"
pveum pool modify dev-resources --vms 200,201,202

# Set permissions
pveum acl modify / --roles PVEAdmin --groups sysadmins
pveum acl modify /pool/dev-resources --roles PVEVMUser --groups devteam
pveum acl modify / --roles PVEAuditor --users monitor1@pve

# Create an API token for monitoring
pveum user token add monitor1@pve grafana --privsep 0 \
    --comment "Grafana dashboard"

Managing Permissions Remotely

When managing a multi-user Proxmox environment, you may need to quickly verify or adjust permissions outside of normal working hours. ProxmoxR provides a convenient way to check on your Proxmox cluster from your phone, letting you review node and VM status when you cannot reach a desktop. This is particularly useful for verifying that permission changes have not disrupted any running workloads.

Best Practices

• Never share the root@pam account. Create individual user accounts for each person who needs access.
• Use groups for permission assignment. Assigning roles to groups instead of individual users makes it easier to manage permissions as team membership changes.
• Apply the principle of least privilege. Start with minimal permissions and add more only when needed. Use the PVEAuditor role as a baseline for users who only need to view status.
• Use API tokens with privilege separation. Set privsep=1 so tokens have only the permissions explicitly granted to them, not the full permissions of the parent user.
• Use pools for multi-tenant setups. Pools let you grant access to a set of resources without granting access to the entire cluster.
• Audit permissions regularly. Run pveum acl list periodically to review who has access to what.

Summary

Proxmox VE's permission system is flexible enough to handle everything from a single-admin homelab to a multi-team enterprise deployment. The key is building on the RBAC model: create users, organize them into groups, define roles with only the necessary privileges, and assign those roles at the most specific path possible. Combined with API tokens for automation and pools for resource grouping, you can implement a least-privilege access model that keeps your infrastructure secure without creating administrative overhead.