2016-10-26 02:20:24 +00:00
|
|
|
---
|
2020-09-01 15:14:13 +00:00
|
|
|
layout: commands
|
2020-04-07 18:55:19 +00:00
|
|
|
page_title: 'Commands: Snapshot Save'
|
2016-10-26 02:20:24 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Consul Snapshot Save
|
|
|
|
|
|
|
|
|
|
Command: `consul snapshot save`
|
|
|
|
|
|
2022-01-10 17:40:11 +00:00
|
|
|
Corresponding HTTP API Endpoint: [\[GET\] /v1/snapshot](https://www.consul.io/api-docs/snapshot#generate-snapshot)
|
|
|
|
|
|
2016-10-26 02:20:24 +00:00
|
|
|
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
|
2019-02-20 16:42:38 +00:00
|
|
|
a snapshot save.
|
2016-10-26 02:20:24 +00:00
|
|
|
|
2021-01-06 18:56:40 +00:00
|
|
|
-> 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. The default location
|
|
|
|
|
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.
|
|
|
|
|
|
2016-10-26 02:20:24 +00:00
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
Usage: `consul snapshot save [options] FILE`
|
|
|
|
|
|
|
|
|
|
#### API Options
|
|
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
@include 'http_api_options_client.mdx'
|
2020-04-07 23:56:08 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
@include 'http_api_options_server.mdx'
|
2016-10-26 02:20:24 +00:00
|
|
|
|
|
|
|
|
## Examples
|
|
|
|
|
|
|
|
|
|
To create a snapshot from the leader server and save it to "backup.snap":
|
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2016-10-26 02:20:24 +00:00
|
|
|
$ 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
|
2017-02-10 01:00:38 +00:00
|
|
|
consistency mode:
|
2016-10-26 02:20:24 +00:00
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2016-10-26 02:20:24 +00:00
|
|
|
$ 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.
|
|
|
|
|
|
2020-04-09 23:46:54 +00:00
|
|
|
Please see the [HTTP API](/api/snapshot) documentation for
|
2016-10-26 02:20:24 +00:00
|
|
|
more details about snapshot internals.
|
