Zextras Suite installation guide

Basic information

Prerequisites

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

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: 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

  • 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:

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 Zxclient 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.

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.

Zimbra 8.x Zimbra Administration Console login issue (AJX Error)

Zimbra 8.x users might experience slowness and AJX 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.

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.

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:

  1. Upload to your server the Zextras Suite package you downloaded

  2. 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'

  3. Enter the directory created by the unpacking of the file: 'cd zextras-suite'

  4. Run the install.sh script with the all option (so './install.sh all').

  5. 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.

$ cd zextras_suite
$ ./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 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.

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.

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.

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

Additional Component

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.

By using the Administration Zimlet/console:
  • 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.

By using the Zextras CLI:
  • 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:

  1. Per user - through the Zimlets section of each user’s settings within the Zimbra Administration Console

  2. Per COS - through the Zimlets section of each Class of Service’s settings within the Zimbra Administration Console

  3. Via the Zimbra CLI through the zmzimletctl command

  4. 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.