Installing and Configuring Z-Push
=================================

If you are installing Z-Push for the first time, there is some configuration
that should be done. At minimum, the following settings should be reviewed:

  - In /etc/z-push/z-push.conf.php:

      Enable PROVISIONING if you want to be able to remotely wipe all
      connected devices. See z-push-admin(1).

      Set BACKEND_PROVIDER to 'BackendKopano' or 'BackendIMAP', or keep it
      empty to use autodetection based on the installed backend packages.

  - In /etc/z-push/autodiscover.conf.php:

      Set ZPUSH_HOST to the name of the web server that is running Z-Push.

  - In /etc/z-push/imap.conf.php:

      You have to set IMAP_SERVER and the IMAP_FOLDER_* options at minimum.

  - In /etc/z-push/kopano.conf.php:

      Nothing; the Kopano backend should work without changes if Kopano is
      installed on the same server as Z-Push.


Upgrading from D-Push
=====================

If you have used D-Push in the past, upgrading to Z-Push will take a bit of
effort. Due to the new package structure of Z-Push, there is no easy way to
convert the D-Push config to Z-Push config. If you are upgrading, make sure
you have the correct backend packages installed and review the configuration
in /etc/z-push.

Things to watch out for:

  - If Apache is used, remove any old d-push config lying around. Check the
    Apache logs for an error such as:

       The Alias directive in /etc/apache2/conf-enabled/z-push.conf at
       line 3 will probably never match because it overlaps an earlier Alias.

  - Review the configuration in /etc/z-push.

  - The D-Push state dir was /var/lib/d-push/state. The Z-Push state dir is
    /var/lib/z-push. State files are currently not migrated.

An effort will be made to write more detailed upgrade instructions, or to
add some automation that will help with this task.


Differences between Debian packages and z-push.org packages
===========================================================

Z-Push can be installed from the official Debian archive and from packages
provided by z-push.org. The list of Z-Push packages between those two is
slightly different. These differences are listed here:

| Package                           | Debian               | z-push.org
|-----------------------------------|----------------------|-------------------|
| z-push                            |                      | N/A (metapackage) |
| z-push-autodiscover               | N/A -> z-push-common |                   |
| z-push-backend-caldav             |                      |                   |
| z-push-backend-carddav            |                      |                   |
| z-push-backend-combined           |                      |                   |
| z-push-backend-galsearch-ldap     |                      |                   |
| z-push-backend-imap               |                      |                   |
| z-push-backend-kopano             |                      |                   |
| z-push-backend-ldap               |                      |                   |
| z-push-common                     |                      |                   |
| z-push-config-apache              | N/A -> z-push-common |                   |
| z-push-config-apache-autodiscover | N/A -> z-push-common |                   |
| z-push-ipc-memcached              |                      |                   |
| z-push-ipc-sharedmemory           | N/A -> z-push-common |                   |
| z-push-kopano                     | N/A (metapackage)    |                   |
| z-push-kopano-gab2contacts        |                      |                   |
| z-push-kopano-gabsync             |                      |                   |
| z-push-state-sql                  |                      |                   |
|-----------------------------------|----------------------|-------------------|

The most important difference is that some of the z-push.org packages have
been merged with 'z-push-common' in Debian. Additionally, the z-push.org
'z-push-kopano' metapackage was dropped, while Debian has a 'z-push'
metapackage.


PEAR modules used in Z-Push
===========================

Z-Push uses several Pear modules. Unfortunately, these are copies of the
original modules that have been slightly modified, so it is not possible to
use the Debian packages for these modules. It is a long-term goal of the
Z-Push developers to replace these copies with their original equivalents,
but until that time the Z-Push packages must carry the copied code.

There are five Pear modules involved: Mail, Mail_MIME, Mail_mimeDecode,
Net_SMTP and Net_Socket.


Apache configuration
====================

The z-push-common package provides two config files for Apache. The first
config file, 'z-push.conf', enables the Z-Push application itself. Since
upstream uses the name 'z-push.conf' for this config file, it seemed better
to use this name as well, even though it is installed by the z-push-common
package. This will make upgrading from upstream packages or source installs
to the standard Debian packages much easier.
The second config file, 'z-push-autodiscover.conf', configures Autodiscovery
for Z-Push. This is done in a separate config file because 1) a user
might not want to enable Autodiscovery or 2) he or she might want to
run Autodiscovery by itself on a different host than the Z-Push application.

Because of this, the lintian suggestion that the name of the Apache
config files should match the package name was not followed, and two
lintian warnings were overridden in z-push-common.lintian-overrides.


Setting up your mobile device
=============================

This is simply a case of adding an 'exchange server' to your activesync
server list, specifying the host name of the Z-Push's apache server,
setting the correct username and password (the domain is ignored, you can
simply specify 'domain' or some other random string), and then going through
the standard activesync settings.

Once you have done this, you should be able to synchronise your mobile
simply by clicking the 'Sync' button in ActiveSync on your mobile.

*NOTE* using the synchronisation without SSL is not recommended because
your private data is transmitted in clear text over the net. Configuring
SSL on Apache is beyond of the scope of this document. Please refer to
Apache documentation available at http://httpd.apache.org/docs/


Troubleshooting
===============

Most problems will be caused by incorrect Apache settings. To test whether
your Apache setup is working correctly, you can simply type the Z-Push URL
in your browser, to see if apache is correctly redirecting your request to
Z-Push. You can simply use:

    https://<servername>/Microsoft-Server-ActiveSync

If correctly configured, you should see a username/password request and
when you specify a valid username and password, you should see a Z-Push
information page, saying that this kind of requests is not supported.
Without authentication credentials Z-Push displays general information.

If not then check your PHP and Apache settings and Apache error logs.

If you have other synchronisation problems, you can increase the LOGLEVEL
parameter in the config e.g. to LOGLEVEL_DEBUG or LOGLEVEL_WBXML.

The z-push.log file will then collect detailed debug information from your
synchronisation.

*NOTE* This setting will set Z-Push to log the detailed information for
*every* user on the system. You can set a different log level for particular
users by configuring $specialLogUsers in /etc/z-push/z-push.conf.php, e.g:
   $specialLogUsers = array("user1", "user2", "user3");
