The Perfect Push Mail Server - Debian Squeeze (Debian 6.0) With ISPConfig 3 & Z-push

Version 1.0
Author: Zicguy

This tutorial describes the installation and configuration of Z-push on a Debian Squeeze server with ISPConfig 3. Z-push is an open-source application to synchronize ActiveSync compatible PDAs and mobile phones. Z-Push was initially developed by Zarafa Deutschland GmbH (Germany). At the end of this tutorial, your customers should be able to sync their mobile phones, by using push technology, with their e-mail accounts stored on your server.

I do not issue any guarantee that this will work for you!

1 Requirements

In order to make Z-push working, you will need the following:

a fully working Debian Squeeze server with ISPConfig 3,
Apache 2, Php 5 and Dovecot (using the IMAP protocol) installed and working on your server,
a mobile phone (I used a 3GS iPhone for this tutorial).

2 Preliminary Note

In this tutorial, I use the hostname example.com as the main domain of the server. I also use the e-mail domain toto.com as a customer domain stored on the server. These settings might differ for you, so you have to replace them when it's appropriate.

3 Required package

To make Z-push working, your server must have the php-soap package. So, we install it:

apt-get install php-soap

4 Z-push installation

We can get Z-push by downloading it from zarafa-deutschland.de. Of course, you can replace the tar.gz file by the last stable version. For information, the new 2.0.6 version allows managing HTML e-mails with Z-push.
As usual, we download it in the /tmp folder :

cd /tmp
wget zarafa-deutschland.de/z-push-download/final/2.0/z-push-2.0.6-1616.tar.gz
tar -xzvf z-push-2.0.6-1616.tar.gz
mkdir -p /usr/share/z-push
cp -R z-push-2.0.6-1616/* /usr/share/z-push
rm -rf z-push*

Now, Z-push is installed on your server in /usr/share/z-push.

5 Z-push configuration

Z-push needs two more directories to work: /var/lib/z-push and /var/log/z-push. So, we create them and we modify owners and rights:

mkdir -p /var/lib/z-push
mkdir -p /var/log/z-push
chown www-data:www-data /var/lib/z-push
chown www-data:www-data /var/log/z-push
chmod 750 /var/lib/z-push
chmod 750 /var/log/z-push

Then, we have to modify the /usr/share/z-push/config.php file to feet to our needs:

vi /usr/share/z-push/config.php

We modify the time zone (e.g. Europe/Paris) and the backend provider (in our case BackendIMAP):

[...]
define('TIMEZONE', 'Europe/Paris');
[...]
define('BACKEND_PROVIDER', "BackendIMAP");
[...]

6 Apache & PHP configuration

We want our customers to configure their mobile phones with their own domain. For example, a customer have an e-mail domain which is called toto.com, stored on our server. We want the customer to configure its e-mail account on its mobile phone by using toto.com. So, we create an apache.conf file in /usr/share/z-push:

vi /usr/share/z-push/apache.conf

It will look like this:

Alias /Microsoft-Server-ActiveSync /usr/share/z-push/index.php
<Directory "/usr/share/z-push/">
      Options -Indexes
      AllowOverride None
      Order allow,deny
      allow from all
</Directory>

Z-Push is an implementation of the ActiveSync protocol, that's why we have to use a such Alias.

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

If it's not, you can append these lines in the /usr/share/z-push/apache.conf, inside the Directory tag.

After that, we have to restart Apache to take changes into account:

service apache2 restart

7 Open Basedir PHP configuration

The last thing we have to do on our server is to configure the Open Basedir PHP of our main domain. We can do that by using ISPConfig.
In this tutorial, we can access ISPConfig under https://example.com:8080 and we log in with admin rights. Under ISPConfig, I have created a website which matches with example.com. So, we click on the websites tab and edit the example.com website. Then, we click on the Options tab.
In the open_basedir PHP field, append the following at the end of the line:

:/usr/share/z-push:/var/lib/z-push:/var/log/z-push

This gives access to /usr/share/z-push, /var/lib/z-push and /var/log/z-push folders to web users.

Now, all is done on our server!

8 Mobile configuration

We can now test if push protocol is working by configuring an e-mail account on a mobile. For this tutorial, I used a 3GS iPhone, but it should also works with Android, Windows or BlackBerry mobiles. To make it works, we have to configure an Exchange account.
On iPhone, we go in Settings > Mail > Add an account. Then, we choose Microsoft Exchange. First, we have to fill the e-mail address, the password and the description of the account we want to use. On the next screen, we have to fill the server field. For example, if the e-mail address is [email protected], we can use toto.com for the server field. We use the e-mail address for the username field. We can choose to use SSL protocol if it's configured on our server. Finally, we validate by clicking on OK.