Product SiteDocumentation Site

5.5. Configure Z-Push (Remote ActiveSync for Mobile Devices)

This chapter describes how to configure the Z-Push software to bridge ZCP with ActiveSync enabled PDAs and smartphones.
Z-Push is available as an open source project on Sourceforge - http://z-push.sourceforge.net
In this manual only the server part of Z-Push is discussed, please refer to our User Manual for instruction on configuring mobile devices.
Mobile phones, smartphones and PDAs can be synchronized because Z-Push emulates the ActiveSync functionality of a MS Exchange server on the server side, allowing mobiles to synchronize via over-the-air ActiveSync (AirSync). Using Z-Push most mobiles can synchronize without installing any additional software on the device.
Z-Push needs to be installed on a web server. It is highly recommended to use Apache.

5.5.1. Compatibility

Z-Push allows users with PDAs and smartphones to synchronise their email, contacts, calendar items and tasks directly from a compatible server over UMTS, GPRS, WiFi or other GSM data connections. The following devices are supported by Z-Push:
  • Windows Mobile 5, 6, 6.1 and 6.5
  • Nokia E/N-series with Mail for Exchange (M4E)
  • Nokia E-series with built in ActiveSync (Nokia Mail 2)
  • Sony Ericsson with RoadSync
  • Apple iPhone
  • Android Cupcake or Donut with third party tools like Nitrodesk Touchdown
  • Android Eclair with Contacts and Calendar synchronization or third party tools
  • other ActiveSync compatible devices
For detailed information about the devices and their compatibily status, please consult the Mobile Compatibility List at http://z-push.sourceforge.net/compatibility

5.5.2. Security

To encrypt data between the mobile devices and the server, it’s required to enable SSL support in the web server. Configuring Apache with SSL certificates is beyond the scope of this document, though many howtos can be found online.
Keep in mind that some mobile devices require an official SSL certificate and don’t work with self signed certificates.

5.5.3. Installation

Download the latest Z-Push software from http://z-push.sourceforge.net/download
To Install Z-Push, simply untar the Z-Push tar to the webroot with:
tar zxvf z-push-<version>.tar.gz -C /var/www/html
The -C option is the destination where the files need to be installed. In the following table the default webroot directories of where some distributions lets the Apache webserver search for files.
Table 5.1. Webroot directories
Distribution Default webroot
Red Hat Enterprise Linux
/var/www/html
SUSE
/srv/www/htdocs
Debian and Ubuntu
/var/www

Make sure that the ‘state’ directory is writeable for the webserver process, so either change the owner of the ‘state’ directory to the UID of the apache process, or make it world writeable:
chmod 755 /var/www/z-push/state
chown apache:apache /var/www/z-push/state
The user and group name of Apache will differ per Linux distribution. The table below shows an overview of the user and group names of the Apache process.
Table 5.2. User and groupnames per distribution
Distribution Apache username Groupname
Red Hat Enterprise Linux
apache
apache
OpenSuSE and SLES
wwwrun
www
Debian and Ubuntu
www-data
www-data

Now, Apache must be configured to redirect the URL Microsoft-Server-ActiveSync to the index.php file in the z-push directory. This can be done by adding the line to the httpd.conf file
Alias /Microsoft-Server-ActiveSync /var/www/html/z-push/index.php
Make sure that the line is added to the correct part of the Apache configuration, taking care of virtual hosts and other Apache configurations.

Important

It is not possible simply rename the Z-Push directory to Microsoft-Server-ActiveSync. This will cause Apache to send redirects to the PDA, which will definitely prevent proper synchronization.
Lastly, make sure that PHP has the following settings:
php_flag magic_quotes_gpc = off
php_flag register_globals = off
php_flag magic_quotes_runtime = off
php_flag short_open_tag = on
Set this in the php.ini or in a .htaccess file in the root directory of Z-Push. If not setup correctly, the PDA will not be able to login correctly via Z-Push.
Reload Apache to activate these changes.

5.5.4. Mobile Device Management

Users can remote wipe own mobile devices from the ZCP Webaccess without interaction of the system administrator. The Mobile Device Management (MDM) plugin can be downloaded at: http://www.zarafa.com/integrations/mobile-device-management-plugin
The system administrator can remote wipe devices from the command line using the z-push-admin tool.

5.5.5. Upgrade

Upgrading to a newer Z-Push version follows the same path as the initial installation.
When upgrading to a new minor version e.g. from Z-Push 1.4 to Z-Push 1.4.1, the existing Z-Push directory can be overwritten when extracting the archive. When installing a new major version it is recommended to extract the tarball to another directory and to copy the state from the existing installation.

Important

It is crucial to always keep the data of the state directory in order to ensure data consistency on already synchronized mobiles.
Without the state information mobile devices, which already have an ActiveSync profile, will receive duplicate items or the synchronization will break completely.
Please also observe the published release notes of the new Z-Push version. For some releases it is necessary to e.g. resynchronize the mobile.

5.5.6. Troubleshooting

General configuration
Most of the difficulties are caused by incorrect Apache settings. The Apache setup can be tested using a webbrowser like Firefox pointing it to:
http://<server>/Microsoft-Server-ActiveSync
If correctly configured, a window requesting username/password should be displayed. Authenticating using valid credentials should display Z-Push information page, containing the following message:
A Z-Push information page should be displayed, containing the message:
*GET not supported*
This is the z-push location and can only be accessed by Microsoft ActiveSync-capable devices.
Verify the PHP and/or Apache configuration if an error is displayed.
Synchronization problems
If synchronization problems are encountered, a debug.txt file has to be created in the root directory of Z-Push. This file should be writeable by the Apache server process.
touch /var/www/z-push/debug.txt
chmod 777 /var/www/z-push/debug.txt
The debug.txt file will collect debug information about the synchronisation.
To obtain a complete synchronization log the file wbxml.php has to be edited and the parameter WBXML_DEBUG set to true:
define('WBXML_DEBUG', true);

Important

The debug.txt logfile contains sensible data and should be protected so it can not be downloaded from the internet.
To protect the debug.txt logfile, a .htaccess has to be created in the z-push root directory, containing:
<Files debug.txt>
 Deny from All
</Files>
Log messages
  • Repeatedly “Command denied: Retry after sending a PROVISIONING command”:
Most probably the mobile device does not support provisioning. The LOOSE_PROVISIONING parameter should be enabled in the configuration. If the messages continues, the ActiveSync profile should be reconfigured on the device. If this does not help, the PROVISIONING could be disabled completely in the config file (applies to all devices!). More information can be found at: http://www.zarafa.com/wiki/index.php/Z-Push_Provisioning
  • Exceptions for Meeting requests cause duplicates if accepted on the mobile:
Please update to Z-Push 1.4 or later. In order to fix existing duplicates, the ActiveSync profile on the mobile has to be recreated or at least the calendar has to be resynchronized completely (disabling calendarsync and enabling it afterwards).