PowerShell scripting in SAM custom templates

PowerShell is a Windows command-line shell and scripting language built on top of the .NET Framework that you can use to create custom scripts for use in SAM templates that support PowerShell scripts, and then assign templates to the main Orion server server or remote target nodes.

The SAM Windows PowerShell monitor supports custom PowerShell scripting and you can create multiple instances of this component monitor for each template. After running a script, the Orion Platform processes the script's exit code and text output to display results in the Orion Web Console.

Please note that custom scripts you create or download from the SolarWinds online IT community, 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.

To learn about PowerShell requirements, important security considerations, installing PowerShell on servers, and enabling remote access for PowerShell, see Use PowerShell in SAM.

Elements of a PowerShell script

SolarWinds recommends writing scripts in the Windows PowerShell Script monitor to verify correct access between the main polling engine, the Orion server, and target server(s). You can write and test PowerShell scripts directly on a target server to verify credentials and target server access.

The script in the monitor should include the following elements:

  • Windows credentials for monitoring that provide access to servers
  • Specific arguments to pass with the script
  • Exit code used to report the status of the monitor in the Orion Web Console.
  • Formatted output

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

Field descriptions

Description

The default description of the monitor that you can override later, if necessary. The variable to access this field is ${UserDescription}.

Enable Component

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

Credential for Monitoring

Windows credential for a user account with login privileges for the Orion server and rights to access the target node to perform whatever action a script needs to do. For example, if a script does something with WMI, the credentials require WMI rights on the target node.

The basic PowerShell monitor resolves credential requests to run a script. However some PowerShell commands used in scripts require the use of the ${CREDENTIAL} variable, as described in Script Body section.

Execution Mode

Specify where to run the PowerShell script:

Count Statistic as Difference

Change 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 option works only in local script execution mode.

  • 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) using the Windows Remote Management (WinRM) system component. Configure WRM separately for use with the 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

Enter PowerShell script code to run and include the ${CREDENTIAL} variable if credentials are required, 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 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

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

Display SAM templates that support PowerShell scripts

To display a list SAM templates that support PowerShell scripts:

  1. Navigate to the Manage Templates page.
    1. Click Settings > All Settings > SAM Settings.
    2. Click Manage Templates.
  2. In the search field, type PowerShell, or browse and click the PowerShell filter.

A list of templates that use customized instances of the Windows PowerShell Monitor displays.

PowerShell-based templates created by other customers and SolarWinds employees are posted in the SolarWinds online IT community, THWACK. Please note that SolarWinds does not directly support third-party applications and/or custom scripts.