2 パッシブおよびアクティブエージェントチェック

概要

このセクションでは、Zabbix エージェントおよびZabbix エージェント 2が実行するパッシブチェックとアクティブチェックについて詳しく説明します。

Zabbixは、エージェントとの通信にJSONベースの通信プロトコルを使用します。

Zabbix 7.0以降、Zabbix エージェントとZabbix エージェント 2のプロトコルは統一されています。 Zabbix エージェントとZabbix エージェント 2のリクエスト/レスポンスの違いは、「variant」タグの値で表されます。

パッシブチェック

パッシブチェックは、単純なデータ要求です。
Zabbixサーバーまたはプロキシがデータ（CPU負荷など）を要求し、Zabbixエージェントが結果をサーバーに返します。

パッシブチェックは非同期で実行されます。つまり、別のチェックを開始する前に、1つの要求に対する応答を受信する必要はありません。
DNS名前解決も非同期で実行されます。

エージェントポーラーは、DNSルックアップで返されたすべてのアドレスへの接続を試みます。
これにより、1つのIPアドレスに到達できない場合、ポーラーは次に利用可能なアドレスを試行するため、接続に成功する可能性が高くなります。
この機能強化は、Zabbixサーバーとプロキシの両方に適用されます。

非同期チェックの最大同時実行数は1000です（MaxConcurrentChecksPerPollerで定義）。

非同期エージェントポーラーの数は、StartAgentPollersパラメータで定義します。

サーバー要求

ヘッダーとデータ長の定義については、プロトコルの詳細を参照してください。

{
  "request": "passive checks",
  "data": [
    {
      "key": "agent.version",
      "timeout": 3
    }
  ]
}
Field Type Mandatory Value
request string yes "passive checks"
data array of object yes パッシブチェックのアイテム。
key string yes マクロを展開したアイテムキー。
timeout number yes 通信タイムアウト。

エージェントの応答

{
  "version": "7.0.0",
  "variant": 2,
  "data": [
    {
      "value": "7.0.0"
    }
  ]
}
Field Type Mandatory Value
version string yes エージェントのバージョン番号。
variant number yes エージェントのバリアント（1 - Zabbixエージェント、2 - Zabbixエージェント2）。
data array of object yes チェック結果が含まれます。
value string no チェックに成功した場合のアイテムの値。
error string no チェックに失敗した場合のエラーメッセージ。

例えば、サポートされているアイテムの場合：

  1. サーバーがTCP接続を開きます
  2. サーバーが <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]} を送信します
  3. エージェントが要求を読み取り、<HEADER><DATALEN>{"version":"7.0.0","variant":2,"data":[{"value":1}]} を返します
  4. サーバーがデータを処理して値を取得します。この場合は「1」です
  5. TCP接続が閉じられます

サポートされていないアイテムの場合：

  1. サーバーがTCP接続を開きます
  2. サーバーが <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size[/nono]","timeout":3}]} を送信します
  3. エージェントが要求を読み取り、<HEADER><DATALEN>{"version":"7.0.0","variant":2,"data":[{"error":"Unsupported item key."}]} を返します
  4. サーバーがデータを処理し、指定されたエラーメッセージとともにアイテムの状態を「サポートされていない」に変更します
  5. TCP接続が閉じられます
旧プロトコルへのフェイルオーバー

プレーンテキストプロトコルを使用する7.0より前のバージョンのエージェントとZabbixサーバーまたはプロキシが確実に動作できるように、旧プロトコルへのフェイルオーバーが実装されています。

パッシブチェックは、再起動後またはインターフェース設定の変更時に、JSONプロトコル（7.0以降）を使用して実行されます。 応答で有効なJSONを受信しなかった場合（エージェントが「ZBX_NOTSUPPORTED」を送信した場合）、Zabbixはそのインターフェースを旧プロトコルとしてキャッシュし、アイテムキーのみを送信してチェックを再試行します。

Zabbixサーバー/プロキシは1時間ごとに、すべてのインターフェースで新しいプロトコルの使用を再試行し、必要に応じて旧プロトコルにフォールバックします。

アクティブチェック

アクティブチェックでは、より複雑な処理が必要です。
エージェントはまず、サーバー/プロキシから、独立して処理するためのアイテムおよび/またはリモートコマンドの一覧を取得する必要があります。

アクティブチェックの取得元となるサーバー/プロキシは、エージェントの設定ファイルの「ServerActive」パラメータに一覧表示されます。
これらのチェックを問い合わせる頻度は、同じ設定ファイル内の「RefreshActiveChecks」パラメータで設定されます。
ただし、アクティブチェックの更新に失敗した場合は、ハードコードされた60秒後に再試行されます。

::: ヒント Zabbix 6.4 以降、エージェント（アクティブモード）は、サーバー/プロキシから2分ごと（デフォルト）に設定の完全なコピーを受信しなくなりました。 代わりに、ネットワークトラフィックとリソース使用量を削減するために、5秒ごと（デフォルト）に設定の増分同期が実行され、エージェントがまだ設定を受け取っていない場合、またはホスト設定、グローバルマクロ、またはグローバル正規表現に変更があった場合にのみ、サーバー/プロキシから設定の完全なコピーが提供されます。 :::

エージェントはその後、新しい値を定期的にサーバーに送信します。 エージェントが実行するリモートコマンドを受信した場合は、実行結果も送信されます。 アクティブエージェントでのリモートコマンドの実行は、Zabbixエージェント7.0以降でサポートされていることに注意してください。

エージェントがファイアウォールの内側にある場合は、アクティブチェックのみを使用することを検討してください。この場合、最初の受信接続を許可するためにファイアウォールを変更する必要がありません。

アイテムのリスト取得

エージェントのリクエスト

アクティブチェックのリクエストは、エージェントが処理するアクティブチェックを取得するために使用されます。 このリクエストは、エージェントの起動時に送信され、その後はRefreshActiveChecksの間隔で送信されます。

{
  "request": "active checks",
  "host": "Zabbix server",
  "host_metadata": "mysql,nginx",
  "interface": "zabbix.server.lan",
  "ip": "159.168.1.1",
  "port": 12050,
  "version": "7.0.0",
  "variant": 2,
  "config_revision": 1,
  "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
}
フィールド 型 必須 値
request string yes active checks
host string yes ホスト名。
host_metadata string no 設定パラメータHostMetadataまたはHostMetadataItemのメトリクス値。
interface string no 設定パラメータHostInterfaceまたはHostInterfaceItemのメトリクス値。
ip string no 設定パラメータListenIPに設定されている場合の最初のIP。
port number no 設定パラメータListenPortに設定されていて、デフォルトのエージェントリスニングポートでない場合の値。
version string yes エージェントのバージョン番号。
variant number yes エージェントの種類（1 - Zabbixエージェント、2 - Zabbixエージェント2）。
config_revision number no 増分設定同期用の設定識別子。
session string no 増分設定同期用のセッション識別子。

サーバーのレスポンス

アクティブチェックのレスポンスは、アクティブチェックのリクエストの処理後に、サーバーからエージェントへ返送されます。

{
  "response": "success",
  "config_revision": 2,
  "data": [
    {
      "key": "system.uptime",
      "itemid": 1234,
      "delay": "10s",
      "lastlogsize": 0,
      "mtime": 0
    },
    {
      "key": "agent.version",
      "itemid": 5678,
      "delay": "10m",
      "lastlogsize": 0,
      "mtime": 0,
      "timeout": "30s"
    }
  ],
  "commands": [
    {
      "command": "df -h --output=source,size / | awk 'NR>1 {print $2}'",
      "id": 1324,
      "wait": 1
    }
  ]
}
フィールド 型 必須 値
response string yes success | failed
info string no 失敗した場合のエラー情報。
data array of objects no アクティブチェックのアイテム。ホスト設定に変更がない場合は省略されます。
key string no マクロが展開されたアイテムキー。
itemid number no アイテム識別子。
delay string no アイテムの更新間隔。
柔軟な間隔およびスケジューリング間隔は、Zabbix 7.0以降、ZabbixエージェントとZabbixエージェント2の両方でサポートされています。
lastlogsize number no アイテムのlastlogsize。
mtime number no アイテムのmtime。
timeout string no アイテムのタイムアウト。
refresh_unsupported number no サポートされていないアイテムの更新間隔。
regexp array of objects no グローバル正規表現。
name string no グローバル正規表現の名前。
expression string no グローバル正規表現。
expression_type number no グローバル正規表現のタイプ。
exp_delimiter string no グローバル正規表現の区切り文字。
case_sensitive number no グローバル正規表現の大文字と小文字の区別設定。
commands array of objects no 実行するリモートコマンド。アクションの実行内容によってリモートコマンドの実行がトリガーされた場合、または手動のスクリプト実行の場合に含まれます。アクティブエージェントでのリモートコマンド実行は、Zabbixエージェント7.0以降でサポートされています。以前のアクティブエージェントは、アクティブチェックのサーバーレスポンスに含まれるリモートコマンドを無視します。
command string no リモートコマンド。
id number no リモートコマンド識別子。
wait number no リモートコマンドの実行モード（アクションの実行内容からのコマンドでは「0」（nowait）、手動のスクリプト実行からのコマンドでは「1」（wait））。
timeout number no サーバー/プロキシ設定におけるリモートコマンド実行のタイムアウト。
config_revision number no 増分設定同期用の設定識別子。ホスト設定に変更がない場合は省略されます。ホスト設定が変更された場合は増加します。

サーバーはsuccessを返さなければなりません。

例:

  1. エージェントがTCP接続を開く
  2. エージェントがチェックのリストを要求する
  3. サーバーがアイテムのリストと実行するリモートコマンドを返す
  4. エージェントがレスポンスを解析する
  5. TCP接続が閉じられる
  6. エージェントが定期的なデータ収集を開始し、リモートコマンドを実行する（Zabbixエージェント7.0以降でサポート）

アクティブチェックを使用すると、Zabbixサーバーのtrapperポートにアクセスできる第三者が、（機密性のある）設定データを利用できるようになる可能性があることに注意してください。 これは、誰でもアクティブエージェントになりすましてアイテム設定データを要求できるためです。暗号化オプションを使用しない限り、認証は行われません。

収集データの送信

エージェントからの送信

エージェントデータリクエストには、収集されたアイテムの値と、実行されたリモートコマンドの値（存在する場合）が含まれます。

{
  "request": "agent data",
  "data": [
    {
      "id": 1,
      "itemid": 5678,
      "value": "7.0.0",
      "clock": 1712830783,
      "ns": 76808644
    },
    {
      "id": 2,
      "itemid": 1234,
      "value": "69672",
      "clock": 1712830783,
      "ns": 77053975
    }
  ],
  "commands": [
    {
      "id": 1324,
      "value": "16G"
    }
  ],
  "session": "8495cd52070e6ca52b371f29c8574165",
  "host": "Zabbix server",
  "version": "7.0.0",
  "variant": 2
}
フィールド 型 必須 値
request string yes agent data
data array of objects yes アイテムの値。
id number yes 値の識別子（ネットワーク障害が発生した場合に重複した値を確認するために使用される増分カウンター）。
itemid number yes アイテムの識別子。
value string no アイテムの値。
lastlogsize number no アイテムの lastlogsize。
mtime number no アイテムの mtime。
state number no アイテムの状態。
source string no 値のイベントログソース。
eventid number no 値のイベントログ eventid。
severity number no 値のイベントログの重要度。
timestamp number no 値のイベントログのタイムスタンプ。
clock number yes 値のタイムスタンプ（Epochからの経過秒数）。
ns number yes 値のタイムスタンプのナノ秒。
commands array of objects no リモートコマンドの実行結果。アクティブエージェントでのリモートコマンド実行は、Zabbixエージェント7.0以降でサポートされます。古いアクティブエージェントは、アクティブチェックのサーバー応答に含まれるリモートコマンドを無視します。
id number no リモートコマンドの識別子。
value string no 実行に成功した場合のリモートコマンドの実行結果。
error string no 実行に失敗した場合のリモートコマンドの実行エラーメッセージ。
session string yes エージェントの起動時に毎回生成される一意のセッション識別子（32桁の16進数）。
host string yes ホスト名。
version string yes エージェントのバージョン番号。
variant number yes エージェントの種類（1 - Zabbixエージェント、2 - Zabbixエージェント2）。

各値には仮想IDが割り当てられます。 値IDは、1つのデータセッション（セッショントークンで識別されます）内で一意の、単純な昇順カウンターです。 このIDは、接続状態が不安定な環境で送信される可能性のある重複値を破棄するために使用されます。

サーバーの応答

エージェントデータリクエストの処理後、エージェントデータの応答がサーバーからエージェントに返されます。

{
  "response": "success",
  "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
}
フィールド 型 必須 値
response string yes success | failed
info string yes アイテムの処理結果。

サーバーで一部の値の送信に失敗した場合（例えば、ホストまたはアイテムが無効化または削除されている場合）、エージェントはそれらの値の送信を再試行しません。

例えば、次のようになります。

  1. エージェントがTCP接続を開く
  2. エージェントが値のリストを送信する
  3. サーバーがデータを処理し、ステータスを返す
  4. TCP接続が閉じられる

エラーメッセージは、サーバー側で2048文字に切り詰められます。

ハートビートメッセージ

エージェントが送信

ハートビートメッセージは、HeartbeatFrequency 秒ごとにアクティブエージェントから Zabbix サーバー/プロキシに送信されます（Zabbix エージェント/エージェント 2 の設定ファイルで設定）。

アクティブチェックの可用性を監視するために使用されます。

{
  "request": "active check heartbeat",
  "host": "Zabbix server",
  "heartbeat_freq": 60,
  "version": "7.0.0",
  "variant": 2
}
フィールド 型 必須 値
request string yes active check heartbeat
host string yes ホスト名。
heartbeat_freq number yes エージェントのハートビート間隔（HeartbeatFrequency 設定パラメータ）。
version string yes エージェントのバージョン番号。
variant number yes エージェントの種類（1 - Zabbix エージェント、2 - Zabbix エージェント 2）。

リダイレクト応答

ホストが再割り当てされた場合、サーバーはエージェントに対して、ハートビート（およびそれ以降のアクティブチェック）を別のプロキシまたはサーバーインスタンスにリダイレクトするよう指示することがあります。

  {
    "response": "failed",
    "redirect": {
      "revision": 2,
      "address": "192.0.2.1:10055"
    }
  }
フィールド 型 必須 値
response string yes success | failed
redirect object yes リダイレクトの指示。
revision number yes 設定リビジョン識別子。
address string yes 対象サーバー/プロキシのアドレス。

旧XMLプロトコル

Zabbixは最大16 MBのXML Base64エンコードデータを受け取りますが、デコード後の1つの値は64 KBを超えないようにしてください。超えた場合、デコード時に64 KBに切り詰められます。