PowerShell

PowerShell provides remote access of the monitored device and the ability to leverage PowerShell modules and .NET libraries installed there.

Prerequisites

WhatsUp Gold uses a 32-bit (in other words, "x86") PowerShell engine. Only 32-bit PowerShell snap-ins are supported and 64-bit only snap-ins will not function properly. Snap-ins that work on both 32-bit and 64-bit operating systems are configured for 64-bit systems by default and must be manually configured for 32-bit PowerShell engine to function properly with WhatsUp Gold.

Remote Connection Requirements

Ensure the following are in place for enabling the WhatsUp Gold machine to connect using PowerShell to the destination (polled) device.

Windows Credentials. Credentials must be used explicitly using the methods and properties provided by the Context object. HTTPS must be used as transport or polled device must be in TrustedHosts list of the machine where WhatsUp Gold is running.
Domain and hostname. If you use user's default credentials. To use IP address alone, you will need to specify credentials at PowerShell/WinRM login. (For more info see this WinRM troubleshooting help.)
Enable-PSRemoting. Enable PowerShell remoting on destination (polled) device. For more information see link to MSDN documentation provided.

Monitor Configuration

Configuration fields for this active monitor include:

Name. Enter a unique name for the active monitor. This name displays in the Monitor Library.
Description. (Optional) Enter additional information about the monitor. This description displays next to the monitor name in the Monitor Library.
Timeout (Seconds). Enter the length of time WhatsUp Gold attempts to connect to the selected device.
Run under device credentials. Enable this check box to execute the script using the Windows credentials for the device.
Script text. Enter your active monitor code.

Available Monitor Objects and Attributes

PowerShell active monitor scripts have two instantiated session objects available.

Context. Implementation of the IScriptContext interface. This object provides access to runtime variables and also provides mechanism for returning results to the client. A few useful methods are listed below:
- object GetProperty(string propertyName) - allows retrieval of context variable values by name.
- object SetProperty (string propertyName, string propertyValue ) - allows specification of context variable values by name.
- void SetResult(int resultCode, ResultsString) - allows the script to set a value to indicate success, usually 0 = success and 1 = failure.
Logger. Implementation of the ILog interface. This object provides the same methods available to C# applications. A few useful methods are listed below:
- void Error(string message) - Creates an error-specific log entry that includes the message.
- void Information(string message) - Creates an information-specific log entry that includes the message.
- void WriteLine(string message) - Creates a generic log entry that includes the message.

Getting or Setting Properties for a Context Object

You can fetch values for context properties using PowerShell active monitor scripts.

Syntax

Property-Value = Context.GetProperty("Property-Name")

Context.SetProperty("Property-Name","Property-Value")

Example

$DeviceIpAddress = $Context.GetProperty("Address")

$Context.SetProperty("Timeout", "180")

Setting Result String and Monitor Status Indicator

The result string you set will be added to the description in the monitor's status change. The status flag you set (0, 1) up/down determines the indicator shown in the State Change Timeline.

# After a successful Get of the deviceIP, Set as result and set success flag ...

$Context.SetResult(0, "Device IP address is: " + $DeviceIpAddress)

Context Object Properties

The following properties can be accessed from the connection object created when running PowerShell.

Property Name	Description
DeviceID	WhatsUp Gold Device identification string.
Address	IP address.
Timeout	Timeout value for this session. (In seconds)

Context Object Credential Properties

The following credential properties can be set for the PowerShell. These are useful when you need to connect to other services, platforms, or applications after the initial PowerShell connection is made using the active monitor.

Property Name	Description
CredWindows:DomainAndUserid	Domain and user for the Windows Credential.
CredWindows:Password	Set the Windows Password.
CredSnmpV1:ReadCommunity	SNMPv1 Read Community string.
CredSnmpV1:WriteCommunity	SNMPv1 Write Community string.
CredSnmpV2:ReadCommunity	SNMPv2 Read Community string.
CredSnmpV2:WriteCommunity	SNMPv2 Write Community string.
CredSnmpV3:AuthPassword	SNMPv3 password.
CredSnmpV3:AuthProtocol(integer-value)	SNMPv3 authentication protocol. values: 1 = None, 2 = MD5, 3 = SHA
CredSnmpV3:EncryptProtocol(integer-value)	Integer value can be one of the following: 1 = None 2 = DES56 3 = AES128 4 = AES192 5 = AES256 6 = THREEDES
CredSnmpV3:EncryptPassword	SNMPv3 Encrypted password.
CredSnmpV3:Username	SNMPv3 user.
CredSnmpV3:Context	SNMPv3 Context.
CredADO:Password	ADO password.
CredADO:Username	ADO username.
CredSSH:Username	SSH username.
CredSSH:Password	SSH password.
CredSSH:EnablePassword	Enable password flag.
CredSSH:Port	SSH port if other than default.
CredSSH:Timeout	Timeout for SSH session.
CredVMware:Username	VMware username.
CredVMware:Password	VMware password.
CredTelnet:Timeout	Time out value for telnet connection.
CredTelnet:Port	Telnet port (if other than default).
CredTelnet:Username	Telnet username.
CredTelnet:Password	Telnet password.
CredJMX:Username	Java Management Extensions username.
CredJMX:Password	Java Management Extensions password.
CredSMIS:Timeout	Storage Management timeout.
CredSMIS:Port	Storage Management port.
CredSMIS:Protocol	Storage Management protocol.
CredSMIS:Username	Storage Management username.
CredSMIS:Password	Storage Management Password.
CredAWS:AccessKeyID	Amazon Web Services account ID.
CredAWS:SecureAccessKey	Amazon Web Services access key.
CredAzure:TenantID	Azure subscription ID.
CredAzure:ClientID	Azure Client account ID.
CredAzure:SecureKey	Azure account key.

Example: Check if Service is Running

Create a PowerShell active monitor that shows status of up only if DNS client is running using stored credentials.

# Device to Poll

$DeviceIpAddress = $Context.GetProperty("Address")

# Set the computer name directly, or...

# $CompName = mydb02.corpnet.example.com (for example)

# ...get it using WMI...

$WmiRes = Invoke-Command -ComputerName $DeviceIpAddress -ScriptBlock { Get-WmiObject Win32_Computersystem }

$CompName = $WMIRes.PSComputerName

# Run command on remote device

$PsResult = Invoke-Command -ComputerName $DeviceName -ScriptBlock { Get-Service | where { $_.Name -match "Dnscache" } }

# Check for condition of 'running'

if ($PsResult.Status -match 'Running') {

$RespondingMessage = "Process '" + $processName + "' running on " + $DeviceIpAddress + " is responding."

$Context.SetResult(0, $RespondingMessage )

} else {

$NotRunningMessage = "Process '" + $processName + "' running on " + $DeviceIpAddress + " is not responding."

$Context.SetResult(1, $NotRunningMessage )

}