Restic/S3 Backup

This article describes the process of installing and configuring Restic to backup to an S3-compatible storage provider such as Backblaze B2, Wasabi, or Minio.

Requirements

Credentials for an S3-compatible storage provider, such as Backblaze B2, Wasabi, or Minio

Installation

Install app-backup/restic:

root #emerge --ask app-backup/restic

Configuration

Restic can use any S3-compatible storage provider as a storage backend.

Note
While Backblaze has its own B2 API for accessing object storage, it also supports the S3 API. Usage of the S3 API is recommended upstream due to deficiencies in the error-handling of the B2 backend module.

Credentials

Note
Credentials should be kept secure. Ensure that files containing backup credentials are only readable by the root user.

Create a file at /etc/restic/restic.env with the following contents:

FILE /etc/restic/restic.envrestic.env

export AWS_ACCESS_KEY_ID=<ACCESS_KEY_GOES_HERE>
export AWS_SECRET_ACCESS_KEY=<SECRET_ACCESS_KEY_GOES_HERE>

Any time that restic is invoked the contents of this file must be read into the environment so that credentials are available to the tool. This can be done by sourcing the file before invoking restic:

root #. /etc/restic/restic.env

A list of Restic environment variables is maintained here, any of these may be used to configure the behaviour of the tool. As an example, RESTIC_PASSWORD_FILE can be used to specify a file containing the password for the repository, while RESTIC_REPOSITORY can store the location of the repository.

Initialising a Repository

S3 Path-style URLs are expected by restic e.g. s3.us-west-2.amazonaws.com/bucket_name. Virtual-host-style URLs (bucket_name.s3.us-west-2.amazonaws.com), where the bucket name is part of the hostname, are not supported. These must be converted to path-style URLs instead.

Note
This example uses the S3 endpoint s3.us-east-005.backblazeb2.com with a bucket name of larry-nas-backup. Ensure that these are updated for a particular deployment, paying particular attention to the region.

Initialise the repository. If the bucket in question does not already exist (and the credentials provided have the appropriate privileges it), it will be created automatically.

root #restic -r s3:s3.us-east-005.backblazeb2.com/larry-nas-backup init

enter password for new repository:
enter password again:
created restic repository eefee03bbd at s3:s3.us-east-005.backblazeb2.com/larry-nas-backup

Please note that knowledge of your password is required to access the repository.
Losing your password means that your data is irrecoverably lost.

Note
If the selected S3 provider does not allow the region to be specified as part of the endpoint URI it may instead be set using the environment variable AWS_DEFAULT_REGION or by calling restic with an option parameter like -o s3.region="us-east-1" If the region is not specified, the default region is used. Afterwards, the S3 server (at least for AWS, s3.amazonaws.com) will redirect restic to the correct endpoint.

Backing up Files

The simplest invocation of a backup command is as follows:

root #restic -r s3:s3.us-east-005.backblazeb2.com/larry-nas-backup --verbose backup /data/@homes

open repository
enter password for repository:
repository eefee03bbd opened (version 2, compression level auto)
lock repository
no parent snapshot found, will read all files
load index files
start scan on [/data/@homes]
start backup on [/data/@homes]
scan finished in 2.545s: 6290 files, 21.695 GiB
[5:42] 4.55%  2696 files 1010.249 MiB, total 6290 files 21.695 GiB, 0 errors ETA 2:47:32

As there is no built-in daemon / timer support, automating backups on a schedule is left as an exercise to the reader. Systemd timers or Cron jobs are both suitable options.