WebMail Pro 8 documentation

Migration from v7

Introduction

NB: To proceed with migrating to v8, make sure you have both v7 and v8 installed on the same server. If you don't have WebMail Pro 8 installed yet, check the installation instructions.

If you have v7 of the product installed on cPanel, please use the other tool: Migration from v7 - console tool

WebMail Pro 8 comes with a migration script dev/migrate.php you can use to migrate user accounts, settings, contacts, calendars, files from version 7 of the product to v8 installation.

To prevent unauthorized access to the script, so that it can only be called by the installation owner, the script can be password-protected.

What is being migrated

The migration script converts system-level data from v7 installation as well as data of user accounts:

  • Common settings
    Language, Refresh every, Date format, Time format, Enable desktop notifications, Messages per page, Contacts per page

  • Accounts
    Incoming Mail Login, Incoming Mail Password, Enable threading, Save Replies To Current Folder, System folders, etc.
  • Identities
    FriendlyName, Email, Signature
  • Social Accounts
  • Contacts
  • Groups

  • Domains (Mail Servers in v8)

Prerequisites and limitations

  1. Data migration procedure assumes that both v7 and v8 installations are on the same server. You need to have WebMail Pro 8 installed, with database set up and tables created.

  2. The script has been tested with the latest 7.7 release of the product. If you're migrating from at an older version of the product, it's recommended to upgrade first.

  3. Currently, WebMail Pro 8 supports MySQL database backend only.

Migration setup

dev/migrate.php script contains the following line:

$sP7ProductPath = "PATH_TO_YOUR_WEBMAIL_V7_INSTALLATION";

You need to replace that value with the actual path of your v7 installation.

Also, you can supply a password as $sPassword value, for example:

$sPassword = "p54321p";

Migrating all user accounts

In the simplest case, if you wish to migrate all the user accounts, you need to navigate to dev/migrate.php script in web browser:

https://yourdomain.com/webmail/dev/migrate.php

It will prepare database and filesystem structures for copying data and will proceed with migrating user accounts to your v8 installation. After copying each user, the script restarts itself so you can observe the process.

If you chose to protect your script with a password, supply the password via ?pass URL parameter, for example:

https://yourdomain.com/webmail/dev/migrate.php?pass=p54321p

Migrating selected users

If you only need to migrate specific user accounts rather than all of them, start the script with ?user_list URL parameter, like this:

https://yourdomain.com/webmail/dev/migrate.php?user_list

If you chose to protect your script with a password, supply the password via ?pass URL parameter additionally to ?user_list:

https://yourdomain.com/webmail/dev/migrate.php?user_list&pass=p54321p

The script will create user_list file under data directory, it will contain a complete list of user accounts found on v7 installation. Review the list and remove users you don't need to be migrated. After that, run the script without ?user_list parameter, to migrate those users listed in user_list file.

Troubleshooting

During the migration, script creates a number of files under data directory:

  • user_list is generated to maintain complete list of user accounts to be migrated;
  • migrated-users lists user accounts migrated successfully;
  • not-migrated-users lists accounts migration has failed for;
    (if all accounts migrated successfully, the file is not created)
  • migration contains information on the current script run iteration.

Also, if logging was enabled in admin area, log files are created under data/logs directory, their filenames start with migration-.

Restarting migration

If there was an error during the migration and you start the script again, it will proceed from the point where the error has occured. But if you wish to run the migration process from scratch, you need to perform the following steps:

  1. Delete migration file.
  2. Delete and recreate database tables used by v8 installation.
  3. Restart migration script.

Alternative migration approach

You may need to use this approach if the standard one fails for you - for example, when the script isn't able to call underlying scripts due to server configuration. And prior to running a migration script, you will need to run several scripts from command line first.

One of the cases when it's necessary is getting an error: "Error during upgrade DB process. Failed migration from a pre-2.0 database to 2.0."

Step 0.

Make sure to grab the up-to-date migration script from here, replace dev/migrate.php with it and specify v7 installation path and, optionally, a password.

Step 1.

Run the following from console:

cd /P8_INSTALLATION_DIR/vendor/sabre/dav/bin
php migrateto20.php "mysql:host=P8_DB_HOST;dbname=P8_DB_NAME" P8_DB_LOGIN P8_DB_PASSWORD

Naturally, you'll need to replace P8_INSTALLATION_DIR, P8_DB_HOST etc. with their actual values.

Step 2.

If Step 1 is done successfully, no errors reported, repeat the same steps with v2.1 of schema:

cd /P8_INSTALLATION_DIR/vendor/sabre/dav/bin
php migrateto21.php "mysql:host=P8_DB_HOST;dbname=P8_DB_NAME" P8_DB_LOGIN P8_DB_PASSWORD

If successful, upgrade to v3.0 schema:

cd /P8_INSTALLATION_DIR/vendor/sabre/dav/bin
php migrateto30.php "mysql:host=P8_DB_HOST;dbname=P8_DB_NAME" P8_DB_LOGIN P8_DB_PASSWORD

Step 3.

If all the above steps report Done, run the migration script with skip_sabredav_migrate parameter, for example:

http://your-webmail-v8-domain/dev/migrate.php?pass=12345&skip_sabredav_migrate