You can find our user documentation at

Check out our new API beta site!

Child pages
  • DNS Cluster
For cPanel & WHM version 70

Skip to end of metadata
Go to start of metadata

(WHM >> Home  >> Clusters >> DNS Cluster)


A DNS cluster is a group of nameservers that share records, which allows you to physically separate nameservers that handle the DNS requests from your web servers. This interface allows you to configure a DNS cluster and add servers to an existing DNS cluster.


For more information about the types of DNS cluster configuration and why you may wish to use a DNS cluster, read our Guide to DNS Cluster Configurations documentation.

DNS cluster requirements

To configure your DNS cluster, you must meet the following minimum requirements:

  • Clusters must include at least two servers. 
  • You must have at least one web server with cPanel & WHM installed. A DNS cluster that includes multiple cPanel DNSONLY™ servers and cPanel & WHM servers is also acceptable.
  • All machines in the DNS cluster must have cPanel & WHM or cPanel DNSONLY version 11 or higher installed. Some features may not work with older versions of cPanel & WHM.
  • All machines configured with PowerDNS must have DNSSEC disabled. 


  • WHM's DNS Cluster feature only provides redundancy for DNS. It does not add Apache or any other services to a DNS cluster configuration.
  • If you set a server in a DNS cluster to the write-only role, WHM will not check whether a DNS zone exists before you create an account. Because of this, it is possible to create the same domain name on two or more of these servers. If this occurs, the servers compete for updates to that domain.
  • cPanel DNSONLY software allows you to run a dedicated physical nameserver. It is essentially the "bare-bones" version of cPanel & WHM, which only replicates DNS zones to your other servers. Only install cPanel DNSONLY on nameservers that have no previous content on them. You can download the cPanel DNSONLY software for free.


cPanel & WHM does not support DNSSEC in DNS clusters.

  • Servers with domains that have DNSSEC configured will be unable to configure DNS clusters.
  • Servers with DNSSEC do not transmit DNSSEC data to cluster members in any form. This means DNS responses from the cluster members will not have the DNSSEC signatures. This can cause DNS resolution errors.

DNS Clustering

To modify DNS cluster settings, log in as the root user. If you log in as a reseller, you will not see the DNS Clustering section of this interface.

Modify Cluster Status

To enable or disable DNS clustering in WHM, perform the following steps:

  1. Select the desired option under the Modify Cluster Status heading:
    • Select Enable DNS clustering to enable DNS clusters.
    • Select Disable DNS clustering to disable DNS clusters.
  2. Click Change. A confirmation message will appear.
  3. Click Return to Cluster Status.


After you enable the DNS Cluster feature, specify which servers you wish to include in the DNS cluster.

  • You must sync each web server to its DNS servers.
  • You do not need to link dedicated DNS servers to each other, or link dedicated web servers to each other.

Global Cluster Options

The Failure threshold for cluster members setting allows you to specify the number of dnsadmin commands that may fail before WHM disables an unresponsive DNS cluster member.


  • We recommend that you disable unresponsive DNS cluster members in order to improve the performance of your server.
  • You must enable DNS clustering in order to view the Global Cluster Options section of this interface.

To configure the Failure threshold for cluster members setting, perform the following steps:

  1. Select an option from the Global Cluster Options section:
    • Select 10 (Default) to use the default option, which allows cluster members to fail up to ten dnsadmin commands.


      We recommend that you use this option.

    • Select the second option to enter a custom failure threshold.


      If server down times or network interruptions are common in your hosting environment, we recommend that you increase the failure number count so that the system does not mark certain cluster members as offline. This may also increase server and network load because the system may repeatedly send some DNS requests. 

    • Select Keep all cluster members online at all times if you wish to keep all of the servers in your DNS cluster continuously online, regardless of the number of failed dnsadmin commands.
  2. If you wish for WHM to notify you when it disables an unresponsive member in your DNS cluster, select Receive a notification when WHM disables an unresponsive cluster member.


    You must manually reenable a disabled cluster member.

  3. Click Change. A confirmation message will display.
  4. Click Return to Cluster Status.


If a cluster member in the sync role is offline for an extended period of time, resynchronize the other server's zones. This ensures that the cluster member is up-to-date.

Servers in your DNS cluster

This section allows you to view, add, and delete servers from your DNS cluster.

The Servers in your DNS cluster table displays the following information about each server in your DNS cluster:

HostnameThe server's hostname.
IP addressThe server's IP address.
UsernameThe WHM username that you used when you configured this server in the DNS cluster. Typically, this is either root or the username of a reseller account.
TypeThe type of server: cPanel, SoftLayer, or VPS.NET.
StatusThe version of cPanel & WHM that the server currently runs, and an icon that indicates the server's status.
DNS role

The server's DNS role. You can choose from the following options:

  • Standalone — This method fetches DNS records from the remote server, but does not write records from the local server to the remote server.
  • Synchronize — This method synchronizes records between the local server and the remote server.
  • Write-only — This method pushes the local server's records to write to the remote server, but does not query records from the remote server to write to the local server.

You can use the menu in this column to change a server's DNS role.

ActionsYou can use the icons in this column to modify a DNS cluster server or to delete a server from the DNS cluster.


Add a new server to the cluster

To add a a cPanel & WHM or cPanel DNSONLY server to the DNS cluster, perform the following steps:

  1. Select the server type from the Backend Type menu.


    To enable DNS clustering with SoftLayer or VPS.NET, you must first obtain an API username and key from or SoftLayer. Then, choose SoftLayer or VPS.NET from the Type menu.

  2. Click Configure. The cPanel DNS Remote Configuration interface will appear.
  3. Enter the hostname or IP address of the nameserver that you wish to link in the Remote cPanel & WHM DNS host text box.
  4. Enter the WHM username for the nameserver in the Remote server username text box.
  5. Enter the nameserver's API token hash or remote access key in the Remote server access hash text box.

    • Enter an API token hash that you saved on your workstation or create a new API token in WHM's Manage API Tokens interface (WHM >> Home >> Development >> Manage API Tokens).


      Make certain that after you create an API token, you save the token hash a safe location on your workstation so that you can use it with other features. The API Tokens table in WHM's Manage API Tokens interface (WHM >> Home >> Development >> Manage API Tokens) only displays the API tokens' names, rather than the tokens' hashes.

    • You can find the server's remote access key in WHM's Remote Access Key interface (WHM >> Home >> Clusters >> Remote Access Key). 


      We deprecated WHM's Remote Access Key feature in cPanel & WHM version 64. We strongly recommend that you use API tokens instead.

  6. Select Setup Reverse Trust Relationship for WHM to automatically configure the DNS cluster on the remote server.


    • If you select this option, you will not need to log in to WHM's DNS Cluster interface on the remote server. However, you may do so if you wish to modify the remote server's DNS cluster configuration.
    • This option automatically sets the remote server's DNS role to Standalone.
  7. Select Debug mode if you want WHM to record DNS clustering transactions in the /usr/local/cpanel/logs/error_log file.
  8. Select an option from the DNS Role menu to specify the server's DNS role.

  9. Click Submit to save your settings. When you return to the DNS Cluster interface, the remote server will appear in the Servers in your DNS Cluster table.

After you add the server to the cluster, synchronize the new DNS server with the other servers in the DNS cluster in WHM's Synchronize DNS Records interface (WHM >> Home >> DNS Functions >> Synchronize DNS Records)

To confirm that the new server functions, run the following command, where represents the server name, and ip represents the server's IP address:

dig +short @ip


We do not recommend that you set up the nameserver to synchronize data to a web server, because this creates extraneous zones on the web server. This means that you do not need to log in to WHM on the nameserver and set the web server's DNS role to Synchronize changes.

Delete a server from a DNS cluster


  • You must delete a server from a DNS zone before you add a replacement server to the DNS cluster. You cannot have two servers with the same hostname in a DNS cluster.
  • If you remove a server from a DNS cluster, the records will no longer synchronize with the other servers in the DNS cluster. The records on the deleted server will also no longer exist on the servers that remain in the DNS cluster.

To remove a cPanel & WHM or cPanel DNSONLY server from a DNS cluster, perform the following steps:

  1. Log in to the server that you wish to remove from the DNS cluster.
  2. Navigate to the DNS Cluster interface.
  3. In the Modify Cluster Status text box, select Disable DNS Clustering.
  4. Click Change.
  5. Click Return to Cluster Status.
  6. Log in to the servers that remain in the cluster.
  7. Navigate to the DNS Cluster interface (WHM >> Home >> Clusters >> DNS Cluster).
  8. Locate the server that you wish to delete.
  9. Click the x icon () under the Actions heading.

When you return to the DNS Cluster interface, the server will no longer appear in the list of servers in the DNS cluster.

Edit a server in a DNS Cluster

You can change a server's DNS role or edit the server's configuration settings at any time.

To edit a server's DNS role, perform the following steps:

  1. Locate the server that you wish to edit.
  2. In the DNS Role menu, select a new role for the server.
  3. Click the save icon () to save your changes.

To edit a server's configuration settings, perform the following steps:

  1. Locate the server you wish to edit.
  2. Click the edit icon () under the Actions heading. The cPanel DNS Remote Configuration interface will appear.
  3. After you make your changes to the server's settings, click Submit.

Additional documentation

There is no content with the specified labels

There is no content with the specified labels

There is no content with the specified labels