How to Install Sensu Go on Debian 11: A Step-by-Step Guide
In the world of modern infrastructure, effective monitoring is no longer a luxury—it’s a necessity. Sensu Go offers a powerful and flexible observability pipeline, allowing you to collect, filter, and process health and metrics data from any source. Unlike traditional monitoring tools, Sensu is designed for the dynamic nature of cloud environments, containers, and microservices.
This comprehensive guide will walk you through the complete installation and initial configuration of the Sensu Go backend and agent on Debian 11 (Bullseye). By the end, you will have a fully functional observability platform ready to monitor your critical systems.
Prerequisites: What You’ll Need Before You Start
Before we begin, ensure your system has the necessary packages to add new software repositories. Most Debian 11 installations will have these, but it’s always best to confirm.
Open your terminal and run the following command to install curl and gnupg:
sudo apt-get update && sudo apt-get install -y curl gnupg
Step 1: Add the Sensu Go Repository
To ensure you receive stable updates, the recommended method for installing Sensu Go is through its official package repository. This process involves two key steps: adding the repository’s GPG key for security and then adding the repository itself.
First, add the GPG key to your system’s trusted keyring. This key verifies that the packages you download are authentic and have not been tampered with.
curl -s https://packagecloud.io/sensu/stable/gpgkey | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/sensu.gpg
Next, add the Sensu Go repository configuration to your system’s package manager sources.
echo "deb https://packagecloud.io/sensu/stable/debian/ buster main" | sudo tee /etc/apt/sources.list.d/sensu.list
Note: While we are on Debian 11 (Bullseye), the ‘buster’ repository is the correct and compatible source for this installation.
Finally, update your local package cache to include the newly added Sensu repository.
sudo apt-get update
Step 2: Install the Sensu Go Backend
The Sensu Go backend is the central processing and data storage component. It manages configuration, processes event data, and provides the API and web UI for interacting with the platform.
Install the backend package with the following command:
sudo apt-get install sensu-go-backend
Step 3: Configure and Initialize the Backend
With the backend installed, you need to create a minimal configuration file. This file tells the backend where to store its data. The default configuration path is /etc/sensu/backend.yml.
Create and edit the file using your preferred text editor, such as nano:
sudo nano /etc/sensu/backend.yml
Add the following basic configuration. This is sufficient to get the service started:
# /etc/sensu/backend.yml
state-dir: "/var/lib/sensu/sensu-backend"
cache-dir: "/var/lib/sensu/sensu-backend/cache"
Now, it’s time to initialize the backend. This crucial one-time step sets up the administrative user and cluster information.
sudo sensu-backend init --cluster-admin-username your-admin-user --cluster-admin-password 'your-strong-password' --interactive
Important: Replace your-admin-user and your-strong-password with your desired credentials. Store this password securely, as you will need it to log in to the web UI and configure the command-line tool.
Once initialization is complete, you can enable and start the backend service.
sudo systemctl enable sensu-go-backend
sudo systemctl start sensu-go-backend
To confirm the service is running correctly, check its status:
sudo systemctl status sensu-go-backend
You should see an “active (running)” status in the output.
Step 4: Configure the sensuctl Command-Line Tool
sensuctl is the command-line interface (CLI) for managing your Sensu Go installation. It’s installed automatically with the backend. You need to configure it to communicate with your backend API.
Run the interactive configuration command:
sensuctl configure
You will be prompted for the following information:
- Sensu Backend URL:
http://127.0.0.1:8080(use the default if running on the same machine) - Username:
your-admin-user(the one you created during initialization) - Password:
your-strong-password(the password you set) - Namespace:
default(press Enter) - Preferred output format:
tabular(press Enter)
After configuration, you can test the connection by listing users:
sensuctl user list
You should see your admin user in the output.
Step 5: Install and Configure the Sensu Go Agent
The Sensu Go agent is a lightweight client that runs on the machines you want to monitor. It discovers system information, executes monitoring checks, and sends the results back to the backend.
Install the agent package on the same server (or any other server you want to monitor):
sudo apt-get install sensu-go-agent
Next, configure the agent by editing its configuration file at /etc/sensu/agent.yml.
sudo nano /etc/sensu/agent.yml
Add the following configuration, ensuring the backend-url points to your Sensu backend’s websocket port (8081).
# /etc/sensu/agent.yml
backend-url:
- "ws://127.0.0.1:8081"
namespace: "default"
If your agent is on a different machine, replace 127.0.0.1 with the IP address or hostname of your Sensu backend server.
Finally, enable and start the agent service.
sudo systemctl enable sensu-go-agent
sudo systemctl start sensu-go-agent
Step 6: Verify Your Installation
Your Sensu Go backend and agent should now be running and communicating. You can verify this in two ways.
First, use sensuctl to see if the agent has registered itself as an “entity” with the backend.
sensuctl entity list
You should see an entry for the host where you installed the agent.
Second, access the Sensu Go web UI. Open a web browser and navigate to your server’s IP address on port 8080:
http://<your-server-ip>:8080
Log in with the admin username and password you created during the backend initialization step. Once logged in, you can explore the dashboard and see your connected agent on the Entities page.
Next Steps and Security Best Practices
You now have a foundational Sensu Go installation. To build a robust and secure observability platform, consider these important next steps:
- Secure the Web UI: For production environments, it is highly recommended to place the backend behind a reverse proxy (like Nginx or Caddy) to enable TLS/SSL encryption for secure web access.
- Implement RBAC: Use Sensu’s Role-Based Access Control (RBAC) to create specific users and roles with limited permissions, adhering to the principle of least privilege.
- Manage Firewall Rules: Ensure your firewall only allows traffic on necessary ports, such as
8080(API/Web UI),8081(agent websocket), and2379/2380(for clustering). - Start Monitoring: Begin creating monitoring checks, handlers to process alerts (e.g., sending notifications to Slack or PagerDuty), and filters to reduce alert noise.
Source: https://kifarunix.com/install-sensu-go-on-debian-11/
