Configure the Contrast service

Unlike the service executable packaged with the Ruby and Python agents, the Contrast service isn't preconfigured with connection parameters. Instead, you must configure the service with a YAML configuration file.

When installed as a system service, the Contrast service is controlled by this YAML configuration file located in the /etc directory. Frequently, the service shares the same contrast_security.yaml file with any other applications on the same server, to ensure that all connection values (like the socket name or port number) are consistent.

Assuming an application-specific configuration file is not already installed in the application's working directory, the location of the YAML configuration file determines whether it can be shared with the agent on the same server:

  • If you don't want it to be shared, place the configuration file at /etc/contrast/webserver/contrast_security.yaml.

  • If you do want it to be shared, place the configuration file at /etc/contrast/contrast_security.yaml.

A default configuration YAML file is installed with the Contrast service Linux package at /etc/contrast/webserver/contrast_security.yaml. This template has placeholders for most necessary items, but you should update the following:

  • api: Set the api properties. This determines how the Contrast service connects to Contrast.

  • agent: This is the top-level configuration section for agent-related configuration.

    • service: These options affect communication between an agent and the Contrast service. The connection configuration must be identical between the Contrast service and the agent communicating with that service.

      • socket: The path to the local unix socket (for example, /tmp/contrast.sock)

      • host and port: Optionally, instead of socket, the Contrast Service can be configured to connect at a host and port.

      • grpc: Set to "true" to use gRPC for agent to service communication. This is optional and may provide a slight performance improvement for the Node.js agent.

If this configuration has an issue or incorrect values, or the Contrast service fails to connect to Contrast, you can troubleshoot the failed connection result at /var/log/contrast/service.log.