Proxmox VE

Install and set up Proxmox for Paymenter: the API token, templates, the private console, product settings, IP pools and the welcome email.

Proxmox VE | Paymenter

Already selling servers with the Paymenter Proxmox extension? Proxmox VE installs next to it. See Migrating from the Paymenter Proxmox extension.

Requirements

  • Paymenter v1.x with a running queue worker (reinstalls and restores run in the background).
  • Proxmox VE 9. Proxmox VE 8 works too; see the note in the role step.
  • An API token on Proxmox. Paymenter has to reach the Proxmox API on port 8006; your customers never need to.

Installation

Step 1: Upload the extension

Extract the zip and upload the ProxmoxVE folder to the server extensions of Paymenter:

/var/www/paymenter/extensions/Servers/ProxmoxVE/

Make sure the web server user owns the files:

chown -R www-data:www-data /var/www/paymenter/extensions/Servers/ProxmoxVE

Step 2: Add the server in Paymenter

Admin Panel → Servers → New server → Extension: Proxmox VE

Fill in the Proxmox URL and the API token from the next section, then press Test Connection.

Preparing Proxmox

The extension only needs access to its own pool, storages and bridge. Run these commands on a Proxmox node as root and change the pool, storage and bridge names to yours.

Step 1: Create a role

pveum role add PaymenterProxmox -privs "VM.Allocate VM.Clone VM.Audit VM.PowerMgmt VM.Console VM.Backup VM.Snapshot VM.Snapshot.Rollback VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.AllocateSpace Datastore.Audit Pool.Audit SDN.Use"

On Proxmox VE 8, replace VM.GuestAgent.Audit VM.GuestAgent.Unrestricted with VM.Monitor.

Step 2: Create a pool, a user and the permissions

pveum pool add customers
pveum user add paymenter@pve
pveum acl modify /pool/customers -user paymenter@pve -role PaymenterProxmox
pveum acl modify /storage/local-zfs -user paymenter@pve -role PaymenterProxmox
pveum acl modify /storage/local -user paymenter@pve -role PaymenterProxmox
pveum acl modify /sdn/zones/localnetwork -user paymenter@pve -role PaymenterProxmox
pveum acl modify /nodes -user paymenter@pve -role PVEAuditor

local-zfs holds the disks, local holds the container templates and backups. Use your own storages if they are different.

Step 3: Create the API token

pveum user token add paymenter@pve billing --privsep 0

Copy the token ID (paymenter@pve!billing) and the secret into the server settings in Paymenter. The secret is shown only once.

Templates

Virtual machine templates

Virtual machines are cloned from a cloud-init template that sits in the pool. A cloud image only allows SSH keys by default, so prepare it once to accept the root password from the welcome email and to run the guest agent:

apt install libguestfs-tools
wget https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2
virt-customize -a debian-13-genericcloud-amd64.qcow2 \
  --install qemu-guest-agent \
  --run-command "printf 'PermitRootLogin yes\nPasswordAuthentication yes\n' > /etc/ssh/sshd_config.d/10-hosting.conf" \
  --run-command "printf 'ssh_pwauth: true\ndisable_root: false\n' > /etc/cloud/cloud.cfg.d/99-hosting.cfg" \
  --truncate /etc/machine-id

Then turn the image into a template:

qm create 9000 --name debian-13 --pool customers --memory 1024 --cores 1 --ostype l26 \
  --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0 --agent enabled=1 --serial0 socket
qm set 9000 --scsi0 local-zfs:0,import-from=/root/debian-13-genericcloud-amd64.qcow2
qm set 9000 --ide2 local-zfs:cloudinit --boot order=scsi0
qm template 9000

Repeat this for every operating system you want to offer. The disk is grown to the size of the product on creation.

Container templates

pveam update
pveam download local debian-13-standard_13.6-1_amd64.tar.zst

Console

The console works right after installation, without any extra setup. The browser of your customer only talks to Paymenter; Paymenter connects to Proxmox with your API token, so Proxmox never has to be public.

Each open console keeps one PHP worker busy while it is open. If many customers use the console at the same time, raise pm.max_children in your PHP-FPM pool, or use the relay service below.

Optional: relay service

For hosts with many consoles open at once. Set Console mode to the relay service, then run it and proxy it in nginx:

[Unit]
Description=Paymenter Proxmox console relay
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/paymenter
ExecStart=/usr/bin/php artisan proxmoxve:console-relay --listen=127.0.0.1:8095
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Save it as /etc/systemd/system/paymenter-proxmox-console.service, run systemctl enable --now paymenter-proxmox-console and add this inside the server block of Paymenter:

location /proxmox-console/ {
    proxy_pass http://127.0.0.1:8095;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 4h;
}

Optional: direct mode

With Console mode set to direct, the browser opens the console on Proxmox itself. Proxmox must then be reachable by your customers on a host that shares a parent domain with Paymenter (for example billing.example.com and pve.example.com), with Console cookie domain set to .example.com. Create the console role and group once:

pveum role add ProxmoxConsole -privs "VM.Console VM.Audit"
pveum group add proxmox-console

Direct mode also needs Permissions.Modify in the role from the previous section, and User.Modify plus Realm.AllocateUser on /access/groups/proxmox-console and /access/realm/pve.

Server settings

SettingDescription
Proxmox URLAddress Paymenter uses for the API, for example https://10.0.0.2:8006.
API token ID / secretThe token from the Proxmox section.
Verify the TLS certificateTurn off only while Proxmox uses its self-signed certificate.
First / last VMIDNew guests get the first free VMID in this range.
Console modeThrough Paymenter (default, no setup), through the optional relay service, or directly to Proxmox.
Demo modeCustomers can look around and use power actions, but cannot change or reinstall anything.

Product settings

Create a product, choose your Proxmox server on the Server tab and fill in the settings.

SettingDescription
Guest typeVirtual machine (KVM) or container (LXC).
NodeA fixed node, or automatic (the online node with the most free memory). Virtual machines are created on the node of their template.
Disk storage, resource poolWhere new disks go and which pool new guests join.
TemplatesThe templates customers can pick at checkout and when they reinstall. Give them friendly names in Template names, one per line: 9000 = Debian 13.
Clone modeFull clone (independent disk) or linked clone (fast, depends on the template).
CPUCores, sockets, vCPUs at boot, CPU type, CPU limit and CPU weight.
MemoryMemory, minimum memory for ballooning (VM) or swap (container).
DiskSize in GiB, cache, async IO, SSD emulation, discard and IO thread.
NetworkBridge, VLAN tag, network card and speed limit in MB/s.
IPv4 / IPv6 poolSee IP pools below.
Login userThe user cloud-init creates with the password and SSH keys. Leave empty to use the image default.
Proxmox firewallTurns on the firewall. Locked security group is a datacenter group that always comes first and cannot be removed by customers. Block IP spoofing only allows traffic from the assigned addresses.
Backups / snapshotsBackup storage, how many backups and snapshots a customer may keep, and the backup mode.
OtherCustomers can reinstall, start after creation, start when the node boots, delete backups on termination and Proxmox tags.

IP pools

Write one range per line. Every line keeps its own prefix and gateway.

203.0.113.10-203.0.113.60/24 gw 203.0.113.1
198.51.100.0/28 gw 198.51.100.1

IPv6 as single addresses, or a whole /64 per server from a larger prefix with split 64:

2001:db8:1::/64 gw 2001:db8:1::1
2001:db8::/48 gw 2001:db8::1 split 64

The first address goes on the network card through cloud-init. Extra addresses are shown to the customer and allowed by the spoofing filter; the customer adds them inside the server.

Configurable options

Every product setting below can be changed per order with a configurable option. Use the setting name as the environment variable of the option and the number as the value.

Environment variableWhat it sets
cores, sockets, vcpusCPU cores, sockets and vCPUs
cpu_limit, cpu_unitsCPU limit and weight
memory, balloon, swapMemory in MiB
diskDisk in GiB (upgrades grow the disk, they never shrink it)
rateNetwork speed limit in MB/s
ipv4_count, ipv6_countNumber of IPv4 addresses and IPv6 addresses or subnets
backup_limit, snapshot_limitNumber of backups and snapshots

Welcome email

Add these variables to the email template of the product:

IP address: {{ $ip }}
Username: {{ $username }}
Password: {{ $password }}
Hostname: {{ $hostname }}
IPv6: {{ $ipv6 }}

Also available: {{ $ipv4 }} (all IPv4 addresses), {{ $vmid }} and {{ $os }}.

Client area

Customers get a Server tab with live usage, graphs, power controls, the console, backups, snapshots, firewall rules and settings for the hostname, password, SSH keys and reinstall.

  • A new password works right away when the guest agent runs; otherwise it is set on the next restart.
  • Containers have no API to change the root password; customers change it inside the container or reinstall.
  • Reinstall keeps the VMID, IP addresses and backups, and creates a new password.

Migrating from the Paymenter Proxmox extension

Proxmox VE uses its own folder and name, so it runs next to the Paymenter Proxmox extension. Your servers keep running during the move. One command moves your products and servers over, shows a dry run first, checks everything before it changes anything, and can undo the move. If something fails halfway, nothing is changed.

Step 1: Make a backup

Back up the Paymenter database before you start.

Step 2: Install Proxmox VE

Upload the ProxmoxVE folder as shown under Installation, or upload the zip under Admin Panel → Extensions → Install Extension. Leave the Proxmox folder of the old extension in place.

Step 3: Add one Proxmox VE server

Add a server with the extension Proxmox VE and fill in the same Proxmox URL and API token as your location in the old extension. Press Test Connection. Paymenter only loads the migration command once a Proxmox VE server exists.

The command reuses this server for every location with the same URL and token. For a location with another URL or token, it creates a new server named after the location.

The token of the old extension often has full access. If it is limited, give it the role from Preparing Proxmox on the pool that holds your servers and templates.

Step 4: Check the plan

cd /var/www/paymenter
php artisan proxmoxve:migrate --dry-run

This only shows what will happen, per product: the server it moves to, the templates, the IP pool and every service with its VMID, node and IP addresses. Nothing is changed. Without --apply the command always does a dry run.

The dry run also checks that the API token can reach Proxmox and can see every server and template. Problems are marked with x; as long as there is one, --apply refuses to run. Lines marked with ! are warnings about settings that cannot be carried over.

Step 5: Migrate

php artisan proxmoxve:migrate --apply

To move one location first, add the IDs of its products: --product=4 --product=5. Products that share a location or IP addresses must move together, otherwise both extensions could give out the same IP address; the command tells you which IDs to add. Services that were already moved are skipped.

Everything is written in one database transaction. If any step fails, including saving the backup file, the whole migration is rolled back and both extensions keep working as before.

The command saves the old values in storage/app/proxmoxve-migrations/ and prints the undo command. Run it without --apply first to see what it will do. To move everything back:

php artisan proxmoxve:migrate --rollback="storage/app/proxmoxve-migrations/migration-20261120-154845.json" --apply

Undo is no longer possible once Proxmox VE has created a new server for one of these products, because the old extension cannot manage it. The command tells you which services block it.

What is carried over

  • The Proxmox URL and API token of each location.
  • The product settings: CPU, memory, disk, network card, speed limit, resource pool, backups and start after creation.
  • The operating systems of the location as templates, with their names.
  • The IP addresses of the location as IPv4 and IPv6 pools.
  • Every server: VMID, node, template, hostname, IP addresses and suspended state. The VMs in Proxmox are not touched.
  • Orders that were not set up yet keep their chosen operating system.
  • Configurable options named ipv4, ipv6, ratelimit and backups are renamed to ipv4_count, ipv6_count, rate and backup_limit. Options that are also linked to products you did not move yet are left alone and shown as a warning.

What is not carried over

  • The monthly bandwidth limit and traffic counter.
  • Placement over several nodes in a location. New virtual machines are created on the node that holds the template; move templates or use one product per node if you need to spread them.
  • A custom MTU on the IP pool. Existing servers keep it.
  • When the IP pools of a location use different bridges or VLANs, the first one is used.
  • IPv6 is given out from the whole prefix of your addresses, not only from the listed addresses.
  • Server passwords. The old extension does not store them; customers can set a new one in the Server tab.

Snapshots are off for migrated products (snapshot limit 0) and customer firewall rules follow the firewall setting of the IP pool. Change both in the product settings if you want to offer them.

Step 6: Remove the old extension

Once every product runs on Proxmox VE and you have checked a few servers, delete the old Proxmox server under Admin Panel → Servers and remove the extensions/Servers/Proxmox folder. Until then customers still see the old Servers page next to the new Server tab; both control the same VM.

Updating

Replace the ProxmoxVE folder with the new version. If you use the optional relay service, restart it with systemctl restart paymenter-proxmox-console.

Troubleshooting

ProblemSolution
Test Connection fails with 401Check the token ID and secret. The token ID looks like paymenter@pve!billing.
Permission check failedThe token misses a privilege on that path. Compare the role and the ACL paths with the Proxmox section; templates must be in the pool.
No templates in the productThe template is not in the pool, or the token cannot see the storage that holds the container templates.
Password login over SSH does not workThe template still has the cloud image defaults. Prepare it as shown under Templates.
The console keeps connectingCheck that Paymenter can reach Proxmox on port 8006 and that the server is running. Behind nginx, make sure responses are not buffered for long requests (the extension sends X-Accel-Buffering: no). With the relay service, check systemctl status paymenter-proxmox-console.
Reinstall or restore stays busyThe Paymenter queue worker is not running.
The migration says "must be migrated together"Those products share a location or IP addresses. Run the command with all product IDs it lists, or without --product.
Command "proxmoxve:migrate" is not definedAdd one Proxmox VE server first (migration step 3). Paymenter only loads the extension once a server uses it.