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

> Invia le notifiche di Proxmox VE e Proxmox Backup Server su iPhone e Android con il target webhook integrato. I backup falliti arrivano con priorità alta, quelli riusciti in silenzio, un nodo sottoposto a fencing ti sveglia, e gli avvisi di smartd e ZFS smettono di finire nella casella di posta di root.

*25.10.2026*

<!-- source: https://pocketalert.app/it/blog/proxmox-alerts -->

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](/get-app) e una chiave API da [Chiavi API](/account/apikeys).
- Accesso a Datacenter → Notifications come `root@pam` o come utente con `Mapping.Modify` su `/mapping/notifications`.

## Cosa può dirti Proxmox

Proxmox VE emette questi eventi, ognuno con un `type`, una severità e alcuni campi di metadati:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Evento</th><th><code>type</code></th><th>Severità</th></tr></thead>
<tbody>
<tr><th>Backup riuscito</th><td><code>vzdump</code></td><td><code>info</code></td></tr>
<tr><th>Backup fallito</th><td><code>vzdump</code></td><td><code>error</code></td></tr>
<tr><th>Job di replica dello storage fallito</th><td><code>replication</code></td><td><code>error</code></td></tr>
<tr><th>Nodo del cluster sottoposto a fencing</th><td><code>fencing</code></td><td><code>error</code></td></tr>
<tr><th>Aggiornamenti di sistema disponibili</th><td><code>package-updates</code></td><td><code>info</code></td></tr>
<tr><th>Posta per root (smartd, ZFS ZED e altri)</th><td><code>system-mail</code></td><td><code>unknown</code></td></tr>
</tbody>
</table>
</div>

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:** `POST` e `https://api.pocketalert.app/v1/messages`
- **Headers:** `Content-Type` = `application/json`, e `Token` = `{{ 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`, `eq` e `or`. I backup falliti, la replica fallita, il fencing e le mail di disco arrivano come `high`, che su iPhone supera Full immersion. I backup riusciti e gli avvisi di aggiornamento arrivano come `low`: 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:

```bash
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à](https://info.pocketalert.app/features/priority-levels.html) 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,unknown` a `pocketalert-all` e i backup riusciti smettono di inviare qualsiasi cosa. Li terremmo come `low`: 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-abc123` limita un matcher a un singolo job pianificato. I backup avviati con **Run now** non hanno `job-id`, quindi non corrispondono.
- **Ore di silenzio.** `match-calendar mon..fri 9-17` limita un matcher all'orario di lavoro, e `invert-match` ti dà il resto.

### Un pulsante che apre l'interfaccia web

Le notifiche push di Pocket Alert possono contenere fino a tre [pulsanti di azione](https://info.pocketalert.app/features/action-buttons.html). 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 con `match-field exact:type=system-mail` e 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](/alternatives/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](/tools/cli) sul nodo come root, esegui `pocketalert auth`, e salva questo file come `/usr/local/bin/vzdump-pocketalert`:

```bash
#!/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 `auto` usa 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.cfg` la voce è `notification-mode notification-system`.
- **Leggi il journal.** `journalctl --since "1 hour ago" | grep -i notif` mostra le richieste fallite. Un `401` significa che la chiave è sbagliata; un `400` di 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 `low` non 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](/use-cases/homelab-alerts) copre i componenti più comuni di un server domestico, e [avvisi di backup](/use-cases/backup-alerts) copre gli strumenti di backup diversi da Proxmox.

[Crea un account gratuito](/signup), 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.
