mirror of https://github.com/hashicorp/consul
59 lines
2.2 KiB
Markdown
59 lines
2.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, revoking old encryption keys,
|
||
|
|
and changing the key 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. The only operation which may be used
|
||
|
|
on client machines is the `-init` argument for initial key configuration.
|
||
|
|
|
||
|
|
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 keys command 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 `-update`.
|
||
|
|
|
||
|
|
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).
|
||
|
|
|
||
|
|
This operation can be run on both client and server nodes and requires no
|
||
|
|
network connectivity.
|
||
|
|
|
||
|
|
* `-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.
|
||
|
|
|
||
|
|
* `-rpc-addr` - RPC address of the Consul agent.
|