3.10 Windows Installation

3.10.1 Prerequisites

Before running the Retain installer, you must first ensure that the following are installed and working:

  • IIS or Apache 2.2.x.

  • PowerShell 3.0 or higher.

  • SQL server with appropriate database created SQL Database Guides.

The Retain installation requires an Internet connection to function properly. The Retain install will automatically download and install the appropriate Java Development Kit 1.8 if the server has a connection to the Internet.

NOTE:IIS has a size limit restriction which will limit uploads, or message and attachment archiving to 30MB, by default.

Be sure your server’s clock is accurate before you begin! Using NTP is recommended to keep your clock accurate.

If PowerShell's execution policy is set too restrictively, the install will fail. See Set-ExecutionPolicy.

3.10.2 Webserver Install

Install a webserver.

If using IIS, use the appropriate version for the platform.

3.10.3 Installing ISAPI extensions and filters with IIS

ISAPI filters allow the gathering and manipulation of, and information about Internet traffic on the system. The following are instructions to install ISAPI filters to an existing IIS installation. If IIS is not installed yet, the Web Server (IIS) should be installed as well.

  1. Open the Server Manager.

  2. In Server Manager, click the Manage menu, and then click Add Roles and Features.

  3. In the Add Roles and Features wizard, click Next. Select the installation type and click Next. Select the destination server and click Next.

  4. On the Server Roles page, expand Web Server (IIS), expand Web Server, expand Application Development, and then select ISAPI Filters and ISAPI Extensions. Click Next.

  5. On the Select features page, click Next.

  6. On the Confirm installation selections page, click Install.

  7. On the Results page, click Close.

If using Apache, download the 2.2.x binary for Windows from apache.org, (choose HTTP Server from left side). Install normally, accepting all prompts. Retain only supports version 2.2.x.

Once Apache and a SQL server are installed, the system is prepared to install Retain’s core components.

The install will complete the following tasks:

  • Java Development Kit 1.8 (JDK) will be checked/installed.

  • Retain Tomcat 7/8 and any existing Retain installation will be stopped.

  • Retain will be installed.

  • Retain Tomcat 8 is restarted and set to run as a system service.

3.10.4 Retain Install

  1. Download the latest version of Retain.

  2. Extract the archive. This will extract into a new folder.

    Right-click and select "Extract All..."

  3. Unzip the downloaded Retain install package to a work directory. Almost any name will do, as long as you remember it.

  4. Run “RetainInstall.exe”. NOTE: If it already exists, Tomcat will be automatically shut down by the installer.

  5. The Retain Setup Wizard welcomes you to the installer.

  6. The Wizard reminds you of the Software Requirements. Click ‘Next’ to continue.

  7. Agree to the license agreement.

  8. Select the install location.

  9. Select the program features to install. (Retain Server, Stubbing Server, Retain Worker, Reporting and Monitoring Server, and the Message Router.)

    9a. If upgrading, previously installed components will be preselected and you will be able to select additional modules to install.

  10. Pre-requirements status is displayed. Installer attempts to detect previous Tomcat installations.

    If none are found, it asks whether Tomcat has been installed. Indicate ‘yes’ or ‘no’.

    If upgrading, Tomcat 7.0 will be upgraded to Tomcat 8.0.

    Please note that the environment variable ‘RETAIN_CATALINA_HOME’ is set after Tomcat installation.

    Click ‘Next’ to continue.

    Java and Tomcat are installed or upgraded. (Note: If there are issues with Apache and Tomcat starting correctly, set the Java initial memory pool and the maximum memory pool to the same value, appropriate to the system and expected load.) Tomcat is run as a System Service and shows up in the system services list as “Retain Tomcat 8”. (Start | Run | services.msc)

    10a. If an Internet connection cannot be made, the installer will ask to retry, abort, or for the local path to the Java installation package. The Java installer can be downloaded from:

  11. Select either Apache or IIS. (If apache, provide the installation directory.)

  12. If a previous version of Retain is detected, upgrade options are displayed; Overwrite or Upgrade. Generally, you will want to choose Upgrade. Click Next.

  13. Confirm settings and select 'Install'.

  14. The product will install.

  15. If Microsoft C++ 2005 Runtime distribution is not installed, the appropriate version will automatically be installed.

  16. The Setup Wizard thanks you for installing Retain.

  17. The Setup Wizard shows you the URL to the Retain admin console.

  18. The Retain installation process is complete. Click Finish.

  19. If using MySQL, stop tomcat Starting and Stopping Tomcat service and install the MySQL Connector/J MySQL Connector/J (JDBC driver for MySQL) Installation, then start tomcat.

  20. Browse to the Retain web console URL and complete the initial setup.

3.10.5 Controlling Tomcat

Tomcat may be started, stopped or restarted from the Services program.

3.10.6 Installing Just a Worker to a Server

The Worker may be installed on a server other than the Retain server itself. For example, the worker may be installed on the email server or on a dedicated worker server.

This is much simpler than installing the entire Retain server system. It only requires installing the webserver and the worker agent software. It uses the same installer as above.


  1. Install the web server (IIS with ISAPI filter, as above).

Pre-install tasks:

  1. Download the latest version of Retain.

  2. Extract the archive. This will extract into a new folder.

    In the GUI right-click and select "Extract All..."

  3. Run the installer, RetainInstall.exe, as above.

  4. Select only "Worker" as the component to install.

  5. Finish the install as normal.

  6. Workers are accessed by browsing to http://[IPAddress or HostName]/RetainWorker

3.10.7 Installing Additional Workers on Windows


In larger email systems, it can take a long time to dredge all the users especially if the users are on multiple mail servers. You can install multiple workers that can run in parallel to speed up the archiving process. We generally recommend one worker per mail server. The Retain installer can install up to 10 workers on a single server. We recommend an additional 1GB for RAM per worker. Workers are accessed by browsing to http://[IPAddress or HostName]/RetainWorkerN

The Retain installer allows you to install up to nine workers at once.


  1. Run the RetainInstall.exe and install at least one Worker or upgrade the existing installation, if you haven't already done so.

  2. From the command line (run as Administrator), type RetainInstall.exe /AddWorker to start the installer in Add Worker Mode.

  3. Acknowledge requirements.

  4. Accept the license agreement.

  5. Confirm the install location of Retain.

  6. Enter the number (1-9) of Worker agents to install. They will be installed in numerical order (e.g. RetainWorker, RetainWorker1, RetainWorker2..., RetainWorker9).

  7. Confirm which webserver is installed.

  8. Install the Worker agent software. After installing and acknowledging the location of the documentation the installer will show you how to access the Workers that were just installed.

  9. Log into the Retain web console as admin

  10. Create a new Worker and download the Bootstrap for each new Worker you installed. You may save it with a different name to organize it.

  11. Browse to the new Worker at http://[ServerAddress]/RetainWorkerN where N is the number of the worker you just installed.

  12. Upload the bootstrap.

  13. Click Continue and login to the worker.

  14. Check the friendly name that it is the one you expect.

There is a separate log file for each worker, found in C:\Program Files\Beginfinite\Retain\Tomcat 8.0\logs\RetainWorkerN.yyyy-mm-dd.log unless otherwise specified in Configure Tomcat.