117 lines
4.2 KiB
Markdown
117 lines
4.2 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Commands: Keyring"
|
|
sidebar_current: "docs-commands-keyring"
|
|
---
|
|
|
|
# Consul Keyring
|
|
|
|
Command: `consul keyring`
|
|
|
|
The `keyring` command is used to examine and modify the encryption keys used in
|
|
Consul's [Gossip Pools](/docs/internals/gossip.html). 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`.
|
|
|
|
With the exception of the `-init` argument, all operations performed by this
|
|
command can only be run against server nodes, and affect both the LAN and
|
|
WAN keyrings in lock-step.
|
|
|
|
All variations of the `keyring` command, unless otherwise specified below, will
|
|
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.
|
|
|
|
## Usage
|
|
|
|
Usage: `consul keyring [options]`
|
|
|
|
Only one actionable argument may be specified per run, including `-init`,
|
|
`-list`, `-install`, `-remove`, and `-use`.
|
|
|
|
The list of available flags are:
|
|
|
|
* `-init` - Creates the keyring file(s). This is useful to configure initial
|
|
encryption keyrings, which can later be mutated using the other arguments in
|
|
this command. This argument accepts an ASCII key, which can be generated using
|
|
the [keygen command](/docs/commands/keygen.html). Requires the `-data-dir`
|
|
argument.
|
|
|
|
This operation can be run on both client and server nodes and requires no
|
|
network connectivity.
|
|
|
|
Returns 0 if the key is successfully configured, or 1 if there were any
|
|
problems.
|
|
|
|
* `-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.
|
|
|
|
* `-list` - List all keys currently in use within the cluster.
|
|
|
|
* `-data-dir` - The path to Consul's data directory. Used with `-init` only.
|
|
|
|
* `-rpc-addr` - RPC address of the Consul agent.
|
|
|
|
## 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]
|
|
```
|
|
|
|
As you can see, the output above is divided first by gossip pool, 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.
|