BorgStack

Organizing Borg archives the easy way.

Why would you need this?

If you are like me, you collect tons of photos and videos over your lifetime. Creating backups to preserve your precious memories makes sense. Therefore, you could consider BorgBackup. Using it is really easy.

Keeping your Borg archives organized, however, is not.

BorgStack helps you here.

How?

Instead of mounting archives one by one, BorgStack enables you to mount many archives at once and stack them up into a single coherent view of your backup. This way, handling differential backups is easy.

Additionally, using a clear naming scheme, creating properly named archives is made really simple.

By using OverlayFS here, we brought the flexibility from good old rsync to Borg. And still, you benefit from all the features of Borg such as encryption, compression and integrity checking.

Usage

Watch out for the *. It's the power of BorgStack when creating new Borg archives.

me@here:~$ # year 1 - first backup
me@here:~$ sudo apt install borgbackup fuse-overlayfs  # or zypper, yum, etc.
me@here:~$ borg init --encryption none /path/to/repo/
me@here:~$ borg-stack create /path/to/repo/::myhome* /home/me/

me@here:~$ # year 2 - add some important stuff
me@here:~$ borg-stack create /path/to/repo/::myhome* /home/me/pictures/2020* /home/me/documents/

me@here:~$ # year 3 - add everything we missed so far
me@here:~$ borg-stack create /path/to/repo/::myhome* /home/me/

Now, let's mount everything we've collected over the last years.

me@here:~$ # year 4 - we need something from the backup
me@here:~$ mkdir /mnt/myhome
me@here:~$ borg-stack mount /path/to/repo/::myhome* /mnt/myhome

What's in the Borg repository?

me@here:~$ borg-stack list /path/to/repo/
myhome*
  myhome20190717170550                 Wed, 2019-07-17 17:05:50 [d5f077465e54290e1a49d900f1d7af799b7c38a44d2b91be473bdd2fd312c343]
  myhome20201019220224                 Mon, 2020-10-19 22:02:24 [6621e47907f10f044f683b479a1f455939352ae78fab853d55edd70665fa1493]
  myhome20210309180215                 Tue, 2021-03-09 18:02:15 [d92508a0f6bd4c0d3a7c3e914d40dc306368181af32f5711ef82852970ee7449]

Features

BorgBackup provides full backups only. That simplifies things a lot but comes at the price of reduced flexibility for the user under certain conditions. Sometimes, a Borg archive is larger than the possibly available space to restore it. That means, you can only restore parts of it. It usually happens when migrating from an rsync-maintained backup, grown carefully over time.

In general, that's not an issue; until it's time to create yet another backup. Because you can create only full backups with Borg, your brand-new archive will contain only parts of your data. As time goes on, this could lead to many Borg archives, each of which with different directory layouts and different parts of your data.

Therefore, BorgStack provides a way to:

• create a stack of archives in an organized way (user-defined prefix + timestamp)
• select a stack of archives in a glob-style manner (prefix*)
• mount a layered version of your data, stacked from newest to oldest
• umount a stack of archives
• delete a stack of archives

So, you will always find the most up-to-date version of all backup'ed files.

Mount-Points and OverlayFS

BorgStack requires the packages borgbackup and fuse-overlayfs.

When you mount a layered version of your data, BorgStack creates the following disk layout at the mount-point:

me@here:~$ find mount-point/
mount-point/                               # here's what you specify during mount and umount
mount-point/archives/
mount-point/archives/<archive-1>           # here's the list of the relevant Borg archives
mount-point/archives/<archive-2>
mount-point/archives/...
mount-point/archives/<archive-n-1>
mount-point/archives/<archive-n>
mount-point/merged-<repository>-<archive>  # here's the content of your Borg stack

All the mount-points under mount-point/archives/* are themselves mount-points created by Borg. After all the archives (the first full one and the other differential ones) are mounted, BorgStack uses OverlayFS to stack these mounted archives in the order of their creation timestamp.

The resulting stacked data is available at mount-point/merged-<repository>-<archive>.

In order to minimize the hassle of unmounting them all, BorgStack provides the command umount. It sifts through the provided layout above to find all mount points and unmounts them all.

Flexible Naming Schemes

You can even add your own structuring or use multiple prefixes as in the following example.

you@there:~$ # add a backup for a different user on a different machine
you@there:~$ borg-stack create /path/to/repo/::yourhome* /home/you/

me@here:~$ # and for the phone
me@here:~$ borg-stack create /path/to/repo/::myphone* /mnt/phone

Borg stacks can happily live together in a single repository.

you@here:~$ borg-stack list /path/to/repo/
myhome*
  myhome20190717170550                 Wed, 2019-07-17 17:05:50 [d5f077465e54290e1a49d900f1d7af799b7c38a44d2b91be473bdd2fd312c343]
  myhome20201019220224                 Mon, 2020-10-19 22:02:24 [6621e47907f10f044f683b479a1f455939352ae78fab853d55edd70665fa1493]
  myhome20210309180215                 Tue, 2021-03-09 18:02:15 [d92508a0f6bd4c0d3a7c3e914d40dc306368181af32f5711ef82852970ee7449]

myphone*
  myphone20201020195244                Tue, 2020-10-20 21:52:44 [f3d845264a119d33c2c534da03d9df6209eafb587c73d9c29f93663087eba732]

yourhome*
  yourhome20210313160210               Sat, 2021-03-13 16:02:10 [f365ee7b892aa89b192192373e7db48158568776c0f5de080c48721d2da7f4d8]

And you can access them the same way you are used to.

me@here:~$ let's check out all my data
me@here:~$ borg-stack mount /path/to/repo/::my* /mnt/my

me@here:~$ or all the home data
me@here:~$ borg-stack mount /path/to/repo/::*home* /mnt/home