Migrating a cPanel Account

Moving domains or accounts between servers is just another necessity of server ownership. It may be necessary to upgrade your operating system, consolidate or decentralize your domains, get onto a different platform type (dedicated or cloud), or refresh your hardware to newer specifications. WHM makes it easy to move all or a portion of your cPanel accounts from an existing cPanel server using a variety of easy-to-use tools.

It’s important to remember that we are not moving domains when we migrate them, we are just copying them. While you are migrating, sites stay live at the origin server until DNS is changed.

There are three different methods we will look at for migrating, all of which are executed from the target server (the server to which we will be copying data and will eventually host the domain).

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

Items that are not migrated are excluded from the backup structure of the single cPanel account. This might include:

• 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

If there is anything that the site depends on outside the cPanel structure, you’ll need to set up manually and ahead of time. Everything you set up directly inside the cPanel account will be included.

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.

For a basic migration of a single account, you can’t ask for much more in terms of simplicity; it is a GUI after all! It also doesn’t require elevated access like the other two methods; if you can log into the cPanel account, you can usually migrate that account using this tool.

This method also works if you have a reseller with WHM access; you can use that reseller’s password in this tool replacing the cPanel user password to migrate a single account.

This tool will not do anything in terms of global configurations or version matching, nor will it affect the DNS of the migrated account. It also cannot work on every single source server; some hosts turn off the ability for cPanel accounts to make their backups. There is also the concern of sufficient free disk space on the source machine. Make sure there is enough room to make a full cPanel backup before starting this procedure.

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.

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.

Update DNS and Finalize Migration

After confirming that the new server is working as you expect, the only remaining step in bringing it live. Updating the DNS for the domain at its current nameservers is necessary. Because we lowered the TTL values at the start of the migration the new change should propagate around the Internet quickly. DNS propagation can still take a few hours to change completely. If DNS is hosted on the source server, you can change this directly in cPanel. Otherwise, check the documentation or help pages for your current nameservers for changing the A record (Liquid Web’s can be found here).

If you do happen to be using the source server as your nameserver, you will also need to make sure that DNS authority is shifted elsewhere: the target server, Liquid Web’s DNS server, or a 3rd party DNS service. Should the source server be terminated or the cPanel account deleted from the source machine, the domain’s zone files will stop working, and the site will go offline. So don’t skip this critical step in finishing your server move!

Need Help?

Liquid Web offers our customer migration services for all of its fully managed products. If a cPanel migration sounds overwhelming, we have a dedicated team available to guide you through the entire process! After ordering a new fully managed server, you can request a migration right from your Manage account. We aren’t limited just to cPanel sources, either. Our experts can analyze any migration and access method for feasibility and have an excellent success rate.

Ready to try your own migration? Order a new Managed Cloud VPS server today!