Issuu on Google+

Z-Push configuration manual

Z-Push configuration manual

Zarafa is a workgroup sharing solution based on the look-and-feel of Microsoft Outlook, which enables sharing of mail and appointments from Outlook and a web based interface. This document describes how to install and configure the Z-Push software to synchronize PDA's and Smartphones with Zarafa. Z-Push is available as an opensource project on Sourceforge.

Introduction The Z-Push software allows users with PDA's and Smartphones to synchronize their email, contacts, calendar items and tasks directly with a Zarafa server over UMTS, GPRS, WiFi or GSM data connections. The following devices are native supported by Z-Push: ●

PocketPc 2002 and 2003

Windows Mobile 5 and 6

Nokia E-series

Sony Ericsson P990, W950 and M600

All other ActiveSync compatible devices

The devices can be synchronised because the Z-Push module emulates an MS Exchange server on the server side, allowing users to synchronize without installing specialized synchronisation software on their devices.

Security You can use the SSL feature of the PDA only when you have setup SSL on your server and your server has an acceptable certificate. This means that you either need an official SSL certificate from a commercial certificate authority, or you need to install the certificate on your PDA. Installing SSL certificates is beyond the scope of this document, but many HOWTO's can be found on the internet.

Installation Download the latest Z-Push software on the following website: To Install Z-Push, simply untar the Z-Push tar to your webroot, e.g. with tar zxvf z-push-<version>.tgz -C /var/www

p. 1

Z-Push configuration manual The -C option is the destination where the files need to be installed. In the following overview you'll see the default webroot directories of where your distribution lets the Apache webserver search for files.


Default webroot



RedHat and clones (eg Fedora, CentOS)


Debian and Ubuntu


This documents continues the the /var/www directory as example.Now, edit the config.php file in the directory to reflect your local system. For MAPI use with Zarafa, you needn't change any settings and should work as-is. Make sure that the 'state' directory is writeable for your webserver process, so either change the owner of the 'state' directory to the UID of your apache process, or make the directory world writeable: chmod 777 /var/www/z-push/state

You can also relax the permisions a bit, and correct the user and/or group of the directory, so only Apache can write in the directory: chmod 755 /var/www/z-push/state chown www-data.www-data /var/www/z-push/state

The user and group name of Apache will differ per Linux distribution. Below you will find a table with an overview of the correct username and groupname for Apache: Distribution

Apache username





RedHat and clones (eg Fedora, CentOS)



Debian and Ubuntu



Now, you must configure Apache 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: Alias /Microsoft-Server-ActiveSync /var/www/z-push/index.php

to your httpd.conf file. Make sure that you are adding the line to the correct part of your Apache configuration, taking care of virtual hosts and other Apache configurations. *WARNING* You CANNOT simply rename the Z-Push directory to Microsoft-Server-ActiveSync. This will cause Apache to send redirects to the PDA, which will definitely break your PDA synchronisation. p. 2

Z-Push configuration manual Lastly, make sure that PHP has the following settings: php_flag php_flag php_flag php_flag

magic_quotes_gpc off register_globals off magic_quotes_runtime off short_open_tag on

You can set this in the httpd.conf, in php.ini or in an .htaccess file in the root of Z-Push. If you don't set this up correctly, you will not be able to login correctly via Z-Push. After doing this, you should be able to synchronize from your PDA

Setting up your PocketPC This is simply a case of adding an 'exchange server' to your activesync server list, specifying the IP address of the Z-Push apache server, disabling SSL, unless you have already setup SSL on your Apache server, setting the correct username & password (the domain is ignored, you can simply specify 'domain' or some other random string), and then going through the standard activesync settings. Once you have done this, you should be able to synchronise your PocketPC simply by clicking the 'Sync' button in ActiveSync on your PocketPC. In steps: 1. Open ActiveSync and select 'set up your device to sync with it'

2. Type your server address (without http or other URL parts) 3. Specify your username and password, you must specify a domain but it is not used within

p. 3

Z-Push configuration manual

Z-Push, so you can specify simply 'domain' or some other random text. Select 'save password' if you wish to automatically sync.

4. Select which items you wish to synchronize

p. 4

Z-Push configuration manual

5. Press 'Finish' You can now synchronize your PDA by pressing 'Sync'

Troubleshooting Most problems will be caused by incorrect Apache settings. To test whether your Apache setup is working correctly, you can simply type the AirSync URL in your browser, to see if apache is correctly redirecting your request to Z-Push. You can simply use: http://<serverip>/Microsoft-Server-ActiveSync

If correctly configured, you should see a username/password request, and when you specify a valid username & password, you should see a string like "Your device requested the AirSync URL without the required GET parameters" If not, then check your PHP and Apache settings. If you have other synchronisation problems, you can create the file 'debug.txt' in the root directory of Z-Push, which should also be world-writable: touch /var/www/z-push/debug.txt chmod 777 /var/www/z-push/debug.txt

The debug.txt file will then collect debug information from your synchronisation.

p. 5

Z-Push configuration manual

Using Z-Push via SSL To synchronise your PDA or Smartphone remote via SSL, you will need SSL support on your Apache webserver. By default the PDA only support SSL certificates that are signed by the following Certified Authorities (CA): • VeriSign • Cybertrust • Thawte • Entrust • GlobalSign • Equifax To buy an official certificate from one of these vendors cost around between 200 and 2000 euro. You can also get a free certificate at With Cacert certificates you still need to install the CA certificate on the PDA. If the server certificate doesn't match with the server name or the CA certificate isn't installed, the remote synchronisation cannot be established.

Generate official SSL certificate To get an official SSL certificate you first need to create Certificate Signing Requests (CSR). To generate a CSR file, you will first need to create private RSA key. This private key should be kept absolutely personal. openssl genrsa -out host.key 1024 chmod 400 host.key openssl req -new -nodes -key host.key -out host.csr

When prompted for the x509 Common Name attribute information, enter the fully qualified hostname the certificate will be used on. The e-mail address will likely be used by the CA to contact you. Leave any subsequent attributes blank, unless the CA requests something be set in them. The csr file must be submitted to a CA. The CA will finally return the certificate. Save the certificate in the file host.crt. To see how you can enable your SSL certificate in your Apache, please see “Configure Apache with SSL”

p. 6

Z-Push configuration manual

Generate a self-signed certificate To create a self signed certificate you first need to setup your own CA by the following commands: openssl genrsa -des3 -out ca.key 4096 openssl req -new -x509 -days 365 -key ca.key -out ca.crt

After your CA is ready, you need to create a Certificate Signing Requests (CSR). openssl genrsa -out host.key 1024 chmod 400 host.key

openssl req -new -nodes -key host.key -out host.csr

When prompted for the x509 Common Name attribute information, enter the fully qualified hostname the certificate will be used on. Now you have to certify your CSR file by your own CA. openssl x509 -req -days 365 -in host.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out host.crt To add the generated certificate and the private key to your Apache webserver, see the following chapter.

Configure Apache with SSL To use the certificate in your Apache webserver, make sure the mod_ssl package is installed and loaded. Depending on your distribution the default Apache SSL configuration settings are available in a different file. See the list below for your distribution: Redhat: /etc/httpd/conf.d/ssl.conf Debian: /etc/apache2/ssl.conf Suse: /etc apache2/vhosts.d/ssl-server.conf To load your new certificate, change the following options in the ssl configuration file: SSLCertificateFile host.crt SSLCertificateKeyFile host.key If you have a self signed certificate, please add also the following option to the ssl configuration file: SSLCACertificateFile /root/ssl/ca.crt p. 7

Z-Push configuration manual

Configure PDA for SSL In Windows Mobile-based PDA's you also need to add the CA Certificate to the Trusted Root Certificates store if you don't have a certificate of one of the Certified Authorities describe in the first chapter. The certificates should be in DER format to install it on the PDA. By default the generated SSL certificates on Linux are in PEM format. The DER certificate is a base64 encoded PEM certificate. You can convert the certificate type by the following commands: openssl x509 -in ca.crt -inform PEM -out ca.cer -outform DER openssl x509 -in host.crt -inform PEM -out host.cer -outform DER

After converting both certificates you need to copy them to the PDA. By selecting the certificates on your PDA they will be stored in the Trusted Root Certificates store of your PDA. The PDA is now ready to use Activesync via SSL.

References •

Z-push website

Setup “Mail for Exchange” to synchronize your Nokia phone

Openssl manuals:

Microsoft tool to disable certificate verification: FamilyId=D88753B8-8B3A-4F1D-8E94-530A67614DF1&displaylang=en

Manual how to add a root certificate to your PDA

p. 8

Test For Bidib