From 281b62c137063c2bb24820063f3ec67dfd458aee Mon Sep 17 00:00:00 2001 From: lasimik Date: Mon, 17 May 2021 14:00:20 +0000 Subject: [PATCH] Update 'Readme.md' --- Readme.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/Readme.md b/Readme.md index 568af11..639bba4 100644 --- a/Readme.md +++ b/Readme.md @@ -1,9 +1,8 @@ - # Desktop notifications from borgmatic when it is run from systemd -How to set up desktop notifications to an arbitrary user, while borgmatic is automatically run from a systemd timer. That implies a Linux machine, of course. +This HowTo shows the way to set up *notifications from `borgmatic` to an arbitrary user*, when borgmatic runs as `root` because it was automatically started from a `system` timer. That implies a Linux machine, of course. -This includes workarounds for current (borgmatic 1.5.13, borg 1.1.16) limitations of borg/borgmatic. They may or may not be necessary in the future. This HowTo was written on 2021-05-17, some downloaded files may have changed since then. +It includes workarounds for current (borgmatic 1.5.13, borg 1.1.16) limitations of `borgmatic` and/or `borg`. Also some downloaded files may have changed since the HowTo was written (2021-05-17). The following needs to be set up for the notifications: @@ -14,13 +13,12 @@ The template from the borgmatic site (the`borgmatic.timer`) is fine, insert a st --- - ### systemd service Again, the template from the borgmatic site (the `borgmatic.service`) is good, but needs an essential change: The line `CapabilityBoundingSet=…` must grant the additional capabilities `AP_SETUID `and `CAP_SETGID`. This will allow borgmatic (and whatever is called from it!!) to act as a different user (other than root). -*__This means a softening of security settings.__ Make sure all permissions on borgmatic and scripts are set correctly!* +*__This weakens security settings.__ Make sure all permissions on borgmatic and scripts are set correctly!* --- @@ -37,9 +35,8 @@ The `notify-send` command sets the urgency of the notifications, and sends a hea hooks: before_backup: - sudo -u NAME DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/UID/bus notify-send --urgency=normal 'Headline' 'Body text goes here.' - ``` -(Note: The config file is YAML, so no shell line continuation (` \`). And spaces, not tabs.) +(Note: All after `sudo …` is one line. The config file is YAML, so there's no shell line continuation (` \`). And spaces, not tabs.) --- @@ -50,7 +47,6 @@ Borgmatic calls an executable script that can do more magic and send the notific hooks: on_error: - /etc/borgmatic/notify-error.sh "{configuration_filename}" "{repository}" "{error}" "{output}" - ``` (Note: The placeholders (`{configuration_filename}`, `{repository}`, `{error}`, and `{output}`) are not all supported under all hooks.) @@ -71,21 +67,19 @@ sudo -u NAME DISPLAY=:0 \ --- --- - ### Example for Overdue Backups Alerts #### In the borgmatic config To know when the last complete backup was made, even if there is no connection to the repository, the date and time needs to be stored locally (here in a `last-successful-backup` file), after every successful backup (hook `after_backup:`). This example uses date and time of the last *complete* backup. Borgmatic does not supply this in a placeholder, so it is identified with `borgmatic list --successful --last 1`, returning only date and time (`--format {time}`) and without control characters (`--no-color `), then the header line is skipped (`sed -n 2p`), and the timezone (that the borgmatic return lacks) is appended (`date +'%:z'`). -It's a good idea to store this value together with the other files for that repository, so `/root/{repository}` would be nice. Unfortunately, `{repository}` is not resolved within borgmatic; the path must be manually copied from the top of the config file and append to `/root/`. +It's a good idea to store this value together with the other files for that repository, so `/root/{repository}` would be nice. Unfortunately, `{repository}` is not resolved within borgmatic; the path must be manually copied from the top of the config file and append to `/root/`, *but __without the `:`__ after the URL!* If an error occurs during backup, a script (here, `notify-error.sh`) will read that date and time and do the subsequent processing. Example for a remote repository: ``` - location: repositories: - BackupUser@BackupServer:/path/to/repository @@ -94,12 +88,12 @@ hooks: after_backup: - echo "$(borgmatic list --successful --last 1 --format {time} --no-color \ | sed -n 2p) $(date +'%:z')" \ - > "/root/BackupUser@BackupServer:/path/to/repository/last-successful-backup" + > "/root/BackupUser@BackupServer/path/to/repository/last-successful-backup" ... on_error: - /etc/borgmatic/notify-error.sh "{configuration_filename}" "{repository}" "{error}" "{output}" ``` -(Note: Inside the quotes of `echo …` line continuation (` \`) can be used to improve readability.) +(Note: Line continuation (` \`) can be used inside the quotes of `echo …` to improve readability.) --- @@ -163,7 +157,6 @@ else # backup age is 24 hours or less sudo -u "$NOTIFYUSER" DISPLAY=:0 "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$NOTIFYUSERID/bus" \ notify-send --urgency=critical "Borgmatic Backup Failed" "$NOTIFYTEXT" fi - ``` ![picture](https://projects.torsion.org/lasimik/borgmatic_notifications/raw/branch/master/borgmatic-notification.png)