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

概要

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

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

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

パッシブチェック

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

パッシブチェックは非同期で実行されます。つまり、ある要求への応答を受信する前に、他のチェックを開始できます。 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.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接続が閉じられる
旧プロトコルへのフェイルオーバー

プレーンテキストプロトコルを使用する 7.2 より前のバージョンのエージェントでも、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.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 エージェント、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
    }
  ]
}
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 エージェントと 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 サーバーのトラッパーポートにアクセスできる第三者が、（機密性のある）設定データを利用できるようになる可能性があることに注意してください。 これは、誰でもアクティブなエージェントを装ってアイテム設定データを要求できるためです。暗号化 オプションを使用しない限り、認証は行われません。

収集データの送信

エージェントからの送信

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

{
  "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
}
フィールド 型 必須 値
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 値のイベントログ severity。
timestamp number no 値のイベントログ timestamp。
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.4.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エンコードデータを受け取りますが、デコード後の単一の値は64 KB以内にする必要があります。これを超える場合、デコード時に64 KBに切り詰められます。