README.md

Tue, 21 Apr 2020 10:05:22 -0500

author
Tuomo Valkonen <tuomov@iki.fi>
date
Tue, 21 Apr 2020 10:05:22 -0500
changeset 130
4c3b655a89c5
parent 129
9f3ae6b3133f
child 131
d5351f9fe8b8
permissions
-rw-r--r--

Update Borg Backup link to main website.
Add note that it needs to be installed.

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
126
cf4e7b6f5f5e Adapt README to be directly useful for the website
Tuomo Valkonen <tuomov@iki.fi>
parents: 123
diff changeset
3 <a href="media/borgend.png"><img src="media/borgend.jpg" style="max-width: 100%" alt="Borgend screenshot"></a>
122
8d2881338a4a screenshot, typofixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 120
diff changeset
4
8d2881338a4a screenshot, typofixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 120
diff changeset
5 Borgend is a retrying and queuing scheduler as well as a macOS tray icon for
130
4c3b655a89c5 Update Borg Backup link to main website.
Tuomo Valkonen <tuomov@iki.fi>
parents: 129
diff changeset
6 [Borg Backup][]. If you are not
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
7 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
8 scheduler.
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
9
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
10 * 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
11 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
12 you wish, you can also choose “realtime” scheduling.
13
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
13
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
14 * 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
15 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
16 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
17 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
18 repository is available.
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
19
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
20 * 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
21 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
22 intervals.
65
6fed67863b00 README and config.example.yaml updates to describe queuing features
Tuomo Valkonen <tuomov@iki.fi>
parents: 56
diff changeset
23
13
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
24 The lead author is Tuomo Valkonen (<tuomov@iki.fi>).
1813654427d7 README/LICENSE
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
25
130
4c3b655a89c5 Update Borg Backup link to main website.
Tuomo Valkonen <tuomov@iki.fi>
parents: 129
diff changeset
26 [Borg Backup]: https://www.borgbackup.org/
4c3b655a89c5 Update Borg Backup link to main website.
Tuomo Valkonen <tuomov@iki.fi>
parents: 129
diff changeset
27
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
28 ## Installation
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
29
130
4c3b655a89c5 Update Borg Backup link to main website.
Tuomo Valkonen <tuomov@iki.fi>
parents: 129
diff changeset
30 Borgend naturally requires [Borg Backup][] to be installed. Borgend is written
4c3b655a89c5 Update Borg Backup link to main website.
Tuomo Valkonen <tuomov@iki.fi>
parents: 129
diff changeset
31 in [Python](https://www.python.org/), and also requires a working python3 installation.
4c3b655a89c5 Update Borg Backup link to main website.
Tuomo Valkonen <tuomov@iki.fi>
parents: 129
diff changeset
32 Install both according to the instructions for your operating system. Borgend also
4c3b655a89c5 Update Borg Backup link to main website.
Tuomo Valkonen <tuomov@iki.fi>
parents: 129
diff changeset
33 requires some additional Python libraries. To install these, on macOS, run
128
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
34
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
35 pip3 install keyring pyyaml rumps
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
36
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
37 On other systems, run
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
38
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
39 pip3 install keyring pyyaml xdg
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
40
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
41 This will install the following Python packages:
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
42
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
43 - [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
44 from the keychain
56
d63f6e9a4633 pyyaml was missing from listed dependencies
Tuomo Valkonen <tuomov@iki.fi>
parents: 47
diff changeset
45 - [pyyaml](http://pyyaml.org/) for parse configuration files
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
46 - [rumps](https://github.com/jaredks/rumps) (Ridiculously Uncomplicated
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
47 macOS Python Statusbar apps)
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
48 - [xdg](https://pypi.python.org/pypi/xdg/3.0.0) for configuration file
128
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
49 location (not needed on macOS)
37
9fab8200f7eb README tune
Tuomo Valkonen <tuomov@iki.fi>
parents: 33
diff changeset
50
129
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
51 With the dependencies satisfied, and Borgend downloaded, it may be run from
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
52 its download location with
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
53
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
54 python3 borgend.py
22
c3e95212e3f0 py2app standalone app generation
Tuomo Valkonen <tuomov@iki.fi>
parents: 20
diff changeset
55
129
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
56 Before this, you will probably, however, want to create a configuration file as detailed below.
41
e2641cb9ca6d --no-tray command line option for running on non-MacOS systems
Tuomo Valkonen <tuomov@iki.fi>
parents: 37
diff changeset
57
25
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
58 ## Usage and configuration
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
59
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
60 ### Configuration file
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
61
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
62 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
63 self-explanatory. The lists `common_parameters`, `create_parameters`, and
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
64 `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
65 to it after expansion of environment variables.
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
66
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
67 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
68 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
69 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
70 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
71 line with the `--help` option.
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
72
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
73 ### Passphrases
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
74
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
75 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
76 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
77 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
78 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
79 `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
80 ‘account’, you may use:
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
81
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
82 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
83
129
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
84 To permanently authenticate Borgend to use the keychain, and therefore not
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
85 have to enter the keychain password every time Borgend is launched, it is
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
86 useful to encapculate it into a macOS app. This can be done with
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
87
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
88 - [py2app](https://py2app.readthedocs.io/en/latest/install.html).
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
89
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
90 To create an app that you can launch at startup and give permanent permissions
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
91 to the keychain, use
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
92
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
93 python3 setup.py py2app -A
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
94
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
95 The app hould be placed under `dist/`. Copy it to your `Applications`
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
96 directory, and set it up to launch on login.
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
97
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
98 If you are keen on wasting your life, you can try to run py2app without the
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
99 `-A` option to create a standalone app that you can copy to computers without
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
100 Python installed. This will, however, most likely not work because py2app
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
101 is shit. Currently (2018-09-18) it is not working with the keyring package.
130
4c3b655a89c5 Update Borg Backup link to main website.
Tuomo Valkonen <tuomov@iki.fi>
parents: 129
diff changeset
102

mercurial