Configuring LINUX-UNIX shell script monitor type

This topic provides information about using TrueSight Operations Management for monitoring using the Remote Scripting execution.

Remote Scripting execution refers to the usage of user defined scripts running on targeted hosts. 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 SSH connections.

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

Monitoring Solution

Version

Monitor Profile

Monitor Type

Script

1.0.00

Script

LINUX-UNIX shell script

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

Click a tab to view the respective configuration.

Related topics

Configuring-after-installation

Configuring-OS-command-line-execution-monitor-type

Enter the remote device details and configure a script that can be executed on the remote Linux 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 SSH connection to the targeted device.
You can also enter an alias name. If you have provided an alias name as the device name, vyou 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. 

Port

Enter the SSH port number to connect to the device. The default port number is 22.

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 an SSH 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 5 seconds.

Poll interval (sec)

The PATROL Agent maintains it’s set of SSH connections to all targeted hosts. If a connection breaks then the PATROL Agent can reconnect smoothly.
Checking the status of the SSH 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 will hold the attributes for this script instance. Input must match ^[0-9a-zA-Z._%:-]+$ regular expression pattern.

For example, the display name can be cron-monitor.sh, ping3rdParty.sh, 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 placed on the target monitored device.
      For example: /tmp/myScript.sh path means that myScript.sh will be uploaded from the PATROL Agent’s 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's 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/mScript.sh). Also, all the additional files and the script file must be present in the .tar or .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 or .tar file to the target host. For example, if the policy is defined with /tmp/myScriptDir/myScript.sh value, the zip file name must be myScript.zip, on the PATROL Agent file system.%PATROL_HOME%/TRO/Conf/Scripts/ScriptFileTransfer/Devices/DeviceName/ Or

      %PATROL_HOME%/TRO/Conf/Scripts/ScriptFileTransfer/ Or

      %PATROL_HOME%/TRO/Conf/Scripts/Samples/)

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

      Note: If the Script (for example, /tmp/bmc/myScript.sh) 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 (also known as one-liner): The script used by the monitor, can be a simple or complex command. Multiple tools
      can be used to write the command. Standard shell syntax rules apply.
      For example: The following line can be used to monitor the file system utilization in percent on the targeted device.

      df -lkh | grep -v Mounted | tr -s ' ' | for line in $(cut -d ' ' -f 6,5|sed -e 's/ /,/g' -e 's/%//
      g' -e 's/\//_/g' );do printf "FileSystem=%s,UsagePct=%d\n" `echo $line | cut -f 2 -d ','` 
      `echo $line | cut -f 1 -d ','`;done

      After defining and executing the script, the KM creates an instance of the LINUX-UNIX shell script monitor type according to
      the policy field. The Script Status attribute monitors the agent’s ability to monitor by using the provided policy details.

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.

The syntax of regular expression has to be considered valid for usage with Oracle Java (java.util.regex).

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 5 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, PATROL Agent default account username is used for the connection.

Password based authentication

Password

Enter the password corresponding to the user name (enter $ character if you want to modify the password and leave it blank).

Key based authentication

Public key file path

Enter the absolute path of the file that will hold the public key.

Private key file path

Enter the absolute path of the file that will hold the private key.

Passphrase

Enter the passphrase to access public and private keys (enter $ character if you want to modify the password and leave it blank).

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/TRO/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 read me file with instructions on how to configure from file is located at $PATROL_HOME/TRO/Conf/ImportDevices directory.

Template for configuring from file:

# Device Name/IP,Forced IP Address,Port,Connection timeout,Connection poll interval,Username,Password,Public Key Path,Private Key Path,Passphrase|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'. User name and password details are available.

clm-aus013799,172.22.177.167,22,2000,60,yossi,yossi123,,,|scriptInstaneName1*/root/yossi/apps/myAppsCPU.bash**60*300*ERR|
scriptInstaneName2*/root/yossi/apps/myAppsMEM.bash**60*300*ERR|scriptInstaneName3*/root/yossi/apps/myAppsSESSION.bash**60*300*ERR|

Example 2:

To configure a device with three scripts that execute without a RegEx, Public, private key, and passphrase details are available.

clm-aus-013799,172.22.177.167,22,2000,60,yossi,,/root/.ssh/id_rsa.pub,/root/.ssh/id_rsa,yossi123|scriptInstaneName1*/root/yossi/apps/
myAppsCPU.bash**60*300*|scriptInstaneName2*/root/yossi/apps/myAppsMEM.bash**60*300*|scriptInstaneName3*/root/yossi/apps/
myAppsSESSION.bash**60*300*|

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

Port

Enter the SSH port number to connect to the configured device. The default port number is 22.

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 an SSH 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 5 seconds.

Poll interval (sec)

The PATROL Agent maintains it’s set of SSH connections to all targeted hosts. If a connection breaks then the PATROL Agent can reconnect smoothly. Checking the status of the SSH 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 based authentication

Password

Enter the password corresponding to the user name (enter $ character if you want to modify the password and leave it blank).

Key based authentication

Public key file path

Enter the absolute path of the file that will hold the public key.

Private key file path

Enter the absolute path of the file that will hold the private key.

Passphrase

Enter the passphrase to access public and private keys (enter $ character if you want to modify the password and leave it blank).

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 display name. This is the main container that will hold 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 name provided with the end user (alias)
  • Disable - Monitors are created within the device of the PATROL Agent(s)

JAVA_HOME path

Enter the complete path of the JAVA_HOME directory if you are not using the JRE that is installed with the PATROL Agent. JAVA home environment variable or PATROL Agent JRE will be used if this field is left empty.

Note: Java Runtime Environment (JRE) 1.8 or later is supported (for LINUX-UNIX shell script monitor type configuration, that is, support for remote script execution only).

Example:

  • (Windows) - If the JRE files reside at C:\Program Files (x86)\Java\jre8\bin\java.exe location then specify the path as C:\Program Files (x86)\Java\jre8
  • (Unix/LINUX) - If the JRE files reside at /usr/java/jdk1.8.0_65/bin/ location then specify the path as /usr/java/jdk1.8.0_65

Custom monitor types cleanup

Allows you to choose to delete the old monitor types (known as knowledge modules) that 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.

Enable logging

Select/clear check box to enable/disable logging. The log files are located at $PATROL_HOME/TRO/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*