Skip to content

cPanel DNS-Only Cluster — Default Setup

Overview

A dedicated DNS-Only cluster is the correct and recommended architecture for shared hosting environments where multiple WHM/cPanel servers need to serve domains under the same nameservers. The DNS-Only nodes act as authoritative nameservers, while the web servers synchronize zones to them.

Architecture

Web Server 1  ──┐
                ├──► DNS-Only Node 1 (ns1)
Web Server 2  ──┤
                └──► DNS-Only Node 2 (ns2)
  • Web servers handle hosting accounts and push DNS zones to the cluster
  • DNS-Only nodes are authoritative nameservers only — no hosting, no cPanel accounts
  • NS nodes can be geographically distributed across different providers or regions — as long as network connectivity between nodes and correct IP assignment for NS records is in place

Cluster Roles

Getting the roles right is critical. Misconfigured roles are the most common cause of sync issues.

On each Web Server (WHM → DNS Cluster config)

Target Node Role
DNS-Only Node 1 Synchronize
DNS-Only Node 2 Synchronize

Synchronize ensures both web servers push zone changes to all DNS nodes and keep records up to date.

On each DNS-Only Node (WHM → DNS Cluster config)

Target Server Role
Web Server 1 Standalone
Web Server 2 Standalone

Standalone on the DNS-Only node side means it does not write back to the web servers — it only receives and serves zones.

Do not use Write-only on web servers targeting DNS-Only nodes. Use Synchronize to ensure both nodes stay consistent.

DNS Backend

PowerDNS (PDNS) is the recommended and default backend.

  • BIND is considered outdated for this use case
  • PDNS is the preferred backend going forward — keep it as default on all DNS-Only nodes

Nameserver IP Changes

When changing the IP of a nameserver node:

  1. Update the A record in the authoritative zone on the main web server
  2. Propagate the zone update to all DNS-Only nodes via the cluster
  3. Update the glue records at the domain registrar for the nameserver hostnames

Propagation delay is expected after glue record changes. If only one NS IP changes, the other nameserver(s) remain operational — no full DNS outage should occur. In practice, NS IP migrations across multiple nodes have been done without downtime.

Multi-Server Account Conflicts

When two web servers share the same DNS cluster:

  • If a domain/zone already exists on one web server and an account with the same domain is created on the other, the cluster will block it — the zone already exists
  • This also affects account migrations: migrating an account between web servers will conflict if the DNS zone is included
  • Fix: exclude DNS zone migration when moving accounts between servers in the same cluster (--skiphomedir / exclude DNS option in transfer wizard)
  • Old accounts on one server and new accounts on another server can coexist without issues, provided no duplicate domains exist across both servers

Best Practices Summary

  • Use Synchronize role on web servers pointing to DNS-Only nodes — not Write-only
  • Use Standalone role on DNS-Only nodes for all web servers
  • Use PowerDNS backend on all DNS-Only nodes
  • Place DNS-Only nodes in separate locations/providers for redundancy
  • Update both the zone A record and the registrar glue records when changing NS IPs
  • When migrating accounts between servers in the same cluster, exclude DNS zones to avoid conflicts
  • Avoid creating accounts with duplicate domain names across servers sharing the same cluster

Verification Commands

Check cluster sync status from a web server: 

whmapi1 dnscluster_list

Check zone existence on a DNS-Only node: 

pdnsutil list-all-zones

Force zone sync from web server to cluster: 

/scripts/dnscluster synczone <domain>

Sync all zones: 

/scripts/dnscluster syncall