BorgBackup : un script commun, piloté par systemd et notifié par ntfy
Un seul script borgbackup pour tous les postes et serveurs, configuré par variables d'environnement, lancé par un service et un timer systemd, avec une notification ntfy qui donne la nature et le détail de l'incident.
Objectif
Avoir un seul script de sauvegarde BorgBackup pour tous les postes, portables et serveurs, avec :
- une configuration par variables d’environnement (aucune modification du script d’une machine à l’autre) ;
- un lancement par systemd (service template + timer) ;
- une notification ntfy à la fin de chaque sauvegarde, qui donne en cas de problème la nature et le détail de l’incident.
Vue d’ensemble
1
2
3
4
5
/etc/borgbackup/<nom>.env variables propres à la machine
│
borgbackup@<nom>.timer ──► borgbackup@<nom>.service ──► /usr/local/bin/borgbackup.sh
│
borg create ─► borg prune ─► ntfy (titre, priorité, détail)
Le service est une unité template : l’instance (e6230, vps1…) choisit le fichier /etc/borgbackup/<instance>.env. Ajouter une machine revient à créer un fichier .env et à activer un timer.
Les variables
Les quatre premières sont obligatoires : ce sont des chemins de fichiers. Le script vérifie qu’ils existent et sont lisibles, sinon il envoie une notification d’erreur de préparation.
| Variable | Rôle |
|---|---|
borg_passphrase |
fichier contenant la passphrase du dépôt |
borg_borgssh |
clé ssh privée |
borg_repository |
fichier contenant l’URL du dépôt |
borg_exclusions |
fichier d’exclusions (--exclude-from) |
borg_info |
libellé dans la notification (défaut : hostname) |
borg_path |
chemin sauvegardé (défaut : /) |
borg_ntfy_env |
fichier d’environnement ntfy (défaut : ~/.config/ntfy/ntfy.env) |
borg_stamp |
oui (défaut) ou non, voir plus bas |
Les dossiers à créer
1
2
3
4
sudo mkdir -p /etc/borgbackup
mkdir -p /home/USER/.config/borg
# si autre dossier sur root
sudo mkdir -p /root/.borg
Exemple de fichier
/etc/borgbackup/e6230.env(chemins absolus : systemd ne développe pas$HOMEdans unEnvironmentFile, et on n’utilise pas de guillemets)
/etc/borgbackup/e6230.env
1
2
3
4
5
6
7
borg_passphrase=/home/USER/.config/borg/e6230.passphrase
borg_borgssh=/home/USER/.config/borg/e6230.borgssh
borg_repository=/home/USER/.config/borg/e6230.repository
borg_exclusions=/home/USER/.config/borg/e6230.exclusions
borg_info=Portable DELL Latitude e6230
borg_ntfy_env=/home/USER/.config/ntfy/ntfy.env
borg_stamp=oui
Remplacer
/home/USER/.config/borgpar votre chemin
Installer Borg et initialiser le dépôt
Comprendre les codes de retour de Borg
La notification repose sur le code de retour de Borg, traduit ainsi :
| Code | Signification | Traitement |
|---|---|---|
| 0 | succès | notification low |
| 1 | avertissement (la sauvegarde est faite, mais avec des warnings, par exemple un fichier modifié pendant la lecture) | notification default, sauvegarde considérée comme faite |
| 2 | erreur | notification high, unité systemd en échec |
| 128 et plus | interruption par un signal | traité comme un échec |
En cas d’échec, le message contient le code, sa nature, les lignes significatives du log (connexion, lock, permission, espace disque, passphrase…) et les dix dernières lignes. Le message est tronqué à 3800 octets, car ntfy convertit en pièce jointe un message de plus de 4096 octets. Le log complet reste dans /var/tmp/borg-<id>-last.log.
Si borg create échoue, borg prune n’est pas exécuté : on ne supprime pas d’anciennes archives alors qu’aucune nouvelle n’a été créée.
Le flag du jour : borg_stamp
borg_stamp=oui(postes et portables, pas toujours allumés) : le timer est horaire, et le script se termine immédiatement si la sauvegarde du jour est faite (flag dans/var/tmp). Une sauvegarde manquée ou échouée est retentée à l’heure suivante.borg_stamp=non(VPS et serveurs toujours allumés) : pas de flag, le timer ne se déclenche qu’une fois par jour.
Le flag et le log portent un identifiant tiré du nom du fichier .repository (e6230.repository donne e6230), pour que plusieurs jobs coexistent sur une même machine.
systemd
Le service, en root pour pouvoir lire tout / :
/etc/systemd/system/borgbackup@.service
1
2
3
4
5
6
7
8
9
10
11
12
13
[Unit]
Description=Borgbackup (%i)
Wants=network-online.target
After=network-online.target
# Portable : ne pas lancer sur batterie (décommenter si souhaité)
#ConditionACPower=true
[Service]
Type=oneshot
EnvironmentFile=/etc/borgbackup/%i.env
ExecStart=/usr/local/bin/borgbackup.sh
Nice=19
IOSchedulingClass=idle
Le timer template, horaire (pour borg_stamp=oui) :
/etc/systemd/system/borgbackup@.timer
1
2
3
4
5
6
7
8
9
10
[Unit]
Description=Borgbackup (%i) : tentative horaire
[Timer]
OnCalendar=hourly
Persistent=true
RandomizedDelaySec=5min
[Install]
WantedBy=timers.target
Pour un serveur (borg_stamp=non), un drop-in surcharge l’horaire de l’instance (sudo systemctl edit borgbackup@vps1.timer) :
1
2
3
[Timer]
OnCalendar=
OnCalendar=*-*-* 03:22
La ligne OnCalendar= vide est indispensable : OnCalendar est une liste, et sans ce reset l’horaire horaire du template resterait actif.
Activation et suivi :
1
2
3
4
5
6
7
8
sudo mkdir -p /etc/borgbackup
sudo chmod 600 /etc/borgbackup/*.env
sudo systemctl daemon-reload
sudo systemctl enable --now borgbackup@e6230.timer
sudo systemctl start borgbackup@e6230.service # test immédiat
journalctl -u borgbackup@e6230.service -f
systemctl list-timers 'borgbackup@*'
Les pièges rencontrés
#!/bin/shau lieu debash:[[ … ]]etPIPESTATUSsont des bashismes. Avec dash, le test final échouait en silence.BORG_RSHentre apostrophes :$HOMEn’était pas développé. Guillemets doubles obligatoires.ssh -o BatchMode=yes: ssh échoue tout de suite au lieu d’attendre un mot de passe, et l’erreur arrive dans la notification.- Les variables d’un pipeline : dans
{ … } | head | notify "$title", chaque élément du pipeline s’exécute dans son propre sous-shell, en parallèle.$titleest développé avant que le premier bloc ne l’ait défini, donc la notification arrive sans titre. La solution est de calculer titre, priorité et tags avant, et d’écrire le corps dans un fichier. - Le code de sortie : le script se terminait par la commande
curl, donc systemd voyait toujours un succès. Il faut finir parexit 1en cas d’échec pour que l’unité passe enfailed. - Root et
known_hosts: le service tourne en root, donc ssh lit/root/.ssh/known_hosts. Il faut une première connexion manuelle en root pour accepter l’empreinte du serveur (BatchModeinterdit de poser la question). Le cache Borg est aussi propre à root.
Le script borgbackup.sh
/usr/local/bin/borgbackup.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
#!/bin/bash
# /usr/local/bin/borgbackup.sh — script commun
#
# Variables à exporter avant l'exécution (chemins de fichiers) :
# borg_passphrase fichier contenant la passphrase du dépôt
# borg_borgssh clé ssh privée
# borg_repository fichier contenant l'URL du dépôt
# borg_exclusions fichier d'exclusions (--exclude-from)
# Optionnelles :
# borg_info libellé affiché dans la notification (défaut : hostname)
# borg_path chemin à sauvegarder (défaut : /)
# borg_ntfy_env fichier d'env ntfy (défaut : ~/.config/ntfy/ntfy.env)
# borg_stamp oui (défaut) : une seule sauvegarde par jour, flag /var/tmp
# non : pas de flag, le timer décide de la fréquence
NTFY_ENV="${borg_ntfy_env:-$HOME/.config/ntfy/ntfy.env}"
if [ ! -r "$NTFY_ENV" ]; then
echo "Fichier ntfy introuvable : $NTFY_ENV" >&2
exit 2
fi
. "$NTFY_ENV"
INFO="${borg_info:-$(hostname)}"
BORG_PATH="${borg_path:-/}"
# --- notification ntfy -------------------------------------------------------
# usage : notify "titre" "priorité" "tags" < corps
notify() {
curl -sS -X POST \
-H "X-Email: $NTFY_EMAIL" \
-H "Title: $1" \
-H "Authorization: Bearer $NTFY_TOKEN" \
-H "Priority: $2" \
-H "Tags: $3" \
-H "Content-Type: text/plain; charset=utf-8" \
--data-binary @- \
"$NTFY_URL"
}
# --- vérification des 4 variables et des fichiers ----------------------------
missing=""
for v in borg_passphrase borg_borgssh borg_repository borg_exclusions; do
eval "val=\${$v:-}"
if [ -z "$val" ]; then
missing="$missing\nVariable non définie : $v"
elif [ ! -r "$val" ]; then
missing="$missing\nFichier introuvable ou illisible : $v=$val"
fi
done
if [ -n "$missing" ]; then
printf "Configuration incomplète :$missing\n" | tee /dev/stderr | \
notify "💻 $INFO : Borgbackup ❌ préparation" "high" "rotating_light"
exit 2
fi
# --- identifiant dérivé du fichier repository (ex. e6230) --------------------
ID="$(basename "$borg_repository")"
ID="${ID%.repository}"
STAMP="/var/tmp/borg-last-backup-$ID"
FULLLOG="/var/tmp/borg-$ID-last.log"
TODAY=$(date +%F)
# --- flag du jour (borg_stamp=oui par défaut) --------------------------------
STAMP_ON=1
case "${borg_stamp:-oui}" in
non|NON|no|NO|false|0) STAMP_ON=0 ;;
esac
if [ "$STAMP_ON" -eq 1 ] && [ -f "$STAMP" ] && [ "$(cat "$STAMP")" = "$TODAY" ]; then
echo "Backup déjà fait aujourd'hui ($TODAY)."
exit 0
fi
LOG_DIR=$(mktemp -d)
trap 'rm -rf "$LOG_DIR"' EXIT
# --- nature de l'incident selon le code de retour borg -----------------------
rc_nature() {
rc=$1
if [ "$rc" -eq 0 ]; then echo "OK"
elif [ "$rc" -eq 1 ]; then echo "AVERTISSEMENT (opération terminée, mais avec des warnings)"
elif [ "$rc" -eq 2 ]; then echo "ERREUR (l'opération a échoué)"
elif [ "$rc" -ge 128 ]; then echo "INTERROMPU par le signal $((rc - 128))"
else echo "CODE DE RETOUR INATTENDU ($rc)"
fi
}
# --- exécute une commande, garde sa sortie dans un log, renvoie son rc -------
run_step() {
logfile=$1; shift
"$@" 2>&1 | tee "$logfile"
return "${PIPESTATUS[0]}"
}
# --- détail d'une étape en échec : lignes parlantes + fin du log -------------
step_detail() {
label=$1; rc=$2; logfile=$3
echo "❌ $label : $(rc_nature "$rc") [rc=$rc]"
if [ -s "$logfile" ]; then
echo "-- Lignes significatives --"
grep -iE 'error|erreur|fail|warning|exception|traceback|denied|refused|timed out|timeout|connection|lock|passphrase|repository|no such file|not found|space' "$logfile" | tail -n 15
echo "-- Fin du log --"
tail -n 10 "$logfile"
else
echo "(aucune sortie de borg)"
fi
echo
}
# --- préparation -------------------------------------------------------------
t=$(date +%s)
export BORG_PASSPHRASE="$(cat "$borg_passphrase")"
# BatchMode : échoue au lieu de demander un mot de passe ssh
export BORG_RSH="ssh -i $borg_borgssh -o BatchMode=yes -o ServerAliveInterval=60 -o ServerAliveCountMax=5"
BACKUP_DATE="$(date +%Y-%m-%d-%Hh%M)"
BORG_REPOSITORY="$(cat "$borg_repository")"
# --- borg create -------------------------------------------------------------
LOG_CREATE="$LOG_DIR/create.log"
run_step "$LOG_CREATE" \
borg create -v --stats --exclude-from "$borg_exclusions" \
"${BORG_REPOSITORY}::${BACKUP_DATE}" "$BORG_PATH"
rc_create=$?
# --- borg prune (sauté si le create a échoué) --------------------------------
LOG_PRUNE="$LOG_DIR/prune.log"
if [ "$rc_create" -le 1 ]; then
run_step "$LOG_PRUNE" \
borg prune -v --stats --keep-daily=7 --keep-weekly=1 --keep-monthly=1 \
"$BORG_REPOSITORY"
rc_prune=$?
else
rc_prune=-1
echo "Prune non exécuté : le borg create a échoué (rc=$rc_create)." > "$LOG_PRUNE"
fi
# --- durée -------------------------------------------------------------------
d=$(( $(date +%s) - t ))
DUREE=$(( d / 3600 ))h$(( (d % 3600) / 60 ))m$(( d % 60 ))s
# --- bilan -------------------------------------------------------------------
# État global : 0 = OK, 1 = avertissement, 2 = échec
if [ "$rc_create" -ge 2 ] || [ "$rc_prune" -ge 2 ] || [ "$rc_prune" -eq -1 ]; then
status=2
elif [ "$rc_create" -eq 1 ] || [ "$rc_prune" -eq 1 ]; then
status=1
else
status=0
fi
# Flag du jour : posé si la sauvegarde est faite (OK ou avertissement)
[ "$STAMP_ON" -eq 1 ] && [ "$status" -le 1 ] && date +%F > "$STAMP"
{
echo "=== borg create ($BACKUP_DATE) ==="; cat "$LOG_CREATE"
echo; echo "=== borg prune ==="; cat "$LOG_PRUNE"
} > "$FULLLOG"
# --- titre / priorité / tags (calculés hors pipeline) ------------------------
if [ "$status" -eq 0 ]; then
title="💻 $INFO : Borgbackup ✔️ en $DUREE"
prio="low"; tags="white_check_mark"
elif [ "$status" -eq 2 ]; then
title="💻 $INFO : Borgbackup ❌ ÉCHEC en $DUREE"
prio="high"; tags="rotating_light"
else
title="💻 $INFO : Borgbackup ⚠️ avertissement en $DUREE"
prio="default"; tags="warning"
fi
# --- corps du message --------------------------------------------------------
BODY="$LOG_DIR/body.txt"
{
if [ "$status" -eq 0 ]; then
echo "✔️ borg create : OK"
tail -n 12 "$LOG_CREATE"
echo
echo "✔️ borg prune : OK"
else
[ "$rc_create" -ne 0 ] && step_detail "borg create" "$rc_create" "$LOG_CREATE"
if [ "$rc_prune" -eq -1 ]; then
echo "⏭️ borg prune : non exécuté (échec du create)"
elif [ "$rc_prune" -ne 0 ]; then
step_detail "borg prune" "$rc_prune" "$LOG_PRUNE"
fi
echo "Log complet : $FULLLOG"
fi
} > "$BODY"
# --- envoi -------------------------------------------------------------------
head -c 3800 "$BODY" | notify "$title" "$prio" "$tags"
# Code de sortie pour systemd : échec = unité en "failed"
[ "$status" -lt 2 ] || exit 1
À rendre exécutable : sudo chmod 755 /usr/local/bin/borgbackup.sh.
Vérifier
- Casser temporairement le chemin du dépôt pour vérifier que la notification d’échec arrive avec son détail.
- Lancer
borg listet unborg extractd’un fichier test : une sauvegarde qu’on n’a jamais restaurée n’est pas une sauvegarde. - Surveiller
systemctl --failed: grâce au code de sortie, une sauvegarde en échec y apparaît.
