restic backup wrapper with tagging, retention and a weekly check

restic itself is one binary with no server component. The missing piece is a small wrapper that fixes the repository, the paths, the retention and the logging in one place so that every run, by hand or from a timer, does the same thing. This script is that wrapper.

One-time setup

sudo mkdir -p /etc/restic
openssl rand -base64 32 | sudo tee /etc/restic/password >/dev/null
sudo chmod 600 /etc/restic/password
printf '%s\n' '/home/*/.cache' '/var/www/*/cache' '*.tmp' | sudo tee /etc/restic/excludes.txt
export RESTIC_REPOSITORY=/srv/backup/restic
export RESTIC_PASSWORD_FILE=/etc/restic/password
restic init

Copy the password file somewhere that is not this machine (a password manager is fine). Without it the repository is unreadable, by you or anyone else. For a remote repository set RESTIC_REPOSITORY to an sftp:user@host:/path, s3: or rclone: URL; restic supports them all with the same commands.

The script

Save as /usr/local/bin/restic-backup.sh, adjust SOURCES and the keep values, and chmod 755 it.

#!/usr/bin/env bash
set -euo pipefail

export RESTIC_REPOSITORY="${RESTIC_REPOSITORY:-/srv/backup/restic}"
export RESTIC_PASSWORD_FILE="${RESTIC_PASSWORD_FILE:-/etc/restic/password}"
SOURCES=(/etc /home /var/www)
EXCLUDE_FILE="/etc/restic/excludes.txt"
KEEP_DAILY=7
KEEP_WEEKLY=4
KEEP_MONTHLY=6
TAG="nightly"
LOG="/var/log/restic-backup.log"

log() { printf '%s %s\n' "$(date '+%F %T')" "$*" | tee -a "$LOG"; }

if [ ! -r "$RESTIC_PASSWORD_FILE" ]; then
  log "password file $RESTIC_PASSWORD_FILE is missing or unreadable"
  exit 1
fi

if ! restic cat config >/dev/null 2>&1; then
  log "repository $RESTIC_REPOSITORY is not initialised, run: restic init"
  exit 1
fi

EXCLUDE_ARGS=()
if [ -r "$EXCLUDE_FILE" ]; then
  EXCLUDE_ARGS=(--exclude-file "$EXCLUDE_FILE")
fi

log "backup start: ${SOURCES[*]}"
restic backup "${SOURCES[@]}" \
  --tag "$TAG" \
  --exclude-caches \
  --one-file-system \
  "${EXCLUDE_ARGS[@]}" 2>&1 | tee -a "$LOG"
status=${PIPESTATUS[0]}
if [ "$status" -eq 3 ]; then
  log "backup finished with warnings: some files could not be read"
elif [ "$status" -ne 0 ]; then
  log "backup FAILED with exit code $status"
  exit "$status"
fi

log "apply retention: daily=$KEEP_DAILY weekly=$KEEP_WEEKLY monthly=$KEEP_MONTHLY"
restic forget \
  --tag "$TAG" \
  --group-by host,paths \
  --keep-daily "$KEEP_DAILY" \
  --keep-weekly "$KEEP_WEEKLY" \
  --keep-monthly "$KEEP_MONTHLY" \
  --prune 2>&1 | tee -a "$LOG"

if [ "$(date +%u)" -eq 7 ]; then
  log "weekly integrity check"
  restic check --read-data-subset=5% 2>&1 | tee -a "$LOG"
fi

log "done, latest snapshots:"
restic snapshots --latest 1 --compact 2>&1 | tee -a "$LOG"

How it works

• restic cat config is a cheap way to confirm the repository exists and the password is right before anything else runs.
• --exclude-caches skips directories marked with a CACHEDIR.TAG file; --one-file-system keeps the backup from wandering into mounted filesystems such as /proc or a NAS mount.
• restic exits with code 3 when some files could not be read (for example a file that vanished mid-run). The script logs that as a warning and continues, because the snapshot is still valid; any other non-zero code aborts before retention runs, so a failed backup never triggers deletion of old snapshots.
• forget --group-by host,paths applies the keep rules per host and path set, so a second machine backing up into the same repository does not consume the first machine’s daily slots.
• Careful: --prune permanently deletes data that no kept snapshot references. Run the forget line with --dry-run once to see what would be removed before you trust the numbers.
• restic check --read-data-subset=5% reads a random 5 percent of the pack files every Sunday and verifies their hashes, catching bit rot on the backup medium without reading the entire repository.

Run it and schedule it

sudo /usr/local/bin/restic-backup.sh
tail -n 30 /var/log/restic-backup.log
restic snapshots

To run it nightly, create a restic-backup.service with Type=oneshot and a matching .timer, exactly as in Schedule PostgreSQL and MySQL dumps with systemd timers; set the environment variables in the service with Environment= lines or keep them in the script as shown. On macOS, a launchd plist with StartCalendarInterval does the same job.

If a run is interrupted

A killed run can leave a stale lock. restic unlock removes locks that no running process holds. If restic check reports errors, run restic repair index and then check again; if it still fails, consult the restic troubleshooting guide before pruning anything.

Official documentation

• restic: Backing up
• restic: Removing backup snapshots
• restic: Working with repositories (check)