How I configure borgbackup and borgmatic

October 2, 2023

This article outlines how I configure borgbackup and borgmatic on my machines.


Tested on

Unlike systemd, launchctl does not have a syslog-like service. (I guess we are expected to use Console instead)

If you want to redirect borgmatic’s stdout and stderr to a $PREFIX/var/log/borgmatic/{stdout,stderr}.log file, I recommend wrapping borgmatic in a helper script like the following, which I have put in $HOME/.local/bin/

set -e
/opt/local/bin/borgmatic create prune -v2 \
  2> >(/opt/local/bin/ts -m '[%Y-%m-%d %H:%M:%S] -' 1>&2) \
  1> >(/opt/local/bin/ts -m '[%Y-%m-%d %H:%M:%S] -')

Create a LaunchAgent in $HOME/Library/LaunchAgents/net.yourdomain.yourprogram.plist like so:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">
<plist version="1.0">

Activate using

launchctl bootstrap "gui/$EUID" "$HOME/Library/LaunchAgents/net.yourdomain.yourprogram.plist"

This will allow you to run borgmatic at the beginning of every hour. If you want to run it immediately, you can kickstart it using

launchctl kickstart gui/501/net.yourdomain.yourprogram.plist

This blog post is pretty helpful in explaining the new bootstrap syntax compared to the legacy load syntax using launchctl.

Restoring Files

Here’s a shortcut that you can use in fish to extract a file: (in this example, /etc/profile)

borgmatic extract \
  --repository "$YOUR_REPOSITORY" \
  --archive (borgmatic --no-color rlist --short --repository borgbase | fzf) \
  --path /etc/profile

This example uses fzf to allow us to select a specific archive. That way we can get a macOS Time Machine-like date selection, as a TUI.

Exporting keys to paper


borgmatic key export --paper

to get all keys for all repositories in an easy to print and manually copy format.

Validating a backup

You can stream a tar ball containing backed up data using export-tar like so:

borgmatic export-tar \
  --repository $REPOSITORY \
  --archive $ARCHIVE \
  --destination - | \
  gtar --compare --file=- -C /

This will use gnu tar (installed with MacPorts as gnutar) to compare the files in the piped tar ball to what is in our file system.


There are some configuration YAML files. Perhaps I will write about this some other time.


I shall write more about it here, thank you for reading this far.

I would be thrilled to hear from you! Please share your thoughts and ideas with me via email.

Back to Index