Z-Push with Zimbra and HTML Support

Z-Push is an open source Active Sync solution, primarily designed to work with Zarafa, it will work must email solutions directly (via IMAP), and can also use 3rd party interfaces (known by Z-Push as backends) in order to access email data. Obviously Active Sync is about more than just email, and Z-Push aims to sync all those other data types (contacts, calendar, tasks etc).

Z-Push v1 wasn't intended to support emails with HTML content, that's expected in v2 (currently in beta), however there is an Active Sync 12.1 branch of Z-Push v1 that can be used (officially its not of a production standard, but it does work very well, so well some have commented that its better than the inbuilt AS support available in Zimbra Network Edition).

In order to get fuller integration between Zimbra and Z-Push requires the use of a specific Zimbra backend, which is currently written/championed by a Zimbra forum member who goes by the name of liverpoolfcfan, who deservers a lot of respect and praise for all his efforts. In order to support HTML email a special version of the backend has been written.

All the information for the procedure below was gleamed from http://www.zimbra.com/forums/mobility/26536-z-push-zimbra-backend-push-email-contacts-appointments-tasks.html, its a mammoth thread, but you can search just that thread. If you run into problems, search it, it's unlikely you've found a new problem, but in case you have, you can always post a question there.

I've also posted a version of this on my Blog, the procedure is the same, but there's some basic troubleshooting pointers at the end.

Procedure

This will 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.

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, there's a problem with your Apache config
2. Enter a valid Zimbra user/pass
   • You should get a "GET not supported" page

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

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-sync/
       Alias /Microsoft-Server-ActiveSync /var/www/z-sync/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-sync/error.log
       CustomLog /var/log/apache2/z-sync/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