Skip to main content

WHM / cPanel Requirements

This page provides the onboarding checklist for integrating WebHost Manager (WHM) / cPanel with StackConsole CMP. Complete the common prerequisites and confirm your hosting topology before connecting.

CMP's Web Hosting integration communicates directly with WHM via its secure JSON-API over HTTPS (port 2087) using API tokens. It manages the full lifecycle of cPanel hosting accounts, including provisioning, package changes, single sign-on (SSO), disciplinary suspension, and termination.

Bare minimum

Items marked as required to begin in the checklist must be completed before the WHM integration can be established in CMP. Without these prerequisites, the connection test and account synchronization will fail.

1. Access for StackConsole Team​

If the StackConsole deployment or support team is assisting with initial integration setup, provide administrative access via one of the following methods:

Option A — VPN access (preferred)

NameEmail
Satish Londhesatish.londhe@stackconsole.io
Sushil Moresushil.more@stackconsole.io

Option B — IP whitelist

If VPN access is not feasible, whitelist the StackConsole jump server in your WHM host firewall (e.g., ConfigServer Security & Firewall / CSF or iptables):

14.192.19.227

2. WHM Server Credentials & API Tokens​

CMP connects to WHM using API token authentication. To adhere to security best practices, use a dedicated administrator or reseller user with least-privilege Access Control Lists (ACLs) rather than unconstrained credentials.

FieldDescription / Value
WHM Hostname / IPFully Qualified Domain Name (FQDN) or IP (e.g., https://whm.example.com or https://169.58.163.216)
Port2087 (WHM SSL secure port)
API Usernameroot or an authorized reseller account with package/account management privileges
API TokenWHM-generated API token configured with required ACLs
SSL CertificateValid SSL/TLS certificate installed on the WHM service
Token Security

Never store or commit WHM API tokens in plain text, tickets, or git repositories. In CMP, credentials are encrypted at rest and masked in all UI responses.

3. CMP VM → WHM API Connectivity​

The CMP backend instance (cmp-app) and background queue workers must be able to establish outbound TCP connections to the WHM server over port 2087 (HTTPS).

Network Reachability​

  • Direct Private Network (Recommended): If CMP and WHM reside in the same datacenter or over an internal VPC/interconnect: 
    https://10.0.10.50:2087
  • Public FQDN / IP: If communicating over the public internet, ensure port 2087 is open and protected by firewall access lists: 
    https://whm.yourdomain.com:2087

Firewall Rules (WHM Server)​

Ensure the WHM firewall permits inbound HTTPS traffic from the CMP application server IP addresses:

SourceDestination PortProtocolPurpose
CMP Application Server(s)2087TCPWHM API communication & package querying
CMP Worker Server(s)2087TCPAsynchronous account provisioning & lifecycle jobs
Admin / Client Jump Host2087TCPAdministrative access & connection testing

4. Required WHM API Permissions (ACLs)​

When creating the API token in WHM (Development → Manage API Tokens), ensure the following Access Control List (ACL) features are granted:

ACL FeaturePurpose in CMP
Account Creation (createacct)Required to provision new customer cPanel accounts
Account Modification (modifyacct)Required to change plan quotas and account parameters
Account Suspension (suspendacct / unsuspendacct)Required for disciplinary and billing lifecycle actions
Account Termination (removeacct)Required for immediate service cancellations
Package Management (listpkgs / changepackage)Required to query available packages and upgrade customer accounts
Account Summary (accountsummary)Required for idempotency checks and disk usage monitoring
Single Sign-On (create_user_session)Required for seamless customer login from CMP into cPanel
Password Reset (passwd)Required for customer-initiated credential resets

5. Hosting Packages on WHM​

Before creating sellable Web Hosting plans in CMP, the corresponding packages must be created in WHM (Packages → Add a Package).

Critical Package Naming Rules

In addition to uppercase characters being omitted, a package named with an un-prefixed underscore like basic_hosting will not appear in the CMP package dropdown due to WHM reseller namespace parsing. Use a space instead: basic hosting or Basic Hosting. If an underscore is required, prefix it with root_ (e.g., root_mailpro). See the WHM Package Naming Guide.

Confirm the following package configurations:

  1. Disk quota (MB) must be specified.
  2. Bandwidth limits (MB) must be defined.
  3. Feature lists must be assigned.
  4. Reseller packages: If a package is reseller-specific, prefix it with resellername_. Global packages should not use reseller prefixes unless meant exclusively for that user.

6. DNS and Domain Architecture​

For automated cPanel account provisioning, ensure your WHM server has valid DNS configurations:

  • Default Nameservers: Configured under Basic WebHost Manager Setup (e.g., ns1.example.com, ns2.example.com).
  • Resolver Configuration: Working recursive DNS resolvers in /etc/resolv.conf.
  • Addon Domain Overwrites: Decide whether WHM should force DNS zone overwrites for addon domains (forcedns). CMP defaults this setting to No.

7. Verification Commands​

Run these verification tests from the CMP backend terminal before attempting to connect the provider in the CMP Admin UI:

Test Port Reachability​

nc -zv -w 5 whm.example.com 2087
# or
curl -Iv https://whm.example.com:2087

Test API Authentication​

curl -H "Authorization: whm root:YOUR_API_TOKEN_HERE" \
     -k https://whm.example.com:2087/json-api/listpkgs?api.version=1

Expected response: HTTP 200 with a JSON payload containing the package array.

8. Checklist​

ItemRequirementStatus
WHM VersionSupported cPanel/WHM version installed with active licenseRequired to begin
Network & PortPort 2087 (TCP) open and reachable from CMP backendRequired to begin
SSL CertificateValid SSL certificate installed on WHM service hostnameRequired to begin
API TokenDedicated API token created with required ACLsRequired to begin
PackagesHosting packages created following CMP naming rules (basic hosting, root_ prefix)Required to begin
FirewallInbound access whitelisted for CMP IPs and jump host (14.192.19.227)Required to begin
Queue WorkersCMP virtual-machine queue workers activeRequired for provisioning
Email Templates"Web Hosting Account Created" notification template enabledOptional (Welcome email)
Was this page helpful?
Found something that could be improved?