Parametry użytkownika

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.

Wynik polecenia

Wartością zwracaną przez polecenie jest standardowe wyjście wraz ze standardowym wyjściem błędów wygenerowanym przez polecenie.

Wartość zwracana jest ograniczona do 16 MB (włącznie z końcowymi białymi znakami, które są obcinane); obowiązują również ograniczenia bazy danych.

Parametry użytkownika zwracające tekst (informacje typu znakowego, log lub tekstowego) mogą również zwracać białe znaki. W przypadku nieprawidłowego wyniku pozycja stanie się nieobsługiwana.

Przykłady prostych parametrów użytkownika

Proste polecenie:

UserParameter=ping,echo 1

agent będzie zawsze zwracał '1' dla pozycji z kluczem 'ping'.

Bardziej złożony przykład:

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

agent zwróci '1', jeśli serwer MySQL działa, w przeciwnym razie '0'.

Przykład 1

Coś bardzo prostego:

UserParameter=ping[*],echo $1

Możemy zdefiniować nieograniczoną liczbę pozycji do monitorowania, wszystkie w formacie ping[coś].

• ping[0] - zawsze zwróci '0'
• ping[aaa] - zawsze zwróci 'aaa'

Przykład 2

Dodajmy więcej sensu!

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

Ten parametr może być używany do monitorowania dostępności bazy danych MySQL. Możemy przekazać nazwę użytkownika i hasło:

mysql.ping[zabbix,our_password]

Przykład 3

Ile linii w pliku pasuje do wyrażenia regularnego?

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

Ten parametr może być używany do obliczania liczby linii w pliku.

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