RHEL/CentOS

Sensu on RHEL/CentOS reference documentation

Install Sensu Core

IMPORTANT: Sensu Core reached end-of-life (EOL) on December 31, 2019, and we permanently removed the Sensu EOL repository on February 1, 2021.

This means the packages and https://eol-repositories.sensuapp.org URLs specified in the instructions and code examples below are no longer available. To migrate to Sensu Go, read Migrate from Sensu Core and Sensu Enterprise to Sensu Go.

Sensu Core is installed on RHEL and CentOS systems via a native system installer package (i.e. a .rpm file), which is available for download and from YUM package management repositories. The Sensu Core package installs several processes including sensu-server, sensu-api, and sensu-client.

Install Sensu using YUM (recommended)

Sensu packages for Red Hat target currently supported versions of Red Hat Enterprise Linux and their Centos equivalents. These packages are generally expected to be compatible with Red Hat derivatives like SuSE, Amazon or Scientific Linux, but packages are not tested on these platforms.

The following instructions describe configuring package repository definitions using Yum variables as components of the baseurl. On Red Hat derivative platforms the value of the $releasever variable will not typically align with the RHEL release versions (e.g. 6 or 7) advertised in the Sensu Yum repository. Please use 6 or 7 in lieu of $releasever on RHEL derivatives, depending on whether they use sysv init or systemd, respectively.

NOTE: As of Sensu version 0.27, the yum repository URL has changed to include the $releasever variable. To install or upgrade to the latest version of Sensu, please ensure you have updated existing repository configurations.

  1. Create the YUM repository configuration file for the Sensu Core repository at /etc/yum.repos.d/sensu.repo: 

    echo '[sensu]
name=sensu
baseurl=https://eol-repositories.sensuapp.org/yum/$releasever/$basearch/
gpgkey=https://eol-repositories.sensuapp.org/yum/pubkey.gpg
gpgcheck=1
enabled=1' | sudo tee /etc/yum.repos.d/sensu.repo

  2. Install Sensu: 

    sudo yum install sensu
    NOTE: as mentioned above, the sensu package installs all of the Sensu Core processes, including sensu-client, sensu-server, and sensu-api.

  3. Configure Sensu. No “default” configuration is provided with Sensu, so none of the Sensu processes will run without the corresponding configuration. Please refer to the “Configure Sensu” section (below), for more information on configuring Sensu. At minimum, all of the Sensu processes will need a working transport definition. The Sensu client will need a client definition, and both the sensu-server and sensu-api will need a data-store (Redis) definition — all of which are explained below.

Install Sensu Enterprise

IMPORTANT: Sensu Enterprise reached end-of-life (EOL) March 31, 2020, and we permanently removed the Sensu EOL repository on February 1, 2021.

This means the packages and https://eol-repositories.sensuapp.org URLs specified in the instructions and code examples below are no longer available. To migrate to Sensu Go, read Migrate from Sensu Core and Sensu Enterprise to Sensu Go.

Sensu Enterprise is installed on RHEL and CentOS systems via a native system installer package (i.e. a .rpm file). The Sensu Enterprise installer package is made available via the Sensu Enterprise YUM repository, which requires access credentials to access. The Sensu Enterprise packages install two processes: sensu-enterprise (which provides the Sensu server and API from a single process), and sensu-enterprise-dashboard (which provides the dashboard API and web application).

NOTE: Some versions of RHEL and CentOS may require the EPEL package repository to provide the required OpenJDK runtime.

WARNING: Sensu Enterprise is designed to be a drop-in replacement for the Sensu Core server and API, only. Sensu Enterprise uses the same sensu-client process provided by the Sensu Core installer packages (above). As a result, Sensu Enterprise does not need to be installed on every system being monitored by Sensu.

Install the Sensu Enterprise repository

  1. Set access credentials as environment variables 

    SE_USER=1234567890
SE_PASS=PASSWORD
    NOTE: please replace 1234567890 and PASSWORD with the access credentials provided with your Sensu Enterprise subscription. These access credentials can be found by logging into the Sensu Account Manager portal. Confirm that you have correctly set your access credentials as environment variables 
    $ echo $SE_USER:$SE_PASS
1234567890:PASSWORD

  2. Create a YUM repository configuration file for the Sensu Enterprise repository at /etc/yum.repos.d/sensu-enterprise.repo: 

    echo "[sensu-enterprise]
name=sensu-enterprise
baseurl=https://$SE_USER:$SE_PASS@enterprise.sensuapp.com/yum/noarch/
gpgkey=https://eol-repositories.sensuapp.org/yum/pubkey.gpg
gpgcheck=1
enabled=1" | sudo tee /etc/yum.repos.d/sensu-enterprise.repo

  3. Install Sensu Enterprise 

    sudo yum install sensu-enterprise

  4. Configure Sensu Enterprise. No “default” configuration is provided with Sensu Enterprise, so Sensu Enterprise will run without the corresponding configuration. Please refer to the “Configure Sensu” section (below) for more information on configuring Sensu Enterprise.

Install the Sensu Enterprise Dashboard repository

  1. Set access credentials as environment variables 

    SE_USER=1234567890
SE_PASS=PASSWORD
    NOTE: please replace 1234567890 and PASSWORD with the access credentials provided with your Sensu Enterprise subscription. These access credentials can be found by logging into the Sensu Account Manager portal. Confirm that you have correctly set your access credentials as environment variables 
    $ echo $SE_USER:$SE_PASS
1234567890:PASSWORD

  2. Create a YUM repository configuration file for the Sensu Enterprise Dashboard repository at /etc/yum.repos.d/sensu-enterprise-dashboard.repo: 

    echo "[sensu-enterprise-dashboard]
name=sensu-enterprise-dashboard
baseurl=https://$SE_USER:$SE_PASS@enterprise.sensuapp.com/yum/\$basearch/
gpgkey=https://eol-repositories.sensuapp.org/yum/pubkey.gpg
gpgcheck=1
enabled=1" | sudo tee /etc/yum.repos.d/sensu-enterprise-dashboard.repo

  3. Install Sensu Enterprise Dashboard 

    sudo yum install sensu-enterprise-dashboard

  4. Configure Sensu Enterprise Dashboard. The default configuration will not work without modification Please refer to the “Example Sensu Enterprise Dashboard configurations” section (below) for more information on configuring Sensu Enterprise Dashboard.

Configure Sensu

By default, all of the Sensu services on RHEL and CentOS systems will load configuration from the following locations:

  • /etc/sensu/config.json
  • /etc/sensu/conf.d/

NOTE: Additional or alternative configuration file and directory locations may be used by modifying Sensu’s service scripts and/or by starting the Sensu services with the corresponding CLI arguments. For more information, please consult the Sensu Configuration reference documentation.

Create the Sensu configuration directory

In some cases, the default Sensu configuration directory (i.e. /etc/sensu/conf.d/) is not created by the Sensu installer, in which case it is necessary to create this directory manually.

mkdir /etc/sensu/conf.d

Example client configuration

  1. Copy the following contents to a configuration file located at /etc/sensu/conf.d/client.json: 
    {
  "client": {
    "name": "rhel-client",
    "address": "127.0.0.1",
    "environment": "development",
    "subscriptions": [
      "dev",
      "rhel-hosts"
    ],
    "socket": {
      "bind": "127.0.0.1",
      "port": 3030
    }
  }
}

Example transport configuration

At minimum, all of the Sensu processes require configuration to tell them how to connect to the configured Sensu Transport.

  1. Copy the following contents to a configuration file located at /etc/sensu/conf.d/transport.json: 

    {
  "transport": {
    "name": "rabbitmq",
    "reconnect_on_error": true
  }
}
    NOTE: if you are using Redis as your transport, please use "name": "redis" for your transport configuration. For more information, please visit the transport definition specification.

  2. If the transport being used is running on a different host, additional configuration is required to tell the sensu client how to connect to the transport. Please see Redis or RabbitMQ reference documentation for examples.

Example data store configuration

The Sensu Core server and API processes, and the Sensu Enterprise process all require configuration to tell them how to connect to Redis (the Sensu data store). Please refer to the Redis reference documentation for configuration file examples.

Example API configurations

Standalone configuration

  1. Copy the following contents to a configuration file located at /etc/sensu/conf.d/api.json: 
    {
  "api": {
    "host": "localhost",
    "bind": "0.0.0.0",
    "port": 4567
  }
}

Distributed configuration

  1. Obtain the IP address of the system where the Sensu API is installed. For the purpose of this guide, we will use 10.0.1.7 as our example IP address.

  2. Create a configuration file with the following contents at /etc/sensu/conf.d/api.json on the Sensu server and API system(s): 

    {
  "api": {
    "host": "10.0.1.7",
    "bind": "10.0.1.7",
    "port": 4567
  }
}

Example Sensu Enterprise Dashboard configurations

Standalone configuration

  1. Copy the following contents to a configuration file located at /etc/sensu/dashboard.json: 
    {
  "sensu": [
    {
      "name": "Datacenter 1",
      "host": "localhost",
      "port": 4567
    }
  ],
  "dashboard": {
    "host": "0.0.0.0",
    "port": 3000
  }
}

Distributed configuration

  1. Obtain the IP address of the system where Sensu Enterprise is installed. For the purpose of this guide, we will use 10.0.1.7 as our example IP address.

  2. Copy the following contents to a configuration file located at /etc/sensu/dashboard.json: 

    {
  "sensu": [
    {
      "name": "Datacenter 1",
      "host": "10.0.1.7",
      "port": 4567
    }
  ],
  "dashboard": {
    "host": "0.0.0.0",
    "port": 3000
  }
}
    NOTE: Multiple Sensu Enterprise Dashboard instances can be installed. When load balancing across multiple Dashboard instances, your load balancer should support “sticky sessions”.

  3. The Sensu Enterprise Dashboard process requires configuration to tell it how to connect to Redis (the Sensu data store). Please refer to the Redis installation instructions for configuration file examples.

Enable the Sensu services to start on boot

By default, the Sensu services are not configured to start automatically on system boot (we recommend managing the Sensu services with a process supervisor such as runit). To enable Sensu services on system boot, use the chkconfig utility.

  • Enable the Sensu client on system boot

    sudo chkconfig sensu-client on

  • Enable the Sensu server and API to start on system boot

    • For Sensu Core users (i.e. sensu-server and sensu-api)

      sudo chkconfig sensu-server on
sudo chkconfig sensu-api on

    • For Sensu Enterprise users

      sudo chkconfig sensu-enterprise on

      WARNING: the sensu-enterprise process is intended to be a drop-in replacement for the Sensu Core sensu-server and sensu-api processes. Please ensure that the Sensu Core processes are not configured to start on system boot before enabling Sensu Enterprise to start on system boot.

  • Enable Sensu Enterprise Dashboard on system boot

    sudo chkconfig sensu-enterprise-dashboard defaults

    WARNING: the sensu-enterprise-dashboard process is intended to be a drop-in replacement for the Uchiwa dashboard. Please ensure that the Uchiwa processes are not configured to start on system boot before enabling the Sensu Enterprise Dashboard to start on system boot.

Disable the Sensu services on boot

If you have enabled Sensu services on boot and now need to disable them, this can also be accomplished using the chkconfig utility.

  • Disable the Sensu client on system boot

    sudo chkconfig sensu-client off

  • Disable the Sensu Core server on system boot

    sudo chkconfig sensu-server off

  • Disable the Sensu Core API on system boot

    sudo chkconfig sensu-api off

  • Disable Sensu Enterprise on system boot

    sudo chkconfig sensu-enterprise off

  • Disable Sensu Enterprise Dashboard on system boot

    sudo chkconfig sensu-enterprise-dashboard remove

Operating Sensu

Managing the Sensu services/processes

To manually start and stop the Sensu services, use the following commands:

NOTE: The service command will not work on CentOS 5, the sysvinit script must be used, e.g. sudo /etc/init.d/sensu-client start

  • Start or stop the Sensu client

    sudo service sensu-client start
sudo service sensu-client stop

  • Start or stop the Sensu Core server

    sudo service sensu-server start
sudo service sensu-server stop

  • Start or stop the Sensu Core API

    sudo service sensu-api start
sudo service sensu-api stop

  • Start or stop Sensu Enterprise

    sudo service sensu-enterprise start
sudo service sensu-enterprise stop

  • Start or stop the Sensu Enterprise Dashboard

    sudo service sensu-enterprise-dashboard start
sudo service sensu-enterprise-dashboard stop

    Verify the Sensu Enterprise Dashboard is running by visiting view the dashboard at http://localhost:3000 (replace localhost with the hostname or IP address where the Sensu Enterprise Dashboard is running).