Migrating your Clients to another cPanel Server (cPanel to cPanel)

After moving hosting accounts from a cPanel & WHM® server to a new one, you may be wondering:

  • What changes do I need to make within WHMCS to associate my existing clients with the new cPanel server?
  • How do I ensure that all future automated module actions (for example, single sign-on, suspend, or terminated) are now all performed on the new cPanel server?

There are several methods available to you depending on your situation.

This troubleshooting guide assumes that your system administrator has already migrated the required client cPanel accounts from the old cPanel server to the new one.  

For more information, see cPanel documentation.

Method 1: Assign the New Server Record to Client's Product/Service

To assign the new server record to the appropriate product or service:

Configure the New cPanel Server in WHMCS

  1. Navigate to Configuration > System Settings > Servers.
  2. Add your new WHM & cPanel® server to WHMCS.  For more information, see  Adding a WHM & cPanel Server.

Assigning the new Server to a Client's Product/Service

  1. Navigate to Products/Services Tab in the Client Profile.
  2. Perform the steps for the appropriate option for your needs.

Option 1 - Change the Server for Each Client Individually

If you have a small number of clients for whom you wish assign the new server, then continue to step 4. Otherwise, skip to Option 2.

  1. Ensure you have correctly selected the client you wish to assign the new server to.
  2. Select the Product/Service you are modifying.
  3. Select the Server from the menu that you created above in step 2 to assign the new server to this client.
  4. Click Save Changes.

The client's server will now be associated with the new server.  In order to associate more clients with the new server,  please repeat steps 5 to 8 for each of them.

You may wish to use this method if you only need to move a small number of users. For example, you could use this if one or two clients need to move to a server with a greater capacity.

You may also want to use this method when moving clients gradually from an old server to a new one. This allows both servers to remain usable within WHMCS and does not require retiring the old server.

Option 2 - Change the Server for Clients in Bulk via MySQL® Query

This is an advanced method. Ask your database administrator or system administrator to perform this task. Always perform a complete file and database backup before performing bulk actions.

If you need to assign a new server to a large number of clients, you can perform a bulk action with a MySQL query that resembles the following example:

UPDATE tblhosting SET server = 'NEW_SERVER_ID' WHERE server = 'OLD_SERVER_ID';

The example above moves all server records, but you can customize your query for your needs.

When you run the query, make certain to change NEW_SERVER_ID and OLD_SERVER_ID to the IDs of the respective servers.

To determine the server ID, go to Configuration > System Settings > Servers and view the server's information. The ID will appear in the URL, as in the example below:

https:///<your_whmcs_host>/configservers.php?action=manage&id=1

In this example, the server ID is 1.

If you are using cPanel & WHM or another control panel, you can use a GUI tool like phpMyAdmin to run the query. Otherwise, use the mysql command line tool. If you need help, contact your system administrator.

Method 2: Server Switchover

This method replaces the old cPanel & WHM server's details with the new server's details in WHMCS.  This retires the old server and moves all of your clients to the new server.

This method requires that you move each account before updating the server information in WHMCS.  Then, you can update the server's details by going to Configuration > System Settings > Servers and editing the old server.

To update the server details:

  1. Replace the old cPanel server's hostname with the new cPanel server's hostname.
  2. Enter the new cPanel server IP address.
  3. If needed, change the nameservers to that of your new cPanel server.
  4. Enter the new server Username.
  5. Enter the new server Password.
  6. Enter API Token for the new server.
  7. Click Save Changes.

You do not need to associate each client and their products and services on the new server because the server ID did not change.

Troubleshooting using the Server Sync Tool

After you migrate accounts using either method, you may want to check whether accounts are working as expected.  The Server Sync Tool allows you to view this, including an overview of any discrepancies between WHMCS and your server's records.

One way to do this is by running Server Sync Tool, where during the Analyse stage you can see an overview of this along with any discrepancies between the service records within WHMCS and the records on your cPanel server.

  1. Begin by navigating to Configuration () > System Settings > Servers or, prior to WHMCS 8.0, Setup > Products/Services > Servers.
  1. Click the Sync Accounts button for the server you wish to  analyse.
  2. WHMCS will make an API call to the remote web server to fetch an  up-to-date list of account records. This may take a few seconds.
  3. Upon completion, an analysis summary report will be displayed to you that looks something like the following.

Do not click the Continue button if an account is missing.  Review the cPanel migration logs and make sure it was transferred to the new server.

For more information, see Server Sync Tool.

Further Reading