Restic Backup Tool

What it is

Restic is a fast, secure, and efficient backup program that makes it easy to save your data to cloud storage or local disks. You reach for it when you need a reliable way to back up your files and directories, with features like deduplication, encryption, and snapshot management.

Installation

Linux

# Using apt (Debian/Ubuntu)
sudo apt update
sudo apt install restic

# Using dnf (Fedora/CentOS/RHEL)
sudo dnf install restic

# Using pacman (Arch Linux)
sudo pacman -S restic

# From binary (recommended for latest version)
# Check https://restic.net/docs/introduction/installation/ for latest version
LATEST_VERSION="0.16.4" # Replace with the actual latest version
curl -L "https://github.com/restic/restic/releases/download/v${LATEST_VERSION}/restic_${LATEST_VERSION}_linux_amd64.bz2" | bunzip2 | sudo tee /usr/local/bin/restic > /dev/null
sudo chmod +x /usr/local/bin/restic

macOS

# Using Homebrew
brew install restic

# From binary (recommended for latest version)
# Check https://restic.net/docs/introduction/installation/ for latest version
LATEST_VERSION="0.16.4" # Replace with the actual latest version
curl -L "https://github.com/restic/restic/releases/download/v${LATEST_VERSION}/restic_${LATEST_VERSION}_darwin_amd64.bz2" | bunzip2 | sudo tee /usr/local/bin/restic > /dev/null
sudo chmod +x /usr/local/bin/restic

Windows

Download the appropriate .exe file from the Restic releases page. Place the executable in a directory that is in your system’s PATH.

Core Concepts

• Repository: The central location where Restic stores your backup data. This can be a local directory, an SFTP server, an S3-compatible object storage, or other backends.
• Snapshot: A snapshot represents a backup of your data at a specific point in time. Restic creates a new snapshot for each backup operation.
• Deduplication: Restic breaks data into chunks and stores each unique chunk only once. This significantly saves space, especially for subsequent backups where much of the data might be unchanged.
• Encryption: Restic encrypts all data before it leaves your machine. You must set a password or use a key file to access your repository.

Commands / Usage

Repository Management

Initialize a new repository

# For local directory backend
restic init --repo /path/to/my/backup/repo

# For SFTP backend
restic init --repo sftp:user@host:/path/to/remote/repo

# For S3 backend
restic init --repo s3:s3.amazonaws.com/my-bucket/my-repo

Initializes a new backup repository at the specified location.

Set repository location (environment variable)

# For local directory
export RESTIC_REPOSITORY=/path/to/my/backup/repo

# For SFTP
export RESTIC_REPOSITORY=sftp:user@host:/path/to/remote/repo

# For S3
export RESTIC_REPOSITORY=s3:s3.amazonaws.com/my-bucket/my-repo

Sets the repository location for subsequent commands, avoiding the need for --repo flag.

Set repository password (environment variable)

export RESTIC_PASSWORD='your_strong_password'
# or
export RESTIC_PASSWORD_FILE=/path/to/password/file

Sets the password for accessing the repository. Using RESTIC_PASSWORD_FILE is generally more secure.

List repositories (if using a backend that supports listing)

# Example for S3 backend
restic ls s3:s3.amazonaws.com/my-bucket/ --recursive

Lists directories and files within a repository backend.

Backing Up Data

Back up specific directories and files

restic backup /home/user/Documents /home/user/Pictures

Creates a new snapshot of the specified directories and files.

Back up with a tag

restic backup --tag important /home/user/data

Creates a snapshot and assigns the tag "important" to it for easier filtering later.

Back up with a snapshot name

restic backup --message "Backup of project X before major refactor" /srv/projectX

Creates a snapshot and attaches a descriptive message to it.

Back up excluding specific patterns

restic backup --exclude '*.tmp' --exclude '/home/user/Downloads/*.iso' /home/user

Creates a snapshot, excluding files matching the given patterns. Patterns can be file paths or glob patterns.

Back up excluding files from a file

restic backup --exclude-file /home/user/.resticignore /home/user

Creates a snapshot, excluding files listed in the specified file. The format of the file is one pattern per line.

Back up with a specific snapshot ID (for resuming interrupted backups)

restic backup --parent <snapshot-id> /path/to/backup

Creates a new snapshot based on an existing one, useful for incremental backups or resuming interrupted operations.

Restoring Data

List available snapshots

restic snapshots

Lists all snapshots in the repository with their IDs, dates, and tags.

Restore a specific snapshot to a directory

restic restore <snapshot-id> --target /path/to/restore/location

Restores the contents of the specified snapshot to the target directory.

Restore the latest snapshot

restic restore latest --target /path/to/restore/location

Restores the contents of the most recent snapshot to the target directory.

Restore a specific file or directory from a snapshot

restic restore <snapshot-id> --target /path/to/restore/location --include /home/user/Documents/important.txt

Restores only the specified file or directory from the snapshot.

Restore files matching a pattern

restic restore <snapshot-id> --target /path/to/restore/location --include-from /path/to/includes.txt

Restores files that match the patterns specified in the file.

Snapshot Management

Check repository integrity

restic check

Verifies the integrity of the repository data and index.

Prune old snapshots (free up space)

# Keep last 5 snapshots
restic forget --keep-last 5 --prune

# Keep daily snapshots for 7 days, weekly for 4 weeks, monthly for 6 months
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

# Keep snapshots with a specific tag
restic forget --tag old --prune

# Keep snapshots older than 30 days
restic forget --keep-time 30d --prune

Removes snapshots based on specified retention policies and then prunes the unreferenced data from the repository.

Remove a specific snapshot

restic delete <snapshot-id>

Permanently removes a specific snapshot from the repository. This does not immediately free up disk space; prune must be run afterward.

Mount a snapshot as a filesystem

restic mount /path/to/mountpoint

Mounts the latest snapshot as a virtual filesystem at the specified mountpoint. This is read-only.

Repository Information

Show repository statistics

restic stats

Displays statistics about the repository, including total size, unique size, and number of snapshots.

Show information about a specific snapshot

restic stats <snapshot-id>

Displays detailed statistics about a particular snapshot.

Show repository backend details

restic cat config

Displays the configuration of the repository.

Common Patterns

Automating Backups with Cron (Linux/macOS)

Create a script (e.g., backup.sh):

#!/bin/bash

export RESTIC_REPOSITORY=/mnt/backups/restic-repo
export RESTIC_PASSWORD_FILE=/home/user/.restic_password

restic backup /home/user/Documents \
              /home/user/Projects \
              --exclude '/home/user/Projects/node_modules' \
              --tag automatic \
              --message "Automated backup run on $(date +%Y-%m-%d_%H:%M:%S)"

# Optional: Prune old snapshots to save space
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

Make it executable: chmod +x backup.sh Add to cron: crontab -e and add a line like:

0 3 * * * /path/to/your/backup.sh >> /var/log/restic_backup.log 2>&1

This runs the backup script every day at 3 AM and logs output.

Backing up to an external drive and then syncing to cloud

# Backup to local external drive
export RESTIC_REPOSITORY=/media/user/ExternalDrive/restic-repo
export RESTIC_PASSWORD='your_password'
restic backup /home/user/Documents

# Later, sync the repository to cloud storage (e.g., S3)
export RESTIC_REPOSITORY=s3:s3.amazonaws.com/my-bucket/restic-repo
export RESTIC_PASSWORD='your_password'
restic backup /media/user/ExternalDrive/restic-repo # This will only upload new/changed chunks

This pattern allows for local quick backups and then a separate process to sync the repository (not the original data) to a remote location.

Restoring a single file

restic restore latest --target . --include /home/user/Documents/important_document.pdf

Restores just important_document.pdf from the latest snapshot into the current directory (.).

Viewing the contents of a snapshot

# Mount the latest snapshot
mkdir /tmp/restic_mount
restic mount /tmp/restic_mount
ls /tmp/restic_mount/home/user/Documents
# Unmount when done
fusermount -u /tmp/restic_mount

This allows you to browse the contents of a snapshot as if it were a regular directory.

Gotchas

• Repository Initialization: You must initialize a repository before you can back up to it.
• Password Security: Never commit your RESTIC_PASSWORD directly into scripts or version control. Use environment variables or, preferably, RESTIC_PASSWORD_FILE.
• Backend Credentials: For cloud backends (S3, Azure, Google Cloud, etc.), ensure your credentials (API keys, access tokens, etc.) are configured correctly in your environment. Restic relies on standard cloud SDK environment variables (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).
• --prune is Crucial: forget only marks snapshots for deletion. You must run restic prune (or use the --prune flag with forget) to actually remove the data and free up space in the repository.
• SFTP Root Directory: When using SFTP, restic init --repo sftp:user@host:/path/to/repo will create the repo directory if it doesn’t exist. If you provide a path that already contains files, Restic might not be able to initialize correctly. Ensure the target path is empty or create it beforehand.
• Data Location: Restic backs up the paths you specify. If you back up /home/user, it will store files relative to /home/user within the snapshot. When restoring, it will recreate this structure relative to your --target directory.
• Interrupted Backups: If a backup is interrupted, Restic can often resume from the last successful state if you run the backup command again with the same parameters. Using --parent <snapshot-id> can sometimes help, but usually just re-running the same command is sufficient.
• restic mount: This uses FUSE. Ensure FUSE is installed and working on your system. It’s read-only.
• restic check Performance: restic check can be very I/O intensive, especially on large repositories. Run it during off-peak hours if necessary.
• Unique Chunk Storage: Restic’s deduplication means that if you back up the same data multiple times to different repositories, each repository will store the data independently. Deduplication works within a single repository.