cPanel/WHM to KLYRN

Read this before anything else

No archive produced by a real cPanel server has ever been fed to KLYRN's parser. The fixtures in the test suite were written from cPanel's published documentation by the same people who wrote the parser. An archive built by test/vps/make-cpmove.sh in pkgacct's layout from a real WordPress site has been run end to end. A stand-in source exercises SSH, the root check, detection, the pkgacct invocation, streaming, cleanup and the whole pipeline. It does not exercise pkgacct.

Anything the parser does not understand becomes a warning on the plan, never a silent omission. Keep the old server running and compare the two sites yourself before DNS moves.

Before you start

Root on the live server

Any account. KLYRN runs the server's own pkgacct, streams the archive here and deletes the temporary copy.
klyrn import ssh --host old.example.com --user root --account acmeuser

The cPanel account's own login

cPanel's own API packages that one account. Another account is refused with “connected as , who can only package their own account”.
klyrn import ssh --host old.example.com --user acmeuser --password ''

An archive you already have

A cpmove- or backup-<date>_<user> archive, uploaded or given by path: .tar.gz, .tgz, .tar.xz, .tar.zst or .tar. A nested homedir.tar is handled.
klyrn import cpanel /root/backup-acme.tar.gz

Whichever route, you also need:

• The cPanel username, matching [a-z][a-z0-9]{0,15}.
• Room on the source for the temporary archive.
• Room here: 1 GB free for a collection, and about twice the archive's size for an import.
• A password or an unencrypted private key.
• A decision about mail.

These routes produce one archive and apply it. Pre-copy, delta and resume belong to a Linux server over SSH.

What migrates

The account

cp/<user>: the main domain, contact address, plan name, source IP and home directory. With no DNS= line it is reported as “main domain unknown”.

Every domain

userdata/main lists them and userdata/<domain> describes each. Addon, subdomain and parked entries become sites. The helper subdomain behind an addon domain does not.

PHP per domain

From phpversion. ea-php81 becomes 8.1, alt-php74 becomes 7.4, and inherit resolves from the parent. A version this server lacks is warned about.

Databases and their users

mysql/<db>.sql holds the dumps and mysql.sql the grants. Users keep their original password hashes.

Scheduled tasks

cron/<user>. Environment lines are skipped.

Files and site type

As in every migration. A WordPress wp-config.php is re-pointed, and the original is kept as wp-config.php.klyrn-import.bak.

An account is renamed when a system user of that name exists here, or the cPanel name is not usable. Its database names are re-prefixed and wp-config.php is updated. Other configuration files may need editing by hand.

What does not migrate

An archive migration leaves mail behind. The analysis counts the mail domains under va/ and the mailboxes under the home directory's mail/. The migration then finishes as Complete with warnings. With mail hosting on, a separate step brings mail from a live cPanel server over SSH. MX records are not touched.

• DNS zones. dnszones/*.db are read. They are copied only when this server is the nameserver.
• Certificates. apache_tls/<domain> is recorded. KLYRN issues its own.
• Autoresponders and filters.
• Apache behaviour nginx does not have. See what happens to .htaccess.
• Bandwidth history and logs. pkgacct runs with --skiplogs --skipbwdata.

Downtime

The source stays live throughout. Anything written on it after the archive is made is not in the archive, and this route has no delta pass.

• Packaging runs on the source. The job logs the archive's size and duration. Without root, KLYRN gives up after six hours.
• Streaming checks the byte count against the size the source reported.
• Apply is the first thing that creates anything here.

For a shorter window, use the SSH route.

Checks and refusals

The connection check and host key pinning are those of every SSH route. cPanel is recognised by /usr/local/cpanel/cpanel and /usr/local/cpanel/version.

“the source does not look like a cPanel server (no /usr/local/cpanel/version)”

Use the generic route, or upload an archive.

“/scripts/pkgacct is missing on the source server”

Without cPanel's packaging tool there is nothing to run.

“no user ‘acme’ on the source server”

Use the cPanel username. The domain will not work.

“this login cannot package a cPanel account: uapi is not available on the source”

Connect as root, or migrate the files and databases directly.

“cPanel refused to create the backup”

The account may be over quota, or the host may have disabled backups.

“cPanel finished but no backup-.tar.gz appeared”

Check the disk quota on the source.

“this archive is not safe to extract”

A member points outside the tree or is a type KLYRN will not extract. The reason names it. A nested homedir.tar is read the same way.

“this does not look like a cPanel account archive (no cp/<user> file found)”

Try klyrn import archive <file>, which detects the kind.

“a site with this domain already exists on this server”

Apply a subset with --domains, or remove the existing site.

“database <name> already exists on this server”

--databases takes a subset.

klyrn import show 1        # every domain, database, user and cron entry, with conflicts
klyrn import apply 1
klyrn import apply 1 --account acme --domains example.com --databases acme_wp
klyrn import apply 1 --no-cron --no-ssl

Cut-over

Follow the cut-over, in order. Two steps are added for mail:

• Before anything else, settle mail. KLYRN never changes an MX record. Leave MX on the old server and keep it running. Or turn mail hosting on here, bring the mail across, check it, and then move MX.
• After DNS moves, check the mail row. The verification marks an MX record pointing at this server as action required.

Keep the old server longer than a week if it still answers for mail.

Rollback

KLYRN never deletes or suspends the source account. It removes only the temporary archive it asked the source to create.

1. Point DNS backThe old server has every file, database and mailbox it had before.
2. Remove what landed hereklyrn import delete <id> removes the migration record and its working files. Delete the sites and databases separately. An archive given by path is never removed. One uploaded through the panel is.

Troubleshooting

“download interrupted after 4.1 GB”

The source archive stays at the path the message names. Run the migration again.

“downloaded 4.1 GB of 6.2 GB”

A short file is deleted here and not analysed.

“cPanel has been packaging for over 6 hours; giving up”

Check the account on the source, then run the migration again.

“could not remove on the source”

A warning. Delete the temporary archive on the old server yourself.

“user had no recoverable password hash; a new password was set”

Reset the password in Databases, and update the application's configuration.

“document root not in the archive; site created empty”

Put the files there yourself.

“no documentroot recorded; will use public_html/<domain> if present”

An addon or subdomain entry with no document root of its own. The plan says so per domain.

“not enough free space to extract this archive”

About twice the archive's size is needed.

“parked (alias) domain: add it as an alias of the main site after import”

It is listed and does not become a second site.