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