cPanel / WHM module

Installs the certificate — leaf, chain and private key — onto each listed domain of a cPanel/WHM server. It is the hosting-panel sibling of the IIS/F5 install modules, and closes the loop for cPanel-hosted sites: issue or renew in CertAutoPilot, then install directly onto the panel.

AutoSSL interaction

If cPanel AutoSSL manages a domain you install onto, it may later re-install its own certificate on top of this one. Exclude the domain from AutoSSL (WHM → Manage AutoSSL) when CertAutoPilot owns its certificate.

Overview

Two modes share one module:

• cpanel — the account-level cPanel UAPI (SSL::install_ssl on port 2083), authenticated as cpanel <user>:<token>. Installs onto the account's own domains.
• whm — the root/reseller WHM API 1 (installssl on port 2087), authenticated as whm <user>:<token>. Installs onto any account's domain on the server; the owning account can be named explicitly (whm_user) or resolved from the domain.

A cPanel install replaces the domain's current certificate, so one target serves many certificates and renewals just re-install. Every run installs unconditionally — a redundant re-install is harmless, and no expiry-based skip is applied (two different certificates can share an expiry second, so a skip there risked serving the wrong certificate).

Target configuration

Field	Type	Required	Default	Description
host	string	yes	—	Bare cPanel/WHM hostname or IPv4 — no scheme, path, or port (use the port field for a custom port).
mode	enum	no	cpanel	cpanel (account UAPI) or whm (root/reseller).
port	number	no	2083 / 2087	Overrides the mode default port.
use_ssl	bool	no	true	Connect over https (recommended).
ssl_verify	bool	no	true	Enforce the server TLS certificate (disable for a self-signed host).
http_timeout	number	no	30	Per-request timeout in seconds (must be ≥ 1 when set; omit for the default).
domains	string[]	no	—	The domain(s) to install onto. Optional — leave empty to make each distribution supply its own via a target override (one server target serving many certificates on different domains, with no shared default to inherit accidentally). A distribution that supplies none fails clearly at deploy. Overridable per distribution (full replacement).
whm_user	string	no	—	WHM mode only: the account that owns the domain(s); empty resolves from the domain. Rejected if set while mode is cpanel.

Credential & required privileges

The credential type is cpanel_api_token, stored as {"username":"...","api_token":"..."}. Authentication is an API token, not the login password — create it in the panel and grant exactly the privileges below (least privilege).

• cpanel mode — in cPanel: Security → Manage API Tokens → Create Token. A cPanel account API token has full access to that account's API (there is no per-feature scope to choose), so the only requirement is that the account's plan (its Feature List) includes SSL/TLS — that is what makes SSL::install_ssl available. Set username to the cPanel account (e.g. elchi) and api_token to the generated token.
• whm mode — in WHM: Development → Manage API Tokens → Generate Token. Restrict the token to the single ACL ssl (listed as SSL/TLS) — that ACL alone is sufficient to install certificates (verified: a token scoped to only ssl installs successfully via installssl); nothing else is needed. Set username to root (or a reseller who holds the ssl ACL and owns the target account) and api_token to the generated token. Do not use a full-access token.

Per-distribution overrides

One cPanel target can be reused across many certificates. A distribution can override the install domain list (a full replacement of the target's domains) and, in WHM mode, the owning account — so a shared server target installs each certificate onto exactly the right domains.

Rollback

cPanel is a stateful module: rollback re-installs a previous retained certificate version through the normal install path, and auto-rollback fires on a failed/partial run where a target changed. Because an install simply replaces the domain's certificate, rolling forward again is a fresh install.

Health check

The health check runs a cheap authenticated probe per target — the cPanel installed-hosts list (UAPI) or the WHM version call — proving the host, port and API token authenticate.

Notes

• The cPanel module is validated against a real cPanel/WHM server (both the cPanel account API and the WHM root API) — install, renewal, the rejected-cert error path, and multi-domain partial installs — in addition to Go unit tests.
• Installing a certificate on cPanel does not change discovery ownership — discovery links a discovered cert to a managed one by fingerprint independently.