Installation and Configuration Guide Step-by-step instructions for installing, configuring and setting up the PUQVPNCP WHMCS module — panel preparation, WHMCS integration, server configuration, location routing and product configuration. WHMCS Installation and Update PUQVPNCP module WHMCS Order now | Download | Community | PUQVPNCP | Order PUQVPNCP System requirements Important: This module works exclusively with PUQVPNCP and requires version 2.x or higher (PUQVPNCP Website | Order PUQVPNCP). Requirement Minimum WHMCS 8.x+, 9.x+ PHP 7.4, 8.1, 8.2, 8.3, 8.4 PUQVPNCP panel v2.x and higher ionCube Loader v15+ Note: The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server. Installation Note: The module now uses ionCube 15, which provides universal out-of-the-box support for all encodings. All versions can be found at this link: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-PUQVPNCP/ Older module versions for WHMCS 8 are available in the archive directory: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-PUQVPNCP/archive/ Download the latest version from the PUQ download page: wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-PUQVPNCP/PUQ_WHMCS-PUQVPNCP-latest.zip Unzip the archive: unzip PUQ_WHMCS-PUQVPNCP-latest.zip -d PUQ_WHMCS-PUQVPNCP-latest Upload the module files to your WHMCS installation: For Server modules: copy the puqVPNcp directory from the unzipped folder to whmcs/modules/servers/ cp -r PUQ_WHMCS-PUQVPNCP-latest/puqVPNcp /path/to/whmcs/modules/servers/ The module files are now in place. Proceed to the PUQVPNCP setup guide and configuration. Update The update procedure is the same as installation — replace the existing files with the new version: Download the latest version as described in the Installation section. Unzip the archive. For server modules: simply overwrite the files in whmcs/modules/servers/puqVPNcp/. No deactivation is needed. Verify the version number in the module interface matches the new release. Setup guide — PUQVPNCP panel PUQVPNCP module WHMCS Order now | Download | Community | PUQVPNCP | Order PUQVPNCP Important: This module works exclusively with PUQVPNCP and requires version 2.x or higher (PUQVPNCP Website | Order PUQVPNCP). Before you can connect WHMCS, you need a running PUQVPNCP panel (v2.x or higher), an API token that WHMCS will use for every operation, and at least one VPN network with the protocols you want to expose enabled (WireGuard, AmneziaWG, OpenVPN, IKEv2). This page walks through both. 1. Panel reachability The panel must be reachable from the WHMCS server over the network. HTTPS is strongly recommended. If you use a self-signed certificate, remember that SSL verification is enabled when the Secure checkbox is ticked on the WHMCS server record — use a publicly trusted certificate, or place the panel behind a reverse-proxy with one. 2. Issue an API token The module authenticates to the panel with a Bearer token issued from the admin's profile page. Step 1 — Open Profile Click your username in the top-right corner of the panel and select Profile. 26-puqvpncp-profile-menu.png Step 2 — Open the API Tokens section Scroll down to the API Tokens card. Click the green + button on the right to create a new token. 27-puqvpncp-profile-tokens.png Step 3 — Create the token Fill in the modal: Token name — a label that identifies the consumer, e.g. whmcs. IP restriction (optional) — a comma-separated list of IPs allowed to use this token. Leave empty to accept the token from any IP, or set it to your WHMCS server's IP for tighter security. Expires (optional) — an expiration date. Leave empty for a non-expiring token. Click Save. 28-puqvpncp-token-create.png Step 4 — Copy the Bearer token The next dialog shows the Bearer Token. Click Copy and store it somewhere safe — the token is shown only once and cannot be retrieved later. If you lose it, delete the token and generate a new one. 29-puqvpncp-token-bearer.png The token grants the user's effective permissions — the admin group used in the screenshot has full access. For tighter control, create a dedicated user/permission group on the panel and issue a token for that user instead. You will paste this token into the Password field of the WHMCS server record — see Add server. 3. Create a VPN network The module needs at least one VPN network on the panel. On the WHMCS product configuration page, every available network is listed as a tickable server → network pair. Step 1 — Open the Networks list In the top menu, open Networks → List of networks. 30-puqvpncp-networks-menu.png The list shows every existing network with the status of WireGuard / OpenVPN / IKEv2, the IPv4 subnet, the upstream interface and the bandwidth caps. 31-puqvpncp-networks-list.png Step 2 — Add a network Click the green + button in the top-right corner of the Networks page. Fill the Create form: Name — internal identifier of the network (used in the WHMCS product configuration). Description (optional) — human-readable note. Subnet (IPv4 CIDR) — VPN subnet that will be assigned to clients (e.g. 10.0.6.0/24). WireGuard IP / OpenVPN IP / IKEv2 IP — gateway addresses for each protocol inside the subnet. Upstream — the host network interface used as the egress for this VPN network. VPN Domain (optional) — overrides the global VPN Domain in all client configs for this network. DNS 1 / DNS 2 — DNS servers pushed to clients. Bandwidth Download / Upload — network-wide caps in Mbit/s (0 = unlimited). Disable NAT — leave unchecked unless you route the VPN subnet upstream yourself. Click the green ✓ in the top-right to save. Protocols (WireGuard / OpenVPN / IKEv2) are configured after the network is created. 32-puqvpncp-network-create.png Step 3 — Enable protocols on the network After saving, you land on the network's Edit page with a row of tabs (Main / WireGuard / AmneziaWG / OpenVPN / IKEv2 / Port Forwarding / Routes / Firewall / Clients / Traffic Control / Traffic) and a Protocols card on the right. Tick Enabled for every protocol you want to offer to customers via WHMCS. The WHMCS module reads this state from GET /api/v1/network/{name} — disabled protocols are hidden in the client area and shown greyed-out (with a tooltip) in the admin service tab. 33-puqvpncp-network-edit-protocols.png Open each protocol-specific tab (WireGuard, AmneziaWG, OpenVPN, IKEv2) to fine-tune ports, ciphers, MTU and other parameters as needed. Defaults are sensible for most deployments. What's next Add the panel to WHMCS — see Add server. Configure a WHMCS product backed by this panel — see Product configuration. Add server (PUQVPNCP panel) PUQVPNCP module WHMCS Order now | Download | Community | PUQVPNCP | Order PUQVPNCP Add a PUQVPNCP panel to WHMCS Navigate to System Settings → Servers → Add New Server. Step 1 — General settings Name — a descriptive label (e.g. VPN Frankfurt). Hostname — the panel's fully-qualified hostname (e.g. vpn-fra.example.com). IP — optional; used as fallback if hostname is empty. Port — leave empty for the default 80/443, or enter a custom port. Secure — check when the panel is served over HTTPS (strongly recommended). SSL verification is enabled when this is checked. 04-add-server-1.png Step 2 — Module settings Server Details section, Type dropdown: select puqVPNcp. Leave Username empty (not used). Paste the panel's API token into the Password field — this is what the module sends as Authorization: Bearer for every API call. Click Test connection — it verifies that the panel is running PUQVPNCP v2.x or higher, calls /api/v1/system/status, /api/v1/license and /api/v1/network, and returns OK on success. 05-add-server-2.png Important: The API token must have permissions to manage clients, query networks and read system status. Step 3 — Assign to a server group For multi-server deployments, add the server to a WHMCS server group. Products bound to that group will list networks from every reachable server in it on the VPN Networks tree of the product configuration page — pick which server → network pairs are allowed for that product. Product configuration PUQVPNCP module WHMCS Order now | Download | Community | PUQVPNCP | Order PUQVPNCP Create the product Navigate to System Settings → Products/Services → Products/Services → Create a New Product. Product Type: Other. Give it a name (e.g. VPN — 100 Mbit/s). On the Module Settings tab, pick PUQ VPNcp as the module and assign a server (or a server group). After saving, the module injects a PUQ VPNcp settings panel below the standard module fields. All settings are persisted as JSON in configoption24 of the product record. 06-product-configuration.png License key Paste your licence key into the License key field. The status row underneath shows the result of the most recent verification (success: or an error). The module re-checks the licence on every product page render and caches the result for the validity period encoded in the licence response. Bandwidth 07-product-config-bandwidth.png Download limit (Mbit/s) — per-client download cap. 0 = unlimited. Upload limit (Mbit/s) — per-client upload cap. 0 = unlimited. The module applies these via PUT /api/v1/client/{name} right after creating the client. The POST /api/v1/client create call does not accept bandwidth fields — the limits are always pushed through the follow-up update. If the bandwidth update fails, the freshly created client is rolled back with DELETE /api/v1/client/{name} so billing never starts charging for an uncapped VPN. Client name 08-product-config-client-name.png Client name rule — template used to generate the VPN client identifier. Default: vpn-{client_id}-{service_id}-{random_letter_4}. Available macros: Base macros {client_id} — WHMCS client ID {service_id} — WHMCS service ID Random macros {random_digit_N} — N random digits (e.g. {random_digit_5}) {random_letter_N} — N random lowercase letters Date & time macros {unixtime}, {year}, {month}, {day}, {hour}, {minute}, {second} If the generated name already exists in tblhosting.username, the module appends -1, -2, … until it finds a free one. Client Area 09-product-config-client-area.png Link to instruction — optional URL shown as a User manual button at the top of the client-area home screen. Leave empty to hide the button. Show password — controls how the VPN password is displayed in the client area: Show button (hidden by default, revealed on button click), Plain text (always visible), or No (hidden entirely). Welcome Email 34-product-config-welcome-email.png Send the customer everything they need to connect the moment their service goes live — automatically. Send welcome email after account provisioning — when ticked, the module emails the client right after the VPN account is created. The message includes the connection details, protocol configuration files and QR codes (WireGuard, AmneziaWG, OpenVPN, IKEv2), a One-Time Link, and a direct button to manage the service. Email template — which WHMCS Product/Service email template to send. Leave it on Module default to use the bundled PUQ VPNcp - Welcome template, or pick any of your custom templates. Default template — a one-click manager for the bundled template: Create if missing — adds the PUQ VPNcp - Welcome template only if it does not exist yet (your edits are never overwritten). The badge shows EXISTS once it is in place. Reset to default — restores the shipped subject and body with all protocol blocks and Smarty conditionals. Template Merge Variables The email template supports Smarty tags and logic in Setup → Email Templates → Product/Services. You can use the following variables: Variable Type Description {$puq_client_name} String VPN client identifier assigned in the panel (e.g. vpn-1-105-a8f1) {$puq_vpn_ip} String Dedicated IPv4 address assigned to the VPN client inside the network {$puq_vpn_username} String Authentication username (used by OpenVPN and IKEv2) {$puq_vpn_password} String Authentication password (used by OpenVPN and IKEv2) {$puq_wg_config} String Full WireGuard .conf configuration text (empty if WireGuard is disabled on network) {$puq_wg_qr} String (Data URI) Base64 PNG data URI (data:image/png;base64,...) for embedding via {$puq_wg_qr_html} HTML Legacy inline element with WireGuard QR code {$puq_awg_config} String Full AmneziaWG configuration text including obfuscation headers (empty if disabled) {$puq_awg_qr} String (Data URI) Base64 PNG data URI (data:image/png;base64,...) for embedding via {$puq_awg_qr_html} HTML Legacy inline element with AmneziaWG QR code {$puq_openvpn_config} String Complete OpenVPN .ovpn configuration profile text (empty if OpenVPN is disabled) {$puq_ovpn_config} String Alias for {$puq_openvpn_config} {$puq_ikev2_config} String IKEv2 / IPsec connection profile and parameters (empty if IKEv2 is disabled) {$puq_otl_url} URL Single-use One-Time Link URL that opens a client onboarding page with all configs and QR codes {$puq_instruction_url} URL Link to user guide configured in product settings (Link to instruction) {$puq_service_url} URL Direct link to the client area service details page (clientarea.php?action=productdetails&id=...) {$puq_has_wireguard} String '1' if WireGuard is enabled on the network, '' otherwise {$puq_has_amneziawg} String '1' if AmneziaWG is enabled on the network, '' otherwise {$puq_has_openvpn} String '1' if OpenVPN is enabled on the network, '' otherwise {$puq_has_ikev2} String '1' if IKEv2 is enabled on the network, '' otherwise Dynamic Protocol Filtering Every protocol section in the bundled welcome template is wrapped in a Smarty conditional: {if $puq_wg_config} {/if} {if $puq_awg_config} {/if} {if $puq_openvpn_config} {/if} {if $puq_ikev2_config} {/if} {if $puq_otl_url} {/if} Automated Protocol Check: The module queries the authoritative protocol availability from the remote PUQVPNCP panel (GET /network/{name}) before sending. If a protocol is disabled on the assigned network, its configuration variable remains empty and Smarty automatically omits that section from the client's email. The template is also auto-created on the first send if it is still missing, so the feature works even if you never touch the template buttons. Speed presets (Configurable Options) 35-product-config-speed-presets.png WHMCS Configurable Options let your customers choose their own download/upload speed at order time and change it later through an upgrade/downgrade — turning a single product into a whole speed-tier line-up. The module reads the selected values and applies them to the VPN client, overriding the product's default bandwidth. Setting these up by hand is fiddly, so the module does it for you with one button. One-click creation Click Create speed presets and the module instantly builds and links everything: a configurable-option group PUQ VPNcp - Speed presets; two dropdown options — Download limit (Mbit/s) and Upload limit (Mbit/s); ready-made presets in each: Unlimited, 10, 25, 50, 100, 250, 500, 1000 Mbit/s, priced at 0 in every currency; a link from the group to the current product. The button is safe to click repeatedly — only missing pieces are added, so your prices and edits are preserved. The status badge reflects the current state: Not created yet → Created & linked. What gets created Option Name Type Reads as Preset sub-options (value|label) puqVPNcp_b_download|Download limit (Mbit/s) Dropdown per-client download cap (Mbit/s) 0|Unlimited, 10|10 Mbit/s, 25|25 Mbit/s, 50|50 Mbit/s, 100|100 Mbit/s, 250|250 Mbit/s, 500|500 Mbit/s, 1000|1000 Mbit/s puqVPNcp_b_upload|Upload limit (Mbit/s) Dropdown per-client upload cap (Mbit/s) same set as above The text before the | is the internal name the module matches on; the text after the | is what the customer sees. The sub-option value 0 means Unlimited. 36-configurable-options-assigned.png The group appears on the product's Configurable Options tab (already ticked under Assigned Option Groups) and under System Settings → Products/Services → Configurable Options. 37-configurable-options-group.png Pricing the tiers By default every preset is free (0.00), so customers can switch speeds at no cost. To monetise faster tiers, open each option and set per-cycle pricing on the sub-options — for example charge more for 500 Mbit/s than for 50 Mbit/s. 38-configurable-options-download.png 39-configurable-options-upload.png After changing pricing, save the product to refresh the panel status. How the value is applied Priority Source When used 1 (wins) Configurable Option selection whenever the option is assigned to the service (including 0 = unlimited) 2 Product Bandwidth default (Module Settings) when no speed option is assigned On provisioning and on every upgrade/downgrade (WHMCS calls the module's change-package routine for configurable-option changes too), the module pushes the resolved b_download / b_upload to the panel via PUT /api/v1/client/{name}. So a customer who upgrades from 100 Mbit/s to 500 Mbit/s gets the new speed applied automatically, with no manual work for you. Adding the speed options is optional. Skip the button and every service simply uses the product's Bandwidth defaults. VPN Networks 10-product-config-vpn-networks.png On opening the product, the module contacts every enabled puqVPNcp server in the product's server group and calls GET /api/v1/network on each. The UI then shows a per-server tree — unreachable servers remain visible with their error so you can see exactly what went wrong. License-slot capacity (used / total) is displayed next to each reachable server. Each checkbox is a server → network pair. Next to each network name, inline status badges indicate protocol availability: WireGuard (blue when enabled, strikethrough when disabled) AmneziaWG (purple when enabled, strikethrough when disabled) OpenVPN (cyan when enabled, strikethrough when disabled) IKEv2 (amber when enabled, strikethrough when disabled) Ticking the same network name on two different servers creates two independent pairs. How a server and network are picked at deploy time The module reads all ticked pairs in the order they appear in the list (top to bottom). For each pair it checks (a) free licence slots on that server (count_accounts < count_accounts_available from GET /api/v1/system/status) and (b) at least one free IP on the network (GET /api/v1/network/{name}/available_ip). The first pair that passes both checks wins. The service is reassigned (tblhosting.server is updated) to the selected server, and the client is created on the selected network via POST /api/v1/client. If nothing is ticked, network_name is omitted from the create call and the panel of the server WHMCS already picked decides automatically. If ticks exist but none is deployable (every chosen server is out of slots or every chosen network is full), provisioning fails — nothing is silently created on a wrong network. Because order matters, put your preferred pairs at the top. If the whole group is unreachable a red banner appears at the top of the section; previously saved ticks are preserved through hidden inputs so your configuration is not lost when you re-save the product. Metric Billing (optional) 11-product-config-metric-billing.png The module ships a WHMCS Usage Billing provider with two metrics: Bandwidth Usage Download (GB) Bandwidth Usage Upload (GB) Enable the metrics on the product's Pricing tab to charge customers per GB of traffic. The provider pulls daily totals directly from the panel via GET /api/v1/client/{name}/traffic/{Y}/{m} and reports them in gigabytes for the current calendar month. No local accumulation table is used — values come live from the panel each time WHMCS runs the usage-billing cron. Configure metric pricing Click Configure Pricing next to each metric to configure the billing scheme (Per Unit, Total Volume, or Graduated), the free included volume quota, and per-GB rates for all configured currencies: 42-product-config-pricing-download.png 43-product-config-pricing-upload.png