---
layout: api
page_title: /sys/storage/raft/snapshot-auto - HTTP API
description: |-

  The `/sys/storage/raft/snapshot-auto` endpoints are used to manage automated
  snapshots with Vault's Raft storage backend.
---

# `/sys/storage/raft/snapshot-auto`

@include 'alerts/enterprise-only.mdx'

@include 'alerts/restricted-root.mdx'

The `/sys/storage/raft/snapshot-auto` endpoints are used to manage automated
snapshots with Vault's Raft storage backend.

## Create/update an automated snapshots config

**This endpoint requires sudo capability.**

This endpoint creates or updates a named configuration. Each configuration
has an interval controlling how often snapshots are taken, a destination
where the snapshots are written, as well as a retention policy governing when
older snapshots get deleted.

Note that for cloud storage types, you can either provide credentials explicitly
using the parameters below, or for GCP and AWS you can omit them and rely on the
other mechanisms the cloud provider's SDK allows for authenticating, e.g.
environment variables or files on disk in predefined locations.

| Method | Path                                           |
| :----- | :--------------------------------------------- |
| `POST` | `/sys/storage/raft/snapshot-auto/config/:name` |

### Parameters

- `name` `(string: <required>)` – Name of the configuration to modify.

- `interval` `(integer or string: <required>)` - Time between snapshots. This
  can be either an integer number of seconds, or a Go duration format string (e.g. 24h)

- `retain` `(integer: 1)` - How many snapshots are to be kept; when writing a
  snapshot, if there are more snapshots already stored than this number, the
  oldest ones will be deleted.

- `path_prefix` `(string: <required>)` - For `storage_type=local`, the directory to
  write the snapshots in. For cloud storage types, the bucket prefix to use.
  Types `azure-blob` and `google-gcs` require a trailing `/` (slash).
  Types `local` and `aws-s3` the trailing `/` is optional.

- `file_prefix` `(string: "vault-snapshot")` - Within the directory or bucket
  prefix given by `path_prefix`, the file or object name of snapshot files
  will start with this string.

- `storage_type` `(string: <required>)` - One of "local", "azure-blob", "aws-s3",
  or "google-gcs". The remaining parameters described below are all specific to
  the selected `storage_type` and prefixed accordingly.

#### storage_type=local

- `local_max_space` `(integer: <required>)` - For `storage_type=local`, the maximum
  space, in bytes, to use for all snapshots with the given `file_prefix` in the `path_prefix` directory. 
  Snapshot attempts will fail if there is not enough
  space left in this allowance.

#### storage_type=aws-s3

- `aws_s3_bucket` `(string: <required>)` - S3 bucket to write snapshots to.

- `aws_s3_region` `(string: <required>)` - AWS region bucket is in.

- `aws_access_key_id` `(string)` - AWS access key ID.

- `aws_secret_access_key` `(string)` - AWS secret access key.

- `aws_session_token` `(string)` - AWS session token.

- `aws_s3_endpoint` `(string)` - AWS endpoint. This is typically only set when
  using a non-AWS S3 implementation like Minio.

- `aws_s3_disable_tls` `(boolean)` - Disable TLS for the S3 endpoint. This
  should only be used for testing purposes, typically in conjunction with
  `aws_s3_endpoint`.

- `aws_s3_force_path_style` `(boolean)` - Use the endpoint/bucket URL style
  instead of bucket.endpoint. May be needed when setting `aws_s3_endpoint`.

- `aws_s3_enable_kms` `(boolean)` - Use KMS to encrypt bucket contents.

- `aws_s3_server_side_encryption` `(boolean)` - Use AES256 to encrypt bucket contents. Cannot use with `aws_s3_enable_kms` parameter.

- `aws_s3_kms_key` `(string)` - Use named KMS key, when `aws_s3_enable_kms=true`

#### storage_type=google-gcs

- `google_gcs_bucket` `(string: <required>)` GCS bucket to write snapshots to.

- `google_service_account_key` `(string)` - Google service account key in JSON format. Depending
  on how the API is invoked, this may be need to be JSON-escaped, e.g. for newlines and double quotes.
  The raw value looks like this:

```json
{
  "type": "service_account",
  "project_id": "project-id",
  "private_key_id": "key-id",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQ ... /WZs=\n-----END RSA PRIVATE KEY-----\n",
  "client_email": "service-account-email",
  "client_id": "client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email"
}
```

- `google_endpoint` `(string)` - GCS endpoint. This is typically only set when
  using a non-Google GCS implementation like fake-gcs-server.

- `google_disable_tls` `(boolean)` - Disable TLS for the GCS endpoint. This
  should only be used for testing purposes, typically in conjunction with
  `google_endpoint`.

#### storage_type=azure-blob

- `azure_container_name` `(string: <required>)` - Azure container name to write
  snapshots to.

- `azure_account_name` `(string)` - Azure account name.

- `azure_account_key` `(string)` - Azure account key.

- `azure_blob_environment` `(string)` - Azure blob environment.

- `azure_endpoint` `(string)` - Azure blob storage endpoint. This is typically
  only set when using a non-Azure implementation like Azurite.

### Sample payload

```json
{
  "interval": "24h",
  "retain": 7,
  "path_prefix": "/opt/vault/snapshots/",
  "storage_type": "local",
  "local_max_space": 10000000
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/config/config1
```

## List automated snapshots configs

**This endpoint requires sudo capability.**

This endpoint lists named configurations.

| Method | Path                                     |
| :----- | :--------------------------------------- |
| `LIST` | `/sys/storage/raft/snapshot-auto/config` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/config
```

### Sample response

```json
{
  "data": {
    "keys": ["config1"]
  }
}
```

## Read automated snapshots config

**This endpoint requires sudo capability.**

This endpoint reads a named configuration.

| Method | Path                                           |
| :----- | :--------------------------------------------- |
| `GET`  | `/sys/storage/raft/snapshot-auto/config/:name` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/config/config1
```

### Sample response

```json
{
  "data": {
    "file_prefix": "vault-snapshot",
    "interval": 86400,
    "local_max_space": 10000000,
    "path_prefix": "/opt/vault/snapshots/",
    "retain": 7,
    "storage_type": "local"
  }
}
```

## Delete automated snapshots config

**This endpoint requires sudo capability.**

This endpoint deletes a named configuration.

| Method   | Path                                           |
| :------- | :--------------------------------------------- |
| `DELETE` | `/sys/storage/raft/snapshot-auto/config/:name` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/config/config1
```

## Read automated snapshots status

This endpoint returns the status of a named configuration.

| Method | Path                                           |
| :----- | :--------------------------------------------- |
| `GET`  | `/sys/storage/raft/snapshot-auto/status/:name` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/status/config1
```

### Sample response

```json
{
  "data": {
    "last_snapshot_end": "2020-10-28T11:17:21-04:00",
    "last_snapshot_error": "",
    "last_snapshot_start": "2020-10-28T11:17:21-04:00",
    "last_snapshot_url": "file:///opt/vault/snapshots/vault-snapshot-1603898241699731000.snap",
    "snapshot_start": "2020-10-28T11:17:21-04:00",
    "snapshot_url": "file:///opt/vault/snapshots/vault-snapshot-1603898241699731000.snap"
  }
}
```
