HostBill

Install the VMStack hosting module in HostBill, connect an App, set up products, form fields and add-ons, client functions and metered billing.

The HostBill module (version 0.1.0) is a hosting module. Besides the server's life cycle it offers add-ons (extra addresses, disks, snapshots, traffic, port forwards), client functions acting on behalf of the customer, account import and metered (hourly) billing.

Requirements#

  • A current HostBill (one with the App connection fields) on PHP 8.1 or later, with cURL.
  • The panel reachable over HTTPS with a valid certificate.
  • A panel API key as described in API key for a billing system. Add-ons other than extra IPv4, IPv6 and port forwards need an administrator's key; making the extra disk at create needs disks:write.

Install#

  1. Get the package vmstack-hostbill-<version>.zip (see Integrations). From the source, php build.php writes it to dist/.
  2. Unpack it into HostBill's main directory. Its paths start with includes/modules/Hosting/vmstack/.
  3. Settings › Modules › Hosting Modules › Inactive: activate VMStack.

On first use of metered billing the module creates one table, vmstack_metered, in HostBill's database.

Connect to the panel#

  1. Settings › Apps › Add new App, module VMStack.
  2. Hostname: the panel's domain, such as panel.example.com (no https://, no path).
  3. Password: the API key (vmk_…).
  4. Press Test Connection. Errors and the summary (account, scopes, placement and add-on notes) are shown.

Product setup#

  1. Create a product and under its connection choose Connect with App and the App above.
  2. Fill in the module options:
Option Default Meaning
Plan – the panel plan
Placement – a location, node group or node
Default image – used when the order has no OS field
Hostname empty {serviceid}, {clientid}, {domain} pattern. Empty: the panel names the server (the typed domain is used only as {domain})
Send welcome password off stores the root password as the account password; needs servers:secrets
Allow the client to create servers in the panel off ticks May create and delete servers on new accounts
Delete the panel account on terminate off deletes the panel account after its server is deleted
Single sign-on on the Open control panel function
Bind sign-in links to the client's address on links work only from the client's address
Usage billing none metered turns on metered billing (below)
Reseller for new accounts (administrator keys) empty panel ID of the reseller new accounts go under
Customer sets up the server off the server waits for the customer (customer setup)

Plan, Placement and Default image can be left to the customer with HostBill's "Allow client to adjust during order"; their form variables are plan, placement and os.

  1. Enable the product's Client Functions you want (see below).

Form fields#

Order form fields (Components › Forms) are matched by variable name:

Variable Effect
plan panel plan
location, node_group, placement placement; placement takes 3, group:2 or node:5. Order: location, node_group, placement, then the product setting
os image
application one-click application slug, or none
ssh_keys text area, one key per line
extra_ipv4, extra_ipv6 extra addresses
extra_disk_space, extra_disks extra disk GB and number of disks (at most 15); with disk space only, one empty disk is made at create
extra_snapshots snapshots kept (at most 20)
extra_traffic GB a month, only for a plan with a traffic limit
extra_port_forwards NAT port forwards (NAT servers only, at most 1000)

Each add-on is the plan's amount plus the order's. Lowering one deletes nothing except addresses.

Account details the module fills in: password (the welcome password), domain (the hostname), Panel server ID (type an ID to link an existing server), Main IP address, Other addresses and SSH port (NAT).

What the module does#

HostBill Panel
Create finds or creates the client's account, creates the server, applies add-ons. If a step after the server exists fails, Create reports failure: run it again, it finds the existing server.
Suspend / Unsuspend suspends with HostBill's suspension reason / lifts it
Terminate deletes the server, optionally the account
Change package, form field change upgrades the plan (downgrades refused), re-applies add-ons
Change password resets the root password
Synchronize reads the hostname and suspension state
Import accounts lists every server the key sees

The admin account page shows the panel server, status, suspension, plan, location, node, addresses, external ID and traffic this month, with a link to the panel.

Client functions#

Function Offers
Server status; Start, Shut down, Reboot, Power off; rescue on and off with the rescue password; console; single sign-on
Reinstall an image from those the plan allows
Reset root password a new root password
Reverse DNS the names of the public addresses
Port forwards add and delete NAT forwards, and a link to the panel
Traffic this month's traffic
Console a console link
Open control panel single sign-on

Actions are sent on behalf of the customer, so the plan's customer permissions and reinstall limits apply and a refusal shows the panel's sentence. Every form carries its own token; an expired one reads "The form has expired. Reload the page and try again."

Metered billing#

With Usage billing set to metered, HostBill's hourly cron reports what grew since the last report for each account of such a product. The variables (all with the overage scheme) are vcpu_hours, memory_gb_hours, disk_gb_hours (main disk only), ipv4_hours, ipv6_hours, traffic_gb and traffic_overage_gb. Set their prices on the product. On the 1st of the month the previous month is finished first. HostBill's cron must run.

Limitations#

  • No CPU, memory or disk sliders; no plan downgrades.
  • A changed client email is not sent to the panel.
  • No single sign-on for staff into the panel (the admin link opens the panel's address only).
  • Extra disk size is not metered.
  • Extra addresses and disks are added only once the server is built.
  • A reseller's key supports only the extra IPv4, IPv6 and port-forward add-ons.