6. Special ZCP Configurations

This chapter describes how to configure special setups that go beyond most common installations of ZCP.

6.1. Running ZCP components beyond localhost

When using the SSL connection with certificates it will not only be possible to encrypt the connection, but Linux services will also be able to login using a client SSL certificate.

Repeat the certificate creation script to create certificates for client programs like the zarafa-spooler, zarafa-monitor, zarafa-gateway, zarafa-dagent and zarafa-admin. It’s possible to create one certificate for all these programs, or a certificate can be created for each program separetely. These clients can then login on the SSL connections with their certificate as authentication.

sh /usr/share/doc/zarafa/ssl-certificates.sh client

Again, when entering the certificate details, at least make the Organizational Unit Name different from the other certificates. Also, do not forget to fill in the Common Name field.

When asked for the creation of the public key, enter y and press enter. Now a new certificate called client.pem and a public key called client-public.pem are present. As an example, the configuration options needed to edit on the dagent.cfg file are as follows:

server_socket = https://name-or-ip-address:237/zarafa
sslkey_file = /etc/zarafa/ssl/client.pem
sslkey_pass = ssl-client-password


For the zarafa-admin tool to function correctly in a multi-server set-up, a admin.cfg file is required in the ZCP configuration directory, usually /etc/zarafa/. It also should contain the options mentioned above.

Enter the correct name or IP-address in the server_socket option. If Another port number for the SSL connections on the server is used, enter the right port number as well. Replace the password with the password used while creating the certificate.

Copy the client-public.pem file to the server location:

mkdir /etc/zarafa/sslkeys
mv client-public.pem /etc/zarafa/sslkeys

Now the client knows the private key, and the server knows the public key. The client can login with this key to the server from anywhere on the network or internet.


Be careful with the client.pem file. Anybody who has this private key can login to the Zarafa server and will be the internal SYSTEM user, who can do anything without restriction.

6.2. Multi-tenancy configurations

This section will provide information regarding the multi-tenancy functionality which was introduced in Zarafa 6.10. The feature is available in all editions, but only officially supported in the Enterprise and Hosted editions.

Multi-tenancy mode enables organisations to run multiple organisations on a single ZCP server where the members of the different organisations won’t see each other.

6.2.1. Support user plugins

Multi-tenancy support can only be enabled when using the DB or LDAP plugin. Currently it’s not possible to use the Unix plugin. When using the DB plugin, the zarafa-admin tool can be used to manage tenants (companies), while with the LDAP plugin all information will come directly from LDAP or Active Directory.


The preferred user plugin for multi-tenancy setups is the LDAP plugin.

6.2.2. Configuring the server

The following configuration options in server.cfg will be used when enabling the multi-tenancy support.

enable_hosted_zarafa = false

When set to true, it is possible to create tenants within the Zarafa instance and assign all users and groups to particular tenants. When set to false, the normal single-tenancy environment is created.


Location of the createcompany script which will be executed when a new tenant has been created.


Location of the deletecompany script which will be executed when a tenant has been deleted.


See Configuring login name for more details about this configuration option.


See Configuring store name for more details about this configuration option. Enabling Multi-tenancy

To enable multi-tenancy support in Zarafa change the following configuration option in server.cfg:

enable_hosted_zarafa = true Configuring login name

The loginname of a user must be unique in order to correctly allow the login attempt. When enabling multi-tenancy support in Zarafa, having an unique loginname can become difficult as the number of companies (tenants) increases. It is easier when the loginname contains the companyname as well, to ensure all loginnames are unique.

The way the companyname is ‘attached’ to the username to create the loginname can be configured with the loginname_format configuration option in server.cfg. This configuration option can contain the following variables:

  • %u - The username
  • %c - The companyname to which the user belongs

As separation character between the username and companyname a character should be chosen that does not appear inside the username or companyname itself. Valid characters for example are @ and \.

Some example loginname_format for a user named “John Doe” who is member of “Exampleorg”:

Although having a loginname that contains a %c is mandatory for the DB plugin, it is optional for the LDAP plugin. Managing unique loginname_s is easier in LDAP because it is possible to use the email address as the _loginname attribute. See the LDAP configuration file for more information about the loginname attribute.


When passing a username to the zarafa-admin tool it should be formatted as configured. For example if the loginname_format configuration value includes company name variable (%c), the company name should be passed to the zarafa-admin tool everytime a username is needed. Configuring store name

When relations between multiple tenants (companies) are allowed, it is possible that users share their store with users from other tenants. To easily differentiate stores from different tenants, the store name can be formatted to contain the tenant’s name (companyname) to which the user/store belongs.

In server.cfg the configuration option storename_format is provided for exactly this purpose. In the format different variables are provided which can be used to different kinds of information.

  • %u - The username
  • %f - The fullname of the user
  • %c - The companyname, name of the tenant, to which the user belongs

Some examples for a user named ‘John Doe’ who is member of the tenant ‘Exampleorg’:

  • %u > john
  • %f > John Doe
  • %f (%c) > John Doe (Exampleorg) Configuring the LDAP plugin

When using the DB plugin no additional configuration is required. For the LDAP plugin there are several configuration options that might require changes.

For a multi-tenancy LDAP setup, it is necessary to have the different company in the LDAP tree and below every company container the users, groups and contacts within that specific company. It’s not possible to assign a user to a specific company by an LDAP attribute.

See the screenshot below for an example LDAP structure.

LDAP tree multi-tenant environment

Figure 6.1. LDAP tree multi-tenant environment

Change the following lines in the LDAP configuration file, to configure the multi-tenancy support.

ldap_company_unique_attribute = ou
ldap_companyname_attribute = ou
ldap_company_scope = sub

Test the settings by using zarafa-admin --list-companies and zarafa-admin -l.

If no companies or users are shown, please check the Zarafa server log file for errors. Setting the loglevel to 6 in the /etc/zarafa/server.cfg will display all LDAP queries by the Zarafa server and possible errors.

With multi-tenancy support enabled it’s not only possible to have different organizations on a single server, but also more advanced settings can be configured, like cross-organization mailbox delegation, different administrator levels and organization quota levels.

See the zarafa-ldap.cfg man page for more detailed information about these multi-tenancy LDAP features.

man zarafa-ldap.cfg Public stores

Once the server has been correctly started, stores can be created. There are two type of stores: Private and public stores. There can only be one public store per company space. When creating a company, the public store will be created simultaneously. If for some reason the public store for the specific company is not created, the public store can be created manually by executing the following command:

/usr/sbin/zarafa-admin -s -I <tenant>

Replace <tenant> with the name of the tenant (company) for which the public store should be created. When the -I option is not used, the public folder will be created for a single-tenancy environment (And will not be accessible when multi-tenancy Zarafa is enabled). The public folder is by default available for all users within a tenant (company).

6.2.3. Managing tenant (company) spaces


Management of tenant (company) spaces through zarafa-admin is only available when using the DB plugin. When the LDAP plugin is used, all administration needs to be done through the LDAP or Active Directory server.

To create a company space use the following command:

/usr/sbin/zarafa-admin --create-company <companyname>

To delete a company space use the following command:

/usr/sbin/zarafa-admin --delete-company <companyname>

To change a company space use the following command:

/usr/sbin/zarafa-admin --update-company <companyname>

This command can be combined with the option --qw for setting the quota warning level for the specified company space.

To control the view privileges for company spaces the following commands can be used:

/usr/sbin/zarafa-admin --add-to-viewlist <viewer> -I <companyname>
/usr/sbin/zarafa-admin --add-to-viewlist <viewer> -I <companyname>
/usr/sbin/zarafa-admin --list-view -I <companyname>

The <viewer> is the companyname which receives or looses permission to view company <companyname>. With the view privileges the Global Address Book can be shared between multiple organizations or use cross organization mailbox delegation.

/usr/sbin/zarafa-admin --add-to-adminlist <admin> -I <companyname>
/usr/sbin/zarafa-admin --del-from-adminlist <admin> -I <companyname>
/usr/sbin/zarafa-admin --list-view -I <companyname>

The <admin> is the loginname of the user who receives or looses admin privileges over the company <companyname>. Please note that a user that is administrator over a tenant still needs to be given view privileges to this tenant to see its stores.

6.2.4. Managing users and groups

When using the DB plugin users and groups should be created using the zarafa-admin tool. For details about using the zarafa-admin tool see man zarafa-admin. The user- or group name that should be given to the zarafa-admin tool depends on the loginname_format configuration option.

For example, when loginname_format is set to %u@%c creating a user for tenant exampleorg would be:

/usr/sbin/zarafa-admin -c john@exampleorg ...other options...

And creating a new group for tenant exampleorg would be:

/usr/sbin/zarafa-admin -g group@exampleorg ...other options...

6.2.5. Quota levels

When using a multi-tenancy installation there are 2 types of quota, namely the quota for the tenant (company) and the quota for the individual user. The quota for the tenant is checked over the total store size of all users within that tenant plus the public store.

At this time only the warning quota can be configured for a tenant, this means it is not possible to set the soft or hard quota to limit the tenant’s email capabilities.

Just like the user quota, there are multiple levels for tenant quota, and there is even a new level for the user quota. A summary of the possible quota levels which can be set in a multi-tenancy environment:

  1. Tenant (company) quota:

    1. Global company quota: Configured in /etc/zarafa/server.cfg and affects all tenants within the system.
    2. Specific company quota: The quota level for a tenant configured through the plugin (LDAP or zarafa-admin tool).
  2. User quota:

    1. Global user quota: This is configured in /etc/zarafa/server.cfg and affects all users from all tenants.
    2. Company user quota: This is the default quota level for all users within a tenant, and is configured through the plugin at tenant level.
    3. Specific user quota: This is the quota level for a specific user, and is configured through the user plugin.

As mentioned above the Global company quota and Global user quota can be configured in the /etc/zarafa/server.cfg file, in there the options quota_warn, quota_soft and quota_hard for the user quota, and the options companyquota_warn for the tenant quota.

To configure the Specific company quota the zarafa-admin tool can be used when using the DB plugin. The following command will set the various quota levels over the tenant:

zarafa-admin --update-company <tenant> --qo y --qw <warningquota>

To configure the Specific user quota the zarafa-admin tool can be used when using the DB plugin. The following command will set the various quota levels over the user:

zarafa-admin -u <user> --qo y --qh <hardquota> --qs <softquota> --qw <warningquota>

To configure the Company user quota the zarafa-admin tool can be used when using the DB plugin by using the --update-company argument. The following command will set the various user default quota levels over the tenant:

zarafa-admin --update-company <tenant> --udqo y --udqh <hardquota> \
             --udqs <softquota> --udqw <warningquota>

When using the LDAP plugin, the attributes which control the quota levels can be configured in /etc/zarafa/ldap.cfg.

6.2.6. Administrator users

In a multi-tenancy installation there are two types of administrator users:

  • System wide administrator
  • Company administrator

The system administrator can access all mailboxes within the hosted environment. A company administrator can only access the mailboxes within the local organisation.

A system administrator can be configured by setting the zarafaAdmin attribute to 2 when using LDAP or use -a 2 when using the DB plugin. A company administrator can be configured by setting the zarafaAdmin attribute to 1.

The type of administrator user can be requested by using the zarafa-admin tools:

zarafa-admin --details <admin username>
Username:              admin@example.com
Fullname:              Administrator
Emailaddress:          admin@example.com
Active:                yes
Administrator:         yes (system)

6.3. Multi-server setup

This chapter will provide information regarding the multi-server functionality which was introduced in Zarafa 6.30.


In order to use this feature a valid Zarafa Enterprise license key is necessary and a running zarafa-licensed is required.

6.3.1. Introduction

The ZCP multi-server feature gives the possibility to distribute ZCP over multiple servers. In this situation the Zarafa-user-stores are divided over several servers, but still acting as one central system. The users, groups and tenants (companies) have to be managed in a LDAP or Active Directory server.

Multiserver environment in one location

Figure 6.2. Multiserver environment in one location

The multi-server support can also be used to support larger number of users or to spread mailboxes over different geographical locations, see Multiserver environment on two locations.

Multiserver environment in two locations

Figure 6.3. Multiserver environment on two locations

The mailbox of a user is always stored on only one server. It’s not possible to synchronize mailboxes over multiple servers.

When accessing mulitple mailboxes, that are located on different servers, the client will make a connection to the different multi-server nodes. See the flowchart Multiserver environment.

Multiserver environment

Figure 6.4. Multiserver environment

User John is located on Node 1 and the user Mary is located on Node 2. John has read access on the mailbox of Mary.

  1. John starts his Outlook client, which connects to Node 1.
  2. The Zarafa Server Node 1 checks the Home Server attribute in the central LDAP server.
  3. The Home Server of user John is returned to the Zarafa Server.
  4. John’s mailbox is located on Node 1, so the mailbox is loaded.
  5. John sends a request to the Zarafa Server to open the mailbox of Mary.
  6. The Zarafa Server Node 1 checks the Home Server attribute of Mary in the central LDAP server.
  7. The Home Server of user Mary is returned to the Zarafa Server
  8. A redirect request is send back to the client
  9. The client makes a connection to Node 2 to open the mailbox of Mary.

In the above example the client has a connection open to both nodes to access the mailboxes.

6.3.2. Prepare / setup the LDAP server for multi-server setup

The Zarafa multi-server version can only be used with the LDAP user plugin.

In a multi-server setup the Zarafa Server will not only request user and group information from the LDAP server, but also information about the different multi-server nodes.

  1. Setup the LDAP server using Configure ZCP OpenLDAP integration or Configure ZCP Active Directory integration in this manual.

  2. In the LDAP structure add a folder or organizational unit for each Zarafa Server node in the multi-server setup.

    Setup directory with all the multi-server nodes

    Figure 6.5. Setup directory with all the multi-server nodes

  3. Add all the multi-server nodes to this directory or organizational unit. In Active Directory the Computer template can be used for this. When using OpenLDAP a custom LDAP object can be created, with the device, ipHost and zarafa-server objectClass.

    Computer creation wizard in ADS

    Figure 6.6. Computer creation wizard in ADS

  4. Every multi-server node should have a common name, FQDN or ip-address and the Zarafa server details. Make sure the FQDN can always be resolved by the clients.

    LDAP server attributes

    Figure 6.7. LDAP server attributes

  5. The attribute ZarafaContainsPublic can only be set for one multi-server node at a time. At the moment there is no support for having a single Public Folder onto multiple nodes.

  6. The Zarafa LDAP configuration needs to be extended with some extra multi-server configuration options. An example configuration file for the multi-server setup can be found in the /usr/share/doc/zarafa-multiserver/example-config directory. The files ldapms.*.cfg are the specific multi-server configuration files. The following LDAP configuration entries need to be configured for a multi-server setup:

ldap_server_type_attribute_value = zarafa-server
ldap_user_server_attribute = zarafaUserServer
ldap_server_address_attribute = ipHostNumber
ldap_server_http_port_attribute = zarafaHttpPort
ldap_server_ssl_port_attribute = zarafaSslPort
ldap_server_file_path_attribute = zarafaFilePath
ldap_server_search_filter =
ldap_server_unique_attribute = cn
  1. Every created Zarafa user in the LDAP server needs to be assigned to a Zarafa server node. This can be set by using the ZarafaUserServer attribute. The attribute should contain the unique server name.

In a multi-tenancy situation, all created tenants (companies) in LDAP have to be updated with the zarafaCompanyServer attribute. Use the server name as well for this.

6.3.3. Configuring the servers

The following configuration options in server.cfg are provided for Multi-server support.


Enable multi-server environment. When set to true it is possible to spread users and companies over multiple servers. When set to false, the single-server environment is created.


The unique server name used to identify each node in the setup. This server name should be configured correctly in the DNS. This server name should be the same as the value of the zarafaUserServer attribute.

To enable multi-server support in Zarafa change the following configuration options in server.cfg:

user_plugin = ldapms
enable_distributed_zarafa = yes
server_name = <servername>
server_ssl_enabled = yes


An upgrade from single server to multi-server support is not a simple task. Please check with the Zarafa Support if migration is possible for the setup used.

6.3.4. Creating SSL certificates

In a multi-server setup, it is required to configure SSL support, because clients like the zarafa-dagent, zarafa-admin, zarafa-monitor need an SSL certifcate to login to the different multi-server nodes.

It’s required to first create server side certificates, so the Zarafa Server is able to accept SSL connections. For the SSL authentication of the Linux clients, like the zarafa-dagent, a private and public key need to be created.

Follow the steps below to create both the server and client certificates.

  1. First, create the directory which will contain the certificates.
mkdir /etc/zarafa/ssl
chmod 700 /etc/zarafa/ssl
  1. Create the server certificate, by using the ssl-certificates.sh script in the /usr/share/doc/zarafa directory, which uses the openssl command and the CA.pl script. Before a server certificate can be created a root CA is required. If no root CA is found, the script will first create an own CA.
cd /etc/zarafa/ssl/
sh /usr/share/doc/zarafa/ssl-certificates.sh server
  1. Enter a password (passphrase) if you want to use a password for the server key. If a password is set, then this password is needed later on to sign certificate requests. Then enter the certificate information. Give extra attention to the Common Name. This has to be the fqdn of the server. The challenge password at the end may be left empty. At the end of the certificate creation the certificate need to be signed against the CA. Accept twice the question for the signing and fill the password of the CA again when asked for.
  2. In the last step, the script will ask if it should display the public key of this certificate. This is not necessary, since the certificates have already been created.
  3. After completing the ssl-certificates.sh script, the server certificate is created in the current directory. The root CA certificate can be found in the same directory or in the default SSL directory of the Linux distribution. On Ubuntu the root CA will be created as ./demoCA/cacert.pem, on RedHat the root CA will be created as /etc/CA/cacert.pem. Edit the following lines in /etc/zarafa/server.cfg.
server_ssl_enabled             = yes
server_ssl_port                = 237
server_ssl_ca_file             = /etc/zarafa/ssl/demoCA/cacert.pem
server_ssl_key_file            = /etc/zarafa/ssl/server.pem
server_ssl_key_pass            = <ssl-password>
sslkeys_path                   = /etc/zarafa/sslkeys
  1. After a restart of the Zarafa-server, the server should accept HTTPS connections. Please check the server logfile for any errors.
  2. For more options concerning ssl certificates please also see the manpages of zarafa-server.cfg.
  3. If the server certificates are successfully created, the client certificates can be created by the following steps:
cd /etc/zarafa/ssl
sh /usr/share/doc/zarafa/ssl-certificates.sh client
  1. Fill in all the information, like the server certificate. On some Linux distributions, the Common Name may not be the same as in the server certificate. At the end of the creation, it is required to sign again the certificate against the CA and create a public key for the certificate.
  2. Two client certificates are created: client.pem and client-public.pem. The client.pem is the private key and will be used by a client (like dagent or spooler). The client-public.pem is the public key which is used by the server.
  3. Create /etc/zarafa/sslkeys and move the public key into it.
mkdir -p /etc/zarafa/sslkeys
mv /etc/zarafa/ssl/client-public.pem /etc/zarafa/sslkeys
  1. Restart the zarafa-server on all nodes to activate the new certificates:
/etc/init.d/zarafa-server restart
  1. To test the client SSL certificates change the following lines in the /etc/zarafa/dagent.cfg.
server_socket =
sslkey_file = /etc/zarafa/ssl/client.pem
sslkey_pass = <ssl-client-password>

When the certificates have been set up email can now be delivered by using the ssl socket with the dagent’s private-key, in this test case on localhost.

zarafa-dagent -v -c /etc/zarafa/dagent.cfg <username_on_this_node>
Subject: test email

When connecting through ssl the dagent will verify the private against the root CA. On Red Hat based systems generated hashed file names have to created of the root certificates:

yum install openssl-perl
cp /etc/CA/cacert.pem /etc/pki/tls/certs/zarafa-ca.pem
c_rehash /etc/pki/tls/certs

This way the dagent is able to verify the private-key against the CA bundle. On Debian based systems this step can be ignored.

  1. If the test case is successful, it is possible to change the following value in the dagent.cfg back to:
server_socket = file:///var/run/zarafa
  1. Deploy all certificates to the different multi-server nodes:
scp -r /etc/zarafa/ssl /etc/zarafa/sslkeys root@node2:/etc/zarafa/

Remember to copy the root CA to the different nodes if this file is placed outside the directories that have just been copied.

  1. Repeat the above steps to configure the server.cfg and dagent.cfg on all the different nodes. On Red Hat based nodes also add the root CA to the CA bundle. When done test remote delivery width:
zarafa-dagent -v -c /etc/zarafa/dagent.cfg <username_on_other_node>
Subject: test email

This delivery should not result in any delivery errors, otherwise please check created certificates. It’s now possible to deliver email from a central MTA to the different multiserver nodes.

The client SSL certificates can be used for the following tools to connect to a remote Zarafa-server:

zarafa-backup, zarafa-restore

For advanced multi-server environments and the best Zarafa configuration for a specific setup, the Zarafa Professional Services are open for advise and support.

6.4. Zarafa Windows Client Updater

ZCP contains a mechanism that allows Zarafa Windows Clients to update themselves to the latest version.


The Zarafa Windows Client Updater is only available to those running the ZCP Professional or Enterprise edition.

Auto-update structure

Figure 6.8. Auto-update structure


  • The auto update mechanism does not support the ability to downgrade the client to a certain version, it will always update the Zarafa Windows Client to the highest version available.
  • The Zarafa Windows Client Updater is not available for Windows 2000 or earlier releases. = The Zarafa Windows Client Updater can not automaticly switch between 32bits and 64 bits installations.


In case the Zarafa server can be reached over the internet the client can also be downloaded over the internet. zarafa-server (by design) does not provide the ability to limit access to defined ip ranges or authenticated users. To limit access to https://your-server:237/autoupdate a reverse proxy should be used (and ip limitation should be configured on the reverse proxy).

6.4.1. Server-side configuration

The Zarafa Windows Client Updater can be enabled by setting the following setting to yes in the server.cfg of the zarafa-server:

client_update_enabled = yes

When a zarafa-server is upgraded, it will copy the latest updated client installer to the path which is specified in the server configuration file server.cfg, As shown below.

client_update_path = /var/lib/zarafa/client

The auto update client can send the log information back to the server. If the updater fails, then the log files are sent to the server by default. This behavior can be changed with the following setting: client_update_log_level = 1

The following options can be set: 0 disabled 1 send only the log files to the server when an error occurs 2 always send the log files to the server

The log files received from the auto update client are put in the following location on the server: client_update_log_path = /var/log/zarafa/autoupdate

The updates at the client update folder follow a naming convention. The Zarafa Server will work only with those updates that adhere to this convention:

zarafaclient-<major version>.<minor version>.<update number>-<build number>.msi

For example zarafaclient-7.2.0-48204.msi is a valid name of an update.

Based on this naming convention, the Zarafa Windows Client Updater finds out if an update of the client software is available. If a client send a request to receive a new version, the zarafa-server will send the new client update package to the client, so that it can update itself to the latest version.


If the default profile is set to use encryption via port 237, the root CA certificate needs to be installed on the desktop used.

6.4.2. Client-side configuration

The Zarafa Windows Client’s auto-update mechanism consists of an application to start the auto-update process by the name of ZarafaLaunchUpdater.exe and a windows service known as ZarafaUpdaterService.exe.

Auto-update structure service

Figure 6.9. Auto-update structure

The Launch Updater application will be launched at Windows’ startup. The command to run the application is placed in the registry here:


This application will find out client’s current version from the following registry key:


This registry key contains the current version of the Zarafa Windows Client installed on the machine.

The Launch Updater application will read default Outlook profile from the registry to gather the credentials needed to connect to the Zarafa Server. It informs the Zarafa Server which version of the Zarafa Windows Client is running, the Zarafa Server responds with a newer Zarafa Windows Client in case that exists. Zarafa Updater Service

The zarafa updater service runs as a local system account. Therefore, it has all the needed privileges to install the Zarafa Windows Client on the desktop.


Figure 6.10. Services

The zarafa updater service will wait on a pipe for Zarafa launch updater application to send it the current version of the client and the details of the Zarafa Server to connect to. If there is a suitable update, the service downloads it to c:\windows\temp\zarafaclient.msi. The zarafa updater service launches this update for installation in a silent mode.

Although the entire update process is silent, logs will be generated for troubleshooting. The Updater service log will be written in the All users\Application data\ directory and the Launch updater log will be written in the <user>\Application data\ directory.

When the Updater service starts the client update, it will create zarafa-<trackid>.log and zarafa-<trackid>msi.log in the <user>\Local Settings\Temp directory. These files are sent to the server depending on the server settings.


The client will only find updates successfully if the default Outlook profile is configured to work with a Zarafa Server, and if updates are available at that server. Even with the setting to `prompt for the profile to be used’ the Zarafa Windows Client Updater will succeed provided the (greyed out) drop-down menu specifies the profile configured for Zarafa. Please refer to the User manual on how to configure Outlook profiles. Zarafa Updater status

The zarafa-server reports the status from the Zarafa client updater in the server.log. The zarafa-admin reports the latest status of the client update. Using the following command, you can view the update information per user: zarafa-admin –details <user>

Client update Information:
Trackid:               1889610488
Last update:           <date>
From version:          <version>
To version:            <version>
Computername:          <name>
Update:                Succeed

When a client update failed, the log files are located in the directory configured in the server.cfg field client_update_log_path (by default, this is set to /var/log/zarafa/autoupdate). The trackid value can be used to find the log files, for example: /var/log/zarafa/autoupdate/0x70A12AF8/zarafa-autoupdate.log

6.4.3. MSI Options

Several options can be specified when pushing the Zarafa client from your Windows Domain Server. For one you can specify the individual components to install using the ADDDEFAULT option. Possible values are Client, Updater and Compat.

If only the client and the OL2010/2013 compatability should be installed the following line can be used:


If the Updater Service (only available in Kopano Pro) should be installed as well the command would be:


To change the default installation path the APPDIR variable can be used. Omit this option to install the client to the default directory.


To make the installation not show any graphical interface the following option can be used:


To show progress of the installation, use the modifier b (for basic gui) or r (for reduced gui). Please be aware that when showing the full gui (f modifier) the installation process will be interactive.

A full list of available option can be gathered when running msiexec.

For a typical automated installation, use the following command:

msiexec /i zarafaclient.msi ADDDEFAULT=Client,Compat /q

6.5. Single Instance Attachment Storage

Since ZCP 6.30 the Zarafa Server provides Single Instance Attachment Storage to avoid redundant storage of attachments. This feature, as its name implies, only keeps one copy of each attachment when a message is sent to multiple recipients within the same server. This mechanism, thus, minimizes the disk space requirements and remarkably enhances delivery efficiency when messages with attachments sent to large distribution lists.

Let’s assume the following situation: user A belongs to a Zarafa server; he sends a message with 10 MB of attachments to 30 users that reside on the same server. In a normal situation 30 copies of the files would be saved on the database, leading to an inefficient usage of the storage space (310 MB of data). With single instance attachment store, only one copy of each attachment is saved on the database (only 10 MB of data in this example) and all the 30 users can access the attachment through a reference pointer.


Single instance attachments are accessible between tenants (companies) as well (even when the tenants cannot view each other), the handling of single storage will be transparent. Thus, considering the example above, if user A sends the message to 30 users of tenant1 and 50 users of tenant2, provided that the tenants reside on the same server, only one copy of the attachments is saved.


Single instanced attachments will be handled per server, when sending an email with attachment to multiple Zarafa users spread over multiple servers, each server will get its own Single instance attachment.

6.5.1. Single Instance Attachment Storage and LMTP

To use the Single Instance Storage it’s required to use the LMTP delivery method executed from the virtual_transport in Postfix.

With the aforementioned setup, externally received email with an attachment sent to multiple internal users will be processed efficiently by saving the attachment only once.

The usage of virtual_transport in Postfix will deliver only one email with a list of the internal users to the dagent instead of one email per internal user. Without virtual transport option, Single Instance can not know that the attachment is similar in the email item(s).

6.6. Running ZCP Services with regular user privileges

Normally the Zarafa services are run as root. Since version 5.0 there is the option to change the user the service runs as, and still start the services as root. However, there are several things to do before the services can correctly run as a non-root user.

If the log_method is set to file, make sure this directory and file is writable by the user or group the service will be running as. When a logrotate happens, by sending the service the HUP signal, a new file is created, which will be owned by the user the service is running under.

The service should still be started as root since it will create a pid file under the system location /var/run, and will open the network sockets which most likely have a number under 1024, which may only be opened as root.

The following example shows how to configure the zarafa-server to run as user zarafa and group zarafa:

addgroup --system zarafa
adduser --system --home /dev/null --no-create-home --ingroup zarafa \
        --disabled-password --gecos 'Zarafa services' --shell /bin/false zarafa
mkdir /var/log/zarafa
chown zarafa:zarafa /var/log/zarafa
chown zarafa:zarafa /etc/zarafa/report
chown -R zarafa:zarafa /var/lib/zarafa


The addgroup and adduser tools may have different syntax on different distributions.

Edit the run_as_user and run_as_group options in the server.cfg file, and set them both to zarafa. Make sure the local_admin_users option still contains root as an administrative user, so the zarafa-admin tool can still be used. Otherwise su or sudo has to be used each time the zarafa-admin tool is started.

6.7. Single Sign On with ZCP

This chapter will describe how to set up a Single Sign On environment with ZCP, so users can authenticate without entering their password. ZCP supports both the NTLM and Kerberos authentication protocol. The Kerberos support is available from ZCP 6.40.2 and higher.

Both methods will be described in the following sections.

6.7.1. NTLM SSO with ADS Installing Linux software

The following software needs to be installed:

  • winbind
  • kinit

Depending on the linux distribution used, this comes through various package names. On Debian use:

apt-get install krb5-user winbind

krb5-user will also install the Kerberos library configuration files in /etc. The package winbind depends on samba-common which will therefore be installed as well. On Red Hat Enterprise Linux both the krb5-workstation and the samba-common package are required for this.

To enable NTLM SSO with ZCP set the following option in /etc/zarafa/server.cfg:

enable_sso  = yes ADS: Specific network setup

The following prerequisites have to be met before proceeding:

  • Every server must have a DNS name, so their IP-addresses can be found by DNS.
  • The time of all servers must be in sync. Time cannot lag for a few minutes.

This document has the following names as example:

  • FQDN of the Windows ADS server: ADSERVER.ADSDOMAIN.EXAMPLE. Therefore, the windows server is named: ADSERVER, the realm is ADSDOMAIN.EXAMPLE, and the domain name is ADSDOMAIN. Workstations can therefore either join the domain using the ADSDOMAIN or ADSDOMAIN.EXAMPLE name.
  • FQDN of the Linux server is LINUXSERVER.EXAMPLE. This name does not matter much, as long as it is handled by the DNS server. Configuring the Kerberos library

First we are going to configure the Kerberos library. The configuration file is /etc/krb5.conf. Under the libdefaults section, set:

default_realm = ADSDOMAIN.EXAMPLE

Under the realms section, add the windows realm:

    kdc =
    admin_server =
    password_server =
    default_domain = ADSDOMAIN.EXAMPLE

Here, is the IP-address of the Windows ADS domain server.

Now that the Kerberos library is configured, it is possible to login using kinit on the linux server:

kinit Administrator

This will ask for a password:

Password of Administrator@ADSDOMAIN.EXAMPLE:

Type the administrator password there, and a Kerberos ticket should be provided by the ADS server. Joining the ADS domain

First we’ll configure samba. Edit the /etc/samba/smb.conf file, and add/set the following options:

For Samba < 3.4

use kerberos keytab = true
security = ads

For Samba >= 3.4

kerberos method = dedicated keytab
dedicated keytab file = /etc/krb5.keytab
security = ads

The value of kerberos method may also be set to system keytab, and dedicated keytab file may be left out. Please consult the smb.conf(5) manual page for more information about these settings.

With this ticket we can join the Windows domain, without typing the password again:

net ads join

or if this doesn’t work:

net ads join -S ADSDOMAIN -U Administrator

This command may also be different for different versions of Samba. If this command asks for a password, something goes wrong and it should be killed with Ctrl-C. When all goes well, the following line is printed to the screen:


or some other success message.

Now it’s required to restart the winbind daemon, because it keeps too many items cached:

/etc/init.d/winbind restart

And that’s it. To test if authentication actually worked, try the following command:

ntlm_auth --username=john

Where john is a user on the ADS server.

The program will asks for a password. After entering the password, it should say:

NT_STATUS_OK: Success (0x0)

If this step does not work, try restarting winbind, check the DNS names, check with strace what ntlm_auth tries to do, check with tcpdump if there is actual traffic on the network from ntlm_auth to the domain server and other lowlevel debugging tools.

6.7.2. NTLM SSO with Samba 3 Installing Linux software

Depending on the Linux distribution used, winbind comes through various package names. On Debian use:

apt-get install winbind

On Red Hat Enterprise Linux the samba-common package is required for this.

To enable NTLM SSO with ZCP set the following in the /etc/zarafa/server.cfg file:

enable_sso = yes Joining the domain

Now the server need to join the Samba domain by executing the following command:

net rpc join

Finish by typing the Administrator password. If successful the prompt should give:

Joined domain <DOMAIN>

The SSO configuration is now done. To test if authentication actually worked, try the following command:

ntlm_auth --username=john

Where john is a valid Samba user.

The program will asks for a password. After entering the password, it should say:

NT_STATUS_OK: Success (0x0)

If this step does not work, try restarting winbind, check the DNS names, check with strace what ntlm_auth tries to do, check with tcpdump if there is actual traffic on the network from ntlm_auth to the domain server and other lowlevel debugging tools.

6.7.3. SSO with Kerberos Requirements and Conventions

  • The server that runs ZCP must have the MIT Kerberos software installed.
  • ZCP version 6.40.2 or higher needs to be installed for SSO with Outlook.
  • Every server must have a DNS name, so their IP-addresses can be found by DNS. It is also required that all servers have a PTR record.
  • The time of all servers must always be in sync with each other.

This document has the following names as example:

  • FQDN of the Windows Active Directory Server: ADSERVER.ADSDOMAIN.EXAMPLE. Therefore the windows server is named: ADSERVER, the realm is ADSDOMAIN.EXAMPLE, and the workgroup name is ADSDOMAIN.
  • FQDN of the Zarafa Server is ZARAFA.LINUXDOMAIN.EXAMPLE.

In this example the Zarafa Server is placed in a different domain. This is no requirement, but this makes the document a bit more clear on how to create the Kerberos principal. Active Directory configuration

Create two Kerberos principals in Active Directory, one for SSO with WebAccess and one for SSO with Outlook.

  1. Add a new user httpd-linux to the Active Directory (this user will be used to create the principal for SSO with WebAccess, username may differ).
  2. Add a new user zarafa-linux to the Active Directory (this user will be used to create the principal for SSO with Outlook, username may differ).
  3. Make sure that the option Password never expires is enabled.
  4. On the account properties for these users, enable: Use DES encryption types for this account.
  5. After setting this account property it is strongly advised to reset the password for these users.


The following commands will use the ktpass.exe utility, which should be installed by default when the ActiveDirectory is running on the same machine. In any other case you can find it with the “Windows Support tools” on the install cd or download them from the Microsoft website.


When creating a keytab on Windows Server 2008 be sure to specify RC4-HMAC-NT as the crypto, -mapop set +desonly must be left out.

Execute the following command to create the keytab file for the Apache webserver:

ktpass.exe -princ HTTP/fqdn@REALM -mapuser account@DOMAIN -crypto DES-CBC-MD5 \
           -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -pass <password> \
           -out c:\keytab.apache

or for Windows Server 2008:

ktpass.exe -princ HTTP/fqdn@REALM -mapuser account@DOMAIN -crypto RC4-HMAC-NT \
           -ptype KRB5_NT_PRINCIPAL -pass <password> -out c:\keytab.apache

Execute the following command to create the keytab file for the Zarafa Server:

ktpass.exe -princ fqdn@REALM -mapuser account@DOMAIN -crypto DES-CBC-MD5 \
           -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -pass <password> \
           -out c:\keytab.zarafa

or for Windos Server 2008:

ktpass.exe -princ fqdn@REALM -mapuser account@DOMAIN -crypto RC4-HMAC-NT \
           -ptype KRB5_NT_PRINCIPAL -pass <password> -out c:\keytab.zarafa
  • Copy the file keytab.apache to /etc/apache2 (Deban and Ubuntu) or /etc/httpd/ (RHEL & SLES) on the Linux server.
  • Copy the file keytab.zarafa to /etc/zarafa/ on the Linux server. Kerberos configuration

Open the file /etc/krb5.conf and insert the following lines:

   default_realm = ADSDOMAIN.EXAMPLE
   default_tgs_enctypes = des-cbc-md5 arcfour-hmac-md5
   default_tkt_enctypes = des-cbc-md5 arcfour-hmac-md5
   permitted_enctypes = des-cbc-md5 arcfour-hmac-md5

           kdc = adserver.adsdomain.example
           admin_server = adserver.adsdomain.example

.adsdomain.example = ADSDOMAIN.EXAMPLE
adsdomain.example = ADSDOMAIN.EXAMPLE

Configuring ZCP for Kerberos SSO with Outlook:

Add the following line to the [libdefaults] section of /etc/krb5.conf:

default_keytab_name = /etc/zarafa/keytab.zarafa Zarafa Server configuration

To enable Outlook SSO with ZCP set the following in the server.cfg file:

enable_sso = yes

If the hostname of the Linux server (see the hostname command) does not equal the FQDN of the Linux server, the server_hostname variable will need to be changed in the server.cfg file:

server_hostname = zarafa.linuxdomain.example

Restart the zarafa-server to activate all changes.

service zarafa-server restart Apache configuration (for SSO with WebAccess/WebApp)

Install the mod_auth_kerb/libapache2-mod-auth-kerb Apache module, e.g. for Red Hat:

yum install mod_auth_kerb

For Debian/Ubuntu: apt-get install libapache2-mod-auth-kerb

Open the vhost configuration of WebAccess/WebApp and add the following lines to the <Directory> directive:

<Directory /usr/share/zarafa-webapp>
  AuthType Kerberos
  AuthName "Kerberos Login"
  KrbMethodNegotiate On
  KrbMethodK5Passwd Off
  KrbServiceName HTTP
  Krb5KeyTab /etc/httpd/keytab.apache
  require valid-user

Set the filesystem permissions of the keytab file to 400 and change the owner to the Apache user:

chmod 400 /etc/httpd/keytab.apache
chown apache:apache /etc/httpd/keytab.apache

Restart Apache to activate all changes, e.g. for Redhat:

service httpd restart WebAccess/WebApp configuration

To setup a Single Sign On environment for Zarafa Collaboration Platform, it’s necessary to make a trust between the Apache webserver and the Zarafa Storage Server. The trust is necessary to manage the user authentication through the webserver and not anymore through Zarafa.

There are two ways to establish this trust. The first option is to have the system user running the Apache process acting as an administrator within Zarafa, which can only be recommended when Zarafa is running on the same systen and no other applications (for instance Z-Push) are running on the same server. The second option is to use ssl client certificates (see Creating SSL certificates) to establish this trust only for a specific web application. Using client certificates for authentication

To use ssl client certificates for authentication (see Creating SSL certificates) the client certificate has to be readable by the user of the webserver. Afterwards the DEFAULT_SERVER, SSLCERT_FILE and SSLCERT_PASS has to be changed in the config.php of WebAccess/WebApp.

// Default Zarafa server to connect to.
// When using a single-signon system on your webserver, but Zarafa is on another server
// you can use https to access the zarafa server, and authenticate using an SSL certificate.
define("SSLCERT_FILE", "/usr/share/zarafa-webapp/zarafa-client.pem");
define("SSLCERT_PASS", mypassword); Running the webserver as an administrator

To have the webserver act as an administrator, the user running the webserver process has to be added on the following line of the server.cfg:

local_admin_users = root apache

Typical users are apache for RHEL, www-data for Debian/Ubuntu and wwwrun for SLES.


This method will only work, when the WebAccess/WebApp is running on the same server as Zarafa.

Restart the zarafa-server processes to activate this change, e.g. for Red Hat:

service zarafa-server restart


Setting the webserver als local_admin_user will allow other applications running on the same server to log in with admin privileges as well. As passwords will no be checked for admin users this means, that user will be able to log in with any password! Common steps

As the passed user in Single Sign On environments also contains the domain/realm (e.g. user@domain), the WebAccess/WebApp has to remove this before logging in. This can be configured in the config.php file:

define("LOGINNAME_STRIP_DOMAIN", true); Browser configuration

Before Single Sign On can be used in a browser, configure the following settings:


  1. Type in the addressbar about:config
  2. Filter on auth
  3. Change the options: network.negotiate-auth.trusted-uris and network.negotiate-auth.delegation-uris to .testdomain.com

Internet Explorer

  1. Go to Tools > Internet options > Advanced
  2. Make sure the option Enable integrated Windows authentication is enabled
  3. Add the url of the Zarafa Server (http://zarafa.linuxdomain.example) to the Local Intranet sites.

Restart the browser and open the WebAccess via the FQDN (http://zarafa.linuxdomain.example). If the configuration is done correctly, the user will be logged in to the WebAccess without typing the username and password.

6.7.4. Up and running

Now that SSO seems to work with the Linux server, it will automatically be used by zarafa-server. Now log on to a Windows workstation on the domain and create a new Outlook profile for the user just logged on, but leave the password field empty. Outlook should create the profile without the password.

6.8. Tracking messages with Zarafa Archiver

This section provides information on how to track all incoming and outgoing messages using Zarafa’s Archiving technology. This can be useful in more strict e-mail environments where it’s important to be able to see what has been sent and received regardless of what the owner of the messages has done with them.

6.8.1. Archive on delivery

Archive on delivery is the process of making sure each message that is received will also be placed in each attached archive. If the message can not be archived it will not be delivered. Instead it will result in a temporary failure, causing the MTA to retry the deliver the message at a later time.

Archive on delivery is implemented by the zarafa-dagent process and can be controlled with the archive_on_delivery configuration option in the dagent configuration file.

For Archive on delivery to work, an archive configuration file needs to be present in the Zarafa configuration directory. In this configuration file settings for sslkey_file and sslkey_pass must me set to values such that Zarafa server can contact the archvier server sucessfully.

When a message is archived with the archive on delivery method, it will become a regular archive entry, meaning the normal rules apply. This means that if a user moves the message in the primary store, the message will also move in the archive. This includes moving to the trash folder.


When a message is deleted from the primary store, the message is not deleted from the archive. Instead it is moved to the special Deleted folder in the archiver.


Due to the current implementation of the Dagent messages that are moved by a rule will sadly be skipped during any subsequent archiving.

6.8.2. Archive on send

Archive on send is the process of making sure each message that is being send by the spooler will also be placed in each attached archive. If the message not be archived it will not be send. Instead it will return a failure message to the user.

Archive on send is implemented by the zarafa-spooler process and can be controlled with the archive_on_send configuration option in the spooler configuration file.


E-mail that is sent directly to an SMTP server (usually when using an IMAP account) will not be archived directly because the zarafa-spooler is not involved in the send process in this situation.

When a message is archived with the archive on send method, it becomes a detached archive. This means it has no reference to the original message in the primary store. There’s also no message in the primary store that will contain a reference to the archived message.


Unless disabled, messages in the sent items folder are archived as any other message. Extra storage is required because those message have also been archived by the spooler.

6.9. Zarafa Python plugin framework

The Zarafa Spooler and the Zarafa Dagent support the Zarafa python plugin framework. This framework makes it easier for advanced system administrators and developers to integrate systems with the spooler and dagent. The advanced system administrator and developer can easily add new functionality or change some behaviours of the existing system. The plugin framework is based on the programming language Python which means that you need to create your own hook in python.

6.9.1. How it works

If the plugin framework in the spooler or dagent is enabled it will search for python files in the directory plugin_path and look for a specific type of plugin. If the plugins are found it will be verified and loaded. Everytime the spooler or dagent is called it will execute the hooks based on priority. Plugins can validate and change a message on different stages of the spooler and dagent process.

6.9.2. General Options

The options for the python plugin framework are for every client the same except the file locations, see Table Python plugin framework options

Table 6.1. Table Python plugin framework options

Option Default Description
plugin_enabled yes Enable the plugin framework in the specfic component
plugin_manager_path /usr/share/zarafa-<co mponentname>/python Path to the plugin manager.
plugin_path /var/lib/zarafa/<comp onentname>/plugins Path to the activated plugins.

The value <componentname> can be dagent or spooler

6.9.3. How to use

After the installation of the component zarafa-dagent or zarafa-spooler, it is possible to activate a plugin. The default plugins are installed in the directory ‘/usr/share/zarafa-<componentname>/python/plugins/’. To activate a plugin, create a symbolic link in the plugin_path directory to the plugin which you want to activate. For example, to activate the disclaimer plugin in the spooler, run the following command:

ln -s /usr/share/zarafa-spooler/python/plugins/disclaimer.py \

6.9.4. Zarafa-DAgent plugins Move to public

The move to public plugin moves incoming messages to a folder in the public store.

Enable the move to public plugin, run the following command:

ln -s /usr/share/zarafa-dagent/python/plugins/movetopublic.py \

For this plugin is a config file required. Make a copy of the configuration file with the following command:

cp /usr/share/zarafa-dagent/python/plugins/movetopublic.cfg /etc/zarafa/movetopublic.cfg BMP2PNG converter

The BMP2PNG plugin converts a BMP to PNG in the incoming email. This plugin can be used to reduce the image size of the delivered email.

Enable the BMP2PNG plugin, run the following command:

ln -s /usr/share/zarafa-dagent/python/plugins/BMP2PNG.py \


The package python-imaging is required to use this plugin.

6.9.5. Zarafa-Spooler plugins Disclaimer

The disclaimer plugin add a disclaimer to every email sent with the Zarafa spooler.

The disclaimer plugin supports plain text and HTML emails. RTF emails are not supported. To use the disclaimer plugin, it is necessary to create the directory /etc/zarafa/disclaimers which must include the disclaimers. The plugin is using the following files for the disclaimer:

Table 6.2. Table Disclaimer files

Filename Description
default.txt The plain text version of the disclaimer
default.html The HTML version of the disclaimer
<companyname>.txt The plain text version of the disclaimer of a company
<companyname>.html The HTML version of the disclaimer of a company


All files must encoded in utf8

Enable the disclaimer plugin, run the following command:

ln -s /usr/share/zarafa-spooler/python/plugins/disclaimer.py \

6.9.6. Troubleshooting

How to troubleshoot issues you might have while installing or using the Python plugin framework in the Zarafa dagent and spooler. Log explanation

The Python plugin framework can log a lot of information, so if there are issues, it is recommended to set the log_level to 6. This will show all the information about the plugin framework.

Python error: No module named mapiplugin

The path to the plugin manager is invalid, this means the plugin framework can not be loaded and will result in the following error:

[TS] [id] PYTHONPATH = /usr/share/zarafa-dagent/python/Unknown_path
[TS] [id]   Python type: (null)
[TS] [id]   Python error: No module named mapiplugin
[TS] [id] Unable to initialize the dagent plugin manager

Check the path in plugin_manager_path should refer to the directory with the following files,

  • mapiplugin.py
  • pluginmanager.py
  • plugintemplates.py
  • wraplogger.py

Plugins not loaded

The path to the plugins directory is invalid or the permissions on the directory are invalid if this is the case you will receive the following error:

[TS] [id] * Loading plugins started
[TS] [id] ! Plugins directory '/invalid/path' doesn't exists. Plugins not loaded.

Check the path in plugin_path by default it refer to the directory ‘/var/lib/zarafa/dagent/plugins’, the permissions on the directory must atleast have read and execute permissions.

Python error: PySwigObject object has no attribute Log

There is an invalid version of MAPICore loaded. The old beta python-MAPI package installed the files in another directory but after removing the package the generated files are not removed after you start the dagent or spooler the old generated file is loaded an cause the following error:

<DATE> [id] PYTHONPATH = /usr/share/zarafa-dagent/python/
<DATE> [id]   Python type: (null)
<DATE> [id]   Python error: 'PySwigObject' object has no attribute 'Log'
<DATE> [id]   Python trace: /usr/share/zarafa-dagent/python/mapiplugin.py(13) __init__
<DATE> [id]   Python trace: /usr/share/zarafa-dagent/python/pluginmanager.py(16) loadPlugins
<DATE> [id]   Python trace: /usr/share/zarafa-dagent/python/wraplogger.py(16) logInfo
<DATE> [id] Unable to initialize the dagent plugin manager

To fix this issue remove the MAPICore.pyc files from your system. One of the locations can be /usr/lib/python2.6/dist-packages/MAPICore.pyc Problem - Solution

  • No plugins are loaded in the zarafa-dagent Does the plugin exist in the directory plugin_path by default in ‘/var/lib/zarafa/dagent/plugins’? If not, create a symlink to the plugin to activated or just copy the plugin into the directory.
  • No plugins are loaded in the zarafa-spooler Does the plugin exist in the directory plugin_path by default in ‘/var/lib/zarafa/spooler/plugins’? If not, create a symlink to the plugin to activated or just copy the plugin into the directory.

6.10. Running ZCP multi-server behind Reverse Proxy

Certain setups require that zarafa-server is not exposed directly to the internet. When offering Outlook access, it is sometimes needed to configure a reverse proxy so that Outlook users can connect to the reverse proxy and not directly to zarafa-server.

Setting up a reverse proxy with a single zarafa-server is quite easy and can be found in chapter 5.1.3 of this administrator manual, however when using a multi-server setup this is a completely different story. Due to the redirection protocol within Zarafa it is quite difficult to setup a reverse proxy for a MutliServer environment, however not impossible.

6.10.1. Description of redirection problem

With redirection the following problem may arise when using a reverse proxy:

  1. Outlook connects to a reverse proxy, and the reverse proxy connects to node Z1.
  2. Node Z1 will send a redirect for User2 to node Z2.
  3. Outlook tries to connect directly to node Z2, but this connection will break on the Firewall.


Therefore zarafa-server has some new options since version 7.1, which will make it easier to setup a reverse proxy for a multi-server environment.

In our new setup the reverse proxy will add extra header information, so the zarafa-server will detect that a connection is being made through a reverse proxy. When a connection is made through a reverse proxy (when the extra header is detected) Zarafa will not reply with the normal redirection string, but it will fetch the connection string from a new ldap attribute: ZARAFAPROXYURL.

Outlook will then still connect to the reverse proxy, even when a redirect command is given:

  1. Outlook connects to the reverse proxy, and the reverse proxy adds the extra header and connects to node Z1.
  2. Node Z1 detects the extra header and will send a redirect for User2 to node Proxy/Z2.
  3. Outlook will now connect again to the proxy, but with a different path /Z2. The proxy will now connect to Z2 so the store of User2 can be opened.


6.10.2. Setup Prerequisites

When setting up a reverse proxy for a multi-server setup using the new ZCP options, the following prerequisites need to be met:

  1. ZCP 7.1 or newer.
  2. OpenLDAP or ADS with the schema extensions from ZCP 7.1 or newer.
  3. A reverse proxy which fully supports HTTP/1.1 (make sure that also the transport encoding “Chuncked Encoding” is supported).

6.10.3. Example Setup with Apache

Apache 2.2 and newer fully supports HTTP/1.1 in the mod_proxy module.

In our example setup we will use an Apache setup which listens on port 237. In your Apache config you will need to add the following:

<IfModule mod_ssl.c>
   NameVirtualHost *:237
   Listen 237

We assume that you have created the correct certificates for Apache, so that Outlook is able to connect using SSL. Configuring Apache

In our example setup we will create a virtual host which is used for reverse proxying:

  1. /zarafa will be reverse proxied to node Z1 (Default connection is made to /zarafa)
  2. /z1 will be reverse proxied to node Z1 (When a redirection is made to node Z1)
  3. /z2 will be reverse proxied to node Z2 (When a redirection is made to node Z2)

In our Apache config we will setup this virtual host:

<VirtualHost *:237>
   ServerName zproxy.example.com
   SSLProxyEngine On

   ProxyPass /zarafa https://z1:237/zarafa retry=0
   ProxyPassReverse /zarafa https://z1:237/zarafa retry=0

   ProxyPass /z1 https://z1:237/z1 retry=0
   ProxyPassReverse /z1 https://z1:237/z1 retry=0

   ProxyPass /z2 https://z2:237/z2 retry=0
   ProxyPassReverse /z2 https://z2:237/z2 retry=0

   Header add zarafa_proxy "yes"
   RequestHeader set zarafa_proxy "yes"

   SSLEngine On
   SSLVerifyDepth 2

   SSLCertificateFile /path/to/WEB.CRT
   SSLCertificateKeyFile /path/to/WEB.KEY
   SSLCACertificateFile /path/to/CA.CRT

   CustomLog /var/log/apache2/zproxy.example.com-access.log combined
   ErrorLog /var/log/apache2/zproxy.example.com-error.log


When using Apache as a reverse proxy, it is advised to use Apache in a threaded model and not in a prefork model, as the threaded model is able to handle far more concurrent connections then the prefork model. Adding attribute to Servers

We assume you have installed the ZCP 7.1 or newer schema extensions.

In ldap add the attribute ZARAFAPROXYURL to all servers in the multi-server environment.

For node Z1 this will be:

ZARAFAPROXYURL: https://zproxy.example.com:237/z1

So the complete ldap record for node Z1 may look something like this:

objectClass: top
objectClass: zarafa-server
objectClass: device
objectClass: ipHost
ZARAFAFILEPATH: /var/run/zarafa
cn: z1
ZARAFAPROXYURL: https://zproxy.example.com:237/z1

For node Z2 this will be:

ZARAFAPROXYURL: https://zproxy.example.com:237/z2

So the complete ldap record for node Z2 may look something like this:

objectClass: top
objectClass: zarafa-server
objectClass: device
objectClass: ipHost
ZARAFAFILEPATH: /var/run/zarafa
cn: z2
ZARAFAPROXYURL: https://zproxy.example.com:237/z2 Configuring Zarafa Server

Now zarafa-server needs to be configured, so that it will send the correct redirect command when the proxy header is detected.

In this example we configured Apache to add the header “zarafa_proxy”, if a connection is being made through our reverse proxy.

On all the zarafa servers in the multi-server environment we will need to add an extra config option to the server.cfg:

proxy_header = zarafa_proxy

Zarafa-server will now send the ZARAFAPROXYURL as redirect string to the client when the header “zarafa_proxy” is detected.

However, internal (´behind´ the proxy) redirections must not be redirected to the proxy since this is not necessary. So any internal service will not connect to the reverse proxy, so the extra header is not added and zarafa-server will send the normal redirect string which is generated from the ldap database.

The proxy_header option can have different values:

  1. Empty: proxy_header option will not be used.
  2. [header]: zarafa-server will check for [header], when found zarafa-server send the ZARAFAPROXYURL as redirect string.
  3. *: will force zarafa-server to send the ZARAFAPROXYURL as a redirect string everytime a redirect command is given. With this value set, you do not need to add the extra header in your reverse proxy. However also internal (´behind´ the proxy) services will be redirected to the reverse proxy.