borgtui

borgtui copied to clipboard

• BorgTUI

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

[[https://user-images.githubusercontent.com/5560032/244952009-ae19036a-8044-4c00-8d42-5305ad6a9860.png][https://user-images.githubusercontent.com/5560032/244952009-ae19036a-8044-4c00-8d42-5305ad6a9860.png]]

** Features

• Simple: Manage your backup sources, backups, and repositories from either the TUI or CLI.
• Ergonomic: Find, add, and canonicalize backup paths [[https://user-images.githubusercontent.com/5560032/244952253-57126b10-d749-4337-9eb4-d6633ee8e0a5.png][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 [[https://aur.archlinux.org/packages/borgtui-git][borgtui-git]].

*** Manual Installation

Please see the [[#manual-installation-1][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 =. The easiest way is to set =BORG_PASSPHRASE= and you can set this using =read= and pasting in the password followed by enter:

#+begin_src bash read -s BORG_PASSPHRASE #+end_src

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

#+begin_src bash export BORG_PASSPHRASE #+end_src

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

#+begin_src bash borgtui add-repo ssh://[email protected]/./repo #+end_src

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

#+begin_src bash borgtui init ssh://david@home-nas/hdd1/borg #+end_src

*** 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".

[[https://user-images.githubusercontent.com/5560032/244952253-57126b10-d749-4337-9eb4-d6633ee8e0a5.png][https://user-images.githubusercontent.com/5560032/244952253-57126b10-d749-4337-9eb4-d6633ee8e0a5.png]]

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

#+begin_src bash borgtui add <backup_path> #+end_src

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.

[[https://user-images.githubusercontent.com/5560032/244974358-5322a8b0-6e0f-4893-ac3d-0b1eeeecacae.png][https://user-images.githubusercontent.com/5560032/244974358-5322a8b0-6e0f-4893-ac3d-0b1eeeecacae.png]]

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

#+begin_src bash borgtui create #+end_src

*** Listing Archives

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

#+begin_src bash borgtui list #+end_src

*** Verifying Backups (Check)

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

#+begin_src bash borgtui check #+end_src

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

#+begin_src bash 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 #+end_src

*** 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.

[[./images/borgtui-mount-screen.png][./images/borgtui-mount-screen.png]]

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:

#+begin_src bash borgui umount #+end_src

**** Restoring from the CLI

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

#+begin_src bash 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 ... #+end_src

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=:

#+begin_src bash mkdir ~/borg-mount borgtui mount /hdd3/NewBackup::real-2023-04-23:14:01:00 ~/borg-mount #+end_src

You can also mount whole repositories:

#+begin_src bash borgtui mount <repository_name> ~/borg-mount #+end_src

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=

#+begin_src bash borgtui umount ~/borg-mount #+end_src

*** 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:

[[https://user-images.githubusercontent.com/5560032/244976922-1fbc3393-a4ba-44be-8b2c-31b3cc02b831.png][https://user-images.githubusercontent.com/5560032/244976922-1fbc3393-a4ba-44be-8b2c-31b3cc02b831.png]]

**** 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:

#+begin_src bash borgtui add-profile #+end_src

*** Pruning and Compacting

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

#+begin_src bash borgtui prune #+end_src

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

#+begin_src bash borgtui compact #+end_src

*** 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:

#+begin_src json "repos": [ { "path": "/path/to/borg/repo", "encryption": "Keyring", "disabled": true }, ] #+end_src

To find your profile use the "config-path" subcommand:

#+begin_src bash borgtui config-path #+end_src

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):

#+begin_src bash borgtui systemd-create-unit --install borgtui systemd-create-unit --install --timer systemctl --user daemon-reload systemctl --user enable --now borgtui-create-default.timer #+end_src

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:

#+begin_src bash systemctl --user start borgtui-create-default #+end_src

You can view logs of past backups with:

#+begin_src bash journalctl --user -u borgtui-create-default #+end_src

*** Without Systemd

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

** Appendix

*** Manual Installation

You can manually install BorgTUI with [[https://doc.rust-lang.org/cargo/getting-started/installation.html][cargo]]:

#+begin_src bash cargo install --git https://github.com/dpbriggs/borgtui.git #+end_src

**** Shell Completion

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

#+begin_src bash source <(borgtui shell-completion --shell zsh) #+end_src

**** Install Man Pages

Install the man pages at a location with:

#+begin_src bash borgtui install-man-pages <install_directory_path> #+end_src

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 ([[https://github.com/borgbase/vorta/issues/942][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 [[file:LICENCE][LICENCE]] file before using this program.

#+begin_quote 15. 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.

16. 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. #+end_quote

** Note

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