The WHMCS module (version 0.1.3) is a provisioning (server) module. It creates the customer's panel account and server on order, follows suspensions, terminations and package changes, shows a client area with power, console, rescue, reinstall, reverse DNS and port forwards, and can bill traffic and hourly usage.
Requirements#
- WHMCS 8.x on PHP 8.1, 8.2 or 8.3. Metric Billing needs WHMCS 7.9 or later (any 8.x has it).
- The panel reachable from the WHMCS server over HTTPS with a valid certificate. Plain HTTP is refused.
- A panel API key as described in API key for a billing system.
Install#
- Get the module package (see Integrations).
- Upload the folder
modules/servers/vmstack/into your WHMCS installation, so that this file exists:
<whmcs>/modules/servers/vmstack/vmstack.php
The folder holds vmstack.php, hooks.php, logo.png, lib/ and templates/clientarea.tpl. Nothing else is needed: the module uses WHMCS's bundled Guzzle when present, else PHP's cURL, and needs no Composer.
To update, replace the folder with the new one.
Connect to the panel#
- In WHMCS go to System Settings › Servers › Add New Server.
- Module: VMStack.
- Hostname: the panel's domain, such as
panel.example.com. A scheme, a path or a trailing/api/v1are stripped;host:portis accepted. If Hostname is empty the IP Address field is used. - Password: the API key (
vmk_…). Username and Port are not used; HTTPS with certificate checks is always used, whatever the Secure box says. - Press Test Connection.
Test Connection calls the panel's GET /me and fails when:
- the key belongs to a user ("The key belongs to a user account; use an administrator's or a reseller's key."),
- a required scope is missing ("Missing scopes the module uses: …").
The full summary (account, key, scopes, and notes on placement and add-ons, such as "Placement: locations only; add infrastructure:read to list node groups and nodes.") is written to the module log (System Logs › Module Log). WHMCS shows it only when the test fails.
Product setup#
- Create a product of type Server/VPS and, on its Module Settings tab, choose VMStack and the server (group) above.
- Fill in the settings:
| # | Setting | Default | Meaning |
|---|---|---|---|
| 1 | Plan | – | The panel plan (active plans, shown with their size). A Plan configurable option overrides it. |
| 2 | Placement | – | "Location: …", "Group: …" or "Node: …". A Location or Node Group option overrides it. Groups and nodes are listed only for an administrator's key with infrastructure:read. |
| 3 | Default image | – | Used when the order has no Operating System option. |
| 4 | Hostname | empty | A pattern with {serviceid}, {clientid}, {domain}, such as vps{serviceid}.example.com. Empty: the panel picks a name. |
| 5 | Send welcome password | off | Stores the server's root password as the service password, for the welcome mail. Needs servers:secrets. Off: the service password is cleared. |
| 6 | Account level for new clients | User | Always User. |
| 7 | Allow the client to create servers in the panel | off | Sets May create and delete servers on a new account. |
| 8 | Delete the panel account on terminate | off | Deletes the customer's panel account after its last server is deleted. Refusals (it still has servers) are only logged. |
| 9 | Single sign-on | on | Shows Open control panel in the client area. |
| 10 | Bind sign-in links to the client's address | on | Sign-in and console links work only from the address the client used in WHMCS. Turn it off when clients reach WHMCS and the panel through different networks or address families. |
| 11 | Usage billing | None | None; Traffic (bandwidth and disk); Hourly (traffic, plus Metric Billing). See below. |
| 12 | Reseller for new accounts (administrator keys) | empty | The panel ID of the reseller new accounts go under. Empty: the panel's own customers. Ignored with a reseller's key. |
| 13 | Customer sets up the server | off | The server waits in Awaiting setup and the customer chooses the OS, hostname and keys in the panel (customer setup). No OS, application or keys are sent; the image is optional. |
Create fails with a clear message when no plan, placement or image (unless setting 13 is on) is set either here or by an option.
The panel plan decides the size, traffic, trial, reinstall limit and what the customer may do; see Plans and Customer permissions.
Configurable options#
Option names are matched on the part before |, without regard to case. Values are ID|Label; the module reads the ID.
| Option name | Values | Effect |
|---|---|---|
Plan |
panel plan IDs | overrides setting 1 |
Location |
location IDs | overrides setting 2, wins over Node Group |
Node Group |
node group IDs | overrides setting 2 |
Operating System |
image IDs | overrides setting 3 |
Application |
`slug | Name, and none |
For Application: email fields of the application get the client's email; a required text field without a default makes the create fail; if the application does not run on the ordered image, its first image is used (logged). See One-click apps.
Add-ons#
These options add to what the plan gives. Each can be a quantity option or a dropdown with values <number>|<label>. Without the option, that part of the server is left as the panel has it.
| Option name | Adds | Needs |
|---|---|---|
Extra IPv4 |
IPv4 addresses | – |
Extra IPv6 |
IPv6 addresses | – |
Extra Disk Space |
GB of extra disk; with no Extra Disks option one disk is made at create |
administrator key, disks:write |
Extra Disks |
how many extra disks the customer may add | administrator key, and Extra Disk Space |
Extra Snapshots |
snapshots kept (at most 20) | administrator key |
Extra Traffic |
GB a month (ignored on a plan without a traffic limit) | administrator key |
Extra Port Forwards |
NAT port forwards (NAT servers only, at most 1000) | – |
The repository's examples/configurable-options.sql creates a "VMStack add-ons" group with example prices; edit @currency and @product before running it.
On a package change the add-ons are applied again. Lowering one deletes nothing, except extra addresses (the newest first, never the main one).
Custom fields#
Add these product custom fields yourself (the module never creates any). They can be admin-only.
| Field name | Purpose |
|---|---|
vmstack_server_id |
The panel server's ID, written at create. Recommended: without it the server is found by the service ID, and usage sync covers only services that have it. To link an existing server, type its ID here. |
SSH public key |
Text area shown on the order form, one key per line. With no key, SSH password login is turned on. |
vmstack_ssh_port |
Optional: stores a NAT server's SSH forward port. |
The module also writes the service's Dedicated IP (the main public IPv4, else the NAT address), Assigned IPs (other IPv4 and IPv6) and Domain (the hostname).
What the module does#
| WHMCS action | Panel |
|---|---|
| Create | finds or creates the client's account, creates the server (waits up to 20 s; a server still building counts as success), then applies the add-ons |
| Suspend | suspends the server with WHMCS's reason, else "Overdue invoice". The customer's account stays active. |
| Unsuspend | lifts that suspension |
| Terminate | deletes the server and waits up to 20 s for the task; a server already gone counts as done |
| Change Package | upgrades to the new plan, then re-applies add-ons. Downgrades are refused by the panel. |
| Change Password | resets the server's root password |
There are no admin custom buttons. The admin services tab shows the panel server (with a link), status, suspension, plan, location, node, addresses with reverse DNS, NAT SSH port and forwards, and this month's traffic. Import (ListAccounts) lists every server the key sees, matched by hostname.
A hook sends a client's new email address to the linked panel account. Deleting a client in WHMCS does nothing in the panel.
Client area#
On the service's overview:
- Power: Start, Shut down, Reboot, Power off.
- Console: a one-time console link in a new tab (shown even with single sign-on off).
- Rescue: Start rescue and End rescue; while in rescue, the SSH command and Show password (needs
servers:secrets). - Reinstall: an image from those the server's plan allows, an optional new root password, confirmed by typing the hostname.
- Reset root password.
- Reverse DNS for each public IPv4 and single IPv6 address.
- Port forwards on NAT servers: list, add (TCP, UDP or both; public port 1024 to 65535 or a free one), delete, and a link to manage them in the panel.
- Traffic this month and the application's install state.
- Open control panel (single sign-on into the server's page), or Set up your server while it awaits setup.
Actions are sent on behalf of the customer, so the plan's switches and reinstall limit apply: a refused action shows the panel's sentence, such as "Your plan does not include rescue." A suspended service shows its status and addresses only. Firewall, backups, snapshots, ISO drives, charts and hostname changes are done in the panel.
Usage billing#
With Usage billing set to Traffic or Hourly, WHMCS's daily usage update reads the panel's traffic for the month:
- Bandwidth used and the limit (the plan's traffic, 0 for none).
- Disk usage and limit: the server's disk size.
With Hourly, the product's Metric Billing gets these metrics: vcpu_hours, memory_gb_hours, disk_gb_hours, ipv4_hours, ipv6_hours, traffic_gb, traffic_overage_gb and extra_disk_gb (the current size, not GB-hours). Set a price per metric in the product's pricing. A server awaiting setup is counted from its creation.
Limitations#
- No CPU, memory or disk sliders: one panel plan per size, chosen by product or
Planoption. - No plan downgrades.
- No single sign-on for WHMCS staff into the panel; no admin custom buttons.
- No backups or snapshots management in the client area.
- Snapshots, extra disks and traffic add-ons need an administrator's key (a reseller's key gets 403).
- Import matches existing servers by hostname only.