# Admin Area

Reference for everything a WHMCS administrator uses to run the Proxmox KVM module: the product configuration panel, the per-service admin page with real-time VM status, deploy logs, charts and module commands, and WHMCS Configurable Options for selectable resources.

# Product Configuration

### Proxmox KVM module **[WHMCS](https://puqcloud.com/link.php?id=77)**
#####  [Order now](https://puqcloud.com/whmcs-module-proxmox-kvm.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Proxmox-KVM/) | [FAQ](https://faq.puqcloud.com/)

The product configuration page defines all default settings for virtual machines provisioned under a given WHMCS product. These settings are accessible by navigating to **Setup > Products/Services > Products/Services**, selecting a product, and opening the **Module Settings** tab with **PUQ ProxmoxKVM** selected as the module.

The module injects a custom settings panel directly below the standard WHMCS module options. All settings are organized into collapsible sections arranged in a two-column layout.

![Full product configuration page](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-gpzduogi.png)

> **Changed in v3.0.** The product configuration page has been fully rewritten as a custom Bootstrap panel injected into the Module Settings tab. In v1.x–v2.x the same options were stored in the stock WHMCS `configoption1..N` fields and displayed as plain textareas — all existing values are preserved during upgrade and migrated to the new panel automatically. The **Firewall** section and the **Anti-spoofing** checkbox, which previously lived inside the Network block, are now a dedicated collapsible section of their own.

---

## License Key

The first field in the standard WHMCS module settings area is the **License key**. Enter your PUQ ProxmoxKVM license key here. The module validates the license on each page load and displays a verification badge next to the field.

---

## VM Configuration

This section controls the core virtual machine parameters applied during provisioning.

![VM Configuration section](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-iclnl2dm.png)

| Setting | Description | Default |
|---------|-------------|---------|
| **Target node** | Proxmox node where VMs will be created. Select a specific node from the dropdown or leave as **automatically** to let the module choose the node with the most available resources. The dropdown is populated via AJAX from the connected Proxmox server; click the refresh button to reload the list. | `automatically` |
| **OS template** | The default operating system template used for cloning new VMs. Templates are loaded from Proxmox via AJAX. Click the refresh button to reload available templates. | (none) |
| **Clone type** | Determines how the VM is cloned from the template. **Linked Clone** is faster and uses less disk space by sharing the base disk with the template. **Full Clone** creates a completely independent copy but is slower and uses more storage. | `Linked Clone` |
| **CPU** | Number of virtual CPU cores assigned to the VM. | `1` |
| **RAM** | Amount of memory in gigabytes assigned to the VM. | `1` |
| **Backups** *(new in v3.3)* | Default maximum number of backups for the service. Overridden by the `Backups` Configurable Option when assigned. `0` = backups disabled. | `0` |
| **Snapshots** *(new in v3.3)* | Default maximum number of snapshots for the service. Overridden by the `Snapshots` Configurable Option when assigned. `0` = snapshots disabled. | `0` |
| **VM name rule** | A naming pattern for the VM hostname. Supports macros that are expanded at provisioning time. Leave empty to use the default pattern. A live preview is shown below the field. | `{client_id}-{service_id}` |
| **First VM ID** | The starting VM ID number. The module assigns VM IDs sequentially from this value, skipping any IDs already in use on the Proxmox cluster. | `100` |
| **OS username** | The default operating system username set via cloud-init. Leave empty to generate a random username. | (empty = random) |
| **Snapshot lifetime** | Automatic cleanup period for client-created snapshots. The cron job removes snapshots older than the selected duration. Set to **Don't remove** to keep snapshots indefinitely. | `Don't remove` |

### VM Name Rule Macros

The following macros can be used in the **VM name rule** field:

| Macro | Description | Example |
|-------|-------------|---------|
| `{client_id}` | WHMCS client ID | `142` |
| `{service_id}` | WHMCS service/hosting ID | `387` |
| `{random_digit_X}` | Random digits (X = count) | `{random_digit_4}` = `7291` |
| `{random_letter_X}` | Random lowercase letters (X = count) | `{random_letter_3}` = `kqz` |
| `{unixtime}` | Current Unix timestamp | `1712678400` |
| `{year}` | Current 4-digit year | `2026` |
| `{month}` | Current 2-digit month | `04` |
| `{day}` | Current 2-digit day | `09` |
| `{hour}` | Current 2-digit hour | `14` |
| `{minute}` | Current 2-digit minute | `35` |
| `{second}` | Current 2-digit second | `07` |

### Snapshot Lifetime Options

| Value | Duration |
|-------|----------|
| Don't remove | Snapshots kept indefinitely |
| 1 day | 86,400 seconds |
| 2 days | 172,800 seconds |
| 3 days | 259,200 seconds |
| 4 days | 345,600 seconds |
| 5 days | 432,000 seconds |
| 6 days | 518,400 seconds |
| 7 days | 604,800 seconds |
| 8 days | 691,200 seconds |
| 9 days | 777,600 seconds |
| 10 days | 864,000 seconds |

---

## Network

This section configures the virtual network adapter and IP addressing behavior for provisioned VMs.

![Network section](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-pyvvazif.png)

| Setting | Description | Default |
|---------|-------------|---------|
| **Model** | The virtual network adapter model. **As in template** preserves the model defined in the Proxmox template. Other options: **VirtIO** (recommended for Linux), **Intel E1000**, **Realtek RTL8139**, **VMware vmxnet3**. | `As in template` |
| **Bandwidth** | Maximum network bandwidth limit in MB/s. Set to **0** for unlimited bandwidth. Overridden by the `Network Bandwidth` Configurable Option when assigned. | `0` (unlimited) |
| **Bridge** | The Proxmox network bridge to attach the VM's network adapter to (e.g., `vmbr0`, `vmbr1`). | `vmbr0` |
| **VLAN tag** | VLAN tag for the network adapter. Set to **0** for no VLAN tagging. Valid range: 0-4096. | `0` |
| **IPv4 count** *(new in v3.3)* | Default number of IPv4 addresses to allocate from the pool. Overridden by the `IPv4 Addresses` Configurable Option when assigned. | `1` |
| **IPv6 count** *(new in v3.3)* | Default number of IPv6 addresses to allocate from the pool. Overridden by the `IPv6 Addresses` Configurable Option when assigned. `0` = no IPv6. | `0` |
| **Auto bridge/VLAN** | When enabled, the bridge and VLAN are automatically determined from the IP Pool configuration in the addon module, overriding the manual Bridge and VLAN settings above. | `on` |
| **DHCP IPv4** | Enable DHCP for IPv4 addressing in cloud-init configuration. | `on` |
| **DHCP IPv6** | Enable DHCP for IPv6 addressing in cloud-init configuration. | `on` |

> **Note:** When **Auto bridge/VLAN** is enabled and the addon module's IP Pools are configured, the pool's bridge and VLAN values take precedence over the manually entered Bridge and VLAN fields.

> **DHCP caveat.** When either DHCP IPv4 or DHCP IPv6 is enabled, the module does **not** know the VM's final IP address at provisioning time. In that case no firewall rules and no anti-spoofing IPSet are applied to the VM's interface (they would be meaningless without a known IP). If you want the firewall feature, either use static IPs with the IP pool, or configure the rules manually after the DHCP lease has been issued.

---

## Firewall

This section defines the default Proxmox firewall configuration applied to each provisioned VM's network interface.

![Firewall section](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-jc58xmvp.png)

### Policy and Logging

| Setting | Description | Default |
|---------|-------------|---------|
| **Input Policy** | Default policy for incoming traffic. Options: **ACCEPT**, **DROP**, **REJECT**. | `ACCEPT` |
| **Output Policy** | Default policy for outgoing traffic. Options: **ACCEPT**, **DROP**, **REJECT**. | `ACCEPT` |
| **Log level in** | Logging level for incoming traffic. Options: **nolog**, **info**, **notice**, **warning**. | `nolog` |
| **Log level out** | Logging level for outgoing traffic. Options: **nolog**, **info**, **notice**, **warning**. | `nolog` |

### Firewall Toggles

| Setting | Description | Default |
|---------|-------------|---------|
| **Enable** | Enable the Proxmox firewall on the VM's network interface. | `on` |
| **DHCP** | Allow DHCP traffic through the firewall. | `on` |
| **NDP** | Allow Neighbor Discovery Protocol (IPv6) traffic. | `on` |
| **Router Adv** | Allow Router Advertisement packets. Typically disabled for client VMs. | `off` |
| **MAC filter** | Enable MAC address filtering on the network interface. | `on` |
| **IP filter** | Enable IP address filtering, restricting traffic to assigned IPs only. | `off` |
| **Anti-spoofing** | Enable anti-spoofing rules to prevent the VM from sending traffic with forged source addresses. | `on` |

> **Anti-spoofing requires a deny-by-default policy on the cluster.** For the anti-spoofing IPSet (`ipfilter-net0`) to actually protect against spoofed traffic, the **cluster / node firewall policy must be DENY/DENY** — the module then only adds permissive rules matching the VM's own IP addresses. Without a DENY baseline, the permissive rules change nothing and the feature has no effect. The filter was renamed from the legacy `wm-VMID` to `ipfilter-net0` in v2.3; v3.0 uses the same naming.

---

## Storage

This section configures the system (boot) disk and optional additional (secondary) disk for provisioned VMs. A value of **0** means "not changed" — the template's default is preserved.

![Storage section](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-34vj7wwc.png)

### System Disk

| Setting | Description | Default |
|---------|-------------|---------|
| **Storage** | Proxmox storage pool for the system disk. Select a specific storage or leave as **auto (from template)** to use the same storage as the template. The dropdown is populated via AJAX from the connected Proxmox server. | `auto (from template)` |
| **Space** | System disk size in GB. Set to **0** to keep the template's disk size. | `0` |
| **Bandwidth Read** | Maximum read throughput in MB/s. Set to **0** for unlimited. | `0` |
| **Bandwidth Write** | Maximum write throughput in MB/s. Set to **0** for unlimited. | `0` |
| **IOPS Read** | Maximum read I/O operations per second. Set to **0** for unlimited. | `0` |
| **IOPS Write** | Maximum write I/O operations per second. Set to **0** for unlimited. | `0` |

### Additional Disk

The additional disk is automatically created during provisioning if the space is set to a value greater than 0.

| Setting | Description | Default |
|---------|-------------|---------|
| **Storage** | Proxmox storage pool for the additional disk. Leave as **same as system disk** to use the system disk's storage. | `same as system disk` |
| **Space** | Additional disk size in GB. Set to **0** to skip additional disk creation. | `0` |
| **Bandwidth Read** | Maximum read throughput in MB/s. Set to **0** for unlimited. | `0` |
| **Bandwidth Write** | Maximum write throughput in MB/s. Set to **0** for unlimited. | `0` |
| **IOPS Read** | Maximum read I/O operations per second. Set to **0** for unlimited. | `0` |
| **IOPS Write** | Maximum write I/O operations per second. Set to **0** for unlimited. | `0` |

> **Important:** Storage names must be identical across all cluster nodes, or use shared storage. If the VM may be migrated between nodes, ensure the target storage exists on all nodes.

---

## Integrations

This section configures external integrations: backup/ISO storage locations, noVNC console proxy, domain naming, reverse DNS ticket creation, and email notification templates.

![Integrations section](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-g7xul7n3.png)

### Storage and Console

| Setting | Description | Default |
|---------|-------------|---------|
| **Backups storage** | Proxmox storage pool for VM backups. The dropdown lists all storages with backup content type. The value includes the storage name and plugin type (e.g., `local\|dir`). | (none) |
| **ISOs storage** | Proxmox storage pool where ISO images are stored for client ISO mount functionality. | (none) |
| **noVNC domain** | Domain name of the noVNC proxy server used for browser-based console access. | `vncproxy.puqcloud.com` |
| **noVNC key** | Authentication key for the noVNC proxy server. | `puqcloud` |

### Domain and DNS

| Setting | Description | Default |
|---------|-------------|---------|
| **Main domain** | The base domain suffix used for VM hostname generation. The full hostname is constructed as `<prefix>-<client_id>-<service_id><main_domain>`. | `.example.com` |
| **RevDNS ticket** | When enabled, a support ticket is automatically created when a client requests a reverse DNS change (if no DNS zone automation is configured). Select the support department for these tickets from the dropdown. | `on` |

### Email Templates

These dropdowns list all WHMCS product-type email templates. Select the template to be sent for each event, or choose **None** to disable the notification.

| Setting | Description | Default Template |
|---------|-------------|-----------------|
| **VM is ready** | Sent when VM provisioning completes successfully. Contains VM credentials and connection details. | `puqProxmoxKVM VM is ready` |
| **Reset password** | Sent when a client resets the VM's OS password. Contains the new credentials. | `puqProxmoxKVM Reset password` |
| **Backup restored** | Sent when a backup restore operation completes. | `puqProxmoxKVM Backup restored` |

---

## Client Area Permissions

This section controls which features are visible and accessible to clients in their service management area. Each toggle enables or disables a specific client area function.

![Client Area Permissions](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-ozdpxccn.png)

| Permission | Description | Default |
|------------|-------------|---------|
| **Start** | Allow clients to power on their VM. | `on` |
| **Stop** | Allow clients to power off their VM. | `on` |
| **noVNC** | Allow clients to open a browser-based console session. | `on` |
| **Charts** | Allow clients to view CPU, RAM, disk, and network performance charts. | `on` |
| **Reinstall** | Allow clients to reinstall the VM's operating system (destructive). | `on` |
| **Reset password** | Allow clients to reset the VM's OS password via cloud-init. | `on` |
| **RevDNS** | Allow clients to configure reverse DNS records for their IP addresses. | `on` |
| **ISO mount** | Allow clients to mount and unmount ISO images on their VM. | `on` |
| **Firewall** | Allow clients to manage their VM's Proxmox firewall rules. | `on` |

---

## Metric Billing

The module includes a built-in WHMCS Usage Billing (Metric) Provider that reports monthly bandwidth consumption per service. This integrates with WHMCS's standard metric billing system.

![Metric billing toggle](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-hcfyys8i.png)

### Available Metrics

| Metric | Description | Unit | Period |
|--------|-------------|------|--------|
| **Bandwidth Usage In** | Total inbound network traffic | GB | Monthly |
| **Bandwidth Usage Out** | Total outbound network traffic | GB | Monthly |

To enable metric billing:

1. Navigate to **Setup > Products/Services > Products/Services** and edit the product
2. Open the **Metrics** tab
3. Enable the desired metrics and configure pricing

The module's cron job collects bandwidth statistics from Proxmox and stores them in the `puqProxmoxKVM_statistics` table. The metric provider aggregates this data for WHMCS's billing calculations.


<!-- sync:7f8d2cfc2cd7ac8e -->

# Service Management

### Proxmox KVM module **[WHMCS](https://puqcloud.com/link.php?id=77)**
#####  [Order now](https://puqcloud.com/whmcs-module-proxmox-kvm.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Proxmox-KVM/) | [FAQ](https://faq.puqcloud.com/)

The service management page is the primary admin interface for an individual client's KVM service. It is accessed by navigating to **Clients > [Client Name] > Products/Services > [Service]** and viewing the module's custom tab fields.

The page provides real-time VM status monitoring, resource usage visualization, deploy logging, console access, performance charts, and direct module command execution.

![Service detail overview](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-y37m7vhe.png)

---

## VM ID and Reverse DNS

At the top of the service tab, the module displays:

- **VM ID** — the Proxmox VM identifier, with a verification status indicator confirming whether the VM exists on the cluster
- **Reverse DNS** — a table listing all assigned IP addresses with editable reverse DNS fields; changes are saved when the admin clicks the WHMCS **Save Changes** button

## API Connection Status

The module checks connectivity to the Proxmox API on each page load. A green **API answer OK** box confirms successful communication. If the connection fails, a red error box is shown with the error details, and real-time features are disabled.

---

## Function Buttons

Below the connection status, a toolbar provides quick-action buttons:

![Module command buttons](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-c0g1vvsc.png)

| Button | Description |
|--------|-------------|
| **noVNC** | Generates a one-time noVNC console URL. The link is valid for 10 seconds. After expiration, click again to generate a new link. |
| **Deploy Log** | Toggles the deploy log panel (see below). |
| **Redeploy** | Deletes the existing VM on Proxmox, clears IP assignments, and starts a fresh provisioning cycle. Requires confirmation. |

### noVNC Console

![noVNC connect button](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-xwjvkw2i.png)

Clicking **noVNC** sends an AJAX request to the module, which obtains a VNC ticket from Proxmox and constructs a proxy URL. The link opens in a new 800x600 browser window. The URL is single-use and expires after 10 seconds for security.

---

## Module Commands

The module registers a set of administrative command buttons in the WHMCS **Module Commands** section of the service page.

![Module command buttons](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-c0g1vvsc.png)

| Command | Description | Notes |
|---------|-------------|-------|
| **Start** | Power on the VM | — |
| **Stop** | Power off the VM | — |
| **Reinstall** | Wipe the VM and reinstall the OS from the template | Destructive; requires confirmation |
| **VMSetDedicatedIp** | Assign or reassign dedicated IP addresses from the pool | — |
| **VMClone** | Clone the VM to a new VM ID | — |
| **Set CPU RAM** | Update CPU core count and RAM size | Requires VM stop for certain changes |
| **Set System Disk Size** | Resize the boot disk | One-way: can only increase |
| **Set System Disk Bandwidth** | Update read/write throughput and IOPS limits on the system disk | — |
| **Set Created Additional Disk** | Create a secondary disk if one does not exist | — |
| **Set Additional Disk Size** | Resize the secondary disk | One-way: can only increase |
| **Set Additional Disk Bandwidth** | Update read/write throughput and IOPS limits on the additional disk | — |
| **Set Network** | Update network bridge, VLAN, bandwidth, and adapter model | — |
| **Set Firewall** | Apply firewall configuration from product settings to the VM | — |
| **SetCloudinit** | Reapply cloud-init configuration (hostname, user, SSH keys, network) | Destructive; overwrites current cloud-init |
| **VMRemove** | Delete the VM from Proxmox | Destructive; requires confirmation |
| **Set DNS records** | Synchronize forward and reverse DNS records based on current IP assignments | — |

> **Legend of the button prefixes:**
>
> - `*` — the function can run while the VM is **running**
> - `**` — the function can only run when the VM is **stopped**
> - `->` — the function participates in the automatic creation/reinstall pipeline and points to the next step in the state machine
>
> These markers match the ones PUQcloud has used since v1.0 — they are shown inline next to each command button in WHMCS.

### Local status values

The module tracks each VM with an internal **local status** that controls which automation actions may run on the next cron tick. Knowing the status helps diagnose stuck deploys.

| Status | Meaning |
|--------|---------|
| `creation` | First status issued at the time of service creation. Indicates that the VM creation process should start on the next cron run. |
| `reinstall` | The VM is in the reinstall queue and will be redeployed from the selected template. |
| `clone` | The clone operation is in progress (or just finished) — the state machine is about to start post-clone configuration. |
| `migrated` | *(new in v3.0)* The VM has been successfully migrated to the target node after cloning. |
| `set_cpu_ram` | CPU cores and RAM have been configured successfully. |
| `set_system_disk_size` | System disk has been resized successfully. |
| `set_system_disk_bandwidth` | System disk I/O bandwidth limits have been applied. |
| `set_created_additional_disk` | Additional disk step finished (whether a disk was created or not — the step is skipped if the package has no additional disk). |
| `set_additional_disk_size` | Additional disk has been resized (or skipped). |
| `set_additional_disk_bandwidth` | Additional disk bandwidth limits have been applied (or skipped). |
| `set_network` | Network card configuration (bridge, VLAN, bandwidth, MAC) is complete. |
| `set_firewall` | Firewall options, policies and anti-spoofing IPSet have been configured. |
| `set_cloudinit` | Cloud-init has been rewritten with the target user/password/network. |
| `ready` | Terminal success state — the VM was created correctly and is ready to work. |
| `set_dns_records` | On the next cron tick, DNS records will be synchronized. |
| `change_package` | On the next cron tick, the module will start the `change_package` state machine to apply new package parameters. |
| `cp_*` | *(new in v3.0)* Intermediate states of the change-package state machine (`cp_update_ip`, `cp_stop`, `cp_cpu_ram`, `cp_system_disk_size`, `cp_system_disk_bandwidth`, `cp_additional_disk`, `cp_additional_disk_size`, `cp_additional_disk_bandwidth`, `cp_network`, `cp_firewall`, `cp_start`). Each state represents a single completed change-package step. On failure the state machine resumes from the last successful state. |

Alongside the local status the module tracks:

- **Remote status** — the status returned by the Proxmox API itself: `running` or `stopped`.
- **VM remote lock** — set by Proxmox while a long operation (like `clone` or `backup`) is in progress. While a lock is present the module pauses all other actions against that VM.

---

## Real-Time VM Information

The real-time information panel refreshes automatically every 5 seconds (with a 10-second initial load). It displays comprehensive VM status and resource usage in a two-column layout.

![Real-time VM info panel](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-zfvqweed.png)

### Left Column: Status and Compute

**Status Section:**

| Field | Description |
|-------|-------------|
| **Remote** | Current VM power state on Proxmox (running/stopped), uptime, and lock status if any operation is in progress |
| **Local / Node** | The module's internal status tracking and the Proxmox node hosting the VM |

**CPU & RAM Section:**

| Field | Description |
|-------|-------------|
| **CPU** | Current CPU usage as a percentage of allocated cores, with a color-coded progress bar (green < 50%, yellow 50-80%, red > 80%) |
| **RAM** | Current memory usage in GiB and percentage, with a color-coded progress bar |

### Right Column: Storage and Network

![Detailed status closeup](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-qxuqmrwv.png)

**System Disk Section:**

| Field | Description |
|-------|-------------|
| **Size** | Current disk size vs. package-configured size, with the underlying file path |
| **I/O real** | Actual read/write throughput in MB/s and IOPS as currently measured |
| **I/O pkg** | Package-configured throughput and IOPS limits |

**Additional Disk Section** (shown only if an additional disk exists):

Same fields as the system disk section, displayed for the secondary disk.

**Network Section:**

| Field | Description |
|-------|-------------|
| **Adapter** | Network model and MAC address |
| **Real** | Actual bandwidth rate, bridge, and VLAN as configured on Proxmox |
| **Package** | Package-configured bandwidth limit, bridge, and VLAN |
| **ISO** | Currently mounted ISO image, if any |

---

## Configurable Options *(new in v3.3)*

A dedicated **Configurable Options** tab on the service page shows the effective per-service selection of every WHMCS Configurable Option that is assigned to the product. Useful for confirming which pricing tier the client actually picked without having to dig into the database or the order itself.

![Service Configurable Options tab](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-cdbtlypg.png)

The tab lists each option by its plain-English name (`CPU Cores`, `RAM`, `System Disk`, `Backups`, `Snapshots`, etc.) together with the human-readable display text of the selected sub-option. When no Configurable Option is assigned for a given resource, the Module Settings default is used and that resource simply does not appear in this tab — see the [Product Configuration chapter](01-product-configuration.md) for where each default lives.

See the dedicated [Configurable Options chapter](03-configurable-options.md) for the full list of supported options, sub-option formats, and pricing-tier examples.

---

## Deploy Log

The deploy log panel is toggled by clicking the **Deploy Log** button. It provides a complete history of all provisioning and administrative operations performed on the VM.

![Deploy log with steps](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-qks7yvf4.png)

### Last Action

The top section shows the most recent operation:

| Field | Description |
|-------|-------------|
| **Action** | The operation name (e.g., `deploy`, `reinstall`, `change_package`) |
| **Result** | Success or failure badge |
| **Time range** | Start and finish timestamps |
| **Steps table** | Numbered list of individual steps with result status and duration in seconds |

### Deploy History

Below the last action, a chronological list of all deploy runs is displayed. Each entry shows:

- Start timestamp
- Status transition (before → after)
- Result badge (success/waiting/error)
- Error message, if applicable
- Expandable step detail table (click the header to toggle)

Each step in the detail table includes:

| Column | Description |
|--------|-------------|
| **#** | Step sequence number |
| **Step** | Operation name (e.g., `clone`, `set_ip`, `set_cpu_ram`, `set_firewall`) |
| **Result** | Success or failure |
| **From** | VM status before this step |
| **To** | VM status after this step |
| **Time** | Timestamp when the step executed |
| **Dur** | Duration in seconds |

---

## Usage Charts

The charts section displays CPU, memory, disk I/O, and network throughput graphs rendered using Google Charts. The data is fetched via AJAX from Proxmox's RRD statistics.

![Usage charts and metrics](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-rosc0rar.png)

### Time Frame Selection

A button group allows selecting the chart time range:

| Button | Period |
|--------|--------|
| **Hour** | Last 60 minutes (default on page load) |
| **Day** | Last 24 hours |
| **Week** | Last 7 days |
| **Month** | Last 30 days |
| **Year** | Last 365 days |

### Chart Types

Three area charts are displayed side by side:

| Chart | Series | Description |
|-------|--------|-------------|
| **CPU & RAM** | CPU %, RAM % | Processor and memory utilization over time |
| **Disk I/O** | Read MB/s, Write MB/s | Storage throughput |
| **Network** | IN MB/s, OUT MB/s | Network interface throughput |

---

## Change Package

When a service's product/package is changed (upgrade or downgrade), the module executes a multi-step reconfiguration process. The admin can monitor progress through the deploy log.

![Change package in progress](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-4wgkccao.png)

The change package operation follows this sequence:

1. Update IP addresses (if pool/network changed)
2. Stop the VM
3. Set CPU and RAM to new values
4. Resize system disk
5. Update system disk bandwidth limits
6. Create or resize additional disk
7. Update additional disk bandwidth limits
8. Reconfigure network adapter
9. Reapply firewall rules
10. Start the VM

![Change package complete](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-uns3ljjr.png)

Each step is logged individually in the deploy log. If any step fails, the process halts and the error is recorded. The admin can review the failure in the deploy log and either fix the issue manually or use the **Redeploy** button to start fresh.


<!-- sync:8ddb8139066f78fa -->

# Configurable Options

### Proxmox KVM module **[WHMCS](https://puqcloud.com/link.php?id=77)**
#####  [Order now](https://puqcloud.com/whmcs-module-proxmox-kvm.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Proxmox-KVM/) | [FAQ](https://faq.puqcloud.com/)

WHMCS Configurable Options allow clients to customize their virtual machine resources at order time and during upgrades. The PUQ Proxmox KVM module reads configurable option values and uses them to override the product's default settings during provisioning and change package operations.

> **New in v3.3.** Eleven new options (every disk size / bandwidth / IOPS parameter plus Network Bandwidth) and clean plain-English names for the four previously prefix-only ones (`Backups`, `Snapshots`, `IPv4 Addresses`, `IPv6 Addresses`). Every overridable resource also has a default in Module Settings, so a product works without any Configurable Options at all.

![Full list of Configurable Options assigned to a product](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-sl8xtgfx.png)

The screenshot above shows all 18 supported options assigned to a single product. The next screenshot shows how a client sees them on the order form:

![Client order form with Configurable Options](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-zvoatpqd.png)

---

## Overview

Configurable Options provide a way to offer multiple resource tiers within a single product. For example, you can create one "KVM VPS" product with configurable options for CPU, RAM, and disk, letting clients pick their desired configuration and pricing tier at checkout.

When a configurable option is set on an order, its value takes precedence over the corresponding product-level default configured in the Module Settings.

---

## Setup

1. Navigate to **Setup > Products/Services > Configurable Options**
2. Click **Create a New Group**
3. Name the group (e.g., "KVM VPS Options")
4. Add individual options as described below
5. Assign the group to your PUQ ProxmoxKVM product(s) using the **Assigned Products** tab

---

## Supported Configurable Options

The module recognizes the following configurable option names. The **Option Name** must match exactly (case-sensitive) for the module to detect and apply the value.

### Compute Resources

| Option Name | Type | Description | Example Values |
|-------------|------|-------------|----------------|
| **CPU Cores** | Dropdown | Number of virtual CPU cores | `1`, `2`, `4`, `8`, `16` |
| **RAM** | Dropdown | Memory size in GB | `1`, `2`, `4`, `8`, `16`, `32` |

### Backups & Snapshots

| Option Name | Type | Description | Example Values |
|-------------|------|-------------|----------------|
| **Backups** | Dropdown | Maximum number of backups for the service (0 = backups disabled) | `0`, `3`, `7`, `14`, `30` |
| **Snapshots** | Dropdown | Maximum number of snapshots for the service (0 = snapshots disabled) | `0`, `1`, `3`, `5`, `10` |

### Storage

| Option Name | Type | Description | Example Values |
|-------------|------|-------------|----------------|
| **System Disk** | Dropdown | Boot disk size in GB | `10`, `20`, `40`, `80`, `160` |
| **Additional Disk** | Dropdown | Secondary disk size in GB (0 = no additional disk) | `0`, `10`, `20`, `50`, `100` |
| **System Disk Read Bandwidth** | Dropdown | System disk read throughput limit in MB/s | `0`, `50`, `100`, `200` |
| **System Disk Write Bandwidth** | Dropdown | System disk write throughput limit in MB/s | `0`, `50`, `100`, `200` |
| **System Disk Read IOPS** | Dropdown | System disk read IOPS limit | `0`, `500`, `1000`, `5000` |
| **System Disk Write IOPS** | Dropdown | System disk write IOPS limit | `0`, `500`, `1000`, `5000` |
| **Additional Disk Read Bandwidth** | Dropdown | Additional disk read throughput limit in MB/s | `0`, `50`, `100` |
| **Additional Disk Write Bandwidth** | Dropdown | Additional disk write throughput limit in MB/s | `0`, `50`, `100` |
| **Additional Disk Read IOPS** | Dropdown | Additional disk read IOPS limit | `0`, `500`, `1000` |
| **Additional Disk Write IOPS** | Dropdown | Additional disk write IOPS limit | `0`, `500`, `1000` |

### Network

| Option Name | Type | Description | Example Values |
|-------------|------|-------------|----------------|
| **Network Bandwidth** | Dropdown | Network bandwidth limit in MB/s (0 = unlimited) | `0`, `10`, `50`, `100`, `1000` |
| **IPv4 Addresses** | Dropdown | Number of IPv4 addresses to allocate from the pool | `1`, `2`, `4`, `8` |
| **IPv6 Addresses** | Dropdown | Number of IPv6 addresses to allocate from the pool | `0`, `1`, `4`, `16` |

### Operating System

| Option Name | Type | Description | Example Values |
|-------------|------|-------------|----------------|
| **Operating System** | Dropdown | OS template selection (Proxmox template VM ID) | Template IDs from Proxmox |

---

## Creating a Configurable Option

For each option:

1. Click **Add New Configurable Option** in your group
2. Set the **Option Name** to match one of the supported names above
3. Set the **Option Type** to **Dropdown**
4. Add sub-options with the format: `value|Display Name`

### Compute resources

#### Example: CPU Cores

```
Option Name: CPU Cores
Option Type: Dropdown

Sub-options:
1|1 Core
2|2 Cores
4|4 Cores
8|8 Cores
16|16 Cores
```

#### Example: RAM

```
Option Name: RAM
Option Type: Dropdown

Sub-options:
1|1 GB
2|2 GB
4|4 GB
8|8 GB
16|16 GB
32|32 GB
```

### Backups & Snapshots

#### Example: Backups

```
Option Name: Backups
Option Type: Dropdown

Sub-options:
0|No backups
3|3 backups
7|7 backups
14|14 backups
30|30 backups
```

#### Example: Snapshots

```
Option Name: Snapshots
Option Type: Dropdown

Sub-options:
0|No snapshots
1|1 snapshot
3|3 snapshots
5|5 snapshots
10|10 snapshots
```

### Storage — size

#### Example: System Disk

```
Option Name: System Disk
Option Type: Dropdown

Sub-options:
10|10 GB
20|20 GB
40|40 GB
80|80 GB
160|160 GB
```

#### Example: Additional Disk

```
Option Name: Additional Disk
Option Type: Dropdown

Sub-options:
0|No additional disk
10|10 GB
20|20 GB
50|50 GB
100|100 GB
500|500 GB
```

> **Note:** `0` means no additional disk required by the package. If a disk already exists on the VM, the module does not delete it — the existing disk is preserved.

### Storage — I/O limits

#### Example: System Disk Read Bandwidth

```
Option Name: System Disk Read Bandwidth
Option Type: Dropdown

Sub-options:
0|Unlimited
50|50 MB/s
100|100 MB/s
200|200 MB/s
500|500 MB/s
```

#### Example: System Disk Write Bandwidth

```
Option Name: System Disk Write Bandwidth
Option Type: Dropdown

Sub-options:
0|Unlimited
50|50 MB/s
100|100 MB/s
200|200 MB/s
500|500 MB/s
```

#### Example: System Disk Read IOPS

```
Option Name: System Disk Read IOPS
Option Type: Dropdown

Sub-options:
0|Unlimited
500|500 IOPS
1000|1000 IOPS
2500|2500 IOPS
5000|5000 IOPS
```

#### Example: System Disk Write IOPS

```
Option Name: System Disk Write IOPS
Option Type: Dropdown

Sub-options:
0|Unlimited
500|500 IOPS
1000|1000 IOPS
2500|2500 IOPS
5000|5000 IOPS
```

#### Example: Additional Disk Read Bandwidth

```
Option Name: Additional Disk Read Bandwidth
Option Type: Dropdown

Sub-options:
0|Unlimited
50|50 MB/s
100|100 MB/s
200|200 MB/s
```

#### Example: Additional Disk Write Bandwidth

```
Option Name: Additional Disk Write Bandwidth
Option Type: Dropdown

Sub-options:
0|Unlimited
50|50 MB/s
100|100 MB/s
200|200 MB/s
```

#### Example: Additional Disk Read IOPS

```
Option Name: Additional Disk Read IOPS
Option Type: Dropdown

Sub-options:
0|Unlimited
500|500 IOPS
1000|1000 IOPS
2500|2500 IOPS
```

#### Example: Additional Disk Write IOPS

```
Option Name: Additional Disk Write IOPS
Option Type: Dropdown

Sub-options:
0|Unlimited
500|500 IOPS
1000|1000 IOPS
2500|2500 IOPS
```

> **Note:** For bandwidth / IOPS options, `0` means **unlimited** — the value is omitted from the disk config string sent to Proxmox.

### Network

#### Example: Network Bandwidth

```
Option Name: Network Bandwidth
Option Type: Dropdown

Sub-options:
0|Unlimited
10|10 MB/s
50|50 MB/s
100|100 MB/s
500|500 MB/s
1000|1 GB/s
```

#### Example: IPv4 Addresses

```
Option Name: IPv4 Addresses
Option Type: Dropdown

Sub-options:
1|1 IPv4
2|2 IPv4
4|4 IPv4
8|8 IPv4
16|16 IPv4
```

#### Example: IPv6 Addresses

```
Option Name: IPv6 Addresses
Option Type: Dropdown

Sub-options:
0|No IPv6
1|1 IPv6
4|4 IPv6
16|16 IPv6
```

> **Note:** Setting either count to `0` means «no addresses of that family will be allocated from the IP pool for this service». Upgrades that lower the count automatically release the excess addresses back to the pool.

### Operating System

#### Example: Operating System

```
Option Name: Operating System
Option Type: Dropdown

Sub-options:
9001|Ubuntu 22.04 LTS
9002|Debian 12
9003|AlmaLinux 9
9004|Windows Server 2022
```

> **Note:** The sub-option values for **Operating System** must be the Proxmox template VM IDs. The display names can be human-readable OS names.

---

## Pricing

Each sub-option can have its own pricing configured per billing cycle. Navigate to the sub-option's pricing section to set monthly, quarterly, semi-annual, and annual prices.

For options where `0` means "not configured" or "unlimited" (such as Additional Disk = 0, Network Bandwidth = 0), you would typically set the price for the `0` sub-option to $0.00.

---

## Upgrade/Downgrade

When a client upgrades or downgrades their service through the WHMCS client area, the module automatically detects the changed configurable option values and triggers a **change package** operation. This operation updates the VM's resources on Proxmox to match the new configuration.

The change package process is logged step-by-step in the [Deploy Log](02-service-management.md#deploy-log) and can be monitored from the admin service management page.

---

## Disk size constraints

**System Disk and Additional Disk size can only be increased.** Proxmox does not support shrinking VM disks (it would risk corrupting/losing data), so any configurable option that would result in a smaller disk than the current size is rejected by the module.

![Client upgrade page with shrink protection — smaller disk options are disabled with a clear warning banner](https://doc.puq.info/uploads/images/gallery/2026-05/embedded-image-skfvpfxj.png)

### How it is enforced

The module applies the constraint at three layers:

1. **Client-area upgrade page** — on `/clientarea.php?action=upgrade&type=configoptions`, sub-options whose value is smaller than the currently selected one are visually disabled in the System Disk / Additional Disk dropdowns and marked `(downgrade not allowed)`. A warning banner is shown above the form.
2. **Change-package state machine** — if a smaller value still reaches the backend (e.g. via direct admin edit), the `Resize system disk` / `Resize additional disk` step is skipped with status `skip — shrink not allowed by Proxmox`. The VM is **not** stopped, snapshots are **not** removed, and the step is logged via `logModuleCall` under the action name `system_disk_shrink_rejected` / `additional_disk_shrink_rejected`.
3. **Post-backup-restore re-apply** — when the module re-applies package configuration after a backup restore, a smaller package disk size is treated the same way: the resize is silently skipped, the existing larger disk is kept, and the rejection is logged.

### Resulting behaviour for clients

- A client picking a smaller System Disk / Additional Disk in an upgrade order cannot submit it — the option is disabled in the UI.
- If by some path a smaller value reaches the change-package operation, the **disk size stays unchanged**. All other configurable options in the same change-package operation (CPU, RAM, bandwidth, IOPS, IPv4/IPv6 count, etc.) are still applied normally.

### Additional Disk special cases

- `Additional Disk = 0` with no existing disk → no action.
- `Additional Disk = 0` with **existing disk** → the existing disk is **detached and deleted**. VM is stopped first, all snapshots are removed (Proxmox requires this for detach), the disk interface is removed from the VM config, and the disk file is purged from storage. **All data on the additional disk is lost.** Logged via `logModuleCall` under `additional_disk_deleted`.
- `Additional Disk` increased from `0` to `N` → new disk is created with size `N` GB.
- `Additional Disk` increased from `N` to `M > N` → disk is resized in place (no data loss).
- `Additional Disk` decreased while > 0 (e.g. from `50` to `20`) → treated as shrink, rejected, current size kept.

> **Note for clients:** The upgrade form shows a confirmation dialog before submitting an Additional Disk = `0` change. The sub-option is also labeled `(removes the existing disk — data will be lost)` in the dropdown to make the destructive effect visible.

> **Note for admins:** If you do not want clients to be able to delete the additional disk via the configurable option, omit the `0|...` sub-option from the Additional Disk dropdown — make the lowest entry the minimum disk size you offer (e.g. `10|10 GB`).

---

## Priority Order

When determining the final value for a VM resource, the module follows this priority:

1. **Configurable Option value** (highest priority — applied whenever the option is assigned to the service, including a value of `0`)
2. **Product Module Settings default** (used only when no configurable option for that resource is assigned to the service)

Every overridable resource has a default in **Module Settings** for the product. If you do not create a Configurable Option for a resource, that default is used for every service of the product. The defaults live in:

| Resource | Module Settings location | Default value (if you don't set it) |
|---|---|---|
| CPU Cores | VM Configuration → CPU | `1` |
| RAM | VM Configuration → RAM | `1` GB |
| Backups | VM Configuration → Backups | `0` (disabled) |
| Snapshots | VM Configuration → Snapshots | `0` (disabled) |
| System Disk size + bandwidth + IOPS | Storage → System Disk | `0` (no change) |
| Additional Disk size + bandwidth + IOPS | Storage → Additional Disk | `0` (no additional disk) |
| Network Bandwidth | Network → Bandwidth | `0` (unlimited) |
| IPv4 count | Network → IPv4 count | `1` |
| IPv6 count | Network → IPv6 count | `0` |
| Operating System | VM Configuration → OS template | `configoption4` (default OS template) |

`0` is a meaningful value for many options and is **always** applied when a client selects it through a Configurable Option:
- `Additional Disk` = `0` → existing disk is **detached and deleted** (data lost)
- `Network Bandwidth` = `0` → unlimited
- `*Bandwidth` / `*IOPS` = `0` → unlimited
- `IPv4 Addresses` / `IPv6 Addresses` = `0` → no address of that family (existing addresses are released back to the pool)
- `Backups` / legacy `B|Backup` = `0` → backups disabled for the service
- `Snapshots` / legacy `S|Snapshot` = `0` → snapshots disabled for the service

This means you can set conservative defaults in the product configuration and allow clients to customize resources both upward (more CPU/RAM/disk) and downward (disable additional disk, set unlimited bandwidth) through configurable options.

---

## Legacy prefix-based option names (v1.x–v2.x)

> **Still supported in v3.0.** In v1.x–v2.x, PUQ Proxmox KVM used a **prefix-based convention** for configurable option names where the prefix identified the option type and the display name was free text. If you upgraded from an older version, your existing configurable options continue to work without any changes — the module recognizes both the legacy prefix-based names and the v3.0 plain names.

The legacy convention uses an Option Name of the form `PREFIX|Display Name` (the text on the right of the `|` can be whatever you want — "My Backup Offer", "Sicherung", etc.) and sub-options of the form `value|Display Name`.

| Legacy Option Name | Sub-option format | Meaning |
|--------------------|-------------------|---------|
| `B\|Backup` | `<count>\|Name` | Number of allowed backups (0 disables backups for the service) |
| `S\|Snapshot` | `<count>\|Name` | Number of allowed snapshots (0 disables snapshots for the service) |
| `CPU\|Processor` | `<count>\|Name` | Number of CPU cores |
| `RAM\|Memory` | `<count>\|Name` | RAM in GB |
| `ipv4\|IPv4` | `<count>\|Name` | Number of IPv4 addresses to allocate |
| `ipv6\|IPv6` | `<count>\|Name` | Number of IPv6 addresses to allocate |
| `OS\|Operating system` | `<template_id>\|Name` | Proxmox template VM ID to clone from |

### Legacy example: Operating System

```
Option Name: OS|Operating system
Option Type: Dropdown

Sub-options:
1010|Debian-10.12
1011|Debian-11
1012|Debian-12
1021|Ubuntu-20.04
1022|Ubuntu-22.04
```

The sub-option values are the Proxmox template VMIDs (e.g. `1010` = a template VM in Proxmox with ID 1010 based on Debian 10). The module uses the number on the left of the `|` to call `qm clone`; the text on the right is shown to the admin/client in the order form.

### Legacy example: Backup

```
Option Name: B|Backup
Option Type: Dropdown

Sub-options:
0|No backups
3|3 backups
7|7 backups
14|14 backups
```

### Legacy example: Snapshot

```
Option Name: S|Snapshot
Option Type: Dropdown

Sub-options:
0|No snapshots
1|1 snapshot
3|3 snapshots
5|5 snapshots
10|10 snapshots
```

### Legacy example: CPU

```
Option Name: CPU|Processor
Option Type: Dropdown

Sub-options:
1|1 Core
2|2 Cores
4|4 Cores
8|8 Cores
16|16 Cores
```

### Legacy example: RAM

```
Option Name: RAM|Memory
Option Type: Dropdown

Sub-options:
1|1 GB
2|2 GB
4|4 GB
8|8 GB
16|16 GB
```

### Legacy example: IPv4

```
Option Name: ipv4|IPv4
Option Type: Dropdown

Sub-options:
1|1 IPv4
2|2 IPv4
4|4 IPv4
8|8 IPv4
```

### Legacy example: IPv6

```
Option Name: ipv6|IPv6
Option Type: Dropdown

Sub-options:
0|No IPv6
1|1 IPv6
4|4 IPv6
16|16 IPv6
```

### Which format should I use?

- **New installations** — use the plain v3.0 names shown higher on this page (`CPU Cores`, `RAM`, `System Disk`, etc.).
- **Upgrades from v1.x/v2.x** — keep using your existing prefix-based names. They are still recognized and require no changes. Migrating them to the new names is optional and purely cosmetic.
- **Mixing both** — not recommended, but technically allowed. If both a legacy `CPU|Processor` and a new `CPU Cores` option are assigned to the same product, the plain v3.0 name wins.


<!-- sync:7a2e4901c08716e2 -->