Zarafa Collaboration Platform 7.0 Administrator Manual en US
Zarafa Collaboration Platform 7.0 Administrator Manual en US
Zarafa Collaboration Platform 7.0 Administrator Manual en US
ZCP 7.0 (build 32167) Zarafa Collaboration Platform The Administrator Manual Edition 7.0
Copyright 2011 Zarafa BV. The text of and illustrations in this document are licensed by Zarafa BV under a Creative Commons AttributionShare 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 the 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 Research In Motion Limited 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 Research In Motion Limited. 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. 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:
1
4 1
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. This document, the Administrator Manual, describes how to install, upgrade, configure and maintain ZCP on your Linux server. In addition various advanced configurations and integration options are discussed.
http://www.zarafa.com/content/editions
1. Introduction 1.1. Intended Audience ....................................................................................................... 1.2. Architecture .................................................................................................................. 1.3. Components ................................................................................................................ 1.4. Protocols and Connections ........................................................................................... 1.4.1. SOAP ............................................................................................................... 1.4.2. Secure HTTP (HTTPS) ...................................................................................... 1.5. ZCP Editions and Licensing .......................................................................................... 1.5.1. The evaluation subscription ................................................................................ 1.5.2. The ZCP Community Edition .............................................................................. 1.5.3. Commercial Editions of ZCP .............................................................................. 1.5.4. Active and non-active users ...............................................................................
1 1 1 2 4 4 4 4 4 4 5 5
2. Installing 7 2.1. System Requirements .................................................................................................. 7 2.1.1. Hardware Recommendations ............................................................................. 7 2.1.2. Supported Platforms .......................................................................................... 7 2.1.3. Dependencies ................................................................................................... 8 2.2. Installation ................................................................................................................... 9 2.2.1. Installing ZCP with a Package Manager ............................................................ 10 2.2.2. Installing with the Install Script ......................................................................... 10 2.2.3. Manually Installing Packages ............................................................................ 11 2.3. Troubleshooting Installation Issues .............................................................................. 12 2.3.1. Server processes ............................................................................................. 12 2.3.2. WebAccess ..................................................................................................... 12 3. Upgrading 3.1. Preparing ................................................................................................................... 3.2. Creating backups ....................................................................................................... 3.3. ZCP7 dependencies ................................................................................................... 3.4. Performing the Upgrade on RPM based distributions .................................................... 3.5. Performing the Upgrade on Debian based distributions ................................................. 3.5.1. Pre 6.40 upgrade steps ................................................................................... 3.5.2. From 6.40 to 7.0.0 and higher .......................................................................... 3.6. Finalizing the upgrade ................................................................................................ 4. Configure ZCP Components 4.1. Configure the Zarafa Server ........................................................................................ 4.2. Configure language on RPM based distributions .......................................................... 4.3. Configure language on Debian based distributions ....................................................... 4.4. User Authentication .................................................................................................... 4.4.1. The DB Authentication Plugin ........................................................................... 4.4.2. The Unix Authentication Plugin ......................................................................... 4.4.3. The LDAP Authentication Plugin ....................................................................... 4.5. Autoresponder ............................................................................................................ 4.6. Storing attachments outside the database .................................................................... 4.7. SSL connections and certificates ................................................................................. 4.8. Configure the License Manager .................................................................................. 4.9. Configure the Zarafa Spooler ...................................................................................... 4.9.1. Configuration ................................................................................................... 4.10. Configure Zarafa Caldav ........................................................................................... 4.10.1. SSL/TLS ........................................................................................................ 4.10.2. Calendar access ............................................................................................ 4.11. Configure Zarafa Gateway (IMAP and POP3) ............................................................. 4.11.1. SSL/TLS ........................................................................................................ 15 15 15 16 16 17 18 19 20 23 23 24 24 25 25 25 26 26 27 28 30 30 31 31 33 33 34 36
Zarafa Collaboration Platform 4.11.2. Important notes .............................................................................................. 4.12. Configure Zarafa Quota Manager .............................................................................. 4.12.1. Setup server-wide quota ................................................................................ 4.12.2. Setup quota per user ..................................................................................... 4.12.3. Monitoring for quota exceeding ....................................................................... 4.12.4. Quota warning templates ................................................................................ 4.13. Configure Zarafa Indexer .......................................................................................... 4.13.1. Enabling indexing service ............................................................................... 4.13.2. Users, companies and servers ....................................................................... 4.13.3. Indexer configuration ...................................................................................... 4.13.4. CLucene configuration ................................................................................... 4.13.5. Attachments .................................................................................................. 5. Configure 3rd Party Components 5.1. Configure the Webserver ............................................................................................ 5.1.1. Configure PHP ................................................................................................ 5.1.2. Configure Apache ............................................................................................ 5.1.3. Apache as a HTTP Proxy ................................................................................ 5.2. Configure ZCP OpenLDAP integration ......................................................................... 5.2.1. Configuring OpenLDAP to use Zarafa schemas ................................................. 5.2.2. Configuring ZCP for OpenLDAP ....................................................................... 5.2.3. User configuration ............................................................................................ 5.2.4. Group configuration ......................................................................................... 5.2.5. Addresslist configuration .................................................................................. 5.2.6. Testing LDAP configuration .............................................................................. 5.3. Configure ZCP Active Directory integration .................................................................. 5.3.1. Installing the Zarafa ADS Plugin and schema files ............................................. 5.3.2. Configuring ZCP for ADS ................................................................................. 5.3.3. User configuration ............................................................................................ 5.3.4. Group configuration ......................................................................................... 5.3.5. Addresslist configuration .................................................................................. 5.3.6. Testing Active Directory configuration ................................................................ 5.4. ZCP Postfix integration ............................................................................................... 5.4.1. Configure ZCP Postfix integration with OpenLDAP ............................................. 5.4.2. Configure ZCP Postfix integration with Active Directory ...................................... 5.4.3. Configure ZCP Postfix integration with virtual users ........................................... 5.5. Configure Z-Push (Remote ActiveSync for Mobile Devices) ........................................... 5.5.1. Compatibility .................................................................................................... 5.5.2. Security ........................................................................................................... 5.5.3. Installation ....................................................................................................... 5.5.4. Mobile Device Management ............................................................................. 5.5.5. Upgrade .......................................................................................................... 5.5.6. Troubleshooting ............................................................................................... 6. Advanced Configurations 6.1. Running ZCP components beyond localhost ................................................................ 6.2. Multi-tenancy configurations ........................................................................................ 6.2.1. Support user plugins ........................................................................................ 6.2.2. Configuring the server ...................................................................................... 6.2.3. Managing tenant (company) spaces .................................................................. 6.2.4. Managing users and groups ............................................................................. 6.2.5. Quota levels .................................................................................................... 6.2.6. Administrator users .......................................................................................... 6.3. Multi-server setup ....................................................................................................... 6.3.1. Introduction ..................................................................................................... vi 36 36 36 36 37 37 38 38 38 39 40 41 43 43 43 43 44 45 45 45 46 47 47 48 49 49 51 51 52 53 53 54 54 55 57 59 59 59 59 61 61 61 63 63 64 64 64 67 67 68 69 69 69
6.4.
6.8.
6.3.2. Prepare / setup the LDAP server for multi-server setup ...................................... 6.3.3. Configuring the servers .................................................................................... 6.3.4. Creating SSL certificates .................................................................................. Zarafa Windows Client Updater ................................................................................... 6.4.1. Server-side configuration .................................................................................. 6.4.2. Client-side configuration ................................................................................... 6.4.3. MSI Options .................................................................................................... Running ZCP Services with regular user privileges ....................................................... Single Instance Attachment Storage ............................................................................ 6.6.1. Single Instance Attachment Storage and LMTP ................................................. Single Sign On with ZCP ............................................................................................ 6.7.1. NTLM SSO with ADS ...................................................................................... 6.7.2. NTLM SSO with Samba ................................................................................... 6.7.3. SSO with Kerberos .......................................................................................... 6.7.4. Up and running ............................................................................................... Tracking messages with Zarafa Archiver ...................................................................... 6.8.1. Archive on delivery .......................................................................................... 6.8.2. Archive on send ..............................................................................................
71 73 73 75 76 77 79 80 80 81 81 81 83 84 87 88 88 88 89 89 89 90 90 90 91 93 94 94
7. Managing ZCP Services 7.1. Starting the services ................................................................................................... 7.1.1. Stopping the services ...................................................................................... 7.1.2. Reloading service configuration ........................................................................ 7.2. Logging options .......................................................................................................... 7.3. Security logging .......................................................................................................... 7.3.1. Logging items .................................................................................................. 7.3.2. Configuration ................................................................................................... 7.4. Zarafa statistics monitoring ......................................................................................... 7.5. Soft Delete system .....................................................................................................
8. User Management 97 8.1. Public folder ............................................................................................................... 97 8.2. General usage of Zarafa-admin tool ............................................................................ 97 8.3. Users management with DB plugin .............................................................................. 99 8.3.1. Creating users with DB plugin .......................................................................... 99 8.3.2. Non-active users .............................................................................................. 99 8.3.3. Updating user information with DB plugin ........................................................ 100 8.3.4. Deleting users with DB plugin ......................................................................... 100 8.3.5. Configuring Send as permissions .................................................................. 100 8.3.6. Groups .......................................................................................................... 101 8.4. Users management with UNIX plugin ........................................................................ 102 8.4.1. Creating users with Unix plugin ...................................................................... 102 8.4.2. Non-active users ............................................................................................ 102 8.4.3. Updating user information with Unix plugin ...................................................... 102 8.4.4. Deleting users with Unix plugin ....................................................................... 103 8.4.5. Configuring Send as permissions .................................................................. 103 8.4.6. Groups with Unix plugin ................................................................................. 104 8.5. User Management with LDAP or Active Directory ....................................................... 104 8.5.1. The Zarafa user synchronization principle ........................................................ 105 8.5.2. User management from ADS .......................................................................... 107 8.5.3. User management from OpenLDAP ................................................................ 111 8.6. LDAP Condition examples ........................................................................................ 113 8.7. Zarafa Feature management ..................................................................................... 114 8.7.1. Globally enabling features .............................................................................. 114 8.7.2. Per-user en- or disabling features ................................................................... 114 vii
Zarafa Collaboration Platform 8.8. Resource configuration ............................................................................................. 8.8.1. Resource booking methods ............................................................................ 8.8.2. Meeting request (MR) booking ........................................................................ 8.8.3. Setting the resource booking method .............................................................. 8.9. Mailbox Storage Relocator ........................................................................................ 8.9.1. Prerequisites .................................................................................................. 8.9.2. Invokation ...................................................................................................... 8.9.3. Updating LDAP/ADS ...................................................................................... 8.9.4. Configuration ................................................................................................. 9. Performance Tuning 9.1. Hardware Considerations .......................................................................................... 9.1.1. Memory usage ............................................................................................... 9.1.2. Hardware considerations ................................................................................ 9.1.3. More Memory is More Speed ......................................................................... 9.1.4. RAID 1/10 is faster than RAID 5 ..................................................................... 9.1.5. High rotation speed (RPMs) for better database performance ............................ 9.1.6. Hardware RAID ............................................................................................. 9.2. Memory Usage setup ................................................................................................ 9.2.1. Zarafas Cell Cache (cache_cell_size) ....................................................... 9.2.2. Zarafas object cache (cache_object_size) ................................................ 9.2.3. Zarafas indexedobject cache (cache_indexedobject_size) ....................... 9.2.4. MySQL innodb_buffer_pool_size ........................................................... 9.2.5. MySQL innodb_log_file_size ................................................................. 9.2.6. MySQL innodb_log_buffer_size ............................................................. 9.2.7. MySQL query_cache_size ......................................................................... 9.3. Setup of modules on different servers ........................................................................ 10. Backup & Restore 10.1. Softdelete cache ..................................................................................................... 10.2. Full database dump ................................................................................................ 10.2.1. SQL dump through mysqldump ..................................................................... 10.2.2. Binary data dump via LVM Snapshotting ....................................................... 10.2.3. Attachments backup ..................................................................................... 10.3. Brick-level backups ................................................................................................. 10.3.1. Backup format ............................................................................................. 10.3.2. Backup process ........................................................................................... 10.3.3. Restore process ........................................................................................... 11. BlackBerry Enterprise Server 11.1. Prerequisites ........................................................................................................... 11.1.1. Software ...................................................................................................... 11.1.2. Authentication Preparation ............................................................................ 11.2. Installation steps ..................................................................................................... 11.3. BES Errors ............................................................................................................. 12. Appendix A; Pre-5.2x upgrade strategies 12.1. Database upgrades from 4.1 or 4.2 ......................................................................... 12.2. Upgrades from 5.0 to 5.1x and up ........................................................................... 12.3. Important changes since 4.x and 5.x ........................................................................ 13. Appendix B; LDAP attribute description 115 116 118 118 119 119 119 119 120 123 123 123 123 123 124 124 124 124 125 125 125 125 125 125 126 126 127 127 127 128 128 128 128 129 129 130 133 133 133 133 133 135 137 137 138 138 139
viii
Chapter 1.
Introduction
The Zarafa Collaboration Platform (ZCP) is an open source software suite capable of replacing Microsoft Exchange. Its architecture is very modular, makes use of standards wherever possible, and integrates with common open source components. This document explains how to perform the most common administrative tasks with ZCP.
Important
Although we, Zarafa, try our best to keep the information in this manual as accurate as possible, we withold the right to modify this information at any time, without prior notice.
1.2. Architecture
In accord with the UNIX philosophy, ZCP consists of components that each take care of a well defined task. See Figure 1.1, Zarafa Collaboration Suite Architecture Diagram which describes the relationships between the components and the protocols used. This diagram describes a simple setup as used by most of our customers. Only the most commonly used components are shown in the diagram. The top part of the diagram shows the clients: software appliances by which users access their data. Some of these appliances are desktop applications, some are mobile applications. In between The Internet and the Zarafa Server, the infrastructure components of Zarafa (blue) and some common infrastructure components (grey) can be found. These components are needed to facilitate communication between the Zarafa Server and various clients. Microsoft Outlook does not need any special infrastructure, but communicates directly with the Zarafa Server using the Zarafa Windows Client. The Zarafa Server is basically serving MAPI calls, while storing data in a MySQL database. For user authentication several methods are available (and discussed in this document), most common are servers that implement LDAP (e.g.: OpenLDAP, or Microsoft Active Directory). The next section briefly describes each of ZCPs components.
Chapter 1. Introduction
1.3. Components
Installations of the Zarafa Collaboration Platform (ZCP) may consist of the following components: 2
Components Zarafa Server (zarafa-server) The server process accepts connections for all clients through SOAP (HTTP), and stores the data in an SQL database. Zarafa License Manager (zarafa-licensed) The licensed process checks which features will be available dependent on the license chosen for the Community, Standard, Professional or Enterprise edition. Zarafa Windows Client The Zarafa client provides access to Outlook through an interface known as MAPI. The connections with the server are handled by SOAP. Zarafa WebAccess (zarafa-webaccess) A full featured web interface (with an Outlook look and feel) that enables users to collaborate from any computer with an internet connection. Zarafa Delivery Agent and Zarafa Spooler (zarafa-dagent, zarafa-spooler) The tools which serve the email communication with the outside world. The dagent delivers mail from the Mail Transport Agent (MTA) to a Zarafa user. The spooler sends mail waiting in the outgoing queue to the specified MTA. Zarafa Admin (zarafa-admin) The command line administration tool is used to manage users, user information and groups. Zarafa Gateway (zarafa-gateway) Optional service to provide POP3 and IMAP access to Zarafa users. Zarafa Monitor (zarafa-monitor) Service which monitors user stores for quota exceeds. Zarafa Caldav (zarafa-caldav) Optional service that provides iCal and CalDAV support. CalDAV is recommended due to speed and less data transfer. Zarafa Backup Tools (zarafa-backup, zarafa-restore) A brick-level backup tools to create simple backups of stores and to restore (part of) those backups on a later point in time. This part is only available in Zarafa commercial editions. Zarafa Indexer Optional service to provide full text indexing. This offers fast searching through email and attachments. Apache Serves web pages of the WebAccess to the users browser. PHP The WebAccess is written in this programming language. PHP-MAPI extension Module for PHP to enable use of the MAPI layer. Through this module, MAPI functions are made accessible for PHP developers. This effectively means that MAPI web clients can be written. The WebAccess is such a client. Python-MAPI extension Module for Python to enable use of the MAPI layer. Through this module, MAPI functions are made accessible for Python developers. For connectivity with mobile devices we recommend using Z-Push (see Section 5.5, Configure ZPush (Remote ActiveSync for Mobile Devices)), an open-source implementation of the ActiveSync protocol. For older mobile devices, and mobile devices that do not support the ActiveSync protocol we ship the Zarafa WebAccess Mobile (zarafa-webaccess-mobile) which provides basic web interface with limited functionality. Please note that this component is deprecated and will probably be removed from future version of ZCP.
1
http://z-push.sourceforge.net
Chapter 1. Introduction
1.4.1. SOAP
SOAP is an abbreviation of Simple Object Access Protocol. It is a protocol to exchange data and make Remote Procedure Calls between applications over a network or Internet for that matter. SOAP is based on XML and HTTP 1.1 (port 80, or port 443 in case of HTTPS). Because of these standards it is possible to connect transparently through proxies, allowing connectivity over most networks without modifications.
The Zarafa Collaboration Platform community edition is licensed under the Affero GPLv3 . This edition can be used with for up to three users with the proprietary Zarafa Windows Client (for connecting with Microsoft Outlook). The WebAccess, IMAP gateway and mobile synchronisation can be used for unlimited users.
http://www.zarafa.com/content/affero-gplv3
Note
To have Outlook support in the community edition the proprietary License Manager component must be running. A subscription is not needed though.
Note
Users are set active or non-active at the time of creation. It is only possible to convert active users to non-active users or vice-versa in ZCP version 6.40 and later: In earlier version the user must deleted and re-created as a different type.
Chapter 1. Introduction In LDAP setups the non-active flag of users can be controlled through the ldap_nonactive_attribute configuration directive. When using the DB back end, its possible to specify the non-active flag with the -n option when using zarafa-admin to create users. The Unix user plugin uses the unix-shell of the user as specified in /etc/passwd to determine if the store should be a non-active store.
Chapter 2.
Installing
2.1. System Requirements
2.1.1. Hardware Recommendations
To give an estimate on the resource use of ZCP we have created the table below. These are merely guidelines, giving a rough estimation on what hardware is required. In this table we assume the CPU is under low load from other applications. Table 2.1. Hardware Recommendations Size of all mailboxes < 5 GB > 5 - < 10 GB > 10 - < 20 GB > 20 - < 50 GB > 50 GB - < 100GB > 100GB - < 250 GB > 250 GB CPU* Dual Core Dual Core Dual Core Quad Xeon Quad Xeon Quad Xeon 2 x Quad Xeon Memory 1 GB 2 GB 2 GB 4 GB > 4 GB 16 GB 32 GB Harddisk SATA, SAS SAS SAS SAS SAS SAS SAS Raid level RAID1 RAID1 RAID1 RAID1 RAID1 RAID10 RAID10
Important
Support for the ia64 architecture will be dropped in the ZCP-7.x.x cycle
Table 2.2. Supported platforms for ZCPs back-end components OS Release RHEL 5 RHEL 6 SLES 10 SLES 11 Debian 5.0 (Lenny) Debian 6.0 (Squeeze) Supported CPU Architectures i386, x86_64, ia64* i686, x86_64 i586, x86_64, ia64* i586, x86_64, ia64* i386, x86_64, ia64* i386, x86_64 7
Chapter 2. Installing OS Release Ubuntu 8.04 LTS (Hardy) Ubuntu 10.04 LTS (Lucid) Supported CPU Architectures i386, x86_64 i386, x86_64
Besides these packages that are build and shipped by us, there are several platforms supported by 1 2 3 4 community build packages. For example Fedora , Mandriva, Gentoo , Arch Linux and OpenBSD . We also have packages in the Canonical Partner Repository. Please have a look at our wiki page on 5 this topic for more information. Table 2.3. Supported platforms for ZCPs Windows Client, Migration Tool and ADS Plugin MS Windows Release Windows Server 2003 Windows Server 2008 Windows XP Windows Vista Windows 7 Supported CPU Architectures 32bit, 64bit 32bit, 64bit 32bit, 64bit 32bit, 64bit 32bit, 64bit
These are the supported Microsoft Windows platforms the components that require a Windows platform, namely: the Windows Client, the Migration Tool and the ADS Plugin.
Note
The Migration Tool is currently not available for 64bit platforms.
Note
Outlook 2010 is still missing some features. For the progress of Outlook 2010 support, see http:// www.zarafa.com/wiki/index.php/Zarafa_Outlook_2010_Support.
2.1.3. Dependencies
In order to build or install ZCP back-end components a bunch of requirements have to be met. These are the main dependencies of ZCP:
1 2
Installation MySQL, without MySQL the Zarafa Server cannot run. No need to run on the same machine as the Zarafa Server, therefor not a package dependency. MySQL version 4.0 or lower will not work correctly. ZCP is tested with MySQL 4.1, 5.0 and 5.1. Apache or any other webserver that supports PHP. ZCP is tested with Apache 2.0 and 2.2. PHP, standalone as CGI or, preferably, as a webserver module. ZCP is tested with PHP 4.3.x and the latest 5.x release. Catdoc and Poppler-utils, for indexing text documents and pdf files. Libicu library that provides robust and full-featured Unicode and locale support. SMTP server of choice. ZCP is tested with Postfix, Exim, Sendmail and Qmail. LDAP server of choice (optional for user management). ZCP is tested with OpenLDAP, eDirectory and Microsoft Active Directory. Most of these dependencies are resolved automatically by the package manager of the Linux rd distribution that ZCP is being installed on. This allows the 3 party components used by ZCP to be installed and upgraded automatically through the package manager of the distribution. Some dependencies in the table above are runtime dependencies, these have to be installed manually as they do not necessarily have to run on the same machine. The default method of deploying ZCP is installing the packages on one of the Linux distributions we support, allowing the 3rd party components used by ZCP to be installed automatically through the rd package manager of the distribution. In this case the 3 party components are upgraded in a standard way according to that distribution.
Note
If youre using Debian or Ubuntu and youre starting with a fresh install of your server, you can use tasksel to easily install the entire LAMP (Apache, MySQL, PHP) stack. This will provide all the packages which are required for the Zarafa installation script to complete successfully.
2.2. Installation
There are roughly 4 ways to install ZCP: (1) through a distributions package manager, (2) using our install script, (3) manually installing packages, and (4) from source. In this section each of these methods is explained along with its pros and cons.
Note
In the community edition the package zarafa-licensed is not needed, though in order to have Outlook support in the community edition, it is necessary to run the zarafa-licensed daemon.
Note
The Multi User Calendar inside the package zarafa-webaccess-muc is a feature not available in the community edition. A valid subscription is needed.
Chapter 2. Installing
Note
The shared libraries which provide the user plugins are installed in /usr/lib64/zarafa, instead of the /usr/lib/zarafa location. This path has to be adjusted in the server.cfg configuration file. Set the plugin_path to /usr/lib64/zarafa, so the server can find the user plugin files.
After running install.sh, the server should be ready to start. Proceed with creating stores as explained by the script. In case the install.sh script is invoked with the -config parameter, it will not install any software but ask the configuration options only.
sh ./install.sh -config
The install.sh script always configures the server to use the DB user plugin. If another user base is neccesary, please read Chapter 4, Configure ZCP Components for information on how to configure the server.
10
Note
If an older version of ZCP is installed, please read Chapter 3, Upgrading. The install.sh script is not usable in this case.
Note
Do not mix packages of different distributions! Choose one distribution, and use only those packages. If this rule is not honored, errors will occur!
Replace <package file> with the packages found in the tarball. Start with libvmime, libical and zarafa (in this order) then install the other packages. The package manager might find unresolved dependencies, try to install packages for these dependencies as normal would be done for that distribution (yum -i on Red Hat, zypper -i on OpenSUSE/SLES).
To install the correct dependencies for ZCP apt-get or an equivalent tool can be used. For MySQL, use:
apt-get install mysql-server
If the Zarafa packages fail to install because of dependencies, please use the following command to install these dependencies:
apt-get -f install
If Apache with PHP support is installed after the Zarafa packages have been installed, please use the following command to automatically update the PHP configuration: 11
Chapter 2. Installing
dpkg-reconfigure zarafa
2.3.2. WebAccess
To correctly see the WebAccess, the following PHP-extensions are needed: gettext session iconv xml Some distributions deliver support for these extension by default through the PHP package. For SuSE distributions, these modules are provided by separate RPMs, eg:
php5-gettext-5.2.8-37.4.x86_64.rpm php5-iconv-5.2.8-37.4.x86_64.rpm
Versions may differ for newer versions of SUSE. For Red Hat Enterprise Linux and Debian-based distributions, these modules are provided by the normal php package which was already installed because of dependencies. If youre experiencing problems with sending attachments, make sure the webserver is able to create files under the WebAccess/tmp directory. If a user is directly logged off when he tries to login to the WebAccess, make sure PHP is configured with:
http://wiki.zarafa.com/
12
WebAccess
register_globals = off
If a distribution in combination with SELinux is used, an error message while logging in may appear when using the WebAccess. The default message suggests that the entered password is wrong or the Zarafa server is not running. When SELinux is enabled, it is blocking the connection from the webserver to the Zarafa server. The SELinux Zarafa policy to allow this can be found on http:// www.zarafa.com/wiki/index.php/Zarafa_Selinux_policy. or SELinux can be disabled by using the following command:
setenforce permissive
When it is chosen to disable SELinux, /etc/sysconfig/selinux also has to be edited, to disable it for after reboots too. More SELinux information can be found on http://fedora.redhat.com/docs/selinux-faq.
13
14
Chapter 3.
Upgrading
3.1. Preparing
Before upgrading to a new version of ZCP, it is recommended to make a backup of the database and the configuration files.
Note
When upgrading a licensed version of ZCP to a new major release, like from 6.40.x to 7.0.x, the 1 license key has to be converted. Converting subscription keys is performed on our portal .
First stop the MTA server running on your server. Should there be errors during the upgrade no e-mail will get lost. In case of postfix, run:
/etc/init.d/postfix stop
Now stop the running services, so the database is not in use anymore:
/etc/init.d/zarafa-spooler stop /etc/init.d/zarafa-server stop /etc/init.d/zarafa-licensed stop
Important
When the attachments are kept in the database, an upgrade to 6.30.x or later will grow the database storage file by the combined size of all attachments (as stored in the lob table). During the upgrade a temporary table to store all attachments is created and removed, since it is not possible to shrink the database storage file it will grow by the combined size of the attachments stored in it. Information on migrating the attachments from the database to the file system can be found on 2 our wiki .
https://portal.zarafa.com/ http://www.zarafa.com/wiki/index.php/Store_attachment_outside_of_the_database
15
Chapter 3. Upgrading
cp -r /etc/zarafa /etc/zarafa.bck
Note
In the community edition the package zarafa-licensed is not needed. Only when Outlook integration is used the zarafa-licensed daemon is required.
16
Performing the Upgrade on Debian based distributions After the new packages are installed, the example configuration files found in the /usr/share/ doc/zarafa/example-config directory can be checked for new configuration options. The new 3 changes can also be found in the Release Notes .
For Debian based installations run the following command to upgrade the ZCP installation:
dpkg -Bi <package name>
Depending on the set of 6.x packages you may have installed, this command may end with errors on the zarafa and zarafa-licensed packages. Due to the big split and renaming of packages some conflicts are not directly resolvable by dpkg. If you receive any errors during the upgrade of these packages, a second try installing these packages using:
dpkg -i <package name>
which should resolve everything properly. When prompted about changed zarafa configuration files it depends greatly on you current situation what the best option is.
Note
In the community edition the package zarafa-licensed is not needed. Only when Outlook integration is used the zarafa-licensed daemon is required.
After the new packages are installed, the example configuration files found in the /usr/share/ doc/zarafa/example-config directory can be checked for new configuration options. The new 4 changes can also be found in the Release Notes .
3 4
http://doc.zarafa.com/trunk/Release_Notes/en-US/html/_config_file_changes.html http://doc.zarafa.com/trunk/Release_Notes/en-US/html/_config_file_changes.html
17
Chapter 3. Upgrading
Note
When using OpenLDAP there is no need to change the ldap_user_unique_attribute.
The send-as options in LDAP are the opposite from 6.30 as of 6.40 and 7.0. This change is done to support groups for the sendas permissions. If the send-as options for users are used, the ldapswitch-sendas.pl script must be run. This script will update the LDAP or ADS server with the current send-as information and switches it to the 6.40 format.
cd /usr/share/doc/zarafa chmod 755 ldap-switch-sendas.pl ./ldap-switch-sendas.pl
In 6.40, send-as permissions are set on the user. Example: A non-active user info@company exists and some users need to send with that address in the from header. The users are added on the info@company object in the send-as attribute list. In the LDAP configuration, the separate search base options for each object are combined in one search filter option named ldap_search_base. All other old search_base options should be removed. Also, all scope options should be removed. Next, object types must be defined. This normally done by means of the objectClass attribute. Every user object must be defined by its objectClass. Lastly, the old per object search filters may be emptied since they are double. It is still advisable to use zarafaAccount in the user filter, so the options are still available. To protect the server from deleting users a safe mode option is available in the server.cfg. Enabling this option will disable all delete and create actions of users and groups. Add the following option in the /etc/zarafa/server.cfg to enable safe mode:
5
http://www.zarafa.com/wiki/index.php/Upgrading_to_6.40/
18
user_safe_mode = yes
Check the server logfile after starting the Zarafa Server for detection of user changes. If no users are recreated or deleted the configuration file is correct and user_safe_mode can safely be disabled.
Important
Its strongly advised only to use the safe_mode after the upgrade. When the upgrade is successfully done, the safe_mode should be disabled. Running a production system with safe_mode enabled can result in performance issues.
Important
Please make sure your MySQL server innodb settings are optimized. For more information about important MySQL tuning parameters, see Chapter 9, Performance Tuning.
To upgrade the database its recommended to use the zarafa7-upgrade tool that comes with the zarafa-server package in ZCP 7.0. This upgrade tool will perform the necessary upgrade steps and will keep you informed about the progress. The zarafa7-upgrade tool can be found in /usr/share/doc/ zarafa and requires the python-mysqldb or MySQL-python package, as well as the python-mapi packages. That last one can be found in the ZCP tarball. Restart the Zarafa-server to convert the database to latest revision.
/etc/init.d/zarafa-server start
When the database is in the correctly converted into the latest 6.40 layout, the Zarafa-server will automatically stop and warn that the update should be executed manually with zarafa7-upgrade script. Run the script zarafa7-upgrade to convert the database layout and make the database unicode ready. To run the upgrade tool use: 19
Chapter 3. Upgrading
python /usr/share/doc/zarafa/zarafa7-upgrade
This script will convert all database tables to UTF-8 to be fully unicode compatible and will convert the database tables to new ZCP 7.0 layout. The script will report the progress of the update. Alternatively the server can be forced to upgrade the database by starting it with the --force-databaseupgrade option.
Important
Using the --force-database-upgrade option is not recommended as it has no progress indication and it can not be interrupted.
Note
When upgrading from older versions of ZCP, for example ZCP 6.30.x, the Zarafa-server will first upgrade the database to the ZCP 6.40 layout and after this update the upgrade script can be executed.
Note
In the community edition the package zarafa-licensed is not needed, though in order to have Outlook support in the community edition, the zarafa-licensed daemon has to run. Since upgrades usually include a changed php-mapi extension, the webserver has to be restarted as well:
20
/etc/init.d/apache2 restart
ZCP 7.0 has a new improved IMAP/POP3 gateway. The new gateway offers better compatibility and higher performance by using additional information which is stored in the database and in the Zarafa attachment directory. As this addition information will use more diskspace and is only used when users are connecting over IMAP, the IMAP/POP3 features are by default disabled. When users should have access to IMAP or POP3 this features has to manually enabled. Read more about enabling/disabling features in Section 8.7, Zarafa Feature management.
21
22
Chapter 4.
The options and their default values are explained both by the in-line comments of the example file and in the following manual page:
man <component name>.cfg
For example:
man zarafa-server.cfg
If a line is not present, the default setting will be assumed. For most basic setups the defaults of the example file will work fine. In this chapter we only explain the basic configuration option of Zarafa Server. The Zarafa Server needs a MySQL database to function, and therefor needs to know how to connect to the MySQL server and the authentication credentials for its database. It will create a database and the tables it needs at first start. Make sure that the MySQL user that the Zarafa Server uses to connect to the database has all privileges, including the right to create a new database. The privilege to create databases could be revoked after the database has been created by the server. Also make sure to give the user enough permissions to connect from localhost to this database, or --if the Zarafa server connects over the network to the MySQL database-- allow it to connect from the IP-address from which the Zarafa Server will connect. For example the following MySQL statement grants all privileges to user zarafa with password password from localhost:
GRANT ALL PRIVILEGES ON zarafa.* TO 'zarafa'@'localhost' IDENTIFIED BY 'password';
23
Chapter 4. Configure ZCP Components To configure the Zarafa Server to use the MySQL server the options starting with mysql in the zarafa-server.cfg need to be set. Once this is setup the Zarafa Zerver should start normally.
Change the option ZARAFA_USERSCRIPT_LOCALE to the correct language, for example nl_NL.UTF-8 or fr_FR.UTF-8. In order to use this language setting make sure the language packs are installed. Red Hat and SuSE based systems contain all language packs by default, but Debian and Ubuntu based systems do not contain these packages. The option ZARAFA_LOCALE in the /etc/sysconfig/zarafa file can be used to start the Zarafa Server component in the correct language. This language setting is used to set the default options, like the Public Folder name to the correct language. The WebAccess GUI language can be set at the login screen. This can be configured per user login.
Important
When upgrading from an earlier ZCP version, please review the language settings as from ZCP 7.0.0 the locale has to be set in UTF-8.
Change the option ZARAFA_USERSCRIPT_LOCALE to the correct language, for example nl_NL.UTF-8 or fr_FR.UTF-8. In order to use this language setting make sure the language packs are installed. Red Hat and SuSE based systems contain all language packs by default, but Debian and Ubuntu based systems do not contain these packages. To install a language pack on Debian and Ubuntu based systems, use the following command (this example is for the Dutch -nl pack):
apt-get install language-pack-nl
The option ZARAFA_LOCALE in the /etc/default/zarafa file can be used to start the Zarafa Server component in the correct language. This language setting is used to set the default options, like the Public Folder name to the correct language. 24
User Authentication The WebAccess GUI language can be set at the login screen. This can be configured per user login. For non-English WebAccess languages the appropriate language-packs need to be installed as well.
Important
When upgrading from an earlier ZCP version, please review the language settings as from ZCP 7.0.0 the locale has to be set in UTF-8.
At some debian distributions the entry in /etc/apache2/envvars needs to be set to force the locale, else locale specific characters might not be displayed correctly in the webaccess.
## The locale used by some modules like mod_dav # export LANG=C ## Uncomment the following line to use the system default locale instead: . /etc/default/locale
Chapter 4. Configure ZCP Components A configuration file, /etc/zarafa/unix.cfg, exists for this plugin. The default set by this file are usually enough, in-line comments explain each option. In this configuration file the uid range of users wanted in the Zarafa server needs to be defined. The same goes for the groups. Non-active users are appointed by a specific shell, default /bin/false. These users cannot login, but the stores can be opened by other users. An administrator should setup the correct access rights for these stores. For an overview of all configuration options of the unix authentication plugin, use:
man zarafa-unix.cfg
The defaults for OpenLDAP and for Active Directory can be found in the /usr/share/doc/zarafa/ example-config directory. Based on these examples the /etc/zarafa/ldap.cfg file should be adjusted to configure the LDAP authentication plugin. More details about configuring the LDAP plugin with OpenLDAP, see Section 5.2, Configure ZCP OpenLDAP integration or Section 5.3, Configure ZCP Active Directory integration for Active Directory.
4.5. Autoresponder
ZCP contains an autoresponder that can be used when a user is out of the office to reply automatically to all incoming e-mails. The autoresponder will automatically be spawned whenever an e-mail is delivered by zarafa-dagent to a store that has the Out of Office option turned ON. Users can manage the autoresponder of their own store as well as of stores to which one has at least secretary rights. Note that this includes public folders. Please refer to the User manual on how to manage these settings. To prevent autoresponder loops (e.g. when sending automated responses to an automated response, which in turn sends an automated response, etc), the autoresponder will only send one autoresponse message per day for any unique sender e-mail address. The autoresponder will also not respond in any of the following cases: 26
Storing attachments outside the database Sending an out-of-office message to yourself. Original message was to mailer-daemon, postmaster or root. Original message was from mailer-daemon, postmaster or root. Furthermore, the autoresponder is configured by default to respond only to e-mails in which the user was explicitly mentioned in the To header. This means that e-mails that were received because the user was in the Cc header or because the user was in a distribution group, are not responded to. Most behaviour can be configured by editing the file /etc/zarafa/autorespond. This file contains the following settings, which will be used for all autorespond messages server-wide:
AUTORESPOND_CC=0
Set this value to 1 to allow autoresponding to messages in which the recipient was only stated in the Cc header.
AUTORESPOND_NORECIP=0
Set this value to 1 to autorespond to all messages, even if the recipient is not stated in any header (for example when the email was directed at a mailing list or group)
TIMELIMIT=$[24*60*60]
Sets the minimum number of seconds between autoresponses to the same e-mail address The following settings normally do not need to be modified:
SENDDB=${TMP:-/tmp}/zarafa-vacation-$USER.db
(file which stores the last date of sending per email address)
SENDDBTMP=${TMP:-/tmp}/zarafa-vacation-$USER-$$.tmp
(parameters used to send actual vacation message) If an alternate autoresponder is required, please refer to the zarafa-dagent manual page which describes how to use an alternate script (using the -a option).
Chapter 4. Configure ZCP Components For first time installations, the attachment storage method should be selected before starting the server for the first time as it is not easy to switch the attachment storage method later on. To change the attachment storage location, edit the following option in the /etc/zarafa/ server.cfg.
attachment_storage = files attachment_path = /var/lib/zarafa
For upgrades, a script exists that copies the attachments from the database to the file storage. This script can be found in /usr/share/doc/zarafa, and is named db-convert-attachments-tofiles. This script is run as follows:
db-convert-attachments-to-files <mysqluser> <mysqlpass> <mysqldb> <destination path> [delete]
It is only possible to convert from database storage to file storage. The <delete> switch is optional. If this parameter is given, the attachments are also removed from the database. Keep in mind that during the conversion the storage of the attachments on the harddisk will double. The amount of storage in MySQL used by ZCP can be looked up the with the following MySQL statements:
mysql> use zarafa; mysql> show table status;
Check the data_length column for the lob table. This contains the number of bytes needed for the attachment storage. To select this new storage method, change the attachment_storage option in the server.cfg file and point the attachment_path option to the folder where the attachments should be stored. After changing this option zarafa-server needs to be started once with the --ignore-attachmentstorage-conflict parameter. Advantages of attachments outside the database are: MySQL does not save the large binary blobs in the database. This improves the general read and write access. Attachments will not cause cache purges of MySQL. Disadvantages of attachments outside the database are: A MySQL dump of the database is not enough for a full recovery. Remote storage of attachments requires a new system, like folder mounted through NFS or Samba. In most cases it is advisable to store attachments apart from the database, especially in setups with more then 50 users.
Important
It is very important, when choosing to store the attachments outside the database, to update the backup strategy accordingly.
SSL connections and certificates This feature may already be available when the HTTPS Apache server is setup to proxy these connections to the Zarafa Server. However, having native SSL connections to the server has an interesting advantage: Zarafa components running beyond localhost can login using their SSL certificate. This section will describe how to setup certificates to add native SSL connections to Zarafa. First, we will create the directory to contain the certificate and setup the permissions, since it contains our private key.
mkdir /etc/zarafa/ssl chmod 700 /etc/zarafa/ssl
If Zarafa is run as another user, as described in the Running as non-root user section, do not forget to chown the directory as well. Now we are ready to create a Certificate Authority (CA). This CA will be used to create the server certificate and sign it. We provide a ssl-certificates.sh script in the /usr/share/doc/ zarafa directory, which uses the openssl command and the CA.pl script from OpenSSL. Depending on the distribution used this script can be installed in different directories. The script will try to find it on its own. If it is not found, either OpenSSL is not installed, or the script is in an unknown location, and location of the script has to be provided manually. Normally, the sslcertificates.sh script can be run without problems.
cd /etc/zarafa/ssl sh /usr/share/doc/zarafa/ssl-certificates.sh server
The parameter server is added, so the name of the new certificate will be called server.pem. When the CA is not found in the default ./demoCA directory, it needs to be created. By pressing enter, the creation of the new CA is started. Enter a password (passphrase) when asked for. This is the password used later on to sign certificate requests. Then certificate information should be entered. Do not leave the Common Name field blank, otherwise the creation will fail. Now that we have a CA, we can create self-signed certificates. The ssl-certificates.sh script will automatically continue with this step. Enter a password for the request, and enter the certificate details. Some details need to be different from those typed when the CA was created. At least the field Organizational Unit Name needs to be different. The challenge password at the end may be left empty. This step created a Certificate Request, that needs to be signed by the CA that was created in the first step of the script. Type the password of the CA again when asked for. The details of the certificate will be shown, and asked for acceptance. Accept the certificate. As the last step, the public key of this certificate will be offered. Since the server certificate just was created the public key of this certificate is not needed. Now that the the CA certificate and the server certificate have been created, SSL can be enabled in the server.cfg file, which is normally disabled. The port 237 is set for SSL connections. This port number can be changed if necessary.
server_ssl_enabled = yes server_ssl_port = 237
29
Chapter 4. Configure ZCP Components The CA certificate must be set in the server_ssl_ca_file setting. The server certificate and password must be set in the server_ssl_cert_file and server_ssl_cert_pass options.
server_ssl_ca_file = /etc/zarafa/ssl/demoCA/cacert.pem server_ssl_key_file = /etc/zarafa/ssl/server.pem server_ssl_key_pass = <password>
Restart the zarafa-server process, and now its possible to connect directly to the SSL port. Create a new Outlook profile, and mark the SSL connection option. Set the port to 237. The connection to the server has now been encrypted.
The License Manager (zarafa-licensed) expects /etc/zarafa/license to contain a file named base which simply holds the license key. To install a license key, use the following command:
mkdir -p /etc/zarafa/license echo <license key> > /etc/zarafa/license/base
<license key> should be replaced with a valid license key obtained from Zarafa or one of its partners.
Note
The license key consists only of numbers and capital letters.
If an extra CAL (Client Access License) is also available, the license key can be added with:
echo 'CAL key' > /etc/zarafa/license/cal1
If more than one CAL are available, please install one CAL per file in the license directory. The filename of the CAL is of no importance. Sub-folders in the /etc/zarafa/license folder are not allowed.
Configuration The spooler will send the email, and after the mail is sent, will move the mail automatically to the users Sent Items folder. If at any time an error was found, the user will be notified with an Undeliverable message. The message will contain an error description on which error was found. Often, the user can retry to send the message.
Note
Both external and internal emails will be sent via the MTA.
4.9.1. Configuration
The Spooler is configured the same as the server. Options in the spooler configuration file are the name or ip-address of the SMTP server, where to find the Zarafa server, and logging options.
smtp_server
The name or IP-address of the SMTP server, which will send the email to the destination. This server may also be given as an argument when starting the spooler.
server_socket
The UNIX socket of the Zarafa server. The spooler will use this socket to create a connection to the server. This value should be the same as set in the server configuration file. The default value is / var/run/zarafa.
[logging]
The spooler has the same configuration options as the server to configure logging options. For an overview of all the configuration options of the zarafa-spooler, use:
man zarafa-spooler.cfg
IP address to bind to. 0.0.0.0 for any address. Default value: 0.0.0.0 31
ical_enable
The plain service will listen on this port for incoming connections. Default Value: 8080
icals_enable
The secure service will listen on this port for incoming connections. Default value: 8443
server_socket
Important
It is not advised to specify the UNIX socket here. In default configuration the Zarafa Caldav will then be trusted by the zarafa-server (as set in its local_admin_users configuration setting). Unless Zarafa Caldav is specified to run as an untrusted user, it always authenticates users even if they provide no or wrong credentials!
ssl_private_key_file
The file that contains the private key used for encrypting the ssl connections. The absolute path to the file should be used. Default value: /etc/zarafa/privkey.pem
ssl_certificate_file
The file that contains the certificate for the server. The absolute path to the file should be used. Default value: /etc/zarafa/cert.pem
ssl_verify_client
The file or path to the files to verify the clients certificate with. The absolute path should be used for both options (no default).
[logging]
The Caldav component has the same configuration options as the server to configure logging options. 32
SSL/TLS
4.10.1. SSL/TLS
As mentioned before the Zarafa Caldav component supports SSL/TLS, for this the OpenSSL library is used. The private key (for encryption) and the certificate (for authentication) file can be set in the configuration file with ssl_private_key_file and ssl_certificate_file. The Zarafa Caldav component can also authenticate the calendar clients that try to connect to it verifying the client certificates using one or more verification files. This can be set with ssl_verify_client, ssl_verify_file and ssl_verify_path. Certificates can be self-signed or signed by a trusted certificate authority. The following command generates an RSA key of 2048 bytes:
openssl genrsa -out /etc/zarafa/privkey.pem 2048
If a .cer file and a .key file are already present, you can create a .pem file from these using the following command:
cat my_server.key > my_server_combined.pem cat my_server.cer >> my_server_combined.pem
And then use the my_server_combined.pem file for ssl_private_key_file or ssl_certificate_file. Please make shure first the .key file is processed, and then the .cer file.
Table 4.2. CALDAV and iCal URLs for MAC OSX iCal client URL For MAC OSX iCal client http://server:8080/caldav/ Calendar Users calendar list
33
Chapter 4. Configure ZCP Components URL For MAC OSX iCal client http://server:8080/caldav/<otheruser> http://server:8080/caldav/public Calendar Other-users calendar list Public folders list
Note
The <other user> or <user>/<calendar> is only reachable if the correct permissions are available.
Note
The Mac OS X iCal client is fully tested and supported up to 10.5.6. Additional information regarding client side setup can be found in the Zarafa User Manual.
IP address to bind to. 0.0.0.0 for any address. Default value: 0.0.0.0
imap_enable
The IMAP service will listen on this port for incoming connections. Default Value: 143
imaps_enable
The secure IMAP service will listen on this port for incoming connections. Default value: 993
pop3_enable
34
Configure Zarafa Gateway (IMAP and POP3) Enable POP3 service with value yes. Default value: yes
pop3_port
The POP3 service will listen on this port for incoming connections. Default value: 110
pop3s_enable
The secure POP3 service will listen on this port for incoming connections. Default value: 995
imap_only_mailfolders
Enable only mailfolders to be shown with value yes. Default value: yes
server_socket
Important
It is not advised to specify the UNIX socket here. In default configuration the Zarafa Gateway will then be trusted by the zarafa-server (as set in its local_admin_users configuration setting). Unless Zarafa Gateway is specified to run as an untrusted user, it always authenticates users even if they provide no or wrong credentials!
ssl_private_key_file
The file that contains the private key used for encrypting the ssl connections. The absolute path to the file should be used. Default value: /etc/zarafa/privkey.pem
ssl_certificate_file
The file that contains the certificate for the server. The absolute path to the file should be used. Default value: /etc/zarafa/cert.pem
ssl_verify_client
The file or path to the files to verify the clients certificate with. The absolute path should be used for both options (no default).
[logging]
The gateway has the same configuration options as the server to configure logging options. 35
4.11.1. SSL/TLS
The Zarafa Gateway supports SSL/TLS using the OpenSSL library. For more information see Section 4.10.1, SSL/TLS, as the options are exactly the same for these two components.
The values are all in megabytes. These values will be honored for all users present in the server. When the values are set to 0, that particular quota level is disabled.
zarafa-admin
-u john
--qo 1
--qw 80
--qs 90
--qh 100
Note
Set user quota with zarafa-admin does not work with LDAP. With LDAP the properties are stored in the LDAP server per user. See the Chapter 8, User Management for more information.
or
zarafa-monitor -c /etc/zarafa/monitor.cfg
The zarafa-monitor will daemonise, so the prompt will almost immediately return. Use -F to start it in the foreground. More information about the configuration options can be found in the manual page:
man zarafa-monitor.cfg
Chapter 4. Configure ZCP Components ZARAFA_QUOTA_WARN_SIZE - The quota warning limit for the user or company. ZARAFA_QUOTA_SOFT_SIZE - The quota soft limit for the user or company. ZARAFA_QUOTA_HARD_SIZE - The quota hard limit for the user or company.
Note
Variables containing a size always include the size unit (B,KB,MB,GB) as part of the variable.
During searching the zarafa-server will connect with the zarafa-indexer service. To set the connection path change the following configuration option:
index_services_path = file://var/run/zarafa-indexer
All user names which should not be indexed should be added to this configuration option. Each name must be separated with a single SPACE character. Similarly all users from specific companies can be excluded from indexing:
index_block_companies =
Again all companies which should be excluded must be separated with a single SPACE character. For multiserver installations the filter works reversed. Each server which must be indexed must be configured using the option: 38
Indexer configuration
index_allow_servers
If this option is empty, all servers within the environment will be included by the indexing service. All server names must be separated by a single SPACE character.
Note
Normally only a single zarafa-indexer instance is needed for a multiserver environment. For performance it is possible to run multiple instances on multiple servers. By using using index_allow_servers correctly it is possible to divide the tasks over the different zarafaindexer instances.
Beneath this folder a subfolder will be created for each Zarafa server within the environment. Beneath these folders, each store will receive its own folder containing the index files.
Important
Files and folders within this index path should not be touched while the indexer is running. If a store must be re-indexed, the zarafa-indexer must be halted first before deleting the folder for that particular store.
The zarafa-indexer service can use streaming synchronization offered by the zarafa-server for fast synchronization of messages at the expense of higher memory consumption. To enable streaming, ensure that the configuration option is enabled:
index_sync_stream = yes
If this option is enabled, the enhanced ICS option in /etc/zarafa/server.cfg must be enabled as well:
enable_enhanced_ics = yes
These options are both enabled by default, and normally there is no reason to disable them. The indexing interval can be configured in /etc/zarafa/indexer.cfg:
index_interval = 5
This interval should be provided in minutes. When this value is increased the delay between receiving the mail and its visibility in search results will also be increased. The indexing of stores can be divided over multiple threads when working on a multiserver environment. The number of index threads can be configured by changing the configuration value:
index_threads = 1
39
Chapter 4. Configure ZCP Components Each thread will only index the stores from a single Zarafa server. The number of threads will thus never exceed the number of servers within the multiserver environment. For single server environments, this value should be kept at 1.
This value is used to control the amount of required memory during the indexing process. When index_max_field_length value is increased, the more memory will be required during indexing. The merge factor indicates the number of index file segments per store before CLucene merges the segments into a single file.
index_merge_factor = 10
A low value will cause less memory to be used during indexing, but the increased IO access to disk causes the indexing process to be slower, while searching will be faster. A high value will speed up the indexing process while searching will be slower. For batch indexing, the index_interval option is set to a high value. In that case, set index_merge_factor to a high value (> 10) as well. For more interactive indexing, where the index_interval is set to a low value, the index_merge_factor should be set to a low value (< 10). The maximum buffered documents controls the maximum number of documents kept in memory before CLucene writes them into a new index file segment on the harddisk.
index_max_buffered_docs = 10
Larger values will increase memory usage but makes the indexing process faster. Larger values also mean that less index segments will be written to disk, which controls how often the segments will be merged (also depending on the index_merge_factor configuration option). The minimum number of messages in a single store which are indexed in memory before the index writer flushed the index to disk as a new index file is controlled using the index_min_merge_docs option:
index_min_merge_docs = 10
Creating new index file segments often increases IO access to disk but reduces the amount of memory required during the indexing process. The maximum number of documents which can exist in a index file segment, can be controlled by the index_max_merge_docs option:
index_max_merge_docs = 2147483647
40
Attachments When a segment contains index_max_merge_docs documents, it will no longer be merged with other index segments. This will limit the total size of an index file segment but will trigger more index file segments to be created. For batch indexing (when index_interval is set to a high value), the index_max_merge_docs should be set to a high value as well (>10000). For interactive indexing (when index_interval is set to a low value), set index_max_merge_docs to a low value (<10000). The fraction of terms in the dictionary which should be stored in memory is controlled by the index_term_interval configuration option.
index_term_interval = 128
Smaller values use more memory, but make searching slightly faster, while larger values use less memory and make searching slightly slower. Searching is typically not dominated by dictionary lookup, so tweaking this is rarely useful. All CLucene writers and searchers are cached to optimize performance at the expense of memory. The time (in seconds) the objects will be kept in cache is controlled by the index_cache_timeout option:
index_cache_timeout = 0
4.13.5. Attachments
Optionally the contents of attachments can be indexed as well. When this is enabled, when searching through the body of a message, the contents will be searched through as well. To enable indexing of attachments can be done in /etc/zarafa/indexer.cfg:
index_attachments = yes
Indexing of attachments is done through parsing the attachments to plain text and indexing the text into the main index for the email. The required time to parse and index a particular attachment depends on the actual size of the attachment. To prevent large attachments adding latency to the total indexing time, the configuration option index_attachment_max_size can be used to prevent large attachments to be indexed. The value provided to this configuration option must be set in kilobytes. To parse the attachments to plain text a separate configuration script must be provided. By default this script is installed to /etc/zarafa/scripts/attachments_parser but the exact location can be configured using the configuration option index_attachment_parser. The script attachments_parser will use the file attachments_parser.db to decide how the attachment should be parsed to plain text. Within this file is a list containing the command to parse each attachment type to plain text. This file can be edited to control the way attachments are parsed and to add or remove support for particular attachment types. The layout of each line is as followed:
<mime-type>;<extension> `<command>`
Each line can have as many mime-types and extensions as needed, each mime-type and extension must be separated using semi-columns. The command must read /dev/stdin for the attachment 41
Chapter 4. Configure ZCP Components data and must return the plain text through /dev/stdout. Some tools cannot parse attachment data from a stream, and require the data to be provided as file. To store the attachment in a temporary file, the script zmktemp can be used. That script will write all attachment data in a temporary file and print the location of the file to /dev/stdout. Attachments which cannot be parsed (for example images), the command echo -n can be used. After editing the command, it is advisable to test it to see if the desired output is returned. Testing the command can be done by executing the following command on the command line:
cat <attachment> | <command>
The resources used by the attachments_parser during the parsing of a single attachment can be restricted by limiting the total memory and CPU time usage. To control the maximum amount of memory the script can use is controlled by the configuration option index_attachment_parser_max_memory. By default this value is set to 0, to disable any memory consumption restriction. If a restriction should be applied, the maximum number of bytes should be provided. The best restriction size depends on the maximum attachment size which can be provided rd to the script (configured using index_attachment_max_size) and the 3 party tools used to parse the attachments. To prevent the script to take too much time, the configuration option index_attachment_parser_max_cputime can be used. By default this value is set to 0, to disable any CPU time restriction. If a restriction should be applied, the maximum number of seconds rd should be provided. The best restriction depends on the 3 party tools used to parse the attachments. If either of these limits is exceeded the script will be canceled and the attachment will not be indexed.
Note
The zarafa-indexer will utilize the Single Instance Attachments feature, and keep parsed attachments in its cache. This will reduce the required indexing time for attachment which have been delivered to multiple users on the same server. The lifetime of this cache is controlled by the index_cache_timeout configuration option discussed earlier.
42
Chapter 5.
After the PHP-extension is in the correct directory, add it to the php.ini configuration file. Add the following line to the php.ini if it does not already exist:
extension = mapi.so
/etc/php5/apache2/php.ini
With the phpinfo() function it is possible to check whether the module will be loaded correctly. Search for the MAPI part to check for the module. The phpinfo can also be viewed by running php i on the command line if php cli is installed.
43
The website files are by default installed in the WebAccess directory. Make sure the webclients login page can be opened by browsing to the correct url:
http://<ip-address server>/webaccess/
If the login page is not shown, the webserver needs to be configured to let it access the correct directory. The following example shows a configuration for Apache2:
Alias /webaccess /usr/share/zarafa-webaccess/ <Directory /usr/share/zarafa-webaccess/> AllowOverride None Order allow,deny Allow from all </Directory>
Make sure the correct directory holding the PHP WebAccess files is typed. The following command will tell apache2 to reread its config file:
/etc/init.d/apache2 reload
The WebAccess should now be visible. If it still does not show up, please see Section 2.3, Troubleshooting Installation Issues for more information.
This means that URLs that begin with /zarafa will be forwarded to localhost on port 236, where the Zarafa Server listens for incoming connections. These lines can be placed globally, or within a VirtualHost declaration.
Note
Keep in mind that using the HTTP proxy has some performance overhead, so for larger setups its not recommended to use this.
44
Note
Most recent Linux distributions use OpenLDAP in dynamic configuration mode. For more information about installing the Zarafa schema on an OpenLDAP server with dynamic configuration, see http://www.zarafa.com/wiki/index.php/ OpenLdap:_Switch_to_dynamic_config_backend_%28cn%3Dconfig%29.
45
Chapter 5. Configure 3rd Party Components At the moment ZCP doesnt support the configuration of multiple LDAP servers. By default the plain LDAP protocol will be used. For configuring secure LDAP, change the following settings. A howto for configuring OpenLDAP with SSL certificates can be found on http:// wiki.zarafa.com.
ldap_port = 389 ldap_protocol = ldap
The Zarafa Server will only read from the OpenLDAP server. The specified bind user should at least have read access on the LDAP server.
ldap_bind_user = cn=Manager,dc=example,dc=com ldap_bind_passwd = secret ldap_authentication_method = bind
The authentication method can be set to password, so the Zarafa Server will compare the encrypted password from the LDAP server with the encrypted password the user filled in during the login. For this method the specified bind user has to be an administrative user in OpenLDAP and have read access on the password attribute. The LDAP search base (base DN) that the search for the different objects should start at. This should be the root of the LDAP directory which contains the users, groups and contacts.
ldap_search_base = dc=example,dc=com ldap_object_type_attribute = objectClass ldap_user_type_attribute_value = posixAccount ldap_group_type_attribute_value = posixGroup ldap_contact_type_attribute_value = zarafa-contact ldap_company_type_attribute_value = zarafa-company ldap_addresslist_type_attribute_value = zarafa-addresslist ldap_dynamicgroup_type_attribute_value = posixGroup,zarafa-dynamicgroup
Based on the type attribute the Zarafa Server will create an object in the database, so its get listed in the Global Address Book. Make sure that the values are always unique for one type of object.
46
Group configuration
ldap_password_attribute = userPassword ldap_isadmin_attribute = zarafaAdmin ldap_nonactive_attribute = zarafaSharedStoreOnly
The unique user attribute is the mapping between a mailbox in the database and the actual user in LDAP. Make sure this field is never changed as the Zarafa Server will perceive that as a user being deleted (and created), and will therefore orphan the users store. The email aliases are shown in the Global Address Book details and can be used for resolving email aliases in Postfix. However it is not possible to deliver email to email aliases. Extra user information, like addresses, phone numbers and company information can be mapped by an extra configuration file:
!propmap /etc/zarafa/ldap.propmap.cfg
The specified attributes for users will also be used for contacts.
For the membership relationships between groups and users, each group object has a group member attribute. This can be configured by:
ldap_groupmembers_attribute = memberUid
The Zarafa Server will by default use the unique user attribute as value of the group member attribute. This can be changed by the group members relation attribute.
ldap_groupmembers_attribute_type = text ldap_groupmembers_relation_attribute = uid
Groups can be flagged as security groups by the security group attribute. Security groups are available in the Global Address Book when creating a new email and setting permissions. To achieve this the attibute (here zarafaSecurityGroup) must be set to 1. When the zarafaSecurityGroup attribute is set to 0, the group will be a distribution group. Distribution groups are only available in the Global Address Book when creating a new email but cannot be used for configuring mailbox permissions.
ldap_group_security_attribute = zarafaSecurityGroup ldap_group_security_attribute_type = boolean
47
Figure 5.1. Addresslists in Global Adress Book Change or add in ldap.cfg the following configuration settings for the addresslist objects:
ldap_addresslist_search_filter = ldap_addresslist_unique_attribute = gidNumber ldap_addresslist_unique_attribute_type = text ldap_addresslist_filter_attribute = zarafaFilter ldap_addresslist_name_attribute = cn
See Section 8.5, User Management with LDAP or Active Directory for more information on how to administer address lists.
To test whether users and groups will be listed correctly using the LDAP configuration, use:
zarafa-admin -l
If no users or groups are shown, please check the Zarafa server log file for errors. Setting the log_level to 6 in the /etc/zarafa/server.cfg will display all LDAP queries send to the server and possible errors.
Note
The first time the zarafa-admin -l is done, all mailboxes will be created. This can take some time, so be patient.
More information about other available LDAP attributes can be found in the man page.
man zarafa-ldap.cfg
48
3. On the Edit menu, click New, and then click DWORD Value. 4. Enter the value data when the following registry value is displayed:
Value Name: Schema Update Allowed Data Type: REG_DWORD Base: Binary Value Data: Type 1 to enable this feature, or 0 (zero) to disable it.
5. Quit Registry Editor. Now the Zarafa Active Directory installer can be executed. For more information take a look at: http:// support.microsoft.com/kb/285172
Note
Dont forget to switch the registry key back after the installation.
At the moment ZCP does not support specifying multiple Active Directory servers here. However, it is possible to point the ldap_host to an Active Directory load balancer. By default the plain LDAP protocol will be used. For configuring secure LDAP, change the following settings:
ldap_port = 636 ldap_protocol = ldaps
A guide for configuring Active Directory with SSL certificates can be found in an article on our wiki . The Zarafa Server only reads from (and never writes to) the LDAP or Active Directory server. Therefore the specified bind user should at least have read access on the LDAP server.
ldap_bind_user = cn=administrator,cn=users,dc=example,dc=com ldap_bind_passwd = secret ldap_authentication_method = bind
The LDAP search base (base DN) specifies a branch that the Zarafa Server with limit itself to. This should be the root of the LDAP directory which contains the users, groups and contacts.
ldap_search_base = dc=example,dc=com
By the following type attributes the Zarafa Server knows what objects to create in the database and what to list in the Global Address Book. Make sure these values are all unique.
ldap_object_type_attribute = objectClass ldap_user_type_attribute_value = User ldap_group_type_attribute_value = Group ldap_contact_type_attribute_value = Contact ldap_company_type_attribute_value = ou ldap_addresslist_type_attribute_value = zarafa-addresslist ldap_dynamicgroup_type_attribute_value = zarafa-dynamicgroup
As performance optimization feature the setting ldap_page_size was implemented to limit result sets in pages of this size downloading fewer results at a time from the LDAP server.
# Default ADS MaxPageSize is 1000. ldap_page_size = 1000
http://www.zarafa.com/wiki/index.php/Configure_Active_Directory_with_SSL
51
ldap_user_search_filter = (zarafaAccount=1)
ldap_fullname_attribute = cn ldap_loginname_attribute = sAMAccountName ldap_emailaddress_attribute = mail ldap_emailaliases_attribute = otherMailbox ldap_password_attribute = ldap_isadmin_attribute = zarafaAdmin ldap_nonactive_attribute = zarafaSharedStoreOnly
The unique user attribute is the mapping between a mailbox in the database and the actual user. Make sure this field can never be changed, otherwise a user deletion will be triggered by the Zarafa Server. The email aliases are shown in the Global Address Book details and can be used for email aliases in Postfix. However its not possible to deliver email to email aliases. Extra user information, like addresses, phone numbers and company information can be mapped by an extra configuration file:
!include /etc/zarafa/ldap.propname.cfg
The specified attributes for users will also be used for the contacts.
Important
The attribute otherMailbox is by default not indexed in Active Directory. Its required to index this attribute in Active Directory, otherwise the Active Directory server will have a high CPU load during search queries on this attribute. For more information about indexing attributes in Active Directory, see http://go.microsoft.com/fwlink/?LinkId=46790.
For the membership relationships between groups and users, each group object has a group member attribute. This can be configured by:
ldap_groupmembers_attribute = member ldap_groupmembers_attribute_type = dn
By the security group attribute group can be specified as security groups in Active Directory. Security groups will only displayed when settings permissions and are not default available in the Global Address Book. 52
Addresslist configuration
Figure 5.4. Addresslists in Global Adress Book Change or add in ldap.cfg the following configuration settings for the addresslist objects.
ldap_addresslist_search_filter = ldap_addresslist_unique_attribute = cn ldap_addresslist_unique_attribute_type = text ldap_addresslist_filter_attribute = zarafaFilter ldap_addresslist_name_attribute = cn
See the Section 8.5, User Management with LDAP or Active Directory for more information on how to administer address lists.
and
zarafa-admin -L
If no users or groups 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. The first time the zarafa-admin -l is done, all mailboxes will be created. This can take some time, so be patient. More information about the other available LDAP attributes can be found in the man page. 53
man zarafa-ldap.cfg
See Chapter 8, User Management for Zarafa user management with Active Directory.
Note
Configuring antispam and antivirus scanning is beyond the scope for this manual. On the internet many example configurations are available for the most common MTAs and scanners.
In order to make Postfix aware of the local emaildomains, add the following line to the main.cf.
virtual_mailbox_domains = example.com, example.org, example.net
Postfix will now see the configured domains as its local email domains, however to accept incoming emails Postfix will do a recipient check. Add the following lines to the main.cf to have Postfix use LDAP for looking up (valid) recipients:
virtual_mailbox_maps = ldap:/etc/postfix/ldap-users.cf virtual_alias_maps = ldap:/etc/postfix/ldap-aliases.cf virtual_transport = lmtp:127.0.0.1:2003
All incoming emails are delivered to the LMTP service of the zarafa-dagent. The delivery needs to be done on the primary mail address of a user. For resolving the primary mail address of the user, create the file /etc/postfix/ldap-users.cf and add the following lines:
2
http://www.postfix.org/LDAP_README.html
54
server_host = localhost search_base = ou=Users,dc=example,dc=com version = 3 scope = sub query_filter = (mail=%s) result_attribute = mail
For lookups of mail aliases create the file /etc/postfix/ldap-aliases.cf and add the following lines:
server_host = localhost search_base = ou=Users,dc=example,dc=com version = 3 scope = sub query_filter = (zarafaAliases=%s) result_attribute = mail
The search base of users and aliases need to match the search base of the LDAP server. After the configuration files have been changed Postfix need to be restarted:
/etc/init.d/postfix restart
Make sure the zarafa-dagent is run as a daemon and started at boot time. For RPM based distributions use:
chkconfig zarafa-dagent on /etc/init.d/zarafa-dagent start
For Debian based distributions enable the zarafa-dagent by setting the option DAGENT_ENABLED to yes in the file /etc/default/zarafa-dagent. To enable the zarafa-dagent at boot time use:
update-rc.d zarafa-dagent defaults
Note
It is advised to enable logging of the zarafa-dagent when running in LMTP mode for monitoring purposes. Enable the logging options in the zarafa-dagent in /etc/zarafa/ dagent.cfg.
http://www.postfix.org/LDAP_README.html
55
inet_interfaces = all
In order to make Postfix aware of the local emaildomains, add the following line to the main.cf:
virtual_mailbox_domains = example.com, example.org, example.net
Postfix will now see the configured domains as its local email domains, however to accept incoming emails Postfix will do a recipient check. This recipient check can be done on the Active Directory server. Add the following lines to the main.cf
virtual_mailbox_maps = ldap:/etc/postfix/ldap-users.cf virtual_alias_maps = ldap:/etc/postfix/ldap-aliases.cf virtual_transport = lmtp:127.0.0.1:2003
All incoming emails are delivered to the LMTP service of the zarafa-dagent. The delivery needs to be done on the primary mail address of a user. For resolving the primary mail address of the user, create the file /etc/postfix/ldap-users.cf and add the following lines:
server_host = 192.168.0.100 search_base = ou=Users,dc=example,dc=local version = 3 bind = yes bind_dn = cn=zarafa,ou=Users,dc=example,dc=local bind_pw = secret scope = sub query_filter = (&(objectClass=person)(mail=%s)) result_attribute = mail
For lookups of mail aliases create the file /etc/postfix/ldap-aliases.cf and add the following lines:
server_host = 192.168.0.100 search_base = ou=Users,dc=example,dc=local version = 3 bind = yes bind_dn = cn=zarafa,ou=Users,dc=example,dc=local bind_pw = secret scope = sub query_filter = (&(objectClass=person)(otherMailbox=%s)) result_attribute = mail
Active Directory has the possibility to create distribution groups which can be used as email distribution list in ZCP. To use integrate Postfix with distribution groups, Postfix 2.4 or higher is required.
Note
Some linux distributions (like RHEL 4 and 5) do not include Postfix 2.4 or higher. Packages of newer versions of Postfix are usually available as community contributed packages. In case of 4 RHEL 4 and 5 these packages can be found here .
http://www.linuxmail.info/postfix-rpm-packages
56
Configure ZCP Postfix integration with virtual users To support distribution groups add the following line to the virtual_alias_maps:
virtual_alias_maps = ldap:/etc/postfix/ldap-aliases.cf, ldap:/etc/postfix/ldap-groups.cf
Create a new file /etc/postfix/ldap-group.cf and insert the LDAP group configuration in there:
server_host = 192.168.0.100 search_base = ou=groups,dc=example,dc=local version = 3 bind = yes bind_dn = cn=zarafa,ou=Users,dc=example,dc=local bind_pw = secret query_filter = (&(objectclass=group)(mail=%s)) leaf_result_attribute = mail special_result_attribute = member
The search base of users, aliases and groups need to match the search base of the Active Directory server. After the configuration files have been changed Postfix need to be restarted:
/etc/init.d/postfix restart
Make sure the zarafa-dagent is run as a daemon and started at boot time. For RPM based distributions use:
chkconfig zarafa-dagent on /etc/init.d/zarafa-dagent start
For Debian based distributions enable the zarafa-dagent by setting the option DAGENT_ENABLED to yes in the file /etc/default/zarafa-dagent. To enable the zarafa-dagent at boot time use:
update-rc.d zarafa-dagent defaults
Note
It is advised to enable logging of the zarafa-dagent when running in LMTP mode for monitoring purposes. Enable the logging options in the zarafa-dagent in /etc/zarafa/ dagent.cfg.
All Postfix configuration files can be found in /etc/postfix directory. The main configuration file is logically called main.cf In order to make Postfix aware of the local email domains, add the following line to the main.cf: 57
Postfix will now regard these domains as its local email domains. In order to accept incoming emails Postfix will also need to validate the recipient. Add the following lines to the main.cf config file in order to have Postfix look up recipient from a hash map:
virtual_mailbox_maps = hash:/etc/postfix/virtual virtual_alias_maps = hash:/etc/postfix/virtual virtual_transport = lmtp:127.0.0.1:2003
The file /etc/postfix/virtual should contain all email addresses and aliases of a user, in the following structure:
#Emailaddress or alias [email protected] [email protected] [email protected] [email protected] [email protected] primary mailaddress of user [email protected] [email protected] [email protected] [email protected] [email protected], [email protected]
The left column contains the email address or alias, the right column contains the primary email addresses on which the message should be delivered. After all users and aliases are added to this file, a hash map needs to be created. The following command will create the actual hash map /etc/postfix/virtual.db.
postmap /etc/postfix/virtual
All incoming emails are delivered to the zarafa-dagent over LMTP using the primary mail address of as specified in the hash map. After changing the configuration files restart Postfix by its init script:
/etc/init.d/postfix restart
For Debian based distributions enable the zarafa-dagent by setting the option DAGENT_ENABLED to yes in the file /etc/default/zarafa-dagent. To enable the zarafa-dagent at boot time use:
update-rc.d zarafa-dagent defaults
Note
Its advised to enable logging of the zarafa-dagent when running in LMTP mode for monitoring purposes. To alter logging options for the zarafa-dagent, adjust the configuration file: /etc/zarafa/dagent.cfg.
58
5.5.1. Compatibility
Z-Push allows users with PDAs and smartphones to synchronise their email, contacts, calendar items and tasks directly from a compatible server over UMTS, GPRS, WiFi or other GSM data connections. The following devices are supported by Z-Push: Windows Mobile 5, 6, 6.1 and 6.5 Nokia E/N-series with Mail for Exchange (M4E) Nokia E-series with built in ActiveSync (Nokia Mail 2) Sony Ericsson with RoadSync Apple iPhone Android Cupcake or Donut with third party tools like Nitrodesk Touchdown Android Eclair with Contacts and Calendar synchronization or third party tools other ActiveSync compatible devices For detailed information about the devices and their compatibily status, please consult the Mobile Compatibility List at http://z-push.sourceforge.net/compatibility
5.5.2. Security
To encrypt data between the mobile devices and the server, its required to enable SSL support in the web server. Configuring Apache with SSL certificates is beyond the scope of this document, though many howtos can be found online. Keep in mind that some mobile devices require an official SSL certificate and dont work with self signed certificates.
5.5.3. Installation
Download the latest Z-Push software from http://z-push.sourceforge.net/download To Install Z-Push, simply untar the Z-Push tar to the webroot with: 59
The -C option is the destination where the files need to be installed. In the following table the default webroot directories of where some distributions lets the Apache webserver search for files. Table 5.1. Webroot directories Distribution Red Hat Enterprise Linux SUSE Debian and Ubuntu Default webroot /var/www/html /srv/www/htdocs /var/www
Make sure that the state directory is writeable for the webserver process, so either change the owner of the state directory to the UID of the apache process, or make it world writeable:
chmod 755 /var/www/z-push/state chown apache:apache /var/www/z-push/state
The user and group name of Apache will differ per Linux distribution. The table below shows an overview of the user and group names of the Apache process. Table 5.2. User and groupnames per distribution Distribution Red Hat Enterprise Linux OpenSuSE and SLES Debian and Ubuntu Apache username apache wwwrun www-data Groupname apache www www-data
Now, Apache must be configured to redirect the URL Microsoft-Server-ActiveSync to the index.php file in the z-push directory. This can be done by adding the line to the httpd.conf file
Alias /Microsoft-Server-ActiveSync /var/www/html/z-push/index.php
Make sure that the line is added to the correct part of the Apache configuration, taking care of virtual hosts and other Apache configurations.
Important
It is not possible simply rename the Z-Push directory to Microsoft-Server-ActiveSync. This will cause Apache to send redirects to the PDA, which will definitely prevent proper synchronization.
Set this in the php.ini or in a .htaccess file in the root directory of Z-Push. If not setup correctly, the PDA will not be able to login correctly via Z-Push. Reload Apache to activate these changes. 60
5.5.5. Upgrade
Upgrading to a newer Z-Push version follows the same path as the initial installation. When upgrading to a new minor version e.g. from Z-Push 1.4 to Z-Push 1.4.1, the existing Z-Push directory can be overwritten when extracting the archive. When installing a new major version it is recommended to extract the tarball to another directory and to copy the state from the existing installation.
Important
It is crucial to always keep the data of the state directory in order to ensure data consistency on already synchronized mobiles.
Without the state information mobile devices, which already have an ActiveSync profile, will receive duplicate items or the synchronization will break completely. Please also observe the published release notes of the new Z-Push version. For some releases it is necessary to e.g. resynchronize the mobile.
5.5.6. Troubleshooting
General configuration Most of the difficulties are caused by incorrect Apache settings. The Apache setup can be tested using a webbrowser like Firefox pointing it to:
http://<server>/Microsoft-Server-ActiveSync
If correctly configured, a window requesting username/password should be displayed. Authenticating using valid credentials should display Z-Push information page, containing the following message: A Z-Push information page should be displayed, containing the message:
*GET not supported* This is the z-push location and can only be accessed by Microsoft ActiveSync-capable devices.
Verify the PHP and/or Apache configuration if an error is displayed. Synchronization problems If synchronization problems are encountered, a debug.txt file has to be created in the root directory of Z-Push. This file should be writeable by the Apache server process.
touch /var/www/z-push/debug.txt
61
The debug.txt file will collect debug information about the synchronisation. To obtain a complete synchronization log the file wbxml.php has to be edited and the parameter WBXML_DEBUG set to true:
define('WBXML_DEBUG', true);
Important
The debug.txt logfile contains sensible data and should be protected so it can not be downloaded from the internet.
To protect the debug.txt logfile, a .htaccess has to be created in the z-push root directory, containing:
<Files debug.txt> Deny from All </Files>
Log messages Repeatedly Command denied: Retry after sending a PROVISIONING command: Most probably the mobile device does not support provisioning. The LOOSE_PROVISIONING parameter should be enabled in the configuration. If the messages continues, the ActiveSync profile should be reconfigured on the device. If this does not help, the PROVISIONING could be disabled completely in the config file (applies to all devices!). More information can be found at: http:// www.zarafa.com/wiki/index.php/Z-Push_Provisioning Exceptions for Meeting requests cause duplicates if accepted on the mobile: Please update to Z-Push 1.4 or later. In order to fix existing duplicates, the ActiveSync profile on the mobile has to be recreated or at least the calendar has to be resynchronized completely (disabling calendarsync and enabling it afterwards).
62
Chapter 6.
Advanced Configurations
This chapter describes how to configure special setups that go beyond most common installations of ZCP.
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
Important
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.
Note
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.
63
When set to true its 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.
createcompany_script
Location of the createcompany script which will be executed when a new tenant has been created.
deletecompany_script
Location of the deletecompany script which will be executed when a tenant has been deleted.
loginname_format
See Section 6.2.2.2, Configuring login name for more details about this configuration option.
storename_format
See Section 6.2.2.3, Configuring store name for more details about this configuration option.
Configuring the server 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": %u > john %u@%c > john@exampleorg
1
\\%c\%u > \\exampleorg\john 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.
Note
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.
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 = text 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 its 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
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). 66
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/bin/zarafa-admin --add-view <viewer> -I <companyname> /usr/bin/zarafa-admin --del-view <viewer> -I <companyname> /usr/bin/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/bin/zarafa-admin --add-admin <admin> -I <companyname> /usr/bin/zarafa-admin --del-admin <admin> -I <companyname> /usr/bin/zarafa-admin --list-view -I <companyname>
The <admin> is the loginname of the user who receives or looses admin privileges over the company <companyname>.
67
Chapter 6. Advanced Configurations And creating a new group for tenant exampleorg would be:
/usr/bin/zarafa-admin -g group@exampleorg ...other options...
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>
68
Administrator users When using the LDAP plugin, the attributes which control the quota levels can be configured in /etc/ zarafa/ldap.cfg.
Note
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.
69
Figure 6.2. Multiserver environment on 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 Figure 6.3, Multiserver environment on two locations.
Figure 6.3. Multiserver environment on two locations The mailbox of a user is always stored on only one server. Its 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 Figure 6.4, Multiserver environment.
70
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. Johns mailbox is located on Node 1, so the mailbox will be directly 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 setup a connection to Node 2 to open the mailbox of Mary.
71
Figure 6.5. Setup directory with all the multi-server nodes 3. Add all the multi-server nodes to this directory or organization 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 and ipHost objectClass. 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.
Figure 6.6. LDAP server attributes 5. The ZarafaContainsPublic attribute can only be set for one multi-server node. At the moment there is not support for multiple Public Folders on different 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/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
7. 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 needs to be updated with the zarafaCompanyServer attribute. Use the server name as well for this.
72
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.
server_name
The unique server name used to identify each node in the setup. This server name should be correctly configured 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
Note
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.
2. 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
3. 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 73
Chapter 6. Advanced Configurations 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. 4. 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. 5. 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 server_ssl_port server_ssl_ca_file server_ssl_key_file server_ssl_key_pass sslkeys_path = = = = = = yes 237 /etc/zarafa/ssl/demoCA/cacert.pem /etc/zarafa/ssl/server.pem <ssl-password> /etc/zarafa/sslkeys
6. After a restart of the Zarafa-server, the server should accept HTTPS connections. Please check the server logfile for any errors. 7. 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
8. 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 its required to sign again the certificate against the CA and create a public key for the certificate. 9. 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. 10. Move the public key to the /etc/zarafa/sslkeys directory.
mv /etc/zarafa/ssl/client-public.pem /etc/zarafa/sslkeys
11. Restart the zarafa-server on all nodes to activate the new certificates:
/etc/init.d/zarafa-server restart
12. To test the client SSL certificates change the following lines in the /etc/zarafa/dagent.cfg.
server_socket = https://127.0.0.1:237/zarafa 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 dagents private-key, in this test case on localhost.
74
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 certifcates:
yum install openssl-perl cp /etc/CA/cacert.pem /etc/pki/tls/certs/zarafa-ca.pem c_rehash
This way the dagent is able to verify the private-key against the CA bundle. On Debian based systems this step can be ignored. 13. 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
Remember to copy the root CA to the different nodes if this file is placed outside the directories that have just been copied. 15. 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 Test <ctrl-d>
This delivery should not result in any delivery errors, otherwise please check created certificates. Its 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-dagent zarafa-spooler zarafa-backup, zarafa-restore zarafa-admin
For advanced multi-server environments and the best Zarafa configuration for a specific setup, the Zarafa Professional Services are open for advise and support.
75
Note
The Zarafa Windows Client Updater is only available to those running the ZCP Professional or Enterprise edition.
Figure 6.7. Auto-update structure Restrictions: 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.
76
Client-side configuration 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-6.40.0-19050.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.
Note
If the default profile is set to use encryption via port 237, the root CA certificate needs to be installed on the desktop used.
Chapter 6. Advanced Configurations The Launch Updater application will be launched at Windows' startup. The command to run the application is placed in the registry here:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Run
This application will find out clients current version from the following registry key:
HKEY_LOCAL_MACHINE\Software\Zarafa\Client\Version
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.
Figure 6.9. 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. 78
MSI Options
Note
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.
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 zarafa-msi.log
79
Note
For an automated installation, you must use the zarafaclient-en.msi file. This installer contains the English language only, and is specially created for this feature.
Note
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.
Single Instance Attachment Storage and LMTP database (only 10 MB of data in this example) and all the 30 users can access the attachment through a reference pointer.
Note
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.
Note
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.
81
Chapter 6. Advanced Configurations 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
Here, 192.168.0.100 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
Type the administrator password there, and a Kerberos ticket should be provided by the ADS server. 82
With this ticket we can join the Windows domain, without typing the password again:
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:
Joined 'LINUXSERVER' to realm 'ADSDOMAIN.LOCAL'
or some other success message. Now its required to restart the winbind daemon, because it keeps too many items cached:
/etc/init.d/winbind restart
And thats 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.
Depending on the Linux distribution used, this comes through various package names. On Debian use:
apt-get install winbind
83
Chapter 6. Advanced Configurations 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
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.
Note
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/[email protected] -mapuser EXAMPLE\httpd-linux -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -pass <password> -out c:\keytab.apache
Execute the following command to create the keytab file for the Zarafa Server:
ktpass.exe -princ zarafa/[email protected] -mapuser EXAMPLE\zarafa-linux -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -pass <password> -out c:\keytab.zarafa
Copy the file keytab.apache to /etc/httpd/conf/ on the Linux server. Copy the file keytab.zarafa to /etc/zarafa/ on the Linux server.
85
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.local
Open the file /etc/httpd/conf.d/auth_kerb.conf. Add the following lines at the end of this file:
Alias /webaccess /usr/share/zarafa-webaccess <Directory /usr/share/zarafa-webaccess> AuthType Kerberos AuthName "Kerberos Login" KrbMethodNegotiate On KrbMethodK5Passwd Off KrbServiceName HTTP KrbAuthRealms ADSDOMAIN.LOCAL Krb5KeyTab /etc/httpd/conf/keytab.apache require valid-user </Directory>
Set the filesystem permissions of the keytab file to 400 and change the owner to the Apache user:
chmod 400 /etc/httpd/conf/keytab.apache chown apache:apache /etc/httpd/conf/keytab.apache
86
Up and running
To configure the Zarafa WebAccess for Single Sign On change the following option in the config.php file:
define("LOGINNAME_STRIP_DOMAIN", true);
Note
In this configuration we assume the Zarafa WebAccess is installed on the same server as the Zarafa Storage Server.
Restart the Zarafa-server processes to activate this change, e.g. for Red Hat:
service zarafa-server restart
Important
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.
Important
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. Theres also no message in the primary store that will contain a reference to the archived message.
Note
Unless disabled, message in the sent items folder are archived as any other message. This causes extra storage is required because those message have also been archived by the spooler.
88
Chapter 7.
Replace <servicename> with the service that needs to start. To start the zarafa-server, type:
/etc/init.d/zarafa-server start
This script will start the server. The init.d scripts can start, stop and restart the services. If the init.d script cannot be used, the server needs to be started manually. It is possible to explicitly tell the zarafa server where the configuration file is, using the -c switch:
/usr/bin/zarafa-server -c /etc/zarafa/server.cfg
The zarafa-server will daemonise, so prompt will almost immediately return. Use -F to start it in the foreground. The -F switch can also be used for programs like daemontools that monitor services.
Most services will stop almost immediately. The zarafa-spooler may take up to 10 seconds to stop. The zarafa-server may take up to 60 seconds to stop.
89
In the reloading chapter are all the options that can be reloaded for that service. To make a service reload the configuration file, type:
/etc/init.d/zarafa-<servicename> reload
How to log the messages. file sends the messages to a file. On Linux systems, syslog sends the messages to the default maillog through syslog.
log_file
When the log_method is set to file, this is the variable that defines the name of file. The server needs write access to the directory and file.
log_level
Increase the level of messages that will be logged. Level 6 is the highest level.
log_timestamp
1 or 0; This will enable or disable a timestamp, when using a file as the log method. Logging of other services than zarafa-server are configured in a same manner as the server.
Logging items
The following tag is possible in the startup line: uid The unix user id used to start the server (not necessarily the user the server will be running as)
7.3.1.2. Signals
When the server receives a signal, the following message will be printed in the security log:
zarafa-server signalled sig=15
The following tag is possible in the signal line: sig The signal the server received. See man 7 signal for a list of most common signal IDs.
7.3.1.3. Authentications
When a user (not the internal SYSTEM user) logs in, the following message will be printed in the security log: Correct authentication:
authenticate ok user='john' from='127.0.0.1' method='User supplied password' program='apache2'
Incorrect authentication:
authenticate failed user='john' from='127.0.0.1' program='apache2'
The following tags are possible in the authentication line: user The username sent to the zarafa server. requested The name in the MAPI profile to open the store of, user tag will be the actual authenticated user. (SSO only) from Unix socket or IP-address the connection to the server was made to. 91
Chapter 7. Managing ZCP Services method Method the user was validated with, one of the following: socket, certificate, password, ntlm sso or kerberos sso. program The program being used to login with.
The following tags are possible in the sharing line: objectid The object being acted on. type The MAPI type of the object (only store, folder and message possible). ownername The owner of the store the objectid is in (not necessarily the user that actually created that object) username The user performing the action on the object. rights The action being performed.
Note
For the Public store the ownername will be SYSTEM in single-tenancy mode, and the company name in multi-tenancy mode.
Possible actions in rights: read Reading the object. create Creating a new object edit Editing an existing object (eg altering properties, but also adding/removing of recipients and attachments) 92
Configuration delete Deleting (softdelete) or moving the object create folder Creating a new folder view Reading the folder hierarchy / contents tables folder permissions Altering the permissions on a folder owner submitMessage/finishMessage/abortSubmit, sending email actions in someone elses store is never permitted unless youre the owner. admin Unused, will never actually be printed
The script will display now the exact foldername which is access in the delegate store:
access allowed rights='view' type='folder' objectid='store\27\IPM_SUBTREE\Calendar' username='john' ownername='mary'
In this example the user john has opened the Calendar of user mary.
7.3.2. Configuration
In the /etc/zarafa/server.cfg the following options are added:
audit_log_enabled = no audit_log_method = syslog audit_log_file = audit_log_level = 1 audit_log_timestamp = 0
By default the audit logging is disabled. When enabled, the default is to log through syslog since this can be configured to send the messages to an external syslog server. The syslog authpriv facility will be used to send the messages to.
93
Hosts: 1 0
QAge:
IP/PID 4527
NREQ 6
TASK
The --top overview gives every second status information about CPU usage, connected clients, active threads, queue length and SQL queries. When the server has a high queue length and age the amount of threads should be normally increased.
<days> denotes the number of days that recently removed items are kept. When 0 (zero) all removed items are purged. 94
Soft Delete system For performance reasons a manual purge of the softdelete system is advisable for larger ZCP environments. This can be simply configured by a cron job.
95
96
Chapter 8.
User Management
8.1. Public folder
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. It can be created with the following command:
/usr/bin/zarafa-admin -s
The public store is the folder every user can always open. After installation and configuration of the server a public store needs to be created before private stores can be made. If ZCP is configured for multi-tenancy, a public store will be automatically created per company. When using multi-server support, the Public store can only be created on the multi-server node which has the ZarafaContainsPublic attribute enabled. Currently the Public Store can be created on only one server. See Section 6.3.2, Prepare / setup the LDAP server for multi-server setup for more information.
Note
The Public store is by default accessible and writable for all users. Please review the permissions before start using the Zarafa system.
97
When a user is deleted the mailbox of the user will be still kept in the database. Use the following command to retrieve a list of stores without a user, and users without a store:
/usr/bin/zarafa-admin --list-orphans Stores without users: Store guid Store size
Guessed username
Last modified
----------------------------------------------------------------------------------------------CAC27E6D70BB45B0B712B760AE6BA0A8 steve 2010/03/22 14:22 2334KB Users without stores: Username ----------------------------jane
It can be decided to remove the store from the database or hook the store to another user to be able to access it once again. To remove the store from the database, an action which is irreversible, use the following command:
/usr/bin/zarafa-admin --remove-store <store-guid>
The user given with the -u option will now have the new store attached to it. Re-login with the webaccess or create a new profile in Outlook to access the store.
Important
When a store is hooked to a user that already has a store attached to it, the original store will be orphaned. This original store can be found using the list-orphans options of the zarafaadmin command.
98
Note
In ZCP 6.30.6 and earlier versions, the store of the user was moved to the Deleted Stores folder in the public store after a user deletion. This folder is only available for administrative users. Administrators can browse the folders or delete the deleted stores completely by removing the corresponding folder from the Deleted stores folder. This is relevant for all user plugins.
More information about all options of the zarafa-admin can be found in the man-page.
man zarafa-admin
The fields between <> should be filled in as follows: User name: The name of the user. With this name the user will log on to the store. Password: The password in plain text. The password will be stored encrypted in the database. Email: The email address of the user. Often this is <user name>@<email domain>. Full name: The full name of the user. Because the full name will contain space characters, and maybe other non-alphanumeric characters, the name should be entered with qoutes (''). Administrator: This value should be 0 or 1. When a user is administrator, the user will be allowed to open all Zarafa stores of any user. It is also possible to pass 2 as administrator level, this will make the user a system administrator who can create/modify/delete companies. All fields except the email address are case sensitive. The password can also be set using the -P switch. The password is then not given at the command prompt, but asked for by the zarafa-admin tool. The password is not echoed on the screen and needs to be typed twice for verification.
Chapter 8. User Management To create a non-active user, use the following command:
zarafa-admin -c <user name> -P -e <email> -f <full name> -n 1
Note
In ZCP version 6.30 and earlier its not possible to switch an active user to non-active and vice versa. Switching the non-active value will trigger a mailbox deletion.
All the changes are optional. For example, only the password for an existing user may be updated, leaving the other user information the same as it was.
The user will be deleted from the database. However the store will be kept in the database, but is not accessible. See Section 8.2, General usage of Zarafa-admin tool for more information about handling orphant stores.
Groups
For example:
zarafa-admin -u helpdesk --add-sendas john
Remove a user from the list of the delegate being updated as a send as user. This option is only valid with the -u update action.
zarafa-admin -u <delegate> --del-sendas <user>
Note
With the DB plugin sendas permissions can not be configured on groups.
Note
When both the "send on behalf of" and "sendas" permissions are configured on the same user, the email will always be sent with "on behalf of".
8.3.6. Groups
The server supports groups. Users can belong to any number of groups. Every user always belongs to the special group Everyone. Defining security settings on folders and items are the same for both users and groups. For example, the group Everyone has read access to the Inbox of Peter. At this point, every user may read the email in Peters Inbox, because all users are a member of the group Everyone. When a new Zarafa user is created, only the free/busy information is open for read access for the group Everyone by default.
Using the options -l or -L, a list of users or groups can be listed from the server. 101
Chapter 8. User Management All created users will be member of the group Everyone, this can not be changed. Groups created with DB plugin can be used both for configuring permissions and sending emails to a specific group.
As the emailaddress of user cant be specified in the adduser command, the default email address will be <username>@default_domain. The default domain is specified in the /etc/zarafa/ unix.cfg. This email address can be changed by using the zarafa-admin tool.
zarafa-admin -u <username> -e <email address>
Note
In ZCP version 6.30 and earlier its not possible to switch an active user to non-active and vice versa. Switching the non-active value will trigger a mailbox deletion.
Deleting users with Unix plugin Mailbox type (active or non-active) Group membership The following other information has to be changed and configured with the zarafa-admin tool. Email address Administrator flag Quota Sendas permissions
The user will be deleted from the database. However the store will be kept in the database, but is not accessible. See Section 8.2, General usage of Zarafa-admin tool for more information about handling orphant stores.
For example:
zarafa-admin -u helpdesk --add-sendas john
Remove a user from the list of the delegate being updated as a send as user. This option is only valid with the -u update action.
zarafa-admin -u <delegate> --del-sendas <user>
103
Chapter 8. User Management List all users who are in the list of the delegate.
zarafa-admin --list-sendas helpdesk Send-as list (1) for user helpdesk: Username Fullname ----------------------------john John Doe
Note
With the Unix plugin sendas permissions can not be configured on groups.
Note
When both the "send on behalf of" and "sendas" permissions are configured on the same user, the email will always be sent with "on behalf of".
Using the options -l or -L, a list of users or groups can be listed from the server. All created users will be member of the group Everyone, this can not be changed. Groups created with unix plugin can be used both for configuring permissions and sending emails to a specific group.
The Zarafa user synchronization principle Various LDAP server systems are supported, and Zarafa will communicate with any standard LDAP protocol version 3 or later server. This means Zarafa works in combination with industry-standard solutions as Microsoft Active Directory, OpenLDAP and eDirectory. This chapter describes loosely how Zarafa uses the LDAP server as a source for user, group, contact and company information. In most cases, the particular setup used will require other options and settings than those described in this document. It is therefore assumed that the reader has a good understanding of how LDAP trees work, and how they are configured in their network. For more information, please refer to the example configurations and manual pages available on all systems on which Zarafa is installed.
Chapter 8. User Management Synchronisation between the LDAP and Zarafa server need to be forced with the following command:
zarafa-admin --sync
User management from ADS The following information is required from the LDAP server: User details (name, email address, etc) Contacts (name, email address) Group details (name of group) Company details User/Group relationships (group membership) Company members (users and group membership) Company relationships (cross-company view and administrator permissions) The objects that are classified as users, contacts, groups, dynamic groups, addresslists or companies and the attributes that contain the data can be configured within the Zarafa configuration files, so Zarafa can meet the LDAP schema needs. However, here are some pointers to keep the LDAP repository clean and easy-to-manage: Always use some sort of graphical user interface for user and group management. There are many 1 LDAP configuration tools. (For example, phpLDAPadmin for OpenLDAP as a web based interface) If there are users that will be using Zarafa, while other users will not, try to group these users into separate folders. An OU record or any other dc-type object can be used to create these folders. If Microsoft Active Directory is run, make sure that the real users are in a separate LDAP folder so that Zarafa doesnt need to import the standard users like Administrator and Guest into the database. It is also possible to filter the users using an LDAP search query, but these search queries can become unsatisfactorily large when using ADS. As a general rule, always use the LDAPS (SSL) protocol while contacting the LDAP server. When SSL is not used, information will be transmitted clear-text over the wire. This opens possibilities to sniffing user (and administrator!) passwords from the network wire. Zarafa supports connecting through LDAP via SSL and a certificate specified in /etc/ldap/ldap.conf which is compatible with both Microsoft Active Directory as OpenLDAP servers. Zarafa does not yet currently support STARTTLStype encryption. More information about setting up Active Directory with SSL support can be found on http://wiki.zarafa.com.
107
108
For example:
zarafa-admin --list-sendas helpdesk Send-as list (1) for user helpdesk: Username Fullname ----------------------------john John Doe
The users that have the sendas permissions, should now be able to add the other address in the FROM field and sendas this account. Since ZCP 6.40 the sendas system is changed: Configuring the sendas permissions is the other way around than previous Zarafa versions. Sendas permissions now have to be configured on the user which is select as the FROM address. 109
Chapter 8. User Management See Section 3.5.1, Pre 6.40 upgrade steps for converting the sendas permissions. Groups can now also be used for setting sendas permissions.
Figure 8.3. Addresslists in the Address book To setup an addresslist in Active Directory its required to have the Zarafa ADS plugin installed. 1. Select a folder in the Active Directory tree from the Users and Group console 2. Create the new addresslist by Action > New > Zarafa Addresslist 3. Insert the name of the addresslist 4. Open the properties of the new created addresslist 5. Add a search filter for the address, see Section 8.6, LDAP Condition examples for example condition queries.
110
Figure 8.4. Hide a user from the Global Address Book using Active Directory
Note
The internal System user and the Everyone group can be made hidden in the /etc/zarafa/ server.cfg.
For example:
zarafa-admin --list-sendas helpdesk Send-as list (1) for user helpdesk: Username Fullname ----------------------------john John Doe
The users that have the sendas permissions, should now be able to add the other address in the FROM field and sendas this account. Since ZCP 6.40 the sendas system is changed: Configuring the sendas permissions is the other way around than previous Zarafa versions. Sendas permissions now have to be configured on the user which is select as the FROM address. See Section 3.5.1, Pre 6.40 upgrade steps for converting the sendas permissions. Groups can now also be used for setting sendas permissions.
Note
When using groups for the sendas permissions, make sure the ldap_sendas_attribute_type is set to dn. See the following LDAP configuration:
112
Figure 8.5. Addresslists in LDAP After restarting the zarafa-server, the addresslists should be visible in the global addressbook.
Note
The internal System user and the Everyone group can be made hidden in the /etc/zarafa/ server.cfg.
113
Chapter 8. User Management This example selects all users with mailaddress [email protected] or [email protected].
(|([email protected])([email protected]))
For Active Directory or OpenLDAP setups (using the ldap or ldapms user plugin), the features will be managed from two LDAP attributes zarafaEnabledFeatures and zarafaDisabledFeatures. Make sure the latest schema file or Active Directory plugin is installed, before using these attributes. These multi-valued attributes can contain any string, but only the features Zarafa knows about will actually be provided through the system.
114
Resource configuration
Note
Make sure a particular feature isnt listed in both zarafaEnabledFeatures and zarafaDisabledFeatures. Consistency will not be guaranteed.
Chapter 8. User Management On the Tools menu, click Options, and then click Calendar Options. Under Advanced options, click Resource Scheduling Enable the automatic acception of meeting request If the resource should decline double bookings of the resource or bookings of recurrent meetings, the options "Decline recurrencing meeting request" and "Decline conflicting meeting requests" should be enabled. Configure the permissions on the calendar of the resource, so the users can book the resource. Users should have at least write permissions to the calendar of the resource. To configure the resource with the zarafa-admin tool, use the following command:
zarafa-admin -u <resource name> --mr-accept 1
The resource will now automatically accept meeting requests. To decline double booking or recurrent meeting, use:
zarafa-admin -u <resource name> --mr-decline-conflict 1 zarafa-admin -u <resource name> --mr-decline-recurring 1
After the automatic acception of meeting requests is configured, make sure the users have permissions at least write permissions on the calendar of the resource. The permissions can be configured by opening the resource mailbox to an administrator user and setting the permissions. To automatic book a resource make sure the resource option is really selected in the Freebusy times when schedulign the meeting.
116
Resource booking methods Both methods are used to book resources; The final outcome is that the user can book a resource, after which the resources calendar will show that it is busy for the allocated timeslot. Both methods support declining recurring and conflicting meetings, but the way that they work differ in various ways: Table 8.2. Table Comparison of resource booking methods Direct booking Books directly in target calendar Needs read/write access to resources calendar Possible to limit bookers through permissions Does not support multiple resources using the same calendar Doesnt work with external bookers MR booking Sends meeting request which is responded to Needs no read or write access to resources calendar Not possible to limit bookers Possible to set double-booking limit to 2 or higher for equipment Works with external bookers
Other versions of outlook also support the registry key for disabling direct booking. For more information, see http://support.microsoft.com/kb/982774
117
Booking by meeting requests works exactly the same as sending a meeting request to another user; When booking the resource, a user sends a meeting request to the resource in an e-mail. The resource then receives the e-mail, checks availability and replies to the meeting requests just like a human user would; the booker receives and Accepted or Declined meeting response by email. This means that when the meeting is sent to the attendees, the resource has actually not been booked yet; it is possible that another user has booked the resource in the mean time, resulting in a declined response from the resource. The booker must then re-schedule and send all participants an update. The main advantage of this method is that the booker neednt have write permissions on the resources calendar. Also, the MR method allows for more flexible handling of meeting requests. For example, if the user has 5 projectors, which have been created as a resource, then they could be created as 5 separate resources, each of which would normally be directly booked. However, this would require the user to search for a free projector and book that specific projector. With MR booking, the administrator can set the equipments capacity to a number other than 1, for example 5 in this case. The administrator then only needs one resource with a capacity of 5 to represent all the projectors. When the MR is processed by the resource, it will check whether all projectors were booked at that moment, only declining when all 5 projectors were not available at that moment. Please note that you must use the equipment type for your resource if you wish to use the capacity feature. The capacity of room resources is ignored (you can not double-book a room). MR booking is processed by the zarafa-mr-accept script which is installed by default. This script is triggered by zarafa-dagent in both direct and LMTP mode when the destination users mr-accept setting is set to TRUE AND the incoming message is a meeting request or meeting cancellation. If the zarafa-mr-accept script fails, delivery processing is done as usual, possibly triggering delivery rules and out-of-office messages.
This will enable or disable direct booking. Disabling direct booking implies that MR booking will be used. For Zarafa WebAccess, you can set the booking method by setting
define('ENABLE_DIRECT_BOOKING', true)
in config.php 118
Mailbox Storage Relocator This will enable or disable direct booking, mirroring the behaviour in Outlook. If you disable direct booking, MR booking will be used.
Note
The zarafa-msr can only be used in multi-server setups. Multi-server support is available in the Zarafa Enterprise and Hosted edition.
8.9.1. Prerequisites
Python 2.5 or above Python MAPI binding Zarafa 6.40.5 or above
8.9.2. Invokation
The only argument required by zarafa-msr is an configuration file specifying the details of the relocation operation.
zarafa-msr config.cfg
where x denotes the number of migrated mailboxes. The administrator can now stop zarafa-msr by pressing Ctrl-C. zarafa-msr can safely be stopped at any time by pressing Ctrl-C. On the next run it will continue where it left off when it was stopped.
Note
Running zarafa-msr after the LDAP/ADS has been modified will not work, because it will automatically connect to the new server for the source mailbox.
119
8.9.4. Configuration
A typical configuration file looks like this:
[Connection] serverpath: file:///var/run/zarafa sslkey_file: ssl.cert sslkey_pass: pass [Servers] server_alias1: https://server1:237/zarafa [Mapping] user1: https://server2:237/zarafa //user2: %(server_alias1)s [Logging] log_file: /var/log/zarafa/msr.log
As many items as needed can be placed in this section. To relocate the public store a special name should be used for the username: 120
Configuration 1. In a multi-tenant environment, the name of the tenant for which to relocate the public store must be used. 2. In a single-tenant environment, the special name public must be used.
121
122
Chapter 9.
Performance Tuning
When installing a Linux server with Zarafa, it is imperative that MySQL is correctly configured to achieve maximum performance on the server; almost all performance bottlenecks are within the database access itself, so getting the SQL queries to run as quickly as possible is very important. For large installations, it is strongly advised to tune Zarafas cache parameters as well; These are normally set quite low to make sure that Zarafa can run on relatively low-end servers, but in anything but the smallest installations, these defaults needs to be upped. Any installation with 50 or more users should definitely tune the cache parameters for maximum performance. This document assumes the primary role of the server is to run Zarafa. Always make sure that other factors are taken into account for example an anti-spam system or a webserver running a site other than the Zarafa WebAccess. More information about performance tuning can also be found on http://wiki.zarafa.com.
Chapter 9. Performance Tuning Zarafa is specifically designed to make use of the large amounts of RAM that is available in modern servers. On the other hand, please remember that in normal Linux server the maximum amount of usable RAM in a 32-bit server is 3Gb unless PAE (physical address extension) is supported in the kernel, CPU and mainboard. If more than 3Gb is needed without some sort of limitation, use a 64 bit system, a 64 bit Linux OS, and a 64 bit Zarafa package.
Zarafas Cell Cache (cache_cell_size) innodb_log_file_size: 25% of the innodb_buffer_pool_size innodb_log_buffer_size: 32M This will cause around 50%-60% of the RAM to be tied up in caches for MySQL and Zarafa. The actual memory usage of the MySQL and Zarafa will then be slightly more than this, giving a total of around 80% of RAM size. Please refer to the MySQL documentation for the setting of the innodb_log_file_size and related settings, as these should also be somewhat higher than the defaults to increase write performance. They dont affect read performance. The 4 settings will now shortly be discussed to illustrate the need of each of these cache settings.
126
Chapter 10.
As can be seen, the most common restore request can be performed by the user itself. This is because the softdelete system is accessable through Outlook. When older messages are requested to be restored, the Administrator will need to consult the backups. It is not possible to restore a single item with a MySQL dump, so this is the point where the zarafa-backup tool steps in. The bricklevel backups from the zarafa-backup tool contain not enough information for disaster recovery. A complete dump of the MySQL database will be needed to perform this type of recovery.
127
128
Backup format
129
Chapter 10. Backup & Restore or for all users and public folders:
zarafa-backup -a
There are a few things to notice about this behavior of the backup tool. When the lists of the previous index and the current contents of the store are compared, it does this per matching container. This means that if the user moved items from one folder to another, they will not be found, thus will be backed up again because they will be marked as new in the other folder they were moved to. If a message was changed by the user since the last backup, the item will have a new last modification date, and will be backed up again in its totality since the backup would become unbearably slow if it would need to check all the properties of a message to see which property changed and which not. Overwriting the old message is also problematic because the new message may be bigger than the old, and it will not fit on the old space of the message. Then when the actual backup process starts, it will first remove the old index. The index file will then be rebuild while the backup processes each message found in the list. The data file will be appended with the new data, keeping the old information which was still available and did not need to be stored again. For more options of the zarafa-backup tool use:
man zarafa-backup
When the items are found, place the restore keys in a separated file, or give them as parameters to the zarafa-restore tool. If the restore key of a container is entered, the complete container with all its items will be restored on one level. If the subcontainers of the selected container need to be restored, add the -r parameter to the command. The following example restores the inbox with subcontainers from userA. The restore key AF000000 is found in the userA.index.zbk file and needs to be defined at the end of the command.
zarafa-restore -u userA -r -c userA.index.zbk AF000000
The --c parameter as a reference for the index file is not necessary when using an index file from the same user. For example, if using zarafa-restore --u userA, the zarafa-restore tool will automatically use the userA.index.zbk file when index.zbk is in the same directory as where the command is executed. In the next example a file (keys.txt) containing multiple restore keys from multiple items and folders from user userA is used. Every restore key in the file needs to be separated with a new line.
zarafa-restore -u userA --r --i keys.txt
130
Restore process To do a full mailbox restore of an user, the following script can be used.
/usr/share/zarafa-backup/full-restore.sh <username>
Please make sure the script is executed from the backup directory. To restore a full mailbox to another user, use:
/usr/share/zarafa-backup/full-restore.sh <username> <destination_username>
For more options of the zarafa-restore tool, please check the man page.
man zarafa-restore
131
132
Chapter 11.
11.1.1. Software
To use BlackBerry Enterprise Server (BES) with Zarafa, the following software packages are needed: Zarafa client 6.40.5 of higher Zarafa BES connector BlackBerry Enterprise Server 5 or Blackberry Enterprise Server Express for MS Exchange Microsoft Outlook 2003 or 2007 Microsoft CDO (part of Office 2003 installation or separate download for Office 2007) A ZCP 6.40.0 or 6.30.18 or later server package, running and configured, is also required.
Important
If a self-signed certificate is being used (very likely), then outlook MUST be started under the user account which BES is using and connect to the server once using SSL. This will pop-up the SSL warning dialog which allows a remember this choice option. If this is not selected, problems will arise with calendar synchronization later on. If a cluster is being run, each server must be connected to.
133
Important
BES 5.0 requires an Active Directory Server for installation. However, this is only needed during installation and is not required while the server is running. Also, the machine installing BES5 must be a domain member, even though everything can be installed using a local Administrator account. If neither of these is available, the installation will fail to complete.
1. Make sure the ZCP server is setup correctly for SSL (see previous step). 2. Install Outlook (In Outlook 2003, use the custom install mode to enable CDO). 3. Install CDO (only needed when using Outlook 2007). 4. Make sure to copy cdo.dll and gapi32.dll from c:\program files\common files \system\msmapi\langid to c:\windows\system32, otherwise blackberry server will be unable to detect CDO. 5. Install the Zarafa Windows Client. 6. Install the Zarafa BES connector. 7. Start+Zarafa++Zarafa BES connector++Create MAPI profile+. This will prompt for Zarafas server address, username and password. An Admin account should be specified here to create the profile. It is recommended SSL is used here, because it will expose any problems with the SSL setup early on. 8. Find any files on the machine called ems*32.dll (normally any of emsui32.dll, emsmdb32.dll and emsabp.32.dll) and replace each of them with the supplied emsmdb32.dll in the program files folder for the Zarafa BES Connector. 9. Set the correct path, password of the SSL key and the server address in file C:\Program Files \Zarafa\Zarafa BES Connector\exchange-redirector.cfg 10. Be sure that all steps (1-10) are done and reboot the machine. 11. Start the BES Installer. 12. When prompted, ignore the warning about the required MAPI libraries. 13. The Administrator account which is requested during the BES installation must be the Administrator of the Active Directory and the Windows domain 14. When prompted for the Exchange server and the mailbox account, please use the Zarafa Server address and admin account of step 7. 15. When prompted, ignore the warning about the Exchange View Only Administrator privileges. 16. To login to the BES Administration Webservice use BES Authentication if the Active Directory is only temporarily setup for BES installation Installation should then complete as normal and the Blackberry services will be automatically started.
134
BES Errors
Note
It is impossible to contact any exchange server from the machine after installing the ems*32.dll files.
Note
Some hints and tricks for the ZCP BlackBerry integration can also be found on http:// www.zarafa.com/wiki/index.php/Blackberry_integration.
135
136
Chapter 12.
This perl script upgrades the database from 4.1 to the 4.20 format. These are changes that regard how users are stored in the database. This script is required, and should be run as follows:
perl /usr/share/doc/zarafa/db-convert-4.1-to-4.2 \ <dbuser> <dbpass> <dbname>
Replace <dbuser> with the username used to connect to the database. Replace <dbpass> with the password of the database user. If there is no password, enter 2 '' single quotes here. Replace <dbname> with the name of the Zarafa database. This will result in something like:
perl /usr/share/doc/zarafa/db-convert-4.1-to-4.2 root '' zarafa
db-convert-4.20-to-4.21
This perl script upgrades the database from 4.20 to the 4.21 format. It will replace an indexing key to improve database speed. This script is highly recommended, and should be run as explained for the db-convert-4.1-to-4.2 script. Depending on the size of the database and the speed of the system, this script might take a while, but it will probably complete within 10 to 30 minutes.
db-convert-4.20-to-innodb.sql
This SQL script converts the converted 4.20 database to InnoDB format. Installations that started at version 4.0 created MyISAM tables. However, the current SQL database layout is optimized for the InnoDB format. Therefore, converting the MyISAM database to InnoDB will result in a huge speed increase. Also, the InnoDB format is less error prone and has less overall table locking. It is highly recommended to convert the database to InnoDB. On the MySQL prompt, import the script:
mysql> source /usr/share/doc/zarafa/db-convert-4.20-to-innodb.sql
Depending on the size of the database and the speed of the system, this script will take a long to very long time. Reserve up to 8 hours of time for this conversion to complete for a database with several gigabytes of data. If the MySQL memory settings are optimized before this script is started, it will run much faster.
db-convert-4.2x-to-5.00
137
Chapter 12. Appendix A; Pre-5.2x upgrade strategies This perl script upgrades the database from 4.2x to the 5.0 format. This script calculates and adds a store column to the properties table. This makes the table sorted on the disk, increasing data throughput. Execute this script as described for the db-convert-4.1-to-4.2 script. Depending on the size of the database and the speed of the system, this script might take a while, but it will probably complete within 10 to 30 minutes on a fast machine.
Note
It advisable to start this script with screen, so this script can continue in the background.
The Zarafa services did not daemonise in versions before 5.0. However, versions 5.0 and newer do daemonise, and run in the background. To revert this behavior, use the -F switch of a service to keep it running in the foreground. Other configuration changes are found in the gateway. The defaults for the ssl_private_file_key and ssl_certificate_file have been changed. The default directory is now /etc/zarafa/ gateway/, to distinguish it from the service ssl files.
138
Chapter 13.
zarafaQuotaOverride
This attribute is used to override the default quota, which configured in the /etc/zarafa/ server.cfg. This attribute always need to enabled to use a custom quota setting. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.1.1 Integer Single-Valued
zarafaQuotaWarn
This attribute contains the warning quota level in Mb. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.1.2 Integer Single-Valued
zarafaQuotaSoft
This attribute contains the soft quota level in Mb. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.1.3 Integer Single-Valued
zarafaQuotaHard
This attribute contains the hard quota level in Mb. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.1.4 Integer Single-Valued
zarafaUserDefaultQuotaOverride
This attribute will override the system wide quota settings for all users within the company. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.1.5 Integer Single-Valued
139
zarafaUserDefaultQuotaWarn
This attribute contains the warning quota level in Mb for all users with the company. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.1.6 Integer Single-Valued
zarafaUserDefaultQuotaSoft
This attribute contains the soft quota level in Mb for all users with the company. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.1.7 Integer Single-Valued
zarafaUserDefaultQuotaHard
This attribute contains the hard quota level in Mb for all users with the company. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.1.8 Integer Single-Valued
zarafaAdmin
This attribute will make a user Zarafa administrator. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.1 Integer Single-Valued
zarafaSharedStoreOnly
This attribute will configure a mailbox as a shared store. On shared stores you will not be able to login. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.2 Integer Single-Valued
zarafaAccount
This attribute can be used in the LDAP search filters to filter users and groups. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.3 Integer Single-Valued
zarafaSendAsPrivilege
This attribute will contain users or groups that should have sendas permissions on the user where this attribute is added. 140
zarafaMrAccept
This attribute will configure auto-acception of meeting requests. This attribute is not used in the current Zarafa versions. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.5 Integer Single-Valued
zarafaMrDeclineConflict
This attribute will decline meeting requests when the calendar contains already appointments. This attribute is not used in the current Zarafa versions. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.6 Integer Single-Valued
zarafaMrDeclineRecurring
This attribute will decline meeting requests when they are set as recurrent. This attribute is not used in the current Zarafa versions. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.7 Integer Single-Valued
zarafaId
This attribute can be used a generic unique id for example users and groups. This attribute is default not used by Zarafa. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.8 Integer Single-Valued
zarafaResourceType
This attribute will configure the resource type of a shared store. The available options are Room or "Equipment" OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.9 DirectoryString Single-Valued
141
zarafaResourceCapacity
This attribute will number of rooms or equipment available. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.10 Integer Single-Valued
zarafaHidden
This attribute will hide the object in the Global Address Book. Keep in mind that objects are never hidden for administrator users. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.11 Integer Single-Valued
zarafaEnabledFeatures
Controls which features are explicitly enabled for a user, and overrides any disabled features in the server disabled_features setting. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.13 String Multi-Valued
zarafaDisabledFeatures
Controls which features are explicitly disabled for a user. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.2.14 String Multi-Valued
zarafaAliases
This attribute will contain all other email addresses and aliases for the user. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.3.1 DirectoryString Multi-Valued
zarafaUserServer
This attribute will the homeserver of a user when running in multi-server mode. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.1.4.1 DirectoryString Single-Valued
142
zarafaSecurityGroup
This attribute will specify whether a group has security possibilities. When the attribute is set to 0, the group will be seen as distribution group. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.2.2.1 Integer Single-Valued
zarafaViewPrivilege
This attribute will contain companies with view privileges over the selected company. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.3.2.4 DirectoryString Multi-Valued
zarafaAdminPrivilege
This attribute will contain users from different companies which are administrator over selected company. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.3.2.5 DirectoryString Multi-Valued
zarafaSystemAdmin
This attribute will specify the user who is the system administrator for this company. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.3.2.6 Integer Single-Valued
zarafaQuotaUserWarningRecipients
This attribute will contain users who will receive a notification email when a user exceeds his quota. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.3.1.5 DirectoryString Multi-Valued
zarafaQuotaCompanyWarningRecipients
This attribute will contain email address who will receive a notification email when a company exceeds his quota. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.3.1.6 DirectoryString Multi-Valued
143
zarafaCompanyServer
This attribute will contain the home server of a company when running in multi-server mode. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.3.4.1 DirectoryString Single-Valued
zarafaHttpPort
This attribute will contain the port for the http connections when running in multi-server mode. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.4.4.1 Integer Single-Valued
zarafaSslPort
This attribute will contain the port for the https connections when running in multi-server mode. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.4.4.2 Integer Single-Valued
zarafaFilePath
This attribute will contain the unix socket or the named pipe of the server when running in multi-server mode. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.4.4.3 DirectoryString Single-Valued
zarafaContainsPublic
This attribute will enable the public store for a specific multi-server node. Make sure only one node has enabled this attribute. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.4.4.4 Integer Single-Valued
zarafaFilter
This attribute will contain the LDAP filter to apply for an addresslist or dynamic group. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.5.5.1 DirectoryString Single-Valued
144
zarafaBase
This attribute will contain the LDAP search base to apply for an addresslist or dynamic group. OID Syntax Multi- or Single-Valued 1.3.6.1.4.1.26278.1.5.5.2 DirectoryString Single-Valued
145
146