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.
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@192.168.1.1:/tmp/zarafa_on_6.dmp /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 192.168.1.1. 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.
rsync -avz -e ssh root@192.168.1.1:/var/lib/zarafa/* /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.
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
etc.
Once all stores are assigned, run the upgrade script to restart services:
/usr/sbin/zarafa-upgrade
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:
https://192.168.1.2/webapp
Where 192.168.1.2 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@192.168.1.1:/tmp/zarafa_on_6.dmp /tmp rsync -avz -e ssh root@192.168.1.1:/var/lib/zarafa/* /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
/usr/sbin/zarafa-upgrade
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/^\s*//g :%s/^/zarafa-admin --hook-store /g :%s/\s\s\s\s/ -u / :%s/\s\s\s\s.*//g
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.
