This section contains various information—requirements, configurationdetails, and guidelines—for a successful installation of ZextrasSuite. Please read carefully next section, Basic Information, tomake sure you do not miss any important piece required to set upZextras Suite.
Basic Information
Prerequisites
To use the Zextras suite, no additional software beyond what’s requiredby a standard Zimbra deployment is necessary in order to install ZextrasSuite. If you did not yet install Zimbra, you can check Zimbra’s SystemRequirements.
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 portstcp 8742 and tcp 8743 respectively, therefore you need to editfile /opt/zimbra/conf/nginx/includes/nginx.conf.web to include thefollowing 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 commandsmust be executed as root, unless differently specified
Minimum Requirements and Tweaking
If you are interested in resources optimization and tweaking, we suggestto read the following article on the Zimbra wiki, which despite thetitle 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 thesystem, which can only contain the following characters up to a maximumlength of 64:
Lowercase and uppercase letters
Number
The following symbols: _ - # ( ) = @
Zimbra IDs containing other characters than the allowed ones will likelycause problems to the Mobile module and possibly to other modules aswell.
Installation possibilities
These are the alternatives to install Zextras:
single-store installation on a single server. This is the easiest andis described in Section Quick Installation Guide.
single-store installation on a multiserver. This approach isequivalent to the previous one and applies when the installation isin a multiserver installation, see Installing Zextras Suite on a Single-store infrastructure.
multistore installation. This approach is required if you need to runmultiple
mailboxdservices, 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 packageextending Zimbra
Zextras Administration Zimlet, abbreviated as Zextras SuiteZimlet or just Zimlet, an administrative zimlet to access and managethe Core.
ZAL - An Open Source abstraction layer for Zimbra. Please readthese advises about ZAL insallation.
The installation script follows the aforementioned structure allowingyou three installation targets: core, zimlet, and all. Thelatter is equivalent of installing Core and immediately afterwardszimlet.
Other Zextras Zimlets
While the Zextras Suite package includes the Zextras AdministrationZimlet, the Zextras Client Zimlet must be deployed separately. Checksection 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 downloadlink after logging inwith their Zextras Store account.
Setup Information
This section contains general information about the set up of thesystem, installation troubleshooting, and important advices about theupgrade to new version of both Zimbra and Zextras.
ZAL - an Abstraction Layer for Zimbra
The Zextras Abstraction Layer (ZAL) is an Open Source abstractionlayer created to allow any extension to easily communicate with ZimbraCollaboration Suite, regardless of the version in use.
It is released under the GPL license and thus cannot be included in theZextras Suite package, but during the installation process the ZextrasInstaller will automatically detect the most appropriate libraryversion and will download and install it autonomously.
Note
Should the automatic download fail, the installation willend. However, a direct download link will be provided: thedownloaded file must be renamed to zal.jar and copied into thepackages/ subdirectory of the Zextras Suite installationpackage. A restart of the installer will detect the new file andinstall it along with Zextras Suite.
The Zimbra DoS Filter
Starting from Zimbra 8.0.0, a connection throttling mechanism calledDoS Filter has been added in order to reduce the impact of Denial ofService attacks. By default the DoS Filter only allows 30 connectionsper second, rejecting any exceeding connection with a 503 HTTPerror.
How the DoS Filter can affect your Zextras Suite experience
Being an Administrative Zimlet, the Zextras Administration Zimlet isloaded upon logging into the Zimbra Administration Console; in order toretrieve all relevant data, many requests are done and this can triggerZimbra’s DoS Filter, causing slowness, AJAX Errors, and general UIcorruption (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 followingone 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 DoSFilter. Each attribute is inherited from global or is configurable at the serverlevel.
Hint
The recommendation is to preserve the default configurationwhenever possible.
DoSFilter Delay (milliseconds) - zimbraHttpDosFilterDelayMillis
Delay is enforced on all requests over the rate limit, before they areconsidered 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 inexcess of this value are throttled. The default is 30 and the minimum is1.
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 thisattribute does not have a default value, nonetheless these loopback IPsare 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 logentry in /opt/zimbra/log/mailbox.log. This log entry should containall of the default whitelisted hosts as well as any IPs added tozimbraHttpThrottleSafeIPs:
2021-03-09 10:33:47,772 INFO [main] [] misc - DoSFilter: Configuredwhitelist 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 theexample below.
Note
Proxy nodes should not need to be whitelisted, as long asthe Originating-IP feature is correctly configured in ZCS, seehttps://wiki.zimbra.com/wiki/Log_Files#Logging_the_Originating_IP.
External hosts that makes SOAP requests for provisioning or any kind ofintegration must be added to the IP whitelist to ensure DoSFilter doesnot block some requests. This is also required whenever there arenetwork resources outside of Zimbra (like e.g., proxies, bouncers,load-balancing servers, firewall, NATting devices) between the clientsand Zimbra). In any of these cases, please refer to the next sections(OIP Logging and non-Zimbra Proxies and ModifyNginx Templates Files for Correct OIP Logging)for more information and directions.
IP addresses should be supplied in the multi-valuedzimbraHttpThrottleSafeIPs attribute.
Hint
Add to zimbraHttpThrottleSafeIPs your private networksand/or IP addresses behind which lay multiple clients.
OIP Logging and non-Zimbra Proxies
This section contains information useful whenever between a Client andZimbra there are proxies or other network devices that are able tomodify the request’s source IP address.
Mailboxd assigns OIP (Originating Client IP Address) valuesfrom the HTTP Request header field X-Forwarded-For.
When a client connects to the Zimbra WebClient through an HTTP proxy ora load balancer and once the traffic is intercepted between clients andservers, the server’s access logs contain the IP address of the proxy orload balancer only. To see the original IP address of the client, theX-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 aproxy that passed the request, adding the IP address where itreceived the request from.
the right-most IP address (<ext-proxyN>) is the IP address of themost 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.yyy22020-08-26 00:19:26.942:INFO:oejs.DoSFilter:qtp1874154700-1750041:: Ignoring malformed remote address xxx.xxx.xxx.xxx, yyy.yyy.yyy.yyy342019-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=152020-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=67ms672020-08-28 00:09:41.837:INFO:oejs.DoSFilter:qtp2036958521-120378:https:: Ignoring malformed remote address xxx.xxx.xxx.xxx, yyy.yyy.yyy.yyy82020-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.xxxis the IP address of the Originating client fromwhere the request originated or was initiated.yyy.yyy.yyy.yyyis the First Proxy server which will send requestto another proxy server or the destination server.
Note
If there are multiple proxy servers, then the left-most willalways be the IP address of the Originating client. If there isonly one proxy server which forwards request directly todestination server, then OIP will have only one entry (i.e. forOriginating 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 patchor zimbra proxy realated installation or upgrade.
Finally, restart the proxy service.
zmproxyctl restart
Note
If multiple zimbra-proxy servers present in the setup, thenmake these changes on all zimbra-proxies.
Zimbra Upgrade
When Zimbra is upgraded, the Zextras Core is removed from the server, soin case of a Zimbra upgrade, Zextras Suite must be reinstalled. All thedata and settings will be maintained, therefore after re-installing theZextras Suite, the set up will be exactly the same as before the Zimbraupgrade.
Warning
Before upgrading your Zimbra server, please make surethat a compatible Zextras Suite version has been released. AZextras Suite compatibility release is usually available within48 hours after the release of a new Zimbra version.
Zimbra Patches
The information above only applies to version upgrades: installing aZimbra patch won’t affect Zextras Suite in any way and thus reinstallingthe 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 adirectory (we suggest in /root/) in your Zimbra server: ‘tar zxfzextras_suite-latest.tgz’
Enter the directory created by the unpacking of the file: ‘cdzextras-suite’
Run the install.sh script with the all option (so ‘./install.shall’).
The installer will take care of downloading the latest availableCore, ZAL and Zimlets for your Zimbra version and start theinstallation.
Zextras Suite on Multiserver infrastructures
Depending on the server roles in use, some additional precautions mustbe taken:
Installing Zextras Suite on a Single-store infrastructure
Installing Zextras Suite on a multiserver infrastructure including asingle mailbox server is just as easy as installing it on asingle-server infrastructure, as the software must only be installed onservers running the mailboxd service.
Installing Zextras Suite on a Multistore infrastructure
Zextras Suite installation in a Multistore infrastructure featuringmultiple mailbox servers requires the following additional setup:
Zextras Suite must be installed on ALL the store servers (i.e.,the ones with the
mailboxdservice running)Zextras Suite uses ports 8735 and 8736 for store-to-storecommunication, therefore make sure your servers can reach each otheron these port and that the same ports is closed to outside traffic.
Detailed Instructions
Before installing Zextras Suite one will need to have downloaded thepackage, as explained in the appropriate section above, and exploded thearchive 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 executableshell script named install.sh, that can be run as ./install.sh-h | ./install.sh [ -u ] [ -d ] all|theme|zimlet|core. Go to thatdirectory and run it with -h to see a quick description of theoptions:
$ cd zextras_suite$ ./install.sh -h-h This very message-d Activates debug mode for the install script-u Uninstall the targetThe targets available for (un)installation are:core -- Zextras Suite Coretheme -- Zextras Suite Themezimlet -- Zextras Suite Zimletall -- 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 aZextras Suite Full Installation or Zextras Suite Full Upgrade, but also astandalone zextras-theme-installer script can be used to installan updated version of the theme.
In order to successfully perform the Zextras suite installation, oneshall need to either become the root user or execute the script withroot privileges (e.g., using sudo).
Once launched, the script will determine the installed Zimbra versionand search for a preexisting installation of either Zextras Suite orZextras Migration Tool.
Warning
Should any component of Zextras Migration Tool bedetected, you will be prompted to uninstall them and run again theZextras Suite installation script afterwards.
Before proceeding with the installation, you will be required to acceptthe EULA of Zextras, after which the actual installation shall takeplace.
Zextras Suite Full Installation
In order to install Zextras Suite you need both Core and Zimlet to becorrectly deployed and operational. By choosing all as target, Coreand Zimlet will be installed in order, in one go.
Full installation:
./install.sh all
You will need to restart Zimbra after the installation has successfullycompleted. 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 servicesbeforehand. This step can be achieved by either stopping them beforerunning the script, or having them stopped by the script when prompted.Afterwards, the script will carry out a series of checks, including forprevious installation of Zextras Core and if needed, it will install thejar file among the Zimbra extensions.
Core-only installation:
./install.sh core
Once the Core has been deployed, Zimbra must be restarted to verify theformer’s correct operation.
Note
If you are using the all target to install both Core andZimlet, the script itself will prompt to start Zimbra.
Zextras Suite Zimlet Installation
Unlike the installation of Zextras Suite Core, in order to install theZextras Suite Zimlet you need Zimbra installed and its services running.As in the Core Installation, you can either proceed manually beforehandor let the script start them after prompting you to do so. Once Zimbrais active the administrative zimlet will be deployed with the versionsmatching Zimbra’s.
Zimlet-only installation:
./install.sh zimlet
Zextras Suite Full Upgrade
In case of an existing instance of Zextras Suite on your system, theinstallation 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 theZimbra 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 upgradedindependently, and Zextras Suite will be fully functional even in anenvironment 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 sametime, as in this case backwards compatibility is not guaranteed andZextras Suite will not be fully functional until all nodes have beenupgraded to the same version.
Zextras Suite Uninstallation
The removal procedure is almost identical to the installation one andplacing the -u switch before the target is all is needed. The scriptwill verify the presence of any Zextras Suite components and prompt fortheir removal.
Therefore:
./install.sh -u allwill uninstall both the Zextras Core and theZextras Administration Zimlet./install.sh -u corewill uninstall the Zextras Core./install.sh -u zimletwill uninstall the Zextras AdministrationZimlet
Post-Install and Post-Uninstall
After either installing or uninstalling Zextras Suite, it’s highlysuggested to clear both your browser’s and the server’s cache; thelatter task can be carried out by running the command:
zmprov fc zimlet
as the zimbra user.
Note
While the Zextras Suite package includes the ZextrasAdministration Zimlet, the Zextras Client Zimlet must be deployedseparately.
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 theZextras Administration Console.
The Zextras Client Zimlet is 100% free, it requires the Zextras Core tobe functional and its deployment is not mandatory. Once deployed, thereare several alternatives to enable it.
Deploy the Zextras Client
Deploying the Zextras Client Zimlet is easy, and can be done via eitherthe 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 ascom_zextras_client.
Issue the dedicated Zextras CLI command
zxsuite core doDeployClientZimlet
Deploying the Zextras Client Zimlet on a multiserver infrastructurerequires the same steps as it does on single server environments. TheZimlet is deployed in LDAP, so you’ll need to only deploy it onceregardless of the number of mailbox servers on your infrastructure.
Enable the Zextras Client
In order to enable the Zextras Client Zimlet, after the deploymentthe Zextras Client Zimlet will be only enabled for users belonging tothe default COS.
You can enable the Zextras Client Zimlet for your users in the followingways:
Per user - through the Zimlets section of each user’s settingswithin the Zimbra Administration Console
Per COS - through the Zimlets section of each Class of Service’ssettings within the Zimbra Administration Console
Via the Zimbra CLI through the
zmzimletctlcommandUpdating the Zextras Client Zimlet
Update the Zextras Client
The Zextras Client Zimlet will be automatically updated by the ZextrasInstaller when updating Zextras Suite. Should this update fail, manuallypressing the Deploy button mentioned above will install the latestversion available.
Remove the Zextras Client
In order to remove the Zextras Client Zimlet, click the Undeploybutton next to the related entry in the Configure → Zimlets section ofthe Zimbra Administration Console or via the Zimbra CLI through thezmzimletctl command.
