Blog
SavedSearch
Visit Hostlelo

Back Up a Linux Web Server With restic to S3-Compatible Storage

Copies on the same server are not backups. Set up restic for encrypted, deduplicated, off-server snapshots of your site files and database, then test a restore.

The short answer

To back up a Linux web server with restic, initialise an encrypted repository on an S3-compatible bucket, back up the web root and a mysqldump taken with --stdin-from-command, and apply a retention policy with restic forget --prune on a nightly schedule. Store the repository password off the server, because restic cannot recover data without it. A backup only counts once you have restored files and the database dump from it into a test location.

Encrypted restic backup flow from a Linux web server to object storage with a separate verified restore test
Reading options

On this page

Before you start

Root or sudo SSH access; restic; a dedicated S3-compatible backup bucket and scoped key; an off-server password manager; a database read-only backup account; an isolated staging database for full import tests.

To back up a Linux web server with restic, you create an encrypted restic repository in an S3-compatible bucket, run restic backup on your web files and on a database dump, then let restic forget --prune thin out old snapshots on a schedule. The part most people skip, and the part that matters, is restoring from it at least once.

A .tar.gz sitting in /home/backups on the same server is a copy, and copies on the same machine die with the machine. If the disk fails, the provider suspends the account, or someone gets root and wipes things, that archive goes too.

By the end of this guide you will have a working repository on S3-compatible storage, nightly backups of your site files and database, a retention policy, and proof that a restore actually works.

What restic actually is, and why S3 storage fits it

restic is a command-line backup program. Each run creates a snapshot, which is a frozen picture of the files at that moment. Data is split into chunks, and a chunk that already exists in the repository is not uploaded again. That is called deduplication, and it is why the hundredth nightly backup of a mostly unchanged site uploads very little.

The repository is the place restic stores those chunks, plus an index of which snapshot uses which chunk. Everything in it is encrypted with a key that is unlocked by your repository password.

Think of it like a safe deposit box at a bank across town. Your house can burn down and the box survives, but the bank keeps no spare key. Lose yours and nobody opens it.

S3-compatible storage means any object storage service that speaks the same API as Amazon S3. Many providers offer it. The rclone project's S3 page lists dozens of them, and the restic docs mention Wasabi and the S3-compatible API of Backblaze B2 by name. I will keep this guide provider-neutral: you need an endpoint URL, a bucket name, an access key ID and a secret key, and every S3-compatible provider gives you those four things.

Heads up: restic is a file-level tool, and it does not replace the full account backups your control panel or host makes. Keep those running. restic is your second, independent copy that lives somewhere your host does not control. If the idea of a server is still new, what is web hosting gives the background.

Before you start

  • Root or sudo access over SSH to the server. If SSH is open to the internet, protect it with Fail2ban and a firewall such as UFW.
  • An S3-compatible bucket created for backups only, with its endpoint URL, bucket name, access key ID and secret access key.
  • An access key scoped to that bucket if your provider allows it. Do not use an account-wide master key.
  • The path to your web files, for example /var/www/example.com.
  • A MySQL or MariaDB user that can read your site database, and its password.
  • Somewhere safe off the server to store the restic password: a password manager is ideal.
  • Risk level: low. Nothing here changes your web server or database. The only files we create live in /root/restic and /var/backups/mysql.

Set up restic and the repository

Step 1: Install restic and check its version

The official restic installation page lists distribution packages. On Debian, and on Ubuntu (where 22.04 and 24.04 carry it in the universe section), this installs it.

sudo apt-get install restic

On Fedora, this installs it.

sudo dnf install restic

On supported RHEL and CentOS Stream releases, restic comes from the EPEL repository, so you enable EPEL first.

sudo dnf install epel-release
sudo dnf install restic

Now check which version you got, because one feature in this guide depends on it.

restic version

You should see a line starting with restic and a version number, followed by the Go version and your platform.

Why this matters: the cleanest way to back up a database, the --stdin-from-command option, arrived in restic 0.17.0 according to the restic changelog. At the time of writing (21 November 2026), the Ubuntu package for 24.04 is version 0.16.4 and the one for 22.04 is 0.12.1. Both are too old for that option.

If your version is older than 0.17.0, you have two choices. You can download the official binary for your system from the restic GitHub release page, and the install docs suggest checking it against the SHA256SUMS file and its signature on first install. Or you can keep the distribution package and use the dump-to-file method I show in Step 6b. Both work.

Step 2: Create a private folder and a strong password

This creates a folder only root can read, then writes a random 32-byte password into a file inside it.

sudo install -d -m 700 /root/restic
sudo sh -c 'openssl rand -base64 32 > /root/restic/password'
sudo chmod 600 /root/restic/password

Now copy that password into your password manager, off the server.

sudo cat /root/restic/password

Heads up: the restic docs are blunt about this. When you create a repository, restic prints "Losing your password means that your data is irrecoverably lost." There is no reset link and no support ticket that brings it back. If the server dies and the only copy of the password was on that server, your backups are useless.

Step 3: Write the environment file

restic can read all its settings from environment variables, so you keep them in one root-only file. This creates that file.

sudo tee /root/restic/env > /dev/null <<'EOF'
export RESTIC_REPOSITORY="s3:https://s3.example.com/example-backups"
export RESTIC_PASSWORD_FILE="/root/restic/password"
export AWS_ACCESS_KEY_ID="EXAMPLEKEYID"
export AWS_SECRET_ACCESS_KEY="example-secret-key"
export AWS_DEFAULT_REGION="us-east-1"
EOF
sudo chmod 600 /root/restic/env

Replace the values with your own. A few notes on each line:

  • RESTIC_REPOSITORY uses the form s3:https://server:port/bucket_name for S3-compatible servers.
  • For Amazon S3 itself, the docs use the form s3:s3.us-east-1.amazonaws.com/bucket_name.
  • AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are the names restic uses for any S3 provider, not only Amazon.
  • AWS_DEFAULT_REGION is only needed if your provider wants a specific region. If you leave it out, restic uses us-east-1.

Step 4: Initialise the repository

This loads the settings and creates the repository in your bucket.

sudo bash -c 'source /root/restic/env && restic init'

You should see a line like created restic repository 085b3c76b9 at s3:https://s3.example.com/example-backups, followed by the reminder about your password. The ID will be different.

What if your provider wants the bucket in the hostname instead? restic uses path-style addresses for most non-Amazon endpoints by default, and the docs say restic -o s3.bucket-lookup=dns init switches that.

Back up the web files and the database

Step 5: Back up your web files

First, make a small exclude list for things that change constantly and have no value in a restore, like cache folders. This creates it.

sudo tee /root/restic/excludes.txt > /dev/null <<'EOF'
/var/www/example.com/wp-content/cache
/var/www/example.com/tmp
EOF

Adjust the paths to your site. Then run the first file backup. Here --one-file-system keeps restic out of other mounted disks and --tag files labels the snapshot.

sudo bash -c 'source /root/restic/env && restic backup --one-file-system --tag files --exclude-file /root/restic/excludes.txt /var/www/example.com'

When it finishes, restic prints a short summary. The first run uploads everything, and later runs only send what changed.

Step 6a: Back up the database straight into restic (restic 0.17.0 or newer)

The database is the part people forget, because it does not live in /var/www. You back it up as a dump made with mysqldump, which writes the database out as SQL statements.

First, create an option file for the database login. The MySQL manual warns that putting a password on the command line "should be considered insecure" and recommends an option file. This creates one.

sudo tee /root/restic/my.cnf > /dev/null <<'EOF'
[client]
user=backup_user
password=example-db-password
EOF
sudo chmod 600 /root/restic/my.cnf

The MariaDB docs say the [client] group is read by all MariaDB and MySQL client programs, so this works for mysqldump, mariadb-dump and mysql.

Now run the database backup. restic starts mysqldump itself and stores its output as a file called example_db.sql.

sudo bash -c 'source /root/restic/env && restic backup --tag db --stdin-filename example_db.sql --stdin-from-command -- mysqldump --defaults-extra-file=/root/restic/my.cnf --single-transaction example_db'

Three details in that line are deliberate:

  • --defaults-extra-file comes first after mysqldump. Both the MySQL and MariaDB docs say it must be given before other options.
  • --single-transaction gives a consistent dump of InnoDB tables without locking them. The MySQL manual notes MyISAM and MEMORY tables can still change during the dump.
  • I did not use --databases. With that option the dump includes CREATE DATABASE and USE statements, which would aim a test import at your live database. Without it, you choose where the dump goes when you restore.

Why this beats a pipe: restic checks the exit code of mysqldump. The docs say a non-zero exit cancels the backup, restic exits with code 1, and no snapshot is created. A plain mysqldump | restic backup --stdin can quietly save an empty backup when the dump fails.

If your site uses stored procedures or functions, add --routines. The MySQL manual says that option needs the global SELECT privilege.

Step 6b: The dump-to-file method (any restic version)

If your restic is older than 0.17.0, dump to a private folder first, then back that folder up. This creates the folder.

sudo install -d -m 700 /var/backups/mysql

This writes the dump and then backs it up, stopping if the dump fails.

sudo bash -c 'set -euo pipefail; source /root/restic/env; mysqldump --defaults-extra-file=/root/restic/my.cnf --single-transaction example_db > /var/backups/mysql/example_db.sql; restic backup --tag db /var/backups/mysql'

Keep the right amount of history

Step 7: Preview a retention policy, then apply it

Without a policy, snapshots pile up forever. restic forget removes snapshots according to rules, and restic prune removes the data nobody uses any more. The docs say --prune runs prune automatically after forget if anything was actually removed.

This shows what would happen with 7 daily, 4 weekly and 6 monthly snapshots, without removing anything.

sudo bash -c 'source /root/restic/env && restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --dry-run'

The output lists which snapshots would be kept and removed. When it looks right, run it for real.

sudo bash -c 'source /root/restic/env && restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune'

But what if the files snapshots and the database snapshots get mixed up? They will not. The docs say forget groups snapshots by host name and paths before applying the policy. Your files backup and your database backup have different paths, so each keeps its own 7, 4 and 6.

Heads up: the docs say that during a prune "the repository is locked and backups cannot be completed." Run it right after your backups, not alongside them.

Step 8: Put it all in one script and schedule it

This creates a script that runs both backups, applies the policy, and stops at the first error, so a failed step never looks like success. It uses the Step 6a database line; swap in the Step 6b lines if you are on an older restic.

sudo tee /root/restic/backup.sh > /dev/null <<'EOF'
#!/bin/bash
set -euo pipefail
source /root/restic/env

restic backup --one-file-system --tag files --exclude-file /root/restic/excludes.txt /var/www/example.com

restic backup --tag db --stdin-filename example_db.sql --stdin-from-command -- mysqldump --defaults-extra-file=/root/restic/my.cnf --single-transaction example_db

restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

echo "restic backup finished at $(date)"
EOF
sudo chmod 700 /root/restic/backup.sh

Run it once by hand and watch it finish.

sudo /root/restic/backup.sh

Then schedule it. This creates a system cron job that runs the script every night at 02:30 as root and logs the output.

echo '30 2 * * * root /root/restic/backup.sh >> /var/log/restic-backup.log 2>&1' | sudo tee /etc/cron.d/restic-backup

How to check it worked

Until you have restored from a backup, you are only hoping it works. Do these checks today, then repeat the restore test every few months.

First, list your snapshots.

sudo bash -c 'source /root/restic/env && restic snapshots'

You should see columns for ID, Date, Host, Tags, Directory and Size, with at least one snapshot tagged files and one tagged db.

Next, check the repository's structure.

sudo bash -c 'source /root/restic/env && restic check'

The output should end with no errors were found. A plain check does not download your actual data, so now and then also read a random sample of it.

sudo bash -c 'source /root/restic/env && restic check --read-data-subset=10%'

That downloads about a tenth of the stored data, which uses bandwidth, so check what your provider charges for downloads.

Now the real test. Restore the latest files snapshot into a scratch folder, never over your live site.

sudo bash -c 'source /root/restic/env && restic restore latest --path /var/www/example.com --target /root/restore-test'

The --path filter matters. The docs warn that if you saved different things into one repository, "the latest snapshot may not be the right one." Then compare a couple of files.

sudo ls -la /root/restore-test/var/www/example.com
sudo diff -rq /var/www/example.com /root/restore-test/var/www/example.com

You should see your site files, and diff should list only files that changed since the backup and the folders you excluded.

For the database, find the ID of the newest snapshot tagged db in the restic snapshots output, then pull the dump out with restic dump. Replace 1a2b3c4d with your ID.

sudo bash -c 'source /root/restic/env && restic dump 1a2b3c4d example_db.sql > /root/restore-test/example_db.sql'

Look at the top of the file and count the tables.

sudo head -n 20 /root/restore-test/example_db.sql
sudo grep -c "CREATE TABLE" /root/restore-test/example_db.sql

You should see a header comment from the dump tool and a table count that matches your site. A complete import test belongs on a disposable staging database with a separately verified host and credentials. Never run create, import or drop commands against the live database endpoint. Record the intended staging hostname and database name, have another administrator verify them, and then follow your database provider's documented restore procedure.

Keep /root/restore-test until you have reviewed the restored files and recorded the result. Remove it later through your normal change process only after confirming the exact path; this guide deliberately avoids an automated recursive-delete command.

Here is a made-up example: a shop owner ran backups for a year and never tested them. When a plugin update broke the site, the latest database snapshot turned out to be a few hundred bytes, because the dump had failed every night on a changed password. With --stdin-from-command that failure would have stopped the snapshot and shown up in the log. With a test restore, it would have shown up in month one.

Troubleshooting

restic exits with code 12

Symptom: every command fails right away, and echo $? shows 12. The restic scripting docs list 12 as "Wrong password" (since restic 0.17.1). Likely cause: the password file was edited, regenerated, or has a stray character. Fix: restore the exact password from your password manager into /root/restic/password. If you never saved it, there is no way in; create a new repository and start fresh.

restic exits with code 10

Symptom: commands fail with an error about the repository and exit code 10, which the docs list as "Repository does not exist" (since restic 0.17.0). Likely cause: a typo in RESTIC_REPOSITORY, the wrong bucket name, or restic init was never run. Fix: compare the endpoint and bucket with your provider's dashboard, then run Step 4. You can test with restic cat config, which the docs suggest for checking that a repository exists.

restic exits with code 11

Symptom: a backup or prune fails with exit code 11, "Failed to lock repository" (since restic 0.17.0). Likely cause: another restic process is running, often a prune that took longer than expected, or an old process crashed and left a lock behind. Fix: wait and check with ps aux | grep restic. If you are sure nothing is running, restic unlock removes locks that other processes created. The global --retry-lock option can also make a job wait for a lock instead of failing.

No database snapshot appears

Symptom: the files snapshot is there, but nothing tagged db, and the log shows restic exiting with code 1. Likely cause: mysqldump failed, so restic cancelled that snapshot as designed. Common reasons are a wrong password in my.cnf, a missing privilege, or --defaults-extra-file not being the first option. Fix: run the dump on its own to see the real error, for example mysqldump --defaults-extra-file=/root/restic/my.cnf --single-transaction example_db > /dev/null.

The files backup exits with code 3

Symptom: the script stops after the files backup with exit code 3. The docs say this means some source files could not be read, and an incomplete snapshot was still created. Likely cause: file permissions, or the script was run as a normal user. Fix: run it as root, and look for "permission denied" lines in the output to find the problem files.

It works by hand but not from cron

Symptom: the script works by hand, but the cron log shows "command not found". Likely cause: cron runs with a minimal environment, so restic may not be on its path. Fix: find the full path with command -v restic and use it in the script, for example /usr/bin/restic. Also note that cron turns an unescaped % into a new line, so escape it as \% if you ever add a date format to the cron line.

A few security notes

The files in /root/restic hold everything needed to read your backups and to delete them. Keep them at 600 or 700 and readable only by root. If your server is compromised, change the S3 key and think about whether the attacker could have read the repository password.

An attacker with root can also use that S3 key to delete snapshots, so if your provider offers object versioning or object lock, read its documentation and consider it.

When should you ask for help? If your database is very large, uses many MyISAM tables, or runs replication, talk to a developer or your host about the dump method before relying on this. And if you are about to change hosts, a fresh tested restic snapshot fits nicely into moving a website to a new host.

The one message worth forwarding

Here is a message you can send to whoever else looks after the site:

"Hi, I have set up nightly off-server backups of example.com with restic to our S3 bucket. Files and the database are backed up at 02:30, keeping 7 daily, 4 weekly and 6 monthly snapshots. The repository password is in our password manager under 'restic repo for example.com'. Without it the backups cannot be opened at all, so please do not delete that entry. I tested a restore today and it worked. The panel backups are still running as before, this is an extra copy. Logs are in /var/log/restic-backup.log."

The takeaway: an encrypted copy in another place, a password stored somewhere other than the server, and one restore you have actually done are what turn files on a disk into a backup.

Reader questions

What happens if I lose the restic repository password?

Your backups cannot be opened. The restic documentation states that losing the password means the data is irrecoverably lost, so keep a copy in a password manager off the server.

Does restic replace my control panel or host backups?

No. restic backs up the files and dumps you point it at, so keep your panel or host backups running and treat restic as an extra, independent copy.

Which restic version do I need for --stdin-from-command?

The option was added in restic 0.17.0. Older distribution packages lack it, so either install the official binary or dump the database to a file first and back up that file.

Does restic forget delete data from the bucket?

restic forget only removes snapshots. The unused data is deleted by restic prune, which you can run automatically by adding --prune to the forget command.

Can I back up several servers into one restic repository?

Yes, restic groups snapshots by host name and paths for retention. When restoring, filter with --host and --path, because the docs warn that latest may not be the snapshot you expect in a shared repository.

How much data does restic check --read-data-subset download?

It downloads the share you ask for, such as 10% of the pack files or a fixed size like 50M. That uses download bandwidth, so check your storage provider's charges.

Sources & further reading

  1. restic docs: Preparing a new repository
  2. restic docs: Backing up
  3. restic docs: Working with repositories
  4. restic docs: Restoring from backup
  5. restic docs: Removing backup snapshots
  6. restic docs: Installation
  7. restic docs: Scripting and exit codes
  8. restic changelog
  9. MySQL 8.4 manual: mysqldump
  10. MariaDB docs: mariadb-dump

What changed

Removed live database create/import/drop examples, required an isolated staging endpoint for full restore tests, removed the automated recursive-delete instruction, and added original article/social media.

Originally published . About our editorial updates.

Your next project deserves a better foundation.

Explore hosting built for your next chapter.

Explore hosting

Find your next answer.

Search published guides and articles.

Ctrl / ⌘ K to open · Esc to close