Contrast service

The Contrast service is a stand-alone executable that enables communication between Contrast and multi-process dynamic language agents (Go, Ruby, Node.js and Python agents). It passes settings from Contrast to the agent. It also aggregates and sends information from the agent back to Contrast.

It is compiled for various supported architectures:

  • Linux 64-bit

  • Macintosh 64-bit

  • Windows 64-bit

The service is packaged with the Node.js, Python and Ruby agents, and starts automatically when the instrumented application is started. The service is not packaged or started by the Go agent. You must have a service installed, configured and running for the Go agent to function. You may do the same for more control when running the Node.js, Python, or Ruby agents.

Install the Contrast service

Installation varies depending on your system:

  • Linux: Install the Contrast service with a system package manager.

  • Debian: Use the commands to install from the correct Debian repository.

    1. Get the CODENAME for your Ubuntu release.

      grep VERSION_CODENAME /etc/os-release

    2. Update the command below with the CODENAME, and run the commands.

      curl https://pkg.contrastsecurity.com/api/gpg/key/public | sudo apt-key add -
echo "deb https://pkg.contrastsecurity.com/debian-public/ CODENAME contrast" | sudo tee /etc/apt/sources.list.d/contrastc.list

    3. Install the Contrast service:

      sudo apt-get update && sudo apt-get install contrast-service

    4. Configure the Contrast service.

  • Red Hat Package Manager (RPM): Use these commands to install from Contrast's yum repository.

    1. Configure your system to use the repository:

      OSREL=$(rpmquery -E "%{rhel}")
sudo -E tee /etc/yum.repos.d/contrast.repo << EOF
[contrast]
name=contrast repo
baseurl=https://pkg.contrastsecurity.com/rpm-public/centos-$OSREL/
gpgcheck=0
enabled=1
EOF

    2. Install the Contrast service:

      yum install contrast-service

    3. Configure the Contrast service.

Tip

To remove the contrast-service package, run apt-get remove contrast-service or yum remove contrast-service.

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.

In this section: