marc0janssen/restic-backup-helper repository overview

Upgrading?

• 3.1.0 → 3.2.0: additive plus safer defaults. New /bin/support-bundle creates a redacted diagnostics tarball. Worker last-*.json files now include documented started_epoch / finished_epoch integers. Compose/Kubernetes/Helm liveness examples now probe local scheduler health (cron.log + crond) instead of remote repository reachability. Tracked config/rclone.conf and config/msmtprc are now .example templates; real local files are gitignored.
• 2.13.0 → 2.14.0: purely additive. New /bin/status helper (alias /bin/health-summary) gives a fast local OK/WARN/FAIL summary from release metadata, rendered crontab (or env preview), recent /var/log/last-*.json files and backup/check/forget/prune/replicate ages + exit codes. It deliberately does not run restic, rclone, hooks, mail, webhooks or a repository probe; use /bin/doctor for deeper diagnostics. --json emits stdout-only schema restic-backup-helper.status/1 and does not write /var/log/last-status.json. No new environment variables.
• 2.10.1 → 2.11.0: purely additive. RESTIC_REPOSITORY_FILE is now first-class. The entrypoint reads the first non-blank, non-comment line of the file and promotes it into RESTIC_REPOSITORY before the banner, the repository probe, the cron-driven workers and restic itself see the env, then unsets RESTIC_REPOSITORY_FILE so restic never fails with Options --repo and --repository-file are mutually exclusive (the image bakes a RESTIC_REPOSITORY=/mnt/restic default in Dockerfile, so the two would otherwise both be set). The "Assuming repository '…' is online" banner now shows the masked resolved URL, and config-check / /bin/doctor surface clear errors when the file is unreadable or empty/comments-only. No behaviour change when RESTIC_REPOSITORY_FILE is unset.
• 2.10.0 → 2.10.1: patch release. Prometheus textfile metrics now escape the hostname label and emit the documented restic_<job>_last_started_timestamp gauge, the webhook helper contract is documented accurately, and docs clarify that RESTIC_*_ARGS / REPLICATE_*_ARGS values are whitespace-split strings rather than full shell syntax. Keep paths/values free of spaces, or use file-based inputs such as --files-from, --exclude-file and rclone config files.
• 2.9.0 → 2.10.0: purely additive. New /bin/notify-test helper sends clearly-labelled test mail and/or webhook notifications through the same notify_mail / notify_webhook helpers used by real jobs, so operators can validate msmtprc, MAILX_RCPT, WEBHOOK_URL, WEBHOOK_HEADER_AUTH and WEBHOOK_TIMEOUT before waiting for a real failure. Default mode sends to every configured target; --mail, --webhook and --all select target scope; --dry-run prints what would be sent without invoking mail or curl; --subject / --message label the test. Unlike real workers, delivery failures affect the helper exit code (1) so CI can catch notification drift. Writes /var/log/last-notify-test.json, restic_notify_test.prom, and runs pre-notify-test / post-notify-test hooks. No new environment variables.
• 2.8.0 → 2.9.0: purely additive. New audited operator helper /bin/init-repo is the operator-driven counterpart to the entrypoint auto-init probe. The recommended deployment pattern on shared remotes is now RESTIC_CHECK_REPOSITORY_STATUS=OFF (no auto-init on a transient TLS / DNS / auth hiccup) plus a one-shot /bin/init-repo --yes (CI) or interactive /bin/init-repo (operator) for the first bootstrap. --dry-run runs the same restic cat config probe and prints the planned restic init command + verdict (would CREATE / would REFUSE — already exists / probe error) without mutation. Without --dry-run a typed init confirmation (interactive TTY) or explicit --yes is required. Adds the RESTIC_INIT_ARGS env-var (e.g. --repository-version=2, --copy-chunker-params=…); CLI passthrough after -- works too. Writes /var/log/last-init-repo.json (with dry_run, assume_yes, confirmed, repo_existed, probe_exit_code, init_args), restic_init_repo.prom, and runs pre-init-repo / post-init-repo hooks, mail and webhook the same way as the other workers. Reachable via docker exec … /bin/init-repo or docker run … init-repo. Idempotent: exits 3 when the repo already exists. No behaviour change for the entrypoint auto-init probe; RESTIC_CHECK_REPOSITORY_STATUS=ON keeps its existing semantics.
• 2.7.0 → 2.8.0: purely additive. New read-only operator helper /bin/sources-report is a pre-flight inventory of the paths your next backup will actually read: re-uses the same BACKUP_ROOT_DIR + RESTIC_JOB_ARGS parsing as /bin/backup, reports readability, type, file count and (optional) size per source, plus pattern counts and missing-entry counts for every --files-from / --exclude-file reference. --no-size skips du -sk on slow / remote sources; --depth N caps find depth; repeatable --source PATH / --files-from FILE add ad-hoc entries. Writes /var/log/last-sources-report.json (flat aggregates plus nested sources, files_from, exclude_files arrays), restic_sources_report.prom, and runs pre-sources-report / post-sources-report hooks, mail and webhook the same way as the other workers. Reachable via docker exec … /bin/sources-report or docker run … sources-report. The size figure is unfiltered (exclude rules are not applied); the exclude-file inventory is reported separately. No env-var changes.
• 2.6.0 → 2.7.0: purely additive. New audited operator helper /bin/unlock complements the safer RESTIC_AUTO_UNLOCK=OFF default (workers still never auto-clear locks on failure). Removes stale exclusive locks by default; --remove-all widens to non-exclusive locks; --dry-run only lists current locks. Writes /var/log/last-unlock.json (with remove_all, dry_run, locks_before, locks_after), restic_unlock.prom, and runs pre-unlock / post-unlock hooks, mail and webhook the same way as the other workers. Reachable via docker exec … /bin/unlock or docker run … unlock. No env-var changes; RESTIC_AUTO_UNLOCK keeps its existing semantics.
• 2.5.0 → 2.6.0: purely additive. New read-only /bin/cron-list inspector prints TZ, the rendered crontab and a per-job summary (run via docker exec … /bin/cron-list or docker run … cron-list). Build scripts gain a --base <restic-tag> CLI flag with newest/latest and prerelease/rc/beta sentinels resolved against Docker Hub before the tag is computed; the resolved tag is verified to exist on Docker Hub before any files are mutated, so a non-existent --base 0.19.0 aborts cleanly instead of producing an image whose tag suffix does not match the base actually used. ./build-testing-local.sh now also patches Dockerfile FROM to match --base, and pushes :develop instead of :testing (versioned :<release> tag unchanged) — update any image: …:testing references in your private-registry manifests to …:develop or pin to …:2.6.0-0.18.1-dev. No runtime change inside the container beyond the new cron-list helper.
• 2.4.0 → 2.5.0: multi-host retention hardening. New standalone /bin/forget worker scheduled via FORGET_CRON (own JSON/Prometheus/mail/webhook/hooks like /bin/prune); when set, /bin/backup skips its inline forget so the exclusive lock is only taken in the dedicated window — eliminates the exit-11 race. Inline post-backup forget exit 11 is also downgraded to ⏭ Forget skipped … (backup exit_code stays 0); the forget result is recorded separately as forget_exit_code in last-backup.json and as a restic_backup_last_forget_exit_code Prometheus gauge. restic unlock is never auto-run on exit 11 regardless of RESTIC_AUTO_UNLOCK (the lock we lost is another host's legitimate lock). Drop-in: FORGET_CRON empty (= default) keeps legacy behaviour. Adding --retry-lock=DURATION to RESTIC_FORGET_ARGS is recommended either way.
• 2.3.x → 2.4.0: additive. New /bin/mount-snapshot helper wraps restic mount (FUSE) read-only under /fusemount (container-internal by design, never collides with /bin/restore output or host bind-mounts), scoped to this container's host/tag by default, with safe target validation, opt-in --allow-other, repeatable --path, an explicit --repo-wide override and an EXIT trap so SIGINT / SIGTERM / crash always unmounts cleanly. FUSE still requires --cap-add SYS_ADMIN --device /dev/fuse and, on hosts that ship AppArmor's docker-default profile, --security-opt apparmor=unconfined.
• 2.2.x → 2.3.0: additive. New /bin/forget-preview helper runs restic forget --dry-run with RESTIC_FORGET_ARGS, host/tag-scoped by default and repository-wide only with --repo-wide.
• 2.2.1 → 2.2.2: docs/patch. Adds a Material for MkDocs documentation site (hosted at https://marc0janssen.github.io/restic-backup-helper/⁠) plus a GitHub Pages deploy workflow. No runtime change.
• 2.2.0 → 2.2.1: patch. CI-only shellcheck cleanup in app/snapshot_export.sh (SC2317/SC2119); no runtime change.
• 2.1.x → 2.2.0: purely additive. New /bin/snapshot-export helper restores a selected snapshot or subtree into a temporary workdir and packages it as .tar.gz under /restore by default. Supports --id, --include, --exclude, --output, --dry-run, hooks, JSON, webhook, mail and metrics.
• 2.0.x → 2.1.0: purely additive. New /bin/doctor read-only diagnostics command for support/triage: masked effective env, path checks, repository probe, replicate job-file validation, hook executable status and recent /var/log summaries. docker run … doctor runs it without starting cron.
• 2.14.x → 3.0.0: Breaking. Removes legacy SYNC_* env vars and /bin/bisync — use REPLICATE_* and /bin/replicate only. See GitHub README / Upgrading⁠.
• 1.18.x → 2.0.0: the old "sync/bisync" surface is renamed to replicate. Use /bin/replicate, REPLICATE_* env vars, /config/replicate_jobs.txt, /hooks/pre-replicate.sh / /hooks/post-replicate.sh, /var/log/last-replicate.json, /var/log/replicate-last.log and restic_replicate.prom. Through 2.x only, legacy SYNC_* and /bin/bisync were accepted with warnings (removed in 3.0.0). Rename any mounted config/sync_jobs.txt to config/replicate_jobs.txt or set REPLICATE_JOB_FILE explicitly. Monitoring and hook paths must be updated.
• 1.17.x → 1.18.0: polish on top of the 1.17.0 /bin/restore wrapper. Three operator-visible additions: --yes / -y runs the wrapper fully non-interactively (skips picker + target + dry-run + Proceed prompts, fills missing answers with cron/CI defaults — useful from inside docker exec -ti …); --verbose / -v now actually streams progress (passes --verbose=2 to restic for per-file lines AND wraps restic in script(1) so the native in-place progress bar renders); interactive mode is TTY-driven only, so modifier flags like --verbose and --force no longer skip the prompts. Image grows ~6 MB to ship util-linux (for script(1)). --include zero-match now exits 3 instead of silently succeeding. Pure polish, no breaking changes for existing scripted callers.
• 1.16.x → 1.17.0: purely additive. New /bin/restore wrapper (interactive on a TTY, flag-driven otherwise) with mail/webhook on by default and /var/log/last-restore.json summary; optional /hooks/{pre,post}-restore.sh. Refuses to restore into /data or a non-empty --target unless --force (or --dry-run). See the GitHub README "Restore (operator-friendly)" section.
• 1.15.x → 1.16.0: purely additive (no env-var rename, no behaviour change). New surfaces: opt-in image SBOM via SBOM=ON ./build.sh (requires syft); source-tree SBOM uploaded by the release CI; scripts/docker-compose.yml ships Compose profiles metrics (node-exporter sidecar) and dev (mailhog); new multi-job example at examples/compose/multi-job.yml; new README "Hardening" section with the read_only: true + tmpfs recipe.
• 1.14.x → 1.15.0: purely additive. New opt-in env vars METRICS_DIR (Prometheus textfile collector) and REPLICATE_BISYNC_CHECK_ACCESS (bisync --check-access opt-in; was SYNC_BISYNC_CHECK_ACCESS in 1.x only). Mail subjects gain [OK|FAIL N] Job host · duration · details prefix. Replicate URL credentials are masked in logs.
• 1.13.x → 1.14.0: explicitly empty RESTIC_TAG is now a hard error. Replicate job files accept optional MODE / EXTRA_ARGS columns. rclone is now installed once with SHA256 verification.
• From 1.11.x: automatic restic unlock after backup / check failures is opt-in (RESTIC_AUTO_UNLOCK=ON, since 1.12.0). 1.13.0 adds standalone PRUNE_CRON + RESTIC_PRUNE_ARGS. See the GitHub README env table.