Over the course of this manual, we use both WHM and command-line to perform necessary actions (SSH credentials are provided after server purchase). WHM is user-friendly and works great for standard actions. However, some steps are either much faster to do from the command-line or not doable from the graphical interface at all.
NOTE: If not stated otherwise, commands should be run on the destination server. Bold text in commands should be replaced with your own data.
This is a simplified workflow that
is likely to work if you have a recent and default cPanel setup on
servers set up by Namecheap. If the source server has a recent cPanel
setup and you did not tweak the server a lot, it can be sufficient.
If this does not work, you will need to check the extended version below and/or do research on your end.
1. Run this one-liner to make sure that no major issues are present.
mkdir -p /root/rpmdb_bak && cp -avr /var/lib/rpm/* /root/rpmdb_bak && rm -vf /var/lib/rpm/__db* && rpm --rebuilddb -vv && /scripts/check_cpanel_rpms --fix && /scripts/upcp --force && whmapi1 set_local_mysql_root_password password="$(openssl rand -base64 14)”
here.
Example:
[source] # ifconfig | grep inet | head -1inet 172.16.0.1 netmask 255.255.255.0 broadcast 172.16.0.255
[destination] # ifconfig | grep inet | head -1
inet 172.16.0.2 netmask 255.255.255.0 broadcast 172.16.0.255
[source] # csf -a 172.16.0.2
[destination] # csf -a 172.16.0.1
3. Start the transfer:
1. Go to WHM >> Transfer Tool;
2. Enter the IP of the source server and root password;
3. Click Scan Remote Server:
- Select the accounts you want to transfer and hit Copy:
You will get a transfer session ID and cPanel will provide continuous
progress updates. If the total amount of data to transfer is small
(let’s say under 10G), you can wait for the transfer to complete in
real-time. Otherwise, copy over the transfer session ID to a safe place
and close the page. The process will continue and you will be able to
get back to it anytime.
4. Once you think that the transfer is over, log into the server and review the session (if you checked before that the transfer is over and there are no errors, just disconnect and get back to it later).
/usr/local/cpanel/bin/view_transfer transfer_id_you_saved_before --overview
5. Check the sites using hosts tools.
6. Use the local hosts file as explained
here.
Switch over DNS. In case you have Private nameservers set up, you will need to only update the IP of the nameservers. If the domain is registered with Namecheap, refer
here.
Otherwise, find the necessary instructions on the site of your registrar. If you are using other nameservers (for example, Cloudflare), the records from the new (destination) server should be copied over to them. Keep in mind that DNS propagation may last up to 24 hours.
Pre-transfer
Setting up a new server
Before doing the transfer itself, it is a good idea to make the setup as similar to the old server as possible. This way you will have less work to do after the transfer.
1. Make sure that the server is set up correctly, cPanel, and core services work.
mkdir -p /root/rpmdb_bak && cp -avr /var/lib/rpm/* /root/rpmdb_bak && rm -vf /var/lib/rpm/__db* && rpm --rebuilddb -vv && /scripts/check_cpanel_rpms --fix && /scripts/upcp --force && whmapi1 set_local_mysql_root_password password="$(openssl rand -base64 14)”
Below you can find the decryption of the command:
| Part of the command | Descryption |
|---|---|
| mkdir -p /root/rpmdb_bak && cp -avr /var/lib/rpm/* /root/rpmdb_bak && rm -vf /var/lib/rpm/__db* && rpm –rebuilddb -vv | There is a minor chance that the RPM database on the server will be corrupt. In this case, several cPanel scripts (and yum) will not work. This one-liner backs up the current database and rebuilds it from scratch. |
| /scripts/check_cpanel_rpms –fix | This script ensures integrity and presence of packages required by cPanel |
| /scripts/upcp –force | Immediately update cPanel. Update ensures that various assets and packages required for normal operations of cPanel are present and up-to-date. |
| whmapi1 set_local_mysql_root_password password=”$(openssl rand -base64 14)” | Ensure that local MySQL root password is set (generally it should be out of the box, but there are no downsides of making sure that it is true) |
2. PHP version/extensions
here.
NOTE: EasyApache4 is a wrapper around YUM package manager. If you are familiar with the latter, you can use it instead. Be careful – it does not offer the same sanity checks as WHM GUI.
3. Additional packages
| Package name | Installation commands to execute via shell access |
|---|---|
| Engintron | cd / && rm -f engintron.sh && wget –no-check-certificate https://raw.githubusercontent.com/engintron/engintron/master/engintron.sh && bash engintron.sh install |
| Node.js NOTE: this applies to CentOS + cPanel. If you are using CloudLinux, start by reading this |
yum -y install epel yum -y install ea-ruby24-mod_passenger ea-apache24-mod_env ea-nodejs10 ea-ruby24-ruby-devel Detailed steps as well as example configs are available here. |
| ConfigServer Firewall (csf) NOTE: we install CSF on new servers with cPanel by default, installation steps are provided mostly for your reference. |
cd /usr/src; rm -fv csf.tgz; wget
https://download.configserver.com/csf.tgz; tar -xzf csf.tgz; cd csf; sh install.sh # Running those is not obligatory, but otherwise csf will spam you with false-positive notifications sed -i ‘s/^TESTING = .*$/TESTING = “0”/’ /etc/csf/csf.conf sed -i ‘s/^IPV6 = .*$/IPV6 = “0”/’ /etc/csf/csf.conf sed -i ‘s/^LF_EMAIL_ALERT = .*$/LF_EMAIL_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^LF_SU_EMAIL_ALERT = .*$/LF_SU_EMAIL_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^LF_WEBMIN_EMAIL_ALERT = .*$/LF_WEBMIN_EMAIL_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^LF_CONSOLE_EMAIL_ALERT = .*$/LF_CONSOLE_EMAIL_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^PT_USERMEM = .*$/PT_USERMEM = “0”/’ /etc/csf/csf.conf sed -i ‘s/^PT_USERRSS = .*$/PT_USERRSS = “0”/’ /etc/csf/csf.conf sed -i ‘s/^PT_USERTIME = .*$/PT_USERTIME = “0”/’ /etc/csf/csf.conf sed -i ‘s/^PT_USERKILL_ALERT = .*$/PT_USERKILL_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^LF_PERMBLOCK_ALERT = .*$/LF_PERMBLOCK_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^LF_NETBLOCK_ALERT = .*$/LF_NETBLOCK_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^LT_EMAIL_ALERT = .*$/LT_EMAIL_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^RT_RELAY_ALERT = .*$/RT_RELAY_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^RT_AUTHRELAY_ALERT = .*$/RT_AUTHRELAY_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^RT_POPRELAY_ALERT = .*$/RT_POPRELAY_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^RT_LOCALHOSTRELAY_ALERT = .*$/RT_LOCALHOSTRELAY_ALERT = “0”/’ /etc/csf/csf.conf sed -i ‘s/^CT_EMAIL_ALERT = .*$/CT_EMAIL_ALERT = “0”/’ /etc/csf/csf.conf |
| Softaculous | whmapi1 set_tweaksetting key=phploader value=ioncube & /usr/local/cpanel/whostmgr/bin/whostmgr2 –updatetweaksettings; wget -N https://files.softaculous.com/install.sh; chmod 755 install.sh; ./install.sh |
If you have installed anything beyond this list, refer to the up-to-date instructions for that software.
Ensure connectivity between servers
If
you have not tweaked/secured your installation, the transfer can be
done by using the default ssh port (22) using the root password and
source server IP.
If you did secure your server, the easiest way
to proceed is to lift wall restrictions and revert to basic settings
during the transfer. If you do not want to do that, the following may be
useful:
| Security feature | How to make transfer work when the feature is enabled |
|---|---|
| SSH password auth is disabled | Use
SSH key for transfer instead. |
| Root auth is disabled | Use a user with necessary sudo rights in the transfer tool. The steps on how it should be set up can be found in
this article. |
| SSH logins are only allowed from specific IPs | Add destination server to /etc/hosts.allow on the source server (or use
Host Access Control WHM menu) |
| Non-standard SSH port | Make sure that outgoing connections via that given port are
allowed on the destination server. If you are using CSF, they can be changed in WHM >> ConfigServer Security & Firewall >> Firewall Configuration For more details, check this article. Alternatively, edit /etc/csf/csf.conf and restart csf (csf -r). If you are using iptables, add the following chain: iptables -A OUTPUT -p tcp –dport your_ssh_port -j ACCEPT If you are using a different firewall, refer to it’s man page. The easier way is to whitelist IP of source server on destination server and vice versa. Example: |
We will not cover further restrictions as they are used very rarely. If you do use them, make the appropriate changes.
Transfer
When
transferring sites between servers via cPanel tools, you will have to
choose between Express and non-Express methods. The differences can be
found
here.
Here is a short summary:
- In the case of Express
transfers, requests/mails will be redirected to the new server, so no
data will be lost (e.g. e-commerce orders). The downside is that if
something gets broken, end-users will be affected by it. - If
non-Express mode is used, traffic is not redirected. It means that you
will have plenty of time to check and fix possible issues, but new
emails/database updates will not be carried over.
There are
workarounds. For example, you may transfer accounts without express
mode, tweak server settings until they all work, remove the accounts
from the new server and re-transfer them with Express mode. If your
budget or technical knowledge allows, you may set up things such as
database replication, or use third-party service/separate server for
email handling, etc. Possibilities are endless and depend on the
specifics of your business. This guide does not cover them. Neither does
Namecheap offer such services.
Run the transfer
1. Go to WHM >> Transfer Tool;
2. Enter the IP of the source server and root password;
3. Click on Scan Remote Server:
4. Select the accounts you want to transfer and hit Copy:
You will get a transfer session ID and cPanel will provide continuous progress updates If the total amount of data to transfer is small (let’s say under 10G). You can wait for the transfer to complete in real-time. Otherwise, copy over the transfer session ID to a safe place and close the page. The process will continue and you will be able to get back to it anytime.
5. Once you think that the transfer is over, log into the server and review the session (if you checked before that the transfer is over and there are no errors, just disconnect and get back to it later).
/usr/local/cpanel/bin/view_transfer transfer_id_you_saved_before --overview
If you see any errors or warnings, you will need to examine the session more closely (without the overview option):
/usr/local/cpanel/bin/view_transfer transfer_id_you_saved_before | less -R
NOTE 1: if you lost the transfer session ID for some reason, check contents of the /var/cpanel/transfer_session folder.
NOTE 2: transfer session may be full of ‘invalid log entry’ errors. They can be ignored.
Fixes to the most common relevant errors you may see in transfer sessions are provided below.
Fixing errors in transfer sessions
| Error | Solution |
|---|---|
| ‘domain.com’ already exists in userdata | Domain already exists on the target server. Due to this, the tool is not able to transfer it’s userdata settings because it would break the Apache (at the very least) configuration.
Most likely, you have created an empty account for that domain on the destination server. If the account with the domain in question holds no valuable data, you can remove it along with the transferred account from the destination server and re-transfer. Another option is to ignore the error and move the contents of the site to the account the domain is tied to on the new server. The owner of the domain can be checked with the following command: |
| Databases are not transferred with ‘max_allowed_packet exceeded’ messages. | Databases use big chunks of space to store data.
You can confirm this trying to dump the database on the source server Once you know what value works, run this both on source and destination servers: Alternatively, you can dump databases and transfer them manually (or deselect ‘Home Directory’ in Transfer Tool) |
| Errors related to source server load in transfer session | Transfer sessions are suspended if the load on the source server is too high. You will need to either wait for a less traffic-heavy period to do the transfer or go for ‘hard’ measures such as shutting down resource-heavy services on the source server (e.g. Apache web-server). |
NOTE: If you have used the Express transfer option and something broke, you will see the results immediately. Due to this, we recommend against using this option if you have a heavily customized setup.
Checking the sites
- If your site(s) feature any form of automated tests, run them and act upon the results.
- Check the sites on the new server using hosts tools. Using local hosts file is the most reliable. If you see any errors, check the Fixing post-transfer errors section.
NOTE: Do not use an online hosts tool to make any changes to the site (e.g. create new posts) because the database will be updated with URLs containing hosts.cx instead of your site.
Fixing post-transfer errors
No matter how hard you try to maintain the setup and satisfy software requirements, there is a chance that something will not work after the transfer. The following table covers some of the common issues you will face.
| Error | Solution |
|---|---|
| cPanel errors without verbose description2. | 1. Try updating cPanel, it works in 95% of cases /scripts/upcp –force 2. If that does not help, check cPanel error log and act accordingly. less /usr/local/cpanel/logs/error_log |
| The site was working on the old server but broke on the new | Most likely, the new server did not have the same PHP version installed and reverted to the system default.
In this case, install the required version and switch to it. Alternatively, you can try switching PHP-FPM for the domain on/off. Both can be done in WHM > MultiPHP Manager If neither of the fixes worked, you will need to examine PHP/Apache error logs for relevant errors. |
| The following entries in PHP error_log (or on the site, depending on what error_reporting is set) [25-Jun-2020 01:10:00 UTC] PHP Warning: Module ‘PDO’ already loaded in Unknown on line 0 [25-Jun-2020 01:10:00 UTC] PHP Warning: Module ‘pdo_sqlite’ already loaded in Unknown on line 0 …. |
find /opt/cpanel/ea-php*/root/etc/php.d/zzzzzzz-pecl.ini -delete |
If the error is not on the list, you will need to do the research to fix it. First of all, check the logs. Most likely you will find the answer in the following logs:
| /var/log/messages | General system log. ftp, named, ssh errors. Kernel messages and many more. |
| /usr/local/cpanel/logs/error_log | Error log of cPanel itself (errors that you will see on cPanel interface are most likely logged here with extra info) |
| /var/log/apache2/error_log or /var/log/httpd/error_log |
Apache web-server error log |
| /var/cpanel/php-fpm/user/logs/error.log | User’s php-fpm error log |
| /opt/cpanel/ea-phpversion/root/var/log/php-fpm/error.log Ex: /opt/cpanel/ea-php56/root/var/log/php-fpm/error.log /opt/cpanel/ea-php72/root/var/log/php-fpm/error.log |
Global php-fpm errors for a given version |
| /home/user/logs | Local user’s php-fpm logs |
| /home/user/site_document_root/error_log | Local php error log (when php-fpm is not used) |
here.
cPanel forums
cPanel/WHM documentation
Stackoverflow
Regardless of where you get the information, make sure that you fully understand what the suggested actions do to the system before applying them.
Adjusting DNS and local email/FTP clients
After you have transferred the data and made sure that all errors are fixed, it is time to make the site(s) work from the new server.
- If you are using a custom reverse DNS (PTR) record, please reach out to us via
Live Chat so that we can set the required PTR for the IP of the new server for you. Otherwise, you may face issues with email deliverability on the new server. - Check email/FTP clients (use the same settings as for the old server, but use IP of the new server as hostname).
- Once the steps above are done, you may proceed to the DNS switch. In case you are using private DNS servers for all domains on the server, you will simply need to register them with new IPs (which can be found in WHM > Edit a DNS Zone menu).
If the domain is registered with Namecheap, refer to
this article. Otherwise, find the necessary instructions on the site of your registrar. If you are using other nameservers (for example, Cloudflare), the records from the new (destination) server should be copied over to them. Keep in mind that DNS propagation may last up to 24-48 hours.
If you have reached this point, the transfer is over and all your sites are working from the new server.
That’s it.
Recent Comments