ZeXtras Suite Installation Guide
From ZeXtras Suite Wiki
- 1 Basic informations
- 2 TL;DR
- 3 Detailed Installation & Setup informations
- 3.1 ZAL - an abstraction layer for Zimbra
- 3.2 Zimbra 8.x Zimbra Administration Console login issue (AjxError)
- 3.3 PermGen and HeapSize warnings
- 3.4 Zimbra Chat removal
- 3.5 Zimbra Upgrade
- 3.6 Minimum requirements and tweaking
- 3.7 ZeXtras Suite on Multiserver infrastructures
- 3.8 General instructions
- 3.9 ZeXtras Suite full Installation
- 3.10 ZeXtras Suite Core Installation
- 3.11 ZeXtras Suite Zimlet Installation
- 3.12 ZeXtras Suite full Upgrade
- 3.13 ZeXtras Suite full Downgrade
- 3.14 ZeXtras Suite Uninstallation
- 4 Post-Install and Post-Uninstall
- 5 Conclusion
|Language:||English • español • português|
No additional software beyond what's required by a standard Zimbra deployment is necessary in order to install ZeXtras Suite.
Where to get the ZeXtras Suite package
Go to the download page on www.zextras.com or simply use wget directly from your server:
(this URL will always point at the latest release of ZeXtras Suite)
ZeXtras Suite is comprised of three major components:
- ZeXtras Suite Core, abbreviated as ZeXtras Core or Core, which is a jar package extending Zimbra
- ZeXtras Suite Administrative Zimlet, abbreviated as ZeXtras Suite Zimlet or just Zimlet, an administrative zimlet which accesses and manages the Core.
- ZAL - An Open Source abstraction layer for Zimbra.
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 .
Below the various combinations are explained in detail.
Other ZeXtras Zimlets
While the ZeXtras Suite package includes the ZeXtras Administration Zimlet, the ZeXtras Chat Zimlet and the ZeXtras Client Zimlet must be deployed severaly. Check the respective ZeXtras Wiki entries for more information.
- Download ZeXtras Suite on your server
- As ROOT, unpack the file you just downloaded inside a directory (we suggest in /root/) in your Zimbra server.
- Enter the directory created by the unpacking of the file.
- Run the install.sh script with the "all" option (so ./install.sh all).
ZeXtras Suite Installation tutorial video
Detailed Installation & Setup informations
ZAL - an abstraction layer for Zimbra
The 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, 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 package. Restarting the installer will detect the new file and install it along with ZeXtras Suite.
Zimbra 8.x Zimbra Administration Console login issue (AjxError)
Zimbra 8.x users might experience slowness and AJAX errors when accessing the Zimbra Administration Console because of the Zimbra DOS Filter. In this case, raising the number of Maximum Requests per Second is suggested (see ZeXtras Suite and the Zimbra DoSFilter for further informations)
PermGen and HeapSize warnings
ZeXtras Suite includes a built-in check to verify that both the "PermGen" and "HeapSize" java properties are set to an appropriate value:
- PermGen: 196mb
- MaxPermGen: 350mb
- Heap: higher than the 20% of installed RAM memory
Albeit this values are not strictly related to ZeXtras Suite, a misconfiguration can lead to instability and crashes of the mailboxd service.
If you received a notification about either one or both this values being undersized you can easily fix this by using the 'zmlocalconfig' zimbra utility to change the following properties:
- mailboxd_java_options (only change the "-XX:PermSize=" and "-XX:MaxPermSize=" parts keeping everything else)
- mailboxd_java_heap_size (in megabytes)
- The "Low PermGen size" warning has been received.
- To check the current value run
root@test:~# su - zimbra zimbra@test:~$ zmlocalconfig mailboxd_java_options mailboxd_java_options = -server -Djava.awt.headless=true -Dsun.net.inetaddr.ttl=60 -XX:+UseConcMarkSweepGC -XX:PermSize=128m \ -XX:MaxPermSize=350m -XX:SoftRefLRUPolicyMSPerMB=1 -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCTimeStamps \ -XX:+PrintGCApplicationStoppedTime -XX:-OmitStackTraceInFastThrow -Djava.net.preferIPv4Stack=true \ -Dorg.apache.jasper.compiler.disablejsr199=true
- To change the PermGen size from 128mb to 196mb run
zimbra@test:~# zmlocalconfig -e mailboxd_java_options="-server -Djava.awt.headless=true -Dsun.net.inetaddr.ttl=60 \ -XX:+UseConcMarkSweepGC -XX:PermSize=196m -XX:MaxPermSize=350m -XX:SoftRefLRUPolicyMSPerMB=1 -verbose:gc -XX:+PrintGCDetails \ -XX:+PrintGCTimeStamps -XX:+PrintGCApplicationStoppedTime -XX:-OmitStackTraceInFastThrow -Djava.net.preferIPv4Stack=true \ -Dorg.apache.jasper.compiler.disablejsr199=true"
Zimbra Chat removal
Starting from version 2.6.1, the Zextras Installer allows to remove the Zimbra Chat component to anyone who is using or wants to use Zextras Chat instead. In order for this to happen, the LDAP and Mailbox services must be up and running as the installer relies on the default `zmzimletctl` command to undeploy the Zimbra Chat zimlet.
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, so after re-installing everything will be exactly as it was before the Zimbra upgrade.
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.
Minimum requirements and tweaking
Zimbra has a minimum RAM requirement of 2GB and a suggested RAM requirement of 4GB. ZeXtras Suite's impact on system resources is neglectible, but we still strongly suggest a minimum RAM of 4GB even for small environments to greatly improve your Zimbra experience.
If you are interested in 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
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 precautions:
- ZeXtras Suite must be installed in ALL the store servers (the ones with the mailboxd service running).
- ZeXtras Suite uses ports 8735 and 8736 for store-to-store communication, make sure your servers can reach each other on this port and that the same port is closed to outside traffic.
- As usual, take your time :)
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-X.X.X.tgz $ ls zextras_suite-X.X.X.tgz zextras_suite-X.X.X/
Inside the directory
zextras_suite-X.X.X one shall find an executable shell script named
$ cd zextras_suite-X.X.X $ ./install.sh -h ./install.sh -h | ./install.sh [ -u ] all|zimlet|core -h This very message -u Uninstall the target The targets available for (un)installation are: core -- ZeXtras Core zimlet -- ZeXtras Suite Zimlet all -- ZeXtras Core followed by ZeXtras Suite Zimlet * In order to use ZeXtras Suite both * core and zimlet need to be installed.
The output of ./install.sh -h will give the user a concise explanation regarding the usage of the installation script.
In order to successfully perform an 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 perform a check of your system determining your Zimbra version and checking for any preexistent installation of either ZeXtras Suite or ZeXtras Migration Tool.
Proceeding with the installation requires for the EULA of ZeXtras to be accepted, after which the actual installation shall take place.
For details regarding the ZeXtras Core or ZeXtras Zimlet installation, see the related sections below.
ZeXtras Suite full Installation
--- RECOMMENDED ---
In order to install ZeXtras Suite you need for both Core and Zimlet to be correctly deployed and functional.
all as target will install Core and Zimlet, in that order, in one go.
Alternatively you can invoke the
install.sh script with either
zimlet as targets, installing each separately
ZeXtras Suite Core Installation
In order to install ZeXtras Core you need for Zimbra services to be stopped beforehand.
You can either stop them before running the script or having them stopped by the script when prompted.
Once that step is cleared the script will perform a series of checks regarding a potential previous installation of ZeXtras Core and eventually install the jar file among the Zimbra extensions.
Deployed the Core, Zimbra will need to 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.)
Once Zimbra is fully started the presence of lines such as the ones below in
/opt/zimbra/log/mailbox.log will mark a successful installation.
INFO [main]  extensions - Initialized extension ZExtrasExtension: com.zextras.extension.ZExtrasExtension@com.zimbra.cs.extension.ZimbraExtensionClassLoader@7543073a [...] INFO [main]  extensions - registered handler at /zextras [...] INFO [main]  extensions - ZExtrasExtension Started
ZeXtras Suite Zimlet Installation
In order to install the ZeXtras Suite Zimlet you need for Zimbra services to be running.
As above, you can either proceed manually beforehand or let the script start them when prompted to do so.
Once Zimbra is active the administrative zimlet will be deployed, provided the core is already installed and both Core and Zimlet versions match.
ZeXtras Suite full Upgrade
In case of a preexistent instance of ZeXtras Suite on your system installing a newer version will automatically perform an upgrade.
See the instructions above for the installation procedure.
If you just upgraded your Zimbra install, please see the Zimbra Upgrade section above.
Upgrading ZeXtras Suite on a Multiserver infrastructure
ZeXtras Suite 2.2.0 introduced backwards compatibility among minor releases, so based on the upgrade you are performing, one among two different upgrade paths must be taken:
- Upgrading ZeXtras Suite 2.2+ to a different micro release (e.g. 2.2.3 to 2.2.4)
- Each separate server can be upgraded independently, and ZeXtras Suite will be fully functional even in a mixed-version environment
- Upgrading from a pre-2.2 release or to a different major release (e.g. 2.0.4 to 2.2.4 or 2.2.4 to 2.4.0)
- 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 full Downgrade
In order to downgrade any components of ZeXtras Suite you need to uninstall them using the installation script from a package of identical or greater version, then install the older versions.
ZeXtras Suite Uninstallation
The removal procedure is mostly similar to the installation one. 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 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 server's cache.
In order to clear your server's Zimlet cache, simply run
zmprov fc zimlet
as the 'zimbra'user.
If you don't reach a successful conclusion, double check step-by-step this guide, or have a look at the ZeXtras Troubleshooting page!