Service Host Manager

Relativity services defined within the Relativity.Services application and other applications, such as Production, run inside of the kCura Service Host Manager service on all web and agent servers in a Relativity environment. kCura Service Host Manager must be running on all web and agent machines to use Relativity.

Services (Local)

This page contains the following information:

Productions example

The following diagram illustrates how the Service Host Manager is used by Relativity productions:

Service Host Manager diagram

  1. Production is a Relativity application installed by default.
  2. When you install Relativity, the Production application is deployed using the Application Deployment System (ADS).
  3. As part of the application installation, the ADS deploys the services included in the Production application to all web and agent servers in you environment. These services are run by the Service Host Manager.

When you use Relativity productions, the browser user interface calls the services, for example, to create, update, or run productions. If the Service Host Manager is down, you can't interact with productions.

You can view the services associated with a Relativity application using the Resource Files tab. The following example displays the services in the Relativity.Productions.Services.dll.

Services in Relativity.Productions.Services.dll

Identifying a process running a specific service

Beginning with the Relativity Larkspur release, the services running in the Service Host Manager are hosted as individual processes. Each of these services execute as a separate instance of Relativity.Platform.Service.exe, resulting in improved stability, and greater ease in identifying services that have failed. To minimize downtime experienced by Relativity users, the Service Host Manager now attempts to restart a failed service up to three times, rather than require a full restart of the service host.

To determine the application service running in a process, open the Task Manager, the select the Details tab, and view the Command line column. You may need to right-click on the column headings and then select the Command line column to display it.

(Click to expand)

Process detail for the Service Host

In Relativity Blazingstar, you can prevent services from starting by listing them in the ServiceHostExclusionList instance setting. If you add a GUID for a service to this list while the Service Host is running, the service shutdowns dynamically. Similiarly, if you remove a GUID, the service starts dynamically. For more information, see Instance settings' descriptions.

Port configuration

In certain network environments, it may be necessary to customize port settings for the Service Host Manager:

  • Service Host Manager by default runs on port 8995 (http://localhost:8995). If the port is not available on your system, add the ServiceHostServiceLocation instance setting with a different port value.
  • Individual service endpoints deployed with the Service Host are assigned port numbers from the default range of 10000–20000. To specify a different port number range, add the ServiceHostPortRange instance setting.

    Note: Note that the range value must be pipe-delimited (20000|30000). You can look up the port number assigned to a specific service in the EDDS.ApplicationServiceLocation table.

HTTPS configuration

Follow these steps to enable HTTPS for the Service Host Manager:

  1. Change the values of the KeplerServicesUri and KeplerServicesUriForAgents instance settings to HTTPS URIs for each server.

    Change the values of the KeplerServicesUri and KeplerServicesUriForAgents instance settings to HTTPS URIs for each server

    Note: The values of KeplerServicesUri and KeplerServicesUriForAgents for HTTPS URIs must match the SSL certificate address, so they cannot use localhost or 127.0.0.1.

  2. Set up the certificate on each server:
    • Install the certificate to the Personal certificate store for the Computer Account on all web and agent servers.

      Note: If the certificate is self-signed, you must add it to both the Personal and the Trusted Root Certification Authorities certificate stores for the Computer Account on all web and agent servers.

      The certificate is bound to IP 0.0.0.0 on the machine hosting Service Host Manager (specified in the KeplerServicesUri instance setting), and the URI of the agents server (KeplerServicesUriForAgents instance setting). The port that the certificate is bound to is as follows:

      • Service Host Manager – the port that the certificate is bound to is determined when the service is started by iterating through the ports specified in the ServiceHostPortRange instance setting (default is 10000 – 20000, as described above). For example, for productions services the certificate may be bound to port 10001 and processing services to port 10002.
      • Agents URI – the certificate is bound to the port specified in the URI in the KeplerServicesUriForAgents instance setting. For example, https://agent1.mycompany.corp:8990 binds the certificate to port 8990.

        Note: The host name specified in the KeplerServicesUri and KeplerServicesUriForAgents instance settings for each web and agent server must match the host name (“Issued To” value) of the certificate. For example, if the agents server host name is https://rel-agent-server1, the KeplerServicesUriForAgents instance setting must be https://rel-agent-server1:8990/Kepler.

    • Upon initialization, Service Host and the Agent Manager attempt to automatically configure HTTPS and select the certificate (because KeplerServicesUri and KeplerServicesUriForAgents instance settings include the HTTPS prefix). Certificate selection logic is as follows:
      • Open the Personal store for the Computer Account and look for an exact host name match. The host name comes from   the KeplerServicesUri and KeplerServicesUriForAgents instance settings.
      • If there is no exact host name match, query the store for all valid certificates and use the one with the largest encryption key.
      • If there are no valid certificates, look for a wildcard certificate that would work.
      • If there are no valid wildcard certificates and the scheme is set to HTTPS, an exception is logged.
    • To override the default automatic certificate selection behavior, add the SslCertificateThumbprint instance setting for the server to explicitly specify the certificate to use:
      • Name – SslCertificateThumbprint.
      • Section – kCura.Service.ServiceHost.
      • Value – The thumbprint of the certificate for SSL bindings. For instructions on retrieving the thumbprint, see https://msdn.microsoft.com/en-us/library/ms734695(v=vs.110).aspx.

        Note: Make sure that you copy the Thumbprint certificate field when retrieving the thumbprint value (it's easy to confuse with the Serial number field). The thumbprint value must not include spaces (when you copy-paste it from the Windows certificate form, it does includes spaces). You must also remove the leading space because it contains an illegal character that can't be matched when the certificate is retrieved from the store. You likely have different certificates for different machines. To configure the certificate for HTTPS bindings for each machine, use the MachineName field of the instance setting.

  3. Set the value of the EnforceHttps instance setting as necessary:
    • EnforceHttps ensures that your KeplerServicesUri and KeplerServicesUriForAgents instance settings are set to HTTPS. If you have EnforceHttps set to Yes and your Kepler Uris are not set accordingly, Service Host will fail to host your services.
    • EnforceHttps can ensure that all incoming Service Host Manager traffic uses HTTPS. If any request comes in as HTTP and EnforceHttps is set to Yes, Service Host will not accept the request. Setting EnforceHttps to No does not force traffic to use HTTPS and allows HTTP. Setting EnforceHttps to Warn will still allow your services to be stood up as HTTP, but will log a warning.

Note: Beginning in Relativity 9.6, the Classic UI is no longer available. Because the new Relativity UI requires the Service Host Manager to already be running, it may not be available for setting up the Service Host Manager instance settings. As a workaround you can install Relativity as non-HTTPS first, and then create the instance settings for HTTPS using the UI. You can also create the instance settings using the stored procedure in the Relativity EDDS database. For more information, see Adding and deleting instance settings with stored procedures.

Removing certificate bindings

Relativity unbinds certificates from ports as part of the services normal shutdown cycle. Because abnormal shutdowns can also occur, and Service Host Manager uses a range of ports, it is possible that over time all ports in the range may be bound to certificates. Removing bindings for server maintenance one-by-one can be time-consuming, so the recommended way of clearing them is by using command line. You must shut down Service Host Manager before running this command:

Relativity.Services.ServiceHost.exe --unbindports

Troubleshooting hosted services

If an application error indicates that a service did not deploy successfully, start by reviewing the information on the Errors tab. If you are unable to identify the cause on the Errors tab, review the Relativity log. For more information, see Logging.

In most cases, Service Host Manager errors are resolved when the service restarts. Once the Service Host Manager restarts, a new end point is generated and service is redeployed.

If the problems persist, review the Service Host Manager port and HTTPS settings described above.