github.com/outbrain/consul@v1.4.5/website/source/docs/commands/keyring.html.markdown.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: Keyring"
     4  sidebar_current: "docs-commands-keyring"
     5  ---
     6  
     7  # Consul Keyring
     8  
     9  Command: `consul keyring`
    10  
    11  The `keyring` command is used to examine and modify the encryption keys used in
    12  Consul's [Gossip Pools](/docs/internals/gossip.html). It is capable of
    13  distributing new encryption keys to the cluster, retiring old encryption keys,
    14  and changing the keys used by the cluster to encrypt messages.
    15  
    16  Consul allows multiple encryption keys to be in use simultaneously. This is
    17  intended to provide a transition state while the cluster converges. It is the
    18  responsibility of the operator to ensure that only the required encryption keys
    19  are installed on the cluster. You can review the installed keys using the
    20  `-list` argument, and remove unneeded keys with `-remove`.
    21  
    22  All operations performed by this command can only be run against server nodes,
    23  and affect both the LAN and WAN keyrings in lock-step.
    24  
    25  All variations of the `keyring` command return 0 if all nodes reply and there
    26  are no errors. If any node fails to reply or reports failure, the exit code
    27  will be 1.
    28  
    29  ## Usage
    30  
    31  Usage: `consul keyring [options]`
    32  
    33  Only one actionable argument may be specified per run, including `-list`,
    34  `-install`, `-remove`, and `-use`.
    35  
    36  #### API Options
    37  
    38  <%= partial "docs/commands/http_api_options_client" %>
    39  
    40  #### Command Options
    41  
    42  * `-list` - List all keys currently in use within the cluster.
    43  
    44  * `-install` - Install a new encryption key. This will broadcast the new key to
    45    all members in the cluster.
    46  
    47  * `-use` - Change the primary encryption key, which is used to encrypt messages.
    48    The key must already be installed before this operation can succeed.
    49  
    50  * `-remove` - Remove the given key from the cluster. This operation may only be
    51    performed on keys which are not currently the primary key.
    52  
    53  * `-relay-factor` - Added in Consul 0.7.4, setting this to a non-zero value will
    54    cause nodes to relay their response to the operation through this many
    55    randomly-chosen other nodes in the cluster. The maximum allowed value is 5.
    56  
    57  ## Output
    58  
    59  The output of the `consul keyring -list` command consolidates information from
    60  all nodes and all datacenters to provide a simple and easy to understand view of
    61  the cluster. The following is some example output from a cluster with two
    62  datacenters, each which consist of one server and one client:
    63  
    64  ```
    65  ==> Gathering installed encryption keys...
    66  ==> Done!
    67  
    68  WAN:
    69    a1i101sMY8rxB+0eAKD/gw== [2/2]
    70  
    71  dc2 (LAN):
    72    a1i101sMY8rxB+0eAKD/gw== [2/2]
    73  
    74  dc1 (LAN):
    75    a1i101sMY8rxB+0eAKD/gw== [2/2]
    76  
    77  dc1 (LAN) [alpha]:
    78    a1i101sMY8rxB+0eAKD/gw== [2/2]
    79  ```
    80  
    81  As you can see, the output above is divided first by gossip pool, including any network
    82  segments, and then by encryption key. The indicator to the right of each key displays
    83  the number of nodes the key is installed on over the total number of nodes in the pool.
    84  
    85  ## Errors
    86  
    87  If any errors are encountered while performing a keyring operation, no key
    88  information is displayed, but instead only error information. The error
    89  information is arranged in a similar fashion, organized first by datacenter,
    90  followed by a simple list of nodes which had errors, and the actual text of the
    91  error. Below is sample output from the same cluster as above, if we try to do
    92  something that causes an error; in this case, trying to remove the primary key:
    93  
    94  ```
    95  ==> Removing gossip encryption key...
    96  
    97  dc1 (LAN) error: 2/2 nodes reported failure
    98    server1: Removing the primary key is not allowed
    99    client1: Removing the primary key is not allowed
   100  
   101  WAN error: 2/2 nodes reported failure
   102    server1.dc1: Removing the primary key is not allowed
   103    server2.dc2: Removing the primary key is not allowed
   104  
   105  dc2 (LAN) error: 2/2 nodes reported failure
   106    server2: Removing the primary key is not allowed
   107    client2: Removing the primary key is not allowed
   108  ```
   109  
   110  As you can see, each node with a failure reported what went wrong.