6 Zabbix agent 2 (Windows)

概述

Zabbix agent 2 是新一代 Zabbix agent，可用于替代 Zabbix agent。

本节列出了 Windows Zabbix agent 2 配置文件 (zabbix_agent2.conf) 支持的参数。

参数仅列出，不提供额外信息。 单击参数可查看完整详情。

除非明确说明某个参数为必需，否则所有参数均为非必需。

注意：

• 默认值反映的是进程默认值，而不是随软件提供的配置文件中的值；
• Zabbix 仅支持 UTF-8 编码且不带 BOM 的配置文件；
• 以 # 开头的注释仅支持位于行首。
  

参数详情

别名

为监控项键设置一个别名。 它可用于用更短、更简单的键替代较长且复杂的监控项键。
可以存在多个 Alias 参数。 不允许使用相同 Alias 键的多个参数。
不同的 Alias 键可以引用同一个监控项键。
别名可用于 HostMetadataItem，但不能用于 HostnameItem 参数。

示例 1：从服务器中检索分页文件使用率百分比。

Alias=pg_usage:perf_counter[\Paging File(_Total)\% Usage]

现在可以使用简写键 pg_usage 来检索数据。

示例 2：使用默认参数和自定义参数获取 CPU 负载。

Alias=cpu.load:system.cpu.load
Alias=cpu.load[*]:system.cpu.load[*]

这允许使用 cpu.load 键获取带默认参数的 CPU 负载，也可以使用 cpu.load[percpu,avg15] 获取有关 CPU 负载的特定数据。

示例 3：运行多个 low-level discovery 规则来处理相同的发现项。

Alias=vfs.fs.discovery[*]:vfs.fs.discovery

现在可以使用 vfs.fs.discovery 并为每条规则设置不同参数来配置多个发现规则，例如 vfs.fs.discovery[foo]、vfs.fs.discovery[bar] 等。

AllowKey

允许执行与某个模式匹配的监控项键。 键模式是一个通配符表达式，支持 * 字符来匹配任意数量的任意字符。
可与 DenyKey 结合定义多个键匹配规则。 参数会按照其出现顺序逐个处理。 另请参见：限制 agent 检查。

BufferSend

该时间间隔（以秒为单位）决定了数值从缓冲区发送到Zabbix server的频率。
请注意，如果缓冲区已满，数据将会提前发送。

默认值：5
范围：1-3600

BufferSize

设置内存缓冲区中的最大值数量。
如果缓冲区已满，agent 将把所有已收集的数据发送到 Zabbix 服务器或 proxy。
仅当持久缓冲区被禁用（EnablePersistentBuffer=0）时才应使用此参数。

默认值：1000
范围：2-65535

ControlSocket

用于通过 -R 选项发送运行时命令的控制套接字。

默认值：\\.\pipe\agent.sock

DebugLevel

指定调试级别：

• 0 - 关于 Zabbix 进程启动和停止的基本信息；
• 1 - 关键信息；
• 2 - 错误信息；
• 3 - 警告；
• 4 - 用于调试（会产生大量信息）；
• 5 - 扩展调试（会产生更多信息）。

默认值：3
范围：0-5

DenyKey

拒绝执行与模式匹配的监控项键。 键模式是一个通配符表达式，支持 * 字符来匹配任意数量的任意字符。
可与 AllowKey 组合定义多个键匹配规则。 参数会按照其出现顺序逐个处理。 另请参见：限制 agent 检查。

EnablePersistentBuffer

启用本地持久化存储以支持主动式监控项。 若禁用持久化存储，将使用memory缓冲区。

默认值：0
可选值：0 - 禁用，1 - 启用

ForceActiveChecksOnStart

在重启后立即对首次接收到的配置执行主动检查。 也可作为每个插件的配置参数使用，例如：Plugins.Uptime.System.ForceActiveChecksOnStart=1

默认值：0
取值：0 - 禁用，1 - 启用

HeartbeatFrequency

心跳消息的频率（以秒为单位）。 用于监控主动检查的可用性。
0 - 禁用心跳消息。

默认值：60
范围：0-3600

HostInterface

一个可选参数，用于定义在主机 自动注册 过程中使用的主机接口（IP 地址或 DNS 名称）。 该值将用于填充新创建主机中的接口，并允许显式配置 IP 或 DNS 地址。 更多详情，请参见 将 DNS 用作默认接口。

如果未定义，该值将从 HostInterfaceItem 获取。

如果该值超过 255 个字符的限制，agent 将报错并且不会启动。

范围：0-255 个字符

HostInterfaceItem

一个可选参数，用于定义在主机 自动注册 过程中，用来确定主机接口（IP 地址或 DNS 名称）的监控项。 仅当未定义 HostInterface 时，才会使用此值。 有关更多详细信息，请参见 将 DNS 用作默认接口。

在自动注册请求期间，如果指定监控项返回的值超过 255 个字符的限制，agent 将记录一条警告消息。

无论 AllowKey/DenyKey 设置如何，都会支持 system.run[] 监控项。

HostMetadata

一个可选参数，用于定义在主机 自动注册 过程中用于识别或区分主机的 元数据（主动 agent）。 HostMetadata 允许在主机名之外进一步区分不同主机。

如果未定义，该值将从 HostMetadataItem 获取。

如果指定的值超过 2034 字节，或者是非 UTF-8 字符串，agent 将报错且不会启动。 当某个参数期望的是 IP 地址或 DNS 名称时，虽然值可能是有效的 UTF-8，但如果不是有效的 IP 或 DNS 名称，也会被拒绝并报告为无效。

不支持多行元数据 — 输出将在第一个换行处被截断。

范围：0-2034 字节

HostMetadataItem

一个可选参数，用于定义一个 Zabbix agent 监控项，以获取 主机元数据。 仅当未定义 HostMetadata 时，才会使用此选项。

HostMetadataItem 的值会在每次 自动注册 尝试时获取，并且仅在主机自动注册流程（active agent）中使用。 HostMetadataItem 允许在主机名之外区分不同的主机。

支持用户参数和别名。 无论 AllowKey/DenyKey 设置如何，均支持 system.run[] 监控项。

在自动注册请求期间，如果指定监控项返回的值超过 65535 个 UTF-8 码点的限制，agent 将记录一条警告消息。 监控项返回的值必须是 UTF-8 字符串，否则将被忽略。 当某个参数期望的是 IP 地址或 DNS 名称时，虽然值可能是有效的 UTF-8，但如果不是有效的 IP 或 DNS 名称，也会被拒绝并报告为无效。

不支持多行元数据 — 输出将在第一个换行处被截断。

Hostname

以逗号分隔的唯一主机名列表（区分大小写）。 主动检查所必需，且必须与服务器上配置的主机名相匹配。 若未定义，该值将从HostnameItem获取。
允许字符：字母数字、'.'、' '、'_'及'-'。 最大长度：每个主机名128字符，整行2048字符。

默认值：由HostnameItem设置

主机名监控项

一个可选参数，用于定义一个用于获取主机名的监控项。 仅当未定义 Hostname 时使用此选项。 不支持用户参数或别名，但无论 AllowKey/DenyKey 的值如何，均支持 system.run[] 监控项。

默认值：system.hostname

包含

您可以在配置文件中包含单个文件或目录中的所有文件（如果通过 Windows MSI 安装包安装 Zabbix agent，则默认位于 C:\Program Files\Zabbix Agent 2；如果 Zabbix agent 以 zip 压缩包形式安装，则位于安装时指定的文件夹中）。 所有包含的文件都必须具有 正确的语法，否则 agent 将无法启动。 该路径可以相对于 zabbix_agent2.conf 文件的位置（例如， Include=.\zabbix_agent2.d\plugins.d\*.conf）。
若只想包含指定目录中相关的文件，支持使用星号通配符进行模式匹配。
有关限制，请参见特殊说明。

示例：

Include=C:\Program Files\Zabbix Agent2\zabbix_agent2.d\*.conf

ListenIP

一个逗号分隔的IP地址列表，agent应监听这些地址。 第一个IP地址会被发送到Zabbix server（如果连接到它）以获取活动检查的列表。

默认值：0.0.0.0

ListenPort

agent将在此端口监听来自服务器的连接。

默认值：10050
范围：1024-32767

LogFile

agent 日志文件的名称。

默认值：c:\zabbix_agent2.log
必填：是，如果 LogType 设置为 file；否则不是

LogFileSize

日志file的最大大小，单位为MB。
0 - 禁用自动日志轮转。
注意：如果日志file大小达到限制且file轮转失败（无论何种原因），现有日志file将被截断并重新开始记录。

默认值：1
范围：0-1024

LogType

日志输出类型：

• file - 将日志写入 LogFile 参数指定的文件；
• console - 将日志写入标准输出。

默认值：file

PersistentBufferFile

Zabbix agent 2 应保存 SQLite 数据库的文件。 必须是完整文件名。 仅在启用持久缓冲区时使用此参数（EnablePersistentBuffer=1）。

PersistentBufferPeriod

在无法连接到服务器或 proxy 时，数据应被存储的时间段。 较早的数据将会丢失。 日志数据将被保留。 仅在启用持久缓冲区时使用此参数（EnablePersistentBuffer=1）。

默认值：1h
范围：1m-365d

Plugins.<PluginName>.System.Capacity

每个<PluginName>插件可以同时执行的检查数量限制.

默认值: 1000 范围: 1-1000

Plugins.Log.MaxLinesPerSecond

设置 agent 在处理 log、logrt 和 eventlog 主动检查时，每秒发送给 Zabbix 服务器或 proxy 的最大新行数。 所提供的值将被 log、logrt 或 eventlog 监控项键中的 maxlines 参数覆盖。
注意：Zabbix 处理的新行数将是 MaxLinesPerSecond 设置值的 10 倍，以便在日志监控项中查找所需字符串。

默认值：20
范围：1-1000

Plugins.SystemRun.LogRemoteCommands

启用将已执行的 shell 命令记录为警告。 仅当命令是远程执行时，才会记录。 如果 system.run[] 由 HostMetadataItem、HostInterfaceItem 或 HostnameItem 参数在本地启动，则不会创建日志条目。

默认值: 0
取值: 0 - 禁用，1 - 启用

PluginSocket

用于可加载插件通信的 Windows 命名管道路径。

默认值：\\.\pipe\agent.plugin.sock

PluginTimeout

可加载插件连接超时时间（秒）

默认值：Timeout
范围：1-30

PerfCounter

定义一个新参数 <parameter_name>，它是系统性能计数器 <perf_counter_path> 在指定时间段 <period>（以秒为单位）内的平均值。
语法：<parameter_name>,"<perf_counter_path>",<period>

例如，如果您希望获取最近一分钟内每秒处理器中断的平均数量，可以将新参数 "interrupts" 定义如下：

PerfCounter = interrupts,"\Processor(0)\Interrupts/sec",60

请注意性能计数器路径周围的双引号。 参数名称（interrupts）在创建监控项时将用作监控项键。 用于计算平均值的样本将每秒采集一次。
您可以运行 typeperf -qx 来获取 Windows 中可用的所有性能计数器列表。

PerfCounterEn

定义一个新参数<parameter_name>，该参数表示系统性能计数器<perf_counter_path>在指定时间段<period>（以秒为单位）内的平均值。 与PerfCounter相比，perfcounter路径必须使用英文。 仅支持Windows Server 2008/Vista及更高版本。
语法：<parameter_name>,"<perf_counter_path>",<period>

例如，如果您希望获取过去一分钟内处理器每秒中断次数的平均值，可以按以下方式定义名为"interrupts"的新参数：

PerfCounterEn = interrupts,"\Processor(0)\Interrupts/sec",60

请注意性能计数器路径两侧的双引号。 参数名(interrupts)将作为创建监控项时的监控项键使用。 系统将每秒采集一次样本用于计算平均值。
您可以通过查看以下注册表项获取英文字符串列表：HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\009。

RefreshActiveChecks

主动检查列表的刷新频率，以秒为单位。 请注意，若主动检查刷新失败，下一次刷新尝试将在60秒后进行。

默认值：5
范围：1-86400

服务器

以逗号分隔的 IP 地址列表，可选使用 CIDR 表示法，或 Zabbix 服务器或 Zabbix proxy 的 DNS 名称。 仅接受来自此处列出的主机的传入连接。 如果启用了 IPv6 支持，则 127.0.0.1、::127.0.0.1、::ffff:127.0.0.1 会被视为相同，且 ::/0 将允许任何 IPv4 或 IPv6 地址。 0.0.0.0/0 可用于允许任何 IPv4 地址。 允许使用空格。 如果未指定此参数，则会禁用被动检查，且 agent 不会监听任何 TCP 端口。

示例：

Server=127.0.0.1,192.168.1.0/24,::1,2001:db8::/32,zabbix.example.com

ServerActive

用于获取主动检查的 Zabbix 服务器/proxy 地址或集群配置。 服务器/proxy 地址是 IP 地址或 DNS 名称，后跟可选端口，二者用冒号分隔。
集群配置是一个或多个服务器或 proxy 组成员地址，地址之间用分号分隔。 可以指定多个 Zabbix 服务器/集群和 Zabbix proxy，彼此之间用逗号分隔。 除非使用 proxy 组，否则每个 Zabbix 服务器/集群不应指定多个 Zabbix proxy。 如果指定了某个 Zabbix proxy，则不应再为该 proxy 指定对应的 Zabbix 服务器/集群。
可以提供多个以逗号分隔的地址，以便并行使用多个独立的 Zabbix 服务器。 允许包含空格。
如果未指定端口，则使用默认端口。
如果为该主机指定了端口，则 IPv6 地址必须用方括号括起来。 如果未指定端口，则 IPv6 地址的方括号可选。
如果未指定此参数，则会禁用主动检查。

Zabbix proxy 示例：

ServerActive=127.0.0.1:10051

Zabbix proxy 组示例：

ServerActive=proxy1.example.com;proxy2.example.com;proxy3.example.com;proxy4.example.com;proxy5.example.com

多个服务器示例：

ServerActive=127.0.0.1:20051,zabbix.domain,\[::1\]:30051,::1,\[12fc::1\]

高可用示例：

ServerActive=zabbix.cluster.node1;zabbix.cluster.node2:20051;zabbix.cluster.node3

包含两个集群和一台服务器的高可用示例：

ServerActive=zabbix.cluster.node1;zabbix.cluster.node2:20051,zabbix.cluster2.node1;zabbix.cluster2.node2,zabbix.domain

SourceIP

用于以下场景的源 IP 地址：

• 到 Zabbix 服务器或 Zabbix proxy 的出站连接；
• 在执行某些监控项（web.page.get、net.tcp.port 等）时建立连接。

StatusPort

若设置此参数，agent将监听该端口以处理HTTP状态请求（http://localhost:<端口>/status）。

取值范围：1024-32767

Timeout

指定与Zabbix proxy或服务器建立连接及交换数据的等待时间（秒）。

该参数定义各类通信操作的最长持续时间，包括：

• 等待Zabbix server响应；
• 向Zabbix server发送请求，包括主动检查中的监控项配置请求和监控项数据；
• 通过日志文件或Windows事件日志监控获取日志数据；
• 发送心跳消息；
• vfs.*检查的最大持续时间；
• 作为version 7.0以下版本的server 或 proxy发送无超时检查时的后备方案。

该超时设置不适用于在前端（全局、proxy或单个监控项级别）可配置超时时间的agent检查项。

默认值：3
取值范围：1-30

TLSAccept

入站连接所需的加密级别。 用于被动检查。 可以指定多个值，以逗号分隔：

• unencrypted - 接受未加密连接（默认）；
• psk - 接受使用 TLS 和预共享密钥（PSK）的连接；
• cert - 接受使用 TLS 和证书的连接。

必填：是，如果已定义 TLS 证书或 PSK 参数（即使是 unencrypted 连接）；否则为否

TLSCAFile

包含用于对等证书验证的Top级别CA证书的file完整路径名，用于Zabbix组件之间的加密通信。

TLSCertFile

包含用于与Zabbix组件进行加密通信的agent证书或证书链的file完整路径名。

TLSCipherAll13

OpenSSL加密套件string（TLS 1.3版本）。 覆盖基于证书和PSK加密的默认密码套件选择标准。

示例：

TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

该参数从Zabbix 7.0.4版本开始支持。

TLSCipherCert13

OpenSSL 密码字符串（TLS 1.3）。 覆盖基于证书的加密的默认密码套件选择标准。

请注意，此参数不能与 TLSAccept=cert,psk 一起使用；对于证书连接（TLSConnect=cert），请改用 TLSCipherAll13。

此参数自 Zabbix 7.0.4 起受支持。

TLSCipherPSK13

OpenSSL加密套件string（TLS 1.3版本）。 覆盖基于PSK加密的默认密码套件选择标准。

示例：

TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

该参数自Zabbix 7.0.4版本起支持。

TLSConnect

agent 与 Zabbix 服务器或 proxy 连接所需的加密级别。
用于主动检查。
只能指定一个值：

• unencrypted - 不使用加密连接（默认）；
• psk - 使用 TLS 和预共享密钥（PSK）连接；
• cert - 使用 TLS 和证书连接。

必填：是，如果定义了 TLS 证书或 PSK 参数（即使是 unencrypted 连接）；否则为否

TLSCRLFile

包含已撤销证书的file完整路径名。 该参数用于Zabbix组件之间的加密通信。

TLSKeyFile

包含用于Zabbix组件间加密通信的agent私钥的file完整路径名。

TLSPSKFile

包含用于与Zabbix server进行加密通信的agent预共享密钥的file完整路径名.

TLSPSKIdentity

预共享密钥标识string，用于与Zabbix server进行加密通信。

TLSServerCertIssuer

允许的服务器(proxy)证书颁发机构。

TLSServerCertSubject

允许的服务器(proxy)证书主题。

UnsafeUserParameters

允许在用户自定义参数参数中传递所有字符。 以下字符不允许使用：\ ' " ` * ? [ ] { } \~ $ ! & ; ( ) < > | # @
此外，换行符也不允许使用。

默认值：0
取值：0 - 不允许，1 - 允许

UserParameter

用于监控的用户自定义参数。 可以有多个用户自定义参数。
格式：UserParameter=<key>,<shell command>
请注意，shell 命令不能只返回空字符串或仅返回 EOL。 如果指定了 UserParameterDir 参数，shell 命令可以使用相对路径。

示例：

UserParameter=system.test,dir /b | find /c /v ""
UserParameter=check_cpu,.\custom\_script.bat

UserParameterDir

UserParameter 命令的默认搜索路径。 如果使用此参数，agent 会在执行命令之前将其工作目录更改为此处指定的目录。 因此，UserParameter 命令可以使用相对的 .\ 前缀，而不是完整路径。
只允许一条配置项。

示例：

UserParameterDir=C:\opt\myscripts