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

概要

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

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

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

パッシブチェック

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

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

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

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

非同期エージェントpollerの数は、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.4.0",
  "variant": 2,
  "data": [
    {
      "value": "7.4.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.4.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.4.0","variant":2,"data":[{"error":"Unsupported item key."}]}
  4. サーバーがデータを処理し、指定されたエラーメッセージとともにアイテムの状態を「未サポート」に変更する
  5. TCP接続が閉じられる
旧プロトコルへのフェイルオーバー

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

再起動後、またはインターフェース設定の変更時に、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.4.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））。
config_revision number no 増分設定同期 の設定識別子。ホスト設定が変更されていない場合は省略されます。ホスト設定が変更された場合にインクリメントされます。

サーバーは success で応答する必要があります。

例:

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

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

収集したデータの送信

エージェントからの送信

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

{
  "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.4.0",
  "variant": 2
}
Field Type Mandatory Value
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つのデータセッション内で一意です（session トークンで識別されます）。このIDは、接続性の悪い環境で送信される可能性がある 重複した値を破棄するために使用されます。

サーバー応答

エージェントデータ応答は、エージェントデータリクエストを処理した後にサーバーからエージェントへ送信されます。

{
  "response": "success",
  "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
}
Field Type Mandatory Value
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": "7.4.0",
  "variant": 2
}
フィールド 型 必須 値
request string はい active check heartbeat
host string はい ホスト名。
heartbeat_freq number はい エージェントのハートビート頻度（HeartbeatFrequency 設定パラメータ）。
version string はい エージェントのバージョン番号。
variant number はい エージェントのバリアント（1 - Zabbix agent、2 - Zabbix agent 2）。

リダイレクト応答

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

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

古い XML プロトコル

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