Sensu on Ubuntu/Debian

Reference documentation

Install Sensu Core

Sensu Core is installed on Ubuntu and Debian systems via a native system installer package (i.e. a .deb file), which is available for download from the Sensu Downloads page, and from APT package management repositories. The Sensu Core package installs several processes including sensu-server, sensu-api, and sensu-client.

Install Sensu using APT (recommended)

NOTE: As of January 2017, 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://sensu.global.ssl.fastly.net/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://sensu.global.ssl.fastly.net/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

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.

    Confirm that you have correctly set your access credentials as environment variables

    $ echo $SE_USER:$SE_PASS
    1234567890:PASSWORD
    
  2. Install the GPG public key:

    wget -q http://$SE_USER:$SE_PASS@enterprise.sensuapp.com/apt/pubkey.gpg -O- | sudo apt-key add -
    
  3. Create an APT configuration file at /etc/apt/sources.list.d/sensu-enterprise.list:

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

    sudo apt-get update
    
  5. Install Sensu Enterprise:

    sudo apt-get install sensu-enterprise sensu-enterprise-dashboard
    
  6. 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.

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 init 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",
        "address": "127.0.0.1",
        "environment": "development",
        "subscriptions": [
          "dev",
          "ubuntu"
        ],
        "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. Please refer to the configuration instructions for the corresponding transport for configuration file examples (see Redis, or RabbitMQ reference documentation).

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.

  • Enable the Sensu client on system boot

    sudo update-rc.d sensu-client defaults
    
  • 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 defaults
      sudo update-rc.d sensu-api defaults
      
    • For Sensu Enterprise users

      sudo update-rc.d sensu-enterprise defaults
      

      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 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 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 provided init scripts:

  • Start or stop the Sensu client

    sudo /etc/init.d/sensu-client start
    sudo /etc/init.d/sensu-client stop
    
  • Start or stop the Sensu Core server

    sudo /etc/init.d/sensu-server start
    sudo /etc/init.d/sensu-server stop
    
  • Start or stop the Sensu Core API

    sudo /etc/init.d/sensu-api start
    sudo /etc/init.d/sensu-api stop
    
  • Start or stop Sensu Enterprise

    sudo /etc/init.d/sensu-enterprise start
    sudo /etc/init.d/sensu-enterprise stop
    
  • Start or stop the Sensu Enterprise Dashboard

    sudo /etc/init.d/sensu-enterprise-dashboard start
    sudo /etc/init.d/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).

Start your FREE trial today.

Already using Sensu Core? Upgrade to Sensu Enterprise today to take advantage of its enterprise console, added-value features, built-in integrations, FREE annual training, and enterprise-class support.