Sensu backend
The Sensu backend is a service that manages check requests and event data.
Every Sensu backend includes an integrated transport for scheduling checks using subscriptions, an event processing pipeline that applies filters, mutators, and handlers, an embedded etcd datastore for storing configuration and state, a Sensu API, Sensu dashboard, and sensu-backend
command-line tool.
The Sensu backend is available for Ubuntu/Debian and RHEL/CentOS distributions of Linux.
See the installation guide to install the backend.
Event pipeline
The backend processes event data and executes filters, mutators, and handlers.
These pipelines are powerful tools to automate your monitoring workflows.
To learn more about filters, mutators, and handlers, see:
Check scheduling
The backend is responsible for storing check definitions and scheduling check requests.
Check scheduling is subscription-based; the backend sends check requests to subscriptions where they’re picked up by subscribing agents.
For information about creating and managing checks, see:
Operation and service management
NOTE: Commands in this section may require administrative privileges.
Starting the service
Use the sensu-backend
tool to start the backend and apply configuration flags.
To start the backend with configuration flags:
sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug
To see available configuration flags and defaults:
sensu-backend start --help
If no configuration flags are provided, the backend loads configuration from /etc/sensu/backend.yml
by default.
To start the backend using a service manager:
service sensu-backend start
Stopping the service
To stop the backend service using a service manager:
service sensu-backend stop
Restarting the service
You must restart the backend to implement any configuration updates.
To restart the backend using a service manager:
service sensu-backend restart
Enabling on boot
To enable the backend to start on system boot:
systemctl enable sensu-backend
To disable the backend from starting on system boot:
systemctl disable sensu-backend
NOTE: On older distributions of Linux, use sudo chkconfig sensu-server on
to enable the backend and sudo chkconfig sensu-server off
to disable.
Getting service status
To see the status of the backend service using a service manager:
service sensu-backend status
Getting service version
To get the current backend version using the sensu-backend
tool:
Getting help
The sensu-backend
tool provides general and command-specific help flags:
# Show sensu-backend commands
sensu-backend help
# Show options for the sensu-backend start subcommand
sensu-backend start --help
Clustering
You can run the backend as a standalone service, but running a cluster of backends makes Sensu more highly available, reliable, and durable.
Sensu backend clusters build on the clustering system used by etcd.
Clustering lets you synchronize data between backends and get the benefits of a highly available configuration.
To configure a cluster, see:
Time synchronization
System clocks between agents and the backend should be synchronized to a central NTP server. Out of sync system time may cause issues with keepalive, metric, and check alerts.
Configuration
You can specify the backend configuration using a /etc/sensu/backend.yml
file or using sensu-backend start
configuration flags.
The backend requires that the state-dir
flag be set before starting; all other required flags have default values.
See the example config file provided with Sensu at /usr/share/doc/sensu-go-backend-5.2.1/backend.yml.example
.
The backend loads configuration upon startup, so you must restart the backend for any configuration updates to take effect.
Configuration summary
$ sensu-backend start --help
start the sensu backend
Usage:
sensu-backend start [flags]
General Flags:
--agent-host string agent listener host (default "[::]")
--agent-port int agent listener port (default 8081)
--api-listen-address string address to listen on for api traffic (default "[::]:8080")
--api-url string url of the api to connect to (default "http://localhost:8080")
--cache-dir string path to store cached data (default "/var/cache/sensu/sensu-backend")
--cert-file string TLS certificate in PEM format
-c, --config-file string path to sensu-backend config file
--dashboard-host string dashboard listener host (default "[::]")
--dashboard-port int dashboard listener port (default 3000)
--debug enable debugging and profiling features
--deregistration-handler string default deregistration handler
-h, --help help for start
--insecure-skip-tls-verify skip TLS verification (not recommended!)
--key-file string TLS certificate key in PEM format
--log-level string logging level [panic, fatal, error, warn, info, debug] (default "warn")
-d, --state-dir string path to sensu state storage (default "/var/lib/sensu/sensu-backend")
--trusted-ca-file string TLS CA certificate bundle in PEM format
Store Flags:
--etcd-advertise-client-urls strings list of this member's client URLs to advertise to the rest of the cluster. (default [http://localhost:2379])
--etcd-cert-file string path to the client server TLS cert file
--etcd-client-cert-auth enable client cert authentication
--etcd-initial-advertise-peer-urls strings list of this member's peer URLs to advertise to the rest of the cluster (default [http://127.0.0.1:2380])
--etcd-initial-cluster string initial cluster configuration for bootstrapping (default "default=http://127.0.0.1:2380")
--etcd-initial-cluster-state string initial cluster state ("new" or "existing") (default "new")
--etcd-initial-cluster-token string initial cluster token for the etcd cluster during bootstrap
--etcd-key-file string path to the client server TLS key file
--etcd-listen-client-urls strings list of URLs to listen on for client traffic (default [http://127.0.0.1:2379])
--etcd-listen-peer-urls strings list of URLs to listen on for peer traffic (default [http://127.0.0.1:2380])
--etcd-name string human-readable name for this member (default "default")
--etcd-peer-cert-file string path to the peer server TLS cert file
--etcd-peer-client-cert-auth enable peer client cert authentication
--etcd-peer-key-file string path to the peer server TLS key file
--etcd-peer-trusted-ca-file string path to the peer server TLS trusted CA file
--etcd-trusted-ca-file string path to the client server TLS trusted CA cert file
--no-embed-etcd don't embed etcd, use external etcd instead
General configuration flags
cache-dir |
|
description |
Path to store cached data |
type |
String |
default |
- Linux:
/var/cache/sensu/sensu-backend - Windows:
C:\\ProgramData\sensu\cache\sensu-backend
|
example |
# Command line example
sensu-backend start --cache-dir /cache/sensu-backend
# /etc/sensu/backend.yml example
cache-dir: "/cache/sensu-backend"
|
config-file |
|
description |
Path to Sensu backend config file |
type |
String |
default |
- Linux:
/etc/sensu/backend.yml - FreeBSD:
/usr/local/etc/sensu/backend.yml - Windows:
C:\\ProgramData\sensu\config\backend.yml
|
example |
# Command line example
sensu-backend start --config-file /etc/sensu/backend.yml
sensu-backend start -c /etc/sensu/backend.yml
# /etc/sensu/backend.yml example
config-file: "/etc/sensu/backend.yml"
|
debug |
|
description |
Enable debugging and profiling features |
type |
Boolean |
default |
false |
example |
# Command line example
sensu-backend start --debug
# /etc/sensu/backend.yml example
debug: true
|
deregistration-handler |
|
description |
Default event handler to use when processing agent deregistration events. |
type |
String |
default |
"" |
example |
# Command line example
sensu-backend start --deregistration-handler /path/to/handler.sh
# /etc/sensu/backend.yml example
deregistration-handler: "/path/to/handler.sh"
|
log-level |
|
description |
Logging level: panic , fatal , error , warn , info , or debug |
type |
String |
default |
warn |
example |
# Command line example
sensu-backend start --log-level debug
# /etc/sensu/backend.yml example
log-level: "debug"
|
state-dir |
|
description |
Path to Sensu state storage: /var/lib/sensu/sensu-backend for Linux and C:\\ProgramData\sensu\data for Windows. |
type |
String |
required |
true |
example |
# Command line example
sensu-backend start --state-dir /var/lib/sensu/sensu-backend
sensu-backend start -d /var/lib/sensu/sensu-backend
# /etc/sensu/backend.yml example
state-dir: "/var/lib/sensu/sensu-backend"
|
api-listen-address |
|
description |
Address the API daemon will listen for requests on |
type |
String |
default |
[::]:8080 |
example |
# Command line example
sensu-backend start --api-listen-address [::]:8080
# /etc/sensu/backend.yml example
api-listen-address: "[::]:8080"
|
api-url |
|
description |
URL used to connect to the API |
type |
String |
default |
http://localhost:8080 |
example |
# Command line example
sensu-backend start --api-url http://localhost:8080
# /etc/sensu/backend.yml example
api-url: "http://localhost:8080"
|
Agent communication configuration flags
agent-host |
|
description |
agent listener host, listens on all IPv4 and IPv6 addresses by default |
type |
String |
default |
[::] |
example |
# Command line example
sensu-backend start --agent-host 127.0.0.1
# /etc/sensu/backend.yml example
agent-host: "127.0.0.1"
|
agent-port |
|
description |
agent listener port |
type |
Integer |
default |
8081 |
example |
# Command line example
sensu-backend start --agent-port 8081
# /etc/sensu/backend.yml example
agent-port: 8081
|
Security configuration flags
cert-file |
|
description |
Path to the primary backend certificate file. This certificate secures communications between Sensu Dashboard and end user web browsers, as well as communication between sensuctl and the Sensu API. |
type |
String |
default |
"" |
example |
# Command line example
sensu-backend start --cert-file /path/to/ssl/cert.pem
# /etc/sensu/backend.yml example
cert-file: "/path/to/ssl/cert.pem"
|
key-file |
|
description |
SSL/TLS certificate key. This key secures communication between Sensu Dashboard and end user web browsers, as well as communication between sensuctl and the Sensu API. |
type |
String |
default |
"" |
example |
# Command line example
sensu-backend start --key-file /path/to/ssl/key.pem
# /etc/sensu/backend.yml example
key-file: "/path/to/ssl/key.pem"
|
trusted-ca-file |
|
description |
Specifies a fallback SSL/TLS certificate authority in PEM format used for etcd client (mutual TLS) communication if the etcd-trusted-ca-file is not used. |
type |
String |
default |
"" |
example |
# Command line example
sensu-backend start --trusted-ca-file /path/to/trusted-certificate-authorities.pem
# /etc/sensu/backend.yml example
trusted-ca-file: "/path/to/trusted-certificate-authorities.pem"
|
insecure-skip-tls-verify |
|
description |
Skip SSL verification. WARNING: This configuration flag is intended for use in development systems only. Do not use this flag in production. |
type |
Boolean |
default |
false |
example |
# Command line example
sensu-backend start --insecure-skip-tls-verify
# /etc/sensu/backend.yml example
insecure-skip-tls-verify: true
|
Dashboard configuration flags
dashboard-host |
|
description |
Dashboard listener host |
type |
String |
default |
[::] |
example |
# Command line example
sensu-backend start --dashboard-host 127.0.0.1
# /etc/sensu/backend.yml example
dashboard-host: "127.0.0.1"
|
dashboard-port |
|
description |
Dashboard listener port |
type |
Integer |
default |
3000 |
example |
# Command line example
sensu-backend start --dashboard-port 4000
# /etc/sensu/backend.yml example
dashboard-port: 4000
|
Datastore and cluster configuration flags
etcd-advertise-client-urls |
|
description |
List of this member’s client URLs to advertise to the rest of the cluster. |
type |
List |
default |
http://localhost:2379 |
example |
# Command line examples
sensu-backend start --etcd-advertise-client-urls http://localhost:2378,http://localhost:2379
sensu-backend start --etcd-advertise-client-urls http://localhost:2378 --etcd-advertise-client-urls http://localhost:2379
# /etc/sensu/backend.yml example
etcd-advertise-client-urls:
- http://localhost:2378
- http://localhost:2379
|
etcd-cert-file |
|
description |
Path to the etcd client API TLS cert file. Secures communication between the embedded etcd client API and any etcd clients. |
type |
String |
default |
"" |
example |
# Command line example
sensu-backend start --etcd-cert-file ./client.pem
# /etc/sensu/backend.yml example
etcd-cert-file: "./client.pem"
|
etcd-client-cert-auth |
|
description |
Enable client cert authentication |
type |
Boolean |
default |
false |
example |
# Command line example
sensu-backend start --etcd-client-cert-auth
# /etc/sensu/backend.yml example
etcd-client-cert-auth: true
|
etcd-initial-advertise-peer-urls |
|
description |
List of this member’s peer URLs to advertise to the rest of the cluster |
type |
List |
default |
http://127.0.0.1:2380 |
example |
# Command line examples
sensu-backend start --etcd-listen-peer-urls https://10.0.0.1:2380,https://10.1.0.1:2380
sensu-backend start --etcd-listen-peer-urls https://10.0.0.1:2380 --etcd-listen-peer-urls https://10.1.0.1:2380
# /etc/sensu/backend.yml example
etcd-listen-peer-urls:
- https://10.0.0.1:2380
- https://10.1.0.1:2380
|
etcd-initial-cluster |
|
description |
Initial cluster configuration for bootstrapping |
type |
String |
default |
default=http://127.0.0.1:2380 |
example |
# Command line example
sensu-backend start --etcd-initial-cluster backend-0=https://10.0.0.1:2380,backend-1=https://10.1.0.1:2380,backend-2=https://10.2.0.1:2380
# /etc/sensu/backend.yml example
etcd-initial-cluster: "backend-0=https://10.0.0.1:2380,backend-1=https://10.1.0.1:2380,backend-2=https://10.2.0.1:2380"
|
etcd-initial-cluster-state |
|
description |
Initial cluster state (new or existing ) |
type |
String |
default |
new |
example |
# Command line example
sensu-backend start --etcd-initial-cluster-state existing
# /etc/sensu/backend.yml example
etcd-initial-cluster-state: "existing"
|
etcd-initial-cluster-token |
|
description |
Initial cluster token for the etcd cluster during bootstrap |
type |
String |
default |
"" |
example |
# Command line example
sensu-backend start --etcd-initial-cluster-token sensu
# /etc/sensu/backend.yml example
etcd-initial-cluster-token: "sensu"
|
etcd-key-file |
|
description |
Path to the etcd client API TLS key file. Secures communication between the embedded etcd client API and any etcd clients. |
type |
String |
example |
# Command line example
sensu-backend start --etcd-key-file ./client-key.pem
# /etc/sensu/backend.yml example
etcd-key-file: "./client-key.pem"
|
etcd-listen-client-urls |
|
description |
List of URLs to listen on for client traffic |
type |
List |
default |
http://127.0.0.1:2379 |
example |
# Command line examples
sensu-backend start --etcd-listen-client-urls https://10.0.0.1:2379,https://10.1.0.1:2379
sensu-backend start --etcd-listen-client-urls https://10.0.0.1:2379 --etcd-listen-client-urls https://10.1.0.1:2379
# /etc/sensu/backend.yml example
etcd-listen-client-urls:
- https://10.0.0.1:2379
- https://10.1.0.1:2379
|
etcd-listen-peer-urls |
|
description |
List of URLs to listen on for peer traffic |
type |
List |
default |
http://127.0.0.1:2380 |
example |
# Command line examples
sensu-backend start --etcd-listen-peer-urls https://10.0.0.1:2380,https://10.1.0.1:2380
sensu-backend start --etcd-listen-peer-urls https://10.0.0.1:2380 --etcd-listen-peer-urls https://10.1.0.1:2380
# /etc/sensu/backend.yml example
etcd-listen-peer-urls:
- https://10.0.0.1:2380
- https://10.1.0.1:2380
|
etcd-name |
|
description |
Human-readable name for this member |
type |
String |
default |
default |
example |
# Command line example
sensu-backend start --etcd-name backend-0
# /etc/sensu/backend.yml example
etcd-name: "backend-0"
|
etcd-peer-cert-file |
|
description |
Path to the peer server TLS certificate file. This certificate secures communication between etcd cluster members. |
type |
String |
example |
# Command line example
sensu-backend start --etcd-peer-cert-file ./backend-0.pem
# /etc/sensu/backend.yml example
etcd-peer-cert-file: "./backend-0.pem"
|
etcd-peer-client-cert-auth |
|
description |
Enable peer client cert authentication |
type |
Boolean |
default |
false |
example |
# Command line example
sensu-backend start --etcd-peer-client-cert-auth
# /etc/sensu/backend.yml example
etcd-peer-client-cert-auth: true
|
etcd-peer-key-file |
|
description |
Path to the etcd peer API TLS key file. Secures communication between etcd cluster members. |
type |
String |
example |
# Command line example
sensu-backend start --etcd-peer-key-file ./backend-0-key.pem
# /etc/sensu/backend.yml example
etcd-peer-key-file: "./backend-0-key.pem"
|
etcd-peer-trusted-ca-file |
|
description |
Path to the etcd peer API server TLS trusted CA file. This certificate secures communication between etcd cluster members. |
type |
String |
example |
# Command line example
sensu-backend start --etcd-peer-trusted-ca-file ./ca.pem
# /etc/sensu/backend.yml example
etcd-peer-trusted-ca-file: "./ca.pem"
|
etcd-trusted-ca-file |
|
description |
Path to the client server TLS trusted CA cert file. Secures communication with the etcd client |
type |
String |
default |
"" |
example |
# Command line example
sensu-backend start --etcd-trusted-ca-file ./ca.pem
# /etc/sensu/backend.yml example
etcd-trusted-ca-file: "./ca.pem"
|
no-embed-etcd |
|
description |
Don’t embed etcd, use external etcd instead |
type |
Boolean |
default |
false |
example |
# Command line example
sensu-backend start --no-embed-etcd
# /etc/sensu/backend.yml example
no-embed-etcd: true
|