github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/source/docs/commands/keyring.html.markdown

2.4 KiB
Raw Blame History

layout page_title sidebar_current
docs Commands: Keyring 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. 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.

Because Consul utilizes multiple gossip pools, this command will only operate against a server node for most operations. By default, all operations carried out by this command are run against the LAN gossip pool in the datacenter of the agent.

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 ensure that a key is not installed using the -list and -remove options.

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.

    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.

  • -wan - Operate on the WAN keyring instead of the LAN keyring (default)

  • -rpc-addr - RPC address of the Consul agent.