BillingServ has no module system, so VMStack integrates through a small separate PHP application, the connector (version 0.1.0). BillingServ sends it webhooks; the connector stores each event and a worker brings the order's server to the state the order's status asks for. Customers manage their servers on the connector's own portal. Usage is reported back to BillingServ as meter events.
Requirements#
- A web server with HTTPS (PHP-FPM or LiteSpeed recommended, so work starts right after a webhook is answered), PHP 8.1 or later with
curlandpdo_sqlite, and cron. - The panel reachable over HTTPS with a valid certificate.
- A panel API key as described in API key for a billing system, with the connector's address allowed.
- A BillingServ live API key (from API Information in BillingServ).
Install#
- Get
vmstack-billingserv-<version>.zip(see Integrations); from the source,php build.phpwrites it todist/. It unpacks tovmstack-billingserv/. - Put it outside the web root, for example
/var/www/vmstack-billingserv, and make only itspublic/directory the document root of a host name such asvps.example.com. Route every path that is not a file topublic/index.php. - Create the configuration and the data directory:
cd /var/www/vmstack-billingserv
cp config.example.php config.php
chmod 600 config.php
mkdir -p var && chown www-data: var config.php
var/ holds the SQLite database, its lock and the log; it must be writable by the web server and by cron (run both as the same user). https://vps.example.com/health answers ok when the app is reachable.
Configuration#
config.php returns an array. The main keys:
| Key | Meaning |
|---|---|
panel.url, panel.api_key |
the panel's domain and API key |
billingserv.url, billingserv.api_key |
your BillingServ address (/api/v2 is added) and its live API key |
billingserv.webhook_secret |
the webhook signing secret, the same as in BillingServ |
billingserv.webhook_token |
a random string of at least 24 characters; it is part of the webhook URL |
events.active_statuses |
statuses that mean "the server should exist and run" (default SETUP, SHIPPED) |
events.terminate_statuses |
statuses that delete the server (default TERMINATED, CANCELLED) |
events.terminate_on_delete |
delete the server when the order is deleted (default true) |
events.max_attempts |
tries before an event is marked failed (default 6) |
events.note_failures |
add a note to the customer in BillingServ when an event finally fails |
defaults.* |
placement, image, hostname pattern ({serviceid} = order ID, {clientid}, {domain}), client may create servers, delete account on terminate, single sign-on, bind links to address, reseller ID, customer setup |
packages.<id> |
one entry per BillingServ package that is a VMStack server: plan, optionally placement, image, fixed add-ons in options, and meters |
portal.* |
the customer portal (below) |
Orders of packages not listed under packages are ignored. A package entry looks like this:
'packages' => [
66 => [
'plan' => 3,
'placement' => 'group:2',
'image' => 12,
'options' => ['Extra IPv4' => 1],
'meters' => ['traffic_overage_gb' => 'Bandwidth overage'],
],
],
options accepts the same names as the WHMCS module: Plan, Location, Node Group, Operating System, Application, SSH public key, Extra IPv4, Extra IPv6, Extra Disk Space, Extra Disks, Extra Snapshots, Extra Traffic, Extra Port Forwards (see WHMCS add-ons). Options sent with the order, if BillingServ sends any, win. php bin/vmstack-billingserv catalog lists the panel's plan, placement and image IDs.
The welcome password is always off: customers reach their server through the portal and single sign-on.
Connect BillingServ#
- Run the check:
php bin/vmstack-billingserv test
It tests the panel key (as the other modules' Test Connection), lists BillingServ's order statuses (warning if they are numbered differently than expected), flags packages without a plan, placement or image, and prints the webhook URL. It ends with "OK." or "Fix the problems above."
- In BillingServ, open API Information and set Webhook URL to the URL printed (
https://vps.example.com/webhook/<webhook_token>) and Webhook Signing Secret towebhook_secret. - Press Send test webhook, then check that it arrived:
php bin/vmstack-billingserv events all
The webhook.test event is listed as ignored.
- Add the cron jobs, as the web server's user:
* * * * * php /var/www/vmstack-billingserv/bin/vmstack-billingserv work
17 * * * * php /var/www/vmstack-billingserv/bin/vmstack-billingserv usage
Webhooks must be signed (BillingServ-Signature, at most 300 seconds old); a wrong token answers 404 and a bad signature 401.
What the connector does#
| BillingServ event | Panel |
|---|---|
| order created or updated to an active status | finds or creates the customer's account and creates the server; unsuspends a suspended one; a new package ID upgrades it |
| status SUSPENDED | suspends the server with the order's reason, else "Overdue invoice" |
| a terminate status, or the order deleted | deletes the server (optionally the account) |
| customer updated | a changed email is sent to the linked panel account |
Events of one order are processed in order; an older event than the last one handled is skipped. Failures are retried after 1, 5, 15, 60 and 180 minutes; configuration errors and refusals (4xx) are not retried.
Customer portal#
With portal.enabled true and portal.url, portal.secret (at least 32 characters) set, customers sign in at the portal with their BillingServ email and password (portal.password_login), or with a signed link you give them:
php bin/vmstack-billingserv portal-link <customer-id> 1440
The link is valid for the given minutes (default 60, at most 31 days). The portal lists the customer's active and suspended orders. Its server page offers Start, Shut down, Reboot, Power off, rescue with Show password, Console, Open control panel, reverse DNS, Reinstall, Reset root password, port forwards (NAT) and Set up your server. Actions are sent on behalf of the customer, so the plan's customer permissions apply. portal.billing_url adds a "Billing" link to its header.
The portal requires HTTPS. Behind a reverse proxy, list the proxy's address in portal.trusted_proxies and have it send X-Forwarded-Proto: https. Sessions last 8 hours.
Usage billing#
usage (hourly from cron) sends meter-event calls to BillingServ for each metric mapped in a package's meters, with whole units that grew since the last run. Metrics: vcpu_hours, memory_gb_hours, disk_gb_hours, ipv4_hours, ipv6_hours, traffic_gb, traffic_overage_gb. Create a usage metric of the mapped name on the BillingServ package. During the first 3 days of a month the previous month is finished too.
Command line#
All commands are php bin/vmstack-billingserv <command>:
| Command | Does |
|---|---|
test |
checks both connections and the configuration |
catalog |
lists panel plans, placements and images |
work |
processes waiting events (cron, every minute) |
usage [YYYY-MM] |
reports usage (cron, hourly) |
events [pending|failed|done|ignored|all] |
the 30 newest events |
retry <event id> |
tries a failed event again |
sync [--apply] |
reads the VMStack orders from BillingServ; --apply brings each order's server to its status (catches up on missed webhooks) |
show <order>, servers |
one order's server, or every server |
create, suspend, unsuspend, terminate, change-package <order> |
acts on one order by hand |
reset-password <order> |
sets a root password read from standard input |
link <order> <server-uuid> |
links an existing panel server owned by the customer's account |
portal-link <customer> [minutes] |
prints a portal sign-in link |
Limitations#
- Nothing appears inside BillingServ itself: no buttons on the order, no client-area tab; the server's address is not written back to the order.
- Order options are not readable through BillingServ's API, so add-ons are fixed per package in
config.php. - No welcome password, no CPU, memory or disk sliders, no downgrades.
extra_disk_gbcannot be metered.- Some BillingServ payload shapes were inferred from its documentation; check
eventsafter your first real orders.