ブログに戻る

Proxmox の通知をスマホへ プッシュ通知: バックアップ、フェンシング、レプリケーション、ディスクエラー

Proxmox の通知をスマホへ プッシュ通知: バックアップ、フェンシング、レプリケーション、ディスクエラー

多くの Proxmox ホストは通知を root@pam に送っています。これは何年も前にインストーラーで入力したメールアドレスで、中継先を設定されていない Postfix から配送されています。夜間バックアップが失敗すると、メールはローカルのキューに溜まります。そして VM を復元する必要が生じた 3 週間後に、ようやく気づくことになります。

よくあるもう一つの設定は、動いてはいても無視されてしまうものです。バックアップジョブごとに毎晩長いメールが届き、どれも「成功」と書かれています。「失敗」と書かれたものだけが、フォルダ内の他の 30 通とまったく同じに見えてしまいます。

Proxmox VE 8.3 と Proxmox Backup Server 3.3 以降では、通知システムに汎用の Webhook ターゲットが加わりました。自分で書いたボディを使って任意の HTTP API を呼び出せるため、スマホへプッシュ通知を直接送れます。失敗と成功で優先度を変えることもできます。ホスト上にスクリプトを置く必要も、メンテナンスすべき中継サーバーもありません。

必要なもの

  • Proxmox VE 8.3 以降(9.x であればどれでも可)、または Proxmox Backup Server 3.3 以降。古いバージョンについては後半で説明します。
  • iPhone または Android の Pocket Alert アプリと、API キーページで発行した API キー。
  • root@pam として、または Mapping.Modify に対する /mapping/notifications 権限を持つユーザーとして、Datacenter → 通知にアクセスできること。

Proxmox が知らせてくれること

Proxmox VE は以下のイベントを発行します。それぞれに type、重大度、いくつかのメタデータフィールドが含まれます。

イベントtype重大度
バックアップ成功vzdumpinfo
バックアップ失敗vzdumperror
ストレージレプリケーションジョブの失敗replicationerror
クラスターノードのフェンシングfencingerror
システムアップデートありpackage-updatesinfo
root 宛てのメール(smartd、ZFS ZED など)system-mailunknown

最後の行は見た目以上に重要です。smartd は 30 分ごとにディスクを確認し、障害が始まると root にメールを送ります。ZFS のイベントデーモンも、劣化したプールやスクラブのエラーについて root にメールを送ります(ZED_EMAIL_ADDR="root" がデフォルトです)。Proxmox はこれらのメールを system-mail イベントに変換するため、バックアップを報告するのと同じ Webhook で、ディスクの故障も知らせることができます。

Webhook ターゲットを設定する

Web UI で Datacenter → 通知 に進み、通知ターゲット の下で 追加 → 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 }} もあり、これは前後の引用符を付けずに同じことをします。
  • キーはシークレットです。 シークレットは /etc/pve/priv/notifications.cfg に保存され、読み取れるのは root だけです。API がその値を返すことはありません。Proxmox はエラーメッセージ中でもシークレットを隠します。
  • レベルは重大度に従います。 Proxmox はボディを Handlebars で描画し、if、eq、or が使えます。バックアップの失敗、レプリケーションの失敗、フェンシング、ディスクのメールは high として届き、iPhone の集中モードを突破します。バックアップの成功やアップデートの通知は low として届きます。フィードには残りますが、通知音は鳴りません。

ターゲットを保存し、テスト をクリックします。数秒以内にテスト通知が届くはずです。

ターゲットは、マッチャーがイベントを振り分けるまで何もしません。通知マッチャー の下で 追加 をクリックし、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> の形式で保存されます。

応用: フェンシングされたノードでは起こしてほしい

バックアップの失敗は朝まで待ってもかまいません。一方、ノードがフェンシングされたということは、HA がホストを強制終了したことを意味し、おやすみモードを突破する critical のプッシュ通知を送る価値があります。マッチャーを使えば、ボディのテンプレートに手を加えずにこれを実現できます。

2 つ目の Webhook ターゲット pocketalert-critical を作成します。ボディの 1 行を除き、最初のターゲットと同じにします。

  "level": "critical"

次に、キャッチオールのマッチャーを、イベントタイプで振り分ける 2 つのマッチャーに置き換えます。

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 ターゲットにだけ送られ、1 つのイベントで 2 回通知が届くことはありません。おやすみモードを突破する critical の配信は有料プランの機能です。無料プランでは high として届きます。各レベルが iOS と Android でどう動作するかは、優先度レベルを参照してください。

マッチャーが役立つ他の用途は次のとおりです。

  • 失敗のみ。 match-severity error,unknown に pocketalert-all を追加すると、成功したバックアップは何も送らなくなります。ただし、成功は low のまま残しておくことをおすすめします。毎晩届く静かな「バックアップ成功」は、通知が届かなくなったときに気づくための最も簡単な手段だからです。
  • 1 つのジョブだけ。 match-field exact:job-id=backup-abc123 を使うと、マッチャーを 1 つのスケジュールジョブに限定できます。今すぐ実行 で開始したバックアップには job-id がないため、一致しません。
  • 時間外の抑制。 match-calendar mon..fri 9-17 でマッチャーを業務時間に限定し、invert-match で残りの時間を対象にできます。

Web UI を開くボタン

Pocket Alert のプッシュ通知には、最大 3 つのアクションボタンを含めることができます。ボディに 1 つ追加すると、失敗したバックアップから 1 タップで Proxmox の UI を開けるようになります。

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

スマホが URL を直接開くため、自宅のネットワークや VPN に接続していれば、ローカルアドレスでも問題なく動作します。

Proxmox Backup Server

PBS 3.3 以降にも、設定 → 通知 の下に同じ通知システムがあり、同じ Webhook ターゲット、同じボディ、同じ 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 の 2 種類で届くため、ボディの同じ if がそのまま機能します。データストアのイベント(gc、prune、sync、verification、tape-backup)には datastore フィールドも含まれるため、match-field regex:datastore=^offsite-.*$ を使えば、オフサイトのデータストアを別のターゲットに送れます。

PBS で確認しておくべき点が 2 つあります。通知システムより前に作成されたデータストアは、notification-mode が legacy-sendmail のままの場合があります。その場合はデータストアのオプションで通知システムに切り替えてください。また、PBS が package-updates の通知を送るのは、有効なサブスクリプションがあるホストだけです。

正直な限界

  • 報告するにはホストがオンラインである必要があります。 Webhook は Proxmox ホスト自身が送信するため、上流の接続が切れていたり電源が落ちていたりすると、何も送られません。「マシン全体がダウンした」場合を検知するには、別のマシンで動くアップタイム監視のような、外部からのチェックが必要です。
  • 長いバックアップレポートはプッシュ通知では切り詰められます。 20 台のゲストのバックアップは長い表を生成します。プッシュ通知に表示されるのはおよそ最初の 3 KB で、全文はアプリのメッセージ履歴にあります。
  • system-mail は root 宛てのすべてのメールです。 smartd と ZFS のメールも含まれますが、cron の出力や、システムで root にメールを送るその他すべてのものも含まれます。通知が多すぎる場合は、match-field exact:type=system-mail を使ってそれらのイベントに専用のマッチャーを設定し、より静かなターゲットに振り分けてください。
  • Gotify との互換性はありません。 Proxmox には Gotify の組み込みターゲットもあり、古いガイドではそれをスマホへの通知に使っています。Pocket Alert は Gotify API を実装していないため、そのターゲットを当サービスに向けることはできません。上記の Webhook ターゲットを使うか、Pocket Alert と Gotify の比較をご覧ください。

Proxmox VE 8.2 以前の場合

アップグレードが最善の解決策です。Webhook ターゲットには 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 の場合、2 番目と 3 番目の引数はバックアップモードと VM ID です。

何も届かない場合

  • まずテストを実行してください。 テストのプッシュ通知は届くのに実際のイベントが届かない場合、ターゲットは正常で、問題はルーティングにあります。マッチャーがそのターゲットを指定しているか、ルールが一致しているかを確認してください。
  • バックアップジョブの通知モードを確認してください。 通知設定にメールアドレスがあり、モードがデフォルトの 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 のサブスクリプションは必要ですか?

いいえ。通知システムと Webhook ターゲットは、無料のリポジトリに含まれています。サブスクリプションが必要なのは、PBS の package-updates 通知だけです。

クラスターのない単一ノードでも使えますか?

はい。単一ノードでも同じ /etc/pve/notifications.cfg を読み込みます。クラスターではこのファイルが共有されるため、設定は一度で済みます。

これをメールでも受け取れますか?

はい。マッチャーの既定の mail-to-root ターゲットはそのまま残し、その横に pocketalert を追加してください。1 つのマッチャーで複数のターゲットに通知でき、各ターゲットへの通知は最大 1 回です。

いくつのプッシュ通知を消費しますか?

イベントごとに 1 件です。夜間のバックアップジョブは、ゲストごとではなくジョブ全体で 1 件の通知になるため、一般的なホームラボでは 1 日に数件程度です。無料プランでは、1 台のデバイスで 1 日 50 件までのメッセージに対応しています。

TrueNAS、UPS の電源イベント、Uptime Kuma はどうですか?

考え方は同じで、送信元が異なるだけです。ホームラボのアラートページでは、自宅サーバーラックの一般的な構成要素を扱っており、バックアップのアラートページでは Proxmox 以外のバックアップツールを扱っています。

無料アカウントを作成して、本文を Webhook ターゲットに貼り付けてください。次に失敗したバックアップが、受信箱ではなくあなたの手元に届くようになります。

この記事をシェア