OXSE4UCS Installation en: Difference between revisions

From Open-Xchange
No edit summary
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Introduction=  
= Introduction =


= First Step: Installation Univention Corporate Server =
This manual describes the installation and configuration of the OX App Suite 7.10.x on Univention Corporate Server (UCS) version 5.0.
As OX App Suite / Server Edition for UCS is an expansion pack for the Univention Corporate Server, one or more UCS server(s) must be installed firstly.
There are several possible different installation scenarios. In principle, OX App Suite / Server Edition for UCS can be installed on all UCS domain controller server roles: DC master, DC backup or DC slave. Installation on the server roles member server or base system is not currently possible.


To start, the Univention Corporate Server systems are installed as usual with UCS 4.x.  
The [https://www.univention.com/products/univention-app-center/app-catalog/oxseforucs/ '''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.


'''Download the UCS Installation DVD Image here:'''  [https://www.univention.de/en/download-and-support/ https://www.univention.de/en/download-and-support/]
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.


If several systems are in the UCS domain, a check must be performed that the join procedure has been run on all servers. This is usually done at the end of the installation procedure. Further information on the installation of UCS can be found in the UCS manual: [https://www.univention.de/en/download-and-support/documentation/ https://www.univention.de/en/download-and-support/documentation/]
The OX App Suite App from Univention App Center provides extensive groupware functionality with email, calendar and tasks.


= Second Step: Installation OX App Suite / Server Edition for UCS =
= Installation =


Since UCS 3.x the Open-Xchange OX App Suite / Server Edition has to be installed via the Univention App Center. To start the Univention App Center, log into Univention Management Console and open the UMC module '''App Center'''.  
The installation of OX App Suite requires an installed UCS system first. Univention offers installation images and pre-installed virtual machine images
In the Univention App Center you need to select the application ''Open-Xchange OX App Suite / Server Edition'' and click on Install.  
on their [https://www.univention.com/downloads/download-ucs/ website]. Download one of them and install UCS. Follow the instructions in the [https://docs.software-univention.de/quickstart/5.0/en/index.html Univention Quickstart Guide] for
installation of UCS.


Download, installation and configuration of OX App Suite / Server Edition for UCS may take several minutes. Please do not shut down or restart the UCS system until the installation is complete.
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.


=Updating=
This guide describes two installation scenarios:


The following steps are necessary to update a UCS 3.0-2 system with OX SE for UCS 6.20.7 to UCS 3.1 with OXSE v6.22.2 / App Suite v7.2.1 for UCS:
* '''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.


* Update to UCS 3.1-1: The update can be started by the UMC module Online update or by the command line tool univention-upgrade. Further details about the update are described in the UCS manual. After the update to UCS 3.1, the OXSE for UCS installation will be automatically reconfigured to use the Univention App Center for further updates.
== Single server installation ==
* Installation of the latest UCS errata updates: The errata updates can be installed with UMC module Online update → Package Updates or by the command line tool Univention-upgrade.
* Update of the “Open-Xchange Server Edition” via the App Center: Now the “Open-Xchange Server Edition” can be updated to version 7.2 with the UMC module App Center. Where necessary, a key identification (Key ID) has to be added to the UCS license. This is done via a special wizard when updating or installing the “Open-Xchange Server Edition” in the App Center.
* Installation of Package Updates: The last step is to ensure, that the latest package updates are installed (with the UMC module Online Update → Package Updates or via the command line tool univention-upgrade).


All further updates for OX SE / App Suite for UCS will be available in Univention App Center. Please check the UMC module App Center for updates of the application Open-Xchange Server Edition / OX App Suite.
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.


=Administration=
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.


==Frontend selection==
To get access to the newest updates for OX App Suite, username and password for a valid LDB account must be configured, see [[{{PAGENAME}}#OX License Management|OX License Management]] for details.


During installation two versions of the Open-Xchange frontend have been configured: OX6 and AppSuite. In default configuration these frontends are shown on the overview page (https://<IP address of the OX system>/) and may be used simultaneously.
== Installation in a distributed environment ==


By setting UCR variables either of those frontends may be deactivated. For disabling the AppSuite
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.
frontend run the following command:


$ ucr set ox/frontend/appsuite/enabled=no
The components can then be distributed on different UCS systems:
and for disabling the OX6 frontend the following command has to be called:
$ ucr set ox/frontend/ox6/enabled=no


== UMC module “Licence management” ==
# Database server
# One or more OX App Suite instances
# IMAP server with spam and anti virus filtering


The license management module supports you in the configuration of an Open-Xchange account and the selection of a suitable Open-Xchange license key. It is necessary to specify an Open-Xchange account to be able to select a license key previously saved in the account and install the UCS license. In addition, the account is also required for the installation of version and security updates from the Open-Xchange online repository, as this requires authentication.
For the following sections you must adapt the steps to your environment. The environment used consists of these systems in one UCS domain:


In this account, the same combination of username and password is required which was also used for the license database http://ldb.open-xchange.com.
* Primary Directory Node: No additional services are installed.
* Replica Directory Node: <tt>db</tt> runs the MariaDB server.
* Replica Directory Nodes: <tt>ox1</tt> and <tt>ox2</tt> run the OX App Suite instances.
* Replica Directory Nodes: <tt>imap1</tt> and <tt>imap2</tt> run the Dovecot instances.


On an unconfigured system, the license management module displays the first configuration step directly, as shown in the figure. In all other cases, an overview of the current configuration is displayed.
=== MariaDB server ===


The first step involves entering the username and password of the Open-Xchange account. After continuing to the second configuration step via the ''Next'' button, the entered account information is automatically verified. Should it prove necessary to reset the password for an account, the ''Reset password'' button can be used to reset the password for an account. The username must be entered in the dialogue which opens; the password must be entered twice. On confirmation, an e-mail is sent to the e-mail address specified for the account containing a confirmation link, which can be opened in the browser of your choice to complete the process.
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.


The second and final step requires to select a suitable Open-Xchange license key. A variety of information is stored in the license database for a license key (e.g., the primary mail domain or the number of licensed users). In addition, a UCS license is saved for every license key in the license database, which is downloaded from the LDB server and installed on the local system when this wizard is finished.
'''<pre style="color: green">Hint:'''
MariaDB cluster can also be used, which is beyond the scope of this guide.</pre style="color: red">


If several keys are saved in the specified account, it is important to select the correct key, as it will otherwise not be possible to complete the configuration if the information saved in the license database does not correspond to the local system.
1. Install MariaDB on the UCS system, where the database shall be installed:
univention-install univention-mariadb</code>


When performing the configuration for the first time, you may be prompted to confirm the end user license agreement (EULA) for the selected product via the checkbox.
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


After clicking on the ''Finish'' button, the UCS license is downloaded and installed. The Open-Xchange license key is then configured on the local system. This procedure can take a few seconds.
'''<pre style="color: green">Tip:'''  
Instead of <tt>0.0.0.0</tt> use the dedicated address of the network interface that will handle the database connections.</pre style="color: red">


Once the configuration is complete, the module redirects to the overview page. This page displays the currently configured Open-Xchange account, the status of the specified user data (valid/invalid), the license key selected for this system and the LDAP base of the installed system.
3. Restart the database server to apply the configuration changes:
service mariadb restart


Following successful configuration, it is possible to ''Switch to the Online Update module'' directly from here and install the available updates.
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


If it proves necessary to change the Open-Xchange account or it has been relicensed, you can open the configuration wizard again using the ''Change settings'' button. For relicensing, it is necessary to perform the configuration procedure anew so that the modified license information is adopted on the local system.
5. Grant access to the database for OX App Suite. Use the username <tt>openexchange</tt> exactly as is. Otherwise the database rejects connections from OX App Suite because of wrong permissions.<br>If you need more than one OX App Suite instance, GRANT must be repeated for all instances. Replace the appropriate host name, for example <tt>ox2.ucs.intranet</tt>.
 
mariadb -h localhost -p$(cat /etc/mysql.secret)<br>Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 36<br>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)</code>
 
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"
 
'''<pre style="color: green">Hint''':
The variable <tt>HISTIGNORE</tt> prevents the export statements from being added to the shell history.</pre style="color: green">
 
* '''OXDB''' - Defines the MariaDB database server for the OX App Suite instance. The names of the databases (<tt>configdb</tt> and <tt>localhost_*</tt>) and the database username <tt>openxchange</tt> are hard coded in OX App Suite.
* '''OXDBPW''' - contains the password for the database user <tt>openxchange</tt>.
* '''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 [[{{PAGENAME}}#Active_OX_App_Suite_instance|active OX App Suite installation]].
 
The following steps describe the installation of a single IMAP server installation. The package <tt>univention-mail-dovecot-ox</tt> installs the IMAP server and because of package dependencies, UCS installs <tt>univention-mail-postfix-ox</tt>.
 
'''<pre style="color: green">Hint''':
An IMAP cluster can also be used, but it is beyond the scope of this guide.</pre style="color: green">
 
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 <tt>univention-mail-dovecot-ox</tt> 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 <tt>/etc/postgrey/whitelist_clients.local</tt>. 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
 
'''<pre style="color: green">Tip''':
To check that the OX listener module is not running, look at <tt>/var/log/univention/listener.log</tt>. With debug level 4, you should see the message <tt>'listener module deactivated by UCR variable "ox/listener/enabled".'</tt> several times.
To increase the debug level:
ucr set ox/debug/level=4
systemctl restart univention-directory-listener.service</pre style="color: green">
 
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 [https://docs.software-univention.de/manual/5.0/en/software/updates.html#software-ucs-updates 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:
 
* [[{{PAGENAME}}#OX_License_Management|OX License Management]]
* [[{{PAGENAME}}#Important_Files|Important Files]]
* [[{{PAGENAME}}#Greylisting|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 <tt>Customer Id</tt> and a <tt>Password</tt>. They are the credentials for the [https://www.open-xchange.com/customer-portal/ 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.
 
'''<pre style="color: green">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.</pre style="color: green">
 
== 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.
 
# Open the OX License Management UMC module on the first UCS system with OX App Suite installed.
# Enter the <tt>Customer ID</tt> and the <tt>Password</tt>.
# 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.
# Click ''OK''. The OX License Management module shows the currently configured Open-Xchange account, the status and the LDAP base of the installed system.
# 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 [[{{PAGENAME}}#Update|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 ==
== User and group management ==


New users and groups can be created using the Univention Management Console (UMC). The UMC can be accessed on the DC master via a web browser at https://<IP address of DC master>/umc/. It is possible to log in as the Administrator user using the password specified during the installation.
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 <tt>Administrator</tt> and the password assigned during installation. All users in the user group <tt>Domain Admins</tt> can create users and groups.


When creating a user, the ''open-xchange groupware account'' user template should be selected. This preselects all Open-Xchange specific settings.
# Open the Users UMC module.
# Create new users and select the User template <tt>open-xchange groupware account</tt> 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.
 
<tt>/var/spool/dovecot/</tt> - 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:
 
* <tt>/var/log/open-xchange/open-xchange.log.0</tt> - contains log information from the OX App Suite instance on the system.
* <tt>/var/log/mail.info</tt> - is the log file for the Postfix SMTP server.
* <tt>/var/log/dovecot.log</tt> - is the log file for the Dovecot IMAP server.
* <tt>/var/log/univention/listener.log</tt> - 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  
[[{{PAGENAME}}##Additional_passive_instance_of_OX_App_Suite|authentication
adjustments during the installation of the second OX App Suite instance]].
 
* <tt>/opt/open-xchange/etc</tt> - contains the configuration files.
 
The schema for the variables is <tt>ox/cfg/<configuration-file>/<setting>=<value></tt>. For example, to set <tt>com.openexchange.mail.mailServerSource</tt> in <tt>mail.properties</tt>:
 
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:
 
'''<pre style="color: red">Warning''':
The value <tt>com.openexchange.mail.mailServerSource</tt> has been set via UCR variable <tt>ox/cfg/mail.properties/com.openexchange.mail.mailServerSource</tt> - please alter the UCR variable instead</pre style="color: red">
 
For documentation on the available configuration settings see the [https://documentation.open-xchange.com/components/middleware/config/7.10.5/ App Suite Configuration Documentation].


== System messages ==
== System messages ==
The mail/alias/root UCS variable must be set so that system messages can be delivered. To do this, either a new account can be created or, alternatively, oxadmin@DOMAIN is provided for this purpose:


<pre>
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=oxadmin@ucs.local
 
$ newaliases
ucr set mail/alias/root=admin@ucs.intranet
$ /etc/init.d/postfix reload
newaliases
</pre>
systemctl reload postfix
 
'''<pre style="color: green">Tip''':
The email address <tt>oxadmin@$your-domain</tt> can also be used for this purpose. You can login to OX App Suite with the username <tt>oxadmin</tt>. The password is stored in <tt>/etc/ox-secrets/context10.secret</tt>.</pre style="color: green">
 
== 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 <tt>mail/postfix/greylisting</tt> 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.
 
{| border="1" cellpadding="3" cellspacing="0"
!align="left" |UCR variables
!align="left" |Default
!align="left" |Description
|-
|<tt>mail/postfix/greylisting/delay</tt>
|<tt>300</tt>
|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.<br>The value is specified as a numerical value in seconds.
|-
|<tt>mail/postfix/greylisting/lookup</tt>
|<tt>host</tt>
|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).
|-
|<tt>mail/postfix/greylisting/max-age</tt>
|<tt>35</tt>
|This value specifies the time period after which old entries are removed from the greylisting database.<br>The value is specified as a numerical value in days.
|-
|<tt>mail/postfix/greylisting/privacy</tt>
|<tt>true</tt>
|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.
|-
|<tt>mail/postfix/greylisting/recipient/whitelist</tt>
|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.<br>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.
|-
|<tt>mail/postfix/greylisting/retry-window</tt>
|<tt>48</tt>
|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.
|-
|<tt>mail/postfix/greylisting/text</tt>
|
|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.<br>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.
|-
|<tt>mail/postfix/greylisting/client/whitelist/auto</tt>
|<tt>5</tt>
|This value specifies after how many successfully delivered emails the respective server is automatically accepted in the whitelist to not delay further emails.<br>The value is specified as a numerical value.
|-
|<tt>mail/postfix/greylisting/client/whitelist</tt>
|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.<br>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.


It is possible to log in as the oxadmin user in the Open-Xchange web interface using the password from the ''/etc/ox-secrets/context10.secret'' file.
= Optional: Univention Corporate Server SAML-SSO Configuration with OX App Suite =


= Additional available Components =
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


The following components are available in the Univention App Store with a valid OX SE / OX App Suite license:
= Optional: Univention Corporate Server OIDC-SSO Configuration with OX App Suite =


* [[AppSuite:Text_Installation_Guide#Univention_Corporate_Server|Download and Installation Guide OX Documents]]
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
* [[AppSuite:OX_Drive#OX_Server_Edition_.2F_App_Suite_for_UCS|Download and Installation Guide OX Drive]]
* [[AppSuite:OX_Guard#Univention_Corporate_Server|Download and Installation Guide OX Guard]]
* [[AppSuite:Connector_for_Business_Mobility_Installation_Guide#Download_and_Installation_OX_Server_Edition_.2F_App_Suite_for_UCS|Download and Installation Guide Connector for Business Mobility]]
* [[AppSuite:Connector_for_Microsoft_Outlook#Download_and_Installation_of_the_Connector_for_MS_Outlook_on_App_Suite_for_UCS|Download and Installation Guide Connector for Microsoft Outlook]]

Latest revision as of 07:11, 8 September 2022

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

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