github.com/outbrain/consul@v1.4.5/website/source/api/snapshot.html.md (about)

     1  ---
     2  layout: api
     3  page_title: Snapshot - HTTP API
     4  sidebar_current: api-snapshot
     5  description: |-
     6    The /snapshot endpoints save and restore Consul's server state for disaster
     7    recovery.
     8  ---
     9  
    10  # Snapshot HTTP Endpoint
    11  
    12  The `/snapshot` endpoints save and restore the state of the Consul
    13  servers for disaster recovery. Snapshots include all state managed by Consul's
    14  Raft [consensus protocol](/docs/internals/consensus.html).
    15  
    16  ## Generate Snapshot
    17  
    18  This endpoint generates and returns an atomic, point-in-time snapshot of the
    19  Consul server state.
    20  
    21  Snapshots are exposed as gzipped tar archives which internally contain the Raft
    22  metadata required to restore, as well as a binary serialized version of the
    23  Consul server state. The contents are covered internally by SHA-256 hashes.
    24  These hashes are verified during snapshot restore operations. The structure of
    25  the archive is internal to Consul and not intended to be used other than for
    26  restore operations. The archives are not designed to be modified before a
    27  restore.
    28  
    29  | Method | Path                         | Produces                   |
    30  | :----- | :--------------------------- | -------------------------- |
    31  | `GET`  | `/snapshot`                  | `200 application/x-gzip`   |
    32  
    33  The table below shows this endpoint's support for
    34  [blocking queries](/api/index.html#blocking-queries),
    35  [consistency modes](/api/index.html#consistency-modes),
    36  [agent caching](/api/index.html#agent-caching), and
    37  [required ACLs](/api/index.html#acls).
    38  
    39  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
    40  | ---------------- | ----------------- | ------------- | ------------ |
    41  | `NO`             | `default,stale`   | `none`        | `management` |
    42  
    43  ### Parameters
    44  
    45  - `dc` `(string: "")` - Specifies the datacenter to query. This will default
    46    to the datacenter of the agent being queried. This is specified as part of the
    47    URL as a query parameter.
    48  
    49  - `stale` `(bool: false)` - Specifies that any follower may reply. By default
    50    requests are forwarded to the leader. Followers may be faster to respond, but
    51    may have stale data. To support bounding the acceptable staleness of
    52    snapshots, responses provide the `X-Consul-LastContact` header containing the
    53    time in milliseconds that a server was last contacted by the leader node. The
    54    `X-Consul-KnownLeader` header also indicates if there is a known leader. These
    55    can be used by clients to gauge the staleness of a snapshot and take
    56    appropriate action. The stale mode is particularly useful for taking a
    57    snapshot of a cluster in a failed state with no current leader.
    58  
    59  ### Sample Request
    60  
    61  With a custom datacenter:
    62  
    63  ```text
    64  $ curl http://127.0.0.1:8500/v1/snapshot?dc=my-datacenter -o snapshot.tgz
    65  ```
    66  
    67  The above example results in a tarball named `snapshot.tgz` in the current working directory.
    68  
    69  In addition to the Consul standard stale-related headers, the `X-Consul-Index`
    70  header will contain the index at which the snapshot took place.
    71  
    72  ## Restore Snapshot
    73  
    74  This endpoint restores a point-in-time snapshot of the Consul server state.
    75  
    76  Restores involve a potentially dangerous low-level Raft operation that is not
    77  designed to handle server failures during a restore. This operation is primarily
    78  intended to be used when recovering from a disaster, restoring into a fresh
    79  cluster of Consul servers.
    80  
    81  The body of the request should be a snapshot archive returned from a previous
    82  call to the `GET` method.
    83  
    84  | Method | Path                         | Produces                      |
    85  | :----- | :--------------------------- | ----------------------------- |
    86  | `PUT`  | `/snapshot`                  | `200 text/plain (empty body)` |
    87  
    88  The table below shows this endpoint's support for
    89  [blocking queries](/api/index.html#blocking-queries),
    90  [consistency modes](/api/index.html#consistency-modes),
    91  [agent caching](/api/index.html#agent-caching), and
    92  [required ACLs](/api/index.html#acls).
    93  
    94  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
    95  | ---------------- | ----------------- | ------------- | ------------ |
    96  | `NO`             | `none`            | `none`        | `management` |
    97  ### Parameters
    98  
    99  - `dc` `(string: "")` - Specifies the datacenter to query. This will default
   100    to the datacenter of the agent being queried. This is specified as part of the
   101    URL as a query parameter.
   102  
   103  ### Sample Request
   104  
   105  ```text
   106  $ curl \
   107      --request PUT \
   108      --data-binary @snapshot \
   109      http://127.0.0.1:8500/v1/snapshot
   110  ```
   111  
   112  ~> Some tools default to www/encoded uploads. Consul expects the snapshot to be
   113  in pure binary form.