Notificações Proxmox no celular: backups, fencing, replicação e erros de disco

A maioria dos hosts Proxmox envia suas notificações para root@pam, ou seja, um endereço de e-mail digitado no instalador anos atrás, entregue por um Postfix que nunca recebeu um relay. O backup noturno falha, o e-mail vai para uma fila local, e você descobre três semanas depois, quando precisa restaurar uma VM.
A outra configuração comum funciona, mas acaba sendo ignorada. Cada job de backup envia um e-mail longo todas as noites, todos dizem "sucesso", e o que diz "falha" parece exatamente igual aos outros trinta na pasta.
Desde o Proxmox VE 8.3 e o Proxmox Backup Server 3.3, o sistema de notificações tem um destino webhook genérico. Ele pode chamar qualquer API HTTP com um corpo que você mesmo escreve, então pode enviar um push direto para o seu celular, com prioridades diferentes para falhas e sucessos. Sem script no host e sem relay para manter.
O que você precisa
- Proxmox VE 8.3 ou mais recente (qualquer 9.x funciona), ou Proxmox Backup Server 3.3 ou mais recente. Versões antigas são cobertas mais adiante.
- O app Pocket Alert no iPhone ou Android e uma chave de API em Chaves de API.
- Acesso a Datacenter → Notifications como
root@pamou a um usuário comMapping.Modifyem/mapping/notifications.
O que o Proxmox pode te avisar
O Proxmox VE emite estes eventos, cada um com um type, uma severidade e alguns campos de metadados:
| Evento | type | Severidade |
|---|---|---|
| Backup concluído | vzdump | info |
| Backup falhou | vzdump | error |
| Job de replicação de storage falhou | replication | error |
| Nó do cluster isolado (fenced) | fencing | error |
| Atualizações do sistema disponíveis | package-updates | info |
| E-mail para root (smartd, ZFS ZED e outros) | system-mail | unknown |
A última linha importa mais do que parece. O smartd verifica seus discos a cada 30 minutos e envia e-mail para o root quando um começa a falhar, e o daemon de eventos do ZFS envia e-mail para o root sobre pools degradados e erros de scrub (ZED_EMAIL_ADDR="root" é o padrão). O Proxmox transforma esses e-mails em eventos system-mail, então o mesmo webhook que informa backups também informa um disco morrendo.
Configure o destino webhook
Na interface web, vá em Datacenter → Notifications e, em Notification Targets, clique em Add → Webhook. Preencha assim:
- Endpoint Name:
pocketalert - Method/URL:
POSTehttps://api.pocketalert.app/v1/messages - Headers:
Content-Type=application/json, eToken={{ secrets.token }} - Secrets:
token= sua chave de API do Pocket Alert
E o Body:
{
"title": {{ json title }},
"message": {{ json message }},
"level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}
Algumas coisas estão acontecendo aqui:
{{ json title }}renderiza o valor como uma string JSON completa, incluindo as aspas. Relatórios de backup são tabelas com várias linhas, e colocar{{ message }}entre aspas quebraria o JSON na primeira quebra de linha. O Proxmox também tem{{ escape message }}, que faz o mesmo sem as aspas ao redor.- A chave é um segredo. Os segredos ficam armazenados em
/etc/pve/priv/notifications.cfg, legível apenas pelo root, e a API nunca retorna seus valores. O Proxmox também os mascara em suas mensagens de erro. - O nível segue a severidade. O Proxmox renderiza o body com Handlebars, que tem
if,eqeor. Falhas de backup, falhas de replicação, fencing e e-mails de disco chegam comohigh, que atravessa o Foco no iPhone. Backups bem-sucedidos e avisos de atualização chegam comolow: eles estão no feed se você quiser vê-los, mas não vibram.
Salve o destino e clique em Test. Uma notificação de teste deve chegar em poucos segundos.
O destino não faz nada até que um matcher direcione eventos para ele. Em Notification Matchers, clique em Add, dê o nome pocketalert-all e, na aba Targets to notify, marque pocketalert. Um matcher sem regras corresponde a todos os eventos.
A mesma coisa pelo shell
Se você prefere a CLI, ou gerencia vários clusters, o pvesh faz o mesmo. Os valores dos headers, o body e os segredos são passados codificados em 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
O resultado fica em /etc/pve/notifications.cfg, que é compartilhado entre o cluster, então uma única configuração cobre todos os nós (o body em base64 foi encurtado aqui):
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
A chave em si fica em /etc/pve/priv/notifications.cfg como secret name=token,value=<base64>.
Segundo nível: um nó isolado deve te acordar
Um backup com falha pode esperar até de manhã. Um nó isolado significa que o HA acabou de derrubar um host, e isso vale um push critical que atravessa o Não perturbe. Os matchers podem fazer isso sem mexer no template do body.
Crie um segundo destino webhook, pocketalert-critical, idêntico ao primeiro exceto por uma linha do body:
"level": "critical"
Depois substitua o matcher geral por dois que se separam pelo tipo do 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
O invert-match inverte o primeiro matcher, então o fencing vai apenas para o destino crítico e você não recebe dois pushes para o mesmo evento. A entrega critical através do Não perturbe é um recurso de plano pago; no plano gratuito ela chega como high. Veja níveis de prioridade para o que cada nível faz no iOS e no Android.
Mais coisas para as quais os matchers servem bem:
- Somente falhas. Adicione
match-severity error,unknownaopocketalert-alle os backups bem-sucedidos param de enviar qualquer coisa. Nós os manteríamos comolow: um "backup concluído" silencioso toda noite é a forma mais fácil de perceber quando ele para de chegar. - Um job.
match-field exact:job-id=backup-abc123limita um matcher a um único job agendado. Backups iniciados com Run now não têmjob-id, então não correspondem. - Horário de silêncio.
match-calendar mon..fri 9-17limita um matcher ao horário de trabalho, einvert-matchte dá o resto.
Um botão que abre a interface web
Os pushes do Pocket Alert podem carregar até três botões de ação. Adicione um ao body e um backup com falha abre a interface do Proxmox com um toque:
"actions": [
{"type": "view", "label": "Open Proxmox", "value": "https://pve1.lan:8006"}
]
O telefone abre a URL diretamente, então um endereço local funciona sempre que você estiver na sua rede doméstica ou na VPN.
Proxmox Backup Server
O PBS 3.3 e mais recentes têm o mesmo sistema de notificações em Configuration → Notifications, com o mesmo destino webhook, o mesmo body e os mesmos helpers do Handlebars. Sua configuração fica em notifications.cfg e notifications-priv.cfg em /etc/proxmox-backup/.
Os eventos são diferentes e mais úteis para um servidor de backup: garbage collection (gc), prune, sync, verification, tape-backup e tape-load, além de falhas na renovação de certificados acme e package-updates. O acme só reporta falhas e o tape-load é um notice; os demais vêm nas versões info e error, então o mesmo if no body funciona sem alterações. Os eventos de datastore (gc, prune, sync, verification, tape-backup) também carregam um campo datastore, então match-field regex:datastore=^offsite-.*$ pode enviar datastores offsite para outro destino.
Dois detalhes do PBS para conferir. Datastores criados antes do sistema de notificações podem ter um notification-mode que ainda seja legacy-sendmail; mude para o sistema de notificações nas opções do datastore. E o PBS só envia notificações de package-updates em hosts com assinatura ativa.
Limites honestos
- O host precisa estar online para reportar. O webhook é enviado pelo próprio host Proxmox, então se ele perdeu o link de rede ou está desligado, nada sai. Para "a máquina inteira está fora", você precisa de uma verificação externa, como um monitor de uptime em outra máquina.
- Relatórios longos de backup são cortados no push. Um backup de vinte convidados gera uma tabela longa. O push mostra cerca de 3 KB do início; o texto completo está no histórico de mensagens do app.
system-mailé tudo que é enviado para o root. Isso inclui smartd e ZFS, mas também a saída do cron e qualquer outra coisa que envie e-mail para o root no seu sistema. Se ficar barulhento, dê a esses eventos um matcher próprio commatch-field exact:type=system-maile um destino mais silencioso.- Sem compatibilidade com Gotify. O Proxmox também tem um destino Gotify integrado, e guias antigos o usam para pushes no celular. O Pocket Alert não implementa a API do Gotify, então esse destino não pode apontar para nós. Use o destino webhook acima, ou veja como o Pocket Alert se compara ao Gotify.
No Proxmox VE 8.2 e anteriores
Atualizar é a melhor solução, já que o destino webhook exige a 8.3. Se você ainda não pode atualizar, um script hook do vzdump cobre o caso mais importante, os backups. Instale a CLI do Pocket Alert no nó como root, rode pocketalert auth e salve isto como /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
Torne-o executável e adicione script: /usr/local/bin/vzdump-pocketalert ao /etc/vzdump.conf. O vzdump o chama em cada fase; para backup-abort, o segundo e o terceiro argumentos são o modo do backup e o ID da VM.
Se nada chegar
- Execute o Test primeiro. Se o push de teste chega mas os eventos reais não, o destino está correto e o problema é o roteamento: verifique se algum matcher cita o destino e se as regras dele correspondem.
- Confira o modo de notificação do job de backup. Um job com um endereço de e-mail nas configurações de notificação e o modo padrão
autousa o sendmail legado e ignora totalmente o sistema de notificações. Limpe o endereço ou defina o modo como sistema de notificações; em/etc/pve/jobs.cfgisso fica comonotification-mode notification-system. - Leia o journal.
journalctl --since "1 hour ago" | grep -i notifmostra as requisições com falha. Um401significa que a chave está errada; um400geralmente significa que o body não é um JSON válido: confira se você usou{{ json message }}e não um{{ message }}solto. - Confira o feed no app. Pushes
lownão fazem som, então um backup bem-sucedido pode parecer que nunca chegou. Ele está no histórico de mensagens.
FAQ
Preciso de uma assinatura do Proxmox?
Não. O sistema de notificações e o destino webhook fazem parte dos repositórios gratuitos. A única peça que depende de assinatura é a notificação de package-updates do PBS.
Isso funciona para um nó único, sem cluster?
Sim. Um nó único lê o mesmo /etc/pve/notifications.cfg. Em um cluster o arquivo é compartilhado, então você configura uma vez só.
Posso receber isso também por e-mail?
Sim. Mantenha o destino padrão mail-to-root no matcher e adicione pocketalert ao lado dele. Um matcher pode notificar vários destinos, e cada destino recebe a notificação no máximo uma vez.
Quantos pushes isso vai usar?
Um por evento. Um job de backup noturno gera uma notificação para o job inteiro, não uma por convidado, então um homelab típico envia poucas por dia. O plano gratuito cobre 50 mensagens por dia em um dispositivo.
E o TrueNAS, os eventos de energia do UPS ou o Uptime Kuma?
A mesma ideia, outro remetente. A página de alertas para homelab cobre as peças comuns de um rack de servidor doméstico, e alertas de backup cobre ferramentas de backup fora do Proxmox.
Crie uma conta gratuita, cole o body em um destino webhook e deixe que o próximo backup com falha encontre você, em vez da sua caixa de entrada.