How to create a Hyperledger Fabric ledger snapshot

A Hyperledger Fabric ledger snapshot captures a peer's channel state at a selected block height so another peer can join from that point or administrators can compare state across peers. Creating one before peer onboarding or state-integrity checks gives operators a completed snapshot directory instead of relying only on peer logs or channel height.

The peer snapshot command schedules the snapshot on a running peer. A request for a future block remains pending until that block is committed, while -b 0 asks the peer to snapshot the latest committed block immediately.

Snapshot generation is resource-intensive. The peer can continue answering endorsements and queries, but it does not commit blocks on that channel while the snapshot is being generated, and the snapshot is not a full peer backup because private data values, MSP material, and peer configuration are not included.

Related: How to join a Hyperledger Fabric peer from a ledger snapshot
Related: How to run the Hyperledger Fabric test network

Steps to create a Hyperledger Fabric ledger snapshot:

  1. Open an admin shell for the peer that will create the snapshot.

    The shell must use a peer MSP identity with permission to administer the target peer. Replace mychannel, peer0.org1.example.com:7051, and /etc/hyperledger/fabric/tls/ca.crt with values from the peer deployment.

  2. Check the current ledger height on the channel. 
    $ peer channel getinfo -c mychannel
Blockchain info: {"height":3,"currentBlockHash":"yclwrdzBu80EjIoJgXEkCMSwGqrpn3vTnuTFBFcbTfE=","previousBlockHash":"2WtLN0J8lsNx1eMvkAtPeuo9cBdxq+OFi1hDm4FmUA8="}
  3. Submit an immediate snapshot request. 
    $ peer snapshot submitrequest -c mychannel -b 0 --peerAddress peer0.org1.example.com:7051 --tlsRootCertFile /etc/hyperledger/fabric/tls/ca.crt
Snapshot request submitted successfully

    Use a specific block number instead of -b 0 when multiple peers must produce snapshots at the same agreed height. Fabric rejects a snapshot request below the current channel height.

  4. Check pending snapshot requests for the channel. 
    $ peer snapshot listpending -c mychannel --peerAddress peer0.org1.example.com:7051 --tlsRootCertFile /etc/hyperledger/fabric/tls/ca.crt
Successfully got pending snapshot requests: []

    An empty list after an immediate request means no scheduled snapshot is still waiting. A future-height request remains listed until that block is committed.

  5. List completed snapshot heights in the peer snapshot root. 
    $ sudo ls /var/hyperledger/production/snapshots/completed/mychannel
2

    Fabric writes completed snapshots under {ledger.snapshots.rootDir}/completed/<channel>/<height>. If ledger.snapshots.rootDir is not set, the root defaults to {peer.fileSystemPath}/snapshots, commonly /var/hyperledger/production/snapshots.

  6. Check the files in the completed snapshot directory. 
    $ sudo ls /var/hyperledger/production/snapshots/completed/mychannel/2
_snapshot_additional_metadata.json
_snapshot_signable_metadata.json
public_state.data
public_state.metadata
txids.data
txids.metadata

    Channels without private data collections may omit collection or private-data files. The metadata files should be present in a completed snapshot.

  7. Inspect the snapshot metadata. 
    $ sudo cat /var/hyperledger/production/snapshots/completed/mychannel/2/_snapshot_additional_metadata.json
{
    "snapshot_hash": "1390f5af8947640cad08b4bbe4e310bb628fb4ba9afedde442d8dbd12b8e21ce",
    "last_block_commit_hash": "5f88b61407b149a48413433f4670c46531e5c4a8febdc339a9536ff8716a559e"
}

    Use snapshot_hash to compare snapshots produced by other peers at the same height before using the snapshot for a peer join or integrity check.