References > Component Monitor Types > Creating a Windows PowerShell monitor

Windows PowerShell monitor

This component monitor runs a Windows PowerShell script on the SolarWinds SAM server or a remote target node and then processes the script's exit code and text output. To create this monitor, see Create a Windows PowerShell monitor.

The Windows PowerShell Monitor requires Windows PowerShell 2.0. It does not work with Windows PowerShell 1.0.

If you are having trouble using the Windows PowerShell Monitor, see the following KB article for some useful tips:

https://support.solarwinds.com/success_center/Server_%26_Application_Monitor_(SAM)/Problems_using_the_Orion_APM_Windows_PowerShell_Monitor

A maximum of 10 output pairs can be returned. If you exceed the maximum allowed, remove the excess output pairs or they will simply be ignored.

Statistic

The statistic for this component monitor is the Statistic value returned by the script.

Configure Windows Remote Management (WinRM)

You need WinRM configured on the Orion server and remote target server.

  1. Install WinRM on the Orion server and remote target servers.
  2. On the Orion server, open a command prompt as an Administrator.

    Go to the Start menu, right-click the cmd.exe, and select Run as Administrator.

  3. Enter the following in the command prompt:

    winrm quickconfig

    winrm set winrm/config/client @{TrustedHosts="*"}

  4. On the target server, open a command prompt as an Administrator.

    Go to the Start menu, right-click the cmd.exe, and select Run as Administrator.

  5. Enter the following in the command prompt:

    winrm quickconfig

    winrm set winrm/config/client @{TrustedHosts="IP_ADDRESS"}

    For IP_ADDRESS enter the IP address of your Orion server.

Field Descriptions

Description

This field provides a default description of the monitor. You have the ability to override the default description by adding to or replacing the text, which will then be automatically saved. The variable to access this field is ${UserDescription}.

Enable Component

Determines whether the component is enabled. Disabling the component leaves it in the application in a deactivated state not influencing either SolarWinds SAM application availability or status.

Credential for Monitoring

Select a Windows credential that is both a user who can log on to the SolarWinds SAM server, and has sufficient rights on the target node to do whatever the script needs to do. For example, if the script does something with WMI, the credentials also need WMI rights on the target node. If the credential you need is not already present in the credentials list, use the Quick Credentials section to add a new credential.

The PowerShell monitor handles requests from PowerShell for the credentials to run the script and resolves them using the selected Credential for Monitoring. However some PowerShell commands used in scripts require the use of the ${CREDENTIAL} variable. See the note in the Script Body section below regarding the use of the ${CREDENTIAL} variable.

Execution Mode

This field allows you to specify where to run the PowerShell script:

Count Statistic as Difference

Changes the statistic to be the difference in query values between polling cycles.

Run the script under specified account

Select this option to enable impersonation with the component's credentials. (This works only in local script execution mode.)

  • Local Host can run scripts only locally, that is, on the SolarWinds SAM server. This is the default value.
  • Remote Host can execute scripts remotely (on the selected target node) using the Windows Remote Management (WRM) system component. WRM should be configured separately to get it working with the Windows PowerShell monitor.
  • 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

This field allows you to specify the PowerShell script you want to run.

Use the ${CREDENTIAL} variable in the script where the credentials are required, as shown in the following 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.

Script Arguments

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

User Notes

This field allows you to add notes for easy reference. You can access this field by using the variable, ${UserNotes}.

Create a Windows PowerShell monitor

With this, you can create a monitor that runs a Windows PowerShell script to monitor specific performance information for troubleshooting a Windows process that may be having issues.

A maximum of 10 output pairs can be returned. If you exceed the maximum allowed, remove the excess output pairs or they will simply be ignored. You may need to log in with an administrator account to perform this action.

What needs to be monitored

The process you want to monitor is lsass.exe, which enforces security on the system for users who are logging on, changing passwords, and so forth. In particular, you want to monitor the average number of read operations performed to check for spikes.

You decide to use the Windows PowerShell monitor to run a PowerShell script that uses the Get-WmiObject call to measure the average ReadOperationCount for the lsass.exe process and monitor its value.

  1. On the Web Console, click Settings > All Settings > SAM Settings > Create a New Template
  2. Name the template, for example, Lsass.exe PowerShell Monitor.
  3. Click Add Component Monitor, then expand the Custom Component Monitors group, and then select Windows PowerShell Monitor and click Add.
  4. Select the Credential for Monitoring with appropriate permissions to run the script on the SolarWinds SAM server, and that also has appropriate permissions to do whatever else the script requires (in this case, to get the average number of read operations performed on the target node).
  5. Select the Execution Mode to use:
    • Local Host can run scripts only locally, that is, on the SolarWinds SAM server.
    • Remote Host can execute scripts remotely (on the remote target node to which the Windows PowerShell monitor is assigned) using the Windows Remote Management (WRM) system component. WRM should be configured separately to get it working with the Windows PowerShell monitor.
  6. Copy the following PowerShell script, which uses the Get-WmiObject call to measure the average ReadOperationCount for the lsass.exe process, into the Script Body field:
    $avg = Get-WmiObject win32_process -ComputerName '${IP}' -Credential '${CREDENTIAL}' | Where-Object {$_.Name -eq "lsass.exe" } | Measure-Object -property ReadOperationCount -Average; Write-Host 'Statistic: ' $avg.Averageexit(0)

    The PowerShell code does the following:

    1. Reads the average ReadOperationCount information for the process lsass.exe from the computer whose IP address is specified by the variable ${IP} using the credential specified by the variable ${CREDENTIAL}.

      The user name from the Credential for Monitoring that is specified is stored automatically in the ${CREDENTIAL} variable by the monitor. Do not add the ${CREDENTIAL} variable in the Script Arguments field. When the script is run by PowerShell, it prompts for a password. The monitor automatically provides the password from the Credential for Monitoring.

    2. Writes the statistic information gathered by the script.
    3. Exits the script.

      The script does not perform error checking.

  7. Enter the following Script Arguments:

    Use the token ${IP} and the IP address will be filled in with the IP address of the target node. You can then access the value in the script body using the variable ${IP}.

    For example, if you type ${IP} for Script Arguments the PowerShell script will be able to access the IP address for the target node using the variable ${IP} in the script body.

  8. Select Run the script under specified account to enable impersonation with the component's credentials. This works only in local script execution mode.
  9. Select Count Statistic as Difference to change the statistic to be the difference in query values between polling cycles.
  10. Change the Statistic Warning Threshold to, greater than 800.
  11. Change the Statistic Critical Threshold to, greater than 1000.
  12. Click Set test node. Browse the tree view, select the desired target node for the PowerShell script, and then click Select.
  13. Click Test, and then click Submit.
  14. Click All in the Select tag to filter by list, and then locate the Lsass.exe PowerShell Monitor.
  15. Select Lsass.exe PowerShell Monitor and then click Assign to Node.
  16. Expand the tree view and select the target node, and then click Next.
  17. Select Inherit credentials from template, and then click Test to confirm the credentials and component monitor against the test node.
  18. Click Assign Application Monitors and then click Done.

Report status through exit codes

Scripts must report their status by exiting with the appropriate exit code. The exit code is used to report the status of the monitor, which is seen by the user through the interface.

To correctly create this component monitor, you must first return an exit code which results in an Up (0), Warning (2), or Critical (3) status. When one of these exit codes is received the appropriate dynamic evidence table structure is created and all further exit codes are handled correctly. If the component only returns Down (1) or Unknown (4) on first use, the appropriate dynamic evidence table structure is not created appropriately.

Exit Code Service State

0

Up

1

Down

2

Warning

3 Critical

Any other value

Unknown, for example 4

Troubleshooting the Lsass.exe PowerShell Monitor

Verify that you are entering the user name and password of an administrator-level account. If you think you have entered an incorrect credential, correct the mistake and then retest.

Make sure that the RPC server is available and that the Windows PowerShell execution policy is not set to Restricted (the default setting). You can check the execution policy by entering the following command at the PowerShell command prompt: Get-ExecutionPolicy

If you are having trouble using the Windows PowerShell Monitor, see the following KB article for some useful tips:

https://support.solarwinds.com/success_center/Server_%26_Application_Monitor_(SAM)/Problems_using_the_Orion_APM_Windows_PowerShell_Monitor