The complete option surface of the image. Defaults below match the
Dockerfile unless noted; an empty default means unset/blank unless you
provide it at runtime.
Legacy aliases
Variables marked legacy are still read at startup for backwards
compatibility and emit a deprecation warning in cron.log when they
override their replacement. They will be removed in 3.0.0.
Restic repository location (local path, s3:…, sftp:…, rclone:…, swift:…, b2:…, etc.). The image bakes the /mnt/restic default into the env; RESTIC_REPOSITORY_FILE (below) is resolved before this value is used so a non-empty file always wins.
RESTIC_REPOSITORY_FILE
(empty)
File path inside the container containing the repository URL (Restic standard, mirrors RESTIC_PASSWORD_FILE). The entrypoint reads the first non-blank, non-comment line — leading/trailing whitespace and trailing CR are stripped — and promotes it into RESTIC_REPOSITORY before any banner, repository probe or worker runs. The original RESTIC_REPOSITORY_FILE env var is unset after a successful promotion so restic never fails with Options --repo and --repository-file are mutually exclusive. Use this to keep rest:https://user:pass@host/, s3:… access strings or any other credential-bearing URL out of docker inspect; point it at a Docker secret mount, e.g. /run/secrets/restic_repository. If the file is unreadable or contains no usable URL the entrypoint leaves both env vars in place and config-check / /bin/doctor surface the specific failure.
RESTIC_PASSWORD
(empty)
Repository password. Appears in docker inspect; prefer RESTIC_PASSWORD_FILE.
RESTIC_PASSWORD_FILE
(empty)
File path inside the container containing the password (Restic standard). Point at a Docker secret mount, e.g. /run/secrets/restic_password.
RESTIC_TAG
automated
Required. Tag passed to restic backup as --tag=…. Explicitly empty value is a hard failure (exit 2). Pick something meaningful, e.g. daily, ${HOSTNAME}-data.
RESTIC_CACHE_DIR
/.cache/restic
Restic cache directory. Mount a volume to persist across restarts.
RESTIC_CACERT
(empty)
Path inside the container to a readable PEM bundle. Automatically passed as --cacert "$RESTIC_CACERT" to every restic invocation. Unreadable path logs a warning and omits the flag; config-check treats the same condition as a hard error.
RESTIC_CHECK_REPOSITORY_STATUS
ON
When ON, the entrypoint probes the repo with restic cat config; auto-restic init runs only on exit 10. Other non-zero exits abort startup. Set to anything else to skip both the probe and the auto-init — pair that with /bin/init-repo for an audited operator-driven bootstrap.
RESTIC_AUTO_UNLOCK
OFF
When ON, /bin/backup and /bin/check run restic unlock after a non-zero restic exit. Default leaves the lock alone — safer for repositories shared across multiple hosts. Use the audited /bin/unlock helper for explicit, logged manual unlocks instead. Conceptual background: Repository locks.
If set, appended as backup path(s). If empty and RESTIC_JOB_ARGS does not contain paths, restic backup runs with no explicit path. Run /bin/sources-report to inspect what these paths look like on disk before the next backup.
RESTIC_JOB_ARGS
(empty)
Extra words passed to restic backup (whitespace-split; not full shell syntax). Examples: --exclude-file /config/exclude_files.txt --one-file-system, --files-from /config/include_files.txt. Keep values free of spaces; use file-based inputs such as --files-from / --exclude-file for complex path lists. /bin/sources-report re-uses the same parsing rules to surface --files-from / --exclude-file readability and pattern counts.
RESTIC_FORGET_ARGS
(empty)
If set and backup exits 0, runs restic forget with these words (whitespace-split; not full shell syntax). Example: --retry-lock=5m --keep-daily 7 --keep-weekly 5 --keep-monthly 12. Add --prune only if you do not run PRUNE_CRON separately.
If non-empty, schedules a standalone /bin/forget on its own flock (/var/run/forget.lock). When set, /bin/backupskips its inline post-backup forget so the repository's exclusive forget-lock is only ever taken in this dedicated maintenance window — the recommended pattern for repositories shared by multiple hosts (eliminates the exit-11 race entirely). RESTIC_FORGET_ARGS is reused verbatim. Typical value 30 1 * * *. See Forget worker.
PRUNE_CRON
(empty)
If non-empty, schedules a standalone /bin/prune on its own flock. Run the heavy restic prune on its own cadence (typically weekly) while RESTIC_FORGET_ARGS keeps post-backup forget cheap.
RESTIC_PRUNE_ARGS
(empty)
Extra words passed to restic prune (whitespace-split; not full shell syntax), e.g. --max-unused 10%, --max-repack-size 5G.
RESTIC_INIT_ARGS
(empty)
Extra words passed to restic init by /bin/init-repo. Whitespace-split, analogous to RESTIC_FORGET_ARGS / RESTIC_PRUNE_ARGS. Examples: --repository-version=2, --copy-chunker-params=/run/secrets/other_repo (deduplication-friendly when cloning a sibling repository). Only consulted by /bin/init-repo; the cron-driven workers ignore it.
Optional snapshot-absolute sub-path to restore for rehearsal (whitespace-split, repeatable). Equivalent to one or more --path flags on /bin/restore-test. Defaults to the full snapshot.
RESTORE_TEST_TARGET
(empty)
Explicit restore target. When unset, the helper picks an auto-mktemp directory under /tmp/restore-test.XXXXXX. Explicit targets must be empty or used together with --force. Refuses /, /data and BACKUP_ROOT_DIR for safety.
RESTORE_TEST_CANARY
(empty)
Whitespace-separated PATH=SHA256 entries; the helper verifies each restored file matches the given lowercase SHA-256 hex digest. Use RESTORE_TEST_CANARY_FILE when paths contain = or whitespace.
RESTORE_TEST_CANARY_FILE
(empty)
Path to a sha256sum-format manifest (<sha256> <path> per line; # comments allowed). Useful for many canaries or awkward paths.
RESTORE_TEST_KEEP
OFF
When ON, leaves the restored tree on disk after verification (default removes auto-tempdirs; operator-supplied targets are never auto-removed).
RESTORE_TEST_MIN_FILES
1
Minimum number of regular files that must be present in the restored tree for the rehearsal to pass. Set to 0 to disable the file-count floor.
RESTORE_TEST_VERIFY
OFF
When ON, passes --verify to restic so per-file hashes are checked against the snapshot manifest during restore. Slower; catches silent corruption.
There is no RESTORE_TEST_CRON baked into the entrypoint by design;
schedule the rehearsal from a sidecar cron / Kubernetes CronJob /
systemd timer that runs docker exec restic-backup-helper
/bin/restore-test. See Restore test
for cadence and canary recommendations.
If set, entrypoint runs mount -o nolock -v "$NFS_TARGET" /mnt/restic. Container aborts with exit 1 if the mount fails. Intended workflow keeps RESTIC_REPOSITORY at default /mnt/restic.
Job file: SOURCE;DESTINATION[;MODE[;EXTRA_ARGS]] per line; # comments allowed. See Replicate worker.
REPLICATE_JOB_ARGS
(empty)
Extra global args passed to every rclone job (whitespace-split; not full shell syntax; --resync stripped from routine runs). Keep values free of spaces or move complex settings into rclone config/files.
REPLICATE_CRON
(empty)
If non-empty, schedules /bin/replicate.
REPLICATE_VERBOSE
ON
When ON, replicate messages also echo to stdout (still always logged to file).
REPLICATE_BISYNC_CHECK_ACCESS
OFF
When ON, appends --check-access to the routine bisync runs and the recovery bisync --resync. Requires the RCLONE_TEST marker file on both endpoints.
When ON, backup / check / prune / restore / snapshot-export / forget-preview only mail on failure. Replicate mails only when at least one job recorded an error.
When set to a writable directory inside the container, every worker writes a restic_<job>.prom document there. Mount that directory into the host and point a node-exporter --collector.textfile.directory at it.
When > 0, wraps each /hooks/*.sh invocation in timeout ${HOOK_TIMEOUT}s. Exit 124 is logged prominently. 0 keeps the historical behaviour of no enforced timeout.
Use the standard AWS environment variables as required by Restic's S3
backend: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
AWS_DEFAULT_REGION, AWS_SESSION_TOKEN, etc. They are not declared in
the Dockerfile but are honoured by Restic at runtime.