README.md

Mon, 29 Jan 2018 09:41:14 +0000

author
Tuomo Valkonen <tuomov@iki.fi>
date
Mon, 29 Jan 2018 09:41:14 +0000
changeset 90
8f84b3e60336
parent 83
1643b1120cc2
child 93
040a0479f51e
permissions
-rw-r--r--

Removed now unused code for obtaining a sub-logger

20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
1 # Borgend
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
2
65
6fed67863b00 README and config.example.yaml updates to describe queuing features
Tuomo Valkonen <tuomov@iki.fi>
parents: 56
diff changeset
3 This is a retrying and queuing scheduler as well as a MacOS tray icon for [BorgBackup](https://borgbackup.readthedocs.io/en/stable/).
67
75e514746980 README Non-MacOS description fix
Tuomo Valkonen <tuomov@iki.fi>
parents: 66
diff changeset
4 If you are not on MacOS, no tray icon will be displayed, but you can still use Borgend as a scheduler.
13
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
5
83
1643b1120cc2 Mention dreamtime in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 67
diff changeset
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.
1643b1120cc2 Mention dreamtime in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 67
diff changeset
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.
66
4bc6322d0306 typofixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 65
diff changeset
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.
65
6fed67863b00 README and config.example.yaml updates to describe queuing features
Tuomo Valkonen <tuomov@iki.fi>
parents: 56
diff changeset
9
13
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
10 The lead author is Tuomo Valkonen (<tuomov@iki.fi>).
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
11
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
12 ## Installation
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
13
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
14 You will need to install the following non-standard Python packages:
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
15
41
e2641cb9ca6d --no-tray command line option for running on non-MacOS systems
Tuomo Valkonen <tuomov@iki.fi>
parents: 37
diff changeset
16 - [keyring](https://pypi.python.org/pypi/keyring) to extract passphrases from the keychain
56
d63f6e9a4633 pyyaml was missing from listed dependencies
Tuomo Valkonen <tuomov@iki.fi>
parents: 47
diff changeset
17 - [pyyaml](http://pyyaml.org/) for parse configuration files
41
e2641cb9ca6d --no-tray command line option for running on non-MacOS systems
Tuomo Valkonen <tuomov@iki.fi>
parents: 37
diff changeset
18
e2641cb9ca6d --no-tray command line option for running on non-MacOS systems
Tuomo Valkonen <tuomov@iki.fi>
parents: 37
diff changeset
19 The use the tray icon on Mac OS, you will need:
e2641cb9ca6d --no-tray command line option for running on non-MacOS systems
Tuomo Valkonen <tuomov@iki.fi>
parents: 37
diff changeset
20
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
21 - [rumps](https://github.com/jaredks/rumps) (Ridiculously Uncomplicated macOS Python Statusbar apps)
37
9fab8200f7eb README tune
Tuomo Valkonen <tuomov@iki.fi>
parents: 33
diff changeset
22
41
e2641cb9ca6d --no-tray command line option for running on non-MacOS systems
Tuomo Valkonen <tuomov@iki.fi>
parents: 37
diff changeset
23 If you are not on Mac OS, you will need:
37
9fab8200f7eb README tune
Tuomo Valkonen <tuomov@iki.fi>
parents: 33
diff changeset
24
9fab8200f7eb README tune
Tuomo Valkonen <tuomov@iki.fi>
parents: 33
diff changeset
25 - [xdg](https://pypi.python.org/pypi/xdg/3.0.0) for configuration file location
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
26
25
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
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
22
c3e95212e3f0 py2app standalone app generation
Tuomo Valkonen <tuomov@iki.fi>
parents: 20
diff changeset
28
c3e95212e3f0 py2app standalone app generation
Tuomo Valkonen <tuomov@iki.fi>
parents: 20
diff changeset
29 pip install py2app
c3e95212e3f0 py2app standalone app generation
Tuomo Valkonen <tuomov@iki.fi>
parents: 20
diff changeset
30
33
91421eeb4426 Use rumps.application_support instead of xdg paths. Also separated branding into config.py
Tuomo Valkonen <tuomov@iki.fi>
parents: 26
diff changeset
31 (for alternatives see [py2app documentation](https://py2app.readthedocs.io/en/latest/install.html)). Then, to build the standalone app, run
22
c3e95212e3f0 py2app standalone app generation
Tuomo Valkonen <tuomov@iki.fi>
parents: 20
diff changeset
32
c3e95212e3f0 py2app standalone app generation
Tuomo Valkonen <tuomov@iki.fi>
parents: 20
diff changeset
33 python3 setup.py py2app
c3e95212e3f0 py2app standalone app generation
Tuomo Valkonen <tuomov@iki.fi>
parents: 20
diff changeset
34
23
86b42610d5a8 #!python3 in script file
Tuomo Valkonen <tuomov@iki.fi>
parents: 22
diff changeset
35 The apps hould be placed under `dist/`.
22
c3e95212e3f0 py2app standalone app generation
Tuomo Valkonen <tuomov@iki.fi>
parents: 20
diff changeset
36
41
e2641cb9ca6d --no-tray command line option for running on non-MacOS systems
Tuomo Valkonen <tuomov@iki.fi>
parents: 37
diff changeset
37
25
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
38 ## Usage and configuration
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
39
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
40 ### Configuration file
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
41
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
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.
47
305de2297fde README configuration file location update
Tuomo Valkonen <tuomov@iki.fi>
parents: 44
diff changeset
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.
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
44
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
45 ### Passphrases
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
46
25
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
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:
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
48
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
49 security add-generic-password -a my-borg-backup -s borg-backup -w [PASSWORD]
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
50
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
51
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
52 ## License
13
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
53
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
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:
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
55
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
56 (a) Always redistribute the **unmodified** and **latest** version provided
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
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
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
58 version the default version offered to your users (on that specific branch).
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
59
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
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.
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
61
44
ac449729a896 License note
Tuomo Valkonen <tuomov@iki.fi>
parents: 43
diff changeset
62 Otherwise, do whatever you want with this software. In particular, you may freely use code snippets in other projects.
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
63
44
ac449729a896 License note
Tuomo Valkonen <tuomov@iki.fi>
parents: 43
diff changeset
64

mercurial