Skip to main content

WHM Requirements Deep Dive

Connecting WebHost Manager (WHM) to StackConsole CMP requires specific infrastructure, network, authentication, and platform configurations to ensure reliable automated provisioning. This page details each technical prerequisite, why it is required, where to configure it, how to verify it, and common pitfalls to avoid.

Quick Checklist

For a quick pre-installation checklist and jump-host IP whitelist details, see the WHM Requirements Checklist.

1. Operating System & WHM Platform​

Requirement​

A dedicated server or virtual machine running a supported enterprise Linux distribution with an active, licensed installation of cPanel & WHM (Version 110 LTS, 118, or 120+).

  • Why it is needed: CMP communicates with WHM's JSON-API v1. Supported operating systems ensure that modern TLS ciphers, systemd services, and cPanel API endpoints are consistently available.
  • Where to configure it: During server installation and initial cPanel deployment.
  • How to verify it: 
    /usr/local/cpanel/cpanel -V
  • Expected result: Output showing cPanel & WHM version 110.0 or higher with an active license: 
    118.0 (build 11)
  • Common mistakes: Running an expired cPanel trial license, which blocks API access and causes HTTP 403 errors during connection testing.

2. Network Reachability & Port Configuration​

Requirement​

Bidirectional TCP connectivity between CMP application/worker nodes and the WHM server on port 2087 (HTTPS).

  • Why it is needed: All administrative calls (listpkgs, createacct, suspendacct, changepackage) and customer SSO requests route over WHM's secure management port 2087.
  • Where to configure it:
    • On the WHM host firewall (e.g., CSF /etc/csf/csf.conf or firewalld).
    • On intermediate network security groups, edge firewalls, and cloud access control lists.
  • How to verify it: Run a network socket test from the CMP backend terminal: 
    nc -zv -w 5 <whm-server-ip-or-fqdn> 2087
  • Expected result: Connection to port 2087 succeeded: 
    Connection to 169.58.163.216 port 2087 [tcp] succeeded!
  • Common mistakes:
    • Leaving port 2087 closed in CSF or security groups.
    • Attempting to connect over unencrypted port 2086 (which is blocked or redirected).
    • Overlooking that CMP background workers (virtual-machine queue) may reside on separate nodes with different outbound public IPs than the primary web app.

3. SSL / TLS Certificate Requirements​

Requirement​

A valid, publicly-trusted SSL/TLS certificate installed on the WHM service (cpanel, whm, webmail).

  • Why it is needed: In production, CMP's HTTP client enforces strict SSL certificate verification (Verify SSL Certificate: Yes). Invalid or self-signed certificates will cause cURL / Guzzle SSL verification exceptions (cURL error 60: SSL certificate problem).
  • Where to configure it: In WHM under Service Configuration → Manage Service SSL Certificates.
  • How to verify it: 
    openssl s_client -connect <whm-server-fqdn>:2087 -servername <whm-server-fqdn> < /dev/null 2>/dev/null | openssl x509 -noout -dates -issuer -subject
  • Expected result: Output displaying a valid certificate issued by a trusted Certificate Authority (e.g., Let's Encrypt, Sectigo, DigiCert) with valid start and expiry dates.
  • Common mistakes:
    • Using the server IP directly with SSL verification enabled when the certificate only covers the hostname FQDN (e.g., whm.example.com).
    • Allowing the default self-signed snakeoil cPanel certificate to remain active in a production deployment.

4. API Authentication & Token Privileges​

Requirement​

A dedicated WHM API token generated for the root administrative user or an authorized reseller account with explicit Access Control List (ACL) privileges.

  • Why it is needed: CMP performs account lifecycle operations programmatically. Token authentication avoids exposing underlying server shell passwords and allows granular permission control.
  • Where to configure it: In WHM under Development → Manage API Tokens.
  • How to verify it: Query the package list using the token via cURL: 
    curl -H "Authorization: whm <username>:<api_token>" \
         https://<whm-server-fqdn>:2087/json-api/listpkgs?api.version=1
  • Expected result: A JSON response with metadata.result: 1 and a populated list of packages.
  • Common mistakes:
    • Selecting "Generate Token" without assigning the required ACL permissions (such as create-user-session, basic-whm-functions, list-pkgs).
    • Creating the token under a reseller user that does not possess root delegation or sufficient account quotas in WHM.

5. Required WHM API Permissions Matrix​

To adhere to least-privilege principles, ensure the API token possesses the following specific permissions:

Permission / ACL FeaturePurpose in CMP IntegrationImpact if Missing
list-pkgsFetches available hosting packages in the rate card setupCMP package dropdown is empty
create-acctProvisions new cPanel accounts upon customer orderAccount creation fails with permission denied
modify-acctModifies account settings and quotasQuota and attribute changes fail
suspend-acctSuspends accounts when invoices are overdueDisciplinary suspension jobs fail
unsuspend-acctRestores suspended accounts upon invoice settlementAccounts remain suspended after payment
kill-acct / removeacctDestroys terminated accounts during immediate cancellationTermination jobs fail and leave orphaned infrastructure
edit-pkg / changepackageApplies package upgradesCustomer plan upgrades fail
create-user-sessionGenerates secure cPanel Single Sign-On (SSO) URLs"Open cPanel" button returns 502 or auth error
passwdHandles password resets from the customer Access tabIn-portal password changes fail

6. Hostname, DNS & Mail Defaults​

Requirement​

A fully qualified server hostname with valid forward and reverse (PTR) DNS records, along with default nameserver configurations.

  • Why it is needed:
    • WHM uses the primary hostname when configuring system mailers and virtual hosts.
    • Newly created customer cPanel accounts inherit default nameserver records and mail routing options configured in WHM.
  • Where to configure it:
    • Server Hostname: Networking Setup → Change Hostname.
    • Nameservers: Server Configuration → Basic WebHost Manager Setup.
  • How to verify it: 
    hostname -f
    dig +short <server-hostname>
    dig -x <server-ip> +short
  • Expected result: Hostname resolves forward and backward to the same server IP.
  • Common mistakes:
    • Leaving the default localhost or an unresolvable domain as the server hostname.
    • Pointing nameservers to inactive DNS IPs, causing DNS propagation failures for customer primary domains.

7. Package Configuration Rules​

Requirement​

Pre-existing hosting packages whose names CMP can list. basic hosting and Basic Hosting work. basic_hosting does not.

  • Why it is needed: CMP queries WHM packages via listpkgs. A bare underscore name such as basic_hosting is left out of the CMP dropdown.
  • Where to configure it: In WHM under Packages → Add a Package.
  • How to verify it: Check package names in WHM Packages → Edit a Package.
  • Expected result: Names such as basic hosting, Basic Hosting, or root_unlimited.
  • Common mistakes:
    • Creating basic_hosting. That underscore form does not appear in CMP. Use basic hosting or Basic Hosting. See WHM Package Naming.
    • Renaming a package in WHM after customers have already been provisioned without updating CMP's plan mapping.

8. Queue Workers & Notification System​

Requirement​

Operational CMP queue workers running for the virtual-machine queue, and active email notification templates.

  • Why it is needed:
    • Account provisioning, upgrades, suspensions, and terminations are asynchronous jobs dispatched to the virtual-machine queue.
    • Welcome emails containing cPanel credentials depend on active notification workers.
  • Where to configure it: On the CMP application host (supervisor or systemd service configurations).
  • How to verify it: Check supervisor status on the CMP server: 
    supervisorctl status
  • Expected result: Queue worker processes for virtual-machine and default queues are in RUNNING status.
  • Common mistakes:
    • Queue workers are stopped or crashed, leaving customer accounts indefinitely in the creating state.
    • Notification worker disabled, preventing customers from receiving automated welcome emails.
Was this page helpful?
Found something that could be improved?