1. cPanel & WHM Documentation
  2. WHM
  3. Clusters
  4. DNS Cluster
whmui dns dnsclusters

DNS Cluster

Valid for versions 106 through the latest version

Version:

106

Last modified: February 28, 2024

Overview

A DNS cluster is a group of nameservers that share records and 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.

Warning:

All servers in the DNS cluster must run PowerDNS if domains that use DNSSEC exist in that cluster. cPanel & WHM supports DNS Security Extensions (DNSSEC) in DNS clusters. PowerDNS servers with domains that have DNSSEC configured can configure DNS clusters.

For more information about DNSSEC, read our How to Use cPanel’s PowerDNS and Zone Editor documentation.

Managing DNS clusters

Important:

Resellers must possess the DNS Clustering Account Creation Limit (ACL) privilege to view the DNS Clustering section of this interface. For more information about DNS cluster-related ACLs, read our Edit Reseller Nameservers and Privileges documentation.

Users who possess the All ACL privilege can add their own custom DNS servers to a cluster. Users with this ACL can also make changes to existing cluster members.

To modify DNS cluster settings, select whether to manage your DNS clusters as the root user or as a reseller from the Managing DNS Cluster as: menu.

  • Before adding custom DNS servers or changing existing cluster members, select the root setting from the Managing DNS Cluster as: menu.

Global Cluster Options

This section of the interface allows you to enable and disable DNS clustering. You can also use this section to configure the Failure threshold for cluster members setting.

Enable and disable DNS clustering

To enable or disable DNS clustering, perform one of the following actions:

  • To enable DNS clustering, click Enable DNS clustering.
  • To disable DNS clustering, click Disable DNS clustering.

Failure threshold for cluster members

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.

Note:

We recommend that you disable unresponsive DNS cluster members to improve performance.

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

  1. Select the desired setting:
    • Select 10 (Default) to use the default setting, which allows cluster members to fail up to ten dnsadmin commands.
      Note:

      We recommend that you use this setting.

    • Select the second setting to enter a custom failure threshold.
      Note:

      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 to keep all of the servers in your DNS cluster continuously online, regardless of the number of failed dnsadmin commands.
  2. To receive notifications when the system disables an unresponsive member in your DNS cluster, select the Receive a notification when WHM disables an unresponsive cluster member checkbox.
    Important:

    You must manually reenable disabled cluster members.

  3. Click Change.
    Important:

    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.

Add a new server to the cluster

Important:

You must perform steps in other interfaces to fully configure a DNS cluster. For more information, read our Guide to DNS Cluster Configurations documentation.

To add 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.
    Note:

    To enable DNS clustering with SoftLayer or VPS.NET, you must first obtain an API username and key from VPS.net or SoftLayer. Then, select 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 to add to the cluster in the Remote cPanel & WHM DNS host text box.
    Note:

    The /etc/ips.dnsmaster file contains the DNS cluster’s list of trusted nameserver IP addresses. If the IP address for a nameserver does not match a trusted IP address, you may experience problems when users create addon or parked domains. For more information about how to add a nameserver’s IP address to your trusted IP addresses, read our Guide to DNS Cluster Configurations documentation.

  4. Enter the WHM username for the nameserver in the Remote server username text box.
  5. Enter the nameserver’s API token hash in the Remote server API token text box. If you do not have a saved API token hash from the nameserver, log in to the nameserver and create a new API token in WHM’s Manage API Tokens interface (WHM » Home » Development » Manage API Tokens).
    Important:
    • After you create an API token, make certain that you save the token hash in a safe location.
    • When you create an API token for DNS clusters, use the DNS Clustering Access Control List (ACL) privilege. For more information, read the Edit Reseller Nameservers and Privileges documentation.
  6. Select Setup Reverse Trust Relationship to automatically configure the DNS cluster on the remote server.
    Note:
    • If you select this setting, 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 setting automatically sets the remote server’s DNS role to Standalone.
  7. Select Synchronize Zones Immediately if you want to synchronize the new server with the other nameservers in your cluster.
  8. Select Debug mode if you want WHM to record DNS clustering transactions in the /usr/local/cpanel/logs/dnsadmin_log file.
  9. Select a setting from the DNS Role menu to specify the server’s DNS role. The DNS role specifies how the server transfers information among the other servers in the DNS cluster.
    Note:

    If you select the Synchronize DNS role and selected Synchronize Zones Immediately in step 7 above, the server will pull all DNS zones from the remote server. This behavior is unique to the combination of the Synchronize role and the Synchronize Zones Immediately option.

  10. Click Submit to save your settings.

Unique DNS Clustering

Warning:

This setting only appears if you manage your DNS cluster as a reseller.

By default, WHM uses the DNS servers in the cluster belonging to the root user or reseller with root-level privileges. To add a different DNS server to the cluster, enable this setting.

To change this setting, perform one of the following actions, where username represents the reseller user:

  • To enable this setting, click Enable unique DNS clustering for accounts owned by username.
  • To disable this setting, click Disable unique DNS clustering for accounts owned by username.

If the root user configured a cluster member, resellers cannot change the settings of that member. However, a reseller can add an additional configuration, with some limitations:

  • If the root user set a server’s role to the Standalone role, then the reseller can select any role for the server.
  • If the root user set a server’s role to the Synchronize or Write-only role, if the reseller selects Standalone, the selection will be ignored.

Resellers can add a Standalone configuration if the root user did not configure the cluster member. However, the Synchronize and Write-only roles require root configuration.

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:

Column Description
Hostname The server’s hostname.
IP address The server’s IP address.
Username The 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.
Type The type of server: cPanel, SoftLayer, or VPS.NET.
Status The version of cPanel & WHM that the server currently runs, and an icon that indicates the server’s status.
  • If your server doesn’t run PowerDNS, this column displays a warning message instead of the cPanel & WHM version. This message notifies you that you must update your server to use PowerDNS if you wish to use DNSSEC clustering. To update your server to use PowerDNS, click the Upgrade link.
Server Type The server’s nameserver software.
DNS role The server’s DNS role. You can choose from the following settings:
  • Standalone — Servers with a Standalone DNS role receive changes from zones with newer serials (modified timestamps) but will not send signals to modify other servers. Most administrators use this setting on their DNS profile servers.
  • Synchronize — Servers with a Synchronize DNS role synchronize records between the local server and the remote server, prioritizing the server with the most recent changes. If a Synchronize server tries to push changes to a DNS zone that has been updated more recently than the Synchronize server, the DNS zone server will push the more up-to-date information back to the Synchronize server. Using the Synchronize setting on servers with DNS profiles can cause overwrite conflicts. Most administrators use this setting on their standard profile servers.
  • Write-only — Servers with a Write-Only DNS role write the local server’s records to the remote server without zone checks. This means that unlike Synchronize servers, Write-only servers can overwrite more recent DNS zones.
Important:
A Write-only server pushes records to the remote server without conflict resolution or checks. Two Write-only servers that attempt to write changes to a matching record on the same remote DNS profile server will cause a conflict and may corrupt data. Setting one or both of these DNS profile servers to Synchronize will avoid this problem.
You can use the menu in this column to change a server’s DNS role.
Actions You can use the icons in this column to modify a DNS cluster server or to delete a server from the DNS cluster.

Delete a server from a DNS cluster

Important:
  • 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