配置参数：Zabbix agent 2
概述
配置参数可用于自定义 Zabbix agent 2 的行为。
Zabbix agent 2 是 Zabbix agent 的新一代版本，可用于替代 Zabbix agent。
请在配置文件（zabbix_agent2.conf）中指定参数值。除非明确说明该参数为必填，否则所有参数均为可选。
本页结构如下：
- 参数概览（要查看参数的完整详情，请单击其名称）
- 参数详情
| Parameter | Description |
|---|---|
| Alias | 为监控项键设置别名。 |
| AllowKey | 允许执行与模式匹配的监控项键。 |
| BufferSend | 设置将缓冲区中的值发送到 Zabbix 服务器/proxy 的频率。 |
| BufferSize | 设置内存缓冲区中的最大值数量。 |
| ControlSocket | 指定用于通过 -R 选项发送运行时命令的控制套接字。 |
| DebugLevel | 设置调试级别。 |
| DenyKey | 拒绝执行与模式匹配的监控项键。 |
| EnablePersistentBuffer | 启用本地持久存储以用于主动监控项。 |
| ForceActiveChecksOnStart | 在重启后立即执行主动检查，以获取首次接收到的配置。 |
| HeartbeatFrequency | 设置心跳消息的频率（秒）。 |
| HostInterface | 指定主机接口。 |
| HostInterfaceItem | 指定用于获取主机接口的监控项。 |
| HostMetadata | 指定主机元数据。 |
| HostMetadataItem | 指定一个 Zabbix agent 监控项用于获取主机元数据。 |
| Hostname | 指定主机名。 |
| HostnameItem | 指定一个 Zabbix agent 监控项用于获取主机名。 |
| Include | 指定要包含到配置文件中的目录或单个文件。 |
| ListenIP | 指定 agent 用于接收来自服务器/proxy 连接的监听 IP 地址。 |
| ListenPort | 指定 agent 监听端口。 |
| LogFile | 指定 agent 日志文件。 |
| LogFileSize | 设置日志文件的最大大小。 |
| LogType | 指定日志输出类型。 |
| PersistentBufferFile | 指定用于保存 SQLite 数据库的文件。 |
| PersistentBufferPeriod | 设置在无法连接到 Zabbix 服务器或 proxy 时保存数据的时间段。 |
| PidFile | 指定 PID 文件。 |
| Plugins.<PluginName>.System.Capacity | 设置每个插件可同时执行的检查数量上限。 |
| Plugins.Log.MaxLinesPerSecond | 在处理 log 或 logrt 主动检查时，设置每秒发送到 Zabbix 服务器/proxy 的最大新行数。 |
| Plugins.SystemRun.LogRemoteCommands | 启用将已执行的 shell 命令记录为警告日志。 |
| PluginSocket | 指定用于可加载插件通信的 UNIX 套接字路径。 |
| PluginTimeout | 设置与可加载插件连接的超时时间。 |
| RefreshActiveChecks | 指定刷新主动检查列表的频率。 |
| Server | 指定 Zabbix 服务器/proxy 的 IP 地址或 DNS 名称。 |
| ServerActive | 指定用于获取主动检查的 Zabbix 服务器/proxy 地址或集群配置。 |
| SourceIP | 指定源 IP 地址。 |
| StatusPort | 指定用于监听 HTTP 状态请求的端口（http://localhost:<port>/status）。 |
| Timeout | 指定与 Zabbix 服务器或 proxy 建立连接并交换数据时的等待时长（秒）。 |
| TLSAccept | 指定入站连接所需的加密级别。 |
| TLSCAFile | 指定包含用于对等证书验证的顶级 CA 证书的文件完整路径名，用于 Zabbix 组件之间的加密通信。 |
| TLSCertFile | 指定包含 agent 证书或证书链的文件完整路径名，用于 Zabbix 组件之间的加密通信。 |
| TLSCipherAll | 指定 OpenSSL 密码字符串（TLS 1.2）。覆盖基于证书和 PSK 的加密默认密码套件选择标准。 |
| TLSCipherAll13 | 指定 OpenSSL 密码字符串（TLS 1.3），适用于 OpenSSL 1.1.1 或更新版本。覆盖基于证书和 PSK 的加密默认密码套件选择标准。 |
| TLSCipherCert | 指定 OpenSSL 密码字符串（TLS 1.2）。覆盖基于证书加密的默认密码套件选择标准。 |
| TLSCipherCert13 | 指定 OpenSSL 密码字符串（TLS 1.3），适用于 OpenSSL 1.1.1 或更新版本。覆盖基于证书加密的默认密码套件选择标准。 |
| TLSCipherPSK | 指定 OpenSSL 密码字符串（TLS 1.2）。覆盖基于 PSK 加密的默认密码套件选择标准。 |
| TLSCipherPSK13 | 指定 OpenSSL 密码字符串（TLS 1.3），适用于 OpenSSL 1.1.1 或更新版本。覆盖基于 PSK 加密的默认密码套件选择标准。 |
| TLSConnect | 指定连接到 Zabbix 服务器或 proxy 所需的加密级别。 |
| TLSCRLFile | 指定包含已吊销证书的文件完整路径名。此参数用于 Zabbix 组件之间的加密通信。 |
| TLSKeyFile | 指定包含 agent 私钥的文件完整路径名，用于 Zabbix 组件之间的加密通信。 |
| TLSPSKFile | 指定包含 agent 预共享密钥的文件完整路径名，用于与 Zabbix 服务器的加密通信。 |
| TLSPSKIdentity | 指定预共享密钥标识字符串，用于与 Zabbix 服务器的加密通信。 |
| TLSServerCertIssuer | 指定允许的服务器（proxy）证书颁发者。 |
| TLSServerCertSubject | 指定允许的服务器（proxy）证书主题。 |
| UnsafeUserParameters | 允许将所有字符作为参数传递给用户自定义参数。 |
| UserParameter | 指定要监控的用户自定义参数。 |
| UserParameterDir | 指定 UserParameter 命令的默认搜索路径。 |
请注意：
参数详情
别名
为监控项键设置一个别名。
它可用于用更短、更简单的键替代较长且复杂的监控项键。
可以存在多个 Alias 参数。
不允许存在具有相同 Alias 键的多个参数。
不同的 Alias 键可以引用同一个监控项键。
别名可用于 HostMetadataItem，但不能用于 HostnameItem 参数。
示例 1：检索用户 'zabbix' 的 ID。
Alias=zabbix.userid:vfs.file.regexp[/etc/passwd,"^zabbix:.:([0-9]+)",,,,\1]现在可以使用 zabbix.userid 简写键来检索数据。
示例 2：使用默认和自定义参数获取 CPU 利用率。
Alias=cpu.util:system.cpu.util
Alias=cpu.util[*]:system.cpu.util[*]这允许使用 cpu.util 键通过默认参数获取 CPU 利用率百分比，也可以使用 cpu.util[all, idle, avg15] 获取有关 CPU 利用率的特定数据。
示例 3：运行多个处理相同发现项的 低级别发现 规则。
Alias=vfs.fs.discovery[*]:vfs.fs.discovery现在可以使用 vfs.fs.discovery 并为每条规则设置不同参数来配置多个发现规则，例如 vfs.fs.discovery[foo]、vfs.fs.discovery[bar] 等。
AllowKey
允许执行与模式匹配的监控项键。
键模式是一个通配符表达式，支持使用 "*" 字符匹配任意数量的任意字符。
可与 DenyKey 结合定义多个键匹配规则。
参数会按照其出现顺序逐一处理。
另请参见：限制 agent 检查。
BufferSend
设置将缓冲区中的值发送到 Zabbix 服务器/proxy 的频率（单位：秒）。
请注意，如果缓冲区已满，数据会更快发送。
默认值：5
范围：1-3600
BufferSize
设置内存缓冲区中的最大值数量。
如果缓冲区已满，agent 将把所有已收集的数据发送到 Zabbix 服务器或 proxy。
仅在禁用持久缓冲区时才应使用此参数（EnablePersistentBuffer=0）。
默认值：1000
范围：2-65535
ControlSocket
指定用于通过 -R 选项发送运行时命令的控制套接字。
默认值：/tmp/agent.sock
DebugLevel
设置调试级别：
0 - 关于 Zabbix 进程启动和停止的基本信息
1 - 关键信息；
2 - 错误信息；
3 - 警告；
4 - 用于调试（会产生大量信息）；
5 - 扩展调试（会产生更多信息）。
默认值：3
范围：0-5
DenyKey
拒绝执行与模式匹配的监控项键。
键模式是一个通配符表达式，支持使用 "*" 字符来匹配任意数量的任意字符。
可与 AllowKey 结合定义多个键匹配规则。
参数会按照其出现顺序逐一处理。
另请参见：限制 agent 检查。
EnablePersistentBuffer
为主动监控项启用本地持久化存储的使用。
如果禁用持久化存储，将使用内存缓冲区。
默认值：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
指定用于在主机自动注册期间识别或区分主机的元数据。
HostMetadata 允许在主机名之外进一步区分不同主机。
如果未定义，该值将从 HostMetadataItem 获取。
如果指定的值超过 2034 字节的限制，或者是非 UTF-8 字符串，agent 将报错且不会启动。 当某个参数要求 IP 地址或 DNS 名称时，虽然是有效 UTF-8，但不是有效 IP 或 DNS 名称的值也会被拒绝，并报告为无效。
不支持多行元数据 — 输出将在第一个换行处被截断。
范围：0-2034 字节
HostMetadataItem
指定一个监控项以获取主机元数据。
此选项仅在未定义 HostMetadata 时使用。
HostMetadataItem 的值会在每次自动注册尝试时获取，并且仅在主机自动注册过程中使用。 HostMetadataItem 允许区分主机，而不仅仅依赖主机名。
支持用户参数和别名。 无论 AllowKey/DenyKey 设置如何，均支持 system.run[] 监控项。
在自动注册请求期间，如果指定监控项返回的值超过 65535 个 UTF-8 码点的限制，agent 将记录一条警告消息。 监控项返回的值必须是 UTF-8 字符串，否则将被忽略。 当某个参数期望的是 IP 地址或 DNS 名称时，虽然值可能是有效的 UTF-8，但如果不是有效的 IP 或 DNS 名称，也会被拒绝并报告为无效。
不支持多行元数据 — 输出将在第一个换行处被截断。
主机名
指定唯一、区分大小写的主机名。使用逗号分隔的列表。
这是主动检查所必需的，并且必须与服务器上配置的主机名一致。
如果未定义，则从 HostnameItem 获取该值。
允许的字符：字母数字字符、'.'、' '、'_' 和 '-'。
每个主机名的最大长度为 128 个字符，整行最大长度为 2048 个字符。
默认值：由 HostnameItem 设置
主机名监控项
指定用于获取主机名的监控项。
仅当未定义 Hostname 时使用此选项。
不支持用户参数或别名，但无论 AllowKey/DenyKey 的值如何，均支持 system.run[] 监控项。
默认值：system.hostname
包含
指定要包含到配置文件中的目录或单个文件。
在安装过程中，Zabbix 会在 /usr/local/etc 中创建 include 目录，除非在编译时进行了修改。
该路径可以相对于 zabbix_agent2.conf 文件所在位置。
若要仅包含指定目录中的相关文件，支持使用星号通配符进行模式匹配。
有关限制，请参见 特殊说明。
示例：
Include=/absolute/path/to/config/files/*.confListenIP
指定 agent 用于接收来自服务器/proxy 连接的监听 IP 地址。使用逗号分隔的列表。
如果连接到 Zabbix 服务器，则会将第一个 IP 地址发送给 Zabbix 服务器，以获取主动检查列表。
默认值：0.0.0.0
ListenPort
指定 agent 用于接收来自服务器/proxy 连接的监听端口。
默认值：10050
范围：1024-32767
LogFile
指定 agent 日志文件。
默认值：/tmp/zabbix_agent2.log
必填：是，如果 LogType 设置为 file；否则为否
LogFileSize
设置最大日志文件大小（以 MB 为单位）。
0 - 禁用自动日志轮转。
注意：如果达到日志文件大小限制且文件轮转因任何原因失败，现有日志文件将被截断并重新开始写入。
默认值：1
范围：0-1024
LogType
指定日志输出类型：
file - 将日志写入由 LogFile 参数指定的文件；
system - 将日志写入 syslog；
console - 将日志写入标准输出
默认值：file
PersistentBufferFile
指定用于保存 SQLite 数据库的文件。必须是完整文件名。
仅在启用持久缓冲区时使用此参数（EnablePersistentBuffer=1）。
PersistentBufferPeriod
设置在无法连接到 Zabbix 服务器或 proxy 时用于存储数据的时间段。
较旧的数据将会丢失。
日志数据将被保留。
仅在启用持久缓冲区时使用此参数（EnablePersistentBuffer=1）。
默认值：1h
范围：1m-365d
PidFile
指定 PID 文件。
默认值：/tmp/zabbix_agent2.pid
插件。<PluginName>.System.Capacity
设置 <PluginName> 插件可同时执行的检查数量上限。
默认值：1000
范围：1-1000
Plugins.Log.MaxLinesPerSecond
设置在处理 log 或 logrt 主动检查时，每秒发送到 Zabbix 服务器/proxy 的最大新行数。
所提供的值将被 'maxlines' 参数覆盖，该参数在 'log' 和 'logrt' 监控项键中提供。
注意：Zabbix 处理的新行数将是 MaxLinesPerSecond 设置值的 10 倍，以便在日志监控项中查找所需字符串。
默认值：20
范围：1-1000
Plugins.SystemRun.LogRemoteCommands
将已执行的 shell 命令作为警告进行记录。
仅当命令是远程执行时才会记录。
如果 system.run[] 由 HostMetadataItem、HostInterfaceItem 或 HostnameItem 参数在本地启动，则不会创建日志条目。
默认值：0
取值：0 - 禁用，1 - 启用
PluginSocket
指定用于可加载插件通信的 UNIX socket 路径。
默认值：/tmp/agent.plugin.sock
PluginTimeout
指定可加载插件连接的超时时间，单位为秒。
默认值：Timeout
范围：1-30
RefreshActiveChecks
指定刷新主动检查列表的频率，单位为秒。
请注意，在刷新主动检查失败后，下一次刷新将在 60 秒后尝试。
默认值：5
范围：1-86400
服务器
指定 Zabbix 服务器/proxy 的 IP 地址（可选使用 CIDR 表示法）或 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.comServerActive
指定用于获取主动检查的 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:10051Zabbix 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.domainSourceIP
为以下连接指定源 IP 地址：
- 到 Zabbix 服务器或 Zabbix proxy 的出站连接。
- 在执行某些监控项（web.page.get、net.tcp.port 等）时建立连接。
StatusPort
指定用于监听 HTTP 状态请求的端口（http://localhost:<port>/status）。
范围：1024-32767
超时
指定建立连接以及与 Zabbix proxy 或服务器交换数据时的等待时间（秒）。
此参数定义了多种通信操作的持续时间，包括：
- 等待来自 Zabbix 服务器的响应；
- 向 Zabbix 服务器发送请求，包括监控项配置请求以及 active checks 中的监控项数据；
- 通过 logfile 获取日志数据；
- 发送心跳消息；
vfs.*检查的最长持续时间；- 在服务器或 proxy 版本早于 7.0 且发送的检查不带超时设置时，作为回退值使用。
对于那些在前端中可配置超时设置的 agent 检查（全局、proxy 级别或按监控项级别），此超时将不会被使用。
默认值：3
范围：1-30
TLSAccept
指定传入连接所需的加密级别。
用于被动检查。
可以指定多个值，以逗号分隔：
unencrypted - 接受未加密连接（默认）
psk - 接受使用 TLS 和预共享密钥（PSK）的连接
cert - 接受使用 TLS 和证书的连接
必填：是，如果已定义 TLS 证书或 PSK 参数（即使是 unencrypted 连接）；否则为否
TLSCAFile
指定包含用于对等证书验证的顶级 CA 证书的文件的完整路径名，该证书用于 Zabbix 组件之间的加密通信。
TLSCertFile
指定包含 agent 证书或证书链的文件的完整路径名，用于与 Zabbix 组件之间的加密通信。
TLSCipherAll
指定 OpenSSL 密码字符串（TLS 1.2）。 覆盖基于证书和基于 PSK 的加密所使用的默认密码套件选择标准。
示例：
EECDH+aRSA+AES128:RSA+aRSA+AES128:kECDHEPSK+AES128:kPSK+AES128TLSCipherAll13
为 OpenSSL 1.1.1 或更新版本指定 OpenSSL 密码字符串（TLS 1.3）。 覆盖基于证书和基于 PSK 的加密的默认密码套件选择标准。
示例：
TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256TLSCipherCert
指定 OpenSSL 密码字符串（TLS 1.2）。 覆盖基于证书加密的默认密码套件选择标准。
示例：
EECDH+aRSA+AES128:RSA+aRSA+AES128请注意，此参数不能与 TLSAccept=cert,psk 同时使用；对于证书连接（TLSConnect=cert），请改用 TLSCipherAll。
TLSCipherCert13
为 OpenSSL 1.1.1 或更新版本指定 OpenSSL 密码字符串（TLS 1.3）。 覆盖基于证书的加密所使用的默认密码套件选择条件。
请注意，此参数不能与 TLSAccept=cert,psk 一起使用；对于证书连接（TLSConnect=cert），请改用 TLSCipherAll13。
TLSCipherPSK
指定 OpenSSL 密码字符串（TLS 1.2）。 覆盖基于 PSK 的加密所使用的默认密码套件选择条件。
示例：
kECDHEPSK+AES128:kPSK+AES128TLSCipherPSK13
为 OpenSSL 1.1.1 或更新版本指定 OpenSSL 密码字符串（TLS 1.3）。 覆盖基于 PSK 的加密所使用的默认密码套件选择条件。
示例：
TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256TLSConnect
指定 agent 连接到 Zabbix 服务器或 proxy 所需的加密级别。
用于主动检查。
只能指定一个值：
unencrypted - 不使用加密连接（默认）
psk - 使用 TLS 和预共享密钥（PSK）连接
cert - 使用 TLS 和证书连接
必填：是，如果定义了 TLS 证书或 PSK 参数（即使是 unencrypted 连接）；否则为否
TLSCRLFile
指定包含已吊销证书的文件的完整路径名。 此参数用于 Zabbix 组件之间的加密通信。
TLSKeyFile
指定包含 agent 私钥的文件的完整路径名，用于 Zabbix 组件之间的加密通信。
TLSPSKFile
指定包含 agent 预共享密钥的文件的完整路径名，用于与 Zabbix 服务器进行加密通信。
TLSPSKIdentity
指定预共享密钥标识字符串，用于与 Zabbix 服务器进行加密通信。
TLSServerCertIssuer
指定允许的服务器（proxy）证书颁发者。
TLSServerCertSubject
指定允许的服务器（proxy）证书主题。
UnsafeUserParameters
允许在参数中传递所有字符到用户自定义参数。
以下字符不允许使用：\ ' " ` * ? [ ] { } \~ $ ! & ; ( ) < > | # @ %
此外，不允许使用换行符。
默认值：0
取值：0 - 不允许，1 - 允许
UserParameter
指定一个用户自定义参数用于监控。
可以有多个用户自定义参数。
格式：UserParameter=<key>,<shell command>
请注意，shell 命令不能只返回空字符串或仅返回 EOL。
如果指定了 UserParameterDir 参数，shell 命令可以使用相对路径。
示例：
UserParameter=system.test,who|wc -l
UserParameter=check_cpu,./custom_script.shUserParameterDir
指定 UserParameter 命令的默认搜索路径。
如果使用此参数，agent 会在执行命令之前将其工作目录切换到此处指定的目录。
因此，UserParameter 命令可以使用相对的 ./ 前缀，而不是完整路径。
只允许一条配置项。
示例：
UserParameterDir=/opt/myscripts