Notifications natives : cibles mail, webhook, Gotify, matchers

Day 2 · ExploiterNiveau 2 · OpérerProcédureRédigé · à valider en lab

Configurez Proxmox VE pour que les échecs de sauvegarde, de réplication, les isolements de nœud (fencing) et les alertes disque arrivent à la bonne équipe, par mail SMTP authentifié ou par webhook vers votre outil de messagerie ou de ticketing. Le système repose sur deux objets : des cibles (targets, où envoyer) et des matchers (quels événements envoyer à quelles cibles).

Notions clés

Objet	Rôle	Remarque
Cible sendmail	Mail via le sendmail local (Postfix)	File d'attente et nouvelles tentatives assurées par Postfix
Cible smtp	Mail directement vers un relais SMTP (TLS, STARTTLS, authentification)	Pas de file d'attente : un relais indisponible = notification perdue
Cible gotify	Push vers un serveur Gotify (URL + jeton)	Respecte le proxy HTTP du Datacenter
Cible webhook	Requête HTTP (POST, PUT ou GET) avec en-têtes et corps en gabarit Handlebars	Teams, Slack, Discord, ntfy, outil de ticketing
Matcher	Règle : si l'événement correspond, notifier les cibles listées	Un matcher sans règle correspond à tout

Configuration commune au cluster : /etc/pve/notifications.cfg ; secrets (mot de passe SMTP, jeton Gotify, secrets de webhook) dans /etc/pve/priv/notifications.cfg, lisible par root uniquement.

Comportement par défaut. Une installation fournit une cible sendmail mail-to-root, qui écrit à l'adresse mail de l'utilisateur root@pam (saisie à l'installation), et un matcher default-matcher qui envoie tous les événements vers cette cible. Le courrier local adressé à root (ZED, cron, smartd) est intercepté par proxmox-mail-forward et devient un événement de type system-mail. Si Postfix n'est pas configuré pour relayer vers l'extérieur, ces mails ne partent nulle part.

Événements et champs utilisables

Événement	type	Sévérité	Autres champs
Sauvegarde réussie / en échec	vzdump	info / error	hostname, job-id (jobs planifiés)
Réplication en échec	replication	error	hostname, job-id
Nœud isolé (fenced) par la HA	fencing	error	hostname
Mises à jour disponibles	package-updates	info	hostname
Mail système pour root (ZED, smartd…)	system-mail	unknown	hostname

Règles d'un matcher : match-field exact:type=vzdump (plusieurs valeurs séparées par des virgules) ou regex:hostname=^pve0[1-3]$, match-severity warning,error, match-calendar mon..fri 8-18. mode all (défaut, toutes les règles) ou mode any (au moins une), invert-match pour inverser.

Avant de toucher la prod

• Relais SMTP identifié (serveur, port, mode TLS, compte de service) ou URL de webhook fournie par l'équipe destinataire.
• Flux sortant ouvert depuis les nœuds vers le relais (TCP 465 ou 587) ou vers l'URL du webhook.
• Adresse de destination validée : une boîte d'équipe, jamais une boîte personnelle.
• Copie de la configuration actuelle : cp /etc/pve/notifications.cfg /root/notifications.cfg.bak.
• Liste des alertes attendues par le MSP (contrats N2/N3 : le MSP reçoit souvent une copie, ne supprimez pas sa cible).

Étapes

Exemple : une cible SMTP mail-exploit pour l'équipe, une cible webhook teams-astreinte pour les erreurs, et deux matchers.

GUICLI

1. Datacenter → Notifications → Notification Targets → Add → SMTP.
   • Endpoint Name : mail-exploit ; Server : smtp.client.fr ; Encryption : TLS (port 465) ou STARTTLS (port 587).
   • Authenticate coché, Username, Password ; From Address : pve@client.fr.
   • Recipient(s) : utilisateurs PVE ou Additional Recipient(s) : exploitation@client.fr.
2. Cliquer Test sur la cible : le mail de test doit arriver en moins d'une minute.

3. Add → Webhook : Endpoint Name teams-astreinte, Method POST, URL fournie par l'outil, en-tête Content-Type: application/json, corps par exemple :

   {"text": "{{ escape title }} : {{ escape message }}"}
   

   Placer la partie confidentielle de l'URL dans Secrets et l'appeler par {{ secrets.<nom> }}. Tester.

4. Notification Matchers → Add : erreurs-astreinte, Match Rules : Match Severity = error ; Targets to notify : teams-astreinte et mail-exploit.

5. Add : info-exploit, règle Match Field type = vzdump, package-updates, system-mail ; cible mail-exploit.
6. Éditer default-matcher : le désactiver (Enable décoché) ou remplacer sa cible par mail-exploit, pour éviter les doublons et les mails perdus vers root.
7. Datacenter → Backup → chaque job → Edit → Notification mode : Notification system. Les anciens réglages Send email to sont alors ignorés.

Le fichier peut être édité directement ; il est répliqué par pmxcfs sur tous les nœuds.

# /etc/pve/notifications.cfg
smtp: mail-exploit
        server smtp.client.fr
        mode tls
        username pve-notif
        from-address pve@client.fr
        mailto exploitation@client.fr
        comment Equipe exploitation

gotify: gotify-astreinte
        server https://gotify.client.fr

matcher: erreurs-astreinte
        match-severity error
        target gotify-astreinte
        target mail-exploit

matcher: info-exploit
        mode all
        match-field exact:type=vzdump,package-updates,system-mail
        target mail-exploit

# /etc/pve/priv/notifications.cfg
smtp: mail-exploit
        password <mot-de-passe>

gotify: gotify-astreinte
        token <jeton>

pvesh get /cluster/notifications/targets                       # cibles connues
pvesh create /cluster/notifications/targets/mail-exploit/test  # envoi de test
vzdump 101 --storage pbs-local --notification-mode notification-system

Les webhooks se créent de préférence par la GUI (gabarits et secrets).

Recommandations MSP

• Deux canaux pour les erreurs : un mail d'équipe et un canal temps réel (webhook ou Gotify).
• Ne filtrez pas system-mail : c'est le canal des alertes ZFS (ZED) et SMART. Voir Scrub, SMART, alertes ZED.
• match-calendar sert à router vers l'astreinte hors heures ouvrées, pas à taire des erreurs.
• PBS 4 dispose du même système (Configuration → Notifications) : configurez-y les échecs de GC, verify et sync, utiles pour RB-14 et RB-15.

Vérifications

• Test sur chaque cible : message reçu.
• vzdump 101 --storage pbs-local sur une petite VM : notification info reçue sur mail-exploit uniquement.
• Sur un nœud de test, printf 'Subject: test root\n\ntest\n' | sendmail root : mail reçu sur la cible associée à system-mail.
• grep -c '^matcher' /etc/pve/notifications.cfg cohérent avec ce qui est attendu.

Rollback

Restaurer la copie : cp /root/notifications.cfg.bak /etc/pve/notifications.cfg, ou réactiver default-matcher dans la GUI. Les jobs repassés en Notification system peuvent revenir en Default (Auto).

Pièges vus en support

• Cible smtp et relais en panne : la notification est perdue sans nouvelle tentative. Gardez un second canal.
• Désactiver default-matcher sans créer de matcher couvrant system-mail : plus aucune alerte disque.
• Job de sauvegarde en mode Auto avec une adresse Send email to remplie : c'est l'ancien envoi par sendmail qui s'applique, pas vos matchers.
• Adresse mail de root@pam jamais modifiée depuis l'installation (boîte d'un ancien prestataire) : Datacenter → Permissions → Users → root → E-Mail.
• Matcher en mode all avec deux match-field sur des types différents : ne correspond jamais.

Quand ouvrir un ticket iTop

Test qui échoue alors que le relais répond depuis le nœud, notifications de fencing jamais reçues, besoin d'un webhook vers l'outil du MSP : P3. Joignez /etc/pve/notifications.cfg (sans le fichier priv) et journalctl -u pvedaemon --since "1 hour ago".

Ouvrir un ticket iTop

Pour aller plus loin

• Documentation PVE : Notifications · vzdump(1), option notification-mode
• Superviser avec Zabbix, Prometheus, InfluxDB
• Routine hebdomadaire