Upgrade Z-Push v2 (with Zimbra Backend)

From vwiki
Jump to navigation Jump to search

It easiest to perform an upgrade by preparing the files for the website in a new folder first. Then, once you're confident all is well, switch over the old and new folders by renaming. If something doesn't work as expected its easy to fall back to the previous running version.

Whilst it shouldn't be necessary for Active-Sync clients to perform any actions prior to or after an upgrade, its worth making sure that they are syncing properly and don't have any current problems. Un-synced changes (that exist on phones etc) could get lost, and any existing problems may be exacerbated.

To check your current running versions (assuming you're logging to /var/log/z-push/z-push.log)...

  • Z-Push
    • grep "] Version=" /var/log/z-push/z-push.log
  • Zimbra backend
    • See the version indicated in <z-push dir>/backend/zimbra/Release Notes.txt
    • If you're running the backend in debug mode (eg define('ZIMBRA_DEBUG',true);) then
      • grep "Zimbra Backend version" /var/log/z-push/z-push.log

Make sure you read the release notes for the new versions of software that you are installing. You may need to make additional changes as part of the upgrade that are not covered here.


  1. Create a folder for Z-Push on your webserver
    • EG mkdir /var/www/z-push-v2.0.6
  2. Download the latest Z-Push version (see http://zarafa-deutschland.de/z-push-download/final/) to a temp folder and unpack
  3. Move the contents to your webserver folder
    • EG mv z-push-2.0.6-1616/* /var/www/z-push/z-push-v2.0.6/
  4. Download the Zimbra Z-Push backend into a /zimbra folder under the backend folder
  5. Copy across the config from your old install
    • I tend to do a diff of my existing and the new config files first, in order to detect if there are new config settings that I might be wiping out by copying across
      • EG diff /var/www/z-push/config.php /var/www/z-push-v2.0.6/config.php
    • Also note that prior to Z-Push v2.0.6, all config was in only one file (see Z-Push Config for more info), since v2.0.6 the backend config has been separated out
    • EG cp /var/www/z-push/config.php /var/www/z-push-v2.0.6/config.php
    • EG cp /var/www/z-push/backend/zimbra/config.php /var/www/z-push-v2.0.6/backend/zimbra/config.php

Go Live

  1. Move old install out of the way
    • EG mv /var/www/z-push /var/www/z-push-v2.0.5
  2. Move new install into place
    • EG mv /var/www/z-push-v2.0.6 /var/www/z-push
  3. Restart webserver
    • apache2ctl -k graceful

Ver 2.0 To Ver 2.1

As described in the release notes, when upgrading from Version 2.0 to Version 2.1 the data states are not compatible and an upgrade script needs to be run. Modified go live procedure...

  1. Move old install out of the way
    • EG mv /var/www/z-push /var/www/z-push-v2.0.7
  2. Move new install into place
    • EG mv /var/www/z-push-v2.1 /var/www/z-push
  3. Restart webserver
    • apache2ctl -k graceful
  4. Run conversion scipt
    • php /var/www/z-push/tools/migrate-2.0.x-2.1.0.php


  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.
  3. Using a mobile device test expected functionality
    • Email sending (send to yourself so you test receiving as well)
    • Create a test contact on device and check sync to server
    • Create a test contact on server and chack sync to device
    • As above for a calendar item
    • As above for a task