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:///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");