Opush 3.1.0 Administration Guide

Opush is capable of doing bidirectional synchronization of:

Every ActiveSync client should be able to synchronize with OBM through Opush.

However, there’s a limited list of officially supported devices:

As Microsoft Exchange Server, Opush can’t go over some clients limitations (or bugs)!

Be aware that users with Android (> 4.4) have limitations on address books synchronization. Their secondary address books (others than the "contacts" one) are read-only, so please note that:

All kind of operations are available (and encouraged) on the main address book.

The Microsoft definition of objects such as events, contacts or emails differ from the OBM representation. Opush closes this gap by providing an ActiveSync frontend to OBM.

For this purpose, when a synchronization request comes from a device, Opush analyzes this request, looks for OBM service locations and delegates data retrieval to Cyrus, obm-sync and/or LDAP.

It then keeps track of objects pushed to the device to handle subsequent synchronization requests. It uses Cassandra and Postgres for this purpose.

Opush is a Java application using an embedded http server.

It uses a modular design that allows shifting technology without breaking the whole application every time.

Recently, Opush has changed the email backend from an in-house solution to a javax.mail based backend and then returned to an improved version of the in-house solution.

It also changed from EHCache to Cassandra for internal state storage.

We expect to continue with such breaking changes for some times, improving our capabilities such as high availability, horizontal scalability, improved management, great monitoring, and support for latest ActiveSync specifications.

First of all, you have to create a keyspace, this must be done in the cqlsh shell with Cassandra administrator:

A keyspace is created with a data replication configuration, to understand it please read this page.
Create it with the following command in the cqlsh shell:

Where:

Finally, still in the cqlsh shell, create a Cassandra user for Opush:

Where:

Modify your /etc/apt/sources.list file by adding the Opush repository:

Add the OBM GPG public key:

Update the system packages list:

And finally, install Opush

Modify your /etc/apt/sources.list file by adding the Opush and squeeze-backports repositories:

Add the OBM GPG public key:

Update the system packages list:

Install Opush:

During the installation process, you will be asked some questions:

Answering these questions will modify the following configuration files:

At this step you should have a Opush 3 and a Cassandra cluster installed and configured.
The last thing to do to have your Opush ready to use is to setup the Cassandra schema.

As obm-full-2.5.X depends on opush-2.5.X, the installation of Opush 3 conflicts with obm-full-2.5.X.
obm-full is a meta-package only used to simplify installation of all OBM packages.
If you have it installed, it will be removed automatically when upgrading to the new version of Opush. This will not affect the functionality of OBM.

During the upgrade apt-get will ask for confirmation before removing conflicting packages. As these are dependencies of Opush 2 only, packages listed below will be removed. No other removal should be necessary.

Modify your /etc/apt/sources.list file by adding the Opush repository:

Update system packages list:

Finally, upgrade Opush:

You will be asked to remove some packages:

Go ahead and accept this solution by answering with Y.

Afterwards, accept the newly installed packages:

Modify your /etc/apt/sources.list file by adding the Opush and squeeze-backports repositories:

Update the system packages list:

To upgrade Opush when you have obm-full installed, please read the Package Dependency Conflicts to understand what will be done with your OBM packages.

To resolve conflicts properly use apt-get instead of aptitude and install explicitly every obm-full dependency to be sure to keep everything.

During the installation process, you will be asked some questions:

Answering these questions will modify the following configuration files:

At this step you should have a Opush 3 and a Cassandra cluster installed and configured.
The last thing to do to have your Opush ready to use is to setup the Cassandra schema.

In order to add the Opush RPM repository declaration, create the file /etc/yum.repos.d/opush.repo and add the following lines:

At this step you should have a Opush 3 and a Cassandra cluster installed and configured.
The last thing to do to have your Opush ready to use is to setup the Cassandra schema.

In order to add the Opush RPM repository declaration, create the file /etc/yum.repos.d/opush.repo and add the following lines:

First of all, you have to remove legacy components:

And finally, upgrade Opush:

At this step you should have a Opush 3 and a Cassandra cluster installed and configured.
The last thing to do to have your Opush ready to use is to setup the Cassandra schema.

The first time you will start Opush, opush.log will contain the following message:

Opush server will not be accessible to clients, but the administrator can connect using the CRaSH shell.
Furthermore you have to execute the schema install CRaSH command and then restart Opush.

There are two kinds of schema upgrades:

CRaSH is a console to administer or monitor an application running on the JVM.

Starting with Opush 2.5.0, Opush integrates CRaSH to provide several administration and debug commands. It is enabled by default and is reachable using an SSH client on port 5665.

Sometimes users may need to reset their devices. This can be done by two different ways in OBM:

Here is a list of devices which are known to be compatible with this operation:

We supply a probe called Spushnik to supervise your Opush server. See the spushnik documentation for more information.

The ActiveSync protocol defines specific URLs on standard https port for devices to detect configuration and perform general operations. Opush runs on port 8082, therefore your web server needs to be configured to publish Opush under the following URLs:

Packaging can create the appropriate Apache configuration to publish the Opush service under this URL. Nevertheless, you sometimes need to manage the reverse proxy configuration by yourself. In this case, be sure to bind https://your_apache_server/Microsoft-Server-ActiveSync to http://your_opush_server:8082/opush/ActiveSyncServlet/ and https://your_apache_server/autodiscover to http://your_opush_server:8082/opush/Autodiscover/

When you try to add an ActiveSync account on your device, you must set the user email address.
When using autoconfiguration feature, the domain part of the email will be used to find the target server.
It’s necessary to have a DNS server configured to help the phone resolve this domain.

Some devices prefix the domain by autodiscover.. So you must add the following entries to your DNS configuration:

and for the reverse DNS part:

Opush needs an IMAP server running and a working IMAP account for every Opush user.
It also needs a working SMTP server.

The Autodiscover feature allows devices to detect the correct configuration based on the user’s email address.

This feature requires a secure communication channel between the device and the server.

Although some devices do not require a valid certificate it is highly recommended to set up a valid SSL certificate.

Two retry policies are available on the Cassandra client configuration used by Opush.

You may choose one of those two different policies by changing the cassandra.retry-policy entry:

The cassandra.max-retries entry determines the maximum number of retries applied on the selected policy.

In order to identify when the retry policy is applied, the Opush administrator has to check in the Opush log file (/var/log/opush/opush.log) for such messages logged by the LoggingRetryPolicy logger:

This file contains important information about Opush operations.

Here is a sample line:

It’s composed of:

Opush, like all Java components of OBM, uses a logging API to generate information useful to developers to investigate bugs. This section documents how to configure the right log level for your needs as an administrator.
Loggers exist in two forms: named loggers and technical loggers.
Technical loggers have names related to the code they belong to and should not be enabled by an administrator.
Named loggers help administrators to understand what happens in their server in order to solve some configuration problem or file a bug report.
Opush will output every log with a level greater or equals to WARN, regardless of the logger name.
You can enable these named loggers by adding entries in /etc/opush/logback.xml.
Modifications are taken into account every minute. You can check that everything is applied correctly by looking at logs in /var/log/opush/out.log.

You can use the following logger modules:

Requests execution timings are tracked by Opush. It records the time spent in every category that compose the request life-cycle.

You have to read the BREAKDOWN log line above as a tree where levels are separated by parentheses.
It is easy to understand with some explanations:

Interpretation of these values can be useful to understand performance metrics of your Opush server.
What is interesting in this example is OTHER:1076, it means that 1076ms has been spent in unnamed code category of EMAIL.
It might be the imap server taking very long to process the Opush requests.

There are few fundamental rules that can be considered for better performance analysis:

A summary log looks like this :

The three fields are always present even when the actual value is 0.

This log is written for every request that retrieve or modify some data.

The changeset provided by OP-139 aims to protect the backend about contact duplication.
That protection is implemented using the hash of every contact created by a device.
When a contact hash is already known by Opush, it’ll not send the creation command to its backend.

This fix has been done to handle the never fixed "ClientId" bug of Android, see https://code.google.com/p/android/issues/detail?id=61100