Zabbix Documentation 4.2

2.23.04.04.2 (current)In development:4.4 (devel)Unsupported:1.82.02.43.23.4

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

Both sides previous revision Previous revision
Next revision
Previous revision
manual:config:items:userparameters [2014/08/26 15:56]
dimir [Command result] rephrase a note to be bit more clear
manual:config:items:userparameters [2018/10/01 09:42] (current)
Line 1: Line 1:
-==== - #4 User parameters ====+==== 4 User parameters ====
  
 === Overview === === Overview ===
Line 5: Line 5:
 Sometimes you may want to run an agent check that does not come predefined with Zabbix. This is where user parameters come to help. 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 [[:2.4/manual/appendix/config/zabbix_agentd|agent configuration file]] ('​UserParameter'​ configuration parameter).+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: A user parameter has the following syntax:
Line 13: Line 13:
 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. 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 [[:​2.4/​manual/​config/​items/​item|configuring an item]], enter the key to reference the command from the user parameter you want executed.+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. This way you can enhance ​the functionality of Zabbix agents.+User parameters are commands executed by Zabbix agent. Up to 512KB of data can be returned ​before item preprocessing stepsNote, however, that the text value that can be eventually stored in database is limited to 64KB on MySQL (see info on other databases in the [[:​manual/​config/​notifications/​action/​operation/​remote_command#​overview|table]])
  
-See a [[:2.4/manual/config/items/userparameters/extending_agent|step-by-step tutorial]] on making use of user parameters.+**/bin/sh** is used as 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 == == Examples of simple user parameters ==
Line 29: Line 34:
 A more complex example: A more complex example:
  
-  UserParameter=mysql.ping,​mysqladmin -uroot ping|grep -c alive+  UserParameter=mysql.ping,​mysqladmin -uroot ping | grep -c alive
  
 The agent will return '​1',​ if MySQL server is alive, '​0'​ - otherwise. The agent will return '​1',​ if MySQL server is alive, '​0'​ - otherwise.
Line 43: Line 48:
 ^Parameter^Description^ ^Parameter^Description^
 |**Key**|Unique item key. The [*] defines that this key accepts parameters within the brackets.\\ Parameters are given when configuring the item.  | |**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.\\ ​Use positional references $1…$9 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.  |+|**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 ​tip>To use positional references unaltered, specify double dollar sign - for example, awk '​{print $$2}'. In this case ''​$$2''​ will actually turn into ''​$2''​ when executing the command.\\ \\ Note that positional ​references with the $ sign are interpreted ​by Zabbix agent regardless of whether they are enclosed between double (") or single (') quotes.</​note>​+<​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 ​[[:2.4/manual/appendix/config/zabbix_agentd|UnsafeUserParameters]] ​agent daemon configuration option is enabled, it is not allowed to pass flexible parameters containing these symbols: \ ' " ` * ? [ ] { } ~ $ ! & ; ( ) < > | # @  ​</​note>​+<note important>​Certain symbols are not allowed in user parameters by default. See [[manual:appendix:config:zabbix_agentd|UnsafeUserParameters]] ​documentation for a full list.</​note>​
  
 == Example 1 == == Example 1 ==
Line 86: Line 91:
 <note important>​A text (character, log or text type of information) item will not become unsupported in case of standard error output.</​note>​ <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.+User parameters that return text (character, log, text type of information) can return whitespace. In case of invalid result ​the item will become unsupported.