5 User parameters
Overview
Sometimes you may want to run an agent check that does not come predefined with Zabbix. This is where user parameters come to help.
You may write a command that retrieves the data you need and include it in the user parameter in the agent configuration file ('UserParameter' configuration parameter).
A user parameter has the following syntax:
UserParameter=<key>,<command>As you can see, a user parameter also contains a key. The key will be necessary when configuring an item. Enter a key of your choice that will be easy to reference (it must be unique within a host).
Restart the agent or use the agent runtime control option to pick up the new parameter, e.g.:
zabbix_agentd -R userparameter_reloadThen, when configuring an item, enter the key to reference the command from the user parameter you want executed.
User parameters are commands executed by Zabbix agent. Note that up to 16MB of data can be returned before item value preprocessing steps.
On UNIX systems, the agent executes user parameter commands using /bin/sh, under the operating system account running the agent (usually zabbix).
That account must have sufficient permissions to execute the command and access any files, sockets, or credentials it uses.
User parameters obey the agent check timeout; if timeout is reached the forked user parameter process is terminated.
See also:
- Step-by-step tutorial on making use of user parameters
- Command execution
Examples of simple user parameters
Example 1: Constant value
UserParameter=ping,echo 1An item with the key ping always returns 1.
Example 2: MySQL server availability
UserParameter=mysql.ping,mysqladmin ping 2>/dev/null | grep -c aliveReturns 1 if the MySQL server responds and 0 otherwise.
The 2>/dev/null redirection discards standard error output from mysqladmin.
Without it, an error message could be returned together with 0, causing an item with the Numeric information type to become unsupported (see Command result).
This example assumes that MySQL connection credentials are configured for the operating system account running the Zabbix agent, for example, in a MySQL option file accessible to that account.
Flexible user parameters
Flexible user parameters accept parameters with the key. This way a flexible user parameter can be the basis for creating several items.
Flexible user parameters have the following syntax:
UserParameter=key[*],command| Parameter | Description |
|---|---|
| Key | Unique item key. The [*] defines that this key accepts parameters within the brackets. Parameters are given when configuring the item. |
| Command | Command to be executed to evaluate value of the key. For flexible user parameters only: You may use positional references $1…$9 in the command to refer to the respective parameter in the item key. Zabbix parses the parameters enclosed in [ ] of the item key and substitutes $1,...,$9 in the command accordingly. $0 will be substituted by the original command (prior to expansion of $0,...,$9) to be run. Positional references are interpreted regardless of whether they are enclosed between double (") or single (') quotes. To use positional references unaltered, specify a double dollar sign - for example, awk '{print $$2}'. In this case $$2 will actually turn into $2 when executing the command. |
Positional references with the $ sign are searched for and replaced by Zabbix agent only for flexible user parameters. For simple user parameters, such reference processing is skipped and, therefore, any $ sign quoting is not necessary.
Certain characters are not allowed in user parameters by default. For the complete list of characters, see UnsafeUserParameters.
Examples of flexible user parameters
The examples below are for demonstration purposes only and should not be used in production without appropriate safeguards.
Flexible user parameters defined using [*] accept arguments that can introduce command injection risks if not handled safely.
Example 1: Returning a parameter
UserParameter=ping[*],echo $1You can define multiple items using this user parameter, with keys in the format ping[parameter]:
ping[0]- returns0.ping[hello]- returnshello.
Example 2: MySQL availability on a specified host
This parameter can be used to monitor the availability of a MySQL server on a specified host.
UserParameter=mysql.ping[*],mysqladmin -h "$1" ping 2>/dev/null | grep -c aliveThe item with the key mysql.ping[db1.example.com] returns 1 if the MySQL server on that host responds and 0 otherwise.
This example assumes that MySQL connection credentials are configured for the operating system account running the Zabbix agent, for example, in a MySQL option file accessible to that account.
Example 3: Counting lines matching a pattern
This parameter can be used to count the number of lines in a file.
UserParameter=grep.count[*],grep -c "$2" "$1"Returns the number of lines in the file specified by the first argument that match the regular expression specified by the second argument.
For example, grep.count[/etc/passwd,root] returns the number of lines in /etc/passwd that match the regular expression root.
Command result
The return value of the command is a standard output together with a standard error produced by the command.
An item that returns text (character, log, or text type of information) will not become unsupported in case of a standard error output.
The return value is limited to 16MB (including trailing whitespace that is truncated); database limits also apply.
User parameters that return text (character, log, or text type of information) can also return a whitespace. In case of an invalid result, the item will become unsupported.