ZeXtras Migration Tool Installation Guide

From ZeXtras Suite Wiki

Jump to: navigation, search
Language: English  • español • português

ZeXtras Migration Tool Installation Guide


No additional software beyond what's required by a standard Zimbra deployment is necessary in order to install ZeXtras Migration Tool.

Where to download the ZeXtras Migration Tool package

Go to the download page on www.zextras.com.

Installation & Setup


ZeXtras Migration Tool is comprised of two major components:

  • ZeXtras Migration Tool Core, abbreviated as Core below, which is a jar package extending Zimbra
  • ZeXtras Migration Tool Zimlet, an administrative zimlet which accesses and manages the Core.

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.

ZeXtras Migration Tool on Multiserver infrastructures

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

Installing ZeXtras Migration Tool on a Single-store infrastructure

Installing ZeXtras Migration Tool 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 Migration Tool on a Multistore infrastructure

ZeXtras Migration Tool installation in a Multistore infrastructure featuring multiple mailbox servers requires the following additional precautions:

  • ZeXtras Migrqation Tool must be installed in ALL the store servers (the ones with the mailboxd service running).
  • Install ZeXtras Migration Tool on your servers one by one. Installing on multiple servers at the same time may clog your logs with errors.
  • If your LDAP Master Server is also a Mailbox server, installing ZeXtras Migration Tool on your servers one by one becomes twice as important.
  • As usual, take your time :)

General instructions

Before installing ZeXtras Migration Tool 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_migration_tool-X.X.X.tgz
$ ls 
zextras_migration_tool-X.X.X.tgz zextras_migration_tool-X.X.X/

Inside the directory zextras_migration_tool-X.X.X one shall find an executable shell script named install.sh.

$ cd zextras_migration_tool-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 Migration Tool Core
zimlet -- ZeXtras Migration Tool Zimlet
all    -- ZeXtras Migration Tool Core followed by ZeXtras Migration Tool Zimlet

* In order to use ZeXtras Migration Tool 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. For example:

$ su -
# ./install.sh all


$ sudo ./install.sh all

Once launched the script will perform a check of your system determining your Zimbra version and checking for any preexistent installation of either ZeXtras Migration Tool or ZeXtras Suite.

Warning.png Warning!

Were any component of ZeXtras Suite detected, you will be prompted to uninstall them (as detailed here) and rerun the ZeXtras Migration Tool installation script afterwards.

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 Migration Tool Core or ZeXtras Migration Tool Zimlet installation, see the related sections below.

ZeXtras Migration Tool full Installation

In order to install ZeXtras Migration Tool you need for both Core and Zimlet to be correctly deployed and functional.
Choosing all as target will install Core and Zimlet, in that order, in one go.
Alternatively you can invoke the install.sh script with either core or zimlet as targets, installing each separately

Warning.png Warning!

Beware: ZeXtras Migration Tool Core and ZeXtras Migration Tool Zimlet MUST match versions, even when installed separately.

ZeXtras Migration Tool Installation tutorial video

Full installation:

./install.sh all

ZeXtras Migration Tool Core Installation

In order to install ZeXtras Migration Tool 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 Migration Tool Core and eventually install the jar file among the Zimbra extensions.

Core-only installation:

./install.sh core

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 Migration Tool Zimlet Installation

In order to install the ZeXtras Migration Tool 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.

Zimlet-only installation:

./install.sh zimlet

ZeXtras Migration Tool full Upgrade

In case of a preexistent instance of ZeXtras Migration Tool on your system installing a newer version will automatically perform an upgrade.
See the instructions above for the installation procedure.

Warning.png Warning!

Core and Zimlet versions MUST always match for ZeXtras Migration Tool to work properly. Be mindful of that if you upgrade the components separately.

ZeXtras Migration Tool full Downgrade

In order to downgrade any components of ZeXtras Migration Tool you need to uninstall them using the installation script from a package of identical or greater version, then install the older versions.
!!! WARNING !!!

Warning.png Warning!

Downgrading might result in existing backups not being recognized correctly by an earlier version of ZeXtras Migration Tool. It is therefore not recommended nor supported.

!!! WARNING !!!

ZeXtras Migration Tool full 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 Migration Tool components and prompt for their removal.
Called with the all target it shall remove ZeXtras Migration Tool Core and after that the ZeXtras Migration Tool Zimlet.

For example:

./install.sh -u all


If you don't reach a successful conclusion, double check step-by-step this guide, or have a look at the ZeXtras Troubleshooting page!


Now that your ZeXtras Migration Tool instance is up and running, should you also wish to make use of it, follow this link to see how.

Personal tools