8 Scripts

Overview

In the Administration → Scripts section user-defined global scripts can be configured and maintained.

Global scripts, depending on the configured scope and also user permissions, are available for execution:

  • from the host menu in various frontend locations (Dashboard, Problems, Latest data, Maps, etc)
  • from the event menu
  • can be run as an action operation

The scripts are executed on Zabbix agent, Zabbix server (proxy) or Zabbix server only. See also Command execution.

Both on Zabbix agent and Zabbix proxy remote scripts are disabled by default. They can be enabled by:

  • adding the AllowKey=system.run[*] parameter in agent configuration;
  • setting the EnableRemoteCommands parameter to ‘1’ in proxy configuration

A listing of existing scripts with their details is displayed.

8 Scripts - 图1

Displayed data:

ColumnDescription
NameName of the script. Clicking on the script name opens the script configuration form.
ScopeScope of the script - action operation, manual host action or manual event action. This setting determines where the script is available.
Used in actionsActions where the script is used are displayed.
TypeScript type is displayed - Webhook, Script, SSH, Telnet or IPMI command.
Execute onIt is displayed whether the script will be executed on Zabbix agent, Zabbix server (proxy) or Zabbix server only.
CommandsAll commands to be executed within the script are displayed.
User groupThe user group that the script is available to is displayed (or All for all user groups).
Host groupThe host group that the script is available for is displayed (or All for all host groups).
Host accessThe permission level for the host group is displayed - Read or Write. Only users with the required permission level will have access to executing the script.

To configure a new script, click on the Create script button in the top right-hand corner.

Mass editing options

A button below the list offers one mass-editing option:

  • Delete - delete the scripts

To use this option, mark the checkboxes before the respective scripts and click on Delete.

Using filter

You can use the filter to display only the scripts you are interested in. For better search performance, data is searched with macros unresolved.

The Filter link is available above the list of scripts. If you click on it, a filter becomes available where you can filter scripts by name and scope.

8 Scripts - 图2

Configuring a global script

8 Scripts - 图3

Script attributes:

ParameterDescription
NameUnique name of the script.
E.g. Clear /tmp filesystem
ScopeScope of the script - action operation, manual host action or manual event action. This setting determines where the script can be used - in remote commands of action operations, from the host menu or from the event menu respectively.
Setting the scope to ‘Action operation’ makes the script available for all users with access to ConfigurationActions.
If a script is actually used in an action, its scope cannot be changed away from ‘action operation’.
Macro support
The scope affects the range of available macros. For example, user-related macros ({USER.}) are supported in scripts to allow passing information about the user that launched the script. However, they are not supported if the script scope is action operation, as action operations are executed automatically.
To find out which macros are supported, do a search for ‘Trigger-based notifications and commands/Trigger-based commands’, ‘Manual host action scripts’ and ‘Manual event action scripts’ in the supported macro table. Note that if a macro may resolve to a value with spaces (for example, host name), don’t forget to quote as needed.
Menu pathThe desired menu path to the script. For example, Default or Default/, will display the script in the respective directory. Menus can be nested, e.g. Main menu/Sub menu1/Sub menu2. When accessing scripts through the host/event menu in monitoring sections, they will be organized according to the given directories.
This field is displayed only if ‘Manual host action’ or ‘Manual event action’ is selected as Scope.
TypeClick the respective button to select script type:
Webhook, Script, SSH, Telnet or IPMI command.
Script type: Webhook
ParametersSpecify the webhook variables as attribute-value pairs.
See also: Webhook media configuration.
Macros and custom user macros are supported in parameter values. Macro support depends on the scope of the script (see Scope above).
ScriptEnter the JavaScript code in the block that appears when clicking in the parameter field (or on the view/edit button next to it).
Macro support depends on the scope of the script (see Scope above).
See also: Webhook media configuration, Additional Javascript objects.
TimeoutJavaScript execution timeout (1-60s, default 30s).
Time suffixes are supported, e.g. 30s, 1m.
Script type: Script
Execute onClick the respective button to execute the shell script on:
Zabbix agent - the script will be executed by Zabbix agent (if the system.run item is allowed) on the host
Zabbix server (proxy) - the script will be executed by Zabbix server or proxy (if enabled by EnableRemoteCommands) - depending on whether the host is monitored by server or proxy
Zabbix server - the script will be executed by Zabbix server only
CommandsEnter full path to the commands to be executed within the script.
Macro support depends on the scope of the script (see Scope above). Custom user macros are supported.
Script type: SSH
Authentication methodSelect authentication method - password or public key.
UsernameEnter the username.
PasswordEnter the password.
This field is available if ‘Password’ is selected as the authentication method.
Public key fileEnter the path to the public key file.
This field is available if ‘Public key’ is selected as the authentication method.
Private key fileEnter the path to the private key file.
This field is available if ‘Public key’ is selected as the authentication method.
PassphraseEnter the passphrase.
This field is available if ‘Public key’ is selected as the authentication method.
PortEnter the port.
CommandsEnter the commands.
Macro support depends on the scope of the script (see Scope above). Custom user macros are supported.
Script type: Telnet
UsernameEnter the username.
PasswordEnter the password.
PortEnter the port.
CommandsEnter the commands.
Macro support depends on the scope of the script (see Scope above). Custom user macros are supported.
Script type: IPMI
CommandEnter the IPMI command.
Macro support depends on the scope of the script (see Scope above). Custom user macros are supported.
DescriptionEnter a description for the script.
Host groupSelect the host group that the script will be available for (or All for all host groups).
User groupSelect the user group that the script will be available to (or All for all user groups).
This field is displayed only if ‘Manual host action’ or ‘Manual event action’ is selected as Scope.
Required host permissionsSelect the permission level for the host group - Read or Write. Only users with the required permission level will have access to executing the script.
This field is displayed only if ‘Manual host action’ or ‘Manual event action’ is selected as Scope.
Enable confirmationMark the checkbox to display a confirmation message before executing the script. This feature might be especially useful with potentially dangerous operations (like a reboot script) or ones that might take a long time.
This option is displayed only if ‘Manual host action’ or ‘Manual event action’ is selected as Scope.
Confirmation textEnter a custom confirmation text for the confirmation popup enabled with the checkbox above (for example, Remote system will be rebooted. Are you sure?). To see how the text will look like, click on Test confirmation next to the field.
{HOST.} and {USER.*} macros are supported. Custom user macros are supported.
Note: the macros will not be expanded when testing the confirmation message.
This field is displayed only if ‘Manual host action’ or ‘Manual event action’ is selected as Scope.

Script execution and result

Scripts run by Zabbix server are executed by the order described in Command execution section including exit code checking. The script result will be displayed in a pop-up window that will appear after the script is run.

Note: The return value of the script is standard output together with standard error.

See an example of a script and the result window below:

  1. uname -v
  2. /tmp/non_existing_script.sh
  3. echo "This script was started by {USER.USERNAME}"

8 Scripts - 图4

The script result does not display the script itself.

Script timeout

Zabbix agent

You may encounter a situation when a timeout occurs while executing a script.

See an example of a script running on Zabbix agent and the result window below:

  1. sleep 5
  2. df -h

8 Scripts - 图5

The error message, in this case, is the following:

  1. Timeout while executing a shell script.

In order to avoid such a situation, it is advised to optimize the script itself (instead of adjusting Timeout parameter to a corresponding value (in our case, > ‘5’) by modifying the Zabbix agent configuration and Zabbix server configuration).

In case still the Timeout parameter is changed in Zabbix agent configuration following error message appears:

  1. Get value from agent failed: ZBX_TCP_READ() timed out.

It means that modification was made in Zabbix agent configuration and it is required to modify Timeout setting also in Zabbix server configuration.

Zabbix server/proxy

See an example of a script running on Zabbix server and the result window below:

  1. sleep 11
  2. df -h

8 Scripts - 图6

It is also advised to optimize the script itself (instead of adjusting TrapperTimeout parameter to a corresponding value (in our case, > ‘11’) by modifying the Zabbix server configuration).