cPanel to CyberPanel Manual User Backup Restore Without Corrupted Tarball Issues

by

Root Cause Diagnosis

CyberPanel’s Backup > Restore Backup page only accepts CyberPanel-format archives, so a cPanel backup-*.tar.gz or cpmove-*.tar.gz has to go through the separate importer script, /usr/local/CyberCP/plogical/cPanelImporter.py. That script extracts the file with a plain tar -xf and then reads userdata/main from the extracted tree. Most “corrupted tarball” errors therefore mean the archive was truncated or altered before extraction (ASCII-mode FTP, an interrupted upload, a full disk, a proxy timeout). The other common cause is a partial cPanel backup (home directory only) that lacks the userdata/ and mysql/ directories the importer expects.

Quick Fix

Verify the archive on the CyberPanel server. If it fails, re-transfer it in binary mode with rsync, then run the importer.

# On the cPanel/WHM source
sha256sum /home/cpmove-USER.tar.gz

# Re-transfer (binary-safe, resumable)
rsync -avP --partial /home/cpmove-USER.tar.gz root@NEW_SERVER_IP:/home/backup/

# On the CyberPanel server
cd /home/backup
sha256sum cpmove-USER.tar.gz          # must match the source hash
gzip -t cpmove-USER.tar.gz && echo OK # must print OK
/usr/local/CyberCP/bin/python3 /usr/local/CyberCP/plogical/cPanelImporter.py --path /home/backup/cpmove-USER.tar.gz

Step-by-Step Resolution

1. Generate a full account package on the source

Run this as root on the cPanel server. It produces a complete cpmove archive, unlike the home-directory-only partial backup.

/scripts/pkgacct USERNAME /home
# Output: /home/cpmove-USERNAME.tar.gz
sha256sum /home/cpmove-USERNAME.tar.gz > /home/cpmove-USERNAME.sha256

2. Check free space on the CyberPanel server

Extraction needs roughly 2–3x the archive size, plus space for the database import.

df -h /home /tmp /root
df -i /home          # inode exhaustion also breaks extraction
grep -n "mainBackupPath" /usr/local/CyberCP/plogical/cPanelImporter.py

Make sure the filesystem holding the path printed by the grep has enough free space.

3. Transfer the archive in binary mode

Use rsync or scp. Do not use the browser file manager, and do not use FTP in ASCII mode.

rsync -avP --partial /home/cpmove-USERNAME.tar.gz root@NEW_SERVER_IP:/home/backup/

If the destination directory does not exist, create it first with mkdir -p /home/backup.

4. Validate the archive before importing

cd /home/backup
sha256sum cpmove-USERNAME.tar.gz
gzip -t cpmove-USERNAME.tar.gz && echo "gzip OK"
tar -tzf cpmove-USERNAME.tar.gz | grep -E '(^|/)userdata/main$|(^|/)mysql/.*\.sql$|(^|/)homedir/' | head

You should see userdata/main, at least one mysql/*.sql file (if the account has databases), and a homedir/ path. If userdata/main is missing, the archive is a partial backup. Regenerate it with pkgacct.

5. Confirm the CyberPanel version supports the importer

The cPanel restore utility was added in CyberPanel v1.8.5, so older installs need upgrading first.

ls /usr/local/CyberCP/plogical/cPanelImporter.py
cat /usr/local/CyberCP/version.txt 2>/dev/null

6. Run the importer

If /home/backup holds a single backup file, you can pass the directory. With several files, pass the full path of the one you want.

/usr/local/CyberCP/bin/python3 /usr/local/CyberCP/plogical/cPanelImporter.py --path /home/backup/cpmove-USERNAME.tar.gz

7. Read the log

The script prints a log path under /home/cyberpanel/ (for example /home/cyberpanel/5761) that records whether the restore succeeded.

tail -n 50 /home/cyberpanel/LOGID

8. Recover manually if the tarball is partially corrupt

Streaming extraction keeps everything readable up to the point of damage.

mkdir -p /root/restore && cd /root/restore
gzip -dc /home/backup/cpmove-USERNAME.tar.gz | tar -xf - 2>/root/restore/tar.err
tail /root/restore/tar.err
ls cpmove-USERNAME/ 2>/dev/null || ls

Then rebuild the site by hand:

  1. Create the website and its database in CyberPanel (Websites > Create Website, Databases > Create Database).
  2. Copy the files:rsync -a /root/restore/cpmove-USERNAME/homedir/public_html/ /home/DOMAIN/public_html/ chown -R SITEUSER:SITEUSER /home/DOMAIN/public_html
  3. Import the database (cPanel prefixes names as user_dbname):mysql NEWDBNAME < /root/restore/cpmove-USERNAME/mysql/OLDDBNAME.sql
  4. Update the credentials in wp-config.php or the equivalent config file.
See also  aaPanel Docker manager bridge network conflicting with local host IP subnets

9. Post-restore: addon domains

If the cPanel account hosted several domains, the restore shows only the main domain. The other domains’ files end up inside the main domain’s public_html. Create each missing site in CyberPanel, then move its files:

mv /home/MAINDOMAIN/public_html/ADDONDOMAIN/* /home/ADDONDOMAIN/public_html/

Reissue SSL certificates afterwards (SSL > Manage SSL), because certificates are not carried over reliably.

Why This Fails for Some Users

  • Partial backups: The cPanel Backup interface’s “Home Directory” or “Databases” downloads are not account packages. Only a full backup or pkgacct output contains userdata/ and mysql/.
  • Disk or inode exhaustion: A full /home or /tmp, or a small tmpfs, aborts extraction mid-stream and the resulting error reads like a corrupt archive. Check with df -h and df -i.
  • Proxy or panel upload limits: Uploads through the panel behind Cloudflare’s proxy, or through the web file manager, can time out or be truncated. Use SSH-based transfers.
  • ASCII-mode FTP: It rewrites line endings inside binary data and always corrupts the gzip stream.
  • Compression mismatch: If cPanel’s backup compression is set to none, you get a plain .tar. Running gzip -t on it fails even though the archive is intact. Check with file cpmove-USERNAME.tar*.
  • Encrypted or renamed archives: Backups processed by GPG or a remote backup tool need decrypting first. Renamed or double-compressed files (.tar.gz.gz) also fail to extract.
  • MySQL 8 to MariaDB dump incompatibilities: Dumps that use collations like utf8mb4_0900_ai_ci, or DEFINER clauses, fail on import into MariaDB. Symptoms are a database that is empty after a “successful” file restore. Fix with sed -i 's/utf8mb4_0900_ai_ci/utf8mb4_general_ci/g; s/DEFINER=[^ ]*//g' file.sql before importing.
  • Domain or user conflicts: If the domain or username already exists in CyberPanel, the importer aborts partway. Remove or rename the conflicting site before running it again.
  • Large accounts: Archives in the tens of GB can exceed the time or space budget of a single run. Restore files and databases separately using the manual procedure in step 8.
  • Old CyberPanel builds: Versions below 1.8.5 have no cPanelImporter.py, and the Restore Backup page rejects the archive with a generic error.
See also  Setting up strict Let's Encrypt renewal with Cloudflare API token without global key

Leave a Comment