README.md

# Borgend

<a href="media/borgend.png"><img src="media/borgend.jpg" style="max-width: 100%" alt="Borgend screenshot"></a>

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

  [Borg Backup]: https://www.borgbackup.org/

## Installation

Borgend naturally requires [Borg Backup][] to be installed. Borgend is written
in [Python](https://www.python.org/), and also requires a working python3 installation.
Install both according to the instructions for your operating system. Borgend also
requires some additional Python libraries. To install these, on macOS, run

    pip3 install keyring pyyaml rumps

On other systems, run

    pip3 install keyring pyyaml xdg

This will install the following Python packages:

 - [keyring](https://pypi.python.org/pypi/keyring) to extract passphrases
   from the keychain
 - [pyyaml](http://pyyaml.org/) for parsing configuration files
 - [rumps](https://github.com/jaredks/rumps) (Ridiculously Uncomplicated
   macOS Python Statusbar apps)
 - [xdg](https://pypi.python.org/pypi/xdg/3.0.0) for configuration file
   location (not needed on macOS)

With the dependencies satisfied, and Borgend downloaded, it may be run from
its download location with

    python3 borgend.py

Before this, you will probably, however, want to create a configuration file as detailed below.

## 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](https://py2app.readthedocs.io/en/latest/install.html).

To create an app that you can launch at startup and give permanent permissions
to the keychain, use

    python3 setup.py py2app -A

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

If you are keen on wasting your life, you can try to run py2app without the
`-A` option to create a standalone app that you can copy to computers without
Python installed. This will, however, most likely not work because py2app
is shit. Currently (2018-09-18) it is not working with the keyring package.