comparison: README.md
README.md
- changeset 93
- 040a0479f51e
- parent 83
- 1643b1120cc2
- child 120
- 109eaddc16e1
equal
deleted
inserted
replaced
| 92:a1d3721ef5fa | 93:040a0479f51e |
|---|---|
| 1 # Borgend | 1 # Borgend |
| 2 | 2 |
| 3 This is a retrying and queuing scheduler as well as a MacOS tray icon for [BorgBackup](https://borgbackup.readthedocs.io/en/stable/). | 3 This is a retrying and queuing scheduler as well as a macOS tray icon for |
| 4 If you are not on MacOS, no tray icon will be displayed, but you can still use Borgend as a scheduler. | 4 [BorgBackup](https://borgbackup.readthedocs.io/en/stable/). If you are not |
| 5 on macOS, no tray icon will be displayed, but you can still use Borgend as a | |
| 6 scheduler. | |
| 5 | 7 |
| 6 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. | 8 * Designed with laptops in mind, Borgend works in “dreamtime”: on macOS the |
| 7 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. | 9 scheduler discounts system sleep periods from the backup intervals. If |
| 8 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. | 10 you wish, you can also choose “realtime” scheduling. |
| 11 | |
| 12 * You can have multiple backups to the same repository; for example, you | |
| 13 may backup a small subset of your files every couple of hours, and | |
| 14 everything once a day or once a week. Borgend will ensure that only one | |
| 15 backup is launched at a time, and queue the other one until the | |
| 16 repository is available. | |
| 17 | |
| 18 * If there was an error, such as when you are offline and backup to a | |
| 19 remote `ssh` location, Borgend will also retry the backup at set shorter | |
| 20 intervals. | |
| 9 | 21 |
| 10 The lead author is Tuomo Valkonen (<tuomov@iki.fi>). | 22 The lead author is Tuomo Valkonen (<tuomov@iki.fi>). |
| 11 | 23 |
| 12 ## Installation | 24 ## Installation |
| 13 | 25 |
| 14 You will need to install the following non-standard Python packages: | 26 You will need to install the following non-standard Python packages: |
| 15 | 27 |
| 16 - [keyring](https://pypi.python.org/pypi/keyring) to extract passphrases from the keychain | 28 - [keyring](https://pypi.python.org/pypi/keyring) to extract passphrases |
| 29 from the keychain | |
| 17 - [pyyaml](http://pyyaml.org/) for parse configuration files | 30 - [pyyaml](http://pyyaml.org/) for parse configuration files |
| 18 | 31 |
| 19 The use the tray icon on Mac OS, you will need: | 32 The use the tray icon on macOS, you will need: |
| 20 | 33 |
| 21 - [rumps](https://github.com/jaredks/rumps) (Ridiculously Uncomplicated macOS Python Statusbar apps) | 34 - [rumps](https://github.com/jaredks/rumps) (Ridiculously Uncomplicated |
| 35 macOS Python Statusbar apps) | |
| 22 | 36 |
| 23 If you are not on Mac OS, you will need: | 37 If you are not on macOS, you will need: |
| 24 | 38 |
| 25 - [xdg](https://pypi.python.org/pypi/xdg/3.0.0) for configuration file location | 39 - [xdg](https://pypi.python.org/pypi/xdg/3.0.0) for configuration file |
| 40 location | |
| 26 | 41 |
| 27 For passphrase use authentication to work correctly, it is useful to create a standalone Mac app. This can be don with `py2app`. You can install it with | 42 With the dependencies satisfied, Borgend may be run with |
| 28 | 43 |
| 29 pip install py2app | 44 python3 borgend.py |
| 30 | 45 |
| 31 (for alternatives see [py2app documentation](https://py2app.readthedocs.io/en/latest/install.html)). Then, to build the standalone app, run | 46 To permanently authenticate Borgend to use the keychain, and therefore not |
| 47 have to enter the keychain password every time Borgend is launched, it is | |
| 48 useful to create a standalone Mac app. This can be done with | |
| 49 | |
| 50 - [py2app](https://py2app.readthedocs.io/en/latest/install.html). | |
| 51 | |
| 52 To create the standalone app | |
| 32 | 53 |
| 33 python3 setup.py py2app | 54 python3 setup.py py2app |
| 34 | 55 |
| 35 The apps hould be placed under `dist/`. | 56 The app hould be placed under `dist/`. Copy it to your `Applications` |
| 57 directory, and set it up to launch on login. | |
| 36 | 58 |
| 37 | 59 |
| 38 ## Usage and configuration | 60 ## Usage and configuration |
| 39 | 61 |
| 40 ### Configuration file | 62 ### Configuration file |
| 41 | 63 |
| 42 See the included `config.example.yaml`, which shoud be relatively self-explanatory. Everything under `common_parameters`, `create_parameters`, and `prune_parameters` are simply Borg command line key–value parameters. | 64 See the included `config.example.yaml`, which shoud be relatively |
| 43 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 `~/.config/borgend/config.yaml`. You can find the location with the `--help` option. | 65 self-explanatory. The lists `common_parameters`, `create_parameters`, and |
| 66 `prune_parameters` are simply Borg command line key–value parameters, passed | |
| 67 to it after expansion of environment variables. | |
| 68 | |
| 69 Edit the sample configuration file and copy it to its proper location. On | |
| 70 macOS this should be `~/Library/Application Support/borgend/config.yaml`, | |
| 71 and on other systems this will usually be `~/.config/borgend/config.yaml`. | |
| 72 You can find out the actual location by launching Borgend from the command | |
| 73 line with the `--help` option. | |
| 44 | 74 |
| 45 ### Passphrases | 75 ### Passphrases |
| 46 | 76 |
| 47 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 ‘my-borg-backup’, you may use: | 77 Passphrases are stored in the OS X Keychain (or whatever the `keyring` |
| 78 package supports on other systems). In the Borgend configuration file, you | |
| 79 only configure the ‘account’ of the of the password using `keychain_account` | |
| 80 keyword of each backup set. The ‘service’ of the password has to be | |
| 81 `borg-backup`. To add a password into the keychain for the `myrepo` | |
| 82 ‘account’, you may use: | |
| 48 | 83 |
| 49 security add-generic-password -a my-borg-backup -s borg-backup -w [PASSWORD] | 84 security add-generic-password -a myrepo -s borg-backup -w [PASSWORD] |
| 50 | 85 |
| 51 | 86 |
| 52 ## License | 87 ## License |
| 53 | 88 |
| 54 This software is distributed under an ANTI-ABUSE LICENSE (aka. *fuck copyright and fuck distributions license*), and without any warranty whatsoever. If you redistribute this software as part of a larger collection/distribution/suite of software, you must do either of the following: | 89 This software is distributed under an ANTI-ABUSE LICENSE (aka. *f..k |
| 90 copyright and f..k distributions license*), and without any warranty | |
| 91 whatsoever. If you redistribute this software as part of a larger | |
| 92 collection/distribution/suite of software, you must do either of the | |
| 93 following: | |
| 55 | 94 |
| 56 (a) Always redistribute the **unmodified** and **latest** version provided | 95 (a) Always redistribute the **unmodified** and **latest** version provided |
| 57 by the lead author. If the lead author releases a new version (on a specific branch, such as 'stable' or 'development'), you must promptly make that new | 96 by the lead author. If the lead author releases a new version (on a specific |
| 97 branch, such as 'stable' or 'development'), you must promptly make that new | |
| 58 version the default version offered to your users (on that specific branch). | 98 version the default version offered to your users (on that specific branch). |
| 59 | 99 |
| 60 (b) Rename the software, and make it obvious that your modified or obsolete software is in no way connected to the lead author of the original software. The users of your version should under no circumstances be under the illusion that they can contact the lead author or any of the authors of the original software if they have any complaints or queries. | 100 (b) Rename the software, and make it obvious that your modified or obsolete |
| 101 software is in no way connected to the lead author of the original software. | |
| 102 The users of your version should under no circumstances be under the | |
| 103 illusion hat they can contact the lead author or any of the authors of the | |
| 104 original software if they have any complaints or queries. | |
| 61 | 105 |
| 62 Otherwise, do whatever you want with this software. In particular, you may freely use code snippets in other projects. | 106 Otherwise, do whatever you want with this software. In particular, you may |
| 107 freely use code snippets in other projects. | |
| 63 | 108 |
| 64 |
