Sensuctl CLI
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 Install Sensu to install and configure sensuctl.
First-time setup and authentication
To set up sensuctl, run sensuctl configure
to log in to sensuctl and connect to the Sensu backend:
sensuctl configure
This starts the prompts for interactive sensuctl setup. When prompted, choose 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 authentication 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
.
Username/password authentication
The sensuctl configure
interactive prompts require you to select the username/password authentication method and enter the Sensu backend URL, namespace, and preferred output format.
Then 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 username/password authentication method:
? Authentication method: username/password
? Sensu Backend URL: http://127.0.0.1:8080
? Namespace: default
? Preferred output format: tabular
? Username: YOUR_USERNAME
? Password: YOUR_PASSWORD
OIDC authentication
The sensuctl configure
interactive prompts require you to select the OIDC authentication method and enter the Sensu backend URL, namespace, and preferred output format.
Then, if you are using a desktop, a browser will open to allow you to authenticate and log in via your OIDC provider.
This example shows the OIDC authentication method:
? Authentication method: OIDC
? Sensu Backend 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 a browser does not open, launch a browser to complete the login via your OIDC provider at the Sensu backend URL you entered in your sensuctl configuration.
NOTE: You can also use sensuctl login oidc
to log in to sensuctl with OIDC.
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, see the backend reference.
sensuctl configure flags
Run sensuctl configure -h
to view command-specific flags you can use to set up sensuctl and bypass interactive mode.
The following table lists the command-specific flags.
Flag | Function and important notes |
---|---|
--format |
Preferred output format (default “tabular”). String. |
-h or --help |
Help for the configure command. |
-n or --non-interactive |
Do not administer interactive questionnaire. |
--oidc |
Use an OIDC provider for authentication (instead of username and password). |
--password string |
User password. String. |
--port |
Port for local HTTP webserver used for OAuth 2 callback during OIDC authentication (default 8000). Integer. |
--url |
The Sensu backend url (default “http://127.0.0.1:8080”). String. |
--username |
Username. String. |
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 these 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"
}
These 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.
Username, password, and namespace
During the Sensu backend installation process, you create 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, see the RBAC reference.
Change admin user’s password
After you have configured sensuctl and authenticated, 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 provider.
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 you know 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
To generate a password hash for a specified cleartext password, run:
sensuctl user hash-password PASSWORD
The sensuctl user hash-password
command creates a bcrypt hash of the specified password.
You can use this hash instead of the password when you use sensuctl to create and edit users.
Preferred output format
Sensuctl supports the following output formats:
tabular
: Output is organized in user-friendly columns (default).yaml
: Output is in YAML format. Resource definitions include an outer-levelspec
“wrapping” for resource attributes and list the resourcetype
andapi_version
.wrapped-json
: Output is in JSON format. Resource definitions include an outer-levelspec
“wrapping” for resource attributes and list the resourcetype
andapi_version
.json
: Output is in JSON format. Resource definitions do not include an outer-levelspec
“wrapping” or the resourcetype
andapi_version
.
After you are logged in, you can change the default output format with sensuctl config set-format
or set the output format per command with the --format
flag.
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.
Non-interactive mode
Run sensuctl configure
non-interactively by adding the -n
(--non-interactive
) flag.
sensuctl configure -n --url http://127.0.0.1:8080 --username YOUR_USERNAME --password YOUR_PASSWORD --format tabular
Get 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
Manage 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
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 output format
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
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 to sensuctl:
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
You can set these flags permanently by editing .config/sensu/sensuctl/{cluster, profile}
.
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 this to your ~/.bash_profile
:
if [ -f $(brew --prefix)/etc/bash_completion ]; then
. $(brew --prefix)/etc/bash_completion
fi
After bash-completion is installed, add this to your ~/.bash_profile
:
source <(sensuctl completion bash)
Now you can source your ~/.bash_profile
or launch a new terminal to use shell auto-completion.
source ~/.bash_profile
Installation (ZSH)
Add this to your ~/.zshrc
:
source <(sensuctl completion zsh)
Now you can source your ~/.zshrc
or launch a new terminal to use shell auto-completion.
source ~/.zshrc
Usage
sensuctl
Tab
check configure event user
asset completion entity handler
sensuctl check
Tab
create delete import list