Skip to content
BAlekssei edited this page Jul 21, 2024 · 7 revisions

This is still a work in progress as the community evolves

Z-Push on Ubuntu 22.04

update packages

sudo apt update
sudo apt -y upgrade

install php and dependancies

install php dependancies for z-push

sudo apt -y install php php-cli php-soap php-mbstring php-curl php-intl

install php dependancies for backends

all backends

sudo apt -y install php-imap php-curl libawl-php php-curl php-xml php-ldap

or for the indivdual backends

imap

sudo apt -y install php-imap

caldav

sudo apt -y install php-curl libawl-php

cardav

sudo apt -y install php-curl php-xml

ldap

sudo apt -y install php-ldap

Download and setup Z-Push

Create folders for the Z-Push and the log

sudo mkdir /usr/local/lib/z-push/ /var/log/z-push
sudo chmod 755 /usr/local/lib/z-push/ /var/log/z-push

Find out the URL for the latest Z-Push from here: https://github.com/Z-Hub/Z-Push/releases/latest

I used the latest version, 2.7.1 at the time. Once you have the URL, go to your server, download extract and copy to /var/lib/z-push

wget -O z-push.tar.gz https://github.com/Z-Hub/Z-Push/archive/refs/tags/2.7.1.tar.gz
tar xzvf z-push.tar.gz 
sudo cp -r Z-Push-2.7.1/src/* /usr/local/lib/z-push/

or use git to get the latest

git clone https://github.com/Z-Hub/Z-Push.git
sudo cp -r Z-Push/src/* /usr/local/lib/z-push/

PHP FPM for Nginx/Apache

install PHP FPM for nginx

sudo apt -y install php-fpm

Next Steps

Installing and setup choice of web server, Apache, Nginx or other. Setup chosen backends.

Z-Push on Mail-in-a-Box

Mail-in-a-Box comes with Z-Push 2.7.0 (as at 8th Jul 2023)

Installation instructions https://github.com/mail-in-a-box/mailinabox#installation Setup Guide https://mailinabox.email/guide.html

Z-Push on Zimbra 8.8.15 Rocky 8

Note that this is intended to only up a dev environment on a single server

adapted from Stefan Seidel's Z-Push on Zimbra 8 post

note please replace the below : 172.31.27.53 the local IP not needs to be updated with your eth0 IP. mail.z-pushtest.xyz is a test domain name that you must update with your own. Need A record and MX DNS entries for your domain name

update packages

sudo dnf update
sudo dnf upgrade

Remove Perl-5 and install Perl

rpm -qa | grep perl-5
sudo dnf remove perl-5.26.3-422.el8.x86_64
sudo dnf install perl

install perl packages for Zimbra Logger

sudo dnf config-manager --set-enabled powertools -y
sudo dnf install epel-release -y
sudo dnf update -y
sudo dnf upgrade -y
sudo dnf install perl-DateTime perl-TimeDate swatch perl-IO-stringy perl-MIME-Types perl-Unix-Syslog  perl-MIME-tools perl-Net-LibIDN perl-Net-Server zeromq -y
sudo ln -sf /usr/share/perl5/vendor_perl/Swatch/ /usr/share/perl5/vendor_perl/Swatchdog

set PHP to right version

these steps already done but worth running anway

sudo dnf install epel-release -y
sudo dnf update -y
sudo dnf upgrade -y

install php dependancies

sudo dnf module enable php:7.4 -y
sudo dnf install git php php-cli php-soap php-process php-mbstring -y

in case enabling 7.4 doesn't work

sudo dnf remove php*
sudo dnf module reset php

Install and Disable postfix

need to test this step

sudo dnf install postfix
sudo systemctl disable --now postfix

Set hostname and hosts file

sudo hostname mail.z-pushtest.xyz
sudo hostnamectl set-hostname mail.z-pushtest.xyz

insert line in to /etc/hosts

sudo vi /etc/hosts
172.31.27.53  mail.z-pushtest.xyz  mail

Install dnsmasq

Partially taken from https://krypted.com/unix/quick-and-dirty-dnsmasq-install-on-ubuntu-18-04-on-aws-ec2-instances/

Now that we’re there, let’s update the package repository to make sure we’re dealing with the latest and greatest recipes:

sudo dnf update

install dnsmasq

sudo dnf install dnsmasq

Now that we’ve done that, let’s go ahead and start our instance and clear out the default resolv.conf information. To do so, first we’ll stop system-resolved:

sudo systemctl stop systemd-resolved

Then we’ll disable it from starting back up in the future:

sudo systemctl disable systemd-resolved

edit /etc/resolv.conf

sudo vi /etc/resolv.conf
search ap-southeast-2.compute.internal mail.z-pushtext.xyz
nameserver 172.31.27.53

make file immutable so it can't be overwritten

sudo chattr +i /etc/resolv.conf

Append/insert intto /etc/dnsmasq.conf

sudo cp /etc/dnsmasq.conf /etc/dnsmasq.conf.old
sudo rm /etc/dnsmasq.conf
sudo vi /etc/dnsmasq.conf
listen-address=::1,127.0.0.1,172.31.27.53
interface=eth0,lo
expand-hosts
domain=mail.z-pushtest.xyz

server=/mail.z-pushtest.xyz/172.31.27.53
server=/27.31.172.in-addr.arpa/172.31.27.53

server=172.31.0.2
mx-host=mail.z-pushtest.xyz,mail.z-pushtest.xyz,10

Note: consider adding this afterwards -- shouldn't need this for single sub-domain setup

# mx-host=mail.z-pushtest.xyz,mail.z-pushtest.xyz,10
sudo systemctl enable dnsmasq
sudo systemctl start dnsmasq
sudo systemctl status dnsmasq

restart the server

sudo reboot

and check the following files haven't changed

cat /etc/hosts
cat /etc/resolv.conf

and check the digs should all be pointing to 172.31.27.53

sudo dnf install bind-utils

dig z-pushtest.xyz
dig mail.z-pushtest.xyz
dig z-pushtest.xyz mx

and check the digs externally resolve without errors

dig google.com

Install Zimbra on Rocky

install wget

sudo dnf install wget

Download and extract files

wget https://files.zimbra.com/downloads/8.8.15_GA/zcs-8.8.15_GA_4362.RHEL8_64.20220721104405.tgz
tar xzvf zcs-8.8.15_GA_4362.RHEL8_64.20220721104405.tgz

change Directory and run install.sh

cd zcs-8.8.15_GA_4362.RHEL8_64.20220721104405
sudo ./install.sh
  • Agree to license agreement: Y
  • Use Zimbra repo: Y
  • Install zimbra-* except for zimbra-dnscache: Y
  • Install zimbra-dnscache: N
  • The system will be modified: Y

need to set admin password before continuing

Main Menu disaplyed

ERROR: Notification failed

  • Configuration complete - press return to exit

restart the server

sudo reboot

after reboot check status and start if need be

sudo -i -u zimbra /opt/zimbra/bin/zmcontrol status
sudo -i -u zimbra /opt/zimbra/bin/zmcontrol start

if logger has problems starting try

sudo /opt/zimbra/libexec/zmfixperms
sudo -i -u zimbra /opt/zimbra/bin/zmcontrol stop
sudo -i -u zimbra /opt/zimbra/bin/zmcontrol start

Z-Push on Zimbra 8.8.15 with Jetty

from https://github.com/imanudin11/zcs-zpush#readme

Install dependecies

these steps already done but worth running anway

sudo dnf install epel-release -y
sudo dnf update -y
sudo dnf upgrade -y

install php dependancies

sudo dnf module enable php:7.4
sudo dnf install git php php-cli php-soap php-process php-mbstring -y

in case enabling 7.4 doesn't work

sudo dnf remove php*
sudo dnf module reset php

Clone repo

git clone https://github.com/imanudin11/zcs-zpush.git

Create folder for log

sudo mkdir /var/lib/z-push /var/log/z-push
sudo chmod 755 /var/lib/z-push /var/log/z-push
sudo chown zimbra:zimbra /var/lib/z-push /var/log/z-push

Save z-push folder on /opt/

cd zcs-zpush
sudo cp -rvf z-push /opt/

Create symlink

sudo ln -sf /var/lib/z-push/src/ /opt/zimbra/jetty/webapps/z-push 

was sudo ln -sf /opt/z-push /opt/zimbra/jetty/webapps/

Save php script on /usr/bin

sudo cp php-cgi-fix.sh /usr/bin/php-cgi-fix.sh
sudo chmod +x /usr/bin/php-cgi-fix.sh
sudo /usr/bin/php-cgi-fix.sh

Change publicHostname domain on your Zimbra into localhost

sudo -u zimbra /opt/zimbra/bin/zmprov md z-pushtest.xyz zimbraPublicServiceHostname localhost
sudo -u zimbra /opt/zimbra/bin/zmprov md z-pushtest.xyz zimbraPublicServiceProtocol https

Backup and replace jetty.xml.in

sudo cp /opt/zimbra/jetty/etc/jetty.xml.in /opt/zimbra/jetty/etc/jetty.xml.in.backup
sudo cp jetty.xml.in-for-zcs-8815 /opt/zimbra/jetty/etc/jetty.xml.in
sudo chown zimbra.zimbra /opt/zimbra/jetty/etc/jetty.xml.in

Replace php.ini

sudo cp /etc/php.ini /etc/php.ini.backup
sudo cp php.ini-centos7 /etc/php.ini

Restart Zimbra Mailbox

sudo -u zimbra /opt/zimbra/bin/zmcontrol restart

For testing, please access https://z-pushtest.xyz/Microsoft-Server-ActiveSync from your browser. Or you can configure your mobile devices and ensure exchange as protocol

Upgrading Z-Push

The easy way to install Z-Push (support for ActiveSync) on Zimbra 8. It does not require additional servers. The installation happens on the Zimbra server where the Proxy is installed.

Preparation

Find out the URL for the latest Z-Push from here: https://github.com/Z-Hub/Z-Push/releases/latest

I used the latest version, 2.7.0 at the time. Once you have the URL, go to your zimbra server as root and type

wget -O z-push.tar.gz https://github.com/Z-Hub/Z-Push/archive/refs/tags/2.7.0.tar.gz

Now we create the Z-Push directory and unpack it there:

tar xzvf z-push.tar.gz 
sudo cp -r Z-Push-2.7.0/src/* /opt/z-push

Now we need to get the Z-Push Zimbra Backend:

wget -O zpushzimbra.tar.gz https://sourceforge.net/projects/zimbrabackend/files/latest/download

and also extract it to the correct directory:

tar xzvf zpushzimbra.tar.gz
sudo cp -r zimbra71/* /opt/z-push/backend/zimbra

Configuration

Now we need to configure Z-Push to use the Zimbra Backend. Edit the file /opt/z-push/config.php and edit these two settings:

sudo vi /opt/z-push/config.php
  • find the line define('USE_CUSTOM_REMOTE_IP_HEADER', false);

    • change it to: define('USE_CUSTOM_REMOTE_IP_HEADER', 'HTTP_X_FORWARDED_FOR');
  • find the line: define('BACKEND_PROVIDER', '');

    • change it to: define('BACKEND_PROVIDER', 'BackendZimbra');

Now edit the file /opt/z-push/backend/zimbra/config.php

sudo vi /opt/z-push/backend/zimbra/config.php
  • add a line with the text: define('ZIMBRA_URL', 'https://z-pushtest.xyz');
  • adjust other settings as needed, first try it as it is

Obviously replace z-pushtest.xyz with the address of your Zimbra installation.

restart zimbra

sudo -u zimbra /opt/zimbra/bin/zmcontrol restart

Setting up let's encrypt

sudo dnf install -y python3 python3-virtualenv augeas-libs
sudo python3 -m venv /opt/certbot/
sudo /opt/certbot/bin/pip install --upgrade pip
sudo /opt/certbot/bin/pip install certbot
sudo ln -s /opt/certbot/bin/certbot /usr/local/sbin/certbot
sudo /opt/certbot/bin/pip install pyOpenSSL==23.1.1
sudo /usr/local/sbin/certbot certonly -d $(hostname --fqdn) --standalone --preferred-chain  "ISRG Root X1" --agree-tos --register-unsafely-without-email --key-type rsa
sudo vi /usr/local/sbin/letsencrypt-zimbra

for z-pushtest.xyz

#!/bin/bash
/usr/local/sbin/certbot certonly -d $(hostname --fqdn) --standalone -n --preferred-chain "ISRG Root X1" --agree-tos --register-unsafely-without-email --key-type rsa
cp "/etc/letsencrypt/live/$(hostname --fqdn)/privkey.pem" /opt/zimbra/ssl/zimbra/commercial/commercial.key
chown zimbra:zimbra /opt/zimbra/ssl/zimbra/commercial/commercial.key
wget -O /tmp/ISRG-X1.pem https://letsencrypt.org/certs/isrgrootx1.pem.txt
rm -f "/etc/letsencrypt/live/$(hostname --fqdn)/chainZimbra.pem"
cd /etc/letsencrypt/live/$(hostname --fqdn)/
awk '/-----BEGIN[[:space:]]CERTIFICATE-----/{x="chain.pem."++i;}{print > x;}' /etc/letsencrypt/live/$(hostname --fqdn)/chain.pem
cp "/etc/letsencrypt/live/$(hostname --fqdn)/chain.pem.1" "/etc/letsencrypt/live/$(hostname --fqdn)/chainZimbra.pem"
cat /tmp/ISRG-X1.pem >> "/etc/letsencrypt/live/$(hostname --fqdn)/chainZimbra.pem"
chown zimbra:zimbra /etc/letsencrypt -R
cd /tmp
su zimbra -c '/opt/zimbra/bin/zmcertmgr deploycrt comm "/etc/letsencrypt/live/$(hostname --fqdn)/cert.pem" "/etc/letsencrypt/live/$(hostname --fqdn)/chainZimbra.pem"'
rm -f "/etc/letsencrypt/live/$(hostname --fqdn)/chainZimbra.pem"
sudo chmod +rx /usr/local/sbin/letsencrypt-zimbra
sudo ln -s /usr/local/sbin/letsencrypt-zimbra /etc/cron.daily/letsencrypt-zimbra
sudo /etc/cron.daily/letsencrypt-zimbra

restart zimbra

sudo -i -u zimbra /opt/zimbra/bin/zmcontrol restart

Prior to 2.7.0

Until version 2.2.x Z-Push was officially only distributed as a tarball. This source tarball will be further maintained for Z-Push 2.3, but it's highly recommended to use the newly available repositories and packages instead. If you are looking for the tarball, scroll to the end of the page. Starting with Z-Push 2.4.0 there won't be tarball releases.

Repository

With the release of Z-Push 2.3 a public repository is available.

Stages

There are different stages of packages available: final stable

Contains the final releases of Z-Push 2.6.x.

This corresponds to the master branch of GIT. old-final old-stable

Contains the final releases of Z-Push 2.5.x.

This corresponds to the release/2.5 branch of GIT. pre-final testing

Contains public alpha and beta releases of Z-Push.

This corresponds to the release/2.6 branch in GIT. develop experimental

Contains nightly builds. Use it to always have the latest code installed.

These packages are not recommended for production use (unless you know exactly what you are doing and are aware of the risks).

Corresponds to the develop branch in GIT.

Distributions

The final repository contains builds for the following distributions/architectures: Debian 8.0

i586

x86_64

Debian 9.0

i586

x86_64 Since Z-Push 2.3.7 Debian 10

i586

x86_64

RHEL 6 + PHP 5.6

x86_64

RHEL 7

x86_64

RHEL 7 + PHP 5.6

x86_64

SLES 12

ppc64le

x86_64

SLES 12 + PHP7

ppc64le

x86_64

Ubuntu 14.04

i586

x86_64

Ubuntu 16.04

i586

x86_64

PHP7 support since Z-Push 2.3.4 Ubuntu 18.04

i586

x86_64

PHP7.2 support since Z-Push 2.4.3 Ubuntu 20.04

i586

x86_64

Univention 4.2

i586

x86_64

Univention 4.3/4.4

i586

x86_64

openSUSE Leap 42.3

i586

x86_64

openSUSE Tumbleweed

i586

x86_64

PHP 5.4 required

Z-Push 2.3, 2.4 and 2.5 require at least PHP 5.4. Due to this, packages for older distributions are not available.

Usage of repositories together with Zarafa/Kopano

Even though the the Z-Push Kopano backend is included in all of the above repositories, this backend can only be used in distributions that are also supported by Kopano/Zarafa and therefore provide php-mapi package.

URL

The base URL of the repository is:

https://download.kopano.io/zhub/z-push:///

To e.g. add the stable repository for Ubuntu 16.04 use:

deb https://download.kopano.io/zhub/z-push:/final/Ubuntu_16.04/ /

To find the correct URL for your distribution, access:

https://download.kopano.io/zhub/z-push:/final/

Packages

Main packages

z-push-common Core - Base components of Z-Push. z-push-config-apache Config Apache configuration Installs the Z-Push alias in the apache configuration and restarts the webserver. z-push-config-nginx Config Nginx configuration Add Nginx configuration file. Make sure you edit it to adapt your needs. z-push-backend-caldav Backend Calendar To get calendaring from a CalDav server. z-push-backend-carddav Backend Contacts To get contacts from a CardDav server. z-push-backend-combined Backend - To use different backends for different folder types. z-push-backend-imap Backend Email To get email from an imap server. z-push-backend-kopano Backend Email, Calendar, Contacts, Tasks, Notes and GAB

Connect against a Kopano or ZCP server to get email, calendar, contacts, notes, tasks and search the GAB.

Dependencies

This package depends on the php-mapi packages provided by Kopano/Zarafa.

These packages can be found for the community or via the repositories for Kopano subscribers. z-push-backend-ldap Backend Contacts To get contacts from an LDAP server. z-push-backend-galsearch-ldap SearchProvider GAB To search the GAB (Global Address Book) against an LDAP server. z-push-ipc-memcached IPC Provider - Stores volatile states (Interprocess communication) in a memcache server. Recommended large for multi-host setups and setups with more than 200 users. z-push-ipc-sharedmemory IPC Provider - Stores volatile states (Interprocess communication) in shared memory. Use on single host installations only. Recommended for setups with less than 200 users. z-push-state-sql StateMachine -

Stores mobile states in a SQL database (e.g. mysql). Recommended for multi-host setups.

Migration script available in Tools. More information see State Machines.

  • GAB = Global Address Book.

Other Packages

z-push-autodiscover Autodiscover To be installed on the Z-Push host with a main backend. z-push-kopano-gabsync KOE GAB Provides the GAB (Global Address Book) for the Kopano Outlook Extension. More information: Configuring GAB-Sync for Kopano OL Extension z-push-kopano-gab2contacts Tool Contains a script that synchronizes the GAB (Global Address Book) into any contacts folder (e.g. in the public folder). This script is also able to update these contacts (e.g. via a daily cron job). Introduced with Z-Push 2.3.5. z-push-kopano Meta package

Installs the basic stack for Kopano (and ZCP). To run on apache install z-push-config-apache.

Includes: z-push-common, z-push-backend-kopano, z-push-ipc-sharedmemory

Please note the additional dependencies for the z-push-backend-kopano package mentioned in the table above.

Installation

This will guide you through the basic installation on example of Kopano/Zarafa.

The examples below show how to add the repository and install Z-Push using shared-memory and the file state machine (same as with Z-Push 2.2.x).

z-push-top and z-push-admin can be executed from any location (as root).

The main directory is /usr/share/z-push, the configuration files are located in /etc/z-push.

If you use Kopano on a different host or ZCP you need to adjust the MAPI_SERVER in /etc/z-push/kopano.conf.php to fit your environment.

Debian und Ubuntu based systems

Add repository

First of all, the repository needs to be added to your distribution.

E.g. for stable releases on Debian 8, create a new file in /etc/apt/sources.list.d/z-push.list with the content:

deb https://download.kopano.io/zhub/z-push:/final/Debian_8.0/ /

To find the correct URL for your distribution, access:

https://download.kopano.io/zhub/z-push:/final/

Then, download the repository key and it to the keychain.

wget -qO - https://download.kopano.io/zhub/z-push:/final/Debian_8.0/Release.key | sudo apt-key add -

Install packages from repository

Assuming that Apache is your webserver, run:

sudo apt-get update

Then:

sudo apt-get install z-push-kopano z-push-config-apache

RHEL based systems

Add repository

First of all, the repository needs to be added to your distribution.

For the final releases on CentOS 7, create a new file in /etc/yum.repos.d/z-push.repo with the content:

[z-push]
name=Z-Push noarch Enterprise Linux 7 - $basearch
baseurl=https://download.kopano.io/zhub/z-push:/final/RHEL_7
failovermethod=priority
enabled=1
gpgcheck=0

Update the package list:

yum update

Note: If you are using RHEL_6_PHP_56 or RHEL_7_PHP_56 repository and memcached for inter process communication, make sure you have Remis repository enabled.

Install packages from repository

Assuming that Apache is your webserver and you want to install basic Z-Push with the Kopano backend, run:

yum install z-push-common z-push-config-apache z-push-backend-kopano z-push-ipc-sharedmemory

From Source

If you really want to install from the source tarball, the download is available here: http://z-push.org/download/

For information on how to install from source, please consult the INSTALL file in the tarballs main directory.

Instead of using the tarball or packages you can also use Z-Push from our GIT. See how to get the latest Z-Push code from GIT.

Speed optimizations

Opcache

Please check if your OS already has or is compatible with PHP opcache. This increases performance a lot as the PHP is compiled and cached. More information can be found here: https://kb.kopano.io/display/WIKI/Speeding+up+WebApp+and+Z-Push+with+PHP+opcache

To check your opcache usage have a look at this script: https://github.com/rlerdorf/opcache-status

States

The file state machine is used by default. It's the easiest to setup and fits most user profiles. As the states are just files they can easily be backup-ed and maintained.

There are a few downsides to the file state-machine, e.g. they are not clusterable. Some admins use NFS to share the states between several machines, which is required if you run several z-push systems and users can connect to any of them (like with a round-robin load balancer without session stickiness). NFS works but has some issues with stability. In this scenario we strongly recommend the usage of the sql state machine.

More about state machines here: State Machines

Inter process communication (IPC)

By default Z-Push installs the shared-memory IPC provider. It's the easiest to setup and a well fit for the most installations.

There are downsides using shared-memory IPC:

  • PHP memory usage per request is about 5 to 10 MB higher than when using the memcache IPC provider
  • It's not clusterable. If you use several z-push servers with shared states (like described above) the IPC data needs to be shared between these machines as well. The Shared-memory IPC doesn't allow that.
  • It doesn't scale for hundreds of users.

You should use the memcache IPC provider in these cases. It requires the installation of a central memcache service, where all Z-Push instances connect to. It's a lightweight service that only requires a few MB of RAM (32 MB should be enough for most cases). You can install it on one of the Z-Push hosts or setup a dedicated machine (ideally with fail over).

It's not ideal if the IPC data is lost (e.g. when restarting the memcache service), but it's not a big problem either. Within a few requests the required data is built up again.

If your Z-Push server is running out of memory handling Z-Push requests, you should immediately switch to memcache IPC (can be running on the same system). There will be no downtime for users. Related configuration topics

Clone this wiki locally