Zabbix Module for WHMCS

A WHMCS provisioning module for Zabbix — sell network monitoring as a service. It automates account creation, suspension, termination and password changes for Zabbix users.

Features

• Automatic provisioning — creates a dedicated host group and user in Zabbix when an order is placed.
• Tariff plans — each product has its own host limit and Zabbix role, configured directly in WHMCS Module Settings. No config files needed.
• Suspend and unsuspend — disables or re-enables the Zabbix user and stops or resumes monitoring for all of their hosts.
• Terminate — removes all hosts, the user, their user group and their host group cleanly, in the correct order.
• Change password — changes the Zabbix user password from the WHMCS interface.
• Client portal — clients manage their infrastructure directly from WHMCS:
  • View all added hosts with live status (Monitored or Not monitored).
  • Add a host by IP address or hostname.
  • Choose connection type: Zabbix Agent, SNMP, or ICMP Ping.
  • On adding a Zabbix Agent host, receive a ready-to-use zabbix_agentd.conf and a unique 256-bit PSK encryption key, shown once.
  • Remove hosts.
  • Direct link to the Zabbix UI.
• Localisation — English, Russian and Ukrainian included; any WHMCS language is supported.

How It Works

The module uses a super-admin API token, so no manual account creation is needed. Each WHMCS service maps to one isolated environment in Zabbix.

Order placed (CreateAccount):

1. hostgroup.create — whmcs_client_{userid}_svc_{serviceid}
2. usergroup.create — usrgrp_whmcs_client_{userid}_svc_{serviceid}, with read-write access scoped to that host group only.
3. user.create — whmcs_{userid}_{serviceid}, assigned the pre-created role from Module Settings.

Order suspended (SuspendAccount):

1. User moved to the whmcs_disabled group, which disables login.
2. All hosts set to status: not monitored.

Order unsuspended (UnsuspendAccount):

1. User restored to their original user group, which enables login.
2. All hosts set to status: monitored.

Order terminated (TerminateAccount):

1. host.delete — all hosts in the group.
2. usergroup.delete — the user group.
3. user.delete — the user.
4. hostgroup.delete — the host group.

Password changed (ChangePassword):

1. user.update — the new password is applied.

Host Isolation

Each client can only see and interact with hosts in their own host group. This is enforced by Zabbix itself through the user group permissions, not by the module. Even if a client uses the Zabbix UI directly, they cannot access hosts belonging to other clients.

PSK Encryption for Zabbix Agent

When a client adds a host with type Zabbix Agent:

1. The module generates a unique 256-bit PSK key using random_bytes(32) and a unique PSK identity.
2. The host is created in Zabbix with TLS and PSK configured.
3. The client receives a ready-to-use zabbix_agentd.conf and the raw PSK key, shown once only.

The PSK key is never stored anywhere. If it is lost, the client removes the host and adds it again to get a new key.

User Roles

The module assigns whatever Zabbix role you specify in the Module Settings of the product. You are free to configure the role however you like: grant read-only access, allow template editing, restrict certain views, or anything else Zabbix roles support. The module does not enforce any specific role configuration, which gives you full flexibility to tailor the client experience to your use case.

Requirements

• WHMCS: 7.x, 8.x or 9.x
• PHP: 7.4 or higher
• PHP extensions: curl, json
• Zabbix: 6.4 or higher (tested on 7.x)
• Zabbix API token: Super-admin, no expiry

Installation

1. Copy Module Files

Upload the modules/ directory to the root of your WHMCS installation, merging with the existing structure. The layout is:

• modules/
  • servers/
    • zabbix/
      • zabbix.php
      • ZabbixAPI.php
      • lang/
        • english.php
        • russian.php
        • ukrainian.php

2. Create a Zabbix API Token

1. Log in to your Zabbix admin panel as a Super Admin user.
2. Go to User settings, then API tokens.
3. Click Create API token and set No expiry.
4. Copy the generated token. You will paste it into WHMCS in the next step.

The token must belong to a Super Admin user. Tokens from regular Admin or User accounts cannot create host groups or manage users.

3. Create a User Role in Zabbix

Go to Administration, then User roles, then Create user role. This role is assigned to every client on this product. You can configure it however suits your service; the module has no requirements. A minimal starting point:

• User type: User
• Monitoring, Hosts: enabled
• Monitoring, Problems: enabled
• Dashboards: enabled
• Data collection: all disabled
• Administration: all disabled
• Default access to new actions: disabled

Save the role and note its name. You will enter it in Module Settings.

4. Add a Server in WHMCS

Go to Setup, then Servers, then Add New Server:

• Name: any label, for example Zabbix Production
• Hostname: your Zabbix hostname, for example zabbix.example.com
• Server Type: Zabbix Monitoring
• Access Hash: paste your API token here
• Secure: checked, for HTTPS

Click Save Changes, then Test Connection. You should see a success message.

Test Connection performs two checks. First it calls apiinfo.version without auth to verify the server is reachable, then it makes an authenticated API call to verify the token is valid.

5. Create a Server Group

Go to Setup, then Server Groups, then Create New Group, and add the server from step 4.

6. Create a Product

Go to Setup, then Products/Services, then Create New Product:

1. Fill in name, pricing and billing cycle as usual.
2. On the Module Settings tab, set Module Name to Zabbix Monitoring and Server Group to the group from step 5.
3. Set the tariff parameters (see below).
4. Save.

Tariff Parameters

Set per-product in Module Settings. Each product can have different values.

• Hosts Limit — default 5. Maximum number of hosts the client can add.
• Zabbix Role Name — default client_basic. Name of the Zabbix role to assign. It must exist in Zabbix beforehand.

Example Plans

• Starter — 5 hosts, role client_basic
• Business — 25 hosts, role client_advanced
• Pro — 100 hosts, role client_pro

Each role can have different API permissions, visible sections, and UI access, all configured in Zabbix.

Client Portal

When a client views their active service they see:

• Username — their Zabbix login.
• Hosts — current count versus limit, for example 2 / 5.
• Open Zabbix — direct link to the Zabbix web UI.

Host List

A table of all added hosts showing name, connection type and monitoring status. Each row has a Remove button.

Adding a Host

The client fills in:

• IP address or hostname — validated before submission.
• Connection type — one of:
  • Zabbix Agent — recommended; requires the agent installed on the target server.
  • SNMP — for network devices; uses port 161.
  • ICMP Ping — simplest; no agent required, just ping.

Zabbix Agent Setup

When the connection type is Zabbix Agent, the client sees a one-time block.

1. PSK file, saved as /etc/zabbix/zabbix_agentd.psk. It contains a single line: 64 hex characters, for example a3f1c8....

2. Agent config, a ready-to-use zabbix_agentd.conf with these directives:

• Server=zabbix.example.com
• ServerActive=zabbix.example.com
• Hostname=client-server.example.com
• TLSConnect=psk
• TLSAccept=psk
• TLSPSKIdentity=psk_client-server_a1b2c3d4
• TLSPSKFile=/etc/zabbix/zabbix_agentd.psk

3. Permissions and restart, run on the target server:

• chmod 400 /etc/zabbix/zabbix_agentd.psk
• chown zabbix:zabbix /etc/zabbix/zabbix_agentd.psk
• systemctl restart zabbix-agent

The PSK key is shown only once and is never stored. If the client loses it, they remove the host and add it again.

Localisation

Language files are in modules/servers/zabbix/lang/. WHMCS automatically loads the file matching the system language, set under Setup, General Settings, Localisation. It falls back to english.php if not found.

To add a new language, copy lang/english.php to lang/<language>.php (lowercase, matching the WHMCS language name) and translate the values.

Security

• SSL verification — CURLOPT_SSL_VERIFYPEER is true and CURLOPT_SSL_VERIFYHOST is 2.
• SSRF via hostname — hostname validated before use; private IP ranges blocked.
• HTTP redirects — CURLOPT_FOLLOWLOCATION is false, so redirects are not followed.
• Header injection — the API token is stripped of newlines before use in headers.
• CSRF on client forms — session token verified with hash_equals().
• Host ownership — before deleting a host, the module verifies that it belongs to the group of the client.
• Path traversal in lang — the language value is filtered through preg_replace before use in a file path.
• PSK keys — generated with random_bytes(32), cryptographically secure, and never stored.

Troubleshooting

Test Connection fails

• Check that the hostname is reachable from the WHMCS server on port 443.
• Make sure the API token belongs to a Super Admin user.
• Verify that the Zabbix API is enabled under Administration, General, API.

CreateAccount fails with a role-not-found error

• The role name in Module Settings must exactly match the role name in Zabbix (case-sensitive).
• Create the role in Zabbix first, then set up the product.

Suspend fails

• The module creates a whmcs_disabled usergroup on first suspend. Make sure the API token has permission to create user groups.

Client sees a host-group-not-found message

• The service was likely created before the module was installed, or CreateAccount failed silently.
• Run Create from the admin service page to re-provision.

CSRF token error in client portal

• This can happen if the session of the client expired mid-page. Refreshing the page resolves it.

File Structure

• modules/servers/zabbix/
  • zabbix.php — WHMCS module hooks (MetaData, ConfigOptions, lifecycle functions)
  • ZabbixAPI.php — Zabbix JSON-RPC API client
  • lang/
    • english.php
    • russian.php
    • ukrainian.php