Skip to content

Latest commit

 

History

History
181 lines (120 loc) · 16.4 KB

relativity_server_cli_setup.md

File metadata and controls

181 lines (120 loc) · 16.4 KB

Set up Environment Watch and/or Data Grid Audit using the Relativity Server CLI

Now that you have installed the required Elastic components for Environment Watch and/or Data Grid Audit, you will configure the integration between Elastic and Relativity by running the Relativity Server CLI on your Primary SQL Server. For Environment Watch, the Relativity Server CLI will also import all of the indexes, alerts, and dashboards that Relativity has developed and shipped as part of the Environment Watch product.

For customers already using Data Grid Audit prior to upgrading to Relativity Server 2024, please see the Important information for existing Data Grid Audit customers section below for additional context on what will happen when you run the ‘Set up Data Grid’ workflow using the Relativity Server CLI for the first time.

Before you start

Before entering the Environment Watch or Data Grid Audit setup workflows, perform or check the following:

  1. Confirm that all Elastic components are installed and verified from stages 1 and 2 of this installation guide. This includes ensuring that the minimum versions of Elasticsearch, Kibana, and APM Server that are specified in the Environment Watch release bundle that you are using are installed and that Elastic certificates have been installed on all Elastic hosts.

Note

Ensuring that you are on the minimum supported version of Elasticsearch for Data Grid Audit as specified in the release bundle is especially important for existing Data Grid Audit customers that may be running legacy versions of Elasticsearch. If you are an existing Data Grid Audit user, you must be on Elasticsearch 7.17 when you initially run the Data Grid Audit setup using the Relativity Server CLI. After you successfully configure Data Grid Audit using the Relativity Server CLI, you can then upgrade to Elasticsearch 8.17 in any cluster being used for Data Grid Audit.

While 7.17 is the minimum supported version for the initial release of the Relativity Server CLI in Server 2024 Patch 1, you should always check the minimum version requirements in the specific Environment Watch release bundle that you are using.

  1. Be prepared to enter admin usernames, passwords, and URLs for Relativity and Elastic components.
  2. [Data Grid Audit only] Install the mapper-size plugin on all nodes in your Elasticsearch cluster (instructions available here). You also must restart the Elasticsearch service after installing the plugin.
  3. [Data Grid Audit only] Before upgrading to Elasticsearch 8.17, the ESIndexCreationSetting may need to be updated. For further details, please refer to the Instance settings' descriptions - Server2024.
  4. At least the minimum Relativity major version and patch specified in the Environment Watch bundle you intend to deploy is installed on all servers in the environment. See the release bundle requirements for the minimum version required.
  5. Verify that the InfraWatch Services application is installed in your Relativity instance (this RAP is delivered as part of the base Relativity Server 2024 installation package).
  6. Follow these instructions to whitelist all hosts with Elastic installed for Secret Store access.
  7. Ensure that you have access to Relativity, as well as the Primary and Distributed SQL Servers
  8. The user must have Command Prompt installed to run the CLI executable.

Set up Environment Watch

Follow these steps to configure Environment Watch using the Relativity Server CLI. If you do not need to set up Environment Watch, proceed to the ‘Set up Data Grid Audit’ section below.

This only needs to be done on your SQL Primary Server.

  1. Install Elastic certificates on your SQL Primary Server
  2. Download the CLI – From here, download the release bundle.
  3. Open Command Terminal - Launch Command Prompt v7 from the Start menu.
  4. Extract the CLI - Navigate to the directory where the gold release bundle was downloaded to and extract the bundle and then extract Relativity.Server.Cli.YY.x.xxxx.zip.
  5. Run the Setup Command – From Command Prompt, execute the following command to enter the setup workflow:
./relsvr.exe setup
  1. Select Environment Watch
  2. [Only applicable if Environment Watch has been set up previously] Choose setup type – If Environment Watch has been set up on this host previously, you will be prompted to select “Upgrade” or “Rerun Setup”. If you are setting up Environment Watch for the first time, you will not be prompted to make this selection and the setup process will continue to the next step.
  3. Provide Relativity parameters – Enter the Relativity admin username and password and Relativity URL.
  4. Provide Elasticsearch parameters - Enter the Elasticsearch admin username and password and Elasticsearch cluster endpoint URL (any node in your cluster will work, but we recommend providing the node URL for the master node where you first installed Elasticsearch in step 1 of this installation guide).
  5. Provide APM Server parameters – Enter your Elasticsearch APM Server Endpoint URL.
  6. Provide Kibana parameters – Enter your Elasticsearch Kibana server Endpoint URL.
  7. Verify the generated API keys – To verify that the API keys used for authenticating Elastic to Relativity were generated:
    1. Open Kibana
    2. Navigate to the path: /app/management/security/api_keys
    3. Verify that API keys for rel-alerts and rel-infrawatch are present. Note: these API keys will need to be refreshed every six months.
  8. Install Elastic certificates on all Web Servers in your environment. Restart services on each host after installing the certificates
  9. Install Elastic certificates on all Agent Servers in your environment. Restart services on each host after installing the certificates

If the setup completes successfully, Environment Watch is now configured for your environment. If you encountered any errors while entering Relativity or Elastic parameters, you will have three retry attempts before the CLI forces an exit and you must restart the setup process.

The following toggles are configured during the Environment Watch setup, which includes enabling application-level instrumentation and other related features:

Primary Environment Watch Toggle:

  • Relativity.EnvironmentWatch.Toggles.EnableEnvironmentWatchToggle

OTEL (OpenTelemetry) Toggles:

  • Relativity.EnvironmentWatch.Toggles.EnableOtelProvidersForKeplerServicesToggle
  • Relativity.EnvironmentWatch.Toggles.EnableOtelProvidersForAgentsToggle
  • Relativity.EnvironmentWatch.Toggles.EnableOtelProvidersForCustomPagesToggle
  • Relativity.EnvironmentWatch.Toggles.EnableOtelProvidersForServiceHostToggle
  • Relativity.EnvironmentWatch.Toggles.EnableOtelSqlClientDbStatementForTextToggle

Invariant Toggles:

  • Invariant.EnvironmentWatch.Toggles.EnableEnvironmentWatchToggle
  • Invariant.EnvironmentWatch.Toggles.EnableOtelProvidersForQueueManager
  • Invariant.EnvironmentWatch.Toggles.EnableOtelProvidersForWorker
  • Invariant.EnvironmentWatch.Toggles.EnableOtelSqlClientDbStatementForTextToggle

Audit-Related Toggle:

  • Relativity.Audit.Common.Toggles.ElasticAPIKeyAuthenticationToggle"

Refer to the Troubleshooting Guide if you encounter any issues.

Set up Data Grid Audit

This section covers the steps for configuring the integration between Relativity and Elasticsearch for Data Grid Audit.

If you are setting up Data Grid Audit for the first time, you will also need to install the Audit application to workspaces and add the Audit agents. See here for more information about the Audit agents.

Important information for existing Data Grid Audit customers

If you have been using Data Grid Audit prior to upgrading to Relativity Server 2024 Patch 1 or later, running the Relativity Server CLI’s ‘Set up Data Grid’ workflow will update how your Elasticsearch cluster authenticates into Relativity. Prior to Server 2024 Patch 1, Data Grid Audit relied on a Elastic plug-in called Custom Realms for authentication. Starting with Server 2024 Patch 1, authentication no longer requires Custom Realms and is now based on an API key-based OAuth2 authentication method.

Once you have cut over to the new API key-based authentication using the Relativity Server CLI, you no longer need to use the Elastic Platinum license key that Relativity previously provided as part of our Elasticsearch installation package (“DataTron”) to use Data Grid Audit. Moving forward, you will use the free/open Elastic license, or optionally apply a Platinum or Enterprise license key held by your organization if you are interested in utilizing Elasticsearch features that are not supported under the free/open license. No core Data Grid Audit functionality is impacted when you downgrade to the free/open license.

All Relativity Server customers that use Data Grid Audit will be required to upgrade to at least Server 2024 Patch 1, cut over to the new API key-based authentication using the Relativity Server CLI, and swap out the Relativity-provided license key for a free/open license or a Platinum/Enterprise license held by your organization by early 2026 in order for Data Grid Audit to continue working.

Steps 12-15 below include important instructions for any existing Audit users that are setting up Data Grid using the Relativity Server CLI for the fist time.

☝️
REMINDER: If you are an existing Data Grid Audit user, you must be on Elasticsearch 7.17 when you initially run the Data Grid Audit setup using the Relativity Server CLI. After you successfully configure Data Grid Audit using the Relativity Server CLI, you can then upgrade to Elasticsearch 8.17 in any cluster being used for Data Grid Audit.

Set up instructions

Follow these steps to set up Data Grid Audit using the Relativity Server CLI.

All setup will occur on the SQL Primary server.

Note: If you have already run the ‘Set up Environment Watch’ workflow on this host, you do not need to repeat steps 1-2 below.

  1. Install Elastic certificate on SQL Primary Server
  2. Download the CLI – From here, download the release bundle.
  3. Open Command Terminal - Launch Command Terminal v7 from the Start menu.
  4. Extract the CLI - Navigate to the directory where the release bundle was downloaded to and extract the Relativity.Server.Cli.YY.x.xxxx.zip.
  5. Run the Setup Command – From Command Prompt, execute the following command to enter the setup workflow:
./relsvr.exe setup
  1. Select DataGrid
  2. [Only applicable if Data Grid Audit has been set up previously using the Relativity Server CLI] Choose setup type – If Data Grid Audit has been set up on this host previously, you will be prompted to select “Rerun Setup” or “Exit”. If you are using the Relativity Server CLI to set up Data Grid Audit on this host for the first time (even if you began adopting Data Grid Audit before the Relativity Server CLI was initially released), you will not be prompted to make this selection and the setup process will continue to the next step.
  3. Provide Relativity parameters – Enter the Relativity admin username and password and Relativity URL.
  4. Provide Elasticsearch parameters - Enter the Elasticsearch admin username and password and Elasticsearch cluster endpoint URL (any node in your cluster will work, but we recommend providing the node URL for the master node where you first installed Elasticsearch in step 1 of this installation guide).
  5. Verify the generated API keys – To verify that the API keys used for authenticating Elastic to Relativity were generated:
    1. Open Kibana
    2. Navigate to the path: /app/management/security/api_keys
    3. Verify that API keys for rel-datagrid is present. Note: This API key will need to be refreshed every six months.
  6. Restart Relativity services

Note

Steps 12 -15 are only applicable if you are running the CLI setup workflow to cut over from the legacy custom realms-based authentication to API key-based authentication.

  1. Verify that API key authentication is being used – Execute the below query at the EDDS database level to verify that Elastic API key authentication is enabled.

Select TOP(50) * from [EDDSLogging].[eddsdbo].[RelativityLogs] where message like '%elastic api key authentication%' ORDER by 1 desc

SELECT * FROM [EDDS].[eddsdbo].[Toggle] where name ='ElasticAPIKeyAuthenticationToggle'

  1. Verify that the Audit dashboard is functional
    1. Navigate to the Audit tab in your Relativity environment.
    2. Verify that the Audit dashboard graphs and data is loading.
  2. Update license key – After successfully running the Data Grid setup and verifying that API key authentication is now being used, you need to update your license to free/open or a different Platinum or Enterprise license that is not the one previously provided by Relativity.
    1. Open Kibana and navigate to Stack Management -> License management
    2. Update your license

Note

Steps 16-17 are only applicable if you have not already installed Elastic certificates on Web and Agent Servers during Environment Watch setup or a previous Data Grid Audit setup.

  1. Install Elastic certificates on all Web Servers in your environment. Restart services on each host after installing the certificates.
  2. Install Elastic certificates on all Agent Servers in your environment. Restart services on each host after installing the certificates.

Note

Step 18 is only applicable if you are doing a first-time setup of Audit in your Relativity instance.

  1. Install Audit application and agents - If you are setting up Data Grid Audit for the first time, you will also need to install the Audit application to workspaces and add the Audit agents. See here for more information about the Audit agents.

If the setup completes successfully, the integration between Elasticsearch and Relativity for Data Grid Audit is now configured for your environment. If you encountered any errors while entering Relativity or Elasticsearch parameters, you will have three retry attempts before the CLI forces an exit and you must restart the setup process.

Refer to the Troubleshooting Guide if you encounter any issues.

Elastic relativity_dashboard_user role

After you complete all five steps of this installation guide and have Environment Watch fully set up in your environment, you need to provide any user that should have access to the alerts and dashboards in Kibana with Elastic access credentials. You will do this by creating users in Kibana. When you create users in Kibana, you will need to assign them a ‘role’. When you run the Environment Watch or Data Grid setup workflow, the Relativity Server CLI will create a security role called ‘relativity_dashboard_user’. We recommend using this role for any users in your organization that should be able to access alerts and dashboards. The role has least privileges to ensure they can see all dashboards and alerts but with permissions restrictions to prevent them from creating or editing alerts, dashboards, and indexes.

You can see the privileges associated with the relativity_dashboard_user role by navigating to Stack Management > Roles > relativity_dashboard_user in Kibana.

Important

In order to extend the ability to export saved searches, go to the kibana.yml file on the server where Kibana is installed, update ‘xpack.reporting.roles.enabled’ to “false”, and then restart the Kibana service.

Next

If you are setting up Environment Watch proceed to stage 3: Install Environment Watch on all hosts