Documentation forServer & Application Monitor

How Execution Mode impacts PowerShell scripts in SAM

Whether using the predefined Windows PowerShell Monitor on its own or within a template, you can configure the Execution Mode to control how and where PowerShell scripts run -- either locally on the Orion server, or remotely on target servers, with or without required credentials.

Leave Execution Mode set to the default value, Local Host, to run scripts locally from the Orion server. The script will run as a service under the local system account unless you also enable the "Run the script under specified account" option. If you need to run specific non-default cmdlets for the target server, install the needed cmdlets on the Orion server.

Set Execution Mode to Remote Host to execute scripts on the selected target node. SAM will create a remote session via WinRM on the target server, copy the script to the target server, and then run the script there.

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

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 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.

Run scripts under a specified account

SAM allows you to run PowerShell scripts using the local impersonation of a specified user account (for example, an account with domain privileges). By enabling the "Run the script under specified account" option when using Local Host as the Execution Mode, you can control what the script can and cannot do via the permissions assigned to the account you specific in the Credential for Monitoring field.

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.
Execution 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 the Orion Job Engine V2 service.

This mode 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 typically functions 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).

To troubleshoot Local Host Execution Mode:

  • Make sure the file exists in the path specified in the script.
  • Verify that the user account specified in the credentials section of the component monitor is a local administrator with sufficient permissions to execute the PowerShell script. Try logging into the server using those credentials and running the script manually.
  • SAM executes PowerShell scripts using 32-bit PowerShell by default. If a PowerShell script runs fine in the Orion Web Console but causes errors in logs, try changing the "Platform for polling jobs" option from x86 to x64. See PowerShell Script Monitor Running in Polling Job on x86/x64 Platform in THWACK.

Example

The following script can be used in the Orion Web Console, or in the PowerShell console. It returns 0 as the exit code and the Hostname of the Orion server (Local Host) or the Hostname of the target machine (Remote Host).

In the PowerShell console, the script returns the local machine Hostname. If the script cannot get the hostname, it returns 1 as the exit code and a “Host not found” message.

$stat = $env:computername;
if ($stat -ne $null)
{
Write-Host "Statistic: 0";
Write-Host "Message: $stat";
}
else
{
Write-Host "Statistic: 1";
Write-Host "Message: Host not found";
}

Tips

To save a script as a PowerShell (ps1) file in Notepad, save it as Get-Date.ps1, and then rename the file from *.txt to *.ps1.)

To open the PowerShell console:

  • For Windows x64:
    • For x64, navigate to Start > Accessories > Windows PowerShell > Windows PowerShell
    • For x86, navigate to Start > Accessories > Windows PowerShell > Windows PowerShell (x86)
  • For Windows x86:
    • Navigate to Start > Accessories > Windows PowerShell > Windows PowerShell

To run this script via remote execution, use this command:

invoke-command –ComputerName SOME_PC -Credential SOME_PC\SOME_USER -ScriptBlock { Get-Date }

To run this script via local execution:

  1. Name the file Get-Date.ps1 .
  2. Double-click the ps1 file.