Notifiche push Proxmox sul telefono: backup, fencing, replica e errori disco

La maggior parte degli host Proxmox invia le notifiche a root@pam, cioè a un indirizzo email inserito anni fa nell'installer, consegnato da un Postfix che non ha mai avuto un relay configurato. Il backup notturno fallisce, la mail finisce in una coda locale, e lo scopri tre settimane dopo, quando devi ripristinare una VM.
L'altra configurazione comune funziona, ma viene ignorata. Ogni job di backup manda ogni notte una lunga email, tutte dicono "riuscito", e quella che dice "fallito" sembra identica alle altre trenta nella cartella.
Da Proxmox VE 8.3 e Proxmox Backup Server 3.3, il sistema di notifiche ha un target webhook generico. Può chiamare qualsiasi API HTTP con un body che scrivi tu, quindi può inviare una notifica push direttamente al telefono, con priorità diverse per fallimenti e successi. Nessuno script sull'host e nessun relay da mantenere.
Cosa ti serve
- Proxmox VE 8.3 o successivo (va bene qualsiasi 9.x), oppure Proxmox Backup Server 3.3 o successivo. Le versioni precedenti sono trattate più avanti.
- L'app Pocket Alert su iPhone o Android e una chiave API da Chiavi API.
- Accesso a Datacenter → Notifications come
root@pamo come utente conMapping.Modifysu/mapping/notifications.
Cosa può dirti Proxmox
Proxmox VE emette questi eventi, ognuno con un type, una severità e alcuni campi di metadati:
| Evento | type | Severità |
|---|---|---|
| Backup riuscito | vzdump | info |
| Backup fallito | vzdump | error |
| Job di replica dello storage fallito | replication | error |
| Nodo del cluster sottoposto a fencing | fencing | error |
| Aggiornamenti di sistema disponibili | package-updates | info |
| Posta per root (smartd, ZFS ZED e altri) | system-mail | unknown |
L'ultima riga conta più di quanto sembri. smartd controlla i dischi ogni 30 minuti e manda una mail a root quando uno inizia a guastarsi, e il demone di eventi ZFS manda a root mail su pool degradati ed errori di scrub (ZED_EMAIL_ADDR="root" è il default). Proxmox trasforma quelle mail in eventi system-mail, quindi lo stesso webhook che segnala i backup segnala anche un disco che sta morendo.
Configura il target webhook
Nell'interfaccia web, vai su Datacenter → Notifications e, sotto Notification Targets, clicca Add → Webhook. Compila così:
- Endpoint Name:
pocketalert - Method/URL:
POSTehttps://api.pocketalert.app/v1/messages - Headers:
Content-Type=application/json, eToken={{ secrets.token }} - Secrets:
token= la tua chiave API Pocket Alert
E il Body:
{
"title": {{ json title }},
"message": {{ json message }},
"level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}
Succedono alcune cose qui:
{{ json title }}restituisce il valore come stringa JSON completa, virgolette incluse. I report di backup sono tabelle su più righe, e inserire{{ message }}tra virgolette romperebbe il JSON al primo a capo. Proxmox ha anche{{ escape message }}, che fa lo stesso senza le virgolette attorno.- La chiave è un segreto. I segreti sono salvati in
/etc/pve/priv/notifications.cfg, leggibile solo da root, e l'API non restituisce mai i loro valori. Proxmox li maschera anche nei messaggi di errore. - Il livello segue la severità. Proxmox renderizza il body con Handlebars, che ha
if,eqeor. I backup falliti, la replica fallita, il fencing e le mail di disco arrivano comehigh, che su iPhone supera Full immersion. I backup riusciti e gli avvisi di aggiornamento arrivano comelow: sono nel feed se li vuoi, ma non fanno vibrare.
Salva il target e clicca Test. Una notifica di prova dovrebbe arrivare in pochi secondi.
Il target non fa nulla finché un matcher non gli instrada gli eventi. Sotto Notification Matchers, clicca Add, chiamalo pocketalert-all, e nella scheda Targets to notify spunta pocketalert. Un matcher senza regole corrisponde a ogni evento.
La stessa cosa dalla shell
Se preferisci la CLI, o gestisci più cluster, pvesh fa lo stesso. I valori degli header, il body e i segreti vengono passati in 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
Il risultato finisce in /etc/pve/notifications.cfg, condiviso in tutto il cluster, quindi una sola configurazione copre ogni nodo (il body in base64 è abbreviato):
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 chiave stessa si trova in /etc/pve/priv/notifications.cfg come secret name=token,value=<base64>.
Secondo livello: un nodo sottoposto a fencing dovrebbe svegliarti
Un backup fallito può aspettare il mattino. Un nodo sottoposto a fencing significa che HA ha appena terminato un host, e questo merita una notifica push critical che passi Non disturbare. I matcher possono farlo senza toccare il template del body.
Crea un secondo target webhook, pocketalert-critical, identico al primo tranne che per una riga del body:
"level": "critical"
Poi sostituisci il matcher catch-all con due matcher che si dividono in base al tipo di evento:
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 inverte il primo matcher, così il fencing va solo al target critical e non ricevi due push per lo stesso evento. La consegna critical attraverso Non disturbare è una funzione dei piani a pagamento; sul piano gratuito arriva come high. Vedi livelli di priorità per capire cosa fa ogni livello su iOS e Android.
Altre cose per cui i matcher sono utili:
- Solo i fallimenti. Aggiungi
match-severity error,unknownapocketalert-alle i backup riusciti smettono di inviare qualsiasi cosa. Li terremmo comelow: un silenzioso "backup riuscito" ogni notte è il modo più semplice per accorgerti quando smette di arrivare. - Un solo job.
match-field exact:job-id=backup-abc123limita un matcher a un singolo job pianificato. I backup avviati con Run now non hannojob-id, quindi non corrispondono. - Ore di silenzio.
match-calendar mon..fri 9-17limita un matcher all'orario di lavoro, einvert-matchti dà il resto.
Un pulsante che apre l'interfaccia web
Le notifiche push di Pocket Alert possono contenere fino a tre pulsanti di azione. Aggiungine uno al body e un backup fallito apre l'interfaccia Proxmox con un solo tocco:
"actions": [
{"type": "view", "label": "Open Proxmox", "value": "https://pve1.lan:8006"}
]
Il telefono apre l'URL direttamente, quindi un indirizzo locale funziona ogni volta che sei sulla rete di casa o in VPN.
Proxmox Backup Server
PBS 3.3 e successivi hanno lo stesso sistema di notifiche sotto Configuration → Notifications, con lo stesso target webhook, lo stesso body e gli stessi helper Handlebars. La sua configurazione vive in notifications.cfg e notifications-priv.cfg sotto /etc/proxmox-backup/.
Gli eventi sono diversi e più utili per un backup server: garbage collection (gc), prune, sync, verification, tape-backup e tape-load, oltre ai fallimenti di rinnovo dei certificati acme e a package-updates. acme segnala solo i fallimenti e tape-load è un notice; gli altri arrivano nelle versioni info ed error, quindi lo stesso if nel body funziona senza modifiche. Gli eventi sui datastore (gc, prune, sync, verification, tape-backup) portano anche un campo datastore, quindi match-field regex:datastore=^offsite-.*$ può inviare i datastore offsite a un target diverso.
Due dettagli di PBS da controllare. I datastore creati prima del sistema di notifiche possono avere un notification-mode ancora impostato su legacy-sendmail; passalo al sistema di notifiche nelle opzioni del datastore. E PBS invia le notifiche package-updates solo sugli host con una subscription attiva.
Limiti onesti
- L'host deve essere online per segnalare. Il webhook viene inviato dall'host Proxmox stesso, quindi se ha perso la connessione o è spento, non esce nulla. Per "tutta la macchina è giù" ti serve un controllo dall'esterno, come un monitor di uptime su un'altra macchina.
- I report di backup lunghi vengono tagliati nella push. Un backup di venti guest produce una tabella lunga. La push mostra circa i primi 3 KB; il testo completo è nella cronologia dei messaggi nell'app.
system-mailè tutto ciò che viene inviato a root. Include smartd e ZFS, ma anche l'output di cron e qualsiasi altra cosa che mandi mail a root sul tuo sistema. Se diventa rumoroso, dai a questi eventi un matcher dedicato conmatch-field exact:type=system-maile un target più silenzioso.- Nessuna compatibilità con Gotify. Proxmox ha anche un target Gotify integrato, e le guide più vecchie lo usano per le push sul telefono. Pocket Alert non implementa l'API Gotify, quindi quel target non può puntare a noi. Usa il target webhook qui sopra, oppure leggi come Pocket Alert si confronta con Gotify.
Su Proxmox VE 8.2 e precedenti
Aggiornare è la soluzione migliore, perché il target webhook richiede la 8.3. Se non puoi ancora aggiornare, uno script hook di vzdump copre il caso più importante, i backup. Installa la CLI di Pocket Alert sul nodo come root, esegui pocketalert auth, e salva questo file come /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
Rendilo eseguibile e aggiungi script: /usr/local/bin/vzdump-pocketalert a /etc/vzdump.conf. vzdump lo chiama a ogni fase; per backup-abort il secondo e il terzo argomento sono la modalità di backup e l'ID della VM.
Se non arriva nulla
- Esegui prima Test. Se la push di prova arriva ma gli eventi reali no, il target funziona e il problema è l'instradamento: verifica che un matcher indichi il target e che le sue regole corrispondano.
- Controlla la modalità di notifica del job di backup. Un job con un indirizzo email nelle impostazioni di notifica e la modalità predefinita
autousa il sendmail legacy e salta completamente il sistema di notifiche. Svuota l'indirizzo oppure imposta la modalità sul sistema di notifiche; in/etc/pve/jobs.cfgla voce ènotification-mode notification-system. - Leggi il journal.
journalctl --since "1 hour ago" | grep -i notifmostra le richieste fallite. Un401significa che la chiave è sbagliata; un400di solito vuol dire che il body non è JSON valido: verifica di aver usato{{ json message }}e non un semplice{{ message }}. - Controlla il feed nell'app. Le push
lownon emettono suono, quindi un backup riuscito può sembrare mai arrivato. È presente nella cronologia dei messaggi.
FAQ
Mi serve una subscription Proxmox?
No. Il sistema di notifiche e il target webhook fanno parte dei repository gratuiti. L'unico elemento legato alla subscription è la notifica package-updates di PBS.
Funziona per un singolo nodo senza cluster?
Sì. Un nodo singolo legge lo stesso /etc/pve/notifications.cfg. In un cluster il file è condiviso, quindi lo configuri una sola volta.
Posso ricevere anche le email?
Sì. Mantieni il target predefinito mail-to-root nel suo matcher e aggiungi pocketalert accanto. Un matcher può notificare più target, e ogni target riceve al massimo una notifica.
Quante push consumerà?
Una per evento. Un job di backup notturno è una sola notifica per l'intero job, non una per guest, quindi un homelab tipico ne invia alcune al giorno. Il piano gratuito copre 50 messaggi al giorno su un dispositivo.
E TrueNAS, gli eventi di alimentazione UPS o Uptime Kuma?
Stessa idea, mittente diverso. La pagina avvisi per homelab copre i componenti più comuni di un server domestico, e avvisi di backup copre gli strumenti di backup diversi da Proxmox.
Crea un account gratuito, incolla il body in un target webhook, e lascia che sia la notifica del prossimo backup fallito a trovarti, invece della tua casella di posta.