Installing Sensu

Sensu Go is available for Linux, Windows (agent and CLI only), macOS (CLI only), and Docker. If you’re trying out Sensu for the first time, we recommend setting up a local environment using the Sensu sandbox. If you’re deploying Sensu to your infrastructure, we recommend one of our supported packages, Docker images, or configuration management integrations. Sensu downloads are provided under the Sensu commercial license; see the supported platforms page for more information.

Architecture overview

Sensu architecture diagram

Powered by an an embedded transport and etcd datastore, the Sensu backend gives you flexible, automated workflows to route metrics and alerts. Sensu backends require persistent storage for their embedded database, disk space for local asset caching, and three exposed ports:

  • 3000 - Sensu web UI
  • 8080 - Sensu API used by sensuctl, some plugins, and any of your custom tooling
  • 8081 - WebSocket API used by Sensu agents

Sensu backends running in a clustered configuration require additional ports. See the deployment guide and hardware requirements guide for deployment recommendations.

Sensu agents are lightweight clients that run on the infrastructure components you want to monitor. Agents register automatically with Sensu as entities and are responsible for creating check and metric events to send to the backend event pipeline. Optionally, agents can expose ports 3031 for the agent API and 8125 for the StatsD listener. Agents using Sensu assets require some disk space for a local cache.

Install the Sensu backend

The Sensu backend is available for Ubuntu/Debian, RHEL/CentOS, and Docker. See the supported platforms page for more information.

1. Download
# All Sensu Docker images contain a Sensu backend and a Sensu agent

# Pull the Alpine-based image
docker pull sensu/sensu

# Pull the image based on Red Hat Enterprise Linux
docker pull sensu/sensu-rhel
# Add the Sensu repository
curl -s https://packagecloud.io/install/repositories/sensu/stable/script.deb.sh | sudo bash

# Install the sensu-go-backend package
sudo apt-get install sensu-go-backend
# Add the Sensu repository
curl -s https://packagecloud.io/install/repositories/sensu/stable/script.rpm.sh | sudo bash

# Install the sensu-go-backend package
sudo yum install sensu-go-backend
2. Initialize

Run sensu-backend init to set up your Sensu administrator username and password. In this initialization step, you only need to set environment variables with a username and password string — no need for role-based access control (RBAC).

Replace YOUR_USERNAME and YOUR_PASSWORD with the username and password you want to use:

export SENSU_BACKEND_CLUSTER_ADMIN_USERNAME=YOUR_USERNAME
export SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=YOUR_PASSWORD
sensu-backend init

For details about sensu-backend init, see the backend reference.

3. Configure and start

You can configure Sensu using sensu-backend start flags or an /etc/sensu/backend.yml file, the former taking precedence. At a minimum, the Sensu backend requires the state-dir flag, but here are some other useful configs and templates.

docker run -v /var/lib/sensu:/var/lib/sensu \
-d --name sensu-backend \
-p 3000:3000 -p 8080:8080 -p 8081:8081 sensu/sensu:latest \
sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug
---
version: "3"
services:
  sensu-backend:
    image: sensu/sensu:latest
    ports:
    - 3000:3000
    - 8080:8080
    - 8081:8081
    volumes:
    - "sensu-backend-data:/var/lib/sensu/etcd"
    command: "sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug"

volumes:
  sensu-backend-data:
    driver: local
# Copy the config template from the docs
sudo curl -L https://docs.sensu.io/sensu-go/latest/files/backend.yml -o /etc/sensu/backend.yml

# Start sensu-backend using a service manager
sudo service sensu-backend start

# Verify that the backend is running
service sensu-backend status
# Copy the config template from the docs
sudo curl -L https://docs.sensu.io/sensu-go/latest/files/backend.yml -o /etc/sensu/backend.yml

# Start sensu-backend using a service manager
sudo service sensu-backend start

# Verify that the backend is running
service sensu-backend status

For a complete list of config options, see the backend reference.

4. Open the web UI

The web UI provides a unified view of your monitoring events with user-friendly tools to reduce alert fatigue. After starting the Sensu backend, open the web UI by visiting http://localhost:3000. You may need to replace localhost with the hostname or IP address where the Sensu backend is running.

To log in, enter your Sensu user credentials (the user ID and password you provided with sensu-backend init). Select the ☰ icon to explore the web UI.

5. Make a request to the health API

To make sure the backend is up and running, we’ll check the health of the backend using the Sensu API. You should see a response that includes "Healthy": true.

curl http://127.0.0.1:8080/health

Now that you’ve installed the Sensu backend, install and configure sensuctl to connect to your backend URL and start monitoring your infrastructure by installing Sensu agents.

Install sensuctl

Sensuctl is a command line tool for managing resources within Sensu. It works by calling Sensu’s HTTP API to create, read, update, and delete resources, events, and entities. Sensuctl is available for Linux, Windows, and macOS.

To install sensuctl:

# Add the Sensu repository
curl -s https://packagecloud.io/install/repositories/sensu/stable/script.deb.sh | sudo bash

# Install the sensu-go-cli package
sudo apt-get install sensu-go-cli
# Add the Sensu repository
curl https://packagecloud.io/install/repositories/sensu/stable/script.rpm.sh | sudo bash

# Install the sensu-go-cli package
sudo yum install sensu-go-cli
# Download sensuctl for Windows amd64
Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.16.0/sensu-go_5.16.0_windows_amd64.zip  -OutFile C:\Users\Administrator\sensu-go_5.16.0_windows_amd64.zip

# Or for 386
Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.16.0/sensu-go_5.16.0_windows_386.zip  -OutFile C:\Users\Administrator\sensu-go_5.16.0_windows_386.zip
# Download the latest release
curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.16.0/sensu-go_5.16.0_darwin_amd64.tar.gz

# Extract the archive
tar -xvf sensu-go_5.16.0_darwin_amd64.tar.gz

# Copy the executable into your PATH.
sudo cp sensuctl /usr/local/bin/

To start using sensuctl, run sensuctl configure and log in with your user credentials, namespace, and Sensu backend URL. To configure sensuctl using defaults:

sensuctl configure -n \
--username 'admin' \
--password 'P@ssw0rd!' \
--namespace default \
--url 'http://127.0.0.1:8080'

Here the -n flag triggers non-interactive mode. Run sensuctl config view to see your user profile.

We strongly recommend that you change the default admin password immediately using sensuctl user change-password --interactive.

For more information about using sensuctl, see the quickstart and reference docs.

Install Sensu agents

The Sensu agent is available for Ubuntu/Debian, RHEL/CentOS, Windows, and Docker. See the supported platforms page for more information.

1. Download
# All Sensu images contain a Sensu backend and a Sensu agent

# Pull the Alpine-based image
docker pull sensu/sensu

# Pull the RHEL-based image
docker pull sensu/sensu-rhel
# Add the Sensu repository
curl -s https://packagecloud.io/install/repositories/sensu/stable/script.deb.sh | sudo bash

# Install the sensu-go-agent package
sudo apt-get install sensu-go-agent
# Add the Sensu repository
curl -s https://packagecloud.io/install/repositories/sensu/stable/script.rpm.sh | sudo bash

# Install the sensu-go-agent package
sudo yum install sensu-go-agent
# Download the Sensu agent for Windows amd64
Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.16.0/sensu-go-agent_5.16.0.7782_en-US.x64.msi  -OutFile "$env:userprofile\sensu-go-agent_5.16.0.7782_en-US.x64.msi"

# Or for Windows 386
Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.16.0/sensu-go-agent_5.16.0.7782_en-US.x86.msi  -OutFile "$env:userprofile\sensu-go-agent_5.16.0.7782_en-US.x86.msi"

# Install the Sensu agent
msiexec.exe /i $env:userprofile\sensu-go-agent_5.16.0.7782_en-US.x64.msi /qn

# Or via Chocolatey
choco install sensu-agent
2. Configure and start

You can configure the Sensu agent using sensu-agent start flags or an /etc/sensu/agent.yml file, the former taking precedence. At a minimum, the Sensu agent requires the --backend-url flag, but here are some other useful configs and templates.

# If you are running the agent locally on the same system as the Sensu backend,
# add `--link sensu-backend` to your Docker arguments and change the backend
# URL to `--backend-url ws://sensu-backend:8081`.

# Starts an agent with the system subscription
docker run -v /var/lib/sensu:/var/lib/sensu -d \
--name sensu-agent sensu/sensu:latest \
sensu-agent start --backend-url ws://sensu.yourdomain.com:8081 --log-level debug --subscriptions system --api-host 0.0.0.0 --cache-dir /var/lib/sensu
# Starts an agent with the system subscription
---
version: "3"
services:
  sensu-agent:
    image: sensu/sensu:latest
    ports:
    - 3031:3031
    volumes:
    - "sensu-agent-data:/var/lib/sensu"
    command: "sensu-agent start --backend-url ws://sensu-backend:8081 --log-level debug --subscriptions system --api-host 0.0.0.0 --cache-dir /var/lib/sensu"

volumes:
  sensu-agent-data:
    driver: local
# Copy the config template from the docs
sudo curl -L https://docs.sensu.io/sensu-go/latest/files/agent.yml -o /etc/sensu/agent.yml

# Start sensu-agent using a service manager
service sensu-agent start
# Copy the config template from the docs
sudo curl -L https://docs.sensu.io/sensu-go/latest/files/agent.yml -o /etc/sensu/agent.yml

# Start sensu-agent using a service manager
service sensu-agent start
# Copy the example agent config file from %ALLUSERSPROFILE%\sensu\config\agent.yml.example
# (default: C:\ProgramData\sensu\config\agent.yml.example) to C:\ProgramData\sensu\config\agent.yml
cp C:\ProgramData\sensu\config\agent.yml.example C:\ProgramData\sensu\config\agent.yml

# Change to the sensu\sensu-agent\bin directory where you've installed Sensu.
cd 'C:\Program Files\sensu\sensu-agent\bin'

# Run the sensu-agent executable.
./sensu-agent.exe

# Install and start the agent.
./sensu-agent service install

For a complete list of config options, see the agent reference.

3. Verify keepalive events

Sensu keepalives are the heartbeat mechanism used to ensure that all registered agents are operational and able to reach the Sensu backend.

To verify that the agent has registered with Sensu and is sending keepalive events, open the entity page in the Sensu web UI or run sensuctl entity list.

Commercial features

Sensu Inc. offers support packages for Sensu Go as well as commercial features designed for monitoring at scale. For more information about commercial features in Sensu Go, see the getting started guide.

All commercial features are free for your first 100 entities. To learn more about Sensu Go commercial licenses for more than 100 entities, contact the Sensu sales team.

If you already have a Sensu commercial license, log in to your Sensu account and download your license file, then add your license using sensuctl.

sensuctl create --file sensu_license.json

You can use sensuctl to view your license details at any time.

sensuctl license info

Next steps

Now that you’ve installed Sensu, here are some resources to help continue your journey: