被动和主动检查协议

本节提供 Zabbix agent 和 Zabbix agent 2 执行的被动检查和主动检查的协议细节。

Zabbix 使用基于 JSON 的通信协议与 agent 进行通信。

自 Zabbix 7.0 起，Zabbix agent 和 Zabbix agent 2 的协议已统一。Zabbix agent 和 Zabbix agent 2 的请求/响应之间的差异通过 "variant" 标签值来体现。

被动检查

被动检查是一种简单的数据请求。Zabbix 服务器或 proxy 会请求某些数据（例如 CPU 负载），然后 Zabbix agent 将结果返回给服务器。

被动检查是异步执行的 - 在开始其他检查之前，不需要先接收某个请求的响应。DNS 解析同样是异步的。

agent poller 会尝试连接 DNS 查询返回的所有地址。这样可以确保如果某个 IP 地址不可达，poller 会尝试下一个可用地址，从而提高连接成功的可能性。此增强适用于 Zabbix 服务器和 proxy。

异步检查的最大并发数为 1000（由 MaxConcurrentChecksPerPoller 定义）。

异步 agent 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 通信超时。

agent 响应

{
  "version": "8.0.0",
  "variant": 2,
  "data": [
    {
      "value": "8.0.0"
    }
  ]
}
Field Type Mandatory Value
version string yes agent 版本号。
variant number yes agent 变体（1 - Zabbix agent，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. agent 读取请求并响应： <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. agent 读取请求并响应： <HEADER><DATALEN>{"version":"8.0.0","variant":2,"data":[{"error":"Unsupported item key."}]}
  4. 服务器处理数据，将监控项状态更改为不受支持，并附带 指定的错误消息
  5. TCP 连接关闭
回退到旧协议

为确保 Zabbix 服务器或 proxy 能与 7.2 之前版本的 agent 配合工作（这些版本使用明文协议），系统实现了对旧协议的回退机制。

在重启后或接口配置发生更改时，被动检查会使用 JSON 协议（7.0 及更高版本）执行。
如果响应中未收到有效的 JSON（agent 返回 "ZBX_NOTSUPPORTED"），Zabbix 会将该接口缓存为旧协议，并通过仅发送监控项键值来重试检查。

请注意，Zabbix 服务器/proxy 每小时都会再次尝试让所有接口使用新协议；如有需要，则回退到旧协议。

主动检查

主动检查需要更复杂的处理。 agent 必须首先从服务器/proxy 获取监控项和/或 远程命令 列表，以便独立处理。

用于获取主动检查的服务器/proxy 列在 agent 配置文件 中的 'ServerActive' 参数里。 请求这些检查的频率由同一配置文件中的 'RefreshActiveChecks' 参数设置。 但是，如果刷新主动检查失败，将在硬编码的 60 秒后重试。

自 Zabbix 6.4 起，agent（主动模式）不再每两分钟（默认）从服务器/proxy 接收一次完整的配置副本。 相反，为了减少网络流量和资源占用，系统会每 5 秒（默认）执行一次增量配置同步；在此过程中，只有当 agent 还未收到配置副本，或者主机配置、全局宏或全局正则表达式发生变化时，服务器/proxy 才会提供完整的配置副本。

agent 随后会定期将新值发送到服务器。 如果 agent 收到了任何要执行的 远程命令，执行结果也会一并发送。 请注意，自 Zabbix agent 7.0 起，活动 agent 支持远程命令执行。

如果 agent 位于防火墙后面，您可以考虑 仅使用主动检查，因为在这种情况下，您无需 修改防火墙以允许初始入站连接。

获取监控项列表

Agent 请求

active checks 请求用于获取由 agent 处理的 active checks。
该请求由 agent 在启动时发送，之后会按照 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 的值（如果已设置且不是默认 agent 监听端口）。
version string yes agent 版本号。
variant number yes agent 变体（1 - Zabbix agent，2 - Zabbix agent 2）。
config_revision number no 增量配置同步 的配置标识符。
session string no 增量配置同步 的会话标识符。

服务器响应

active checks 响应由服务器在处理 active checks 请求后返回给 agent。

{
  "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 active check 监控项。如果主机配置未更改，则省略。
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 要执行的远程命令。如果远程命令执行是由某个动作 操作 或手动 脚本 执行触发的，则会包含此字段。请注意，自 Zabbix agent 7.0 起，活动 agent 支持远程命令执行。较旧的活动 agent 会忽略 active checks 服务器响应中包含的任何远程命令。
command string no 远程命令。
id number no 远程命令标识符。
wait number no 远程命令执行模式（来自动作 操作 的命令为 "0"（nowait）；来自手动 脚本 执行的命令为 "1"（wait））。
timeout number no 服务器/proxy 配置中的远程命令执行超时时间。
config_revision number no 增量配置同步 的配置标识符。如果主机配置未更改，则省略。若主机配置发生更改，则递增。

服务器必须返回 success。

例如：

  1. Agent 打开一个 TCP 连接
  2. Agent 请求监控项列表
  3. 服务器返回监控项列表和要执行的远程命令
  4. Agent 解析响应
  5. TCP 连接关闭
  6. Agent 开始周期性采集数据并执行远程命令（自 Zabbix agent 7.0 起支持）

请注意，使用 active check 时，具有访问 Zabbix 服务器 trapper 端口权限的人员可能会获取（敏感的）配置数据。之所以可能发生这种情况，是因为任何人都可以伪装成活动 agent 并请求监控项配置数据；除非使用 加密 选项，否则不会进行身份验证。

发送收集到的数据

Agent 发送

agent 数据请求包含已收集的监控项值以及已执行远程命令的值（如果有）。

{
  "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
}
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 监控项状态。
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 agent 7.0 起，活动 agent 支持远程命令执行。较旧的活动 agent 会忽略活动检查服务器响应中包含的任何远程命令。
id number no 远程命令标识符。
value string no 如果执行成功，则为远程命令执行结果。
error string no 如果执行失败，则为远程命令执行错误消息。
session string yes 每次启动 agent 时生成的唯一会话标识符。
host string yes 主机名。
version string yes agent 版本号。
variant number yes agent 变体（1 - Zabbix agent，2 - Zabbix agent 2）。

每个值都会分配一个虚拟 ID。值 ID 是一个简单的递增计数器，在一个数据会话内唯一（由会话令牌标识）。该 ID 用于丢弃在网络连接不佳的环境中可能发送的重复值。

服务器响应

服务器在处理 agent 数据请求后，会将 agent 数据响应发送回 agent。

{
  "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 监控项处理结果。

如果服务器上某些值发送失败（例如，因为主机或监控项已被禁用或删除），agent 不会重试发送这些值。

例如：

  1. Agent 打开一个 TCP 连接
  2. Agent 发送一个值列表
  3. 服务器处理数据并返回状态
  4. TCP 连接关闭

错误消息将在服务器端被截断为 2048 个字符。

心跳消息

Agent 发送

心跳消息由活动 agent 每隔 HeartbeatFrequency 秒发送到 Zabbix 服务器/proxy（在 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 agent 心跳频率（HeartbeatFrequency 配置参数）。
version string yes agent 版本号。
variant number yes agent 变体（1 - Zabbix agent，2 - Zabbix agent 2）。

重定向响应

当主机被重新分配后，服务器可能会指示 agent 将其心跳（以及后续的主动监控项）重定向到另一个 proxy 或服务器实例。

  {
    "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 目标服务器/proxy 地址。

较旧的 XML 协议

Zabbix 最多可接收 16 MB 的 XML Base64 编码数据，但 单个解码后的值不应超过 64 KB，否则在解码时将被截断为 64 KB。