iotexproject / iotexproject/iotex-bootstrap

Docs: add checksum verification to snapshot download instructions

Open
#330 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
97
Forks
43
Avg merge
1h 7m
Merged PRs (30d)
2

Description

### Problem

The snapshot download steps in the README ([core](https://t.iotex.me/mainnet-data-snapshot-core-latest), [gateway](https://t.iotex.me/mainnet-data-snapshot-gateway-latest)) provide no way for users to verify the integrity of the downloaded archive. Snapshots are large (the mainnet gateway archive is ~48 GB), so interrupted or truncated downloads are common.

When the archive is truncated, extraction fails with errors that don't make the root cause obvious:

```
gzip: stdin: unexpected end of file
tar: Unexpected EOF in archive
tar: Error is not recoverable: exiting now
```

A user recently reported exactly this. On investigation the snapshot on the server was fully intact — the failure was a truncated download on the user's side. Without a published checksum (or even an expected file size), users can't tell a corrupt download apart from a corrupt snapshot, and end up re-downloading blindly or filing false bug reports.

### Suggestion

1. Publish a checksum (e.g. `SHA256SUMS`) alongside each snapshot at `t.iotex.me` / `storage.iotex.io`.
2. Add a verification step to the README snapshot section, e.g.:

```
curl -L -C - -o $IOTEX_HOME/data.tar.gz https://t.iotex.me/mainnet-data-snapshot-core-latest
curl -L -o $IOTEX_HOME/data.tar.gz.sha256 https://t.iotex.me/mainnet-data-snapshot-core-latest.sha256
sha256sum -c $IOTEX_HOME/data.tar.gz.sha256
```

3. At minimum, document the expected file size so users can sanity-check (the current mainnet gateway archive is `48598308441` bytes), and recommend `gunzip -t` before extracting.

This would make download failures self-diagnosable and cut down on confusion.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.