Beta. This feature works and is being tested on more setups. Report anything that does not behave as described here.
The SolusVM-compatible API is a migration aid for hosts moving from SolusVM 1. A billing module written for SolusVM 1's admin API, such as the SolusVM module for WHMCS or Blesta, keeps working against VMStack unchanged. It talks to https://panel.example.com/api/admin/command.php. New integrations should use the REST API or a VMStack billing module instead.
This layer is beta: it works and is covered by automated tests, and is being tested against more billing installs. Please report any action that behaves differently from SolusVM.
How it works#
- The layer speaks SolusVM 1's protocol: a form
POST(orGET) withid,key,actionand the action's fields. The answer is<status>success</status><statusmsg>…</statusmsg>followed by the fields, or one JSON object whenrdtype=jsonis sent. It is always HTTP 200. On a failurestatusiserrorandstatusmsgsays why. - Each SolusVM action is carried out as one or more requests to the panel's own
/api/v1operations, made with the credential. The credential's scopes, allowed addresses, the administrator's staff role and the rate limits all apply. The panel applies the same rules and refusals as on its own pages. - Each sub-request is a row in the API log, beside the row for the
command.phprequest. Audit entries say"via": "solusvm". - The layer is off by default. While it is off,
command.phpanswers 404 with "The SolusVM compatible API is turned off on this panel.", so a billing system's connection test says why.
Setting it up#
- Go to System › Settings and open the SolusVM API tab.
- Tick Answer SolusVM 1 API requests and save.
- Under Credentials, enter a Name (for example
WHMCS) and the billing server's public address under Allowed addresses, then click Create credential. - Copy the id and the key with the copy buttons. The key is shown once; only its hash is kept.
- Under Names, map the names the billing module sends to what they are in VMStack (see below).
A credential belongs to the administrator who created it and acts as that administrator, with the scopes a billing module needs. It never expires. It works only at command.php: it is refused as a bearer key on /api/v1 and on the MCP server, and an ordinary API key is refused at command.php. Credentials do not appear under Settings › API keys, but they do appear under System › API keys and in the API log. While Administrator keys must have allowed addresses is on (the default, on the API tab), a credential needs allowed addresses.
To revoke a credential, click Revoke on its row and confirm. The billing module using it stops working at once. A revoked credential cannot be restored: create a new one instead.
Mapping names#
SolusVM billing products refer to templates, plans, nodes and node groups by name. Under Names, choose the kind (Template, Plan, Node or Node group), enter the Name in SolusVM, choose what it is Here, and save.
| SolusVM kind | Maps to |
|---|---|
| Template | An image |
| Plan | A plan |
| Node | A node |
| Node group | A node group or a location |
A name that is not mapped is looked up as the panel's own: an image's name or slug, a plan's name, a node's name or address, or a node group's or location's name. The lists given to the module (listtemplates, listplans, listnodes, listnodegroups) show the mapped names, so the module's dropdowns offer names that resolve. A numeric nodegroup that is not mapped is taken as a VMStack node group ID.
Server and client IDs#
vserveridis a number. A server imported from SolusVM 1 with Infrastructure › Import from another panel keeps the ID it had there, so existing billing services stay linked. Any other server gets the next free number the first time the layer names it. The server's VMStack UUID is accepted too.- A client's
usernameis the oneclient-createstored, the username the client had on an imported SolusVM 1 panel, or its e-mail address.
See Importing from SolusVM for moving the servers themselves.
Configuring WHMCS#
In WHMCS, add a server of type SolusVM:
| Field | Value |
|---|---|
| Hostname | panel.example.com (leave the IP address empty) |
| Username | The credential's id |
| Password | The credential's key |
| Secure | Ticked |
| Access Hash | <connect-via-hostname>yes</connect-via-hostname><port>443</port> |
Test Connection should report success. Then set up the products as you did for SolusVM: virtualization KVM, a node or node group, a plan and a template from the module's dropdowns.
Warning: Always use POST. SolusVM modules can send
idandkeyin the query string with GET. The panel's API log keeps only parameter names, but a proxy or web server log in between would keep the values.
Supported actions#
| Area | Actions |
|---|---|
| Servers | vserver-create, vserver-checkexists, vserver-boot, vserver-reboot, vserver-shutdown, vserver-suspend, vserver-unsuspend, vserver-terminate, vserver-info, vserver-infoall, vserver-status, vserver-rebuild, vserver-change (also accepted as vserver-changeplan), vserver-change-memory, vserver-change-hdd, vserver-change-cpu, vserver-hostname, vserver-rootpassword, vserver-addip, vserver-delip, vserver-bandwidth, vserver-rescue |
| Clients | client-create, client-checkexists, client-updatepassword |
| Lists | listnodes, node-idlist, listnodegroups, listplans, listtemplates, node-statistics |
Details that differ from SolusVM:
vserver-createmakes KVM servers only, sized by the plan.custom*sizes are refused, andipsis ignored because the plan decides the addresses. The answer carriesvserverid,rootpassword,mainipaddress,extraipaddress,hostname,nodeidandvirtid;consoleuserandconsolepasswordare empty.vserver-suspendsuspends with the reason "Suspended by the billing system."vserver-terminatedeletes the server. The client account stays;deleteclientis not supported.vserver-changeand the-memory,-hddand-cpuvariants are upgrades. A downgrade is refused with the panel's reason.vserver-bandwidthsets the server's monthly traffic limit in GB (0 means no limit). It is not a usage query.vserver-statusanswersonline(running or in rescue),offline(stopped, building, in error or being deleted) ordisabled(suspended).vserver-infoallgives the state, addresses, node, rescue mode, the disk and memory sizes and the traffic (allowance and counted). Usage graphs are empty.- A server the credential cannot see, or that does not exist, answers
Virtual server not found, which is what the WHMCS module checks before creating.
Not supported#
Each of these answers status=error with a sentence saying what to use instead:
| Action | Why, and what to use |
|---|---|
vserver-vnc, vserver-vncpass, vserver-console |
Raw console details are never given out. Open the console in the panel, or use a console link from the REST API (POST /api/v1/servers/{id}/console-link). |
vserver-change-nspeed |
Network speed is set by the plan, or by an administrator in the panel. |
vserver-mountiso, vserver-unmountiso |
ISO drives are changed in the panel or with the REST API. |
client-authenticate |
Passwords are not checked through this API. |
client-key-login |
Single sign-on uses the REST API's one-time login links (POST /api/v1/users/{id}/login-links). |
client-list, client-delete, node-virtualservers, node-iplist |
Use the panel or the REST API. |
An unknown action answers Invalid action. The SolusVM client API (/api/client/command.php, with per-server keys) is not offered: it answers that customers should use the panel's own API with an API key.
Expected gaps in a WHMCS client area: the VNC and HTML5 console buttons fail with the panel's message, usage graphs are empty, and the admin and client single sign-on buttons do not work.