How to Fix cPanel & WHM DNS Cluster Sync Failures, API Token Authentication & Split-Brain Zones in Pakistan

Operating distributed authoritative nameservers across enterprise web clusters is essential for redundancy, low-latency anycast resolution, and zero-downtime website failover. For web hosting providers and multi-server enterprises in Pakistan, cPanel & WHM’s native DNS clustering engine allows multiple cPanel web hosts to replicate DNS zone changes directly to dedicated, standalone cPanel DNSOnly nameservers (such as ns1.example.pk and ns2.example.pk).

However, when network partitions occur across transit links, API tokens expire, or write relationships are misconfigured, the cluster can suffer from catastrophic split-brain zone divergence. In this state, web nodes fail to sync updates, SOA serial numbers drift out of phase, and authoritative nameservers return conflicting DNS records to local ISPs like PTCL, Nayatel, and StormFiber.

In this deep-dive guide, we will unpack the internal architecture of cpanel_dnsadmin, audit the cluster authentication pipeline, and demonstrate how to recover corrupted zones without service disruption.

---

1. Understanding cPanel’s DNS Clustering Architecture

The cPanel DNS cluster operates on an agent-daemon model. Each web hosting node runs the client script /scripts/dnscluster, which communicates over HTTPS (port 2087) with the cpanel_dnsadmin daemon running on remote DNSOnly nodes.

+------------------------------------+
|   cPanel Web Host (Web1.pk)        |
|   /scripts/dnscluster client       |
+-----------------+------------------+
                  |  Port 2087 (WHM API v1 / cpanel_dnsadmin)
                  v
+-----------------+------------------+
|   Dedicated cPanel DNSOnly Node    |
|   `cpanel_dnsadmin` Daemon         |
|   BIND (named) / PowerDNS Engine   |
+------------------------------------+

Cluster Relationship Modes

When linking a web node to a DNSOnly server in WHM (Home » Clusters » DNS Cluster), cPanel provides three synchronization roles:

1. Synchronize Changes (Bi-directional): Zone modifications on this server update the cluster, and zone modifications on other nodes replicate back to this server.
2. Write-Only (One-way): The local web server pushes its zone creations and edits to the DNS cluster node, but never imports zones generated by other servers in the cluster.
3. Standalone: The server operates in isolation and does not sync records to the cluster.

[!CAUTION] Configuring multiple web hosting nodes with Synchronize Changes directly to each other without dedicated DNSOnly hub nodes frequently leads to circular sync deadlocks and race conditions. For production multi-server fleets, web nodes must always be configured as Write-Only toward dedicated nameservers.

If you are scaling multi-tenant clusters or running high-density hosting nodes, deploying your authoritative nameservers on bare-metal Dedicated Servers or low-latency Dedicated Servers in Pakistan guarantees isolated network sockets and unmetered local routing.

---

2. Diagnosing cpanel_dnsadmin API Token & SSL Handshake Errors

The most common cause of cluster synchronization failure is an authentication timeout or TLS rejection between the web node and the remote nameserver.

Checking Cluster Node Configuration

cPanel stores cluster peer configs in /var/cpanel/cluster/root/config/:

# List all configured cluster peer connections
ls -la /var/cpanel/cluster/root/config/

# View configuration for a specific nameserver
cat /var/cpanel/cluster/root/config/ns1.nextgen.pk

A healthy config file contains the remote host address, the API user (root), the authentication type (hash or token), and the encrypted token payload:

host=ns1.nextgen.pk
user=root
type=token
auth=WHMAPITOKENSTRINGHEXVALUE987654321
action=writeonly

Testing Connection via CLI

Execute the native diagnostic check from the cPanel web node:

# Test connectivity and authentication against all cluster nodes
/scripts/dnscluster status

If the connection fails with: [cpanel_dnsadmin] SSL Connection Failed: 500 Can't connect to ns1.nextgen.pk:2087 (certificate verify failed)

Verify that the remote DNSOnly node has a valid, non-expired TLS certificate installed on its cPanel service daemon (cpsrvd):

# Verify the remote WHM SSL certificate
openssl s_client -connect ns1.nextgen.pk:2087 -servername ns1.nextgen.pk </dev/null 2>/dev/null | openssl x509 -noout -dates -subject

If the certificate is expired or invalid on the DNSOnly node, log in to the DNSOnly server via SSH and execute:

/usr/local/cpanel/bin/checkallsslcerts --force

---

3. Detecting and Resolving Split-Brain Zone Divergence

When two different servers believe they own the same zone file, or when a network disconnect halts replication while local edits continue, the zone enters a split-brain state. The local web server updates its local BIND zone /var/named/example.pk.db, but the remote DNSOnly node retains stale records.

Comparing SOA Serials Across Cluster Nodes

Run this shell one-liner to query the SOA serial number of your domain across your web node and all authoritative nameservers:

DOMAIN="example.pk"
NAMESERVERS=("localhost" "ns1.nextgen.pk" "ns2.nextgen.pk")

echo "=== SOA Serial Comparison for $DOMAIN ==="
for ns in "${NAMESERVERS[@]}"; do
    SERIAL=$(dig +short @$ns $DOMAIN SOA | awk '{print $3}')
    echo "$ns authoritative serial: $SERIAL"
done

If localhost reports serial 2026100405 while ns1.nextgen.pk reports 2026092001, the remote cluster node is out of date and rejecting stale incremental syncs.

Forcing Incremental & Full Zone Cluster Resynchronization

To push local zones and force authoritative nameservers to update their records, use cPanel’s internal maintenance binaries:

# 1. Sync a single domain zone to the cluster
/scripts/dnscluster synczone example.pk

# 2. Force a full cluster synchronization for all zones hosted on the server
/scripts/dnscluster syncall --force

Resolving “Zone Already Exists” Clashes

If an account was migrated between two web servers or deleted incompletely, the DNSOnly node may refuse to accept updates due to ownership locking. To resolve this:

# SSH into the DNSOnly node (ns1.nextgen.pk)
# Check if the zone file is present in BIND
ls -l /var/named/example.pk.db

# Verify zone ownership mapping in cPanel userdb
grep "example.pk" /etc/userdomains

# Remove orphan zone on DNSOnly node if web host migration moved the primary owner
/scripts/killdns example.pk

# Return to the active Web Host node and re-push the authoritative zone
/scripts/dnscluster synczone example.pk

---

4. Automating DNS Cluster Health Monitoring

To ensure your production clusters never silently desynchronize, deploy a lightweight cron verification script on your primary web hosting nodes:

#!/usr/bin/env bash
# /usr/local/sbin/check_dns_cluster.sh
set -euo pipefail

ALERT_EMAIL="[email protected]"
HOSTNAME=$(hostname -f)
STATUS_OUTPUT=$(/scripts/dnscluster status 2>&1)

if echo "$STATUS_OUTPUT" | grep -Ei "fail|error|refused|timed out"; then
    echo "CRITICAL: cPanel DNS Cluster failure detected on $HOSTNAME" | mail -s "ALERT: DNS Cluster Sync Failure [$HOSTNAME]" "$ALERT_EMAIL" <<EOF
cPanel DNS Cluster Error detected on $HOSTNAME:

$STATUS_OUTPUT

Please inspect /var/cpanel/cluster/root/config/ and verify port 2087 connectivity.
EOF
fi

Make the script executable and add it to root’s crontab:

chmod 700 /usr/local/sbin/check_dns_cluster.sh
crontab -e
# Run health check every 30 minutes
*/30 * * * * /usr/local/sbin/check_dns_cluster.sh >/dev/null 2>&1

For hardening your DNS infrastructure further, explore our deep-dive guides on cPanel Named BIND DNSSEC Key Rollover and cPanel ProFTPD Hardening.

---