Voltar para o blog

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

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@pam ou a um usuário com Mapping.Modify em /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:

EventotypeSeveridade
Backup concluídovzdumpinfo
Backup falhouvzdumperror
Job de replicação de storage falhoureplicationerror
Nó do cluster isolado (fenced)fencingerror
Atualizações do sistema disponíveispackage-updatesinfo
E-mail para root (smartd, ZFS ZED e outros)system-mailunknown

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: POST e https://api.pocketalert.app/v1/messages
  • Headers: Content-Type = application/json, e Token = {{ 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, eq e or. Falhas de backup, falhas de replicação, fencing e e-mails de disco chegam como high, que atravessa o Foco no iPhone. Backups bem-sucedidos e avisos de atualização chegam como low: 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,unknown ao pocketalert-all e os backups bem-sucedidos param de enviar qualquer coisa. Nós os manteríamos como low: 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-abc123 limita um matcher a um único job agendado. Backups iniciados com Run now não têm job-id, então não correspondem.
  • Horário de silêncio. match-calendar mon..fri 9-17 limita um matcher ao horário de trabalho, e invert-match te 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 com match-field exact:type=system-mail e 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 auto usa 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.cfg isso fica como notification-mode notification-system.
  • Leia o journal. journalctl --since "1 hour ago" | grep -i notif mostra as requisições com falha. Um 401 significa que a chave está errada; um 400 geralmente 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 low nã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.

Compartilhe este artigo