d447b54ad3
Remove outdated usage of "Consul Connect" instead of Consul service mesh. The connect subsystem in Consul provides Consul's service mesh capabilities. However, the term "Consul Connect" should not be used as an alternative to the name "Consul service mesh".
274 lines
8.5 KiB
Plaintext
274 lines
8.5 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: Commands
|
|
description: >-
|
|
Consul is controlled via a very easy to use command-line interface (CLI).
|
|
Consul is only a single command-line application: `consul`. This application
|
|
then takes a subcommand such as agent or members. The complete list of
|
|
subcommands is in the navigation to the left.
|
|
---
|
|
|
|
# Consul Commands (CLI)
|
|
|
|
Consul is controlled via a very easy to use command-line interface (CLI).
|
|
Consul is only a single command-line application: `consul`. This application
|
|
then takes a subcommand such as "agent" or "members". The complete list of
|
|
subcommands is in the navigation to the left.
|
|
|
|
The `consul` CLI is a well-behaved command line application. In erroneous
|
|
cases, a non-zero exit status will be returned. It also responds to `-h` and `--help`
|
|
as you'd most likely expect. And some commands that expect input accept
|
|
"-" as a parameter to tell Consul to read the input from stdin.
|
|
|
|
To view a list of the available commands at any time, just run `consul` with
|
|
no arguments:
|
|
|
|
```shell-session
|
|
$ consul
|
|
Usage: consul [--version] [--help] <command> [<args>]
|
|
|
|
Available commands are:
|
|
acl Interact with Consul's ACLs
|
|
agent Runs a Consul agent
|
|
catalog Interact with the catalog
|
|
connect Interact with service mesh functionality
|
|
debug Records a debugging archive for operators
|
|
event Fire a new event
|
|
exec Executes a command on Consul nodes
|
|
force-leave Forces a member of the cluster to enter the "left" state
|
|
info Provides debugging information for operators.
|
|
intention Interact with service mesh intentions
|
|
join Tell Consul agent to join cluster
|
|
keygen Generates a new encryption key
|
|
keyring Manages gossip layer encryption keys
|
|
kv Interact with the key-value store
|
|
leave Gracefully leaves the Consul cluster and shuts down
|
|
lock Execute a command holding a lock
|
|
login Login to Consul using an auth method
|
|
logout Destroy a Consul token created with login
|
|
maint Controls node or service maintenance mode
|
|
members Lists the members of a Consul cluster
|
|
monitor Stream logs from a Consul agent
|
|
operator Provides cluster-level tools for Consul operators
|
|
peering Create and manage peering connections between Consul clusters
|
|
reload Triggers the agent to reload configuration files
|
|
rtt Estimates network round trip time between nodes
|
|
services Interact with services
|
|
snapshot Saves, restores and inspects snapshots of Consul server state
|
|
tls Builtin helpers for creating CAs and certificates
|
|
troubleshoot Provides tools to troubleshoot Consul's service mesh configuration
|
|
validate Validate config files/directories
|
|
version Prints the Consul version
|
|
watch Watch for changes in Consul
|
|
```
|
|
|
|
To get help for any specific command, pass the `-h` flag to the relevant
|
|
subcommand. For example, to see help about the `join` subcommand:
|
|
|
|
```shell-session
|
|
$ consul join --help
|
|
Usage: consul join [options] address ...
|
|
|
|
Tells a running Consul agent (with "consul agent") to join the cluster
|
|
by specifying at least one existing member.
|
|
|
|
HTTP API Options
|
|
|
|
-http-addr=<address>
|
|
The `address` and port of the Consul HTTP agent. The value can be
|
|
an IP address or DNS address, but it must also include the port.
|
|
This can also be specified via the CONSUL_HTTP_ADDR environment
|
|
variable. The default value is http://127.0.0.1:8500. The scheme
|
|
can also be set to HTTPS by setting the environment variable
|
|
CONSUL_HTTP_SSL=true.
|
|
|
|
-token=<value>
|
|
ACL token to use in the request. This can also be specified via the
|
|
CONSUL_HTTP_TOKEN environment variable. If unspecified, the query
|
|
will default to the token of the Consul agent at the HTTP address.
|
|
|
|
Command Options
|
|
|
|
-wan
|
|
Joins a server to another server in the WAN pool.
|
|
```
|
|
|
|
## Authentication
|
|
|
|
When the [ACL system is enabled](/consul/docs/agent/config/config-files#acl) the Consul CLI will
|
|
require an [ACL token](/consul/docs/security/acl#tokens) to perform API requests.
|
|
|
|
The ACL token can be provided directly on the command line using the `-token` command line flag,
|
|
from a file using the `-token-file` command line flag, or from the
|
|
[`CONSUL_HTTP_TOKEN`](#consul_http_token_file) environment variable.
|
|
|
|
## Autocompletion
|
|
|
|
The `consul` command features opt-in subcommand autocompletion that you can
|
|
enable for your shell with `consul -autocomplete-install`. After doing so,
|
|
you can invoke a new shell and use the feature.
|
|
|
|
For example, assume a tab is typed at the end of each prompt line:
|
|
|
|
```shell-session
|
|
$ consul e
|
|
event exec
|
|
|
|
$ consul r
|
|
reload rtt
|
|
|
|
$ consul operator raft
|
|
list-peers remove-peer
|
|
```
|
|
|
|
## Arguments with URL-Invalid Characters
|
|
|
|
The CLI automatically URL-encodes arguments, which are then
|
|
[URL-decoded by the underlying HTTP API endpoints](/consul/api-docs/api-structure#url-encoded-resource-names).
|
|
To avoid double-encoding arguments, do not URL-encode arguments passed to the CLI.
|
|
|
|
## Environment Variables
|
|
|
|
In addition to CLI flags, Consul reads environment variables for behavior
|
|
defaults. CLI flags always take precedence over environment variables, but it
|
|
is often helpful to use environment variables to configure the Consul agent,
|
|
particularly with configuration management and init systems.
|
|
|
|
These environment variables and their purpose are described below:
|
|
|
|
### `CONSUL_HTTP_ADDR`
|
|
|
|
This is the HTTP API address to the _local_ Consul agent
|
|
(not the remote server) specified as a URI with optional scheme:
|
|
|
|
```
|
|
CONSUL_HTTP_ADDR=127.0.0.1:8500
|
|
```
|
|
|
|
or as a Unix socket path:
|
|
|
|
```
|
|
CONSUL_HTTP_ADDR=unix:///var/run/consul_http.sock
|
|
```
|
|
|
|
If the `https://` scheme is used, `CONSUL_HTTP_SSL` is implied to be true.
|
|
|
|
### `CONSUL_HTTP_TOKEN`
|
|
|
|
This is the API access token required when access control lists (ACLs)
|
|
are enabled, for example:
|
|
|
|
```
|
|
CONSUL_HTTP_TOKEN=aba7cbe5-879b-999a-07cc-2efd9ac0ffe
|
|
```
|
|
|
|
### `CONSUL_HTTP_TOKEN_FILE`
|
|
|
|
This is a path to a file containing the API access token required when access
|
|
control lists (ACLs) are enabled, for example:
|
|
|
|
```
|
|
CONSUL_HTTP_TOKEN_FILE=/path/to/consul.token
|
|
```
|
|
|
|
### `CONSUL_HTTP_AUTH`
|
|
|
|
This specifies HTTP Basic access credentials as a username:password pair:
|
|
|
|
```
|
|
CONSUL_HTTP_AUTH=operations:JPIMCmhDHzTukgO6
|
|
```
|
|
|
|
### `CONSUL_HTTP_SSL`
|
|
|
|
This is a boolean value (default is false) that enables the HTTPS URI
|
|
scheme and SSL connections to the HTTP API:
|
|
|
|
```
|
|
CONSUL_HTTP_SSL=true
|
|
```
|
|
|
|
### `CONSUL_HTTP_SSL_VERIFY`
|
|
|
|
This is a boolean value (default true) to specify SSL certificate verification;
|
|
setting this value to `false` is not recommended for production use. Example for
|
|
development purposes:
|
|
|
|
```
|
|
CONSUL_HTTP_SSL_VERIFY=false
|
|
```
|
|
|
|
### `CONSUL_CACERT`
|
|
|
|
Path to a CA file to use for TLS when communicating with Consul.
|
|
|
|
```
|
|
CONSUL_CACERT=ca.crt
|
|
```
|
|
|
|
### `CONSUL_CAPATH`
|
|
|
|
Path to a directory of CA certificates to use for TLS when communicating with Consul.
|
|
|
|
```
|
|
CONSUL_CAPATH=ca_certs/
|
|
```
|
|
|
|
### `CONSUL_CLIENT_CERT`
|
|
|
|
Path to a client cert file to use for TLS when `verify_incoming` is enabled.
|
|
|
|
```
|
|
CONSUL_CLIENT_CERT=client.crt
|
|
```
|
|
|
|
### `CONSUL_CLIENT_KEY`
|
|
|
|
Path to a client key file to use for TLS when `verify_incoming` is enabled.
|
|
|
|
```
|
|
CONSUL_CLIENT_KEY=client.key
|
|
```
|
|
|
|
### `CONSUL_TLS_SERVER_NAME`
|
|
|
|
The server name to use as the SNI host when connecting via TLS.
|
|
|
|
```
|
|
CONSUL_TLS_SERVER_NAME=consulserver.domain
|
|
```
|
|
|
|
### `CONSUL_GRPC_ADDR`
|
|
|
|
Like [`CONSUL_HTTP_ADDR`](#consul_http_addr) but configures the address the
|
|
local agent is listening for gRPC requests. Currently gRPC is only used for
|
|
integrating [Envoy proxy](/consul/docs/connect/proxies/envoy) and must be [enabled
|
|
explicitly](/consul/docs/agent/config/config-files#grpc_port) in agent configuration.
|
|
|
|
```
|
|
CONSUL_GRPC_ADDR=127.0.0.1:8502
|
|
```
|
|
|
|
or as a Unix socket path:
|
|
|
|
```
|
|
CONSUL_GRPC_ADDR=unix://var/run/consul_grpc.sock
|
|
```
|
|
|
|
If the agent is [configured with TLS
|
|
certificates](/consul/docs/security/encryption#rpc-encryption-with-tls), then the
|
|
gRPC listener will require TLS and present the same certificate as the https
|
|
listener. As with `CONSUL_HTTP_ADDR`, if TLS is enabled either the `https://`
|
|
scheme should be used, or `CONSUL_HTTP_SSL` set.
|
|
|
|
### `CONSUL_NAMESPACE`
|
|
|
|
**Enterprise only**
|
|
If you're using Consul Enterprise namespaces you can set this for the CLI to
|
|
explicitly use a single namespace. This is common across all Hashicorp
|
|
products that support Enterprise namespaces.
|
|
|
|
```
|
|
CONSUL_NAMESPACE=default
|
|
```
|