OXSE4UCS Installation en

Introduction

This manual describes the installation and configuration of the OX App Suite 7.10.x on Univention Corporate Server (UCS) version 5.0.

The OX App Suite app in the App Center of UCS includes the groupware OX App Suite and the integration packages for UCS. OX App Suite is a modular communication and collaboration platform. Based on open standards, OX App Suite can be easily integrated into existing IT infrastructures. IT is targeted at businesses, education and public authorities.

UCS is the innovative basis for the cost-efficient operation and easy administration of server applications and entire IT infrastructures. UCS is optimally suited to the management of distributed heterogeneous and virtualized IT environments, regardless of whether you employ Microsoft Windows, Mac OS X or Linux systems.

The OX App Suite App from Univention App Center provides extensive groupware functionality with email, calendar and tasks.

Installation

The installation of OX App Suite requires an installed UCS system first. Univention offers installation images and pre-installed virtual machine images on their website. Download one of them and install UCS. Follow the instructions in the Univention Quickstart Guide for installation of UCS.

Make sure to select one of the system roles required by OX App Suite: Primary Directory Node, Backup Directory Node and Replica Directory Node. Other system roles are not supported and the App Center does not offer installations for them.

This guide describes two installation scenarios:

• Single server installation for environments with OX App Suite and the required services on only one UCS system.
• Installation in a distributed environment for larger environments where the services for OX App Suite are distributed on several UCS systems.

Single server installation

After UCS is up and running, login to the Univention Management Console as Administrator, select the UMC module App Center and install OX App Suite in a single server setup. The App Center runs checks on the requirements and installs the app.

Download, installation and configuration of OX App Suite may take several minutes. Please do not shut down or restart the UCS system until the installation is complete. The app installs OX App Suite, MariaDB and the mail server stack (Postfix, Dovecot) on the same UCS system.

To get access to the newest updates for OX App Suite, username and password for a valid LDB account must be configured, see OX License Management for details.

Installation in a distributed environment

It is also possible to install OX App Suite in a distributed UCS environment. This is helpful in the case that many thousand users will be used or if a fail-safe setup is required.

The components can then be distributed on different UCS systems:

1. Database server
2. One or more OX App Suite instances
3. IMAP server with spam and anti virus filtering

For the following sections you must adapt the steps to your environment. The environment used consists of these systems in one UCS domain:

• Primary Directory Node: No additional services are installed.
• Replica Directory Node: db runs the MariaDB server.
• Replica Directory Nodes: ox1 and ox2 run the OX App Suite instances.
• Replica Directory Nodes: imap1 and imap2 run the Dovecot instances.

MariaDB server

OX App Suite uses MariaDB as database to store non-mail user data. The following steps describe the installation of a single MariaDB database server.

Hint:
MariaDB cluster can also be used, which is beyond the scope of this guide.

1. Install MariaDB on the UCS system, where the database shall be installed:

univention-install univention-mariadb

2. Configure MariaDB so that it can be accessed from remote systems and let it listen on all network interfaces:

ucr set mysql/config/mysqld/bind_address=0.0.0.0

Tip: 
Instead of 0.0.0.0 use the dedicated address of the network interface that will handle the database connections.

3. Restart the database server to apply the configuration changes:

service mariadb restart

4. Open the MariaDB port in the local firewall to accept remote connections to the database:

ucr set security/packetfilter/tcp/3306/all=ACCEPT
service univention-firewall restart

5. Grant access to the database for OX App Suite. Use the username openexchange exactly as is. Otherwise the database rejects connections from OX App Suite because of wrong permissions.
If you need more than one OX App Suite instance, GRANT must be repeated for all instances. Replace the appropriate host name, for example ox2.ucs.intranet.

mariadb -h localhost -p$(cat /etc/mysql.secret)
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 36
Server version: 10.3.31-MariaDB-0+deb10u1 Debian 10
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> GRANT
   -> CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER,
   -> SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW, SHOW DATABASES
   -> ON *.* TO 'openexchange'@'ox1.ucs.intranet' IDENTIFIED BY 'secret';
Query OK, 0 rows affected (0.001 sec)

MariaDB [(none)]> GRANT
   -> CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER,
   -> SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW, SHOW DATABASES
   -> ON *.* TO 'openexchange'@'ox2.ucs.intranet' IDENTIFIED BY 'secret';
Query OK, 0 rows affected (0.001 sec)

MariaDB [(none)]> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.001 sec)

MariaDB [(none)]> exit

Active OX App Suite instance

After the database installation, you can continue with the first installation of OX App Suite.

1. Prepare the environment: On the UCS system where OX App Suite shall be installed, set the following environment variables to ensure the corresponding permissions for the join script:

export HISTIGNORE="export*"
export OXDB="db.ucs.intranet"
export OXDBPW="secret"
export OXIMAPSERVER="imap1.ucs.intranet"

Hint: 
The variable HISTIGNORE prevents the export statements from being added to the shell history.

• OXDB - Defines the MariaDB database server for the OX App Suite instance. The names of the databases (configdb and localhost_*) and the database username openxchange are hard coded in OX App Suite.
• OXDBPW - contains the password for the database user openxchange.
• OXIMAPSERVER - defines the fully qualified domain name (FQDN) for the standard IMAP server. IP addresses are not allowed.

2. Install OX App Suite through the App Center:

univention-app install oxseforucs \
--skip-check must_have_correct_server_role

3. Configure the Sieve server and the IMAP server with UCR variables. The IMAP is configured globally for all users:

ucr set \
ox/cfg/mailfilter.properties/com.openexchange.mail.filter.server="$OXIMAPSERVER"
ucr set \
ox/cfg/mail.properties/com.openexchange.mail.mailServer="$OXIMAPSERVER:143"
ucr set \
ox/cfg/mail.properties/com.openexchange.mail.mailServerSource=global

4. Configure OX App Suite to send emails through a dedicated SMTP server. In this setup it is the same system that also hosts the mailboxes.

ucr set \
ox/cfg/mail.properties/com.openexchange.mail.transportServerSource="global"
ucr set \
ox/cfg/mail.properties/com.openexchange.mail.transportServer=smtp://$OXIMAPSERVER:587

5. Finally, unset the environment variable OXDBPW with the database password for cleanup and restart the OX App Suite server:

unset OXDBPW
systemctl restart open-xchange

For creating users and groups see User and group management.

IMAP server

Install the IMAP server after the installation of the active OX App Suite instance. The IMAP server needs a specific LDAP schema extension that is installed together with the active OX App Suite installation.

The following steps describe the installation of a single IMAP server installation. The package univention-mail-dovecot-ox installs the IMAP server and because of package dependencies, UCS installs univention-mail-postfix-ox.

Hint: 
An IMAP cluster can also be used, but it is beyond the scope of this guide.

1. Add the OX App Suite app repository:

univention-app register oxseforucs --component --do-it

This command activates the package repository for the OX App Suite app without installing the app and provides access to the package needed for the IMAP server.

2. Install the IMAP server package univention-mail-dovecot-ox on the dedicated UCS system. The command installs the spam and anti-virus check with Amavis, Spamassassin and ClamAV.

univention-install univention-mail-dovecot-ox

3. Check for the join scripts, if they have run. All scripts must be listed as either skipped (already executed) or done.

univention-run-join-scripts

4. Add the fully qualified domain name of the UCS system with the OX App Suite instance to the configuration file /etc/postgrey/whitelist_clients.local. It makes sure that mails are sent to the OX App Suite instance. If you have several OX App Suite instance, add them all.

echo "ox1.ucs.intranet" >> /etc/postgrey/whitelist_clients.local
ucr commit /etc/default/postgrey
systemctl restart postgrey

5. Make the IMAP server known to the domain and ensure that this one is used. Run the following command on the Primary domain controller:

udm oxmail/oxdomain modify \
--dn "cn=$(ucr get domainname),cn=domain,cn=mail,$(ucr get ldap/base)" \
--set oxImapServer="imap1.ucs.intranet"

Additional passive instance of OX App Suite

After the first installation of OX App Suite, you can install additional instances. You must make sure that the OX listener is deactivated and the join script for OX App Suite is not running for additional installations. Additional OX listeners in one UCS environment are not supported and will cause negative side effects. For example it can happen that a new user is created several times within OX App Suite, which is undesired.

The OX join script installs LDAP schema, UDM modules and the like. Since these artifacts are already installed, it is not necessary to run the join script on another system.

To prevent the OX Listener from starting and the OX join script from running, you must set the UCR variables as described later. Both parts check for the UCR variables and end their work gracefully without applying the usual changes.

1. Prepare installation:

export HISTIGNORE="export*"
export OXDB="db.ucs.intranet"
export OXDBPW="secret"
export OXIMAPSERVER="imap1.ucs.intranet"
ucr set ox/listener/enabled=no
ucr set ox/joinscript/skip=yes

2. Install OX App Suite:

univention-app install oxseforucs \
--skip-check must_have_correct_server_role

Tip: 
 To check that the OX listener module is not running, look at /var/log/univention/listener.log. With debug level 4, you should see the message 'listener module deactivated by UCR variable "ox/listener/enabled".' several times.
 To increase the debug level:
 
 ucr set ox/debug/level=4
 
 systemctl restart univention-directory-listener.service

3. Copy the settings from the first OX App Suite instance:

rsync -a root@ox1.ucs.intranet:/opt/open-xchange/etc/ \
/opt/open-xchange/etc

4. Adjust the authentication plugin on the new instance to use the best fitting LDAP connection. The additional OX App Suite instance uses the local LDAP server for authentication:

ucr set \
ox/cfg/authplugin.properties/com.openexchange.authentication.ucs.bindPassword=\
'@&@/etc/machine.secret@&@'
ucr set \
ox/cfg/authplugin.properties/com.openexchange.authentication.ucs.bindDn=\
'@%@ldap/hostdn@%@'
ucr set \
ox/cfg/authplugin.properties/com.openexchange.authentication.ucs.ldapUrl=\
'ldaps://@%@ldap/server/name@%@:7636'

5. Configure the IMAP and the SMTP server as a global value instead of a per user base. The user specific IMAP server configuration is stored with the mail home server attribute on the user object.

ucr set \
ox/cfg/groupware/mailfilter.properties/com.openexchange.mail.filter.server="$OXIMAPSERVER"
ucr set \
ox/cfg/mail.properties/com.openexchange.mail.mailServerSource=global
ucr set \
ox/cfg/mail.properties/com.openexchange.mail.mailServer="$OXIMAPSERVER:143"
ucr set \
ox/cfg/mail.properties/com.openexchange.mail.transportServerSource="global"
ucr set \
ox/cfg/mail.properties/com.openexchange.mail.transportServer=smtp://$OXIMAPSERVER:587

See the file /opt/open-xchange/etc/mail.properties for details.

6. Finally, restart the passive OX App Suite instance:

systemctl restart open-xchange

Update

Univention App Center provides updates for OX App Suite. Check the UMC module App Center for application updates and follow the steps on the screen.

Alternatively, run the app updates from the command-line:

univention-app update oxseforucs

Regular UCS software updates cover the updates for the mail stack (including IMAP and SMTP) and the MariaDB database servers on those systems.

For more information see Updates of UCS systems in the UCS manual.

Administration

Once OX App Suite is installed the phase for administration and maintenance begins. The chapter covers the following topics:

• OX License Management
• Important Files
• Greylisting

OX License Management

Open-Xchange offers security and software updates for OX App Suite through a dedicated access protected online repository.

As part of your contract you have a Customer Id and a Password. They are the credentials for the OX Customer Portal “License and Maintenance”. In your account you see the active license keys together with the enabled modules.

With your Customer Id and the password you have access to the online repository. The OX App Suite app also installs the OX License Management UMC module. It configures the access to the online repository so that security and software updates become available to your local OX App Suite installation.

Note: 
The OX license management module is specific to the UCS systems where OX App Suite is installed. When you have several systems with OX App Suite, the steps to change the Open-Xchange account must be done on all UCS systems where OX App Suite is installed.

Install the OX license

To configure your local OX App Suite installation for access to the protected online repository run the following steps in the OX License Management UMC module.

1. Open the OX License Management UMC module on the first UCS system with OX App Suite installed.
2. Enter the Customer ID and the Password.
3. Click the Finish button. The input is verified. You see a success message confirming that the settings have been updated successfully. The system’s online repository configuration has been updated accordingly. You now have access to the online repository.
4. Click OK. The OX License Management module shows the currently configured Open-Xchange account, the status and the LDAP base of the installed system.
5. To check for available updates for the OX App Suite packages, click Switch to the Online Update module.

The software updates here only cover the same OX App Suite version. For updates to a new OX App Suite version, you need to use the App Center, see Update.

Change the Open-Xchange account

You can change the associated Open-Xchange customer account in the OX License Management anytime with the Change settings button. You can switch to a different account or re-license your OX App Suite for example for a different number of users accounts.

When OX App Suite is re-licensed, you must run the configuration procedure again to adapt the modified license information on the local system.

Depending on the system design it can happen that the settings for the additional repositories are not activated automatically. To activate the additional repositories, run the join script:

univention-run-join-scripts \
--run-scripts \
--force 65univention-ox.inst

User and group management

New users and groups are created using the UMC. You access it from the UCS portal page when you directly open the address of your UCS Primary Node in a web browser.

You login to UMC with the username Administrator and the password assigned during installation. All users in the user group Domain Admins can create users and groups.

1. Open the Users UMC module.
2. Create new users and select the User template open-xchange groupware account in the Add a new user wizard. The template ensures that OX App Suite specific settings are made for the user account.

Important Files

OX App Suite and the required components use different files that are of interest for administrating persons.

/var/spool/dovecot/ - directory contains the mails in Maildir format delivered to a local system. See Maildir Mailbox Format in the Dovecot documentation.

Log files

Different log files are useful for troubleshooting and debugging. You find them in the following locations:

• /var/log/open-xchange/open-xchange.log.0 - contains log information from the OX App Suite instance on the system.
• /var/log/mail.info - is the log file for the Postfix SMTP server.
• /var/log/dovecot.log - is the log file for the Dovecot IMAP server.
• /var/log/univention/listener.log - is the log file for the Univention Directory Listener.

Configuration files

The UCR mechanism controls the configuration files for OX App Suite. As administrator you can explicitly set OX configurations and implicitly mark the settings as deviation from the default. Furthermore, the UCR variables are protected from update changes and ensure that your local configuration is not overwritten by a new value. And UCR variables can use values from other UCR variables, as you see for example in the authentication adjustments during the installation of the second OX App Suite instance.

• /opt/open-xchange/etc - contains the configuration files.

The schema for the variables is ox/cfg/<configuration-file>/<setting>=<value>. For example, to set com.openexchange.mail.mailServerSource in mail.properties:

ucr set \
ox/cfg/mail.properties/com.openexchange.mail.mailServerSource="global"

Every setting that has been configured by UCR has a respective comment in the configuration file, for example:

Warning: 
 The value com.openexchange.mail.mailServerSource has been set via UCR variable ox/cfg/mail.properties/com.openexchange.mail.mailServerSource - please alter the UCR variable instead

For documentation on the available configuration settings see the App Suite Configuration Documentation.

System messages

To deliver system email messages to a dedicated email account, you must set the mail/alias/root UCR variable to a valid email address. This step must be executed on every UCS system that has this requirement.

ucr set mail/alias/root=admin@ucs.intranet
newaliases
systemctl reload postfix

Tip: 
The email address oxadmin@$your-domain can also be used for this purpose. You can login to OX App Suite with the username oxadmin. The password is stored in /etc/ox-secrets/context10.secret.

Greylisting

Greylisting is a method of defending email users from spam emails. It temporarily rejects email delivery. Usually SMTP servers are obliged to retry to send emails later. The resend tries are often not provided by the simple implementations of the SMTP clients used by spammers. A good portion of spam emails is filtered out without creating compute loads with complex filter software on the receiving email servers.

Installation

The OX App Suite app installs and activates greylisting automatically. Unset the UCR variable mail/postfix/greylisting to deactivate the greylisting function. Once the variable changes, you must restart the system services for Postgrey and Postfix, for example through the command-line:

systemctl restart postgrey
systemctl restart postfix

For more settings on greylisting, look at the UCR variable and their descriptions and set them to your needs:

ucr search greylisting

Configuration

The UCR variables listed below influence the actions of postgrey. You can change them through the Univention Configuration Registry UMC module or the command-line. Once the variables changed, the system service for Postgrey must be restarted to activate the changes.

UCR variables	Default	Description
mail/postfix/greylisting/delay	300	This value specifies the period for which an email is temporarily rejected. The email is only delivered once the server attempts to resend it after this period has expired. The value is specified as a numerical value in seconds.
mail/postfix/greylisting/lookup	host	Specifies whether email servers are identified by their complete IP address (value: host) or only by the first 24 bits of the address (value: subnet).
mail/postfix/greylisting/max-age	35	This value specifies the time period after which old entries are removed from the greylisting database. The value is specified as a numerical value in days.
mail/postfix/greylisting/privacy	true	Specifies whether the entries in the database are masked with a one-way function in order to make it difficult to discover sensitive data. The possible values are true for masking and false for plain text.
mail/postfix/greylisting/recipient/whitelist	See UCR variable description	This value is a list of files separated by spaces which contain recipient addresses for which greylisting should not be performed. It is also possible to specify regular expressions in the files. The default value already includes two files: The list supplied by Postgrey and a file for local changes called /etc/postgrey/whitelist_recipients.local. It can be adapted for additional entries.
mail/postfix/greylisting/retry-window	48	The variable defines the time period within which the server must attempt to resend the rejected email to not be temporarily rejected again. The value is specified as a numerical value in hours.
mail/postfix/greylisting/text		If required, the variable includes a text deviating from the default, which is sent to the server as a reason when emails are temporarily rejected. This message is shown to users of defective mail servers which do not try to resend the email after the temporary failure and is thus not normally seen by users.
mail/postfix/greylisting/client/whitelist/auto	5	This value specifies after how many successfully delivered emails the respective server is automatically accepted in the whitelist to not delay further emails. The value is specified as a numerical value.
mail/postfix/greylisting/client/whitelist	See UCR variable description	This value is a list of files separated by spaces which contain server addresses for which greylisting should not be performed. It is also possible to specify regular expressions in the files. The default value already includes two files: The list supplied by Postgrey and a file for local changes named /etc/postgrey/whitelist_clients.local. It can be adapted for additional entries.

You can find a more information on the postgrey configuration in the postgrey man page.

Optional: Univention Corporate Server SAML-SSO Configuration with OX App Suite

Further information on the optional Univention Corporate Server SAML-SSO Configuration with OX App Suite, can be found here: https://oxpedia.org/wiki/index.php?title=AppSuite:UCS_SAML_SSO_with_OX_App_Suite

Optional: Univention Corporate Server OIDC-SSO Configuration with OX App Suite

Further information on the optional Univention Corporate Server OIDC-SSO Configuration with OX App Suite, can be found here: https://oxpedia.org/wiki/index.php?title=AppSuite:UCS_OIDC_SSO_with_OX_App_Suite