README.md

Wed, 14 Feb 2018 15:23:39 +0000

author
Tuomo Valkonen <tuomov@iki.fi>
date
Wed, 14 Feb 2018 15:23:39 +0000
changeset 114
ad9fb3dd9fec
parent 93
040a0479f51e
child 120
109eaddc16e1
permissions
-rw-r--r--

Disable Notification Centre notifications.
They don't work reliably for some reason, and are in any case annoying
unless the display is somehow fine-tuned.

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
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
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
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
22 The lead author is Tuomo Valkonen (<tuomov@iki.fi>).
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
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
9fab8200f7eb README tune
Tuomo Valkonen <tuomov@iki.fi>
parents: 33
diff changeset
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
9fab8200f7eb README tune
Tuomo Valkonen <tuomov@iki.fi>
parents: 33
diff changeset
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
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
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
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
94
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
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
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
98 version the default version offered to your users (on that specific branch).
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
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
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
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

mercurial