AppSuite:Connector for Business Mobility Installation Guide
Open-Xchange Connector for Business Mobility
Components
With the Connector 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 Connector 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. OX App Suite v7.0 or later is required to operate this extension. The Connector 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.
Installation
Redhat Enterprise Linux 6 or CentOS 6
Add the following repositories to your Open-Xchange yum configuration:
[open-xchange-usm-updates] name=Open-Xchange-usm-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/usm/updates/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-mobilityconnector] name=Open-Xchange-mobilityconnector baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/mobilityconnector/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-usm] name=Open-Xchange-usm baseurl=https://software.open-xchange.com/products/appsuite/stable/usm/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
$ yum install open-xchange-meta-mobility
Redhat Enterprise Linux 7 or CentOS 7
Add the following repositories to your Open-Xchange yum configuration:
[open-xchange-usm-updates] name=Open-Xchange-usm-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/usm/updates/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-mobilityconnector] name=Open-Xchange-mobilityconnector baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/mobilityconnector/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-usm] name=Open-Xchange-usm baseurl=https://software.open-xchange.com/products/appsuite/stable/usm/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
$ yum install open-xchange-meta-mobility
Debian GNU/Linux 7.0 (valid until v7.8.2)
Add the following repositories to your Open-Xchange apt configuration:
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/usm/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/mobilityconnector/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/7.8.2/usm/DebianWheezy /
$ apt-get update $ apt-get install open-xchange-meta-mobility
Debian GNU/Linux 8.0
Add the following repositories to your Open-Xchange apt configuration:
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/usm/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/mobilityconnector/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/usm/DebianJessie /
$ apt-get update $ apt-get install open-xchange-meta-mobility
SUSE Linux Enterprise Server 11 (valid until v7.8.2)
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/usm/updates/SLES11 usm-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/mobilityconnector/SLES11 mobilityconnector
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/usm/SLES11 usm
$ zypper ref $ zypper install open-xchange-meta-mobility
Now the Open-Xchange service needs to be restarted:
/etc/init.d/open-xchange restart
On the first login after the restart, all required database tables will be created.
SUSE Linux Enterprise Server 12
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/usm/updates/SLE_12 usm-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/mobilityconnector/SLE_12 mobilityconnector
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/usm/SLE_12 usm
$ zypper ref $ zypper install open-xchange-meta-mobility
Now the Open-Xchange service needs to be restarted:
/etc/init.d/open-xchange restart
On the first login after the restart, all required database tables will be created.
Download and Installation OX Server Edition / App Suite for UCS
If you have purchased the OX Server Edition / App Suite for UCS, the Connector is part of the offering. Installation of the Connector with the following steps:
- Please make sure that the OX Customer Id has been entered in the UMC module "OX License Management" (Category "System").
- Open the UMC module "Repository Settings" (Category Software), activate the checkbox "oxmobility762" resp. "oxmobility780" (depends on the installed OX version) and click on "Install".
- The module shows a confirmation dialog that shows which packages will be installed if the installation of the Connector for Business Mobility is continued.
- After installation open the UMC module "Domain Join" (Category "Domain") and execute all pending join scripts to complete installation.
Configuration
Mail Push
A push mechanism is highly recommended to have a proper user experience. In order to set up mail push, follow the introduction and see the possibilities here.
Open-Xchange configuration
The configuration for USM and the EAS protocol can be found in these two configuration files:
/opt/open-xchange/etc/usm.properties /opt/open-xchange/etc/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. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.
com.openexchange.usm.ox.url=http://localhost/ajax/
in case webserver and Open-Xchange aren't running on the same machine:
com.openexchange.usm.ox.url=http://$FQDN/ajax/
(Where $FQDN is the fully qualified domain name of your frontend system)
On clustered setups, adjust the file /opt/open-xchange/etc/groupware/noipcheck.cnf to include the range of IP addresses of the servers on which USM is running.
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.
Apache Configuration
Mobile devices supporting ActiveSync use a special URL to communicate with an ActiveSync enabled Open-Xchange Server. This URL needs to be forwarded to the Open-Xchange ActiveSync servlet. The required configuration options are already part of the default Open-Xchange installation instructions.
The example assumes that Open-Xchange Server is running on the same machine like the webserver. Please refer the Open-Xchange administration documentation for more information about Apache configuration. Please restart apache after performing the configuration change.
/etc/init.d/apache2 restart
Enabling ActiveSync for user accounts
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.
Activating ActiveSync for specific users:
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on
Activating ActiveSync for a whole context:
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on
Log files and issue tracking
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.
Open-Xchange Server logfile
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.
Commons Logging
This is the default logging mechanism. If the Open-Xchange Server log output is written to var/log/open-xchange/open-xchange.log it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:
vim /opt/open-xchange/etc/file-logging.properties [...] com.openexchange.usm.level=FINE
This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.
Log4j
If the package open-xchange-log4j is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like /var/log/syslog. To make the log output more verbose, add the following parameter:
vim /opt/open-xchange/etc/log4j.xml
[...]
<category name="com.openexchange.usm">
<level value="DEBUG"/>
<appender-ref ref="SERVER_LOG"/>
</category>
Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.
EAS debug logfile
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.
vim /opt/open-xchange/etc/eas.properties [...] com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log
This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.
Network traffic
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).
Client configuration
Information about the client configuration for the different devices is available at the User Guides.
Known Issues
- The Exchange Active Sync protocol does not support the synchronization of client email drafts-folder to the server. Synchronization from server drafts-folder to the client will work.