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

Why? Because restic is unfortunately still missing config files.

The goal of crestic is to make running restic easy, e.g. creating backups using

crestic home backup

instead of running complex restic commands

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

To achieve this, this tool does not try to be clever, it simply maps any commandline options for restic to a key in an config file:

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

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

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

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

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

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

Python 3.7+ is required for certain arguments.

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

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

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.

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

[[email protected]]
arguments: ~

[[email protected]]
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. [[email protected]]
7. [location@repo]
8. [[email protected]]
9. options from the commandline

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

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

For daily user backups using systemd timers, create a file ~/.config/systemd/user/[email protected]

[Unit]
Description=crestic %I backup

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

and a file ~/.config/systemd/user/[email protected]

[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@[email protected]

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.

For daily user backups using launchctl timers, i.e. for the home@nas preset, create a file ~/Library/LaunchAgents/[email protected]

<?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/[email protected]

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