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

> 내장 웹훅 대상으로 Proxmox VE와 Proxmox Backup Server 알림을 아이폰과 안드로이드에 보내세요. 백업 실패는 확실하게, 성공은 조용하게 도착하고, 펜싱된 노드는 바로 깨워 주며, smartd와 ZFS 경고는 root 메일함에서 묻히지 않습니다.

*25.10.2026*

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

대부분의 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 이상. 이전 버전은 아래에서 따로 다룹니다.
- [아이폰 또는 안드로이드](/get-app)의 Pocket Alert 앱과 [API 키](/account/apikeys) 페이지에서 발급받은 API 키.
- `root@pam` 계정, 또는 `Mapping.Modify`에 대한 `/mapping/notifications` 권한이 있는 사용자로 데이터센터 → 알림에 접근할 수 있는 권한.

## Proxmox가 알려 주는 것들

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

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>이벤트</th><th><code>type</code></th><th>심각도</th></tr></thead>
<tbody>
<tr><th>백업 성공</th><td><code>vzdump</code></td><td><code>info</code></td></tr>
<tr><th>백업 실패</th><td><code>vzdump</code></td><td><code>error</code></td></tr>
<tr><th>스토리지 복제 작업 실패</th><td><code>replication</code></td><td><code>error</code></td></tr>
<tr><th>클러스터 노드 펜싱됨</th><td><code>fencing</code></td><td><code>error</code></td></tr>
<tr><th>시스템 업데이트 가능</th><td><code>package-updates</code></td><td><code>info</code></td></tr>
<tr><th>root 대상 메일(smartd, ZFS ZED 등)</th><td><code>system-mail</code></td><td><code>unknown</code></td></tr>
</tbody>
</table>
</div>

마지막 행은 생각보다 중요합니다. `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로 인코딩해서 전달합니다.

```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
```

결과는 `/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와 안드로이드에서 어떻게 동작하는지는 [우선순위 레벨](https://info.pocketalert.app/features/priority-levels.html)을 참고하세요.

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

- **실패만 받기.** `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 푸시에는 최대 세 개의 [액션 버튼](https://info.pocketalert.app/features/action-buttons.html)을 넣을 수 있습니다. 본문에 하나를 추가하면 실패한 백업 알림을 한 번의 탭으로 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 비교](/alternatives/gotify)를 확인하세요.

## Proxmox VE 8.2 이하에서

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

실행 권한을 주고 `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는 어떻게 하나요?

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

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