Configuring Windows PowerShell monitor type

This topic provides information about using TrueSight Operations Management for monitoring using the PowerShell.

TrueSight Operations Management allows the user to maintain a set of scripts on a host where a PATROL Agent is running. As per policy configuration the scripts will run on targeted remote hosts and the output of the execution is consumed by the KM to set value to parameters. Connection to the remote hosts is done based on PowerShell connections.

This topic provides the user with information on how to setup policies for Windows monitor type. To configure monitoring, create a monitoring definition within a policy according to the following fields and attributes:

Monitoring Solution

Version

Monitor Profile

Monitor Type

Scripting

2.0.00

Windows

Windows PowerShell

This monitor type enables you to configure devices, scripts, administration, file based monitoring, and default configuration.

Click to view a short video on how to configure the Windows Monitor profile using PowerShell.

icon-play.png https://youtu.be/yd8Xno0LJbM

Click a tab to view the respective configuration.

Related topics

Configuring-after-installation



Enter the remote device details and configure a script that can be executed on the remote computer.

Field

Description

Click Add button.png button to configure the remote Devices.

Device details

Device name/IP

Enter a host name or an IP address. The name can be short or long. The KM uses this value when setting up the remote PowerShell connection to the targeted device.
You can also enter an alias name. If you have provided an alias name as the device name, you must configure the device IP address by entering the IP
address in the Forced IP Address field. Using an alias and not a real direct name is useful when the user wants to force access to the remote targeted 
device on a non-resolvable name and IP address (for example, when having devices with multiple network adapters).

Input must match ^[0-9a-zA-Z._%:-]+$ regular expression pattern.

Forced IP Address

(Optional) Enter the IP address of the device you want to monitor.

You can leave this field blank if you have provided the real host name or an IP address in the Device name/IP field.

Input must match [^(?:(^((?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?):{1,2}((?:[0-9A-Fa-f]{1,4}(?::
[0-9A-Fa-f]{1,4})*)?)$)|(^(25[0-5]|2[0-4]\d|[0-1]?\d?\d)(\.(25[0-5]|2[0-4]\d|[0-1]?\d?\d)){3}$))]]> regular expression pattern.

Category

Enter a category name to group the devices. A container is created with the category name. Input must not contain <>\/|":*?]] characters. 

Timeout (sec)

Enter the connection timeout period in seconds. A targeted device might not be available or might be very slow to respond. In such scenarios, ensure that 
the KM will not wait for it and just stop responding. This value is used in such scenarios. You can define the maximum time to allow for a remote PowerShell connection 
establishment. If the time elapses, the KM understands that there is a failure in ability to monitor using the script. If the network or targeted host is slow, 
you can still get the KM to work properly by allowing a longer timeout period.

The minimum value is 1 second and the maximum value is 600 seconds. Default value is 30 seconds.

Poll interval (sec)

The PATROL Agent maintains a set of remote PowerShell connections to all targeted hosts. If a connection breaks then the PATROL Agent can reconnect smoothly.
Checking the status of the remote PowerShell connection is done at a polling interval defined by this field. By default, the KM checks the connection status every 300
seconds. The minimum value is 10 seconds and the maximum value is 3600 seconds.

Scripts

Click Add button.png button to configure the remote Scripts.

Field

Description

Name

Enter a display name for the script. A container will be created with the script display name.

This container holds the attributes for this script instance. Input must match ^[0-9a-zA-Z._%:-]+$ regular expression pattern.

For example, the display name can be FileSizeMonitor.ps1, GetServiceStatus.ps1, and so on.

Script

The KM supports multiple types of values for this field:


    1. Absolute path to a script file: Enter the absolute path to the location and the file name where the script should be executed on the target monitored device.

      For example: \tmp\myScript.ps1 path means that myScript.ps1 will be copied from the PATROL Agent host to the folder \tmp on the targeted device. It will be executed from there. The file will be uploaded each time when the script source on the PATROL Agent host changes.

      In some scenarios there is a need to run a script with other files (for example, data) that are bundled with the script. In such cases, the KM uploads these files along with the script file. To use this feature, the policy must be defined for a single file (for example, tmp\myScriptDir\myScript.ps1); also all the additional files and the script file must be present in the .zip file on the PATROL Agent file system. The archive must have the same name as the base script for the KM to upload the content of the .zip file to the target host. For example, if the policy is defined with \tmp\myScriptDir\myScript.ps1 value, the zip file name must be myScript.zip on the PATROL Agent file system.

      %PATROL_HOME%\TROMS\Conf\Scripts\ScriptFileTransfer\Devices\DeviceName\ Or

      %PATROL_HOME%\TROMS\Conf\Scripts\ScriptFileTransfer\ Or

      %PATROL_HOME%\TROMS\Conf\Scripts\Samples\)

      If the script does not exist on the PATROL Agent filesystem in the accepted formats (.zip), the Script Status parameter generates an alert with an annotation containing the problem details.

      Note: If the Script (for example, \tmp\bmc\myScript.ps1) does not exist on the remote device but is present on the monitoring system the KM copies the script to the remote device. The KM creates the specified directory structure (\tmp\bmc\) on the remote device and then copies the script. 


    2. One OS command line (one-liner): The script used by the monitor can be a simple or complex command. Use (;) semicolon to separate commands.
      For example: The following line can be used to identify the processes with highest CPU.

      Get-Process | Sort-Object CPU -desc |
      Select-Object -first 10 |fl Name,CPU,Id,Handles,WS,VM,NPM,PM
  • Formatted output (Format-List ) is supported only in one-liner commands. In absolute path its customer responsibility to edit executed file output and provide a supported format.
  • Both script output and on-liner output should have valid output according the supported format definition. For more information, see Defining the script output for Windows environments.
  • Windows Monitor profile in this KM supports execution of scripts in all formats (.exe , bat , perl ,python and so on).

Arguments

Enter the arguments that will be passed during the script execution. The arguments must be separated by a space character.

Example: A script file that measures the log file size must have the argument of the log file name.

Content match

Beyond monitoring for numeric values, the KM is capable of monitoring a specific text pattern returned by the script during execution. This is useful when you need to enable a certain value where the actual numeric value is the same.

The KM scans for a value defined in this field. It returns an annotation text along with the value and the that text defined in this field. A single or a semicolon separated list of regular expressions is supported.

Timeout (sec)

Enter the script timeout period in seconds. If the configured script does not provide a result in the specified time period, a timeout annotation
message is displayed in the Status attribute of the configured script.

If the configured script runs successfully, then the values of Content match, Script response time, Exit Status and Script value attributes are updated.

The minimum value is 1 second and the maximum value is 600 seconds. Default timeout value is 30 seconds.

Note: The script execution is terminated in case of a timeout alert.

Poll interval (sec)

Enter the period in seconds between two consecutive script execution intervals. By default, the script runs every 300 seconds.  The minimum value is 10 seconds and the maximum value is 3600 seconds.

OK

Click to save the configuration.

Cancel

Click to close the configuration window.

Credentials configuration

Username

Enter the username used to connect to the remote host. If this field is left blank, then it will take shared configuration account credentials. If the shared configuration account credentials are blank, then it will take PATROL Agent default account credentials for the connection.

Password

Enter the password corresponding to the user name.

Confirm Password

Re-enter the password.

Authentication Type

Select the authentication from the following:

  • Kerberos
  • Negotiate
  • Use shared authentication

Connection Protocol

Select the protocol from the following:

  • HTTP
  • HTTPS
  • Use shared protocol

Port Number

Enter the PowerShell port number to connect to the configured device. The default port number is 5985.

OK

Click to save the configuration.

Cancel

Click to close the configuration window.


Configure scripts and devices from a file.

Field

Description

Import devices from files

Enable this option to configure devices and scripts from file. The files must be located in %PATROL_HOME%\TROMS\Conf\ImportDevices directory. PATROL Agent will read the files and configure the devices and scripts within each file.

An instance name is created for the configured files. The instance name is similar to the file name. All devices and scripts in a file are grouped under the same instance.

A readme file with instructions on how to configure from file is located at %PATROL_HOME%\TROMS\Conf\ImportDevices directory.

Template for configuring from file:

# Device Name/IP,Forced IP Address,Port,Connection timeout,Connection poll interval,Username,Password,Authentication Protocol,Connection Protocol|Script name*Script path*Script arguments*Script timeout*Script poll Interval*Script RegEx to search|Script name*Script path*Script arguments*Script timeout*Script poll Interval*Script RegEx to search

Example 1:

To configure a device with three scripts that execute RegEx 'ERR' when all the details are available.

clm-aus-013799,172.22.177.167,5985,2000,60,bmc,bmcuser123,0,0|scriptInstaneName1*C:/user/apps/myAppsCPU.bat**60*300*ERR|scriptInstaneName2*C:/user/apps/myAppsMEM.bat**60*300*ERR|scriptInstaneName3*C:/user/apps/myAppsSESSION.bat**60*300*ERR|

Example 2:

To configure a device with three scripts that execute without a RegEx, when only username is available.

clm-aus-013799,172.22.177.167,5985,2000,60,bmc,,,|scriptInstaneName1*C:/user/apps/myAppsCPU.bat**60*300*|scriptInstaneName2*C:/user/apps/myAppsMEM.bat**60*300*|scriptInstaneName3*C:/user/apps/myAppsSESSION.bat**60*300*|

Example 3:

To configure a device with default configuration (Port,Connection timeout,Connection poll interval,Username,Password,Authentication protocol,Connection protocol ) (Script timeout*Script poll Interval).

clm-aus-013799,172.22.177.167,,,,,,,|scriptInstaneName1*C:/user/apps/myAppsCPU.bat|scriptInstaneName2*C:/user/apps/myAppsMEM.bat

The KM uses default configuration if you do not configure Devices, port, timeout, polling interval, and credentials in the device configuration section.

The KM uses the default configuration if Timeout and poll interval are not provided in any script configuration. 

Field

Description

Default device configuration

Timeout (sec)

Enter the connection timeout period in seconds. A targeted device might not be available or might be very slow to respond. In such scenarios, ensure that the KM will not wait for it and just stop responding. This value is used in such scenarios. You can define the maximum time to allow for a remote PowerShell connection establishment. If the time elapses, the KM understands that there is a failure in ability to monitor using the script. If the network or targeted host is slow, you can still get the KM to work properly by allowing a longer timeout period.

The minimum value is 1 second and the maximum value is 600 seconds. Default value is 30 seconds.

Poll interval (sec)

The PATROL Agent maintains set of remote PowerShell connections to all targeted hosts. If a connection breaks then the PATROL Agent can reconnect smoothly. Checking the status of the remote PowerShell connection is done at a polling interval defined by this field. By default, the KM checks the connection status every 300 seconds.

The minimum value is 10 seconds and the maximum value is 3600 seconds.

Credentials configuration

Username

Enter the username to connect to the remote device.

Password

Enter the password corresponding to the user name.

Confirm Password

Re-enter the password.

Authentication Type

Select the authentication from the following:

  • Negotiate
  • Kerberos

Connection Protocol

 Select the protocol from the following:

  • HTTP
  • HTTPS

Port

Enter the PowerShell port number to connect to the configured device. The default port number is 5985.

Default script configuration

Timeout (sec)

Enter the script timeout in seconds. The default value is 30 seconds.

Poll interval (sec)

Enter the period in seconds between two consecutive script execution intervals. By default, the script runs every 300 seconds.  

The minimum value is 10 seconds and the maximum value is 3600 seconds.


Configure the administration section to use the KM more efficiently.

Field

Description

Root display name

Enter the root application class display name. It acts as a container and holds all the scripts. The name must not contain < > \ / | " : * ? characters.

Device mapping

Select the device mapping mode:

  • FQDN - Monitors are created within a device according to the discovered FQDN of the monitored system
  • User defined - Monitors are created within a monitored device using alias name provided with the end user
  • Disable - Monitors are created within the device of the PATROL Agent(s)

Note

If the configured Device name/IP is set using alias name and the force IP address, the device gets mapped to the TrueSight with the Device name/IP instead of the device FQDN although this option was enabled.

Custom monitor types cleanup

Allows you to choose to delete the old monitor types (known as knowledge modules which were created based on the scripts output and are no longer in use).

  • Disable - Automatic cleanup is disabled.
  • Daily - Automatic cleanup is enabled. Monitor types that are not in use since last one day will be deleted.
  • Weekly - Automatic cleanup is enabled. Monitor types that are not in use since last one week will be deleted.
  • Monthly - Automatic cleanup is enabled. Monitor types that are not in use since last one month will be deleted.

WinRM trusted hosts

Select the trusted hosts option from the following:

  • Disable - Addition of devices automatically to the WinRM trusted hosts is disabled. For more information, see Windows-PowerShell-remote-connection-requirements.
    Devices should be added manually to the trusted host.
  • All - Allows connection to all of the remote hosts by setting the value to * to the WinRM trusted hosts.
  • Device - Adds the remote device to the WinRM trusted hosts.

Enable logging

Select/clear check box to enable/disable logging. The log files are located at %PATROL_HOME%\TROMS\logs, on the server where the PATROL Agent is running. By default, the debug is disabled (check box cleared).

OK

Click to save the configuration.

Cancel

Click to close the configuration window.


 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*