Installing Sensu

Select a platform from the dropdown above. Sensu Go is available for Linux, Windows (agent and CLI only), macOS (CLI only), and Docker. See the list of supported platforms for more information.

Install the Sensu backend

The Sensu backend is available for Ubuntu, RHEL/CentOS, and Docker.

1. Install the package

Ubuntu

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

RHEL/CentOS

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. Create the configuration file

Copy the example backend config file to the default config path.

sudo cp /usr/share/doc/sensu-go-backend-5.1.0/backend.yml.example /etc/sensu/backend.yml

NOTE: The Sensu backend can be configured using a /etc/sensu/backend.yml configuration file or using sensu-backend start configuration flags. For more information, see the backend reference.

3. Start the service

Start the backend using a service manager.

sudo service sensu-backend start

You can verify that the backend is running properly using the sensu-backend tool.

sensu-backend -h

Next steps

Now that you’ve installed the Sensu backend:

Install the Sensu agent

The Sensu agent is available for Ubuntu, RHEL/CentOS, Windows, and Docker.

1. Install the package

Ubuntu

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

RHEL/CentOS

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

Windows

Download the Sensu agent for Windows.

Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.1.0/sensu-go-5.1.0-windows-amd64.tar.gz  -OutFile C:\Users\Administrator\sensu-go-5.1.0-windows-amd64.tar.gz

See the verifying Sensu guide to verify your download using checksums.

2. Create the configuration file

Ubuntu/RHEL/CentOS

Copy the example agent config file to the default config path.

sudo cp /usr/share/doc/sensu-go-agent-5.1.0/agent.yml.example /etc/sensu/agent.yml

NOTE: The Sensu agent can be configured using a /etc/sensu/agent.yml configuration file or using sensu-agent start configuration flags. For more information, see the agent reference.

Windows

Download the example agent configuration file and save it as C:\\ProgramData\sensu\config\agent.yml.

3. Start the service

Ubuntu/RHEL/CentOS

Start the agent using a service manager.

sudo service sensu-agent start

You can verify that the agent is running properly using the sensu-agent tool.

sensu-agent -h

Windows

Coming soon.

Next steps

Now that you’ve installed the Sensu agent:

Install sensuctl

Sensu Go can be configured and used with the sensuctl command line utility. Sensuctl is available for Ubuntu, RHEL/CentOS, Windows, and macOS.

1. Install the package

Ubuntu

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

RHEL/CentOS

Add the Sensu repository.

curl -s https://packagecloud.io/install/repositories/sensu/stable/script.rpm.sh | sudo bash

Install the sensu-go-cli package.

sudo yum install sensu-go-cli

Windows

Download sensuctl for Windows.

Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.1.0/sensu-go-5.1.0-windows-amd64.tar.gz  -OutFile C:\Users\Administrator\sensu-go-5.1.0-windows-amd64.tar.gz

See the verifying Sensu guide to verify your download using checksums.

macOS

Download the latest release. See the verifying Sensu guide to verify your download using checksums.

curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.1.0/sensu-go-5.1.0-darwin-amd64.tar.gz

Extract the archive.

tar -xvf sensu-go-5.1.0-darwin-amd64.tar.gz

Copy the executable into your PATH.

sudo cp bin/sensuctl /usr/local/bin/

2. Configure sensuctl

You must configure sensuctl before it can connect to Sensu Go. Run sensuctl configure to get started.

$ sensuctl configure
? Sensu Backend URL: http://127.0.0.1:8080
? Username: admin
? Password: *********
? Namespace: default
? Preferred output format: tabular

By default, your Sensu installation comes with a user named admin with password P@ssw0rd!. We strongly recommended that you change the password immediately. Once authenticated, you can change the password using the change-password command.

$ sensuctl user change-password --interactive
? Current Password:  *********
? Password:          *********
? Confirm:           *********

You can change individual values of your sensuctl configuration with the config subcommand.

sensuctl config set-namespace default

See the sensuctl reference for more information about using sensuctl.

Next steps

Now that you’ve installed sensuctl:

Deploy Sensu with Docker

Sensu Go can be run via Docker or rkt using the sensu/sensu image. When running Sensu from Docker there are a couple of things to take into consideration.

The backend requires four exposed ports and persistent storage. This example uses a shared filesystem. Sensu Go is backed by a distributed database, and its storage should be provisioned accordingly. We recommend local storage or something like Throughput Optimized or Provisioned IOPS EBS if local storage is unavailable. The exposed ports are:

  • 2380: Sensu storage peer listener (only other Sensu backends need access to this port)
  • 3000: Sensu dashboard
  • 8080: Sensu API (all users need access to this port)
  • 8081: Agent API (all agents need access to this port)

We suggest, but do not require, persistent storage for Sensu backends and Sensu agents. The Sensu agent will cache runtime assets locally for each check, and the Sensu backend will cache runtime assets locally for each handler and mutator. This storage should be unique per sensu-backend/sensu-agent process.

Start a Sensu backend

docker run -v /var/lib/sensu:/var/lib/sensu -d --name sensu-backend -p 2380:2380 \
-p 3000:3000 -p 8080:8080 -p 8081:8081 sensu/sensu:latest sensu-backend start

Start a Sensu agent

In this case, we’re starting an agent with the webserver and system subscriptions as an example. This assumes that the Sensu backend is running on another host named sensu.yourdomain.com. If you are running these locally on the same system, be sure to add --link sensu-backend to your Docker arguments and change the backend URL --backend-url ws://sensu-backend:8081.

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 \
--subscriptions webserver,system --cache-dir /var/lib/sensu

NOTE: You can configure the backend and agent log levels by using the --log-level flag on either process. Log levels include panic, fatal, error, warn, info, and debug, defaulting to warn.

sensuctl and Docker

It’s best to run sensuctl locally and point it at the exposed API port for your the Sensu backend. The sensuctl utility stores configuration locally, and you’ll likely want to persist it across uses. While it can be run from the docker container, doing so may be problematic.