HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Consul
Consul Home

Consul Snapshot Save

Command: consul snapshot save

Corresponding HTTP API Endpoint: [GET] /v1/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. 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. Configuration of blocking queries and agent 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

  • -ca-file=<value> - Path to a CA file to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CACERT environment variable.

  • -ca-path=<value> - Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CAPATH environment variable.

  • -client-cert=<value> - Path to a client cert file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_CERT environment variable.

  • -client-key=<value> - Path to a client key file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_KEY environment variable.

  • -http-addr=<addr> - Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via the CONSUL_HTTP_ADDR environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using unix:///path/to/socket if the agent is configured to listen that way.

  • -tls-server-name=<value> - The server name to use as the SNI host when connecting via TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME environment variable.

  • -token=<value> - ACL token to use in the request. This can also be specified via the CONSUL_HTTP_TOKEN environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.

  • -token-file=<value> - File containing the ACL token to use in the request instead of one specified via the -token argument or CONSUL_HTTP_TOKEN environment variable. This can also be specified via the CONSUL_HTTP_TOKEN_FILE environment variable.

  • -datacenter=<name> - Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.

  • -stale - Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.

  • -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":

$ 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:

$ 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

$ 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 documentation for more details about snapshot internals.

Edit this page on GitHub