Skip to content

Zabbix UserParameter with PowerShell on Windows

UserParameter allows Zabbix to execute custom scripts on an agent, enabling monitoring beyond standard Metrics. On Windows, this is commonly implemented using PowerShell.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

Configuration Requirements

To execute PowerShell scripts via Zabbix UserParameter, specific permissions and configuration flags must be set in the zabbix_agentd.conf file or within the PowerShell environment.

PowerShell Execution Policy

By default, Windows may prevent script execution. To resolve this, the PowerShell execution policy must be set to allow scripts, typically using RemoteSigned.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

Set-ExecutionPolicy RemoteSigned
^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

Agent Configuration Flags

The Zabbix agent configuration file requires several parameters to be enabled to support the execution of custom scripts safely:

  • EnableRemoteCommands: Must be set to 1 to allow the Zabbix server to trigger remote command execution on the agent.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]
  • UnsafeUserParameters: Must be set to 1.^[600-developer__operation-maintenance__zabbix__zabbix-key.md] This allows special characters (such as backslashes, quotes, or pipes) to be passed as arguments to the user-defined script, which is often necessary for Windows paths or PowerShell arguments.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]
  • Timeout: The default timeout (often 3 seconds) might be insufficient for PowerShell scripts that query system state (like Java processes). It is recommended to increase this value (e.g., Timeout=30) in the configuration file to prevent ZBX_NOTSUPPORTED: Timeout while executing a shell script errors.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

Defining the UserParameter

The UserParameter directive links a specific key used by Zabbix to a command executed on the host.

Syntax

The general format is UserParameter=<key>,<shell command>.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

PowerShell Implementation

To call a PowerShell script (e.g., robot.ps1) with arguments, the configuration must point to the powershell.exe executable and use the -File parameter.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

Example Configuration: 

UserParameter=mypay.robot[*],C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -File C:\Zabbix\robot.ps1 $1 $2 $3 $4 $5 $6 $7 $8 $9
^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

In this example, [*] indicates that the key accepts arguments, which are then passed to the script as $1, $2, etc.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

Example Use Case: Monitoring JVM Processes

A common application of this method is checking for specific running Java processes (JVMs) based on their command-line arguments or main class.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

The PowerShell script logic generally involves: 1. Retrieving all Java Process IDs using Get-Process -Name java.^[600-developer__operation-maintenance__zabbix__zabbix-key.md] 2. Iterating through each ID. 3. Using Java diagnostic tools like jinfo or jcmd to query the process details (e.g., VM.command_line or system properties).^[600-developer__operation-maintenance__zabbix__zabbix-key.md] 4. Searching the output for a specific string (argument or path) passed as a parameter to the script.^[600-developer__operation-maintenance__zabbix__zabbix-key.md] 5. Returning a standard output value (e.g., 1 for found, 0 for not found) for Zabbix to process.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

Script Logic Example

$arr = $args[0]
$mark = 0
Get-Process -Name java | select -expand id | ForEach {
    $queryCondition = jinfo $_
    $isExist = $queryCondition.split(' ') | Select-String -include string $arr -CaseSensitive 
    if ($isExist.length -gt 0) {
        $mark += 1
    }
}
echo $mark
^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

Verification and Debugging

After configuring the agent and creating the script, the setup can be verified using the zabbix_get utility on the Zabbix server.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

Command: 

/usr/bin/zabbix_get -s <agent_ip> -p 10050 -k "mypay.robot[robot1047]"
^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

This command should return the value calculated by the PowerShell script. If it times out, verify the Timeout setting in the Windows agent configuration file.^[600-developer__operation-maintenance__zabbix__zabbix-key.md]

  • [[Zabbix]]
  • [[PowerShell]]
  • [[Java Monitoring]]

Sources

^[600-developer__operation-maintenance__zabbix__zabbix-key.md]