Requirements and agent-specific installation and configuration information for the monitoring agent

This chapter contains information about the requirements for the Blue Medora Agent for Ping Probe, and agent-specific information related to installation and configuration of the agent.

To install and configure the Blue Medora Agent for Ping Probe, use the procedures for installing monitoring agents in the IBM Tivoli Monitoring Installation and Setup Guide along with the information in this chapter.

If you are performing a silent installation using a response file, see the information about performing a silent installation in the IBM Tivoli Monitoring Installation and Setup Guide.

Requirements for the monitoring agent

In addition to the requirements described in the IBM Tivoli Monitoring Installation and Setup Guide that are applicable to the installation of any IBM Tivoli Monitoring Agent including all Blue Medora ITM Agents, the Blue Medora Agent for Ping Probe has the following requirements:

Requirement for Pre-existing IBM Tivoli Monitoring agent

To install any Blue Medora ITM Agent you must have at least one pre-existing IBM published agent already  installed.  The Blue Medora Agent for Ping Probe does not include key IBM specific Java",  IBM GSkit, or the IBM Tivoli Monitoring runtime libraries. Installing an IBM-provided agent (normally the OS agent) installs these elements, and the Blue Medora Agent for Ping Probe will be able to run.

Versions of IBM Tivoli Monitoring Supported

The monitoring agent is supported with the following versions of IBM Tivoli Monitoring:

Operating Systems Supported

The monitoring agent runs on any of these operating systems where a pre-existing Tivoli Enterprise Management Agent (TEMA) exists:: 

Disk Space Requirements Agent User Permission Requirements
 Components of the Monitoring Agent After you install the prerequisite software, install the following software, which is required for the Blue Medora Agent for Ping to operate:

Local Installation - Command Line Installation

To install the agent using from the command line, unzip the downloaded agent installation media, or insert the installation CD.   From the command line you can perform any of the following actions:

To install the Ping Probe monitoring agent on a target system, navigate to the <CD ROOT>/kb4/UA_APP/BUNDLE directory and run the appropriate installation script.

For the installIra.bat, installIraAgentTEMS.bat, and installIraAgentTEMS.sh installation scripts, the installation location continues to be mandatory, and must be the first argument. The rest is optional. If you are installing on an IBM Tivoli Monitoring v6.2 Fix Pack 1 system and do not supply any of the three new arguments, the behavior will be the same as it was before. The Tivoli Enterprise Monitoring Server will restart during the process of loading the support. If the system on which you are installing is IBM Tivoli Monitoring v6.2, then the new arguments are not be allowed, as the new function which uses them is not available. On an IBM Tivoli Monitoring v6.2 Fix Pack 1 system, if you provide the new arguments, then Tivoli Enterprise Monitoring Server support will be loaded without causing the Tivoli Enterprise Monitoring Server to restart.

Note: On Unix / Linux systems, depending on how the media was unzipped, the execute bit on the installIRA install scripts may have been removed.  If that is the case in your environment use the chmod command to add the execute bit back ontop the installer before installing.

Note: For Unix / Linux systems, follow the instructions in the IBM Tivoli Monitoring Installation and Setup Guide found in the section titled, "Installing and enabling application support" to ensure the agent application support has been loaded correctly.

Local GUI Configuration of the Ping Probe Agent

For both local and remote configuration, provide the configuration values for the agent to operate. When configuring an agent, a panel is displayed so you can enter each value. When there is a default value, this value is pre-entered into the field. If a field represents a password, two entry fields are displayed. You must enter the same value in each field. The values you type are not displayed to help maintain the security of these values.

In the GUI configuration menu, the proceeding values may be found on the first page of the dialogue. All of these values must be filled in for the agent to successfully perform its operations.

Note:  When configuring the agent to ping remote hosts you have the option to define the hostnames and / or IP addresses to be monitored  in either the standard Agent configuration panels and / or via a externalized configuration file that is suited more for defining mass numbers of hostname to monitor.

The configuration for this agent is organized into the following sections:

Basic  Configuration

The Basic Configuration section contains high level configuration options that are not specific to the hosts that are going to be pinged.  The configuration values focus on Instance Naming, Agent Data Collection interval, and the Logging level of the agent.

Instance Name

If it is the first time the agent has been configured, the user may specify the instance name in this dialogue.  The Ping Probe Agent is a multi-instance agent, meaning that multiple instances of the agent may be run at the same time.  Each instance will have a different name and directives file, and may have a different collection interval or logging level.

The multi-instance capability is useful when the user wishes to monitor two different host configurations at different collection intervals.

Data Collection Interval

This setting is used to control the data collection interval of the agent.  It may be desirable to configure an instance of the agent to ping different collections of hosts at variable collection intervals.  The user should use discretion while creating directives to be used with short collection intervals, keeping in mind that the greater the number of hosts the agent has to connect to, the longer the scan will take.  The default value is 5 minutes.  

Logging Level of the agent

The log level may be changed to assist in debugging issues with the Ping Probe agent custom data provider. It is unnecessary to change this value under normal circumstances, and it is recommended to leave it at the default setting of "warn". 

The agent logs files may be found in the ITM home directory.  On Linux/Unix platforms, the specific location of the log file will be in the ITM home logs directory.  The name of the principal agent log file containing Ping Probe agent specific specific data collection related diagnostics isl be kb4_<instance>_trace.log, where instance is the instance name of the agent.

The possible log levels are:

The drop down selections for the logging levels differ slightly from the actual values the agent requires. When configuring the logging level through tacmd, the acceptable values are: DEBUG, INFO, WARN, ERROR, and FATAL. The difference is capitalization.

Global Ping Values

Global Ping Timeout Value


The overall timeout value is the amount of time in milliseconds that determines if a host is unreachable for all hosts that were not provided with a timeout value in the directives file.  This value should never exceed the slow response threshold value.  You can override ths value for individual hosts later on when you define the specif hosts you want to ping.  If you have a large amount of hosts in your directives file, be sure not to set the overall timeout value too high.  This will cause the data gathering loop to take a long time.     

Slow response threshold

The slow response threshold is the amount of time in milliseconds that you wish to consider a host that has been pinged as slow.  This value will be used to slow responding hosts in the TEMS/TEPS in the Ping Result Description field and in Situations.

IMPORTANT: Make sure that this value is NOT larger than the Global Ping Timeout Value, both in the main configuration as well as for individual hosts that you have configured over-rides for.

Retry Attempts

The Retry Attempts configuration value indicates the amount of times that you wish to retry pinging the host if it was not successful the first time.  

Note -- If you are monitoring a large number of hosts, make sure not to set the retry amount to high, this will cause the data gathering loop to take a long time.  

Maximum Concurrent Pings

The number of concurrent pings to the agent will perform at once.  The default value is 10.   Raising and lowering this settting should be done with caution.  Increasing the maximum number of concurrent pings increases the memory and cpu usage on the server the agent is installed on.  Depending the on platform, high numbers of concurrent pings can be expensive from a utilization perspective.

Note -- If you are monitoring a large number of hosts, make sure not to set the retry amount to high, this will cause the data gathering loop to take a long time.  

Location of Optional Ping Probe Host File

The Ping Probe Directives File

The Ping Probe Directives File is a file where hosts that are to be "pinged" can be defined.  When using the Ping Probe agent on a Unix or Linux platform, the file is still stored in the ITM installation file structure, under the subdirectory will is based on the ITM platform code, the product code of the agent, and bin.  For example, for a Linux 2.6 system with a  default ITM home location, the location of the sample directives file will be:

        /opt/IBM/ITM/li6263/p7/bin/KXF_directive_sample.csv
 
Although the sample directives file is located within the ITM installation folders, the user may place their own directives files anywhere on the file system, as long as the user account the agent is running under has sufficient operating systems privledges to access the file.

Hosts to Ping

Note: You can define hosts to be pinged via the Hosts to Ping ITM configuration panels and / or the Optional Ping Probe Host File (see next section).  It is required that you define hosts to be ping in at least one of them.

The Hosts to Ping section of the Agent configuration allows you to define hostnames the agent will ping.  If you have between 1 and 20 hosts you would like to ping, configuring the agent using the Hosts to Ping configuration panels is an acceptable method for doing so.  The section is repeatable so after you've defined an individual hostname / port combination you can click "New" and define another another.

Hostname

TCP/IP host the connect to.  

Timeout

Timeout value is the amount of time in milliseconds that determines if a host is unreachable

Alias

Descriptive name for host to be pinged.  

Extended Configuration via the Directives File

Note: You can define hosts to be pinged via the Hosts to Ping ITM configuration panels and / or the Optional Ping Probe Host File (see next section).  It is required that you define hosts to be ping in at least one of them.

Use of the Ping Probe monitoring agent starts with the directives file.  If the agent has been installed on the target machine, a sample directives file will be located in the agent's bin directory under the ITM home directory.   The file name is  KXF_directive_sample.csv.  It is strongly recommended that this file be renamed or moved before it is used.  If this file is not renamed, it will be overwritten when the agent is reinstalled or upgraded to a later version.  If the user wishes to use the example directives provided, they must also remove the pound (#) characters at the beginning of the appropriate lines, based on what system platform on which they are installing the agent.

The directive configuration file is comprised of two types of lines, comments and directives.  Comments contain a pound character (#) as their first non white space character.  These lines are completely ignored by the agent, and are meant to provide a space for agent administrators to leave notes.  Lines containing only white space are also ignored.  Each directive will contain exactly one record in the TEP with which it is associated.

Directives give the agent criteria for monitoring important files and folders.  The directive is split into four comma separated fields.  The four fields are the alias, the path, the recursion flag, and the regular expression field.  The only field that MUST be expressed is the path with a comma preceding it.

Host

This value is the host that you wish to monitor.  The host may not be left blank.

Timeout

The timeout value represents the amount of time in milliseconds that is used to determine if the host is up or down for this configuration line.  If this value is left blank than the default timeout valued that was defined during agent configuration will be used.  If you wish to leave this value blank but would like to specify a alias value simply include a comma without a value.  

Example:  Host, ,alias

Alias

The alias is used to provide an easy and readable way of referencing the host that is being monitored.  The alias will appear verbatim in the TEP next to the Ping Result Description representing the line on which the directive was found.  If the alias is left blank (by placing a comma in the first field and nothing else), a default value will be assigned that is the same as the hostname,

Scenarios and Use Cases

This section contains more advanced scenarios which may be used as example directives.

Example:  Monitoring a critical system

A user wants to monitor a critical system that should never take more than 1000ms to come back with a reachable state.  A directive line to monitor such a scenario would look like this:

        critical_system.local, 1000 , My important system

The first part of the line (before the first comma) is the host you would like to monitor.  The next element in the line is the timeout in milliseconds for the provided host. The final element in the directive line is the alias for the configuration (A way of remembering the system that you are monitoring)


Example:  Monitoring a critical system without an alias

A user wants to monitor a critical system that should never take more than 500ms to come back with a reachable state.  A directive line to monitor such a scenario would look like this:

            critical_system2.local, 500

The first part of the line (before the first comma) is the host you would like to monitor.  Then followed by the time in milliseconds for the host to report down (the timeout).  When you do not provide an alias, the alias field in the TEP comes back as the host that you specified in the first line.


Example:  Monitoring a critical system without a alias or timeout interval

A user wants to monitor a critical system that should never take more than the overall time-out (the value provided in configuration) to come back with a reachable state.  A directive line to monitor such a scenario would look like this:

            critical_system2.local

The first part of the line (before the first comma) is the host you would like to monitor.  For directives without an alias specified, the hostname is repeated in the alias output attribute.

Note: If you want to monitor the same host at different timeout intervals, you must specify an alias for each of them.  If you don't do so the last collected result from the directives file will be the only element that shows up in the TEP.

Remote installation and configuration

To deploy the Probe Probe agent via TACMD command CLI, follow the instructions for loading an agent into the TEMS depot. Refer to the Tivoli documentation regarding remote deployment for further instructions:

http://publib.boulder.ibm.com/infocenter/tivihelp/v24r1/topic/com.ibm.itm.doc_6.2.1/itm_install161.htm#deploy

When installing the agent remotely, you must provide the configuration values for the agent to operate. 

See the tacmd describeSystemType section in the IBM Tivoli Monitoring Command Reference for information on displaying the configuration options that are available to use with the configureSystem or addSystem commands.

Once the agent has been added to the depot, a managed system may be added to a node monitored by an Operating System agent.  Example:  

An administrator wishes to add the Ping Probe agent to a Windows 2003 server based node, tw3g3.  tw3g3 is already an ITM node.  In this case the Ping Probe is configured to only use the extended directives file.
tacmd addsystem -t XF -n Primary:TW3G3:NT -p 
BASICCONFIG.KXF_LOG_LEVEL="WARN" 
BASICCONFIG.KXF_DATA_COLLECTION_INTERVAL="1" 
GLOBALPINGCONFIG.KXF_GLOBAL_PING_TIMEOUT="1000" 
GLOBALPINGCONFIG.KXF_SLOW_RESPONSE_THRESHOLD="750" 
GLOBALPINGCONFIG.KXF_RETRY_ATTEMPTS="1" 
GLOBALPINGCONFIG.KXF_PROCESSING_THREAD_AMOUNT="10" 
CONFIGFILE.KXF_CONFIG_FILE="C:\\Documents and Settings\\Administrator\\Desktop\\hosts.csv" 
INSTANCE="Intranet_Hosts"