Skip to content

Proxmox VE Clusters

Configure the Proxmox VE clusters that cv4pve-admin will manage.

When adding a cluster you can specify individual nodes and define their display order in the grid by setting a position for each node — useful to arrange them in a custom order rather than the default alphabetical order.

Sections

  • Cluster list — add / edit / remove clusters, set enabled flag, set node order
  • Web API Access — credentials cv4pve-admin uses to talk to PVE
  • SSH Credentials — credentials cv4pve-admin uses for features that need SSH (snapshot size, …)

Web API Access

Configure the Proxmox VE API credentials used to connect to each cluster.

Show Web API credential fields
Field Description
Access Type Credential (username/password) or API Token
API Token Token in format user@realm!tokenname=secret
Timeout (msec) HTTP request timeout in milliseconds (default: 1000)
Validate Certificate Verify TLS certificate of Proxmox VE nodes

Automatic API Token Creation

Instead of manually creating an API token in Proxmox, use the 🔑 button next to the API Token field to generate one automatically.

A dialog will ask for:

  • Username — a Proxmox user with sufficient privileges (e.g. root@pam)
  • Password — used only during this operation, never stored
  • Token Name — identifier for the token (default: cv4pve-admin)

The following steps are performed automatically on the Proxmox cluster:

  1. Creates a dedicated Proxmox user cv4pve-admin@pve
  2. Assigns the PVEAdmin role on path / (with propagation)
  3. Creates the API token cv4pve-admin@pve!{token-name} with privsep=0 (inherits PVEAdmin role)
  4. Populates the API Token field with the generated value (cv4pve-admin@pve!{token-name}=secret)
  5. Shows a one-time dialog to copy the token — it will not be shown again

The username and password are used only during this wizard and are never saved.

Web API Access Type — feature limitations

Web API access type feature matrix

The choice of Access Type affects which features are available:

Feature Credential (PAM user) Credential (non-PAM) API Token
SSH — Same as WEB API ✅ ❌ PAM only ❌
Node console (NoVnc, Xterm.js) ✅ ❌ PAM only ❌
VM/LXC console (NoVnc, Xterm.js, Spice) ✅ ✅ ❌

Why PAM for node console and SSH Same as Web API?

Node consoles (NoVnc, Xterm.js) and SSH require OS-level credentials — i.e. a Linux system user. Only PAM users (@pam realm, or username without realm) map to actual Linux users on the Proxmox nodes. Users from other realms (PVE, LDAP, etc.) exist only in Proxmox's internal database and have no corresponding SSH/OS account.

Why not API Token for console?

Proxmox VE requires an active user session (ticket) to open a VM or node console via NoVnc/Xterm.js/Spice. API Tokens do not create a session ticket, so console access is not possible when using API Token authentication.

SSH Configuration

Several features require SSH access to the Proxmox VE nodes, including snapshot size calculation, node configuration backup (Node Protect) and parallel update scans (Update Manager).

SSH is configured per-cluster under Proxmox VE Clusters → SSH Credentials.

Show SSH credential fields
Field Description
Auth Method None, Password, Private Key, or Same as WEB API
Username SSH user (typically root)
Password Used when Auth Method is Password
Private Key PEM/OpenSSH private key content
Passphrase Optional passphrase for private key
Timeout (msec) Connection timeout in milliseconds (default: 5000)

SSH Auth Methods

Method Description
None SSH disabled — features requiring SSH will be skipped
Password Authenticate with username and password
Private Key Authenticate with a private key (recommended)
Same as WEB API Reuse WEB API credentials (username without @realm, same password)

Same as WEB API — PAM users only

The Same as WEB API method is only valid for PAM users (e.g. root@pam). Users authenticated via other realms (PVE, LDAP, etc.) do not have corresponding SSH credentials. If the WEB API user is not a PAM user, a warning will be shown and SSH will not work.

Use Private Key

Use Private Key authentication for better security. You can upload the key file directly from the UI.

Timeout scope

The SSH timeout applies only to the connection phase (handshake), not to command execution duration.

Use the Test SSH button to verify connectivity to all nodes before saving.