Migrating from Z-Push

1. Import the configuration

python3 /usr/share/active-push/zpush-import.py /usr/share/z-push > zpush.json    # source installation
python3 /usr/share/active-push/zpush-import.py /etc/z-push > zpush.json          # Debian packages (*.conf.php)
less zpush.json                                                                  # review and complete
sudo -u active-push active-push config apply zpush.json

The importer reads config.php, backend/{imap,caldav,carddav,combined}/config.php, autodiscover/config.php and policies.ini. Comments on stderr point out what needs attention (e.g. IMAP_SMTP_METHOD = 'mail' -> sendmail; switching to SMTP submission on 587 is recommended).

2. Switch the traffic

Install ActivePush, create the administrator, verify the backends with Test connection in the panel.
Check the protocol with a real account: active-push probe --url https://mail.example.com/Microsoft-Server-ActiveSync --user jan@example.com (through nginx after the switch) or directly against http://127.0.0.1:8081/... before it.
In nginx replace the fastcgi_pass ... z-push/index.php and autodiscover.php blocks with proxy_pass (see INSTALL.md), then nginx -t && systemctl reload nginx.
Disable the Z-Push PHP-FPM pool and the z-push-admin cron jobs.

3. What happens to devices

Z-Push states are not transferred (their format depends on the PHP backends). On the first connection:

the device sends its old X-MS-PolicyKey -> new provisioning (HTTP 449, or status 142/144 for AS >= 14),
the old hierarchy SyncKey -> FolderSync status 9 -> the device downloads the folder list again,
old folder keys -> Sync status 3 -> full folder synchronisation,
folder ids that only existed in Z-Push (e.g. a6271970) -> Sync status 12, and the next FolderSync sends a Delete for them so the device stops using them.

iOS, Android (Gmail, Samsung, Nine), Outlook and Windows Mail handle this automatically. Large mailboxes may take a few minutes - limit sync.filter_time_max or the policy maxemailagefilter if needed.

4. `z-push-admin` equivalents

z-push-admin	ActivePush
`-a list`	`active-push device list` / panel Devices
`-a wipe -d ID`	`active-push device wipe <id>` / Remote wipe button
`-a remove -d ID`	`active-push device remove <id>`
`-a resync -d ID`	`active-push device resync <id>` / Full resync
`-a clearloop`	automatic - loop counter in the device details
`-a fixstates`	`panel.device_inactive_days` + hourly housekeeping
`z-push-top`	panel Live

5. Functional differences

Kopano/Zarafa (MAPI) is not supported - only IMAP/SMTP + CalDAV/CardDAV (combined).
LDAP/SQL as sender source (IMAP_FROM_SQL_*, IMAP_FROM_LDAP_*) is replaced by general.email_template.
searchldap -> GAL through CardDAV (carddav.gal_path); SOGo/Nextcloud expose the directory as a book.
Out of office - reading returns "disabled", setting returns an error; configure vacation in Sieve.
AS 16.x is not announced (like Z-Push with IMAP by default) - devices use 14.1.
Notes and SMS are not synchronised (Z-Push IMAP did not do this either).

3.2 KiB Raw Blame History