restic-backup-suite: Troubleshooting
Troubleshooting restic-backup-suite: script messages with cause and solution, SFTP connection, repository init, database dumps, locks and frequently asked questions.
Troubleshooting
You find the log files under LOG_DIR (template: /var/log/restic/backup-YYYY-MM-DD.log), see Monitoring.
Script messages
| Message | Cause | Solution |
|---|---|---|
Config file not found: ... |
Neither --config, nor config.sh in the script directory, nor /etc/restic/config.sh exists |
cp config.example.sh config.sh or sudo ./install.sh |
This script must be run as root. |
Run without root | Start with sudo |
restic is not installed or not in PATH. |
restic is missing | Install restic. For the cron job, check PATH in /etc/cron.d/restic-backup |
SFTP connection to <host> failed. |
The BatchMode connection test failed: unknown host key, key not installed or wrong port |
Run sftp <SSH_HOST> by hand, add the host key to /root/.ssh/known_hosts |
SSH key not found: ... (warning) |
SSH_KEY_FILE points to no file |
Create the key or fix the path |
Failed to initialize restic repository. |
restic snapshots failed and restic init failed too. An existing repository with a wrong password, unreachable storage or a lock triggers this chain as well |
Check the password file, reachability and run restic snapshots by hand (restic-snapshots) |
Backup failed. |
restic backup failed |
Read restic's output in the log |
Retention policy failed (warning) |
restic forget --prune failed, often because of a lock |
restic-unlock, try again on the next run |
Repository check reported issues (warning) |
restic check found problems |
Run restic check by hand with a larger share |
Container not running (skipped): ... |
A container in a dump list is not running | Check the name with docker ps. The entry must match the name exactly |
Invalid password env var name for ... |
The fourth field in DOCKER_MARIADB_CONTAINERS contains invalid characters |
Letters, digits and underscore only |
Access denied (using password: NO) during a dump |
The container uses a different variable than MYSQL_ROOT_PASSWORD |
Set the fourth field, for example "container:root:db:MARIADB_ROOT_PASSWORD" |
Neither mariadb-dump nor mysqldump found |
No dump program on the host (native dump only) | Install the mariadb-client or mysql-client package |
Neither mariadb nor mysql client found |
No client on the host (native dump only) | As above |
Docker Compose file not found (skipped) |
The path in DOCKER_SERVICES_TO_STOP is wrong |
Check the absolute path to the Compose file |
Could not write success marker (warning) |
Directory or file system not writable | Check the SUCCESS_MARKER_FILE path |
Lock errors
After an aborted run a stale lock can remain in the repository. Remove it with restic-unlock once you are sure no other run is active.
Docker containers are not running after a failure
The restart happens in the script's cleanup. If the script was killed with SIGKILL or the server crashed, the restart is missing. Start the services by hand, see Stopping services.
Frequently asked questions
Why do retention and prune run with --dry-run?
Because --dry-run only skips restic backup and stopping Docker services. See Usage. Only use --dry-run to test paths in environments where retention and stopping systemd services are harmless.
Can I back up several servers or repositories with one configuration?
No. One configuration file describes one repository. Create further files and call the scripts with --config.
How do I back up to a second repository?
restic-backup-suite has no feature for that. Use restic's own tools or a second backup with its own configuration file.
Where are the SSH settings?
In the directory of the SSH_KEY_FILE file, subfolder config.d, file restic-backup.