Encrypted Backups with Restic
Back up a Linux server with Restic to S3-compatible storage: encryption, systemd scheduling, retention, verification and a restore test.
On this page
This guide explains how to back up your VPS or dedicated server with Restic to S3-compatible storage. Restic encrypts data on the server before sending it, transfers only what has changed and keeps several restore points, called snapshots.
You will set up a daily backup, a retention policy, a weekly integrity check and, above all, a restore test. Until this test has succeeded, consider that you have no backup.
Prerequisites
- A server running Debian 12 or 13, or Ubuntu 22.04 or 24.04, with
sudoaccess - A bucket on S3-compatible storage, with an access key and a secret key
- A system clock set to the correct time: see our guide Configure NTP
- A place off the server to keep the repository password, such as a password manager
No inbound port needs to be opened. The server only needs to reach the storage over HTTPS on outbound port 443.
Choose the storage
The examples use HostMyServers Object Storage, which is S3-compatible and whose endpoint published on that page is https://s3.lyn.io.hostmyservers.net. The bucket is called mes-sauvegardes and the web01 folder stands for your server: adapt both names.
For another S3-compatible provider, simply replace the address in RESTIC_REPOSITORY with the one it gives you.
Install Restic
Distribution packages can be outdated. Install the official binary published by the project. At the time of writing, the latest version is 0.19.1: see the releases page and adjust RESTIC_VERSION if needed.
RESTIC_VERSION="0.19.1"
ARCH="$(dpkg --print-architecture)"
FILE="restic_${RESTIC_VERSION}_linux_${ARCH}.bz2"
cd /tmp
curl -fsSLO "https://github.com/restic/restic/releases/download/v${RESTIC_VERSION}/${FILE}"
curl -fsSLO "https://github.com/restic/restic/releases/download/v${RESTIC_VERSION}/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMSThe verification must show OK. Then install the binary:
bunzip2 "$FILE"
sudo install -m 755 "${FILE%.bz2}" /usr/local/bin/restic
restic versionIf bunzip2 is missing, install it with sudo apt install -y bzip2.
Prepare the configuration
-
Create the configuration folder and the repository password:
Terminalsudo install -d -m 700 /etc/restic sudo sh -c 'umask 077; openssl rand -base64 32 > /etc/restic/password' sudo cat /etc/restic/password -
Create the environment file:
Terminalsudo install -m 600 /dev/null /etc/restic/restic.env sudo nano /etc/restic/restic.envConfigurationRESTIC_REPOSITORY='s3:https://s3.lyn.io.hostmyservers.net/mes-sauvegardes/web01' RESTIC_PASSWORD_FILE='/etc/restic/password' AWS_ACCESS_KEY_ID='YOUR_ACCESS_KEY' AWS_SECRET_ACCESS_KEY='YOUR_SECRET_KEY'If your provider requires a region, add
AWS_DEFAULT_REGION='YOUR_REGION'. -
List the folders to back up. Only list paths that exist:
Terminalsudo nano /etc/restic/pathsText/etc /home /root /var/www /var/backups -
List what must be ignored:
Terminalsudo nano /etc/restic/excludesText/home/*/.cache /root/.cache /var/www/*/cache **/node_modules *.tmp -
Create a small command that loads this configuration:
Terminalsudo nano /usr/local/sbin/restic-envTerminal#!/bin/sh set -a . /etc/restic/restic.env set +a exec /usr/local/bin/restic "$@"Terminalsudo chmod 700 /usr/local/sbin/restic-env
Create the repository and run a first backup
-
Initialize the repository:
Terminalsudo restic-env init -
Simulate the backup to check which files are selected:
Terminalsudo restic-env backup --files-from /etc/restic/paths --exclude-file /etc/restic/excludes --exclude-caches --dry-run --verbose -
Run the backup:
Terminalsudo restic-env backup --files-from /etc/restic/paths --exclude-file /etc/restic/excludes --exclude-caches --tag auto -
Check the result:
Terminalsudo restic-env snapshots sudo restic-env ls latest /etc/hostname sudo restic-env checkcheckmust end withno errors were found.
Test the restore
Do this test now, then at least once a quarter. It has three levels, from the quickest to the most complete.
Level 1: one file
sudo rm -rf /var/tmp/restic-test
sudo restic-env restore latest --target /var/tmp/restic-test --include /etc/hostname
sudo diff /etc/hostname /var/tmp/restic-test/etc/hostname && echo "Identical"Level 2: a whole folder
sudo restic-env restore latest:/etc --target /var/tmp/restic-test/etc-full
sudo diff -r /etc /var/tmp/restic-test/etc-full | head -n 20
sudo stat -c '%U:%G %a %n' /etc/shadow /var/tmp/restic-test/etc-full/shadowOnly files modified since the backup should appear in diff. The owner and permissions of shadow must be identical. Then delete this folder, which contains sensitive data:
sudo rm -rf /var/tmp/restic-testLevel 3: recovery on another server
This is the test that proves you could start again after losing the server entirely. On another machine:
-
Install Restic as above.
-
Recreate
/etc/restic/restic.env,/etc/restic/passwordand/usr/local/sbin/restic-envfrom your external copies. -
Restore into a dedicated folder, without overwriting the system:
Terminalsudo restic-env snapshots --host web01 sudo restic-env restore latest --host web01 --target /var/restore -
Check your files, then restore a database from its exports by following the matching guide.
Note the date of the test and the time it took: it is a good estimate of your real recovery time. Here, web01 is the host name of the original server, shown by restic-env snapshots.
Schedule backups with systemd
-
Create the backup service:
Terminalsudo nano /etc/systemd/system/restic-backup.serviceConfiguration[Unit] Description=Restic backup Wants=network-online.target After=network-online.target [Service] Type=oneshot EnvironmentFile=/etc/restic/restic.env Environment=HOME=/root Environment=RESTIC_CACHE_DIR=/var/cache/restic CacheDirectory=restic CacheDirectoryMode=0700 Nice=10 IOSchedulingClass=idle ExecStart=/usr/local/bin/restic backup --retry-lock 1h --files-from /etc/restic/paths --exclude-file /etc/restic/excludes --exclude-caches --tag auto -
Create its timer:
Terminalsudo nano /etc/systemd/system/restic-backup.timerConfiguration[Unit] Description=Daily Restic backup [Timer] OnCalendar=*-*-* 03:30:00 RandomizedDelaySec=20min Persistent=true [Install] WantedBy=timers.target -
Create the maintenance service, which applies the retention policy and then checks the repository:
Terminalsudo nano /etc/systemd/system/restic-maintenance.serviceConfiguration[Unit] Description=Restic retention and check Wants=network-online.target After=network-online.target [Service] Type=oneshot EnvironmentFile=/etc/restic/restic.env Environment=HOME=/root Environment=RESTIC_CACHE_DIR=/var/cache/restic CacheDirectory=restic CacheDirectoryMode=0700 Nice=10 IOSchedulingClass=idle ExecStart=/usr/local/bin/restic forget --retry-lock 1h --tag auto --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune ExecStart=/usr/local/bin/restic check --retry-lock 1h --read-data-subset=5%%The
%sign is doubled because systemd gives it a special meaning in its unit files. -
Create its timer:
Terminalsudo nano /etc/systemd/system/restic-maintenance.timerConfiguration[Unit] Description=Weekly Restic maintenance [Timer] OnCalendar=Sun *-*-* 05:00:00 RandomizedDelaySec=20min Persistent=true [Install] WantedBy=timers.target -
Enable both timers and run a backup through this mechanism:
Terminalsudo systemctl daemon-reload sudo systemctl enable --now restic-backup.timer restic-maintenance.timer sudo systemctl start restic-backup.service sudo systemctl status restic-backup.service --no-pager systemctl list-timers 'restic-*'
View the logs with sudo journalctl -u restic-backup.service -n 50 --no-pager. Remember to monitor these services: a backup that fails silently for weeks is a common risk. systemctl --failed lists them if they fail.
Understand retention
| Option | Keeps |
|---|---|
--keep-daily 7 |
The latest snapshot of each of the last 7 days that have one |
--keep-weekly 4 |
The latest snapshot of each of the last 4 weeks that have one |
--keep-monthly 6 |
The latest snapshot of each of the last 6 months that have one |
forget removes snapshots, and --prune then frees the corresponding space. Before changing these values, simulate the result:
sudo restic-env forget --tag auto --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --dry-run--read-data-subset=5% downloads and verifies a random sample of about 5% of the data on each run. To check everything, use --read-data, which takes longer and transfers more data.
Limit the risks
- The keys stored on the server allow the repository to be deleted. If an attacker takes control of the server, they can also reach your backups.
- The HMS offer advertises versioning and lifecycle rules on its presentation page. Versioning lets you recover an overwritten or deleted object, but the versions kept count toward the billed volume.
- A second repository key avoids depending on a single password. Add it with
sudo restic-env key add, and keep it off the server as well.
Update Restic
The official binary updates itself, after verifying its signature:
sudo restic self-update
restic versionYour data stays in the repository. After a major update, run sudo restic-env check again and a level 1 restore test.
Troubleshooting
wrong password or no key found
The content of /etc/restic/password does not match the repository. Restore the password from your external copy. Without any valid password, the data cannot be recovered.
repository does not exist: unable to open config file
The repository has not been initialized at this address, or the address is wrong. Check RESTIC_REPOSITORY, the bucket name and the folder. Run sudo restic-env init only if this really is a new repository.
repository is already locked
Another operation is running, or an earlier operation was interrupted. First check that no Restic process is running on any server using this repository:
pgrep -a restic
sudo restic-env list locksThen remove only the stale locks:
sudo restic-env unlockSignatureDoesNotMatch, InvalidAccessKeyId or AccessDenied
The keys are incorrect, or do not have access to this bucket. Check AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and the endpoint shown for your service. If the error mentions a region, add AWS_DEFAULT_REGION with the value provided by your storage provider, or contact support from your customer area.
RequestTimeTooSkewed
The server clock is off. Check it with timedatectl, then fix it with our guide Configure NTP.
NoSuchBucket
The bucket does not exist or its name is misspelled. Create it from your customer area, then run init again.
no such host or timeout
Check the endpoint, DNS resolution and outbound access to port 443:
curl -I https://s3.lyn.io.hostmyservers.netAny HTTP response, even a 403 error, proves the service is reachable.
The service exits with code 3
The snapshot was created, but some files could not be read. The log lists them. Fix the permissions, exclude temporary files, then run the backup again.
The repository reports errors on check
Run neither forget nor prune, keep the current state and follow the official troubleshooting procedure.