Z-Push with Zimbra and HTML Support

All the information for the procedure below was gleamed from Z-Push Zimbra Backend (Push Email, Contacts, Appointments & Tasks) - Zimbra :: Forums. Its a mammoth thread, but you can search just that thread to find what you need. If you run into problems, search it, even if there isn't an exact match you'll find some useful pointers. Failing that, you could try the Troubleshooting page on this vWiki (its not particularly developed yet) or the Z-Push Zimbra Backend Support Requests page on SourceForge.net.

Be aware that the AS 12.1 branch of Z-Push v1 (and the Zimbra backend), which this page covers, are not officially supported (but in general they seem to work well for most people).

Z-Push v2, which fully supports HTML email, has now been released. See Z-Push v2 with Zimbra for install instructions.

Procedure

This procedure should get you up and running so you can sync your mobile device to your Zimbra server using Active-Sync, complete with proper HTML emails.

It doesn't include setting up provisioning, which is the AS feature that enhances security by providing a mechanism to remote wipe your devices, enforce storage encryption etc. See the forum thread above if you want to know how to set it up.

It's not recommended that you try to run Z-Push on the same server as Zimbra.

It is possible, but will require you to hack your Zimbra installation, and performing a Zimbra upgrade will probably break Z-Push. If you must do it, then your best bet is to install on separate server first. Then, once you know you've got a working installation, try to get Z-Push running on your Zimbra server.

The following procedure assumes that you have a web-server that's accessible from the internet. Mine is an Apache2 webserver, running on Ubuntu 10.04 LTS, therefore any references to commands, paths, etc, will have come from that set-up.

1. If you don't have them, install subversion and php-curl
   • apt-get install subversion php5-curl
2. Create a folder for Z-Push on your webserver
   • EG mkdir /var/www/z-push
3. Download the Z-Push Active-Sync 12.1 branch to the folder
   • EG svn checkout svn://svn.berlios.de/z-push/branches/as12.1 /var/www/z-push
4. Download the Zimbra Active-Sync 12.1 backend branch into a /zimbra folder
   • EG mkdir /var/www/z-push/zimbra
   • EG svn checkout https://zimbrabackend.svn.sourceforge.net/svnroot/zimbrabackend/zimbra-backend/branches/as12.1 /var/www/z-push/zimbra
5. Move unrequired files out of backend, leaving only backend.php and diffbackend.php
   • EG mkdir /var/www/z-push/backend-old
   • EG mv /var/www/z-push/backend/* /var/www/z-push/backend-old
   • EG mv /var/www/z-push/backend-old/backend.php /var/www/z-push/backend/
   • EG mv /var/www/z-push/backend-old/diffbackend.php /var/www/z-push/backend/
6. Move the zimbra.php file into backend
   • EG mv /var/www/z-push/zimbra/zimbra.php /var/www/z-push/backend/
7. Allow write access to the state folder
   • EG chgrp www-data /var/www/z-push/state
   • EG chmod g+w /var/www/z-push/state
8. Create file for debug to go to
   • EG touch /var/www/z-push/debug.txt
   • EG chmod 777 /var/www/z-push/debug.txt
9. Update the config.php file as required (see example below - Z-Push Config)
10. Create an Apache2 config file for the Active-Sync website (see below for example normal and SSL configs), and enable
    • EG vi /etc/apache2/sites-available/z-push
    • EG cd /etc/apache2/sites-enabled
    • EG ln -s ../sites-available/z-push z-push
    • service apache2 restart

In theory, it should be working now, in order to test...

1. Browse to your server, eg http://as.domain.com/Microsoft-Server-ActiveSync
   • You should be prompted for a username and password (for an account on your Zimbra server)
   • If not, Apache has failed to deliver the prompt to you. Check the webserver log, either your website isn't configured correctly or Z-Push experienced a PHP error.
2. Enter a valid Zimbra user/pass
   • You should get a "GET not supported" page - this confirms that connectivity exists between all the required components (Apache, Z-Push, Zimbra), and that they are basically OK.

In case of problems check your Apache error log, and the z-push debug logs. Fix any Apache errors 1st.

If you think there might be an error in the procedure or similar query, pls feel free to post a comment on my blog post of setting up Z-Push with Zimbra - [1].

Z-Push Config

# Update the following existing config lines
date_default_timezone_set("Europe/London");                # Or use whatever Unix style time-zone that's appropriate for you
define('PROVISIONING', false);
$BACKEND_PROVIDER = "BackendZimbra";

# Add the following config lines
define('ZIMBRA_DEBUG',true);
define('ZIMBRA_URL', 'https://mysserveraddress.com');      # Update with you Zimbra server hostname
define('ZIMBRA_USER_DIR', 'zimbra');
define('ZIMBRA_SYNC_CONTACT_PICTURES', true);
define('ZIMBRA_VIRTUAL_CONTACTS',true);
define('ZIMBRA_VIRTUAL_APPOINTMENTS',true);
define('ZIMBRA_VIRTUAL_TASKS',true);
define('ZIMBRA_IGNORE_EMAILED_CONTACTS',true);
define('ZIMBRA_HTML',true);

Apache Config (Normal)

Update as required, at minimum you'll need to change the hostname to whatever your web server is (the ServerAdmin and ServerName parameters).

 <VirtualHost *:80>
        ServerAdmin info@as.domain.com
        ServerName  as.domain.com
 
        # Indexes + Directory Root.
        DirectoryIndex index.php
        DocumentRoot /var/www/z-push/
        Alias /Microsoft-Server-ActiveSync /var/www/z-push/index.php
 
        <Directory />
                AllowOverride All
        </Directory>
 
	php_flag magic_quotes_gpc off
	php_flag register_globals off
	php_flag magic_quotes_runtime off
	php_flag short_open_tag on
 
        # Logfiles
        ErrorLog  /var/log/apache2/z-push/error.log
        CustomLog /var/log/apache2/z-push/access.log combined

 </VirtualHost>

Apache Config (SSL)

Update as required, at minimum you'll need to change the hostname to whatever your server has, and update the paths to your keys/certificates, so the following parameters...

• ServerAdmin
• ServerName
• SSLCertificateFile
• SSLCertificateKeyFile
• SSLCertificateChainFile
• SSLCACertificateFile

For more info on setting up a secure website see Secure Website.

<IfModule mod_ssl.c>
 <VirtualHost _default_:443>
        ServerAdmin info@as.domain.com
        ServerName  as.domain.com
 
        # Indexes + Directory Root.
        DirectoryIndex index.php
        DocumentRoot /var/www/z-push/
        Alias /Microsoft-Server-ActiveSync /var/www/z-push/index.php
 
        <Directory />
               AllowOverride None
        </Directory>
 
        php_flag magic_quotes_gpc off
        php_flag register_globals off
        php_flag magic_quotes_runtime off
        php_flag short_open_tag on
 
        # Logfiles
        ErrorLog  /var/log/apache2/z-push/error.log
        CustomLog /var/log/apache2/z-push/access.log combined
 
        #   SSL Engine Switch:
        #   Enable/Disable SSL for this virtual host.
        SSLEngine on
 
        #   Server Certificate:
        SSLCertificateFile /etc/apache2/ssl/web.crt
 
        #   Server Private Key:
        SSLCertificateKeyFile /etc/apache2/ssl/server.key
 
        #   Server Certificate Chain:
        SSLCertificateChainFile /etc/apache2/ssl/ca.crt
 
        #   Certificate Authority (CA):
        SSLCACertificateFile /etc/apache2/ssl/ca.crt
 
 </VirtualHost>
</IfModule>

Android Account Set-Up

1. In the Set up email screen
   • Enter your account email address and password and select Manual setup
2. Add email account screen
   • Select Microsoft Exchange ActiveSync
3. Exchange server settings screen
   • Enter your server hostname in Exchange server
   • Untick Use secure connection (SSL) if your Z-Push site is not secure (it should be!)
   • Tick Accept all SSL certificates if your Z-Push site doesn't use certificates verifiable with an internet trusted CA (eg they're self-signed)
4. Account options screen (your device will attempt to connect to your server and if successful will present these options)
   • Untick Sync SMS
     • Do not enable SMS sync (ever! - if you do/have, delete the account from your device and start again)
   • Leave Emails retrieval size as is, otherwise you can set what you like