Zextras Suite Installation Guide

This section contains various information—requirements, configuration details, and guidelines—for a successful installation of Zextras Suite. Please read carefully next section, Basic Information, to make sure you do not miss any important piece required to set up Zextras Suite.

Basic Information

Prerequisites

To use the Zextras suite, no additional software beyond what’s required by a standard Zimbra deployment is necessary in order to install Zextras Suite. If you did not yet install Zimbra, you can check Zimbra’s System Requirements.

If you plan to use either Zextras Drive, Zextras Team, or both, you need some additional setup. These two apps, indeed, need to communicate using web sockets on ports tcp 8742 and tcp 8743 respectively, therefore you need to edit file /opt/zimbra/conf/nginx/includes/nginx.conf.web to include the following code.

upstream zx
    {
        server    mail.example.com:8742 fail_timeout=5s version=8.8.15_GA_20201272;
        zmauth_zx;
    }
    #  Define the collection of upstream HTTPS servers to dedicated zx ssl port of jetty
    upstream zx_ssl
    {
        server    mail.example.com:8743 fail_timeout=5s version=8.8.15_GA_20201272;
        zmauth_zx;
    }

replace mail.example.com with your server.

Note

In the reminder of this installation guide, all commands must be executed as root, unless differently specified

Minimum Requirements and Tweaking

If you are interested in resources optimization and tweaking, we suggest to read the following article on the Zimbra wiki, which despite the title applies to both large and small deployments: https://wiki.zimbra.com/wiki/Performance_Tuning_Guidelines_for_Large_Deployments.

Another strict requirement is the composition of the Zimbra IDs in the system, which can only contain the following characters up to a maximum length of 64:

Lowercase and uppercase letters
Number
The following symbols: _ - # ( ) = @

Zimbra IDs containing other characters than the allowed ones will likely cause problems to the Mobile module and possibly to other modules as well.

Installation possibilities

These are the alternatives to install Zextras:

single-store installation on a single server. This is the easiest and is described in Section Quick Installation Guide.
single-store installation on a multiserver. This approach is equivalent to the previous one and applies when the installation is in a multiserver installation, see Installing Zextras Suite on a Single-store infrastructure.
multistore installation. This approach is required if you need to run multiple mailboxd services, see Installing Zextras Suite on a Multistore infrastructure.

Components

Zextras Suite is comprised of three major components:

Zextras Core, abbreviated as Core, which is a jar package extending Zimbra
Zextras Administration Zimlet, abbreviated as Zextras Suite Zimlet or just Zimlet, an administrative zimlet to access and manage the Core.
ZAL - An Open Source abstraction layer for Zimbra. Please read these advises about ZAL insallation.

The installation script follows the aforementioned structure allowing you three installation targets: core, zimlet, and all. The latter is equivalent of installing Core and immediately afterwards zimlet.

Other Zextras Zimlets

While the Zextras Suite package includes the Zextras Administration Zimlet, the Zextras Client Zimlet must be deployed separately. Check section Zextras Client at the bottom of this page for directions

Where to get the Zextras Suite package

The Zextras Suite installer can be obtained from the download section of zextras’ website, while existing customers will be able to find a direct download link after logging in with their Zextras Store account.

Setup Information

This section contains general information about the set up of the system, installation troubleshooting, and important advices about the upgrade to new version of both Zimbra and Zextras.

ZAL - an Abstraction Layer for Zimbra

The Zextras Abstraction Layer (ZAL) is an Open Source abstraction layer created to allow any extension to easily communicate with Zimbra Collaboration Suite, regardless of the version in use.

It is released under the GPL license and thus cannot be included in the Zextras Suite package, but during the installation process the Zextras Installer will automatically detect the most appropriate library version and will download and install it autonomously.

Note

Should the automatic download fail, the installation will end. However, a direct download link will be provided: the downloaded file must be renamed to zal.jar and copied into the packages/ subdirectory of the Zextras Suite installation package. A restart of the installer will detect the new file and install it along with Zextras Suite.

The Zimbra DoS Filter

Starting from Zimbra 8.0.0, a connection throttling mechanism called DoS Filter has been added in order to reduce the impact of Denial of Service attacks. By default the DoS Filter only allows 30 connections per second, rejecting any exceeding connection with a 503 HTTP error.

How the DoS Filter can affect your Zextras Suite experience

Being an Administrative Zimlet, the Zextras Administration Zimlet is loaded upon logging into the Zimbra Administration Console; in order to retrieve all relevant data, many requests are done and this can trigger Zimbra’s DoS Filter, causing slowness, AJAX Errors, and general UI corruption (e.g. empty text boxes or incoherent checkbox state).

DoS Filter warnings can be found and identified in the log file /opt/zimbra/log/zmmailboxd.out, where messages like the following one can be found:

2021-03-31 10:01:51.917:WARN:oejs.DoSFilter:qtp1027591600-
190:https://192.168.73.35:7071/service/admin/soap/GetAllZimletsRequest:
DOS ALERT: Request rejected ip=192.168.73.73, session=null, user=null

Managing the DoS Filter

There are 3 different configuration properties controlling the DoS Filter. Each attribute is inherited from global or is configurable at the server level.

Hint

The recommendation is to preserve the default configuration whenever possible.

DoSFilter Delay (milliseconds) - zimbraHttpDosFilterDelayMillis

Delay is enforced on all requests over the rate limit, before they are considered at all.

-1 = Reject request
0 = No delay
Any other integer value = Delay in ms

The default is -1.

To modify in the global configuration (e.g. set the delay to 20ms):

zmprov mcf zimbraHttpDosFilterDelayMillis 20

DoSFilter Maximum Requests Per Second - zimbraHttpDosFilterMaxRequestsPerSec

Maximum number of requests per second from a connection. All requests in excess of this value are throttled. The default is 30 and the minimum is 1.

To set the maximum number for requests in the global configuration:

zmprov mcf zimbraHttpDosFilterMaxRequestsPerSec 100

DoSFilter IP Addresses Whitelist - zimbraHttpThrottleSafeIPs

IP addresses to ignore when applying Jetty DosFilter. While this attribute does not have a default value, nonetheless these loopback IPs are whitelisted by default:

127.0.0.1
::1
0:0:0:0:0:0:0:1
All mailboxd servers

You can check if these hosts have been correctly whitelisted by the log entry in /opt/zimbra/log/mailbox.log. This log entry should contain all of the default whitelisted hosts as well as any IPs added to zimbraHttpThrottleSafeIPs:

2021-03-09 10:33:47,772 INFO  [main] [] misc - DoSFilter: Configured
whitelist IPs = 192.168.234.130,127.0.0.1,::1,0:0:0:0:0:0:0:1

See how to add single IP addresses or IP ranges in the example below.

Note

Proxy nodes should not need to be whitelisted, as long as the Originating-IP feature is correctly configured in ZCS, see https://wiki.zimbra.com/wiki/Log_Files#Logging_the_Originating_IP.

External hosts that makes SOAP requests for provisioning or any kind of integration must be added to the IP whitelist to ensure DoSFilter does not block some requests. This is also required whenever there are network resources outside of Zimbra (like e.g., proxies, bouncers, load-balancing servers, firewall, NATting devices) between the clients and Zimbra). In any of these cases, please refer to the next sections (OIP Logging and non-Zimbra Proxies and Modify Nginx Templates Files for Correct OIP Logging) for more information and directions.

IP addresses should be supplied in the multi-valued zimbraHttpThrottleSafeIPs attribute.

Hint

Add to zimbraHttpThrottleSafeIPs your private networks and/or IP addresses behind which lay multiple clients.

OIP Logging and non-Zimbra Proxies

This section contains information useful whenever between a Client and Zimbra there are proxies or other network devices that are able to modify the request’s source IP address.

Mailboxd assigns OIP (Originating Client IP Address) values from the HTTP Request header field X-Forwarded-For.

When a client connects to the Zimbra WebClient through an HTTP proxy or a load balancer and once the traffic is intercepted between clients and servers, the server’s access logs contain the IP address of the proxy or load balancer only. To see the original IP address of the client, the X-Forwarded-For request header is used, whose general format is:

X-Forwarded-For: <client>, <ext-proxy1>, <ext-proxy2>, ..., <ext-proxyN>

Here the values form a comma-separated list of the IP addresses:

the left-most (<client>) is the original client IP address
each successive IP address (<ext-proxy1>, <ext-proxy2>, …) is a proxy that passed the request, adding the IP address where it received the request from.
the right-most IP address (<ext-proxyN>) is the IP address of the most recent proxy

Sample log entries:

12020-08-26 10:00:38.074:INFO:oejs.DoSFilter:qtp1684106402-771:: Ignoring malformed remote address xxx.xxx.xxx.xxx,  yyy.yyy.yyy.yyy
22020-08-26 00:19:26.942:INFO:oejs.DoSFilter:qtp1874154700-1750041:: Ignoring malformed remote address xxx.xxx.xxx.xxx, yyy.yyy.yyy.yyy
3
42019-08-26 06:46:36,965 INFO  [qtp1874154700-1886919:] [name=john.doe@zimbrasupportlab.com.com;oip=xxx.xxx.xxx.xxx, yyy.yyy.yyy.yyy;ua=zclient/8.8.15_GA_1728;soapId=39504524;] soap - AuthRequest elapsed=1
52020-08-26 07:27:53,459 INFO  [qtp1874154700-1900882:] [name=john.doe@zimbrasupportlab.com.com;mid=28;oip=xxx.xxx.xxx.xxx, yyy.yyy.yyy.yyy;ua=zclient/8.8.15_GA_1728;soapId=39505079;] gal - autocomplete: overall=296ms, ranking=227ms, folder=2ms, gal=67ms
6
72020-08-28 00:09:41.837:INFO:oejs.DoSFilter:qtp2036958521-120378:https:: Ignoring malformed remote address xxx.xxx.xxx.xxx, yyy.yyy.yyy.yyy
82020-08-28 00:09:53.907:INFO:oejs.DoSFilter:qtp2036958521-120413:https:: Ignoring malformed remote address xxx.xxx.xxx.xxx, yyy.yyy.yyy.yyy

xxx.xxx.xxx.xxx is the IP address of the Originating client from where the request originated or was initiated.
yyy.yyy.yyy.yyy is the First Proxy server which will send request to another proxy server or the destination server.

Note

If there are multiple proxy servers, then the left-most will always be the IP address of the Originating client. If there is only one proxy server which forwards request directly to destination server, then OIP will have only one entry (i.e. for Originating client IP).

Modify Nginx Templates Files for Correct OIP Logging

In order to properly log the OIP, Nginx templates must be modified.

Warning

These commands must be run as the ROOT user!

First, take a backup of existing Nginx conf directory.

cp -pvr /opt/zimbra/conf/nginx /opt/zimbra/conf/nginx-`date +"%d-%m-%Y"`

Next, replace $proxy_add_x_forwarded_for with $http_x_forwarded_for in the all template files under /opt/zimbra/conf/nginx/templates.

sed -i 's/$proxy_add_x_forwarded_for/$http_x_forwarded_for/g' /opt/zimbra/conf/nginx/templates/*

Hint

Replacement must be checked and reapplied after every patch or zimbra proxy realated installation or upgrade.

Finally, restart the proxy service.

zmproxyctl restart

Note

If multiple zimbra-proxy servers present in the setup, then make these changes on all zimbra-proxies.

Zimbra Upgrade

When Zimbra is upgraded, the Zextras Core is removed from the server, so in case of a Zimbra upgrade, Zextras Suite must be reinstalled. All the data and settings will be maintained, therefore after re-installing the Zextras Suite, the set up will be exactly the same as before the Zimbra upgrade.

Warning

Before upgrading your Zimbra server, please make sure that a compatible Zextras Suite version has been released. A Zextras Suite compatibility release is usually available within 48 hours after the release of a new Zimbra version.

Zimbra Patches

The information above only applies to version upgrades: installing a Zimbra patch won’t affect Zextras Suite in any way and thus reinstalling the package is not required.

Quick Installation Guide

Installation can be carried out in a few steps:

Upload to your server the Zextras Suite package you downloaded
As the root user, unpack the file you just downloaded inside a directory (we suggest in /root/) in your Zimbra server: ‘tar zxf zextras_suite-latest.tgz’
Enter the directory created by the unpacking of the file: ‘cd zextras-suite’
Run the install.sh script with the all option (so ‘./install.sh all’).
The installer will take care of downloading the latest available Core, ZAL and Zimlets for your Zimbra version and start the installation.

Zextras Suite on Multiserver infrastructures

Depending on the server roles in use, some additional precautions must be taken:

Installing Zextras Suite on a Single-store infrastructure

Installing Zextras Suite on a multiserver infrastructure including a single mailbox server is just as easy as installing it on a single-server infrastructure, as the software must only be installed on servers running the mailboxd service.

Installing Zextras Suite on a Multistore infrastructure

Zextras Suite installation in a Multistore infrastructure featuring multiple mailbox servers requires the following additional setup:

Zextras Suite must be installed on ALL the store servers (i.e., the ones with the mailboxd service running)
Zextras Suite uses ports 8735 and 8736 for store-to-store communication, therefore make sure your servers can reach each other on these port and that the same ports is closed to outside traffic.

Detailed Instructions

Before installing Zextras Suite one will need to have downloaded the package, as explained in the appropriate section above, and exploded the archive in a directory of one’s choice.

$ tar xfz zextras_suite-latest.tgz
$ ls zextras_suite-latest.tgz zextras_suite/

Inside the directory zextras_suite one shall find an executable shell script named install.sh, that can be run as ./install.sh -h | ./install.sh [ -u ] [ -d ] all|theme|zimlet|core. Go to that directory and run it with -h to see a quick description of the options:

$ cd zextras_suite
$ ./install.sh -h

-h         This very message
-d         Activates debug mode for the install script
-u         Uninstall the target

The targets available for (un)installation are:
core   -- Zextras Suite Core
theme  -- Zextras Suite Theme
zimlet -- Zextras Suite Zimlet
all    -- Zextras Suite Core followed by Zextras Suite Zimlet

* In order to use Zextras Suite, both
* Core and Zimlet need to be installed.

A Zextras Theme is automatically installed during a Zextras Suite Full Installation or Zextras Suite Full Upgrade, but also a standalone zextras-theme-installer script can be used to install an updated version of the theme.

In order to successfully perform the Zextras suite installation, one shall need to either become the root user or execute the script with root privileges (e.g., using sudo).

Once launched, the script will determine the installed Zimbra version and search for a preexisting installation of either Zextras Suite or Zextras Migration Tool.

Warning

Should any component of Zextras Migration Tool be detected, you will be prompted to uninstall them and run again the Zextras Suite installation script afterwards.

Before proceeding with the installation, you will be required to accept the EULA of Zextras, after which the actual installation shall take place.

Zextras Suite Full Installation

In order to install Zextras Suite you need both Core and Zimlet to be correctly deployed and operational. By choosing all as target, Core and Zimlet will be installed in order, in one go.

Full installation:

./install.sh all

You will need to restart Zimbra after the installation has successfully completed. The script itself will prompt you to do so.

Zextras Suite Core Installation

In order to install Zextras Core you need to stop the Zimbra services beforehand. This step can be achieved by either stopping them before running the script, or having them stopped by the script when prompted. Afterwards, the script will carry out a series of checks, including for previous installation of Zextras Core and if needed, it will install the jar file among the Zimbra extensions.

Core-only installation:

./install.sh core

Once the Core has been deployed, Zimbra must be restarted to verify the former’s correct operation.

Note

If you are using the all target to install both Core and Zimlet, the script itself will prompt to start Zimbra.

Zextras Suite Zimlet Installation

Unlike the installation of Zextras Suite Core, in order to install the Zextras Suite Zimlet you need Zimbra installed and its services running. As in the Core Installation, you can either proceed manually beforehand or let the script start them after prompting you to do so. Once Zimbra is active the administrative zimlet will be deployed with the versions matching Zimbra’s.

Zimlet-only installation:

./install.sh zimlet

Zextras Suite Full Upgrade

In case of an existing instance of Zextras Suite on your system, the installation of a newer version will automatically perform an upgrade. Please refer to the instructions above for the installation procedure.

If you just upgraded your Zimbra installation, please see the Zimbra Upgrade section above.

Upgrading Zextras Suite on a Multiserver infrastructure

Upgrading Zextras Suite to a different minor release (e.g. 2.16.1 to 2.16.2). Each separate server can be upgraded independently, and Zextras Suite will be fully functional even in an environment with mixed minor versions.
Upgrading Zextras Suite to a different major release (e.g. 2.14.x to 2.16.x). All servers should be upgraded at the same time, as in this case backwards compatibility is not guaranteed and Zextras Suite will not be fully functional until all nodes have been upgraded to the same version.

Zextras Suite Uninstallation

The removal procedure is almost identical to the installation one and placing the -u switch before the target is all is needed. The script will verify the presence of any Zextras Suite components and prompt for their removal.

Therefore:

./install.sh -u all will uninstall both the Zextras Core and the Zextras Administration Zimlet
./install.sh -u core will uninstall the Zextras Core
./install.sh -u zimlet will uninstall the Zextras Administration Zimlet

Post-Install and Post-Uninstall

After either installing or uninstalling Zextras Suite, it’s highly suggested to clear both your browser’s and the server’s cache; the latter task can be carried out by running the command:

zmprov fc zimlet

as the zimbra user.

Note

While the Zextras Suite package includes the Zextras Administration Zimlet, the Zextras Client Zimlet must be deployed separately.

Additional Components

Zextras Client

Zextras Client allows end users to access new Zextras Suite features, along with some old ones which were previously available only in the Zextras Administration Console.

The Zextras Client Zimlet is 100% free, it requires the Zextras Core to be functional and its deployment is not mandatory. Once deployed, there are several alternatives to enable it.

Deploy the Zextras Client

Deploying the Zextras Client Zimlet is easy, and can be done via either the Zextras Administration Zimlet or the Zextras CLI in a few steps.

Log into the Zimbra Administration Console
Enter the Core section of the Zextras Administration Zimlet
Click on the Deploy button under Zextras Client Zimlet
Once deployed, the zimlet will appear in the deployed zimlets list as com_zextras_client.
Issue the dedicated Zextras CLI command zxsuite core doDeployClientZimlet

Deploying the Zextras Client Zimlet on a multiserver infrastructure requires the same steps as it does on single server environments. The Zimlet is deployed in LDAP, so you’ll need to only deploy it once regardless of the number of mailbox servers on your infrastructure.

Enable the Zextras Client

In order to enable the Zextras Client Zimlet, after the deployment the Zextras Client Zimlet will be only enabled for users belonging to the default COS.

You can enable the Zextras Client Zimlet for your users in the following ways:

Per user - through the Zimlets section of each user’s settings within the Zimbra Administration Console
Per COS - through the Zimlets section of each Class of Service’s settings within the Zimbra Administration Console
Via the Zimbra CLI through the zmzimletctl command
Updating the Zextras Client Zimlet

Update the Zextras Client

The Zextras Client Zimlet will be automatically updated by the Zextras Installer when updating Zextras Suite. Should this update fail, manually pressing the Deploy button mentioned above will install the latest version available.

Remove the Zextras Client

In order to remove the Zextras Client Zimlet, click the Undeploy button next to the related entry in the Configure → Zimlets section of the Zimbra Administration Console or via the Zimbra CLI through the zmzimletctl command.