Sensuctl
- First-time setup
- Managing sensuctl
- Creating resources
- Updating resources
- Managing resources
- Filtering (licensed tier)
- Time formats
- Shell auto-completion
- Config files
Sensuctl is a command line tool for managing resources within Sensu. It works by calling Sensu’s underlying API to create, read, update, and delete resources, events, and entities. Sensuctl is available for Linux, macOS, and Windows. See the installation guide to install and configure sensuctl.
Getting help
Sensuctl supports a --help
flag for each command and subcommand.
# See command and global flags
sensuctl --help
# See subcommands and flags
sensuctl check --help
# See usage and flags
sensuctl check delete --help
First-time setup
To set up sensuctl, run sensuctl configure
to log in to sensuctl and connect to the Sensu backend.
sensuctl configure
When prompted, input the Sensu backend URL and your Sensu access credentials.
? Sensu Backend URL: http://127.0.0.1:8080
? Username: admin
? Password: P@ssw0rd!
? Namespace: default
? Preferred output format: tabular
Sensu backend URL
The HTTP or HTTPS URL where sensuctl can connect to the Sensu backend server, defaulting to http://127.0.0.1:8080
.
When connecting to a Sensu cluster, connect sensuctl to any single backend in the cluster.
For more information on configuring the Sensu backend URL, see the backend reference.
Username | password | namespace
By default, Sensu includes a user named admin
with password P@ssw0rd!
and a default
namespace.
Your ability to get, list, create, update, and delete resources with sensuctl depends on the permissions assigned to your Sensu user.
For more information about configuring Sensu access control, see the RBAC reference.
Preferred output format
Sensuctl supports the following output formats:
tabular
: user-friendly, columnar formatwrapped-json
: accepted format for use withsensuctl create
yaml
: accepted format for use withsensuctl create
json
: format used by the Sensu API
Once logged in, you can change the output format using sensuctl config set-format
or set it per command using the --format
flag.
Non-interactive
You can run sensuctl configure
non-interactively using the -n
(--non-interactive
) flag.
sensuctl configure -n --url http://127.0.0.1:8080 --username admin --password P@ssw0rd! --format tabular
Managing sensuctl
The sencutl config
command lets you view the current sensuctl configuration and set the namespace and output format.
View sensuctl config
To view the active configuration for sensuctl:
sensuctl config view
Sensuctl configuration includes the Sensu backend url, default output format for the current user, and default namespace for the current user.
api-url: http://127.0.0.1:8080
format: wrapped-json
namespace: default
Set output format
You can use the set-format
command to change the default output format for the current user.
For example, to change the output format to tabular
:
sensuctl config set-format tabular
Set namespace
You can use the set-namespace
command to change the default namespace for the current user.
For more information about configuring Sensu access control, see the RBAC reference.
For example, to change the default namespace to development
:
sensuctl config set-namespace development
Log out of sensuctl
To log out of sensuctl:
sensuctl logout
To log back in:
sensuctl configure
View the sensuctl version number
To display the current version of sensuctl:
sensuctl version
Global flags
Global flags modify settings specific to sensuctl, such as the Sensu backend URL and namespace. You can use global flags with most sensuctl commands.
--api-url string host URL of Sensu installation
--cache-dir string path to directory containing cache & temporary files
--config-dir string path to directory containing configuration files
--insecure-skip-tls-verify skip TLS certificate verification (not recommended!)
--namespace string namespace in which we perform actions
--trusted-ca-file string TLS CA certificate bundle in PEM format
Additionally, these flags can be set permanently by editing .config/sensu/sensuctl/{cluster, profile}
.
Creating resources
The sensuctl create
command allows you to create or update resources by reading from STDIN or a flag configured file (-f
).
The create
command accepts Sensu resource definitions in wrapped-json
and yaml
.
Both JSON and YAML resource definitions wrap the contents of the resource in spec
and identify the resource type
(see below for an example, and this table for a list of supported types).
See the reference docs for information about creating resource definitions.
wrapped-json
format
The following file my-resources.json
specifies two resources: a marketing-site
check and a slack
handler, separated without a comma.
{
"type": "CheckConfig",
"api_version": "core/v2",
"metadata" : {
"name": "marketing-site",
"namespace": "default"
},
"spec": {
"command": "check-http.rb -u https://sensu.io",
"subscriptions": ["demo"],
"interval": 15,
"handlers": ["slack"]
}
}
{
"type": "Handler",
"api_version": "core/v2",
"metadata": {
"name": "slack",
"namespace": "default"
},
"spec": {
"command": "sensu-slack-handler --channel '#monitoring'",
"env_vars": [
"SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
],
"filters": [
"is_incident",
"not_silenced"
],
"handlers": [],
"runtime_assets": [],
"timeout": 0,
"type": "pipe"
}
}
To create all resources from my-resources.json
using sensuctl create
:
sensuctl create --file my-resources.json
Or:
cat my-resources.json | sensuctl create
yaml
format
The following file my-resources.yml
specifies two resources: a marketing-site
check and a slack
handler, separated with three dashes (---
).
---
type: CheckConfig
api_version: core/v2
metadata:
name: marketing-site
namespace: default
spec:
command: check-http.rb -u https://sensu.io
subscriptions:
- demo
interval: 15
handlers:
- slack
---
type: Handler
api_version: core/v2
metadata:
name: slack
namespace: default
spec:
command: sensu-slack-handler --channel '#monitoring'
env_vars:
- SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
filters:
- is_incident
- not_silenced
type: pipe
To create all resources from my-resources.yml
using sensuctl create
:
sensuctl create --file my-resources.yml
Or:
cat my-resources.yml | sensuctl create
sensuctl create resource types
sensuctl create types | |||
---|---|---|---|
AdhocRequest |
adhoc_request |
Asset |
asset |
CheckConfig |
check_config |
ClusterRole |
cluster_role |
ClusterRoleBinding |
cluster_role_binding |
Entity |
entity |
Event |
event |
EventFilter |
event_filter |
Handler |
handler |
Hook |
hook |
HookConfig |
hook_config |
Mutator |
mutator |
Namespace |
namespace |
Role |
role |
RoleBinding |
role_binding |
Silenced |
silenced |
ldap |
ad |
TessenConfig |
Updating resources
Sensuctl allows you to update resource definitions using a text editor.
To use sensuctl edit
, specify the resource type and resource name.
For example, to edit a handler named slack
using sensuctl edit
:
sensuctl edit handler slack
sensuctl edit resource types
sensuctl edit types | |||
---|---|---|---|
asset |
check |
cluster |
cluster-role |
cluster-role-binding |
entity |
event |
filter |
handler |
hook |
mutator |
namespace |
role |
role-binding |
silenced |
user |
auth |
Managing resources
Sensuctl provides the following commands to manage Sensu resources.
sensuctl asset
sensuctl auth
(licensed tier)sensuctl check
sensuctl cluster
sensuctl cluster-role
sensuctl cluster-role-binding
sensuctl entity
sensuctl event
sensuctl filter
sensuctl handler
sensuctl hook
sensuctl license
(licensed tier)sensuctl mutator
sensuctl namespace
sensuctl role
sensuctl role-binding
sensuctl silenced
sensuctl tessen
sensuctl user
Subcommands
Sensuctl provides a standard set of list, info, and delete operations for most resource types.
list list resources
info NAME show detailed resource information given resource name
delete NAME delete resource given resource name
For example, to list all monitoring checks:
sensuctl check list
To list checks from all namespaces:
sensuctl check list --all-namespaces
To write all checks to my-resources.json
in wrapped-json
format:
sensuctl check list --format wrapped-json > my-resources.json
To see the definition for a check named check-cpu
in wrapped-json
format:
sensuctl check info check-cpu --format wrapped-json
In addition to the standard operations, commands may support subcommands or flags that allow you to take special action based on the resource type; the following sections call out those resource-specific operations.
For a list of subcommands specific to a resource, run sensuctl TYPE --help
.
sensuctl check
In addition to the standard subcommands, sensuctl provides a command to execute a check on demand, given the check name.
sensuctl check execute NAME
For example, the following command executes the check-cpu
check with an attached message:
sensuctl check execute check-cpu --reason "giving a sensuctl demo"
You can also use the --subscriptions
flag to override the subscriptions in the check definition:
sensuctl check execute check-cpu --subscriptions demo,webserver
sensuctl cluster
The sensuctl cluster
command lets you manage a Sensu cluster using the following subcommands.
health get sensu health status
member-add add cluster member to an existing cluster, with comma-separated peer addresses
member-list list cluster members
member-remove remove cluster member by ID
member-update update cluster member by ID with comma-separated peer addresses
To view cluster members:
sensuctl cluster member-list
To see the health of your Sensu cluster:
sensuctl cluster health
sensuctl event
In addition to the standard subcommands, sensuctl provides a command to resolve an event.
sensuctl event resolve ENTITY CHECK
For example, the following command manually resolves an event created by the entity webserver1
and the check check-http
:
sensuctl event resolve webserver1 check-http
sensuctl namespace
See the RBAC reference for information about using access control with namespaces.
sensuctl user
See the RBAC reference for information about local user management with sensuctl.
Filtering
LICENSED TIER: Unlock sensuctl filtering with a Sensu license. To activate your license, see the getting started guide.
Sensuctl supports filtering for all list
commands using the --label-selector
and --field-selector
flags.
For information about the operators and fields available to use in filters, see the API docs.
Filtering syntax quick reference
operator | description | example |
---|---|---|
== |
Equality | check.publish == true |
!= |
Inequality | check.namespace != "default" |
in |
Included in | linux in check.subscriptions |
notin |
Not included in | slack notin check.handlers |
&& |
Logical AND | check.publish == true && slack in check.handlers |
Filtering with labels
You can use the --label-selector
flag to filter using custom labels.
For example, the following command returns entities with the proxy_type
label set to switch
.
sensuctl entity list --label-selector 'proxy_type == switch'
Filtering with resource attributes
You can use the --field-selector
flag to filter using selected resource attributes.
To see the resource attributes available to use in filter statements, see the API docs.
For example, the following command returns entities with the switches
subscription.
sensuctl entity list --field-selector 'switches in entity.subscriptions'
You can also combine the --label-selector
and --field-selector
flags.
For example, the following command returns checks with the region
label set to us-west-1
and the slack
handler.
sensuctl check list --label-selector 'region == "us-west-1"' --field-selector 'slack in check.handlers'
Time formats
Sensuctl supports multiple time formats depending on the manipulated resource. Supported canonical time zone IDs are defined in the tz database.
WARNING: Canonical zone IDs (i.e. America/Vancouver
) are not supported on
Windows.
Dates with time
Full dates with time are used to specify an exact point in time, which can be used with silences, for example. The following formats are supported:
- RFC3339 with numeric zone offset:
2018-05-10T07:04:00-08:00
or2018-05-10T15:04:00Z
- RFC3339 with space delimiters and numeric zone offset:
2018-05-10 07:04:00 -08:00
- Sensu alpha legacy format with canonical zone ID:
May 10 2018 7:04AM America/Vancouver
Shell auto-completion
Installation (Bash Shell)
Make sure bash completion is installed. If you use a current Linux in a non-minimal installation, bash completion should be available. On macOS, install with:
brew install bash-completion
Then add the following to your ~/.bash_profile
:
if [ -f $(brew --prefix)/etc/bash_completion ]; then
. $(brew --prefix)/etc/bash_completion
fi
Once bash-completion is available, add the following to your ~/.bash_profile
:
source <(sensuctl completion bash)
You can now source your ~/.bash_profile
or launch a new terminal to utilize completion.
source ~/.bash_profile
Installation (ZSH)
Add the following to your ~/.zshrc
:
source <(sensuctl completion zsh)
You can now source your ~/.zshrc
or launch a new terminal to utilize completion.
source ~/.zshrc
Usage
sensuctl
Tab
check configure event user
asset completion entity handler
sensuctl check
Tab
create delete import list
Configuration files
During configuration, sensuctl creates configuration files that contain information for connecting to your Sensu Go deployment. You can find them at $HOME/.config/sensu/sensuctl/profile
and $HOME/.config/sensu/sensuctl/cluster
. For example:
cat .config/sensu/sensuctl/profile
{
"format": "tabular",
"namespace": "demo"
}
cat .config/sensu/sensuctl/cluster
{
"api-url": "http://localhost:8080",
"trusted-ca-file": "",
"insecure-skip-tls-verify": false,
"access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"expires_at": 1550082282,
"refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
These are useful if you want to know what cluster you’re connecting to, or what namespace you’re currently configured to use.