Upgrading/Migrating Zarafa ZCP from ClearOS 6 to ClearOS 7

This howto will guide you through the steps required to migrate a Zarafa Collaboration Platform (ZCP) running on any version of ClearOS 6.x to any version running ClearOS 7.x.

Getting Started

As with any upgrade/migration, we recommend you do a full backup of configuration settings and data in the event a 'roll-back' is required.

This guide assumes that your are upgrading your hardware and have both systems running simultaneously to perform the migration. If you are performing an upgrade from ClearOS 6 to ClearOS 7 on the same hardware, you can still use the guide below, however, you will have additional downtime while you're re-installing ClearOS 7 and performing the initial configuration.

Inline upgrades - upgrading your OS without re-installing from scratch - are not supported between ClearOS 6 and ClearOS 7. A re-install of the OS is necessary, which means any data contained on the same block device which is the target of the OS installation will be deleted!

Minimizing Downtime

Mail for even a few users can contain large data-sets (both file and database). In order to minimize actual downtime of the server, it is recommended to create snapshots of data while in production and copy to the new target server (running ClearOS 7). This data can then be efficiently transferred using the rsync utility at the final stage to minimize downtime.

Preparing the ClearOS 6 Production Server

With the production mail server still running, preform a database dump (snapshot) of the Zarafa database.

First, obtain the System MySQL password by running the following command:

cat /var/clearos/system_database/zarafa

This command will yield something similar to:

password = IClPN9HNmJr4RUqsEKW6WvkdOtU=

Use this password on the server to perform a MySQL database dump of the Zarafa database:

/usr/clearos/sandbox/usr/bin/mysqldump -uzarafa zarafa -pIClPN9HNmJr4RUqsEKW6WvkdOtU= > /tmp/zarafa_on_6.dmp

In the above command, we have dumped the contents of the Zarafa database to a file located/named /tmp/zarafa_on_6.dmp

Now, install the rsync tool which will be used to efficiently migrate the dataset.

yum -y --enablerepo=clearos-centos install rsync

Preparing the ClearOS 7 Target server

Prepare your ClearOS 7 server as you normally would…things that need to get done post-install are:

  • First boot wizard, including setting up networking and system registration
  • Installing Zarafa from the Marketplace
  • Initializing the users directory
  • Creating user accounts (you can use the Account Import app, if desired)
  • Configuring the mail server

Essentially, take all necessary steps to get a working mail server up and running, even though no mail will be going to the new server yet.

Next, we will need to install rsync on the ClearOS 7 target server as well.

yum -y --enablerepo=clearos-centos install rsync

Time to do an initial sync of the files/folders from the production server 'snapshots' we took earlier. This data will be incomplete (eg. new mail etc.), however, if we sync against these files when we are ready, we can dramatically reduce the downtime of the mail service, especially with a large number of users.

Let's begin a sync of the database dump file first.

rsync -avz -e ssh root@ /tmp

Enter the root password when prompted of the ClearOS 6 server. The above example assumes the ClearOS 6 and 7 server are on the same subnet (eg. able to connect to each other) and that the ClearOS 6 server is at Change the IP to reflect your network configuration.

Once the sync is complete, we have a complete copy of the database to re-sync to when the time comes in our /tmp directory on ClearOS 7.

Next, we need the attachments folder…similar syntax, but this time, no need to copy to the /tmp directory…we can put the files in the working directories.

Attachments in ClearOS 6 were stored in folders directly in /var/lib/zarafa/ whereas in ClearOS 7, the default is /var/lib/zarafa/attachments/. Note how the sample command below takes this into account.
rsync -avz -e ssh root@* /var/lib/zarafa/attachments/
rm -rf /var/lib/zarafa/attachments/attachments
rm -rf /var/lib/zarafa/attachments/index

Interim Testing

At this stage, we can (and probably should) do some testing with the data that we have. With this 'practice run', we will hopefully avoid finding any unknowns/hiccups along the way once we are on the final migration step.

The next few steps are DONE ON THE CLEAROS 7 target mail server. If you run these commands mistakenly on the ClearOS 6 production server, you will have a bad day.

Import the Database

On the ClearOS 7 server, import the database. Grab the System Maria DB database password:

cat /var/clearos/system_database/zarafa

And import the database:

/usr/clearos/sandbox/usr/bin/mysql -uzarafa -pxxxxyyyy zarafa < /tmp/zarafa_on_6.dmp

Where xxxxyyyy is the password you obtained in the previous step.

Store Assignments

You may find that Zarafa is unable to definitively map a store (essentially, a mail folder) to a user. To see if this is the case, run:

zarafa-admin --list-orphans

You may get output similar to this:

Stores without users:
	Store guid				Guessed username	Last login		Store size	Store type	
	4E9C3929EB574ADEB4E5384BC1E3E31D	user1   		04/01/16 11:15:18 AM	0.05 MB		private	
	C184683B55C04BC1935F7BC418FEBF80	user2			04/01/16 11:15:02 AM	0.05 MB		private	

If you do have stores that are not associated to the guessed user, you can correct the situation with the following syntax:

zarafa-admin --hook-store 4E9C3929EB574ADEB4E5384BC1E3E31D -u user1
zarafa-admin --hook-store C184683B55C04BC1935F7BC418FEBF80 -u user2


Once all stores are assigned, run the upgrade script to restart services:


Testing the Accounts

You should now be able to login as a user into Zarafa's Webapp and view mail, calendar events etc. as a snapshot in time when it was taken from the ClearOS 6 server. On the new (ClearOS 7) server, go to Zarafa's Webapp and login as a user…As a reminder, the URL will be something like: 

Where is the IP of your ClearOS 7 server.

Final Migration

Once you are comfortable with the overall migration and all users have checked their accounts for correct behaviour (albeit, with an old mail store that doesn't change), you are ready to perform the final syncs and import and switch mail over to the new server.

Essentially, we are going to repeat the steps of:

  • Database export (ClearOS 6)
  • Sync data
  • Data import (ClearOS 7)

However, this time, we will be stopping the Postfix MTA and Zarafa Gateway so that no new messages can come into the server or be sent from users. The act of rsyncing the data from our relatively recent dumps ensures this procedure will be done as fast as possible.

Shutdown Essential Services

On the ClearOS 6 server, stop essential services:

service postfix stop
service zarafa-server stop
service zarafa-gateway stop

You could also close port 25 (or disable redirect to ClearOS 6 server if ClearOS is not your gateway).

Perform Final MySQL Database Dump

On the ClearOS 6 server:

cat /var/clearos/system_databasee/zarafa
/usr/clearos/sandbox/usr/bin/mysqldump -uzarafa zarafa -pXXXX > /tmp/zarafa_on_6.dmp

Perform Final Rsync

On the ClearOS 7 server:

rsync -avz -e ssh root@ /tmp
rsync -avz -e ssh root@* /var/lib/zarafa/attachments/
rm -rf /var/lib/zarafa/attachments/attachments
rm -rf /var/lib/zarafa/attachments/index

Perform Final Database Import

On the ClearOS 7 server:

cat /var/clearos/system_database/zarafa

And import the database:

/usr/clearos/sandbox/usr/bin/mysql -uzarafa -pxxxxyyyy zarafa < /tmp/zarafa_on_6.dmp

Where xxxxyyyy is the password from the first 'cat' command above.

Delete the Search Cache

service zarafa-search stop
rm /var/lib/zarafa/search/* -rf

Restart Services


Check/Associate Stores

/usr/sbin/zarafa-admin --list-orphans
zarafa-admin --hook-store guid -u user

If you have a lot of stores that need to be associated, and if you are familiar with the 'vi' editor, you can save some time:

/usr/sbin/zarafa-admin –list-orphans > /tmp/orphaned.txt

Edit that file and remove the headers…then run the following commands:

:%s/^/zarafa-admin --hook-store /g
:%s/\s\s\s\s/ -u /

Copy this new file and paste it to your shell to quickly associate all accounts.

Place ClearOS 7 in Production

This step depends on your network topology. If the old ClearOS 6 server is still your active gateway, you would forward port 25 (remove incoming/allow port 25/SMTP) to the LAN IP of the ClearOS 7 server.

An alternative scenarios might to replace your ClearOS 6 gateway/server with the new ClearOS 7 box. In that case, physically changing locations and/or cables and making the ClearOS your active gateway and opening port 25/SMTP (in addition to additional ports like 443/HTTPS and 993/IMAPS) would be the course of action.

Since the Postfix server on ClearOS 7 was running from the start, it should begin to automatically receive/deliver mail on your new server.

Zarafa Small Business Licensing

If you are running Zarafa Small Business Server, your serial number that you used for your ClearOS 6 (Zarafa 7.0 or 7.1) will no longer work on ClearOS 7 which runs Zarafa 7.2.

Prior to starting your upgrade/migration, please submit a support ticket to ClearCenter support requesting your Zarafa 7.2 serial. Please provide your Zarafa 7.0/7.1 serial from your ClearOS 6 server so that we can associate/convert the correct license. search?q=clearos%2C%20clearos%20content%2C%20kb%2C%20howtos%2C%20clearos6%2C%20skunkworks%2C%20clearos7%2C%20categoryserver%2C%20maintainer_bchambers%2C%20maintainerreview_x%2C%20keywordfix&amp;btnI=lucky

content/en_us/kb_howtos_upgrading_zarafa_6_to_7.txt · Last modified: 2016/01/05 12:26 (external edit)