Documentation forServer & Application Monitor

Windows PowerShell Monitor

You can use this predefined component monitor to run a Windows PowerShell script on the Orion server or a remote target node to collect metrics, as summarized here:

  1. The monitor checks if the execution mode is Local Host or Remote Host.

    If Local Host, the script executes using the script arguments on the Orion server.

    If Remote Host, the script connects via SSH connection to run the script on the target server.

  2. The script executes and collects metrics from the target server using entered credentials.
  3. The script reports is status to SAM by finishing with an exit code to indicate if the monitor is in an Up (0), Warning (2), or Critical (3) status.
  4. SAM parses the text output, saves data, and reports values using output formats from the component monitor.

This monitor can return up to ten pairs — 10 statistic values and 10 optional messages. If you exceed the maximum allowed, remove the excess output pairs or they will simply be ignored. For details, see Use script component monitors in SAM.

See these SAM Custom Template Guide topics to learn more about PowerShell scripts:

See also Use PowerShell in SAM.

Field descriptions

Description

Add or replace text to override the default description of the monitor. The variable to access this field is ${UserDescription}.

Enable Component

Determines if the component is enabled. Disabling the component leaves it in a deactivated state that does not influence either SolarWinds SAM application availability or status.

Credential for Monitoring

Select a Windows credential with rights to log into the Orion server plus sufficient rights on the target node to do whatever the script needs to do. The basic PowerShell monitor resolves credential requests to run a script. However, some PowerShell commands require the use of the ${CREDENTIAL} variable, as described in Script Body section.

For example, if a script does something with WMI, the credentials also need WMI rights on the target node. Some PowerShell commands require the use of the ${CREDENTIAL} variable; see Script Body for details.

To increase security, SolarWinds recommends using a dedicated Windows account with minimal privileges for PowerShell monitors, especially for scripts executed on the main polling engine (that is, the Orion server). For details, see How SAM handles credentials based on Execution Mode.

Execution Mode

Specify where to run the PowerShell script.

Leave this value set to the default value, Local Host, to run scripts locally from the Orion server. Make sure that WinRM is properly configured on the Orion server so scripts can run on remote target servers.

If you select Local Host but do not enable the "Run the script under specified account" option, the script has the same unlimited access privileges as other Orion services, which presents high risk from a security perspective. For details, see How SAM handles credentials based on Execution Mode.

Select Remote Host to execute scripts on the selected target node. The following options are available for Remote Host mode:

  • Use HTTPS Protocol: The default value is HTTP. Select HTTPS if you want the monitor to send and receive encrypted Web Services (WS)-Management protocol requests and responses for increased security.
  • URL Prefix: Specify the URL prefix on which to accept HTTP or HTTPS requests. The default is wsman.
  • Port Number: Specify the TCP port used to listen for traffic. For WinRM 1.1 and earlier, the default port is 80. For WinRM 2.0, the default port is 5985.

Count Statistic as Difference

Enable this option to include the difference between two polling intervals in script output.

Run the script under specified account

Select this option to enable impersonation with the component's credentials.

    This option is only available if the Execution Mode is set to the Local Host.

  • Local Host can run scripts only locally, that is, on the Orion server. This is the default value.
  • Remote Host can execute scripts remotely (on the selected target node)if WinRM is properly configured on the Orion server.
  • If Remote Host is selected, the following options are available:
    • Use HTTPS Protocol - if checked, specifies that the secure HTTPS protocol should be used to send and receive WS-Management protocol requests and responses. Otherwise the HTTP protocol is used.
    • URL Prefix - specifies a URL prefix on which to accept HTTP or HTTPS requests. The default is wsman.
    • Port Number - specifies the TCP port for which this listener is created. For WinRM 1.1 and earlier, the default HTTP port is 80. For WinRM 2.0, the default HTTP port is 5985.

Script Body

Specify the PowerShell script you want to run.

SolarWinds recommends that you always review the Script Body to check for malicious code, Custom scripts you create or download from THWACK are not part of the SolarWinds software purchased from SolarWinds. Your organization should internally review and assess to what extent PowerShell scripts will be incorporated into your environment. You elect to utilize custom scripts at your own risk, and you will be solely responsible for the incorporation of the same, if any. For details, see Use PowerShell in SAM.


SolarWinds does not recommend the use of Clear-Host methods in PowerShell scripts. Click here for details.

If a script includes PowerShell commands that require valid credentials for the Orion server and target servers (such as Get-WmiObject), use the ${CREDENTIAL} variable, as shown in this example:

$avg = Get-WmiObject win32_process -ComputerName '${IP}' -Credential '${CREDENTIAL}' | Where-Object {$_.Name -eq "lsass.exe"} | Measure-Object -property ReadOperationCount -Average;

Some PowerShell commands (such as Get-WmiObject as shown in the example above) require the ${CREDENTIAL} variable. The user name from the specified Credential for Monitoring is stored automatically in the ${CREDENTIAL} variable for you by the monitor. As a result, the ${CREDENTIAL} variable should not be placed in the Script Arguments field, since it is set automatically. When the script is run by PowerShell, it prompts for a password. The monitor automatically provides the password from the specified Credential for Monitoring.

Custom Properties can be passed by using the following format: ${Node.Custom.XXX} where xxx is the name of the custom property.

Scripts must report the status of the component monitor by exiting with the appropriate exit code, which determines what appears in the Orion Web Console. See Report status through exit codes

Script Arguments

Specify arguments to pass to the script. You may include the variable ${IP}, which is replaced by the IP address of the target node. Do not include variables that are stored automatically, such as the ${CREDENTIAL} variable.

Enter arguments in a comma-separated list.

For example: ${Component.ID},${Node.Caption},${IP},Dell.ChangeAuditor,Coordinator

User Notes

Add notes for reference, accessible by using the variable, ${UserNotes}.