Sensuctl CLI
Sensuctl is the command line tool for managing resources within Sensu. It works by calling Sensu’s underlying API to create, read, update, and delete events, entities, and resources.
Sensuctl is available for Linux, macOS, and Windows.
For Windows operating systems, sensuctl uses cmd.exe
for the execution environment.
For all other operating systems, sensuctl uses the Bourne shell (sh).
Read Install Sensu to install and configure sensuctl.
First-time setup and authentication
To log in to sensuctl and connect to the Sensu backend by following interactive prompts, run:
sensuctl configure
The sensuctl configure
command starts the prompts for interactive setup.
The first prompt is for the authentication method you wish to use: username/password or OIDC.
Sensuctl uses your username and password or OIDC credentials to obtain access and refresh tokens via the Sensu /auth API. The access and refresh tokens are HMAC-SHA256 JSON Web Tokens (JWTs) that Sensu issues to record the details of users’ authenticated Sensu sessions. The backend digitally signs these tokens, and the tokens can’t be changed without invalidating the signature.
Upon successful authentication, sensuctl stores the access and refresh tokens in a cluster
configuration file under the current user’s home directory.
For example, on Unix systems, sensuctl stores the tokens in $HOME/.config/sensu/sensuctl/cluster
.
The sensuctl configure
interactive prompts require you to select an authentication method and enter the Sensu backend URL, namespace, and preferred output format.
Username/password authentication
If you select username/password authentication, you will be prompted to enter your username and password Sensu access credentials.
Username/password authentication applies to the following authentication providers:
- Built-in basic authentication
- Lightweight Directory Access Protocol (LDAP) authentication (commercial feature)
- Active Directory (AD) authentication (commercial feature)
This example shows the sensuctl configure
interactive dialog for the username/password authentication method:
Authentication method: username/password
Sensu Backend API URL: http://127.0.0.1:8080
Namespace: default
Preferred output format: tabular
Username: <YOUR_USERNAME>
Password: <YOUR_PASSWORD>
OIDC authentication
This example shows the sensuctl configure
interactive dialog if you select the OIDC authentication method:
Authentication method: OIDC
Sensu Backend API URL: http://127.0.0.1:8080
Namespace: default
Preferred output format: tabular
Launching browser to complete the login via your OIDC provider at following URL:
http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/authorize?callback=http%3A%2F%2Flocalhost%3A8000%2Fcallback
You may also manually open this URL. Waiting for callback...
If you are using a desktop, a browser should open to allow you to authenticate and log in via your OIDC provider.
If a browser does not open, launch a browser and go to the OIDC URL listed at the end of the sensuctl configure
interactive dialog to complete authentication and log in via your OIDC provider.
NOTE: You can also use sensuctl login oidc
to log in to sensuctl with OIDC.
Use flags to configure sensuctl in non-interactive mode
Run sensuctl configure
non-interactively by adding the -n
(--non-interactive
) flag.
For example, the following command configures sensuctl with the same values used in the username/password interactive example:
sensuctl configure -n --url http://127.0.0.1:8080 --format tabular --username <YOUR_USERNAME> --password '<YOUR_PASSWORD>'
Run sensuctl configure -h
to view command-specific and global flags that you can use to set up sensuctl when you bypass interactive mode:
Initialize sensuctl configuration
Usage: sensuctl configure [flags]
Flags:
--format string preferred output format (default "tabular")
-h, --help help for configure
-n, --non-interactive do not administer interactive questionnaire
--oidc use an OIDC provider for authentication
--password string password
--port int port for local HTTP web server used for OAuth 2 callback during OIDC authentication (default 8000)
--url string the sensu backend url (default "http://localhost:8080")
--username string username
Global Flags:
--api-key string API key to use for authentication
--api-url string host URL of Sensu installation
--cache-dir string path to directory containing cache & temporary files (default "/Users/hillaryfraley/Library/Caches/sensu/sensuctl")
--config-dir string path to directory containing configuration files (default "/Users/hillaryfraley/.config/sensu/sensuctl")
--insecure-skip-tls-verify skip TLS certificate verification (not recommended!)
--namespace string namespace in which we perform actions (default "default")
--timeout duration timeout when communicating with sensu backend (default 15s)
--trusted-ca-file string TLS CA certificate bundle in PEM format
Username, password, and namespace
The Sensu backend installation process creates an administrator username and password and a default
namespace.
NOTE: For a new installation, you can set administrator credentials with environment variables during initialization.
If you are using Docker and you do not include the environment variables to set administrator credentials, the backend will initialize with the default username (admin
) and password (P@ssw0rd!
).
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, read the role-based access control (RBAC) reference.
Change the admin user’s password
After you configure sensuctl and authenticate, you can change the admin user’s password. Run:
sensuctl user change-password --interactive
You must specify the user’s current password to use the sensuctl user change-password
command.
Reset a user password
To reset a user password without specifying the current password, run:
sensuctl user reset-password <USERNAME> --interactive
You must have admin permissions to use the sensuctl user reset-password
command.
Test a user password
To test the password for a user created with Sensu’s built-in basic authentication:
sensuctl user test-creds <USERNAME> --password 'password'
An empty response indicates valid credentials.
A request-unauthorized
response indicates invalid credentials.
NOTE: The sensuctl user test-creds
command tests passwords for users created with Sensu’s built-in basic authentication.
It does not test user credentials defined via an authentication provider like Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC).
For example, if you test LDAP credentials with the sensuctl user test-creds
command, the backend will log an error, even if the LDAP credentials are correct:
{"component":"apid.routers","error":"basic provider is disabled","level":"info","msg":"invalid username and/or password","time":"2020-02-07T20:42:14Z","user":"dev"}
Generate a password hash
You can use a password hash instead of a user’s password in the sensuctl commands to create and edit users.
The sensuctl user hash-password
command creates a bcrypt hash of the specified password.
To generate a password hash for a specified cleartext password, run:
sensuctl user hash-password <PASSWORD>
Sensu backend URL
The Sensu backend URL is the HTTP or HTTPS URL where sensuctl can connect to the Sensu backend server.
The default URL is http://127.0.0.1:8080
.
To connect to a Sensu cluster, connect sensuctl to any single backend in the cluster. For information about configuring the Sensu backend URL, read the backend reference.
Preferred output format
After you configure sensuctl, you can change the default output format for sensuctl responses. Sensuctl supports the following output formats:
Format | Description |
---|---|
tabular |
Output is organized in user-friendly columns. Tabular is the default output format. |
yaml |
Output is in YAML format. Resource definitions include the resource type and api_version as well as an outer-level spec “wrapping” for the resource attributes. |
wrapped-json |
Output is in JSON format. Resource definitions include the resource type and api_version as well as an outer-level spec “wrapping” for the resource attributes. |
json |
Output is in JSON format. Resource definitions do not include the resource type and api_version or an outer-level spec “wrapping”. |
Use sensuctl config set-format
to change the preferred output format.
Output format significance
To use sensuctl create to create a resource, you must provide the resource definition in yaml
or wrapped-json
format.
These formats include the resource type
, which sensuctl needs to determine what kind of resource to create.
The Sensu API uses json
output format for responses for APIs in the core
group.
For APIs that are not in the core
group, responses are in the wrapped-json
output format.
Sensu sends events to the backend in json
format, without the spec
attribute wrapper or type
and api_version
attributes.
Sensuctl configuration files
During configuration, sensuctl creates configuration files that contain information for connecting to your Sensu Go deployment.
You can find these files at $HOME/.config/sensu/sensuctl/profile
and $HOME/.config/sensu/sensuctl/cluster
.
Use the cat
command to view the contents of the configuration files.
For example, to view your sensuctl profile configuration, run:
cat .config/sensu/sensuctl/profile
The response should be similar to this example:
{
"format": "tabular",
"namespace": "default",
"username": "admin"
}
To view your sensuctl cluster configuration, run:
cat .config/sensu/sensuctl/cluster
The response should be similar to this example:
{
"api-url": "http://localhost:8080",
"trusted-ca-file": "",
"insecure-skip-tls-verify": false,
"access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"expires_at": 1550082282,
"refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
The sensuctl configuration files are useful if you want to know which cluster you’re connecting to or which namespace or username you’re currently configured to use.
Get help for sensuctl commands
Sensuctl supports a --help
flag for each command and subcommand.
The help response includes a usage template and lists of any available flags and further commands and subcommands.
To list global and command-specific flags for sensuctl in general, run:
sensuctl --help
To list available flags and subcommands for a sensuctl command like sensuctl check
or sensuctl create
, run:
sensuctl check --help
sensuctl create --help
To list available flags for a complete sensuctl command like sensuctl check delete
, run:
sensuctl check delete --help
Manage sensuctl
Use the sencutl config
command to view and modify the current sensuctl configuration.
To view flags and command options, run:
sensuctl config --help
The response lists the global flags and commands available to use with sensuctl config
:
Modify sensuctl configuration
Usage: sensuctl config COMMAND
Flags:
-h, --help help for config
Global Flags:
--api-key string API key to use for authentication
--api-url string host URL of Sensu installation
--cache-dir string path to directory containing cache & temporary files (default "/home/vagrant/.cache/sensu/sensuctl")
--config-dir string path to directory containing configuration files (default "/home/vagrant/.config/sensu/sensuctl")
--insecure-skip-tls-verify skip TLS certificate verification (not recommended!)
--namespace string namespace in which we perform actions (default "default")
--timeout duration timeout when communicating with sensu backend (default 15s)
--trusted-ca-file string TLS CA certificate bundle in PEM format
Commands:
set-format Set format for active profile
set-namespace Set namespace for active profile
set-timeout Set timeout for active profile in duration format (ex: 15s)
view Display active configuration
There are also commands for logging out of sensuctl and viewing the current sensuctl version.
View sensuctl config
To view the active configuration for sensuctl:
sensuctl config view
The sensuctl config view
response includes the Sensu backend URL, default namespace for the current user, default output format for the current user, and currently configured username:
=== Active Configuration
API URL: http://127.0.0.1:8080
Namespace: default
Format: tabular
Username: admin
Set preferred output format
Use the set-format
command to change the preferred output format for the current user.
For example, to change the default tabular format to YAML for all sensuctl commands, run:
sensuctl config set-format yaml
You can also use the --format
flag to set the output format for the response to a single sensuctl command.
For example, to keep the default format set at tabular, but retrieve a specific entity definition in YAML format, run:
sensuctl entity info <ENTITY_NAME> --format yaml
Set namespace
Use the set-namespace
command to change the default namespace for the current user.
For more information about configuring Sensu access control, read 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 to sensuctl:
sensuctl configure
View the sensuctl version number
To display the current version of sensuctl:
sensuctl version
Use global flags for sensuctl settings
Global flags modify settings specific to sensuctl, such as the Sensu backend URL and namespace.
--api-key string API key to use for authentication
--api-url string host URL of Sensu installation
--cache-dir string path to directory containing cache & temporary files (default "/home/vagrant/.cache/sensu/sensuctl")
--config-dir string path to directory containing configuration files (default "/home/vagrant/.config/sensu/sensuctl")
--insecure-skip-tls-verify skip TLS certificate verification (not recommended!)
--namespace string namespace in which we perform actions (default "default")
--timeout duration timeout when communicating with sensu backend (default 15s)
--trusted-ca-file string TLS CA certificate bundle in PEM format
You can use global flags with most sensuctl commands.
To set global flags permanently, edit .config/sensu/sensuctl/{cluster, profile}
.
Use shell autocompletion with sensuctl
Use shell autocompletion to create and run valid sensuctl commands. After you install and configure autocompletion, you can use the tab key to view and select from available options for each part of a sensuctl command directly from the command line.
Type sensuctl
and press tab to view the list of available variables:
api-key cluster-role configure edit handler logout role user
asset cluster-role-binding create entity help mutator role-binding version
auth command delete env hook namespace secret
check completion describe-type event license pipeline silenced
cluster config dump filter login prune tessen
Type your selected variable and press tab again to view the list of available variables to complete the command:
create delete info list
Type your selected variable to complete the command and press enter to run it.
Install and configure autocompletion for sensuctl
Follow the instructions in this section to install and configure Bash or zsh autocompletion for sensuctl.
Install and configure for Bash
To install and configure Bash autocompletion for sensuctl:
-
Install bash-completion.
NOTE: If you use a current version of Linux in a non-minimal installation, bash-completion may already be installed.
To install bash-completion on macOS, run:
brew install bash-completion
Open
~/.bash_profile
, add the following lines, and save:if [ -f $(brew --prefix)/etc/bash_completion ]; then . $(brew --prefix)/etc/bash_completion fi
-
Open
~/.bash_profile
, add the following line, and save:source <(sensuctl completion bash)
-
Run the following command to source your
~/.bash_profile
file so that its resources are available:source ~/.bash_profile
Shell autocompletion should now be available for sensuctl.
Install and configure for zsh
To install and configure zsh autocompletion for sensuctl:
-
Open
~/.zshrc
, add the following line, and save:source <(sensuctl completion zsh)
-
Run the following command to source your
~/.zshrc
file so that its resources are available:source ~/.zshrc