WHMCS

The VirtConsole module for WHMCS automates the instance lifecycle from order to termination. It covers:

• Creation, with optional OS selection, SSH key injection and hostname at order time
• Suspension and unsuspension
• Termination
• Package upgrades. Plan changes and the full add-on resource set are reconciled on the running instance; downgrades error where the storage size would shrink.
• Add-on resources at order time and on upgrade (extra vCPU, RAM, disk, bandwidth, IPv4 addresses, IPv6 /64 subnets)
• Power control, reinstall and password reset from the client area and the admin area
• One-click SSO from the client area into the panel

Before you begin

• A working panel with at least one instance plan and one image. See Quick setup.
• A billing API token, generated on the management server with vcli api:billing-token generate. See API tokens.
• WHMCS 9.x running PHP 8.2 or 8.3.

Install the module

The module is open source. Download it from https://packages.virtconsole.com/whmcs-virtconsole.zip, unzip it and copy the contents into the root directory of your WHMCS installation. The archive already contains the modules/servers/ structure, so nothing needs to be moved by hand.

Your module path should look like WHMCSROOT/modules/servers/virtconsole/virtconsole.php.

The archive also ships two companion provisioning modules under the same modules/servers/ tree:

• VirtConsole Credits (virtconsolecredits). Sells panel credit top-ups for Cloud Service, the built-in hourly billing.
• VirtConsole SP (virtconsolesp). Sells Self-Provisioning packs, prepaid resource pools that customers deploy instances into.

Both are ordinary WHMCS server modules. Configure them exactly like the main module: add a server of their type, then assign it on the product.

The folder contains:

File	Purpose
virtconsole.php	The provisioning module itself
client.php	Client area endpoint used for SSO, live status and instance actions
templates/overview.tpl	Client area instance panel
templates/error.tpl	Client area error state
whmcs.json	WHMCS Marketplace module metadata
logo.png	Module logo shown by WHMCS

The module is listed in WHMCS as VirtConsole Provisioning Module. As of 3.0.0 the internal module identifier is virtconsole: the folder, the function prefix, the mod_virtconsole table and the server type. Installs upgrading from a 2.x hypervisorv2 release run the one-time SQL migration in Upgrade notes. It preserves all data, and products re-link automatically once the server type matches.

Note

The module targets WHMCS 9.x and is compatible with PHP 8.2 and 8.3.

Caution

client.php must be uploaded along with the module. Without it the client area cannot fetch an SSO link, refresh live status or run any instance actions.

Configure the server connection

In the WHMCS admin area, add a new server and select VirtConsole as the server type. The Add New Server screen shows the connection fields below.

Field	What to enter
Hostname	Your management server hostname.
API Token	The billing API token generated with vcli api:billing-token generate. See API tokens.
Secure	Always tick this.

Note

A self-signed certificate, or connecting by IP address, works. The module does not reject the management server’s certificate. Where you can, still use a hostname with a valid certificate: the API token travels over this connection.

Use Test Connection to confirm the module can reach the panel before you assign the server to a product.

Product setup

On the product’s module settings page, pick the provisioning defaults for every order of this product.

Setting	Purpose
VirtConsole Master	The management server this product is provisioned on.
Plan	Any plan from your management server.
Hypervisor Group/Region	Instances deploy onto an available hypervisor from this group.
Hypervisor	A specific hypervisor. Used when Override Hypervisor Region/Group is ticked.
Override Hypervisor Region/Group	Tick to skip the group and deploy on the hypervisor selected above.

The same page carries the settings that govern order customization:

Setting	Type	Purpose
Max additional vCPU	Text	Per-product cap for the Additional vCPU configurable option.
Max additional RAM (GB)	Text	Per-product cap for the Additional RAM (GB) configurable option.
Max additional Disk (GB)	Text	Per-product cap for the Additional Disk (GB) configurable option.
Max additional Bandwidth (TB)	Text	Per-product cap for the Additional Bandwidth (TB) configurable option.
Max additional IPv4	Text	Per-product cap for the Additional IPv4 configurable option.
Max additional IPv6	Text	Per-product cap for the Additional IPv6 configurable option (/64 subnets).
Apply resource changes	Dropdown	At next reboot (default) or Restart now. How vCPU, RAM, disk and bandwidth changes are applied to a running instance after a plan or option change.
Client actions	Dropdown	Actions offered on the client-area card: Power only (default), Power + Reinstall, Power + Reinstall + Password, All actions (additionally enables the console deep link).
Order-form OS field	Yes/No	When ticked, the module adds an Operating System dropdown custom field to the order form.

A blank cap means the add-on is uncapped on this product; the management server’s hard limits still apply (see below). Quantities ordered above a cap are silently clamped to the cap.

Regardless of product caps, the management server refuses out-of-range values outright: vCPU 0-64, RAM 0-512 GB, disk 0-5000 GB, bandwidth 0-100 TB, additional IPv4 0-20 and additional IPv6 /64 subnets 0-5.

The settings page prints the image table (name, slug, UUID) fetched from the management server. Copy values from this table into your Operating System configurable option or custom field definitions. If the management server is unreachable, the table degrades to a warning row and the settings form keeps working.

Configurable options

Configurable options let a single product sell different plans, locations, operating systems and add-on resources. The module matches them by name, so the option name must be entered exactly as shown below.

Option name	Type	Value	Applied
Plan	Dropdown	Plan ID from the management server	Order and upgrade
Location	Dropdown	Hypervisor group ID	Order and upgrade
Operating System	Dropdown	Image UUID or slug (see the image value rule below)	Order
Additional vCPU	Quantity	Extra vCPU cores on top of the plan	Order and upgrade
Additional RAM (GB)	Quantity	Extra RAM in GB on top of the plan	Order and upgrade
Additional Disk (GB)	Quantity	Extra disk in GB on top of the plan. Grows the primary disk.	Order and upgrade
Additional Bandwidth (TB)	Quantity	Extra monthly bandwidth in TB on top of the plan	Order and upgrade
Additional IPv4	Quantity	Number of extra public IPv4 addresses	Order and upgrade
Additional IPv6	Quantity	Number of extra IPv6 /64 subnets	Order and upgrade

Plan and Location override the product-level plan and group selections when present. Add-on quantities are always additive on top of the selected plan’s own allocation.

Note

Configurable options are not created automatically, because WHMCS options are orderable the moment they exist and a newly created option has no price. Create them yourself under Configurable Options, set your per-unit pricing, then tick the group on the product.

Image value rule

The value of an Operating System option (or the Operating System custom field) must be either an image UUID or an image slug (for example ubuntu-24.04). Slugs match case-insensitively; the UUID must match exactly. The full list of orderable images, with name, slug and UUID, is printed on the product’s module settings page.

If the value cannot be resolved, provisioning fails with Unknown operating system option '<value>'; valid values are listed on the product's module settings page.

If no OS is selected anywhere on the order, the instance is created undeployed and the customer picks the OS from the panel after their first login.

Precedence

For values that can come from more than one place, the first non-empty source wins: configurable option, then custom field, then the product default. In practice: the Operating System configurable option is read before the Operating System custom field, and the Plan and Location configurable options are read before the product-level module settings.

Custom fields

Two order-flow custom fields are created automatically on the product when the module settings page is opened. You do not add them yourself:

• SSH Key. A customer-visible, optional textarea on the order form. A pasted public key (ssh-rsa, ECDSA or Ed25519) is found or created on the customer’s panel account and injected at deploy.
• Operating System. A customer-visible dropdown on the order form, created only when the Order-form OS field product setting is ticked, so existing products do not sprout a new field. Fill its choices with image UUIDs or slugs from the image table on the module settings page.

The module also stores the link between a WHMCS service and the instance it created in its own table (mod_virtconsole), created automatically the first time the module runs. For visibility it writes two admin-only product custom fields, user_id and instance_id. These are created automatically too. Services created by older versions of the module are migrated into the table the first time any action runs against them.

If the product has WHMCS’s domain/hostname prompt enabled, the entered hostname is validated and sent to the management server as the instance hostname; otherwise a random hostname is generated.

Post-purchase changes (upgrade)

WHMCS calls the module’s upgrade routine both on plan changes and on configurable-option changes. The module sends the selected plan plus the full current add-on set in a single request, and the management server reconciles the running instance to the resulting effective resources:

• vCPU, RAM and bandwidth take effect at the instance’s next restart. With Apply resource changes set to At next reboot (default) the instance is left alone and the upgrade reports that some changes take effect at next reboot; set to Restart now and the module restarts the instance immediately after a successful upgrade.
• Disk is grow only: the primary disk is resized up, and shrinking it is refused with a clear error that WHMCS shows. For instances provisioned by v3, Additional Disk (GB) grows the primary disk rather than attaching a second volume. Legacy instances that already have a secondary add-on disk keep it untouched.
• IPv4 and IPv6 changes allocate or release the difference; releases never touch the primary address, and a decrease is refused while the instance is suspended.
• When only some parts of a change can be applied, the upgrade reports the applied parts and each failed part individually.

A pending restart is also surfaced on the admin services tab until the instance is restarted.

Client area

The instance card shows the service status, live power state, resource tiles (vCPU, RAM, disk, bandwidth used vs quota, OS), the primary IP address, the hostname and any additional IPv4 and IPv6 addresses. Status is refreshed from the management server when the page is opened, polled every few seconds while a task is running (the card shows the task name and progress), and can be refreshed manually at any time.

The card offers:

• Open control panel. One-click SSO login into the panel. WHMCS’s own SSO sidebar button on the product page works as well.
• Start, Restart, Stop and Force off power controls.
• Console. An SSO deep link intended for the panel’s console page; it currently opens the panel itself while the panel-side landing is still being wired up. Only with the All actions tier.
• Reinstall. An image picker with a confirmation dialog; rebuilding the instance erases its disk.
• Reset password. With a confirmation dialog. The new password is emailed to the customer by the panel and is never shown in WHMCS.

Which of these appear is controlled per product by the Client actions setting: Power only (default) shows the power controls, Power + Reinstall adds reinstall, Power + Reinstall + Password adds the password reset, and All actions additionally enables the console deep link.

Note

All card actions run through client.php, which checks the logged-in client’s ownership of the service and requires a session nonce for any mutating request.

Admin area

The module adds the following to the service page in the WHMCS admin area:

• Instance ID and Panel User ID. Editable, so a service can be re-linked to a different instance, or unlinked by clearing both fields.
• A link that opens the instance directly on the management server.
• A Sync Instance Info button that pulls the current instance details from the management server and refreshes the dedicated and assigned IPs stored on the service.
• Start, Restart, Stop, Force off and Reinstall buttons. Reinstall uses the image chosen in the Reinstall Image selector on the same tab. Admin buttons are always available to admins regardless of the Client actions product setting.
• A resource summary showing effective values (plan base + add-ons sold on the service), an add-on breakdown, the last task run on the instance and a pending-restart hint when the most recent upgrade left changes waiting for a restart.

Note

If a service is already linked to an instance, running Create again is refused rather than provisioning a second instance. Terminate the service first, or clear the Instance ID field, before re-provisioning.

Upgrade notes

From 2.x to 3.0.0

3.0.0 renames the module slug from hypervisorv2 to virtconsole. Run this one-time SQL against your WHMCS database before or after dropping in the new files (order does not matter); it preserves all data and re-links configured products automatically:

RENAME TABLE mod_hypervisorv2 TO mod_virtconsole;
RENAME TABLE mod_hypervisorv2_cache TO mod_virtconsole_cache;
UPDATE tblservers   SET type       = 'virtconsole'    WHERE type       = 'hypervisorv2';
UPDATE tblproducts  SET servertype = 'virtconsole'    WHERE servertype = 'hypervisorv2';

The companion provisioning modules were renamed too (hypervisorv2c to virtconsolecredits, hypervisorv2sp to virtconsolesp). They are server modules, not addon modules: upload their folders under modules/servers/ (the download archive already places them there) and run the equivalent renames for any servers and products using them:

UPDATE tblservers   SET type       = 'virtconsolecredits' WHERE type       = 'hypervisorv2c';
UPDATE tblproducts  SET servertype = 'virtconsolecredits' WHERE servertype = 'hypervisorv2c';
UPDATE tblservers   SET type       = 'virtconsolesp'      WHERE type       = 'hypervisorv2sp';
UPDATE tblproducts  SET servertype = 'virtconsolesp'      WHERE servertype = 'hypervisorv2sp';

They create no database tables of their own.

Behaviour after upgrading

• The existing Plan, Location, Additional IPv4 and Additional Disk (GB) option names keep working unchanged.
• All new fields and product settings are opt-in: caps default to blank (uncapped), Apply resource changes defaults to At next reboot, Client actions defaults to Power only, and the Operating System order-form field is only created when Order-form OS field is ticked. A product with no OS option keeps today’s behaviour: the instance is created undeployed and the customer picks the OS in the panel.
• One behaviour change for new orders: Additional Disk (GB) now grows the primary disk instead of attaching a second volume. Existing instances that already have the secondary add-on disk keep it.
• Password behaviour is unchanged: root and admin passwords are never returned to WHMCS over the billing API; the panel emails them on deploy and on reset.

Common problems

• Test Connection fails. Confirm the hostname or IP resolves to your management server, the Secure box is ticked, and the API token was generated on that same server and is not IP-restricted to a different address.
• Create fails with “Service is already linked to instance …”. The service already has an instance. Terminate it, or clear the Instance ID field on the service’s module tab if the instance no longer exists.
• Create or upgrade fails with “Unknown operating system option …”. The Operating System option or custom field value is neither an image UUID nor a slug on this management server. Copy a valid value from the image table on the product’s module settings page.
• Terminate reports success but the instance is missing. Expected. If the instance has already been deleted on the management server, the module completes the local cleanup so the service can be terminated in WHMCS.
• Suspend, unsuspend or upgrade says the instance no longer exists. The instance was deleted on the management server while the service was still active. Terminate the service and re-provision it.
• Upgrade says an IP decrease was refused. Additional IPv4 and IPv6 addresses cannot be removed while the instance is suspended. Unsuspend it and run the upgrade again.
• Launch control panel does nothing. Check that client.php exists in the module folder. The management server also rate-limits SSO link generation, so repeated rapid clicks may be briefly refused; wait a minute and retry.

For panel-side issues, see the FAQ.

Related

• Blesta
• HostBill
• API tokens
• API overview
• Cloud Service