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.
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.
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.
If set, appended as backup path(s). If empty and RESTIC_JOB_ARGS does not contain paths, restic backup runs with no explicit path.
RESTIC_JOB_ARGS
(empty)
Extra words passed to restic backup (shell-word split). Examples: --exclude-file /config/exclude_files.txt --one-file-system, --files-from /config/include_files.txt.
RESTIC_FORGET_ARGS
(empty)
If set and backup exits 0, runs restic forget with these words (shell-word split). Example: --prune --keep-daily 7 --keep-weekly 5 --keep-monthly 12.
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, e.g. --max-unused 10%, --max-repack-size 5G.
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.
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.