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 doesn’t have a syslog-like service. (I guess Apple expects you 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 .plist file configures borgmatic to run at the beginning of every hour. If you want to run borgmatic 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 select a specific archive. That way you 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 a printable ASCII format. You can print this file and recover your keys if you lose it.

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 uses gnu tar (installed with MacPorts as gnutar) to compare the files in the piped tar ball to what’s stored on your filesystem.

Configuration

You can configure Borgmatic using a YAML file. I plan to write about this some other time.

Debian

I plan to write more about using BorgBackup on Debian here, thank you for reading this far.