Transfer Tool

Valid for versions 98 through the latest version

Version:

98


Last modified: February 22, 2024

Overview

This interface copies multiple accounts from a remote server to your cPanel & WHM server. To transfer accounts, you must have root-level privileges with the su or sudo commands.

Before getting started

You should review the following tips before you use the Transfer Tool feature:

  • Do not shut down or restart any processes on either server during the transfer and restoration process.
  • Do not start a transfer during a system update (upcp) or start a system update during a transfer. The system update will fail.
  • The Transfer Tool feature replaces the source server’s files with the target server’s zone files when the following conditions are true:
    • The target server resides in the same Domain Name System (DNS) cluster as the source server.
    • The source server and the DNS nodes use the Synchronized Changes DNS role. For more information about DNS clusters, read our DNS Cluster documentation.
  • The Transfer Tool feature does not transfer the DNS zone templates. If custom DNS zone templates exist on the remote server, the system ignores these zone templates when it recreates the account on the destination server. For more information, read the transfer process section below.
  • Account transfers process AAAA records differently than A records.
  • The target server will not alter AAAA records that point to servers other than the source server or servers related to the source.
  • A target server without IPv6 enabled will strip locally-managed AAAA records that pointed to the source server.
  • A target server with IPv6 enabled will point any source-related AAAA record to the account’s shared IPv6 address in the domain’s locally-managed zone file.
  • The server disregards the Restrict document roots to public_html Tweak Setting setting during server transfers. The transfer tool retains any pre-transfer public_html/ directory structures, even those that place addon and subdomains document roots outside of the primary website’s document root. However, after the transfer, addon and subdomains that the restored user creates will adhere to this setting.
  • Do not use the skip-name-resolve setting in your server’s MySQL® configuration. This setting can cause problems on any server. It will create more problems on remote MySQL servers during account transfers.
  • To use this feature, we strongly recommend that your source and target servers are able to communicate over port 2087. For more information about the ports that cPanel & WHM uses, read our How to Configure Your Firewall for cPanel & WHM Services documentation.
  • Due to networking requirements, you cannot run an IPv6-only cPanel & WHM server. You must have at least one IPv4 address.
  • This feature does not transfer Two-Factor Authentication (2FA) configuration information for an account. The user will need to reconfigure 2FA on the new server.
  • If you experience problems with session timeouts, increase the number of seconds in the Number of seconds an SSH connection related to an account transfer may be inactive before timing out setting in the System section of WHM’s Tweak Settings interface (WHM » Home » Server Configuration » Tweak Settings).
  • If one of the accounts that you wish to transfer uses Microsoft® FrontPage® on the remote server, we strongly recommend that you disable FrontPage for that account before you attempt to transfer the account. cPanel & WHM does not support FrontPage, and the restoration process does not restore FrontPage-specific files and directories.
  • If you only possess user credentials and do not have root access or privileges, use WHM’s Transfer or Restore a cPanel Account interface (WHM » Home » Transfers » Transfer or Restore a cPanel Account).

Important notes about account transfers from Plesk

The system will not transfer any email addresses from Plesk to cPanel & WHM that contain a plus sign (+) in the email username. The system will also not transfer any FTP accounts that contain an underscore (_) in the username.

To transfer accounts from Plesk, first change any forwarded domains to physical hosting accounts. To do this, run the following command as the root user:

/usr/local/psa/bin/domain --update example.com -hst_type phys -login "example" -hosting true -ip 127.0.0.1 -passwd "12345luggage"

  • example.com represents the forwarding domain.
  • example represents the new account’s username.
  • 127.0.0.1 represents the new account’s IP address.
  • 12345luggage represents the new account’s password.

If you need to convert several forwarding domains into hosting accounts, open a support ticket and our migration team will contact you.

IP address transfers

To transfer IP addresses from one server to another, use WHM’s IP Migration Wizard IP Migration Wizard interface (WHM » Home » IP Functions » IP Migration Wizard).

If the IP address is the server’s main IP address, you must also update your cPanel license’s IP address. You can update your license’s IP address through Manage2, if you use it, or through the cPanel Store.

Important:

You can only transfer a cPanel license to an IP address that does not already possess a cPanel license.

Transfer via Manage2

If you purchased your license via Manage2, perform the steps in our Transfer a License documentation.

Transfer via cPanel Store

If you purchased your license directly from WebPros International, LLC, perform the following steps:

  1. Log in to your cPanel Store account.
  2. Click My Account. The My Account interface will appear.
  3. Under Orders/Licenses, click View my licenses. The Manage Licenses interface will appear.
  4. Select the checkbox for the license that you wish to transfer.
  5. Click Edit IP. The Change IP Address dialog box will appear.
  6. Enter the license’s new IP address in the New IP Address text box.
  7. Click Save Changes.

If you experience any issues with the transfer, open a support ticket.

How to transfer and restore multiple accounts

Remote server information

This section of the Transfer Tool interface allows you to specify information about the remote server (the server from which to transfer accounts).

  1. In the Remote Server Address text box, enter an IP address or a Fully Qualified Domain Name (FQDN).
    • IP address example127.0.0.1
    • FQDN examplehost.example.com
      Note:
      In this case, the FQDN does not require the trailing dot.
  2. In the Remote SSH port text box, specify the port to use.
    Note:

    The default value for SSH is port 22. If the server cannot establish an SSH connection, the Transfer Tool uses port 2087 instead.

Authentication

In this section of the Transfer Tool interface, specify the authentication method with which to log in to the remote server.

To specify an authentication method, perform the following steps:

  1. Select whether to log in as the root user or with a specific username.
    Note:

    If the PermitRootLogin value equals no in the sshd_config file on the remote server, you must log in as a user other than the root user and then escalate to the root user.

  2. If you selected User for Login, perform the following actions:
    • Enter the remote account’s username in the Username text box.
    • Enter the remote account’s password in the Password text box.
  3. Use the Authentication Method menu to specify whether to use a password or an SSH key pair to authenticate to the remote server.
    • If you select Password, enter the password for the account in the Password text box.
    • If you select SSH Public Key, select the key pair to use during authentication. Make certain that you installed the appropriate key pair in WHM’s Manage root’s SSH Keys interface (WHM » Home » Security Center » Manage root’s SSH Keys).
      Note:
      • If you encrypted your account’s SSH key pair, enter the SSH Key Passphrase.
      • If you’re experiencing firewall issues, use the Password method instead.
  4. Optionally:
    • If you select User under Login, select a root escalation method under the Root Escalation Method heading.
    • If you select su for the Root Escalation Method, enter the root password in the Root Password text box.
    • To bypass TLS verification, select the I understand the risks. Connect anyway. checkbox and then click Continue.
      Warning:

      We strongly recommend that you do not use this option. Only use this option if you can confirm the identity of the source server.

Security

Warning:

This feature is experimental. Do not consider it an effective security control. Exercise extreme caution when using the Restricted Restore feature.

In this section of the Transfer Tool interface, select whether to use the Restricted Restore feature or copy reseller privileges. The Restricted Restore feature lets the system perform extra security checks on the archive file. If part of the file has a security issue, the system will not restore that part of the archive file. This helps mitigate the risk of transfers from unfamiliar sources. The system enables this feature by default.

If you do not trust the source of the account backup with root access to your server, use the Restricted Restore feature to protect your server.

Warnings about the Restricted Restore feature

If you use the Restricted Restore feature, be advised that:

  • When you restore an account with this feature, the system may leave behind unnecessary account data. This can cause conflicts and leave the account in a broken state. You must remove the account and then restore it without using the Restricted Restore feature.
  • The Restricted Restore feature will not restore reseller privileges. If you wish to add reseller privileges to a transfered account, use WHM’s Reseller Center interface (WHM » Home » Resellers » Reseller Center).
  • This feature will not restore parked (aliased) or addon domains.
  • This feature only allows restored accounts to use noshell or jailshell environments. If the restored account uses another shell, the system will set the account to use noshell environment.
  • If you use this feature to restore an account that contains PostgreSQL® databases, the target server must use PostgreSQL version 8.4 or later.

Advanced

This section of the Transfer Tool interface provides advanced settings for the transfer. Click Show to display the list of settings.

To select the advanced settings, perform the following steps:

  1. From the Remote Server Type menu, select the web control panel that the remote server runs. Choose from the following settings:
    • Auto Detect
    • cPanel & WHM
    • DirectAdmin
    • Ensim (Parallels Pro)
    • Plesk
  2. Select Unencrypted to use an unencrypted session to transfer the files.
  3. Select Compressed Transfers to compress the files during the rsync process when the remote server transfers the files between the remote and destination servers.
    Note:

    This setting does not affect the package account function, which creates a gzip archive of the user’s account on the remote server.

  4. Select Low Priority to use less CPU and input/output (I/O) on the remote server.
    Note:

    This setting reduces the impact on performance on the remote server, but increases the duration of the transfer session.

  5. Select Use Incremental Backups speed-up to decrease the amount of time that the system uses to package the account on the remote server. If a daily incremental backup exists, WHM uses that backup as a starting point. The system then updates the package before transfer.
  6. Select Use custom account packaging modules from /var/cpanel/lib/Whostmgr/Pkgacct to use packaging scripts in that directory.
    Important:

    The system does not create the /var/cpanel/lib/Whostmgr/Pkgacct directory by default. You must create the /var/cpanel/lib/Whostmgr/Pkgacct directory before you select this setting, if the directory does not already exist.

    Note:

    cPanel & WHM always prioritizes custom restore modules in the /var/cpanel/perl/Whostmgr/Transfers/Systems directory over the cPanel-provided modules in the /usr/local/cpanel/Whostmgr/Transfers/Systems directory.

    • The /var/cpanel/perl/Whostmgr/Transfers/Systems directory stores any custom modules that you create.
    • The /usr/local/cpanel/Whostmgr/Transfers/Systems directory stores the modules that ship with cPanel & WHM.
  7. Specify the number of CPU processes (threads) for the transfer session in the Number of Transfer Threads text box.
    Note:

    This setting defaults to a number of processes (threads) based on the available amount of memory and number of CPUs. You can specify a maximum value of five, but the system may still automatically reduce that number based on available resources.

  8. Specify the number of CPU processes (threads) for the restore session in the Number of Restore Threads text box.
    Note:

    This setting defaults to a number of processes (threads) based on the available amount of memory and number of CPUs. You can specify a maximum value of five, but the system may still automatically reduce that number based on available resources.

  9. Enter the number of seconds that the transfer session remains open before it times out in the Transfer Session Timeout text box.
    Important:

    If you change the default in the Transfer Session Timeout text box, it will only apply to the current session. You must enter a new value each time that you run a transfer. You can permanently change the value in WHM’s Tweak Settings interface (WHM » Home » Server Configuration » Tweak Settings).

  10. After you make your selections, click Scan Remote Server. A new interface will appear.

The Account List interface

The top of the Account List interface displays information about the source server. If any of this information appears incorrect, click Rescan Source Server.

Below the source server information, the interface displays if any available IP addresses exist.

Warning:

If no available IP addresses exist on the target server, accounts on the source server that use a dedicated IP address will not transfer.

Accounts

This tab allows you to transfer cPanel accounts to this server.

How to copy accounts

To copy accounts, perform the following steps:

  1. Select the checkbox for each cPanel account that you wish to transfer.
    • To copy all of the accounts that the interface currently displays, select the checkbox at the top of the column in the table header.
    • Use the Search text box to filter the list of accounts.
    • Click a column header to sort the accounts by that column.
  2. By default, the system adopts the username from the source server. To specify a new username, enter the new username in the User text box.
    Note:

    The User text boxes display the following colors as warning indicators:

    • A red highlight indicates that the username or domain already exists on this server. The account will fail to transfer if you do not change the username, select Overwrite, or select Overwrite with delete. You cannot transfer an account that uses the same domain.
    • A green checkmark (checkmark) indicates that the account does not already exist.
  3. Select the accounts to which the system will assign dedicated IP addresses under the Dedicated IP Address heading. The interface will select the Dedicated IP checkbox for accounts that currently use a dedicated IP address.
    Warning:

    You can only assign available dedicated IP addresses from your server. If your server doesn’t have the required number of available IP addresses, the transfer will fail.

  4. Click Default to show the What to Transfer section. The following settings will appear:
    • Home Directory — Transfer the account’s home directory.
      Note:

      When you transfer the home directory, the system checks whether it can run the rsync command. If the system does not find an error, it will rsync the home directory when the system completes the transfer.

    • Reseller Privileges — Retain the account’s reseller privileges.
    • Databases — Transfer the account’s databases.
    • Bandwidth Data — Transfer the account’s bandwidth data.
  5. Click Default to show the Live Transfer section.
    Note:

    For more information, read the Live transfer section below.

  6. If your server uses a linked node, click Default to show the Linked Node Options section. The following settings will appear:
    • Use only this server. Transfer or restore locally. — Transfer the account to the local server.
    • The alias and hostname of an existing cPanel & WHM server node. For example, mailserver (mailnode.example.com). — Transfer the account’s mail services to the selected linked node.
  7. Click Apply to save the What to Transfer and Linked Node Options settings for this account. You can click Apply to other selected accounts to apply these settings to all currently selected accounts. To apply the default settings for this account, click Reset.
  8. The Overwrite column displays a menu that allows you to overwrite local data for the transfer.
    • Do Not Overwrite — Do not perform an overwrite.
    • Overwrite — Overwrite the home directory on the destination server with the contents of the source server. Do not delete any other files or directories on the destination server.
    • Overwrite with Delete — Overwrite the home directory on the destination server with the contents of the source server. Delete all files and directories on the destination server that don’t exist on the source server.
      Warning:

      This setting will overwrite or delete all files on the destination server for the cPanel account. You cannot reverse this action. We strongly recommend that you first create a backup of the account.

  9. Click Copy. The Account Transfer interface will appear.
SNI information
Important:

To transfer SNI information, you must select the Home Directory setting.

If you do not select the Home Directory setting, the system will not add the necessary SNI information to Dovecot’s configuration files. To manually configure SNI information in Dovecot’s configuration files after an alternative transfer of home directories, run the following command:

/usr/local/cpanel/scripts/build_mail_sni --rebuild_dovecot_sni_conf --restartsrvs

Accounts will retain their mailbox format settings from the source server. For example, if an account uses the maildir format on the source server, it will use the maildir format on the target server.

Packages

In this section of the Account List interface, select the packages on the remote server to copy to your local server.

How to copy packages

Note:

The Transfer Tool feature transfers feature lists for the packages that you select.

To copy a package, perform the following steps:

  1. Select the packages that you wish to copy.
    • Select the checkbox in the table header to select all of the packages from the remote server.
    • Use the Search text box to filter the list of packages.
    • Use the navigation controls to page through the list of packages.
    • Click a column header to sort the packages by that column.
  2. Click Copy.
    Important:

    This will also transfer any accounts that you select in the Accounts tab.

    Warning:
    • The system will overwrite any packages or feature lists with the same name that exist on the destination server.
    • If the transfer fails to create a new package or feature list, it will assign the default package or feature list to the account.

Package and feature list naming

The transfer tool feature performs the following actions during package transfers:

  • The restore system attempts to extract the package information from the cpmove file. If the package does not already exist on the target system, the system creates the package and assigns it to the account. If the system cannot create the package, the system assigns the default package to the account.
  • If the feature list for the account exists on the target system, the system assigns it to the account. If the feature list does not exist, the system assigns the default feature list to the account.
  • You can transfer a new package and feature list with the same name as a package that already exists on the target server. This package will override the previous package’s settings.

Service Configurations

In this section of the Account List interface, select the configuration settings on the remote server that you wish to copy to a destination server.

You can transfer the following configurations:

  • AutoSSL Options
    Note:

    This module does not modify the SSL provider. To update your SSL provider, use WHM’s Manage AutoSSL interface (WHM » Home » SSL/TLS » Manage AutoSSL).

  • Backups
  • cPanel & WHM (whmconf)
    Note:

    This configuration includes WHM’s common settings that aren’t user-specific. For example, the settings from WHM’s Tweak Settings interface (WHM » Home » Server Configuration » Tweak Settings) and WHM’s Basic WebHost Manager Setup interface (WHM » Home » Server Configuration » Basic WebHost Manager Setup).

  • Database Server
    Note:

    When you transfer remote MySQL databases, the Transfer Tool feature includes any comments associated with the remote MySQL server. For more information about remote MySQL comments, read our Remote MySQL documentation.

  • EasyApache
  • Exim
  • GreyList
  • Hulk
    Note:
    • The Transfer Tool feature does not copy history reports.
    • The Transfer Tool feature appends whitelist- and blacklist-management configuration settings. It does not replace these configuration settings.
  • ModSecurity®
    Note:
    The EasyApache service configuration also contains some ModSecurity settings. Use the ModSecurity service configuration to affect only the ModSecurity settings.
  • User Interface Themes

For more information about the files that the system transfers for each configuration, read the cpconftool script documentation.

To select your desired configurations, perform the following steps:

  1. The Configuration Name and Analysis columns display the available configurations and versions. You may need to click Show for the available configurations to appear.
  2. Select the configurations that you wish to transfer to your local server.
    Note:
    • The system displays warning messages in yellow and blocker messages in red text.
    • If you receive a blocker message, the system disables the EasyApache setting.
  3. Click Copy. The system will display the progress interface.
    Important:

    This will also transfer any accounts that you select in the Accounts tab.

    Note:
    • You cannot click Copy until you select a configuration to transfer.
    • The Transfer column displays the status of all configurations from the remote server.
    • The Restore column displays the status of all configurations to the destination server.
    • The system displays any error messages in yellow and warning messages in red text.

The summary bar displays the transferred or restored configurations.

Restore the PHP-FPM .yaml configuration file

MultiPHP user’s PHP-FPM settings do not transfer. The system transfers the PHP-FPM .yaml configurations to the filename.php-fpm.transferred file. The system does this action because it cannot determine the status of the PHP and FPM services.

To restore the PHP-FPM .yaml configuration file manually, rename the file to the filename.php-fpm.yaml file.

/scripts/php_fpm_config --rebuild

The system restores your account’s PHP-FPM .yaml configuration file.

The transfer process

Note:
  • In the following steps, domain represents the name of a domain that you transferred.
  • The system considers any two records with the same resource name and type to be duplicates.
  • MultiPHP user’s PHP-FPM settings do not transfer. The system transfers the PHP-FPM .yaml configurations to the filename.php-fpm.transferred file. The system does this action because it cannot determine the status of the PHP and FPM services. To restore this file manually, read the Restore the PHP-FPM .yaml configuration file section above.
Warning:

If you dedistribute a mail account back to a parent node, the system will overwrite any mail that may be on the parent node for that account. We strongly recommend that you use the Transfer Tool interface (WHM » Home » Transfers » Transfer Tool) for the entire distribution process to avoid any issues with moving email to the child node.

When you use the Transfer Tool interface to transfer accounts, the system performs the following actions:

  1. The system creates the account.
  2. The system compares the DNS zone file from the account’s backup file with the template-generated zone file that the system generated during account creation.
    Important:

    The Transfer Tool feature does not transfer DNS zone templates. If custom DNS zone templates exist on the remote server, the system ignores these zone templates when it recreates the account on the destination server.

  3. The system updates the SOA record to match the target server’s zone templates and comments out the existing SOA record from the remote server.
  4. The system updates domain NS records to match the target server’s zone templates and comments out any duplicate domain NS records from the remote server.
  5. The system updates ftp.domain A, AAAA, and CNAME records to match the target server’s DNS templates and comments out any identical ftp.domain records from the remote server.
    Note:

    cPanel & WHM uses the IP address in the destination server’s standardvirtualftp zone template (usually, the server’s main IP address) for virtual FTP when the account exists on a shared IP address.

  6. The system checks whether the template-generated zone file uses an MX preference of 0, and then performs the following actions:
    • If the zone file’s MX preference is 0 and the MX record points to $PRIMARY_DOMAIN or mail.$PRIMARY_DOMAIN, the system does not merge in the generated templates and does not update the MX preference from the remote server.
    • If the zone file’s MX preference is 0 and the MX record does not point to $PRIMARY_DOMAIN or mail.$PRIMARY_DOMAIN (a non-standard mail configuration), the system merges the generated templates and comments out templates from the remote server.
    • For example, when the zone template’s MX record defines an external mail service, the system prefers that entry over the record in the backup.
  7. The system comments out duplicate records.
  8. The system comments out CNAME records that conflict with any other records. If two or more CNAME records conflict, the system comments out all but the first CNAME record.
  9. The system updates records that reference the old IP address to use the account’s new IP address.
  10. The system increments the SOA serial number for the domain.
  11. The system removes comments that are older than 30 days.
  12. The system updates CalDAV and CardDAV records to match the target server’s DNS template.
  13. The system transfers any DNSSEC key information from the backup file to the new server.
    Important:

    If the destination server does not support DNSSEC, that system will not restore any DNSSEC keys in the backup file.

  14. If the zone file contains an $ORIGIN directive for an additional domain, the system will not update that additional domain’s records.

Live Transfer

Warning:
  • You can only use the Live transfer feature to transfer accounts between cPanel & WHM servers.
  • You must update your DNS before removing your old account from your previous server with Live Transfer.
Note:
  • You cannot enable this setting if the destination server’s hostname does not resolve. Run the /usr/local/cpanel/scripts/ensure_hostname_resolves script, or use WHM’s Change Hostname interface (WHM » Home » Networking Setup » Change Hostname) to fix your hostname resolution.
  • This process only includes active PHP sessions from the user’s home directory. Users may need to log in again for features such as WordPress®, phpMyAdmin, and Webmail.
  • The Live Transfer feature uses the Accept and queue messages setting behavior for email delivery. For more information about this setting, read our What Happens When You Suspend an Account documentation.

Use the Live Transfer feature to reduce downtime during account transfers. The interface enables this feature by default. The Live Transfer feature moves cPanel accounts to a new server and performs the following actions on the source server:

  1. Updates the account’s A record to point to the destination server.
  2. Changes the domain’s nameserver entries to point to the destination server.
  3. Updates the email routing configuration’s MX records so that mail arrives at the destination server.
  4. Sends requests for certain services to the destination server. For example, the system can redirect web and mail traffic to the destination server.
    Note:
    • Mail services redirect to the child node, if applicable.
    • To disable service proxying, unsuspend the account on the source server.
  5. Copy the mailbox data from the source server again.
  6. Suspends the transferred accounts on the source server. For more information, read our What Happens When You Suspend an Account documentation. The system performs changes on the source server in the /usr/local/cpanel/scripts/xferpoint directory.
    Note:

    If you do not want to use this feature, you can use the swapip script to update the transferred accounts’ nameserver records.

Additional Documentation