Crestic - configurable Restic

This is a slim configuration wrapper for Restic, a pretty awesome backup tool.

Why? Because restic is unfortunately still missing config files.

Usage

This tool does not try to be clever, it simply maps any commandline options for restic to a key in an config file.

For example, to use restic to back up your home directory with a password and an exclude-file, you would use

restic backup \
    --repo sftp:your_server:my_computer.restic \
    --password-file ~/.config/restic/password \
    --exclude-file ~/.config/restic/excludes \
    ~

With crestic, you can set all these values in a config file

[home]
repo: sftp:your_server:my_computer.restic
password-file: ~/.config/restic/password

[home.backup]
exclude-file: ~/.config/restic/excludes
arguments: ~

and then call one simple command

crestic home backup

More advanced usage examples can be found further down this file.

Installation

Just install it using pip

pip install crestic

or download crestic into your $PATH

curl https://raw.githubusercontent.com/nils-werner/crestic/master/crestic.py --output ~/.local/bin/crestic
chmod +x ~/.local/bin/crestic

Config File Detection

The following locations are used in descending order of importance:

• environment variable $CRESTIC_CONFIG_FILE, a single filename
• environment variable $CRESTIC_CONFIG_PATHS, a colon separated list of directories containing a file crestic.cfg
• ~/.config/crestic/crestic.cfg
• /etc/crestic.cfg

crestic may also optionally use appdirs to automatically pick up config files from platform-dependent locations. This is especially useful on macOS or Windows. Just install appdirs

pip install appdirs

Requirements

Plain Python 3.6+ on a UNIX system. Nothing else.

Python 3.7+ is required for certain arguments.

Debugging

If you set the environment variable $CRESTIC_DRYRUN, crestic will not run restic but instead output

• the config files in use
• the config sections in use
• the final command

env CRESTIC_DRYRUN=1 crestic home backup

will print

             Warning: Executing in debug mode. restic will not run, backups are not touched!
        Config files: examples/multiple_presets.cfg
   Config files used: examples/multiple_presets.cfg
     Config sections: global, global.backup, home, home.backup
Config sections used: global, global.backup
        Env sections: global.environ, global.backup.environ, home.environ, home.backup.environ
   Env sections used:
    Expanded command: restic backup --password-file ~/.config/restic/password --exclude-file ~/.config/restic/excludes --exclude config.py --exclude passwords.txt

Config File Parsing

On the commandline, crestic commands follow the syntax

crestic preset command [--options, ...]

Where preset is a preset key in the config file, and command is the restic command.

Crestic config keys follow the convention

[preset]
[preset.command]

where preset and command are the preset and command names from above. For example

[home]
...
[home.backup]
...

are read for crestic home backup calls.

There exist a few special config keys:

• [global] is a special pseudo preset which is always read before any actual preset value.
• [global.command] is a special pseudo command which is always read before any actual preset command. These two keys can be used to set global values, valid for any preset, i.e. a password-file
• [global.environ], [preset.environ], [global.command.environ] and [preset.command.environ] are special pseudo commands which are used to set environment variables for the restic command. They are usually used to set cloud provider credentials.

Config keys are always read in the following order, of ascending importance. Later values override earlier ones:

1. [global]
2. [global.command]
3. [preset]
4. [preset.command]
5. options from the commandline

Advanced Usage

Multiple preset

crestic allows multiple presets per config file, so you can define config files

[global]
password-file: ~/.config/restic/password

[global]
repo: sftp:your_server:my_computer.restic

[global.backup]
exclude-file: ~/.config/restic/excludes

[home.backup]
arguments: ~

[work.backup]
arguments: ~/work

Which can be used as crestic home backup and crestic work backup

See examples/multiple_presets.cfg for a more complicated example with multiple repos and directories and forgetting rules.

Split preset

crestic allows for so-called split presets. These split presets are in the format of prefix@suffix and are usually used to separate local location values from remote repo locations, i.e. location@repo.

Using this techique you can back up several locations on your machine to several remote repositories, i.e. a home and a work location to a disk and a cloud repo

crestic home@disk backup
crestic home@cloud backup
crestic work@disk backup
crestic work@cloud backup

To use these split presets, simply define location keys with an @ suffix

[home@.backup]
arguments: ~

[work@.backup]
arguments: ~/work

and repo keys with an @ prefix

[@disk]
repo: /Volumes/Backup

[@cloud]
repo: b2:bucketname:my_computer.restic

[@cloud.environ]
B2_ACCOUNT_ID: <MY_APPLICATION_KEY_ID>
B2_ACCOUNT_KEY: <MY_APPLICATION_KEY>

Split config keys are always read in the following order, of ascending importance. Later values override earlier ones:

1. [global]
2. [global.command]
3. [@repo]
4. [@repo.command]
5. [location@]
6. [location@.command]
7. [location@repo]
8. [location@repo.command]
9. options from the commandline

See examples/split_presets.cfg for a complete example of location@repo split presets.

Automated Backups

Make sure to adjust the path to the crestic executable in the following sections.

Linux/systemd

For daily user backups using systemd timers, create a file ~/.config/systemd/user/crestic@.service

[Unit]
Description=crestic %I backup

[Service]
Nice=19
IOSchedulingClass=idle
KillSignal=SIGINT
ExecStart=/usr/bin/crestic %I backup

and a file ~/.config/systemd/user/crestic@.timer

[Unit]
Description=Daily crestic %I backup

[Timer]
OnCalendar=daily
AccuracySec=1m
RandomizedDelaySec=1h
Persistent=true

[Install]
WantedBy=timers.target

then activate the timer for your crestic preset, i.e. for home@nas

systemctl --user enable --now crestic@home@nas.timer

For system backups, put these files in /etc/systemd/system and the config in /etc/crestic.cfg

Also see the Arch Linux package for a working solution including systemd timers.

macOS/launchctl

For daily user backups using launchctl timers, i.e. for the home@nas preset, create a file ~/Library/LaunchAgents/local.crestic.home@nas.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Daily crestic home@nas backup</key>
    <string>local.crestic.home@nas</string>
    <key>ProgramArguments</key>
    <array>
        <string>crestic</string>
        <string>home@nas</string>
        <string>backup</string>
    </array>
    <key>StartInterval</key>
    <integer>86400</integer>
</dict>
</plist>

then activate the timer

launchctl load ~/Library/LaunchAgents/local.crestic.home@nas.plist

For system backups, put this file in /Library/LaunchAgents and the config in /etc/crestic.cfg