Retour au blog

Notifications Proxmox sur votre téléphone : sauvegardes, fencing, réplication et erreurs de disque

Notifications Proxmox sur votre téléphone : sauvegardes, fencing, réplication et erreurs de disque

La plupart des hôtes Proxmox envoient leurs notifications à root@pam, c’est-à-dire à une adresse e-mail saisie dans l’installeur il y a des années, distribuée par un Postfix qui n’a jamais reçu de relais. La sauvegarde nocturne échoue, un mail part dans une file d’attente locale, et vous le découvrez trois semaines plus tard, au moment où vous avez besoin de restaurer une VM.

L’autre configuration courante fonctionne, mais tout le monde l’ignore. Chaque tâche de sauvegarde envoie un long e-mail chaque nuit, tous disent « réussie », et celui qui dit « échec » ressemble exactement aux trente autres dans le dossier.

Depuis Proxmox VE 8.3 et Proxmox Backup Server 3.3, le système de notifications dispose d’une cible webhook générique. Elle peut appeler n’importe quelle API HTTP avec un corps que vous écrivez vous-même, donc elle peut envoyer une notification push directement sur votre téléphone, avec une priorité différente pour les échecs et pour les réussites. Pas de script sur l’hôte, pas de relais à maintenir.

De quoi avez-vous besoin

  • Proxmox VE 8.3 ou plus récent (toutes les versions 9.x conviennent), ou Proxmox Backup Server 3.3 ou plus récent. Les versions plus anciennes sont traitées plus bas.
  • L’application Pocket Alert sur iPhone ou Android et une clé API depuis Clés API.
  • Un accès à Datacenter → Notifications en tant que root@pam, ou à un utilisateur disposant de Mapping.Modify sur /mapping/notifications.

Ce que Proxmox peut vous signaler

Proxmox VE émet ces événements, chacun avec un type, une gravité et quelques champs de métadonnées :

ÉvénementtypeGravité
Sauvegarde réussievzdumpinfo
Sauvegarde échouéevzdumperror
Échec d’une tâche de réplication de stockagereplicationerror
Nœud de cluster isolé (fencing)fencingerror
Mises à jour système disponiblespackage-updatesinfo
Courrier pour root (smartd, ZFS ZED et autres)system-mailunknown

La dernière ligne compte plus qu’il n’y paraît. smartd vérifie vos disques toutes les 30 minutes et envoie un mail à root lorsqu’un disque commence à défaillir, et le démon d’événements ZFS envoie un mail à root au sujet des pools dégradés et des erreurs de scrub (ZED_EMAIL_ADDR="root" est la valeur par défaut). Proxmox transforme ces mails en événements system-mail, donc le même webhook qui signale les sauvegardes signale aussi un disque en train de mourir.

Configurer la cible webhook

Dans l’interface web, allez dans Datacenter → Notifications, puis, sous Notification Targets, cliquez sur Add → Webhook. Remplissez-la comme suit :

  • Endpoint Name : pocketalert
  • Method/URL : POST et https://api.pocketalert.app/v1/messages
  • Headers : Content-Type = application/json, et Token = {{ secrets.token }}
  • Secrets : token = votre clé API Pocket Alert

Puis le Body :

{
  "title": {{ json title }},
  "message": {{ json message }},
  "level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}

Plusieurs choses se passent ici :

  • {{ json title }} affiche la valeur sous forme de chaîne JSON complète, guillemets compris. Les rapports de sauvegarde sont des tableaux sur plusieurs lignes, et insérer {{ message }} entre guillemets casserait le JSON au premier retour à la ligne. Proxmox propose aussi {{ escape message }}, qui fait la même chose sans les guillemets.
  • La clé est un secret. Les secrets sont stockés dans /etc/pve/priv/notifications.cfg, lisible uniquement par root, et l’API ne renvoie jamais leurs valeurs. Proxmox les masque aussi dans ses messages d’erreur.
  • Le niveau suit la gravité. Proxmox affiche le corps avec Handlebars, qui dispose de if, eq et or. Les sauvegardes échouées, les échecs de réplication, les fencings et les mails de disque arrivent en high, ce qui passe à travers la Concentration sur iPhone. Les sauvegardes réussies et les avis de mise à jour arrivent en low : ils sont dans le fil si vous le souhaitez, mais ne font pas vibrer.

Enregistrez la cible et cliquez sur Test. Une notification de test devrait arriver en quelques secondes.

La cible ne fait rien tant qu’un matcher ne lui envoie pas d’événements. Sous Notification Matchers, cliquez sur Add, nommez-le pocketalert-all, puis, dans l’onglet Targets to notify, cochez pocketalert. Un matcher sans règle correspond à tous les événements.

La même chose depuis le shell

Si vous préférez la CLI, ou si vous gérez plusieurs clusters, pvesh fait le même travail. Les valeurs d’en-têtes, le corps et les secrets sont transmis encodés en base64 :

PA_KEY='your-api-key'
BODY='{
  "title": {{ json title }},
  "message": {{ json message }},
  "level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}'
b64() { printf '%s' "$1" | base64 -w0; }

pvesh create /cluster/notifications/endpoints/webhook \
  --name pocketalert --method post \
  --url https://api.pocketalert.app/v1/messages \
  --header "name=Content-Type,value=$(b64 application/json)" \
  --header "name=Token,value=$(b64 '{{ secrets.token }}')" \
  --secret "name=token,value=$(b64 "$PA_KEY")" \
  --body "$(b64 "$BODY")"

pvesh create /cluster/notifications/matchers --name pocketalert-all --target pocketalert
pvesh create /cluster/notifications/targets/pocketalert/test

Le résultat est écrit dans /etc/pve/notifications.cfg, qui est partagé dans le cluster : une seule configuration couvre donc chaque nœud (le corps encodé en base64 est raccourci ici) :

webhook: pocketalert
	method post
	url https://api.pocketalert.app/v1/messages
	header name=Content-Type,value=YXBwbGljYXRpb24vanNvbg==
	header name=Token,value=e3sgc2VjcmV0cy50b2tlbiB9fQ==
	body ewogICJ0aXRsZSI6IHt7IGpzb24gdGl0bGUgfX0s...

matcher: pocketalert-all
	target pocketalert

La clé elle-même se trouve dans /etc/pve/priv/notifications.cfg, sous la forme secret name=token,value=<base64>.

Niveau supérieur : un nœud isolé doit vous réveiller

Une sauvegarde échouée peut attendre le matin. Un nœud isolé signifie que la HA vient de couper un hôte, et cela mérite une notification push critical qui passe le mode Ne pas déranger. Les matchers peuvent le faire sans toucher au modèle de corps.

Créez une seconde cible webhook, pocketalert-critical, identique à la première sauf pour une ligne du corps :

  "level": "critical"

Remplacez ensuite le matcher attrape-tout par deux matchers qui se distinguent par le type d’événement :

matcher: pocketalert-all
	match-field exact:type=fencing
	invert-match true
	target pocketalert

matcher: pocketalert-fencing
	match-field exact:type=fencing
	target pocketalert-critical

invert-match inverse le premier matcher : le fencing ne va donc que vers la cible critique, et vous ne recevez pas deux notifications pour un même événement. La distribution critical à travers le mode Ne pas déranger est une fonctionnalité des offres payantes ; sur l’offre gratuite, elle arrive en high. Consultez les niveaux de priorité pour savoir ce que fait chaque niveau sur iOS et Android.

D’autres usages utiles des matchers :

  • Échecs uniquement. Ajoutez match-severity error,unknown à pocketalert-all et les sauvegardes réussies n’envoient plus rien. Nous les conserverions en low : une notification discrète « sauvegarde réussie » chaque nuit est le moyen le plus simple de remarquer quand elle cesse d’arriver.
  • Une seule tâche. match-field exact:job-id=backup-abc123 limite un matcher à une tâche planifiée. Les sauvegardes lancées avec Run now n’ont pas de job-id, elles ne correspondront donc pas.
  • Heures calmes. match-calendar mon..fri 9-17 limite un matcher aux heures de travail, et invert-match vous donne le reste.

Un bouton qui ouvre l’interface web

Les notifications push Pocket Alert peuvent contenir jusqu’à trois boutons d’action. Ajoutez-en un au corps, et une sauvegarde échouée ouvre l’interface Proxmox en un seul geste :

  "actions": [
    {"type": "view", "label": "Open Proxmox", "value": "https://pve1.lan:8006"}
  ]

Le téléphone ouvre lui-même l’URL, donc une adresse locale fonctionne dès que vous êtes sur votre réseau domestique ou sur votre VPN.

Proxmox Backup Server

PBS 3.3 et plus récent disposent du même système de notifications, sous Configuration → Notifications, avec la même cible webhook, le même corps et les mêmes helpers Handlebars. Sa configuration se trouve dans notifications.cfg et notifications-priv.cfg, sous /etc/proxmox-backup/.

Les événements sont différents et plus utiles pour un serveur de sauvegarde : ramasse-miettes (gc), prune, sync, verification, tape-backup et tape-load, ainsi que les échecs de renouvellement de certificats acme et package-updates. acme ne signale que les échecs et tape-load est un notice ; les autres existent en versions info et error, donc le même if dans le corps fonctionne sans modification. Les événements liés aux datastores (gc, prune, sync, verification, tape-backup) portent aussi un champ datastore, si bien que match-field regex:datastore=^offsite-.*$ peut envoyer les datastores hors site vers une autre cible.

Deux points de PBS à vérifier. Les datastores créés avant le système de notifications peuvent avoir un notification-mode encore réglé sur legacy-sendmail ; passez-le au système de notifications dans les options du datastore. Et PBS n’envoie les notifications package-updates que sur les hôtes disposant d’un abonnement actif.

Les limites, en toute honnêteté

  • L’hôte doit être en ligne pour signaler. Le webhook est envoyé par l’hôte Proxmox lui-même : s’il a perdu sa connexion montante ou s’il est éteint, rien ne part. Pour « tout le serveur est tombé », il faut une vérification depuis l’extérieur, comme une supervision de disponibilité sur une autre machine.
  • Les longs rapports de sauvegarde sont tronqués dans la notification push. Une sauvegarde de vingt invités produit un long tableau. La notification affiche environ les 3 premiers Ko ; le texte complet se trouve dans l’historique des messages de l’application.
  • system-mail regroupe tout ce qui est envoyé à root. Cela inclut smartd et ZFS, mais aussi la sortie de cron et tout autre message adressé à root sur votre système. Si cela devient bruyant, donnez à ces événements leur propre matcher avec match-field exact:type=system-mail et une cible plus discrète.
  • Pas de compatibilité Gotify. Proxmox dispose aussi d’une cible Gotify intégrée, et d’anciens guides l’utilisent pour les notifications push sur téléphone. Pocket Alert n’implémente pas l’API Gotify, donc cette cible ne peut pas pointer vers nous. Utilisez la cible webhook ci-dessus, ou consultez la comparaison entre Pocket Alert et Gotify.

Sur Proxmox VE 8.2 et versions antérieures

Mettre à jour reste la meilleure solution, puisque la cible webhook exige la 8.3. Si vous ne pouvez pas encore mettre à jour, un script de hook vzdump couvre le cas le plus important, les sauvegardes. Installez la CLI Pocket Alert sur le nœud en tant que root, exécutez pocketalert auth, et enregistrez ce script sous /usr/local/bin/vzdump-pocketalert :

#!/bin/sh
case "$1" in
  backup-abort) pocketalert send -t "Backup failed: $3 on $(hostname)" -m "Mode: $2" -l high ;;
  job-end)      pocketalert send -t "Backup job finished on $(hostname)" -m "Check the task log for details" -l low ;;
esac
exit 0

Rendez-le exécutable et ajoutez script: /usr/local/bin/vzdump-pocketalert dans /etc/vzdump.conf. vzdump l’appelle à chaque phase ; pour backup-abort, les deuxième et troisième arguments sont le mode de sauvegarde et l’identifiant de la VM.

Si rien n’arrive

  • Lancez d’abord Test. Si la notification de test arrive mais que les événements réels n’arrivent pas, la cible fonctionne et le problème vient du routage : vérifiez qu’un matcher désigne la cible et que ses règles correspondent.
  • Regardez le mode de notification de la tâche de sauvegarde. Une tâche qui a une adresse e-mail dans ses paramètres de notification et le mode par défaut auto utilise l’ancien sendmail et contourne entièrement le système de notifications. Supprimez l’adresse ou passez le mode au système de notifications ; dans /etc/pve/jobs.cfg, cela donne notification-mode notification-system.
  • Lisez le journal. journalctl --since "1 hour ago" | grep -i notif affiche les requêtes en échec. Un 401 signifie que la clé est incorrecte ; un 400 indique généralement que le corps n’est pas un JSON valide : vérifiez que vous avez utilisé {{ json message }} et non un simple {{ message }}.
  • Vérifiez le fil dans l’application. Les notifications low ne font aucun bruit, donc une sauvegarde réussie peut donner l’impression de ne jamais être arrivée. Elle se trouve dans l’historique des messages.

FAQ

Ai-je besoin d’un abonnement Proxmox ?

Non. Le système de notifications et la cible webhook font partie des dépôts gratuits. Le seul élément qui dépend d’un abonnement est la notification package-updates de PBS.

Cela fonctionne-t-il pour un nœud unique sans cluster ?

Oui. Un nœud unique lit le même /etc/pve/notifications.cfg. Dans un cluster, ce fichier est partagé, donc vous ne le configurez qu’une fois.

Puis-je aussi recevoir ces notifications par e-mail ?

Oui. Gardez la cible mail-to-root par défaut dans son matcher et ajoutez pocketalert à côté. Un matcher peut notifier plusieurs cibles, et chaque cible reçoit au plus une notification par événement.

Combien de notifications push cela consommera-t-il ?

Une par événement. Une tâche de sauvegarde nocturne ne donne qu’une seule notification pour l’ensemble de la tâche, et non une par invité ; un homelab typique en reçoit donc quelques-unes par jour. L’offre gratuite couvre 50 messages par jour sur un appareil.

Et TrueNAS, les événements d’alimentation de l’onduleur ou Uptime Kuma ?

Même principe, expéditeur différent. La page alertes homelab couvre les éléments courants d’une baie de serveur domestique, et alertes de sauvegarde traite des outils de sauvegarde autres que Proxmox.

Créez un compte gratuit, collez le corps dans une cible webhook, et laissez la prochaine sauvegarde échouée vous trouver au lieu de votre boîte mail.

Partager cet article