Z-Push v2 with Zimbra

From vwiki
Jump to navigation Jump to search

The procedure below should get you up and running so that you can sync your mobile device to your Zimbra server, using the Active-Sync protocol, provided by Z-Push.

It doesn't include setting up provisioning, which is the Active-Sync feature that enhances security by providing a mechanism to remote wipe your devices, enforce storage encryption etc. Buried in the Zimbra forum thread are instructions on how to set it up - Z-Push Zimbra Backend (Push Email, Contacts, Appointments & Tasks) - Zimbra :: Forums.

Do not attempt to install 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.

{{#widget:Widget:GoogleAdSenseSkyscraper}} Z-Push is essentially a website. Mobile devices access the site in order to be able to sync with your Zimbra server. Therefore, you need a publicly accessible server that can host the site, and a DNS record that points to it (that client mobile devices will need to be able to resolve)

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.

If you are upgrading from Z-Push v1 its recommended that you start from scratch; move your old installation to a different folder (eg mv /var/ww/z-push /var/www/z-push-v1), then install v2 to /var/ww/z-push. Client devices shouldn't need to have their accounts re-added/re-sync'ed following the new install as Z-Push should manage this anyway. However I found that this doesn't always work properly and have ended up needing to re-add accounts to some mobile devices.

Set-up

See the following sections for Apache configuration...

You are advised to read the INSTALL file that comes with the Zimbra backend before you attempt the install. Don't just blindly follow the steps below, they should work but are intended to provide additional support and not to replace any of the documentation supplied by Z-Push or the Zimbra Backend's authors. You may miss a critical dependency or alteration required for your environment.

  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 latest Z-Push version (see http://zarafa-deutschland.de/z-push-download/final/) to a temp folder and unpack
  4. Move the contents to your webserver folder
    • EG mv z-push-2.0.6-1616/* /var/www/z-push/
  5. Create folders for state (/var/lib/z-push) and log data (/var/log/z-push) and make writeable by the webserver (can be altered in config.php file)
    • mkdir /var/lib/z-push
    • mkdir /var/log/z-push
    • EG chgrp www-data /var/lib/z-push
    • EG chmod g+w /var/lib/z-push
    • EG chgrp www-data /var/log/z-push
    • EG chmod g+w /var/log/z-push
  6. Download the Zimbra Z-Push backend into a /zimbra folder under the backend folder
  7. Update the Z-Push config.php file as required (see example below - Z-Push Config)

Additional steps

Some additional steps are sometimes required due to bugs etc, see the INSTALL file included with the backend for more info.

  • If running Zimbra backend 59 onwards fix Z-Push's RowCmp() function
    • Within z-push/lib/default/diffbackend/diffstate.php, replace existing contents of RowCmp() with
    • return strcmp( $b["id"], $a["id"] ) ;
  • If running Zimbra 7.2 onwards and have clients with multiple devices you need to allow them to connect simultaneously, on your Zimbra server allow an appropriate number of sessions (default is 5)
    • zmlocalconfig -e zimbra_session_limit_soap=7
    • zmconfigdctl reload
  • If running Zimbra 8 onwards you need to whitelist your Z-Push server otherwise its likely to get blocked by Zimbra, on your Zimbra server allow your Z-Push server's IP address
    • EG zmprov mcf zimbraHttpThrottleSafeIPs 158.10.20.123

Testing

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 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 page showing "Z-Push - Open Source ActiveSync" which doesn't contain errors - this confirms that connectivity exists between all the required components (Apache, Z-Push, Zimbra), and that they are basically OK.

Logrotate

You should also set-up logrotate on the Z-Push logs, example below will rotate daily, keeping two weeks of logs. Create in /etc/logrotate.d, eg vi /etc/logrotate.d/z-push 

/var/log/z-push/*.log {
        daily
        missingok
        rotate 14
        compress
        delaycompress
        notifempty
}

{{#widget:Widget:GoogleAdSenseSkyscraper}}

Z-Push Config

Note that starting from Z-Push version v2.0.6, there are now seperate config files for both Z-Push and the Zimbra Backend. If you're installing an old version for some reason, see the Pre Z-Push v2.0.6 section below.

The following are excerpts from the config files that need to be edited or should be considered by you. Update the existing files provided with the software as per your requirements.

Z-Push Config Example

EG /var/www/z-push/config.php 

// Update existing fields in config
define('TIMEZONE', 'Europe/London"');
define('PROVISIONING', false);
$BACKEND_PROVIDER = "BackendZimbra";

Zimbra Backend Config

EG /var/www/z-push//backend/zimbra/config.php The below is just an example, see the INSTALL file that comes with the Zimbra backend to work out the correct settings for your environment. 

define('ZIMBRA_URL', 'https://mail.domain.com');
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);

define('ZIMBRA_ENFORCE_VALID_EMAIL', true);

define('ZIMBRA_SMART_FOLDERS',false);
define('ZIMBRA_RETRIES_ON_HOST_CONNECT_ERROR',5);

define('ZIMBRA_LOCAL_CACHE', true);

define('ZIMBRA_DEBUG',false);

Pre Z-Push v2.0.6 Example

The below is just an example, see the INSTALL file that comes with the Zimbra backend to work out the correct settings for your environment. 

// Update existing fields in config
define('TIMEZONE', 'Europe/London"');
define('PROVISIONING', false);
$BACKEND_PROVIDER = "BackendZimbra";

// Add to config
define('ZIMBRA_URL', 'https://mail.domain.com');
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);
define('ZIMBRA_ENFORCE_VALID_EMAIL',true);
define('ZIMBRA_RETRIES_ON_HOST_CONNECT_ERROR',3);
define('ZIMBRA_DEBUG',true);

See http://php.net/manual/en/timezones.php for the correct name for your local timezone

Config Items

This section does not contain an exhaustive list of all configuration options, just the more common ones.

Z-Push

Item Example Value Purpose / Comments
TIMEZONE Europe/London Default timezome of server - see http://php.net/manual/en/timezones.php
STATE_DIR /var/lib/z-push/ Where sync state data gets stored
LOGFILEDIR /var/log/z-push/ Where logs get written to
LOGLEVEL LOGLEVEL_INFO Logging level - see config file for available options
LOGAUTHFAIL false Whether to log user authentication failures or not
LOGUSERLEVEL LOGLEVEL_DEVICEID Logging level for per user logging (off by default, add users to log for to array, eg $specialLogUsers = array("user@domain.com");)
PROVISIONING false Whether to enforce provisioning (ActiveSync security policies) over devices
LOOSE_PROVISIONING false Allows legacy devices that don't support provisioning to still be able to sync
SYNC_FILTERTIME_MAX SYNC_FILTERTYPE_ALL Allows you to limit the time period obver which devices can sync (see config file for available time periods). Useful for when time-outs are causing device syncs to fail. See also SYNC_MAX_ITEMS
FILEAS_ORDER SYNC_FILEAS_LASTFIRST Sets FileAs/SaveAs for contacts
SYNC_MAX_ITEMS 100 Limits the number of items sync'ed in one device request. Useful for when time-outs are causing device syncs to fail. See also SYNC_FILTERTIME_MAX
BACKEND_PROVIDER BackendZimbra Backend interconnect provider which alows Z-Push to interact Zimbra (or other) email/collaboration server

Zimbra Backend

Item Examplqe Value Purpose / Comments
ZIMBRA_URL https://mail.domain.com URL to Zimbra server (can be http or https)
ZIMBRA_USER_DIR zimbra
ZIMBRA_SYNC_CONTACT_PICTURES true Sync contact pictures to devices.
ZIMBRA_VIRTUAL_CONTACTS true
ZIMBRA_VIRTUAL_APPOINTMENTS true
ZIMBRA_VIRTUAL_TASKS true
ZIMBRA_IGNORE_EMAILED_CONTACTS true
ZIMBRA_HTML true Whether to sync email etc content as HTML, or raw/basic text
ZIMBRA_ENFORCE_VALID_EMAIL true
ZIMBRA_SMART_FOLDERS true Whether to enable Smart Folders or not (a Backend feature that allows end user control of what gets synced to their devices). Cannot be changed on the fly, all sync state data needs to be manually cleared.
ZIMBRA_RETRIES_ON_HOST_CONNECT_ERROR 5 How many times the backend should attempt to reconnect to Zimbra should connect fail (because services are down for backup, for example)
ZIMBRA_LOCAL_CACHE true
ZIMBRA_DEBUG false

Mobile Device Setup

To sync devices via Active Sync add the account details as an Microsoft Exchange or Active Sync account.

Do not select to sync SMS - the Active Sync protocol that Z-Push uses supports it, but Zimbra does not.

Retrieved from ‘http://vwiki.co.uk/index.php?title=Z-Push_v2_with_Zimbra&oldid=2648’