How I configure borgbackup and borgmatic

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

macOS

Tested on

MacBook Air M2
macOS Ventura 13.4.1
borgmatic 1.7.12 (MacPorts)
moreutils 0.67_1 (MacPorts)

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/borgmatic_timestamp.sh:

#!/bin/bash
# https://apple.stackexchange.com/a/406097
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" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>net.yourdomain.yourpgraom</string>
    <key>ProgramArguments</key>
    <array>
      <string>/Users/$USER/.local/bin/borgmatic_timestamp.sh</string>
    </array>
    <key>UserName</key>
    <string>$USER</string>
    <key>StartCalendarInterval</key>
    <dict>
      <key>Minute</key>
      <integer>0</integer>
    </dict>
    <key>StandardOutPath</key>
    <string>/Users/$USER/.local/var/log/borgmatic.stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/$USER/.local/var/log/borgmatic.stderr.log</string>
    <key>EnvironmentVariables</key>
    <dict>
      <key>HOME</key>
      <string>/Users/$USER</string>
    </dict>
    <key>TimeOut</key>
    <integer>1800</integer>
  </dict>
</plist>

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

Run

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 \
  --path $PATH_YOU_WANT_TO_TEST \
  --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.

Configuration

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

Debian

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