# 5. Configure KC Components¶

Most KC and 3rd party components are configured by a configuration file. This section explains most common options that are set to get these components up and running. It is important to note that components usually have to be restarted to make use of updated configuration files, read more about this in the Managing KC Components.

In short, after modifications have been made to a component’s configuration file, that component has to be restarted e.g. with:

/etc/init.d/kopano-<component name> restart
# or
service kopano-<component name> restart
# or
systemctl restart kopano-<component name>


## 5.1. Configure the Kopano Server¶

The Kopano Server component is configured by a system-wide configuration file, usually located here:

/etc/kopano/<component name>.cfg


When installing KC an example of this file is put here:

/usr/share/doc/kopano-<component name>/example-config/kopano-<component name>.cfg


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 kopano-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 Kopano Server.

The Kopano 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 Kopano Server uses to connect to the database has all privileges, including the right to create a new database. Also make sure to give the user enough permissions to connect from localhost to this database, or –if the Kopano server connects over the network to the MySQL database– allow it to connect from the IP-address from which the Kopano Server will connect.

For example the following MySQL statement grants all privileges to user “kopano” with password “password” from localhost:

GRANT ALL PRIVILEGES ON kopano.* TO 'kopano'@'localhost' IDENTIFIED BY 'password';


If you want to restrict the privileges of the kopano connection, the following grant command lists only the required privileges:

GRANT ALTER, CREATE, CREATE ROUTINE, DELETE, DROP, INDEX, INSERT, LOCK TABLES, \
SELECT, UPDATE ON kopano.* TO 'kopano'@'localhost' IDENTIFIED BY 'password';


To configure the Kopano Server to use the MySQL server the options starting with mysql in the kopano-server.cfg need to be set. Once this is setup the Kopano Server should start normally.

## 5.2. Configure language on RPM based distributions¶

After the creation of new users the Kopano Server will automatically create the actual mailbox. This mailbox is by default created in the language of the Linux server. When another language is required the following configuration file has to be changed:

/etc/sysconfig/kopano


Change the option KOPANO_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.

The option LC_CTYPE in the /etc/sysconfig/kopano file can be used to start the Kopano 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.

Important

When upgrading from an earlier KC version, please review the language settings as from KC 7.0.0 the locale has to be set in UTF-8.

## 5.3. Configure language on Debian based distributions¶

When adding new users the Kopano Server will automatically create the actual mailbox. The mailbox is by default created in english language. To create the mailboxes in English, it is required to have the en_US.UTF-8 locale installed.

When the mailbox should be created in another language the following configuration file has to be updated/created:

/etc/default/kopano


Add/Change the option KOPANO_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 correct language packs are installed and configured.

To install a language pack on an Ubuntu based system, use the following command (this example is for the Dutch -nl pack):

apt-get install language-pack-nl


On Debian based systems the locale needs to be enabled in /etc/locale.gen. The following command can be used to easily enable and generate the needed locales:

dpkg-reconfigure locales


The option LC_CTYPE in the /etc/default/kopano file can be used to start the Kopano 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.

Important

When upgrading from an earlier KC version, please review the language settings as from KC 7.0.0 the locale has to be set in UTF-8.

In Debian distributions the follwing entry in /etc/apache2/envvars needs to be set to force the locale for Apache, else locale specific characters might not be displayed correctly in the WebApp.

## 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


## 5.4. User Authentication¶

Another important configuration option for the Kopano Server is the user_plugin. This setting determines which back-end is used for managing users and groups. There are three options, namely db, unix and ldap.

By default the db plugin is used as it does not require any further configuration. The ldap plugin is used most in larger setups as it proves to be most flexible and integrates nicely with an organization’s the existing infrastructure. The ldap plugin can optionally also hold the required configuration for a multi-server Kopano environment. Multi-server support is only supported in the Kopano Enterprise edition.

For a comparison between the different plugins, see the table below:

Table 4.1. User plugin comparison

Feature DB Unix LDAP
Create/delete/ modify users yes yes yes
Set aliases On MTA level On MTA level yes
Hide users
yes
Sendas permissions yes yes yes
Sendas permissions of groups
yes
Security Groups yes yes yes
Distribution groups
yes
Hide groups
yes
Dynamic groups
yes
Contacts support
yes
Multi-tenancy support yes
yes
yes
Multi-server support
yes

Important

Although multi-tenancy is already possible when using the DB plugin, we strongly suggest using an LDAP backend when planning to host multiple tenants within one installation.

### 5.4.1. The DB Authentication Plugin¶

This plugin uses the Kopano MySQL database to store user and group information. The kopano-cli tool can be used to manage users.

The DB plugin supports only basic user and group information. For more advanced configurations, we advise to use the LDAP plugin.

For more information about user management with the kopano-cli tool, see User Management.

### 5.4.2. The Unix Authentication Plugin¶

The Unix plugin is used on a server which has all its user information setup in the /etc/passwd file. Group information will be read from /etc/group. Passwords are checked against /etc/shadow, so the kopano-server process must have read access to this file (this process is normally run as root, so usually that is not a problem).

Since the unix files do not contain enough information for Kopano, there are some properties of a user that will be stored in the database. These properties are the email address, overriding quota settings, and administrator settings. The kopano-cli tool has to be used to update these user properties. All other user properties are done using the normal unix tools.

A configuration file, /etc/kopano/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 Kopano 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 kopano-unix.cfg


### 5.4.3. The LDAP Authentication Plugin¶

The LDAP plugin is used for coupling any LDAP compliant server with the Kopano Server. This way, all users, groups and membership information can be retrieved ‘live’ from an LDAP server.

The LDAP plugin support next to the default users, groups and companies also the following object types:

• Contacts - External SMTP contacts which can be used as members of distribution lists
• Addresslists - Sub categories of the Global Address Book, based on a specified LDAP filter
• Dynamic groups - Dynamically created groups, based on a specified LDAP filter. Therefore LDAP plugin is the recommended user plugin for KC.

The Kopano Server needs two configuration directives in the server.cfg configuration file to use the LDAP backend, namely:

user_plugin = ldap
user_plugin_config = /etc/kopano/ldap.cfg


The defaults for OpenLDAP and for Active Directory can be found in the /usr/share/doc/kopano/example-config directory. Based on these examples the /etc/kopano/ldap.cfg file should be adjusted to configure the LDAP authentication plugin.

More details about configuring the LDAP plugin with OpenLDAP, see Configure KC OpenLDAP integration or Configure KC Active Directory integration for Active Directory.

## 5.5. Autoresponder¶

KC 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 kopano-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:

• 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/kopano/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}/kopano-vacation-$USER.db  (file which stores the last date of sending per email address) SENDDBTMP=${TMP:-/tmp}/kopano-vacation-$USER-$$.tmp  (temporary file used during update of the database) SENDMAILCMD=/usr/sbin/sendmail  (command used to send actual vacation message) SENDMAILPARAMS="-t -f"  (parameters used to send actual vacation message) If an alternate autoresponder is required, please refer to the kopano-dagent manual page which describes how to use an alternate script (using the -a option). ## 5.6. Storing attachments outside the database¶ Since KC version 6.0 it is possible to save the attachments outside the database. KC 7.0.5 and higher will use the filesystem as default location for attachment storage. 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/kopano/server.cfg. attachment_storage = files attachment_path = /var/lib/kopano/attachments  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/kopano, and is named db-convert-attachments-to-files. This script can be used as follows: db-convert-attachments-to-files <myuser> <mypass> <mydb> <dest path> [delete]  Note The script can be executed while the kopano-server process is running. 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 KC can be looked up the with the following MySQL statements: use kopano; 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 kopano-server needs to be started once with the --ignore-attachment-storage-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. • Make use of deduplication techniques (for example filesystem capabilities or through hardlinking) to further reduce hard disk space. Disadvantages of attachments outside the database are: • A MySQLdump 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. Important It is very important, when choosing to store the attachments outside the database, to update the backup strategy accordingly. Important When using NFS as storage backend for Attachment-Store or as WebApp TMP_PATH we recommend turning of NFS locking by using the -o nolock mount option as this potentially can cause severe performance penalties. ## 5.7. SSL connections and certificates¶ The Kopano Server is capable of directly accepting encrypted SSL connections. This feature may already be available when the HTTPS Apache server is setup to proxy these connections to the Kopano Server. However, having native SSL connections to the server has an interesting advantage: Kopano components running beyond localhost can login using their SSL certificate. This section will describe how to setup certificates to add native SSL connections to Kopano. First, we will create the directory to contain the certificate and setup the permissions, since it contains our private key. mkdir /etc/kopano/ssl chmod 700 /etc/kopano/ssl  If Kopano 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/kopano 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 ssl-certificates.sh script can be run without problems. Note With the release of Kopano 8.2.0 all Kopano components now check the validity of the CN and subjectAltNames fields of the certificate. Unlike browsers Kopano does not stop at self-signed certificates, so these can use used as well. cd /etc/kopano/ssl sh /usr/share/doc/kopano/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. The Common Name has to reflect the hostname clients will use to connect to. 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  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/kopano/ssl/demoCA/cacert.pem server_ssl_key_file = /etc/kopano/ssl/server.pem server_ssl_key_pass = <password>  Restart the kopano-server process, and now it’s 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. ## 5.8. Configure the Kopano Spooler¶ The Kopano-spooler sends email from the global outgoing queue to a SMTP server, which sends the email to the correct address. When an email message is sent from Outlook or WebApp, the message is placed in the Outbox folder, and a submit message is sent to the Kopano server. The server notifies the Kopano spooler to send the email to the SMTP server. The spooler will now start to convert the message to a normal email message. When the conversion is complete, a connection to the supplied SMTP server is created, and the email is sent to the SMTP server. The spooler will send the email, and after the mail is sent, will move the mail automatically to the user’s 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. ### 5.8.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 Kopano 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 Kopano 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/kopano. [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 kopano-spooler, use: man kopano-spooler.cfg  ## 5.9. Configure Kopano Caldav¶ Kopano Caldav is a component that enables users to view their calendar data by clients that support the Caldav standard, like Sunbird or Evolution. This component connects with the Kopano Server using MAPI over HTTP. Caldav and iCal push and retrieve complete calendars. Sunbird and other clients support both retrieving and pushing, while Evolution does only support retrieving of calendars. The Kopano Caldav component can be configured using a configuration file in the same fashion as the Kopano Server. It supports both plain and SSL/TLS secured connections. To increase security it is recommended to enable secure Caldav connectivity exclusively. The configuration options are: server_bind  IP address to bind to. 0.0.0.0 for any address. Default value: 0.0.0.0 ical_enable  Enable plain service with value yes. Default value: yes ical_port  The plain service will listen on this port for incoming connections. Default Value: 8080 icals_enable  Enable secure service with value yes. Default value: no icals_port  The secure service will listen on this port for incoming connections. Default value: 8443 server_socket  The http address of the Kopano Server. Default value: http://localhost:236/ Important It is not advised to specify the UNIX socket here. In default configuration the Kopano Caldav will then be trusted by the kopano-server (as set in its local_admin_users configuration setting). Unless Kopano 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/kopano/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/kopano/cert.pem ssl_verify_client  Enable client certificate verification with value yes. Default value: no ssl_verify_file / ssl_verify_path  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. ### 5.9.1. SSL/TLS for CalDAV¶ As mentioned before the Kopano 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 Kopano 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/kopano/privkey.pem 2048  This command creates a self-signed test certificate valid for 3 years: openssl req -new -x509 -key /etc/kopano/privkey.pem -out /etc/kopano/cert.pem \ -days 1825  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 sure first the .key file is processed, and then the .cer file. The same approach can be used to include any neccesary intermediate certificates into the file. ## 5.10. Configure Kopano Gateway (IMAP and POP3)¶ The Kopano IMAP & POP3 Gateway enables users to view mail stored on the Kopano Server with an IMAP or POP3 client. For example Mozilla Thunderbird or a mobile device with Microsoft Pocket Outlook. To access the user data, the Kopano Gateway itself connects to the Kopano Server with MAPI. POP3 can only retrieve the mail in the Inbox from the server. IMAP on the other hand displays all folders that can contain mail, such as Drafts and Deleted Items. All sub-folders are shown as in Microsoft Office Outlook or the Kopano WebApp. The Kopano IMAP & POP3 Gateway can be configured with a configuration file. The configuration options are: server_bind  IP address to bind to. 0.0.0.0 for any address. Default value: 0.0.0.0 imap_enable  Enable IMAP service with value yes. Default value: yes imap_port  The IMAP service will listen on this port for incoming connections. Default Value: 143 imaps_enable  Enable secure IMAP service with value yes. Default value: no imaps_port  The secure IMAP service will listen on this port for incoming connections. Default value: 993 pop3_enable  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  Enable secure POP3 service with value yes. Default value: no pop3s_port  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  The http address of the Kopano server. Default value: http://localhost:236/ Important It is not advised to specify the UNIX socket here. In default configuration the Kopano Gateway will then be trusted by the kopano-server (as set in its local_admin_users configuration setting). Unless Kopano 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/kopano/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/kopano/cert.pem ssl_verify_client  Enable client certificate verification with value yes. Default value: no ssl_verify_file / ssl_verify_path  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. ### 5.10.1. SSL/TLS for Gateway¶ The Kopano Gateway supports SSL/TLS using the OpenSSL library. For more information see SSL/TLS for CalDAV, as the options are exactly the same for these two components. ### 5.10.2. Important notes¶ IMAP and POP3 are provided for backward compatibility and will not provide the same experience like clients that support MAPI (Microsoft Outlook or our WebApp). IMAP/POP3 clients use these protocols for mails only (where MAPI does mail, calendar and contacts). Setting the Out of Office message is not possible with IMAP or POP3 clients. Rules set in Microsoft Outlook do not work using the Kopano IMAP & POP3 Gateway. Some clients can set rules but these rules are not related to the rules set by a MAPI enabled client. Deleting a mail using IMAP will mark the mail for deletion. This is not shown in Microsoft Outlook and Kopano WebApp. The mail will be deleted when the client expunges the folder. Some clients allow to expunge folders manually and some have settings when to expunge a folder. Other clients expunge the folder automatically when a mail is deleted. Moving mail to a different folder with IMAP is done by copying the mail to the new folder and mark the originating mail for deletion. As long as the the original mail is not expunged from its folder, the mail will be shown in both folders as stated above. ## 5.11. Configure Kopano Quota Manager¶ Users can collect a lot of email, while disk space can be limited. The Kopano Quota Manager can be used to set server-wide or user specific space quotas. The Kopano Quota Manager knows three levels: warn, soft and hard quota. When one of the levels will be reached, the user receives an email with the quota sizes and which quota level was reached. The quota settings can be configured server-wide in the server.cfg or per user via the user plugin. When a user reaches the warning quota level, the user will receive an email with a warning and quota information. As the user reaches the soft quota limit, the user will not be able to sent email until the size of the store is reduced. When the hard quota limit is reached, email can also not be delivered to that user anymore. ### 5.11.1. Setup server-wide quota¶ The server-wide quota can be configured in the configuration file of the server: quota_warn = 100 quota_soft = 150 quota_hard = 200  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. ### 5.11.2. Setup quota per user¶ By using the kopano-cli tool, the user quota can be set for a specific user. Example: Set the quota of the user John with the settings: Warning level to 80 Mb, soft level to 90 Mb and hard level to 100 Mb. kopano-cli -u john --quota-override yes --quota-warn 80 --quota-soft 90 --quota-hard 100  Note Set user quota with kopano-cli is not supported for the LDAP backend. With LDAP the properties are stored in the LDAP server per user. See the User Management for more information. ### 5.11.3. Monitoring for quota exceeding¶ The kopano-monitor program checks every hour (by default) for users who have exceeded a quota level and sends emails to a user when the warning or soft quota limit is exceeded. Global quota settings can be set in the server configuration. User specific levels can be set via kopano-cli when using the db or unix plugin, or by editing the LDAP values as described in the User Management section. To start the kopano-monitor, use: systemctl start kopano-monitor.service  or kopano-monitor -c /etc/kopano/monitor.cfg  The kopano-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 kopano-monitor.cfg  ### 5.11.4. Quota warning templates¶ When working with the kopano-monitor, it is possible to modify the contents of the email which will be sent out when a user or company exceeds its quota. For each quota level a separate quota template can be specified, these can be configured with the following options: • userquota_warning_template • companyquota_warning_template By default the templates are stored in /etc/kopano/quotamail, in each of these templates certain variables are provided which will be substituted for the real value before the email is sent: • KOPANO_QUOTA_NAME - The name of the user or company who exceeded his quota • KOPANO_QUOTA_COMPANY - The name of the company to which the user belongs • KOPANO_QUOTA_STORE_SIZE - When a user exceeds his quota, this variable contains the total size of the user’s store. When a company exceeds its quota this variable contains the total size of all stores, including the public store within the company space. • KOPANO_QUOTA_WARN_SIZE - The quota warning 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. ## 5.13. Configure Kopano WebApp¶ The Kopano WbApp includes a configuration file, which allows the Administrators for example to define a default language for the WebApp, limit the amount of available languages or disable certain plugins. This configuration can be found in /etc/kopano/webapp/config.php and is also present (as a symlink) in /usr/share/kopano-webapp. In addition this folder also contains configuration files for some of the distributed WebApp plugins like the chat integration or the link to the WebApp manual. With Version 1.4 of the Kopano WebApp two new options were introduced to globally define the time frame for free/busy information. FREEBUSY_LOAD_START_OFFSET defines the amount of days for which old appointments are kept in the free/busy database and FREEBUSY_LOAD_END_OFFSET defines the amount of days for which upcoming appointments are stored in the free/busy database. By default the information for the last seven and the upcoming 90 days are saved. ## 5.14. Configure the Webserver¶ Normally, the Kopano package will configure PHP on the system automatically. In most situations this chapter can be skipped and continued with Configure Apache. ### 5.14.1. Configure PHP¶ PHP is needed in order to use WebApp. The PHP-MAPI extension is installed in the default directory of distribution: • Red Hat Enterprise Linux: /usr/lib/php5/modules/ • SLES: /usr/lib/php/extensions/ • Debian: /usr/lib/php5/20060613/ • Ubuntu: /usr/lib/php5/20060613/ If a different directory for PHP-extensions has been selected, move the mapi.so* files to this location, eg: mv /usr/lib/php/mapi.so* /usr/local/lib/php/  To find the PHP-extensions location, use the following command: php-config --extension-dir  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  Common places for the php.ini file are: /etc/php.ini /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. ### 5.14.2. Configure Apache¶ To correctly load the recently added mapi.so extension, the webserver needs to be restarted. The following example shows how to restart Apache2: /etc/init.d/apache2 restart  or /etc/init.d/httpd restart  #### 5.14.2.1. For WebApp¶ The website files are by default installed in the WebApp directory. Make sure the webclient’s login page can be opened by browsing to the correct url: http://<ip-address server>/webapp/  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 /webapp /usr/share/kopano-webapp/ <Directory /usr/share/kopano-webapp/> AllowOverride None Order allow,deny Allow from all </Directory>  Make sure the correct directory holding the PHP WebApp files is typed. The following command will tell apache2 to reread its config file: /etc/init.d/apache2 reload  The WebApp should now be visible. If it still does not show up, please see Troubleshooting Installation Issues for more information. When leaving the configuration at this point, Apache will request the browsers to cache all files as long as they see fit. This may mean that users are still seeing the old interface while the WebApp package on the server has been upgraded. To fix this, the package comes with an example configuration that includes instructions to the browsers on how long WebApp resources may be kept around. Using this, we are saying that Javascript and CSS files need to be checked against the server versions very often, but Apache can serve these files very quickly from the filesystem. For images, we allow the clients to keep using them for a much longer period (2 months). For this, we use the FileETag setting of Apache to generate a unique identifier for each served static file. To use this, the Apache modules mod_expires and mod_headers need to be loaded. The following can be included in the Apache configuration within the <Directory> directive as described above: FileETag All ExpiresActive On <filesMatch "\.(jpg|gif|png)$">
ExpiresDefault "access plus 2 months"
</filesMatch>

<FilesMatch "\.(js|css)$"> ExpiresDefault "access plus 2 weeks" Header append Cache-Control "no-cache, must-revalidate" </FilesMatch> <filesMatch "\.(php)$">
ExpiresActive Off
Header set Cache-Control "private, no-cache, no-store, proxy-revalidate, no-transform"
</filesMatch>


The example kopano-webapp.conf that comes with the WebApp package contains a more extensive version of this. Especially if you have a lot of users with Internet Explorer, this will be better suited for you than the terse example above.

#### 5.14.2.2. As a HTTP Reverse Proxy for Outlook¶

The transmitted data between the client and server is compressed XML, wrapped in HTTP packets. The use of HTTP allows packets to be forwarded by a proxy (or a webserver with built-in proxy functionality). Please make sure that the proxy fully supports HTTP/1.1 and “Chunked Encoding” is available as a transport.

The following lines are an example of how Apache can be configured to forward incoming connections on port 80 to the Kopano Server on port 236. In case the Apache server also accepts HTTPS connections, the proxyed connections can also be encrypted. The proxy and proxy_html modules of Apache need to be loaded for this to work(for example with a2enmod proxy proxy_http).

<IfModule mod_proxy.c>
ProxyPass /kopano http://127.0.0.1:236/
ProxyPassReverse /kopano http://127.0.0.1:236/
</IfModule>


This means that URLs that begin with /kopano will be forwarded to localhost on port 236, where the Kopano Server listens for incoming connections. These lines can be placed globally, or within a VirtualHost declaration.

Note

Keep in mind that using a HTTP proxy will create some performance overhead on your system, so it is not recommended to use this for larger setups.

Note

Chunked encoding can be forced within Apache by setting SetEnv proxy-sendchunked 1.

Apache 2.2 is known to have some trouble with chunked encoding. Therefore we recommend using Apache 2.4 (or even Nginx) when planning to implement such a proxy.

## 5.15. Configure KC OpenLDAP integration¶

In several network environments OpenLDAP is used to keep track of various bits of information. Mast notably: users and their credentials. Kopano integrates with LDAP server and supports the use of OpenLDAP in particular.

As Kopano doesn’t bundle a LDAP server, this has to be setup separately uf there is not yet a server available in the environment. Please read the documentation of the used Linux distribution on how to setup an OpenLDAP server. Kopano provides an example LDIF file in Appendix C: Example LDIF.

Connections to the OpenLDAP server run over port 389 or 636 (TLS/SSL). For best speed and reliability it is always recommended to install an OpenLDAP server on the same host as the Kopano Server itself. This local server can then be setup to replicate the main LDAP server. Besides performance improvements this also allows the Kopano Server to function even when the main LDAP server is not available.

In the following paragraphs the needed steps are provided to connect Kopano to an existing OpenLDAP tree. The OpenLDAP configuration is usually located in /etc, depending on the used distribution the exact location may vary.

For the official supported distributions the locations are:

• RHEL: /etc/openldap
• SLES: /etc/openldap
• Debian & Ubuntu: /etc/ldap

Through out this guide we will use: /etc/openldap

### 5.15.1. Configuring OpenLDAP to use the Kopano schema¶

To make managing Kopano user easier it is recommended to import the Kopano LDAP schema. The schema can be imported by issuing the following command:

zcat /usr/share/doc/kopano/kopano.ldif.gz | ldapadd -H ldapi:/// -Y EXTERNAL


### 5.15.2. LDAP indices¶

Indexing entries is a way to improve performance performing a filtered search on the LDAP directory. The following table shows the most important attributes to index and the type of index that should be implemented.

Table 5.1. LDAP indices

Attribute name Type
cn pres,eq,sub
gidNumber pres,eq
mail pres,eq,sub
memberUid pres,eq
objectClass pres,eq
ou pres,eq
sn pres,eq,sub
uid pres,eq
uidNumber pres,eq
kopanoAliases pres,eq,sub
kopanoAccount pres,eq
kopanoSendAsPrivilege preq,eq
kopanoViewPrivilege pres,eq

Depending on the Kopano ldap configuration the attributes may be different.

Please check the OpenLDAP or syslog logfiles for further attributes which are not yet indexed and could be included to increase performance. Check below for an example log message:

May 13 14:37:17 kopano slapd[4507]: <= bdb_equality_candidates: (mail) not indexed


When using the cn=config backend the following ldif file can be used to add the given attributes to the index of OpenLDAP:

dn: olcDatabase={1}hdb,cn=config
changetype: modify
olcDbIndex: cn eq
olcDbIndex: gidNumber eq
olcDbIndex: mail eq
olcDbIndex: memberUid eq
olcDbIndex: ou eq
olcDbIndex: uid eq
olcDbIndex: uidNumber eq
olcDbIndex: uniqueMember eq
olcDbIndex: kopanoAccount eq
olcDbIndex: kopanoAliases eq
olcDbIndex: kopanoViewPrivilege eq


To import this the following comman can be used:

cat optimize-index.ldif | ldapmodify -Y EXTERNAL -H ldapi:///


### 5.15.3. Configuring KC for OpenLDAP¶

To integrate KC with an OpenLDAP server change the following option in the ldap.cfg configuration file:

Specify in the ldap_host option the ip-address or server name of the LDAP server.

ldap_host = localhost


By default the plain LDAP protocol will be used. For configuring secure LDAP, change the following settings to use LDAPS and the matching SSL Port:

ldap_port = 389
ldap_protocol = ldap


To connect KC to multiple LDAP servers, use the following setting:

ldap_uri = ldap://ldapserver1:389 ldap://ldapserver2:389


The different ldap uri’s should be seperated by a whitespace. When using the ldap_uri option, the options ldap_host, ldap_port and ldap_protocol are ignored.

The Kopano 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 Kopano 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 = kopano-contact
ldap_company_type_attribute_value = kopano-company
ldap_dynamicgroup_type_attribute_value = kopano-dynamicgroup


Based on the ldap_object_type attribute, the Kopano Server will create an object in the MySQL database, so it gets listed in the Global Address Book. Make sure that the values are always unique for one type of object, as Kopano needs to be able to distinguish the different objects.

#### 5.15.3.1. SSL configuration for OpenLDAP¶

Setting up SSL for OpenLDAP requires you to create an SSL certificate, install the certificate, and set up slapd (the OpenLDAP server process) to accept connections on the SSL port. If you already have an SSL certificate (for example, for Apache), then you can use that certificate for slapd also. First, create a private key with:

openssl genrsa -out private.pem 2048


This will create the file ‘private.pem’ with a 2048-bit private RSA key. You can then create a self-signed SSL certificate with:

openssl req -new -x509 -key private.pem -out cert.pem -days 1825


Make sure that the private.pem file stays secret to anybody except the server process serving the SSL (ie slapd), while the cert.pem file is freely available to clients wanting to access the server. Normally, you would place private.pem in /etc/ldap/private.pem and cert.pem in /etc/ssl/certs/<servername>.pem. You must also create the hash link in /etc/ssl/certs: In debian, this is accomplished by running ‘update-ca-certificates’. In other Linux distributions, you must create the link manually with:

ln -s /etc/ssl/certs/server.pem openssl x509 -noout -hash -in /etc/ssl/certs/server.pem


Configuring OpenLDAP’s slapd to use SSL To configure openldap to use SSL, you need to add the following configuration directives to /etc/ldap/slapd.conf:

TLSCipherSuite HIGH:MEDIUM:+TLSv1:!SSLv2:+SSLv3
TLSCACertificateFile /etc/ssl/certs/server.pem
TLSCertificateFile /etc/ssl/certs/server.pem
TLSCertificateKeyFile /etc/ldap/private.pem
TLSVerifyClient never


The service then needs to be restarted:

/etc/init.d/slapd restart


or

/etc/init.d/ldap restart


Whether the SSL connection works can be tested with:

openssl s_client -connect <ip>:636 -CApath /etc/ssl/certs


To test whether the SSL connection is working correctly with LDAP, use the following command:

ldapsearch -x -H ldaps://openldap.domain.com -b <BASEDN> -D <binddn> -w


### 5.15.4. User configuration¶

Normally a user store is created for each object in the LDAP directory that has the user type attribute as mentioned in the previous section (posixAccount in the previous example). An additional search filter can be specified to limit store creation to a subset of the objects that have the user type attribute. For example:

ldap_user_search_filter = (kopanoAccount=1)


All user related fields can be mapped by the following options:

ldap_user_unique_attribute = uidNumber
ldap_user_unique_attribute_type = text
ldap_fullname_attribute = cn
ldap_emailaliases_attribute = kopanoAliases
ldap_nonactive_attribute = kopanoSharedStoreOnly


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 Kopano Server will perceive that as a user being deleted (and created), and will therefore orphan the user’s 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 with the dagent directly, this needs to be resolved by Postfix.

Extra user information, like addresses, phone numbers and company information can be mapped by an extra configuration file:

!propmap /etc/kopano/ldap.propmap.cfg


The specified attributes for users will also be used for contacts.

### 5.15.5. Group configuration¶

The groups can be filtered by an extra search filter as well.

ldap_group_search_filter = (objectClass=kopano-group)
ldap_group_unique_attribute = gidNumber
ldap_group_unique_attribute_type = text


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 Kopano Server will by default use the unique user attribute as value of the group member attribute. This can be changed by the group member’s 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 kopanoSecurityGroup) must be set to 1. When the kopanoSecurityGroup 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 = kopanoSecurityGroup
ldap_group_security_attribute_type = boolean


Addresslists are groups of users that match a custom condition. These addresslists are shown as sub-folders in the Global Address Book.

Change or add in ldap.cfg the following configuration settings for the addresslist objects:

ldap_addresslist_search_filter =


### 5.15.7. Testing LDAP configuration¶

After the LDAP configuration is done, the changes can be activated by reloading the Kopano Server.

/etc/init.d/kopano-server reload


To test whether users and groups will be listed correctly using the LDAP configuration, use:

kopano-cli --list-users


for users, and for groups:

kopano-cli --list-groups


If no users or groups are shown, please check the Kopano server log file for errors. Setting the log_level to 0x00020003 in the /etc/kopano/server.cfg will display all LDAP queries send to the server and possible errors.

Note

The first time the kopano-cli --list-users is done, all mailboxes will be created, therefore it can take some time before the execution finishes, so be patient.

man kopano-ldap.cfg


## 5.16. Configure KC Active Directory integration¶

### 5.16.1. Installing the Kopano ADS Extension and schema files¶

KC provides an installer for extending the Active Directory schema and installing an Active Directory snap-in for managing the Kopano specific attributes.

With Kopano ADS Extension it is possible to create and modify the following objects in Active Directory:

• Kopano Users
• Kopano Groups
• Kopano Dynamic Distribution Lists
• Kopano Computers (For usage with Multi-Server support)
• Kopano Companies (For usage with Multi-Company support)

Make sure you have prepared the AD role based on the usual best practice. We do not cover details of the setup, just a basic setup howto to get you started with Active Directory.

Before you deploy the AD role, you should make sure the following tasks have been completed:

• The networking has been setup accordingly (static IP)
• The latest windows updates have been installed
• The user the installer is run with, should be part of the “Schema Admins” group

To make your system ready to provide an Active Directory, please follow the following steps. The steps are based on Windows Server 2016, Installation might differ slightly for previous versions.

1. In Server manager, select “Add roles and features” which starts the “Add Roles and Features Wizard”.
2. After confirming the “Before you begin” page as a reminder to the tasks also mentioned above, continue with “Next”.
3. Select “Role-based or feature-based installation”, continue with “Next”.
4. Select the Server you want to install the AD role(s) to, continue with “Next”.
5. Select “Active Directory Domain Services” and confirm the pop-up dialog to add the missing dependencies (including the management tools by keeping the checkmark enabled)
6. Select “Active Directory Lightweight Directory Services” and confirm the pop-up dialog to add the missing dependencies (including the management tools by keeping the checkmark enabled)
7. Continue with “Next” after having selected the roles mentioned above.
8. Continue with “Next” without selecting any additional (required) features.
9. Continue with “Next” confirming the installation of “AD DS” role.
10. Continue with “Next” confirming the installation of “AD LDS” role.
11. Continue with “Install” at the installation page to make the roles available. The checkmark for automatic restart can be set - in any case after deployment of AD a restart is required, whether this is done manually or automatic.

After these steps, with a reboot of the System your Active Directory should available and ready for installation of Kopano AD Extension.

The Kopano ADS Extension should be installed as a local administrator user on the Active Directory server which is the schema master. Following the above statement installs the schema role automatically on the system.

Note

Please restart the GUI after install of the Kopano ADS plugin to show the Kopano tab in the user details.

The Kopano ADS Extension is supported with Windows Server releases from 2008 R2 and 2016. The installation and schema extension are straight forward and it is possible to step through the setup by clicking the next button. The same installer can be used to install the MMC extension for non-AD-controllers to allow management of Kopano objects also remotely.

If the Kopano ADS Extension is installed, it is possible to edit the Kopano specific attributes. For editing a user go to Active Directory Users and Computers, select a user and get the properties. The Kopano tab should be available if the installation is successfully completed.

Figure 5.2. Kopano user tab

Figure 5.3. Kopano group tab

Note

It is also possible to use the Kopano AD Extension with an existing Zarafa-Schema. The installer still installs the Kopano Schema, to allow an administrator-defined timeframe for moving to the new schema. To enable the Zarafa Schema instead of the Kopano Schema, please modify the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Kopano\Kopano ADS\Prefix from “kopano” to “zarafa”.

Note

Starting with version 1.1 it is possible to store a default email domain in the windows registry. For this set HKEY_LOCAL_MACHINE\Software\Kopano\Kopano ADS\MailDomain to your preferred domain. If the key is missing or empty Kopano ADS will fall back to the default behaviour. See KC-670 for more information.

### 5.16.2. Configuring KC for ADS¶

To integrate KC with an Active Directory server change the following option in the ldap.cfg configuration file:

Specify in the ldap_host option the ip-address or server name of the Active Directory server.

ldap_host = 192.168.0.100


By default the plain LDAP protocol will be used. For configuring secure LDAP, change the following settings:

ldap_port = 636
ldap_protocol = ldaps


To connect KC to multiple Active Directory servers, use the following setting:

ldap_uri = ldap://dc1:389 ldap://dc2:389


The different ldap uri’s should be seperated by a whitespace. When using the ldap_uri option, the options ldap_host, ldap_port and ldap_protocol are ignored.

The Kopano 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 Kopano 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 Kopano 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 = organizationalUnit
ldap_dynamicgroup_type_attribute_value = kopanoDynamicGroup


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


### 5.16.3. Setting up Active Directory for SSL access¶

Make sure that the Certificate Authority is installed on the DC running your Active Directory.

Windows 2008

• Open the “Server Manager” and select “Active Directory Certificate Service” in your Domain Controller, click Next
• Click Next
• Select the Services “Certification Authority”, “Certification Authority Web Enrollment”, “Online Responer” and “Certification Enrollment Policy Web Service”, click Next
• Select “Enterprise”, click Next
• Select “Root CA”, click Next
• Select “Create a new private key”, click Next
• Enter the corresponding fields (Example: “Common name for this CA” with “kopano-ad-ca”, “Distinguished name suffix” with “DC=kopano,DC=com”), click Next
• Set the validity period, click Next
• Configure the certificate database location, click Next
• Choose a certificate for SSL encryption (use the recommended), click Next
• Click Next
• Click Install

After installation you can verify the AD certification service in the Server Manager, and from this moment on Active Directory can be accessed via SSL.

### 5.16.4. User configuration¶

Which have specified user type attribute an additional search filter can be specified. For example:

ldap_user_search_filter = (kopanoAccount=1)


All user related fields can be mapped by the following options:

ldap_user_unique_attribute = objectGUID
ldap_user_unique_attribute_type = binary
ldap_fullname_attribute = cn
ldap_emailaliases_attribute = otherMailbox
ldap_nonactive_attribute = kopanoSharedStoreOnly


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 Kopano Server.

The email aliases are shown in the Global Address Book details and can be used for email aliases in Postfix. However, it is not possible to deliver email to email aliases, instead the MTA has to resolve the alias and deliver to the primary adress.

Extra user information, like addresses, phone numbers and company information can be mapped by an extra configuration file:

!include /etc/kopano/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. It’s 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 https://technet.microsoft.com/en-us/library/cc737526(WS.10).aspx.

### 5.16.5. Group configuration¶

The groups can be as well filtered by an extra search filter.

ldap_group_search_filter =
ldap_group_unique_attribute = objectSid
ldap_group_unique_attribute_type = binary


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.

ldap_group_security_attribute = groupType


Addresslists are groups of users that match a custom condition. These addresslists are showed as subfolders of the Global Address Book.

Change or add in ldap.cfg the following configuration settings for the addresslist objects.

ldap_addresslist_search_filter =


### 5.16.7. Testing Active Directory configuration¶

After the LDAP configuration is done, the changes can be activated by reloading the Kopano Server.

/etc/init.d/kopano-server reload


To test users and groups will be listed, use:

kopano-cli --list-users


and

kopano-cli --list-groups


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

The first time the kopano-cli --list-users is done, all mailboxes will be created, therefore it can take some time before the execution finishes, so be patient.

man kopano-ldap.cfg


See User Management for Kopano user management with Active Directory.

## 5.17. KC Postfix integration¶

KC does not include its own MTA, but can be integrated all established MTAs found in modern Linux distributions. Although KC support most Linux MTAs, we advise to use Postfix.

In order to deliver an email into a user’s mailbox, the kopano-dagent is executed. Messages are passed to the kopano-dagent from the standard input or by the LMTP protocol. The usage of LMTP is the recommended delivery method as this enable the Single Instance Attachment Storage.

A few examples of the KC Postfix integration are described in the following sections. Keep in mind that Postfix is very flexible, so many different configurations are possible, most of which are beyond the scope of this document.

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.

### 5.17.1. Configure KC Postfix integration with OpenLDAP¶

The Postfix MTA can connect to an OpenLDAP server to resolve the primary mail addresses as well as aliases of users and groups. The Postfix package in most Linux distributions has LDAP support enabled by default. To read more about Postfix LDAP support see the LDAP README on the Postfix website.

All Postfix configuration files can be found in /etc/postfix directory. The main configuration file is logically called main.cf

By default Postfix will only accept incoming emails from localhost. To accept emails from the complete network, configure the following option:

inet_interfaces = all


In order to make Postfix aware of the local email domains, 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, ldap:/etc/postfix/ldap-groups.cf, ldap:/etc/postfix/ldap-groups-expand.cf
virtual_transport = lmtp:127.0.0.1:2003


All incoming emails are delivered to the LMTP service of the kopano-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 = localhost
search_base = ou=Users,dc=example,dc=com
version = 3
scope = sub
query_filter = (&(objectClass=posixAccount)(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 = (&(objectClass=posixAccount)(kopanoAliases=%s))
result_attribute = mail


To deliver mails to member of a group the email addresses of the individual must be resolved:

For resolving group members create the file /etc/postfix/ldap-groups.cf and add the following lines:

server_host = localhost
search_base = ou=Groups,dc=example,dc=com
version = 3
scope = sub
query_filter = (&(objectclass=kopano-group)(mail=%s))
result_attribute = memberUid


To expand group members’ mail into uid create the file /etc/postfix/ldap-groups-expand.cf and add the following lines:

server_host = localhost
search_base = ou=Groups,dc=example,dc=com
version = 3
scope = sub
query_filter = (&(objectclass=kopano-user)(uid=%s))
result_attribute = mail


Note

While this approach creates an additional query, it has the benefit that the memberOf overlay does not need to be enabled in OpenLDAP.

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 needs to be restarted:

service postfix restart


By default the kopano-dagent is configured to run as a deamon and started at boot time. With the following commands you can check if the default configuration is used.

For RPM based distributions use:

chkconfig kopano-dagent on
service kopano-dagent start


For Debian based distributions enable the kopano-dagent by setting the option DAGENT_ENABLED to yes in the file /etc/default/kopano-dagent. To enable the kopano-dagent at boot time use:

update-rc.d kopano-dagent defaults


Note

It is advised to enable logging of the kopano-dagent when running in LMTP mode for monitoring purposes. Enable the logging options in the kopano-dagent in /etc/kopano/dagent.cfg.

### 5.17.2. Configure KC Postfix integration with Active Directory¶

The Postfix can resolve primary mail addresses and aliases of users and groups from the Active Directory server. The Postfix package in most Linux distributions has LDAP support enabled by default. To read more about Postfix LDAP support see the LDAP README on the Postfix website.

All Postfix configuration files can be found in /etc/postfix directory. The main configuration file is logically called main.cf.

By default Postfix will only accept incoming emails from localhost. To accept emails from the complete network, configure the following option:

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 kopano-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=kopano,ou=Users,dc=example,dc=local
bind_pw = secret
scope = sub
query_filter = (&(objectClass=user)(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=kopano,ou=Users,dc=example,dc=local
bind_pw = secret
scope = sub
query_filter = (&(objectClass=user)(otherMailbox=%s))
result_attribute = mail


Active Directory has the possibility to create distribution groups which can be used as email distribution list in KC. 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 RHEL 4 and 5 these packages can be found here.

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=kopano,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 kopano-dagent is run as a daemon and started at boot time.

For RPM based distributions use:

chkconfig kopano-dagent on
/etc/init.d/kopano-dagent start


For Debian based distributions enable the kopano-dagent by setting the option DAGENT_ENABLED to yes in the file /etc/default/kopano-dagent. To enable the kopano-dagent at boot time use:

update-rc.d kopano-dagent defaults


Note

It is advised to enable logging of the kopano-dagent when running in LMTP mode for monitoring purposes. Enable the logging options in the kopano-dagent in /etc/kopano/dagent.cfg.

### 5.17.3. Configure KC Postfix integration with virtual users¶

If no OpenLDAP or Active Directory Server is available, Postfix can be configured with virtual users in a hash map. In this section we explain how.

By default Postfix will only accept incoming emails from localhost. To accept emails from the complete network, configure the following option:

inet_interfaces = all


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:

virtual_mailbox_domains = example.com, example.org, example.net


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        primary mailaddress of user
john@example.com              john@example.com
user1@example.com             user1@example.com
user1@example.net             user1@example.com
alias_user1@example.com       user1@example.com
info@example.com              user2@example.com, user1@example.com


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 kopano-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 RPM based distributions use:

chkconfig kopano-dagent on
/etc/init.d/kopano-dagent start


For Debian based distributions enable the kopano-dagent by setting the option DAGENT_ENABLED to yes in the file /etc/default/kopano-dagent. To enable the kopano-dagent at boot time use:

update-rc.d kopano-dagent defaults


Note

It’s advised to enable logging of the kopano-dagent when running in LMTP mode for monitoring purposes. To alter logging options for the kopano-dagent, adjust the configuration file: /etc/kopano/dagent.cfg.

### 5.17.4. Configure KC Postfix integration with the DB plugin¶

Alternatively to managing virtual users in a file, the MySQL Database of Kopano can be used to check if a message should be delivered. For this to work most of the configuration for Configure KC Postfix integration with virtual users can be reused.

Note

For this to work Postfix needs the ability to do lookups against a MySQL database. In Debian and Ubuntu this can be accomplished by installing the postfix-mysql package. When using Red Hat or Centos Postfix doesn’t have the mysql module included. Alternatively the Postfix Package from the Centos Plus repository can be used.

Instead of executing virtual_mailbox_maps and virtual_alias_maps against /etc/postfix/virtual, a mysql lookup will be defined inside of main.cf.

alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
virtual_alias_maps = mysql:/etc/postfix/mysql-users.cf


This lookup is defined as pictured below:

# Replace with the user name and password to log into the MySQL server.
user = root
hosts = 127.0.0.1
dbname = kopano
query = select value from objectproperty where \
objectid=(select objectid from objectproperty where value='%s' limit 1) \


This configuration only resolves the primary mail address of an user. Aliases should be kept in the /etc/aliases file or an extra aliases MySQL table.

## 5.18. Configure Z-Push (ActiveSync for Mobile Devices)¶

This chapter describes how to configure the Z-Push software to bridge KC with ActiveSync enabled PDAs and smartphones.

Z-Push is an independent project available as an open source from http://z-push.org/

In this manual only the server part of Z-Push is discussed, please refer to our User Manual for instruction on configuring mobile devices.

Mobile phones, smartphones and PDAs can be synchronized because Z-Push emulates the ActiveSync functionality of a MS Exchange server on the server side, allowing mobiles to synchronize via over-the-air ActiveSync (AirSync). Using Z-Push most mobiles can synchronize without installing any additional software on the device.

Z-Push needs to be installed on a web server. It is highly recommended to use Apache. It is also highly recommended to use PHP as an Apache module.

Important

Z-Push >=2.1 requires KC 7.0.6 or later.

### 5.18.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. Among others the following devices are known to by working with Z-Push:

• Windows Phone 7, 7.5 and 8
• Android phones with Android 4.x and newer
• Blackberry PlayBook and 10 (with ActiveSync)
• other ActiveSync compatible devices

For detailed information about the devices and their compatibility status, please consult the Mobile Compatibility List at http://z-push.org/compatibility

### 5.18.2. Security¶

To encrypt data between the mobile devices and the server, it’s 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 don’t work with self signed certificates. For Windows Phone and Windows Mobile you might need to install the certificates on the device (See Configuring SSL for Windows Mobile and Windows Phone for details).

### 5.18.3. Installation¶

To install Z-Push, simply extract the Z-Push archive to the /usr/share/z-push directory:

mkdir -p /usr/share/z-push
tar zxvf z-push-*.tar.gz -C /usr/share/z-push/ --strip-components=1


The -C option is the destination where the files need to be installed.

Z-Push is using a state directory to store a per-user synchronisation status and a log directory for its default logging. Make sure that the ‘state’ and ‘log’ directories exists and are 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:

mkdir /var/lib/z-push /var/log/z-push
chown www-data:www-data /var/lib/z-push /var/log/z-push


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

Red Hat Enterprise Linux apache apache
SLES wwwrun www
Debian and Ubuntu www-data www-data

On systems with SELinux enabled the security context of these folders might need to be changed, e.g.

chcon -R -t httpd_sys_rw_content_t /var/lib/z-push
chcon -R -t httpd_sys_rw_content_t /var/log/z-push


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 following line to the httpd.conf file:

Alias /Microsoft-Server-ActiveSync /usr/share/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.

To use the full featureset of Z-Push 2 and the z-push-top command line utility, additional php packages are required. These provide SOAP support, access to process control and shared memory.

Table 5.3. Additional packages per distribution

Distribution Package name
Red Hat Enterprise Linux* php-cli php-soap php-process
SLES** php53 php53-soap php53-pcntl php53-sysvshm php53-sysvsem php53-posix
Debian and Ubuntu php5-cli php-soap
• To install the php-process package you need to add an extra channel subscription from the RHEL Server Optional channel.
• The PHP Posix package is included in the SLES SDK Repository.

Important

It is not possible to simply rename the Z-Push directory to Microsoft-Server-ActiveSync. This will cause Apache to send redirects to the smartphone, which will prevent proper synchronization.

Lastly, make sure that PHP has the following settings:

php_flag magic_quotes_gpc = off
php_flag register_globals = off
php_flag magic_quotes_runtime = off
php_flag short_open_tag = on


Set this in the php.ini or in a .htaccess file in the root directory of Z-Push.

If you have several php applications on the same system, you could specify the z-push directory so these settings are considered only there.

<Directory /usr/share/z-push>
php_flag magic_quotes_gpc off
php_flag register_globals off
php_flag magic_quotes_runtime off
php_flag short_open_tag on
</Directory>


If not setup correctly, the smartphone will not be able to login correctly via Z-Push.

Reload Apache to activate these changes.

To use the Z-Push 2.X command line tools, access the installation directory /usr/share/z-push and execute:

./z-push-top.php


and/or

./z-push-admin.php


To facilitate the access symbolic links can be created, by executing:

ln -s /usr/share/z-push/z-push-admin.php /usr/local/sbin/z-push-admin

ln -s /usr/share/z-push/z-push-top.php /usr/local/sbin/z-push-top


With these symlinks in place the cli tools can be accessed from any directory and without the .php file extension.

### 5.18.4. Mobile Device Management¶

Users can remote wipe own mobile devices from Kopano WebApp without interaction of the system administrator by using the Kopano MDM plugin.

The system administrator can remote wipe devices from the command line using the z-push-admin tool.

Starting with Z-Push 2.2.0 it is possible to allow/deny Z-Push access for certain users. For this Z-Push makes use of the enabled/disabled feature functionality of kopano-server (see Kopano Feature management). Z-Push uses the keyword “mobile”.

A more in details explanation of this functionality can be found on the Z-Push Wiki.

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.

Important

Upgrading to Z-Push 2.X from 1.X it is not necessary to copy the state directory because states are not compatible. However Z-Push 2 implements a fully automatic resynchronizing of devices in the case states are missing or faulty. Downgrading from Z-Push 2.X to 1.X is not simple. As the states are not compatible you would have to follow the procedure for a new installation and re-create profiles on every device. States of Z-Push 2.0 and Z-Push 2.1 are not compatible. A state migration script is available in the tools folder.

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.18.7. S/MIME¶

Z-Push supports signing and en-/decrypting of emails on mobile devices since the version 2.0.7.

Important

Currently only Android 4.X and higher and iOS 5 and higher devices are known to support encryption/signing of emails.

It might be possible that PHP functions require CA information in order to validate certs. Therefore the CAINFO parameter in the config.php must be configured properly.

The major part of S/MIME deployment is the PKI setup. It includes the public-private key/certificate obtaining, their management in directory service and roll-out to the mobile devices. Individual certificates can either be obtained from a local (company intern) or a public CA. There are various public CAs offering certificates: commercial ones e.g. Symantec or Comodo or community-driven e.g. CAcert.org.

Both most popular directory services Microsoft Active Directory (MS AD) and free open source solution OpenLDAP allow to save certificates. Private keys/certificates reside in user’s directory or on a smartcard. Public certificates are saved in directory. MS AD and OpenLDAP both use userCertificate attribute to save it.

In Active Directory, the public key for contacts from GAB is saved in PR_EMS_AB_TAGGED_X509_CERT (0x8C6A1102) property, and if you save a key in a contact, it is PR_USER_X509_CERTIFICATE (0x3A701102).

In LDAP public key for contacts from GAB is saved in userCertificate property. It should be mapped to 0x3A220102 in ldap.propmap.cfg (0x3A220102 = userCertificate). Make sure it looks like this in LDAP:

userCertificate;binary::
MIIFGjCCBAKgAwIBAgIQbRnqpxlPa...


Important

It is strongly recommended to use MS AD or LDAP to manage certificates. Other user plugin options like db or unix might not work correctly and are not supported.

### 5.18.8. Configuring SSL for Windows Mobile and Windows Phone¶

If you don’t have a certificate of one of the Certified Authorities, you also need to add the CA Certificate to the Trusted Root Certificates store of the device.

The certificates should be in DER format to install it on a windows device. By default the generated SSL certificates on Linux are in PEM format. The DER certificate is a base64 encoded PEM certificate. You can convert the certificate type by the following commands:

openssl x509 -in ca.crt -inform PEM -out ca.cer -outform DER

openssl x509 -in host.crt -inform PEM -out host.cer -outform DER


where ca.crt is your CA certificate file and host.crt is your certified file.

After converting both certificates you need to copy them to the PDA. It can be e.g. done by putting the files on a local intranet server and accessing them with the device’s browser:

http://intranet/certs/ca.cer

http://intranet/certs/host.cer


By selecting the certificates on your PDA they will be stored in the Trusted Root Certificates store of your device.

### 5.18.9. Troubleshooting¶

#### 5.18.9.1. 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.

#### 5.18.9.2. Synchronization problems¶

Important

The following text regarding debug.txt and WBXML debug applies to Z-Push 1.X versions only. In Z-Push 2 there is a separate log directory and the loglevel is configured in config.php.

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
chmod 777 /var/www/z-push/debug.txt


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 sensitive 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>


#### 5.18.9.3. 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!).

In most cases Z-Push Provisioning will work without any issues.

The following message is shown when the provisioning is requested by the server to mobile.

POST cmd FolderSync denied: Retry after sending a PROVISION command


It’s normal to see this message when a device is reconfigured or e.g. a policy changed. If you see this messages repeated several times (more than 3), then your device is not “understanding” it should execute the provisioning. Follow this procedure to check how to proceed. Look into the Z-Push Mobile Compatibility List to check if this mobile supports provisioning. Some devices like older native Android clients need the LOOSE_PROVISIONING configuration parameter set (see how to set this below).

If your device supports provisioning, try to fully reconfigure the profile on your phone. Try a hard-reset if the error persists

Optionally you may also disable provisioning, however this will also disable the ability to wipe your phone remotely.

Location of the config.php depends on where you installed Z-Push.

Change

define('PROVISIONING', true);


to

define('PROVISIONING', false);


Also in order to enable LOOSE_PROVISIONING, change the following:

define('LOOSE_PROVISIONING', false);


to

define('LOOSE_PROVISIONING', true);

• 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).

If a password contains characters which are encoded differently in ISO-8859-1 and Windows-1252 encodings (e.g. “§”) the login might fail with Z-Push but it works fine with the WebApp. The solution is to add setlocale(LC_CTYPE, “en_US.UTF-8”); to the config.php file.