开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

Automatic restic Backups using Native OS Task Schedulers

formerly named restic-systemd-automatic-backup

including these top contributors:

Intro

restic is a command-line tool for making backups, the right way. Check the official website for a feature explanation. As a storage backend, I recommend Backblaze B2 as restic works well with it, and it is (at the time of writing) very affordable for the hobbyist hacker! (anecdotal: I pay for my full-systems backups each month typically < 1 USD).

Unfortunately restic does not come pre-configured with a way to run automated backups, say every day. However it's possible to set this up yourself using built-in tools in your OS and some wrappers. For Linux with systemd, it's convenient to use systemd timers. For macOS systems, we can use built-in LaunchAgents. For Windows we can use ScheduledTasks. Any OS having something cron-like will also work!

Here follows a step-by step tutorial on how to set it up, with my sample script and configurations that you can modify to suit your needs.

Note, you can use any restic's supported storage backends. The setup should be similar but you will have to use other configuration variables to match your backend of choice.

Project Scope

The scope for this is not to be a full-fledged super solution that solves all the problems and all possible setups. The aim is to be a hackable code base for you to start sewing up the perfect backup solution that fits your requirements!

Nevertheless the project should work out of the box, be minimal but still open the doors for configuration and extensions by users.

To use a different storage backend than B2, you should only need to tweak a few settings variables in the backup profile as well as some restic arguments inside restic_backup.sh.

Notes

• Tip: Navigate this document easily from the Section icon in the top left corner.
• ☝ Note: in the command listing in this document, $ means a user shell and # means a root shell (or use sudo).

Requirements

• restic >=v0.9.6
• bash >=v4.0.0
• (recommended) GNU make if you want an automated install
  • Arch: part of the base-devel meta package, Debian/Ubuntu: part of the build-essential meta package, macOS: use the pre-installed or a more recent with Homebrew

Setup

Depending on your system, the setup will look different. Choose one of:

• Linux + Systemd
• macOS + LaunchAgent
• Windows + ScheduledTask
• Cron - for any system having a cron daemon. Tested on FreeBSD and macOS.

Setup Linux Systemd

☝ Note The Linux setup here will assume an installation to /.

Many Linux distributions nowadays use Systemd, which features good support for running services and scheduled jobs. If your distribution is no on Systemd, check out the cron setup instead.

TL;DR setup

1. Create B2 bucket + credentials
2. Install scripts, configs systemd units/timers:
   • With make:

   $ sudo make install-systemd

   • Arch Linux users: use the AUR package, e.g.

   $ yay -S restic-automatic-backup-scheduler

3. Fill out configuration values in /etc/restic.
4. Initialize the remote repo. Source the profile to make all needed configuration available to restic(1). All commands after this assumes the profile is sourced in the current shell.

    # source /etc/restic/default.env.sh
    # restic init

5. Configure how often backups should be done.
   • If needed, edit OnCalendar in /usr/lib/systemd/system/[email protected].
6. Enable automated backup for starting with the system & make the first backup:

   # systemctl enable --now [email protected]

7. Watch the first backup progress with Systemd journal:

   # journalctl -f --lines=50 -u restic-backup@default

8. Verify the backup

   # restic snapshots

9. (recommended) Enable the check job that verifies that the backups for the profile are all intact.

   # systemctl enable --now [email protected]

10. (optional) Define multiple profiles: just make a copy of the default.env.sh and use the defined profile name in place of default to run backups or enable timers. Notice that the value after @ works as a parameter.

    # systemctl enable restic-backup@other_profile.timer

11. Consider more optional features.

Setup macOS LaunchAgent

☝ Note The macOS setup here will assume a Homebrew installation to the recommended default location. This is $HOMEBREW_PREFIX (brew --prefix) , which is /usr/local on Intel Macs and /opt/homebrew on Apple Silicon.

Launchd is the modern built-in service scheduler in macOS. It has support for running services as root (Daemon) or as a normal user (Agent). Here we set up a LaunchAgent to be run as your normal user for starting regular backups.

TL;DR setup

1. Create B2 bucket + credentials
2. Install scripts, configs and LaunchAgent:
   • (recommended) with Homebrew from the erikw/homebrew-tap:

    $ brew install erikw/tap/restic-automatic-backup-scheduler

   • Using make:

    $ make PREFIX=$(brew --prefix) install-launchagent

3. Fill out configuration values in $(brew --prefix)/etc/restic.
4. Initialize the remote repo. Source the profile to make all needed configuration available to restic(1). All commands after this assumes the profile is sourced in the current shell.

    $ source $(brew --prefix)/etc/restic/default.env.sh
    $ restic init

5. Configure how often backups should be done. If needed, edit OnCalendar in
   • Homebrew install: ~/Library/LaunchAgents/homebrew.mxcl.restic-automatic-backup-scheduler.plist.
   • make install: ~/Library/LaunchAgents/com.github.erikw.restic-backup.plist.
6. Enable automated backup for starting with the system & make the first backup:
   • Homebrew install:

   $ brew services start restic-automatic-backup-scheduler

   • make install:

   $ launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.github.erikw.restic-backup.plist
   $ launchctl enable gui/$UID/com.github.erikw.restic-backup
   $ launchctl kickstart -p gui/$UID/com.github.erikw.restic-backup

   As a convenience, a shortcut for the above commands are $ make activate-launchagent-backup.
7. Watch the first backup progress from the log files:

   $ tail -f ~/Library/Logs/restic/backup*

8. Verify the backup

   $ restic snapshots

9. (recommended) Enable the check job that verifies that the backups for the profile are all intact.
   • Homebrew install:

   $ brew services start restic-automatic-backup-scheduler-check

   • make install:

   $ launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.github.erikw.restic-check.plist
   $ launchctl enable gui/$UID/com.github.erikw.restic-check
   $ launchctl kickstart -p gui/$UID/com.github.erikw.restic-check

   As a convenience, a shortcut for the above commands are $ make activate-launchagent-check.
10. Consider more optional features.

Homebrew Setup Notes

Then control the service with homebrew:

$ brew services start restic-automatic-backup-scheduler
$ brew services restart restic-automatic-backup-scheduler
$ brew services stop restic-automatic-backup-scheduler

If services start fails, it might be due to previous version installed. In that case remove the existing version and try again:

$ launchctl bootout gui/$UID/com.github.erikw.restic-backup
$ brew services start restic-automatic-backup-scheduler

Make Setup Notes

Use the disable command to temporarily pause the agent, or bootout to uninstall it.

$ launchctl disable gui/$UID/com.github.erikw.restic-backup
$ launchctl bootout gui/$UID/com.github.erikw.restic-backup

If you updated the .plist file, you need to issue the bootout followed by bootrstrap and enable sub-commands of launchctl. This will guarantee that the file is properly reloaded.

Setup Windows ScheduledTask

Windows comes with a built-in task scheduler called ScheduledTask. The frontend app is "Task Scheduler" (taskschd.msc) and we can use PowerShell commands to install a new scheduled task.

I describe here one of may ways you can get restic and this backup script working on Windows. Here I chose to work with scoop and git-bash.

TL;DR setup

1. Install scoop
2. Install dependencies from a PowerShell with administrator privileges:

    powershell> scoop install restic make git

3. In a non-privileged PowerShell, start git-bash and clone this repo

    powershell> git-bash
    git-bash$ mkdir ~/src && cd ~/src/
    git-bash$ git clone https://github.com/erikw/restic-automatic-backup-scheduler.git && cd $(basename "$_" .git)

4. Install scripts, configs and ScheduledTasks

    git-bash$ make install-schedtask

5. Fill out configuration values in /etc/restic.

    git-bash$ vim /etc/restic/*

   Note that you should use cygwin/git-bash paths. E.g. in default.env.sh you could have

    export RESTIC_BACKUP_PATHS='/c/Users/<username>/My Documents'

6. Initialize the remote repo. Source the profile to make all needed configuration available to restic(1). All commands after this assumes the profile is sourced in the current shell.

    git-bash$ source /etc/restic/default.env.sh
    git-bash$ restic init

7. Make the first backup

    git-bash$ restic_backup.sh

8. Verify the backup

    git-bash$ restic snapshots

9. Inspect the installed ScheduledTasks and make a test run
   1. Open the app "Task Scheduler" (taskschd.msc)
   2. Go to the local "Task Scheduler Library"
   3. Right click on one of the newly installed tasks e.g. restic_backup and click "run".
      • If the tasks are not there, maybe you opended it up before make install-schedtask: just close and start it again to refresh.
   4. Now a git-bash window should open running restic_backup.sh, and the next time the configured schedule hits!
10. Consider more optional features.

With taskschd.msc you can easily start, stop, delete and configure the scheduled tasks to your liking:

Setup Cron

☝ Note There are many different cron implementations out there and they all work slightly different.

Any system that has a cron-like system can easily setup restic backups as well. However if you system supports any of the previous setups, those are recommended over cron as they provide more features and reliability for your backups.

TL;DR setup

1. Create B2 bucket + credentials
2. Install scripts, configs systemd units/timers:

   $ sudo make install-cron

   • This assumes that your cron supports dropping files into /etc/cron.d/. If that is not the case, simply copy the relevant contents of the installed /etc/cron.d/restic in to your /etc/crontab.

   # grep "^@.*restic_" /etc/cron.d/restic >> /etc/crontab

3. Fill out configuration values in /etc/restic.
4. Initialize the remote repo. Source the profile to make all needed configuration available to restic(1). All commands after this assumes the profile is sourced in the current shell.

    # source /etc/restic/default.env.sh
    # restic init

5. Make the first backup

    # restic_backup.sh

6. Verify the backup

   # restic snapshots

7. Configure how often backups should be done by directly editing /etc/cron.d/restic (or /etc/crontab).
8. Consider more optional features.

Detailed Manual Setup

This is a more detailed explanation than the TL;DR sections above that will give you more understanding in the setup. This section is more general, but uses Linux + Systemd as the example setup.

0. Clone Repo

$ git clone https://github.com/erikw/restic-automatic-backup-scheduler.git && cd $(basename "$_" .git)

Make a quick search-and-replace in the source files:

$ find etc bin -type f -exec sed -i.bak -e 's|$INSTALL_PREFIX||g' {} \; -exec rm {}.bak \;

and you should now see that all files have been changed like e.g.

-export RESTIC_PASSWORD_FILE="$INSTALL_PREFIX/etc/restic/pw.txt"
+export RESTIC_PASSWORD_FILE="/etc/restic/pw.txt"

Why? The OS specific TL;DR setups above all use the Makefile or a package manager to install these files. The placeholder string $INSTALL_PREFIX is in the source files for portability reasons, so that the Makefile can support all different operating systems. make users can set a different $PREFIX when installing like PREFIX=/usr/local make install-systemd.

In this detailed manual setup we will copy all files manually to /etcand /bin. Thus we need to remove the placeholder string $INSTALL_PREFIX in the source files as a first step.

1. Create Backblaze B2 Account, Bucket and Keys

In short:

1. Create a Backblaze account (use 2FA!).
2. Create a new B2 bucket.
   • Private, without B2 encryption and without the object lock feature
3. Create a pair of keyId and applicationKey
   • Limit scope of the new id and key pair to only the above created bucket.

First, see this official Backblaze tutorial on restic, and follow the instructions ("Create Backblaze account with B2 enabled") there on how to create a new B2 bucket. In general, you'd want a private bucket, without B2 encryption (restic does the encryption client side for us) and without the object lock feature.

For restic to be able to connect to your bucket, you want to in the B2 settings create a pair of keyID and applicationKey. It's a good idea to create a separate pair of ID and Key with for each bucket that you will use, with limited read&write access to only that bucket.

2. Configure B2 Credentials Locally

Put these files in /etc/restic/:

• _global.env.sh: Fill this file out with your global settings including B2 keyID & applicationKey.
• default.env.sh: This is the default profile. Fill this out with bucket name, backup paths and retention policy. This file sources _global.env.sh and is thus self-contained and can be sourced in the shell when you want to issue some manual restic commands. For example:

  $ source /etc/restic/default.env.sh
  $ restic snapshots    # You don't have to supply all parameters like --repo, as they are now in your environment!

• pw.txt: This file should contain the restic password (single line) used to encrypt the repository. This is a new password what soon will be used when initializing the new repository. It should be unique to this restic backup repository and is needed for restoring from it. Don't re-use your B2 login password, this should be different. For example you can generate a 128 character password (must all be on one line) with:

  $ openssl rand -base64 128 | tr -d '\n' > /etc/restic/pw.txt

• backup_exclude.txt: List of file patterns to ignore. This will trim down your backup size and the speed of the backup a lot when done properly!

3. Initialize remote repo

Now we must initialize the repository on the remote end:

$ sudo -i
# source /etc/restic/default.env.sh
# restic init

4. Script for doing the backup

Put this file in /bin:

• restic_backup.sh: A script that defines how to run the backup. The intention is that you should not need to edit this script yourself, but be able to control everything from the *.env.sh profiles.

Restic support exclude files. They list file pattern paths to exclude from you backups, files that just occupy storage space, backup-time, network and money. restic_backup.sh allows for a few different exclude files.

• /etc/restic/backup_exclude.txt - global exclude list. You can use only this one if your setup is easy. This is set in _global.env.sh. If you need a different file for another profile, you can override the envvar RESTIC_BACKUP_EXCLUDE_FILE in this profile.
• .backup_exclude.txt per backup path. If you have e.g. an USB disk mounted at /mnt/media and this path is included in the $RESTIC_BACKUP_PATHS, you can place a file /mnt/media/.backup_exclude.txt and it will automatically picked up. The nice thing about this is that the backup paths are self-contained in terms of what they shoud exclude!

5. Make first backup

Now see if the backup itself works, by running as root

# source /etc/restic/default.env.sh
# /bin/restic_backup.sh

6. Verify the backup

As the default.env.sh is already sourced in your root shell, you can now just list the snapshost

# restic snapshots

Alternatively you can mount the restic snapshots to a directory set /mnt/restic

# restic mount /mnt/restic
# ls /mnt/restic

7. Backup automatically

All OS setups differs in what task scheduler they use. As a demonstration, let's look at how we can do this with systemd under Linux here.

Put these files in /etc/systemd/system (note that the Makefile installs as package to /usr/lib/systemd/system)

• [email protected]: A service that calls the backup script with the specified profile. The profile is specified by the value after @ when running it (see below).
• [email protected]: A timer that starts the former backup every day (same thing about profile here).
  • If needed, edit this file to configure how often back up should be made. See the OnCalendar key in the file.

Now simply enable the timer with:

# systemctl enable --now [email protected]

You can see when your next backup is scheduled to run with

# systemctl list-timers | grep restic

and see the status of a currently running backup with:

# systemctl status restic-backup

or start a backup manually:

$ systemctl start restic-backup@default

You can follow the backup stdout output live as backup is running with:

$ journalctl -f -u [email protected]

(skip -f to see all backups that has run)

Recommended: Automated Backup Checks

Once in a while it can be good to do a health check of the remote repository, to make sure it's