4.2 Upgrading from Retain 3.5.1.1 or 4.x to Current version

4.2.1 Upgrade changes

Retain 4 contains significant improvements over previous versions. The User Interface in Retain 4 is changed and a completely new search has been implemented. The new search contains a new, high powered indexer and back end which allows searching in multiple new ways on each item to maximize relevant and intuitive results. Due to the increased ability, some system requirements have been increased.

4.2.2 Requirements

  • Storage Space

    While the migration is performed, a new index will be created. The current index storage space will be temporarily increased while the two indexes exist.

    There is a check for at least 4 times the available free space compared to the existing 3.5.1.1 index. A warning will appear if there is less disk space available, this is only a warning, proceed at your own risk.

    Once migration is complete, the old index may be removed and space reclaimed.

    See Estimating Storage Requirements Estimating Storage Requirements.

  • Time and Access

    The upgrade to Retain 4 will take some time, how much depends on how large the Retain archive is. The upgrade includes an update to the configuration database, which is completed at first start-up and should be completed in less than ten minutes, and a migration to a new index. While the index migration may take significant time, the existing index and system will still be available and accessible during the entire process.

  • System Requirements Changes

    The system Requirements have been increased for Retain 4 to 12 GB RAM on the minimum side. Check the requirements in the Technical Support section to verify changes required for the system.

  • Licenses

    Retain 4 will require new licenses to function after the upgrade. Make sure to have the required licenses on hand for the install. An upgraded Retain 4 system will not function until the licenses are applied.

    Make sure to run the install on every component in the installed Retain system to make sure all components are upgraded together. Any Workers and Servers not hosted on the same machine must each have the installer run to be upgraded.

4.2.3 GroupWise Module

If you are archiving with the GroupWise Module, log into Retain and determine which storage flag Retain is currently using. This is the flag you want to choose during the upgrade process. Retain will query GroupWise and update the Item Store Flag in the Retain database for each user.

If you should choose incorrectly, it can be changed in the module. If not set correctly, it will mean that the next job will, at most, do a full dredge.

Please note that after the upgrade to 4.2 there will be a new default Scope setting in Profile(s).

The option "New items" will become the default selection if previously the Date Range to Scan was set to "All Messages (ignore date)" and Duplicate Check was set to anything other than "Try to publish all messages (SLOW)."

Please note that in 4.2 upgrade the controls for the GroupWise Storage Flags have been moved from the Profile to the Module Configuration page.

See the GroupWise module page for more details.

4.2.4 Upgrade Process

If upgrading from Retain 4.0.x the upgrade process should take between 15 and 30 minutes, depending on the size of the system, very large systems may take longer.

  1. Download the latest version of Retain.

    On Linux, you may use the command line "wget http://download.gwava.com/download.php?product=Retain&version=current"

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

    On Linux, in the GUI right-click and select "Extract Here" or on the command line "unzip Retain<version>.zip"

    On Windows, right-click and select "Extract All..."

  3. If on Linux, open a terminal window in the Retain install folder and make the bash script file executable by running the command: "chmod +x *.sh"

  4. Run the installer:

    On Linux: "./RetainInstall.sh"

    On Windows: "RetainInstall.exe"

  5. The installer will check the tomcat version that is installed and will upgrade it to Tomcat 8.0

  6. Retain will detect if a previous version of Retain exists on the server. It will report what components have been installed and will ask if you wish to upgrade the current installation or if you want to add new components as well.

  7. If you choose to install additional components it will ask what you wish to install.

  8. Then the installer will ask if you want to Upgrade Retain, preserving the existing configuration or Overwrite Retain which will replace the configuration file but will not erase data. This is useful in certain troubleshooting circumstances.

  9. After choosing to upgrade or overwrite Retain, the installation will begin. Wait until the installation is finished.

4.2.5 Post-Install Tasks

  1. Browse to Retain Web Console.

  2. The upgrade may require a configuration database update, depending on the version of Retain you upgraded from. Select the ‘Enter Credentials’ button and enter the administrator account username and password. Select the button to start the migration.

    1. During the database Migration, do not interrupt the process. Wait until the process completes.

    2. Once the migration is complete, the system will instruct you to restart tomcat.

    3. Once the update has completed, restart tomcat to initiate the new database.

    4. The tomcat restart will take a little bit longer than a normal restart, as the database needs to be initialized and set up the new interface.

    5. After a few minutes, browse again to the Retain Management interface.

  3. If you have the GroupWise module configured how the GroupWise timestamps are used by Retain have changed.

    1. You will receive a warning page describing what will happen.

    2. You will need to enter the admin credentials.

    3. Choose which timestamp flag Retain will use in the Module.

    4. Retain will update, which will take some time. The Retain interface will not be available until this process completes. In Retain 4.2, this process is done in the background so the interface is available immediately, however jobs will be disabled until the process is complete.

    5. When the migration is complete you will need to restart tomcat. In Retain 4.2, no restart of tomcat is needed, jobs will begin again on schedule once the process is complete.

  4. Login to the Retain Management interface. If upgrading from a version of Retain previous to Retain 4.x, new licenses for Retain 4 must be immediately applied. These licenses should be provided by the sales representative. (Removing old licenses is not required, but may help to keep interface looking clean.)

    1. To install the new licenses, select the ‘Browse’ button from the ‘Submit License’ section at the bottom of the screen. Select the desired license and when back in the Retain interface, select ‘Submit License’ to upload the new license to the system. Repeat the process for each license required for the active and desired modules in the system.

    2. It is a good practice to remove expired licenses from the Retain system to keep the interface clean and to easily see any licensing issue. However, removing expired licenses is not required.

  5. If upgrading from Retain 3.5.1.1:

    1. Immediately go to the Server Configuration page and select the Index tab.

    2. Select the Migrate to 4.0 indexer button.

    3. There are two index options: High Availability Indexer and the standard index. Both options utilize the same high performance index engine and will both provide new searching functionality; however, the 'standard' engine is embedded while the 'High Availability Indexer' is a scalable, external, cluster system for large systems. The default is set to the standard index. The standard index engine is very powerful and sufficient for everything up to extremely large or busy systems.

      If you wish to use the High Availability Index engine, a separate license is required. Please contact support for guidance, system planning, and installation.

    4. Once the migrate button has been pressed, the new indexer section is displayed.

    5. The Standard engine only requires the Retain admin credentials. Enter the administrator credentials then save the changes by selecting the save-changes button to continue.

    6. The index migration begins automatically. During the migration of the index, the active index is displayed at the top of the page. The active index displayed at the top of the page will still be available and fully functional. New search options and features will not be available until the new index becomes active.

    7. The index page is updated every 10 seconds to display the progress. With no archive jobs, migrations of the index will average 60 messages per second on a Linux server, and about 45 messages per second on Windows Server. Migration speed is limited by disk IO, (and network speed with external indexes). Large messages with large attachments will take longer. If archival jobs are running, the speed of the migration will depend wholly on the size and activity of the archival job.

    8. When the index page updates showing the new index is running, the new index has automatically become active.

    9. Once the index migration is complete, the indexer will need to optimize the index files. This is done during the nightly maintenance. The larger or more segmented the indexes the longer this will take. This may temporarily triple the disk space the indexes use as the files are consolidated. It is a recommended to go to the Server Configuration | Maintenance tab and set the Enable Index Optimization to Saturday weekly. The first optimization is the longest and may take many hours, after that it usually only takes minutes and can be done nightly.

  6. The upgrade is complete.

4.2.6 Removing old indexes after Retain 4.0 has completed re-indexing

If you upgraded from Retain 3, all items are re-indexed by the new indexing engine. During the index migration the Retain 3 indexes are available as legacy search, which is automatically disabled once the migration process completes.

You can find the location of your indexes in your ASConfig file. In that file there will be a line that says your path: <indexPath>

  • Windows: C:\Program Files\Beginfinite\retain\RetainServer\WEB-INF\cfg\ASConfig.cfg

  • Linux: /opt/beginfinite/retain/RetainServer/WEB-INF/cfg/ASConfig.cfg

Once you find your index directory, be very careful! You can delete all of the files EXCEPT the solrhome directory, the zoo_data directory (This is not an essential directory, but you don't want to delete it while Retain is running.), and the log.1 file.

4.2.7 Tool Compatibility with Retain 3.x (Lucene) Indexes

Not all tools are compatible with the Retain 3.x (Lucene) indexes.

Tool

Compatibility

Retain web console

Compatible

Publisher

Not compatible

Outlook Plugin

Not compatible

Retain App for Android Phones

Not compatible

Retain App for iOS Phones

Not compatible

Retain Single Sign-on plugin for GroupWise Client

Does not use indexes

Retain Single Sign-on plugin for GroupWise WebAccess

Does not use indexes

GroupWise Archive Migrator/PAM Tool

Does not use indexes

PST Importer

Does not use indexes

Netmail and M+ to Retain Migration Utility

Does not use indexes

PowerShell Sync Script

Does not use indexes