

An upgrade of your Analytics server is required for Server 2024. Follow these steps to upgrade your analytics servers.
Before upgrading the Analytics servers, make sure you have completed the following steps:
The Analytics engine has TLS 1.1 disabled by default. This may cause issues if you're not using TLS 1.2 everywhere throughout your environment.
For this reason, we recommend enabling TLS 1.2 comprehensively throughout your environment. If it is already, no further action is recommended.
If you're not sure whether it is or not, check the registry key on all web and agent servers and then enable TLS 1.2, per the description in Managing TLS protocols and specifying cipher suites.
For assistance with enabling TLS 1.2, contact Support.
You need the following items in order to successfully run the upgrade or installation:
Consider the following when upgrading or installing:
Use the following sections to install Analytics for the first time. If you have previously installed Analytics and want to upgrade, see Upgrading from previous versions.
Before new installations, unzip the Analytics package and open the response-file.properties file in a text editor. Complete the below Common Properties settings in the input file.
Note: For first time installs, all settings are considered and you must specify all response file values. Check to make sure the provided default works with your environment.
The following are available properties in the response-file.properties file:
In former versions of the installer, this was called “Analytics Server folder.” This is the path to the folder containing the Analytics installation files. This value is required for upgrades.
A forward slash ( / ) or a double back slash ( \\ ) should be used as a path separator, rather than a single back slash, as shown in the examples below.
caat.install-dir=C:/CAAT caat.install-dir=C:\\CAAT
Note: Spaces cannot be present within the file path.
In former versions of the installer, this was called “Analytics Server Port Number.” This is the HTTP port to be used for requests to the Analytics engine. The HTTP port will default to 8080 for new installations, but you can configure a different port number. For upgrades, the value entered will only be used to ensure that the CAAT server is not running on that port.
caat.http-port=8080
This option should be set to true. Please note that this option is ignored upon upgrade.
caat.as-windows-service=true
This is the Windows service name. The service name will default to Relativity Analytics Engine if a service name is not provided. Please note that the service name will not change upon an upgrade, and this value is ignored upon upgrade.
caat.windows-service-name=Relativity Analytics Engine
In former versions of the installer, this was called “Analytics Index Directory.” The Analytics data directory must also be created before installing Relativity Analytics. A forward slash ( / ) or a double back slash ( \\ ) should be used as a path separator, rather than a single back slash, as shown in the examples below. This value is required for initial installs.
This is the directory where indexes and structured analytics sets are stored on disk.
caat.single-data-dir= E:/AnalyticsData caat.single-data-dir= E:\\AnalyticsData caat.single-data-dir= //servername/AnalyticsData caat.single-data-dir= \\\\servername\\AnalyticsData
This is the minimum Java Heap size in megabytes. If this is left blank, the default will be used. The default is 1/8 of total physical memory installed on the machine. It is recommended to leave this blank. This value is ignored upon upgrade.
caat.min-heap-size=
This is the maximum Java Heap size (-xmx) in megabytes. For example, 4096. If this is left blank the default will be used. The default is half of total physical memory installed on the machine.
caat.max-heap=
This value must be set to true.
caat.http.authentication-status=true
In former versions of the installer, this was called “REST Password.” This is the password you create for the REST API user. This can be any password that you choose, but for ease of use, you may want to enter your Relativity Service account password. Whatever you enter here corresponds only with the REST API password field on the Analytics server that you will add in Relativity after you install the Analytics server here. This value is not related to any pre-existing part of the system, meaning that it is not the password for a SQL login, Windows Domain user, or Relativity user. This value is required for upgrades.
Note: The caat.http-password value entered here must be 20 characters or less.
caat.http-password=SuperSecretPassword
Note: It is not possible to change an existing password with this entry. In order to change the password, see Changing the REST password.
In former versions of the installer, this was called “REST Username.” This is the username that a system admin or Relativity uses to authenticate with the REST API. This can be any user name that you choose, but for ease of use, you may want to enter your Relativity Service account user name. Whatever you enter here corresponds only with the REST API user name field on the Analytics server that you will add in Relativity after you install the Analytics server here. This value is not related to any pre-existing part of the system, meaning that it is not a SQL login, Windows Domain user, or Relativity user. This value is required for upgrades.
Note: It is not possible to change an existing username with this entry.
caat.http-user=AnalyticsUser
This value needs to be set to true. This value is ignored upon upgrade.
caat.ssl-status=true
This is the file path to the existing valid PKCS12 certificate-key file. This value is ignored upon upgrade. A forward slash ( / ) or a double back slash ( \\ ) should be used as a path separator, rather than a single back slash, as shown in the examples below.
caat.ssl-certificate-key-path=C:/CertPath/AnalyticsCert.pfx caat.ssl-certificate-key-path=C:\\CertPath\\AnalyticsCert.pfx
Note: This value is required. The Relativity Analytics engine accepts both self-signed and trusted certificates. To create a self-signed certificate, see Updating the default SSL/TLS certificate.
This is the SSL certificate password. This value is ignored upon upgrade.
caat.ssl-password=CertificatePasswordHere
Note: This value is required before performing a first time install.
Before running the Analytics Server Installer:
Note: This service may be named Relativity Analytics Engine depending on your version of Relativity.
During the installation or upgrade of the Analytics Engine, the process will log to a file, such as installer.log, in the logs directory. For example, CAAT-win64-kcura-[Version].GA\logs.
The pattern for the log message is:
[log-level] [date] [thread-name] message
Example: [INFO] [2017-01-18 19:05:54 [main]: Loading installation options
Note: Log messages will be appended to the same log file on subsequent runs.
The Analytics upgrade includes an updated version of PostgreSQL, which is installed in the background. Review the following guidelines for applying this upgrade:
Ensure that you have Microsoft Visual C++ Redistributables 2010/2012/2013/2015, x64 and x86, installed. For download links, see Microsoft's Support site.
After you apply the upgrade and verify all Analytics components are functioning correctly, delete the old PostgreSQL install directory from the following locations to complete the uninstall:
${install_dir}/CAAT/pgsql_9.3
${install_dir}/CAAT/pgsql_9.6
Also check the corresponding folders in the indexshare location (.ufx/rdbms_9.3 and rdbms_9.6).
Before upgrades or new installations, unzip the Analytics package and open the response-file.properties file in a text editor.
For upgrades, only the following settings are considered:
For a complete list of settings and descriptions, see Installing Analytics for the first time.
Note: The caat.upgrade-now response file property is no longer used.
Complete the following Common Properties settings in the input file:
In former versions of the installer, this was called Analytics Server folder.
This is the path to the folder containing the Analytics installation files. This value is required for upgrades.
A forward slash ( / ) or a double back slash ( \\ ) should be used as a path separator, rather than a single back slash, as shown in the examples below.
caat.install-dir=C:/CAAT caat.install-dir=C:\\CAAT
Note: Spaces cannot be present within the file path.
In former versions of the installer, this was called REST Username.
This is the username that a system admin or Relativity uses to authenticate with the REST API. This can be any username that you choose, but for ease of use, you may want to enter your Relativity Service account username. Whatever you enter here corresponds only with the REST API username field on the Analytics server that you will add in Relativity after you install the Analytics server here. This value is not related to any pre-existing part of the system, meaning that it is not a SQL login, Windows Domain user, or Relativity user. This value is required for upgrades.
Note: It is not possible to change an existing username with this entry.
caat.http-user=AnalyticsUser
In former versions of the installer, this was called REST Password.
This is the password you create for the REST API user. This can be any password that you choose, but for ease of use, you may want to enter your Relativity Service account password. Whatever you enter here corresponds only with the REST API password field on the Analytics server that you will add in Relativity after you install the Analytics server here. This value isn't related to any pre-existing part of the system, meaning that it isn't the password for a SQL login, Windows Domain user, or Relativity user. This value is required for upgrades.
Note: The caat.http-password value entered here must be 20 characters or less.
caat.http-password=SuperSecretPassword
Note: It is not possible to change an existing password with this entry. In order to change the password, see Changing the REST password.
This option defaults to false. When false, this checks whether the Analytics server needs a major version PostgreSQL upgrade in order to succeed. If a PostgreSQL upgrade is needed, the Analytics server upgrade will fail, and you will see a message to check the installation prerequisites. Once you have satisfied all the prerequisites, set this value to true and re-run.
caat.allow-postgres-data-upgrade=false
This property enables or disables in place upgrades for PostgreSQL data. It defaults to false, indicating that data is copied during upgrade.
caat.pg.upgrade-in-place=false
Review the behavior based on the following settings for this property:
If you use the bin/upgrade command directly, set this property as follows:
.\upgrade.cmd -Dcaat.upgradePgInPlace="true"
This property enables or disables a disk space check override when CAAT is performing a major version PostgreSQL upgrade. It defaults to false, indicating that a disk space check is run.
caat.overrideDiskSpaceCheck=false
To disable the disk space check, set this property to true.
If you use the bin/upgrade command directly, set this property as follows:
.\upgrade.cmd -Dcaat.overrideDiskSpaceCheck="true"
Consider the following before running the Analytics Server Installer:
Note: This service may be named “Relativity Analytics Engine” depending on your version of Relativity.
During the installation or upgrade of the Analytics Engine, the process will log to a file, such as installer.log, n the logs directory. For example, CAAT-win64-kcura-[Version].GA\logs.
The pattern for the log message is:
[log-level] [date] [thread-name] message
Example: [INFO] [2017-01-18 19:05:54 [main]: Loading installation options
Note: Log messages will be appended to the same log file on subsequent runs.
Use the certificate generated by Relativity Secret Store when the Analytics server is registered. For more information, see Relativity Secret Store.
Your certificate uses one of the following keystores. To determine which one is in use, see Updating a certificate.
If you do not have the password, you must install a duplicate copy of Analytics with a new certificate. You need to replace the keystore file in the original installation with the duplicate generated as part of the new installation. Next, you need to change the password that the keystore is using to the password from the new installation. See Analytics - How to change the keystore password for Analytics on the Relativity Community site.
Use the following steps to update a certificate.
C:\CAAT\jdk1.8.0_212b04\bin\keytool.exe -keystore <<PathToKeystore>> -list -v
Replace the <<PathToKeystore>> placeholder in this command with the keystore path from step 1b.
C:\CAAT\jdk1.8.0_212b04\bin\keytool.exe -delete -keystore <<PathToKeystore>> -alias <<ALIAS_NAME>>
C:\CAAT\jdk1.8.0_212b04\bin\keytool.exe -importkeystore -srckeystore <<Certificate>> -srcstorepass <<CertPassword>> -srcstoretype pkcs12 -destkeystore <<PathToKeystore>> -deststorepass <<DestinationsPassword>> -deststoretype JKS
https://<servername.FQDN>:8443/nexus/r1
Note: If you use Secret Store, you do not need to push the certificate to the agent, web, and message broker, including the Relativity Service Bus, servers because they already trust certificates from it. However, if you use self-signed certificates, you must update certificates on these servers.
Verify in Relativity that the Analytics server URL uses the fully qualified domain name (FQDN) and not the server name or IP address. Navigate to the Servers tab, and check the URL of the Analytics server. If it does not contain the FQDN, then follow these steps:
When setting up Analytics, you have the option of disabling TLS 1.0 and 1.1 to enforce stricter security protocols. Additionally, you can specify which cipher suites you want to use or block.
To do this, complete the following steps:
If the file already exists, append the following lines:
<!-- Eliminate Insecure Protocols --> <Call name="addExcludeProtocols"> <Arg> <Array type="java.lang.String"> <Item>SSL</Item> <Item>SSLv2</Item> <Item>SSLv3</Item> <Item>TLSv1</Item> <Item>TLSv1.1</Item> </Array> </Arg> </Call>
If the file does not exist yet, create a new XML file with that name and file path. Enter the following full text:
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!-- Tweak SslContextFactory Includes / Excludes --> <Configure id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory$Server"> <!-- Eliminate Insecure Protocols --> <Call name="addExcludeProtocols"> <Arg> <Array type="java.lang.String"> <Item>SSL</Item> <Item>SSLv2</Item> <Item>SSLv3</Item> <Item>TLSv1</Item> <Item>TLSv1.1</Item> </Array> </Arg> </Call> </Configure>
(Optional) To specify allowed or excluded cipher suites, append the following to C:\CAAT\etc\ssl\tweak-ssl.xml.
Note: The cipher suites used in this sample text are examples only. We do not currently endorse specific cipher suites, and we recommend discussing preferred suites with your security team.
<!-- Include allowed cipher suites --> <Call name="setIncludeCipherSuites"> <Arg> <Array type="String"> <Item>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</Item> <Item>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</Item> <Item>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Item> <Item>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</Item> <Item>TLS_RSA_WITH_AES_256_GCM_SHA384</Item> <Item>TLS_RSA_WITH_AES_128_GCM_SHA256</Item> <Item>TLS_RSA_WITH_AES_256_CBC_SHA256</Item> <Item>TLS_RSA_WITH_AES_128_CBC_SHA256</Item> </Array> </Arg> </Call> <!-- Exclude weak ciphers --> <Call name="addExcludeCipherSuites"> <Arg> <Array type="String"> <Item>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</Item> <Item>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</Item> <Item>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</Item> <Item>TLS_RSA_WITH_DES_CBC_SHA</Item> <Item>TLS_DHE_RSA_WITH_DES_CBC_SHA</Item> <Item>TLS_RSA_EXPORT_WITH_DES40_CBC_SHA</Item> <Item>TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</Item> <Item>TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</Item> </Array> </Arg> </Call>
Open C:\CAAT\start.ini. Look for the tweak-ssl.xml file path. If it's not listed yet, append it to the bottom as follows:
## Override SSL configuration file etc/ssl/tweak-ssl.xml
Note: If you do not have a file called start.ini, do not create a new one. Instead, contact our Support team at support@relativity.com.
Restart the Content Analyst (CAAT) Windows service.
Update the registry key on all web and agent servers as follows. If you previously disabled TLS 1.0 and 1.1 for other parts of Relativity, you can skip this step.
Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319] "SchUseStrongCrypto"=dword:00000001 [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319] "SchUseStrongCrypto"=dword:00000001
Verify that the connection works by clicking Save in the Analytics Server layout.
When your primary SQL Server uses SSL encryption, you must satisfy the following additional environment requirements in order for the Analytics server to communicate with SQL Server:
Complete the following steps to install a SQL Server's certificate in your Analytics server KeyStore:
<CAAT install drive>\jdk1.x\jre\lib\security
The <CAAT install drive> reference represents the Analytics server installation folder, and x represents the version of the JDK installed on your Analytics server. Browse to the security directory using Windows Explorer first to ensure you use the correct Analytics server installation path.
..\..\bin\keytool.exe -import -alias <CN> -keystore cacerts -file <path to cert file from Step 1>
Replace <CN> with the CN property recorded in the SQL Server's certificate and replace <path to cert file from Step 1> with the path location of the certificate file you copied to the Analytics server.
Note: This step is only required if your Java KeyStore is password protected. Please refer to Oracle for default Java password information.
When running an Analytics server with a SQL Server that uses SSL encryption, the name of the SQL Server recorded on the Servers tab in Relativity and the name entered during Analytics server installation must match the CN value recorded in the SQL Server's security certificate. When running the Analytics Server installation, enter the CN property value from your SQL Server's certificate in the Primary Database Server Instance field on the Primary Database Server Configuration dialog.
Note: If your SQL Server's Name value recorded on the Servers tab in Relativity does not match the CN property in the SQL Server's security certificate, contact Relativity Support for assistance with updating the SQL Server name in Relativity. Change the SQL Server's Name value in Relativity after you complete the Analytics installation.
If you need to change the REST password, perform the following steps:
Note: You'll need an encryption tool to encrypt a new BCrypt Hash Password. We recommend using BCrypt Calculator.
When updating the hash value, ensure that it starts with $2a$ as in the example above. The 2y tag is not supported by CAAT at this time. The hash value will likely come from the generator with the 2y tag like the following:
$2y$12$hoLehyRmWV3Kjs6ORLtFUOSiCbQeFVt9xt9v8TrtnomVf3Z0oXo/6
When you add it to the realm.properties file, ensure it has $2a$ at the beginning like the following:
$2a$12$hoLehyRmWV3Kjs6ORLtFUOSiCbQeFVt9xt9v8TrtnomVf3Z0oXo/6
The number after the 2a tag indicates the number of rounds. The default value of 12 is typically fine.
Once the password is updated on the Analytics server, you must update it in Relativity.
We do not recommend uninstalling the Analytics Server application for any reason as it causes data loss. If you uninstall the Analytics Server application from the analytics server, all structured analytics sets created in Relativity cannot be used with another installation. There is no way to merge a previous Analytics Server installation with a new installation. As a result, structured analytics sets become unusable.
You should not uninstall the application from the server unless you're certain you will not use the server for Analytics functionality in the future, and you understand that uninstalling Analytics renders structured analytics sets unusable.
If you still need to uninstall the Analytics components from the server, complete the following steps:
On this page
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!