Z-Push (ActiveSync)

z-push is an ActiveSync clone used to provide push notificiations for some Microsoft Email clients.

It should never be used, always choose 'imap' instead, it is much much faster and better and more reliable.

Z-Push's implementation of imap is not good, and on large email accounts it is not reliable. It gets into a 'loop' state and then bails completely in some situations. We do NOT support this protocol. Even microsoft don't support activesync anymore 🙂.

If you have no choice, then you should use this patched version which fixes some serious performance issues. Specifically it's more efficient and has some better defaults.

note: Z-Push is not actively supported, neither is ActiveSync, these are obsolete and should be avoided.

What did we fix? (cough improve)

  • Most of these faults relate to 'real' systems, with many folders, each containing thousands of messages of various sizes. On test systems these issues would not show up. On real systems it was simply broken.
  • Memory setting added to override random default on the system.
  • Memory headroom increased so it won't run out of memory when reading a single large message
  • Setting added to define the max size message that can be safely processed.
  • Messages above max size are not fetched!
  • When trying to find the list of existing messages in a folder, the original implementation would scan the headers of every message in the folder. When no headers are needed!
  • Built in 'incredibly inefficient' overview imap command replaced with efficient one that just lists flags and uid's.
  • When updating folders the original implemenation would scan every folder on the system, (and scan the headers of every message in every folder). And then repeat that step for each block of 100 messages. Now it remembers which folder it was updating.
  • Enforced more conservative timeout limits. This helps reduce the chance of multiple duplicate updates being initiated by an impatient client.
  • Actual imap 'idle' command implemented so it can detect new messages in the INBOX efficiently.
  • While updating once a limit is reached the next update of all folders will continue at the one it was on rather than scanning all other folders 'again' first 🙂
  • We added the following php library to handle imap more efficiently: https://github.com/petewarden/handmadeimap

How to install over an existing z-push installation

wget https://github.com/chrispugmire/Z-Push/archive/refs/heads/develop.zip
unzip develop.zip
cd Z-Push

php install.php

How to install this version of z-push from scratch

mkdir /var/share/z-push
mkdir /var/lib/z-push
mkdir /var/log/z-push
wget https://github.com/chrispugmire/Z-Push/archive/refs/heads/develop.zip
unzip develop.zip

cd Z-Push
php install.php # this coppies the files to /usr/share/z-push, it doesn't overwrite existing config.php files!

# repace www-data with the account that apache runs as!
chown -R www-data /var/lib/z-push /var/share/z-push /var/log/z-push

# apache2 config ubuntu...

cp Z-Push/config/apache2/z-push.conf /etc/apache2/conf-available
cp Z-Push/config/apache2/z-push-autodiscover.conf /etc/apache2/conf-available

a2enconf z-push.conf
a2enconf z-push-autodiscover.conf
systemctl reload apache2

Adjust the config files.

cd /usr/share/z-push
edit config.php
     # add new settings
     define('MAX_MSG_SIZE',20); //  Units=MB

     # set backend provider inf config.php if not already set correctly...
     define('BACKEND_PROVIDER', 'BackendIMAP');

# set imap settings if not already set correct! 
edit backend/imap/config.php

Surgemail Settings you should check

This significantly improves performance:

g_imap_status_stored "true"

Test APACHE config is working


Now configure Outlook to use ActiveSync

This is hard to do because it's not in the normal outlook account setup, to get to the active sync option you do this:

Control Panel/ search for Mail / choose "Email Accounts" / choose "New" / Manual / Exchange ActiveSync...

Now check the logs

cd /var/log/z-push

tail -1000 z-push.log

tail z-push-error.log

Run the monitor to see what z-push is doing


Commands that 'might' unjam a stuck z-push

# These two seem fairly safe and are a reasonable first thing to try...
/usr/share/z-push/z-push-admin.php -a clearloop

# commands that would reset zpush completely, (not recommended)
/usr/share/z-push/z-push-admin.php -a remove -u user@domain.name

# manually fix states (causes refetch of all messages)
/usr/share/z-push/z-push-admin -a fixstates

# completely WIPE the zpush state folders...
rm -r /var/lib/z-push/*

# If all else fails delete the account from exchange and recreate it! This often gets rid of a whole bunch of errors. 

Was this article helpful?

Related Articles