3. Installing

3.1. System Requirements

3.1.1. Hardware Recommendations

To give an estimate on the resource use of KC 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 and size concerns the storage used in MySQL Server for the mailboxes.

Table 2.1. Minimal Hardware Recommendations

Database Size / Users CPU (Cores) Memory Harddisk RAID level
< 5 GB / 1-25 users 2 2 GB SATA, SAS, 7.2k RAID 1
5 GB - 10 GB / 26-50 users 4 4 GB SAS, 7.2k RAID 1
10 GB - 20 GB / 51-100 users 4 6 GB SAS, 10k RAID 10
20 GB - 50 GB / 101-200 users 6 8 GB SAS, 10k RAID 10
50 GB - 100 GB / 201-300 users 6 10 GB SAS, 10k RAID 10
100 GB - 250 GB / 301-500 users 6 12 GB SAS, 10k RAID 10
> 250 GB / 501-1000 users 8 16 GB SAS or SATA/SSD Hybrid, >= 10k RAID 10

Important

Attachments do not require the same speed that is needed for the database storage. These can be safely put on slower disks/different RAID levels.

Important

Tuning of the server configuration and the individual software components for the specific onsite usage can drastically improve performance of your Kopano Core instance. For more than 500 users and/or a total mailbox storage bigger than 250Gb, as well as any high availability structures it is advised to seek professional engineering support.

3.1.2. Connection/bandwidth Recommendation

In order to seamlessly connect Outlook clients to Kopano the network latency should not be higher than 20ms. Network latencies of 200ms (500ms under exceptional circumstances) should not be exceeded in order to aid the user acceptance.

The needed bandwidth is very much depended on the individual user behaviour. Based on large scale projects we use the following key figures to calculate the minimal needed bandwidth:

For implementations with more than 100 users (with external access) we calculate with an average bandwidth utilization of “x (actual amount of users) * 8kbit/s (ISDN speed)”. In real world scenarios not all users will require exactly the same amount of bandwidth at the exact same time, which still leaves room to serve short term higher demands of single users (like requesting an attachment from the server).

Given these key figures (with +20% TCP protocol overhead) the following minimum bandwidth for Outlook users can be calculated:

Table 2.2. Minimum bandwith Requirements

Amount of users Connection speed Connection speed incl. TCP overhead
25 200 kbit/s 240 kbit/s
50 400 kbit/s 480 kbit/s
100 800 kbit/s 960 kbit/s
150 1200 kbit/s 1440 kbit/s
200 1600 kbit/s 1920 kbit/s
250 2000 kbit/s 2400 kbit/s
500 4000 kbit/s 4800 kbit/s
1000 8000 kbit/s 9600 kbit/s

Of course these are only bare minimums and providing a higher bandwidth will increase download speeds.

3.1.3. Supported Platforms

KC consists of a large variety of components: some back-end components that are run on Linux platforms, and components that can be installed on the computers of end-users. In this section we list the different platforms that we support.

At the start of each general release cycle (like 6.x.x or 7.x.x) we decide which plaforms are supported. Usually that means the current release of that platform and the most recent previous release. During the major release cycle supported platforms can be added but not removed.

Please use the x86_64 or 64bit packages if 64bit hardware and OS are available. It is recommended to run on 64bit whenever possible.

Table 2.3. Supported platforms for KC’s back-end components

OS Release Supported CPU Architectures
Debian 7.x (Wheezy) i386, x86_64
Debian 8.x (Jessie) i386, x86_64
RHEL 6 i686, x86_64
RHEL 7 x86_64
SLES 12 x86_64
Ubuntu 14.04 LTS (Trusty Tahr) x86_64
Ubuntu 16.04 LTS (Xenial Xerus) x86_64
Univention 4.x i386 (only for updates), x86_64

Important

Please be aware that this only specifies the architecture of the operating system and not the architecture of the client used.

These are the supported Microsoft Windows platforms for the components that require a Windows platform, namely: the ADS Plugin.

KC requires a system where glibc’s functions (including semctl) work properly. Systems known to be problematic are for example OpenVZ containers. This is for example due to the lack of /dev/shm being provided as tmpfs. Systems using semi-virtualization where glibc’s default behavior is not maintained are not supported. This does not apply to fully or paravirtual solutions such as KVM, ESX, XEN, Hyper-V or any real isolated container format such as docker or lxc; These solutions are fully supported.

For more information about officially supported clients and support levels, please have a look at the Support Lifecycle document.

3.1.4. Dependencies

In order to build or install KC back-end components a bunch of requirements have to be met. These are the main dependencies of KC:

  • MySQL, without an available MySQL Server the Kopano Server cannot run. There is no requirement to run Mysql Server on the same machine as the Kopano Server, therefor it is not a package dependency. MySQL version 4.0 or lower will not work correctly. KC is tested with MySQL 4.1, 5.0 and 5.1, 5.5 and 5.6.
  • Apache or any other webserver that supports PHP. KC is tested with Apache 2.2 and 2.4.
  • PHP, standalone as CGI or, preferably, as a webserver module. KC is tested with PHP >= 5.3 releases.
  • Libicu library that provides robust and full-featured Unicode and locale support.
  • SMTP server of choice. KC is tested with Postfix, Exim, Sendmail and Qmail.
  • LDAP server of choice (optional for user management). KC is tested with OpenLDAP, eDirectory and Microsoft Active Directory.
  • Catdoc used to index text from Office documents.
  • Poppler-utils used to index text from pdf files.
  • w3m used to index HTML text from email.

Most of these dependencies are resolved automatically by the package manager of the Linux distribution that KC is being installed on. This allows the 3rd party components used by KC 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 KC is installing the packages on one of the Linux distributions we support, allowing the 3rd party components used by KC to be installed automatically through the package manager of the distribution. In this case the 3rd party components are upgraded in a standard way according to that distribution.

Note

If you’re using Debian or Ubuntu and you’re 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 Kopano installation script to complete successfully.

3.2. Installation

There are multiple way to install Kopano Core: (1) through a distribution’s package manager and the package repositories provided by Kopano, (2) by manually installing the individual packages, and (3) from source. The following chapter gives an overview of how to install Kopano Core through repositories and individual packages.

When installing the provided packages, please always use the package provided for the individual distribution. Plese see the istribution list in Supported Platforms for an overview of officially supported distributions. Packages available on the Kopano Downloadserver for distributions not mentioned in this table are provided as-is.

3.2.1. Installing Kopano Core through the Kopano package repositories

To simplify the installation and updating of a Kopano system, Kopano provides packages reprositories for customers with a valid subscription. On overview of the all available repositories can be found at https://download.kopano.io/supported/. The url of each repository consists of the following parts:

The base url of the repository. The is always https://download.kopano.io/supported/. Navigation to this url in a webbrowser gives an overview of all the available products.

The product root. This is the codename of the individual product, followed by a colon (:). For Kopano Core, the product root is “core:”.

The release type. Can either be final, pre-final or master. Kopano products are provided in three different release types. The “master” release is a nightly build of the main development branch of the individual product. The “pre-final” release type includes pre release quality software, like beta or RC releases. The last type “final” included packages that have been released as stable releases.

For production systems we recommend to use packages of the “final” release type, as only these are officially supported.

And the last part is the identifier of the used distribution. The easiest way to check for the correct identifier of your distrubtion is to navigate to this url in your browser. Additionally you can also find a directoy called “tarballs” at this location, this directory also containes tarballs of previous releases.

You can find more information at https://kb.kopano.io/display/WIKI/Install+and+upgrade+Kopano+products+using+repositories

After configuring the desired Kopano Core repository Kopano can simply be installed through the meta package “kopano-server-packages”.

3.2.2. Manually Installing the inidivual Packages

The packaging layout is displayed in the following table. Please note that not all download packages contain all the mentioned packages.

Table 2.5. Package layout

Package name Description
php(5)-mapi / php(7)-mapi Contains the php-mapi extension
python-mapi Contains the Python MAPI bindings for Kopano
python-kopano Contains high-level Python bindings for Kopano
kopano-server-packages Can be used to install the complete KC stack on a server
kopano-archiver Contains the separately distributed kopano-archiver packages
kopano-backup Contains the kopano backup and restore tools
kopano-client Contains the MAPI provider for the MAPI clients
kopano-common Contains shared files between KC services
kopano-contacts Contains the MAPI provider for adding contact folders in the addressbook
kopano-dagent Contains the delivery dagent
kopano-dev Contains C++ Development files for the Kopano Core
kopano-gateway Contains the POP3/IMAP gateway
kopano-gsoap Contains stub generators for gSOAP
kopano-gsoap-doc Contains gSOAP documentation
kopano-ical Contains the iCal library used for Caldav and iCal
kopano-lang Contains translations for Kopano components
kopano-libarchiver Contains the de-stubbing libary for the Kopano Archiver
kopano-libgoogle-perftools Contains libraries for CPU and heap analysis, plus an efficient thread-caching malloc
kopano-libgoogle-perftools-dev Contains development files for the former
kopano-libgsoap Contains runtime libraries for gSOAP
kopano-libgsoap-dev Contains development files for the former
kopano-libical Contains the iCalendar library implementation in C (runtime)
kopano-libical-dev Contains development files for the former
kopano-libmapi Contains the Kopano MAPI libraries
kopano-libvmime Contains the library for working with mime and rfc822 messages
kopano-libvmime-dev Contains development files for the former
kopano-monitor Contains the quota monitor
kopano-presence Contains the Kopano presence daemon
kopano-search Contains the Kopano indexer using the xapian search engine
kopano-server Contains the backend server and configuration files
kopano-spooler Contains the spooler
kopano-utils Contains the administration tools, like kopano-admin and kopano-fsck

// TODO check packages against the build system

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!

3.2.2.1. RPM based distributions

Use the following command to install the KC packages on RPM based distributions:

rpm -Uvh <package files you want to install>

Replace <package file> with the packages found in the tarball. Start with kopano-server-packages (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 SLES).

Note

Using distribution specific packaging tools it may be easier to resolve package dependencies for rpm based distributions. For SLES you should use “zypper in <package>” and for RHEL based system “yum localinstall <package>”. If you have a subscription we recommend the use of our package repositories.

3.2.2.2. DEB based distributions

On DEB based distributions (most commonly Debian and Ubuntu) use:

dpkg -i <package files you want to install>

Note

If you have a subscription we recommend the use of our package repositories.

For MySQL, use:

apt-get install mysql-server

For Apache with the needed PHP support, use:

apt-get install apache2-mpm-prefork libapache2-mod-php5

If the Kopano packages fail to install because of dependencies, please use the following command to install these dependencies:

apt-get -f install

Note

The quickest way to install Kopano is not by one by one selecting packages to install and then resolving their dependencies, but by doing it the other way around. Therefore it is recommended to simply remove packages you explicitly do not want and simply installing the rest by issuing “dpkg -i *.deb” followed by “apt-get install -f” to get the missing dependencies from apt.

3.3. Troubleshooting Installation Issues

3.3.1. Server processes

Make sure at least MySQL 5.0 is installed. The server will only run with this version of the database server or a more recent version.

If errors when loading libraries occur or connecting to MySQL fails, the errors are printed in the log. Always check if the service was started correctly.

When an invalid configuration option is present in a configuration file, the service will not start. The wrong options will be printed on the console.

3.3.2. SELinux

If a distribution in combination with SELinux is used, an error message while logging in may appear when using WebApp. The default message suggests that the entered password is wrong or the Kopano server is not running. When SELinux is enabled, it is blocking the connection from the webserver to the Kopano server.

To create a minimal SElinux policy for Kopano, please walk through the following steps:

  • Create a file kopano.te with the following lines:
module kopano 1.1;

require {
        type var_run_t;
        type postfix_postdrop_t;
        type httpd_t;
        type postfix_pipe_t;
        type initrc_t;
        class sock_file write;
        class unix_stream_socket connectto;
        class fifo_file { write getattr };
}

#============= httpd_t ==============
allow httpd_t initrc_t:unix_stream_socket connectto;
allow httpd_t var_run_t:sock_file write;

#============= postfix_pipe_t ==============
allow postfix_pipe_t initrc_t:unix_stream_socket connectto;
allow postfix_pipe_t var_run_t:sock_file write;

#============= postfix_postdrop_t ==============
allow postfix_postdrop_t initrc_t:fifo_file { write getattr };
  • Compile the Selinux policy with command: checkmodule -M -m -o kopano.mod kopano.te
  • Packade the policy with command: semodule_package -o kopano.pp -m kopano.mod
  • Copy the kopano.pp policy file to the directory: /etc/selinux/targeted/modules/active/modules
  • Now load the policy with the command: semodule -vi /etc/selinux/targeted/modules/active/modules/kopano.pp
  • To check if the policy is loaded, you can use semodule -l

Alternatively 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://selinuxproject.org/page/Main_Page.

3.4. SSL

By default, the WebApp installation requires HTTPS to be configured, which is recommended. When SSL is not desired, it is possible to disable the configuration check for these security options inside the config.php file, and disable the option CONFIG_CHECK_COOKIES_SSL.

The following steps will guide you through the process of creating a self-signed certificate in order to secure Kopano WebApp. In environments where users are going to access WebApp and you do not want them to receive a warning message using a self-signed certificate, please follow the how to on requesting a certificate from an official certificate authority provider, which requires you to generate a CSR (certificate signing request) to get an officially signed certificate.

  • Creating the directory to hold the certificate files:
mkdir /etc/aache2/certs
chmod 700 /etc/apache2/certs
cd /etc/apache2/certs
  • Generating the key for the certificate. Follow the wizard and answer the questions required (as prompted) to generate the certificate.
openssl req -nodes -newkey rsa:2048 -keyout kopano-ssl.key -out kopano-ssl.csr

This creates two files. The file kopano-ssl.key contains a private key; do not disclose this file to anyone. Carefully protect the private key.

In particular, be sure to backup the private key, as there is no means to recover it should it be lost. The private key is used as input in the command to generate a Certificate Signing Request (CSR).

  • You will now be asked to enter details to be entered into your CSR. What you are about to enter is what is called a Distinguished Name or a DN. For some fields there will be a default value, If you enter ‘.’, the field will be left blank.
Country Name (2 letter code) [AU]: NL
State or Province Name (full name) [Some-State]: Zuid-Holland
Locality Name (eg, city) []: Delft
Organization Name (eg, company) [Internet Widgits Pty Ltd]: Kopano
Organizational Unit Name (eg, section) []: IT
Common Name (eg, YOUR name) []: example.kopano.com
Email Address []:

Use the name of the webserver as Common Name (CN). If the domain name (Common Name) is domain.com append the domain to the hostname (use the fully qualified domain name). The fields email address, optional company name and challenge password can be left blank for a webserver certificate.

  • When ordering a certificate, you will need the contents of the kopano-ssl.csr file.
cat /etc/apache2/certs/kopano-ssl.csr

Paste the contents of the file into order form on the website you are ordering from. After receiving the certificate, follow the instructions given by your certificate reseller.

  • Self-signing the certificate (Skip this step if you are purchasing a certificate)
openssl x509 -req -in kopano-ssl.csr -signkey kopano-ssl.key -out kopano-ssl.crt \
        -days 1825