OXSE4UCS Installation en: Difference between revisions

From Open-Xchange
No edit summary
No edit summary
 
(74 intermediate revisions by 6 users not shown)
Line 1: Line 1:
= OXSE for UCS Quickinstall Guide =
= Introduction =


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


==Preparation==
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
===Planing a scenario===
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.
Before the installation you must decide which scenario for the OXSEforUCS-integration will be used. You can find the supported scenarios in the specifications of OXSEforUCS in chapter 7. For simplification the installation only varies between 3 cases
* One-Server-Solution comparable with OXAE
* dedicated slave server for OXSE
* installation in distributed environments


===Installing UCS-systems===
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
====UCS Master installation====
IT environments, regardless of whether you employ Microsoft Windows, Mac OS X or Linux systems.
A UCS Master is required for every scenario. It is possible to use an existing UCS Master, if so, exactly '''UCS version 2.2-3 must''' be installed.


'''Please Note: For installation, please only this mentioned path with UCS 2.2-3. UCS 2.3 is currently not supported for the OXSE for UCS and there is no possibility to downgrade UCS 2.3 to 2.2-3.'''
The OX App Suite App from Univention App Center provides extensive groupware functionality with email, calendar and tasks.


The UCS ISO images are available at http://apt.univention.de/download/ucs-cds/ucs2.2-0/
= Installation =


Please select one of the images, that is appropriate for your platform, burn it, and reboot the machines with the DVD in the tray. Choose Univention Installer from the boot-menu and proceed after the boot-dialog has been loaded as follows:
The installation of OX App Suite requires an installed UCS system first. Univention offers installation images and pre-installed virtual machine images
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.


* Choose installer language
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.
* Press F12 to load all modules. If you don't want to load certain modules (e.g. for hardware compatibility reasons), deselect them. After that press F12.
* Choose the medium, you want to install from (default ist /dev/hdc, the DVD Drive)
* Choose your timezone and press F12
* Choose the keyboard layout and press F12
* Choose one or more system languages and press F12
* Choose the default language from the list and press F12
* Next, you have to act as follows. For Single-Server-Setup, choose '''Domain Controller Master'''. In the Single-Server-Setup you need exactly one '''Domain Controller Master'''. All other servers have to be '''Domain Controller Backup''' or '''Domain Controller Slave'''
* In the next step, you have to configure the hostname, domainname, the LDAP-Base and the Windows-Domain, as well as to set the root-password.
The LDAP Base will be genererated from the domainname as follows:<p>
subdomain.domain.com will become dc=subdomain,dc=domain,dc=com</p>
<p>
You can enter a different LDAP Base here, but for readbility reasons you should refrain from that.</p>
* In the next step you have to partition the medium, that you're going to install to. This is left up to your needs. You're welcome to use the auto partitioner that will create swap-space and apply the LVM onto the partitions.
After that, press F12 and install the bootloader, again with F12.
* After that, your are requested to enter the Data for your networking interface. Press F12.


The nameserver field should contain the nameserver, that handles the previously configured domain. As UCS brings its own nameserver '''bind''', this could also be 127.0.01 or the IP address of the networking interface, configured previously. Please enter the DNS-server of your ISP into the DNS Forwarder field. This will be automatically entered into bind. An optional proxy server can be entered in the HTTP proxy field. F12
This guide describes two installation scenarios:


* In the next dialog, you can enter certain values for the SSL certificate of your site. These should be correct, as they will be shown in the browsers that access your site with HTTPS. F12
* '''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.


* The next dialog is a basic configuration of the firewall. This is left up to you. F12
== Single server installation ==


* Package selection (without GUI). We recommend to deselect following packages, press F12 after that:
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.
<p>
Mail/Groupware: Kolab 2 for UCS, Kolab 2 Webservices</p><p>
Systemservices: Thinclient Environment</p><p>
Graphical UI: all</p>
* In the following step, you can choose to mirror the univention-repository locally. This and the decision to export home directories via NFS/SMB is left up to you. If you export home directories, without further configuration, all users will get a share, that they can access on the OXSEforUCS server.
* In the next step you can start the installation with F12


After the installer has finished, you will be requested to reboot. Following steps remain:
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.


====Update to 2.2-3 (prerequisite)====
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.


The update might take long, and the progress won't be shown on the shell.
== Installation in a distributed environment ==


You can observe the progress by:
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.
<pre>tail -f /var/log/univention/updater.log</pre>


CTRL-C exits the output.
The components can then be distributed on different UCS systems:


If you are logged in via ssh, the system will refuse to update at first. You can circumvent this by typing:
# Database server
<pre>ucr set update22/ignoressh=yes</pre>
# One or more OX App Suite instances
# IMAP server with spam and anti virus filtering


A safer solution to this is to install '''screen''' beforehand, and run the update in screen. screen is a console-window-manager, that detaches from the user-terminal, so that the update can continue, even if the controlling terminal of the user exits (e.g. triggered by the update). Installation and running screen is done by:
For the following sections you must adapt the steps to your environment. The environment used consists of these systems in one UCS domain:


<pre>apt-get install screen
* Primary Directory Node: No additional services are installed.
screen</pre>
* 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.


=====Update in shell/screen=====
=== MariaDB server ===
The actual update ist performed with
<pre>
univention-updater net --updateto 2.2-3
univention-security-update net
</pre>
After the update, you can exit screen by typing '''exit''' or pressing CTRL-D.


It's recommended to perform the update in screen or the local console.
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.


=====Update via UMC=====
'''<pre style="color: green">Hint:'''
Login into UMC and click on the Online-Updates module.
MariaDB cluster can also be used, which is beyond the scope of this guide.</pre style="color: red">
Under "UCS release" click on "Check for updates". Perform the Update.
Under "Security Updates" click on "Check for updates". Perform the Update.


Restart the machine, when the systems asks you to.
1. Install MariaDB on the UCS system, where the database shall be installed:
univention-install univention-mariadb</code>


====One-Server-Solution comparable with OXAE====
2. Configure MariaDB so that it can be accessed from remote systems and let it listen on all network interfaces:
After the Master installation there are no further preparations needed for the One-Server-Solution
ucr set mysql/config/mysqld/bind_address=0.0.0.0


====Dedicated Slave-/Backup server for OXSE====
'''<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">


* One UCS Master 2.2-0 installation (as describe above)
3. Restart the database server to apply the configuration changes:
* '''update to 2.2-3'''
service mariadb restart
* One or more UCS Backup or Slave 2.2-0 installations (as described above)
* the LDAP base must be the same as for the master
* during installation, you will be asked to join the master: ensure, that DNS is running and the enter the hostname of the master and the credentials at this point.
* '''update to 2.2-3'''


====Installing a distributed environment====
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


For the installation of a distributed environment you must define, how the several services should be distributed on your system. In a distributed environment the following services can be installed and used on any system role (Master/Backup/Slave)
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>.


===== Open-Xchange Server =====
mariadb -h localhost -p$(cat /etc/mysql.secret)<br>Welcome to the MariaDB monitor.  Commands end with ; or \g.
More than one instance of Open-Xchange Server can be installed, in that case first one Open-Xchange Server instance must be installed and then bound to the UCS-domain with a join. This Open-Xchange Server instance uses a listener to synchronize with the UCS-directory service. Additional Open-Xchange Server instances can now be created easily out of existing Open-Xchange Server instances. The first instance, which takes care of the synchronization, is called 'Active-OX' (in the following example it is called ox-instance1), all additional Open-Xchange Server instances, which just access to the OX-DB, are called 'Passive-OX' (in the following example it is called ox-instance2)
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.


===== IMAP Server =====
MariaDB [(none)]> GRANT
It is possible to install a dedicated IMAP server for every mail-domain (in the following example it is called oximapserver), but of course one IMAP server can be responsible for multiple mail-domains too. Every mail-domain has to be dedicated exactly to one IMAP server.
    -> 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>


===== MySQL Server =====
MariaDB [(none)]> GRANT
For a distributed environment exactly one MySQL server (in the following example it is called oxdbserver) is used, which can be located on one of the UCS-systems. MySQL replication can be established manually afterwards over the known MySQL replication mechanisms. The Open-Xchange instances must be customized therefore.
    -> 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)


===Installation on all hosts===
MariaDB [(none)]> FLUSH PRIVILEGES;
====Register Apt-Sources====
Query OK, 0 rows affected (0.001 sec)
Please enter your Open-Xchange LDB (License database) credentials. Replace {LDB-USERNAME} by the user name and {LDB-PASSWORD} by the corresponding password.


  ucr set repository/online/component/ox/server=software.open-xchange.com \
  MariaDB [(none)]> exit
  repository/online/component/ox/prefix=OX6/OXSEforUCS \
  repository/online/component/ox/username={LDB-USERNAME} \
  repository/online/component/ox/password='{LDB-PASSWORD}' \
  repository/online/component/ox=enabled \
  repository/online/component/oxseforucs/server=software.open-xchange.com \
  repository/online/component/oxseforucs/prefix=OX6/OXSEforUCS \
  repository/online/component/oxseforucs/username={LDB-USERNAME} \
  repository/online/component/oxseforucs/password='{LDB-PASSWORD}' \
  repository/online/component/oxseforucs=enabled


Update the repository data afterwards
=== Active OX App Suite instance ===
apt-get update


====Assuring, that all systems are joined====
After the database installation, you can continue with the first installation of OX App Suite.
If it is not sure that all systems are joined the join should be executed again.
univention-join


== Installation of the component OXSEforUCS ==
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:
=== One-Server solution comparable with OXAE ===
* DC Master Single Server: Installation univention-ox


  DEBIAN_FRONTEND=noninteractive apt-get \
  export HISTIGNORE="export*"
  -o DPkg::Options::=--force-confold -y --force-yes \
export OXDB="db.ucs.intranet"
  install univention-ox-directory-integration univention-ox \
export OXDBPW="secret"
  univention-mail-cyrus-ox univention-ox-framework
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


=== Dedicated Slave server for OXSE ===
For creating users and groups see User and group management.
* DC Master: Installation univention-ox-directory-integration
apt-get install univention-ox-directory-integration


* Slave: Installation univention-ox
=== IMAP server ===
DEBIAN_FRONTEND=noninteractive apt-get \
  -o DPkg::Options::=--force-confold -y --force-yes \
  install univention-ox univention-mail-cyrus-ox \
  univention-ox-framework


If it is not sure that all systems are joined the join should be executed again.
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]].
univention-join


====Installation of additional passive Open-Xchange Server instances ====
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>.
Please notice that the installation described here,  '''does not support''' the future installation of further '''passive Open-Xchange Server instances'''. If this is required, please follow the Installation procedure "Installation of a distributed environment" described below and set both variables, OXDB and OXIMAPSERVER to the FQDN of the slave server.


===Installation of a distributed environment===
'''<pre style="color: green">Hint''':
====DC Master Installation====
An IMAP cluster can also be used, but it is beyond the scope of this guide.</pre style="color: green">
apt-get install univention-ox-directory-integration


====Installation of additional Servers====
1. Add the OX App Suite app repository:
On the other servers all dedicated packages can be installed (univention-mail-cyrus-ox, mysql-server, univention-ox-instance, univention-mail-antispam-ox)


* Installation of the IMAP server:
  univention-app register oxseforucs --component --do-it
  apt-get install univention-mail-cyrus-ox


* Installation of the MySQL server
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.


apt-get install mysql-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.


Set up MySQL to listen to an external interface. The among others Bind-Address of “0.0.0.0” can be replaced through the IP-addresses of the network interface:
univention-install univention-mail-dovecot-ox


/etc/mysql/my.cnf
3. Check for the join scripts, if they have run. All scripts must be listed as either skipped (already executed) or done.
bind-address 0.0.0.0
or
sed -i 's/^bind-address.*$/bind-address = 0.0.0.0/' /etc/mysql/my.cnf


Restart MySQL
  univention-run-join-scripts
  /etc/init.d/mysql restart


Register authorizations of all open-xchange-instances
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.
mysql
mysql> GRANT ALL PRIVILEGES ON *.* TO \
  'openexchange'@'ox-instance1.ox-experten.de' \
  IDENTIFIED BY 'geheim';
mysql> GRANT ALL PRIVILEGES ON *.* TO \
  'openexchange'@'ox-instance2.ox-experten.de' \
  IDENTIFIED BY 'geheim';
mysql> GRANT ...
mysql> FLUSH PRIVILEGES;
mysql> exit


====Installation of the active Open-Xchange instance ====
echo "ox1.ucs.intranet" >> /etc/postgrey/whitelist_clients.local
* Installation with apt
ucr commit /etc/default/postgrey
apt-get install univention-ox univention-ox-framework
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:


* Specifcation of IMAP and MySQL server
For the IMAP and MySQL services, which are not based on this host, they must be specified as environment variables before the join:
  export HISTIGNORE="export*"
  export HISTIGNORE="export*"
  export OXDB=oxdbserver.ox-experten.de
  export OXDB="db.ucs.intranet"
  export OXDBPW="geheim"
  export OXDBPW="secret"
  export OXIMAPSERVER=oximapserver.ox-experten.de
  export OXIMAPSERVER="imap1.ucs.intranet"
ucr set ox/listener/enabled=no
ucr set ox/joinscript/skip=yes
2. Install OX App Suite:


* Optional: testing MySQL-connection before the join
univention-app install oxseforucs \
--skip-check must_have_correct_server_role


  apt-get install mysql-client
'''<pre style="color: green">Tip''':
  mysql -u openexchange -h $OXDB --password="$OXDBPW"</pre>
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">


* (Re-)Join des Systems
3. Copy the settings from the first OX App Suite instance:
univention-join


if the join-scripts have not been executed, this is sufficient:
rsync -a root@ox1.ucs.intranet:/opt/open-xchange/etc/ \
  univention-run-join-scripts
/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 ===


====Installation of additional passive Open-Xchange Server instances ====
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.
apt-get install univention-ox univention-ox-framework


rsync -essh -a root@ox-instance1.ox-experten.de:/opt/open-xchange/. /opt/open-xchange/
When OX App Suite is re-licensed, you must run the configuration procedure again to adapt the modified license information on the local system.


/opt/open-xchange/etc/groupware/usm.properties
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:
com.openexchange.usm.ox.url=ox-instance2.ox-experten.de


/opt/open-xchange/etc/authplugin.properties
univention-run-join-scripts \
  LDAP_HOST=ox-instance2.ox-experten.de
--run-scripts \
  --force 65univention-ox.inst


/etc/init.d/open-xchange-admin restart
== User and group management ==
/etc/init.d/open-xchange-groupware restart


=== Creation of the first user ===
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.
To do so, login on the Web-GUI of the DC-Master in the Univention Directory Manager and choose under the point "user" the option "add".
There the pattern "open-xchange groupware account" has to be chosen and the button "next" must be clicked.
In this Tab all fields marked with a * and the field "forename" have to be filled in.


[[File:User_anlegen_en.jpg|center|600px|]]
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.


=== Mobility ===
# Open the Users UMC module.
Information about the mobility support can be found here: http://www.open-xchange.com/en/mobility-solutions-en.
# 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.
For mobility support, a new component has to be added on all servers where installation will happen later. Please enter your Open-Xchange LDB (License database) credentials. Replace {LDB-USERNAME} by the user name and {LDB-PASSWORD} by the corresponding password. Please note that accessing this component requires a mobility license key.


<pre>
== Important Files ==
ucr set repository/online/component/oxmobility/server=software.open-xchange.com\
repository/online/component/oxmobility/prefix=OX6/OXSEforUCS \
repository/online/component/oxmobility/username={LDB-USERNAME} \
repository/online/component/oxmobility/password='{LDB-PASSWORD}' \
repository/online/component/oxmobility=enabled
</pre>


After the following installation procedure, you can configure mobility access per-user in the UDM user-module.
OX App Suite and the required components use different files that are of interest for administrating persons.


Beware, that the groupware will be restarted, and users will lose their sessions:
<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.


==== Single Server ====
=== Log files ===


On a single-server solution, following packages have to be installed:
Different log files are useful for troubleshooting and debugging. You find them in the following locations:


<pre>
* <tt>/var/log/open-xchange/open-xchange.log.0</tt> - contains log information from the OX App Suite instance on the system.
apt-get install univention-ox-usm-udm
* <tt>/var/log/mail.info</tt> - is the log file for the Postfix SMTP server.
apt-get install univention-ox-usm-ox
* <tt>/var/log/dovecot.log</tt> - is the log file for the Dovecot IMAP server.
</pre>
* <tt>/var/log/univention/listener.log</tt> - is the log file for the Univention Directory Listener.


==== Multi Server ====
=== Configuration files ===


On master:
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
<pre>
for example in the
apt-get install univention-ox-usm-udm
[[{{PAGENAME}}##Additional_passive_instance_of_OX_App_Suite|authentication
</pre>
adjustments during the installation of the second OX App Suite instance]].


On the primary OX:
* <tt>/opt/open-xchange/etc</tt> - contains the configuration files.
<pre>
apt-get install univention-ox-usm-ox
</pre>


===Spam treatment===
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>:
The antispam package is optional. It must be installed and configured separately, in a distributed environment it must be placed on the IMAP servers.
Install with:
apt-get install univention-mail-antispam-ox


Additionally the open-xchange bundle is required:
ucr set \
  apt-get install open-xchange-spamhandler-spamassassin
  ox/cfg/mail.properties/com.openexchange.mail.mailServerSource="global"


To make the spamd service start automatically the default configuration has to be edited:
Every setting that has been configured by UCR has a respective comment in the configuration file, for example:


/etc/default/spamassassin
'''<pre style="color: red">Warning''':
ENABLED=1
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">


/etc/init.d/spamassassin restart
For documentation on the available configuration settings see the [https://documentation.open-xchange.com/components/middleware/config/7.10.5/ App Suite Configuration Documentation].


Activation
== System messages ==
ucr set postfix/procmaildelivery=yes


The spamrunner is started with
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/antispam/ox/spamrunner=yes


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


== apt cannot find packages ==
'''<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">


Please check the apt-sources. Maybe the credentials were not entered or wrong. UCS doesn't warn about that.
== Greylisting ==
<pre>cat /etc/apt/sources.list.d/20_ucs-online-component.list</pre>
must contain lines like
<pre>deb http://user:password@software.open-xchange.com/OX6/OXSEforUCS/2.2/maintained/component oxseforucs/i386/</pre>


for your architecture (here: /i386/), platform independent (/all/) and all components (at the moment: oxseforucs and oxmobility)
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.


You can check the settings of your components on the shell with
=== Installation ===
<pre>ucr search repository</pre>


Then configure the variables with (here: the password for the oxseforucs component):
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:
<pre>ucr set repository/online/component/oxseforucs/password=secret</pre>


systemctl restart postgrey
systemctl restart postfix


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


== What is the oxmobility component? ==
ucr search greylisting
The oxmobility component is the implementation of "OXtender for Business Mobility" into OXSEforUCS. It has to be licensed and installed seperately. Further information is available under http://sdb.open-xchange.com/faq/63


== How can I switch of the scan of the package database? ==
=== Configuration ===


If you keep getting messages like:
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.
<pre>Cannot find service-record of _pkgdb._tcp.
No DB-Server-Name found.
</pre>
you can ignore them or switch the packagedb-scan off with
<pre>ucr set pkgsb/scan=no


</pre>
{| 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.
|-
|}


== Where are the repositories located? ==
You can find a more information on the postgrey configuration in the postgrey man page.


Conceptionally, OXSEforUCS is a component or an add-on to UCS. Thus, the distribution of ucs and the apt-sources are located at http://apt.univention.de
= Optional: Univention Corporate Server SAML-SSO Configuration with OX App Suite =


The apt-sources for the components are in the (LDB-)password-protected area below http://software.open-xchange.com/OX6/OXSEforUCS/
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 =


[[Category: OX6]]
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

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