restic-backup-suite: Configuration

Configuration reference for restic-backup-suite: every config.sh key with defaults, repository examples, backup paths, excludes, retention and integrity check.

Deutsche Version

Back to overview

Configuration

All settings live in one file that the scripts read as Bash code (source). The template is config.example.sh. After running the installer the file is /etc/restic/config.sh.

The scripts look for the file in this order:

--config <file>, if given
config.sh in the script's directory
/etc/restic/config.sh

If the file is missing, the scripts abort with Config file not found.

The file holds paths and references to credentials and is executed as code. Mode 600, owned by root. See Security.

Keys

The column "Template value" shows the example value from config.example.sh. "Code fallback" applies when the key is missing from config.sh.

Restic

Key	Meaning	Template value	Code fallback
`RESTIC_PASSWORD_FILE`	File containing the repository password	`/etc/restic/password.txt`	none
`RESTIC_REPOSITORY`	Repository location	`sftp:myhost:/backup/restic`	none
`RESTIC_CACHE_DIR`	restic cache directory	`${HOME}/.cache/restic`	none
`GOMAXPROCS`	Number of CPU cores for restic (0 = all, per the template)	`2`	none

backup.sh exports all four variables into restic's environment. restore.sh and inspect.sh export only the first three, so GOMAXPROCS has no effect there. The shell aliases export all four.

SFTP and SSH

Only relevant when RESTIC_REPOSITORY starts with sftp:.

Key	Meaning	Template value
`SSH_HOST`	Alias that restic uses in the repository address	`myhost`
`SSH_HOSTNAME`	Real hostname or IP	`storage.example.com`
`SSH_PORT`	SSH port	`22`
`SSH_USER`	User on the target server	`myuser`
`SSH_KEY_FILE`	Private key	`${HOME}/.ssh/id_ed25519`
`SSH_KNOWN_HOSTS_FILE`	No effect, no script reads this value	`${HOME}/.ssh/known_hosts_backup`

Logging

Key	Meaning	Template value
`LOG_DIR`	Directory for log files, created if missing	`/var/log/restic`

Backup scope

Key	Meaning	Template value	Code fallback
`BACKUP_PATHS`	Array of paths to back up	`/var/www`, `/etc`, `/home`	empty
`BACKUP_EXCLUDES`	Array of exclude patterns, one `--exclude` per entry	`.log`, `/tmp/`, `/cache/`, `/.git/`, `/node_modules/`, `/vendor/*`	empty
`BACKUP_EXCLUDE_IF_PRESENT`	Directories containing a file with this name are skipped	`.backupignore`	`.backupignore`

Retention and verification

Key	Meaning	Template value	Code fallback
`RETENTION_KEEP_DAILY`	Daily snapshots to keep	`7`	`7`
`RETENTION_KEEP_WEEKLY`	Weekly snapshots to keep	`4`	`4`
`RETENTION_KEEP_MONTHLY`	Monthly snapshots to keep	`6`	`6`
`REPO_CHECK_SUBSET`	Share of pack files read and verified after the backup	`5%`	`5%`

Databases

See Database dumps.

Key	Meaning	Template value
`MYSQL_BACKUP_ENABLED`	Enable native MySQL/MariaDB dumps (`true`)	`false`
`MYSQL_EXCLUDE_DBS`	Space-separated databases that are not dumped	`information_schema performance_schema mysql sys`
`DOCKER_MARIADB_CONTAINERS`	Array, format `container:db_user:db_name[:password_env_var]`	empty
`DOCKER_POSTGRES_CONTAINERS`	Array, format `container:db_user:db_name`	empty

Stopping services

See Stopping services.

Key	Meaning	Template value	Code fallback
`SERVICES_TO_STOP`	Array of systemd services	empty	empty
`SERVICE_STOP_WAIT`	Seconds to wait after stopping	`2`	`2`
`SERVICE_START_WAIT`	Seconds to wait after starting	`3`	`3`
`DOCKER_SERVICES_TO_STOP`	Array, entries `/path/docker-compose.yml:service` or `container-name`	empty	empty
`DOCKER_STOP_WAIT`	Seconds to wait after stopping	`2`	`2`
`DOCKER_START_WAIT`	Seconds to wait after starting	`3`	`3`

Monitoring

Key	Meaning	Template value	Code fallback
`SUCCESS_MARKER_FILE`	Path of the marker file written after a successful backup. An empty value does not disable it, it falls back to the default path	`/var/backup/.last_restic_success`	`/var/backup/.last_restic_success`

See Monitoring.

Repository and backends

restic-backup-suite passes RESTIC_REPOSITORY to restic unchanged. Examples from the template:

Backend	Example
SFTP	`sftp:myhost:/path/to/repo`
Local	`/mnt/backup/restic-repo`
Amazon S3	`s3:s3.amazonaws.com/bucket-name`
Backblaze B2	`b2:bucket-name:/path`
REST server	`rest:http://localhost:8000/`

Only for sftp: does the backup write an SSH configuration and test the connection. For all other backends restic handles the connection itself.

Credentials for backends such as S3 or B2 (for example AWS_ACCESS_KEY_ID) are not part of the template. The configuration file is read as Bash code, so you can set such variables there with export. The aliases like restic-snapshots work the same way because they read the same file.

What the backup passes to restic

Every run calls restic with these fixed options: --compression max, --exclude-caches, --one-file-system, --exclude-if-present <BACKUP_EXCLUDE_IF_PRESENT>, --verbose, --tag automated, plus one --exclude per entry in BACKUP_EXCLUDES.

--one-file-system: file systems mounted below a backup path are not included. List such mount points as their own entry in BACKUP_PATHS.
--exclude-caches: directories containing a CACHEDIR.TAG are skipped.
The directory with the database dumps is backed up in addition to BACKUP_PATHS.