用户参数

概述

当没有内置的 Zabbix agent 监控项能够提供所需数据时，用户参数允许您定义自定义监控项键值以及用于获取其值的命令。 用户参数是由用户定义的命令，通过用户定义的监控项键值引用，并由 Zabbix agent 在检查相应监控项时执行。

在 UNIX 系统上，agent 使用 /bin/sh 执行用户参数命令，运行时使用的是执行 agent 的操作系统账户（通常为 zabbix）。 该账户必须具有执行命令以及访问命令所使用的任何文件、套接字或凭据的足够权限。

用户参数有两种类型：

  • 简单用户参数不接受参数；它们定义一个固定的监控项键值和要执行的命令。
  • 灵活用户参数接受参数（在监控项键值中指定），并将这些参数传递给命令，从而允许单个定义服务于多个监控项。

用户参数配置

用户参数使用 UserParameter 配置参数定义。

用户参数的语法如下：

UserParameter=<key>,<shell command>

其中：

  • <key> - 用于标识用户参数的唯一监控项键。
    配置监控项时，指定此键以引用用户参数定义的命令。
    对于简单用户参数，键是固定的，不接受参数。 对于灵活用户参数，在键后追加 [*]（例如 mysql.status[*]），表示该键接受参数。 配置监控项时，将这些参数指定为监控项键中的参数。 命令可以使用位置引用 $1–$9 引用这些参数。
  • <shell command> - agent 执行以获取监控项值的 shell 命令或自定义脚本路径。
    对于灵活用户参数，命令可以使用位置引用 $1–$9 引用监控项键中的相应参数（例如 UserParameter=mysql.status[*],mysqladmin status --user=$1 --password=$2）。 Zabbix 会解析监控项键中包含在 [] 内的参数（即 mysql.status[zabbix,{$MYSQL.PASSWORD}]），并相应地替换命令中的位置引用。
    在展开位置引用之前，$0 会替换为原始命令。 无论位置引用是否包含在双引号 (") 或单引号 (') 中，都会对其进行解析。 如需使用位置引用而不进行替换，请指定两个美元符号。 例如，awk '{print $$2}' 会将 $2 原样传递给命令。
    请注意，只有在灵活用户参数中，Zabbix agent 才会搜索并替换以 $ 开头的位置引用。 对于简单用户参数，不会处理位置引用，因此无需对 $ 进行转义。

默认情况下，某些字符不能作为参数传递。 有关完整的字符列表，请参阅 UnsafeUserParameters。

每个使用该参数的 Zabbix agent 都必须配置 UserParameter：

  • 直接在 Zabbix agent 配置文件（zabbix_agentd.conf 或 zabbix_agent2.conf）中配置。
  • 在单独的 *.conf 文件中配置，前提是该文件已由 agent 配置包含。

每个 agent 可以定义多个 UserParameter，因为可以包含具有不同参数集的多个文件。 每个用户参数在受监控主机中必须具有唯一的监控项键。

UserParameterDir 配置参数用于指定执行 UserParameter 命令时的工作目录。 如果已配置该参数，agent 会在执行命令前将其工作目录切换到指定目录。 可以使用带有 ./ 前缀的相对路径指定命令，例如 UserParameter=mykey,./myscript.sh。

配置用户参数：

  1. 编写用于获取所需数据的自定义脚本或命令。
  2. 将命令及其唯一的监控项键添加到 Zabbix agent 配置文件（zabbix_agentd.conf）中的 UserParameter 配置参数。

  3. 运行运行时控制命令，从配置文件重新加载用户参数：

    zabbix_agentd -R userparameter_reload

    也可以重启 agent 以应用配置更改。

  4. 在受监控主机上使用 UserParameter 中定义的监控项键创建新监控项。
    将监控项的类型设置为 Zabbix Agent 或 Zabbix Agent (active)。
    确保正确配置监控项的 Type of information；否则，Zabbix 将拒绝返回的值。

有关配置和使用用户参数的示例，请参阅扩展 Zabbix agent。

用户参数受 Zabbix agent 检查超时限制。 如果达到超时时间，执行用户参数的进程将被终止。 有关更多信息，请参阅命令执行。

请注意，长时间运行的脚本可能会消耗系统资源，并延迟其他检查。

命令结果

命令的返回值由命令生成的标准输出和标准错误组成。

返回文本（字符、日志或文本信息类型）的用户参数也可以返回空白字符。 如果命令生成无效结果，监控项将变为不受支持。 但是，具有上述信息类型之一的监控项不会仅因为命令在标准错误中生成输出而变为不受支持。

命令的返回值限制为 16 MB，包括尾随空白字符；超出部分将被截断。 此限制在执行监控项值预处理步骤之前生效。 数据库限制同样适用。

用户参数示例

本节提供了简单用户参数和灵活用户参数的示例。

以下示例仅用于演示目的，未经适当的安全防护，不应在生产环境中使用。 使用 [*] 定义的灵活用户参数接受可能引入命令注入风险的参数，除非进行安全处理。

简单用户参数示例

示例 1：常量值

UserParameter=ping,echo 1

键为 ping 的监控项始终返回 1。

示例 2：MySQL 服务器可用性

UserParameter=mysql.ping,mysqladmin ping 2>/dev/null | grep -c alive

如果 MySQL 服务器响应，则返回 1；否则返回 0。 2>/dev/null 重定向会丢弃 mysqladmin 的标准错误输出。 如果没有此重定向，错误消息可能会与 0 一起返回，从而导致信息类型为 Numeric 的监控项变为不支持（请参阅命令结果）。
此示例假设已为运行 Zabbix agent 的操作系统账户配置 MySQL 连接凭据，例如，将凭据配置在该账户可访问的 MySQL 选项文件中。

灵活用户参数示例

示例 1：返回参数

UserParameter=ping[*],echo $1

您可以使用此用户参数定义多个监控项，其键的格式为 ping[parameter]：

  • ping[0] - 返回 0。
  • ping[hello] - 返回 hello。

示例 2：指定主机上的 MySQL 可用性

此参数可用于监控指定主机上 MySQL 服务器的可用性。

UserParameter=mysql.ping[*],mysqladmin -h "$1" ping 2>/dev/null | grep -c alive

键为 mysql.ping[db1.example.com] 的监控项在该主机上的 MySQL 服务器响应时返回 1，否则返回 0。
此示例假设已为运行 Zabbix agent 的操作系统账户配置 MySQL 连接凭据，例如，将凭据配置在该账户可访问的 MySQL 选项文件中。

示例 3：统计匹配模式的行数

此参数可用于统计文件中的行数。

UserParameter=grep.count[*],grep -c "$2" "$1"

返回第一个参数指定的文件中与第二个参数指定的正则表达式匹配的行数。 例如，grep.count[/etc/passwd,root] 返回 /etc/passwd 中与正则表达式 root 匹配的行数。