5.3.0-git
2016-09-30
Last Modified 2016-02-15 by Michael Rubinsky

ActiveSync

Exchange ActiveSync (EAS) is a protocol designed for client synchronization of Email, Contacts, Calendar, Tasks, and Memo data with a groupware/messaging server. EAS is a WAP Binary XML (WBXML) based protocol and is communicated over HTTP/HTTPS. It was originally developed by Microsoft for synchronizing PocketPC devices with Microsoft Exchange servers, but has since become widely adopted as the preferred synchronization method. Just about every modern device capable of synchronization includes out of the box support for EAS. Android, iOS, Windows Phone, Blackberry, even current versions of Microsoft Outlook and Windows Mail include support for EAS.

In addition to synchronization, the protocol provides some device management and security related features.

People

Michael Rubinsky

Bugs

See the bug tracker and the list of known issues and the list of broken client behavior.

Description

The Horde_ActiveSync library provides the framework for synchronizing a groupware server with an EAS client. This page describes the use of this library for synchronizing a Horde Groupware stack. For the specific versions and features supported in different Horde versions, see the ActiveSync Feature Grid.

As of Horde 5, ActiveSync support passes Microsoft's Remote Connectivity Analyzer - though you must disable provisioning on the account you use for testing since the analyzer doesn't respond to the 449 Header that is sent when Provisioning is required.

For information on using this library in your own groupware stack, see the developer documentation.

Server Setup

To activate the server, it needs to be enabled in Horde's configuration, on the ActiveSync tab. The SQL tables that horde uses are created as usual from the Horde configuration screen.

Webserver

You will 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/horde/rpc.php

Note: It has been reported that when running PHP via mod_fcgid on Apache that the Alias directive will not pass the correct URL to the fcgid-script handler. This can be worked around by using a RewriteRule instead (adapted from http://maurus.net/weblog/2010/10/26/running-z-push-1-4-2-with-apache-and-fastcgifcgid/):
    RewriteEngine On
    RewriteRule ^/Microsoft-Server-ActiveSync /horde/rpc.php [PT,L,QSA]

There has also been a report from that the Authorization headers are not correctly passed when using mod_php with Apache. These are known issues and are should actually already be taken care of by the Horde_Controller_Request object. However, if you are still having issues with ActiveSync complaining about no Authorization errors, you can try the following configuration:

RewriteRule .* - [E=HTTP_MS_ASPROTOCOLVERSION:%{HTTP:Ms-Asprotocolversion}]
RewriteRule .* - [E=HTTP_X_MS_POLICYKEY:%{HTTP:X-Ms-Policykey}]
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

None of these issues have been reported using lighttpd/fastcgi or Apache+mod_fastcgi+php-fpm.

For Apache + PHP-FPM using mod_proxy_fcgi

ProxyPassMatch ^/Microsoft-Server-ActiveSync$ unix:/usr/local/php55/sockets/webapps.sock|fcgi://127.0.0.1:9000/var/www/html/horde/rpc.php$1

Note: Sockets are only available from Apache 2.4.8 or if the appropriate patch has been applied. In all other case, use a tcp connection.
Note: If setting ProxyErrorOverride On then when testing the ActiveSync endpoint via a browser you may not see the expected activesync error message - as it would be replaced by the overridden Apache error message.

Since Horde ActiveSync connections are held open for a period of time up to 3540 seconds (depending on client and $conf[activesync][ping][heartbeatmax] setting, if using a proxy server you need to ensure it does not time out before the request is complete. Add this to your virtualhost:

ProxyTimeout 5400

Autodiscover

In order for the Autodiscovery service to work, a request to /autodiscover/autodiscover.xml needs to reach rpc.php. How it does this depends on your specific server setup. Below are a few examples to point you in the right direction. Note that for autodiscovery to work, the final endpoint MUST be over SSL. Autodiscover requests will NOT work without a valid SSL certificate.

The easiest example is when Horde is running on the same domain, with NO subdomain as the email address domain. Example, for user@example.com and Horde is reachable at https://example.com/horde. For this, you simply create an Alias pointing /autodiscover/autodiscover.xml to /rpc.php. Note that the documentation specifies different case for the URL in different parts. You should allow the following URLs to be redirected:

Alias /autodiscover/autodiscover.xml /var/www/horde/rpc.php
Alias /Autodiscover/Autodiscover.xml /var/www/horde/rpc.php
Alias /AutoDiscover/AutoDiscover.xml /var/www/horde/rpc.php

For Apache + PHP-FPM using mod_proxy_fcgi

ProxyPassMatch ^/autodiscover/autodiscover.xml$ unix:/usr/local/php55/sockets/webapps.sock|fcgi://127.0.0.1:9000/var/www/html/horde/rpc.php$1
ProxyPassMatch ^/Autodiscover/Autodiscover.xml$ unix:/usr/local/php55/sockets/webapps.sock|fcgi://127.0.0.1:9000/var/www/html/horde/rpc.php$1
ProxyPassMatch ^/AutoDiscover/AutoDiscover.xml$ unix:/usr/local/php55/sockets/webapps.sock|fcgi://127.0.0.1:9000/var/www/html/horde/rpc.php$1

A more common example is when Horde is running on something like mail.example.com while the email addresses are simply @example.com. For this, there are two options. First, if example.com is an existing site, already runs over HTTPS and is on the same physical server as mail.example.com, you could simply use the Alias example above in the configuration for the example.com site. Note again, this MUST ALL BE OVER SSL.

If the ActiveSync client fails to find an acceptable autodiscover response at https://example.com, it will then send a request to http://autodiscover.example.com. Note that this is NOT over SSL. This request MUST respond with a 302 redirect to a SSL endpoint that will answer the autodiscover request:

<VirtualHost *:80>
    ServerName autodiscover.example.com
    DocumentRoot /var/www/html
    RedirectMatch 302 (?i)/autodiscover/autodiscover.xml https://mail.example.com/autodiscover/autodiscover.xml
</VirtualHost>

# Obviously, you can't use a wildcard 443 here, but you get the idea...basically you
# need to set these Alias entries for https://mail.example.com/autodiscover/autodiscover.xml
<VirtualHost *:443>
    ServerName mail.example.com
    Alias /autodiscover/autodiscover.xml /var/www/html/groupware/rpc.php
    Alias /Autodiscover/Autodiscover.xml /var/www/html/groupware/rpc.php
    Alias /AutoDiscover/AutoDiscover.xml /var/www/html/groupware/rpc.php
   
   ##  Rest of config....
</VirtualHost>

Basic example for lighttpd:

$HTTP["host"] =~ "(^|www\.)example\.com$" {
    url.redirect = ("^/(?i)autodiscover/autodiscover.xml$" => "https://horde.example.com/autodiscover/autodiscover.xml")
}

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

It should also be noted that the protocol documentation explicitly lists the autodiscover url as all lowercase, some clients actually request it as AutoDiscover/AutoDiscover.xml so if you are having problems, you should adjust your alias/rewrite rules accordingly.

Setting up Horde ActiveSync behind a Reverse Proxy Server

Since Horde ActiveSync connections are held open for a period of time up to 3540 seconds (depending on client and $conf[activesync][ping][heartbeatmax] setting, if using a proxy server you need to ensure it does not time out before the request is complete. Failure to do this will result in errors like this in your proxy server's web server log:

[Mon Jun 10 22:24:56 2013] [error] [client 101.169.127.248] (70007)The timeout specified has expired: proxy: error reading status line from remote server 192.168.1.230
[Mon Jun 10 22:24:56 2013] [error] [client 101.169.127.248] proxy: Error reading from remote server returned by /Microsoft-Server-ActiveSync

For an Apache proxy:

  ProxyPass        / https://192.168.1.230/ connectiontimeout=600 timeout=4000
  ProxyPassReverse / https://192.168.1.230/

That allows for up to 600 seconds for a connection to be established (should cover ALL possibilities) and then holds that connection open for up to 4000 seconds. This should be adjusted for you specific needs/environment.

Horde

You should make sure that the max_execution time is either set to 0 or at least twice the maximum heartbeat interval. This can be set in Horde's general configuration tab.

Application Configuration

No additional steps are normally necessary for synchronization of the supported applications. However, each application that supports synchronization also has user preferences to determine which shares will be synchronized. For example, in Kronolith the user's default calendar is always synchronized, but the user can choose to add any additional calendars he/she owns.

Multiple sources in the same collection

Prior to Horde 5.2, all non-email sources would be "multiplexed" together so they appear as a single source on the client. For example, all user calendars would appear as a single, combined calendar on the client and any new events would always be added to the user's default calendar. Starting with Horde 5.2, applications can be configured to provide all user sources as discrete sources on the client. Since not all EAS clients support this, there are a number of ways to control this.

  • By enabling/disabling the discrete sources preference per application. This, of course, affects all of a user's devices, so must be set to the lowest common denominator. If it is desired to always force the multiplexed collections, you can lock the preference. When this pref is activated, the ActiveSync library a tries to sniff out the client's capability and disables this if the client is unable to honor it.
  • By implementing the activesync_device_modify hook (see horde/config/hooks.php.dist). There is a sample hook already defined that performs some basic device sniffing to determine which collections do not support discrete sources.

Note: that all sync-able sources MUST be writable by the user.

The following chart is meant to provide a general idea of what device class supports this, not a listing of all devices and capabilities:
Device Calendars Contacts Tasks Memos Creating new sources Notes
Android
Blackberry Yes Yes Yes Yes Yes, for Tasks and Notes Creating a new Notes source from 10.3.x only
iOS Yes Yes Yes Yes, for Calendars and Tasks
Outlook Yes No Yes n/a
Windows Phone Yes

Users can also view all their paired ActiveSync devices by visiting their ActiveSync Devices preferences. This is located within Horde's Global Preferences. From here, it is possible to force a complete re-sync, or to request a remote wipe of a provisioned device (see below).

Email Support

Email synchronization has been added in Horde 5. Since in some installs this may be undesirable, it is possible to deactivate email support via Horde's configuration, on the ActiveSync tab.

ActiveSync email support requires an IMAP server. POP3 is not supported. When used in the Horde groupware stack, it will use the same server that IMP is configured to connect to. It is recommended that this server support the QRESYNC server extension for performance reasons, though it will work without this. It can also help performance if an IMAP proxy is used. Some IMAP servers like older Cyrus versions (< 2.4) might support QRESYNC but do not enable per mailbox MODSEQ by default. Enabling this on these servers will greatly improve performance.

The only flags supported by ActiveSync are the seen and flagged for follow up flags. Flag changes will be synchronized, but flag changes alone will only trigger a SYNC if per mailbox MODSEQ is supported on the server. Otherwise, the only thing that will trigger a SYNC is the arrival of a new message (technically, an increase in the NEXTUID value). Once this SYNC is triggered though, all message changes are taken into account - including any flag changes.

Since ActiveSync does not support the deleted flag, messages in a mailbox with this flag are ignored when syncing. Deleting a message will produce the following actions:

  • Deleting on the device will do one of two things; If the user has enabled a Trash mailbox then the message will be moved to that mailbox. Otherwise, the message is immediately expunged.
  • Deleting from a MUA: If the MUA is not configured to move messages to the trash, and instead just flags them as deleted, these message deletions will NOT be synched to the ActiveSync client, as there is no equivalent command in the protocol. These messages will only be removed from the ActiveSync client once expunged from the mailbox. This is in accordance with the ActiveSync protocol specs. If you wish to ensure all message deletions are synched quickly to the device, you should configure the use of a Trash folder.

Forwarding a message will always attempt to put the main message text body in-line and keep any original attachments. It seems that a number of devices cannot view message/rfc822 attachments, so any messages that have been forwarded as an attachment may not be viewable in the ActiveSync mail client.

S/MIME Support

Client S/MIME support
iOS Can sign and encrypt outgoing email and successfully validate/decrypt received email. Some issues with validating certificates on emails sent from iOS > 6.1.
Android Most clients do not support this AT ALL. Some, such as Samsung's proprietary client, can send encrypted/signed email but cannot decrypt or validate received email. The third party client Touchdown supports this well.
BlackBerry 10 Can sign and encrypt outgoing email, but has trouble validating/decrypting received and sent emails. Some issues with validating chained certificates

Autodiscover

Some devices attempt to use Exchange's Autodiscover service to make it easier for both the user to setup the account and for the administrator to make drastic changes like moving the server to a new URL. Horde attempts to support this as best it can. For this to work, you must create the URL alias as described above, and Horde must be able to figure out the Horde username based on the email address the user provided to the device. The configuration screen provides multiple options for this. In the worst case, if Horde cannot authenticate based on the provided information from the Autodiscover request, the device will fall back to requiring manual configuration. See the notes in the compatibility grid for any known information regarding device support for this feature.

ActiveSync Versions

See also: Supported ActiveSync Features.
Horde 5 adds support for ActiveSync versions 12.0 and 12.1 - the version shipped with Exchange Server 2007 and 2007sp1. This adds among other things: HTML email support, flagged for followup, more atomic policy settings, additional search sources, local wipe rules, and WBXML based provisioning (instead of the XML used in 2.5).

Horde 5.1 adds support for ActiveSync versions 14.0 and 14.1. These versions are shipped with Exchange Server 2010sp1 and 2010sp2. This allows MS Outlook synchronization (with Outlook 2013 or newer), since Outlook requires at least ActiveSync protocol version 14.0. See the Supported ActiveSync Features for the full list of features.

Administration

Administrators can view all of the ActiveSync devices paired with the server. This is the ActiveSync Devices link located under the Administration menu. From here an administrator can request a remote wipe, or force a re-provisioning of any device.

@TODO: Explain various setup configuration options and security policies (heartbeat etc...)

An explanation of the EAS security policies.

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 Horde 5, provisioning is enabled via the permissions interface. You must first add the ActiveSync permission as a child of the Horde permission. The Provisioning permission is a child of ActiveSync and all policies are children of Provisioning.

In order to enforce any security policies on a device, it must be provisioned. However, not all devices support this and some will downright refuse to work if it's enabled. There are three choices for provisioning support. None, Force, and Allow. Choosing None will disable provisioning and any enforcement of security polices or remote wipe. Force will only allow devices that are successfully provisioned to connect to the server. This means devices that don't properly support provisioning, such as some older Android versions, will simply not work. The third choice, Allow will enforce provisioning on the devices that support it, but will also allow devices that don't support it to connect to the server. Once provisioning support is added, security policies can also be added via the permissions interface.

Users can initiate a remote wipe, as well as view/manage their partnered devices in the ActiveSync user preference.

Clicking Wipe in the Horde interfaces for device management flags the server to send the wipe command to the device the next time it synchronizes. The next time the device attempts to request a command other then PING or OPTIONS, it will be wiped. The ActiveSync preference page shows the status of all the user's devices. If the status is listed as Pending, and you wish to cancel the wipe request, you may do this by clicking the Cancel Wipe button. You should see the status be reset to Provisioned. After it is wiped, the status will be shown as Wiped, if you wish to allow the device to connect to your server again, you need to explicitly remove the device as a sync partner by clicking the Remove button. If you do not remove this entry, the device will continue to be wiped each time it reconnects to the server.

What works

Contacts, Calendar, Task, Notes and Email syncing are all working. Note that not all devices support Tasks or Notes. Of the tested devices, iOS (versions < 5.0) and Android are lacking native Task applications. The TouchDown client, Moxier Mail, and Windows Mobile both support Tasks. Windows Mobile, and iOS 7+ are the only clients I've found so far that support Notes.

For the complete feature set, sorted by ActiveSync version, see Supported ActiveSync Features.

This following devices have been tested:
Device Version(s) Provisioning GAL Searching Notes Verified EAS Versions Autodiscover
Android Emulator 6.0.0 Yes, required ? Android 6.0 seems to require provisioning to be enforced on the server. Otherwise, it enters into a FOLDERSYNC loop, where it keeps resetting the sync state. There also appears to be major issues with the native ActiveSync implementation which leads to the client constantly resetting the state making it pretty much unusable. 14.1 ?
BlackBerry PlayBook 2.1.0.1088 ? ? Emails, contacts and calendars are synced, but the PlayBook often resets the sync when connecting to 2 accounts 12.1
BlackBerry 10 (Simulator) 10.1 Yes Yes Email, Contacts, Calendars, Tasks, Notes 14.1 ?
BlackBerry Z10, Q5, Q10, Z30 10.0, 10.1, 10.2, 10.2.1 Yes Yes Email, Contacts, Calendars, Tasks, Notes 14.1 Yes
Google Nexus 4 4.2, 4.3 ? ? Emails, contacts and calendars. Android 4.4.2 has broken EAS support. 14.1
Google Nexus 7 4.2, 4.3 ? ? Emails, contacts and calendars. Android 4.4.2 has broken EAS support. 14.1
HP WebOS 2.1.0 Yes ? Contacts, Calendar, Tasks are working, for SSL with a private certificate you have to trust the certificate in the browser 2.5
HTC Desire Z / HTC Desire HD 2.2 Yes Yes Contacts and Calendar via native ActiveSync, SSL ok 2.5
HTC Desire S 2.3.3 ? ? Contacts and Calendar via native ActiveSync, SSL ok 2.5
HTC Magic Android 2.2.1 unbranded ? ? Contacts, Calendars 2.5
iOS Devices (iPhone, iPad, iPod) 3.1.3 -> 4.3.5 Yes, with Bugs. Certain versions of iOS - 4.3(8F190) for one, go into a provisioning loop due to a bug in iOS (it continues to send the OLD X-Ms-Policykey value after it receives a new one). Yes Contacts, Calendar and Email 2.5, 12.1
iOS Devices (iPhone, iPad, iPod) 5.x Yes Yes Contacts, Calendar, Email, and basic support for Tasks via the Reminders App. 2.5, 12.1 Yes.
iOS Devices (iPhone, iPad, iPod) 6.0 Yes Yes Broken email push, issues with meeting invitations and responses. These have been reported fixed in 6.0.1. Major issues with recurring events and exceptions. See known issues for more info. 2.5, 12.1 Yes.
iOS Devices 7.0.x Yes Yes Contacts, Calendar, Email, Tasks, and Notes. Major issues with recurring events and exceptions. See known issues for more info. 2.5, 12.0, 12.1, 14.0, 14.1 Yes
iOS Devices 8.1.x ? ? Contacts, Calendar, Email (?), Tasks, and Notes. Major issues with recurring events and exceptions. See known issues for more info. ?,?,?,?, 14.1 Yes
Motorola Moto G Android 4.4.4 Yes Yes Mail, contacts, calendar and remote wipe work. SSL works as well. ?
Motorola Razr i XT890 Android 4.1.2 Yes Yes Mail, contacts, calendar and remote wipe work. SSL works as well. ?
Motorola Razr XT910 Android 2.3.6, 4.1.2 Yes Yes Mail, contacts, calendar data tasks and remote wipe work. SSL works as well. ?
Motorola Droid 2.0.1, 2.1, 2.2, 2.3 Broken support before 2.2, works with 2.2 and above. Native support in 2.2 and later, earlier versions can use the Corporate Directory app in the Marketplace. Contacts, Calendar and Email. On Froyo/2.2 SSL connections will NOT work with a self signed certificate even if the "Accept All Certificates" checkbox is selected. See http://www.google.com/support/forum/p/android/thread?tid=45e6836618212fdf&hl=en (A (Free) Level One certificate from http://www.startssl.com/ seems to work well here). 2.5, 12.0
Motorola Milestone 2.1, 2.2 See Motorola Droid above. See Motorola Droid above. Contacts, Calendar, and Email 2.5, 12.0
Moxier Mail 2.15.1 (Android) Yes Yes Contacts, Calendar with minimal recurrence support and Email. DOES NOT RESPECT SERVER SIDE STATE RESETS - so changing sync prefs, clearing state on server will require a manual resync on the device! 2.5, 12.0
Nine 1.5.0 Yes Yes Mail, Contacts, Calendar, Tasks and Notes. 2.5 - 14.1 Yes
Nokia E5-00 ? ? ? Contacts & calendar via RoadSync. Calendar works native client but contacts do not seem to work. 2.5
Nokia E90 MfE 3.0 ? ? Contacts verified to work. 2.5
Nokia N900 Maemo 1.3 No Yes, in the "contacts" app Emails, events, contacts and tasks work. Earlier versions of firmware are either broken, or only support ActiveSync version 12.1. Sent messages are only stored locally. The device always "pings" all folders by default on the server, it might cause higher server load with a lot of folders. You can adjust which folders to sync with the mfefolders (http://mfefolders.garage.maemo.org/) app. 2.5, 12.1
Samsung Galaxy Gio 2.3.6 Yes Yes Contacts and calendar data works. SSL works as well. 2.5
Samsung Galaxy Nexus 4.0.2 (ICS), 4.1.2, 4.2.x, 4.3.x (Jelly Bean) Yes, full support. Yes, native support via the search functionality. Calendar, Contacts, and Email works. Be sure to ENABLE email syncing. Disabling email syncing - even if enabling calendar and contacts - seems to prevent the initial folder sync required for the account to be initially set up on the phone. 2.5, 12.0, 12.1 Yes, though the device defaults to using the email address as the horde login and must be changed by the user if this is not the case.
Samsung Galaxy S2 2.3.4 ? ? GT-I9100 - Contacts and calendar data works. SSL works as well (self-signed certificates also). 2.5
Samsung Galaxy S2 4.0.3 (ICS) Yes, full support. Yes, native support via the search functionality. GT-I9100 - Calendar, Contacts and Email works. Be sure to ENABLE email syncing. Disabling email syncing - even if enabling calendar and contacts - seems to prevent the initial folder sync required for the account to be initially set up on the phone. SSL works as well (self-signed certificates also). 2.5, 12.0
Samsung Galaxy S2 4.1.2 (JB) Yes, full support. Yes, native support via the search functionality. GT-I9100 - Calendar, Tasks, Contacts and Email works. Be sure to ENABLE email syncing. Disabling email syncing - even if enabling calendar, tasks and contacts - seems to prevent the initial folder sync required for the account to be initially set up on the phone. SSL works as well (self-signed certificates also). 2.5, 12.1
Samsung Galaxy S3 LTE 4.3 Yes ? GT-I9305 - Calendar and Email works. 14.1
Samsung Galaxy Note 3 4.3 Yes Yes Calendar, Contacts, Email, Notes. 14.1
Samsung Galaxy S4 4.3 Yes Yes GT-I9505 - Calendar, Contacts, Email, Notes. 14.1
"Tasks and Notes" for Android ? ? N/A Requires Horde >= 5.1.0. Available via the Android App store: https://play.google.com/store/apps/details?id=org.myklos.inote 12.0, 12.1, 14.1 No
TouchDown for Android Version 6.5.0002 Yes Yes Contacts, Calendar (recurrence/exceptions mostly work - minor bugs still being worked out), Tasks, and Email. 2.5, 12.1
Windows 8 Mail 8.1 required (see notes) Yes Contacts, Calendar, Email. Will not work if provisioning is completely disabled. 14.1 Yes
Windows Mobile 6.1 ? ? Contacts, Email 2.5
Windows Mobile 6.5 Yes, full support. Yes Contacts, Calendar, Tasks, Email. 2.5, 12.0, 12.1
Windows Phone 7.0 Yes, with limited security policy support. Yes Contacts, Calendar, Tasks, Email 2.5, 12.0, 12.1
Windows Phone 7.5 Yes, with limited security policy support. Yes Contacts, Calendar, Tasks, Email. Some devices may require a Deleted items folder to be enabled. If error 8004010F is displayed on the device, this is the likely culprit. See http://social.msdn.microsoft.com/Forums/en/os_exchangeprotocols/thread/86e10e2d-bc4d-43dc-b6b7-f02630ff052b for more info. 2.5, 12.0, 12.1
Windows Phone 8 Yes Yes Contacts, Calendar, Tasks, Email 12.1, 14.0, 14.1 Yes

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 the 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 host.example.com. You can ignore any reference to a domain entry. If the device requires the domain entry (some Windows Mobile devices do this) you may safely enter any value.

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

Outlook Connectivity

Starting with Outlook 2013, Outlook has the ability to synchronize via Exchange ActiveSync. This requires at least version 14.0 of the EAS protocol, which Horde supports starting with Horde 5.1 (the ActiveSync library supports this starting with 2.4.0 if you are not using it with Horde). It's important to remember that connecting via ActiveSync does not provide all the same functionality of Outlook as you would get when connecting directly to an Exchange server.

If you have correctly setup your server to handle Autodiscover requests, you should be able to create the Outlook account using the basic "Email Account" screen. If you have trouble, or you don't have Autodiscover setup, you should select manual setup and then "Outlook.com or Exchange ActiveSync compatible service". Do NOT select "Microsoft Exchange Server or compatible service".

Issues/Workarounds

For some reason, Outlook 2013 doesn't use EAS to provide Free/Busy lookup, even though the version of the EAS protocol it uses supports it. If you want Outlook to be able to lookup Free/Busy information using Horde/Kronolith you need to provide it with the Free/Busy URL. Under File -> Options -> Calendar Options select the "Free/Busy Options" button. Enter Kronolith's Free/Busy URL: http://example.com/horde/kronolith/fb.php?u=%NAME%. The %NAME% string will be replaced by the user portion of the SMTP mailing address used in the meeting request.

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

First off, you should check the list of known issues to see if your problem is expected or not. You can also check the Horde bug tracker to see if your issue has been reported already.

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 all else fails and you can't figure out the issue, we will be happy to try to help you work it out, but you should be able to check/provide us with the following:

  • Be sure to check the notes in the chart above for your specific device. This might be a known issue, or a workaround may be known.
  • 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 see the affected device's state records in the database.

Using tshark (command line wireshark) to obtain a network capture

If you want to sniff the traffic on your server, and wireshark is not available becuase there is no windowing system, you can use the tshark application instead. The following command will capture http traffic on port 80, and will ignore most requests we are not interested in. It's worth mentioning that for the capture to be useful, you MUST not setup SSL on the device. Depending on your user's rights, you may need to run this as sudo:

tshark 'tcp port 80 and (((ip[2:2] - ((ip[0]&0xf)<<2)) - ((tcp[12]&0xf0)>>2)) != 0)' -w /path/to/capture/file

A note to developers attempting to use wireshark/tshark over ssl connections: Some clients (like Outlook) REQUIRE a SSL connection and as such, make it more difficult to trace. Wireshark is able to dissect SSL communication if it is given the server's private RSA key. The only caveat here is that it will NOT work with so called forward-secure ciphers like Diffie-Hellman since the server's key is not enough to decode the data. If you find yourself needing to trace ActiveSync traffic over SSL connections you must make sure you configure the webserver to use a less secure cipher. Obviously you only want to do this on test systems with non-production private keys. For lighttpd, this can be done using something like:

ssl.cipher-list = "AES256-SHA AES128-SHA RC4-SHA RC4-MD5"

Debug logging on device.

On Android devices, it is possible to enable debug level logging of the ActiveSync conversation as well:

To reach the Debug logging screen:
pre-Honeycomb: Go to the Account screen in the Email application and type debug.
Honeycomb (tablet): Go to the Account Settings screen using the action bar, then tap Email Preferences repeatedly until Debug appears in the account list. Tap Debug.
All phones: From the dialer, dial *#*#36245#*#* (the numbers correspond to EMAIL)
All devices: Go to the account creation screen (method differs depending on OS version) and enter d@d.d for email address and debug for password.
All devices (adb): $ adb shell am broadcast -a android.provider.Telephony.SECRET_CODE android_secret_code://36245

Here's what the checkboxes mean:

  • "Enable extra debug logging" - If checked, this turns on basic logging (no passwords or other content is logged); most useful for debugging crashes.
  • "Enable sensitive information debugging" - If checked, this causes POP/IMAP passwords to be logged. Exchange passwords are NEVER logged.
  • "Enable Exchange parser logging" - If checked, logs a great deal of the CONTENT of mail, contacts, and calendar entries (excluding the text of emails other than perhaps the first line). This information helpful for debugging things like missing folders, missing calendar entries, etc.
  • "Enable Exchange SD card logging" - If checked, puts all of the Exchange related logging onto SD card in a file named emaillog.txt. This file grows continuously until deleted (or the checkbox is unchecked). This can be helpful in finding issues that are sporadic, as the log is essentially unlimited in size.

Roadmap

Horde 5.1

Feature Status
EAS 14(.1) support. Complete.
Improved device management via hooks. Complete.
Support for SOFTDELETE Complete.

Horde 5.2

Feature Status
Improved email identity support. Complete.
Support for multiple sources per collection. E.g., Multiple calendars, addressbooks etc... Complete.
Improved device management GUI. Complete.

Horde 6.0

Feature Status
Ability for admin to toggle sync log on/off per device from GUI and view via GUI. Planned
CLI admin tool. If sponsored.
SMS Synchronization - probably via a small separate app. Planned, but sponsoring would hasten.
EAS 16.0 support in applications. In progress.

EAS 16.0 support is being added to the ActiveSync library prior to Horde 6, but in order to make full use of any new features in the Horde Groupware stack, Horde 6 will be required. See the EAS 16.0 page for progress and further information.

Horde_ActiveSync vs. Z-Push

The protocol handling in Horde_ActiveSync was based on Z-Push. The code that handles the protocol level is essentially the same, though it has been heavily refactored and cleaned.

Z-Push comes out of the box with a number of backends. The only one that is really fully functional is the "ICS" backend which connects to a Zarafa server. In addition to the ICS backend, Z-Push also provides a number of other backends - all of which extend what they call the "Diff" backend.

The diff backend is a very inefficient way of determining what needs to be synched. It uses file based storage - depending on the Z-Push version it uses either a single file or a directory of files for each device. These files contain, along with some basic device state information, a list of every UID that is on the device.

To determine what has changed, Z-Push essentially polls whatever storage backend e.g., the IMAP server, every $timeout seconds to get the full list of message IDs on the server. It then iterates over all the UIDs that are known to be on the device and stats every single one of these UIDs against the server to get the modification time, flags etc.

Like mentioned above, a number of backends are based on this Diff backend. Out of the box, if you are not using a Zarafa server you have the following options:

  • An IMAP backend - obviously only for syncing emails. This uses the PHP IMAP functions for fetching the complete list of message IDs and stating each and every UID - on each and every PING loop - by default something like every 10 seconds or so.
  • A vCard backend that syncs contacts against a directory of vCards on the server.
  • A Kolab backend - I'm not sure how complete this is, but this may be the backend that's used by Kolab's ActiveSync support.
  • A Maildir backend that - from what I can tell - syncs email by using filesystem based commands instead of going through an IMAP server.
  • A SearchLdap backend that - from what I can tell - is used as a Global Address Book source for searching for individual contacts (not for syncing the entire address book).

As of the time Horde_ActiveSync was written, you could only use one backend at a time - so, unless you were using Zarafa (or maybe Kolab) you could sync email or contacts. Since then they have started a "combined" backend that is supposed to wrap any number of backends. Last I checked it wasn't complete yet.

The main differences between 1.5.x and 2 are the versions of EAS that are supported. 1.5.x supports only up to Exchange 2003sp1 (same as Horde 4). Version 2 is supposedly going to support up to EAS 14 (Exchange 2010) - though I believe only up to 12.1 (Exchange 2007) is working...and I don't believe that is even fully functional.

The main differences

Some of these are specific to using Horde data as a backend to Horde_ActiveSync:

  1. Modularity. Separate classes for maintaining device state and for obtaining message diffs. If not using Horde as a backend, all that is needed is to write a new class that extends Horde_ActiveSync_Driver_Base. This allows the backend, itself, to determine the best way to calculate diffs...like using Horde's History system. In Z-Push, diff generation and state management are tightly coupled.
  2. Efficiency. The history based diff engine is orders of magnitude more efficient than Z-Push's file based diff backend.
  3. Unless using Zarafa, Z-Push contained no message-specific logic. For example, no code for dealing with appointment related issues such as timezones, recurrence series etc. Horde_ActiveSync contains support for these things out of the box.
  4. Horde's ActiveSync library supports a larger set of available EAS security policies.
  5. At least at the time of writing, Horde allowed better configuration of things such as heartbeat/timeout intervals. We also actually allow configuring available security policies. Z-Push had basic support for provisioning and for turning on or off the requirement for a device PIN - but contained no facility for configuring any of the other options without editing code. Also, if using Horde_ActiveSync as part of a typical Horde install you get all the ease of configuration that our administration interface provides.
  6. I don't have hard data on device compatibility as it compares to Z-Push, but I do know that we have fixed some device specific issues in the past that - at least at the time of this writing - were not working with Z-Push. Certain Nokia devices come to mind that use MfE. Z-Push lists these as "unknown" compatibility but they work, at least for contacts/calendar with Horde. Remote wiping iOS devices is also problematic in Z-Push.
  7. Email sync with Horde_ActiveSync uses the vastly more efficient Horde_Imap_Client library and takes full advantage of IMAP servers with QRESYNC capabilities. Z-Push uses the very poor performing c-client PHP extension.
  8. Horde's email support is more complete than Z-Push's IMAP based implementation - with support for version 12.0 style email store searching, follow-up flag synchronization, reply,forward history synchronization, S/Mime signatures and encryption, and more.
  9. Horde_ActiveSync currently supports almost the full feature set up to Exchange 2010sp2 - Z-Push 2 works with Exchange 2007 has code in development that works to some extent with 2010.
  10. Horde_ActiveSync supports multiple users per device - when the device supports it. AFAIK, Z-Push only supports a single user account per device.

Resources

Other implementations

http://z-push.sourceforge.net
https://developer.berlios.de/project/showfiles.php?group_id=8963
http://www.tine20.org/wiki/index.php/Developers/Getting_Started/Working_with_GIT
http://code.google.com/p/libeas/

Documentation

http://www.scribd.com/doc/6601589/W11-Server-Active-Sync
http://en.wikipedia.org/wiki/Exchange_ActiveSync - Good description of differences between AS versions.
http://paulrobichaux.wordpress.com/2011/08/09/advice-to-exchange-activesync-developers/
http://blogs.msdn.com/b/exchangedev/
http://msdn.microsoft.com/en-us/library/dn144954%28v=exchg.140%29.aspx

Clients

TouchDown
Nine - currently the best third party client available for Android, in my opinion.

Outlook 2013

Some links to articles describing issues with OL2013
Undocumented Codepage

Android:

http://developer.android.com/sdk/index.html
https://android.googlesource.com/platform/packages/apps/Email/
https://android.googlesource.com/platform/packages/apps/Exchange/
https://android.googlesource.com/platform/packages/apps/Calendar/

iOS

Enterprise Deployment Guide.
iPhone configuration utility.

Windows Mobile (very old, probably of little value):

Cellular Network Emulator
Device Images
Setup

BlackBerry simulators:

Blackberry simulators