How To Migrate ISPConfig 2, ISPConfig 3.x, Confixx, CPanel or Plesk to ISPConfig 3.2 (single server)

Prerequisites

ISPConfig 3.x on the source server.
ISPConfig 3.1.7 or higher on the target server.
PHP 5.3+ with JSON, mcrypt, OpenSSL and mbstring support on the source.
Old and new server must not be connected to the same master server. If they are connected to the same master, use ISPCopy instead (which is part of the Migration Toolkit as well).
Migration Toolkit License.
The old and new server must use the same Let's Encrypt client. If your old server uses certbot, then ensure that the new system is using certbot too and not acme.sh.

Create a remote user in ISPConfig

You need a remote user on the target ISPConfig server.

Go to System -> Remote User

Click on the Add new user button.

Enter a username and password for the remote user, e. g. "remoter" and make sure you checked all checkboxes. Then click "save".

If you are using an ISPConfig version 3.1.11 on the target server, then edit the file /usr/local/ispconfig/security/security_settings.ini as root user:

nano /usr/local/ispconfig/security/security_settings.ini

and change the values of ids_anon_enabled and ids_user_enabled from 'yes' to 'no'.

....
[ids]
ids_anon_enabled=no
ids_anon_log_level=1
ids_anon_warn_level=5
ids_anon_block_level=20
ids_user_enabled=no
ids_user_log_level=1
ids_user_warn_level=10
ids_user_block_level=25
ids_admin_enabled=no
ids_admin_log_level=1
ids_admin_warn_level=5
ids_admin_block_level=100
sql_scan_enabled=yes
sql_scan_action=warn
apache_directives_scan_enabled=yes
nginx_directives_scan_enabled=yes
....

The IDS can be enabled again when the migration is finished. If you use ISPConfig 3.1.12 or newer, then this change is not required.

Next, please check if the php-soap module is installed on the target server. If it is not installed, then install it now. On Debian and Ubuntu, you can install the PHP Soap module with apt:

apt-get install php-soap

Another prerequisite is that target and source server must have rsync installed. Please check with e.g.:

rsync --version

on both nodes that rsync is installed. If it is not installed, then install the rsync package of the operating system. E.g. with:

apt-get install rsync

on Debian and Ubuntu or with:

yum install rsync

on CentOS.

On the target server, there might be a file /etc/ssh/sshd_config.d/custom.conf created by the ISPConfig auto-installer which prevents the Migration tool from working. This file must be deleted if it exists. Run this command on the target server as root user to delete the file:

rm /etc/ssh/sshd_config.d/custom.conf

All following steps are done on the source server unless told otherwise.

Download and extract the Migration Tool

cd /root
mkdir migration
cd migration
wget https://www.ispconfig.org/downloads/ispconfig_migration_toolkit-latest.zip
unzip ispconfig_migration_toolkit-latest.zip
mv ispconfig_migration_toolkit/ispc3-migration-tool-*.tar.gz /root/migration/migtool.tar.gz
tar xzf migtool.tar.gz
rm -f migtool.tar.gz

During migration, there will be an SSH connection for transferring settings and data from the source to the target server(s). For this, the source server has to be able to connect to the target(s) without password.

You can either:

Set up passwordless login by yourself (add the public key of the source to the target root's authorized_keys file).
Or allow root access via ssh to the target by password (temporarily). The Migration Tool will then call ssh-keygen and ssh-copy-id for you. These are direct system calls, so if you are prompted for the target's ssh root password during this step, the input is NOT read by the Migration Tool, it is a direct prompt by the ssh-copy-id system command.

Run the migration (dry-run)

./migrate

If you want to run the tool on a specific PHP version (E.g. PHP 7.4 on Ubuntu 22.04), then use this command instead:

PHP=/usr/bin/php7.4 ./migrate

The result of any of the above commands will be like this:

Welcome to the ISPConfig3 Migration Tool V2 Version 2.0.0

Although this tool does not alter anything on the source server, you should
ALWAYS make a BACKUP of all your data before migrating to a new server!

You need to have some prerequisites set up to use this tool:
 * create an remote user (system -> remote users) in your TARGET ISPConfig3 system and grant ALL rights to it
 * make sure this (the SOURCE system) can reach the remoting api of the TARGET system

*** Disclaimer of Warranties ***
ISPConfig disclaims to the fullest extent authorized by law any and all other warranties, whether express or implied,
including, without limitation, any implied warranties of title, non-infringement, integration, merchantability or
fitness for a particular purpose.
By continuing to use this software, you agree to this.

First of all the most important question:
Do you want to make a real migration or a dry run? (dry, migrate): dry

We want to run in dry-run mode first, so we enter dry here.

The following modules are available:
        1. Confixx to ISPConfig 3 migrator (confixx)
        2. Plesk (10.5 - 17.5) to ISPConfig 3 migrator (plesk)
        3. ISPConfig 2 to 3 migrator (ispconfig2)
        4. ISPConfig 3 to ISPConfig 3 migrator (ispconfig3)

Which one is the one matching your SOURCE system? (confixx, plesk, ispconfig2, ispconfig3): ispconfig3

The Migration Tool needs to know which control panel you are using on your source server. It tries to recognize the required module on the source server, so you can normally simply press ENTER.

Enter this (SOURCE) server's ip that is used for outgoing connections [192.168.10.10]: 123.123.123.123

The Migration Tool needs to know what IP address on the source server is used for outgoing connections, i. e. which ip address other servers will see when the source is connecting to them. The tool tries to guess the ip address but you might need to change the value if you are using a private network for example.

Name of the remote user of TARGET ISPConfig3 system []: remoter
Password for this remote user []: yourremotepassword
URL to the remote system (e. g. https://yourdomain.com:8080/remote/) []: https://www.example.com:8080/remote/
You gave me remote user 'remoter' with password 'yourremotepassword'
And I shall connect to 'https://www.example.com:8080/remote/'
Is this correct? (y, n): y

Provide the Migration Tool with the data of the remote user that you created on the target and confirm your input with "y". The Migration Tool then will try to connect to the remote API of your target system.

I will now have to make some changes in your ISPConfig3 TARGET system config.
        1.) Enable domain module if needed
        2.) Remove client prefixes (will be undone automatically at the end)
        3.) Enable login for mail accounts if needed

Testing MySQL connection ... OK

What is the main public(!) ip of the target server www.example.com? [123.123.123.123]: [ENTER]

The Migration Tool will change some ISPConfig settings on the target (these changes will not be done, when runnin in dry-run mode) and test the connection to the MySQL server. It tries to guess the MySQL credentials by looking at some system files but eventually, you will be prompted for the MySQL root password.

Next, you need to give the public IP of the target server. It will be pre-fetched from DNS, but you might need to adjust it, especially if you use the same hostname on the source and target.

Do you want me to overwrite/update existing entries with the same name? (y, n): y
You can now set entry names, that shall NOT be overwritten.
You should use this if you plan to import several server's data to a multi-server installation.
If this tool finds a name that is already present, it UPDATES the data with the SOURCE data!
If this tool finds a name that you marked as not to overwrite, it either
         - appends a _2, _3 etc. to this name and creates a new entry, or
         - prepends a server prefix if specified by --server-prefix argument

The Migration Tool allows merging multiple servers into one target. When doing this, it might be that there are conflicting usernames on the source servers, e. g. if you have two databases with the name "testdatabase". If you answer "y" to this question, then the second database will replace the first one. If you answer "n" then it will change the name of the second database to "testdatabase_2".

Be sure to answer "y" when doing a single server migration because otherwise, you will create duplicates if you run the migration tool multiple times on the same source.

You currently have 0 FTP username name(s) marked:

You can now add further names to this list. Just enter them one by one or provide a comma-separated list.
To delete one or more names from the list, prepend a /DELETE to your input.
To clear all names from the list, type /CLEAR.
A blank input proceeds to the next step.
Your choice : [ENTER]

The Migration Tool offers you to mark some usernames for FTP, databases, clients etc. as "reserved". This means they will not be overwritten as mentioned in the section above. Normally you will leave this blank, but in some cases you might prevent usernames like "admin" or "administrator" from being imported. So you can enter them here which will result in a renaming of the imported names to "admin_2" etc.

The question is repeated for the different service types (FTP, database, clients, mail users).

What is the database name of your SOURCE ISPConfig 3 installation? [dbispconfig]: [ENTER]

The tool now asks for the database name on the source server that holds the control panel's data. Please check if the recognized database is correct and change it if needed.

Do you want to migrate only some services or everything?                                                                 
Valid services are: client, web, mail, ftp, database, cronjob, dns, billing                                              
Please enter one or more services (comma-separated) or leave blank for all: [ENTER]

The new Migration Tool is able to only migrate a subset of services, e. g. only migrate mail accounts and skip webs etc.

We want to migrate all services so we just leave the input blank and press ENTER.

To copy over web data, I need SSH access to the target webserver.
Please make sure that root login via SSH is allowed. On the target open /etc/ssh/sshd_config
and set PermitRootLogin to yes or without-password.
You can revert this once the migration is complete.

What is the ip for the target web server to connect via SSH? [123.123.123.123]: [ENTER]
What is the SSH port? [22]: [ENTER]

For copying over web, mail and db data, the Migration Tool requires passwordless SSH access to the target server. You need to provide the ip and port that the source should connect to. If you haven't already set up passwordless access you will be prompted for the root SSH password of the target server.

Testing MySQL connection ... OK

Starting API calls.

[50/74] <Domain> processing mydomain.com

The tool will now start to create/update all the entries on the target ISPConfig. On dry run it won't change or copy anything of course. Wait for the API calls to finish.

Processing of entries done.                                                                                              
=============
Migration tool run completed.

Once the migration tool finished the dry run without errors, we can continue with the real migration.

Run the migration

./migrate

If you want to run the tool on a specific PHP version (E.g. PHP 7.4 on Ubuntu 22.04), then use this command instead:

PHP=/usr/bin/php7.4 ./migrate

The result of any of the above commands will be like this:

	Welcome to the ISPConfig3 Migration Tool V2 Version 2.0.0rc2

Although this tool does not alter anything on the source server, you should
ALWAYS make a BACKUP of all your data before migrating to a new server!

You need to have some prerequisites set up to use this tool:
 * create an remote user (system -> remote users) in your TARGET ISPConfig3 system and grant ALL rights to it
 * make sure this (the SOURCE system) can reach the remoting api of the TARGET system

*** Disclaimer of Warranties ***
ISPConfig disclaims to the fullest extent authorized by law any and all other warranties, whether express or implied,
including, without limitation, any implied warranties of title, non-infringement, integration, merchantability or
fitness for a particular purpose.
By continuing to use this software, you agree to this.

First of all the most important question:
Do you want to make a real migration or a dry run? (dry, migrate): migrate

This time we answer the prompt with "migrate" and answer the questions just as we did during the dry run. The tool will have your inputs from the dry run pre-filled, so you will mostly be able to press ENTER.

Testing MySQL connection ... OK
Copying Let'sEncrypt files to target ... OK

Starting API calls.
[9/11]  processing [email protected] (web213p41)

This time the process will take a bit longer as there are real API calls being done. Wait for the process to finish.

Processing of entries done.                                                                                              
Target ISPConfig job queue has 35 entries left. Waiting ..

To make sure all paths are created on the target the Migration Tool waits for ISPConfig to process all requests before it continues.

[INFO] Target ISPConfig job queue has completed. Continuing.

[19/935] Syncing /var/www/clients/client26/web21/web to /var/www/clients/client1424/web21/

Now the tool syncs all paths (web, mail) and copies over the database contents to the target server. This process can take a while depending on the amount of data you have.

If you want to do the actual data syncing in a separate step you can skip it by running ./migrate --no-syncjobs instead of just ./migrate

Final steps

The Migration Tool will reset the values it changed at the beginning (e. g. client prefixes).

Depending on your source control panel the Migration Tool activated the domain module on your target ISPConfig. This means that domains can only be used for websites, email domains etc. if they have been assigned by an administrator first (using Client -> Domains). If you do not want to use the domain module, you can disable it under System -> Interface settings -> Tab "Domains".

Finally, check the migrate.log that was created for entries that have [ERROR] or [WARNING] markers. These indicate problems during the migration process.

Re-Sync your target

Re-Sync accounts and settings

If things changed on the source control panel after you did the migration, you can just re-run it. The Migration Tool will update all entries with the new settings from your source server. And add new entries that were created in the meantime. Deleted entries on the source will not be deleted on the target!.

Re-Sync data

If you only want to re-sync the data for web, mail, and databases you can run ./migrate --syncjobs. This will skip all migration steps and only run the synchronization of websites, databases, and emails.

You can also ony re-sync one of the services, e. g. ./migrate --syncjobs --only=database. This will skip re-syncing website data and emails.

Advanced options

To get a list of advanced options which allows it to migrate e.g. single websites, mail domains or clients, use the --help option.

./migrate --help

The current options are:

Usage:  migrate <options>
        List of options:
        --help
                        Show this screen
        --server-prefix=<prefix>
                Use given prefix for conflicting usernames, if further
conflicts occur,
                add _2 _3 _4 ... to username
        --source-temp-dir=<parth>
                Set a different temp directory for actions on the source
server than /tmp
        --target-temp-dir=<parth>
                Set a different temp directory for actions on the target
server than /tmp
        --syncjobs
                Don't run the migration process, just re-sync all data
(web files, database contents)
        --no-syncjobs
                Only do the migration, don't copy any data files or
database contents to target
        --ignore-sync-errors
                Don't abort syncjobs processing if an error occurs. This
can be helpful for example
                if a command like chattr does not work correctly on the
target server.
        --confixx-no-domain
                On a confixx migration (source server) do not create a
dummy website that contains
                all other domains of that client as alias domains.
                Confixx uses a different approach for storing and
managing domains, so there is no
                "main" domain, but a hosting instead, that has all
domains assigned.
                On confixx servers where clients only have a single
domain it can be better to not
                create a dummy website with a single alias, but use the
domain as website instead.
        --only=client|web|mail|ftp|database|cronjob|dns|billing
                Only migrate the given service(s) and skip the others.
Can be provided multiple times.
        --exclude=client|web|mail|ftp|database|cronjob|dns|billing
                Migrate all services but the given one(s). Can be
provided multiple times.
        --only=/--exclude= on --syncjobs run
                When limiting the resync to single services, only web,
mail, database, system are valid.
        --only-client=<username>
                Only migrate a single client and it's data (web, mail
etc.). This can be used together
                with --only= / --exclude= to limit the migrated data
even further.
        --only-web=<domain.com>
                Only migrate the given domain and it's assigned
databases, ftp accounts etc.
                This can be used together with the other
--only-x/--exclude-x and --only=/--exclude= options
                to specify the data to be migrated.
        --only-mail=<domain.com>
                Only migrate the given mail domain and it's assigned
mail accounts, spam filter etc.
                This can be used together with the other
--only-x/--exclude-x and --only=/--exclude= options
                to specify the data to be migrated.
        --only-database=<databasename>
                Only migrate the given database and it's parent website.
                This can be used together with the other
--only-x/--exclude-x and --only=/--exclude= options
                to specify the data to be migrated.
        --only-dns=<domain.com>
                Only migrate the given DNS zone and it's assigned DNS
records.

                The above options can also be used in the opposite way,
using --exclude-client, --exclude-web,
                --exclude-mail, --exclude-database, --exclude-dns
                WARNING! Clients ALWAYS have to be migrated otherwise
you will have all migrated data assigned
                to the admin user instead of the client!