Benutzerparameter

Overview

A user parameter lets you define a custom item key and the command used to retrieve its value when no built-in Zabbix agent item provides the data you need. A user parameter is a user-defined command referenced by a user-defined item key and executed by the Zabbix agent when the corresponding item is checked.

There are two types of user parameters:

• Simple user parameters do not accept arguments; they define a fixed item key and a command to execute.
• Flexible user parameters accept arguments (specified as parameters in the item key) and pass them to the command, allowing a single definition to serve multiple items.

User parameter configuration

A user parameter is defined using the UserParameter configuration parameter.

A user parameter has the following syntax:

UserParameter=<key>,<shell command>

where:

• <key> - a unique item key that identifies the user parameter.
  When configuring an item, specify this key to reference the command defined by the user parameter.
  For a simple user parameter, the key is fixed and does not accept arguments. For a flexible user parameter, append [*] to the key (for example, mysql.status[*]) to indicate that it accepts arguments. Specify these arguments as parameters in the item key when configuring the item. The command can refer to the parameters using positional references $1–$9.
• <shell command> - a shell command or a path to a custom script that the agent executes to obtain the item value.
  For the flexible user parameter, the command can use positional references $1–$9 to refer to the corresponding parameters in the item key (for example, UserParameter=mysql.status[*],mysqladmin status --user=$1 --password=$2). Zabbix parses the parameters enclosed in [] in the item key (i.e., mysql.status[zabbix,{$MYSQL.PASSWORD}]) and substitutes the positional references in the command accordingly.
  $0 is substituted with the original command before positional references are expanded. Positional references are interpreted regardless of whether they are enclosed in double (") or single (') quotes. To use positional references without substitution, specify a double dollar sign. For example, awk '{print $$2}' passes $2 to the command unchanged.
  Note that positional references prefixed with $ are searched for and replaced by the Zabbix agent only in flexible user parameters. For simple user parameters, positional references are not processed, so escaping $ is unnecessary.

UserParameter must be configured on each Zabbix agent that uses it:

• Directly in the Zabbix agent configuration file (zabbix_agentd.conf or zabbix_agent2.conf).
• In a separate *.conf file, provided that the file is included by the agent configuration.

More than one UserParameter can be defined per agent, as multiple files can be included with different sets of parameters. Each user parameter must have a unique item key within the monitored host.

The UserParameterDir configuration parameter lets you specify the working directory for executing UserParameter commands. If configured, the agent changes its working directory to the specified directory before executing a command. Commands can be specified using a relative path with the ./ prefix, for example, UserParameter=mykey,./myscript.sh.

To configure a user parameter:

1. Write a custom script or command to retrieve the required data.
2. Add the command and its unique item key to the UserParameter configuration parameter in the Zabbix agent configuration file (zabbix_agentd.conf).

3. Reload user parameters from the configuration file by running the runtime control command:

   zabbix_agentd -R userparameter_reload

   Alternatively, restart the agent to apply the configuration changes.

4. Create a new item on the monitored host with the item key defined in UserParameter.
   Set the item's type to Zabbix Agent or Zabbix Agent (active).
   Make sure that the item's Type of information is configured correctly; otherwise, Zabbix will reject the returned value.

See Extending Zabbix agents for an example of configuring and using user parameters.

User parameters are subject to the Zabbix agent check timeout. If the timeout is reached, the process executing the user parameter is terminated. See Command execution for more information.

Note that long-running scripts may consume system resources and delay other checks.

Befehlsergebnis

Der Rückgabewert des Befehls ist die Standardausgabe zusammen mit der Standardfehlerausgabe, die vom Befehl erzeugt wird.

Der Rückgabewert ist auf 16 MB begrenzt (einschließlich nachgestellter Leerzeichen, die abgeschnitten werden); Datenbankbeschränkungen gelten ebenfalls.

Benutzerparameter, die Text zurückgeben (Zeichen-, Log- oder Texttyp von Informationen), können ebenfalls Leerraum zurückgeben. Im Fall eines ungültigen Ergebnisses wird der Datenpunkt zu „nicht unterstützt“.

Beispiele für einfache Benutzerparameter

Ein einfacher Befehl:

UserParameter=ping,echo 1

Der Agent wird immer eine "1" für ein Element mit dem Schlüssel "ping" zurückgeben.

Ein komplexeres Beispiel:

UserParameter=mysql.ping,mysqladmin -uroot ping | grep -c alive

Der Agent gibt '1' zurück, wenn der MySQL-Server aktiv ist, andernfalls '0'.

Beispiel 1

Etwas sehr Einfaches:

UserParameter=ping[*],echo $1

Wir können eine unbegrenzte Anzahl von Elementen für die Überwachung definieren, die alle das folgende Format haben ping[something].

• ping[0] - wird immer '0' zurückgeben
• ping[aaa] - wird immer 'aaa' zurückgeben

Beispiel 2

Lassen Sie uns mehr Sinn hinzufügen!

UserParameter=mysql.ping[*],mysqladmin -u$1 -p$2 ping | grep -c alive

Dieser Parameter kann zur Überwachung der Verfügbarkeit einer MySQL-Datenbank verwendet werden. Wir können Benutzernamen und Passwort übergeben:

mysql.ping[zabbix,our_password]

Beispiel 3

Wie viele Zeilen in einer Datei entsprechen einem regulären Ausdruck?

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

Dieser Parameter kann verwendet werden, um die Anzahl der Zeilen in einer Datei zu berechnen.

wc[/etc/passwd,root]
wc[/etc/services,zabbix]