Ubuntu/Debian

Sensu on Ubuntu/Debian 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 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 Ubuntu and Debian systems via a native system installer package (i.e. a .deb file). The Sensu Core package installs several processes including sensu-server, sensu-api, and sensu-client.

Sensu packages for Debian target current stable and oldstable releases.

Sensu packages for Ubuntu target current Long Term Support (LTS) releases.

If you wish to install Sensu packages on newer Debian or Ubuntu releases, please try installing a package built for the most recent Debian stable or Ubuntu LTS release.

Install Sensu using APT (recommended)

NOTE: As of Sensu version 0.27, apt repository configuration has changed to include the “codename” of the Ubuntu/Debian release. To install or upgrade to the latest version of Sensu, please ensure you have updated existing repository configurations.

  1. Install the GPG public key: 

    wget -q https://eol-repositories.sensuapp.org/apt/pubkey.gpg -O- | sudo apt-key add -

  2. Determine the codename of the Ubuntu/Debian release on your system: 

    . /etc/os-release && echo $VERSION
"14.04.4 LTS, Trusty Tahr" # codename for this system is "trusty"

  3. Create an APT configuration file at /etc/apt/sources.list.d/sensu.list: 

    export CODENAME=your_release_codename_here # e.g. "trusty"
echo "deb     https://eol-repositories.sensuapp.org/apt $CODENAME main" | sudo tee /etc/apt/sources.list.d/sensu.list

  4. Update APT: 

    sudo apt-get update

  5. Install Sensu: 

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

  6. 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 specified in the instructions 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 Ubuntu and Debian systems via a native system installer package (i.e. a .deb file). The Sensu Enterprise installer package is made available via the Sensu Enterprise APT 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).

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. Install the apt-transport-https package: 

    sudo apt-get install apt-transport-https

  3. Install the GPG public key: 

    wget -q https://$SE_USER:$SE_PASS@enterprise.sensuapp.com/apt/pubkey.gpg -O- | sudo apt-key add -

  4. Create an APT configuration file at /etc/apt/sources.list.d/sensu-enterprise.list: 

    echo "deb     https://$SE_USER:$SE_PASS@enterprise.sensuapp.com/apt sensu-enterprise main" | sudo tee /etc/apt/sources.list.d/sensu-enterprise.list

  5. Update APT: 

    sudo apt-get update

  6. Install Sensu Enterprise: 

    sudo apt-get install sensu-enterprise

  7. 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. Install the apt-transport-https package: 

    sudo apt-get install apt-transport-https

  3. Install the GPG public key: 

    wget -q https://$SE_USER:$SE_PASS@enterprise.sensuapp.com/apt/pubkey.gpg -O- | sudo apt-key add -

  4. Create an APT configuration file at /etc/apt/sources.list.d/sensu-enterprise.list: 

    echo "deb     https://$SE_USER:$SE_PASS@enterprise.sensuapp.com/apt sensu-enterprise main" | sudo tee /etc/apt/sources.list.d/sensu-enterprise.list

  5. Update APT: 

    sudo apt-get update

  6. Install Sensu Enterprise Dashboard: 

    sudo apt-get install sensu-enterprise-dashboard

  7. 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 Ubuntu and Debian 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.

sudo 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": "ubuntu-client",
    "address": "127.0.0.1",
    "environment": "development",
    "subscriptions": [
      "dev",
      "ubuntu-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 update-rc.d utility. If you are using Ubuntu 16.04+ you will need to use systemctl instead.

  • Enable the Sensu client on system boot

    sudo update-rc.d sensu-client enable

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

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

      sudo update-rc.d sensu-server enable
sudo update-rc.d sensu-api enable

    • For Sensu Enterprise users

      sudo update-rc.d sensu-enterprise enable

      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 update-rc.d sensu-enterprise-dashboard enable

    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 update-rc.d utility.

  • Disable the Sensu client on system boot

    sudo update-rc.d sensu-client disable

  • Disable the Sensu Core server on system boot

    sudo update-rc.d sensu-server disable

  • Disable the Sensu Core API on system boot

    sudo update-rc.d sensu-api disable

  • Disable Sensu Enterprise on system boot

    sudo update-rc.d sensu-enterprise disable

  • Disable Sensu Enterprise Dashboard on system boot

    sudo update-rc.d sensu-enterprise-dashboard disable

Operating Sensu

Managing the Sensu services/processes

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

  • 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).