Proxmox VE Suite for WHMCS

1. Overview & Key Features

Proxmox VE Suite for WHMCS provides hosting providers, cloud operators, and data centers with a turnkey commercial solution to automate Proxmox VE virtualization directly through WHMCS.

2. System Requirements

• WHMCS Version: WHMCS 8.2 through 8.11+
• PHP Version: PHP 8.1 or PHP 8.2 with cURL, OpenSSL, and JSON extensions enabled
• Proxmox VE Version: Proxmox VE 7.x, 8.x, or 9.x Cluster
• Network Ports: HTTPS outbound (port 443) from WHMCS server to Proxmox API (default port 8006 or reverse proxy)
• Licensing: Active Enterprise License Key issued by Nextgen Hosting

3. Installation & Module Activation

whmcs-root/
├── includes/
│   └── hooks/
│       └── pvewhmcs.php          # Sidebar & package lifecycle hooks
├── modules/
│   ├── addons/
│   │   └── pvewhmcs/             # Administrative Management Suite
│   └── servers/
│       └── pvewhmcs/             # Client Provisioning & noVNC Router

4. Commercial Licensing Setup

Proxmox VE Suite features a built-in cryptographic licensing subsystem that binds to your licensed domain and server IP address.

1. Go to Addons > Proxmox VE Suite.
2. Enter the License Key provided in your order email (Format: PVE-XXXX-XXXX-XXXX).
3. Click Activate License. The module will verify cryptographically with Nextgen Hosting licensing servers, cache your local signature (1-day secure cache), and lift the blur overlay.

Need a license? Order your Proxmox VE Suite License here.

5. Proxmox Cluster Connection & API Tokens

We strongly recommend creating a dedicated unprivileged API Token on Proxmox VE rather than using the root user password.

# 1. Create a dedicated API user in the PVE realm
pveum user add whmcs-api@pve --comment "WHMCS Automation Service Account"

# 2. Create a custom role with required VM & Storage privileges
pveum role add WHMCS-Admin -privs "VM.Allocate VM.Audit VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Console VM.Snapshot VM.Snapshot.Rollback VM.Backup Datastore.AllocateSpace Datastore.Audit"

# 3. Assign role to the API user on root cluster path
pveum acl modify / -user whmcs-api@pve -role WHMCS-Admin

# 4. Generate API Token
pveum user token add whmcs-api@pve whmcs-token --privsep 0

In WHMCS, add your server under System Settings > Servers with module type Proxmox VE, entering your hostname, username (whmcs-api@pve), and Token Secret in the Access Hash / Password field.

6. Backup Storage Configuration (Dynamic Pools)

The module allows you to target any Proxmox backup storage pool dynamically per product package (e.g. local, pbs, hetzner-backup, nfs-storage).

Supported Storage Types in Proxmox VE:

In your WHMCS Product Module Settings, configure the Backup Storage field to match your Proxmox Storage ID exactly (e.g. hetzner-backup).

7. Automated vzdump Retention (7, 15, 30 Days)

The module integrates with standard WHMCS Configurable Options to bill and enforce backup retention policies.

WHMCS Configurable Option Setup:

• Option Name: Backup Retention|Backup Retention
• Option Type: Dropdown
• Sub-Options:
  • None|No Backups
  • 7d|Daily Backups (7 Days Retention)
  • 15d|Daily Backups (15 Days Retention)
  • 30d|Daily Backups (30 Days Retention)

When a VM is provisioned or upgraded via ChangePackage, the module automatically sets Proxmox tags (backup-7d, backup-15d, backup-30d) on the virtual machine. Proxmox cluster backup jobs can filter by these tags to enforce automated pruning policies (keep-daily=7, 15, 30).

8. Snapshot Lifecycle & Quotas (0, 5, 10, 30)

Empower your clients to take instant snapshots before OS updates or config changes, while strictly preventing storage exhaustion.

WHMCS Configurable Option Setup:

• Option Name: Snapshot Quota|Snapshot Quota
• Option Type: Dropdown
• Sub-Options:
  • 0|No Snapshots Allowed
  • 5|5 Snapshots Quota
  • 10|10 Snapshots Quota
  • 30|30 Snapshots Quota

The client area displays a live quota progress badge (e.g., "2 of 5 Snapshots Used"). Creating a snapshot beyond the purchased quota is strictly blocked at the API level.

9. HTML5 noVNC Console

Clients can access their server console directly inside their browser with full keyboard and mouse support, even if their SSH service or networking is misconfigured.

• Uses Proxmox VE vncproxy tickets with short 10-second lifetimes.
• Zero root password exposure to the browser.
• Direct WebSocket proxying through your WHMCS server or reverse proxy.

10. Complete WHMCS Product Setup Checklist

1. Navigate to System Settings > Products/Services.
2. Create a new product with Type: Server/VPS.
3. Under Module Settings, select Proxmox VE.
4. Select your Proxmox Server Group, Node, and base VM Template ID.
5. Specify your Backup Storage pool (e.g. hetzner-backup).
6. Assign your Configurable Options Group containing Backup Retention and Snapshot Quota.
7. Save Changes. Your product is now fully automated!

11. Frequently Asked Questions