WsManShellMonitor
Use this monitor to run a command on a Windows host through WinRS (the Windows Remote Shell protocol carried over WS-Management) and mark the service as up when its output matches an optional banner and, if configured, it exits with the expected code.
Connection details, credentials, and Kerberos settings for the target come from wsman-config.xml; see WS-Management agent configuration and WS-Management Kerberos authentication and message encryption.
The command runs as the user configured in wsman-config.xml, in a fresh short-lived shell that is deleted when the command completes.
Give that account only the rights it needs: membership in the Remote Management Users group on the target is enough to run commands.
The command and args values are handed to the Windows command interpreter exactly as written, and cmd.exe treats characters such as &, |, and > as command separators.
For that reason these two parameters do not support placeholder substitution: substituting a value that someone else can influence, such as a node label, would let that person run commands on the host.
Metadata expressions are still expanded by the poller for every parameter, so avoid referencing node, interface, or asset metadata in command or args unless you control who can edit it.
|
Configuration and use
| Parameter | Description | Default |
|---|---|---|
Required |
||
command |
The executable to run, for example |
n/a |
Optional |
||
args |
Arguments passed to the command.
The value is handed to the Windows host verbatim, so it is the rest of the command line exactly as you would type it there, using Windows quoting rules.
Write double quotes as |
none |
banner {} |
Text that must appear in the command’s standard output for the service to be considered up.
If the value starts with |
|
exit-code |
Exit code the command must return, for example |
|
no-profile |
Skip loading the user profile when creating the shell. |
|
codepage |
Windows code page number the remote shell uses to encode the command’s output, which the monitor decodes with the same code page.
The default, |
|
working-directory |
Working directory for the command. |
Shell default |
timeout |
Time in milliseconds that bounds each step of the poll: connecting to the host, creating the shell, waiting for the command to complete, and deleting the shell.
No single step may take longer than this, so a poll against an unresponsive host ends after a small multiple of the value.
When the command itself exceeds it, the command is terminated and the poll fails.
Falls back to the |
|
retry |
Number of retries after a failed attempt.
Falls back to the |
|
{} indicates the parameter supports placeholder substitution.
This monitor implements the Common Configuration Parameters.
Examples
Check that the Windows Time service is running:
<service name="W32Time" interval="300000" user-defined="true" status="on">
<parameter key="command" value="sc"/>
<parameter key="args" value="query w32time"/>
<parameter key="banner" value="~.*STATE\s*:\s*4\s+RUNNING.*"/>
</service>
<monitor service="W32Time" class-name="org.opennms.netmgt.poller.monitors.WsManShellMonitor" />Run a PowerShell command and rely on its exit code alone:
<service name="Cluster-Health" interval="300000" user-defined="true" status="on">
<parameter key="command" value="powershell"/>
<parameter key="args" value="-NoProfile -NonInteractive -Command "if ((Get-ClusterNode -Name $env:COMPUTERNAME).State -ne 'Up') { exit 1 }""/>
<parameter key="exit-code" value="0"/>
<parameter key="timeout" value="5000"/>
</service>
<monitor service="Cluster-Health" class-name="org.opennms.netmgt.poller.monitors.WsManShellMonitor" />