WHMCS

Install the VMStack provisioning module in WHMCS, connect it to the panel, set up products, configurable options, add-ons, usage billing and the client area.

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#

  1. Get the module package (see Integrations).
  2. 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#

  1. In WHMCS go to System Settings › Servers › Add New Server.
  2. Module: VMStack.
  3. Hostname: the panel's domain, such as panel.example.com. A scheme, a path or a trailing /api/v1 are stripped; host:port is accepted. If Hostname is empty the IP Address field is used.
  4. Password: the API key (vmk_…). Username and Port are not used; HTTPS with certificate checks is always used, whatever the Secure box says.
  5. 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#

  1. Create a product of type Server/VPS and, on its Module Settings tab, choose VMStack and the server (group) above.
  2. 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 Plan option.
  • 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.