OX6:OXtender for Business Mobility Installation Guide
Open-Xchange OXtender for Business Mobility
Components
With the OXtender for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management. The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.
Component Overview
USM, EAS and OX work together as components. This is a general outline about how these components interact.
When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.
Requirements
Since the OXtender for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. Open-Xchange Server 6.12 or later is required to operate this extension. The OXtender for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.
Please Note: To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article Updating OX-Packages explains how that can be done.
Download
Follow this link to download the Installation package and the Release Notes. (The LDB credentials have to be provided)
Follow this link to download the User Manuals in different languages.
Installation of the OXtender for Business Mobility
New Installation
After downloading the addon package, it can be installed using the operating systems package manager. This will extract the package and configure the integration with Open-Xchange Server.
For Debian based systems:
dpkg -i open-xchange-usm_<version>_all.deb
For SLES or RHEL systems:
rpm -i open-xchange-usm-<version>.noarch.rpm
Move the database update task configuration file to another directory before proceeding with the installation. Only tasks mentioned at this file will be executed. Since the new EAS/USM tasks are not core functionality they are not contained in this file.
mv /opt/open-xchange/etc/groupware/updatetasks.cfg /root
The USM package provides some additional database update tasks, it is required to re-run these update tasks after the installation. This is done by resetting the database version of the OX database which will trigger all relevant update tasks up to the most current database version. Database update tasks that have already been completed in the past will not be executed again. You only need to run this command for one context of each database schema.
/opt/open-xchange/sbin/resetversion -v 33 -c 1
Now the Open-Xchange groupware and admin service needs to be restarted:
/etc/init.d/open-xchange-groupware restart /etc/init.d/open-xchange-admin restart
Move the database update task configuration file back to its original directory.
mv /root/updatetasks.cfg /opt/open-xchange/etc/groupware/
On the first login of a user after the restart, all required database tables will be created.
Configuration
Open-Xchange configuration
The configuration for USM and the EAS protocol can be found in these two configuration files:
/opt/open-xchange/etc/groupware/usm.properties /opt/open-xchange/etc/groupware/eas.properties
Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface.
com.openexchange.usm.ox.url=http://your.ox.server/ajax/
Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.
/etc/init.d/open-xchange-groupware restart
Apache Configuration
Mobile devices supporting ActiveSync use a special URL to communicate with the ActiveSync enabled server. This URL needs to be forwarded to the Open-Xchange ActiveSync servlet. When using Apache 2 and mod_proxy_ajp, this servlet can simply be added to the webservers proxy_ajp configuration:
ProxyPass /Microsoft-Server-ActiveSync ajp://127.0.0.1:8009/Microsoft-Server-ActiveSync smax=0 ttl=60 retry=5
The example assumes that the Open-Xchange server is running on the same machine like the webserver. Please refer the Open-Xchange administrator documentation for more information about Apache configuration. Please restart apache after performing the configuration change.
Enabling ActiveSync for user accounts
In order to use synchronization through ActiveSync, this feature needs to be activated for those user accounts. You can either activate specific users or a whole context.
Activating ActiveSync for specific users:
/opt/open-xchange/sbin/changeuser -c 1 -u testuser --access-usm on --access-active-sync on
Activating ActiveSync for a whole context:
/opt/open-xchange/sbin/changecontext -c 1 --access-usm on --access-active-sync on
Upgrade from a previous BETA version
It is very important to know that updating your installation requires a bit more than just installing the latest packages. Some additional tasks need to be executed by the administrator to successfully upgrade the USM installation.
After downloading the packages, they can be installed using the operating systems package manager. For example:
dpkg -i open-xchange-usm_<version>_all.deb
This will extract the package and configure the integration to the Open-Xchange server. Please check the configuration files after applying an update for correct settings.
/opt/open-xchange/etc/groupware/usm.properties /opt/open-xchange/etc/groupware/eas.properties
Move the file /opt/open-xchange/etc/groupware/updatetasks.cfg to another directory before starting the update procedure.
mv /opt/open-xchange/etc/groupware/updatetasks.cfg /root
Now the Open-Xchange groupware and admin service needs to be shut down:
/etc/init.d/open-xchange-groupware stop /etc/init.d/open-xchange-admin stop
The next step is to purge some database tables, as the USM installer is not able to do this step on his own at the moment. To do so please execute the following mysql commands. Afterwards you need to re-run the updatetasks once again. This is done by resetting the database version of the OX database which will trigger all relevant updatetasks. Note that the database name for Open-Xchange Server mentioned in this example can be different, depending on your setup.
mysql> USE oxdatabase_6; mysql> DROP TABLE USMSessionFields; mysql> DROP TABLE sequence_usmSessionId; mysql> DROP TABLE USMDataStorage; mysql> DROP TABLE usmIdMapping; mysql> DROP TABLE sequence_usmIdMapping; mysql> DROP TABLE easUIDMapping; mysql> DROP TABLE USMSession; mysql> DROP PROCEDURE get_sequence_usmIdMapping_id; mysql> DROP PROCEDURE get_sequence_usmSessionId_id; mysql> UPDATE version SET version=33;
Start the Open-Xchange groupware and admin service again:
/etc/init.d/open-xchange-groupware start /etc/init.d/open-xchange-admin start
Move the file updatetasks.cfg back to its original directory.
mv /root/updatetasks.cfg /opt/open-xchange/etc/groupware/
On the first login of a user after the restart, all required database tables will be created.