Proxmox VE — Integration

This guide describes the steps to integrate OpenVLE with Proxmox VE (PVE), including setting up users, permissions, and API access.

Required Component

Proxmox VE is a core dependency of OpenVLE. Without proper Proxmox configuration, the application will start but all actions involving VMs and VM templates (creating, cloning, starting, stopping, deleting) will fail.

Set Up Proxmox User and Token

To use the Proxmox API, a pool, a user, an API token, roles, and the corresponding permissions must be created.

Create Pool

Create a pool such as OpenVLE-VMs.
This pool will be used for all templates and VMs managed by OpenVLE. Only VMs and templates in this pool are visible to OpenVLE.

CLI command

pvesh create /pools --poolid 'OpenVLE-VMs'

WebGUI

Datacenter -> Permissions -> Pools -> Add

Create User Account

Create a user such as OpenVLE@pve — you can use any username (we use this one as a reference throughout the rest of this guide).
This user will be used for all interactions between OpenVLE and Proxmox. It can be a @pve, @pam, @ldap, or any other account.
Since OpenVLE connects via an API token, the backend realm does not matter.
The account does not need a password (note: accounts without a password can only be created via the PVE CLI, not via the WebGUI).
User attributes such as First name / Last name, Email, and Comment can be set to anything — they are not relevant for OpenVLE's functionality. The user only needs to have the Enabled flag set to true.

CLI command

pvesh create /access/users --userid 'OpenVLE@pve'

WebGUI

Datacenter -> Permissions -> Users -> Add

Generate API Token

Generate an API token for the user you just created.
For the Token ID, you can choose any ID — we use prod01 here.
Set Privilege Separation to true.
Take note of the token details, as they are only displayed once.

Why Privilege Separation?

Without Privilege Separation, an API token automatically inherits all permissions of its user. With Privilege Separation enabled, however, a token only has the permissions that are explicitly assigned to it.

This makes it possible to run multiple OpenVLE instances in isolation with a single Proxmox user: Create a separate API token for each instance (e.g., production, staging, testing) and assign each token only its respective VM pool. This way, a staging instance can only access its own VMs without seeing or affecting the production VMs.

Example: A user OpenVLE@pve with two tokens:

• OpenVLE@pve!prod01 → Pool OpenVLE-Prod (production environment)
• OpenVLE@pve!staging01 → Pool OpenVLE-Staging (test environment)

CLI command

pvesh create /access/users/OpenVLE@pve/token/prod01

WebGUI

Datacenter -> Permissions -> API Tokens -> Add

Create Two Roles on PVE

Since the user and the API token require different permissions on different paths within PVE, two roles must be created.

1. OpenVLE-Infra-General with the following privileges:
   1. Sys.Audit
   2. Sys.Console
2. OpenVLE-Infra-VMs with the following privileges:
   1. VM.Allocate
   2. VM.Audit
   3. VM.Clone
   4. VM.Config.Disk
   5. VM.Config.CDROM
   6. VM.Config.CPU
   7. VM.Config.Memory
   8. VM.Config.Network
   9. VM.Config.HWType
   10. VM.Config.Options
   11. VM.Config.Cloudinit
   12. VM.GuestAudit
   13. VM.Migrate
   14. VM.Monitor
   15. VM.PowerMgmt

Proxmox VE < 9

The VM.GuestAudit privilege only exists from Proxmox VE 9 onwards. If you are using an older version, omit this privilege.

What are these privileges used for?

OpenVLE-Infra-General — Assigned to path / and enables system-wide queries:

Privilege	Usage in OpenVLE
Sys.Audit	Query cluster status and resources, retrieve node statistics, check task status, read HA configuration
Sys.Console	Create, modify, and delete HA configuration for VMs

OpenVLE-Infra-VMs — Assigned to the VM pool and enables the management of VMs and templates:

Privilege	Usage in OpenVLE
VM.Allocate	Create and delete VMs and templates
VM.Audit	Query VM status and configuration, regenerate CloudInit configuration
VM.Clone	Clone VMs and templates
VM.Config.*	Modify VM configuration (Disk, CDROM, CPU, Memory, Network, HWType, Options, Cloudinit)
VM.GuestAudit	Execute guest agent queries and commands (from PVE 9, omit for PVE < 9)
VM.Migrate	Migrate VMs between nodes
VM.Monitor	Read network interfaces (e.g., determine the IPv4 address of a VM)
VM.PowerMgmt	Start, stop, restart, shut down, pause, and resume VMs

CLI command

pvesh create /access/roles --roleid 'OpenVLE-Infra-General' --privs 'Sys.Audit,Sys.Console'
pvesh create /access/roles --roleid 'OpenVLE-Infra-VMs' --privs 'VM.Allocate, VM.Audit, VM.Clone, 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.GuestAudit, VM.Migrate, VM.Monitor, VM.PowerMgmt'

WebGUI

Datacenter -> Permissions -> Roles -> Create

Assign Permissions

All of the following permissions must be assigned to both the user (OpenVLE@pve) and the API token (OpenVLE@pve!prod01). Due to Privilege Separation, Proxmox validates the permissions of both identities independently — if an assignment is missing, API calls will fail.

Assign Corresponding Roles

The previously created roles must be assigned to their respective paths.

1. General System Permissions (OpenVLE-Infra-General)

• Path: /
• Role: OpenVLE-Infra-General
• Propagate: True

This assignment enables system-wide operations: querying cluster status and resources, retrieving node statistics, checking task status, and managing HA configurations.

2. VM Permissions in the Pool (OpenVLE-Infra-VMs)

• Path: /pool/OpenVLE-VMs
• Role: OpenVLE-Infra-VMs
• Propagate: True

This assignment restricts VM management to the previously created pool. OpenVLE can then create, clone, configure, control, and delete VMs and templates within this pool — but cannot affect VMs outside the pool.

Assign Storage and Network Permissions

When cloning VMs, Proxmox requires additional permissions on the storage and network being used. Without these permissions, cloning will fail with a permission error even though the VM permissions are correctly set.

Environment-Specific

The following paths are examples. You must adapt them to the storage and network of your environment.

If your VMs and templates use different storages or networks (e.g., VMs on local-lvm and templates on ceph, or VMs in different VLANs), you must assign the respective permission per storage or network separately. Simply create additional assignments with the same role on the additional paths.

3. Storage Permissions

Create one assignment per storage used:

• Path: /storage/ceph (replace ceph with your storage name)
• Role: PVEDatastoreUser
• Propagate: True

Allows allocating disk images when cloning and creating VMs on the specified storage. If your VMs and templates use multiple storages, repeat this step for each storage (e.g., /storage/local-lvm, /storage/nfs-share).

4. SDN/Network Permissions

Create one assignment per network segment used:

• Path: /sdn/zones/localnetwork/vmbr1/10 (replace with your zone, bridge, and VLAN)
• Role: PVESDNUser
• Propagate: True

Allows assigning network interfaces when cloning and configuring VMs. If VMs are running in different VLANs or bridges, repeat this step for each network segment (e.g., /sdn/zones/localnetwork/vmbr1/20).

CLI Commands and WebGUI

CLI commands (all 4 assignments)

Replace the values for user, API token, pool, storage, and network with your own.

# 1. General system permissions
pvesh set /access/acl --path '/' \
--roles 'OpenVLE-Infra-General' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'

# 2. VM permissions in the pool
pvesh set /access/acl --path '/pool/OpenVLE-VMs' \
--roles 'OpenVLE-Infra-VMs' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'

# 3. Storage permissions
pvesh set /access/acl --path '/storage/ceph' \
--roles 'PVEDatastoreUser' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'

# 4. SDN/network permissions
pvesh set /access/acl --path '/sdn/zones/localnetwork/vmbr1/10' \
--roles 'PVESDNUser' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'

WebGUI

For each of the 4 assignments:

Datacenter -> Permissions -> Add -> User Permission
Datacenter -> Permissions -> Add -> API Token Permission

Select the respective path and role, and set Propagate to True.

API Reference

OpenVLE uses the following Proxmox VE API endpoints. This overview serves as a reference for troubleshooting permission issues. The complete Proxmox API documentation can be found in the PVE API Viewer.

Complete API endpoint overview

Cluster Operations

Endpoints with privilege "None*" do not require an explicit privilege but only return objects that the user or token has access to through other permissions (e.g., Sys.Audit, VM.Audit). The result set is dynamically filtered by Proxmox based on existing permissions.

Endpoint	Method	Required Privilege	Function
/cluster/resources	GET	None*	Query cluster resources and node assignments
/cluster/status	GET	Sys.Audit	Query cluster status
/cluster/nextid	GET	None*	Determine next available VM ID
/cluster/log	GET	None*	Retrieve PVE logs
/cluster/tasks	GET	None*	List current cluster tasks
/nodes	GET	None	List all PVE nodes
/nodes/{node}/rrd	GET	Sys.Audit	Retrieve node statistics

High Availability (HA)

Endpoint	Method	Required Privilege	Function
/cluster/ha/resources	GET	Sys.Audit	List all HA resources
/cluster/ha/resources	POST	Sys.Console	Enable HA for a VM
/cluster/ha/resources/{sid}	GET	Sys.Audit	Query HA status of a VM
/cluster/ha/resources/{sid}	PUT	Sys.Console	Modify HA configuration of a VM
/cluster/ha/resources/{sid}	DELETE	Sys.Console	Disable HA for a VM

VM Management

Endpoint	Method	Required Privilege	Function
/nodes/{node}/qemu/{vmid}/config	GET	VM.Audit	Query VM configuration
/nodes/{node}/qemu/{vmid}/config	PUT	VM.Config.*	Modify VM configuration
/nodes/{node}/qemu/{vmid}/status/current	GET	VM.Audit	Query current VM status
/nodes/{node}/qemu/{vmid}/clone	POST	VM.Clone, VM.Allocate	Clone VM or template
/nodes/{node}/qemu/{vmid}	DELETE	VM.Allocate	Delete VM
/nodes/{node}/qemu/{vmid}/migrate	POST	VM.Migrate	Migrate VM to another node
/nodes/{node}/qemu/{vmid}/cloudinit	PUT	VM.Audit	Regenerate CloudInit configuration
/nodes/{node}/qemu/{vmid}/agent/network-get-interfaces	GET	VM.Monitor	Read network interfaces (IPv4)
/nodes/{node}/tasks/{upid}/status	GET	Sys.Audit	Query task status

VM Control (Power Management)

Endpoint	Method	Required Privilege	Function
/nodes/{node}/qemu/{vmid}/status/{action}	POST	VM.PowerMgmt	Control VM: start, stop, shutdown, reboot, reset, resume, suspend