User parameters

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.

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.

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.

Certain characters cannot be passed as arguments by default. For the complete list of characters, see UnsafeUserParameters.

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.

Command result

The command's return value consists of standard output and standard error produced by the command.

User parameters that return text (the Character, Log, or Text type of information) can also return a whitespace. If the command produces an invalid result, the item becomes unsupported. However, an item with one of these information types will not become unsupported solely because the command produces output on standard error.

The command's return value is limited to 16 MB, including trailing whitespace, which is truncated. This limit applies before item value preprocessing steps. Database limits also apply.

Examples of user parameters

This section provides examples of simple and 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.

Examples of simple user parameters

Example 1: Constant value

UserParameter=ping,echo 1

An item with the key ping always returns 1.

Example 2: MySQL server availability

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

Returns 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.

Examples of flexible user parameters

Example 1: Returning a parameter

UserParameter=ping[*],echo $1

You can define multiple items using this user parameter, with keys in the format ping[parameter]:

  • ping[0] - returns 0.
  • ping[hello] - returns hello.

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 alive

The 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.