Troubleshooting (Z-Push)

This is by no means an exhaustive guide to troubleshooting Zimbra Z-Push, I manage a very modest installation, which, as a result will not turn up a huge range of problems to investigate.

The Basics

If things aren't behaving as expected, you need to identify which component is experiencing the problem...

• Mobile device
  • Instigates connection to Z-Push, the client
• Webserver (eg Apache)
  • Provides network services for Z-Push
• Z-Push
  • Provides ActiveSync to mobile device, the front-end
• Zimbra backend
  • Provides interface between Z-Push and Zimbra
• Zimbra
  • Hosts account mailboxes, the server

Understanding the scope of the fault may aid in reducing the above list of components to investigate... Is it only one user? Is it all users with a particular device? Be careful if you have Android users, many manufacturers have implemented their own ActiveSync stack or modified the standard Android software (as Google's attempts have generally been poor, seemingly because they only really want you to use Gmail). As a result different flavours of Android device should not be assumed to be running the same software and exhibit the same behaviour. Is it everyone?

As with all fault finding, there is only so much prescriptive investigation that can be done - you need to understand how your system works and so be able to identify where the problem lies.

1. Browse to your server's ActiveSync URL, eg http://as.domain.com/Microsoft-Server-ActiveSync
   • If you get a blank page and nothing else, the webserver (eg Apache) is failing to deliver the page. This is most likely due to a PHP error and you'll need to look at the webserver logs.
   • You should be prompted for a username and password (for an account on your Zimbra server), in which case your webserver is working correctly
2. Enter a valid Zimbra account user/pass
   • You should get a "GET not supported" page
   • If not, then Z-Push is unable to successfully authenticate the supplied user/pass, investigate the Zimbra audit logs

Assuming the above works, then the basic configuration and interconnectivity of the components (excluding mobile devices) is working.

Tailing the Z-Push log (EG tail -f /var/www/z-push/debug.txt) whilst forcing a device to sync can be worth a try, in case there are some obvious errors to fix. If you're not seeing any activity in the Z-Push log for the device, that suggests that the device is either failing to initiate a sync, or is unable to reach the ActiveSync URL.

Logging

If possible, limit the amount of syncing that's taking place when investigating a problem in the logs. Stop any devices that you can from syncing, and especially on a specific device you're interested in, stop all syncing, and then manually force a sync for a particular data type (calendar, contacts, etc). You're ability to do this will be governed by your users, and types of devices that are syncing.

Z-Push

By default Z-Push will log to debug.txt, though this will only work if the webserver has write access. Similarly the logging cannot be turned off, so to prevent a large logfile remove write access to the file.

To reduce the amount of data the appears in the log, XML output can be turned off by editing wbxml.php...

define('WBXML_DEBUG', false);

Zimbra Backend

The Zimbra Backend does not have its own log, it writes to the Z-Push log. Logging can be enabled by setting the following entry in config.php. Having this enabled creates alot of logging, sync contents (of emails, contacts, appointments etc) can be visible.

define('ZIMBRA_DEBUG',true);

Zimbra

The following logs can be worth investigating...

Log	Notes
/opt/zimbra/log/audit.log	Security auditing log You should see access to your Zimbra server's SOAP URL from the webserver hosting Z-Push using the account that is trying to sync EG btpool0-8://mail.domain.com/service/soap
/var/log/zimbra.log	Zimbra mail log You should see any in/outgoing email being logged.

Reset Device Synchronisation

If a particular mobile device is experiencing sync issues, it can be useful to force it to start afresh.

1. Identify the device's Mobile Device ID
   1. Search the debug.txt file for devid and a username used by the device to connect
      • EG egrep -w 'devid|username' debug.txt , where username is substituted appropriately
      • Example log line: ... Statemachine _devid initialized with samsung1234510043207510 for user username
   • It can probably be found on the device as well, eg on Android this can be seen when adding a new Microsoft Exchange ActiveSynce account
2. Delete all accounts from the device that access Z-Push
3. Delete the state data for the device
   1. EG rm -fr state/samsung1234510043207510/
4. Recreate the accounts on the device
   • Remember not to sync SMS