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

概要

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

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

ZabbixエージェントとZabbixエージェント2のプロトコルは、Zabbix 7.0以降で統一されました。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": "8.0.0",
  "variant": 2,
  "data": [
    {
      "value": "8.0.0"
    }
  ]
}
Field Type Mandatory Value
version string yes エージェントのバージョン番号。
variant number yes エージェントの種類（1 - Zabbix エージェント、2 - Zabbix agent 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":"8.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":"8.0.0","variant":2,"data":[{"error":"Unsupported item key."}]}
  4. サーバーがデータを処理し、指定されたエラーメッセージを伴ってアイテムの状態をサポート対象外に変更する
  5. TCP 接続が閉じられる
古いプロトコルへのフェイルオーバー

Zabbixサーバーまたはプロキシが、プレーンテキストプロトコルを持つ7.2以前のバージョンのエージェントと連携できるように、古いプロトコルへのフェイルオーバーが実装されています。

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

Zabbixサーバー/プロキシは、すべてのインターフェースで毎時新しいプロトコルでの動作を再試行し、必要に応じて古いプロトコルにフォールバックすることに注意してください。

アクティブチェック

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

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

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

エージェントは定期的に新しい値をサーバーに送信します。 エージェントが実行するリモートコマンドを受信した場合、実行結果も送信されます。 アクティブエージェントでのリモートコマンド実行のサポートは、Zabbix agent 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": "8.0.0",
  "variant": 2,
  "config_revision": 1,
  "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
}
Field Type Mandatory Value
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 agent、2 - Zabbix agent 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
    }
  ]
}
Field Type Mandatory Value
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 agent と Zabbix agent 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 実行するリモートコマンド。アクションの operation または手動の script 実行によってリモートコマンドの実行がトリガーされた場合に含まれます。アクティブなエージェント上でのリモートコマンド実行は、Zabbix agent 7.0 以降でサポートされている点に注意してください。古いアクティブエージェントは、アクティブチェックのサーバー応答に含まれるリモートコマンドを無視します。
command string no リモートコマンド。
id number no リモートコマンド識別子。
wait number no リモートコマンドの実行モード（アクションの operations からのコマンドでは "0"（nowait）、手動の script 実行からのコマンドでは "1"（wait））。
timeout number no サーバー/プロキシ 設定におけるリモートコマンド実行タイムアウト。
config_revision number no 増分設定同期 用の設定識別子。ホスト設定が変更されていない場合は省略されます。ホスト設定が変更された場合は増分されます。

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

例:

  1. エージェントが TCP 接続を開く
  2. エージェントがチェック一覧を要求する
  3. サーバーがアイテム一覧と実行するリモートコマンドを返す
  4. エージェントが応答を解析する
  5. TCP 接続が閉じられる
  6. エージェントが定期的なデータ収集を開始し、リモートコマンドを実行する（Zabbix agent 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": "8.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 アイテムのstate。
source string no 値のイベントログソース。
eventid number no 値のイベントログeventid。
severity number no 値のイベントログseverity。
timestamp number no 値のイベントログtimestamp。
clock number yes 値のタイムスタンプ（Epochからの秒数）。
ns number yes 値のタイムスタンプのナノ秒。
commands array of objects no リモートコマンドの実行結果。アクティブエージェントでのリモートコマンド実行はZabbix agent 7.0以降でサポートされています。古いアクティブエージェントは、アクティブチェックサーバーの応答に含まれるリモートコマンドを無視します。
id number no リモートコマンドの識別子。
value string no 実行が成功した場合のリモートコマンドの実行結果。
error string no 実行が失敗した場合のリモートコマンドの実行エラーメッセージ。
session string yes エージェントが起動されるたびに生成される一意のセッション識別子。
host string yes ホスト名。
version string yes エージェントのバージョン番号。
variant number yes エージェントのバリアント（1 - Zabbix agent、2 - Zabbix agent 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文字に切り詰められます。

ハートビートメッセージ

エージェントが送信

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

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

{
  "request": "active check heartbeat",
  "host": "Zabbix server",
  "heartbeat_freq": 60,
  "version": "8.0.0",
  "variant": 2
}
Field Type Mandatory Value
request string yes active check heartbeat
host string yes ホスト名。
heartbeat_freq number yes エージェントのハートビート頻度（HeartbeatFrequency 設定パラメータ）。
version string yes エージェントのバージョン番号。
variant number yes エージェントの種類（1 - Zabbix agent、2 - Zabbix agent 2）。

リダイレクト応答

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

  {
    "response": "failed",
    "redirect": {
      "revision": 2,
      "address": "192.0.2.1:10055"
    }
  }
Field Type Mandatory Value
response string yes success | failed
redirect object yes リダイレクト指示。
revision number yes 設定リビジョン識別子。
address string yes リダイレクト先のサーバー/プロキシアドレス。

古い XML プロトコル

Zabbixは、 Base64にエンコードされたXMLのデータを16MBまで取得しますが、デコードされる値は1つが64KB以下でなければなりません。そうでないと、デコード中にそれが64KBに切り捨てられます。