How to Configure Kopano Z-Push for ActiveSync Mobile Sync

Z-Push lets compatible mobile devices synchronize with Kopano Core through Microsoft Exchange ActiveSync. A reliable setup depends on matching the Z-Push backend to the Kopano server, publishing the ActiveSync endpoint over HTTPS, and preserving Z-Push state during upgrades. The right configuration also depends on whether you want the simplest single-server deployment or need separate services and multi-host capacity.

Choose the setup that fits your environment

Z-Push is an open-source ActiveSync synchronization server. It acts as the protocol layer between a compatible device and a groupware backend; the device usually adds an Exchange or ActiveSync account rather than connecting directly to Kopano. Z-Push can synchronize email, contacts, calendar items, and tasks when the chosen backend and mobile client support those data types. Kopano describes this relationship in its Kopano Core administrator documentation.

For an existing Kopano Core server, the Kopano backend is the natural starting point. Select IMAP plus CalDAV/CardDAV only when those systems actually hold the relevant data, or when you intentionally want separate sources. Backend substitutions are not feature-neutral: synchronization behavior, address books, tasks, public folders, and compatibility can differ.

Before installing or changing configuration

• Record your Kopano Core, Z-Push, PHP, web-server, and operating-system versions. Check the supported combinations for the packages you plan to use; the PHP version accepted by Z-Push alone does not guarantee that the Kopano MAPI extension is available for it.
• Choose the public hostname clients will use, such as sync.example.com, and prepare a trusted TLS certificate for that name.
• Decide whether Z-Push runs on the Kopano host or a separate web server. A separate host can isolate web-facing services, but requires working network access to Kopano and a correctly configured MAPI server address.
• Back up the Z-Push configuration and state directories before an upgrade. Z-Push state tracks device synchronization; Kopano’s documented upgrade guidance says to preserve state for existing mobile profiles.
• Choose the data types each user should synchronize and review device policy requirements before enrolling personal or company phones.

Configure the server side

1. Install a matching Z-Push package set

Use packages built for your distribution and Kopano release when they are available. A typical package-based setup separates the Z-Push core, the Kopano backend, and the web-server integration. Kopano’s administrator manual describes packages such as z-push-backend-kopano and web-server configuration packages, but the exact package names and repository availability are distribution-specific and the manual covers an older Kopano Core documentation generation. Confirm current package support before applying its historic commands.

Source installs and containers provide more control over versions and filesystem layout. They also shift responsibility to the operator: you must make PHP extensions available to the same PHP runtime used by the web server, persist state and logs, and keep the ActiveSync route reachable after redeployments.

2. Select the Kopano backend and server address

In the main Z-Push configuration, set the backend provider to the Kopano backend using the setting and class name documented for your installed release. A common setting in packaged deployments is BackendKopano; do not paste a setting into a differently structured configuration file without checking the sample shipped by your package. In the Kopano backend configuration, set the MAPI server address when the Kopano service is not on the same host or cannot be reached through the default local connection.

// Example only: confirm the setting and file path in your installed package.
define('BACKEND_PROVIDER', 'BackendKopano');

File names and constants can differ between packaged releases. Keep secrets out of public configuration examples, restrict configuration-file permissions, and verify that the PHP runtime used by Apache or PHP-FPM can load the required Kopano MAPI extension. A healthy command-line PHP environment does not prove the web PHP runtime has the same extensions enabled.

3. Publish the ActiveSync endpoint over HTTPS

Clients need a stable HTTPS URL for the ActiveSync handler, commonly the hostname followed by /Microsoft-Server-ActiveSync. Configure Apache, Nginx, or the chosen reverse proxy to route that path to Z-Push’s entry point. Keep the canonical endpoint on the same hostname and avoid redirects that change the request method or send a mobile client to a different path. The Kopano guide specifically warns against renaming the Z-Push directory to create the endpoint because a redirect can break device synchronization.

Use a valid certificate whose name matches the endpoint hostname. HTTPS protects credentials and synchronization data in transit, and many current mobile clients reject untrusted or mismatched certificates. Do not work around certificate warnings by disabling TLS on production accounts. If TLS terminates at a reverse proxy, confirm the proxy forwards requests and authentication-related headers as intended and that the connection from the proxy to Z-Push follows your internal security policy.

4. Set writable state and log locations

Z-Push must be able to write its state and log locations. Grant access to the specific web-server account, such as www-data on many Debian and Ubuntu installs; the service account varies by distribution. Avoid making these directories world-writable. In a multi-host deployment, choose a state mechanism designed for shared access rather than assuming files on one node are visible to another. The Kopano administrator guide explains state-directory permissions and notes that state should be retained when upgrading Z-Push.

Set up the mobile account

On the phone, add a work or Exchange account and select Exchange ActiveSync, Microsoft Exchange, or the equivalent option offered by that client. Exact labels and screens vary by operating system and mail app. Enter the user’s email address and credentials. If automatic discovery does not locate the server, enter the Z-Push hostname and, if requested, the ActiveSync endpoint. Use the username format your Kopano authentication setup expects; do not assume the full email address and Kopano login name are always identical.

Leave SSL/TLS enabled and accept device policies only after reviewing what they allow, such as requiring a passcode or applying organization-managed device controls. Select which categories to sync: mail, contacts, calendar, and tasks where available. The legacy Kopano mobile-device guide describes the general Exchange account workflow, but the screenshots and operating-system labels are dated. Follow the current phone’s prompts rather than copying older menu paths literally.

If the mail app offers sync schedules, push or frequent updates provide quicker delivery but may use more battery and network activity. Longer polling intervals reduce background checks but delay new messages. For a work account where timely mail matters, start with the client’s push setting if supported, then adjust based on battery use and organizational policy.

Verify each layer before enrolling more devices

1. Endpoint: Open the public hostname in a browser and confirm the TLS certificate is valid. A browser error or certificate warning should be fixed before adding accounts.
2. Web routing: Confirm the ActiveSync path reaches the Z-Push handler without redirect loops or a generic web-server 404 page. The endpoint is a protocol handler, not a normal website.
3. Backend authentication: Use a test account and confirm that the Z-Push logs show a successful backend connection without exposing passwords or tokens.
4. Initial sync: Add one test phone and check the selected mail folders, contacts, calendar, and tasks. A successful login does not prove every data type is syncing correctly.
5. Two-way changes: Create a test calendar event on the phone and confirm it appears in Kopano; then make a test change in Kopano and confirm it reaches the phone.
6. Restart and restore: Restart the web service during a planned test window, verify sync recovers, and confirm that the state directory remains intact.

Troubleshoot by symptom

Use Z-Push’s own logs and the web-server/PHP logs together, matched to the same timestamp. If you need to test a fresh device profile, first confirm that a server-side state reset is appropriate for your release and understand whether it will trigger a full resynchronization. Do not delete the entire state directory as a first troubleshooting step.

Which configuration should you choose?

For a small existing Kopano Core installation, a distribution-supported Z-Push package set, the Kopano backend, one HTTPS endpoint, and carefully permissioned local state usually minimize moving parts. Use a separate host when isolation or operational boundaries justify the extra network and PHP-MAPI compatibility work. Use a multi-host design only after selecting and testing a shared state approach. If mail, calendars, or contacts live outside Kopano, compare the relevant Z-Push backends before rollout and test each data type on the actual mobile clients your users rely on.

Z-Push and Kopano packaging, PHP support, and device behavior change across releases. Treat the installed package’s sample configuration and its matching release documentation as authoritative; older Kopano manuals are useful for concepts but should not be copied blindly into a newer system. The Z-Push project repository is the source for current project code and release information.