BillingServ

Run the VMStack connector for BillingServ: hosting, configuration, the webhook, the worker and usage cron, the customer portal and the command line.

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 curl and pdo_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#

  1. Get vmstack-billingserv-<version>.zip (see Integrations); from the source, php build.php writes it to dist/. It unpacks to vmstack-billingserv/.
  2. Put it outside the web root, for example /var/www/vmstack-billingserv, and make only its public/ directory the document root of a host name such as vps.example.com. Route every path that is not a file to public/index.php.
  3. 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#

  1. 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."

  1. In BillingServ, open API Information and set Webhook URL to the URL printed (https://vps.example.com/webhook/<webhook_token>) and Webhook Signing Secret to webhook_secret.
  2. Press Send test webhook, then check that it arrived:
php bin/vmstack-billingserv events all

The webhook.test event is listed as ignored.

  1. 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_gb cannot be metered.
  • Some BillingServ payload shapes were inferred from its documentation; check events after your first real orders.