Install Sensu
This installation guide describes how to install the Sensu backend, Sensu agent, and sensuctl command line tool. If you’re trying Sensu for the first time, we recommend setting up a local environment using the Sensu sandbox.
NOTE: The instructions in this guide explain how to install Sensu for proof-of-concept purposes or testing in a development environment. If you will deploy Sensu to your infrastructure, we recommend one of our supported packages, Docker images, or configuration management integrations, as well as securing your installation with transport layer security (TLS). Read Generate certificates next to get the certificates you will need for TLS.
Sensu downloads are provided under the Sensu commercial license.
Sensu Go is packaged for Linux, Windows (agent and CLI only), macOS (CLI only), and Docker. See supported platforms for more information.
Architecture overview
Sensu works differently from other monitoring and observability solutions. Instead of provisioning each device, server, container, or sidecar you want to monitor, you install the Sensu agent on each infrastructure component.
Sensu agents are lightweight clients that run on the infrastructure components you want to monitor. Agents are responsible for creating status and metric events to send to the Sensu backend event pipeline. Agents automatically register with Sensu as entities when you start them up and connect to the Sensu backend with no need for further provisioning. You only need to specify the IP address for the Sensu backend server — you do not need to list the components to monitor in the backend.
The Sensu backend is powered by an an embedded transport and etcd datastore. The backend sends specific checks for each agent to execute according to the subscriptions you define in the agent configuration. Sensu automatically downloads the files needed to run the checks from an asset repository like Bonsai or a local repo and schedules the checks on each agent. The agents execute the checks the backend sends to their subscriptions and send the resulting status and metric events to the backend event pipeline, which gives you flexible, automated workflows to route these events.

The Sensu backend keeps track of all self-registered agents. If the backend loses a keepalive signal from any of the agents, it flags the agent and generates an event. You can configure your instance so that when an agent (e.g. a server) shuts down gracefully, the agent automatically de-registers from the backend and does not generate an alert.
Sensu backends require persistent storage for their embedded database, disk space for local asset caching, and several exposed ports. Agents that use Sensu dynamic runtime assets require some disk space for a local cache.
For more information, see the Secure Sensu guide. See deployment architecture and hardware requirements for deployment recommendations.
Ports
Sensu backends require the following ports:
Port | Protocol | Description |
---|---|---|
2379 | gRPC | Sensu storage client: Required for Sensu backends using an external etcd instance |
2380 | gRPC | Sensu storage peer: Required for other Sensu backends in a cluster |
3000 | HTTP/HTTPS | Sensu web UI: Required for all Sensu backends using a Sensu web UI |
6060 | HTTP/HTTPS | Required for all Sensu backends when performance profiling is enabled via debug setting |
8080 | HTTP/HTTPS | Sensu API: Required for all users accessing the Sensu API |
8081 | WS/WSS | Agent API: Required for all Sensu agents connecting to a Sensu backend |
The Sensu agent uses the following ports:
Port | Protocol | Description |
---|---|---|
3030 | TCP/UDP | Sensu agent socket: Required for Sensu agents using the agent socket |
3031 | HTTP | Sensu agent API: Required for all users accessing the agent API |
8125 | UDP | StatsD listener: Required for all Sensu agents using the StatsD listener |
The agent TCP and UDP sockets are deprecated in favor of the agent API.
Install the Sensu backend
The Sensu backend is available for Ubuntu/Debian, RHEL/CentOS, and Docker. See supported platforms 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. Configure and start
You can configure the Sensu backend with sensu-backend start
flags (recommended) or an /etc/sensu/backend.yml
file.
The Sensu backend requires the state-dir
flag at minimum, but other useful configurations and templates are available.
NOTE: If you are using Docker, intitialization is included in this step when you start the backend rather than in 3. Initialize. For details about intialization in Docker, see the backend reference.
# Replace `YOUR_USERNAME` and `YOUR_PASSWORD` with the username and password
# you want to use for your admin user credentials.
docker run -v /var/lib/sensu:/var/lib/sensu \
-d --name sensu-backend \
-p 3000:3000 -p 8080:8080 -p 8081:8081 \
-e SENSU_BACKEND_CLUSTER_ADMIN_USERNAME=YOUR_USERNAME \
-e SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=YOUR_PASSWORD \
sensu/sensu:latest \
sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug
# Replace `YOUR_USERNAME` and `YOUR_PASSWORD` with the username and password
# you want to use for your admin user credentials.
---
version: "3"
services:
sensu-backend:
ports:
- 3000:3000
- 8080:8080
- 8081:8081
volumes:
- "sensu-backend-data:/var/lib/sensu/sensu-backend/etcd"
command: "sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug"
environment:
- SENSU_BACKEND_CLUSTER_ADMIN_USERNAME=YOUR_USERNAME
- SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=YOUR_PASSWORD
image: sensu/sensu:latest
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 configuration options, see the backend reference.
IMPORTANT: If you plan to run a Sensu cluster, make sure that each of your backend nodes is configured, running, and a member of the cluster before you continue the installation process.
3. Initialize
NOTE: If you are using Docker, you already completed intitialization in 2. Configure and start. Skip ahead to 4. Open the web UI to continue the backend installation process. If you did not use environment variables to override the default admin credentials in step 2, skip ahead to Install sensuctl so you can change your default admin password immediately.
With the backend running, 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
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.
NOTE: You may need to allow access to the ports Sensu requires in your local server firewall. Refer to the documentation for your operating system to configure port access as needed.
4. Open the web UI
The web UI provides a unified view of your observability events and 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 to the web UI, enter your Sensu user credentials.
If you are using Docker and you did not specify environment variables to override the default admin credentials, your user credentials are username admin
and password P@ssw0rd!
.
Otherwise, your user credentials are the username and password you provided with the SENSU_BACKEND_CLUSTER_ADMIN_USERNAME
and SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD
environment variables.
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, use the Sensu health API to check the backend’s health.
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. Then you can install a Sensu agent and start monitoring your infrastructure.
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/6.0.0/sensu-go_6.0.0_windows_amd64.zip -OutFile C:\Users\Administrator\sensu-go_6.0.0_windows_amd64.zip
# Or for 386
Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.0.0/sensu-go_6.0.0_windows_386.zip -OutFile C:\Users\Administrator\sensu-go_6.0.0_windows_386.zip
# Download the latest release
curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.0.0/sensu-go_6.0.0_darwin_amd64.tar.gz
# Extract the archive
tar -xvf sensu-go_6.0.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 default values:
sensuctl configure -n \
--username 'YOUR_USERNAME' \
--password 'YOUR_PASSWORD' \
--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.
For more information about sensuctl, see the sensuctl documentation.
Change default admin password
If you are using Docker and you did not use environment variables to override the default admin credentials in step 2 of the backend installation process, we recommend that you change the default admin password as soon as you have installed sensuctl. Run:
sensuctl user change-password --interactive
Install Sensu agents
The Sensu agent is available for Ubuntu/Debian, RHEL/CentOS, Windows, and Docker. See supported platforms 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/6.0.0/sensu-go-agent_6.0.0.3003_en-US.x64.msi -OutFile "$env:userprofile\sensu-go-agent_6.0.0.3003_en-US.x64.msi"
# Or for Windows 386
Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.0.0/sensu-go-agent_6.0.0.3003_en-US.x86.msi -OutFile "$env:userprofile\sensu-go-agent_6.0.0.3003_en-US.x86.msi"
# Install the Sensu agent
msiexec.exe /i $env:userprofile\sensu-go-agent_6.0.0.3003_en-US.x64.msi /qn
# Or via Chocolatey
choco install sensu-agent
2. Configure and start
You can configure the Sensu agent with sensu-agent start
flags (recommended) or an /etc/sensu/agent.yml
file.
The Sensu agent requires the --backend-url
flag at minimum, but other useful configurations and templates are available.
# 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`.
# Start 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
# Start 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 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 configuration options, see the agent reference.
3. Verify keepalive events
Sensu keepalives are the heartbeat mechanism used to ensure that all registered agents are operating and can reach the Sensu backend.
To confirm that the agent is registered with Sensu and is sending keepalive events, open the entity page in the Sensu web UI or run sensuctl entity list
.
4. Verify an example event
With your backend and agent still running, send this request to the Sensu events API:
curl -X POST \
-H 'Content-Type: application/json' \
-d '{
"check": {
"metadata": {
"name": "check-mysql-status"
},
"status": 1,
"output": "could not connect to mysql"
}
}' \
http://127.0.0.1:3031/events
This request creates a warning
event that you can view in your web UI Events page.
To create an OK
event, change the status
to 0
and resend.
You can change the output
value to connected to mysql
to see a different message for the OK
event.
Next steps
Now that you have installed Sensu, you’re ready to build your observability pipelines! Here are some ideas for next steps.
Get started with Sensu
If you’re ready to see what Sensu can do, one of these pathways can get you started:
- Manually trigger an event that sends alerts to your email inbox.
- Create a check to monitor CPU usage and send Slack alerts based on your check.
- Collect metrics with a Sensu check and use a handler to populate metrics in InfluxDB.
- Use the sensuctl dump command to export all of your events and resources as a backup — then use sensuctl create to restore if needed.
Deploy Sensu outside your local development environment
To deploy Sensu for use outside of a local development environment, first decide whether you want to run a Sensu cluster. A Sensu cluster is a group of three or more sensu-backend nodes, each connected to a shared database provided either by Sensu’s embedded etcd or an external etcd cluster.
Clustering allows you to absorb the loss of a backend node, prevent data loss, and distribute the network load of agents. However, scaling a single backend to a cluster or migrating a cluster from cleartext HTTP to encrypted HTTPS without downtime can require a number of tedious steps. For this reason, we recommend that you decide whether your deployment will require clustering as part of your initial planning effort.
No matter whether you deploy a single backend or a clustered configuration, begin by securing Sensu with transport layer security (TLS). The first step in setting up TLS is to generate the certificates you need. Then, follow our Secure Sensu guide to make Sensu production-ready.
After you’ve secured Sensu, read Run a Sensu cluster if you are setting up a clustered configuration.
Commercial features
Sensu Inc. offers support packages for Sensu Go and commercial features designed for monitoring at scale.
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