Difference between revisions of "OX6:OXtender for Business Mobility Installation Guide"

(changed the name of the properties file to enable debug logging)
(removed old installation howtos/versions from requirements)
 
(32 intermediate revisions by 8 users not shown)
Line 1: Line 1:
= Open-Xchange OXtender for Business Mobility =
+
= Open-Xchange Connector for Business Mobility =
  
 
== Components ==
 
== 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.
+
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.
 
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.
  
Line 13: Line 13:
 
=== Requirements ===
 
=== 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.16 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.
+
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.
 
 
* [[Open-Xchange_Installation_Guide_for_Debian_4.0 | Debian 4.0 (Etch)]]
 
* [[Open-Xchange_Installation_Guide_for_Debian_5.0 | Debian 5.0 (Lenny)]]
 
* [[Open-Xchange_Installation_Guide_for_SLES10 | SLES10]]
 
* [[Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]
 
* [[Open-Xchange_Installation_Guide_for_RHEL5 | RHEL5]]
 
  
 
'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license.  The article [[UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.
 
'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license.  The article [[UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.
  
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD}}
+
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility}}
  
 
Follow this [http://software.open-xchange.com/OX6/doc/BusinessMobilityOXtender/ link] to download the User Manuals in different languages.
 
Follow this [http://software.open-xchange.com/OX6/doc/BusinessMobilityOXtender/ link] to download the User Manuals in different languages.
Line 33: Line 27:
  
 
On the first login after the restart, all required database tables will be created.
 
On the first login after the restart, all required database tables will be created.
 +
 +
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=6.22/OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility|version=v6.22.x}}
 +
 +
=== RedHat Enterprise Linux 5 ===
 +
'''Please note,''' the last available version for RHEL5 is 6.22.0
 +
 +
$ vim /etc/yum.repos.d/oxmobility.repo
 +
 +
[oxmobility]
 +
name=Open-Xchange
 +
baseurl=http://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/OX6/6.22/6.22.0/OXtender/BusinessMobilityOXtender/RHEL5/
 +
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
 +
enabled=1
 +
gpgcheck=1
 +
metadata_expire=0m
 +
 +
and run
 +
 +
$ yum update
 +
$ yum 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 on 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:
 +
 +
* The new license is already registered at the LDB after purchase.
 +
* Log on at the Univention Management Console (UMC)
 +
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"
 +
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"
 +
* Within the component list, select "Connector for Business Mobility" and press the "Install" button
 +
 +
== Installation on OX App Suite ==
 +
The download and installation information for Open-Xchange App Suite product family (Open-Xchange Server Edition and Hosting Edition) is available at: http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Business_Mobility_Installation_Guide
  
 
== Configuration ==
 
== Configuration ==
 +
 +
=== Mail Push ===
 +
 +
In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle‎‎]] instructions on how to set up real mail push with cyrus.
 +
 
=== Open-Xchange configuration ===
 
=== Open-Xchange configuration ===
 
The configuration for USM and the EAS protocol can be found in these two configuration files:
 
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/usm.properties
  /opt/open-xchange/etc/groupware/eas.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.
 
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/
 
  com.openexchange.usm.ox.url=http://localhost/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.
+
in case webserver and Open-Xchange aren't running on the same machine:
/etc/init.d/open-xchange-groupware restart
+
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/noipcheck.cnf
 +
to include the range of IP addresses of the servers on which USM is running.
  
=== 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. 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 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.
+
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/apache2 restart
 
  
 
=== Enabling ActiveSync for user accounts ===
 
=== Enabling ActiveSync for user accounts ===
Line 65: Line 107:
 
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.
 
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 ===
+
=== Server-side logging: Options ===
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.
+
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.  
 +
 
 +
There are three different mechanisms, depending on your server version: If you use 7.4.2 or later, we use ''logback''. Before that, the default was ''commons logging'', unless you explicitly installed ''Log4j''.
 +
 
 +
==== Logback ====
 +
As said, this is the default after (and including) 7.4.2. To get more verbose output, simply extend the logback.xml configuration file by the following line:
 +
 
 +
  <logger level="DEBUG" name="com.openexchange.usm"/>
 +
 
  
=== Commons Logging ===
+
==== 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:
+
This is the default logging mechanism prior to 7.4.2. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it is an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:
  
  vim /opt/open-xchange/etc/groupware/file-logging.properties
+
  vim /opt/open-xchange/etc/file-logging.properties
 
  [...]
 
  [...]
 
  com.openexchange.usm.level=FINE
 
  com.openexchange.usm.level=FINE
Line 77: Line 127:
 
This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.
 
This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.
  
=== Log4j ===
+
==== 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:
 
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/groupware/log4j.xml
+
  vim /opt/open-xchange/etc/log4j.xml
 
  [...]
 
  [...]
 
     <category name="com.openexchange.usm">
 
     <category name="com.openexchange.usm">
Line 89: Line 139:
 
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.
 
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 ===
+
=== Client-side logging: 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.
 
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/groupware/eas.properties
+
  vim /opt/open-xchange/etc/eas.properties
 
  [...]
 
  [...]
 
  com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log
 
  com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log
Line 106: Line 156:
 
[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]
 
[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]
  
* Product: OXtender for Business Mobility
+
* Product: Connector for Business Mobility
  
 
[[Category: OX6]]
 
[[Category: OX6]]

Latest revision as of 05:12, 1 October 2019

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.

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.

Install on OX AppSuite

Debian GNU/Linux 10.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/products/OXtender-stable/BusinessMobilityOXtender/DebianBuster/ /

and run

$ apt-get update
$ apt-get install open-xchange-meta-mobility

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/products/OXtender-stable/BusinessMobilityOXtender/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-meta-mobility


Follow this link to download the User Manuals in different languages.


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

On the first login after the restart, all required database tables will be created.

Install on OX v6.22.x

Debian GNU/Linux 10.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/products/6.22/OXtender-stable/BusinessMobilityOXtender/DebianBuster/ /

and run

$ apt-get update
$ apt-get install open-xchange-meta-mobility

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/products/6.22/OXtender-stable/BusinessMobilityOXtender/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-meta-mobility


RedHat Enterprise Linux 5

Please note, the last available version for RHEL5 is 6.22.0

$ vim /etc/yum.repos.d/oxmobility.repo

[oxmobility]
name=Open-Xchange
baseurl=http://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/OX6/6.22/6.22.0/OXtender/BusinessMobilityOXtender/RHEL5/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update
$ yum 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 on 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:

  • The new license is already registered at the LDB after purchase.
  • Log on at the Univention Management Console (UMC)
  • Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"
  • Click on "App Center" at the UMC und switch to the tab "Repository Settings"
  • Within the component list, select "Connector for Business Mobility" and press the "Install" button

Installation on OX App Suite

The download and installation information for Open-Xchange App Suite product family (Open-Xchange Server Edition and Hosting Edition) is available at: http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Business_Mobility_Installation_Guide

Configuration

Mail Push

In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the MailNotify Bundle‎‎ instructions on how to set up real mail push with cyrus.

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/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.

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.

Server-side logging: Options

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.

There are three different mechanisms, depending on your server version: If you use 7.4.2 or later, we use logback. Before that, the default was commons logging, unless you explicitly installed Log4j.

Logback

As said, this is the default after (and including) 7.4.2. To get more verbose output, simply extend the logback.xml configuration file by the following line:

 <logger level="DEBUG" name="com.openexchange.usm"/>


Commons Logging

This is the default logging mechanism prior to 7.4.2. If the Open-Xchange Server log output is written to var/log/open-xchange/open-xchange.log it is 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.

Client-side logging: 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).

Bug-Reporting

Please report bugs via the Open-Xchange Bugzilla:

Direct link to Open-Xchange Bugzilla

  • Product: Connector for Business Mobility