Quick Start¶
This guide will get you up and running. It was last tested on the 1st March 2023 with debian stable (restic v0.11.0, BASH v5.1.4)
In this guide we’ll do the following:
Define a location (a backup source)
Define a backend (a restic repository)
Run bashtic
Create a custom pipeline
Tidy up
Next moves
We’ll create a temporary restic repository so there’s no risk of harm to your existing repositories.
Prerequisites:
If you’ve not installed bashtic refer to our installation instructions.
The example code is all BASH, so we assume you are in a BASH shell.
Restic should also be installed of course.
Define a location¶
If we run bashtic straight after installation we’ll get an error:
$ bashtic
No location found at /home/you/.config/bashtic/locations/default
Bashtic requires configuration before it can do anything meaningful. The first step is to define a location which will be backed up. Locations described what is to be backed up and where it should be backed up to.
Let’s backup our home dir and make it the default location. We configure
bashtic’s default location by creating a file
$HOME/.config/bashtic/locations/default:
mkdir -p ~/.config/bashtic/locations
cat > ~/.config/bashtic/locations/default << EOF
from=("$HOME")
to=("localdir")
EOF
This configuration simply states that we backup from our $HOME to a backend
labelled localdir which we’ll define next. Note that both from and to are
BASH arrays so they can contain more than one entry. This allows us to backup
multiple directories to multiple backends.
For more information on configuring locations see locations.
Define a backend¶
If we run bashtic at this point it’ll complain again:
$ bashtic
No backend found at /home/you/.config/bashtic/backends/localdir
We need to configure the backend we referred to as ‘localdir’ in the location config above. Let’s do that now:
mkdir -p ~/.config/bashtic/backends
cat > ~/.config/bashtic/backends/localdir << EOF
type="local"
path="/tmp/bashtic_test_repo"
EOF
This configuration defines a local type of backend with the path
/tmp/bashtic_test_repo. So this backend will target a repository at this
location.
Let’s create a test repo where our configuration expects it:
restic init -r /tmp/bashtic_test_repo
You’ll need to remember the password for the next step but as this is a test it does not need to be long.
For more information on configuring backends see backends.
Run bashtic¶
We now ready to run a bashtic backup:
$ bashtic backup
enter password for repository:
repository 37f039c2 opened successfully, password is correct
created new cache in /home/you/.cache/restic
Files: 75 new, 0 changed, 0 unmodified
Dirs: 42 new, 0 changed, 0 unmodified
Added to the repo: 367.673 KiB
processed 75 files, 314.460 KiB in 0:00
snapshot 1c575225 saved
Congratulations this is your first backup with bashtic.
Let’s explain what just happened:
bashtic backup
This command asked bashtic to run a pipeline called ‘backup’. The is one of the built-in pipelines included with bashtic. There are two others:
forget
check
Go ahead and try these now. If you are familiar with restic you can guess what they will do. The forget pipeline should be safe as we have not defined any forget policy yet so restic will do nothing. A forget policy lives in the location configuration, see locations for more on that.
Let’s also try out the dry-run feature:
$ bashtic --dryrun backup
enter password for repository:
restic backup -r /tmp/bashtic_test_repo /home/you
Now bashtic logs the restic commands it would invoke, instead of running them. This is useful to ensure your configuration is correct without changing your repositories.
So far all bashtic has done is save us some typing at the cmdline. What else can we do?
Create a custom pipeline¶
Let’s imagine that after every backup we want to run a check as well. We could do this:
bashtic backup
bashtic check
However there’s a way to combine these steps in our own custom pipeline. Let’s do that now:
mkdir -p ~/.config/bashtic/pipelines
cat > ~/.config/bashtic/pipelines/mypipeline << EOF
bashtic_backup
bashtic_check
EOF
Here we create a pipeline called mypipeline with the config file
~/.config/bashtic/pipelines/mypipeline. The content is pure BASH. Bashtic
will run your pipeline in an environment that includes functions for you to call
that invoke the suggested restic operations. In this case we have specified:
bashtic_backup
bashtic_check
This simple pipeline will backup and then check the repo. Let’s ask bashtic to run this pipeline now:
$ bashtic mypipeline
enter password for repository:
repository 37f039c2 opened successfully, password is correct
Files: 1 new, 0 changed, 75 unmodified
Dirs: 1 new, 6 changed, 36 unmodified
Added to the repo: 7.330 KiB
processed 76 files, 314.488 KiB in 0:00
snapshot bc16b339 saved
using temporary cache in /tmp/restic-check-cache-458583489
repository 37f039c2 opened successfully, password is correct
created new cache in /tmp/restic-check-cache-458583489
create exclusive lock for repository
load indexes
check all packs
check snapshots, trees and blobs
no errors were found
Congratulations - now you can create whatever pipelines you need for your
workflow in pure BASH. Besides the bashtic_backup and bashtic_check
functions we used above you can also call the function bashtic_forget to run a
forget operation.
When developing your own pipelines don’t forget the dry-run feature to test your configuration:
$ bashtic --dryrun mypipeline
enter password for repository:
restic backup -r /tmp/bashtic_test_repo /home/you
restic check -r /tmp/bashtic_test_repo
Caution
Bashtic can only apply dry-run to its own functions, any custom BASH code in your pipeline will be executed as normal.
If you name your pipeline default then you don’t even need to name it
explicitly on the cmdline:
bashtic
You can also pass cmdline arguments to your custom pipeline by specifying them
after a -- separator:
bashtic -- arg1 arg2
There are infinite possibilities for what you put in your own pipelines, here are some ideas:
Check filesystems are mounted/unmounted before/after backups.
Stop system services that write to disk during backup and resume them on completion. Or abort the backup process if they can’t be interrupted.
Skip a backup if it’s been done recently.
Warn if a backend has not been backed up to recently.
Notify a desktop user a backup is underway/completed.
For more information on developing pipelines see pipelines.
Tidy up¶
If you’ve finished trying things out let’s get rid of the temporary repo:
rm -rf /tmp/bashtic_test_repo
If you also want to clear out the bashtic configuration we’ve created run the following command. Just be mindful if you’ve made your own alterations to save them first if needed:
rm -f ~/.config/bashtic/locations/default \
~/.config/bashtic/backends/localdir \
~/.config/bashtic/pipelines/mypipeline
Next moves¶
Thank you for getting this far. Some thoughts on what you might do next: