Zabbix Documentation 2.4

3.04.04.4 (current)| In development:5.0 (devel)| Unsupported:1.82.02.22.43.23.44.2Guidelines

User Tools

Site Tools


manual:config:items:userparameters

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

manual:config:items:userparameters [2017/10/10 05:40]
manual:config:items:userparameters [2016/01/13 09:41] (current)
martins-v trying to fix numbering
Line 1: Line 1:
 +==== 4 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 [[manual:​appendix:​config:​zabbix_agentd|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.
 +
 +Then, when [[item|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. Up to 512KB of data can be returned. **/bin/sh** is used as a command line interpreter under UNIX operating systems. User parameters obey the agent check timeout; if timeout is reached the forked user parameter process is terminated.
 +
 +See also:
 +
 +  * [[manual:​config:​items:​userparameters:​extending_agent|Step-by-step tutorial]] on making use of user parameters
 +  * [[manual/​appendix/​command_execution|Command execution]]
 +
 +== Examples of simple user parameters ==
 +
 +A simple command:
 +
 +  UserParameter=ping,​echo 1
 +
 +The agent will always return '​1'​ for an item with '​ping'​ key.
 +
 +A more complex example:
 +
 +  UserParameter=mysql.ping,​mysqladmin -uroot ping | grep -c alive
 +
 +The agent will return '​1',​ if MySQL server is alive, '​0'​ - otherwise.
 +
 +=== 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. ​ |
 +
 +<note important>​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.</​note>​
 +
 +<note important>​Unless [[manual:​appendix:​config:​zabbix_agentd|UnsafeUserParameters]] agent daemon configuration option is enabled, it is not allowed to pass flexible parameters containing these symbols: \ ' " ` * ? [ ] { } ~ $ ! & ; ( ) < > | # @. Additionally,​ newline is not allowed either.</​note>​
 +
 +== Example 1 ==
 +
 +Something very simple:
 +
 +  UserParameter=ping[*],​echo $1
 +
 +We may define unlimited number of items for monitoring all having format ping[something]. ​
 +  * ping[0] - will always return '​0'​
 +  * ping[aaa] - will always return '​aaa'​
 +
 +== Example 2 ==
 +
 +Let's add more sense!
 +
 +  UserParameter=mysql.ping[*],​mysqladmin -u$1 -p$2 ping | grep -c alive
 +
 +This parameter can be used for monitoring availability of MySQL database. We can pass user name and password:
 +
 +  mysql.ping[zabbix,​our_password]
 +
 +== Example 3 ==
 +
 +How many lines matching a regular expression in a file?
 +
 +  UserParameter=wc[*],​grep -c "​$2"​ $1
 +
 +This parameter can be used to calculate number of lines in a file.
 +
 +  wc[/​etc/​passwd,​root]
 +  wc[/​etc/​services,​zabbix]
 +
 +=== Command result ===
 +
 +The return value of the command is standard output together with standard error.
 +
 +<note important>​A text (character, log or text type of information) item will not become unsupported in case of standard error output.</​note>​
 +
 +User parameters that return text (character, log, text type of information) can return whitespace. In case of invalid result item will become unsupported.