OX6:Open-Xchange Installation Guide for RHEL5 622

Requirements

• Plain installed RedHat Enterprise Linux 5 with latest updates
• Valid access to the RedHat Network
• A configured internet connection

Enabling required RedHat Repositories

When setting up RedHat Enterprise Linux (RHEL), only the base software channel is subscribed, this alone does not provide all required software packages. Before you start, please login to the RedHat Network (https://rhn.redhat.com) using your RedHat Account and enable the channel RHEL Supplementary (v. 5 for ...) by selecting the registered RHEL deployment and using the "Alter Subscriptions" button. After saving this configuration, the RHEL installation is capable to fetch all required software packages for Open-Xchange to work properly.

Add Open-Xchange Repository

Open-Xchange maintains public available software repositories for different platforms, such as RHEL. This repository should be added to the RHEL installation to enable simple installation and updates.

Start a console and create a software repository file for Open-Xchange:

$ vim /etc/yum.repos.d/ox.repo
[ox-appsuiteui]
name=Open-Xchange-appsuiteui
baseurl=https://software.open-xchange.com/products/appsuite/stable/appsuiteui/RHEL5/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL5/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed

[ox-updates-appsuiteui]
name=Open-Xchange Updates-appsuiteui
baseurl=https://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/RHEL5/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m
 
[ox-updates-backend]
name=Open-Xchange Updates-backend
baseurl=https://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL5/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

In case there are issues with an username and password containing URL unsafe characters, e.g. an @, they have to be entered URL encoded. Details can be found at https://www.w3schools.com/tags/ref_urlencode.asp

Updating repositories and installing packages

Reload the package index. This will download the package descriptions available at the software repositories:

$ yum update

The following command starts the download and installation process of all required package for Open-Xchange deployment:

Using Meta packages

The following Meta packages are available:

Name	Description
open-xchange-meta-admin	all provisioning packages
open-xchange-meta-gui	all gui packages
open-xchange-meta-messaging	the complete messaging packages like unified inbox, twitter, facebook, etc.
open-xchange-meta-mobility	OXtender for business mobility
open-xchange-meta-outlook	Outlook OXtender Updater
open-xchange-meta-pubsub	all publish/subscribe related packages
open-xchange-meta-server	the server backend packages
open-xchange-meta-databaseonly	all packages needed when open-xchange is only managed via database and not e.g. LDAP
open-xchange-meta-singleserver	most of the above

If you want to install everything on a single server, just run

$ yum install open-xchange-meta-singleserver \
   open-xchange-authentication-database open-xchange-spamhandler-default 

Note: You have to choose between one of the available spamhandler and authentication packages depending on your requirements. If you plan to only manage your open-xchange installation via database and do not plan to integrate e.g. with LDAP and OXLDAPSync, you might also want to install the package open-xchange-meta-databaseonly.

Of course you can still install the single packages as usual to be able to select a specific set of functionality that you'd like to have, for example:

$ yum install \
open-xchange open-xchange-authentication-database \
open-xchange-admin-client open-xchange-admin-lib \
open-xchange-admin-plugin-hosting open-xchange-admin-plugin-hosting-client \
open-xchange-admin-plugin-hosting-lib open-xchange-configjump-generic \
open-xchange-admin-doc open-xchange-contactcollector \
open-xchange-conversion open-xchange-conversion-engine \
open-xchange-conversion-servlet open-xchange-crypto \
open-xchange-data-conversion-ical4j open-xchange-dataretention \
open-xchange-genconf open-xchange-genconf-mysql \
open-xchange-imap open-xchange-mailfilter \
open-xchange-management open-xchange-monitoring \
open-xchange-passwordchange-database open-xchange-passwordchange-servlet \
open-xchange-pop3 open-xchange-publish open-xchange-publish-basic \
open-xchange-publish-infostore-online open-xchange-publish-json \
open-xchange-publish-microformats open-xchange-push-udp \
open-xchange-resource-managerequest open-xchange-server \
open-xchange-settings-extensions open-xchange-smtp \
open-xchange-spamhandler-default open-xchange-sql open-xchange-subscribe \
open-xchange-xerces-sun open-xchange-subscribe-json \
open-xchange-subscribe-microformats open-xchange-subscribe-crawler \
open-xchange-templating open-xchange-threadpool open-xchange-unifiedinbox \
open-xchange-admin-plugin-hosting-doc open-xchange-charset \
open-xchange-group-managerequest open-xchange-i18n open-xchange-jcharset \
open-xchange-sessiond open-xchange-calendar-printing \
open-xchange-user-json open-xchange-gui-wizard-plugin \
open-xchange-report-client \
open-xchange-configjump-generic-gui \
open-xchange-gui open-xchange-gui-wizard-plugin-gui \
open-xchange-online-help-de \
open-xchange-online-help-en open-xchange-online-help-fr

Open-Xchange configuration

To avoid confusion right at the start notice that Open-Xchange uses multiple administration levels and requires different credentials at some stages at the installation and server management. Note that the passwords chosen at this guide are weak and should be replaced by stronger passwords.

• The MySQL database user
  • Username: openexchange
  • Password used at this guide: db_password
  • Responsibility: Execute all kinds of database operations

• The Open-Xchange Admin Master
  • Username: oxadminmaster
  • Password used at this guide: admin_master_password
  • Responsibility: Manage contexts, manage all kinds of low level server configuration

• The Context Admin
  • Username: oxadmin
  • Password used at this guide: admin_password
  • Responsibility: Manage users/groups/resources inside a context

As stated above we assume the MySQL service has been installed previously, and it is running and available.

A good idea is to add the Open-Xchange binaries to PATH:

$  echo PATH=$PATH:/opt/open-xchange/sbin/ >> ~/.bashrc && . ~/.bashrc

Now we have to initialize the Open-Xchange configdb database. This can all be done by executing the initconfigdb script.

$ /opt/open-xchange/sbin/initconfigdb --configdb-pass=db_password -a --mysql-root-passwd=root_password

Use the --mysql-root-passwd option to supply the MySQL root password as configured during database installation.

Add the -i option if you want to remove an already existing open-xchange configdb.

Note: The -a parameter adds an openexchange account to MySQL. This account will be used for database connections from the OX App Suite middleware and requires some privileges. You can also create that account manually during database installation / configuration, in which case you can (should) skip the -a parameter here.

Before starting any service, all basic configuration files need to be set up correctly. The --configdb-pass option indicates the password of the openexchange database user previously created, the --master-pass options specifies the password of the Open-Xchange adminmaster user that will be created when executing the oxinstaller script.

Important: You should have your Open-Xchange license code at hand. If you do not plan to license Open-Xchange, you can use the option --no-license instead. Please also check OXReportClient documentation for more information about configuring a supported and maintained Open-Xchange server.

Important: For MAX_MEMORY_FOR_JAVAVM a rule of thumb for simple installations is half available system memory. The value must be in MB. For example "1024" for 1GB .

$ /opt/open-xchange/sbin/oxinstaller --add-license=YOUR-OX-LICENSE-CODE \
--servername=oxserver --configdb-pass=db_password \
--master-pass=admin_master_password --ajp-bind-port=localhost --servermemory MAX_MEMORY_FOR_JAVAVM

Note: In a clustered setup, --ajp-bind-port must be set to *

Now is a good time to configure the way OX will authenticate to your mail server. Edit the file /opt/open-xchange/etc/mail.properties and change the com.openexchange.mail.loginSource to use. This is very important for servers that require your full email address to log in with.

# adjust com.openexchange.mail.loginSource
$ vim /opt/open-xchange/etc/mail.properties

After initializing the configuration, start the Open-Xchange Administration service by executing:

$ /etc/init.d/open-xchange-admin start

Next we have to register the local server at the Open-Xchange configdb database:

$ /opt/open-xchange/sbin/registerserver -n oxserver -A oxadminmaster -P admin_master_password

Now we have to create a local directory that should be used as Open-Xchange filestore. This directory will contain all Infostore content and files attached to groupware objects. To maintain access by the Open-Xchange Groupware service, it is required to grant permissions to the open-xchange system user.

$ mkdir /var/opt/filestore
$ chown open-xchange:open-xchange /var/opt/filestore

Now register the directory as a filestore at the Open-Xchange server:

$ /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P admin_master_password \
-t file:/var/opt/filestore -s 1000000

Note: You might want to adapt the value provided with -s, the "The maximum size of the filestore in MB", see registerfilestore --help.

Note 2: If you are setting up OX App Suite, you need a shared filestore accross your OX servers even though you do not plan to have the OX Files feature enabled for your customers.

Finally register the groupware database, this is a separated database where all groupware specific data is stored:

$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password \
-n oxdatabase -p db_password -m true

Configure services

Now as the Open-Xchange Server has been set up and the database is running, we have to configure the Apache webserver and the mod_proxy_ajp module to access the groupware frontend. To gain better GUI performance, the usage of mod_expires and mod_deflate is strongly recommended. Those modules will limit the amount of client requests and compress the delivered content. The default installation of the Apache webserver on RHEL provides a welcome screen which is not necessary for server operation, it can be removed by deleting the corresponding configuration file:

$ rm /etc/httpd/conf.d/welcome.conf

Configure the mod_proxy_ajp module by creating a new Apache configuration file.

$ vim /etc/httpd/conf.d/proxy_ajp.conf

<Location /servlet/axis2/services>
    # restrict access to the soap provisioning API
    Order Deny,Allow
    Deny from all
    Allow from 127.0.0.1
    # you might add more ip addresses / networks here
    # Allow from 192.168 10 172.16
</Location>

LoadModule proxy_ajp_module modules/mod_proxy_ajp.so

<IfModule mod_proxy_ajp.c>
   ProxyRequests Off
   
   <Proxy balancer://oxcluster>
       Order deny,allow
       Allow from all
       # multiple server setups need to have the hostname inserted instead localhost
       BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
       # Enable and maybe add additional hosts running OX here
       # BalancerMember ajp://oxhost2:8009 timeout=100  smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
      ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
      
   </Proxy>
   
   # OX frontend
   <Proxy /ajax>
       ProxyPass balancer://oxcluster/ajax
   </Proxy>
   <Proxy /servlet>
       ProxyPass balancer://oxcluster/servlet
   </Proxy>
   <Proxy /infostore>
       ProxyPass balancer://oxcluster/infostore
   </Proxy>
   <Proxy /publications>
       ProxyPass balancer://oxcluster/publications
   </Proxy>
   # USM
   <Proxy /usm-json>
       ProxyPass balancer://oxcluster/usm-json
   </Proxy>
   # SOAP
   <Proxy /webservices>
       ProxyPass balancer://oxcluster/webservices
  </Proxy>
  
   # OXtender
   <Proxy /Microsoft-Server-ActiveSync>
       ProxyPass balancer://oxcluster/Microsoft-Server-ActiveSync
   </Proxy>
</IfModule>

Modify the default website settings to display the Open-Xchange GUI

$ vim /etc/httpd/conf.d/ox.conf

<VirtualHost *:80>
	ServerAdmin webmaster@localhost

	DocumentRoot /var/www/html/

	<Directory /var/www/html/>
		AllowOverride None
		Order allow,deny
		allow from all
		RedirectMatch ^/$ /ox6/
               Options +FollowSymLinks +SymLinksIfOwnerMatch
	</Directory>
       # deflate
      AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript

	# pre-compressed files
	AddType text/javascript .jsz
	AddType text/css .cssz
	AddType text/xml .xmlz
        AddType text/plain .po
	
	AddEncoding gzip .jsz .cssz .xmlz
	SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip
	
	ExpiresActive On
	
	<Location /ox6>
	        # Expires (via ExpiresByType to override global settings)
	        ExpiresByType image/gif "access plus 6 months"
	        ExpiresByType image/png "access plus 6 months"
	        ExpiresByType image/jpg "access plus 6 months"
	        ExpiresByType image/jpeg "access plus 6 months"
	        ExpiresByType text/css "access plus 6 months"
	        ExpiresByType text/html "access plus 6 months"
	        ExpiresByType text/xml "access plus 6 months"
	        ExpiresByType text/javascript "access plus 6 months"
	        ExpiresByType text/x-js "access plus 6 months"
	        ExpiresByType application/x-javascript "access plus 6 months"
	        ExpiresDefault "access plus 6 months"
	        Header append Cache-Control "private"
	        Header unset Last-Modified
	        Header unset Vary
	        # Strip version
	        RewriteEngine On
	        RewriteRule v=\w+/(.+) $1 [L]
	        # Turn off ETag
	        Header unset ETag
	        FileETag None
	</Location>
	
	<Location /ox6/ox.html>
	        ExpiresByType text/html "now"
	        ExpiresDefault "now"
	        Header unset Last-Modified
	        Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
	        # Turn off ETag
	        Header unset ETag
	        FileETag None
	</Location>
	
	<Location /ox6/index.html>
	        ExpiresByType text/html "now"
	        ExpiresDefault "now"
	        Header unset Last-Modified
	        Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
	        # Turn off ETag
	        Header unset ETag
	        FileETag None
	</Location>
</VirtualHost>

After the configuration is done, restart the Apache webserver

$ /etc/init.d/httpd restart

Finally start the Open-Xchange Groupware service

$ /etc/init.d/open-xchange-groupware start

Adding services to runlevels

The new services are now installed and configured, but to make them start up on a server boot, they need to be added to some runlevels:

$ chkconfig --level 345 mysqld on
$ chkconfig --level 345 httpd on
$ chkconfig --level 345 open-xchange-groupware on
$ chkconfig --level 345 open-xchange-admin on

Creating contexts and users

Now as the whole setup is complete and you already should get a login screen when accessing the server with a webbrowser, we have to setup a context and a default user as the last step of this tutorial.

The mapping defaultcontext will allow you to set this context as the default one of the entire system so that users which will be created within this context can login into Open-Xchange Server without specifying their domain at the login screen. Only one context can be specified as defaultcontext. The oxadmin user that will be created by this command is the default admin of the created context. This account will gather additional functions that are also described in the administration manual. The context id parameter must to be unique and numeric, otherwise the server will complain when you try to create a context. New contexts must be created by the oxadminmaster user, user accounts inside a context are created with the credentials of the contexts oxadmin account. The access-combination-name property defines the set of available modules and functions for users of the context.

$ /opt/open-xchange/sbin/createcontext -A oxadminmaster -P admin_master_password -c 1 \
-u oxadmin -d "Context Admin" -g Admin -s User -p admin_password -L defaultcontext \
-e oxadmin@example.com -q 1024 --access-combination-name=groupware_standard

To create a user for testing purposes (Make sure the password you use here for the user is the same password as your email account or you will not be able to use the email module until it is set right):

$ /opt/open-xchange/sbin/createuser -c 1 -A oxadmin -P admin_password -u testuser \
-d "Test User" -g Test -s User -p secret -e testuser@example.com \
--imaplogin testuser --imapserver 127.0.0.1 --smtpserver 127.0.0.1

Now connect to the server with a webbrowser and login using the credentials testuser / secret.

A complete overview about the different parameter is provided at the permission matrix

If you need to migrate a batch of users and contexts at once, check the CSV Batch Import documentation page.

Log files and issue tracking

Default logging mechanism

Whenever unexpected or erroneous behavior takes place, it will be logged depending on the configured loglevel. All logfiles are stored at the operating systems default location. Events triggered by the Open-Xchange Groupware services are logged to a rotating file open-xchange.log.0. Those files are the very first place to monitor.

$ tail -f -n200 /var/log/open-xchange/open-xchange.log.0

Alternative logging mechanisms

Apart from the default file logging mechanism, Open-Xchange supports logging via logback framework and therefore via syslog and/or logstash. This makes it possible to directly log to a local or remote syslog daemon or other services. Logback is highly customizable, please see the documentation below.

• Logback configuration Guide OX App Suite

Installing Open-Xchange Update packages

Please read UpdatingOXPackages on how to get access to the latest Open-Xchange packages.