What Will Be Migrated?
Essentially, everything that can be associated with one specific cPanel account is included in the cPanel backup structure. This includes, but is not limited to:- metadata for setting up the account, like the username, password, list of domains, DNS zone file, and custom apache includes files
- full home directory of the account, including the document root (site files), email files and forwarders for all the owned domains
- MySQL databases, users, and grants that are mapped to the account
- SSL keys and certificates
- statistics files like bandwidth usage or AWStats
- databases used by the account that belongs to a completely different cPanel account that is not part of your migration
- grants or databases set up from the command line and not mapped to your cPanel account
- other file dependencies outside the cPanel user’s home directory (such as the /images directory on another partition)
- extra programs and configurations that are set up server-wide, even if they are only installed for one user’s benefit (such as Sphinx or ImageMagick)
- server-wide configurations such as email sending limits or global PHP settings
Getting Ready To Migrate
When starting a migration, the end goal should be in mind: updating DNS to make the domain live on the target server. So, the first thing we should do is determine where DNS is hosted for the domains we are migrating, and lower the TTL value for the A records, without actually changing the IP address values. This allows for quicker propagation when we do eventually change the IPs. If your DNS is in several locations, you might consider consolidating it to a single location in advance. If that happens to be Liquid Web’s shared nameservers, you can use the Live Import feature when setting up your zone files to import much of the public DNS zone file without effort. This will let you change your DNS to Liquid Web without changing any of the traffic to your sites. We should also have a look at the versions of software on the source machine and make sure that something compatible is available on the target machine. This can be as thorough as you like, but I recommend at least looking at the PHP version on the old server and what is available in EasyApache 4 on the new server, and if possible, adding that version. Finally, we will need to have some level of access on the source server, either credential for root or for the cPanel user we are migrating. The access level will define the method we use.Copying Data: cPanel Account or Reseller Access
If you only happen to have a cPanel account username and password, there are two options. The first is to create a backup using the cPanel GUI on the source server, download it to the target server, and restore it from the command line. For ease of use, these functions are encompassed in the WHM tool handily titled “Copy an Account From Another Server With an Account Password”.
This cPanel tool, like all the others we will go over, is used on the target server. It allows you to enter a domain name, hostname, or IP address for a source server, as well as the username and password combination for logging into cPanel. The tool will function very well for a single cPanel account if the servers can reach each other and the source server supports a generation of backups from the cPanel account.
The copy tool will perform the following actions:
- Connect to the source cPanel server and log in using provided credentials.
- Start a generation of a cPanel backup to the local directory.
- Recheck the backup generation once per minute to see if it is complete.
- Once the backup is finished, download the backup to a temporary directory on the local server.
- Restore the backup and delete the backup file.
Copying Data: WHM Access
With root-level WHM access, it becomes effortless to migrate multiple cPanel accounts at once. This is the same concept as the cPanel tool, but is rolled into a more broadly termed “Transfer Tool”.
This tool works with root-level SSH access to the source server using a password, key, or SSH user with privileges to escalate to root. After entering the source server hostname or IP and the SSH information and credentials, the tool will collect a list of accounts on the source machine and present a checklist of accounts it can migrate for you. After making your selections, it works in parallel to bring accounts into the new server in the same fashion as the cPanel-only access tool above.
If you are bringing over a selection of users or even a full server into a new machine, or are combining accounts from multiple servers into one, this graphical tool is ideal. It also can bring over basic configurations from the source server into the target server, to help match the WHM environments.
There are some pitfalls to this method, however, including the need for SSH access as root to the source server. Reseller or cPanel user passwords won’t work here either. You need to be able to get into the server as the root user. Again, there is the need for sufficient disk space on the source server.
Note
Filling up your hard disk completely with temporary backup files could cause all your sites on the source server to go offline!
Copying Data: SSH Access
A command line method for migrating a single cPanel account is available as well. A backup can be created on the source server using the pkgacct function:/scripts/pkgacct username
By default, pkgacct will make a full backup of the user specified, and place the backup at /home/cpmove-username.tar.gz. It might be preferable to place the backup inside the user’s home directory instead and give it a unique name; this can be done by adding the –userbackup flag:
/scripts/pkgacct --userbackup username
The command will make the same backup, but instead, it will be placed at /home/username/backup-mm.dd.yyyy_hh:mm:ss_username.tar.gz, with the unique identifier of the start time of the backup task.
After the backup is created, it can be copied over to the new server using your favorite method. You may prefer to use scp from the target server, just in case the source server has a rootkit we don’t know about:
scp root@123.45.67.89:/home/cpmove-username.tar.gz /home/
This will place the backup in the /home/ directory when executing from the target machine. You can then easily restore using the restorepkg command:
/scripts/restorepkg /home/cpmove-username.tar.gz
That’s all! The account will be recreated, reconfigured, and repopulated with the contents of the backup.
A more accurate and flexible method for migrating cPanel accounts is to use command line tools on both servers to create targeted backups of only the data you need to restore the account. Then you can bring over additional files and databases to complete the backup separately. That method is quite a bit more complex than the tools we are covering, and outside the scope of this article. If you have disk space issues on your source server that can’t be reconciled, or require more precise control to specific portions of the cPanel accounts that are being migrated, you can read a bit more at this blog post. You can check the help text for the /scripts/pkgacct command by running it without arguments.
Verify Data Migration
After completing the account migration using any of the graphical methods, you should be presented with the transfer session log. This log lists any errors that may have occurred during the transfer, such as a missing file, or a conflict with another account. If there are no issues, you’ll be able to check the “List Accounts” function on your target WHM panel to see the migrated accounts. To test the functionality of these migrated accounts, we recommend modifying your computer’s hosts file and browse the new server directly. Changing your /etc/hosts file is the most accurate method of testing since the server and your browser both believe that this is real live traffic.Migration Troubleshooting
Some common issues encountered during a cPanel migration include:- Naming conflicts. If a conflict is found, the account will fail to restore. If using the WHM Transfer Tool, it will detect these conflicts before you start the task, and allow you to rename the restored account. But, the cPanel-level tool may not verify this before starting and fail part way through the restore. In this case, you can download the backup from the source server, upload it to the target server, and use the command line restorepkg tool to load the package with a new name:
/scripts/restorepkg --newuser anothername /path/to/uploaded/backup-file.tar.gz
- Database name conflicts. In these cases, the conflict is not fatal; the restore command will instead change the name of the database (usually by putting a ‘2’ at the end) and then restore the database there instead. You will have to go into your website files and change any pointers to the database name to the new one.
- Disk space issues. There must be enough room on the new server to completely extract the cPanel backup; WHM generally calculates this by multiplying the size of the backup by about 3. The best cure for this is to clean up the disk space on the target server, but if this is not plausible (and you know the account will fit), you can fall back to the manual method of skipping the home directory in the package and bringing it over separately.
