Create a Windows PowerShell monitor

Before creating a PowerShell monitor, review Using PowerShell in SAM to learn about PowerShell requirements, security considerations, installation, and enabling remote access with the Windows Remote Management (WinRM) service.

This component monitor runs a Windows PowerShell script on the Orion server or a remote target node to collect metrics as follows:

  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. 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. You may need an administrator account to perform this action.

This section includes field descriptions and a Windows PowerShell monitor example. Before creating a PowerShell monitor, review Using PowerShell in SAM to learn about PowerShell requirements, security considerations, installation, and enabling remote access with the Windows Remote Management (WinRM) service.

Your organization should internally review and assess to what extent PowerShell scripts will be incorporated into your environment. See PowerShell security considerations for details.

Windows PowerShell monitor 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. 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

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. To learn more, 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 works only if Local Host is selected as the Execution Mode.) See also How SAM handles credentials based on Execution Mode.

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.

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;

The ${CREDENTIAL} variable provides the user name and password specified in the Credential for Monitoring field when prompted by the script so there is no need to include that variable in the Script Argument — credentials are provided automatically.

To pass a custom property to a script, using ${Node.Custom.XXX}, where xxx is the name of the custom property.

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.

User Notes

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

How SAM handles credentials based on Execution Mode

The following table describes how SAM handles credentials for a PowerShell script based on:

  • The selected Execution Mode: Local Host or Remote Host
  • If the "Run the script under specified account" option is enabled.
Mode "Run the script under specified account" option Result
Local Host Disabled

The Credential for Monitoring is not used. Instead, the PowerShell script uses the same Local Admin account as the Orion Platform to run the script via an Orion Job Engine V2 service.

This method grants the script the same unlimited access privileges as other Orion services, which presents high risk from a security perspective.

SolarWinds recommends using a dedicated Windows account with minimal privileges for PowerShell monitors, especially for scripts executed on the Orion server that performs as the main polling engine.

Local Host Enabled SAM uses the Credential for Monitoring to run PowerShell scripts on the Orion server.
Remote Host N/A

The script connects via SSH to run the script on the target server. SAM uses the Credential for Monitoring to run the PowerShell script on the target server.

Make sure that:

To increase security, SolarWinds recommends configuring WinRM to use HTTPS. See PowerShell Remoting Security Considerations (© 2018 Microsoft Corp., available at https://docs.microsoft.com; link obtained on October 19, 2018).

Windows PowerShell monitor example

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.

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

To use the Windows PowerShell monitor to run a PowerShell script with a Get-WmiObject call to measure the average ReadOperationCount for the lsass.exe process and monitor its value:

  1. In the Orion 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, expand the Custom Component Monitors group, select Windows PowerShell Monitor, and click Add.
  4. Select the Credential for Monitoring with appropriate permissions to run the script on the Orion 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 Orion server.
    • Remote Host can execute scripts remotely (on the remote target node to which the Windows PowerShell monitor is assigned) using the WinRM service, which must be properly configured on the main Orion server and target servers to run PowerShell commands remotely. See Enable remote access for PowerShell with WinRM.
  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.

      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. See Report status through exit codes.

      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. Click Set test node. Browse the tree view, select the desired target node for the PowerShell script, and then click Select.
  11. Change the Statistic Warning Threshold to, greater than 800.
  12. Change the Statistic Critical Threshold to, greater than 1000.
  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.