mirror of https://github.com/hashicorp/consul
97 lines
3.8 KiB
Markdown
97 lines
3.8 KiB
Markdown
---
|
|
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
|
|
# ...
|
|
```
|
|
|
|
To create snapshot file with consul version, datacenter, node name and leader/follower info,
|
|
run
|
|
|
|
```shell-session
|
|
$ consul snapshot save -append-filename node,status,version,dc backup.snap
|
|
#...
|
|
```
|
|
|
|
File name created will be like backup-%CONSUL_VERSION%-%DC_NAME%-%NODE_NAME%-%STATUS.snap
|
|
example - backup-1.17.0-dc1-local-machine-leader.tgz
|
|
|
|
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.
|
|
|
|
Please see the [HTTP API](/consul/api-docs/snapshot) documentation for
|
|
more details about snapshot internals.
|