restic

Identity

Key Operations

Expected State

• restic -r /repo check exits 0 with no errors printed
• restic -r /repo snapshots lists recent snapshots covering expected paths and hosts
• Retention policy applied on a schedule (cron or systemd timer) with forget --prune or forget followed by prune
• Repository password and path stored securely and separately from the machine being backed up

Health Checks

1. restic -r /repo snapshots 2>&1 | tail -5 — lists recent snapshots; confirms repo is accessible and password is correct
2. restic -r /repo check 2>&1 — verifies repository structure and metadata; exits 0 on success
3. restic -r /repo stats 2>&1 | grep -E 'Total|Snapshots' — shows dedup stats and snapshot count without a full data read

Common Failures

Pain Points

• forget and prune are separate commands — restic forget --keep-daily 7 marks old snapshots for deletion and removes them from the snapshot list, but does NOT free disk space. The underlying data blobs are still on disk until you run restic prune. To do both in one step, use restic forget --prune --keep-*. Many users run forget expecting disk usage to drop immediately, then wonder why nothing changed.

• No recovery without the password — Restic repositories are encrypted with AES-256 using a key derived from the password. There is no recovery path if the password is lost. Store it in a password manager (vaultwarden, keepass) alongside the repository URL, and test that you can list snapshots from a clean machine before an emergency occurs.

• check vs check --read-data — restic check verifies the repository structure and snapshot metadata quickly (seconds to minutes). restic check --read-data downloads and verifies every data chunk against its stored hash — this is slow (hours for large repos) but the only way to verify the actual backup data hasn't been corrupted or partially deleted. Run --read-data on a weekly or monthly schedule, not after every backup.

• Exclude caches and temp dirs explicitly — Without exclusions, restic backs up ~/.cache, /tmp, browser cache directories, node_modules, .venv, .tox, and similar volatile trees. Use --exclude-caches (respects CACHEDIR.TAG files that tools like pip and npm write automatically) plus explicit --exclude patterns for the rest. A backup that includes gigabytes of caches wastes space and slows both backup and prune.

• Lock file deadlock with parallel runs — Two simultaneous restic backup commands against the same repository will deadlock on the lock file — the second run will fail immediately with a "repository is already locked" error. For cron/systemd automation, use Conflicts= in the systemd service or a script-level lock guard (flock) to prevent overlapping runs.

• Snapshot IDs are not stable across forget/prune cycles — Short IDs (8 hex chars) are computed from the full 64-char SHA-256 prefix and can collide as the repository grows. Scripts should use either the full 64-char ID or the latest keyword. Always retrieve current IDs with restic snapshots rather than storing them long-term.

References

See references/ for:

• cheatsheet.md — 10 task-organized patterns with copy-paste commands
• common-patterns.md — backend setup, systemd timer automation, rest-server, retention policies
• docs.md — official documentation links