Overview
The Configuration Cluster feature in WHM allows a master server to push its configuration settings to secondary servers, keeping them synchronized. If you need to update a server's connection details (such as the username or API token) in the cluster, you can edit it directly from this interface. This is commonly needed when API tokens are rotated or when server credentials change.
Step 1: Log in to the Master Server's WHM
Log in to WHM on the master server of your configuration cluster. The Configuration Cluster interface is only available on the master server — changes cannot be made from a secondary server's perspective.
Step 2: Open the Configuration Cluster Interface
In the WHM sidebar, navigate to:
Home » Clusters » Configuration Cluster
Step 3: Locate the Server to Edit
Find the server you want to modify in the configuration cluster table. Each row displays the server's hostname or IP address, the username, and the API token or remote access key used for authentication.
Step 4: Edit the Server Settings
Click the Edit button (or arrow icon) that corresponds to the server you wish to modify. You can update any of the following fields:
- Server — The hostname or IP address of the secondary server.
- User — The root-level account username on the secondary server (defaults to
root). - API Token or Remote Access Key — The authentication credential used to connect to the secondary server.
Step 5: Save the Changes
Click Save to apply your changes. The master server will use the updated credentials the next time it pushes configuration changes to the secondary server.
Important Notes
- Master server only — You can only view and edit the configuration cluster from the master server. If you log in to a secondary server, the interface will not indicate that it is part of a cluster.
- API tokens recommended — cPanel has deprecated Remote Access Keys and plans to remove them in a future release. Use API tokens instead. You can generate an API token in WHM under Home » Development » Manage API Tokens. The token must have the root-level Everything ACL privilege.
- Settings may be overwritten — If you make changes directly on a secondary server, the master server's next push may overwrite those changes.
- Test the connection — After saving, verify that the master server can still communicate with the secondary server by pushing a configuration update via Home » Server Configuration » Update Preferences.
Troubleshooting
- Connection fails after editing — Double-check the API token or remote access key. Ensure it is valid and has not expired. Also verify that the secondary server's hostname resolves correctly and that firewall rules allow connections on port
2087. - Changes not syncing — Make sure the Send my settings to all configuration cluster servers checkbox is enabled in Home » Server Configuration » Update Preferences.
For the official cPanel documentation, visit the Configuration Cluster page.
