HashiConf 2024 Now streaming live from Boston! Attend for free
Consul
Consul Home

You are viewing documentation for version v1.11.x. View latest version.

Consul Keyring

Command: consul keyring

Corresponding HTTP API Endpoints: [VARIES] /v1/operator/keyring

The keyring command is used to examine and modify the encryption keys used in Consul's Gossip Pools. It is capable of distributing new encryption keys to the cluster, retiring old encryption keys, and changing the keys used by the cluster to encrypt messages.

Consul allows multiple encryption keys to be in use simultaneously. This is intended to provide a transition state while the cluster converges. It is the responsibility of the operator to ensure that only the required encryption keys are installed on the cluster. You can review the installed keys using the -list argument, and remove unneeded keys with -remove.

All operations performed by this command can only be run against server nodes, and affect both the LAN and WAN keyrings in lock-step. The only exception to this is for the -list operation, you may set the -local-only flag to only query against local server nodes.

All variations of the keyring command return 0 if all nodes reply and there are no errors. If any node fails to reply or reports failure, the exit code will be 1.

The table below shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.

ACL Required1
keyring:read
keyring:write

1 The actual ACL required depends on the flags being used in the command.

Usage

Usage: consul keyring [options]

Only one actionable argument may be specified per run, including -list, -install, -remove, and -use.

API Options

  • -ca-file=<value> - Path to a CA file to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CACERT environment variable.

  • -ca-path=<value> - Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CAPATH environment variable.

  • -client-cert=<value> - Path to a client cert file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_CERT environment variable.

  • -client-key=<value> - Path to a client key file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_KEY environment variable.

  • -http-addr=<addr> - Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via the CONSUL_HTTP_ADDR environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using unix:///path/to/socket if the agent is configured to listen that way.

  • -tls-server-name=<value> - The server name to use as the SNI host when connecting via TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME environment variable.

  • -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.

  • -token-file=<value> - File containing the ACL token to use in the request instead of one specified via the -token argument or CONSUL_HTTP_TOKEN environment variable. This can also be specified via the CONSUL_HTTP_TOKEN_FILE environment variable.

Command Options

  • -list - List all keys currently in use within the cluster.

  • -list-primary - List all primary keys currently in use within the cluster.

  • -install - Install a new encryption key. This will broadcast the new key to all members in the cluster.

  • -use - Change the primary encryption key, which is used to encrypt messages. The key must already be installed before this operation can succeed.

  • -remove - Remove the given key from the cluster. This operation may only be performed on keys which are not currently the primary key.

  • -relay-factor - Added in Consul 0.7.4, setting this to a non-zero value will cause nodes to relay their response to the operation through this many randomly-chosen other nodes in the cluster. The maximum allowed value is 5.

  • -local-only - Setting this to true will force a keyring list query to only hit local servers (no WAN traffic). Setting local-only is only allowed for list queries.

Output

The output of the consul keyring -list command consolidates information from all nodes and all datacenters to provide a simple and easy to understand view of the cluster. The following is some example output from a cluster with two datacenters, each which consist of one server and one client:

==> Gathering installed encryption keys...
==> Done!

WAN:
  a1i101sMY8rxB+0eAKD/gw== [2/2]

dc2 (LAN):
  a1i101sMY8rxB+0eAKD/gw== [2/2]

dc1 (LAN):
  a1i101sMY8rxB+0eAKD/gw== [2/2]

dc1 (LAN) [alpha]:
  a1i101sMY8rxB+0eAKD/gw== [2/2]

As you can see, the output above is divided first by gossip pool, including any network segments, and then by encryption key. The indicator to the right of each key displays the number of nodes the key is installed on over the total number of nodes in the pool.

Errors

If any errors are encountered while performing a keyring operation, no key information is displayed, but instead only error information. The error information is arranged in a similar fashion, organized first by datacenter, followed by a simple list of nodes which had errors, and the actual text of the error. Below is sample output from the same cluster as above, if we try to do something that causes an error; in this case, trying to remove the primary key:

==> Removing gossip encryption key...

dc1 (LAN) error: 2/2 nodes reported failure
  server1: Removing the primary key is not allowed
  client1: Removing the primary key is not allowed

WAN error: 2/2 nodes reported failure
  server1.dc1: Removing the primary key is not allowed
  server2.dc2: Removing the primary key is not allowed

dc2 (LAN) error: 2/2 nodes reported failure
  server2: Removing the primary key is not allowed
  client2: Removing the primary key is not allowed

As you can see, each node with a failure reported what went wrong.