~tuomov ⇝ Software ⇝

Borgend

Borgend is a retrying and queuing scheduler as well as a macOS tray icon for Borg Backup. If you are not on macOS, no tray icon will be displayed, but you can still use Borgend as a scheduler.

Designed with laptops in mind, Borgend works in “dreamtime”: on macOS the scheduler discounts system sleep periods from the backup intervals. If you wish, you can also choose “realtime” scheduling.
You can have multiple backups to the same repository; for example, you may backup a small subset of your files every couple of hours, and everything once a day or once a week. Borgend will ensure that only one backup is launched at a time, and queue the other one until the repository is available.
If there was an error, such as when you are offline and backup to a remote ssh location, Borgend will also retry the backup at set shorter intervals.

The lead author is Tuomo Valkonen (tuomov@iki.fi).

Installation

Borgend naturally requires Borg Backup to be installed as well as a working Python 3 installation. Install both according to the instructions for your operating system. With this done, located in the top-level directory of the borgend source tree, you can install borgend

pip3 install .

This will also install some additional Python libraries (keyring, pyyaml, rumps, and, if not on MacOS, xdg). Now you can start borgend with

borgend

Before this, you will probably, however, want to create a configuration file as detailed below. A standalone application, explained below, can be more convenient for access to passwords from the system keyring.

If you do not wish to install borgend and would rather run it in-place, use

python3 -m borgend

in the toplevel directory of the borgend source tree.

Usage and configuration

Configuration file

See the included config.example.yaml, which shoud be relatively self-explanatory. The lists common_parameters, create_parameters, and prune_parameters are simply Borg command line key–value parameters, passed to it after expansion of environment variables.

Edit the sample configuration file and copy it to its proper location. On macOS this should be ~/Library/Application Support/borgend/config.yaml, and on other systems this will usually be ~/.config/borgend/config.yaml. You can find out the actual location by launching Borgend from the command line with the --help option.

Passphrases

Passphrases are stored in the OS X Keychain (or whatever the keyring package supports on other systems). In the Borgend configuration file, you only configure the ‘account’ of the of the password using keychain_account keyword of each backup set. The ‘service’ of the password has to be borg-backup. To add a password into the keychain for the myrepo ‘account’, you may use:

security add-generic-password -a myrepo -s borg-backup -w [PASSWORD]

To permanently authenticate Borgend to use the keychain, and therefore not have to enter the keychain password every time Borgend is launched, it is useful to encapculate it into a macOS app. This can be done with py2app. To create a standalone app that you can launch at startup and give permanent permissions to the keychain, use

python3 setup.py py2app

The app hould be placed under dist/. Copy it to your Applications directory, and set it up to launch on login.

Py2app is flaky to say the least. If the positions of sunspots so dictate, the above command may not create a working standalone application. If this is the case, you may attempt to add the -A option to the command. It will then create a non-standalone application. While not easily transferrable between different machines, it will still help with keychain permissions.

Downloads

borgend is available from its Mercurial repository. You may either use Mercurial to clone the entire repository or you may download a snapshot as a zip or tarball. To clone use the command

hg clone https://tuomov.iki.fi/repos/borgend/

Contributing, distributing, derivative works

If you would like to contribute to this project, simply clone the repository and email me a hg bundle of your changes.

This software may be redistributed and derivate works may be created under the terms of the Anti-abuse License.