Panellicense

Set up a cPanel DNS cluster with DNSONLY nameservers

Build a redundant cPanel DNS cluster with two free DNSONLY nodes — install, trust setup with API tokens, sync roles, and verification with dig.

8 min readUpdated 2026-05-16cpanel · dns · dnsonly · cluster
schema: HowToschema: FAQPageschema: BreadcrumbList

If your hosting business has grown past one server, the DNS that ships on the cPanel box itself is now a single point of failure. When the primary reboots, every customer domain goes dark inside its TTL. The fix is a DNS cluster: two or more dedicated nameservers that share authoritative zones with the primary cPanel box and stay reachable when it isn't.

cPanel sells this configuration as DNSONLY — a stripped-down WHM image with no Exim, no Dovecot, no MySQL, just BIND or PowerDNS and the cluster API. The DNSONLY license is free and self-issues against the server's IP, so a three-node cluster costs you only the two extra VPSes.

Architecture

The typical small-host setup is three nodes:

RoleHostnameLicenseServices
Primaryserver1.example.comcPanel & WHMApache, MySQL, Exim, BIND
Secondary nameserverns1.example.comDNSONLY (free)BIND only
Tertiary nameserverns2.example.comDNSONLY (free)BIND only

All three run BIND. When you create a zone on the primary, the cluster API pushes it to both DNSONLY nodes over port 2087. If the primary goes down, the two DNSONLY nodes keep answering queries from the cached zones — your customers don't notice.

For a larger fleet you can chain multiple cPanel servers into the same cluster, with each DNSONLY node acting as authoritative for every cPanel box in the group. cPanel supports up to 200 servers per cluster.

Prerequisites

  • A working primary cPanel server. If you don't have one yet, start with installing cPanel on a fresh VPS.
  • Two additional VPSes for the DNSONLY nodes. 1 vCPU and 1 GB RAM is plenty — BIND is light. Use AlmaLinux 9 to match the primary.
  • Public IPv4 addresses on all three. cPanel licensing is IP-bound; the DNSONLY licenses self-issue when the installer runs.
  • Port 2087/tcp open between all cluster members (this is the WHM API port the cluster uses to push zones).
  • Port 53/tcp and 53/udp open from the public internet to both DNSONLY nodes.
  • Glue records at your domain registrar pointing ns1.example.com and ns2.example.com at the DNSONLY IPs — see step 5.

Step 1 — Install DNSONLY on both secondaries

SSH into the first DNSONLY box as root and set the hostname:

hostnamectl set-hostname ns1.example.com
echo "203.0.113.20 ns1.example.com ns1" >> /etc/hosts

Run the DNSONLY installer:

cd /home
curl -o latest-dnsonly -L https://securedownloads.cpanel.net/latest-dnsonly
sh latest-dnsonly

It runs for 10–15 minutes and finishes with a WHM login URL. Repeat the entire step on ns2.example.com with its own hostname and IP. Once both are up, run cpkeyclt on each to confirm the free DNSONLY license is bound:

/usr/local/cpanel/cpkeyclt

You want Update succeeded. If you see License File Invalid, the licensing endpoint couldn't reach the IP — usually a firewall blocking outbound 443 to verify.cpanel.net.

Step 2 — Generate API tokens on each node

The cluster authenticates with WHM API tokens. The older "Remote Access Hash" is deprecated and disabled by default since cPanel 100. Tokens are per-node and per-direction, so you'll create three of them.

On each of the three servers, log into WHM as root and go to Development → Manage API Tokens → Generate Token. Name it cluster-from-<other-hostname> so you can identify it later, leave privileges at root, and copy the token immediately — WHM only shows it once.

You should end up with:

Token lives onUsed byName
server1ns1, ns2cluster-from-ns
ns1server1, ns2cluster-from-server1-ns2
ns2server1, ns1cluster-from-server1-ns1

Step 3 — Enable DNS clustering and add the trust relationships

On the primary (server1), open WHM → Clusters → Configure Cluster and toggle DNS Clustering to Enabled. Save.

Then go to Clusters → DNS Cluster → Configure Cluster Member. For each DNSONLY node:

  1. Set Server Type to cPanel. (DNSONLY identifies as cPanel for cluster purposes.)
  2. Enter the remote IP, e.g. 203.0.113.20.
  3. Paste the token you generated on that DNSONLY node.
  4. Set the DNS Role to Synchronize Changes.
  5. Click Submit. WHM tests the connection and saves the trust.

Synchronize Changes is the role you want for a true HA cluster — both sides accept writes and propagate. Write-only sends but never accepts, which is correct when the secondary is a pure stealth slave. Standalone disables sync for that pair.

Now repeat the same exercise on each DNSONLY node, adding both other nodes as Synchronize Changes peers. When you're done, every node should list both peers as green/trusted under DNS Cluster → Configure.

Step 4 — Set the cluster's nameserver IPs

On the primary, WHM → Server Configuration → Basic WebHost Manager Setup. In the Nameservers section:

  • Set ns1.example.com → 203.0.113.20
  • Set ns2.example.com → 203.0.113.21

Click Assign IP Address next to each and then Save Changes. From now on, every new cPanel account WHM creates will write its zone with these two nameservers and immediately push it to both DNSONLY nodes.

Step 5 — Register glue records at your registrar

The two DNSONLY hostnames have to resolve at the registry level, not just inside your zone. Log into your domain registrar and create glue records (sometimes labelled "child nameservers" or "register a host"):

  • ns1.example.com → 203.0.113.20
  • ns2.example.com → 203.0.113.21

Then change example.com's authoritative nameservers to those two glue records. Propagation takes 24–48 hours at the registry, longer at some recursive resolvers.

Step 6 — Verify replication

Create a throwaway test zone on the primary and confirm it appears on both DNSONLY nodes within a few seconds:

# on the primary
whmapi1 adddns domain=clustertest.example.com ip=203.0.113.10

Then query each DNSONLY node directly with dig:

dig @203.0.113.20 clustertest.example.com SOA
dig @203.0.113.21 clustertest.example.com SOA

Both should return the SOA record with server1.example.com. as the MNAME. If a node returns REFUSED or SERVFAIL, the cluster push failed — check /usr/local/cpanel/logs/dnsadmin_log on the primary for the error.

Clean up:

whmapi1 killdns domain=clustertest.example.com

Common gotchas

  • TLS certificate on DNSONLY. The cluster API uses HTTPS on 2087. If the DNSONLY node is using a self-signed cert from a hostname mismatch, WHM logs SSL certificate problem and refuses to push. Run AutoSSL on the DNSONLY box for its own hostname — see WHM AutoSSL failures.
  • Firewall. ConfigServer Firewall on either node will block 2087 unless you add the other node's IP to TCP_IN and the peer IP allowlist.
  • Mismatched cPanel versions. A primary on 11.124 stable will refuse to cluster with a DNSONLY on 11.120 lts. Match release tiers across the cluster.
  • NSD users. If you've switched the primary from BIND to NSD, the DNSONLY nodes must match. Mixed clusters work, but zone-format edge cases will bite you.
Is the DNSONLY license really free?+
Yes. cPanel issues DNSONLY licenses at no cost, self-issued by IP the first time cpkeyclt runs on a freshly installed DNSONLY server. There is no purchase step and no expiry as long as the IP keeps requesting the license.
Can I run a DNS cluster on the same server as cPanel?+
Technically yes, but it defeats the purpose. The whole point of the cluster is to keep DNS up when the primary cPanel box is down. Put the DNSONLY nodes on physically separate machines in different datacentres if possible.
How many DNSONLY nodes do I need?+
Two is the minimum for redundancy and what most registrars expect when you delegate a domain. Adding a third in a different region helps geographic latency for global customer bases but is optional.
Will the cluster replicate existing zones, or only new ones?+
Only new and modified zones replicate automatically. To push the entire existing zone set after building the cluster, run /scripts/dnscluster syncall on the primary.
Does the cluster work with PowerDNS instead of BIND?+
Yes. Switch each node's nameserver in WHM → Service Configuration → Nameserver Selection. The cluster API speaks to whichever backend is active, but all members of one cluster should run the same nameserver to avoid zone-format drift.
What happens if the primary is down when a customer changes a DNS record?+
They can't. The cPanel UI is on the primary, and the cluster API only pushes outbound from a cPanel node, not from DNSONLY. The DNSONLY nodes keep serving the last-known zones but can't accept edits. A second cPanel node in the cluster would solve this.

Next steps

Related articles

All tutorials & how-tos →
how to
Set up JetBackup 5 deduplication backups to cut storage cost
JetBackup 5.4 added a deduplication backup structure that fingerprints data in chunks and stores each unique chunk once — here's how it works, where it pays off, and how to turn it on.
6 min read
how to
Plesk 360 setup guide for centralized licenses and monitoring
Plesk 360 is the SaaS control plane for everyone running more than one Plesk box — license management, uptime monitoring, and SSO into every panel from one dashboard.
7 min read
how to
Use the Plesk REST API with reseller and customer accounts
Plesk Obsidian 18.0.79 opens the REST API to reseller and customer accounts and adds file, log, and impersonation endpoints — how to authenticate and use them.
7 min read
Switch in an afternoon

Switch from your current reseller — free.

We migrate active cPanel, Plesk, LiteSpeed and CloudLinux licenses from any reseller. We prorate the first month so you never pay twice, and your customers see zero downtime during the swap.