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.
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. It is also highly recommended to use PHP as an Apache module.
Z-Push >=2.1 requires ZCP 7.0.6 or later.
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. Among others the following devices are known to by working with Z-Push:
Apple iPhone and iPad
Windows Phone 7, 7.5 and 8
Android phones with Android 4.x and newer
Blackberry PlayBook and 10 (with ActiveSync)
other ActiveSync compatible devices
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.
To install Z-Push, simply extract the Z-Push archive to the /usr/share/z-push directory:
mkdir -p /usr/share/z-push
tar zxvf z-push-*.tar.gz -C /usr/share/z-push/ --strip-components=1
The -C option is the destination where the files need to be installed.
Z-Push is using a state directory to store a per-user synchronisation status and a log directory for its default logging. Make sure that the ‘state’ and ‘log’ directories exists and are 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:
mkdir /var/lib/z-push /var/log/z-push
chown www-data:www-data /var/lib/z-push /var/log/z-push
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
|
|
SLES
|
wwwrun
|
www
|
|
Debian and Ubuntu
|
www-data
|
www-data
|
On systems with SELinux enabled the security context of these folders might need to be changed, e.g.
chcon -R -t httpd_sys_rw_content_t /var/lib/z-push
chcon -R -t httpd_sys_rw_content_t /var/log/z-push
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 following line to the httpd.conf file:
Alias /Microsoft-Server-ActiveSync /usr/share/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.
Additional PHP Packages
To use the full featureset of Z-Push 2 and the z-push-top command line utility, additional php packages are required. These provide SOAP support, access to process control and shared memory.
Table 5.3. Additional packages per distribution
|
Distribution
|
Package name
|
|---|
|
Red Hat Enterprise Linux*
|
php-cli php-soap php-process
|
|
SLES**
|
php53 php53-soap php53-pcntl php53-sysvshm php53-sysvsem php53-posix
|
|
Debian and Ubuntu
|
php5-cli php-soap
|
It is not possible to simply rename the Z-Push directory to Microsoft-Server-ActiveSync. This will cause Apache to send redirects to the smartphone, which will 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 you have several php applications on the same system, you could specify the z-push directory so these settings are considered only there.
<Directory /usr/share/z-push>
php_flag magic_quotes_gpc off
php_flag register_globals off
php_flag magic_quotes_runtime off
php_flag short_open_tag on
</Directory>
If not setup correctly, the smartphone will not be able to login correctly via Z-Push.
Reload Apache to activate these changes.
To use the Z-Push 2.X command line tools, access the installation directory /usr/share/z-push and execute:
./z-push-top.php
and/or
./z-push-admin.php
To facilitate the access symbolic links can be created, by executing:
ln -s /usr/share/z-push/z-push-admin.php /usr/local/sbin/z-push-admin
ln -s /usr/share/z-push/z-push-top.php /usr/local/sbin/z-push-top
With these symlinks in place the cli tools can be accessed from any directory and without the .php file extension.
5.5.4. Mobile Device Management
The system administrator can remote wipe devices from the command line using the z-push-admin tool.
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.
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.
Upgrading to Z-Push 2.X from 1.X it is not necessary to copy the state directory because states are not compatible. However Z-Push 2 implements a fully automatic resynchronizing of devices in the case states are missing or faulty.
Downgrading from Z-Push 2.X to 1.X is not simple. As the states are not compatible you would have to follow the procedure for a new installation and re-create profiles on every device.
States of Z-Push 2.0 and Z-Push 2.1 are not compatible. A state migration script is available in the tools folder.
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.
Z-Push supports signing and en-/decrypting of emails on mobile devices since the version 2.0.7.
Currently only Android 4.X and higher and iOS 5 and higher devices are known to support encryption/signing of emails.
It might be possible that PHP functions require CA information in order to validate certs. Therefore the CAINFO parameter in the config.php must be configured properly.
The major part of S/MIME deployment is the PKI setup. It includes the public-private key/certificate obtaining, their management in directory service and roll-out to the mobile devices. Individual certificates can either be obtained from a local (company intern) or a public CA. There are various public CAs offering certificates: commercial ones e.g. Symantec or Comodo or community-driven e.g. CAcert.org.
Both most popular directory services Microsoft Active Directory (MS AD) and free open source solution OpenLDAP allow to save certificates. Private keys/certificates reside in user’s directory or on a smartcard. Public certificates are saved in directory. MS AD and OpenLDAP both use userCertificate attribute to save it.
In Active Directory, the public key for contacts from GAB is saved in PR_EMS_AB_TAGGED_X509_CERT (0x8C6A1102) property, and if you save a key in a contact, it is PR_USER_X509_CERTIFICATE (0x3A701102).
In LDAP public key for contacts from GAB is saved in userCertificate property. It should be mapped to 0x3A220102 in ldap.propmap.cfg (0x3A220102 = userCertificate). Make sure it looks like this in LDAP:
- userCertificate;binary
MIIFGjCCBAKgAwIBAgIQbRnqpxlPa…
It is strongly recommended to use MS AD or LDAP to manage certificates. Other user plugin options like db or unix might not work correctly and are not supported.
