80 lines
3.1 KiB
Plaintext
80 lines
3.1 KiB
Plaintext
---
|
|
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. 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.
|
|
|
|
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'
|
|
|
|
## 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.
|
|
|
|
Please see the [HTTP API](/consul/api-docs/snapshot) documentation for
|
|
more details about snapshot internals.
|