Introduction
The Transfer Tool is recommended to handle most transfers, but there are cases where a manual transfer is required. Accounts that use large amounts of disk space, contain especially large databases, or are on servers with a general lack of free space may be served better by doing a manual transfer. By using the pkgacct and rsync commands, you can manually transfer accounts between two servers.
Procedure
Definitions: We will refer to the server you are migrating FROM as the 'Source' server and the server you are migrating TO as the 'Destination' server.
Warning: The command examples that are provided within this article will need to be tailored to your specific situation. Rsync will replace files if they already exist without a prompt or warning, and a single missing '/' (trailing slash) from the command could have catastrophic consequences. Please double-check any commands before running them.
If you are not familiar with the process or comfortable with running the commands documented below, we recommend working with a qualified System Administrator to perform the manual transfer. You can find resources on locating a System Administrator here:
System Administration Services
Setup
- Establish an SSH connection on the source server as the root user.
- Establish a second SSH connection on the destination server as the root user.
- (Optional) Install the screen utility on both servers. Screen is recommended to ensure tasks can be completed even if your SSH session is disconnected:
How to use the Screen utility - Make a note of the home directory path for the user you will transfer. You can identify the cPanel user attached to a domain name with the following command:
grep '^domain.tld' /etc/userdomains | cut -d ' ' -f2
This will output a user's home folder when you replace $user with the cPanel username:awk -F ':' '/$user/ {print $6}' /etc/passwd
Creating the Account Backups
- Access the source server via SSH as the root user
- If screen is installed, open a screen session:
screen -S transfer-session
- Set up a "working directory" to keep our work separate from any critical system or site files:
mkdir -pv /root/site-migration/source-server && cd /root/site-migration/source-server && pwd
- Use the pkgacct script to make a backup of the account using the '--skiphomedir' option. This will back up all of the cPanel-specific files, configurations, and preferences, along with the databases for the specified account:
/usr/local/cpanel/scripts/pkgacct --skiphomedir $user /root/site-migration/source-server
If large databases are preventing you from using the transfer tool, include the '--dbbackup=schema' flag for the command. (Refer to "Handling Large Databases" below for exporting databases separately.) - Check the integrity of the account backup using the tar command:
tar -tzf cpmove-$user.tar.gz
Once your newly created archive has passed the integrity check, we can begin the process of transferring it to the destination server.
Handling Large Databases (Optional)
- Create a directory to hold the databases you wish to export and enter that directory:
mkdir databases && cd databases
- Generate a list of the databases that need to be exported for transfer. Remember to replace '$user' with the cPanel username:
mysql -se 'show databases like "$user_%";'
- Use the mysqldump command to create a backup of the database:
mysqldump $database_name -r $database_name.sql
Copying the Backups to the Destination
- Access the destination server via SSH as the root user
- If screen is installed, open a screen session:
screen -S transfer-session
- Use rsync to grab the files from the remote source server. You will need the root username, the destination server's IP address, the path to the folder you created to store the migration data, and the folder on the destination server to which they will be copied:
rsync -avPhz root@203.0.113.2:/root/site-migration/source-server /root/site-migration
- The rsync command generates an SSH session, so pay attention to any prompts to complete the connection. Once connected, the process will show the progress as it copies the files over.
- List the files in the transferred directory to make sure everything came over as expected:
ls -lah /root/site-migration/source-server/
- Use the restorepkg script to restore the account shell to the destination server:
/usr/local/cpanel/scripts/restorepkg
/root/site-migration/source-server/
cpmove-$user.tar.gz - Get the path to our newly restored user's home directory on the destination server:
grep '$user' /etc/passwd | awk -F ':' '{print $6}'
- Use rsync to grab the contents of the home folder from the source server. You will need the data gathered from "Setup" (Step 4) and the user's home directory on the destination server.
Please note that the trailing slashes are required here. Do not omit them, as this will cause your data to be transferred to the wrong destination:rsync -avPhz 203.0.113.2:/home/$user/ /home/$user/
- The rsync command will take time to process and migrate the data from one server to another. If you are not in a screen session, you will need to make sure your terminal session stays open the entire time or risk restarting the transfer.
- When the transfer is complete, you can list the files to make sure everything was transferred over as expected. Compare the output of checking the home directory on both source and destination servers:
ls -lah /home/$user/
If you encounter issues with rsync failing due to a large number of files, refer to this article:
Copying Large Databases (Optional)
If you created the optional database dumps in the first Large Databases section, we must import them once the account is restored. This section operates on the destination server as well.
- The 'databases' folder should have been transferred with the account data:
cd /root/site-migration/source-server/databases/
- Import the databases into MySQL:
mysql $database_name < $database_name.sql
- Repeat as necessary to import all of the databases.
Transfer Complete
With the account shell restored, the home directory copied over, and the databases imported, the account transfer is complete. Before updating your DNS, you can make use of your hosts file to view your site on the destination server to make sure everything was transferred successfully:
Comments
0 comments
Article is closed for comments.