Get a crash course on Network Monitoring delivered right to your inboxThis free 7-day email course provides a primer to the philosophy, theory, and fundamental concepts involved in IT monitoring. Lessons will explain not only how to perform various monitoring tasks, but why and when you should use them. Sign up now.

PowerShell scripting in SAM custom templates

Table of contents

The SAM Windows PowerShell monitor supports custom PowerShell scripting. You can create multiple instances of this component monitor per template to run custom PowerShell scripts.

This information details the format and usage of PowerShell scripts for SAM, including script arguments and output formats. For detailed information for learning or using the PowerShell programming language, see Microsoft PowerShell resources.

After configuring PowerShell and reviewing the components of a script, create PowerShell scripts using the component monitor per template.

PowerShell support in SAM

SAM requirements support PowerShell 2.0 and higher. To use scripts in templates, install PowerShell on your Orion main poller, all additional polling engines, and all target servers. When installing PowerShell, install 64-bit (x64) or 32-bit (x84) depending on the server OS and application configurations.

To locate a list of out-of-the-box PowerShell script supporting templates, navigate to the Manage Templates page. Click Settings > All Settings > SAM Settings and click Manage Templates. In the search field, enter PowerShell, or browse and click the PowerShell filter. These templates use customized instances of the Windows PowerShell Monitor.

Credentials

PowerShell requires administrator account credentials and permissions on the target server. Without the correct permissions, the script returns an unknown status.

For best results, the OS and PowerShell version should all match. For example, On a 64-bit main poller, polling a 64-bit server, install PowerShell 64-bit.

WinRM installed and configured

You also need Windows Report Management (WinRM) installed on the Orion server and remote target server.

Install WinRM on the Orion server and remote target servers.

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.

Enter the following in the command prompt:

winrm quickconfig

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

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.

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.

How the PowerShell script works

The Windows PowerShell Script Monitor executes the script based on a selection in the monitor to collect metrics:

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.

The script executes and collects metrics from the target server using entered credentials.

SAM parses the text output, saves data, and reports the values using the output formats from the component monitor.

Components of a PowerShell script

SolarWinds recommends writing scripts in the Windows PowerShell Script monitor to verify correct access between the main polling engine, SAM, and the target server(s). You can write and test PowerShell scripts directly on the target server to verify if the code functions. Including and testing the code through the monitor ensures the entered credentials and target server access.

The script in the monitor should include:

PowerShell script code written in the Script Body field with credentials

Specific arguments to pass with the script in the Script Arguments field

Exit codes to report status in the script

Formatted output

You must test the component monitor and script before assigning and using the component monitor within a template as is. Testing the script generates the required database tables for output and verifies output processes.

Script Fields

Script Body field

Use the Script Body field to enter PowerShell script code to run.

Use the ${CREDENTIAL} variable in the script where the credentials are required. For example:

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 their status by exiting with the appropriate exit code. The exit code is used to report the status of the monitor, displayed in the Orion Web Console.

Script Arguments field

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. Enter arguments in a comma-separated list.

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