Installation
This is still a work in progress as the community evolves
sudo apt update
sudo apt -y upgrade
install php dependancies for z-push
sudo apt -y install php php-cli php-soap php-mbstring
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
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/
install PHP FPM for nginx
sudo apt -y install php-fpm
Installing and setup choice of web server, Apache, Nginx or other. Setup chosen backends.
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
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
sudo dnf update
sudo dnf upgrade
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
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
need to test this step
sudo dnf install postfix
sudo systemctl disable --now postfix
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
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 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
-
Address unconfigured: 6 (Zimbra-Store)
- Select: 4 (Admin Password)
- Password: (copy suggested or create new)
- Select: r (return to prev menu)
-
Select from menu: a (apply config)
-
Save config: Y
-
Save config to file: (as suggested)
-
System will be modified: Y
-
Notify Zimbra of your installation? [Yes]: Y Notifying Zimbra of installation via http://www.zimbra.com/cgi-bin/notify.cgi?VER=8.8.15_GA_4362_RHEL8_64&MAIL=admin@z-pushtest.xyz
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
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
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.
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
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');
- change it to:
-
find the line:
define('BACKEND_PROVIDER', '');- change it to:
define('BACKEND_PROVIDER', 'BackendZimbra');
- change it to:
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
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
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.
With the release of Z-Push 2.3 a public repository is available.
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.
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.
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/
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.
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.
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.
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 -
Assuming that Apache is your webserver, run:
sudo apt-get update
Then:
sudo apt-get install z-push-kopano z-push-config-apache
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.
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
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.
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
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
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