Table of Contents
3 Scripts
Overview
In the Alerts → 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:
- For remote commands executed on Zabbix agent:
- adding an AllowKey=system.run[<command>,*] parameter for each allowed command in agent configuration, * stands for wait and nowait mode;
- For remote commands executed on Zabbix proxy:
- Warning: It is not required to enable remote commands on Zabbix proxy if remote commands are executed on Zabbix agent that is monitored by Zabbix proxy. If, however, it is required to execute remote commands on Zabbix proxy, set EnableRemoteCommands parameter to '1' in the proxy configuration.
Global script execution on Zabbix server can be disabled by setting EnableGlobalScripts=0 in server configuration. For new installations, since Zabbix 7.0, global script execution on Zabbix server is disabled by default.
A listing of existing scripts with their details is displayed.
Displayed data:
| Column | Description |
|---|---|
| Name | Name of the script. Clicking on the script name opens the script configuration form. |
| Scope | Scope of the script - action operation, manual host action or manual event action. This setting determines where the script is available. |
| Used in actions | Actions where the script is used are displayed. |
| Type | Script type is displayed - URL, Webhook, Script, SSH, Telnet or IPMI command. |
| Execute on | It is displayed whether the script will be executed on Zabbix agent, Zabbix proxy or server, or Zabbix server only. |
| Commands | All commands to be executed within the script are displayed. |
| User group | The user group that the script is available to is displayed (or All for all user groups). |
| Host group | The host group that the script is available for is displayed (or All for all host groups). |
| Host access | The 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.
Configuring a global script
Script attributes:
| Parameter | Description | |
|---|---|---|
| Name | Unique name of the script. E.g. Clear /tmp filesystem |
|
| Scope | Scope 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 Alerts → Actions. 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. A {MANUALINPUT} macro allows to specify manual input at script execution time. It is supported for manual host action and manual event action scripts. To find out which other 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 path | The 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. |
|
| Type | Click the respective button to select script type: URL, Webhook, Script, SSH, Telnet or IPMI command. The type URL is available only when 'Manual host action' or 'Manual event action' is selected as Scope. |
|
| Script type: URL | ||
| URL | Specify the URL for quick access from the host menu or event menu. Macros and custom user macros are supported. Macro support depends on the scope of the script (see Scope above). Use the {MANUALINPUT} macro in this field to be able to specify manual input at script execution time, for example: http://{MANUALINPUT}/zabbix/zabbix.php?action=dashboard.viewMacro values must not be URL-encoded. |
|
| Open in new window | Determines whether the URL should be opened in a new or the same browser tab. | |
| Script type: Webhook | ||
| Parameters | Specify 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). |
|
| Script | Enter 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. |
|
| Timeout | JavaScript execution timeout (1-60s, default 30s). Time suffixes are supported, e.g. 30s, 1m. |
|
| Script type: Script | ||
| Execute on | Click 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 proxy or server - the script will be executed by Zabbix proxy or server - depending on whether the host is monitored by proxy or server. It will be executed on the proxy if enabled by EnableRemoteCommands. It will be executed on the server if global scripts are enabled by the EnableGlobalScripts server parameter. Zabbix server - the script will be executed by Zabbix server only. This option will not be available if global scripts are disabled by the EnableGlobalScripts server parameter. |
|
| Commands | Enter 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 method | Select authentication method - password or public key. | |
| Username | Enter the username. | |
| Password | Enter the password. This field is available if 'Password' is selected as the authentication method. |
|
| Public key file | Enter the path to the public key file. This field is available if 'Public key' is selected as the authentication method. |
|
| Private key file | Enter the path to the private key file. This field is available if 'Public key' is selected as the authentication method. |
|
| Passphrase | Enter the passphrase. This field is available if 'Public key' is selected as the authentication method. |
|
| Port | Enter the port. | |
| Commands | Enter the commands. Macro support depends on the scope of the script (see Scope above). Custom user macros are supported. |
|
| Script type: Telnet | ||
| Username | Enter the username. | |
| Password | Enter the password. | |
| Port | Enter the port. | |
| Commands | Enter the commands. Macro support depends on the scope of the script (see Scope above). Custom user macros are supported. |
|
| Script type: IPMI | ||
| Command | Enter the IPMI command. Macro support depends on the scope of the script (see Scope above). Custom user macros are supported. |
|
| Description | Enter a description for the script. | |
| Host group | Select the host group that the script will be available for (or All for all host groups). | |
| User group | Select 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 permissions | Select 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. |
|
| Advanced configuration | Click on the Advanced configuration label to display advanced configuration options. This field is displayed only if 'Manual host action' or 'Manual event action' is selected as Scope. |
|
Advanced configuration
Advanced configuration options are available in a collapsible Advanced configuration section:
| Parameter | Description |
|---|---|
| Enable user input | Mark the checkbox to enable manual user input before executing the script. Manual user input will replace the {MANUALINPUT} macro value in the script. See also: Manual user input. |
| Input prompt | Enter custom text prompting for custom user input. This text will be displayed above the input field in the Manual input popup. To see a preview of the Manual input popup, click on Test user input. The preview also allows to test if the input string complies with the input validation rule (see parameters below). Macro and user macro support depends on the scope of the script (see Scope in general script configuration parameters). |
| Input type | Select the manual input type: String - single string; Dropdown - value is selected from multiple dropdown options. |
| Dropdown options | Enter unique values for the user input dropdown in a comma-delimited list. To include an empty option in the dropdown, add an extra comma at the beginning, middle, or end of the list. This field is displayed only if 'Dropdown' is selected as Input type. |
| Default input string | Enter the default string for user input (or none). This field will be validated against the regular expression provided in the Input validation rule field. The value entered here will be displayed by default in the Manual input popup. This field is displayed only if 'String' is selected as Input type. |
| Input validation rule | Enter a regular expression to validate the user input string. Global regular expressions are supported. This field is displayed only if 'String' is selected as Input type. |
| Enable confirmation | Mark 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. |
| Confirmation text | Enter 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. Macros and custom user macros are supported. Note: the macros will not be expanded when testing the confirmation message. |
If both manual user input and a confirmation message are configured, they will be displayed in consecutive popup windows.
Manual user input
Manual user input allows to supply a custom parameter on each execution of the script. This saves the necessity to create multiple similar user scripts with only a single parameter difference.
For example, you may want to supply a different integer or a different URL address to the script during execution.
To enable manual user input:
- use the {MANUALINPUT} macro in the script (commands, script, script parameter) where required; or in the URL field of URL scripts;
- in advanced script configuration, enable manual user input and configure input options.
With user input enabled, before script execution, a Manual input popup will appear to the user asking to supply a custom value. The supplied value will replace {MANUALINPUT} in the script.
Depending on the configuration, the user will be asked to enter a string value:
Or select the value from a dropdown of pre-determined options:
Manual user input is available only for scripts where the scope is 'Manual host action' or 'Manual event action'.
Script execution and result
Scripts run by Zabbix server are executed in the order described in the Command execution page (including exit code checking). The script result will be displayed in a pop-up window that will appear after the script is run.
The return value of the script is a standard output together with a standard error.
The return value is limited to 16MB (including trailing whitespace that is truncated); database limits also apply. When data has to pass through Zabbix proxy, it must be stored in the database, thus subjecting it to the same database limits.
See an example of a script and the result window below:
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:
The error message, in this case, is the following:
To avoid such situations, it is advised to optimize the script itself (in the example above, "5") instead of adjusting the Timeout parameter in Zabbix agent configuration and Zabbix server configuration. However, for Zabbix agent in active mode, the Timeout parameter in Zabbix server configuration should be at least several seconds longer than the RefreshActiveChecks parameter in Zabbix agent configuration. This ensures that the server has enough time to receive the active check results from the agent. Note that script execution on an active agent is supported since Zabbix agent 7.0.
In case the Timeout parameter has been changed in Zabbix agent configuration, the following error message will appear:
It means that the modification has been made in Zabbix agent configuration, but it is required to modify the Timeout parameter in Zabbix server configuration as well.
Zabbix server/proxy
See an example of a script running on Zabbix server and the result window below:
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).