A configuration cluster in WHM allows you to link a master server to additional servers and automatically sync server configuration settings across all connected machines. After you set up the cluster, any changes you make to WHM's Update Preferences on the master server can automatically push to all cluster members, ensuring consistent configurations across your infrastructure.
This feature is essential for administrators managing multiple servers who want to maintain uniform settings without manually updating each machine individually.
What Is a Configuration Cluster?
The Configuration Cluster interface in WHM enables you to designate one server as the master and connect it to one or more additional servers. Once configured, the master server can distribute its configuration settings to all cluster members through WHM's Update Preferences interface (WHM >> Home >> Server Configuration >> Update Preferences).
This centralized management approach saves time and reduces configuration errors when maintaining multiple servers with identical or similar settings.
Important Prerequisites and Considerations
Before setting up a configuration cluster, keep these critical points in mind:
- Use API tokens instead of remote access keys: The Remote Access Key feature was deprecated in cPanel & WHM version 64. OBHost strongly recommends using API tokens for secure authentication between servers.
- Root-level access required: You must log in as a root-level user on the server you want to use as the master server. You also need root access when making configuration changes to push to cluster members.
- Enable settings distribution: After adding servers to the cluster, you must select the "Send my settings to all configuration cluster servers" checkbox in WHM's Update Preferences interface on the master server. This checkbox only appears after you add at least one server to the cluster.
- Master server visibility: If you log in to a non-master cluster server, the WHM interface will not indicate that the server is part of a configuration cluster. You can only view cluster membership information from the master server.
- Settings may be overwritten: Any configuration changes made directly on non-master servers may be overwritten when the master server pushes its settings to the cluster.
Understanding the Configuration Cluster Interface
The Configuration Cluster interface displays all servers linked to your current master server. For each connected server, you'll see:
- Server: The server's IP address or the hostname you assigned (for example, server1.example.com). You can use any domain name that resolves to the server's IP address, but using the server's hostname is recommended to prevent issues if domains migrate to other servers.
- User: The username of the server's root-level account, typically "root" by default.
- API Token or Remote Access Key: The signature version of the authentication credential used to connect to the remote server.
How to Add a Server to Your Configuration Cluster
Follow these steps to add a server to your configuration cluster:
- Log in to WHM as the root user on the server you want to designate as the master.
- Navigate to WHM >> Home >> Clusters >> Configuration Cluster.
- In the Configuration Cluster interface, locate the "Add a New Server" section.
- Enter the target server's hostname or IP address in the Server field.
- Enter the root username in the User field (typically "root").
- Provide either an API token or remote access key for authentication. Generate an API token in WHM >> Home >> Development >> Manage API Tokens on the target server before completing this step.
- Click the "Add Server" button to establish the connection.
The system will verify the connection and add the server to your cluster if authentication succeeds. The newly added server will appear in the list of cluster members.
Managing Configuration Distribution
After setting up your configuration cluster, configure how settings sync across servers:
- Navigate to WHM >> Home >> Server Configuration >> Update Preferences on your master server.
- Make any desired configuration changes to services like Apache, PHP, MySQL, or email settings.
- Select the "Send my settings to all configuration cluster servers" checkbox at the bottom of the page.
- Click "Save" to apply changes and push them to all cluster members.
The master server will connect to each cluster member and replicate the selected configuration settings automatically.
Best Practices for Configuration Clusters
To get the most from your configuration cluster setup, follow these recommendations:
- Use hostnames instead of IP addresses: Referencing servers by hostname makes your cluster more maintainable and prevents issues if IP addresses change.
- Document cluster membership: Keep records of which servers belong to which clusters, since non-master servers don't display their cluster membership in WHM.
- Test before wide deployment: When first setting up a cluster, test with a small number of servers to ensure settings sync correctly before adding more members.
- Avoid manual changes on non-master servers: Make all configuration changes on the master server to prevent them from being overwritten during the next sync.
- Regular API token rotation: Periodically update API tokens used for cluster authentication to maintain security best practices.
Importing Configurations from Remote Servers
If you need to import service configurations from a remote server rather than pushing from a master, use WHM's Transfer Tool interface (WHM >> Home >> Transfers >> Transfer Tool). The Configuration Cluster feature only pushes settings from master to cluster members, not the reverse direction.
Frequently Asked Questions
Can I have multiple master servers in a configuration cluster?
No, each configuration cluster has only one master server that distributes settings to cluster members. If you need to manage multiple independent server groups, create separate configuration clusters with different master servers.
What happens if the master server goes offline?
If the master server becomes unavailable, cluster members continue operating with their existing configurations. However, you won't be able to push new configuration updates until the master server is back online. Cluster members function independently and don't require constant connection to the master.
Which configuration settings sync through a configuration cluster?
The configuration cluster primarily syncs settings you configure in WHM's Update Preferences interface, including cPanel & WHM software updates, service configurations (Apache, PHP, MySQL), Tweak Settings, and various server-wide preferences. Account-specific data, website files, and databases do not sync through configuration clusters.
Can I remove a server from a configuration cluster?
Yes, you can remove a server from the cluster by navigating to the Configuration Cluster interface on the master server and clicking the remove or delete button next to the server you want to disconnect. The removed server will retain its current configuration but will no longer receive updates from the master.
If you need assistance setting up or managing configuration clusters on your servers, OBHost's support team is available 24/7 to help. Contact us at https://www.obhost.net/contact or email support@obhost.org for expert guidance on server clustering and configuration management.
