Parametri utente

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.

Risultato del comando

Il valore restituito dal comando è l'output standard insieme all'errore standard prodotto dal comando.

Il valore restituito è limitato a 16MB (inclusi gli spazi finali che vengono troncati); si applicano anche i limiti del database.

I parametri utente che restituiscono testo (informazioni di tipo character, log o text) possono anche restituire spazi vuoti. In caso di risultato non valido, l'item diventerà unsupported.

Esempi di parametri utente semplici

Un comando semplice:

UserParameter=ping,echo 1

L'agent restituirà sempre '1' per un item con chiave 'ping'.

Un esempio più complesso:

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

L'agent restituirà '1' se il server MySQL è attivo, altrimenti '0'.

Esempio 1

Qualcosa di molto semplice:

UserParameter=ping[*],echo $1

Possiamo definire un numero illimitato di item per il monitoraggio, tutti con il formato ping[qualcosa].

• ping[0] - restituirà sempre '0'
• ping[aaa] - restituirà sempre 'aaa'

Esempio 2

Aggiungiamo più funzionalità!

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

Questo parametro può essere utilizzato per monitorare la disponibilità del database MySQL. Possiamo passare nome utente e password:

mysql.ping[zabbix,our_password]

Esempio 3

Quante righe corrispondono a un'espressione regolare in un file?

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

Questo parametro può essere utilizzato per calcolare il numero di righe in un file.

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