apnscp provides an automated migration system to assist you in moving accounts from system to system and platform to platform. There are a few prerequisites to confirm before migrating:

✅ You have root (administrative) access on both servers
✅ Public key authentication is configured on the destination server
✅ Both source + destination run apnscp
✅ Source + destination server have DNS configured (optional)

As long as the account fits this checklist, you're golden! To initiate migration, issue the following command:

apnscp_php /usr/local/apnscp/bin/scripts/transfersite.php -s <newserver> <domain>

Where is the destination server, a fully-qualified domain isn't necessary, and is the domain name, site identifier (siteXX), or invoice grouping to migrate. For example, if a server has 3 accounts run by Ted with the billing grouping "tedsite" via billing,invoice/billing,parent_invoice in its service definition, then the following will kickoff 3 migrations in serial for Ted's sites to the server with the hostname newsvr.mydomain.com:

apnscp_php /usr/local/apnscp/bin/scripts/transfersite.php -s newsvr.mydomain.com tedsite

As long as DNS is configured for the site and the target server has the same DNS provider configured, then migration will be fully automated with an initial stage to prep files and give a 24 hour window to preview the domain. If DNS isn't configured for a site, (dns,provider=builtin), then an optional parameter, --stage, can be provided to set the migration stages.

  • Stage 0: initial creation
  • Stage 1: second sync
  • Stage 2: site completed

Stage 2 is a no-op; the site is considered migrated.

apnscp_php bin/scripts/transfersite.php --stage=0 newsvr.mydomain.com tedsite

To skip creation as a site, for example if an intermediate stage fails, then --no-create can be specified to skip creation on when stage is 0.

Migration components

apnscp migrates sites by component. Available components may be enumerated using, --components

Stages

  • users
  • passwords
  • sql_databases
  • sql_users
  • mysql_users
  • pgsql_users
  • sql_schema
  • addon_domains
  • subdomains
  • email_domains
  • mailing_lists
  • files
  • mailboxes
  • crons
  • vmount
  • dns
  • http_custom_config
  • letsencrypt_ssl
  • mysql_schema
  • pgsql_schema

Some components accept arguments, such as files in which case typical apnscp syntax applies. Component arguments are delimited by a comma:

apnscp_php bin/scripts/transfersite.php --do=files,'[/var/www]' mydomain.com

Reruns file migration on /var/www for mydomain.com. Upon completion the stage won't be updated.

Multiple stages can be run by specifying --do multiple times.

apnscp_php bin/scripts/transfersite.php --do=addon_domains --do=subdomains mydomain.com

Overriding configuration

Site configuration can be overridden during stage 0 (account creation). This is useful for example if you are changing VPS providers, while retaining the respective provider's DNS service.

apnscp_php bin/scripts/transfersite.php --override='dns,provider=linode' --override='dns,key=abcdef1234567890' mydomain.com

On the source server, mydomain.com may continue to use DigitalOcean as its DNS provider while the on the target server mydomain.com will use Linode's DNS provider. Once mydomain.com completes its initial stage (stage 0), be sure to update the nameservers for mydomain.com.

Migration internals

apnscp uses DNS + atd to manage migration stages. A TXT record named __acct_migration with the unix timestamp is created on the source server. This is used internally by apnscp to track migration. apnscp creates an API client on both the target and source servers. A 24 hour delay is in place between migration stages to allow DNS to propagate and sufficiently prep, including preview, for a final migration. This delay can be bypassed by specifying --force. All resolvers obey TTL, so don't force a migration until the minimum TTL time has elapsed!

Migration TTLs are adjusted on the target server to 60 seconds. If you are changing DNS providers during migration, this will allow you to make nameserver changes without affecting your site. On its inital migration (stage 0), apnscp copies all DNS records verbatim to the target. At the end of the second migration stage (stage 1), all records that match your old hosting IP address are updated to your new IP address. All other records are not altered. Additionally, __acct_migration is removed from the source DNS server and account put into a suspended state. When both source and target share the same nameserver, only TTL is reflected at the end of stage 0 and IP address changed at the end of stage 1. At the end of stage 1, TTL is reset to the default TTL setting.

Further reading