Snapshots and recovery

Two kinds of "snapshot" co-exist in etcd, and they're easy to confuse:

Kind	Trigger	Format	Purpose
Raft snapshot	Periodic, on every --snapshot-count committed entries	<data-dir>/member/snap/<term>-<index>.snap	Bound WAL size; bootstrap slow followers
Backup snapshot	Operator-initiated (etcdctl snapshot save / etcdutl snapshot save)	A .db file	Disaster recovery

The two share the underlying bbolt DB on disk but address different problems.

Raft snapshot

Source: server/etcdserver/api/snap/, plus the trigger in server/etcdserver/server.go::triggerSnapshot.

graph LR
    raft[raftNode loop] -->|every N committed entries| trigger[triggerSnapshot]
    trigger -->|raftNode.CreateSnapshot| store[serverstorage]
    store --> snapshotter[snap.Snapshotter]
    snapshotter --> file[(member/snap/<term>-<index>.snap)]
    store --> wal[wal.ReleaseLockTo]
    wal --> trim[(old WAL segments deletable)]

When a slow follower can't catch up from WAL, the leader installs a snapshot via rafthttp.SnapshotSender (server/etcdserver/api/rafthttp/snapshot_sender.go). The follower writes the snap, then re-opens MVCC + bbolt at the new starting state.

Backup snapshot

etcdctl snapshot save and etcdutl snapshot save both go through etcdutl/snapshot/. The flow:

1. The client opens a Snapshot RPC against the leader (server/etcdserver/api/v3rpc/maintenance.go::Snapshot).
2. The server bbolt-clones the live DB, streams it back over gRPC.
3. The client writes the .db to the requested path; status / hash are verified locally.

snapshot status validates the .db without restoring; snapshot restore bootstraps a fresh <name>.etcd member directory using the snapshot as the starting state.

Restore is a destructive operation

snapshot restore writes a brand-new member/ directory: WAL is fresh, the cluster ID is regenerated, and existing peer memberships are discarded. Operators run it on each survivor of a disaster, then reconfigure the cluster as a new, independent quorum. See https://etcd.io/docs/latest/op-guide/recovery for the canonical operational guide.

Defragmentation

Backups and snapshots both observe the physical size of the bolt DB, which can be larger than the live keyspace because of free-page fragmentation. etcdctl defrag (or etcdutl defrag) compacts the file in place. See systems/backend.

Hash verification

For both kinds of snapshot, the server can produce a content hash (HashKV RPC) that the operator compares across members or before/after restore. Implementation: server/storage/mvcc/hash.go, server/etcdserver/api/v3rpc/maintenance.go.

Cross-references

• systems/wal — snapshot decouples WAL retention from log length.
• systems/backend — defragmentation, copy-on-write snapshot.
• applications/etcdutl — offline snapshot tooling.
• Documentation/postmortems/ — historical recovery exercises.