Vault can be started using the
-recovery flag to bring it up in Recovery Mode.
The main purpose of recovery mode is to allow direct access to storage in case
Vault isn't starting up due to some newly discovered bug. This probably won't
be helpful without a Vault expert on hand to advise.
Differences between recovery mode and regular Vault operation:
- none of the usual subsystems run, e.g. expiration, clustering, RPCs from other nodes
- instead of a regular unseal request, unseal a node by generating a recovery token
- all requests are to
sys/rawand are authenticated using the recovery token
The usual way recovery mode is used is:
- seal or stop all nodes in the cluster
- if using Integrated Storage, run
vault statuson each node to find the highest-index ones (this will require they be running and sealed, as if unsealed a new leader might be elected and writes could happen, confusing the issue)
- restart the target node in recovery mode
- generate a recovery token on that node
- use the recovery token to perform sys/raw requests to repair the node
- if using Integrated Storage, reform the raft cluster as described below
If Integrated Storage is used in hybrid mode (i.e. for
recovery mode will not allow for changes to the Raft data but instead allow for
modification of the underlying physical data that is associated with Vault's
storage backend. This means that the notes regarding Integrated Storage in
this doc do not apply.
With Integrated Storage, not all nodes are equal. It's possible that some nodes are further behind - i.e. haven't applied as many Raft logs. It is important when choosing a node to use for recovery that it has the highest AppliedIndex found in the cluster.
Each node's AppliedIndex value can be obtained by running
vault status against
the node sealed nodes of the cluster after bringing it down.
Recovery tokens are issued in much the same way as root tokens are generated, only using a different endpoint, and the Vault node must be sealed first. Unlike root tokens, the recovery token is not persisted, so if Vault is restarted into recovery mode a new one must be generated.
Only a single recovery token can be generated. If lost, restart Vault and generate a new one.
Requests can be issued to
sys/raw in just the same way as in regular Vault
server mode. The only difference is that in recovery mode,
must contain a recovery token instead of a service or batch token.
Recovery mode Vault automatically resizes the cluster to size 1. This is necessary because the Raft protocol won't allow changes to be made without a quorum, and in recovery mode we wish to make changes using a single node.
This means that after having used recovery mode, part of the procedure for returning to active service must include re-forming the raft cluster. There are two ways to do so: either delete the vault data directory on the other nodes and re-join them to the recovered node, or use the Manual Recovery Using peers.json approach to get all nodes to agree on what nodes are part of the cluster.