sysadmin

cPanel Server Migration Guide

Migrating your websites from one server to another can be a difficult and time consuming process, but with preparation and consideration, it can go smoothly.  Throughout my time as a systems administrator, migrations have been some of the most time consuming tasks I’ve worked on. The purpose of this guide is to provide you with the benefit of my experience so that you know what type of issues you may run into, and how you can best pre-emptively avoid those issues.

cPanel has fantastic tools for migrations, and the scope of this guide is meant for users migrating from one cPanel environment to another, however a lot of the general principles here apply to any server migration.

I will break down your migration into a few phases:

  1. Planning – This is stuff that you do before the migration begins to prepare.
  2. Preparation – This is stuff that you do immediately before the migration (day of).
  3. Migration – This is the actual process of migrating the data.
  4. Wrap Up – Cleaning things up to finalize the transition.

cPanel’s Migration Tools

cPanel has included tools for backing up most of the information owned by each user account including:

    • Home directory (all of the user’s files
      • The user’s email files are typically in a Maildir folder inside the home directory.
  • MySQL databases
  • Email accounts
  • Email Forwarders & Filters

Unfortunately, not all of the configuration and modules in WHM have an easy migration path.  If you have a lot of customizations on your server, it would be best to plan to audit this manually and determine what you may need to configure on the new server.

If you’ve made relatively few changes in WHM throughout the course of using the old server, most likely there is not much special to be concerned with.

In WHM, the EasyApache tool is used to provision common server software such as Apache or PHP.  If you have made customizations in EasyApache this information won’t be carried over by your account backups.

If you are running EasyApache 3, you should upgrade to EasyApache 4 first before migrating to a new server. This way, you can isolate any issues that stem from that software upgrade first before you migrate.  This upgrade process is well documented on the cPanel KB. Otherwise you can easily transfer the profile to your new server to retain your current configuration options. 

Planning

These steps and considerations should be reviewed while considering your migration process.  Most of this planning can be done before you have even ordered the new server which you’re planning to migrate to.

  • Clean Up Unused Data

    There is little reason to waste time and effort migrating accounts of former customers, defunct projects, or other no longer used websites.  So, before you begin the migration process, it is worthwhile to spend some time looking through your accounts list to see if there is anything you can eliminate.

    Also, it’s a good practice to look through your larger accounts and see why they are so large.  You may find large useless folders containing things like old backups which you may not need to migrate to your new server.

    Anything that you can eliminate will cut down on the time required for your migration, as well as make sure that you are optimally using your new server resources.

  • Consider IP Address Changes

    While migrating to a new server, there are many cases that you may need to change IP addresses you are currently using.If you have any websites using one such IP address, they will need the IP changed when they are migrated.  If you have a nameserver using an IP that needs to change, you will need to update its GLUE records when it is migrated.

    At GigeNET, and many other providers, the main IP address of your server is tied to a slot location, and thus will need to change if you move to new hardware.   We can however assist with rerouting your routed IP allocations in most cases, as long as the new server is in the same location as the old server.

    This tactic can be used to save time by not changing IPs during server migrations, or changing them beforehand to routable IPs.  If you plan ahead, you could possibly change the IPs of your websites before carrying out the server migration to IPs that you can move easily.

    If you know that you will need to change IP addresses, review where your DNS is hosted for all of your websites.  If you have websites that are using a third party DNS service (some proxy services like CloudFlare will set this up by default as well), any changes to the IP address of these websites will need to be coordinated with whomever has access to those services.  Otherwise, you will want to get access to them beforehand.

    In the case that you are changing IP addresses, it is a good idea to lower the TTL of the DNS records ahead of time.  The TTL, or time to live, is a value which determines how long DNS servers around the Internet will remember (or cache) the information stored in a particular DNS record.  Lowering this value ahead of time can allow for faster DNS propagation.

  • Consider the Software Version Changes

    While migrating to the new server, you will presumably be setting up shop on a server with a freshly installed operating system.  So, most likely that server will be running the latest versions of available software. Your old server may not have been.

  • If you are currently running an Apache version older than 2.4, an update to 2.4 may break some .htaccess rules. This is something that you should be aware of beforehand so that you can make sure you know what needs to be fixed. If this upgrade is carried out while incompatible .htaccess rules exist, you may find yourself chasing down 500 Internal Server Errors later on the affected websites.

You can find details on what specifically may need to be updated in your .htaccess files on the Apache documentation: https://httpd.apache.org/docs/trunk/upgrading.html

  • At the time of writing, EasyApache 4 supports PHP versions 5.4, 5.5, 5.6, 7.0, 7.1, and 7.2.  If you are running PHP 5.3 or older currently, you may run into difficulties migrating your websites to a newer version of PHP. Some websites which worked n PHP 5.3 may continue to work fine on future versions. If you are not a developer, then really, the best way to know for sure is to try it. PHP 5.4 and beyond introduce changes to the way that the code executes, and periodically remove or change the way PHP functions work.  So the further away you get from the version of PHP your site was written for, the less likely it will work.
  • Consider your options:
      • You could upgrade the website’s code to be compatible with the new version of PHP.  Ideally, this is what you would want to do. However, this will likely be time consuming as well as outside the scope of your hosting provider’s support.  You may need to enlist a developer for assistance.
      • If your website is a popular web application such as WordPress, Joomla, or something similar; consider upgrading to the latest version, as typically the latest versions of these applications support new versions of PHP.  This is a good security practice and something that you should ideally be doing anyway.
      • If you need to run older versions of PHP, it is possible to safely do so thanks to CloudLinux’s HardenedPHP feature, which you can read more about here:  https://www.cloudlinux.com/hardenedphp
    • CloudLinux is not free, so consider this as a part of the operating cost for your new server if you are not planning to update the affected websites.

Preparation

These steps should be carried out before starting the migration, but relatively soon before the migration (the day of ideally).

  1. Check DNS TTLs
    Review any notes from the above information in the planning stage.  If you are changing any IP addresses, did you remember to lower the TTL on the DNS records to enable quicker propagation?
  • Maintenance Mode
    As much as possible, you should put any websites into read-only or maintenance modes.  Migrations are not instantaneous, there will be some lag time between when you start copying data from the old server and when the site is live on the new server.  During that time, your visitors will still see the website from the old server.

If changes are made during this time window, they may be lost since the transfer has already began.  To combat this and other issues, many popular web applications can be placed into “Maintenance Mode”.  This prevents your visitors from making changes to dynamic aspects of the site.

If you are not going to go ahead with this, please carefully consider the consequences as they may apply to your website:

  1. Blogs may lose comments posted by visitors during the migration.
  2. Forums may lost posts made during the migration.
  3. eCommerce store fronts may lose information about orders placed during the migration.

  • Prevent Missed Emails
    If emails are received on the old server during the migration, they will be delivered to the mailbox on the old server, but may never have a chance to be copied to the new server.A simple way to combat this is by disabling the Exim mail server on the old server when you are starting the migration.If someone tries to send an email during this time to someone on your server, their mail server will detect the failure connecting and will try again later.
    In most cases, this results in the emails being delivered to the new server with some delay after the new server is brought online. If you do not complete the migration by the time configured on the sender’s mail server for retry, the sender will receive a bounceback and the email will not be delivered. Either case is better than the email being silently delivered to the old mailbox but never seen by the user.

Migration

This portion of the process will be the most time consuming, but requires very little interaction from you!

There are two techniques commonly used for migrating cPanel accounts:

  • WHM Transfer Tool
    The WHM Transfer Tool provides a simple graphical interface for migrating accounts between servers.  If you are doing a transfer yourself with relatively little server administration experience, this may be your preferred method.The tool is well documented, so I will not go into great detail here.  You can consult this documentation for details on the tool: https://documentation.cpanel.net/display/68Docs/Transfer+Tool
  • Scripted Migration
    Server administrators who want more control over the migration may choose to migrate accounts manually or with a basic script.cPanel’s included scripts can be used to migrate individual accounts, like so:

 /scripts/pkgacct username  < Packages up username’s account.

/scripts/restorepkg /path/to/package.tar.gz   < Restores the account in package.tar.gz

Using these scripts, it is relatively simple to create a script to package up all of the accounts.  You can do it with a simple for loop in Bash like this:

for i in $(cat users.txt); do /scripts/pkgacct $i; done

For the above to work, you do need to create a users.txt file containing a list of all of the cPanel usernames you wish to migrate.

If you run into difficulty packaging an account, you can consult the cPanel documentation on this script.

The pkgacct script supports a variety of options, such as skipping the databases, skipping the home directory, and toggling compression of the archive.  These can come in handy for special cases, such as accounts that have massive MySQL databases or home folders. In those cases, there may be circumstances where you would prefer that cPanel not bundle those files up because it is either running into problems, taking a long time, or creating a massive archive; and in those cases you can then have the option to transfer them yourself using other means.

Once the backup packages are created, you can transfer them to your new server using a transfer tool such as scp, sftp, or rsync.

The same methodology can be used to restore the packages.  Something like:

for i in $(ls -1 cpmove*.tar.gz); do /scripts/restorepkg $i; done

In general, the WHM Transfer Tool would be most user’s preferred way to complete a migration.  The scripted migration technique is helpful for cases where you need more control or need to be able to troubleshoot any errors created from the migration scripts.

Wrap Up

Once you’ve completed the migration steps above for all of your accounts, it is a good idea to test all of your websites as soon as you can before switching the live sites to the new server.

If the websites are configured on new IP addresses, you can override the DNS locally on your computer by editing your hosts file.  This way, you can visit the websites in your browser and see what they look like on the new server before making them live for everyone.  If you need help with this step, you may find this guide useful. 

Once you’ve decided that you are ready to bring the sites live on the new server, go ahead and update any residual DNS entries to point the domains to the new server.  If you have IP addresses that you are routing to the new server from the old server, go ahead and proceed.

It is a good idea to review your DNS zones manually to make sure that everything is cleaned up.  Make sure that no references to old IP addresses still exist in the DNS zone, and update accordingly as needed.  Also, if you lowered TTL times, you could take this time to increase them back to higher values. This isn’t required, but is considered to be a good practice and will reduce query load to your DNS server.

Once you think that you have everything live on the new server, it is a good idea to power down the old server completely.  Do not proceed with cancelling the old server with your hosting provider until you are sure everything is working completely and correctly on the new server.  There have been many times during migrations I have worked on that we find some surprises during this step, and customers realize that a few things were not really pointed to the new server.  So, it’s a good idea to do this, since it’s easily reversible (just turn the server back on) and will help you find any oversights quickly so that you can fix them.

When you feel comfortable, you can go ahead and cancel the old server.  

Congratulations, you have successfully completed your migration!