OpenText Retain CE 24.

2
Installation and Upgrade
April 2024
 Legal Notice
Copyright 2023-2024 Open Text

The only warranties for products and services of Open Text and its affiliates and licensors (“Open Text”) are as may be set
forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as
constituting an additional warranty. Open Text shall not be liable for technical or editorial errors or omissions contained
herein. The information contained herein is subject to change without notice.

2
Contents

Preface 7
About Retain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
For Documentation Feedback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
To Join the Retain Idea Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
For Additional Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
To Contact Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
For Sales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
For Professional Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1 Installing Retain 24.2 9

Retain Deployment Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Installing a Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Linux Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Windows Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
(Optional) Apache Install on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Creating and Maintaining an SQL Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
The Database Is Your Responsibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
The Database’s Role in Retain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Never Use NFS Shares in a Database System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
If You Need a Secure Database Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Basic Setup Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Example Instructions for Your Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Installing a Retain Server on Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Retain Prerequisites for Linux Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Downloading and Preparing the Retain Installation Files on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Installing the Retain Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Installing a Retain Server on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Downloading and Preparing the Retain Windows Installation Source Files . . . . . . . . . . . . . . . . . . . . 24
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Retain Install. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Running the Retain Server Configuration Wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Retain’s Browser-based Management Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Logging In as an Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Retain Server Administrative Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Always Remember to Save Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
About Retain Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
The Licensing Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Installing Your Retain Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Backing Up Retain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Where Data Is Stored In Retain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Backing Up Retain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
General Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Un-installing Retain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Contents 3
 Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Installing Other Retain Components on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Deploying Production-Use Worker Agents on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Installing a Retain Message Router on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Installing Other Retain Components on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Installing Additional Retain Workers on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Installing a Retain Message Router on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Starting and Stopping the Retain Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

2 Upgrading to Retain 23.4 and Later 55

Preparing to Upgrade to 23.4 and Later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Prerequisites for Upgrading to 23.4 and Later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Installing Java on a Server with no Internet Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Upgrading from 23.2 or 23.3 to 23.4 and Later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Preparing to Upgrade to 23.4 and Later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Upgrading to 23.4 and Later (SLES) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Upgrading to 23.4 and Later (Windows) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Updating to the Solr 9 Indexing Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Upgrading from 4.11 to 23.4 and Later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Preparing to Upgrade to 23.4 and Later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Upgrading to 23.4 and Later(SLES) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Upgrading to 23.4 and Later (Windows) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

3 Moving Retain to a New Server 67

Moving Retain from Windows to Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Preparation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Moving Retain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Moving Retain from Linux to Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Preparation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Moving Retain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Moving Retain To a Different Windows Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Preparation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Moving Retain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Moving Retain To a Different Linux Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Preparation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Move the MySQL Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

4 Moving a MySQL Database to Another Server 83

Linux to Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Linux or Windows to Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

5 Upgrading MySQL to a New Version 87

Upgrading MySQL on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

4 Contents
Upgrading MySQL on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Contents 5
6
 Preface

About Retain
Retain Unified Archiving
 Archives email and text messages.
 Catalogs them for search and retrieval.

Retain is not a backup/restore system.

About This Guide

This is the installation and upgrade documentation for Retain Unified Archiving version 24.2.

For Documentation Feedback

Scroll to the bottom of the online page and enter a User Comment.

To Join the Retain Idea Exchange

Got an idea for a new Retain feature or enhancement? Log in to official website and join the
conversations happening inside the Retain Idea Exchange.

For Additional Documentation

See the OpenText Knowledge Base website.

To Contact Technical Support

Browse to the OpenText Support Page and begin typing Retain Unified Archiving in the Search for a
Product field.

For Sales
Go to the OpenText Contact page.

For Professional Services

Contact OpenText Professional Services by sending an email to [email protected] or calling
(877) 772-4450.

Preface 7
8 Preface
1 Installing Retain 24.2
1

 “Retain Deployment Checklist” on page 9

 “Installing a Web Server” on page 10
 “Creating and Maintaining an SQL Database” on page 11
 “Installing a Retain Server on Linux” on page 21
 “Installing a Retain Server on Windows” on page 24
 “Running the Retain Server Configuration Wizard” on page 34
 “Retain’s Browser-based Management Tool” on page 38
 “Licensing” on page 41
 “Backing Up Retain” on page 43
 “General Maintenance” on page 47
 “Un-installing Retain” on page 48
 “Installing Other Retain Components on Linux” on page 49
 “Installing Other Retain Components on Windows” on page 51
 “Starting and Stopping the Retain Server” on page 53

Retain Deployment Checklist

For a successful Retain deployment, complete the following tasks in the order listed, choosing those
that apply to your deployment.
1. Get a copy of your company’s retention policy and follow it as you work through the “Retain
Planning and Design Best Practices” in OpenText Retain CE 24.2: Planning.
2. Identify Retain admin credentials you plan to use.
3. Gather and document the SMTP host connection information.
4. Install a web server. See “Installing a Web Server” on page 10
5. Gather the database connection information, DNS name or IP address, Retain database name,
retain database user name and password.
6. Create a database for Retain to use. See “Creating and Maintaining an SQL Database” on
page 11
7. Download and install Retain on your chosen platform:
 Linux: “Installing a Retain Server on Linux” on page 21
 Windows: “Installing a Retain Server on Windows” on page 24
8. If desired, set custom storage paths. See “Setting Custom Storage Path Rights on Linux” in
OpenText Retain CE 24.2: Planning.
9. Configure the Retain server. “Running the Retain Server Configuration Wizard” on page 34.

Installing Retain 24.2 9

 10. Install the production Retain Worker Agents.
 Linux: “Deploying Production-Use Worker Agents on Linux” on page 49
 Windows: “Installing Additional Retain Workers on Windows” on page 51
11. If archiving mobile devices, install the Retain Router. “Installing a Retain Message Router on
Linux” on page 50 or “Installing a Retain Message Router on Windows” on page 53
12. Access Retain’s management interface. “Logging In as an Administrator” on page 38
13. Configure Reporting and Monitoring. See “Configuring the R&M Server” in OpenText
Retain CE 24.2 : Configuration and Administration.
14. Create and configure jobs for the systems you are archiving.
15. Configure the Reports you need. See “Retain’s Reports” in OpenText Retain CE 24.2 :
Configuration and Administration.
16. Confirm that data is being archived. See “Using Retain’s Archives” in OpenText Retain CE 24.2:
User Guide.
17. Upload the required licenses. “Licensing” on page 41
18. Set up the Tools your deployment needs. See “Tools Overview” in OpenText Retain CE 24.2: User
Guide.

Installing a Web Server

Retain requires a web server on each server running a Retain component (Server, Worker, etc.).

Linux Web Server

1 Install the Apache Web Server distributed with your SLES server.
2 Make sure you also select and install the following Apache components:
 apache2-mod_jk - Connectors between Apache and Tomcat Servlet Container
 apache2-prefork - Apache 2 "prefork" MPM (Multi-Processing Module)
 apache2-worker - Apache 2 worker MPM (Multi-Processing Module)

Windows Web Server

NOTE: OpenText recommends using IIS on Windows, but Apache can be used if necessary. See the
Apache web site for installation instructions.
If you must use Apache instead of IIS, skip to “(Optional) Apache Install on Windows” on page 11.
Otherwise, continue with this section.

1 If you are using IIS and it is not already installed, install it now along with the ISAPI Extensions
and Filters.
The ISAPI Extensions and Filters allow Retain to gather and manipulate information about
Internet traffic on the system.

10 Installing Retain 24.2

 2 If your system has IIS installed and running without the ISAPI components, do the following:
2a Open the Server Manager.
2b In Server Manager, click the Manage menu, then click Add Roles and Features.
2c In the Add Roles and Features wizard, click Next.
2d Select the installation type and click Next.
2e Select the destination server and click Next.
2f On the Server Roles page, expand Web Server (IIS), expand Web Server, expand Application
Development, and then select ISAPI Filters and ISAPI Extensions.
2g Click Next.
2h On the Select Features page, click Next.
2i On the Confirm Installation Selections page, click Install.
2j On the Results page, click Close.

(Optional) Apache Install on Windows

If you need to use Apache instead of IIS, do the following:
1. Download the 2.4 binary for Windows from apache.org.

IMPORTANT: Retain only supports version 2.4.

2. Install normally, accepting all of the defaults.

Creating and Maintaining an SQL Database

 “The Database Is Your Responsibility” on page 11
 “The Database’s Role in Retain” on page 12
 “Never Use NFS Shares in a Database System.” on page 12
 “If You Need a Secure Database Connection” on page 12
 “Basic Setup Overview” on page 12
 “Example Instructions for Your Reference” on page 13

The Database Is Your Responsibility

IMPORTANT: Your organization is entirely responsible for the Retain database.
OpenText strongly recommends that it be installed, configured, tuned, and maintained on one of the
supported database platforms by qualified database administrators. See “SQL Database” in OpenText
Retain CE 24.2: Planning.
Providing adequate instructions for the above tasks on the various Retain-supported database
platforms is well beyond the scope of this guide.

Installing Retain 24.2 11

 The setup and configuration instructions in “Example Instructions for Your Reference” on page 13
are only for proof-of-concept deployment use.

The Database’s Role in Retain

Retain stores header data and pointers to the Retain datastore in an SQL database.
Retain administrators are responsible to ensure that Retain databases are properly installed,
configured, tuned, and maintained.

Never Use NFS Shares in a Database System.

NFS locking is insufficient for database requirements and results in corruption.

If You Need a Secure Database Connection

You can secure the connection between Retain and all the supported database types (MariaDB,
MySQL, Oracle, PostgreSQL, and MSSQL). See “Securing the Database Connection” in the OpenText
Retain CE 24.2: Planning guide. For configuring SSL on your database, refer to the sections on the
Vendor document where the SSL configuration details are provided for each database type.

Basic Setup Overview

Setting up the Retain database involves the following general steps:
1. Download a supported database platform. See “SQL Database” in OpenText Retain CE 24.2:
Planning.
2. Install it on one of the following, according to your organization’s needs:
 A dedicated database server (recommended).
 The Retain server itself for a small, all-in-one deployment.
3. Create a database for Retain to use.
4. Create a user/role with ownership rights to the database that you just created.

IMPORTANT: Deploying Retain requires that you provide:

 The database name
 The database user’s/role’s name
 The user’s/role’s password

12 Installing Retain 24.2

Example Instructions for Your Reference
The following sections contain sample instructions and tips that might be useful if you are setting up
a proof-of-concept Retain deployment.
They are not adequate for deploying Retain in a production environment, which requires assistance
from a qualified database administrator.
 “MySQL” on page 13
 “MS SQL Server 2022, 2019, 2017, and 2016” on page 14
 “ORACLE” on page 15
 “Postgres 10.9” on page 17
 “MariaDB 10.x and 11.1.2” on page 17
 “Further Database Tuning” on page 18

MySQL
1. Download and install the latest MySQL server and client and configure according to local system
needs.
a. Install the server: rpm -ivh MySQL-server-version.sles11.x86_64.rpm
b. install the client: rpm -ivh MySQL-client-version.sles11.x86_64.rpm
c. Modify /usr/my.cnf, to move the database to a data volume, by adding the line datadir=/
path/to/where/you/want/the/MySQL/data
d. Find the root password in /root/.mysql_secret
cat /root/.mysql_secret
e. Start MySQL:
rcmysql start
f. Change the root password:
/usr/bin/mysql_secure_installation
2. Log in to MySQL using the client:
mysql -u root -p
3. Create the database: * This is critical. Not storing the database in UTF-8 format guarantees
irreparable corruption for non-US-ASCII characters. *
CREATE DATABASE retain DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE
utf8mb4_unicode_ci;
a. If you make a mistake, enter this command:
DROP DATABASE retain;
b. Then repeat step 3 to create the database.
4. This step depends on which version of MySQL you are using.
 For MySQL 5.x: Retain needs to be configured with a user account that you grant full rights
to the Retain database.

IMPORTANT: OpenText strongly recommends against using the ‘root’ account.

Installing Retain 24.2 13

 While logged in to MySQL, enter the following commands, replacing UserName and
Password with the desired user name and password.
 GRANT ALL PRIVILEGES ON retain.* TO 'UserName'@'%' IDENTIFIED BY
'Password';
To restrict the connection to a specific IP address, replace the percentage sign (%) with
the address.
 GRANT ALL PRIVILEGES ON retain.* TO 'UserName'@'localhost'
IDENTIFIED BY 'Password';
For example, if the database user's name is retainuser, the password is P@ssword1,
and you want database access restricted to 192.168.1.142:
 GRANT ALL PRIVILEGES ON retain.* TO 'retainuser'@'192.168.1.142'
IDENTIFIED BY 'P@ssword1';
 GRANT ALL PRIVILEGES ON retain.* TO 'retainuser'@'localhost'
IDENTIFIED BY 'P@ssword1';
 For MySQL 8.x: You need to create the user account and then grant it full rights to the
Retain database.
While logged in to MySQL, enter the following commands, replacing UserName and
Password with the desired user name and password.
 CREATE USER ' UserName' IDENTIFIED WITH mysql_native_password BY
' Password';
 CREATE USER ' UserName'@'localhost' IDENTIFIED WITH
mysql_native_password BY ' Password';
 GRANT ALL PRIVILEGES ON retain.* TO ' UserName'@'localhost';
 GRANT ALL PRIVILEGES ON retain.* TO ' UserName'@'%';
If you run the mysql-database on the same server as the Retain-Server you can add the
following option to your my.cnf-configuration:
[mysqld]
default-authentication-plugin=mysql_native_password

MS SQL Server 2022, 2019, 2017, and 2016

1. Install as a default instance, with Latin1_ General_CI_AS as the encoding standard.
2. Enable SQL Server Authentication in addition to Windows Authentication.
3. Once installed, verify the server is listening on port 1433. At the command prompt, run:
telnet <IP address> 1433
4. Ensure TCP/IP is enabled - Run SQL Server Configuration Manager
5. Expand SQL Server Network Configuration
6. Protocols for MSSQLSERVER
7. Enable TCP/IP
8. Run SQL Server Management Studio, connect to the Server.
9. Under Security/Logins, right-click and select create Login, (for example Retainuser) that uses SQL
Server authentication.

14 Installing Retain 24.2

10. Assign a password.
11. Right click Databases, create a new database named Retain and assign Retainuser as the owner.

ORACLE
Retain supports the usage of Oracle databases on all platforms. (For more information, see
“Database Platforms” in the OpenText Retain CE 24.2: Planning guide.)
However, it is the customer’s responsibility to employ an experienced Oracle DBA to install,
maintain, and tune Oracle.
The instructions below serve as a guideline, but may result in poorly performing, insecure
environments.
Oracle Installation instructions vary widely depending on the version, OS, storage configuration,
clustering, and so on. There is no one-size-fits-all.
This is also true of other SQL Server products, but especially for Oracle, which is why relying on a
DBA is so critical.
Using Oracle with Retain requires the following tasks:
 “Installing the Oracle Server” on page 15
 “Setting Up a TCPIP Listener” on page 15
 “Creating a Database Named Retain” on page 15
 “Creating a User Account to Access the Retain Database” on page 16
 “Tuning Oracle” on page 17

Installing the Oracle Server

Install your Oracle Server normally, according to your standards and practices. One option is to use
the Universal Installer, specifying a custom installation, choose the type of Oracle Server to install,
and to Install Files Only

Setting Up a TCPIP Listener

Next use the Net Configuration Assistant (or manually edit the Oracle Listener configuration) to
create a TCP based listener on port 1521. This allows TCPIP clients to connect to Oracle and is
required for Retain.

Creating a Database Named Retain

Next, either use the Database Configuration Assistant or manually create the database with your
favorite tool. Regardless, you want to create a database and sid, named Retain, and create your
SYSTEM account
An example of a create statement (do not use as is):

Installing Retain 24.2 15

 connect "SYS"/"&&sysPassword" as SYSDBA
set echo on
spool C:\oracle\product\10.2.0\admin\Retain\scripts\CreateDB.log
startup nomount
pfile="C:\oracle\product\10.2.0\admin\Retain\scripts\init.ora";
CREATE DATABASE "Retain"
MAXINSTANCES 8
MAXLOGHISTORY 1
MAXLOGFILES 16
MAXLOGMEMBERS 3
MAXDATAFILES 100
DATAFILE 'C:\oracle\product\10.2.0\oradata\Retain\system01.dbf' SIZE 300M
REUSE AUTOEXTEND ON NEXT 10240K MAXSIZE UNLIMITED
EXTENT MANAGEMENT LOCAL
SYSAUX DATAFILE 'C:\oracle\product\10.2.0\oradata\Retain\sysaux01.dbf'
SIZE 120M REUSE AUTOEXTEND ON NEXT 10240K MAXSIZE UNLIMITED
SMALLFILE DEFAULT TEMPORARY TABLESPACE TEMP TEMPFILE
'C:\oracle\product\10.2.0\oradata\Retain\temp01.dbf' SIZE 20M REUSE
AUTOEXTEND ON NEXT 640K MAXSIZE UNLIMITED
SMALLFILE UNDO TABLESPACE "UNDOTBS1" DATAFILE
'C:\oracle\product\10.2.0\oradata\Retain\undotbs01.dbf' SIZE 200M REUSE
AUTOEXTEND ON NEXT 5120K MAXSIZE UNLIMITED
CHARACTER SET AL32UTF8
NATIONAL CHARACTER SET AL16UTF16
LOGFILE GROUP 1 ('C:\oracle\product\10.2.0\oradata\Retain\redo01.log')
SIZE 51200K,
GROUP 2 ('C:\oracle\product\10.2.0\oradata\Retain\redo02.log') SIZE
51200K,
GROUP 3 ('C:\oracle\product\10.2.0\oradata\Retain\redo03.log') SIZE 51200K
USER SYS IDENTIFIED BY "&&sysPassword" USER SYSTEM IDENTIFIED BY
"&&systemPassword";
spool off
The most critical items to note are the CHARACTER SET (AL32UTF8 aka UTF8), and the NATIONAL
CHARACTER SET (AL16UTF16). If using a GUI based installed, make sure that you set these because
they are easily missed. (They are located on the Encoding tab of the 10th step or so in the wizard).

Creating a User Account to Access the Retain Database

Finally, using the SYSTEM account, connect to the database, create a user, and grant full system
privileges to the account. An example is shown below:
CREATE USER user-name IDENTIFIED BY password;
grant dba to user-name;
Restart everything, and verify you can telnet on the TCP LISTENER's PORT (1521 if as above).
If a restricted user is desired, Retain requires a user with the following role:
 RESOURCE CONNECT

And the following database privileges to the Retain database:

 CREATE PROCEDURE
 CREATE SESSION

16 Installing Retain 24.2

  CREATE SYNONYM
 CREATE TABLE
 CREATE TYPE
 CREATE VIEW

Tuning Oracle
Tuning Oracle is well beyond the scope of this manual and requires Oracle's online guides, as well as
an experienced DBA or extensive training.

Postgres 10.9
When creating a PostgreSQL database for use by Retain, specify UTF8 encoding.
If the Retain Server is on a different machine, you must configure PostgreSQL to accept connections
from that machine's IP address.
1. Connect to PostgreSQL using its psql utility.
2. Create a new database and user for use by Retain. The example below creates a user named
"retainuser":
CREATE DATABASE retain WITH OWNER = retainuser ENCODING = 'UTF8' TABLESPACE = pg_default
CONNECTION LIMIT = -1;

MariaDB 10.x and 11.1.2

You install MariaDB using YaST.
Log into MariaDB, and set up the Retain database and user.
1. Create the database: * This is critical. Not storing the database in UTF-8 format guarantees
irreparable corruption for non-US-ASCII characters. *
CREATE DATABASE retain DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE
utf8mb4_unicode_ci;
a. If you make a mistake, enter this command:
DROP DATABASE retain;
b. The repeat this step to create the database.
2. Retain needs a user account created that has full rights to the Retain database.

IMPORTANT: OpenText strongly recommends against using the ‘root’ account.

While logged in to MariaDB, enter the following commands, replacing UserName and Password
with the desired user name and password
Both commands are needed. The ‘%’ is a wildcard. If you want to restrict the connection to a
specific IP address, specify the address instead of the ‘%’ sign.):
GRANT ALL PRIVILEGES ON retain.* TO 'UserName'@'%' IDENTIFIED BY
'Password';

Installing Retain 24.2 17

 GRANT ALL PRIVILEGES ON retain.* TO 'UserName'@'localhost' IDENTIFIED
BY 'Password';
For example, if the database user's name is "retainuser" and the password is "P@ssword1":
GRANT ALL PRIVILEGES ON retain.* TO 'retainuser'@'%' IDENTIFIED BY
'P@ssword1';
GRANT ALL PRIVILEGES ON retain.* TO 'retainuser'@'localhost' IDENTIFIED
BY 'P@ssword1';

Further Database Tuning

You are responsible to tune the SQL Database Server. Tuning database servers for performance often
requires an experienced DBA.
You are also responsible for backing up, managing storage, and ensure that the database is fault
tolerant.

MySQL
You should periodically optimize the Retain tables in order to achieve optimum query and update
performance. This can have a big impact on the performance of archive jobs, deletion jobs, etc. It is
also a good idea to optimize the memory settings for MySQL.

Backing Up the Database

Be sure to back up (dump) the database (https://support.microfocus.com/kb/doc.php?id=7019083)
before performing any maintenance. If on a VM, you can alternatively back up the VM or take a
snapshot.

Optimizing Tables

WARNING: This should be done during a maintenance window because it locks the tables and can
take hours to complete (or days for larger databases).
The time required is a function of the number of records in the tables, the power of the underlying
hardware, and the RAM available. The more innodb_buffer_pool_size you can give to MySQL, the
more tablespace it can load into RAM as explained here (https://dev.mysql.com/doc/refman/5.5/en/
glossary.html#glos_buffer_pool).

Like hard disks, database tables' indexes can become fragmented resulting in poor performance.
Optimizing tables can dramatically improve archive job and deletion job performance.
At the command prompt, type: mysqlcheck -o -u root -p retain
 "-o" instructs it to optimize all tables in the database.
 "-u root" specifies the user "root".
 "-p" causes it to prompt for the retain database password.
 "retain" instructs it to run against the "retain" database (or whatever you named it during
installation - "retain" is the default).
The command above optimizes all Retain tables at once. However, many are static and would not
necessarily be subject to fragmentation issues.

18 Installing Retain 24.2

Paste the following query into the MySQL prompt after logging into MySQL. This optimizes the tables
one at a time.
These are the Retain tables you might consider optimizing:
OPTIMIZE TABLE retain.Audit;
OPTIMIZE TABLE retain.s_AddressBookCache;
OPTIMIZE TABLE retain.t_abook;
OPTIMIZE TABLE retain.t_document;
OPTIMIZE TABLE retain.t_dsref;
OPTIMIZE TABLE retain.t_message;
OPTIMIZE TABLE retain.t_message_attachments;
OPTIMIZE TABLE retain.t_message_properties;
OPTIMIZE TABLE retain.t_message_recipients;
OPTIMIZE TABLE retain.t_recipient;
You can check on the progress of the queries by opening a separate terminal window and launching
the following command:
watch -n 1 "mysqladmin -u root -p[password] processlist"
(note: no space between "-p" and your mysql root user password!)

NOTE: Retain uses the innoDB engine in MySQL, which does not support the optimize option;
however, running this option automatically performs a re-create action on the tables, which
eliminates the fragmentation. There might be better ways to accomplish this, so this information is
supplied to point you in the right direction.

For more detailed information and other mysqlcheck options, you may want to research this on the
Internet. For your convenience, here are a couple of helpful articles:
4.5.3. mysqlcheck - A Table Maintenance Program (http://dev.mysql.com/doc/refman/5.0/en/
mysqlcheck.html#option_mysqlcheck_analyze)
MySQL Back to Basics: Analyze, Check, Optimize, and Repair (http://www.pythian.com/blog/mysql-
back-to-basics-analyze-check-optimize-and-repair/) (written in 2008)
MySQL Reference Manual on getting a dump of a corrupted database (http://dev.mysql.com/doc/
refman/5.5/en/forcing-innodb-recovery.html) This is sometimes the only option for recovering data
from a corrupted INNODB database.

Memory Optimization
Memory for your innoDB can be configured in /etc/my.cnf (Linux) or on Windows, in the
[drive]:\Program Files\MySQL\MySQL Server 5.x/my.ini file (where "x" is the MySQL
version).
You'll find the following section in your my.cnf and there are identical lines in the my.ini on
Windows although they may not be in this same order. The settings you may want to consider
modifying are in red. This is followed by indented explanations in blue and are additional comments
made for this article - those additional comments are not found in the my.cnf or my.ini.
Be sure to stop tomcat “Starting and Stopping the Retain Server” on page 53 before working with
MySQL.

Installing Retain 24.2 19

 # Uncomment the following if you are using InnoDB tables. If it does not exist, create it.
innodb_file_per_table
The "innodb_file_per_table" is not included in the default my.cnf or my.ini and has to be typed in
manually. It causes MySQL to create an .idx file for every table in the database. The benefits of this is
up for debate. Some swear by it because they feel it eliminates contention for a single file containing
all the tables (ibdata1); however, others have written that it is fast at first and then bogs down. We
have found that, for Retain databases, it seems to positively impact performance. Do your own
research and determine what is best for your system.
#innodb_data_home_dir = /var/lib/mysql
#innodb_data_file_path = ibdata1:10M:autoextend
#innodb_log_group_home_dir = /var/lib/mysql
# You can set .._buffer_pool_size up to 50 - 80 %
# of RAM but beware of setting memory usage too high
innodb_buffer_pool_size = 4G
This allocates buffer memory for MySQL (https://dev.mysql.com/doc/refman/5.5/en/
glossary.html#glos_buffer_pool) into which it can load table and index data. Obviously, accessing
RAM is faster than disk, so the more memory you can give for the buffer pool, the more MySQL can
load into the buffer. MySQL uses memory for other things, so if you have 6G to play with, you
probably do not want the buffer pool to be larger than 4G. You'll have to experiment on your own
system.
A helpful tool that is free is called mysqltuner.pl. It is a perl script that runs against your database to
help you tune it's memory, security, etc. To get it, create a directory on your Linux server and change
to that directory. Then type: wget mysqltuner.pl. Once it is down donwloading (takes 1 second),
type: chmod +x *.pl so that it can be executed; then, execute it by typing: ./mysqltuner.pl.
innodb_additional_mem_pool_size = 204M
From what we've seen, this should be set to 5% of the buffer pool size. But, again, do your research.
# Set .._log_file_size to 25 % of buffer pool size
innodb_log_file_size = 1024M
This affects the ib_logfile0 and ib_logfile1 files in your MySQL data directory. These files hold
statements/transactions. The maximum size these can be set to (regardless of your buffer pool size)
is 1024M (or 1G, totaling 2 GB for all log files together) for MySQL 5.5 and 255 G (total for all log files
together can be up to 512 GB) for 5.6. For more information check out the MySQL website here
(http://dev.mysql.com/doc/refman/5.6/en/innodb-parameters.html#sysvar_innodb_log_file_size).
There is also some discussion on what values you should set the log files to (see https://
www.percona.com/blog/2008/11/21/how-to-calculate-a-good-innodb-log-file-size/ (https://
www.percona.com/blog/2008/11/21/how-to-calculate-a-good-innodb-log-file-size/). The maximum
size these can be set to is 1024M.

IMPORTANT: If you change this setting, it would be a good idea to flush the existing logs (ib_logfile0
and ib_logfile1). To do this, take the following steps:
a) Log into MySQL: mysql -u root -p
b) From the MySQL prompt, type: SET GLOBAL innodb_fast_shutdown=0;
Then type "quit" to log out of MySQL.
c) Shut down MySQL: rcmysql stop

20 Installing Retain 24.2

 d) Rename the ib_logfile0 and ib_logfile1 files.
g) Start up MySQL: rcmysql start
h) If MySQL starts up successfully, you can delete the ib_logfile* files.
If you do not delete or move the exisiting ib_logfile0 and ib_logfile1 files from the MySQL data
directory when changing the logfile size, MySQL does not load.
innodb_log_buffer_size = 8M
The log buffer allows transactions to run without having to write the log to disk before the
transactions commit. If the transactions are large, then making the log buffer larger saves disk I/O.
There is a status called "innodb_log_waits" in MySQL. This shows the number of times a wait was
required for it to be flushed before continuing. If you have any waits, then the buffer size is too small.
Here is the query you can run on that status: SHOW GLOBAL STATUS LIKE 'innodb_log_waits';

#innodb_flush_log_at_trx_commit = 1
#innodb_lock_wait_timeout = 50
To enable any one of those settings, remove the hash mark ("#") preceding it. The following is an
example for a typical system that has 16G of total RAM, where 2G is allocated for the Linux OS and
8G to Tomcat. The amount allocated to Tomcat versus the database varies per customer. A system
where a lot of queries/searches are made in Retain for items, or that runs multiple workers on the
Retain Server itself, allocates more memory to Tomcat, like in this example; otherwise, a customer
might want to favor MySQL a bit and give Tomcat a little less.
Changes to the my.cnf do not take affect until after MySQL is restarted. Again, if you changed the log
file size setting, you must follow the steps listed above or MySQL fails to load.
Once MySQL loads successfully, you can start tomcat “Starting and Stopping the Retain Server” on
page 53.

Installing a Retain Server on Linux

 “Retain Prerequisites for Linux Servers” on page 22
 “Downloading and Preparing the Retain Installation Files on Linux” on page 22
 “Installing the Retain Server” on page 22

Installing Retain 24.2 21

 Retain Prerequisites for Linux Servers
IMPORTANT: Make sure you have planned your deployment before installing the software. For
example, if the Linux server doesn’t have the minimum RAM Requirements for the components you
specify, the installation aborts. Refer to the official Apache website for instructions on how to set up
SSL on Apache2.

Successfully installing Retain and/or its components on Linux servers, requires the following:
 An Apache Web Server: Installed and running on each Linux server as outlined in “Linux Web
Server” on page 10.
 Access to the appropriate JDK running on the system: By default, the installer expects the
appropriate JDK to be running on the Linux system. (For Retain 23.4, this is JDK 17)
If the appropriate JDK is not found and the server is connected to the Internet, the install
automatically downloads and installs the JDK.
If the appropriate JDK is not found and an Internet connection is not available, you must type
the path to the appropriate JDK installation source files on the Linux server before the
installation will continue.
 Synchronized server clock: Before you start the Retain install, the Linux server must be
synchronized with the time on your network. For example, if your organization uses NTP,
configure the server with your organization’s NTP settings.

Downloading and Preparing the Retain Installation Files on Linux

Do the following:
1 Using your OpenText Customer Center account, download the latest version of Retain to the
Linux server where you are installing Retain or one of its components.
2 Extract the archive into a new folder.
 Graphical Interface: Right-click the download and select Extract Here.
 Terminal Prompt: Enter the following command
unzip Retainversion.zip
where version is the release version number in the .zip filename.
3 Make the script executable.
 Graphical Interface: Right-click the download and select Properties > Permissions tab >
Allow executing file as program.
 Terminal Prompt: Change to the Retain install folder that you just extracted, then enter
the following command:
chmod +x *.sh

Installing the Retain Server

The Retain Server is the main component of a Retain deployment and is installed on only one Linux
server. Other Retain components can be installed with Retain or separately (as explained in Step 5
below).

22 Installing Retain 24.2

IMPORTANT: Make sure that you have planned your deployment before installing Retain software. If
the Linux server doesn’t have the minimum RAM for the components you select, the installation
aborts.

Retain installs an embedded Tomcat. Consider removing any existing Tomcat installation prior to
installing Retain components.
1 If you have not already done so, download and prepare the target server with the Retain
installation files, as instructed in “Downloading and Preparing the Retain Installation Files on
Linux” on page 22.
2 Acting as root, access the server’s terminal prompt and enter the following command:
./RetainInstall.sh
3 Read and accept the license agreement.

TIP: To go immediately to the acceptance prompt, type q.

4 Read the software requirements and press Enter.

5 The install prompts for which of the following Retain components you want to install on the
server:

Component Placement Detail

Retain Server Install one instance of this on the main server in your deployment

Stubbing Server This only applies to GroupWise. See “Stubbing Server Overview” in OpenText
Retain CE 24.2 : Configuration and Administration.

Reporting and Generally, you should install this on the Retain server.
Monitoring Server

Retain Worker Generally, you should install a Worker on the Retain server. for troubleshooting
purposes.

Instructions for installing production-use Workers follow this section in

“Deploying Production-Use Worker Agents on Linux” on page 49.

Retain Message Router Install this in the DMZ. For instructions, see “Installing a Retain Message Router
on Linux” on page 50.

Type y to install a component; n to not install it.

6 The install checks the server for the supported version of Java (currently JDK 17).
If the required version is not found on the server, the installation downloads the correct version,
and then upgrades or installs Java as needed.
If the download connection fails, the installer asks whether you want to retry, abort the
installation, or specify a local path to the Java installation package.
7 The install restarts Tomcat and alters the runlevel so that Retain starts automatically when the
system does.
8 When the installation completes, it displays the URL for accessing the Retain Server’s web
console in a browser and returns to the terminal prompt.

Installing Retain 24.2 23

 9 Open a terminal prompt and verify that the Retain Server installed by checking that both
Apache 2 and Retain Tomcat are running by entering the following commands:
service apache2 status
service retain-tomcat status
10 Continue with “Running the Retain Server Configuration Wizard” on page 34.

Installing a Retain Server on Windows

 “Downloading and Preparing the Retain Windows Installation Source Files” on page 24
 “Prerequisites” on page 24
 “Retain Install” on page 25

Downloading and Preparing the Retain Windows Installation

Source Files
Do the following:
1 Using your OpenText Customer Center account, download the latest version of Retain to the
Linux server where you are installing Retain or one of its components.
2 Using Windows Explorer, extract the archive into a new folder.

Prerequisites
Before running the Retain installer, you must first ensure that the following are installed and
working:
 A Web Server: Installed and running on each Windows server as outlined in “Windows Web
Server” on page 10.

NOTE: IIS has a size limit restriction which limits uploads of message and attachment archiving
to 30MB, by default. Refer to the official microfost website for instructions on how to set up SSL
on IIS.

 PowerShell 3.0 or higher: If PowerShell's execution policy is set too restrictively, the install fails.
See Set-ExecutionPolicy (https://docs.microsoft.com/en-us/powershell/module/
Microsoft.PowerShell.Security/Set-ExecutionPolicy?view=powershell-5.1).
 Access to the appropriate JDK running on the system: For Retain 23.4, this is JDK 17.
If the appropriate JDK is not found and the server is connected to the Internet, the install
automatically downloads and installs the JDK.
If the appropriate JDK is not found and an Internet connection is not available, you must browse
to the appropriate JDK installation source files on the Windows server before the installation
will continue.
 Synchronized server clock: Before you start the Retain install, the Windows server must be
synchronized with the time on your network.

24 Installing Retain 24.2

Retain Install
1 Prepare the Retain installation software on the server as instructed in “Downloading and
Preparing the Retain Windows Installation Source Files” on page 24.
2 Run “RetainInstall.exe”. NOTE: If it already exists, the installer automatically shuts down
Tomcat.
3 The Retain Setup Wizard welcomes you to the installer.

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

Installing Retain 24.2 25

 5 Agree to the license agreement.

6 Select the install location.

26 Installing Retain 24.2

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

7a. If you are upgrading, previously installed components are preselected and you can select
additional modules to install.

Installing Retain 24.2 27

 8 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’.
Tomcat 9.0 is the supported version with Retain.23.2.
Please note that the environment variable ‘RETAIN_CATALINA_HOME’ is set after Tomcat
installation.
Click ‘Next’ to continue.

28 Installing Retain 24.2

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 9”. (Start | Run | services.msc)
If an Internet connection cannot be made, the installer asks whether to retry, to abort, or use a
local path to the Java installation package. You can download the correct version of the Java
installer for Windows here.

Installing Retain 24.2 29

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

10 If a previous version of Retain is detected, upgrade options are displayed; Overwrite or

Upgrade. Generally, you should choose Upgrade. Click Next.

30 Installing Retain 24.2

11 Confirm settings and select 'Install'.

12 The product installs.

Installing Retain 24.2 31

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

14 The Setup Wizard thanks you for installing Retain.

32 Installing Retain 24.2

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

16 The Retain installation process is complete. Click Finish.

Installing Retain 24.2 33

 17 Continue with “Running the Retain Server Configuration Wizard” on page 34

Running the Retain Server Configuration Wizard

After installing the Retain Server, you must run the initial configuration wizard to prepare the server
for working with all the components that will constitute your Retain deployment.
Do the following:
1 On an administrative workstation, open a supported administrative web browser.
2 Go to http://RetainServer-IP-or-DNS/RetainServer.
3 Run the wizard to configure the Retain Server as outlined in the following table.

34 Installing Retain 24.2

Table 1-1 Running the Retain Server Configuration Wizard

Panel or Prompt Action Information

Welcome > File Path 1. Set the paths for Retain as planned in Storing data on separate volumes can
“Storage Planning” in OpenText Retain yield significant performance
CE 24.2: Planning. increases. Therefore, Retain lets you
By default, all data is stored as follows: specify where you want to store
archived data, indexes, and so on.
 Linux: /var/opt/
beginfinite/retain If you are running Retain on a Windows
Server, Solr9 disallows the use of
 Windows: C:\Retain
Windows SMB shares on the UNC
By default, zookeeper path is as follows: format, such
 Linux: /var/opt/ as\\myhost\myshare\mypath. For
beginfinite/retain the indexer storage path, you are can
use a drive and mount later. As a
 Windows: \Retain\zookeeper workaround, map the storage path in
Retain derives all file paths from this UNC format to a symbolic link folder on
base path. the local drive:
Retain derives all file paths from this 1. On the server where Retain is
base path. running, run the following
2. If you need to alter the base path, select command in the Windows
Custom in the drop-down list and Command Prompt: mklink /D
specify an alternate path. C:\myLink \\IP
address\c\Retain\Index In
IMPORTANT: As outlined in “Setting the above command,
Custom Storage Path Rights on C:\myLink corresponds to the
Linux” in OpenText Retain CE 24.2: linked folder on the local drive
Planning, specifying an alternate and \\IP
storage path on a Linux system address\c\Retain\Index
requires that you grant sufficient corresponds to the storage path
rights to Retain before running this in UNC format.
wizard.
2. Ensure that the Retain Tomcat
 Ensure that the ownership of the service is running as a user who
base path is set to tomcat:www, has access to the shared folder. If
otherwise, the runtime Zookeeper not, please update the service
directory creation fails. For more and restart Tomcat.
information, see the Indexes
section in the OpenText Retain CE
24.2: Planning guide.
3. To customize the path for each item
(attachments, XML mappings, etc.), click
Advanced Settings and disable the
Derive all file locations from above
specified path? option.
4. When the path settings are complete,
click Continue.

Installing Retain 24.2 35

 Panel or Prompt Action Information

Message Store 1. Enter the database connection This is the database that stores meta
Database information for the database you data for messages and other data
created in “Creating and Maintaining an archived in the datastore.
SQL Database” on page 11.
2. Click the Enable SSL check box to secure
the database connection to Retain.
Else, click Continue and proceed to
“Configuration Database” on page 37.
3. If the SSL is enabled and the database
type is MariaDB, MySQL, PostgreSQL,
and MSSQL, select one of the options
from the Choose Trust Mode dropdown
list.
 Allow only trusted certificate: This
allows only trusted certificates and
you can upload the SSL certificate
created during SSL configuration.
 Allow all certificate: if this option
is selected, and the SSL is
configured with the database, then
all the certificates are trusted.
If your database type is Oracle, the
Private Key and Certificate will be a
single file and you must provide an alias
name and password while uploading the
certificate .
4. Browse to and select the Database client
server’s Private Key and Certificate files
that you identified in “Securing the
Database Connection” in the OpenText
Retain CE 24.2: Planning guide.
Following are the supported and
certified files formats:
 MSSQL - .pfx
 Postgres - .pem and .crt
 MariaDB -.pem and .crt
 MySQL - .pem and .crt
 Oracle - .p12
5. Based on the database type, the
certificates can be either a lone
certificate or a key pair. The certificate
name has to be unique else you will not
be able to upload the file. To create a key
pair, you must upload the cert.pem
first and then the key.pem. Ensure that
the alias name given for both the files
are same. Only self-signed certificates
need to be manually trusted. Registered
CA-signed certificates are automatically
trusted
36 Installing Retain 24.2 6. Click Continue.
Panel or Prompt Action Information

Configuration 1. Enter the database connection This is usually the same as the Message
Database information for the database you Store Database, so all connection
created in “Creating and Maintaining an information is carried forward to this
SQL Database” on page 11. dialog except the password.
2. Click Continue and continue with
“Administrator Account” on page 37

Administrator 1. Specify and confirm a password for the This account

Account main administrator account.  Has all admin rights.
2. Click Continue.  Never expires.
 Can authenticate when the
system is offline.

NOTE: Retain lets you create as many

user accounts with administrative roles
as you need. If this account is deleted,
you will need to contact OpenText
support.

SMTP Notifications 1. Enter the following information: Retain uses an SMTP relay host for
 SMTP Server: The DNS hostname sending notifications.
(preferred) or IP address of the The wizard attempts to send a test
SMTP server that Retain should use message.
for emailing notifications.
You shouldn’t proceed with setting up
 From address: The From address
Retain until the SMTP test message is
shown on the messages that Retain
successfully delivered. If you see an
sends.
error, check firewall settings, including
 To address: The address to which local application firewalls running on
Retain sends notifications through affected desktops and/or servers.
the SMTP server.
If no SMTP is present, you can skip this
 Username: The username for
step by typing skip in the SMTP Mail
authenticating with the SMTP
Server field. This disables Retain’s
server.
notification services and is therefore
 Password: The password for the not recommended for production
username. deployments.
 Click Continue.

Indexing Engine 1. Enter the admin password you set The default port for indexer is 8081.
earlier. You can change the port if required.
2. Click Continue. By default, zookeeper path is as
The system initializes and connects to follows:
the indexing engine.  Linux: /var/opt/
beginfinite/retain
 Windows:
\Retain\zookeeper

Installing Retain 24.2 37

 Panel or Prompt Action Information

Retain Server 1. Set up the Retain Server connection.

Connections This sets the connection for the Router
(“Retain Message Router Configuration
Page” in OpenText Retain CE 24.2 :
Configuration and Administration) and
REST applications.
When possible, use the Retain Server’s
DNS hostname so that external devices
can resolve to it.

(Optional) Cloud 1. (Optional) Configure the Cloud Mobile

Mobile Service Service (CMS) Proxy Connection. If you
Proxy Connection would like to provision and register
devices using CMS and have a Proxy
server for your Retain server, you can
specify the Proxy server information
here.
2. Click Continue > Complete.
The Retain login prompt displays.

Retain’s Browser-based Management Tool

You manage the Retain server and its associated components using browser-based administrative
consoles.
 “Logging In as an Administrator” on page 38
 “Retain Server Administrative Console” on page 39
 “Always Remember to Save Changes” on page 40
 “Notifications” on page 40

Logging In as an Administrator
1 Enter the following URL in an administrative web browser.
http://Retain-Server-IP-or-DNS/RetainServer
2 Sign in as admin by using the password that you specified in the configuration wizard.
Users with administrative rights see the administrative console below. Non-administrators see
only the Search interface documented in “Using Retain’s Archives” in the OpenText Retain CE
24.2: User Guide.)

38 Installing Retain 24.2

Retain Server Administrative Console
Figure 1-1 The Retain Server’s Administrative Console Landing Page

Table 1-2 Navigating Retain’s Administrative Console’s Landing Page

Field, Option, or Button Information and/or Action

Left Navigation Panel

This provides access to all of the Retain server’s configuration and management dialogs. Panel items grow
dynamically as you add components to the Retain infrastructure,

For example, the Overview section initially has four entries: Documentation, Search Messages, Auditing, and
System Log. When you add a Reporting and Monitoring server, the entries expand to provide direct access to
those services.

Status Panel

The status panel has seven tabs: Jobs, Worker Group Jobs, Deletion, Worker, Server, Updates, and Archive
Stats.

When you open the Retain Console, the tab requiring the most attention displays.

For example, if a Server Error has occurred, the Server tab displays. If an update is available, the Update tab
displays, and so on.

Statistics in the tabs are for the current server session. They are cleared and start fresh each time the Retain
server (Apache Tomcat) starts/restarts.

Installing Retain 24.2 39

 Field, Option, or Button Information and/or Action

Jobs Tab This shows the server’s archiving jobs and their status.

To see only active jobs, select the Show only active jobs option.

Worker Groups Jobs This displays the worker Group Jobs with workers and other statistics like
Tab Current Job began, Ended, their last active jobs, list of workers, totals etc.

There are options to see the last job details and deleted message details.

Deletion Tab This shows the server’s deletion jobs and their status, including the remaining
items marked for deletion in the database and file system.

To see only active jobs, select the Show only active jobs option.

Worker Tab The workers tab displays the workers and their last active jobs, connections, and
totals.

Server Tab The Server tab shows the basic status of the Server with the messages archived
and maintenance information.

Updates Tab The updates tab indicates that the latest version is installed or that there is a
later version available.

IMPORTANT: Information displays only during initial access to the console’s

landing page after the server starts/restarts. Navigating to another section of
the console clears tab content.

You must restart Tomcat to display the information again.

Archive Stats Tab This tab is deprecated and its functionality replaced by the Reporting and
Monitoring server.

Basically, it provides a small statistics summary from a basic search of the

server’s archive statistics.

Always Remember to Save Changes

When you see Save Changes highlighted in red at the top-right corner of the screen, be sure to click
it. Otherwise, changes you have made are lost.

Notifications
Retain uses its SMTP configuration to notify when data is moved because of a system migration, or
exporting, forwarding, restoring or publishing data.
To view the Notifications Center page, click the Welcome link at the top of the Admin Console page.
A lifted-flag icon indicates new notifications.

40 Installing Retain 24.2

 The highlighted notifications are new, unread notifications and events. Selecting the event
notification provides all the pertinent information regarding the event.
If there are errors, Retain provides a truncated error log that details the error and the reason for it.

Licensing
About Retain Licenses
Retain comes with a 30-day trial license. This is a fully operational trial to see if Retain works with
your system.
When your licenses expire, Retain displays only the license page so that you can upload a valid
license.
There are two kinds of licenses: PEM and REST. PEM licenses are used for most functions. Some
functions require using the REST API, which requires a REST license as well.

The Licensing Page

The Licensing page lets you view and manage the licenses installed in the Retain System. The status
displays active users, inactive users, merged mailboxes, and individual counts for active and inactive
users on each licensed module.
Path: Retain Server Manager > Configuration > Licensing

General Summary Panel

 Date contains today's date.
 Product is what version of Retain is currently installed.
 License Count is the number of mailboxes archived by Retain. Active mailboxes have had data
archived in the last 90 days, Inactive mailboxes have had no new data archived in the last 90
days.
 Merged Mailboxes is the number of mailboxes merged with Mailbox Mapping Options and/or
the Mailbox Merger/Splitter.
Generate Licensing Report creates a PDF file which displays the same information as seen in the
License Summary section and lists the licenses.

Installing Retain 24.2 41

 Licenses Panel
The Licenses panel displays the currently installed license.
After the initial installation, Retain functions for 30 days for evaluation purposes.
When this period elapses, the following occurs:
 Users without the "Manage Servers" right are not allowed to log in at all.
 Users with the "Manage Servers" right are allowed access, but only to the Licensing Page.
 All jobs continue to be processed normally

Installing Your Retain Licenses

You should receive an email with your validation keys, including one for base server access and
another for the module used for archiving from your email system. You can also find the keys in the
OpenText Customer Center.
1. Log in to the OpenText Customer Center.
2. Select the proper Product from the drop down menu.
3. Enter the Validation Key and click Next.
4. Fill out the contact information and click Next.
5. Download the PEM file.

Submitting a PEM License

To upload a new PEM license:
1. Browse to the RetainServer console.
2. Select Licensing from the left navbar.
3. Scroll to the bottom of the page.
4. Click the Choose File button from the Submit License section.
5. Browse to and select the desired license file.
6. Click the Submit License button.
7. The new license is added to the system.
8. Log out and in again to the server to see the license in effect.

Installing a REST License

Some components require that you install a REST license file.
1. Go to Server Configuration/REST API.
2. Scroll down to Submit License, Browse to the ZIP file and press Submit License.

42 Installing Retain 24.2

 3. The license is uploaded to the Retain server and appears in the list under Application Settings.
The Application reflects what system Retain can connect to via REST.

Backing Up Retain
When you first set up Retain and dredge the email system you have two identical data sets.
When older items are deleted from the email system. That means Retain is the only repository of the
data. When it comes to backups: "Two is one, one is none." That means if one fails, a backup remains
or not. Depending on the type of your organization the legal ramifications of lost data can be
significant.

Installing Retain 24.2 43

 Where Data Is Stored In Retain
There are only a few major places where data is stored in Retain. See “System File Locations” in
OpenText Retain CE 24.2: Planning.
1. Program directory
2. Archive directory
3. Index directory (this may be on an external cluster)
4. Database directory (this may be on an external server)
5. Office 365 CSV files

The Reporting and Monitoring Server data is stored in the database.

The Archive Job configuration is stored in the database.
Each major part of Retain keeps logs of what is happening the primary ones being the RetainServer,
RetainWorker, Indexer and the Reporting and Monitoring log as RetainStatServer.
When you are interacting with Retain, depending on what you are doing you are viewing different
parts of Retain the data.
 When you browse messages, you are viewing the metadata of the message that is stored in the
database.
 When you search messages, you are viewing the indexes of the messages.
 When you open a message, you are viewing the message as saved on disk.

All message content and attachments to messages are stored on disk in the Retain storage area in a
directory off of the "archive" directory (Server Configuration | Storage | Advanced). Every message
and attachment gets assigned a "hash". Because the byte count of every message and file is unique,

44 Installing Retain 24.2

its hash value is unique. This is how Retain Server determines whether a message and/or attachment
has already been processed and stored on disk when an archive job runs. That file's hash value is
stored in the Retain database in the t_document and t_attachment tables.
The archive directory uses a load balancing strategy on disk. Thus, off the archive directory you'll find
256 two-digit subdirectories: 00 through FF. Each of those directories have their own set of 256
directories utilizing the same naming sequence (00 through FF). Additionally, those directories also
have their own set of 256 subdirectories. Thus, if the filename were
B4F05EECB7B21D9014A86C32291C913D190C33394365AC79ED3E1F6849532, you would find it
under .../archive/B4/F0/5E.
When a user clicks on a message link in the Retain mailbox - whether from the Browse tab or the
Search tab's search result list - Retain finds the file on disk and places the contents in the message
window. If the original message was known to have text and the message window comes up blank,
the file is missing from the location that Retain thinks it is in. This is extremely rare and usually only
happens as a result of moving the archive directory to a new location. In such cases, we find that
either the files did not all copy over properly from the old location or the administrator forgot to tell
Retain where the new location is at.

Backing Up Retain
The archive directory consists of up to approximately 16.7+ million directories and the archives are
stored evenly across them. This makes it hard (if not impossible) for the traditional file-based backup
systems to back it up; thus, you either need a disk image (block level) backup or you need to use a
backup/restore solution of your choice.
The three most critical pieces that must be backed up are the archive data (specifically, the "archive"
directory), the Retain database and the configuration files. Losing even one of those pieces would
mean that your archive data is completely lost. They are interdependent. Indexes can be recreated,
although that takes time.

Virtual Machines
If you are running Retain on a VM and if you are using a purchased version of VMWare at any level,
the purchased version provides a disk backup utility. This can be used to back up Retain if the VM's
local disks are part of the VM guest itself. However, those backups can also take a lot of time as the
data grows, so even in those circumstances, you still may want to consider using a backup/restore
solution of your choice.
If the disks are external to the VM guest, then those disks need to be backed up. This article assumes
that the reader understands how disks work with VMs. If you do not fully understand virtual
machine concepts, we recommend that you consult with the person that set up and maintains your
VM environment.

Finding Retain’s Storage Paths

To find your Retain system's storage paths, do the following:
1 Log in to the administrative web console (http://ipaddress_or_DNS-hostname/RetainServer).
2 Under Configuration, click Server Configuration > Storage.

Installing Retain 24.2 45

 3 Click Advanced Settings and deselect the Derive all file locations from the above base path
(unless it is already deselected).
4 The list of storage paths displays.

NOTE: The information shown in the Storage tab in the Server Configuration screen is also stored in
the ASConfig.cfg file.

What to Back Up
Other than backing up the archive directory structure, there are a few areas of Retain that are
important to backup that would not require a disk image (block level) backup:
1. Configurations files
 ASConfig.cfg
 Indexer configuration files
2. Database (critical)
3. License
4. Index files (these can be rebuilt but that process can take days, weeks or months during which
time your searches cannot produce full results)
5. Office 365 address book CSV files.

46 Installing Retain 24.2

 File Locations
1. Configuration files.
 ASConfig.cfg is stored in a directory off of your Retain installation:
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/cfg
Windows default: [Drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-INF\cfg
 Indexer configuration files (the entire directory's contents):
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/solrweb/WEB-INF/cfg
Windows default: [Drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-
INF\solrweb\WEB-INF\cfg
2. Database.
 The location is too varied to mention here. Each customer should know where their Retain
database resides.
3. License.
 The license directory is located under your storage path.
4. Indexes.
 Because the Index directory can be in a constant state of change, it is recommended that
you back up the index subdirectory located beneath the backup directory (also found
under the storage path).
 When the Retain maintenance routine runs, it makes a backup copy of the index directory
and places it here. The frequency of this backup is configured in the RetainServer interface
under Server Configuration | Maintenance.
5. Office 365 address book CSV files. These files can be found under the CSV path designated in
Module Configuration | Exchange Module | Hosted Services.
If performing an upgrade of the Retain software you are strongly advised to manually back up all the
files mentioned in this article before performing the upgrade.
Note on backing up during the nightly maintenance cycle:
In Retain 4.0.3 and higher the indexes are optimized during maintenance every night. This may take
a hours after an upgrade. During optimization the index directory may grow by 2-3 times as
temporary files are created and removed. Backing up during this time is not recommended.

General Maintenance
There are a few items of manual maintenance you need to do occasionally. Annually is usually
sufficient.
 Remove old logs from the logs directory (Linux)/opt/beginfinite/retain/Tomcat[version]/logs or
(Windows) Program Files/beginfinite/retain/Tomcat[version]/logs

Installing Retain 24.2 47

  Remove old deletion reports from the archive directory. The file location can be found under
Retain Web console | Server Configuration | Storage tab. If it is not under the base storage
path, you may need to select Advanced settings and temporarily disable “Derive all file
locations from above base path?“
 Remove old exports from the exports directory. The file location can be found under Retain
Web console | Server Configuration | Storage tab. If it is not under the base storage path, you
may need to select Advanced settings and temporarily disable “Derive all file locations from
above base path?“

Un-installing Retain
To uninstall Retain, use the following general procedure. Actual locations may vary according to your
specific setup, storage location, and host operating system.

Linux
1. Shut Down Tomcat: “service retain-tomcat stop”
2. Shut Down Apache: “service apache2 stop”
3. (Optional) Remove the data storage files
Can be: /var/opt/beginfinite/retain. See the Retain Administration Guide section on storage to
see where your data actually is placed.
4. Remove the program files
Can be: /opt/beginfinite/retain
5. Remove the RetainWorker.xml, RetainServer.xml, RetainRouter.xml, and RetainStatsServer.xml
from Tomcat
Can be: /opt/beginfinite/retain/tomcat/conf/Catalina/localhost
6. Remove the directories under tomcat/work (but NOT work itself)
“rm –r /var/cache/retain-tomcat/work/*”
7. Remove references to Retain in httpd.conf
Can be: /etc/apache2/conf.d/retain-apache.conf
8. Remove tomcat service file: “rm /etc/init.d/retain-tomcat”
9. If Apache and Tomcat were not removed, restart them both to verify that they load without
problems.

Windows
1. Shut down Tomcat service
2. Remove Retain Tomcat service
Open a terminal as admin and type: “sc delete tomcat”
3. Remove the program files
Can be: C:\Program Files\Beginfinite\Retain

48 Installing Retain 24.2

 4. Remove the environment variables from the registry: RETAIN_CATALINA_HOME,
RETAIN_HOME, RETAIN_JAVA_HOME, RETAIN_JAVA_VERSION, and RETAIN_JRE_HOME
5. (Optional) Remove the data storage files
Can be: C:\Retain
6. (Optional) Remove SQL Database, SQL Server, Apache or IIS

Installing Other Retain Components on Linux

 “Deploying Production-Use Worker Agents on Linux” on page 49
 “Installing a Retain Message Router on Linux” on page 50

Deploying Production-Use Worker Agents on Linux

For all but small, all-in-one installations, best practice dictates having a Worker installed on each
email, messaging, or other targeted system as applicable. For more information, see “Worker
Locations” in OpenText Retain CE 24.2: Planning.

Installing Worker Agents

The Linux installer lets you install additional workers, one at a time.
1 Make sure the email or other server meets the “Retain Prerequisites for Linux Servers” on
page 22.
2 Prepare the Retain installation software on the server as instructed in “Downloading and
Preparing the Retain Installation Files on Linux” on page 22.
3 At the terminal prompt, enter the appropriate command for the worker instance you are
installing on the server:
3a First worker on server:
./RetainInstall.sh
3b Each additional worker:
./RetainInstall.sh addworker
4 Accept the license agreement.
Type q to go directly to the acceptance options.
5 Acknowledge the system requirements by pressing Enter.
6 (First Worker only) By typing n or y as appropriate, choose to install only a Worker.
7 (Additional Workers only) Enter the number (1-9) of the Worker agent you wish to install. You
can install workers in any order.
If you mistakenly enter a number that you have previously entered, before the install finishes, it
asks whether you want to keep the same configuration, overwrite the configuration, or quit the
installation.
8 For the Worker installation location, you can either confirm the standard install location (/opt/
beginfinite/retain), change the installation path, or quit the installation.

Installing Retain 24.2 49

 9 For the Worker log file location, you can choose to keep the default log location at /var/logs
or to store the log files in /opt/beginfinite/retain/tomcat/logs.
There is a separate log file for each worker, found in /var/log/retain-tomcat/
RetainWorkerN.yyyy-mm-dd.log unless otherwise specified for this worker.
10 (First Worker only) The install checks for JDK 17 as described in “Access to the appropriate JDK
running on the system:” on page 22.
11 Choose to run the retain-tomcat process on start-up or not.

NOTE: This choice affects Tomcat start-up for the server and any workers that you installed
previously, not just the worker you are currently installing.

The installer completes the Worker configuration, displays information about accessing the
worker in a browser, and provides some brief troubleshooting tips.

Creating Worker Web Objects and Downloading Worker Boostrap Files

After installing the Worker Agents for your Retain deployment, you need to connect them to the
Retain Server by creating a Worker Web Object for each of them and downloading their respective
bootstrap files.
1 After installing and acknowledging the location of the documentation, the installer shows you
how to access the Workers that were just installed.
2 Using the password you set during the installation, log into the Retain web console as admin.
3 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.
4 Browse to the new Worker at http://[ServerAddress]/RetainWorkerN, where N is the number of
the worker you just installed.
5 Upload the bootstrap.
6 Click Continue and log in to the worker.
7 Check the friendly name that it is the one you expect.

Installing a Retain Message Router on Linux

Install the Router on a separate Linux server in the DMZ to allow devices outside your network to
archive to the Retain Server without exposing the server directly to the Internet.
1 Make sure the server meets the “Retain Prerequisites for Linux Servers” on page 22.
2 Prepare the Retain installation software on the server as instructed in “Downloading and
Preparing the Retain Installation Files on Linux” on page 22.
3 If a previous version of Java was installed via YaST, tomcat may fail to start. Uninstall the existing
Java with YaST and unset the JRE_HOME path (unset JRE_HOME).
4 Run the installer. Enter the following command: ./RetainInstall.sh
5 When selecting the components to install. Select yes to "Install Retain Message Router" only.
6 Finish the install as normal.
7 Create a 10 GB data directory for the Router to use to temporarily use to store messages until
they can be transferred to the Retain Server.

50 Installing Retain 24.2

 NOTE: The Storage Path must not be the same as the Mobile Module Data path.

8 Configure the Router in the Retain Server console under Configuration | Router Configuration.
See “Retain Message Router Configuration Page” in OpenText Retain CE 24.2 : Configuration and
Administration.
9 The Router can be accessed by browsing to (case-sensitive): http://[IPAddress or
HostName]/RetainRouter.

Installing Other Retain Components on Windows

 “Installing Additional Retain Workers on Windows” on page 51
 “Installing a Retain Message Router on Windows” on page 53

Installing Additional Retain Workers on Windows

Typically, one Worker Agent is installed on the Retain Server, but it may make sense for your system
to use multiple workers.
One design option is to place a Worker Agent on each post office server, that would save network
bandwidth as only new messages would be transmitted. Another option is to place multiple worker
agents on a dedicated worker server.
Installing a worker agent is much simpler than installing the entire Retain server system. It only
requires installing the web server and the worker agent software. It uses the same installer as above.

Prerequisite
Install the web server (IIS with ISAPI filter, as above).“Installing a Web Server” on page 10

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

Procedure
1 Download and prepare the software on the Windows server as outlined in “Downloading and
Preparing the Retain Windows Installation Source Files” on page 24.
2 Run the RetainInstall.exe and install at least one Worker or upgrade the existing installation, if
you haven't already done so.
3 From the command line (run as Administrator), type RetainInstall.exe /AddWorker to start the
installer in Add Worker Mode.
4 Acknowledge the requirements.

Installing Retain 24.2 51

 5 Accept the license agreement.
6 Confirm the install location of Retain.
7 Enter the number (1-9) of Worker agents to install. They are installed in numerical order (e.g.
RetainWorker, RetainWorker1, RetainWorker2..., RetainWorker9).

8 Confirm which webserver is installed.

9 Install the Worker agent software. After installing and acknowledging the location of the
documentation the installer shows you how to access the Workers that were just installed.
10 Log into the Retain web console as admin
11 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.
12 Browse to the new Worker at http://[ServerAddress]/RetainWorkerN where N is the number of
the worker you just installed.
13 Upload the bootstrap.
14 Click Continue and login to the worker.
15 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
\logs\RetainWorkerN.yyyy-mm-dd.log unless otherwise specified in Configure Tomcat.

52 Installing Retain 24.2

 Installing a Retain Message Router on Windows
The Retain Message Router allows devices outside your network to archive to the Retain Server
without exposing the server directly to the Internet. The Router sits in your network's DMZ and
routes items to the Retain Server.
The Router should be installed on a server other than the Retain server itself.
This is much simpler than installing the entire Retain server system. It only requires installing the
webserver and the Router agent software. It uses the same installer as above.
Prerequisites:
 Install the web server (IIS with ISAPI filter, as above).
 Make sure that the Router server can connect to the Retain Server.

Install:
1 Download and prepare the software on the Windows server as outlined in “Downloading and
Preparing the Retain Windows Installation Source Files” on page 24.
2 Extract the archive.
3 Run the installer, RetainInstall.exe, as above.
4 When selecting the components to install. Select "Message Router" only.
5 Finish the install as normal.
6 Create a 10 GB data directory for the Router to use to temporarily store messages until they can
be transferred to the Retain Server.

NOTE: The Storage Path must not be the same as the Mobile Module Data path.

7 Configure the Router in the Retain Server console under Configuration | Router Configuration.
See “Retain Message Router Configuration Page” in OpenText Retain CE 24.2 : Configuration and
Administration.
8 The Router can be accessed by browsing to http://[IPAddress or HostName]/
RetainRouter.

Starting and Stopping the Retain Server

To start, stop, or restart Retain, you must start, stop, or restart Tomcat.

Windows
In Windows, Retain runs as a service. Open Services, select the Retain service then start, stop, or
restart that service.

Installing Retain 24.2 53

 Linux
Use the following commands at the terminal prompt to start and stop Tomcat:
systemctl start retain-tomcat.service

systemctl stop retain-tomcat.service

systemctl restart retain-tomcat.service

systemctl status retain-tomcat.service

54 Installing Retain 24.2

2 Upgrading to Retain 23.4 and Later
2

The following is a graphical overview of the upgrade path to Retain 23.4 and later.

IMPORTANT: The supported path is from Retain 4.11 or later to 23.4 and later.
 Beginning with 23.4, Solr 9 is supported. For more information see the see the Updating to the
Solr 9 Indexing Engine section in the OpenText Retain CE 24.2: Installation and Upgrade guide.
 If you are using Retain 4.11 or 4.11.0.1, before upgrading to 23.4 and later ensure that Solr
8 is the Active Index Engine and Solr 7 cleanup is performed.
 On the Retain 23.4 and later upgraded setup, the zookeeper path by default will be on the
base path. For example,
Linux: /var/opt/beginfinite/retain
Windows: \Retain\zookeeper

1 Before you start upgrading, complete the instructions in “Preparing to Upgrade to 23.4 and
Later” on page 56.
Use the following instructions to upgrade to Retain 23.4 and later.
 “Preparing to Upgrade to 23.4 and Later” on page 56
 “Upgrading from 23.2 or 23.3 to 23.4 and Later” on page 58
 “Upgrading from 4.11 to 23.4 and Later” on page 64

Upgrading to Retain 23.4 and Later 55

 Preparing to Upgrade to 23.4 and Later
Prerequisites for Upgrading to 23.4 and Later
Before starting the upgrade processes, OpenText recommends that you make sure you have the
requirements for a Retain 23.4 or later system, as outlined in “System Requirements” in OpenText
Retain CE 24.2: Planning.

Installing Java on a Server with no Internet Connection

By default, the Retain installation program uses an Internet connection to download a specific
version of Java for each version of Retain. If the Retain server is not connected to the Internet, you
must prepare the server with a workaround beforehand. Otherwise, the installation fails.
The following sections outline the preparation steps for each Retain version in the supported
upgrade path as well as for installing the current Retain release.
 “Linux Servers” on page 56
 “Windows Servers” on page 57

Linux Servers
Prepare your Linux Retain server by using the information in the row that matches your target
version.
1 On a workstation with an Internet connection, use the links in the following table to download
the linked Java version that applies to your upgrade target. Then refer to the Action column for
further instructions.

Retain Platform and Download and Copy These Action

Version Files to Each Retain Server

Linux 4.11 OpenJDK11U- 1. When prompted about the missing JDK

jdk_x64_linux_hotspot_11.0.1 file, select option 3 and enter the path to
6+8.tar.gz the folder containing the file that you
previously copied to the server.
2. Continue with the upgrade process.

Linux 23.2 OpenJDK11U- 1. When prompted about the missing JDK

jdk_x64_linux_hotspot_11.0.1 file, select option 3 and enter the path to
7+8.tar.gz the folder containing the file that you
previously copied to the server.
2. Continue with the upgrade process.

Linux 23.3, 23.4, and OpenJDK17U- 1. When prompted about the missing JDK
later jdk_x64_linux_hotspot_17.0.6 file, select option 3 and enter the path to
_10.tar.gz the folder containing the file that you
previously copied to the server.
2. Continue with the upgrade process.

56 Upgrading to Retain 23.4 and Later

Windows Servers
Prepare your Windows Retain server by using the information in the row that matches your target
version.
1 On a workstation with an Internet connection, use the links in the following table to download
the linked Java versions that apply to your upgrade path. Then refer to the Action column for
further instructions.

Retain Version Download and Copy These Action

Files to Each Server

Retain 4.11 OpenJDK11U- 1. Extract the files to this location:

jdk_x64_windows_hotspot_11. C:\Program Files\Beginfinite\Retain\Java
0.16_8.zip

Retain 23.2 OpenJDK11_x64_windows_jdk- 1. Extract the files to this location:

11.0.17_8.zip C:\Program Files\Beginfinite\Retain\Java

Retain 23.3, 23.4, OpenJDK17_x64_windows_jdk- 1. Extract the files to this location:

and later 17.0.6_10.zip C:\Program Files\Beginfinite\Retain\Java

2 After extracting the files, before running the Retain installer, edit the system’s Environment
Variables to reflect the values indicated for the version you are upgrading to.

Retain Target Variable Name Value

Version

RETAIN_JRE_HOME C:\Program Files\Beginfinite\Retain\Java\jdk-10.0.2+13

Retain 4.11 RETAIN_JAVA_HOME C:\Program Files\Beginfinite\Retain\Java\jdk-11.0.16+8

RETAIN_JAVA_VERSION jdk-11.0.16+8

RETAIN_JRE_HOME C:\Program Files\Beginfinite\Retain\Java\jdk-11.0.16+8

Retain 23.2 RETAIN_JAVA_HOME C:\Program Files\Beginfinite\Retain\Java\jdk-11.0.17+8

RETAIN_JAVA_VERSION jdk-11.0.17+8

RETAIN_JRE_HOME C:\Program Files\Beginfinite\Retain\Java\jdk-11.0.17+8

Retain 23.3, RETAIN_JAVA_HOME C:\Program Files\Beginfinite\Retain\Java\jdk-17.0.6_10

23.4, and
later

RETAIN_JAVA_VERSION jdk-17.0.6_10

RETAIN_JRE_HOME C:\Program Files\Beginfinite\Retain\Java\jdk-17.0.6_10

3 When you run the Retain installer, it recognizes that Java is already installed.

Upgrading to Retain 23.4 and Later 57

 Upgrading from 23.2 or 23.3 to 23.4 and Later
Use the instructions in the following sections to upgrade from Retain 23.2 or later to Retain 23.4 and
later.
 “Preparing to Upgrade to 23.4 and Later” on page 58
 “Upgrading to 23.4 and Later (SLES)” on page 58
 “Upgrading to 23.4 and Later (Windows)” on page 59
 “Updating to the Solr 9 Indexing Engine” on page 61

Preparing to Upgrade to 23.4 and Later

Table 2-1 Preparing for Retain 23.4 and Later

Task Details

Ensure that the Retain 1. Verify that the Retain server is connected to the Internet, so that the
server is connected to installer can install OpenJDK 17.
the Internet
If your server isn’t connected to the Internet, see “Installing Java on a Server
with no Internet Connection” on page 56.

Ensure that SMTP Is 1. The installer must be able to email status messages to the configured SMTP
Working in Retain account. Otherwise, it will stop and display an error message.

Get the 23.4 and later 1. Using your OpenText Customer Center account, download the latest version
software of the Retain installation.zip file.
2. Copy the file and unzip/extract it on the following:
 The Retain server that you are upgrading.
 Every server that is running a Retain Worker or other component.
3. (SLES) Open a terminal, navigate to the extracted folder, run the following
command to make the script files executable:
chmod +x *.sh

Ensure Adequate RAM 1. Make sure that the Retain server has at least 12 GB RAM.

Back up the Database The upgrade should run smoothly. However, best practice always dictates backing
and the Retain Server up systems before making major changes.

1. Back up your database and the Retain server immediately before starting
the upgrade.

Upgrading to 23.4 and Later (SLES)

If you are upgrading Retain on a Windows server, go to “Upgrading to 23.4 and Later (Windows)” on
page 59

58 Upgrading to Retain 23.4 and Later

Table 2-2 Upgrading to 23.4 on SLES

Installation Section Details

Stop Retain before 1. On the Retain server, open a terminal prompt.

Upgrading 2. Stop Retain by stopping the Apache Tomcat service.
For example, on SLES 12 or SLES 15 enter the following command:
systemctl stop retain-tomcat.service

Run the Retain 23.4 1. At the terminal prompt, navigate to the folder that you prepared in “Get the
and later Installation 23.4 and later software” on page 58, then enter the following command:

./RetainInstall.sh

License Agreement 1. Scroll through the license agreement, then type 1 and press Enter.

Software and RAM The Linux install lists the 23.4 and later software and RAM requirements.
Requirements
1. Press Enter to continue.

Retain Components The install displays the Retain components that are already installed on the server.
Selection Page
1. If you want to upgrade only the listed components, enter 1.
2. If you want to also install additional components, enter 2, then enter y for the
components you wish to add to the server.

Pre-requirements The install checks for OpenJDK 17 and an updated version of Tomcat 9. If they are
Status not installed, it installs and configures them for Retain.

NOTE: The Java and Tomcat verification/installation process can take a while, so be
patient while the installation works in the background.

The installation process extracts and installs Retain 23.4 and later.

Next, it starts the system processes that Retain requires.

Finally, a message reminds you to consult the documentation.

1. When the system prompt displays, wait a few moments to make sure all the
components are running.

Upgrading to 23.4 and Later (Windows)

If you are upgrading Retain on a SLES server, go to “Upgrading to 23.4 and Later (Windows)” on
page 59

Table 2-3 Upgrading to 23.4 on Windows

Dialog/Section Details

Stop Retain before 1. On the Retain server, click Start > Administrative Tools > Services (or the
Upgrading equivalent on your version of Windows Server).
2. Stop Retain by stopping the Retain Tomcat service.

Upgrading to Retain 23.4 and Later 59

 Dialog/Section Details

Run the Retain 23.4 1. In the folder that you prepared in “Get the 23.4 and later software” on page 58,
and later Installation right click RetainInstall.exe and select Run as Administrator.

Welcome to the 1. Click Next.

Retain Setup Wizard

Software The install lists the 23.4 software and hardware requirements along with the
Requirements software that it will install

1. Click Next.

License Agreement 1. Accept the agreement and click Next.

Select Destination 1. If you want to install the upgraded Retain components in a non-default
Location location, use the Browse button to change the path.
2. Click Next.

Retain Components The install displays the components that are already installed on the server.
Selection Page
1. If desired, you can select additional components for installation.
2. Click Next.

Pre-requirements 1. The install checks for OpenJDK 17 and an updated Tomcat 9. If they are not
Status installed, it indicates that they will be.
2. Click Next.
If needed, the install runs the OpenJDK 17 installation and updates Tomcat 9.
Click through any security alerts or other dialogs to allow the process to run to
completion.

Information The install reminds you to consult the documentation.

1. Wait a few moments to make sure all components have finished installing.
2. Click Next.

General Information A message shows the Retain access URL.

1. Click Next.

Completing the Retain 1. Click Finish.

Setup Wizard

60 Upgrading to Retain 23.4 and Later

Updating to the Solr 9 Indexing Engine
After Retain 23.4 or later is updated, update the Indexing Engine to Solr 9. You can do this at any
time after the upgrade, but if you have Manage Server rights, you are prompted to perform the
Index Engine update.
1 In Admin Console, when it is prompted to update the indexing engine, click Ok.

NOTE: It can take some time for the Server Configuration page to load.

2 In Server Configuration > Index, click Configure in the Indexing Node column.

IMPORTANT: When you configure Solr 9, all delete jobs are disabled until Solr 8 clean-up is
completed.

Upgrading to Retain 23.4 and Later 61

 3 You are prompted to select a Port and Index Path. The default Port is 1 more than the port used
for Solr 9. For example, if the port for Solr 8 index engine is 8081, then on upgrading Retain, the
default port for Solr 9 will be 8082. The index path is the new path for index files. If the index
directory is using a symlink, another symlink needs to be created for the new index folder so
that the new index files are stored in an appropriate storage location.

NOTE:
 If you are running Retain on a Windows Server, Solr 9 restricts the use of Windows SMB
shares on the UNC format, such as\\myhost\myshare\mypath. For the indexer storage
path, you can use a drive and mount it later. As a workaround, map the storage path in
UNC format to a symbolic link folder on the local drive:
1. On the server where Retain is running, run the following command in the Windows
Command Prompt: mklink /D C:\myLink \\IP address\c\Retain\Index In
the above command, C:\myLink corresponds to the linked folder on the local drive
and \\IP address\c\Retain\Index corresponds to the storage path in UNC
format.
2. Ensure that the Retain Tomcat service is running as a user who has access to the
shared folder. If not, please update the service and restart Tomcat.
 If you are running Retain on a Linux Server, using a different path than the default, you
need to make sure the ownership is set to tomcat:www.

A disk check will run to make sure that there is enough space on your server to migrate the
indexer. The free space needed for the migration is 3 times the size of the current index. The
recommended free space is 3.5 times the current index size.

When the check passes, Solr 9 is configured and starts indexing. At this point, you can continue
with the next steps to switch to Solr 9 or you can wait for Solr 9 to finish indexing.

IMPORTANT: Once Solr 9 is configured, index optimization and backup are disabled until Solr 8
clean-up is completed.

62 Upgrading to Retain 23.4 and Later

4 After Solr 9 is configured, click Switch to Solr 9 and restart the Tomcat service.

IMPORTANT: If you switch to Solr 9 when the re-indexing is in progress, the search results in
Retain will not be accurate.

Ensure that Solr 9 works as expected. If not, select Re-index All Items and switch back to Solr 8.
5 Click Clean up Solr 8.

IMPORTANT: This deletes Solr 8 and all the Solr 8 data from the system. Before you perform
Solr 8 clean up, ensure that the Solr 9 is working as expected.

6 Click Ok to confirm.

Upgrading to Retain 23.4 and Later 63

 Upgrading from 4.11 to 23.4 and Later
Use the instructions in the following sections to upgrade from Retain 4.11 or later to Retain 23.4.
 “Preparing to Upgrade to 23.4 and Later” on page 64
 “Upgrading to 23.4 and Later(SLES)” on page 64
 “Upgrading to 23.4 and Later (Windows)” on page 65

Preparing to Upgrade to 23.4 and Later

Table 2-4 Preparing for Retain 23.4 and later

Task Details

Ensure that the Solr 8 is Beginning with 23.4 only Solr 9 is supported. For more information, see “Updating
the Active Index Engine to the Solr 9 Indexing Engine” on page 61.
and Solr 7 cleanup is
performed.

Ensure that the Retain 1. Verify that the Retain server is connected to the Internet, so that the
server is connected to installer can install OpenJDK 17.
the Internet
If your server isn’t connected to the Internet, see “Installing Java on a Server
with no Internet Connection” on page 56.

Ensure that SMTP Is 1. The installer must be able to email status messages to the configured SMTP
Working in Retain account. Otherwise, it will stop and display an error message.

Get the 23.4 or later 1. Using your OpenText Customer Center account, download the latest version
software of the Retain installation .zip file.
2. Copy the file and unzip/extract it on the following:
 The Retain server that you are upgrading.
 Every server that is running a Retain Worker or other component.
3. (SLES) Open a terminal, navigate to the extracted folder, run the following
command to make the script files executable:
chmod +x *.sh

Ensure Adequate RAM 1. Make sure that the Retain server has at least 12 GB RAM.

Back up the Database The upgrade should run smoothly. However, best practice always dictates backing
and the Retain Server up systems before making major changes.

1. Back up your database and the Retain server immediately before starting
the upgrade.

Upgrading to 23.4 and Later(SLES)

If you are upgrading Retain on a Windows server, go to “Upgrading to 23.4 and Later (Windows)” on
page 59

64 Upgrading to Retain 23.4 and Later

Table 2-5 Upgrading to 23.4 on SLES

Installation Section Details

Stop Retain before 1. On the Retain server, open a terminal prompt.

Upgrading 2. Stop Retain by stopping the Apache Tomcat service.
For example, on SLES 12 or SLES 15 enter the following command:
systemctl stop retain-tomcat.service

Run the Retain 23.4 or 1. At the terminal prompt, navigate to the folder that you prepared in “Get the
later Installation 23.4 and later software” on page 58, then enter the following command:

./RetainInstall.sh

License Agreement 1. Scroll through the license agreement, then type 1 and press Enter.

Software and RAM The Linux install lists the 23.4 software and RAM requirements.
Requirements
1. Press Enter to continue.

Retain Components The install displays the Retain components that are already installed on the server.
Selection Page
1. If you want to upgrade only the listed components, enter 1.
2. If you want to also install additional components, enter 2, then enter y for the
components you wish to add to the server.

Pre-requirements The install checks for OpenJDK 17 and an updated version of Tomcat 9. If they are
Status not installed, it installs and configures them for Retain.

NOTE: The Java and Tomcat verification/installation process can take a while, so be
patient while the installation works in the background.

The installation process extracts and installs Retain 23.4.

Next, it starts the system processes that Retain requires.

Finally, a message reminds you to consult the documentation.

1. When the system prompt displays, wait a few moments to make sure all the
components are running.

Upgrading to 23.4 and Later (Windows)

If you are upgrading Retain on a SLES server, go to “Upgrading to 23.4 and Later (SLES)” on page 58

Table 2-6 Upgrading to 23.4 on Windows

Dialog/Section Details

Stop Retain before 1. On the Retain server, click Start > Administrative Tools > Services (or the
Upgrading equivalent on your version of Windows Server).
2. Stop Retain by stopping the Retain Tomcat service.

Run the Retain 23.4 1. In the folder that you prepared in “Get the 23.4 and later software” on page 58,
and later Installation right click RetainInstall.exe and select Run as Administrator.

Upgrading to Retain 23.4 and Later 65

 Dialog/Section Details

Welcome to the 1. Click Next.

Retain Setup Wizard

Software The install lists the 23.4 software and hardware requirements along with the
Requirements software that it will install

1. Click Next.

License Agreement 1. Accept the agreement and click Next.

Select Destination 1. If you want to install the upgraded Retain components in a non-default
Location location, use the Browse button to change the path.
2. Click Next.

Retain Components The install displays the components that are already installed on the server.
Selection Page
1. If desired, you can select additional components for installation.
2. Click Next.

Pre-requirements 1. The install checks for OpenJDK 17 and an updated Tomcat 9. If they are not
Status installed, it indicates that they will be.
2. Click Next.
If needed, the install runs the OpenJDK 17 installation and updates Tomcat 9.
Click through any security alerts or other dialogs to allow the process to run to
completion.

Information The install reminds you to consult the documentation.

1. Wait a few moments to make sure all components have finished installing.
2. Click Next.

General Information A message shows the Retain access URL.

1. Click Next.

Completing the Retain 1. Click Finish.

Setup Wizard

66 Upgrading to Retain 23.4 and Later

3 Moving Retain to a New Server
3

 “Moving Retain from Windows to Linux” on page 67

 “Moving Retain from Linux to Windows” on page 71
 “Moving Retain To a Different Windows Server” on page 74
 “Moving Retain To a Different Linux Server” on page 77

Moving Retain from Windows to Linux

The easiest method is to re-install everything to the new server and then copy over the archive and
configuration files.
These instructions are for moving Retain and maintaining its current version.
 “Overview” on page 67
 “Preparation” on page 68
 “Moving Retain” on page 68

Overview
To move Retain, you must move 3 things:
 Configuration files. Move the ASConfig.cfg, which is stored in a directory off of your Retain
installation:
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/cfg
Windows default: [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-INF\cfg
Indexer configuration files (the entire directory's contents):
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/solrweb/WEB-INF/cfg
Windows default: [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-
INF\solrweb\WEB-INF\cfg
 Database. Unless it's on a separate server and you are not moving it.
 Storage. In summary, the storage directories to be copied are:
 archive (required)
 backup (optional, although we recommend you skip this since having it on the old server is
backup enough until the next Retain maintenance performs a backup on he new server)
 ebdb (optional)
 export (optional)
 index (required in Retain 4, recommended for Retain 3)

Moving Retain to a New Server 67

  license (optional)
 xml (optional)

NOTE: If you've added storage partitions in the Retain admin web interface, you must make sure all
of those are copied correctly, too.

Preparation
1. Note where your Retain storage directory is located.
To determine what that directory is, log into the RetainServer web interface and click on Server
Configuration | Storage. The "Base Storage path" is your Retain storage directory (https://
www.novell.com/documentation/retain-24.2/config-admin/data/svr-cf-scfg-stor-
tab.html#storage-panel).
2. Download Retain to the new server and prepare it for the installation.
a. Create the download directory.
i. Make the directory for holding the software: md /software
ii. Change to that directory: cd /software
b. Download the latest version of Retain on the new server. For Retain 2.x customers, migrate
your data to Retain 3.x format first; then proceed with moving Retain

NOTE: You can use the wget command to download the software to the Linux server by
changing into the software directory you created in step 2.a and running this command:
wget '[url]'

i. Get the URL of the most current version of Retain from the Customer Center.
ii. Now use that URL with the wget command on the Linux server inside the software
directory you created.
c. Unzip the file and make the script files (.sh) executable.
i. unzip [retain zip file] -d [retain zip filename, excluding the ".zip" at the end]
Example: unzip Retainversion.zip -d retainversion
The "-d" option causes it to create Note how we kept the "r" in lowercase follwing the
"-d" option since Linux is case sensitive when changing directories.
ii. chmod +x *.sh
3. Install Apache2 to the new server.
a. Launch YaST | Software Management.
b. In the search window, type: Apache2.
c. Click on Apache2 (only), click on the Accept button, and accept the defaults.
4. (Optional) If you have edited the default properties files under the .../RetainWorker/WEB-INF/
classes/config, back up those files and restore them after the final step of the move.

Moving Retain
1. Disable archive jobs and, if applicable, deletion jobs on the old server.

68 Moving Retain to a New Server

2. For good measure, shut down Tomcat (https://support.microfocus.com/kb/
doc.php?id=7019531) on the old server.
3. Move the MySQL database if it resides on the Retain server; otherwise, proceed to step #4.
See: "Moving MySQL Database to Another Server (https://support.microfocus.com/kb/
doc.php?id=7019952)".
4. Install Retain on the new server.
a. Change to your Retain software installation directory (i.e., /software/retain3510ga_262)
b. Execute the installation script: ./RetainInstall.sh
*****************************IMPORTANT**********************************
At a certain point of the installation, you are presented the following prompt:
Will MySQL be running on the same server as Retain?
1) Yes
2) No <---- Select this option even if MySQL is running on the same server
Even if MySQL is running on the same server as Retain, type "2" for "No"; otherwise, it
attempts to install and configure MySQL. At this point, you have already installed MySQL
and moved your MySQL database to this new server, so selecting option 1 causes
problems.
*DO NOT log into the WEB UI at this point, you could damage the database data that
you've just moved.
c. Shut down Tomcat (https://support.microfocus.com/kb/doc.php?id=7019531) on the new
server.
5. Copy the Retain storage directories from the old server to the new server (see step #1 under the
"Preparation" section for the location of this directory). WARNING: This step can take days or
weeks depending on the data size.
Because the Windows server is using NTFS as the disk format and Linux something different
(ext3, xfs, etc), you'll need to employ an approach where the data on these two distinct disk
formats can be read from and written to by the same process.
One approach is to create a CIFS mount from the Linux box to the Windows server. This requires
that you first share the parent directory of the "archive" directory on your Windows server
housing Retain. Another approach would be to install NFS services on the new Windows server,
share the new storage directories, and mount from the old Linux server to the new shared
storage directories.
Once that is done, you can now use rsync to copy the files (https://support.microfocus.com/kb/
doc.php?id=7019348) from Retain storage directory on Windows to the new Linux server. To
help with this process, you may download and install Support's utility (https://
support.microfocus.com/kb/doc.php?id=7019279) for copying the files/directories.
Change to the new archive directory. It should have 256 subdirectories (00 - FF). All those
subdirectories must have the ownership of tomcat tomcat.

Moving Retain to a New Server 69

 Windows does not have a file ownership scheme similar to Linux, so once you've copied the
storage directories over, you'll need to set the directory/file ownership and permissions. That
process can take almost as much time as copying the directories did but it must be done in
order for Retain to be able to read from and write to them. To do this, type: chown -R
tomcat:tomcat [directory].
EXAMPLE: chown -R tomcat:tomcat archive (performed from the base storage path containing
the archive, index, and other Retain storage directories)
6. Copy the configuration files from the old server to the new server and edit the paths referenced
in those files to reflect their new locations:
a. ASConfig.cfg, located in [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-
INF\cfg.
b. Edit the ASConfig.cfg and change several parameters to reflect the storage paths on the
new server. Or, you can start tomcat, logon to the Retain Server web admin console, and
change the paths under Server Configuration | Storage. If editing the ASConfig.cfg directly,
look for these parameters for the storage paths:
 <basepath>
 <archivePath>
 <xmlPath>
 <indexPath>
 <backupPath>
 <licensePath>
 <EBDBPath>
 <exportPath>

70 Moving Retain to a New Server

 c. RETAIN 4 ONLY:
i. Edit the path the index directory to reflect its new location by opening the zoo.cfg file
in ...\index\solrhome\
ii. Copy everything from [drive]:\RetainServer\WEB-INF\solrweb\WEBINF\cfg.
7. Start Tomcat on the new server.
8. Login to the Retain Server web admin console.
9. Replace the existing Worker object. This is for systems where the Worker is on the Retain server
or for situations where jobs won't start after moving Retain:
a. Create a new worker web object using the instructions in “Installing and Configuring a
Worker” in OpenText Retain CE 24.2: Archiving Guide.
b. Download the bootstrap file.
c. Edit all jobs assigned to the old worker and re-assign them to the new one.
d. Delete the old worker object.
e. Restart tomcat.
f. From a web browser, go to the RetainWorker and upload the new bootstrap.
http://[Retain server IP]/RetainWorker
10. If you backed up any of the Retain Worker properties files (see step #5 under the Preparation
section), restore those to their respective directories. This does not apply to most customers -
this is very rarely done.

Moving Retain from Linux to Windows

The easiest method is to re-install everything to the new server and then copy over the archive and
configuration files.
These instructions are for moving Retain and maintaining its current version.
 “Overview” on page 71
 “Preparation” on page 72
 “Moving Retain” on page 73

Overview
To move Retain, you must move 3 things:
 Configuration files. Move the ASConfig.cfg, which is stored in a directory off of your Retain
installation:
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/cfg
Windows default: [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-INF\cfg
Indexer configuration files (the entire directory's contents):
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/solrweb/WEB-INF/cfg

Moving Retain to a New Server 71

 Windows default: [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-
INF\solrweb\WEB-INF\cfg
 Database. Unless it's on a separate server from the Retain server and you are not wanting to
move it.
 Storage. In summary, the storage directories to be copied are:
 archive (required)
 backup (optional, although we recommend you skip this since having it on the old server is
backup enough until the next Retain maintenance performs a backup on he new server)
 ebdb (optional)
 export (optional)
 index (required in Retain 4, recommended for Retain 3)
 license (optional)
 xml (optional)

NOTE: If you've added storage partitions in the Retain admin web interface, you must make sure all
of those are copied correctly, too.

Preparation
1. Note where your Retain storage directory is located. To determine what that directory is, log
into the RetainServer web interface and click on Server Configuration | Storage. The "Base
Storage path" is your Retain storage directory.
2. Download Retain to the new server and prepare it for the installation.
a. Prepare the download directory.
We recommend creating a directory called Software on the root of the drive. It is not
required and you may store the installation files wherever you desire, but if you do not
have a strong preference, storing it at [drive]:\Software makes it easier to find later,
especially for technical support.
b. Download the latest version of Retain on the new server. For Retain 2.x customers, you'll
first want to migrate your data to Retain 3.x format first; then proceed with moving Retain.
c. Unzip the file, allowing Windows to create a new subdirectory off of "Software" with the
same name as the zip file.
For example, if the zip file were named, "Retain4031ga_48.zip", Windows - by default -
creates a subdirectory called "Retain4031ga_48", so that the full path to the installation
files becomes [drive]:\Software\Retain4031ga_48.
3. (Optional) Configure NFS Services (https://support.microfocus.com/kb/doc.php?id=7020834)
on the new Windows server if you want to use Support's Retain Auxilliary Tool Set utility to copy
your Retain storage to your new server.
4. Install/Configure IIS (https://support.microfocus.com/kb/doc.php?id=7020584) on the new
server.
5. (Optional) If you have edited the default properties files under the Retain Worker directory(ies)
(.../RetainWorker/classes/config) such as attachment.properties or errors.properties, you may
want to back up those files to restore them after the final step of the move.

72 Moving Retain to a New Server

Moving Retain
1. Disable archive all archive jobs, and if applicable, deletion jobs on the old server.
2. For good measure, shut down Tomcat (https://support.microfocus.com/kb/
doc.php?id=7019531) on the old server.
3. Move the database if it resides on the Retain server; otherwise, proceed to step #4. For
customers using MySQL, reference "Moving MySQL Database to Another Server (https://
support.microfocus.com/kb/doc.php?id=7019952)".
4. Copy the Retain storage directory from the old server to the new server (see step #1 under the
"Preparation" section for the location of this directory).

WARNING: This step can take days or weeks depending on volume.

Because the Windows server is using NTFS as the disk format and Linux something different
(ext3, xfs, etc), you'll need to employ an approach where the data on these two distinct disk
formats can be read from and written to by the same process.
We recommend that you install NFS services on the new Windows server (https://
support.microfocus.com/kb/doc.php?id=7020834), share the new storage directories, and
mount from the old Linux server to the new shared storage directories.
Once that is done, you can now use rsync to copy the files from Retain storage directory on
LInux to the new Windows server. To help with this process, you may download and install
Support's utility for copying the archive directory.
5. Install Retain on the new server.
*DO NOT log into the WEB UI at this point, you could damage the database data that you've just
moved.
6. Shut down Tomcat on the new server.
7. Copy the configuration files from the old server to the new server and edit the paths referenced
in those files to reflect their new locations:
a. ASConfig.cfg, located in [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-
INF\cfg.
b. Edit the ASConfig.cfg and change several parameters to reflect the storage paths on the
new server. Or, you can start tomcat, logon to the Retain Server web admin console, and
change the paths under Server Configuration | Storage. If editing the ASConfig.cfg directly,
look for these parameters for the storage paths:
 <basepath>
 <archivePath>
 <xmlPath>
 <indexPath>
 <backupPath>
 <licensePath>
 <EBDBPath>
 <exportPath>

Moving Retain to a New Server 73

 c. RETAIN 4 ONLY:
i. Edit the path the index directory to reflect its new loation by opening the zoo.cfg file in
...\index\solrhome\
ii. Copy everything from [drive]:\RetainServer\WEB-INF\solrweb\WEBINF\cfg.
8. Start Tomcat on the new server.
9. Login to the Retain Server web admin console.
10. Replace the existing Worker object. This is for systems where the Worker is on the Retain server
or for situations where jobs won't start after moving Retain:
a. Create a new worker object (https://support.microfocus.com/kb/doc.php?id=7020431).
b. Download the bootstrap file.
c. Edit all jobs assigned to the old worker and re-assign them to the new one.
d. Delete the old worker object.
e. Restart tomcat.
f. From a web browser, go to the RetainWorker (http://[Retain server IP]/RetainWorker) and
upload the new bootstrap.
11. If you backed up any of the Retain Worker properties files (see step #5 under the Preparation
section), restore those to their respective directories. This does not apply to most customers -
this is very rarely done.

Moving Retain To a Different Windows Server

The easiest method is to re-install everything to the new server and then copy over the archive and
configuration files.
These instructions are for moving Retain and maintaining its current version. If your current version
of Retain is 2.x and you wish to upgrade afterwards (highly recommended), follow the instructions in
the KB article, "Upgrade: Retain 2.x to Retain 3.5.1.1 (Windows)".
 “Overview” on page 74
 “Preparation” on page 75
 “Moving Retain” on page 76

Overview
To move Retain, you must move 3 things:
 Configuration files. Move the ASConfig.cfg, which is stored in a directory off of your Retain
installation:
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/cfg
Windows default: [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-INF\cfg
Indexer configuration files (the entire directory's contents):
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/solrweb/WEB-INF/cfg

74 Moving Retain to a New Server

 Windows default: [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-
INF\solrweb\WEB-INF\cfg
 Database. Unless it's on a separate server from the Retain server and you are not wanting to
move it.
 Storage. In summary, the storage directories to be copied are:
 archive (required)
 backup (optional, although we recommend you skip this since having it on the old server is
backup enough until the next Retain maintenance performs a backup on he new server)
 ebdb (optional)
 export (optional)
 index (required in Retain 4, recommended for Retain 3)
 license (optional)
 xml (optional)

NOTE: If you've added storage partitions in the Retain admin web interface, you must make sure all
of those are copied correctly, too.

Preparation
1. Make a note of where your Retain storage directory is located. To determine what that directory
is, log into the RetainServer web interface and click on Server Configuration | Storage. The
"Base Storage path" is your Retain storage directory.
2. Download Retain to the new server and prepare it for the installation.
a. Prepare the download directory.
We recommend creating a directory called Software on the root of the drive. It is not
required and you may store the installation files wherever you desire, but if you do not
have a strong preference, storing it at [drive]:\Software makes it easier to find later,
especially for technical support.
b. Download the latest version of Retain on the new server. For Retain 2.x customers, you'll
first want to migrate your data to Retain 3.x format first; then proceed with moving Retain.
c. Unzip the file, allowing Windows to create a new subdirectory off of "Software" with the
same name as the zip file.
For example, if the zip file were named, "Retain4031ga_48.zip", Windows - by default -
creates a subdirectory called "Retain4031ga_48", so that the full path to the installation
files becomes [drive]:\Software\Retain4031ga_48.
3. (Optional) Configure NFS Services (https://support.microfocus.com/kb/doc.php?id=7020834)
on the new Windows server if you want to use Support's Retain Auxilliary Tool Set utility to copy
your Retain storage to your new server.
4. Install/Configure IIS (https://support.microfocus.com/kb/doc.php?id=7020584) on the new
server.
5. (Optional) If you have edited the default properties files under the Retain Worker directory(ies)
(.../RetainWorker/classes/config) such as attachment.properties or errors.properties, you may
want to back up those files to restore them after the final step of the move.

Moving Retain to a New Server 75

 Moving Retain
1. Disable archive all archive jobs, and if applicable, deletion jobs on the old server.
2. For good measure, shut down Tomcat (https://support.microfocus.com/kb/
doc.php?id=7019531) on the old server.
3. Move the database if it resides on the Retain server; otherwise, proceed to step #4. For
customers using MySQL, reference "Moving MySQL Database to Another Server (https://
support.microfocus.com/kb/doc.php?id=7019952)".
4. Install Retain on the new server. *DO NOT log into the WEB UI at this point, you could damage
the database data that you've just moved.
5. Shut down Tomcat on the new server.
6. Copy the Retain storage directory from the old server to the new server (see step #1 under the
"Preparation" section). Robocopy (http://social.technet.microsoft.com/wiki/contents/articles/
1073.robocopy-and-a-few-examples.aspx)is Microsoft's tool for this kind job. Make sure to
include empty directories. Verbose logging is recommended.

WARNING: This step can take days or weeks depending on volume.

7. Copy the configuration files from the old server to the new server and edit the paths referenced
in those files to reflect their new locations:
a. ASConfig.cfg, located in [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-
INF\cfg.
b. Edit the ASConfig.cfg and change several parameters to reflect the storage paths on the
new server. Or, you can start tomcat, logon to the Retain Server web admin console, and
change the paths under Server Configuration | Storage. If editing the ASConfig.cfg directly,
look for these parameters for the storage paths:
 <basepath>
 <archivePath>
 <xmlPath>
 <indexPath>
 <backupPath>
 <licensePath>
 <EBDBPath>
 <exportPath>
c. RETAIN 4 ONLY:
a. Edit the path the index directory to reflect its new loation by opening the zoo.cfg file in
...\index\solrhome\
b. Copy everything from [drive]:\RetainServer\WEB-INF\solrweb\WEBINF\cfg.
8. Start Tomcat on the new server.
9. Login to the Retain Server web admin console.

76 Moving Retain to a New Server

 10. Replace the existing Worker object. This is for systems where the Worker is on the Retain server
or for situations where jobs won't start after moving Retain:
a. Create a new worker web object. See “Installing and Configuring a Worker” in OpenText
Retain CE 24.2: Archiving Guide.
b. Download the bootstrap file.
c. Edit all jobs assigned to the old worker and re-assign them to the new one.
d. Delete the old worker object.
e. Restart tomcat.
f. From a web browser, go to the RetainWorker (http://[Retain server IP]/RetainWorker) and
upload the new bootstrap.
11. If you backed up any of the Retain Worker properties files (see step #5 under the Preparation
section), restore those to their respective directories. This does not apply to most customers -
this is very rarely done.

Moving Retain To a Different Linux Server

The easiest method is to re-install everything to the new server and then copy over the archive and
configuration files.
These instructions are for moving Retain and maintaining its current version. If your current version
of Retain is 2.x and you wish to upgrade afterwards (highly recommended), follow the instructions in
the KB article, "Upgrade: Retain 2.x to Retain 3.x (Windows)".
 “Overview” on page 77
 “Preparation” on page 78
 “Move the MySQL Database” on page 79

Overview
In order to move Retain there are 3 things that are not optional that MUST be moved.
1. The ASConfig.cfg
2. The Database (unless it's on a separate server in which case it can stay there. That part is up to
you.)
3. The archive files. It is recommended that you also copy the indexes. It would be more work not
to and would be disruptive to searching.
Everything else can be re-created but can also be copied if you wish. In summary, here are the
storage directories to be copied:
 archive (required)
 index (recommended)
 backup (optional)
 ebdb (optional)
 export (optional)

Moving Retain to a New Server 77

  license (optional)
 xml (optional)
 .../zookeeper/zoo.cfg
 .../RetainServer/WEB-INF/solrweb9/WEB-INF/cfg/

NOTE: If you've added storage partitions in the Retain admin web interface, you must make sure all
of those are copied correctly, too.

Preparation
1. Make a note of where your Retain storage directory is located.
To determine what that directory is, log into the RetainServer web interface and click on Server
Configuration | Storage. The "Base Storage path" is your Retain storage directory.
2. Download Retain to the new server and prepare it for the installation.
a. Create the download directory.
 Make the directory for holding the software: md /software
 Change to that directory: cd /software
b. Download the major Retain version you are currently using into the software directory you
created on the new server.
If Retain 2.x, download that version. It could be a newer build of that same major version.
What you want to avoid is downloading Retain 2.x when your old system is Retain 1.x or
downloading Retain 3.x when your old system is Retain 2.x.
Download the same major version of Retain that you are currently using from the
OpenText Customer Center, going with the latest build of that major version (where "major
version" is 2.x, 3.x, 4.x, etc):
NOTE: You can use the wget command to download the software to the Linux server by
changing into the software directory you created in step 2.a and running this command:
wget '[url]'
c. Unzip the file and make the script files (.sh) executable.
i. unzip [retain zip file] -d [retain zip filename, excluding the ".zip" at the end]
Example: unzip Retain3511ga_53.zip -d retain3511ga_53
The "-d" option causes it to create Note how we kept the "r" in lowercase follwing the
"-d" option since Linux is case sensitive when changing directories.
ii. chmod +x *.sh
3. Install Apache2 to the new server.
a. Launch YaST | Software Management.
b. In the search window, type: Apache2.
c. Click on Apache2 (only), click on the Accept button, and accept the defaults.
4. (Optional) If you have edited the default properties files under the .../RetainWorker/WEB-INF/
classes/config, you may want to back up those files to restore them after the final step of the
move. However, you could always access them from the original Retain server if needed.

78 Moving Retain to a New Server

Move the MySQL Database
1. Disable all archive and deletion jobs on the old server.
2. For good measure, stop Tomcat (http://https://support.microfocus.com/kb/
doc.php?id=7019531) on the old server.
3. Move the MySQL database if it resides on the Retain server. See: "Moving MySQL Database to
Another Server".
4. Install Retain on the new server.
a. Change to your Retain software installation directory (i.e., /software/retain3510ga_262)
b. Execute the installation script: ./RetainInstall.sh
*****************************IMPORTANT**********************************
At a certain point of the installation, you are presented the following prompt:
Will MySQL be running on the same server as Retain?
1) Yes
2) No <---- Select this option even if MySQL is running on the same server
Even if MySQL is running on the same server as Retain, type "2" for "No"; otherwise, it
attempts to install and configure MySQL. At this point, you have already installed MySQL
and moved your MySQL database to this new server, so selecting option 1 causes
problems.
*DO NOT log into the WEB UI at this point, you could damage the database data that
you've just moved. Now is probably the best time to Stop Retain.
5. Copy your storage directory contents from the existing server to the new server.

NOTE: This step is made easy by a Linux utility created by GWAVA Support for this very purpose
called Retain Auxiliary Tool Set (http://support.microfocus.com/kb/doc.php?id=7019279)
(affectionately referred to as "RATS").

If you wish to manually do this (ok, so you like to do it the hard way), here are the steps:
a. Connect the existing server's storage directory to the new server; or, rsync supports
addressing the DNS hostname or IP address of the destination server if you wish to do it
that way.
If you decide to mount the new server's storage directory, one way to do this is to create an
"export" of the existing server's storage directory and create an NFS mount to a drive from
the new server over to the exported drive on the existing server. For sample instructions on
how to create an export and how to mount to it, see "How to 'Map' (Mount) Another
Server's Linux Directory to Your Server (https://support.microfocus.com/kb/
doc.php?id=7020700)".
b. Change the tomcat userid on the new server to match the tomcat userid on the old server
(if necessary).
File ownership and permissions are tied to a userid, not a user name; thus, if tomcat on
server A has a userid assignment of 110 and tomcat on new server B has 107, then the files
that get copied over come over as being owned by userid 110, not "tomcat". As the files
get stored on server B, it looks up userid 110 on its system. If that ID is assigned to another

Moving Retain to a New Server 79

 process, say "Puppet", then the files are owned by that program, not tomcat. So, you must
check what the tomcat userid is on source server A and and on destination server B and
make them match by changing the userid, if necessary, on destination server B.
i. On the old server, type: cat /etc/passwd
This lists all the user accounts on the server, showing their userids and group IDs. In
the list in the screenshot, tomcat is listed last and its userid is 110 and its group ID is
1000.

ii. Do this same procedure on the new server.

If the userids match for tomcat on both servers, consider yourself fortunate and you
are ready for the next step "c"; otherwise, proceed to sub-step "3)".
iii. Look at the new server's userid list you obtained.
Determine whether another process on the new server is using the same userid
assigned to Tomcat on the old server.
If so, you'll need to change that processes' userid to an unused userid by following the
same steps outlined in the following sub-step "4)" for Tomcat's userid change. Then,
follow sub-step "4)" to change Tomcat's userid.
iv. Change a userid by typing this command: usermod -u [new userid assignment]
[username getting the new userid]

80 Moving Retain to a New Server

 You can also use vi to edit /etc/passwd and manually change the userids; whichever is
easier for you.
c. Change to the main Retain storage directory and copy it from the old server to the new
server.
We recommend using rsync. Regardless, when copying files on Linux, be sure that
whatever method you use copies over the permissions and ownerships.

NOTE: This should carry over the tomcat ownership and proper file permissions; however,
if they are not preserved during the copy process for some reason, you need to set them:

chown –R tomcat:tomcat [full path to new storage directory]

chmod –R 744 [full path to new storage directory]
This could take days or weeks to complete since the storage's archive directory contains
over 16M subdirectories; thus, it is much better if the permissions/ownership are
preserved during the copy process.
6. Shut down Tomcat on the new server if you haven't already.
7. Copy Retain configuration file(s):
Again, copy in such a way that you maintain its file permissions and ownership (tomcat:tomcat);
otherwise, remember to set the file ownership and permissions afterwards..
a. Copy the /opt/beginfinite/retain/RetainServer/WEB-INF/cfg/ASConfig.cfg

NOTE: If the storage directory on the new server is different from the old server, you must
open ASConfig.cfg and change several parameters to reflect the storage paths on the new
server:

 <basepath>
 <archivePath>
 <xmlPath>

Moving Retain to a New Server 81

  <indexPath>
 <backupPath>
 <licensePath>
 <EBDBPath>
 <exportPath>
b. If this is a Retain 4 system:
i. Copy the .../index/solrhome/zoo.cfg and edit the path the index directory if it has
changed.
ii. Copy everything from .../RetainServer/WEB-INF/solrweb/WEBINF/cfg.
8. Start Tomcat on the new server.
9. Login to the RetainServer web interface.
10. For systems where the Worker is on the Retain server, create a new worker object in the
RetainServer web interface to replace the old one:
a. Create a new worker (https://support.microfocus.com/kb/doc.php?id=7020431).
b. Download the bootstrap file.
c. Edit all jobs assigned to the old worker and re-assign them to the new one.
d. Delete the old worker.
e. Restart tomcat.
f. From a web browser, go to the RetainWorker (http://[Retain server IP]/RetainWorker) and
upload the new bootstrap
11. If you backed up any of the RetainWorker properties files (see step #4 under the Preparation
section), restore those to their respective directories. This does not apply to most customers -
this is very rarely done.

82 Moving Retain to a New Server

4 Moving a MySQL Database to Another
4

Server
The steps for moving a MySQL database are provided as a courtesy and are not officially supported
by OpenText; however, we do provide consulting services that can perform this for you. Contact your
local sales representative if interested.
 “Linux to Linux” on page 83
 “Linux or Windows to Windows” on page 84

Linux to Linux
1. Disable all archive and deletion jobs and stop Tomcat on the Retain server.
2. Perform a dump of the database.
3. Download MySQL onto the new server and un-tar it. Retain only needs the client and the server
RPM's, but it is simpler to download one bundle file then two separate files.
4. Install MySQL and configure the retain database on the new server.
At this point, you may want to configure MySQL memory allocation in the /etc/my.cnf file. Your
retain database uses the innoDB storage engine. The following should be researched and
considered:
innodb_buffer_pool_size
innodb_innodb_additional_mem_pool_size
innodb_log_file_size
innodb_log_buffer_size
If done correctly, this can enhance the performance of MySQL and Retain. You might want to
research this and experiment with those settings to find what works best for your system.
OpenText support cannot answer questions about or help customer's with their databases. That
is the customer's responsibility.
If you decide to change the innodb_log_file_size setting, you must take the following steps first:
a. Log into MySQL: mysql -u root -p
b. From the MySQL prompt, type: SET GLOBAL innodb_fast_shutdown=0;
Then type "quit" to log out of MySQL.
c. Shut down MySQL: rcmysql stop
d. Rename the ib_logfile0 and ib_logfile1 files.
e. Edit the /etc/my.cnf and change the logfile size.

Moving a MySQL Database to Another Server 83

 f. Start up MySQL: rcmysql start
If you do not take these steps when changing the logfile size, MySQL doesn’t load. You can
re-enable the innodb_fast_shutdown (...=1) afterwards if there is a need, but average size
systems do not seem to experience any significant delay in MySQL shutdowns by leaving
fast shutdowns disabled.
5. Import the dump into the new retain database.
mysql -u root -p retain < /[path to dump file]/[dump filename] To watch the progress of the
import, use this command: watch "mysqladmin -u root -p[mysql root user pw] processlist"
6. (Optional) Reboot the server to clear the memory. 7. Start up Tomcat and re-enable archive
jobs; and if used, re-enable deletion jobs.

Linux or Windows to Windows

1. Disable all archive and deletion jobs and - for good measure, stop Tomcat on the Retain server.
2. Perform a dump of the database (https://dev.mysql.com/doc/refman/5.5/en/mysqldump.html).
3. Download MySQL onto the new server.
4. Install MySQL and configure the retain database on the new server.
Refer to the appendix of the Windows Install Guide for instructions. At this point, you may want
to configure MySQL memory allocation in the [drive]:\Program Files\MySQL\MySQL Server
5.x\my.ini file. Your retain database uses the innoDB storage engine. The following should be
researched and considered (reference our KB, "MySQL Database maintenance for Best
Performance"):
innodb_buffer_pool_size
innodb_innodb_additional_mem_pool_size
innodb_log_file_size
innodb_log_buffer_size
This can enhance the performance of MySQL and Retain. The MySQL for Windows installer
configures settings for you based on your system's available memory and the answers to the
questions you provide its configuration wizard, so there may not be anything you need to do;
however, you might want to research this and play with those settings to find what works best
for your system. OpenText support cannot answer questions about or help customer's with
their databases. That is the customer's responsibility.
If you decide to change the innodb_log_file_size setting, you must take the following
preparatory steps before doing so:
a. Open the MySQL Command Line Client (Start | Programs | MySQL)
b. Log into MySQL: mysql -u root -p
c. From the MySQL prompt, type: SET GLOBAL innodb_fast_shutdown=0; Then type "quit" to
log out of MySQL.
d. Stop the MySQL service.
e. Rename the ib_logfile0 and ib_logfile1 files.
f. Edit the C:\Program Files\MySQL\MySQL Server 5.x\my.ini and change the
innodb_log_file_size setting and save the file.
g. Start the MySQL service.

84 Moving a MySQL Database to Another Server

 If you do not take these steps when changing the logfile size, MySQL doesn’t load. You can re-
enable the innodb_fast_shutdown (...=1) afterwards if there is a need, but average size systems
do not seem to experience any significant delay in MySQL shutdowns by leaving it disabled.
5. Import the dump into the new retain database.
a. Open the MySQL Command Line Client (Start | Programs | MySQL)b) Type: mysql -u root -
p retain < [path to dump file]\[dump filename]
EX: mysql -u root -p retain < d:\dump\2013-12-11.sql NOTE: This assumes that the
..\MySQL\bin directory is in the path.
6. (Optional) Reboot the server to clear memory.8. Start Tomcat and re-enable archive jobs; and, if
used, re-enable deletion jobs. 9. If only moving MySQL and not Retain; and, if using IP addresses
and not DNS names (or using a new DNS address), change Retain's URL to the MySQL server in
the ASConfig.cfg:
a. Edit the ASConfig.cfg (/opt/beginfinite/retain/RetainServer/WEB-INF/cfg) 2) Change the
<DBURL> and <confDBURL> settings to reflect the the new IP/DNS address 3) Save the
changes 4) Restart Tomcat on the Retain server.

Moving a MySQL Database to Another Server 85

86 Moving a MySQL Database to Another Server
5 Upgrading MySQL to a New Version
5

 “Upgrading MySQL on Linux” on page 87

 “Upgrading MySQL on Windows” on page 88

Upgrading MySQL on Linux

Upgrading and existing MySQL on a Retain server.
1. Stop Tomcat on the Retain server. See “Starting and Stopping the Retain Server” on page 53
2. Perform a dump (https://dev.mysql.com/doc/refman/5.5/en/mysqldump.html) of the database.
3. Download MySQL onto the server on which you wish to install MySQL and un-tar it. Retain only
needs the client and the server RPM's, but it is simpler to download one bundle file then two
separate files.
4. Stop MySQL: rcmysql stop
5. Uninstall MySQL if upgrading to the same server; otherwise, skip to step #8.
a. Check YaST | Software Management first for MySQL. Uninstall it from there if applicable.
If it has a "lock" icon, it cannot be uninstalled from Software Management. Proceed to step
"b".
b. Check for any other MySQL RPMs.
rpm -qa | grep -i mysql
Sample screen output:

c. Uninstall all instances of MySQL found in step b (if any) - but only the entries beginning
with "MySQL..."
rpm -e [current mysql rpm]
Based on the screenshot shown above in in sub-step "b", I would type:
rpm -e MySQL-server-community-5.1.72-1.sles11
This has to be done for each RPM discovered.
6. Delete or rename the entire "datadir" directory.
This is the mysql directory containing the ibdata1 database and the "retain" subdirectory. It is
no longer needed since you have already dumped the database. All of the files and
subdirectories are recreated without any loss of data as long as you have a good/current dump.

Upgrading MySQL to a New Version 87

 The "datdir" directory is specified in the /etc/my.cnf. Look for the "[mysqld]" section. The first
line reads, "datdir=[path]"
If not specified in the my.cnf, the datadir could be at /var/lib/mysql. This is the default datadir
directory if MySQL is installed manually.
7. Rename /etc/my.cnf to my.cnf.old.
8. Install MySQL and configure the retain database.
9. Import the dump into the new retain database.
mysql -u root -p retain < /[path to dump file]/[dump filename]
To watch the progress of the import, use this command: watch "mysqladmin -u root -p[mysql
root user pw] processlist"
10. Reboot the server to clear the memory; otherwise, start up Tomcat and you are done.

Upgrading MySQL on Windows

Upgrading MySQL
1. Stop Tomcat on the Retain server. See “Starting and Stopping the Retain Server” on page 53.
2. Perform a dump (https://dev.mysql.com/doc/refman/5.5/en/mysqldump.html) of the database.
3. Download MySQL onto the server on which you want to install it.
4. Install MySQL and configure the retain database. Refer to the appendix of the Windows Install
Guide for instructions.
5. Import the dump into the new retain database.
a. Open a command window (cmd).
b. Change directories to: C:\Program Files\MySQL\MySQL Server 5.0\bin (the beginning of
the path depends upon where MySQL was installed).
c. Type: mysql -u root -p retain < [path to dump file]\[dump filename]
EX: mysql -u root -p retain < d:\dump\2013-12-11.sql

NOTE: This assumes that the ..\MySQL\bin directory is in the path.

6. (Optional) Reboot the server to clear memory; otherwise, just start Tomcat.

88 Upgrading MySQL to a New Version