Install Sensu
This installation guide describes how to install the Sensu backend, Sensu agent, and sensuctl command line tool.
These instructions explain how to install Sensu for proof-of-concept purposes or testing in a development environment. We recommend using a supported package to follow this guide.
To build Sensu Go from source (OSS), follow the Sensu Go installation instructions on GitHub.
NOTE: If you’re trying Sensu for the first time, consider following the the Sensu Go workshop instead.
The workshop includes a local sandbox environment and a collection of resources designed to help new users learn and test Sensu.
If you will deploy Sensu to your infrastructure, we recommend securing your installation with transport layer security (TLS) in addition to using one of our supported packages, Docker images, or configuration management integrations.
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 sensuctl only), macOS (sensuctl only), and Docker. Review 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 (for example, 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, read Secure Sensu. Read 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 etcd cluster members to communicate directly with their peers |
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 (backend WebSocket): 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 Debian- and RHEL-family distributions and Docker. Review 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, read the backend reference.
# Replace `<username>` and `<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=<username> \
-e SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=<password> \
sensu/sensu:latest \
sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug
# Replace `<username>` and `<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=<username>
- SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=<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 systemctl start sensu-backend
# Verify that the backend is running
sudo systemctl status sensu-backend
# 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 systemctl start sensu-backend
# Verify that the backend is running
sudo systemctl status sensu-backend
The backend reference includes a complete list of configuration options and backend initialization details.
WARNING: 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 <username>
and <password>
with the username and password you want to use:
export SENSU_BACKEND_CLUSTER_ADMIN_USERNAME=<username>
export SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=<password>
sensu-backend init
export SENSU_BACKEND_CLUSTER_ADMIN_USERNAME=<username>
export SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=<password>
sensu-backend init
For details about initializing the Sensu backend, read 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
COMMERCIAL FEATURE: Access the Sensu web UI in the packaged Sensu Go distribution. For more information, read Get started with commercial features.
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 receive 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.10.0/sensu-go_6.10.0_windows_amd64.zip -OutFile C:\Users\Administrator\sensu-go_6.10.0_windows_amd64.zip
# Or for Windows 386
Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.10.0/sensu-go_6.10.0_windows_386.zip -OutFile C:\Users\Administrator\sensu-go_6.10.0_windows_386.zip
# Unzip the file with PowerShell for Windows amd64
Expand-Archive -LiteralPath 'C:\Users\Administrator\sensu-go_6.10.0_windows_amd64.zip' -DestinationPath 'C:\\Program Files\sensu\sensuctl\bin'
# or for Windows 386
Expand-Archive -LiteralPath 'C:\Users\Administrator\sensu-go_6.10.0_windows_386.zip' -DestinationPath 'C:\\Program Files\sensu\sensuctl\bin'
# Download the latest release
curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.10.0/sensu-go_6.10.0_darwin_amd64.tar.gz
# Extract the archive
tar -xvf sensu-go_6.10.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 view your user profile.
For more information about sensuctl, read 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 Debian- and RHEL-family distributions, Windows, and Docker. Review 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.10.0/sensu-go-agent_6.10.0.7172_en-US.x64.msi -OutFile "$env:userprofile\sensu-go-agent_6.10.0.7172_en-US.x64.msi"
# Or for Windows 386
Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.10.0/sensu-go-agent_6.10.0.7172_en-US.x86.msi -OutFile "$env:userprofile\sensu-go-agent_6.10.0.7172_en-US.x86.msi"
# Install the Sensu agent for Windows amd64
msiexec.exe /i $env:userprofile\sensu-go-agent_6.10.0.7172_en-US.x64.msi /qn
# Or for Windows 386
msiexec.exe /i $env:userprofile\sensu-go-agent_6.10.0.7172_en-US.x86.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
sudo systemctl start sensu-agent
# 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
sudo systemctl start sensu-agent
# 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
The agent reference includes a complete list of configuration options.
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 core/v2/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 use 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 try Sensu, 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.
Save your license to a file such as sensu_license.yml
or sensu_license.json
.
Use sensuctl to activate your license:
sensuctl create --file sensu_license.yml
sensuctl create --file sensu_license.json
You can use sensuctl to view your license details at any time.
sensuctl license info