How Do We Set All of this Up

Disaster Recovery (DR) replication in HashiCorp Vault isn’t enabled by default. Follow these four steps to set up a DR replica set:

Enable DR replication on the primary cluster
Generate a wrapped secondary token
(Optional) Inspect the token’s contents
Activate DR replication on the secondary cluster

1. Enable DR Replication on the Primary Cluster

On your primary Vault cluster, enable DR replication. Vault will automatically:

Provision an internal root CA
Issue a root certificate and a client certificate for mutual TLS
Prepare to generate secondary tokens

Note

These internal certificates are separate from the TLS certificates you configure for your Vault listener.

The image is a slide about activating DR replication in Vault, detailing the need to enable replication on each cluster, the creation of a root certificate, and the use of mutual TLS connections. It also mentions potential issues with load balancers terminating TLS.

Warning

If your Vault nodes sit behind a load balancer that terminates TLS, ensure mTLS traffic on port 8201 is passed through end-to-end. Either disable TLS termination or configure a TCP passthrough.

# Example: Enable DR replication on primary
vault write -f sys/replication/dr/primary/enable

2. Generate the Wrapped Secondary Token

Next, create a DR secondary token on the primary. This wrapped, single-use token contains:

The primary’s unwrapping address
The CA certificate for mTLS
A client certificate and key

vault write -wrap-ttl=5m -f sys/replication/dr/secondary-token

The image is a slide about "Secondary Token" requirements for cluster replication, detailing its sensitivity, single-use nature, and included information. It also features a certification badge and a cartoon character at the bottom.

3. (Optional) Inspect the Wrapped Token

Typically you hand this wrapped token directly to the secondary without unwrapping. For demonstration, here’s the JSON after unwrapping:

{
  "request_id": "98d4c7a5-0f00-4872-1cad-6ab8fa35694c",
  "data": {
    "ca_cert": "MIIC/fCCAd ...",
    "client_cert": "MIICjCCAjgAwIBAgIIK4vDI ...",
    "client_key": {
      "type": "p521",
      "d": "...",
      "x": "...",
      "y": "..."
    }
  },
  "cluster_id": "0d12790a-996e-152f-0113-3b016812d64d",
  "id": "secondary"
}

You can skip this step in production—Vault handles unwrapping automatically on the secondary.

4. Activate DR Replication on the Secondary Cluster

On your secondary cluster, supply the wrapped token when enabling DR replication. Vault will:

Call back to the primary’s API on port 8200 to unwrap the token
Extract mTLS credentials and primary address
Establish inter-cluster connections on port 8201
Begin streaming data from primary to secondary

vault write sys/replication/dr/secondary/enable \
    token="<wrapped_token_response>"

The image is a flowchart illustrating the process of using a secondary token, showing steps from token creation to secondary cluster readiness. It includes icons and text explaining each stage, with a certification badge in the top right corner.

Once complete, your secondary cluster is fully synchronized and ready for disaster recovery.

Watch Video

Watch video content

1. Enable DR Replication on the Primary Cluster

2. Generate the Wrapped Secondary Token

3. (Optional) Inspect the Wrapped Token

4. Activate DR Replication on the Secondary Cluster

Further Reading

Watch Video