This article will guide you through the installation of the Open-Xchange server, it describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system and requires average system administration skills. More, this guide will show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:
Important: This installation guide will only work for v6.22. If you want to install v6.20 please use the installation guide for earlier versions.
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.
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-frontend] name=Open-Xchange-frontend baseurl=http://software.open-xchange.com/OX6/6.22/frontend/RHEL5/ gpgkey=http://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m [ox-backend] name=Open-Xchange-backend baseurl=http://software.open-xchange.com/OX6/6.22/backend/RHEL5/ gpgkey=http://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[ox-usm] name=Open-Xchange-USM baseurl=http://software.open-xchange.com/OX6/6.22/usm/RHEL5/ gpgkey=http://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-frontend] name=Open-Xchange Updates-frontend baseurl=http://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/OX6/6.22/updates/frontend/RHEL5/ gpgkey=http://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m [ox-updates-backend] name=Open-Xchange Updates-backend baseurl=http://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/OX6/6.22/updates/backend/RHEL5/ gpgkey=http://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[ox-updates-usm] name=Open-Xchange Updates-USM baseurl=http://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/OX6/6.22/updates/usm/RHEL5/ gpgkey=http://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 http://www.w3schools.com/tags/ref_urlencode.asp
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:
If you want to install everything on a single server, just run
$ yum install mysql-server open-xchange open-xchange-authentication-database open-xchange-grizzly open-xchange-admin \ open-xchange-gui
Note 1: You have to choose between one of the available spamhandler and authentication packages depending on your requirements.
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.
In order to setup the Open-Xchange Server it is mandatory to have the database running:
$ /etc/init.d/mysqld start
Note: in case of a distributed setup, it is recommended to start mysql with --skip-name-resolve or to add all hosts to the hosts file of the database server so that slow DNS responses do not slow down the creation of new database connections.
In a distributed setup you should also take care of the fact that Open-Xchange supports only a Statement Based Replication at the moment (http://dev.mysql.com/doc/refman/5.1/en/replication-formats.html). See also Load_balancing_and_clustering
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
Add the -i option if you want to remove an already existing open-xchange configdb.
Note: The -a parameter adds an administrative account to mysql, this administrative account is required for the creation of the oxdatabase database, you may find problems following the instructions of this tutorial if you either set a mysql root password or do not create this administrative account, if you have manually setup this administrative account, grant the permissions for database creation or you may find a problem in the context creation.
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 --network-listener-host=localhost --servermemory MAX_MEMORY_FOR_JAVAVM
Note: In a clustered setup, --network-listener-host 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 service by executing:
$ /etc/init.d/open-xchange 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
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_http module by creating a new Apache configuration file.
$ vim /etc/httpd/conf.d/proxy_http.conf
<Location /webservices> # Please note that the servlet path to the soap API has changed: # 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> # the old path is kept for compatibility reasons <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_http_module modules/mod_proxy_http.so <IfModule mod_proxy_http.c> ProxyRequests Off # When enabled, this option will pass the Host: line from the incoming request to the proxied host. ProxyPreserveHost On <Proxy balancer://oxcluster> Order deny,allow Allow from all # multiple server setups need to have the hostname inserted instead localhost BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1 # Enable and maybe add additional hosts running OX here # BalancerMember http://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2 ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On SetEnv proxy-initial-not-pooled SetEnv proxy-sendchunked </Proxy> # Define another Proxy Container with different timeout for the sync clients. Microsoft recommends a minimum value of 15 minutes. # Setting the value lower than the one defined as com.openexchange.usm.eas.ping.max_heartbeat in eas.properties will lead to connection # timeouts for clients. See http://support.microsoft.com/?kbid=905013 for additional information. # # NOTE for Apache versions < 2.4: # When using a single node system or using BalancerMembers that are assigned to other balancers please add a second hostname for that # BalancerMember's IP so Apache can treat it as additional BalancerMember with a different timeout. # # Example from /etc/hosts: 127.0.0.1 localhost localhost_sync # # Alternatively select one or more hosts of your cluster to be restricted to handle only eas/usm requests <Proxy balancer://eas_oxcluster> Order deny,allow Allow from all # multiple server setups need to have the hostname inserted instead localhost BalancerMember http://localhost_sync:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1 # Enable and maybe add additional hosts running OX here # BalancerMember http://oxhost2:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 route=APP2 ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On SetEnv proxy-initial-not-pooled SetEnv proxy-sendchunked </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> <Proxy /realtime> ProxyPass balancer://oxcluster/realtime </Proxy> # OXtender/EAS specific proxy container with higher timeout <Proxy /Microsoft-Server-ActiveSync> ProxyPass balancer://eas_oxcluster/Microsoft-Server-ActiveSync </Proxy> </IfModule>
Modify the default website settings to display the Open-Xchange GUI
$ vim /etc/httpd/conf.d/ox.conf
After the configuration is done, restart the Apache webserver
$ /etc/init.d/httpd restart
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 on
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 email@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 firstname.lastname@example.org \ --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.
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, events triggered by the Open-Xchange Administration service are logged to open-xchange-admin.log. Those files are the very first place to monitor.
$ tail -f -n200 /var/log/open-xchange/open-xchange.log.0
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.
Depending on your setup and the user accounts, it´s often helpful to know, how to get a better performance from the complete system. This section will try to assist you, how to tune the components within an OX setup, before you need to install a second server, add more RAM, add new CPU to existing servers.
Since OX itself used very specific features from MySQL like InnoDB instead of MyISAM as DB Engine, it´s often needed, how to increase performance of the OX databases. In general, you should always monitor your MySQL system via tools like "munin", to see when your system reaches it´s limits. Once, you recognized, the system responds more and more slowly, you start to read and research on the internet how to change your mysql configuration, specially, the my.cnf file. But due to the fact, that nearly every system is different in regards of hardware etc. you cannot just copy&paste existing configurations. At this point, a tool called "mysqltuner.pl" can help you. MySQLTuner is a script written in Perl that will assist you with your MySQL configuration and make recommendations for increased performance and stability. Within seconds, it will display statistics about your MySQL installation and the areas where it can be improved. To work with this tool, you need unrestricted read access to the MySQL server (OS root access is recommended). Just download and execute as shown below, and modify your existing my.cnf configuration file.
IMPORTANT INFO: The MySQL system must run for several days, to gather statistics and informations about queries etc. from OX. After these days, you should execute mysqltuner.pl script. It does not work if you run it directly after installing an OX/MySQL setup. You can force traffic to OX while writing automatic testcases or jmeter plans.
As already said, this is just ONE way to analyze MySQL systems. You can also check MYSQL.com for a consultant service or similar.
Make the PERL script executable:
$ chmod +x mysqltuner.pl
Execute the PERL script:
If prompted, enter your MySQL credentials and read carefully through the complete output of the script. Now you have very good informations, how to change your mysql system.
Please read UpdatingOXPackages on how to get access to the latest Open-Xchange packages.