There are three basic migration stages, each of which might finish with some issues:
The migration tool has pre-migration checks that verify whether all necessary resources are available for migration. This section describes how to resolve the problems found by the migration tool’s diagnostic utilities before migration has been started.
Pre-migration checkers can be launched by the "check" command of the 'panel-migrator' utility (both on Windows and Linux). Note that this command requires a migration list file; so "generate-migration-list" should be launched beforehand, or the "--migration-list-file" options should be added. During the execution of this command, the migration tool performs common checks (whether the required services are running and ports are open). Then it creates a shallow dump of business logic objects on the source server and compares the generated dump with the destination server. If there are any conflicts, they are added to the pre-migration check report.
The following types of issues can occur on the pre-migration check stage:
For each detected issue, there is a corresponding warning in the final report.
Errors that are caused by stopped services or closed ports are usually self-descriptive. Each error message contains information about the problematic port or service and the server where the issue occurred. Example:
¦ L error: Service 'mail' port 143 on target Plesk server is closed.
¦ 1) Check that service is up
¦ 2) Check that there are no firewall rules that may block connection to the service
Another example:
[INFO] | START: Check connections
[ERROR] | Exception: Error reading SSH protocol banner[Errno 104] Connection reset by peer
[ERROR] | Traceback (most recent call last):
[ERROR] | File "/opt/panel-migrator/thirdparties/python/lib/python2.7/site-packages/paramiko/transport.py", line 1516, in run
[ERROR] | self._check_banner()
[ERROR] | File "/opt/panel-migrator/thirdparties/python/lib/python2.7/site-packages/paramiko/transport.py", line 1633, in _check_banner
Previous page
Locate page
Link to this page
[ERROR] | raise SSHException('Error reading SSH protocol banner' + str(x))
[ERROR] | SSHException: Error reading SSH protocol banner[Errno 104] Connection reset by peer
[ERROR] |
[ERROR] | Failed to perform action: Check connections
Cause: Error while checking connection settings: 'Failed to connect to the source server 'Source' (10.52.44.249) by SSH: Error reading SSH protocol banner[Errno 104] Connection reset by peer'
If the service is running on the corresponding server, but the report still contains an error, you can check a few things as well:
The restoration process consists of the following parts:
Common problems that might occur during the restoration of subscriptions and customer accounts are as follows:
The migration tool will do an automatic IP mapping by default. If there are not enough IP addresses of corresponding type, the default shared IP addresses will be used for mapping. If manual mapping is used, only minimal checks will be carried out (such as that IP address from map file is present, or IPv4 address is not mapped to IPv6 and vice versa). If mapping was done incorrectly, the creation of subscriptions may fail with errors. Therefore, manual mapping should be done with extra attention.
There might be various causes for such an issue. If subscription creation fails, the migration tool tries to repeat the operation several times in order to exclude failures caused by interruptions and timeouts in Plesk API or hosting service unavailability. In some rare cases, subscription might be created even if Plesk returns an error. If this happens, the migration tool tries to repeat the operation and receives the “subscription already exist” error. In this case, we recommended that you investigate the migration tool's debugging log and find the very first attempt of creation in order to find out the root cause.
The restoration of hosting features usually fails due to license limitations, service plan settings, or absence of the corresponding feature on the target server. Hosting features can be limited by the Plesk license and also by some commercial managed products, such as mail servers (on Windows, there are commercial SmarterMail, MailEnable, and IceWarp), antiviruses, spam filters, mailing lists and so on. If the restored hosting feature is not installed on the target server, it could be removed from a target service plan that is used for the migrated subscriptions.
Databases dump and restoration are being made via native tools that are different for every type of database. Database dump might fail due to insufficient space in the backup storage or a database corruption. The exact reason should be checked in the corresponding database server logs. Logs are commonly stored in the following locations depending on the database type:
MySQL - /var/log/mysqld.log, /var/log/mysql/error.log, /var/log/mysql/`hostname`.err
MySQL(Windows) - %plesk_dir%\Databases\MySQL\data\<server_hostname>.err
Postgres - /var/log/postgresql
MSSQL - %plesk_dir%\Databases\MSSQL\<instance_name>\MSSQL\Log\ERRORLOG
Transfer of web content is being performed via 'rsync' on both Windows and Linux. Mail content is restored either via a native mail server utility, or via IMAP on Windows, and with the same 'rsync' utility on Linux. Usually content transfer may fail due to network issues. Please make sure that SSH connection is not limited by firewall and there are no network timeouts that might cause connection abort.
The best practice in any case is to remove the failed subscription from the target server, investigate the migration tool logs (see the migration tool logs page) to find the root cause of failure, resolve the issue that prevents successful migration, create a separate migration list with failed subscriptions (or use the one that the migration tool creates automatically if there are any failures), and transfer them anew.
If errors occur during the subscription restoration process, such subscriptions are recorded in a separate migration list file, of which the user is notified as follows:
[ERROR] | Failed to perform operation on 1 subscription(s): 'domain1.tld'
[ERROR] | 1 of 1 subscription(s) failed to migrate. All of them are listed in "
C:\ICW\home\Administrator\panel-migrator\sessions\migration-session\failed-subsc
riptions.1433993886.34".
To repeat migration for these subscriptions only, run the migration tool in the following way:
# panel-migrator transfer-accounts config.ini --migration-list-file C:\ICW\home\Administrator\panel-migrator\sessions\migration-session\failed-subscriptions.1433993886.34
Post-migration check verifies the consistency of migrated data. This includes the availability of migrated web pages, messages in mailboxes, access of FTP, database and SSH\RDP users, and consistency of migrated databases.
Post-migration check can be launched with the 'test-all' command after the migration. It will generate a hierarchical tree for all migrated objects and their aspects, like the following:
|- Reseller 'oldresunixelev'
| |
| `- Client 'custunixeleven'
| |
| `- Subscription 'custunixeleven.tld'
| |
| |- Database service 'custunixeleven.tld'
| |
| |- Apache web site 'ü-idn-frame-forwarding.pfu11'
| |
| |- Apache web site '*.custunixeleven.tld'
| |
| |- Mail domain 'ü-idn-frame-forwarding.pfu11'
| |
| |- Apache web site 'custunixeleven.tld'
| |
| |- DNS zone 'addon.custunixeleven.tld'
| |
| |- Mail domain 'custunixeleven.tld'
| |
| |- FTP service 'custunixeleven.tld'
| |
| |- Mail domain '*.custunixeleven.tld'
| |
| |- DNS zone '*.custunixeleven.tld'
| |
| |- Mail domain 'sub.custunixeleven.tld'
| |
| |- Mail domain 'addon.custunixeleven.tld'
| |
| |- Mail domain '*.addon.custunixeleven.tld'
| |
| |- DNS zone '*.addon.custunixeleven.tld'
| |
| |- DNS zone 'sub.custunixeleven.tld'
| |
| |- Apache web site 'sub.custunixeleven.tld'
| |
| |- DNS zone 'custunixeleven.tld'
| |
| |- SSH service 'custunixeleven.tld'
| |
| |- DNS zone 'ü-idn-frame-forwarding.pfu11'
| |
| |- Apache web site '*.addon.custunixeleven.tld'
| |
| `- Apache web site 'addon.custunixeleven.tld'
For each hosting object (website, mailbox, or database), the tool compares the corresponding objects on the target and source servers. If there is a difference, it will append an error to the final report, which will contain a hint on how to resolve the issue.
Common problems that post-migration check helps to reveal are as follows:
If there is an issue with one of these items, you should conduct an investigation by using the following algorithm:
Migration process can be roughly divided into the following parts:
During these two basic steps, the migration tool creates logs both on the source and target servers, which might be very useful during the troubleshooting.
Preliminary backup is being performed during the generation of a migration list with the help of so-called "agents" that are copied to source servers and create backups there.
Backup logs can be found in the corresponding locations on the source server:
On Windows:
C:\panel-migrator-transfer-agent\debug.log – Agent log
C:\PMMtemp\migrator backup\2015_06_11_10[1]\psadump.log – backup utility log
On Linux:
/tmp/agent/dump.log
Restoration logs can be found in PMM directories:
The migration tool itself writes the debugging log into the following location (relatively to the migration tool's installation directory) both on Windows and Linux: logs/panel-migrator.debug.log.
This log contains all operations that the migration tool executes and their output. If an error occurs during the migration, you can find the error text in the debugging log, and moving up through the log, find out what command\API call\SQL query caused the issue.
If the error in migration occurred during the execution of a Plesk utility, Plesk debugging log can also be used for investigation. Plesk logs are located in the following places:
Plesk errors could be resolved with debugging options (see the article at http://kb.odin.com/en/120101). For that, you need to find the exact Plesk command that was issued (in the migration debugging log), increase the Plesk log verbosity, and run the same command in the command line to receive the debugging output.
Please be aware that debugging should be disabled after troubleshooting, since it might cause the migration tool to hang.