🛎️ This is outdated! See docs/admin/Migrations.md for the most recent version.

apnscp now supports cPanel migrations as of v3.0.53. Migrations allow fast restoration into apnscp. Better yet, apnscp can be used with PowerDNS integration to share DNS servers with cPanel as you transition over.

Components

• Import account metadata from cp
  - Apply plan from PLAN=
  - Preserve STARTDATE=, DEMO=,
  - Copy storage/bandwidth/domain limits
• SSL certificates
• Cronjobs
• Users, quota limits, passwords
  - Each user assigned unique user ID
  - Conflicting email addresses by default fail, set --conflict=merge per Merge Policy
• Email aliases, forwards
  - Conflict policy applies
• Restores inboxes and files within /homedir
• Addon domains, parked domains (aliases to primary domain)
• MySQL databases, users (override conflict with -c mysql,dbaseprefix)
• DNS change on migration, disable with --no-activate
• Automatic Web App scan + enrollment in nightly updates (--no-scan disables)
• Add last login IPs to delegated whitelist if platform version supported (v8+, see Caveats section)

Migration procedure

ImportDomain consists of two stages, account creation and file migration. Stages may be selectively run.

Basic usage

ImportDomain --format=cpanel /path/to/cpmove-backup.tar.gz

Account creation

An import will faithfully restore whatever options were used in creation. Conflicts may arise and can be remedied by overriding creation options using -c service,parameter=value. For example to change the storage to 10 GB in a restore,

ImportDomain -c diskquota,quota=10 -c diskquota,units=G --format=cpanel  /path/to/cpmove-backup.tar.gz

Dumping parsed configuration

--dump will dump the configuration inferred from the backup.

ImportDomain --format=cpanel --dump /path/to/cpmove-backup.tar.gz

Sample response:

siteinfo:
    plan: basic
    email: matt@apnscp.test
    domain: apnscpbackup.test
    admin_user: atest
bandwidth:
    threshold: 104857600000
    units: B
diskquota:
    quota: !!float 3000
    units: MB
aliases:
    max: null
    aliases: { apnscpaddon.test, apnscpaddon.apnscpbackup.test, dph.apnscpbackup.test }
mlist:
    max: null
mysql:
    dbasenum: null
    dbaseadmin: atest
rampart:
    whitelist: [64.22.68.1]
auth:
    cpasswd: $6$test$test
ssh:
    enabled: true
crontab:
    enabled: true

Account import

Import occurs following creation. Import is destructive. Any users in conflict or directories in conflict with the backup will be removed during the import stage. Use --no-create to bypass creation and perform just data import.

ImportDomain --format=cpanel --no-create /path/to/cpmove-backup.tar.gz

Email conflict

Each email account is delivered to a separate user account. Partitioning email into distinct user accounts ensures that an account may have multiple distinct users and each of these users is protected from snooping by other users on the account. Such a format conflicts with cPanel's single UID approach. apnscp has a few solutions to remedy:

Conflict strategy may be specified with --conflict=method. The default method is fail.

Bypasses

DNS activation

DNS will update to the current server at conclusion of import. This behavior may be disabled by passing --no-activate to ImportDomain.

Web App scan/update

Once an import concludes, the filesystem is scoured for known web apps to be enrolled in nightly automatic Web App updates (core: nightly, assets: Wednesday/Sunday). Use --no-scan to prevent this behavior.

Decompression oddities

Migration will attempt to use PHP's PharData handler to decompress files. It's based on USTAR, which has limitations that may result in a cPanel backup generated in POSIX.1-2001 standards to fail. Use --no-builtin to disable the builtin handler from attempting to read the backup.

Previewing domains

There's a KB article on it!

Caveats

• Delegated whitelisting requires apnscp 3.1.
• apnscp has no notion of a "parked domain". The maximum number of addon domains is the max of MAXADDON and MAXPARK.
• Accounts are multi-tenant. Each mailbox is a separate user account. In multi-domain layouts duplicate email addresses can be merged into a single user account or separated into distinct user accounts. Default policy is to fail when a conflict is encountered. Specifying --conflict=merge or --conflict=namespaced will merge duplicate addresses or split addresses into separate user accounts when encountered.
• Database and account passwords are separate. cPanel does not store the database password anywhere instead relying on storing the password in the active session for phpMyAdmin SSO. SSO will not function until the user updates the password via Databases > phpMyAdmin. For added security, the password should be changed to something different than the panel password via Databases > MySQL Manager. Doing so will also update the stored password in ~/.my.cnf.

To-do

• Mailing list
• PostgreSQL user/database
• Update paths in files/database
• Webmail address book