Upgrading your Relativity service bus

To upgrade the Relativity service bus, you run the installer on a machine where it is already installed, or where the Service Bus for Windows Server or RabbitMQ is installed. You must include the Relativity service bus server as a node in the Service Bus for Windows Server farm or as a server in RabbitMQ cluster. For more information, see Pre-installation.

When you perform an upgrade, the Relativity installer saves information about the about the farm/cluster to the primary SQL Server database. It also performs setup tasks on farm/cluster, so that Relativity can connect to the service bus.

Relativity service bus upgrade

The Relativity service bus supports messaging between application components. Before installing or upgrading the Relativity service bus, upgrade the primary SQL Server. For more information, see Relativity service bus.

Contact Customer Support to get a copy of the Relativity installer.

Save the following files to the root directory of any server contributing to the Relativity environment:

Relativity.exe—the executable file that installs Relativity components determined by the values entered in the RelativityResponse.txt file.
- You must save Relativity.exe on a drive local to the server. Running Relativity.exe from a shared location results in upgrade or installation failure.
- The Relativity.exe file does not open a user interface. Use Install.bat to proceed with installation.
Install.bat—the code that prompts Relativity.exe to proceed with the installation process. You must edit line 11 of the Install.bat file with the exact name of the Relativity installation file.
```
 start /wait "" "INSERT EXACT NAME OF RELATIVITY INSTALLATION FILE" /log InstallLog.txt /responsefilepath=RelativityResponse.txt
```
- You may need to run this file from an elevated command line prompt to avoid permission issues.
- You must surround the name of the Relativity installation file with quotation marks.
RelativityResponse.txt—the text file that determines which components Relativity.exe installs, uninstalls, or upgrades on the server.

Note: Every line in the RelativityResponse.txt file that starts with ### is a comment and meant to provide instruction.

Setting properties in the RelativityResponse.txt file

Relativity requires RabbitMQ or Service Bus for Windows Server. Depending on the message broker you have installed, complete the following steps:

Service Bus for Windows Server

You must include the Relativity service bus server as a node in the Service Bus for Windows Server farm. The Relativity installer saves information about the farm to the primary SQL Server database. It also performs setup tasks on farm, so that Relativity can connect to the service bus. For information about prerequisites, see Pre-installation. If you're re-purposing a worker as a conversion agent, seeRe-Purposing.

Open the RelativityResponse.txt file in a text editor and edit the parameters as follows to install Relativity on the machine that serves the role of the service bus server:

Feature selection

INSTALLSERVICEBUS - Set this value to one to install the Relativity service bus.
```
INSTALLSERVICEBUS=1
```
- If the service bus server is already installed on this machine and the INSTALLSERVICEBUS property is set to zero, the installer removes the previously existing service bus server.
- When using Service Bus for Windows Server, the Relativity Installer with the INSTALLSERVICEBUS=1 feature selection must be run on a server that is hosting Service Bus for Windows Server.

Common properties

Note: The following non-alpha-numeric characters are not allowed in passwords: \, ", <, >.

INSTALLDIR - Enter the installation directory. This is the target directory for all files related to the local installation. This path must be local to the machine and accessible by the server. You must use ASCII characters for this path.
```
INSTALLDIR=C:\Program Files\kCura Corporation\Relativity
```
PRIMARYSQLINSTANCE - Enter the primary SQL instance. If you are installing to a cluster, specify the cluster and instance name. If you are installing to a named instance, specify the server and instance name. All features require this input.
```
PRIMARYSQLINSTANCE=ML12
```
EDDSDBOPASSWORD - Enter the EDDSDBO password.
```
EDDSDBOPASSWORD=MySecretPassword
```
SERVICEUSERNAME - Enter the service username. The Windows login must already exist.
```
SERVICEUSERNAME=example\exampleusername
```
SERVICEPASSWORD - Enter the service password.
```
SERVICEPASSWORD=MySecretPassword
```
USEWINAUTH - Set this to one to use Windows authentication for the SQL Server.
```
USEWINAUTH=1
```
Note: If the USEWINAUTH value is set to one, then the user running the installer must be a SQL sysadmin, and any values entered for SQLUSERNAME and SQLPASSWORD are ignored.
SQLUSERNAME - Enter the SQL username to use SQL Server login authentication.
```
SQLUSERNAME=mySqlUserName
```
Note: This value is ignored if USEWINAUTH is set to one.
SQLPASSWORD - Enter the SQL password to use SQL Server login authentication.
```
SQLPASSWORD=myPassword
```
Note: This value is ignored if USEWINAUTH is set to one.
SERVICEBUSPROVIDER - If applicable, enter Windows when using Service Bus for Windows Server as your message broker. The value defaults to Windows.

SERVICEBUSPROVIDER=Windows

Save your edits to the RelativityResponse.txt file, and launch the Install.bat file to proceed with the installation.

Note: The values in the Service Bus section of the response file DO NOT need to be filled out when using Service Bus for Windows Server.

A sample response file for a service bus only installation looks like this:

INSTALLSERVICEBUS=1
INSTALLDIR=C:\Program Files\kCura Corporation\Relativity
PRIMARYSQLINSTANCE=ML12
EDDSDBOPASSWORD=MySecretPassword
SERVICEUSERNAME=example\exampleusername
SERVICEPASSWORD=MySecretPassword 
USEWINAUTH=1
SERVICEBUSPROVIDER=Windows

Note: Every line in the RelativityResponse.txt file that starts with ### is a comment and meant to provide instruction.

Troubleshooting the service bus installation

Use the following information to troubleshoot issues that may occur during the service bus installation:

In the RelativityResponse.txt file, ensure that you set the INSTALLSERVICEBUS property to 1 before you run the installer.
Verify that the following instance settings contain the correct values:

Note: For general troubleshooting information, see Troubleshooting the Service Bus for Windows Server and Relativity service bus.

RabbitMQ

When using RabbitMQ as your chosen message broker, RabbitMQ must be installed and configured prior to running the Relativity Installer. For information, see Pre-installation.

Open the RelativityResponse.txt file in a text editor and edit the parameters as follows to install Relativity on the machine that serves the role of the service bus server:

Feature selection

INSTALLSERVICEBUS - Set this value to one to install the Relativity service bus.
```
INSTALLSERVICEBUS=1
```
- If the service bus server is already installed on this machine and the INSTALLSERVICEBUS property is set to zero, the installer removes the previously existing service bus server.
- When using RabbitMQ, the Relativity Installer with the INSTALLSERVICEBUS=1 feature selection can be run on any server with network connectivity to both the Primary SQL Server and the RabbitMQ server / cluster.

Common properties

Note: The following non-alpha-numeric characters are not allowed in passwords: \, ", <, >.

INSTALLDIR - Enter the installation directory. This is the target directory for all files related to the local installation. This path must be local to the machine and accessible by the server. You must use ASCII characters for this path.
```
INSTALLDIR=C:\Program Files\kCura Corporation\Relativity
```
PRIMARYSQLINSTANCE - Enter the primary SQL instance. If you are installing to a cluster, specify the cluster and instance name. If you are installing to a named instance, specify the server and instance name. All features require this input.
```
PRIMARYSQLINSTANCE=ML12
```
EDDSDBOPASSWORD - Enter the EDDSDBO password.
```
EDDSDBOPASSWORD=MySecretPassword
```
SERVICEUSERNAME - Enter the service username. The Windows login must already exist.
```
SERVICEUSERNAME=example\exampleusername
```
SERVICEPASSWORD - Enter the service password.
```
SERVICEPASSWORD=MySecretPassword
```
USEWINAUTH - Set this to one to use Windows authentication for the SQL Server.
```
USEWINAUTH=1
```
Note: If the USEWINAUTH value is set to one, then the user running the installer must be a SQL sysadmin, and any values entered for SQLUSERNAME and SQLPASSWORD are ignored.
SQLUSERNAME - Enter the SQL username to use SQL Server login authentication.
```
SQLUSERNAME=mySqlUserName
```
Note: This value is ignored if USEWINAUTH is set to one.
SQLPASSWORD - Enter the SQL password to use SQL Server login authentication.
```
SQLPASSWORD=myPassword
```
Note: This value is ignored if USEWINAUTH is set to one.

SERVICEBUSPROVIDER - Enter RabbitMQ when using RabbitMQ as your message broker
```
SERVICEBUSPROVIDER=RabbitMQ
```
SERVERFQDN - Enter the fully qualified domain name of your message broker.
```
SERVERFQDN=localhost
```
SHAREDACCESSKEY - Enter the password Relativity will use when connecting.
```
SHAREDACCESSKEY=guest
```
SHAREDACCESSKEYNAME - Enter the username Relativity will use when connecting.
```
SHAREDACCESSKEYNAME=guest
```
Note: This value is case sensitive.
SERVICENAMESPACE - Enter the virtual host Relativity will use.
```
SERVICENAMESPACE=Relativity
```
TLSENABLED - Set this to zero if RabbitMQ is not configured for TLS, and set this to one if RabbitMQ is configured for TLS.
```
TLSENABLED=1
```

Save your edits to the RelativityResponse.txt file, and launch the Install.bat file to proceed with the installation.

A sample response file for a service bus only installation looks like this:

INSTALLSERVICEBUS=1
INSTALLDIR=C:\Program Files\kCura Corporation\Relativity
PRIMARYSQLINSTANCE=ML12
EDDSDBOPASSWORD=MySecretPassword
SERVICEUSERNAME=example\exampleusername
SERVICEPASSWORD=MySecretPassword 
USEWINAUTH=1
SERVICEBUSPROVIDER=RabbitMQ
SERVERFQDN=localhost
SHAREDACCESSKEY=guest
SHAREDACCESSKEYNAME=guest
SERVICENAMESPACE=Relativity
TLSENABLED=1

Note: Every line in the RelativityResponse.txt file that starts with ### is a comment and meant to provide instruction.

Troubleshooting the service bus installation

For more information to troubleshoot issues that may occur during the service bus installation, see Troubleshooting RabbitMQ .

ServiceBusFullyQualifiedDomainName instance setting

The Relativity installer populates the ServiceBusFullyQualifiedDomainName instance setting according to the following rules during a new installation:

When using Service Bus for Windows Server, if the FarmDNS property for the service bus farm has a value, then the installer sets the ServiceBusFullyQualifiedDomainName instance setting to this value.
When using Service Bus for Windows Server, if the FarmDNS property does not have a value, then the installer sets the ServiceBusFullyQualifiedDomainName instance setting to a semi-colon delimited list of all hosts in the farm.
When using RabbitMQ, ServiceBusFullyQualifiedDomainName specifies the fully-qualified domain name for the machine or load balancer where Relativity can reach the environment’s cluster. The Relativity installer automatically sets this value during an installation or upgrade based on the inputs in the RelativityResponse.txt file.

Note: The semi-colon delimited list is not supported for RabbitMQ.

For more information, see ServiceBusFullyQualifiedDomainName instance setting.