Zextras Suite installation guide
- Basic information
- Setup Information
- Quick Installation Guide
- Detailed Instructions
- Post-Install and Post-Uninstall
- Additional Component
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.
|All commands must be executed as root unless differently specified|
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: http://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
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.
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 yuo need to ru multiple
mailboxdservices, see Installing Zextras Suite on a Multistore infrastructure
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.
While the Zextras Suite package includes the Zextras Administration Zimlet, the Zextras Client Zimlet must be deployed separately. Check section Zxclient at the bottom of this page for directions
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.
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.
|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.|
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.
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
There are 3 different configuration properties controlling the DoS Filter:
Each attribute is inherited from global or is configurable at the server level.
|The recommendation is to preserve the default configuration whenever possible.|
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
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
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:
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
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 examples below.
|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.
|Add to zimbraHttpThrottleSafeIPs your private networks and/or IP addresses behind which lay multiple clients.|
Examples in ZCS 8.7 or above
The following command adds a single IP and an IP range too zimbraHttpThrottleSafeIPs:
zmprov mcf zimbraHttpThrottleSafeIPs 192.168.234.130/32 zimbraHttpThrottleSafeIPs 192.168.4.0/24
To append the values to an existing list of multi-valued zimbraHttpThrottleSafeIPs:
zmprov mcf +zimbraHttpThrottleSafeIPs 192.168.234.130/32 zmprov mcf +zimbraHttpThrottleSafeIPs 192.168.4.0/24
All of this properties require a mailboxd service restart in order for any change to be applied
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
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
X-Forwarded-For request header is used, whose general
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 (1) (2) 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:] [email@example.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:] [firstname.lastname@example.org;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
|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).|
In order to properly log the OIP, Nginx templates must be modified.
|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"`
$http_x_forwarded_for in the all template files under
sed -i 's/$proxy_add_x_forwarded_for/$http_x_forwarded_for/g' /opt/zimbra/conf/nginx/templates/*
|Replacement must be checked and reapplied after every patch or zimbra proxy realated installation or upgrade.|
Finally, restart the proxy service.
|If multiple zimbra-proxy servers present in the setup, then make these changes on all zimbra-proxies.|
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.
|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.|
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.
Depending on the server roles in use, some additional precautions must be taken:
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
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
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.
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
-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.
|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.
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.
$ ./install.sh all
You will need to restart Zimbra after the installation has successfully completed. The script itself will prompt you to do so.
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.
$ ./install.sh core
Once the Core has been deployed, Zimbra must be restarted to verify the former’s correct operation.
|If you are using the all target to install both Core and Zimlet, the script itself will prompt to start Zimbra.|
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.
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 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.
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.
./install.sh -u allwill uninstall both the Zextras Core and the Zextras Administration Zimlet
./install.sh -u corewill uninstall the Zextras Core
./install.sh -u zimletwill uninstall the Zextras Administration Zimlet
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.
|While the Zextras Suite package includes the Zextras Administration Zimlet, the Zextras Client Zimlet must be deployed separately.|
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.
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.
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
Updating the Zextras Client Zimlet
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.