블로그로 돌아가기

Proxmox 알림을 휴대폰으로: 백업, 펜싱, 복제, 디스크 오류 푸시 알림

Proxmox 알림을 휴대폰으로: 백업, 펜싱, 복제, 디스크 오류 푸시 알림

대부분의 Proxmox 호스트는 알림을 root@pam으로 보냅니다. 몇 년 전 설치 과정에서 입력한 이메일 주소로, 릴레이를 한 번도 설정하지 않은 Postfix를 통해 전달되는 방식이죠. 매일 밤 백업이 실패하면 메일은 로컬 큐에 쌓이고, 세 주 뒤 VM을 복구해야 할 때가 되어서야 그 사실을 알게 됩니다.

흔히 쓰는 다른 방식도 동작은 하지만 아무도 보지 않게 됩니다. 백업 작업마다 매일 밤 긴 이메일이 한 통씩 오고, 그 메일들은 모두 "성공"이라고 말하며, "실패" 메일은 폴더에 있는 다른 서른 통과 똑같아 보입니다.

Proxmox VE 8.3과 Proxmox Backup Server 3.3부터 알림 시스템에 범용 웹훅 대상이 생겼습니다. 직접 작성한 본문으로 어떤 HTTP API든 호출할 수 있어서, 스크립트나 관리해야 할 릴레이 없이도 휴대폰으로 푸시를 바로 보낼 수 있고, 실패와 성공에 서로 다른 우선순위를 줄 수 있습니다.

준비물

  • Proxmox VE 8.3 이상(9.x 모두 가능), 또는 Proxmox Backup Server 3.3 이상. 이전 버전은 아래에서 따로 다룹니다.
  • 아이폰 또는 안드로이드의 Pocket Alert 앱과 API 키 페이지에서 발급받은 API 키.
  • root@pam 계정, 또는 Mapping.Modify에 대한 /mapping/notifications 권한이 있는 사용자로 데이터센터 → 알림에 접근할 수 있는 권한.

Proxmox가 알려 주는 것들

Proxmox VE는 다음 이벤트를 발생시킵니다. 각 이벤트에는 type, 심각도, 몇 가지 메타데이터 필드가 붙습니다.

이벤트type심각도
백업 성공vzdumpinfo
백업 실패vzdumperror
스토리지 복제 작업 실패replicationerror
클러스터 노드 펜싱됨fencingerror
시스템 업데이트 가능package-updatesinfo
root 대상 메일(smartd, ZFS ZED 등)system-mailunknown

마지막 행은 생각보다 중요합니다. smartd는 30분마다 디스크를 점검하고 디스크에 문제가 생기기 시작하면 root에게 메일을 보내며, ZFS 이벤트 데몬은 degraded 풀과 scrub 오류에 대해 root에게 메일을 보냅니다(ZED_EMAIL_ADDR="root"가 기본값입니다). Proxmox는 이 메일들을 system-mail 이벤트로 바꾸므로, 백업을 알려 주는 것과 같은 웹훅으로 죽어 가는 디스크도 알 수 있습니다.

웹훅 대상 설정하기

웹 UI에서 데이터센터 → 알림으로 이동한 뒤, 알림 대상에서 추가 → Webhook을 클릭하세요. 아래와 같이 입력합니다.

  • Endpoint Name: pocketalert
  • Method/URL: POST와 https://api.pocketalert.app/v1/messages
  • Headers: Content-Type = application/json, 그리고 Token = {{ secrets.token }}
  • Secrets: token = 여러분의 Pocket Alert API 키

그리고 Body는 다음과 같습니다.

{
  "title": {{ json title }},
  "message": {{ json message }},
  "level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}

여기서 몇 가지 일이 일어납니다.

  • {{ json title }}은 값을 따옴표까지 포함한 완전한 JSON 문자열로 출력합니다. 백업 보고서는 여러 줄짜리 표이므로, {{ message }}를 따옴표 사이에 그대로 넣으면 첫 줄바꿈에서 JSON이 깨집니다. Proxmox에는 {{ escape message }}도 있는데, 이는 앞뒤 따옴표 없이 같은 일을 합니다.
  • 키는 비밀 값입니다. 시크릿은 root만 읽을 수 있는 /etc/pve/priv/notifications.cfg에 저장되며, API는 그 값을 절대 돌려주지 않습니다. Proxmox는 오류 메시지에서도 이 값을 가립니다.
  • 레벨은 심각도를 따릅니다. Proxmox는 본문을 Handlebars로 렌더링하며, 여기에는 if, eq, or가 있습니다. 백업 실패, 복제 실패, 펜싱, 디스크 메일은 high로 도착해서 아이폰의 집중 모드를 뚫고 들어갑니다. 백업 성공과 업데이트 알림은 low로 도착합니다. 피드에는 남아 있어 필요하면 볼 수 있지만, 진동이 울리지는 않습니다.

대상을 저장하고 Test를 클릭하세요. 몇 초 안에 테스트 알림이 도착해야 합니다.

매처가 이벤트를 이 대상으로 라우팅하기 전까지 대상은 아무 일도 하지 않습니다. 알림 매처에서 추가를 클릭하고 이름을 pocketalert-all로 정한 뒤, 알림 대상 탭에서 pocketalert를 체크하세요. 규칙이 없는 매처는 모든 이벤트와 일치합니다.

셸에서 같은 작업 하기

CLI를 선호하거나 여러 클러스터를 관리한다면 pvesh로 같은 일을 할 수 있습니다. 헤더 값, 본문, 시크릿은 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

결과는 /etc/pve/notifications.cfg에 저장되는데, 이 파일은 클러스터 전체에서 공유되므로 한 번 설정하면 모든 노드에 적용됩니다(아래에서는 base64 본문을 줄여서 표시했습니다).

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

키 자체는 /etc/pve/priv/notifications.cfg에 secret name=token,value=<base64> 형태로 들어 있습니다.

2단계: 펜싱된 노드는 바로 깨워야 합니다

실패한 백업은 아침까지 기다려도 됩니다. 하지만 노드가 펜싱되었다는 것은 HA가 호스트를 방금 강제 종료했다는 뜻이므로, 방해 금지 모드도 뚫고 오는 critical 푸시를 받을 만한 일입니다. 본문 템플릿을 건드리지 않고도 매처로 이를 구현할 수 있습니다.

두 번째 웹훅 대상 pocketalert-critical을 만드세요. 본문의 한 줄만 빼고 첫 번째 대상과 같습니다.

  "level": "critical"

그다음 전체 매처를 이벤트 유형으로 나뉜 두 개의 매처로 교체하세요.

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는 첫 번째 매처의 조건을 뒤집어서, 펜싱 이벤트는 critical 대상으로만 가고 같은 이벤트로 푸시가 두 번 오지 않게 합니다. 방해 금지 모드를 뚫는 critical 전달은 유료 플랜 기능입니다. 무료 플랜에서는 high로 도착합니다. 각 레벨이 iOS와 안드로이드에서 어떻게 동작하는지는 우선순위 레벨을 참고하세요.

매처가 유용한 다른 사례들:

  • 실패만 받기. match-severity error,unknown에 pocketalert-all을 추가하면 백업 성공 알림은 아무것도 보내지 않습니다. 저희는 이 알림을 low로 두는 것을 권장합니다. 매일 밤 조용히 오는 "백업 성공" 알림이 있어야 그 알림이 멈췄을 때 바로 알아챌 수 있기 때문입니다.
  • 작업 하나만. match-field exact:job-id=backup-abc123은 매처를 예약된 작업 하나로 제한합니다. 지금 실행으로 시작한 백업에는 job-id가 없으므로 이 매처와 일치하지 않습니다.
  • 조용한 시간. match-calendar mon..fri 9-17은 매처를 근무 시간으로 제한하고, invert-match를 쓰면 나머지 시간을 지정할 수 있습니다.

웹 UI를 여는 버튼

Pocket Alert 푸시에는 최대 세 개의 액션 버튼을 넣을 수 있습니다. 본문에 하나를 추가하면 실패한 백업 알림을 한 번의 탭으로 Proxmox UI를 열 수 있습니다.

  "actions": [
    {"type": "view", "label": "Open Proxmox", "value": "https://pve1.lan:8006"}
  ]

휴대폰이 URL을 직접 열기 때문에, 집 네트워크나 VPN에 연결되어 있다면 로컬 주소로도 작동합니다.

Proxmox Backup Server

PBS 3.3 이상에는 설정 → 알림에 같은 알림 시스템이 있으며, 같은 웹훅 대상, 같은 본문, 같은 Handlebars 헬퍼를 사용합니다. 설정 파일은 notifications.cfg 아래의 notifications-priv.cfg와 /etc/proxmox-backup/에 있습니다.

이벤트는 다르며 백업 서버에서는 더 유용합니다. 가비지 컬렉션(gc), prune, sync, verification, tape-backup, tape-load, 그리고 acme 인증서 갱신 실패와 package-updates가 있습니다. acme는 실패만 보고하고 tape-load는 notice입니다. 나머지는 info와 error 버전으로 오기 때문에, 본문의 같은 if가 그대로 작동합니다. 데이터스토어 이벤트(gc, prune, sync, verification, tape-backup)에는 datastore 필드도 포함되므로, match-field regex:datastore=^offsite-.*$를 쓰면 오프사이트 데이터스토어의 알림만 다른 대상으로 보낼 수 있습니다.

PBS에서 확인해야 할 두 가지가 있습니다. 알림 시스템이 도입되기 전에 만든 데이터스토어는 notification-mode가 여전히 legacy-sendmail일 수 있으니, 데이터스토어 옵션에서 알림 시스템으로 바꾸세요. 그리고 PBS는 활성 구독이 있는 호스트에서만 package-updates 알림을 보냅니다.

솔직한 한계

  • 보고하려면 호스트가 온라인이어야 합니다. 웹훅은 Proxmox 호스트 자체가 보내므로, 업링크가 끊기거나 전원이 꺼져 있으면 아무것도 나가지 않습니다. "서버 전체가 다운됐는지"를 알고 싶다면 다른 기기에서 돌리는 업타임 모니터처럼 외부에서 확인하는 장치가 필요합니다.
  • 긴 백업 보고서는 푸시에서 잘립니다. 게스트 20개를 백업하면 긴 표가 생깁니다. 푸시에는 대략 처음 3KB만 표시되고, 전체 내용은 앱의 메시지 기록에 있습니다.
  • system-mail은 root에게 가는 모든 메일입니다. smartd와 ZFS뿐 아니라 cron 출력이나 시스템에서 root에게 메일을 보내는 다른 모든 것도 포함됩니다. 너무 시끄럽다면 match-field exact:type=system-mail로 이 이벤트만 따로 매처를 만들고 더 조용한 대상으로 보내세요.
  • Gotify 호환성은 없습니다. Proxmox에는 내장 Gotify 대상도 있고, 오래된 가이드들은 이를 휴대폰 푸시에 사용합니다. Pocket Alert는 Gotify API를 구현하지 않으므로 그 대상은 저희를 가리킬 수 없습니다. 위의 웹훅 대상을 사용하시거나 Pocket Alert와 Gotify 비교를 확인하세요.

Proxmox VE 8.2 이하에서

가장 좋은 해결책은 업그레이드입니다. 웹훅 대상은 8.3이 필요하기 때문입니다. 아직 업그레이드할 수 없다면, vzdump 훅 스크립트로 가장 중요한 경우인 백업은 처리할 수 있습니다. 노드에 root로 Pocket Alert CLI를 설치하고 pocketalert auth를 실행한 뒤, 다음 내용을 /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

실행 권한을 주고 script: /usr/local/bin/vzdump-pocketalert에 /etc/vzdump.conf를 추가하세요. vzdump는 각 단계에서 이 스크립트를 호출하며, backup-abort의 경우 두 번째와 세 번째 인자는 백업 모드와 VM ID입니다.

아무것도 도착하지 않는다면

  • 먼저 Test를 실행하세요. 테스트 푸시는 도착하는데 실제 이벤트가 오지 않는다면 대상은 정상이고 문제는 라우팅입니다. 매처가 대상을 지정했는지, 그리고 규칙이 일치하는지 확인하세요.
  • 백업 작업의 알림 모드를 확인하세요. 알림 설정에 이메일 주소가 있고 기본 모드인 auto를 쓰는 작업은 레거시 sendmail을 사용하여 알림 시스템을 완전히 건너뜁니다. 주소를 지우거나 모드를 알림 시스템으로 설정하세요. /etc/pve/jobs.cfg에서는 notification-mode notification-system입니다.
  • 저널을 읽어 보세요. journalctl --since "1 hour ago" | grep -i notif는 실패한 요청을 보여 줍니다. 401은 키가 잘못되었다는 뜻이고, 400은 대개 본문이 유효한 JSON이 아니라는 뜻입니다. {{ json message }}를 그대로 쓰지 않고 {{ message }}를 썼는지 확인하세요.
  • 앱에서 피드를 확인하세요. low 푸시는 소리가 나지 않으므로, 성공한 백업이 도착하지 않은 것처럼 보일 수 있습니다. 메시지 기록에 남아 있습니다.

자주 묻는 질문

Proxmox 구독이 필요한가요?

아니요. 알림 시스템과 웹훅 대상은 무료 저장소에 포함되어 있습니다. 구독에 의존하는 부분은 PBS의 package-updates 알림뿐입니다.

클러스터가 없는 단일 노드에서도 되나요?

네. 단일 노드도 같은 /etc/pve/notifications.cfg를 읽습니다. 클러스터에서는 파일이 공유되므로 한 번만 설정하면 됩니다.

이 알림을 이메일로도 받을 수 있나요?

네. 매처에 있는 기본 mail-to-root 대상을 그대로 두고 그 옆에 pocketalert를 추가하세요. 매처 하나가 여러 대상에 알림을 보낼 수 있고, 각 대상은 최대 한 번씩 알림을 받습니다.

이 방식은 푸시를 몇 개나 사용하나요?

이벤트 하나당 하나입니다. 매일 밤 실행되는 백업 작업은 게스트마다가 아니라 작업 전체에 대해 알림 하나를 보내므로, 일반적인 홈랩은 하루에 몇 개 정도만 사용합니다. 무료 플랜은 기기 한 대에서 하루 50개 메시지를 제공합니다.

TrueNAS, UPS 전원 이벤트, Uptime Kuma는 어떻게 하나요?

원리는 같고 발신자만 다릅니다. 홈랩 알림 페이지에서 홈 서버 랙의 일반적인 구성 요소들을 다루고, 백업 알림 페이지에서는 Proxmox 밖의 백업 도구를 다룹니다.

무료 계정을 만들고, 본문을 웹훅 대상에 붙여 넣은 뒤, 다음번 백업 실패를 받은편지함이 아니라 휴대폰에서 바로 알아채세요.

이 글 공유하기