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.

 * Can discover, e.g., home servers using SSDP/UPnP

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

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

## Installation

Borgend naturally requires [Borg Backup][] to be installed as well as a working
[Python 3](https://www.python.org/) 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](https://pypi.python.org/pypi/keyring),
[pyyaml](http://pyyaml.org/),
[ssdpy](https://pypi.org/project/ssdpy/),
[rumps](https://github.com/jaredks/rumps), and, if not on MacOS,
[xdg](https://pypi.python.org/pypi/xdg/3.0.0)).
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](https://py2app.readthedocs.io/en/latest/install.html).
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.

## SSDP

Borgend can discover local servers using SDSP/UPnP. The server should have
a corresponding annoucement service running. Relevant Python script and
systemd setup files can be found under `announce/`. The `--uuid` parameter
of the script should match the `ssdp_uuid` configuration setting of the
repository, while `ssdp_path` should indicate the path within the server.
The announce script can also communicate user ID on the server, as set with
`--user`.

For some additional security, `borgend` itself does not query the  service 
with the `uuid`, but merely with the service type `borg`. It will only attempt
to connect if a server with the correct UUID answers to its SSDP query.