In this howto, we’ll show how to use the ISPConfig Migration Tool 2.0 to migrate a single server to a new ISPConfig 3.2 server. The Migration Tool is part of the ISPConfig Migration toolkit which is available here.
The ISPConfig Migration Tool can be used to migrate these Hosting Control Panels to an ISPConfig 3.2 server:
- ISPConfig 2
- ISPConfig 3 and 3,1
- Plesk 10 – 12.5
- Plesk Onyx
In this tutorial, we’ll migrate an ISPConfig 3.0 server to a new system running ISPConfig 3.2. The Migration from other supported hosting control panels is done similarly. The Migration Tool will guide you step by step through the migration process.
- 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”.
fIf 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:
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.:
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 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:
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
Prepare passwordless login (optional)
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)
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:
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]: 22.214.171.124
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? [126.96.36.199]: [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? [188.8.131.52]: [ENTER] What is the SSH port? : [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]
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
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:
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
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!.
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.
To get a list of advanced options which allows it to migrate e.g. single websites, mail domains or clients, use the –help option.
The current options are:
List of options: --help Show this screen --server-prefix= Use given prefix for conflicting usernames, if further conflicts occur, add _2 _3 _4 ... to username --source-temp-dir= Set a different temp directory for actions on the source server than /tmp --target-temp-dir= 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= 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= 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= 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= 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= 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!