README.md

Sun, 04 Feb 2018 01:36:59 +0000

author
Tuomo Valkonen <tuomov@iki.fi>
date
Sun, 04 Feb 2018 01:36:59 +0000
changeset 102
0d43cd568f3c
parent 93
040a0479f51e
child 120
109eaddc16e1
permissions
-rw-r--r--

Changed scheduler busylooping method, and decreased precision to 5 minutes:
if there are finite-horizon events in the queue, the scheduler thread will never
sleep longer than that. This is to quickly get back on track with the schedule
when the computer wakes up from sleep, if the sleep monitor is not working or
is not implemented for the particular operating system. However, if there are
only infinite-horizon events in the queue (meaning, DreamTime-scheduled events,
and the system is sleeping or "sleeping"), the scheduler will also sleep.
Hopefully this will also help the system stay properly asleep.

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