Skip to content

Quick Start

Command Line Options

python3 pegaprox_multi_cluster.py [OPTIONS]

Options:
  --debug               Enable debug mode with verbose logging
  --port PORT           Set the server port (default: 5000)
  --host HOST           Set the bind address (default: 0.0.0.0)
  --requirements        Install/update Python dependencies
  --download-static     Download static assets for offline mode
  --help                Show help message

First-Run Setup Wizard

A fresh install has no default credentials. The very first login attempt against an uninitialised system returns NOT_INITIALIZED and the UI redirects to an in-browser setup wizard. Pick an admin username, password (passes through the strength meter), email, and optionally enable 2FA enrolment on first login. Installs upgraded from an earlier version keep their accounts and skip this step.

The wizard opens only on an install that holds no accounts and no configuration. If a restore leaves the clusters but no users behind, it stays closed, so nobody who reaches the port can take over the existing clusters. From 1.3, to reopen it on purpose, create an empty file named reopen_setup in the PegaProx config directory on the server (for example touch /opt/PegaProx/config/reopen_setup, in Docker /app/config/reopen_setup) and refresh the page. PegaProx removes the file once the new administrator exists. Audit-logged under admin.initial_setup.

After the first login PegaProx asks which layout you want: Modern, Corporate Redesigned or Cloud. You can change it later in your profile settings. From 1.5, classic Corporate is deprecated and no longer offered there.

Adding Your First Cluster

  1. Log in to PegaProx with the admin account you created in the setup wizard

  2. Navigate to Settings → Clusters

  3. Click "Add Cluster"

  4. Enter your Proxmox host, port (8006), and credentials

Verify Setup

The dashboard should populate with cluster data within seconds. Check that node count and VM count appear correctly. You can also verify the health endpoint: curl -sk https://localhost:5000/api/health should return {"status": "ok"}.

From 1.3, Check connection on a cluster runs read-only probes and names a fix for each item that fails: the API and fallback hosts, the TLS fingerprint, the token's privileges against what PegaProx needs, versions, clock, quorum and SSH. It needs the cluster.config permission.

Changing a cluster's address later

When you change a cluster's host, port or fallback hosts, or switch its TLS verification off, PegaProx asks for the password or token secret again in the same step (from 1.3). The stored credential is never sent to an address you have not confirmed with it. Renaming a cluster or changing other settings needs no credential.

SSH to the nodes

Features that run commands on the nodes (rolling updates, SMBIOS auto-config, custom scripts, hardening checks, the 2-node HA agents) log in as the user of the cluster login without its realm (root@pam logs in as root). The cluster's SSH key goes first if one is set; otherwise, or when the key is refused, the node gets a password: its own if you gave it one, else the password the cluster was added with. The node shell is different: it asks for its login in its own dialog.

New in 1.4.0

Node credentials, a password of its own per node and the login check after adding a cluster, come with 1.4.0. In 1.3.0 every node gets the password the cluster was added with, or the SSH key.

Nodes with different root passwords. Right-click the cluster, choose Re-configure Cluster and open Node credentials. Every node is listed with the password it gets (the cluster's or its own) and the result of its last login check; set or clear a node's own password there, each node is saved on its own. A node's password is only ever offered to that node's own address, and it is also used when PegaProx has to sign in to the Proxmox API on that node because the cluster's main host is down (for @pam users, whose password is per node). The value is stored encrypted and never shown again.

After you add a cluster, PegaProx tries the login on every node in the background. If a node refuses it, a notice leads you straight to Node credentials. Check connection (same menu) runs the same test at any time and shows which credential each node got.

If you change the cluster's address, SSH port or certificate check later, the node passwords are cleared like the other stored credentials and the notice names the nodes that need theirs again.

Keys instead of passwords. A key works for all nodes at once: put its public key into /root/.ssh/authorized_keys on every node and paste the private key under SSH Key (Optional) in Re-configure Cluster.

Clusters without SSH

Some features use SSH to the nodes (node shell, rolling updates, SMBIOS auto-config, hardening checks). If SSH is not allowed in your environment, switch on No SSH to this cluster in the cluster settings: PegaProx then never opens SSH connections to it and says which features are unavailable instead of trying.

Optional: Set Cluster Location for Worldmap

While editing the cluster, scroll to Location and fill in latitude / longitude / display label. The Worldmap sidebar entry will then pin the cluster on the SVG world map and the dashboard widget will summarise health by region.

Proxmox API User Permissions

Important: We strongly recommend using root@pam. Several PegaProx features (SMBIOS Auto-Config, Rolling Updates, 2-Node HA, Node Shell) require full root access and will not work with limited users.

@pam vs @pve Users

✅ Recommended: @pam Users

@pam users are Linux system users authenticated via PAM (Pluggable Authentication Modules).

  • SSH Access – Required for Node Shell feature
  • System Integration – Real Linux user
  • Full Features – All PegaProx features work

Examples: root@pam, admin@pam

⚠ Not Recommended: @pve Users

@pve users are Proxmox-only users that exist only in the Proxmox user database.

  • ❌ No SSH Access – Node Shell won't work
  • ❌ No System User – Cannot login to Linux
  • ⚠ API Only – Limited to Proxmox API

Examples: apiuser@pve, monitor@pve

Using root@pam is strongly recommended and ensures all features work correctly:

  • Full VM/Container management
  • Live migration (including cross-node)
  • VNC/SPICE console access
  • Node Shell
  • SMBIOS Auto-Config
  • Rolling Updates
  • 2-Node HA
  • All other PegaProx features

This is the simplest and most reliable option.

Username: root@pam
Password: [your root password]

# Or with API token (Not Recommended):
Username: root@pam
API Token ID: root@pam!pegaprox
API Token Secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Users without root access will have limited functionality:

  • ❌ SMBIOS Auto-Config won't work
  • ❌ Rolling Updates won't work
  • ❌ 2-Node HA won't work
  • ❌ Node Shell won't work
  • ⚠ @pve users can't use SSH features

Note: Basic API operations may work, but several important PegaProx features require ssh root access.

API token clusters in 1.3

From 1.3, clusters added with only an API token can open VNC consoles, and PCI and USB passthrough work through the cluster's resource mappings. Features that run commands on the nodes over SSH still need SSH credentials.

Option B: Create a Dedicated @pam User

# On the Proxmox host:
# 1. Create Linux user
useradd -m pegaprox
passwd pegaprox

# 2. Grant sudo access (needed for some features)
echo "pegaprox ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/pegaprox

# 3. Add to Proxmox with Administrator role
pveum useradd pegaprox@pam -comment "PegaProx Service Account"
pveum aclmod / -user pegaprox@pam -role Administrator

# 4. Optional: Create API token
pveum user token add pegaprox@pam pegaprox --privsep=0

Best Practice Summary: Use root@pam for full functionality with ssh. If you must use a dedicated user, use a @pam user (not @pve). API tokens with --privsep=0 inherit the user's full permissions.