How To: Manual Account Transfer With Rsync – cPanel

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
```
The ideal outcome of this command is no output. If you receive any output at all, this generally means the archive is bad and will need to be re-created.

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)

If you used the '--dbbackup=schema' flag when creating account backups, you can use the following steps to generate the database backups:

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
```
The '$database_name' should be the name of the database gathered from step 2, and the export file should end in '.sql'. Depending on the size of the database, this command may take some time to complete and needs to be done for each database you are transferring.

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/
```
You can compare this output to what is on the source server. If anything is missing, you may need to review the rsync output to figure out why.

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:

How do I transfer a large number of files using rsync?

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:

How can I view my site without pointing DNS?