2017-07-26 20:47:41 +00:00
|
|
|
|
---
|
2020-01-18 00:18:09 +00:00
|
|
|
|
layout: api
|
|
|
|
|
page_title: /sys/replication - HTTP API
|
|
|
|
|
description: >-
|
|
|
|
|
The '/sys/replication/dr' endpoint focuses on managing general operations in
|
|
|
|
|
Vault Enterprise Disaster Recovery replication
|
2017-07-26 20:47:41 +00:00
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# `/sys/replication/dr`
|
|
|
|
|
|
|
|
|
|
~> **Enterprise Only** – These endpoints require Vault Enterprise.
|
|
|
|
|
|
|
|
|
|
## Check DR Status
|
|
|
|
|
|
|
|
|
|
This endpoint prints information about the status of replication (mode,
|
|
|
|
|
sync progress, etc).
|
|
|
|
|
|
2022-03-01 22:41:47 +00:00
|
|
|
|
This is an unauthenticated endpoint.
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :--------------------------- |
|
|
|
|
|
| `GET` | `/sys/replication/dr/status` |
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-07-26 20:47:41 +00:00
|
|
|
|
$ curl \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/status
|
2017-07-26 20:47:41 +00:00
|
|
|
|
```
|
|
|
|
|
|
2018-06-13 23:43:39 +00:00
|
|
|
|
### Sample Response from Primary
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
The printed status of the replication environment. As an example, for a
|
|
|
|
|
primary, it will look something like:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"data": {
|
|
|
|
|
"cluster_id": "d4095d41-3aee-8791-c421-9bc7f88f7c3e",
|
2020-06-29 22:11:17 +00:00
|
|
|
|
"known_secondaries": ["3"],
|
2018-06-13 23:43:39 +00:00
|
|
|
|
"last_wal": 241,
|
|
|
|
|
"merkle_root": "56794a98e52598f35974024fba6691f047e772e9",
|
2020-06-29 22:11:17 +00:00
|
|
|
|
"mode": "primary",
|
|
|
|
|
"secondaries": [
|
|
|
|
|
{
|
|
|
|
|
"api_address": "https://127.0.0.1:49264",
|
|
|
|
|
"cluster_address": "https://127.0.0.1:49267",
|
|
|
|
|
"connection_status": "connected",
|
|
|
|
|
"last_heartbeat": "2020-06-10T15:40:47-07:00",
|
|
|
|
|
"node_id": "3"
|
|
|
|
|
}
|
|
|
|
|
]
|
2020-01-18 00:18:09 +00:00
|
|
|
|
}
|
2018-06-13 23:43:39 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
2020-01-18 00:18:09 +00:00
|
|
|
|
|
2018-06-13 23:43:39 +00:00
|
|
|
|
### Sample Response from Secondary
|
|
|
|
|
|
|
|
|
|
The printed status of the replication environment. As an example, for a
|
|
|
|
|
secondary, it will look something like:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"data": {
|
|
|
|
|
"cluster_id": "d4095d41-3aee-8791-c421-9bc7f88f7c3e",
|
2020-01-18 00:18:09 +00:00
|
|
|
|
"known_primary_cluster_addrs": ["https://127.0.0.1:8201"],
|
2018-06-13 23:43:39 +00:00
|
|
|
|
"last_remote_wal": 241,
|
|
|
|
|
"merkle_root": "56794a98e52598f35974024fba6691f047e772e9",
|
|
|
|
|
"mode": "secondary",
|
2020-06-29 22:11:17 +00:00
|
|
|
|
"primaries": [
|
|
|
|
|
{
|
|
|
|
|
"api_address": "https://127.0.0.1:49244",
|
|
|
|
|
"cluster_address": "https://127.0.0.1:8201",
|
|
|
|
|
"connection_status": "connected",
|
|
|
|
|
"last_heartbeat": "2020-06-10T15:40:46-07:00"
|
|
|
|
|
}
|
|
|
|
|
],
|
2018-06-13 23:43:39 +00:00
|
|
|
|
"primary_cluster_addr": "https://127.0.0.1:8201",
|
|
|
|
|
"secondary_id": "3",
|
|
|
|
|
"state": "stream-wals"
|
2020-01-18 00:18:09 +00:00
|
|
|
|
}
|
2017-07-26 20:47:41 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Enable DR Primary Replication
|
|
|
|
|
|
|
|
|
|
This endpoint enables DR replication in primary mode. This is used when DR replication
|
|
|
|
|
is currently disabled on the cluster (if the cluster is already a secondary, it
|
|
|
|
|
must be promoted).
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :----------------------------------- |
|
|
|
|
|
| `POST` | `/sys/replication/dr/primary/enable` |
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `primary_cluster_addr` `(string: "")` – Specifies the cluster address that the
|
|
|
|
|
primary gives to secondary nodes. Useful if the primary's cluster address is
|
|
|
|
|
not directly accessible and must be accessed via an alternate path/address,
|
|
|
|
|
such as through a TCP-based load balancer.
|
|
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-07-26 20:47:41 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
|
|
|
|
--data @payload.json \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/primary/enable
|
2017-07-26 20:47:41 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Demote DR Primary
|
|
|
|
|
|
|
|
|
|
This endpoint demotes a DR primary cluster to a secondary. This DR secondary cluster
|
|
|
|
|
will not attempt to connect to a primary (see the update-primary call), but will
|
|
|
|
|
maintain knowledge of its cluster ID and can be reconnected to the same
|
|
|
|
|
DR replication set without wiping local storage.
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :----------------------------------- |
|
|
|
|
|
| `POST` | `/sys/replication/dr/primary/demote` |
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-07-26 20:47:41 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/primary/demote
|
2017-07-26 20:47:41 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Disable DR Primary
|
|
|
|
|
|
|
|
|
|
This endpoint disables DR replication entirely on the cluster. Any secondaries will
|
|
|
|
|
no longer be able to connect. Caution: re-enabling this node as a primary or
|
|
|
|
|
secondary will change its cluster ID; in the secondary case this means a wipe of
|
|
|
|
|
the underlying storage when connected to a primary, and in the primary case,
|
|
|
|
|
secondaries connecting back to the cluster (even if they have connected before)
|
|
|
|
|
will require a wipe of the underlying storage.
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :------------------------------------ |
|
|
|
|
|
| `POST` | `/sys/replication/dr/primary/disable` |
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-07-26 20:47:41 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/primary/disable
|
2017-07-26 20:47:41 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Generate DR Secondary Token
|
|
|
|
|
|
|
|
|
|
This endpoint generates a DR secondary activation token for the
|
|
|
|
|
cluster with the given opaque identifier, which must be unique. This
|
|
|
|
|
identifier can later be used to revoke a DR secondary's access.
|
|
|
|
|
|
|
|
|
|
**This endpoint requires 'sudo' capability.**
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :-------------------------------------------- |
|
|
|
|
|
| `POST` | `/sys/replication/dr/primary/secondary-token` |
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `id` `(string: <required>)` – Specifies an opaque identifier, e.g. 'us-east'
|
|
|
|
|
|
|
|
|
|
- `ttl` `(string: "30m")` – Specifies the TTL for the secondary activation
|
|
|
|
|
token.
|
|
|
|
|
|
2019-11-06 21:37:46 +00:00
|
|
|
|
- `secondary_public_key` `(string: "")` – Specifies the secondary's generated
|
|
|
|
|
public key, if using encryption rather than response wrapping to protect the
|
|
|
|
|
secondary credentials. (Vault 1.3+)
|
|
|
|
|
|
2018-05-08 20:35:48 +00:00
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"id": "us-east-1"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2017-07-26 20:47:41 +00:00
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-07-26 20:47:41 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
2018-05-08 20:35:48 +00:00
|
|
|
|
--request POST \
|
|
|
|
|
--data @payload.json \
|
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/primary/secondary-token
|
2017-07-26 20:47:41 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"request_id": "",
|
|
|
|
|
"lease_id": "",
|
|
|
|
|
"lease_duration": 0,
|
|
|
|
|
"renewable": false,
|
|
|
|
|
"data": null,
|
|
|
|
|
"warnings": null,
|
|
|
|
|
"wrap_info": {
|
|
|
|
|
"token": "fb79b9d3-d94e-9eb6-4919-c559311133d6",
|
|
|
|
|
"ttl": 300,
|
|
|
|
|
"creation_time": "2016-09-28T14:41:00.56961496-04:00",
|
|
|
|
|
"wrapped_accessor": ""
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Revoke DR Secondary Token
|
|
|
|
|
|
|
|
|
|
This endpoint revokes a DR secondary's ability to connect to the DR primary cluster;
|
|
|
|
|
the DR secondary will immediately be disconnected and will not be allowed to
|
2022-08-12 16:10:40 +00:00
|
|
|
|
connect again unless given a new activation token. This command can be run from any node on the DR primary cluster.
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :--------------------------------------------- |
|
|
|
|
|
| `POST` | `/sys/replication/dr/primary/revoke-secondary` |
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `id` `(string: <required>)` – Specifies an opaque identifier, e.g. 'us-east'
|
|
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"id": "us-east"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-07-26 20:47:41 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
|
|
|
|
--data @payload.json \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/primary/revoke-secondary
|
2017-07-26 20:47:41 +00:00
|
|
|
|
```
|
|
|
|
|
|
2019-11-06 21:37:46 +00:00
|
|
|
|
## Fetch DR Secondary Public Key
|
|
|
|
|
|
|
|
|
|
(Vault 1.3+)
|
|
|
|
|
|
|
|
|
|
This endpoint allows fetching a public key that is used to encrypt the returned
|
|
|
|
|
credential information (instead of using a response wrapped token). This avoids
|
|
|
|
|
needing to make an API call to the primary during activation.
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :-------------------------------------------------- |
|
|
|
|
|
| `POST` | `/sys/replication/dr/secondary/generate-public-key` |
|
2019-11-06 21:37:46 +00:00
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2019-11-06 21:37:46 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-public-key
|
|
|
|
|
```
|
|
|
|
|
|
2017-07-26 20:47:41 +00:00
|
|
|
|
## Enable DR Secondary
|
|
|
|
|
|
|
|
|
|
This endpoint enables replication on a DR secondary using a DR secondary activation
|
|
|
|
|
token.
|
|
|
|
|
|
|
|
|
|
!> This will immediately clear all data in the secondary cluster!
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :------------------------------------- |
|
|
|
|
|
| `POST` | `/sys/replication/dr/secondary/enable` |
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
2019-11-06 21:37:46 +00:00
|
|
|
|
- `token` `(string: <required>)` – Specifies the secondary activation token
|
|
|
|
|
fetched from the primary.
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
- `primary_api_addr` `(string: "")` – Set this to the API address (normal Vault
|
|
|
|
|
address) to override the value embedded in the token. This can be useful if
|
|
|
|
|
the primary's redirect address is not accessible directly from this cluster
|
|
|
|
|
(e.g. through a load balancer).
|
|
|
|
|
|
|
|
|
|
- `ca_file` `(string: "")` – Specifies the path to a CA root file (PEM format)
|
|
|
|
|
that the secondary can use when unwrapping the token from the primary. If this
|
|
|
|
|
and ca_path are not given, defaults to system CA roots.
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
- `ca_path` `(string: "")` – Specifies the path to a CA root directory
|
2017-07-26 20:47:41 +00:00
|
|
|
|
containing PEM-format files that the secondary can use when unwrapping the
|
|
|
|
|
token from the primary. If this and ca_file are not given, defaults to system
|
|
|
|
|
CA roots.
|
|
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"token": "..."
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-07-26 20:47:41 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
|
|
|
|
--data @payload.json \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/enable
|
2017-07-26 20:47:41 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Promote DR Secondary
|
|
|
|
|
|
|
|
|
|
This endpoint promotes the DR secondary cluster to DR primary. For data safety and
|
|
|
|
|
security reasons, new secondary tokens will need to be issued to other
|
|
|
|
|
secondaries, and there should never be more than one primary at a time.
|
|
|
|
|
|
2017-09-28 11:54:40 +00:00
|
|
|
|
If the DR secondary's primary cluster is also in a performance replication set,
|
2017-07-26 20:47:41 +00:00
|
|
|
|
the DR secondary will be promoted into that replication set. Care should be
|
|
|
|
|
taken when promoting to ensure multiple performance primary clusters are not
|
2022-06-29 17:10:53 +00:00
|
|
|
|
active at the same time.
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
If the DR secondary's primary cluster is a performance secondary, the promoted
|
|
|
|
|
cluster will attempt to connect to the performance primary cluster using the
|
|
|
|
|
same secondary token.
|
|
|
|
|
|
2017-11-14 11:13:11 +00:00
|
|
|
|
This endpoint requires a DR Operation Token to be provided as means of
|
|
|
|
|
authorization. See the [DR Operation Token API
|
2018-11-15 17:23:05 +00:00
|
|
|
|
docs](#generate-disaster-recovery-operation-token) for more information.
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
2017-07-26 20:47:41 +00:00
|
|
|
|
!> Only one performance primary should be active at a given time. Multiple primaries may
|
|
|
|
|
result in data loss!
|
|
|
|
|
|
2021-12-20 18:46:57 +00:00
|
|
|
|
~> It is not safe to replicate from a newer version of Vault to an older version.
|
|
|
|
|
When upgrading replicated clusters, ensure that upstream clusters are always
|
|
|
|
|
on older versions of Vault than downstream clusters. See
|
|
|
|
|
[Upgrading Vault](/docs/upgrading#replication-installations) for an example.
|
|
|
|
|
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :-------------------------------------- |
|
|
|
|
|
| `POST` | `/sys/replication/dr/secondary/promote` |
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
2017-11-14 11:13:11 +00:00
|
|
|
|
- `dr_operation_token` `(string: <required>)` - DR operation token used to authorize this request.
|
2017-07-26 20:47:41 +00:00
|
|
|
|
- `primary_cluster_addr` `(string: "")` – Specifies the cluster address that the
|
|
|
|
|
primary gives to secondary nodes. Useful if the primary's cluster address is
|
|
|
|
|
not directly accessible and must be accessed via an alternate path/address
|
|
|
|
|
(e.g. through a load balancer).
|
2018-11-15 17:23:05 +00:00
|
|
|
|
- `force` `(bool: false)` - If true the cluster will be promoted even if it fails
|
|
|
|
|
certain safety checks. Caution: Forcing promotion could result in data loss if
|
2018-10-01 20:59:17 +00:00
|
|
|
|
data isn't fully replicated.
|
2017-07-26 20:47:41 +00:00
|
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
2018-05-03 01:35:51 +00:00
|
|
|
|
"dr_operation_token": "ijH8tphEHaBtgx+IvPfxDsSi2LV4j9k+Lad6eqT5cJw="
|
2017-07-26 20:47:41 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-07-26 20:47:41 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
|
|
|
|
--data @payload.json \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/promote
|
2017-07-26 20:47:41 +00:00
|
|
|
|
```
|
2017-08-07 14:59:46 +00:00
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"progress": 0,
|
|
|
|
|
"required": 1,
|
|
|
|
|
"complete": false,
|
|
|
|
|
"request_id": "ad8f9074-0e24-d30e-83cd-595c9652ff89",
|
|
|
|
|
"lease_id": "",
|
|
|
|
|
"renewable": false,
|
|
|
|
|
"lease_duration": 0,
|
|
|
|
|
"data": {
|
|
|
|
|
"complete": false,
|
|
|
|
|
"progress": 0,
|
|
|
|
|
"required": 1
|
|
|
|
|
},
|
|
|
|
|
"wrap_info": null,
|
|
|
|
|
"warnings": null,
|
|
|
|
|
"auth": null
|
|
|
|
|
}
|
|
|
|
|
```
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
2020-03-25 17:55:29 +00:00
|
|
|
|
## Disable DR Secondary
|
|
|
|
|
|
|
|
|
|
This endpoint disables DR replication entirely on the cluster. The cluster will no
|
|
|
|
|
longer be able to connect to the DR primary.
|
|
|
|
|
|
|
|
|
|
!> Re-enabling this node as a DR primary or secondary will change its cluster ID;
|
|
|
|
|
in the secondary case this means a wipe of the underlying storage when connected
|
|
|
|
|
to a primary, and in the primary case, secondaries connecting back to the
|
|
|
|
|
cluster (even if they have connected before) will require a wipe of the
|
|
|
|
|
underlying storage.
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :-------------------------------------- |
|
2020-03-25 17:55:29 +00:00
|
|
|
|
| `POST` | `/sys/replication/dr/secondary/disable` |
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2020-03-25 17:55:29 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/disable
|
|
|
|
|
```
|
|
|
|
|
|
2017-11-14 11:13:11 +00:00
|
|
|
|
## Update DR Secondary's Primary
|
|
|
|
|
|
|
|
|
|
This endpoint changes a DR secondary cluster's assigned primary cluster using a
|
|
|
|
|
secondary activation token. This does not wipe all data in the cluster.
|
|
|
|
|
|
|
|
|
|
This endpoint requires a DR Operation Token to be provided as means of
|
|
|
|
|
authorization. See the [DR Operation Token API
|
2018-11-15 17:23:05 +00:00
|
|
|
|
docs](#generate-disaster-recovery-operation-token) for more information.
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :--------------------------------------------- |
|
|
|
|
|
| `POST` | `/sys/replication/dr/secondary/update-primary` |
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `dr_operation_token` `(string: <required>)` - DR operation token used to authorize this request.
|
|
|
|
|
|
|
|
|
|
- `token` `(string: <required>)` – Specifies the secondary activation token
|
|
|
|
|
fetched from the primary. If you set this to a blank string, the cluster will
|
|
|
|
|
stay a secondary but clear its knowledge of any past primary (and thus not
|
|
|
|
|
attempt to connect to the previous primary). This can be useful if the primary
|
|
|
|
|
is down to stop the secondary from trying to reconnect to it.
|
|
|
|
|
|
|
|
|
|
- `primary_api_addr` `(string: )` – Specifies the API address (normal Vault
|
|
|
|
|
address) to override the value embedded in the token. This can be useful if
|
|
|
|
|
the primary's redirect address is not accessible directly from this cluster.
|
|
|
|
|
|
|
|
|
|
- `ca_file` `(string: "")` – Specifies the path to a CA root file (PEM format)
|
|
|
|
|
that the secondary can use when unwrapping the token from the primary. If this
|
|
|
|
|
and ca_path are not given, defaults to system CA roots.
|
|
|
|
|
|
|
|
|
|
- `ca_path` `string: ()` – Specifies the path to a CA root directory containing
|
|
|
|
|
PEM-format files that the secondary can use when unwrapping the token from the
|
|
|
|
|
primary. If this and ca_file are not given, defaults to system CA roots.
|
|
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"dr_operation_token": "...",
|
|
|
|
|
"token": "..."
|
|
|
|
|
}
|
2018-03-21 14:14:52 +00:00
|
|
|
|
```
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-11-14 11:13:11 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
|
|
|
|
--data @payload.json \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/update-primary
|
2017-11-14 11:13:11 +00:00
|
|
|
|
```
|
|
|
|
|
|
2018-03-21 14:14:52 +00:00
|
|
|
|
## Generate Disaster Recovery Operation Token
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
The `/sys/replication/dr/secondary/generate-operation-token` endpoint is used to create a new Disaster
|
|
|
|
|
Recovery operation token for a DR secondary. These tokens are used to authorize
|
2019-11-14 16:53:42 +00:00
|
|
|
|
certain DR Operations. They should be treated like traditional root tokens by
|
2018-05-03 20:37:44 +00:00
|
|
|
|
being generated when needed and deleted soon after.
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
## Read Generation Progress
|
|
|
|
|
|
|
|
|
|
This endpoint reads the configuration and process of the current generation
|
|
|
|
|
attempt.
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :--------------------------------------------------------------- |
|
|
|
|
|
| `GET` | `/sys/replication/dr/secondary/generate-operation-token/attempt` |
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-11-14 11:13:11 +00:00
|
|
|
|
$ curl \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-operation-token/attempt
|
2017-11-14 11:13:11 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"started": true,
|
|
|
|
|
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
|
|
|
|
"progress": 1,
|
|
|
|
|
"required": 3,
|
|
|
|
|
"encoded_token": "",
|
|
|
|
|
"pgp_fingerprint": "",
|
|
|
|
|
"complete": false
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If a generation is started, `progress` is how many unseal keys have been
|
|
|
|
|
provided for this generation attempt, where `required` must be reached to
|
|
|
|
|
complete. The `nonce` for the current attempt and whether the attempt is
|
|
|
|
|
complete is also displayed. If a PGP key is being used to encrypt the final
|
|
|
|
|
token, its fingerprint will be returned. Note that if an OTP is being used to
|
|
|
|
|
encode the final token, it will never be returned.
|
|
|
|
|
|
|
|
|
|
## Start Token Generation
|
|
|
|
|
|
|
|
|
|
This endpoint initializes a new generation attempt. Only a single
|
2018-11-15 17:23:05 +00:00
|
|
|
|
generation attempt can take place at a time.
|
2018-10-10 15:51:05 +00:00
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :--------------------------------------------------------------- |
|
2022-02-25 14:52:24 +00:00
|
|
|
|
| `POST` | `/sys/replication/dr/secondary/generate-operation-token/attempt` |
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
2018-10-10 15:56:50 +00:00
|
|
|
|
- `pgp_key` `(string: <optional>)` – Specifies a base64-encoded PGP public key.
|
|
|
|
|
The raw bytes of the token will be encrypted with this value before being
|
|
|
|
|
returned to the final unseal key provider.
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-11-14 11:13:11 +00:00
|
|
|
|
$ curl \
|
2022-02-25 14:52:24 +00:00
|
|
|
|
--request POST \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-operation-token/attempt
|
2017-11-14 11:13:11 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"started": true,
|
|
|
|
|
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
|
|
|
|
"progress": 1,
|
|
|
|
|
"required": 3,
|
|
|
|
|
"encoded_token": "",
|
2018-10-10 15:51:05 +00:00
|
|
|
|
"otp": "2vPFYG8gUSW9npwzyvxXMug0",
|
2020-01-18 00:18:09 +00:00
|
|
|
|
"otp_length": 24,
|
2017-11-14 11:13:11 +00:00
|
|
|
|
"complete": false
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Cancel Generation
|
|
|
|
|
|
|
|
|
|
This endpoint cancels any in-progress generation attempt. This clears any
|
|
|
|
|
progress made. This must be called to change the OTP or PGP key being used.
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :------- | :--------------------------------------------------------------- |
|
2019-03-22 16:15:37 +00:00
|
|
|
|
| `DELETE` | `/sys/replication/dr/secondary/generate-operation-token/attempt` |
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-11-14 11:13:11 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--request DELETE \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-operation-token/attempt
|
2017-11-14 11:13:11 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Provide Key Share to Generate Token
|
|
|
|
|
|
2022-03-17 05:01:38 +00:00
|
|
|
|
This endpoint is used to enter a single root key share to progress the
|
|
|
|
|
generation attempt. If the threshold number of root key shares is reached,
|
2020-01-18 00:18:09 +00:00
|
|
|
|
Vault will complete the generation and issue the new token. Otherwise,
|
2017-11-14 11:13:11 +00:00
|
|
|
|
this API must be called multiple times until that threshold is met. The attempt
|
|
|
|
|
nonce must be provided with each call.
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :-------------------------------------------------------------- |
|
2022-02-25 14:52:24 +00:00
|
|
|
|
| `POST` | `/sys/replication/dr/secondary/generate-operation-token/update` |
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
2022-03-17 05:01:38 +00:00
|
|
|
|
- `key` `(string: <required>)` – Specifies a single root key share.
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
- `nonce` `(string: <required>)` – Specifies the nonce of the attempt.
|
|
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"key": "acbd1234",
|
|
|
|
|
"nonce": "ad235"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-11-14 11:13:11 +00:00
|
|
|
|
$ curl \
|
2022-02-25 14:52:24 +00:00
|
|
|
|
--request POST \
|
2017-11-14 11:13:11 +00:00
|
|
|
|
--data @payload.json \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-operation-token/update
|
2017-11-14 11:13:11 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
This returns a JSON-encoded object indicating the attempt nonce, and completion
|
|
|
|
|
status, and the encoded token, if the attempt is complete.
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"started": true,
|
|
|
|
|
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
|
|
|
|
"progress": 3,
|
|
|
|
|
"required": 3,
|
|
|
|
|
"pgp_fingerprint": "",
|
|
|
|
|
"complete": true,
|
|
|
|
|
"encoded_token": "FPzkNBvwNDeFh4SmGA8c+w=="
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Delete DR Operation Token
|
2018-03-21 14:14:52 +00:00
|
|
|
|
|
2017-11-14 11:13:11 +00:00
|
|
|
|
This endpoint revokes the DR Operation Token. This token does not have a TTL
|
|
|
|
|
and therefore should be deleted when it is no longer needed.
|
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
|
| Method | Path |
|
|
|
|
|
| :----- | :----------------------------------------------------- |
|
|
|
|
|
| `POST` | `/sys/replication/dr/secondary/operation-token/delete` |
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `dr_operation_token` `(string: <required>)` - DR operation token used to authorize this request.
|
|
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"dr_operation_token": "..."
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
|
```shell-session
|
2017-11-14 11:13:11 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
|
--request POST \
|
|
|
|
|
--data @payload.json \
|
2018-03-23 15:41:51 +00:00
|
|
|
|
http://127.0.0.1:8200/v1/sys/replication/dr/secondary/operation-token/delete
|
2017-11-14 11:13:11 +00:00
|
|
|
|
```
|