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. Sensu downloads are provided under the Sensu License.

Install the Sensu backend

The Sensu backend is available for Ubuntu/Debian, RHEL/CentOS, and Docker. In addition to packages, binary-only distributions for Linux are available for amd64, arm64, armv5, armv6, armv7, and 386 architectures.

1. Install the package

Ubuntu/Debian

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.7.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

Verify that the backend is running.

service sensu-backend status

Next steps

Now that you’ve installed the Sensu backend:

Install the Sensu agent

The Sensu agent is available for Ubuntu/Debian, RHEL/CentOS, Windows, and Docker. In addition to packages, binary-only distributions for Linux are available for amd64, arm64, armv5, armv6, armv7, and 386 architectures and for Windows amd64 and 386 architectures.

1. Install the package

Ubuntu/Debian

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 amd64 or 386 architectures.

Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.7.0/sensu-go-agent_5.7.0.2380_en-US.x64.msi  -OutFile "$env:userprofile\sensu-go-agent_5.7.0.2380_en-US.x64.msi"

Start the installation wizard.

msiexec.exe /i $env:userprofile\sensu-go-agent_5.7.0.2380_en-US.x64.msi

2. Create the configuration file

Linux

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

sudo cp /usr/share/doc/sensu-go-agent-5.7.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

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

3. Start the service

Linux

Start the agent using a service manager.

sudo service sensu-agent start

Verify that the agent is running.

service sensu-agent status

Windows

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

Run the following command to install and start the agent.

./sensu-agent service install

Verify that the agent is running.

sc.exe query SensuAgent

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/Debian, RHEL/CentOS, Windows, and macOS.

1. Install the package

Ubuntu/Debian

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 amd64.

Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.7.0/sensu-enterprise-go_5.7.0_windows_amd64.tar.gz  -OutFile C:\Users\Administrator\sensu-enterprise-go_5.7.0_windows_amd64.tar.gz

Or download sensuctl for Windows 386.

Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.7.0/sensu-enterprise-go_5.7.0_windows_386.tar.gz  -OutFile C:\Users\Administrator\sensu-enterprise-go_5.7.0_windows_386.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.7.0/sensu-enterprise-go_5.7.0_darwin_amd64.tar.gz

Extract the archive.

tar -xvf sensu-enterprise-go_5.7.0_darwin_amd64.tar.gz

Copy the executable into your PATH.

sudo cp 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.

3. Activate enterprise-only features

Sensu Inc. offers support packages for Sensu Go as well as license-activated features designed for enterprises. To learn more about enterprise features in Sensu Go, contact the Sensu sales team.

If you already have an enterprise license, log in to your Sensu account and download your license file, then activate 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

For more information about enterprise features in Sensu Go, see the getting started guide.

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, add --link sensu-backend to your Docker arguments and change the backend URL to --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 install and 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.