WHM/cPanel-to-WHM server migration guide

My personal checklist guide to streamline WHM-to-WHM server migrations as much as possible.

Every little thing I think about when migrating existing WHM/cPanel servers to another WHM server. (All this incredible hands-on experience generously given to me by the sudden abandonment of CentOS & RockyLinux distribution!! ARGGH!!!)

Follow my steps below to avoid:

• lengthy downtimes
• blocked ports
• hostname reversion issues
• WHM license failures
• untransferred data & settings
• …and most of all…ANGRY CLIENTS!

I already ran into all the obstacles so you don’t have to!

Why migrate from one WHM/cPanel server to another?

1. Because your server is so broken or hacked – that it doesn’t make any sense to waste time trying to fix it. Rebuilding a new server is faster, easier, and more secure! (Hopefully…you have a server image or provisioning script on hand to avoid doing everything from scratch.)

2. Because your server needs an update – perhaps it’s too outdated, or like my situation…CentOS distro was suddenly abandoned and I had to roll out all client servers to a new distribution before our CentOS servers reached EOL. (I chose AlmaLinux, an RHEL-alternate, in case you’re wondering.) FYI: I also had servers on RockyLinux, which also lost support, but luckily there was an easy script to switch to AlmaLinux.

• FYI: cPanel’s official documentation conversion script for RockyLinux > AlmaLinux was initially incorrect, and support told me to use curl -O https://raw.githubusercontent.com/AlmaLinux/almalinux-deploy/master/almalinux-deploy.sh; bash almalinux-deploy.sh (maybe they’ve corrected it by now). Also don’t worry if command ends with /etc/grub.d/00_tuned: line 26: /etc/tuned/bootcmdline: No such file or directory it’s harmless and can be ignored.

3. You want a new physical host – perhaps your old provider or the physical server sucked. And you want to roll out to a new physical host with better performance, etc.

Steps for a smooth migration

Steps 1-5 should be done BEFORE the actual migration time. Then when it comes to migration time, you’re ready to go and you’re in and out. Setting yourself up for the smallest downtime possible.

1. Client notification

Notify all clients that you need to migrate them to a new server. Explain that it’s to have the latest operating system, updated features, updated security, and also that it may be required to run the latest versions of websites and plugins.

• Request clients to update their WordPress, themes, and plugins as much as possible. Then switch to the latest PHP version available.
• Request a time window when you can migrate, to minimize downtime and avoid affecting their business.

2. License preparation

The old server should already have a WHM license. The new server will need a “trial license”. You can request a trial license by sending an email to [email protected]. You’ll have to list the old server IP and the new server IP for every server migration you plan.

If you’re using LiteSpeed server or any other server software that needs licenses, make sure that the licenses are updated and available in case you have to reactivate them.

3. Old server prep (pre-transfer)

• fixquotas – run /usr/local/cpanel/scripts/fixquotas to see the accurate disk usage of each account.
• clear space – find and delete unnecessary files for accounts using tons of space.
  • Old backups files, overgrown logs, unnecessary duplicates or archives, cache directories. Perhaps even giant database tables with unnecessary logs (security, redirects, visitor tracking, etc).
  • Ask clients beforehand before deleting things. Or point these out to clients to delete it themselves.
• optimize DB tables – change large database tables to use InnoDB instead of MyISAM. Can do it via phpMyAdmin or LiteSpeed Cache plugin. Also run optimize command to trim down their size.
• upgrade PHP – on as many sites as you can to the latest major PHP version (PHP 8.5 when I wrote this.)
• allow SSH pass access – from WHM backend if you want to use pass-authorization for the transfer.

Of course, you can just continue on to the migration without these prep steps but I find them extremely helpful for identifying potential migration problems beforehand. Also, pruning large account sizes and overgrown data will speed up migration time which also means shorter downtimes for clients!

4. New server prep (provision)

• provision (script) – provision the new server. Fire up a new instance and install WHM with your desired configs. Or if you’re doing many servers, it’s best to have a clone copy ready to go (which then only requires minimal reconfiguring).
• match root pass – reuse same root pass as old server (if you like).
• disk resize – don’t forget to resize your disk instance. I sometimes like to fire up small instances (to save money) while I prep them beforehand and then resize later. Don’t forget to upsize the disk, or you’ll have transfer problems and have to redo (argh!).
• give SSH access – make sure the new server allows SSH access. To make things easier, I allow SSH password authorization at first.
• WHM > software > system update – update everything.
• basic webhost manager setup > basic config > IPv4 > set to your original server IP. (So transferred sites already take on original IP and you don’t have to change this again later.)

5. DNS preparation

• add Cloudflare entries – I do all my DNS management on Cloudflare and never use the server’s nameserver function (which I usually have disabled).
  • I have A records for both the old server and new server.
  • Old server hostname is set to “serverold” and new server hostname is set to “server” (or whatever sub-domain you were using for your old server).
• edit server hosts file – edit /etc/hosts for both old and new server to reflect their temporary hostname and IP.
• change old server hostname to something like “serverold.domain.com” using hostnamectl set-hostname serverold.domain.com (then verify correct hostname using hostnamectl)
• configure new server hostname and IP to match original (if that’s what you want) using hostnamectl set-hostname server.domain.com
  • if needed, other places to see what hostname is set to are /etc/sysconfig/network and /etc/hostname
• register WHM license on new server – /usr/local/cpanel/cpkeyclt (don’t do this until hostname is set correctly)
• transfer prep (DNS test) – don’t know why I wrote this and I hope I remember later.

6. Data transfer

Use WHM transfer tool (from new server):

• Enter origin server IP, SSH port, and password (if using password authentication). Then click [Scan].
• Scan finishes and you see listed accounts, choose page size “ALL” so you can see everything. On both [Accounts] and [Packages] tabs, I select all. Can do it in parts if you’re expecting certain large accounts to give you problems. Server to server transfer is very fast anyway.
• Then on the [Service Configurations] tab…I usually select AutoSSL Options, Backups, cPanel & WHM, EXIM, Hulk, ModSecurity, User Interface Themes. Skipping the Database Server, Easy Apache, and GreyList. The rest I don’t select as your new server will have more updated info anyway.
• If you see… (argh I forgot what I was gonna say here).
• If you have reseller accounts, you will see the reseller accounts listed. You’ll have to expand each of those individually and check the “Reseller Privileges” then click [Apply] button on right side.
• Then continue with the transfer.

If you have transfer issues:

• If you get error message relating to any ports (usually your SSH port)…then open the port and reload firewall
  • firewall-cmd --permanent --add-port=22/tcp – opens SSH port 22 (or change if you have custom port number)
  • firewall-cmd --reload – reloads firewall to apply changes
• You can manually cancel WHM transfers using this guide. Or can also stop process in WHM process manager.
• usually there will be warning messages
  • COMMON ERROR #1 i care about are RSYNC partial transfer (so i know to manually push files) A non-fatal error occurred during rsync streaming: Partial transfer due to error
  • COMMON ERROR #2 i care about are DB transfer errors. this way i know to push DB manually The MySQL restore process exited with the error “255”. Removed empty DB for failed restore of “user123_wp_isyv1”. The system has saved the database archive data in the directory “/home/user123/cpmove_failed_mysql_dbs.1728716320”. You may use this directory’s contents to restore your data manually. The MySQL restore process exited with the error “255”. Removed empty DB for failed restore of “user123_wp_isyv1”. Failed to write to DBI subprocess: Bad file descriptor
  • any message about “system not authoritative zone” is not an alarm, it’s probably due to you using Cloudflare as your authoritative DNS zone/server.
• view transfer logs
• copy over again using “Overwrite” or “Overwite with Delete” option

7. DNS follow-up

• swap IP – once accounts and files are transferred to new server, I swap IP’s using my hardware provider interface.
• update hostname & hosts – update server hostname using hostnamectl set-hostname server.domain.com and update /etc/hosts file to use correct hostnames and IP’s.

8. Post migration follow-up

• enable Litespeed server (if you’re using this)
• make sure all PHP versions and INI configs are matching. you can fix just about any old PHP compatibility issues by updating core, themes, plugin.
  • if clients complain, you can enable cloudlinux for outdated PHP…or move them back temporarily to old server.
• make sure sites work (both frontend site and backend login page)
• go to WP Toolkit and scan for each cPanel account. There may be breaks (for example mysql only allows DB usernames up to 32 characters)
• fixquotas – run /usr/local/cpanel/scripts/fixquotas to see that account sizes match
• regenerate SSL for server hostname – there’s usually a bit of hassle for this. below are my usual steps. do each one until you see that it works. may have to wait a few minutes to hours or even 1 day to notice that it’s working. you might also have to check from an incognito browser to see the HTTPS lock on the address bar.
  • verify proper server IP is listed everywhere, and pointing to the right server hostname (sometimes wrong server hostname or IP shows when clone instances). check following locations below and change IP if you see it listed incorrectly:
    • WHM > Basic WebHost Manager Setup > Basic Config > IPv4 setup – check IP here.
    • /etc/hosts – remove unused IP’s or incorrect/outdated domain names as well
    • /var/cpanel/mainip
    • /etc/ips – probably not listed (and doesn’t need to be)
    • /etc/sysconfig/network-scripts/*networkdevice* – IP probably not listed, and not necessary
    • /etc/sysconfig/network – IP probably not listed, but verify correct server hostname here
    • if you corrected anything, use this command to restart network service and assign new IP (it didn’t work for me on RockyLinux 9.x and wasn’t necessary anyway) service network restart
  • delete unnecessary DNS zones – using WHM > DNS Functions > Delete a DNS Zone > search the word “server” or any other incorrect domain names
  • DNS Cleanup – use WHM > Perform a DNS Cleanup
  • Delete unused SSL certificates – WHM > SSL Storage Manager > search for unused hostnames and delete their certificates and associated key as well.
  • reset DNS zone – to remove outdated DNS records created during migration (necessary if server changed IP) using whmapi1 resetzone domain=yourserverdomain.com. You only need this for server hostname domain.
  • add A record for server hostname – using WHM > DNS Functions > Add an A Entry for Your Hostname. Make sure proper IP shows.
  • Regenerate all SSL certificates – use this command pay attention to any error messages you see, especially for domains that still didn’t get their SSL generated. /usr/local/cpanel/bin/checkallsslcerts --verbose
  • This should be enough to generate proper SSL for the server hostname. If not, then….
  • Perform a DNS cleanup
  • WHM > DNS Functions > DNS Zone Manager – go into server hostname domain, and check that server A record is pointing to the correct IP.
• database connection errors:
  • Quite often, databases do not transfer fully because of some issue with a specific table. Usually something like too long of an index key. You can resolve this by manually exporting the table again by changing the table storage engine to InnoDB (if it isn’t already).
  • You’ll also find that the the table-user creation somehow doesn’t work right. Easiest way to get around this is by creating a new user. But if you must get the absolute same DB user working, and willing to resolve it the long painful way…you’ll probably have to do a combination of logging into the MySQL console and deleting the user and/or also deleting the user files from the MySQL user directories in the command line.
• notifying client to check their most critical sites
• power-down old server, to see that all critical functions run without it. eventually delete old server within 1 week
• check backup configs – verify backup configs transferred (including offsite backup settings), and force-run backup on new server using /usr/local/cpanel/bin/backup --force
• regenerate API token for whatever 3rd-party connections you have (like WHMCS or other centralized control panel)

References:

• How do you programmatically add or remove a DNS record from WHM/cPanel? – Vander Host (knowledgebase)
• How to change the primary IP address of a WHM/cPanel Server – Boxis.net
• How to Set and Change Hostname in Rocky Linux – Atlantic.Net

Did I miss anything? Lemme know and I’ll add it below.