consul/website/content/commands/snapshot/save.mdx

---
layout: commands
page_title: 'Commands: Snapshot Save'
description: |
  The `consul snapshot save` command retrieves a point-in-time snapshot of the state of the Consul servers and saves it to a specified location. Data saved in snapshots includes key/value entries, registered services in the catalog, prepared queries, sessions, and ACLs from a saved snapshot.
---

# Consul Snapshot Save

Command: `consul snapshot save`

Corresponding HTTP API Endpoint: [\[GET\] /v1/snapshot](/consul/api-docs/snapshot#generate-snapshot)

The `snapshot save` command is used to retrieve an atomic, point-in-time snapshot
of the state of the Consul servers which includes key/value entries,
service catalog, prepared queries, sessions, and ACLs. The snapshot is saved to
the given file.

If ACLs are enabled, a management token must be supplied in order to perform
a snapshot save.

-> Note that saving a snapshot involves the server process writing the snapshot to a
temporary file on-disk before sending that file to the CLI client. Upon successful completion,
Consul removes the temporary file. The default location of the temporary file
can vary depending on operating system, but typically is `/tmp`. You can get more detailed
information on default locations in the Go documentation for [os.TempDir](https://golang.org/pkg/os/#TempDir).
If you need to change this location, you can do so by setting the `TMPDIR` environment
variable for the Consul server processes. Keep in mind that setting the environment variable for
the CLI client attempting to perform a snapshot save will have no effect. It _must_ be set in
the context of the server process. If you're using Systemd to manage your Consul server
processes, then adding `Environment=TMPDIR=/path/to/dir` to your Consul unit file will work.
As a result of the Raft snapshot, Consul also saves one snapshot file at `data_dir/raft/snapshots`.

The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of
[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.

| ACL Required |
| ------------ |
| `management` |

## Usage

Usage: `consul snapshot save [options] FILE`

#### API Options

@include 'http_api_options_client.mdx'

@include 'http_api_options_server.mdx'

- `-append-filename=<value>` - Value can be - version,dc,node,status
Adds consul version, datacenter name, node name, and status (leader/follower)
to the file name before the extension separated by `-`

## Examples

To create a snapshot from the leader server and save it to "backup.snap":

```shell-session
$ consul snapshot save backup.snap
Saved and verified snapshot to index 8419
```

By default, snapshots are taken using a consistent mode that forwards requests
to the leader and the leader verifies it is still in power before taking the
snapshot.

After the snapshot is written to the given file it is read back and verified for
integrity.

To create a potentially stale snapshot from any available server, use the stale
consistency mode:

```shell-session
$ consul snapshot save -stale backup.snap
# ...
```

This is useful for situations where a cluster is in a degraded state and no
leader is available. To target a specific server for a snapshot, you can run
the `consul snapshot save` command on that specific server.

To create snapshot file with consul version and datacenter run

```shell-session
$ consul snapshot save -append-filename version,dc backup.snap
#...
```

File name created will be like backup-%CONSUL_VERSION%-%DC_NAME%.snap
example - backup-1.17.0-dc1-local-machine-leader.tgz
Note Version is always the leader's consul version

Please see the [HTTP API](/consul/api-docs/snapshot) documentation for
more details about snapshot internals.