6.0.0-git
2021-10-17
Last Modified 2010-04-11 by Michael Rubinsky

Horde_ActiveSync

Add ActiveSync support to Horde for allowing Horde to sync with mobile devices using the mobile device's support for Microsoft Exchange/ActiveSync. Use Z-Push library (http://z-push.sourceforge.net) for handling ActiveSync protocol communication.

Bugs

People

Michael Rubinsky
Jan Schneider

Description

Integrate the Z-Push library into Horde. Provide the ability for Horde to provide over the air synchronization of email, contacts, and calendar data to devices such as the iPhone/iPod Touch, Android and any other system supporting ActiveSync. This implementation supports Microsoft ActiveSync protocol versions up to 2.5 - the version implemented by Microsoft Exchange 2003.

Trying it out

The ActiveSync code has been merged into git master, but is not active by default. You should be aware that this code is still very experimental. While it mostly works for me in my tests, on my test devices, there are likely still many bugs. It may work, it might not, or it might make your iPod grow legs and run for higher ground. You have been warned.

To activate the server, you need to enable it in Horde's configuration. You will see an ActiveSync tab.

You will also need to configure your webserver to redirect the URL Microsoft-Server-ActiveSync to your horde/rpc.php file. How you do this depends on your webserver and it's configuration. For Apache, something like:

Alias /Microsoft-Server-ActiveSync /var/www/html/horde/rpc.php

or for lighttpd:

alias.url = ("/Microsoft-Server-ActiveSync" => "/var/www/html/horde/rpc.php");

What works

Contacts, Calendar and Task syncing are mostly working. The only client with task support that has been tested is the TouchDown client. Neither Android or the iPod/iPhone have a native ActiveSync tasks application.

Provisioning along with remote wipe is also working on devices that actually support it.

This code has been tested to some degree on the following devices:
Device Version(s) Provisioning Notes
Android SDK Emulator 2.0.1 and 2.1 Does NOT support provisioning and will NOT work with it set to Force or Allow. Contacts only as the emulator does not have a native calendar application
Motorola Droid 2.0.1 and 2.1 No (See above) Contacts and Calendar data (Droid's Corporate Calendar has a buggy client implementation)
Motorola Milestone 2.1 See important note below ??
TouchDown For Droid Version 5.1.0028 Yes Contacts, Calendar (You can create recurring events, but cannot edit them. Also, recurring events with exceptions are not supported at all. See Touchdown website for details), and Tasks.
iPod Touch 3.1.3 Yes Contacts and Calendar

IMPORTANT NOTE There have been reports that some devices running Android 2.1 DO have support for provisioning, however there have been reports of major issues with regards to the unlock password screen. Evidently, once a password is set it looks like it's impossible to remove it. I have tested both the 2.1 SDK emulator as well as the Motorola Droid (NOT the Milestone) and these still do NOT support provisioning. This issue might be limited to the Milestone device. That being said if you plan on having users with Android 2.1 devices, do NOT enable provisioning unless you are willing to deal with this issue.

Setting up the device

It's beyond the scope of this page to go into detail for each individual device. In general, you will need to create a new account on your device. The account type should be something like Microsoft Exchange or ActiveSync. Some devices use Corporate. You will need to enter your normal Horde username and password in the appropriate fields. In the field for the server address, you should enter the root of the webserver or virtual host that hosts Horde. For example, if you host horde at http://host.example.com/horde then you should enter http://host.example.com. You can ignore any reference to a domain entry.

A special note for the iPhone/iPod (and possibly others) - if you do not use a SSL enabled site you may receive errors about not being able to find the ActiveSync server. If this happens, just continue, or save, or whatever your option is to continue. On the iPhone, after everything is completely set up, you must go back into the account settings and disable SSL.

After the connection particulars are entered, you should choose to enable the folders that you want sync'd. Right now only Contacts and Calendar are supported.

Provisioning/RemoteWipe

Provisioning allows devices to be more tightly registered with a particular server. It enables the server to be able to send policy settings to the device. These policy settings include things like requiring a PIN to unlock the device, the complexity of the PIN required, the number of failed login attempts allowed etc... Additionally, it enables devices to be remotely wiped so that if a device is lost or stolen, the user or administrator can request the device to be wiped.

As of yet, no user interface yet exists for initiating a remote wipe, but the functionality is there. If you want to test this you need to:

  1. Open up the device's state info file. This is in your state directory and is named info-{deviceidgoeshere}.
  2. Set the 'rwstatus' value from 0 to 2.
  3. Change the policykey to 0 (actually, any value other then the current policykey would work).
  4. Save the file

The next time the device attempts to request a command other then PING or OPTIONS, it will be wiped. DO THIS AT YOUR OWN RISK!!! After it is wiped, if you wish to allow the device to connect to your server again, you should remove the info-{deviceidgoeshere} file so it can be rebuilt. If you do not remove this file, or at least set the value of rwstatus back to 0, the device will continue to be wiped each time it reconnects to the server.

Rough list of issues/todos/development notes in no particular order

  • Horde_History state driver. Currently, ActiveSync support uses a file-based state driver to persist the PIM state so we know what changes. This is a refactored implementation of what the Z-Push library does. For Horde, this is inefficient, as we have the data needed to know what has changed and when. Once the majority of the feature set is working, a Horde_History driver should be written to replace the file based driver when syncing contacts, calendar, and todo data. We might still need it if/when push email is implemented. The backend drivers are able to specify a particular state storage to enable this functionality if it is needed.
    • Need to implement ghosted properties / SUPPORTED tag. Currently, each message that is sent from PIM -> Server is overwritten and replaced with only what the PIM sends. It's possible for some PIMS to ghost contact and calendar properties so that only the supplied tags are changed and missing, ghosted, properties are retained on the server. When a PIM supports this, it sends a SUPPORTED tag with children representing the NON-ghosted properties. The absence of the SUPPORTED tag would indicate that any property not transmitted should be handled as a ghosted property.
    • Configurable heartbeat interval range: The protocol allows for rejecting heartbeat intervals that fall outside a specific range, and send back a suggested heartbeat interval to the client. This should be implemented as a configuration value.
    • Todo syncing: Neither the iPod/iPhone or Android have a native Todo application. TouchDown does provide one, but backend support still needs to be added.
    • Implement more recent protocol version support - version 12 or maybe 12.1 (Exchange 2007??) should be fairly non-disruptive. Version 12 would get us more atomic policy settings, local wipe rules, as well as the ability to send the policy settings to the client as the more compact wbxml. 14 (Exchange 2010?) would probably be lots more work as it does away with PING, using SYNC for waiting for changes instead.
    • Rework the PING command's use of state so that it only has to stat the messages that fall within the time period prescribed by the FILTERTYPE tag passed when SYNCing calendar folders. Currently, the file driver is very wasteful in this regard, it has to stat every appointment message on the server since it knows nothing about the FILTERTYPE last used. Need to add the last used filtertype to the device's state file and use that in PING to set an appropriate filter type value for the state machine to use when diffing. This should improve performance greatly on calendars with a substantial amount of old events. Of course, this won't be an issue with a horde history driver.
    • Add configuration in Horde to allow specifying a specific addressbook to act like an Exchange GAL for ActiveSync purposes.

What to do if you have problems (or How to help us debug your issue)

If you are not even able to get past the initial setup page on your phone: you should first check to be sure you do not have SSL enabled on the phone when you're server is not serving SSL. The iPhone/iPod will not let you turn this off until after you save the configuration, so you must continue through all the errors and go back into the settings to disable SSL. You should also make sure that you have not enabled Provisioning support if your phone does not support it.

If the configuration went well, but you are not seeing any contacts/calendar items appear on the device: Some clients require a manual refresh or folder selection after setup when not using the "Automatic Discovery" facility of Exchange. With TouchDown, for example, after setup you must select the folders you want sync'd under the Advanced settings tab. If you can't figure out this issue, we will be happy to try to help work it out, but you should be able to check/provide us with the following:

  • Check the web server error logs and see if there are any PHP errors being logged.
  • Configure Horde to send ActiveSync log messages to a separate logfile. This is configured on the ActiveSync tab of Horde's configuration screen.
  • If you are able to, it would also be useful to run a wireshark session to capture the network communication.
  • In some cases, it might be useful for us to look at the contents of the various state files.

Resources

http://z-push.sourceforge.net
https://zimbrabackend.svn.sourceforge.net/svnroot/zimbrabackend/zimbra.php
Some discussion/issues/info on calendar sycing
http://z-push.sourceforge.net/phpbb/viewtopic.php?f=4&t=119&start=10

Some discussion on remote wipe issues with various devices
http://z-push.sourceforge.net/phpbb/viewtopic.php?f=4&t=802

Useful information/examples:
http://wiki.openchange.org/index.php/ActiveSync_Protocol

Another AS implementation in PHP - there is some good implementation information there for the taking.
https://svn.tine20.org/svn/trunk/tine20/ActiveSync

TouchDown Client:
http://www.nitrodesk.com/dk_touchdownFeatures.aspx

Android SDK:
http://developer.android.com/sdk/index.html

iPhone/iPod Touch EAS:
http://manuals.info.apple.com/en_US/Enterprise_Deployment_Guide.pdf


Back to the Project List