PowerShell scripting in SAM component monitors

As described in Use PowerShell in SAM, many features, such as AppInsight for IIS, leverage PowerShell to execute commands and gather data from remote, target systems. Several out-of-the-box SAM application monitor templates also use the predefined Windows PowerShell Monitor to gather data.

The ability to create and deploy PowerShell scripts to remote machines within SAM is a powerful advantage for system administrators. With an interactive prompt and scripting environment, PowerShell provides access to the file system on remote computers, along with datastores such as the registry, so you can use it monitor applications that might not otherwise be monitorable.

In addition to this overview, see the following topics in this section:

• Create a Windows PowerShell script monitor in SAM
• How Execution Mode impacts PowerShell scripts in SAM
• Use case: Create a SAM template that uses the Windows PowerShell Monitor to detect possible dictionary attacks

SolarWinds recommends using PowerShell 5.1.

Disclaimer: SolarWinds recommends that you always review scripts 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.

Elements of a PowerShell script

Each PowerShell script should include the following elements:

• Windows credentials that provide access to target servers.
• Specific arguments to pass with the script.
• Exit codes that report the status of the monitor in the SolarWinds Platform Web Console.
• Formatted output.

Avoid using Clear-Host methods in PowerShell scripts. Click here for details.

Here is a summary of what happens when a Windows PowerShell script runs in SAM:

1. The Windows PowerShell Monitor checks if the Execution Mode is set to Local Host or Remote Host.

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

   If Remote Host, the script connects via WS-Management to run the script on the target server.
   

   WinRM must be properly configured on the SolarWinds Platform server and target servers so scripts can run. See Use PowerShell in SAM.

2. The script executes and collects metrics from the target server using entered credentials.
3. The script reports its 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. The 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 be ignored.

Test the component monitor and script before assigning and using the component monitor against nodes. After testing, verify that the script generated the correct database tables for output and/or output processes.