open-consul/website/source/api/snapshot.html.md
Jack Pearkes a1bd33da11
website: use 127.0.0.1 instead of consul.rocks (#4523)
By default, the Consul agent listens on the local interface
at port 8500 for API requests. This change makes the API examples
using `curl` copy-pasteable for this default configuration.
2018-08-28 09:07:15 -07:00

4.3 KiB

layout page_title sidebar_current description
api Snapshot - HTTP API api-snapshot The /snapshot endpoints save and restore Consul's server state for disaster recovery.

Snapshot HTTP Endpoint

The /snapshot endpoints save and restore the state of the Consul servers for disaster recovery. Snapshots include all state managed by Consul's Raft consensus protocol.

Generate Snapshot

This endpoint generates and returns an atomic, point-in-time snapshot of the Consul server state.

Snapshots are exposed as gzipped tar archives which internally contain the Raft metadata required to restore, as well as a binary serialized version of the Consul server state. The contents are covered internally by SHA-256 hashes. These hashes are verified during snapshot restore operations. The structure of the archive is internal to Consul and not intended to be used other than for restore operations. The archives are not designed to be modified before a restore.

Method Path Produces
GET /snapshot 200 application/x-gzip

The table below shows this endpoint's support for blocking queries, consistency modes, and required ACLs.

Blocking Queries Consistency Modes ACL Required
NO default,stale management

Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.

  • stale (bool: false) - Specifies that any follower may reply. By default requests are forwarded to the leader. Followers may be faster to respond, but may have stale data. To support bounding the acceptable staleness of snapshots, responses provide the X-Consul-LastContact header containing the time in milliseconds that a server was last contacted by the leader node. The X-Consul-KnownLeader header also indicates if there is a known leader. These can be used by clients to gauge the staleness of a snapshot and take appropriate action. The stale mode is particularly useful for taking a snapshot of a cluster in a failed state with no current leader.

Sample Request

With a custom datacenter:

$ curl http://127.0.0.1:8500/v1/snapshot?dc=my-datacenter -o snapshot.tgz

The above example results in a tarball named snapshot.tgz in the current working directory.

In addition to the Consul standard stale-related headers, the X-Consul-Index header will contain the index at which the snapshot took place.

Restore Snapshot

This endpoint restores a point-in-time snapshot of the Consul server state.

Restores involve a potentially dangerous low-level Raft operation that is not designed to handle server failures during a restore. This operation is primarily intended to be used when recovering from a disaster, restoring into a fresh cluster of Consul servers.

The body of the request should be a snapshot archive returned from a previous call to the GET method.

Method Path Produces
PUT /snapshot 200 text/plain (empty body)

The table below shows this endpoint's support for blocking queries, consistency modes, and required ACLs.

Blocking Queries Consistency Modes ACL Required
NO none management

Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.

Sample Request

$ curl \
    --request PUT \
    --data-binary @snapshot \
    http://127.0.0.1:8500/v1/snapshot

~> Some tools default to www/encoded uploads. Consul expects the snapshot to be in pure binary form.