Post

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.

BorgBackup : un script commun, piloté par systemd et notifié par ntfy

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 $HOME dans un EnvironmentFile, 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/borg par votre chemin

Installer Borg et initialiser le dépôt

BorgBackup VPS Générique

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/sh au lieu de bash : [[ … ]] et PIPESTATUS sont des bashismes. Avec dash, le test final échouait en silence.
  • BORG_RSH entre apostrophes : $HOME n’é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. $title est 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 par exit 1 en cas d’échec pour que l’unité passe en failed.
  • 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 (BatchMode interdit 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 list et un borg extract d’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.
Cet article est sous licence CC BY 4.0 par l'auteur.