Migrating to MultiServer setup

From Zarafa wiki

Revision as of 11:13, 5 April 2011 by Msartor (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

When running Zarafa 6.30 or later you have the possibility of striping users over different Zarafa nodes. When starting from the scratch with a Zarafa setup you can immediately start to setup a MultiServer setup. However if you already have a single node Zarafa setup, this document will describe howto migrate your single node Zarafa setup to a MultiServer Zarafa setup.




  • This document assumes that you are already running Zarafa with the ldap user plugin. If you do not have this please, consult Zarafa's documentation on how to migrate to a setup with an ldap user backend.
  • This document assumes that you will first have upgraded to 6.40 or later. If you do not have this, please consult Zarafa's documentation on how to upgrade to 6.40.

Zarafa version 6.20 or older

If your single node Zarafa setup has users which were created with Zarafa version 6.20 or older, these users have enty-id's which need to be converted to a MultiServer compatible entry-id. The following script can be run to convert those entry id's. If your single node Zarafa setup only has users which were created with Zarafa version 6.30 or later, you do NOT need to run this script.

The script File:Db-upgrade-addressbook-entryids.tar.gz changes the entry-id's directly in the database, so it can be run directly on the MySQL server. It takes the mysql credentials from /etc/zarafa/server.cfg, so if you want to run it directly on your dedicated MySQL server make sure you have that file on the MySQL server.

Depending on the size of your database and the speed of your IO subsystem, this script will run slower or faster. In general this is a IO intensive script, there is no way to estimate how long the script will be running. E.g.: On a 500GB database which is stored over NFS on a NetApp it may take 20 to 26 hours to complete.

NOTE: NEVER run the mysql command "flush tables" while running this script (e.g. when creating a snapshot). This will hang zarafa until both the script and the "flush tables" command are finished.

You may only run this script on Zarafa database versions which are 6.30 or later.


  • 2009: Running Zarafa version 6.20
  • 2010: Running Zarafa version 6.30
  • 2011: Running Zarafa version 6.40
  • Now you want to upgrade to a MultiServer setup
  • Because this example has ran Zarafa 6.20 in the past we need to run the script in File:Db-upgrade-addressbook-entryids.tar.gz to convert entry-id's
  • After converting the enty-id's with the script, continue with this document to migrate to MultiServer

Preparing the LDAP schemas

You need to have the Zarafa schema installed from at least version 6.30 or later. This schema file will have the MultiServer settings available.

If you do not have this, you need to upgrade your LDAP with the latest Zarafa schema files, or if you are using ADS you can download the latest ADS plugin from our website.

Migrating to MultiServer

We can now start to migrate our Zarafa config to a multi server compatible setup. We need to modify some config files in order to complete this.


The first thing you need to do is create an empty MultiServer ldap config file. There are examples in /etc/zarafa:

  • When having ADS as a user backend: ldapms.active-directory.cfg
  • When having OpenLDAP as a user backend: ldapms.openldap.cfg

So copy one of those example files to ldapms.cfg to create an empty ldap multiserver config file. If we are using ADS as a user backend we would use the following command:

cp /etc/zarafa/ldapms.active-directory.cfg /etc/zarafa/ldapms.cfg

As we are assuming that you are already running Zarafa with ldap as the user backend, you can copy most of your current ldap.cfg settings to the new config file for MultiServer (ldapms.cfg).

When creating the new ldap config file pay extra attention to the Multi-server part in the config file.


In the server.cfg pay extra attention to the option: server_name = zarafa

Every Zarafa node needs to have a different server_name. This is how the cluster will distinguish the different nodes, so if you want to change that name, now is the time to do it. In this document we will use zarafa01 as an example:

server_name = zarafa01

To be sure we did not make any mistakes we set user_safe_mode to yes:

user_safe_mode = yes

Now we set the user_plugin to ldapms to enable the multiserver ldap extensions:

user_plugin = ldapms

We also need to change the user_plugin_config as we need to use our newly created ldapms.cfg:

user_plugin_config = /etc/zarafa/ldapms.cfg

We can now do a first check to see if our ldapms.cfg is correct, first we need to restart zarafa:

/etc/init.d/zarafa-server restart

Now check if all users and groups are still there:

zarafa-admin -l
zarafa-admin -L

Also check /var/log/zarafa/server.log for any warnings or errors.

Prepare LDAP objects

Now we need to prepare our ldap objects so that we can assign homeservers to our users.

Server objects

First we will create the server-objects in our ldap tree. If you do not know how to do this, consult the administrator manual on how to get this done.

This is an example of an OpenLDAP zarafa-server object:

objectclass: device (structural)
objectclass: ipHost (auxiliary)
objectclass: top (abstract)
objectclass: zarafa-server (auxiliary)
cn: zarafa01
zarafaContainsPublic: 1
zarafaFilePath: /var/run/zarafa
zarafaHttpPort: 236
zarafaSslPort: 237

In ADS you need to add a zarafa-server as a computer. Consult the administrator manual on how to do this.

Keep in mind that you set the zarafaContainsPublic attribute on your current node, because this node already contains the public folders.

User objects

In a MultiServer setup every user needs to have a homeserver assigned. This needs to be done in LDAP.

  • When using ADS, you can just edit the user object and select the "Home Server".
  • When using OpenLDAP, you need to set the attribute zarafaUserServer on every user.

On the current node there exist already some users, so we need to set this node as the users' Home Server for ALL users. So in our example (note we changed the server_name to zarafa01):

zarafaUserServer: zarafa01

Starting Multi Server

When we have updated ALL user objects with the correct users' Home Server (zarafaUserServer), we can finally start our MultiServer setup. For this we need to change one option in the server.cfg:

enable_distributed_zarafa = true

Now we restart zarafa:

/etc/init.d/zarafa-server restart

Check the log for warnings and errors. If you see the error: "Multiserver mode is locked, reason: 'upgrade'. Contact Zarafa for support." Then you most likely forgot to run the script db-upgrade-addressbook-entryids.pl to convert the entry-id's.

Check if all users have an assigned home server:

zarafa-admin -l

This should give an output which looks something like this (note that you now see the users' Home Server at the end):

User list for Default(8):
        username                fullname
        SYSTEM          SYSTEM
        user1           User One        (zarafa01)
        user2           User Two        (zarafa01)
        user3           User Three      (zarafa01)

Remove Safe Mode

When all looks ok, we can finally switch off the user_safe_mode in the server.cfg:

user_safe_mode = no

Restart Zarafa server:

/etc/init.d/zarafa-server restart

Further Steps

We have now successfully migrated our single node setup to a MultiServer compatible setup. This means that we can now add new nodes to the cluster. Consult our administrator manual on how to setup SSL for node to node communication.

Once you have setup extra nodes in cluster, you can use the "Mailbox Storage Relocator" (MSR) to migrate stores from one node to the other. Consult the administrator manual on how to use the MSR.

Client Actions

When you needed to run the script "db-upgrade-addressbook-entryids.pl" to update the entry id's AND migrated to MultiServer mode, you need to perform some client actions.

These actions are MANDATORY when you start running more than one Zarafa node in the cluster. So while you are running only 1 node in the cluster (e.g. the node we have just migrated), these actions are advised but NOT mandatory.

Client Actions:

  • Every Outlook client that runs in cached mode needs to have the profile deleted and recreated in order to perform a complete resync.
  • Every Outlook client (both online and cached) needs the NK2 cache files removed.
Personal tools