README.md

Sun, 05 Dec 2021 21:20:09 +0200

author
Tuomo Valkonen <tuomov@iki.fi>
date
Sun, 05 Dec 2021 21:20:09 +0200
changeset 142
ad1d4a29ec75
parent 140
a70ba964f455
permissions
-rw-r--r--

Update main module imports to relative form

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
139
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
30 Borgend naturally requires [Borg Backup][] to be installed as well as a working
142
ad1d4a29ec75 Update main module imports to relative form
Tuomo Valkonen <tuomov@iki.fi>
parents: 140
diff changeset
31 [Python 3](https://www.python.org/) installation. Install both according to the
ad1d4a29ec75 Update main module imports to relative form
Tuomo Valkonen <tuomov@iki.fi>
parents: 140
diff changeset
32 instructions for your operating system. With this done, located in the top-level
139
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
33 directory of the borgend source tree, you can install borgend
128
3e9d88b2c14b Improve installation instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 126
diff changeset
34
139
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
35 pip3 install .
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
36
139
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
37 This will also install some additional Python libraries
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
38 ([keyring](https://pypi.python.org/pypi/keyring),
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
39 [pyyaml](http://pyyaml.org/),
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
40 [rumps](https://github.com/jaredks/rumps), and, if not on MacOS,
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
41 [xdg](https://pypi.python.org/pypi/xdg/3.0.0)).
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
42 Now you can start borgend with
37
9fab8200f7eb README tune
Tuomo Valkonen <tuomov@iki.fi>
parents: 33
diff changeset
43
139
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
44 borgend
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
45
139
84b041f6f7f3 Update build instructions
Tuomo Valkonen <tuomov@iki.fi>
parents: 134
diff changeset
46 Before this, you will probably, however, want to create a configuration file as detailed below. A standalone application, explained below, can be more convenient for access to passwords from the system keyring.
41
e2641cb9ca6d --no-tray command line option for running on non-MacOS systems
Tuomo Valkonen <tuomov@iki.fi>
parents: 37
diff changeset
47
142
ad1d4a29ec75 Update main module imports to relative form
Tuomo Valkonen <tuomov@iki.fi>
parents: 140
diff changeset
48 If you do not wish to install borgend and would rather run it in-place, use
ad1d4a29ec75 Update main module imports to relative form
Tuomo Valkonen <tuomov@iki.fi>
parents: 140
diff changeset
49
ad1d4a29ec75 Update main module imports to relative form
Tuomo Valkonen <tuomov@iki.fi>
parents: 140
diff changeset
50 python3 -m borgend
ad1d4a29ec75 Update main module imports to relative form
Tuomo Valkonen <tuomov@iki.fi>
parents: 140
diff changeset
51
ad1d4a29ec75 Update main module imports to relative form
Tuomo Valkonen <tuomov@iki.fi>
parents: 140
diff changeset
52 in the toplevel directory of the borgend source tree.
ad1d4a29ec75 Update main module imports to relative form
Tuomo Valkonen <tuomov@iki.fi>
parents: 140
diff changeset
53
ad1d4a29ec75 Update main module imports to relative form
Tuomo Valkonen <tuomov@iki.fi>
parents: 140
diff changeset
54
25
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
55 ## Usage and configuration
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
56
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
57 ### Configuration file
efa4c61c6f01 Sample configuration file added along with a few words of documentation
Tuomo Valkonen <tuomov@iki.fi>
parents: 23
diff changeset
58
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
59 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
60 self-explanatory. The lists `common_parameters`, `create_parameters`, and
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
61 `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
62 to it after expansion of environment variables.
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
63
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
64 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
65 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
66 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
67 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
68 line with the `--help` option.
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
69
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
70 ### Passphrases
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
71
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
72 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
73 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
74 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
75 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
76 `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
77 ‘account’, you may use:
20
fdfbe5d7b677 Keychain support and random fixes
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
78
93
040a0479f51e README <80-line formatting, etc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 83
diff changeset
79 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
80
129
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
81 To permanently authenticate Borgend to use the keychain, and therefore not
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
82 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
83 useful to encapculate it into a macOS app. This can be done with
140
a70ba964f455 Update py2app discussion in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 139
diff changeset
84 [py2app](https://py2app.readthedocs.io/en/latest/install.html).
a70ba964f455 Update py2app discussion in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 139
diff changeset
85 To create a standalone app that you can launch at startup and give permanent
a70ba964f455 Update py2app discussion in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 139
diff changeset
86 permissions to the keychain, use
129
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
87
140
a70ba964f455 Update py2app discussion in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 139
diff changeset
88 python3 setup.py py2app
129
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 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
91 directory, and set it up to launch on login.
9f3ae6b3133f Improve installation instructions;
Tuomo Valkonen <tuomov@iki.fi>
parents: 128
diff changeset
92
140
a70ba964f455 Update py2app discussion in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 139
diff changeset
93 Py2app is _flaky_ to say the least. If the positions of sunspots so dictate,
a70ba964f455 Update py2app discussion in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 139
diff changeset
94 the above command may not create a working standalone application. If this is
a70ba964f455 Update py2app discussion in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 139
diff changeset
95 the case, you may attempt to add the `-A` option to the command. It will
a70ba964f455 Update py2app discussion in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 139
diff changeset
96 then create a non-standalone application. While not easily transferrable
a70ba964f455 Update py2app discussion in README
Tuomo Valkonen <tuomov@iki.fi>
parents: 139
diff changeset
97 between different machines, it will still help with keychain permissions.
130
4c3b655a89c5 Update Borg Backup link to main website.
Tuomo Valkonen <tuomov@iki.fi>
parents: 129
diff changeset
98

mercurial