BorgTUI

A simple TUI and CLI to automate your Borg backups :^)

Features

• Simple: Manage your backup sources, backups, and repositories from either the TUI or CLI.
• Ergonomic: Find, add, and canonicalize backup paths from the TUI.
• Concurrent: All operations occur concurrently and in parallel for each repository.
• Easy: Just Works™. BorgTUI will backup every source directory to every remote repository.
• Friendly: Shell completions, desktop notifications, systemd unit generation.
• Automation: Designed to perform regular and scheduled backups.
• Documentation: Has man pages and helpful error messages.

Installation

Arch Linux

BorgTUI is available on the AUR as borgtui-git.

Manual Installation

Please see the Manual Installation section in the appendix.

Quick Start Guide

Initializing or Adding a New Repository

BorgTUI normally retrieves the repository encryption passphrase from your keyring. However, when setting up a new repository BorgTUI reads the passphrase from the environment or from the command-line with borgtui (init|add-repo) -e <passphrase> <location>. The easiest way is to set BORG_PASSPHRASE and you can set this using read and pasting in the password followed by enter:

read -s BORG_PASSPHRASE

You’ll need to export that variable for BorgTUI to pick it up:

export BORG_PASSPHRASE

If you want to add an existing repository, use borgtui add-repo:

borgtui add-repo ssh://abcdefg@abc123.repo.borgbase.com/./repo

If you want to create a new repository, use borgtui init:

borgtui init ssh://david@home-nas/hdd1/borg

Adding Sources

You can add new backup sources by using the directory chooser in borgtui. Press “a” to open the directory chooser. Autocomplete and canonicalize paths with “TAB”.

You can also use borgtui add on the command-line:

borgtui add <backup_path>

You can manually add paths by editing the profile json file under ~/.config/borgtui/profiles/. Make sure to run that path through realpath first!

Creating a Backup

You can create a new backup across each repository by pressing “u” when borgtui is open.

You can also create a backup on the command-line using:

borgtui create

Listing Archives

You can list archives in the TUI by hitting “l”. You can also list backups by using:

borgtui list

Verifying Backups (Check)

You can verify the integrity of backups by using `borgtui check`. This is currently only supported in CLI mode.

borgtui check

You can create systemd units for verifying the backups by issuing:

borgtui systemd-create-unit --install --check-unit
borgtui systemd-create-unit --install --check-unit --timer
systemctl --user daemon-reload
systemctl --user enable --now borgtui-check-default.timer

Restoring from a Backup

BorgTUI supports restoring from backups by mounting an archive or repository and allowing users to interactively restore from that.

Restoring from the TUI

In the UI hit “m” or “M” to select an archive or a repository and the select a mount point. Use ‘G’ to unmount once you’ve restored from a backup.

BorgTUI will automatically suggest “~/borg-mount” as a mount point and will create the folder when selected. If you exit the TUI without unmounting you can use the following command to unmount:

borgui umount <mointpoint>

Restoring from the CLI

Currently BorgTUI supports mounting an archive or repository. First you need to select and archive to restore from:

borgtui list
2023-06-11T22:15:31.551471Z  INFO borgtui: /hdd3/NewBackup::real-2023-04-23:14:01:00
2023-06-11T22:15:31.551481Z  INFO borgtui: /hdd3/NewBackup::real-2023-04-23:23:27:23
... truncated ...

The archive /hdd3/NewBackup::real-2023-04-23:14:01:00 looks good. The repository /hdd3/NewBackup is also a good choice. Let’s mount the archive at ~/borg-mount:

mkdir ~/borg-mount
borgtui mount /hdd3/NewBackup::real-2023-04-23:14:01:00 ~/borg-mount

You can also mount whole repositories:

borgtui mount <repository_name> ~/borg-mount

Your backup should show up in that folder. Ideally use a file manager to browse and restore whatever files you need selectively. You can unmount a mounted archive or repository by using borgtui umount

borgtui umount ~/borg-mount

Profiles

BorgTUI supports having several profiles which each contain their own backup sources and borg repositories. The default profile is called “default” and lives under ~/.config/borgtui/profiles/default.json on Linux. You can set BORGTUI_PROFILE in your environment or use borgtui -p <profile_name> ... to select the profile.

The default screen in BorgTUI is the profile view where you can see your backup paths and repositories:

Creating New Profiles

Interacting with BorgTUI will automatically create a profile called “default” unless a different profile is specified. You can create a new profile with:

borgtui add-profile <profile-name>

Pruning and Compacting

You can prune by pressing “" in the TUI or by issuing:

borgtui prune

You can compact a repo by pressing “c” in the TUI or by issuing:

borgtui compact

Disabling a Repository

To disable a repository so that BorgTUI won’t interact with it set the disabled flag in the repository section of the configuration:

"repos": [
  {
    "path": "/path/to/borg/repo",
    "encryption": "Keyring",
    "disabled": true
  },
]

To find your profile use the “config-path” subcommand:

borgtui config-path

This is useful to prevent unnecessary errors and logs when you’re upgrading your NAS or BorgBase decides to have an extended outage :^)

Automatic Scheduled Backups

BorgTUI is designed to regularly back up your files.

Systemd User Units

BorgTUI contains systemd user unit templates you can use to automate backups. You can install the service and timer with (replace -default with your custom profile name if you have one):

borgtui systemd-create-unit --install
borgtui systemd-create-unit --install --timer
systemctl --user daemon-reload
systemctl --user enable --now borgtui-create-default.timer

By default the backup occurs every night at 9PM local time. Edit the timer unit in ~/.config/systemd/user/ to modify the schedule. BorgTUI will issue a notification that the backup completed.

You can trigger backups manually with:

systemctl --user start borgtui-create-default

You can view logs of past backups with:

journalctl --user -u borgtui-create-default

Without Systemd

Simply issue borgtui create with the scheduling system of your choosing (cron, etc).

Appendix

Manual Installation

You can manually install BorgTUI with cargo:

cargo install --git https://github.com/dpbriggs/borgtui.git

Shell Completion

Shell completions can be enabled by sourcing completions generated by BorgTUI. Replace “zsh” with whatever shell you’re using (e.g. “bash”):

source <(borgtui shell-completion --shell zsh)

Install Man Pages

Install the man pages at a location with:

borgtui install-man-pages <install_directory_path>

On most systems you can use manpath to find where to install those man-pages.

Why does this exist?

I wanted a tool to automatically backup the same set of folders to every repository. I couldn’t get Vorta to ergonomically backup the same set of folders to several remote repositories (issue).

Known issues

Password-based SSH doesn’t work and messes up the terminal

I can’t find a way to ask SSH to not ask for a password without modifying the actual SSH command used or editing the ssh_config. I can’t do the latter so a refactor would need to occur somewhere between BorgTUI and borg itself.

If you attempt to init or add a repository with a faulty (or not-running) keyring the profile saves but the password doesn’t

A workaround is to start whatever keyring you use (search “wallet”, open chromium, etc), remove the repo from the config-path, and then use `add-repo` to re-add it.

Choice Excerpt from the Licence

Please carefully read the LICENCE file before using this program.

1. Disclaimer of Warranty.

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

1. Limitation of Liability.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Note

This work is not affiliated with my employer in any way.