ZCP 7.

1 (build 48315)
Zarafa Collaboration
Platform
The Migration Manual
Zarafa Collaboration Platform

ZCP 7.1 (build 48315) Zarafa Collaboration Platform

The Migration Manual
Edition 2.0

Copyright © 2015 Zarafa BV.

The text of and illustrations in this document are licensed by Zarafa BV under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available
4
at the creativecommons.org website . In accordance with CC-BY-SA, if you distribute this document or
an adaptation of it, you must provide the URL for the original version.

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other
countries.

Red Hat®, Red Hat Enterprise Linux®, Fedora® and RHCE® are trademarks of Red Hat, Inc.,
registered in the United States and other countries.

Ubuntu® and Canonical® are registered trademarks of Canonical Ltd.

Debian® is a registered trademark of Software in the Public Interest, Inc.

SUSE® and eDirectory® are registered trademarks of Novell, Inc.

Microsoft® Windows®, Microsoft Office Outlook®, Microsoft Exchange® and Microsoft Active
Directory® are registered trademarks of Microsoft Corporation in the United States and/or other
countries.

The Trademark BlackBerry® is owned by BlackBerry and is registered in the United States and may
be pending or registered in other countries. Zarafa BV is not endorsed, sponsored, affiliated with or
otherwise authorized by BlackBerry.

All trademarks are the property of their respective owners.

Disclaimer: Although all documentation is written and compiled with care, Zarafa is not responsible for
direct actions or consequences derived from using this documentation, including unclear instructions
or missing information not contained in these documents.

The Zarafa Collaboration Platform (ZCP) combines the usability of Outlook with the stability and
flexibility of a Linux server. It features a rich web-interface, the Zarafa WebAccess, and provides
brilliant integration options with all sorts of clients including all most popular mobile platforms.
1
Most components of ZCP are open source, licensed under the AGPLv3 , can therefore be
2
downloaded freely as ZCP's Community Edition .

Several closed source components exist, most notably:

4
http://creativecommons.org/licenses/by-sa/3.0/
1
http://www.gnu.org/licenses/agpl-3.0.html
2
http://www.zarafa.com/content/community
• the Zarafa Windows Client providing Outlook integration,

• the Zarafa BES Integration providing Blackberry Enterprise Server connectivity,

• the Zarafa ADS Plugin providing Active Directory integration, and

• the Zarafa Backup Tools.

These components, together with several advanced features for large setups and hosters, are only
3
available in combination with a support contract as part of ZCP's Commercial Editions .

Alternatively there is a wide selection of hosted ZCP offerings available.

3
http://www.zarafa.com/content/editions
1. Introduction 1
1.1. Zarafa Migration Tool .................................................................................................... 1
1.1.1. Exchange to Zarafa Migration ............................................................................ 1
1.1.2. PST to Zarafa Migration ..................................................................................... 1
1.1.3. Zarafa to PST Migration ..................................................................................... 1
1.1.4. Scalix to Zarafa Migration Tool ........................................................................... 1
1.2. Scope of this document ................................................................................................ 1
2. Usage 3
2.1. Starting the Migration Tool ............................................................................................ 3
2.2. Select Type Of Migration .............................................................................................. 3
2.3. Logging, Data Filter, etc. .............................................................................................. 3
2.4. Source and destination configuration ............................................................................. 4
2.4.1. Exchange To Zarafa Migration ............................................................................ 4
2.4.2. PST To Zarafa Migration .................................................................................... 4
2.4.3. Zarafa To PST Migration .................................................................................... 5
2.5. Account User Mapping ................................................................................................. 5
2.6. Migration Progress ....................................................................................................... 7
2.7. Report ......................................................................................................................... 7
2.8. Trouble Shooting .......................................................................................................... 7
2.9. Migrating Public Folders ............................................................................................... 7
3. Scalix Migration 9
3.1. Prerequisites ................................................................................................................ 9
3.2. Setting up the coupling CSV ....................................................................................... 10
3.3. Invoking the migrator .................................................................................................. 10
3.4. Known issues ............................................................................................................. 10
4. Known Issues 11
5. Appendix A; Configuration options command line tool 13
5.1. Config File ................................................................................................................. 13
5.2. Command line parameters .......................................................................................... 14

v
vi
 Chapter 1.

Introduction
Currently migrating for MS Exchange to the Zarafa Collaboration Platform is performed by importing
.pst files to the Zarafa Server. It is also possible to export .pst files from Zarafa.

1.1. Zarafa Migration Tool

The Zarafa Migration Tool performs a migration by opening each user’s store in the data source
(exchange.pst), travesing over the MAPI folder structure migrating each message and folder. This
means that all data from the data source will be migrated, including mail, attachments, appointments,
tasks, contacts etc. The Zarafa Migration Tool will also check if the message/folder already exists
at the destination (a Zarafa Server or a .pst file) to avoid duplicates. The tool will not create users
on the Zarafa Collaboration Platform, it assumes that the users to which the administrator wants to
migrate data to already exist on the Zarafa Server.

1.1.1. Exchange to Zarafa Migration

The Zarafa Migration Tool can migrate multiple stores from one MS Exchange server to one Zarafa
Server.

1.1.2. PST to Zarafa Migration

The Zarafa Migration Tool can import multiple .pst files to the stores of the users on the Zarafa
Server. There are many ways to retrieve the .pst files with the users store. You might work with .pst
files stored on clients separately, centrally stored on a server or use a groupware solution.

Microsoft has made a very useful tool, called “ExMerge”. With this .pst files can be imported into an
Exchange mail server, and more importantly, allows one to export an Exchange mail server to .pst
1
files. See the Knowledge Base article for the installation and configuration of Exmerge.

The Zarafa Migration Tool is then used in the next stage to import these .pst files into the Zarafa
Server.

1.1.3. Zarafa to PST Migration

The Zarafa Migration Tool can export pst files from Zarafa server user stores. The tool will create one
pst per user store.

1.1.4. Scalix to Zarafa Migration Tool

The Zarafa Migration Tool can migrate multiple stores from one Scalix server to one Zarafa Server.
However, this can only be done with the zarafamigrationCmdLine.exe tool. See Chapter 3,
Scalix Migration for more information on migrating from Scalix to Zarafa.

1.2. Scope of this document

This manual is intended for users of the Zarafa Migration Tool. This document will explain how to
conduct the different migrations available.

1
http://support.microsoft.com/kb/327304

1
2
 Chapter 2.

Usage
Before installing the Zarafa Migration Tool make sure the Zarafa Server is installed and configured
on the Linux server. The Exchange server or pst files used as data-source are available. The Zarafa
Migration tool must be installed on a Windows system without any components of MS Exchange.
Before installing the Migration tool make sure you have installed Outlook 2003/2007, the Zarafa client
with the same version as the Zarafa server and .NET framework 3.x.

Important

Before starting the Migration Tool, make shure all the .NET packages are updated to the
most recent released version. It is known at least the following issues should be adressed: -
KB2418240 - KB983582 - KB983582 - KB982865 - KB951847

When closing the migration before completing the installation it is possible to save the configuration.
This option is available when closing the migration tool in a dialog. When restarting the migration tool
the saved values are picked up so the migration an continue.

The tool can also be run from the command line by issuing the command
zarafamigrationCmdLine.exe from the migration program folder. If run with --help it will show
the available options. If a config.cfg file is available in the same directory or specified by the -f
command line option the config file will be used. See the Chapter 5, Appendix A; Configuration options
command line tool for a peek at config file format.

2.1. Starting the Migration Tool

To install the Migration tool run zarafamigrationtool.msi and follow the necessary steps. Then
start the migration tool itself: Start > Programs > Zarafa Migration Tool.

2.2. Select Type Of Migration

In the welcome screen click link corresponding to the type of migration that is going to be conducted.
The first page will be about setting Logging and Filters amoung others. The following two pages will
differ depending on the chosen migration type (see next three chapters). After which the rest of the
input pages are common to all migration types.

Figure 2.1. Welcome

2.3. Logging, Data Filter, etc.

At the first page it is possible to set a number of parameters controlling the migration.

Figure 2.2. Logging

It is possible to specify another log file name and location then the default one
(ZarafaMigration.log in the migration program directory).

• Click browse and select file.

It is possible to select another logging level. 0 means no logging and 6 means debug logging, which
is very verbose. By default info logging level is used (3). Change values in the drop down menu.

3
Chapter 2. Usage

• If migration of junk folder is wanted tick the check box Migrate Junk Folder.

• If migration of deleted items is wanted tick the check box Migrate Deleted Items Folder.

• If filtering of old items is wanted, enter the date for which to filter the stores with.

• If use date filter is checked, items older then the specified date will be excluded in the migration.

2.4. Source and destination configuration

2.4.1. Exchange To Zarafa Migration

Figure 2.3. ExchangeServer

In the Exchange Server Page enter either a pre created Outlook admin profile or enter the Exchange
server name and admin user and password. By selecting either server address or profile radio-
buttons. Click next.

Figure 2.4. ExchangeOutlookProfile

A connection test is performed, of which the progress is shown in status field at the bottom left. When
the test is successful, the next page will be shown.

On the Zarafa Server Page the address of Zarafa Server instance should be provided, by default port
236 will be added. If another port is used this should be specified with a colon after the host name.
Consequtively the admin users credentials should be supplied.

Figure 2.5. Zarafa

Click next.

Again a connection test is performed, of which the progress is shown in status field at the bottom left.
When the test is successful, the next page will be shown.

2.4.2. PST To Zarafa Migration

In the PST File Configuration Page click the Browse button and locate the location of where the .pst
files are stored.

If none is chosen it defaults to the migrator program folder.

Figure 2.6. PSTRead

In case unicode files are provided the migration tool should be told so by checking the appropriate
check box. This supports large files, up to 20GB. This option can only be used if using Outlook 2003
and higher. If not ticked a maximum size of 2GB will be used.

Click Next

4
 Zarafa To PST Migration

On the Zarafa Server Page the address of Zarafa Server instance should be provided, by default port
236 will be added. If another port is used this should be specified with a colon after the host name.

See Figure 2.5, “Zarafa”

Click next.

A connection test is performed, of which the progress is shown in status field at the bottom left. When
the test is successful, the next page will be shown.

2.4.3. Zarafa To PST Migration

See Figure 2.5, “Zarafa”

Click next.

A connection test is performed, of which the progress is shown in status field at the bottom left. When
the test is successful, the next page will be shown.

In the PST File Configuration Page click the Browse button and locate the location of where the .pst
files are to be stored. If none is chosen the default location is the Migration Tool’s program folder.

Figure 2.7. Zarafa

See Figure 2.6, “PSTRead”

If Unicode file format is to be used tick the check box. This support large files, 20GB. This option can
only be used if using Outlook 2003 and higher. If not ticked a maximum size 2GB will be used. Click
Next

2.5. Account User Mapping

If no .csv file is supplied a match on all names in data-source and data-destination will be done.

Figure 2.8. Mapping

If the .csv coupling is used, a comma separated value file needs to be specified. The .csv file
should contain at least 2 columns: destination-user and filename. It is important that these 2 columns
are defined with a column head on the first line of the .csv file. The column heads indicate in what
order the data is presented in the rest of the file. Column heads are case sensitive. Any extra columns
will be ignored. Do not include any spaces between column heads. Template files for each migration
file can be found in migration tool program directory.

To find out the correct user store string for the user to be migrated, log into the MS Exchange server
using an admin account. Four alternatives exist to find the info:

1. Using CSVDE:

This is the easiest method, it allows to completely export all users into a CSV for use with the
Zarafa migrator. Open a command prompt and run the following command:

csvde -f C:\zarafa-migrator.csv -d "OU=ExchangeUsers,DC=myserver,DC=local" -r

objectCategory=user -l "legacyExchangeDN,sAMAccountname"

Example export:

5
Chapter 2. Usage

DN,sAMAccountName,legacyExchangeDN
"CN=John Doe,OU=ExchangeUsers,DC=myserver,DC=local",johndoe,/o=TESTER/ou=first
administrative group/cn=Recipients/cn=johndoe

Now simply open it up in an editor and remove the DN column. After this change the columns
to this order: legacyExchangeDN,sAMAccountname. This way it can be used with the migrator
tool. Switch explanation: -f path to save the csv, -d folder from which to export users, -r object
type, -l properties to export. If desired switch sAMAccountname for mail to use the email as the
username for the users.

2. Using Adsiedit:

Open Adsiedit on the Windows server, right click on ADSI Edit and choose Connect to…
now choose Default naming context in the second drop down box and click Ok. Once
connected expand the Default naming context container until finding the container in which
the users reside. Right click on the user and choose Properties, scroll through the list until
legacyExchangeDN is shown. Double click the entry and copy the value. This value can then be
used in the CSV file.

3. Using Outlook:

Open the address book and find the user to be migrated. In the main address book view you find
the store address in the field E-mail Address. Replace the line in the template file /o=TESTER/
ou=first administrative group/cn=Recipients/cn=exchangeUser1 with the
information found for the user.

4. Using Outlook Spy (Outlook add-in):

Click IAddrBook/GetDefaultDir/GetContentsTable, then double-click on the user find

the property “+PR_EMAIL_ADDRESS+”, double-click it and copy the value. Users in the same
exchange server are usually prefixed with the same default, so usually it is enough to find it out
only once and then only change the last cn part.

Exchange to Zarafa

datasourceuser,destinationuser
/o=TESTER/ou=first administrative group/cn=Recipients/cn=exchangeUser1,zarafaDestinationUser1
/o=TESTER/ou=first administrative group/cn=Recipients/cn=exchangeUser2,zarafaDestinationUser2

Exchange to PST

datasourceuser,destinationuser
/o=TESTER/ou=first administrative group/cn=Recipients/
cn=exchangeUser1,pstDestinationUser1.pst
/o=TESTER/ou=first administrative group/cn=Recipients/
cn=exchangeUser2,pstDestinationUser1.pst

PST to Zarafa

datasourceuser,destinationuser
ZarafaDataSourceUser1.pst,pstDestinationUser1
ZarafaDataSourceUser2.pst,pstDestinationUser1

6
 Migration Progress

When finished click Next.

The mapping will be initialized and if successful the next page will be shown.

2.6. Migration Progress

Click start migration, the progress will be indicated by the three progress bars. Store, folder and
message level.

Figure 2.9. Progress

If starting migration fails it will tell in the status below Store progress bar. Check log file for hints on
configuration problems, increase log level and retry to get more interesting details in log file. When
finished it will be shown in the status below the progress bars and the Next button will be activated.

Click Next

2.7. Report
Here it is possible to view the generated html report (it is stored in the migrator program directory).

Figure 2.10. Result

It is also possible to open it in the default web-browser for better overview.

2.8. Trouble Shooting

The connection tests done after clicking next from the server configuration pages will provide an
error code if failed in the bottom left status field. The field which most probably caused the error will
be marked red. The error code is a MAPI error code and can be found by searching for the code on
MSDN. It is also possible in first page to increase the log level and rerun connection test to get more
information about the problem in the log file.

2.9. Migrating Public Folders

The migration tool does not support migration of public folders. It can instead easaly be done by
exporting the public folders to PST using MS Outlook. File→Import/Export, choose Export to file, PST
file format and select the public folder to be exported. Import the exported PST file using an admin
account in Outlook. File→Import/Export, choose Import from another program or file, PST file and
browse to the previously expoted file.

7
8
 Chapter 3.

Scalix Migration
The Zarafa Migration Tool can migrate stores of premium Scalix users to Zarafa. It’s important to note
that it can not migrate the stores of non-premium Scalix users because Scalix doesn’t allow MAPI
access for those users.

3.1. Prerequisites
In order to migrate stores from a Scalix system to a Zarafa system, both the Zarafa client and the
Scalix client need to be installed on the system on which the migration tool will be executed.

The scalix version must be either 11.3 or 11.4, the 11.4 version is strongly advised. Earlier and later
versions contain compatibility issues and cannot be supported.

Then an admin user must be created that has the special privilege "Mboxadmin" assigned to it.

Once this is done, a special Scalix admin profile needs to be created for the migrator to use so stores
of all the required users can be openend. This is done by creating a special install.ini file and passing
it to sxpro.exe (this tool comes with the Scalix client connector package and can be found in the Scalix
installation directory).

The install.ini file must look like this:

[Install Flags]
InstallLogfileUpLoadLocation=c:\\log.txt
InstallWithServerStore=1
InstallAllowSavedPassword=1
InstallAskForPSTPassword=0
InstallTrySSOFIRST=0
InstallExternalPST=0
InstallSetDefaultProfile=0
InstallLogFileLocation=c:\\temp.txt
InstallMigrateDefaultProfile=0
InstallEnableSmartCache=0
InstallUseSSL=0
InstallPassword=SU=sxadmin;PASS=scalix
InstallMailServerName=scalix.mailserver.com
InstallUsername=sxuser
InstallDefaultProfileName=migrator2

Some variables in this file must be changed:

• sxadmin in the InstallPassword variable must be replaced with the admin user for the Scalix
system. scalix in the same variable must be replaced with the actual password.

• scalix.mailserver.com in the InstallMailServerName varibale must be replaced with the name of

the actual Scalix system.

Some varibales in this file may be changes:

• sxuser in the InstallUsername varibale may be changed in an actual existing user. However, the
migrator will update the profile with the required user for each store to migrate, overwriting this
setting.

• migrator2 in the InstallDefaultProfileName may be replaced with another profile name. This profile
name is used when invoking the migrator when specifying which profile to use.

To create the actual Scalix profile, invoke the sxpro.exe tool and pass the directory in which
install.ini resides:

9
Chapter 3. Scalix Migration

sxpro.exe -i <directory_containing_install.ini>

3.2. Setting up the coupling CSV

The coupling CSV file for matching Scalix users to Zarafa users looks like this:

datasourceuser,destinationuser
scalixUser1,zarafaDestinationUser1
scalixUser2,zarafaDestinationUser2

3.3. Invoking the migrator

To start the migration execute the following command with the proper arguments replaced with the
correct values:

• -E: The scalix profile created in Section 3.1, “Prerequisites”.

• -a: The Zarafa admin user.

• -p: The passwors for the Zarafa admin user.

• -h: The address or name of the Zarafa server.

zarafamigrationcmdline.exe -D Scalix -E migrator2 -d Zarafa -a admin -p pass -h

zarafa.mailserver.com -c CSV -C m:\coupling.csv

3.4. Known issues

The following issues are only related to Scalix migration.

• Sometimes the migrator seems to get stuck during initialiazation. Cancelling the process with Ctrl-C
and restarting it resolves the issue.

• It has been reported that the migrator seems to get stuck in the middle of the migration process.
This issue has not been verified by Zarafa, but if it occurs, the migrator can be interrupted with Ctrl-
C. Restarting the migrator will cause it to continue where it left off.

10
 Chapter 4.

Known Issues
The migration of attachments of embedded messages from Exchange to Zarafa will fail with clients
prior to 6.40.6. The attachments will be visible in the migrated message, but an error will occur when
attempting to open it.

Ticket: http://trac.zarafa.com/ticket/7059

11
12
 Chapter 5.

Appendix A; Configuration options

command line tool
5.1. Config File

Use with UI

Rename this file to config.cfg and place in installation

directory and click tick box read from config.cfg
on first wizard page.

Use with CmdClient

Either rename to config.cfg and place in

installation directory and run CmdClient
withouth arguments.
Or run the CmdClient with option
'-f config_template.cfg'

config_template.cfg available in migrator installation directory:

##################################################################################
# MIGRATOR SETTINGS Template File
#
# Use with UI: Rename this file to config.cfg and place in installation
# directory and click tick box read from config.cfg
# on first wizard page.
# Use with CmdClient: Either rename to config.cfg and place in
# installation directory and run CmdClient
# withouth arguments.
# Or run the CmdClient with option
# '-f config_template.cfg'
#
##################################################################################

# Source selection. Exchange, Zarafa, PST and Scalix are supported

datasource_type = Exchange
#datasource_type = Zarafa
#datasource_type = PST
#datasource_type = Scalix

# Exchange source settings

exchange_source_host = datasource.host.com
exchange_source_profile = adminMailProfile
#exchange_source_admin_user = adminUser
#exchange_source_admin_password = adminUserPassword

# Zarafa source settings

#zarafa_source_host = datasource.host.com
#zarafa_source_profile = adminMailProfile
#zarafa_source_admin_user = adminUser
#zarafa_source_admin_password = adminUserPassword

# PST source settings

#pst_source_path = c:\tmp\pst
#pst_source_format = UNICODE

13
Chapter 5. Appendix A; Configuration options command line tool

# Scalix source settings

#scalix_source_profile = adminMailProfile

# Destination selection. Zarafa and PST are supported

destination_type = Zarafa
#destination_type = PST

# Zarafa destination settings

zarafa_destination_host = destination.mailserver.com
zarafa_destination_profile = adminMailProfile
#zarafa_destination_admin_user = adminUser
#zarafa_destination_admin_password = adminUserPassword

# PST derstination settings

#pst_destination_path = c:\tmp\pst
#pst_destination_format = UNICODE

# Coupling settings
coupling_type = CSV
coupling_csv_file_path = mapping_exch_to_zarafa_template.csv
#coupling_csv_delimeter = ,

# Advanced options
migrate_junk_folder = FALSE
migrate_delete_folder = FALSE

# Log options
logging_enable = TRUE
logging_level = 3
logging_file_path = ZarafaMigrator.log

# Data filte used to filter items older than data set

# YYYY/MM/DD-HH:MM:SS
#date_filter = 2008/02/22-21:23:43

5.2. Command line parameters

zarafamigrationCmdLine.exe --help

Usage: -f config file -w [true|false] -d [Zarafa|PST] -D [Exchange|Zarafa|PST|Scalix]

-p 'path' -c [PST|CSV] -C 'path' -s ',' -E exchange_profile -H exchange_host
-A exchange_admin -P exchange_pass -h zarafa_host:port -a zarafa_admin -p zarafa_pass
--log 'path'

ConfigFile:
-f [config.cfg] Only file name, i.e config.cfg, using exectution directory or full path i.e
c:\tmp\config.cfg
WriteConfigToFile -w [false] Write configuration arguments to configuraton file.
DataSource:
-D [Exchange]" << "\t" << "Type of data source, only Exchange, Zarafa, PST and Scalix are
supported. [Exchange|Zarafa|PST|Scalix]" << endl;
-E Source profile (overrules -H and -A options)
-H Source server address, e.g. localhost, 10.0.0.205
-A Source server administrator username.
-P Source server administrator password.

DataDestination:

14
 Command line parameters

-d [Zarafa] Type of data destination, only Zarafa and PST are supported.[Zarafa|PST]
-h Destination server address, e.g. localhost:236, default port is 236.
-a Destination server administrator username.
-p Destination server administrator password.

-F 'path' Optional: Path to the PST folder, default is current folder. Used when PST
type is chosen as DataSource or DataDestination

Coupling:
-c [CSV] Type of coupling. [PST|CSV]
-C 'CSV path' CSV only: Path to the CSV file.
-s ',' Optional: CSV: seperator character in csv file, default is ','.

Date-Time filter:
-t YYYY/MM/DD-HH:MM:SS Date-time filter automatically excludes messages from being
migrated that are older than the specified date.
-o Outlook PST file format [ANSI] The format of the PST file, only 2003 and later
supports unicode. [ANSI|unicode].
-l Log Level[3] 0- None, 1- Fatal, 2- Error, 3- Warning, 4- Info, 5- Any, 6- Debug [0-6].

--log 'path' Enable logging to file.

--help show this help text.
-V Print version info.

15
16