rofi-borg

rofi-borg is a GUI wrapper script for borg backup. It aims to be easy to setup, highly capable, and customizable.

Motivation

With my system, software, and configurations managed through GitHub (debian-autosetup and .dotfiles), I required a method to backup and restore my private files. Thus, I created rofi-borg as a lean solution to have encrypted backups and a simple GUI to manage them.

I wanted to allow others to have easy access to encrypted and deduplicated backups too. With that in mind, the script is designed to handle the boilerplate by automating the building of commands and menus for you. You simply set variables once and the script builds what it needs.

Features

Borg

• Create and Prune backups (archives) in a repository.
• List archives in a repository.
• Download an archive from a repository.
• Delete an archive from a repository.
• Automatic password handling.
• Able to use borg environment variables without setting them globally in env.
  • Protects you from having your borg information being backed up in your dotfiles.

Scripts

• Supports automation of backups.
  • Just call backup_run.sh from cron or systemd. May create template for this later.
• Supports notifications!
  • Uses your notification command of choice. Default: Dunst.
• Uses logging:
  • Gets info in the background and logs to files, allowing you to work while rofi-borg runs.
  • Configurable number of logs to keep.
  • Automatic pruning of logs directory.
• Easily configured:
  • Configured from main script. Settings are passed to subsequent scripts.
• Customizable:
  • Default theme is Dracula!
  • There is a main theme config, edit that to change the primary theming. Certain scripts have their own configs which inherit from the main config, rofi-borg.rasi. This allows theming to be configured from the main file, or to change theme/size per script, independently.
• Extendable:
  • Just write a script and point it to the main rofi config or inherit/write your own, then add it to the rofi-borg.sh menu items!

Requirements

• rofi and borg
• some form of font based icons: default: Font Awesome 5

Installation

1. Install dependencies.
2. Reccomended Install:
   • This install method allows you to version control rofi-borg into your rofi dotfiles, so it’s available to reinstall your backups as soon as your dotfiles are installed.
     1. cd $HOME/.config/rofi/
     2. git clone https://github.com/noncog/rofi-borg
     3. configure rofi-borg.sh and launch using preferred method.

Usage

Before you can use the script, it must be configured and you need to setup a launching method.

⚠️ WARNING
This script is not designed to completely setup borg backup for you. You need to have an understanding of how borg is used and have a valid repository.

Configuration

rofi-borg is designed to be easily configured from the top level script and the settings are passed into subsequent scripts.

Configuring rofi-borg.sh, backup_run.sh backup directories, and setting your repository and password in the first line of $HOME/.config/borg/repository and $HOME/.config/borg/passphrase is the minimal amount of configuration required. However, I recommend you checkout every script to make sure it’s setup how you like.

The options you can change in each script are clearly marked in the comments.

rofi-borg.sh

• global options - Applies to all subscripts.
  • Minimally must set:
    1. directory=” ” to your install location.
    2. downloads=” ” to your desired download location.
    3. notifications=”y” or “n” if you want progress notifications.
       • If using “y”, must set notifier=” ” to your desired command for notifications.
• borg environment variables - Only set/add them here. Not in subscripts.
  • Minimally must use:
    1. BORG_REPO
    2. BORG_PASSPHRASE or BORG_PASSCOMMAND
       • If using password/passkey. (RECCOMENDED)
       • Otherwise comment it out.

NOTE - These are setup to search for $HOME/.config/borg/repository and $HOME/.config/borg/passphrase by default. Just put your repository and passpharase in there and you’re good to go!

sub-scripts

• Located in rofi-borg/scripts/
• Contain borg command options.
  • Always located under borg-vars comment in each script.
    • rofi-borg ships with sane defaults.
    • If you know the exact command options you want, set them in the corresponding script before using.

Launching

You can launch rofi-borg however you like, there are no hard coded methods for doing so. Below are some possible methods.

Locally

1. cd into install directory
2. ./rofi-borg.sh or bash rofi-borg.sh

Globally

• bash $HOME/.config/rofi/rofi-borg/rofi-borg.sh
  • If installed elsewhere supply your own file path.
• (optional) For easy access, add the script somewhere in your $PATH.

From Window Managers

Just call the script from your window manager config.

• i3: bindsym $mod+Shift+BackSpace exec --no-startup-id $HOME/.config/rofi/rofi-borg/rofi-borg.sh

From Custom Rofi Menus

I assume, if you have a custom rofi menu that you know how to add to it and will not be covering that. Instead, all you should need is to call the script using the global launch method from above:

• bash $HOME/.config/rofi/rofi-borg/rofi-borg.sh
  • NOTE If you keep your menu scripts in rofi or better integrate rofi-borg into them, the file paths can be more easily managed. Just another reason to keep your rofi stuff together.

From Rofi combi-mode

Just add the script to combi-modi in your main rofi config: $HOME/.config/rofi/config.rasi

configuration {
    combi-modi: "window,drun,ssh,rofi-borg:~/.config/rofi/rofi-borg/rofi-borg.sh";
    modi: "combi";
}

• NOTE I don’t use this method and have not tested it. I use my own custom menu. Please report on this.

Tips

• Notifications are highly reccomended. But be warned, any command you set for your notifier is evaluated, meaning that it is ran regardless of what it is. Be warned, this can be devastating if you put an unsafe command there. There currently isn’t a way around this, just be safe.
• Do not run another borg command while the previous is running. It will fail. The remote server is busy. This is a good reason to use notifications, to understand the scripts’ state and avoiding collisions.
• Large downloads will take some time. Do not worry. Another good reason to use notifications: downloads will announce when they’re finished. Do not start a large download before you plan to do other actions.

Customizing

General

• Every script that creates a rofi window contains it’s own prompt_message string and can be configured per script. It is clearly marked under the variables you can change.

Theme

• The rofi configuration files are located in configs.
• See man rofi-theme for all theming related rofi information.
  • NOTE Created with rofi 1.5.4. I’m no rofi expert, unsure if my theme setup is backward/forward compatible, etc. Please contribute.

Font

• By default the scripts’ rofi configs inherit the font from your global rofi config.rasi.
• If you would like to set the font, uncomment the font line in the associated config and change it to your desired font.

Icons

• Just use any font-based icons you want. Place the icon glyphs in the string for the menu item.
• If you want it to “just work” then install Font Awesome 5
• I would love it if someone contributed a version that uses real icons or buttons, but I also enjoy the simplicity of this version.

Extending

• A good method for adding a script is to view the four provided, and model your script after them.
• The main script passes required variables to the subscripts. Your script must function the same way.
• If a script is to return output to rofi, it must use logging by sending the stderr/stdout to a log file to be presented to rofi. If this is not done, rofi will freeze your computer if rofi has to wait for the command to finish before displaying it’s result.
• The script MUST handle canceling a selection with a simple if-else to check if the selection is empty or not. See the scripts for examples. Do not let your script run when an explicit selection is not made.
• The script MUST handle the building of commands and menus for the user. The user should only be required to set variables once, at the top of the script or top level script. Follow the commenting style and setting of variables, and building of commands and menus as I have. If you have a better method for doing all of this, please submit it!

Contributing

See the customizing and extending sections above. All script contributions must adhere to those guidelines.

Guide:

1. Clone the repo and create a new branch: git checkout https://github.com/noncog/rofi-borg -b name_for_new_branch
2. Make changes and test.
3. Submit pull request with comprehensive description of changes.

Additionally, here is a list of things that I would like to add but don’t have time:

• Greater support for more command options of borg. If you use a certain borg command and I’m not supporting it, contribute it!
• Greater abstraction of the subscript design to allow others more easily to contribute subscripts.