Retain 4.0.3.1 Install Guide

  • 7019073
  • 29-Sep-2016
  • 07-Jun-2018

Environment

Retain 4.0.3.1

Situation

How to Install Retain 4.0.3.1
This is a condensed version of the installation, please see the install section of the documentation.

Resolution

Overview of an Install:

  1. Install Web server
  2. Install Database
  3. Install Retain 4.0.3.1
  4. Post-Install Tasks
  5. Retain Configuration Wizard
  6. Retain Post-Configuration Tasks
     

General Setup Items:

Set the IP address of the server.
Create data volumes for:

  • Archive
  • Index
  • Logs
  • Database (if installed locally)

Install Web Server

Linux:
Install apache from YaST
 
Windows:
Install IIS or apache
If installing IIS, Under Role Services, open Application Development and enable:
    ISAPI Extensions
    ISAPI Filters
 

Database Installation:

If installing Database locally, do so now.     

Supported SQL server include:

  • MySQL 5.5
  • MySQL 5.6 (the Windows version has a bug that only allows it to use C:\ for data)
  • SQL Server 2008 R2, 2012, 2014
  • ORACLE 10/11g

Create and configure a database and user for Retain:

MySQL

After installing MySQL.
Login using the MySQL 5.x Command Line Client
Create a database (e.g. retain) for Retain to use:
CREATE DATABASE retain DEFAULT CHARACTER SET 'utf8' DEFAULT COLLATE 'utf8_bin';
 * This is critical. Not storing the database in UTF-8 format guarantees irreparable corruption for non US-ASCII characters. *
    If you make a mistake, enter this command:
    DROP DATABASE retain;
    then and repeat the database creation step.
 
Create a user for Retain to use to access the database:
GRANT ALL PRIVILEGES ON retain.* TO '(UserName)'@'%' IDENTIFIED BY '(Pass­word)';
GRANT ALL PRIVILEGES ON retain.* TO '(Username)'@'localhost' IDENTIFIED BY '(Password)';
Example, grant access to the 'retain' database to the user 'retain' with the password 'password1':
GRANT ALL PRIVILEGES ON retain.* TO 'retain'@'%'  IDENTIFIED BY 'password1';
GRANT ALL PRIVILEGES ON retain.* TO 'retain'@'localhost' IDENTIFIED BY 'password1';

MS SQL Server

Install as default instance, with Latin 1_ General_C1_AS as standard encoding.
Enable SQL Server Authentication in addition to Windows Authentication
Once installed, Verify server is listening on port 1433 (telnet ip address 1433)
Ensure TCP/IP is enabled - Run SQL Server Configuration Manager
Expand SQL Server Network Configuration
Protocols for MSSQLSERVER
Enable TCP/IP
Run SQL Server Management Studio, connect to Server
Under Security/Logins, right click and select "create Login, (for example Retainuser) that uses SQL Server authentication. Assign a password.
Right click on Databases, and create a new database named Retain and assign Retainuser as the owner. (There are other ways to grant the permissions but this is easiest)

ORACLE

Retain supports the usage of Oracle 10 and 11 on all platforms. However, it is the customer’s responsibil­ity 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 wildly depending the version, OS, storage, clustering, etc. so consult your DBA. There is no one-size-fits-all. This is also true of other SQL Server products, but Oracle even more so.

Using Oracle with Retain consists of:
Installation of the Oracle Server
Setting up a TCP IP listener
Setting up a new database named Retain
Creating a user to access the database, and granting sufficient rights.

Installation
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

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.

Database Creation
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 (which should not be used as is):
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 AUTOEX­TEND ON NEXT  10240K MAXSIZE UNLIMITED
SMALLFILE DEFAULT TEMPORARY TABLESPACE TEMP TEMPFILE 'C:\oracle\product\10.2.0\ora­data\Retain\temp01.dbf' SIZE 20M REUSE AUTOEXTEND ON NEXT 640K MAXSIZE UNLIMITED
SMALLFILE UNDO TABLESPACE "UNDOTBS1" DATAFILE 'C:\oracle\product\10.2.0\ora­data\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 CHAR­ACTER SET (AL16UTF16). If using a GUI based installed, be careful to set these - they are easily missed. (They are located on the Encoding tab of the 10th step or so of the wizard).

User Account Creation
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 roles:
RESOURCE CONNECT

And the following database privileges to the Retain database:
CREATE PROCEDURE
CREATE SESSION
CREATE SYNONYM
CREATE TABLE
CREATE TYPE
CREATE VIEW

Tuning
Tuning Oracle is quite far beyond the scope of this manual. The manuals on Oracle's site, as well as an experienced DBA or extensive training is strongly recommended.

Install Retain 4.0.3.1

Download and unzip Retain
     Linux: In the Retain install directory make all scripts executable by running the command: chmod +x *.sh

If upgrading, save the worker attachment.properties file to a separate location. This file is overwritten during an upgrade. This is important if max.errors has been set to -1. Replace these files after the install.

Run the installer:
     Linux: ./RetainInstall.sh
     Windows: RetainInstall.exe

  • Read and accept the license agreement.
  • Select upgrade and migration options. There are two options: upgrading from a version of Retain older than 3.x, or a new install or upgrade from 3.x.
  • Select the modules which will be installed on the machine. (Retain Server, Stubbing Server, Reporting and Monitoring Server, Worker, and Message Router.)
  •      If upgrading, the installation will detect whether Retain currently exists, and prompt for upgrade options. NOTE: If components already exist on the system, but new features are being added, all new and existing features must be selected for install, AND the upgrade must be selected with the first option: “Upgrade Retain, Preserving configuration†must be selected.
  • The installer will download and configure Java 8 and tomcat 7.

Post-install Tasks

Stop Tomcat

Linux permissions for separate data volumes:

Linux: If using separate data volumes, you must change the directory ownership and permissions:
chown -R tomcat:tomcat <storage directory or disk name>
chmod -R 744 <storage directory or disk name>

Change the logging path to a different volume

MySQL JDBC driver install:

MySQL on Windows or Linux:

  • The MySQL Connector/J  driver must be provided to the Retain Server and/or the Reporting and Monitoring Server and/or the Stubbing Server.
  • Download Connector/J 5.1.21 or higher
  • Copy the mysql-connector-java-5.1.X-bin.jar file to ...RetainServer/WEB-INF/lib (for Retain Server) and/or ...RetainStatsServer/WEB-INF/lib (for the Reporting and Monitoring Server) and/or ...RetainStubbingServer/WEB-INF/lib (for the Stubbing Server).
  • Linux: Change the ownership of the jar file to match the other files with chown tomcat:www mysql-connector-java-5.1.X-bin.jar
  • Linux: Change the permissions of the jar file to match the other files with chmod 755 mysql-connector-java-5.1.X-bin

*Note: This JDBC driver download ONLY applies to MySQL, other database management systems will not require any additional software downloads.

Start Tomcat

Run the Retain Server Configuration Wizard

  • Browse to http://[RetainServerIPAddress]/RetainServer, if you are on the Retain server itself you can use localhost or the IPaddress or hostname of the server Retain is hosted on from any computer on your network.
  • Set the File Path, if you have separate data volumes select Advanced Settings and deselect “Derive all files locations from above specified path†to enter the paths. Click continue.
  • Set the Message Store Database Connection Parameters to your database. Click continue.
  • Set the Configuration Database Connection Parameters to your database. Click continue.
  • Set the Administrator Account username and password. Click continue.
  • Set the SMTP Notification parameters. Click continue.
  • Set the Indexing Engine. Enter the admin username and password. Click continue.
  • Click Complete.

Post-Configuration Tasks:

  • Log into Retain with the admin credentials.
  • Choose Licensing and upload the .pem file.
  • Choose Reporting and Monitoring, configure and download the bootstrap. Click on Reporting and upload the bootstrap.
  • Configure a Module.
  • Choose Worker, configure and download the bootstrap. Browse to http://[RetainWorkerIPAddress]/RetainWorker, and upload bootstrap.
  • Configure a Schedule, Profile, Job.
  • Run the job.

Additional Information

This article was originally published in the GWAVA knowledgebase as article ID 2867.