Pre-installation

For the IIS on Windows Server 2012 R2 or Windows Server 2016, use this procedure to view the minimum role service requirements for Relativity:

1. Open the Server Manager on Windows Server 2012 R2 or Windows Server 2016.
2. Click Manage to display a drop-down menu.
3. Click Add Roles and Features. The Add Roles and Features wizard appears.

   

4. Click Next on the Before you begin dialog box.
5. Click Next on the Select installation type dialog box.
6. On the Select destination server dialog box, select Server Roles.
7. Select Web Server (IIS), and then click Install.
8. On the pop-up window, ensure that Include management tools (if applicable) is checked, and then click Add Features.
9. Click Next to go to the Features page.

10. Review the following illustration for Features configuration settings:

    

11. Click Next to confirm the applicable Features.
12. Click Next on the Web Server Role (IIS) page.
13. On the Role Service page, review the following illustration for minimum role service requirements for Relativity:

14. Click Next to confirm the Role Services.
15. Click Install.

Logging is a default role installed on the IIS and enabled in most environments. Use the following instructions to set the maximum size for the log files:

1. Open the Server Manager.
2. On the Tools menu, select Internet Information Services (IIS) Manager.
3. Expand the server node to display the Features View.
4. Double-click the Logging icon to display the Logging page.

   

5. Update the maximum file size for your environment if necessary. The following illustration shows the maximum file size used to restrict the log files from growing larger than 3 MB.

   

If you manually installed the failed trace logging through the Role Services on your IIS, complete the following steps to set the maximum number trace files stored.

1. Open the Server Manager.
2. On the Tools menu, select Internet Information Services (IIS) Manager.
3. Expand the server node to display the Features View.
4. Highlight the Default Web Site.
5. Double-click the Failed Request Tracing icon to display the Failed Request Tracing Rules page.

   

6. Right-click on the rules to display a pop-up menu, and then click Edit Site Tracing.

   

7. Update the value in the Maximum number of trace files box. This value should be set no higher than 500.

To set up SSL on your web server, you must obtain a certificate, which is digital identification document used by the browser to authenticate the server. A server certificate contains detailed identification information, such as the name of the organization affiliated with the server content, the name of the organization that issued the certificate, and a public key used to establish an encrypted connection. It provides a way for the browser to confirm the authenticity of web server content and the integrity of the SSL-secured connection before transmitting information.

You can obtain a certificate from Microsoft Certificate Services or from a mutually trusted CA. A CA confirms your identity to ensure the validity of the information contained in your certificate. In general, you must provide your name, address, organization, and other information.

Note: If you do not issue your server certificate through Microsoft Certificate Services, a third-party certification authority must approve your request and issue your server certificate.

After obtaining an SSL certificate, install it in the certificate store on your web server. For more information, see Import or export certificates and private keys on the Microsoft Windows website.

The IIS resets after you configure the HTTPS site bindings and update the SSL setting as described in the following section.

Use these steps to configure HTTPS site bindings:

1. Open the IIS Manager.
2. In the IIS Manager Connections pane, expand Sites.
3. Right -click on the Default Web Site, and then click Edit Bindings on the menu.

   

4. Click Add to display the Add Site Binding dialog box.

   

5. In the Type drop-down menu, select https.
6. In the SSL certificate drop-down menu, select your certificate.
7. Click OK. You now see https listed in the Type column.
8. Click Close.

Use the following steps to configure SSL settings on the IIS:

1. Open IIS Manager.
2. Navigate to the Relativity virtual directory, and then select Relativity.
3. Double-click SSL Settings.
4. Select Require SSL.

   

5. Click Apply in the Actions pane.

You also need to enable HTTPS for the Service Host Manager service, which must run on all web and agent machines that use Relativity. For a detailed overview of this service and configuration steps, see Service Host Manager.

You must enable Microsoft DTC on the Agent server along with the following configuration changes:

1. Add the Application Server role and select Distributed Transactions. Select Incoming Remote Transactions and Outgoing Remote Transactions.

Note: As of Windows Server 2016 the Application Server role has been deprecated. Use the Distributed Transaction Coordinator, if it is not present on your machine download the Microsoft Distributed Transaction Coordinator (MSDTC) 2016 Management Pack for Microsoft System Center located here, download.

2. Type dcomcnfg on your Start menu , and then press Enter to open Component Services.
3. Expand Component Services > Computers > My Computer > Distributed Transaction Coordinator.
4. Right-click Local DTC, and then click Properties.
5. Click the Security tab.
6. Select the following check boxes:
   • Allow Remote Clients
   • Allow Inbound
   • Allow Outbound
7. Click Apply.
8. Click Yes to restart the MSDTC service.
9. Click OK.

You must enable HTTP activation on your agent server as follows for Microsoft Windows Server 2012 R:

1. Click Start > Administrative Tools > Server Manager.
2. In the Server Manager Dashboard, click Manage > Add Roles and Features.
3. In the Add Roles and Features, choose Server Selection.
4. Select the server running the agents is selected in the Server Pool box, and then click Next.
5. Click Features in the sidebar of the wizard.
6. Select the following check boxes in the Feature box:
   • .NET Framework 3.5 Features

   Note: Ensure all check boxes below .NET Framework 3.5 Features are checked.

   • .NET Framework 4.5 Features

   Note: Ensure all check boxes below .NET Framework 4.5 Features are checked.

   Make sure that HTTP Activation is installed and selected when you expand each of these sections.

7. Install any missing features are necessary.
8. When the installation is complete, expand .NET Framework 3.5 Features and .NET Framework 4.5 Features to verify that HTTP Activation is installed. See the following screen shot:

   

Use the following guidelines to optimize the RabbitMQ installation:

• RabbitMQ installation—for a typical installation, install RabbitMQ on a server or VM that is accessible throughout your Relativity instance. Must be accessible by all Web and Agent servers. Minimum of 2 GB of RAM, 2 CPU cores, and 10 GB of free disk space. Recommend 4-8 GB of RAM, 4 CPU cores, 40 GB of free disk space. Additionally, in environments where large batch jobs may be sent to RabbitMQ, such as mass conversions with greater than 25,000 documents, disk IO may become a factor in performance. Relativity recommends RabbitMQ’s mnesia database be located on a drive with less than 15ms latency and at least 30 mb/sec read/write speeds. For information about configuring RabbtitMQ’s directories, see the RabbitMQ website.
• Clustering and High Availability—a typical Relativity installation requires only a single RabbitMQ server. However, high availability can be achieved by deploying multiple RabbitMQ servers in a cluster. For more information, see Setting up RabbitMQ for high availability.

Before installing RabbitMQ, complete the following prerequisites:

• If you wish to have RabbitMQ and Relativity communicate over TLS, see Certificate requirements for RabbitMQ.

• Ensure that you have the prerequisites for RabbitMQ. You need to meet these requirements to set up your cluster correctly.
• For a typical installation, identify the server or VM where you want to install RabbitMQ. To install RabbitMQ on multiple hosts, identify the servers or VMs for this purpose. The cluster can have any number of servers, but three servers is recommended. For more information, see Best practices for RabbitMQ.
• Relativity agent and web servers must be able to communicate with the cluster over the following ports:
  • TCP: 5672 (non TLS configurations) and/or 5671 (TLS configurations)
  • HTTP(S): 15672 (non TLS configurations) and / or 15671 (TLS configurations)

Note: You must use RabbitMQ version 3.11.x or 3.12.x and a compatible version of Erlang. For compatibility details, see Erlang Version Requirements.. If you intend to use RabbitMQ 3.10.x, or Erlang version 25.0 or higher, you must have Relativity Server 2022 Patch 2 for 12.1.537.3 (released on January 5, 2023) installed, and you must have valid Community credentials to access and download it. Ensure that you're using the 64-bit version of Erlang, or else the system will be constrained to 2GB of memory.

Complete the following steps to install Erlang and RabbitMQ:

1. Download and install the latest version of Erlang that is compatible with RabbitMQ 3.11.x, or 3.12.x. Note that you cannot currently run version 3.12.x with any supported version of Erlang above v25.x. With how frequently both RabbitMQ and Erlang upgrade their products, we recommend you review the RabbitMQ-Erlang version requirements here. Make sure to run the installer in Administrator mode.

2. Complete the steps in the Installation Configuration Wizard.
3. When the installation process completes, click Close. You have now installed Erlang.

4. Download and install RabbitMQ 3.11.x or 3.12.x here. Be sure to run the installer in Administrator mode.

5. Complete the steps in the Installation Configuration Wizard.
6. When the installation process completes, click Finish. You have now installed RabbitMQ.
7. Search "RabbitMQ Command Prompt (sbin dir)" on your machine. Open the RabbitMQ command prompt.
8. In the RabbitMQ command prompt, run the following command:

rabbitmq-plugins enable rabbitmq_management

This command enables the management plugin, management UI, and management API. Relativity's RabbitMQ provider requires the management API to perform certain operations.

9. Restart the RabbitMQ Windows Service.
10. Open a browser and navigate to http://localhost:15672/
11. Log in with the following credentials:
    • Username: guest
    • Password: guest .

Note: The default user guest can only log in from local host.

You should see an overview and your server displaying various green statistics.

Note: RabbitMQ requires .NET 3.5

After installing Erlang and RabbitMQ, you need to complete the following steps to configure RabbitMQ:

• Create a new virtual host to be used by Relativity
• Create a new user to be used by Relativity

Create a new virtual host to be used by Relativity

Complete the following steps to create a new virtual host to be used by Relativity:

Note: Virtual hosts in RabbitMQ are analogous to Namespaces in Azure Service Bus and Service Bus for Windows Server.

1. Open a browser and navigate to http://localhost:15672/
2. Log in using the following credentials:
   • username: guest
   • password: guest

Note: The default user guest can only log in from local host.

3. Click Admin > Virtual Hosts.
4. Expand Add a new virtual host.
5. Enter a name for a virtual host to be used in the Name field, ex: Relativity.
6. Click Add virtual host.

Create a new user to be used by Relativity

Complete the following steps to create a new user to be used by Relativity:

1. Open a browser and navigate to http://localhost:15672/
2. Log in using the following credentials:
   • username: guest
   • password: guest

Note: The default user guest can only log in from local host.

3. Click Admin > Users.
4. Expand Add users.
5. Enter a user name and password in the Username and Password fields.
6. Select Admin, under the Tags field.
7. Click Add user.
8. Expand All users.
9. Click on the user you just created.
10. Expand Permissions.
11. Select the virtual host you created in the previous steps in the Virtual Host drop-down menu.
12. In the Configure regexp, Write regexp, and Read regexp fields ensure the value is set to .* .
13. Click Set permission, the permissions now display under current permissions.

Note: For advanced deployment and configuration options, see the RabbitMQ website.

Adding a new RabbitMQ policy for SignalR

A SignalR policy ensures all SignalR queues are deleted after five minutes without a consumer, rather than the default setting of one hour. In addition, high availability policies are not applied to SignalR queues, limiting the performance impact of many queues.

To add a SignalR policy:

1. Open your browser and navigate to http://localhost:15672/.
2. Log in using the following credentials. The default user guest can only log in from local host.
   • username: guest
   • password: guest

3. Click Admin > Policies.
4. Expand the Add / update a policy section.
5. Select a virtual host to be used, specifically Relativity.
   • Name - SignalR
   • Pattern - SIGNALR
   • Priority - 10
   • Definition - expires = 300000 | Number
     
     
     
     

6. Click Add / update policy to save the policy. Confirm the policy has been saved in the following format:
   

Note: TLS is optional and controlled by the TLSENABLED response file input and EnableTLSForServiceBus instance setting.

In order to setup RabbitMQ to use TLS for secure communication you must update the server side configuration of RabbitMQ. To enable SSL communication with the RabbitMQ server in Relativity, you must also update the instance setting. The following section documents the minimum requirements for using RabbitMQ over TLS with Relativity. For complete documentation of RabbitMQ with TLS, see the RabbitMQ website.

Note: Relativity only supports TLS 1.0, 1.1, and 1.2. SSL3 is NOT supported. When TLS is enabled for Relativity the ports 5671 and 15671 must be open and available for use by RabbitMQ.

1. Before you begin, you need a certificate. For more information, see Certificate requirements for RabbitMQ.
2. Navigate to your RabbitMQ directory. On Windows, this defaults to C:\Users\<user>\AppData\Roaming\RabbitMQ, <user> is the user account used to install the service.
3. Depending on the version of RabbitMQ, download the advanced.config file. The slashes in the advanced.config file must be forward slashes (/); entering backward slashes will result in an error.

   Below RabbitMQ 3.8.15+	RabbitMQ 3.8.15+ or above
   advanced.config	advanced.config

[
    {ssl, [
        {versions, ['tlsv1.2', 'tlsv1.1']}
    ]},
      
    {rabbit, [
        {consumer_timeout, 5400000},
        {ssl_listeners, [5671]},
        {ssl_options,
            [{cacertfile, "C:/Path/To/Your/CACert/caCert.pem"},
             {certfile,   "C:/Path/To/Your/Cert/cert.pem"},
             {keyfile,    "C:/Path/To/Your/Key/key.pem"},
             {verify,     verify_none},
             {fail_if_no_peer_cert, false},
             {versions, ['tlsv1.2', 'tlsv1.1']}
            ]}
    ]},
    
    {rabbitmq_management, [
        {listener, [
            {port,     15671},
            {ssl,      true},
            {ssl_opts, [
                {cacertfile, "C:/Path/To/Your/CACert/caCert.pem"},
                {certfile,   "C:/Path/To/Your/Cert/cert.pem"},
                {keyfile,    "C:/Path/To/Your/Key/key.pem"}
            ]}
        ]}
    ]}
].

Note: Before editing the advanced.config file, ensure the certificate files are converted into the .PEM format. For more information, see Convert certificates to PEM Format.

The below image is an example of the advanced.confg file setup for TLS utilizing a self-signed certificate:

Notes:
• In the advanced.confg file, ports 5671 and 15671 are specified in the file and are required for Relativity.
• The settings verify and fail_if_no_peer_cert are used for Client Certificates. Relativity does not support Client Certificates with RabbitMQ at this time, and requires username password authentication. As a result, verify must be set to verify_none, and fail_if_no_peer_cert must be set to false.
• For more information on how to configure RabbitMQ for TLS, see TLS Support and Configuring Cipher Suites.

In order to deploy RabbitMQ in a high availability configuration, create a cluster of servers, nodes, hosting RabbitMQ. Once configured, Relativity can continue to function in the event that any individual RabbitMQ node goes down. While this section provides the basic steps necessary set up a RabbitMQ cluster, clustering in RabbitMQ supports many different configurations and network topologies. For more information, see clustering on the RabbitMQ website.

Optional configuration topics not included in this section include:

• Alternative Cluster Formation Techniques
• TLS for Inter-node (Clustering) Traffic

Planning the cluster

To achieve high availability, your cluster must include at least two nodes, servers, hosting RabbitMQ, and it is generally recommended to have at least three nodes. It is highly recommended that all nodes communicate over a reliable LAN. A reliable network connection between nodes is important for avoiding partitions. For more information, see partitions on the RabbitMQ website.

• Review the port requirements, see ports on the RabbitMQ website.
• Relativity agent and web servers must be able to communicate with the cluster over the following ports:
  • TCP: 5672 (non TLS configurations) and / or 5671 (TLS configurations)
  • HTTP(S): 15672 (non TLS configurations) and / or 15671 (TLS configurations)
• Options for handling node failures:
  • Manual Fail Over
    • No special network configuration required.
    • Manual updates to relativity configuration and service restarts needed in the event of node failure.
  • Load Balancer/Proxy
    • Configure Relativity’s service bus instance settings to connect to a load balancer for the cluster.
    • HTTP and TCP traffic should be load balanced across at least two nodes in the cluster.
    • The load balancer must allow for long lived TCP connections to avoid a degradation in performance.
    • In the event of a node failure, Relativity processes connected to the node will attempt to reconnect until successful allowing the load balancer to the direct the connection to a healthy node.
    • Round Robin or other more advanced routing techniques can be used.
  • Dynamic DNS
    • Configure Relativity to connect to a domain name which is dynamically routed to the RabbitMQ nodes with a very short time to live.
    • Effectively a Round Robin Load Balancer.

Creating the Cluster

Note: The following steps assume a windows server based RabbitMQ deployment.

1. Before forming a cluster, install Erlang and RabbitMQ on each server you which to include in the cluster. For more information, see Installing Erlang and RabbitMQ.

2. Obtain an Erlang cookie to be used by the cluster. This cookie is used for inter-node authentication and is randomly generated on start-up if not present. For a cluster, the values much match on every host. For more information, see the RabbitMQ website.
   1. Log into the host server.
   2. Navigate to C:\WINDOWS\system32\config\systemprofile.
   3. Copy the .erlang.cookie file to a central location. This will serve as the shared cookie for the cluster.
3. For each host server:
   1. Run rabbitmqctl stop_app in the RabbitMQ command prompt.

   Note: If you run into issues while running RabbitMQ commands, trying restarting the RabbitMQ windows service. If you still see issues, try rebooting the server.

   2. Run rabbitmqctl reset.
   3. Replace the .erlang.cookie file at C:\WINDOWS\system32\config\systemprofile with the one you copied to a central location.

   4. Run rabbitmqctl join_cluster rabbit@%ComputerNameOfHostThatCookieWasCopiedFrom%.

      Note: Do not use the FQDN of the server or the command will error without the RABBITMQ_USE_LONGNAME setting in RabbitMQ set. Also, the host name is case sensitive.

   5. Replace the .erlang.cookie file at C:\Users\%USERNAME_THAT_INSTALLED_RABBITMQ%\.erlang.cookie with the one you copied to a central location.

   6. Open RabbitMQ command prompt.

4. Run rabbitmqctl cluster_status on any host in the RabbitMQ command prompt and confirm the output for nodes and running nodes contains all hosts.

Note: Ensure the management plugin is enabled on each node. For more information, see Installing Erlang and RabbitMQ.

5. Verify the status of the cluster on the RabbitMQ management page.



Notes:
• If any of the nodes are missing, log into that node and complete the steps found under Creating a cluster.
• If any of the nodes are yellow, this likely means the management plugin has not been enabled. Log in to that host and run rabbitmq-plugins enable rabbitmq_management in the RabbitMQ command prompt. For more information, see Installing Erlang and RabbitMQ.

Configuring the Cluster

By default, each queue and exchange only exists on a single node in the cluster. This means that those queues and exchanges are no longer be available if those nodes go down. For high availability, it is also necessary to ensure the individual queues and exchanges on the cluster are mirrored across multiple nodes. For more information, see the RabbitMQ website.

Notes:
• If your cluster has more than three nodes, it may be beneficial to configure your queues and exchanges to be mirrored across an exact number of nodes in order to limit internode communication.
  
• The following steps can be used to configure all queue and exchanges to be mirrored across all nodes.

1. Open a browser and navigate to http://localhost:15672/
2. Log in using the following credentials:
   • username: guest
   • password: guest

Note: The default user guest can only log in from local host.

3. Click Admin > Policies.
4. Expand Add / update a policy.
5. Select a virtual host to be used, ex: Relativity.
6. Enter the following information:
   • Name—Ha-all
     • This will apply to all queues that are not SignalR or Conversion. In addition to the normal HA values, it also places a default expiration on all queues of 24 hours. The addition of the expiration value should help to clean up miscellaneous orphaned queues, such as ResourcePoolStatus queues for agents that no longer exist.
     • The 24-hour expiration only starts after the policy has been applied. This means the orphaned queues will not be cleaned up immediately, but will be cleaned up 24 hours after creating the policy.
   • Pattern—leave blank, means the policy will apply to everything.
   • Priority— -10
   • Definition
     • expires = 86400000 | Number
     • ha-mode = all | String
     • ha-sync-mode = automatic | String
       
7. Click Add policy. The policy now appears under User policies.
8. Add another policy for Relativity Document Conversions by first selecting Relativity again as the virtual host to be used.
9. Enter the following information:
   • Name—Conversion
     • This policy applies to all conversion queues. This includes all values from the new HA-All policy as well as lowering the message time to live to 1 hour, down from 24 hours. The reduced message time to live will help discard conversion requests for especially large documents that are taking a very long time to convert.
     • The messages will not be discarded if they are currently in an unacked/in progress state, and restarting or deleting and recreating conversion agents may still be required.
   • Pattern—Conversion
   • Priority— 0
   • Definition
     • expires = 86400000 | Number
     • ha-mode = all
     • ha-sync-mode = automatic
     • message-ttl = 3600000 | Number
       
       
10. Confirm that all policies are properly logged. From the queues page, all SignalR queues should display SignalR under features. All conversion queues should display Conversion under features. All other queues should display HA-All under features.
    

Use the following guidelines to optimize the Service Bus for Windows Server installation and farm setup:

• Service bus installation—For a typical installation, install Service Bus for Windows Server on a server or VM that is accessible throughout your Relativity instance. Install the service bus on a machine that meets these minimum requirements: CPU clock speed of 1.6GHz, a CPU core count of 2 or more, and physical memory of 3.5 GB, although 6 GB is recommended. These same guidelines also apply when installing the service bus on multiple hosts. See Best Practices Analyzer on the Microsoft site.
• Node—a typical Relativity installation requires only a single node in a farm. For a multiple host installation, ensure that you have an odd number of nodes, but do not exceed the maximum of five nodes. Three nodes is a common configuration for most environments configured with multiple hosts. While you can install the service bus on five nodes, determine if your Relativity installation requires these additional nodes. They may result in unnecessary overhead for your environment.

  Note: During installation or upgrade, the machine for the Relativity service bus must be a node in the farm.

• SQL Server instance location—any machine in the farm can host the service bus databases. We recommend hosting the SQL instance on the Invariant database server. However, you can host it on a SQL instance on a separate machine. The SQL Server instance used for the Service Bus for Windows Server must meet the minimum requirements that Microsoft specifies in Prerequisites on MSDN.
• Message containers—For a typical Relativity installation with a single node, we recommend using the default value of three message containers in the farm.For a multiple host environment, Microsoft recommends using 2n message containers, where n is the number of nodes. For example, if you install the service bus on three hosts, then you need six message containers.See step 11 in Setting up a new farm.

  To review the Microsoft recommendations for message containers, see Scaling on MSDN.

• Message backing (SQL) high availability—review the Microsoft recommendations for message backing with high availability, which suggest using SQL mirroring or SQL AlwaysOn availability groups. For more information, see Architecture overview on MSDN.
• Server roles—install the Relativity service bus on a single machine that is a node in the Service Bus for Windows Server farm. In a multiple host environment, install the Service Bus for Windows Server on multiple machines that you want added to your farm. However, you only need to install the Relativity service bus on single machine as in a typical installation. For more information, see Relativity installation.

  Note: Make sure that you set up a farm and configure it before you run the Relativity installer. The Relativity installer validates that your environment meets this requirement. See Configuring Service Bus for Windows Server.

Before installing Service Bus for Windows Server, complete the following prerequisites:

• Complete the pre-installation steps for Relativity, such as setting up user accounts and certificates. For more information, see Certificate requirements for Service Bus for Windows Server.
• Ensure that you have the prerequisites for Service Bus for Windows Server. You need to meet these requirements to set up your farm correctly. See Planning Your Deployment on the Microsoft site.
• For a typical installation, identify the server or VM where you want to install Service Bus for Windows Server. To install the service bus on multiple hosts, identify the servers or VMs for this purpose. The farm requires that you add an odd number of nodes, but you should not exceed a maximum of five nodes. For more information, see Best practices for RabbitMQ.

  Note: For a typical installation, install Service Bus for Windows Server on a server or VM that is accessible throughout your Relativity instance. Install the service bus on a machine that meets these minimum requirements: CPU clock speed of 1.6GHz, a CPU core count of 2 or more, and physical memory of 3.5 GB, although 6 GB is recommended. These same guidelines also apply when installing the service bus on multiple hosts. See Best Practices Analyzer on the Microsoft site.

• Ensure that you install .NET Version 4.7.2 or 4.8 in your environment. You must install.NET Version 4.7.2 or 4.8 before you install Service Bus 1.1 with TLS 1.2. It requires .NET Version 4.7.2 or 4.8.

To perform an online installation, you must have an internet connection. This process includes downloading the Microsoft Web Platform Installer (Web PI) and then installing the service bus on server or VM in your Relativity environment. See Best practices for RabbitMQ.

Review the following installation considerations:

• For a typical installation, install Service Bus for Windows Server on a server or VM that is accessible throughout your Relativity instance. Consider installing the service bus on the agent server where you intend to run conversion agents. Follow these same guidelines when installing the service bus on multiple hosts.
• In a multiple host environment, install the Service Bus for Windows Server on each machine that you want added as a node in the farm. However, you only need to install the Relativity service bus on single machine that is a node in the farm. For more information, see Relativity installation.

• Notice that the installer for the Service Bus for Windows Server adds the database files for the service bus to the default locations used by your SQL Server. These database locations differ from those used for the Relativity databases specified in the RelativityResponse.txt file installation input file.

  You can use the default locations for the Service Bus for Windows Server databases. However, if you want to change these locations, see View or Change the Default Locations for Data and Log Files (SQL Server Management Studio) on the Microsoft website.

If you do not have an internet connection, you can perform an offline installation. For more information, see Offline installation for Service Bus for Windows Server.

Use the following steps to install Service Bus for Windows Server:

1. To download the Web PI, click Web Platform Installer Direct Downloads.
2. In the WebPI 5.0 section, click the appropriate link for your machine.
3. Locate the WebPlatformInstaller_amd64_en-US.msi that was downloaded by the installer. It appears in the lower left corner of the browser, or in your download folder.
4. Double-click the file to launch the Web PI. When the Security Warning dialog box appears, click Run.
5. On the Spotlight tab, search for Service Bus 1.1 with TLS 1.2 Support.

   

6. Select Windows Azure Pack: Service Bus 1.1 with TLS 1.2 Support in the search results.
7. Click Add > Install.
8. Click I Accept to accept the license terms and start the installation.
9. When the installation process completes, click Finish. You have now installed Service Bus for Windows Server.
10. Complete the steps for configuring the service bus. For more information, see Configuring Service Bus for Windows Server.

To perform an offline installation, you only need an internet connection to download the installer. You can then complete the offline installation process on server or VM in your Relativity environment. See Best practices for RabbitMQ.

Review the following installation considerations:

• For a typical installation, install Service Bus for Windows Server on a server or VM that is accessible throughout your Relativity instance. Consider installing the service bus on the agent server where you intend to run conversion agents. Follow these same guidelines when installing the service bus on multiple hosts.
• In a multiple host environment, install the Service Bus for Windows Server on each machine that you want added as a node in the farm. However, you only need to install the Relativity service bus on single machine that is a node in the farm. For more information, see Relativity installation.

• Notice that the installer for the Service Bus for Windows Server adds the database files for the service bus to the default locations used by your SQL Server. These database locations differ from those used for the Relativity databases specified in the RelativityResponse.txt file installation input file.

  You can use the default locations for the Service Bus for Windows Server databases. However, if you want to change these locations, see View or Change the Default Locations for Data and Log Files (SQL Server Management Studio) on the Microsoft website.

After you complete the installation, call the WebPICmd executable using the following command line switches in a command prompt window:

• /list—displays a list of available products.
• /listoption:—acts as a sub-command used for filtering on a list.
• /install—installs products available through the Web PI.
• /offline—downloads the products for use offline. This command downloads products so you can be installed later by running the /install command.
• /Products:—acts as a sub-command of both the /offline and /install commands. You can use it to indicate which of the available products you want to download and install, respectively.

Downloading the Web Platform Installer

You need an internet connection to download the Web Platform Installer (Web PI) used to install the Service Bus for Windows Server.

Use the following steps to download the installer:

1. On a machine with an internet connection, complete steps 1-4 listed in Online installation for Service Bus for Windows Server. You should now have installed the Web PI on your machine.
2. Verify that the WebPICmd.exe file was installed on your machine by locating it in the following folder:

   %ProgramFiles%\Microsoft\Web Platform Installer

3. Open a Windows PowerShell command prompt. Select Run as Administrator.
4. Run the following /list command to display ServiceBus_1_1 in a list of service bus products:

   webpicmd /list /listoption:Available|?{ $_.Contains(“ServiceBus”) }

   

5. Use the following command to download the files for installing Service Bus 1.1 with TLS 1.2 Support:

   webpicmd /offline /Products:"ServiceBus_1_1_TLS_1_2" /Path:C:\ServiceBusOfflineFiles

   

6. Verify that PowerShell displays information about the products that are cached and processed, and the feeds being built.

   These processes succeeded if you see the message listed in the following screen shot. The path command indicates where the files are downloaded. You can modify this path as necessary.

   

7. After the download completes, copy the entire /Path directory to the machines in your offline environment where you want to install Service Bus for Windows Server.

Installing Service Bus for Windows Server

For a typical Relativity installation, install the Service Bus for Windows Server on the machine that you want added as a node in the farm. For a multiple host environment, repeat this installation process on all the machines that you want added as nodes in the farm.

Use the following steps to install the service bus:

1. Open a Windows PowerShell command prompt. Select Run as Administrator.
2. Change to the directory containing the installation files that you downloaded using the /offline command and copied to this machine. See step 7 in Downloading the Web Platform Installer.

   For example, if you download the files to a directory on your hard drive called ServiceBusOfflineFiles, you would execute this command:

   cd C:\ServiceBusOfflineFiles\

3. Run the following command to install Service Bus 1.1 with TLS 1.2 Support. Update the initial part of the path displayed after the /xml command with the directory where your files are located. For example, you would replace C:\ServiceBusOfflineFiles with your file path:

   .\bin\WebpiCmd.exe /install /Products:"ServiceBus_1_1_TLS_1_2" /xml:C:\ServiceBusOfflineFiles\feeds\latest\webproductlist.xml

4. Accept the licensing agreement to install the service bus.
5. After the installation completes, verify that you see a message like the one in the screen shot:

   

6. Complete the steps for configuring the service bus. For more information, see Configuring Service Bus for Windows Server.

After installing Service Bus for Windows Server, you need to complete several configuration steps, which include setting up a new service bus farm. A farm consists of one or more servers, or nodes that use the service bus. For troubleshooting information, see Relativity service bus.

This section contains the following information:

• Setting up a new farm
• Configuring an auto-generated SSL certificate
• Optionally adding multiple servers to an existing farm
• Adding a new message container
• Troubleshooting the service bus farm

Setting up a new farm

You set up a new farm by adding a single server to it. After completing this process, you can optionally add multiple hosts to the farm. For more information, see Optionally adding multiple servers to an existing farm.

Note: Before you can add a server to a farm, you must install the Service Bus for Windows Server on it.

Use the following steps to set up a new farm:

1. Locate the Service Bus Configuration tool on your desktop. The service bus installer automatically installs this tool for you.
2. Launch the Service Bus Configuration tool, and then click With Custom Settings.
3. Complete the fields in the Service Bus Configuration wizard. See Fields in Service Bus Configuration wizard.
4. After you set the fields in the wizard, click the to display a summary of the information used to configure the service bus.
5. Click the to start the configuration process.
6. Set the DNS for the service bus farm. Execute the following commands with the Service Bus PowerShell tool. This DNS must match the name in the Issued to field on the certificate used for the service bus.

   Stop-SBFarm
   							Set-SBFarm -FarmDns 'YOUR_DNS'
   							Update-SBHost
   					Start-SBFarm

7. Verify that the service bus is configured properly by entering your URL into a web browser, and confirming that the following page is displayed. Use this format for the URL: https://<Your_DNS>:<Your_HTTPS_Port>/<Your_Namespace>.

   

Fields in Service Bus Configuration wizard

In the Service Bus Configuration wizard, you need to set the following fields, including the suggested or required values for them.

Configure Farm Management Database

In this section, click the Advanced Options drop-down to display additional fields.

• SQL Server Instance—enter the name or address of the SQL Server where you want to host the SbManagementDB. This SQL instance hosts the databases for your farm.
• Enable SSL connection with the SQL Server instance—optionally, click this checkbox to use SSL.
• Authentication—complete one of the following tasks to set up authentication for the SQL instance:
  • Windows Authentication—select this option if your instance supports Windows authentication.
  • SQL Server Authentication—select this option to use SQL server authentication. Enter credentials in the User Name and Password fields for a sysadmin account or the EDDSDBO account.
• Use the above SQL Server instance and settings for all databases—click this checkbox.
• Database Name—optionally, update the name for your database. You can also just use the default name, which is SbManagementDB.
• Test Connection—click this button to ensure that you have enter the correct settings for your SQL Server.

Configure Gateway Database

• SQL Server Instance—do not modify the default setting for the Gateway database.
• Database Name—do not modify the default name for the Gateway database.
• Test Connection—click the button for the database instance. appears next to the server instance when the installer verifies a connection.

Configure Message Container Database

• SQL Server Instance—do not modify the default setting for the Message Container database.
• Database Name Prefix—do not modify the default name for the Message Container database.
• Number of Containers—enter a value for the number of containers. For a typical Relativity installation with a single node, we recommend using the default value of three message containers in the farm. For a multiple host environment, Microsoft recommends using 2n message containers, where n is the number of nodes. For example, if you install the service bus on three hosts, then you need six message containers. For more information, Best practices for RabbitMQ.

  Note: If you previously configured the number of containers and need to update this value, see Adding a new message container.

• Test Connection—click this button for the database instance. appears next to the server instance when the installer verifies a connection.

Configure Service Account

• User ID—enter the user ID for the Relativity service account.
• Password—enter the password for the Relativity service account.

  Note: You must use the Relativity service account credentials for the service account on the Service Bus for Windows Server. For more information, see User and group accounts.

Configure Certificate

Use one of the following methods to configure a certificate. You can auto-generate a certificate. Alternatively, you can use an existing certificate with the same domain as the FQDN of the service bus server, or you can issue a certificate through an CA. For more information, see Certificate requirements for Service Bus for Windows Server.

• Auto-generate—select this checkbox to automatically create a certificate. If you select this option , you must enter a value in the following fields:
  • Certificate Generation Key—enter a certificate generation key of your choice, any combination of characters, if you are auto-generating a certificate. This key is required if you want to add more hosts to the farm in the future. Complete the steps required to distribute the generated certificate to all agent, web, queue manager, and worker servers agent and web servers. See Configuring an auto-generated SSL certificate.

  Note: A certificate is required on the queue manager and worker servers as part of the connection between Invariant and Service Bus.

  • Confirm Certificate Generation Key—re-enter the key from the previous field.
• Farm Certificate—if you did not auto-generate a certificate, click Browse to select the certificate that you want to use for HTTPS communication between the service bus and the clients. For more information, see Certificate requirements for Service Bus for Windows Server.
• Encryption Certificate—if you did not auto-generate a certificate, click Browse to select the certificate used to encrypt all the connection strings in the SbManagementDB database and registry. You configured the SbManagementDB database in Configure Farm Management Database. For more information, see Certificate requirements for Service Bus for Windows Server.

Configure Ports

• Consider using the port numbers in the following table. These port numbers are suggested configuration values.

  Port name	Port number	Description
  HTTPS Port	9455	Specifies the HTTPS port used for communication with Service Bus for Windows Server. To avoid port conflicts with Data Grid, this value differs from Microsoft's default value.
  TCP Port	9454	Specifies the TCP port used for communication with Service Bus for Windows Server. To avoid port conflicts with Data Grid, this value differs from Microsoft's default value.
  Message Broker Port	9456	Specifies the port used for message broker communication by Service Bus for Windows Server. To avoid port conflicts with Data Grid, this value differs from Microsoft's default value.
  Resource Provider HTTPS Port	9459	Specifies the port used for communication with the Service Bus Management Portal. To avoid port conflicts with Data Grid, this value differs from Microsoft's default value.
  AMQP Port	5682	Specifies the AMQP port used for communication with the Service Bus via the AMQP protocol. The default value of 5672 is the industry default for AMQP communication. We recommend changing this value to 5682 to avoid potential port conflicts.
  AMQPS Port	5681	Specifies the AMQPS port used for communication with the Service Bus via the AMQP protocol over SSL. The default value of 5671 is the industry default for AMQPS communication. We recommend changing this value to 5681 to avoid potential port conflicts.
  Internal Communication Port Range	9000	Specifies the ports used for communication between hosts in the Service Bus farm. Use the default recommended by Microsoft default. It does not have any port conflicts with Relativity components.

• Enable firewall rules on this computer—select this checkbox. When you select this option, the service bus automatically sets up the necessary rules to communicate over the firewall. If you do not select this option, then the client must configure the necessary rules or the service bus will not function properly.

Configure Admin Group

• Configure Admin Group—enter the name of an admin user group. This group has access to the service bus databases and admin access to the farm, including full admin rights on the Service Bus for Windows Server. By default, the Admin Group box is set to BUILTIN\Administrators group, but you can modify the users in this group as necessary.

  Note: If the admin group is a local group, make sure that it exists on all servers in the farm and the SQL instance specified in Configure Farm Management Database.

Configure Service Bus Namespace

• Create a default namespace—select this check box. Optionally, enter a name for the namespace in the text box. You can use the default value, since Relativity creates an new namespace during installation.

Note: After you complete these fields, you must return to step 4 in Setting up a new farm to complete the installation process. Additional steps include setting up the DNS for the service bus farm, and verifying that the service bus is working properly.

Configuring an auto-generated SSL certificate

You can auto-generate SSL certificates for remote clients and then export the CA and Certificate revocation list (CRL) to them.

Use the following steps to configure a certificate on a remote client:

1. Log in to the machine where you installed Service Bus for Windows Server.
2. Open the Service Bus PowerShell tool.
3. To export the CA and CRL from a farm node, execute the following cmdlet:

   Get-SBAutoGeneratedCA

   If you do not provide file names, the cmdlet exports the CA and CRL to the service bus root folder with the name AutoGeneratedCA.cer and AutoGeneratedCA.crl respectively. The following example illustrates how to run this cmdlet with file names:

   Get-SBAutoGeneratedCA -CACertificateFileName "C:\CACert.cer" -RevocationListFileName "C:\RevocationList.crl"

4. Import the CA and CRL files to your Relativity servers that need access to the service bus. For example, you need to import the auto-generated service bus certificates to the web, agent, worker, and worker manager servers.
5. On the client machine, open a Microsoft Management Console (MMC) window. On the Start menu, click Run, enter MMC, and then click OK.
6. In the MMC window, click File > Add/Remove Snap-in. The Add/Remove Snap-in dialog box appears.
7. Add the Certificates snap-in by selecting the Computer Account and Local Computer options. Click OK.
8. In the MMC window, right-click the Certificates\Trusted Root Certification Authorities.
9. Open All Tasks, and select Import.
10. Select the AutoGeneratedCA.cer file and import it.
11. In the MMC window, right-click on the Intermediate Certification Authorities.
12. Open All Tasks, and select Import.
13. Select the AutoGeneratedCA.crl file and import it.

Optionally adding multiple servers to an existing farm

You can optionally add more servers or nodes to increase the computing power of the service bus. A typical Relativity installation requires only a single node in the farm. For a multiple host installation, you can optionally add three or five nodes to the farm. Three nodes is a common configuration for most environments using multiple hosts.

Before adding more nodes to your farm, review these guidelines:

• Add nodes that reside in the same domain.
• Use the fully qualified domain name as the instance address for each machine that you add.
• Ensure that you have an odd number of nodes. A service bus farm must have an odd number of nodes. For example, it can include one, three, or five nodes. See Best practices for RabbitMQ.
• Do not exceed the maximum of five nodes in the farm. To avoid extra overhead, determine whether your environment needs the additional nodes.

Use the following steps to add another server:

1. Open the Service Bus Configuration tool.
2. Click Join an Existing Farm.

   

3. In SQL Server Instance box, enter the name or address of the SQL Server where the SbManagementDB is hosted.
4. Enter the SQL Server instance address. Use the fully qualified domain name for the machine as the instance address.
5. In the Database Name box, enter the name of the database if you modified the default name.
6. Under Advanced Options, click one of these options to set up authentication for the SQL instance:
   • Enable SSL connection with the SQL Server instance—select this option for SSL.
   • Windows Authentication—select this option if your instance supports this authentication type.
   • SQL Server Authentication—if you select this option, enter credentials in the User Name and Password fields.
7. On the Join Service Bus Farm page, enter the User ID and Password for the Relativity service account. For example, you could use relativity.service@example.com as the User ID.

   

8. Select Enable firewall rules on this computer. If you auto-generated the certificate, you must enter the certificate generation key in the Provide Certificate Generation Key box. You must enter the same farm key you used to auto-generate the certificate for the service bus farm.
9. Click the , and then to start the configuration process.

Adding a new message container

After you configure your service bus farm, you can continue to add new message containers to your environment. Adding containers scales the data tier of the service bus. The larger data tier increases the availability of the SQL layer to store messages, queues, topics, and other entities. Review following guidelines to determine the number of message containers required for your service bus:

• Single node installation—For a typical Relativity installation with a single node, we recommend using the default value of three message containers in the farm. See step 11 in Setting up a new farm.
• Multiple node installation—For a multiple host environment, Microsoft recommends using 2n message containers, where n is the number of nodes. For example, if you install the service bus on three hosts, then you need six message containers. To review the Microsoft recommendations for message containers, see Scaling on MSDN.

Use the following PowerShell cmdlets to add a new message container. For more information, see Service Bus PowerShell cmdlets.

• Execute a cmdlet from outside the farm—when you execute a cmdlet from outside the farm, the SBFarmConnectionString points to the management databases of the service bus farm.

  New-SBMessageContainer –ContainerDBConnectionString <Connection string for the database with message containers> -SBFarmConnectionString <Connection string for the SbManagementDb>

• Execute a cmdlet from inside the farm—when you execute a cmdlet inside the farm, you call the cmdlet without the SBFarmConnectionString. In this example, the database is called container2. You must specify a unique database name for use in your environment when you run the New-SBMessageContainer command.

  New-SBMessageContainer -ContainerDBConnectionString "data source=localhost\sqlexpress;database=container2;integrated security=true"

Troubleshooting the service bus farm

Review the following list of errors and resolutions to troubleshoot your service bus configuration. For additional troubleshooting information, see Service bus PowerShell cmdlets.

Service Bus Gateway service will not start

If you cannot start the Service Bus Gateway service, then you may need to install a Windows update. To install this update, see https://support.microsoft.com/en-us/kb/3086798.

Timeout error occurs when creating or joining service bus farm

If you receive a timeout error when attempting to create or join a service bus farm, you may have a port conflict in your environment. You can check the availability of a port in your environment by running the following netstat command:

netstat -na | find "<Your Port>"

See the following sample command:

netstat -na | find "9455"

If the command doesn’t return a value, then the port is free. For a list of recommended ports, see Configure Ports.