Support · Requirements · Installation · License · Related Integrations
The cPanel DNS Plugin is a Keyfactor Domain Validator implementation that manages DNS records on a cPanel / WHM server. It plugs into the Keyfactor AnyCA Gateway as an IDomainValidator and is invoked automatically during certificate enrollment when DNS-based domain control validation is required.
The DLL ships two validator types:
| Validator class | Validation type | Record published | Use case |
|---|---|---|---|
CPanelDomainValidator |
dns-01 |
TXT | ACME DNS-01 challenges |
CPanelCnameDomainValidator |
cname |
CNAME | CNAME-based DCV (e.g. CSC Global, SSL Store) |
When configuring a Domain Validation Configuration in the gateway UI, pick the validator type that matches the CA's requirement — TXT/dns-01 for ACME, CNAME/cname for CAs that validate via CNAME. Both share the same cPanel credentials and configuration fields.
The plugin uses the server-wide WHM API 1 with a WHM API token, so a single root or reseller credential can manage every DNS zone the server is authoritative for. Records are read with dumpzone, created with addzonerecord, and removed with removezonerecord; zones are enumerated with listzones. For TXT staging, existing values at the same name are preserved and the new value is appended, so co-existing ACME challenges (a wildcard and the apex domain both producing _acme-challenge TXT values) coexist. For CNAME staging, any existing CNAME at the name is removed first since a CNAME is singular per name by DNS rules. The owning zone for an FQDN is resolved by selecting the zone whose name is the longest matching suffix of the record name.
- Automated DNS TXT record creation and deletion in cPanel DNS
- Keyfactor AnyCA Gateway REST 26.2 or later (DNS validation support was added in AnyCA Gateway 26.2)
- A gateway product that supports DNS-01 domain validation (ACME REST Gateway, DigiCert, Sectigo, etc.)
- Keyfactor AnyCA Gateway REST 26.2 or later (DNS validation support was added in AnyCA Gateway 26.2)
- A gateway product that supports DNS-based domain validation (ACME REST Gateway, DigiCert, Sectigo, SSL Store, etc.)
- A cPanel & WHM server that is authoritative for the domains being validated (the domain's nameservers delegate to this server). If DNS for the domain is hosted elsewhere, records created here will not be resolvable by the CA.
- A WHM API token (WHM » Development » Manage API Tokens) owned by
rootor a reseller, with privileges to read and edit DNS zones (listzones,dumpzone,addzonerecord,removezonerecord). - Network reachability from the gateway host to the WHM port (2087/tcp) on the cPanel server.
| Field | Required | Description |
|---|---|---|
CPanel_BaseUrl |
Yes | Base URL of the cPanel/WHM server including the WHM port, e.g. https://host.example.com:2087. |
CPanel_Username |
Yes | WHM user that owns the API token (typically root). |
CPanel_ApiToken |
Yes | WHM API token with DNS zone privileges. Stored as a secret. |
CPanel_SkipTlsValidation |
No | Set to true to skip TLS certificate validation when the server uses a self-signed certificate. Defaults to false. |
- The plugin sets the record TTL to 300 seconds.
- Records are managed via the server-wide WHM API 1; the token must belong to
rootor a reseller with DNS zone privileges. A per-account cPanel UAPI mode is not implemented in this release. - Zones are discovered from the server's
listzonesoutput; a record whose domain is not covered by a zone on the server fails withNo cPanel DNS zone found. - Record removal uses
dumpzoneline numbers; because WHM re-indexes records after each deletion, the plugin removes matched lines in descending order within a singledumpzonesnapshot. - Each validator type manages only its own record type:
CPanelDomainValidatorreads/writesTXT,CPanelCnameDomainValidatorreads/writesCNAME. Neither touches other record types.
- .NET 10.0 runtime (provided by the gateway server)
This plugin is installed alongside any Keyfactor gateway server that supports DNS-01 domain validation (ACME REST Gateway, DigiCert, Sectigo, etc.). The same DLL works with every supported gateway.
See the official Keyfactor AnyCA Gateway REST installation documentation for the authoritative install instructions: . The steps below are a general guide; defer to the official docs if they diverge.
Download the latest release from the Releases page.
On the server hosting your gateway, unzip the release and copy the contents of the net10.0 directory into the gateway's Extensions folder.
Windows (example path — substitute the gateway product folder for your install):
C:\Program Files\Keyfactor\<GatewayName>\AnyGatewayREST\net10.0\Extensions\
Linux:
/opt/keyfactor/<gateway-name>/AnyGatewayREST/net10.0/Extensions/
Replace <GatewayName> (or <gateway-name> on Linux) with the gateway you are installing into (e.g. AcmeGwDns, DigiCert, Sectigo).
Restart the AnyGatewayREST Windows service for the gateway you installed the plugin into so the Extensions folder is rescanned.
After installing the plugin DLL into the gateway's Extensions folder, configure a new DNS Provider entry in the AnyCA Gateway REST UI and select cPanel as the provider type. See the official Keyfactor AnyCA Gateway REST documentation for the canonical UI walkthrough: .
| Parameter | Description | Required | Example |
|---|---|---|---|
CPanel_BaseUrl |
Base URL of the cPanel/WHM server including the WHM port, e.g. https://host.example.com:2087. | Yes | |
CPanel_Username |
WHM user that owns the API token (typically 'root' or a reseller account). | Yes | root |
CPanel_ApiToken |
WHM API token with DNS zone privileges. Stored as a secret. | Yes | |
CPanel_SkipTlsValidation |
Set to 'true' to skip TLS certificate validation when the cPanel server uses a self-signed certificate. Defaults to false. | No | false |
{
"CPanel_BaseUrl": "",
"CPanel_Username": "",
"CPanel_ApiToken": "",
"CPanel_SkipTlsValidation": ""
}Once configured, the plugin automatically handles DNS validation during certificate enrollment and renewal:
- Record Creation: Plugin creates a DNS TXT record with the validation challenge
- Propagation Wait: Plugin waits for DNS propagation
- Verification: Plugin verifies the record exists on cPanel DNS nameservers
- Cleanup: Plugin deletes the validation record after successful validation
The plugin automatically discovers the appropriate DNS zone for a domain:
- For
www.example.com, searches for zones:www.example.com,example.com - For
sub.example.com, searches for zones:sub.example.com,example.com - For
*.example.com, searches for zones:example.com
- Authentication Failures: Verify cPanel DNS credentials are valid, not expired, and authorized for the target zone.
- Insufficient Permissions: Verify the account/role has the documented minimum permissions on the target DNS zone.
- Zone Not Found: Verify the target DNS zone exists in your cPanel DNS account and is reachable from the gateway server.
- DNS Propagation Timeouts: Check cPanel DNS service health; verify authoritative nameservers are responding.
Enable debug logging in the gateway's logging configuration:
{
"Logging": {
"LogLevel": {
"Keyfactor.Extensions.DomainValidator.CPanel": "Debug"
}
}
}The cPanel DNS Provider plugin is open source and there is no SLA. Keyfactor will address issues as resources become available. Keyfactor customers may request escalation by opening a support ticket through their Keyfactor representative.
To report a problem or suggest a new feature, use the Issues tab. If you want to contribute actual bug fixes or proposed enhancements, use the Pull requests tab.
Apache License 2.0, see LICENSE.
See all Keyfactor DNS Provider plugins.