WHM Transfer Tool: move cPanel accounts between servers

The Transfer Tool is the supported way to move accounts between two WHM servers — packages, feature lists, reseller hierarchy, service config, and the accounts themselves. It pulls from the source over SSH, so you run it from the destination server, never the source.

This guide covers the tool end-to-end: when to pick it over rsync or JetBackup, the SSH plumbing that has to be in place first, Express Transfer (the option most people miss), and the DNS cutover sequence that keeps mail flowing while accounts move.

When Transfer Tool is the right choice

Use it when:

• Source and destination are both WHM, both running a supported AlmaLinux / Rocky / Ubuntu version, and the destination version is equal to or newer than the source. Transfers from a newer cPanel build to an older one are blocked.
• You want resellers, packages, and feature lists copied alongside accounts. pkgacct only handles individual accounts; the Transfer Tool handles the WHM-level state too.
• You can tolerate a single sync window per account. The tool snapshots, transfers, and restores — it does not do continuous replication.

Reach for alternatives when:

• You need delta sync over hours or days while a site stays live. Use JetBackup account restores from incrementals, or a manual rsync of /home/<user> plus a final cutover.
• You're moving off cPanel entirely. See migrating cPanel accounts to Plesk instead.
• The source is unreachable. The tool requires SSH; if all you have is a backup tarball, restore it with /scripts/restorepkg.

Pre-flight: requirements on both servers

On the destination (where you'll run the tool):

• Free disk on /home of at least 1.5× the source's used /home size. Express Transfer needs less, but plan for the safe number.
• A licensed WHM (check your tier — Solo only allows one account, so a multi-account transfer will fail at account two).
• Outbound TCP/22 to the source IP. If the source firewalls SSH by IP, whitelist the destination first.

On the source:

• Root SSH enabled, even if only temporarily. The tool authenticates as root.
• Backups paused, or at least no pkgacct running. Concurrent pkgacct jobs on the same account corrupt the tarball.
• Enough free space in /home (or /backup if that's where pkgacct writes) for one account's tarball at a time — typically the largest account's /home size plus 20%.

Authenticate the destination to the source

The tool accepts either a root password or an SSH key. Keys are faster, don't time out, and don't sit in the WHM session. Set one up:

# On the destination
ssh-keygen -t ed25519 -f /root/.ssh/transfer_key -N ""
ssh-copy-id -i /root/.ssh/transfer_key.pub root@source.example.com

Test it:

ssh -i /root/.ssh/transfer_key root@source.example.com 'whoami && /usr/local/cpanel/cpanel -V'

You should see root and the source's cPanel version. If the version comparison goes the wrong way (destination older than source), stop here and upgrade the destination first — the rest of the transfer will fail at the restore step.

Run the transfer

Via the WHM UI

WHM » Transfer Tool » Transfer or Copy an Entire Account.

1. Server type: WHM with root access.
2. Hostname or IP: the source FQDN. Use IP if DNS for the source might change mid-transfer (it will, see DNS cutover below).
3. Authentication: paste the contents of /root/.ssh/transfer_key as the SSH key, leave password blank.
4. Port: 22 unless you've moved it.
5. Click Fetch Account List. You'll get the user list with checkboxes.
6. Select accounts. Check Express Transfer at the top.
7. Under Transfer Options, keep Copy Reseller Privileges, Copy Packages, and Copy Feature Lists enabled unless you're flattening reseller structure on the new box.
8. Click Copy.

Express Transfer — what it actually does

Express Transfer streams the account directly into place on the destination as the source generates it, instead of writing a tarball, transferring it, then unpacking. On a 50 GB account it's roughly half the wall-clock time, and it removes the "do I have enough scratch space for the tarball" question.

Caveats: Express Transfer aborts if the network drops mid-stream and the account has to be re-queued from scratch. On a flaky link, the classic mode is more recoverable because pkgacct's tarball survives a reconnect.

Via the command line

For scripted migrations, kick off the same transfer with whmapi1:

whmapi1 create_remote_user \
  remote_server=source.example.com \
  remote_user=root \
  authentication=key \
  ssh_key_name=transfer_key

whmapi1 start_transfer_session \
  remote_server=source.example.com \
  user-1=alice \
  user-2=bob \
  use_express_transfer=1

Poll status with whmapi1 get_transfer_session_state transfer_session_id=<id>. Logs land in /var/cpanel/logs/transfer/.

DNS cutover with low downtime

The transfer copies DNS zones but doesn't change the records — A records still point at the source IP. Cut over in this order:

1. Drop TTLs to 300 seconds on the source zones 24-48 hours before the transfer window. Do this even if you don't think you need it.
2. Run the transfer. Verify each account loads on the destination by editing /etc/hosts on a workstation and browsing the site.
3. Repoint A records to the destination IP. If you run a DNS-only cluster, update there.
4. Park mail on the destination by ensuring MX records flip at the same time. If MX still points at the old IP, mail keeps landing on the source for the duration of TTL propagation — you'll need to re-sync mail at cutover or run a final rsync of /home/<user>/mail after DNS settles.
5. Once propagation is done (check with dig +short @8.8.8.8 example.com), suspend the source account with whmapi1 suspendacct user=alice to make sure no stragglers write to it.

Post-transfer verification

For each transferred account, check:

• /var/cpanel/users/<user> exists and contains the right package and IP.
• /etc/userdatadomains lists the account's domains.
• Mail flows: mail-test@mail-tester.com from the account's webmail.
• SSL is intact. AutoSSL should re-issue on the destination within 24 hours; if it doesn't, see AutoSSL failures.
• The customer can log into cPanel using their old password (passwords transfer as hashes — no reset needed).

If you're transferring to a LiteSpeed-backed server, the licence migrates with the account but LSCache for WordPress needs to be re-enabled per site if the source ran Apache.

Common failures and fixes

Next steps

• Upgrading the underlying OS before migration — if your source is still on CentOS 7, fix that first.
• cPanel licence tiers explained — make sure the destination tier covers the account count.
• AutoSSL failures after migration — the most common post-transfer ticket.

Volume migrations across multiple servers? Contact sales — we can issue temporary destination licences during cutover windows so the old box stays licensed until DNS fully propagates.