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 250 GB, 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 20 ms. 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 dependent 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) * 8kbyte/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 bandwidth Requirements
| Amount of users | Connection speed | Connection speed incl. TCP overhead |
|---|---|---|
| 25 | 200 kbyte/s | 240 kbyte/s |
| 50 | 400 kbyte/s | 480 kbyte/s |
| 100 | 800 kbyte/s | 960 kbyte/s |
| 150 | 1200 kbyte/s | 1440 kbyte/s |
| 200 | 1600 kbyte/s | 1920 kbyte/s |
| 250 | 2000 kbyte/s | 2400 kbyte/s |
| 500 | 4000 kbyte/s | 4800 kbyte/s |
| 1000 | 8000 kbyte/s | 9600 kbyte/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 7.x.x, 8.x.x or 9.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.
For a supported installation, make sure you use the x86_64 or 64-bit packages. Other architectures (e.g. i586, i686, ppc or arm) are not supported.
Table 2.3. Supported platforms for KC’s back-end components
| OS Release | Supported CPU Architectures |
|---|---|
| Debian 8.x (Jessie) * | x86_64 |
| Debian 9.x (Stretch) | x86_64 |
| Debian 10.x (Buster) | x86_64 |
| RHEL 6 * | x86_64 |
| RHEL 7 * | x86_64 |
| SLES 12 * | x86_64 |
| Ubuntu 16.04 LTS (Xenial Xerus) * | x86_64 |
| Ubuntu 18.04 LTS (Bionic Beaver) | x86_64 |
| Ubuntu 20.04 LTS (Focal Fossa) | x86_64 |
| Univention 4.3 * | x86_64 |
| Univention 4.4 | x86_64 |
Warning
Deprecation warning: distributions marked with a * will not be supported with Kopano Core 9.x and newer.
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.
| MS Windows Release | Supported CPU Architectures |
|---|---|
| Windows Server 2008 R2 | 64-bit |
| Windows Server 2012 | 64-bit |
| Windows Server 2016 | 64-bit |
| Windows Server 2019 | 64-bit |
| Windows 8 | 64-bit |
| Windows 10 | 64-bit |
Important
Please note that Windows Server 2008 and Windows Server 2012 are no longer supported by Microsoft.
KC requires a system where glibc’s functions (including semctl) work properly. Systems known to be problematic are for example old OpenVZ environments with kernel 2.6.x. 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 number 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 the MySQL/MariaDB version provided by default by the supported distributions.
- Apache or any other webserver that supports PHP. KC is tested with Apache 2.2 and 2.4.
- PHP, standalone as CGI or as a webserver module. KC is tested with PHP >= 5.3 releases.
- ICU 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 ways 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 distribution list in Supported Platforms for an overview of officially supported distributions. Packages available on the Kopano download server for distributions not mentioned in this table are provided as-is.
For per-distribution installation steps, please have a look at the Kopano Knowledge Base.
Note
In an effort to have consistent behaviour between distributions Kopano packages do not start after installation or enable automatic restart after a reboot (usual behaviour for RHEL/SLES, but maybe not expected for Debian/Ubuntu).
3.2.1. Installing Kopano Core through the Kopano package repositories¶
To simplify the installation and updating of a Kopano system, Kopano provides packages repositories for customers with a valid subscription. An 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
This is always https://download.kopano.io/supported/. Navigation to this URL in a web browser 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.
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 directory called “tarballs” at this location. This directory also containes tarballs of previous releases.
You can find more information in the Kopano Knowledge Base.
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 individual Packages¶
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 systems, “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 the database, use:
apt install mysql-server
# or depending on availability
apt install mariadb-server
For Apache with the needed PHP support, use the following.
For PHP 5:
apt install apache2 libapache2-mod-php5
For PHP 7 (e.g. Ubuntu 16.04 and Debian 9):
apt install apache2 libapache2-mod-php7.0
phpenmod kopano
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 selecting packages one by one 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 (like *-dev and *-dbg) 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/apache2/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