Zimbra NG Modules/Zimbra NG Backup/zxbackup-migration: Difference between revisions

Line 162: Line 162:
*Proper Zimbra JVM memory settings (heap size and PermGen/MaxPermGen)
*Proper Zimbra JVM memory settings (heap size and PermGen/MaxPermGen)
are properly dealt with before starting the import.
are properly dealt with before starting the import.
==The situation so far==

Revision as of 20:07, 23 August 2017

ZCS 8.8 Article ZCS 8.8


  • This guide describes how to perform an Incremental Migration using ZeXtras Backup.
  • It's specifically designed for the migration of a production environment, minimizing the downtime and aiming to be transparent for the users.
  • If correctly planned and executed, your mail system won't suffer any downtime and the impact on the users will be close to zero.
  • All the CLI commands in this guide must be executed as the Zimbra user unless otherwise specified.

What will be migrated

  • Emails and Email Folders.
  • Contacts and Address Books.
  • Appointments and Calendars.
  • Tasks and Tasklists.
  • Files and Briefcases.
  • Share informations.
  • User Preferences.
  • User Settings.
  • Class of Service Settings.
  • Domain Settings.

What will NOT be migrated

  • Server settings (migrated for reference but not restored).
  • Global Settings (migrated for reference but not restored).
  • Customizations (Postfix, Jetty, etc...).
  • Items moved or deleted during the process will not be moved or deleted on the destination server.
  • Preferences (e.g. passwords) changed during the process will be reset upon each import.

Warning! The Incremental Migration is not designed to set up a server-to-server mirroring. Using multiple imports to create a mirrored copy of the source server won't create a mirrored copy at all, since no deletions are performed by the Import process.

Pre-migration checks

FAQs and Troubleshootings

Please carefully read the ZxBackup Troubleshooting and the ZxBackup FAQs pages before running an incremental migration


  • The source server: any Zimbra server can be the source of your migration, as long as the running Zimbra version is 6.0.7 or higher.
  • The destination server: any Zimbra server can be the destination of your migration, as long as the running Zimbra version is 6.0.7 or higher.

Be sure to have root access to both servers, and have a look at "ZxBackup: External Restore - Before you start" for some import performance tips.


  • On the Source server: If ZeXtras Backup is not currently enabled on the source server, make sure you have an amount of free disk space comparable to the size of the /opt/zimbra/store/ folder (the exported data is compressed through the gzip algorythm, and all zimbra items are deduplicated, usually reducing the size of exported to the 70% of the original size).
  • On the Destination server: Make sure you have an amount of free space greater than the size of the /opt/zimbra/store/ and of the "export" folders on the source server combined

Data Transfer

While you can choose to transfer the data in any other way, rsync is our method of choice as it's a good compromise between speed and convenience.

The main data transfer is executed while the source server is still active and functional. However, since the transfer is performed via network, carefully plan your transfer in advance so that you'll have transfered all of your data before migrating.

Alternative Ways to transfer your data Anything spanning from remote mount to physical move of the drive is ok as long as it suits your needs.


Set the TTL value of your MX record to 300 on your "real" DNS. This will allow a fast switch between source and destination server.

The Set-up

Step 1: Coherency checks

In order to avoid any possible data-related issue, run the following checks on the source server:

  • zmblobchk: this command checks the consistency between Zimbra's metadata and BLOBs.
  • zmdbintegrityreport: this command checks the integrity of the Zimbra's database.

Repair any error found as described in Zimbra's official documentation. Running a reindex of all mailboxes is also suggested.

Step 2: ZeXtras Suite setup

Only for servers on which ZeXtras Backup is not already initialized and running Install ZeXtras Suite on both servers:

[run this commands as Root]
wget http://www.zextras.com/download/zextras_suite-latest.tgz
tar zxvf zextras_suite-latest.tgz
cd zextras_suite-[version]
./install.sh all

Disable the Real Time Scanner on both servers:

zxsuite backup setProperty ZxBackup_RealTimeScanner false

A dedicated device for the data export is strongly recommended in order to improve the export performance and to lower the impact on the performances of the running system.

Such device must be mounted on the /opt/zimbra/backup/ path and the Zimbra user must have r/w permissions on it

Step 3: Data Export (SmartScan)

Run a SmartScan on the source server:

zxsuite backup doSmartScan

All your data will be exported to the default backup path (/opt/zimbra/backup/zextras/).

Pro-Tip: Single Domains Export You can also choose to only migrate one or more domains instead of all of them. To do so, run the following command instead of the SmartScan:

zxsuite backup doExport /path/to/export/folder/ domains yourdomain.com,yourdomain2.com[..]

Mind that if you start with the "SmartScan" method you'll have to carry on the migration with such method, and if you start with the "Single Domains" method you'll have to carry on the migration with this one. The two methods cannot be mixed.

Data export (SmartScan) via the ZeXtras Administration Zimlet You can also choose to export your data using the ZeXtras Administration Zimlet following [THIS guide][1].

Step 4: Data Synchronization

Warning! When you move the exported data to the destination server make sure that the destination folder is not ZxBackup's backup path on the destination server in order to avoid any nuisiances if you already use ZxBackup or plan to do so on the destination server.

(You can skip this step if you choose to transfer your data by other means than rsync.)

Using rsync, copy the data contained in the /opt/zimbra/backup/zextras/ on a directory in the destination server (make sure the Zimbra user has r/w permissions on such folder). Use a terminal multiplexer like screen or tmux, this process command might need A LOT of time depending on network speed and amount of data involved.

[run this command as Root]
rsync -avH /opt/zimbra/backup/zextras/ root@desinationserver:/path/for/the/data/

Alternate synchronization method

While the suggested method is great for high-bandwidth situations, the first synchronization can involve a lot of data. If you feel that the rsync method is too slow, you might consider a physical move of the device (or the proper disk file if running on a virtual environment).

After moving the disk, you can remotely mount it back to the source server (e.g. via SSHFS), as the additional synchronizations needed for the migration will involve much less data. In this case, be sure to remount the device on the source server as /opt/zimbra/backup/zextras/ with all due permissions.

Step 5: First import

Import all exported data to the destination server:

zxsuite backup doExternalRestore /path/for/the/data/

Now sit back and relax while ZeXtras Suite imports your data on the destination server.

Warning: Do not edit nor delete the Map Files after this point. Doing so will cause item duplication issues and will almost surely disrupt your migration process.

First import via the ZeXtras Administration Zimlet You can also choose to import your data using the ZeXtras Administration Zimlet following THIS guide. While importing via the ZeXtras Administration Zimlet be sure to remove all System Accounts (like GalSync, Ham, Spam, Quarantine etc.) from the imported account list.

Step 5 (alternate): First import for large migrations [ADVANCED users only]

If you are to migrate a very large infrastructure where an export/import lasts for hours or even days, there is an alternative way to handle the migration from this point forward.

Instead of importing all of your data to the destination server, you can run a "Provisioning Only" import that will only create Domains, Classes of Service and Accounts on the destination server, skipping all mailbox contents.

zxsuite backup doExternalRestore /path/for/the/data/ provisioning_only TRUE

After doing this, switch the mailflow to the new server and, when the switch is completed, start the "real" import.

zxsuite backup doExternalRestore /path/for/the/data/

This way, your users will now connect to the new server where new emails will be delivered while old emails are being restored.

This approach has it's pros and cons, namely: Pros

  • Since items are only imported once and never modified or deleted afterwards, using this method will result in less discrepancies than the "standard" incremental migration.
  • This is the option that has less impact on the source server (e.g. good if you are in a hurry to decommission it).


  • Depending on the timing of the operation, this method has a higher impact on your users due to the fact that items are restored WHILE they work on their mailbox.
  • Since the import is done on a running system, you might notice some slowdowns.

Warning! "Be aware that THERE IS NO WAY BACK! Once the firewall and DNS settings are changed, going back to the old server is pretty much impossible without extensive handiwork. Thus, make sure that things like:

  • Disk Sizing
  • Filesystem health
  • Zimbra BLOB and DB health
  • Proper Zimbra JVM memory settings (heap size and PermGen/MaxPermGen)

are properly dealt with before starting the import.

The situation so far

Jump to: navigation, search