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#
- Get the package
vmstack-hostbill-<version>.zip(see Integrations). From the source,php build.phpwrites it todist/. - Unpack it into HostBill's main directory. Its paths start with
includes/modules/Hosting/vmstack/. - 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#
- Settings › Apps › Add new App, module VMStack.
- Hostname: the panel's domain, such as
panel.example.com(nohttps://, no path). - Password: the API key (
vmk_…). - Press Test Connection. Errors and the summary (account, scopes, placement and add-on notes) are shown.
Product setup#
- Create a product and under its connection choose Connect with App and the App above.
- 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.
- 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.