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 Files and Directories, and agent-specific information related to installation and configuration of the agent.

To install and configure the Blue Medora Agent for Files and Directories, 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 Files and Directories has the following requirements:

Local vs Remote Monitoring support

The Blue Medora Agent for Files and Directories only supports "local" monitoring of files and directories.  This means the agent must be installed directly on a supported server in order for it to fully function.  "Remote" monitoring of non-local servers is not currently supported.

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 Files and Directories 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 Files and Directories 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 Components of the Monitoring Agent After you install the prerequisite software, install the following software, which is required for the Blue Medora Agent for Files and Directories to operate:

Agent Installation

There are several methods available for installing any IBM Tivoli Monitoring agent, and those methods are closely related to some of the dependencies listed in the Installation Prerequisites section. Below are a few methods for installing the agent with examples.

Local Installation - Windows GUI Install

To install the agent, unzip the downloaded agent installation media, or insert the installation CD. In the root of the installation media,you will a file named setupwin32.exe file. Run the file to perform any of the following actions:

Follow the wizard through the basic installation steps, then in the MTEMS console, start the configuration dialogue for the FDM Monitoring agent.

Local Installation - Unix/Linux GUI Install

For Unix and Linux, ensure you are installing from a valid Xwindows console and navigate to the top level of the installation media. On Linux systems, run setupLinux.bin. On Unix systems, run setupUnix.sh. A dialogue box will appear and guide the user through the rest of the installation. You will have the option to perform any of the following actions:

For Linux systems, special care should be taken to install all of the the Linux dependencies indicated in the Installation Prerequisites section, specifically making sure that libXp.so.6 is installed. The GUI installation will not function properly without this shared object.

Basic Agent Configuration

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.

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

Instance Name

If it is the first time the agent has been configured, the user may specify the instance name in this dialogue.  The Files and Directories Monitoring 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 File/Directory monitoring configurations at different collection intervals.

Data Collection Interval

It may be desirable to configure an instance of the agent to monitor important files and directories at short 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 files and directories the agent has to scan, the longer the scan will take.

The Files and Directories Directives File

On a Windows platform, the directives file will reside in the ITM home folder under the TMAITM6 subdirectory.  Ultimately the name of the directives file is left to the user, but the sample directives file by default is named “KP7_directive_sample.csv”.  The contents of the directives file will be  detailed in the next section.

When using the FDM agent on a Unix or Linux platform, the file is still stored in the ITM installation file structure, but the subdirectory will be 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/KP7_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 agent has sufficient credentials to access the file.

Logging Level of the agent

The log level may be changed to assist in debugging issues with the File and Directory 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. On Windows systems, the file will be located in the ITM/TMAITM6/logs directory. The name of the principal agent log file containing File and Directory specific data collection related diagnostics isl be kp7_<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.

Extended Configuration via the Directives File

Use of the Files and Directories 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 ITM home installation directory.  The file name is  “KP7_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 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.

Alias

The alias is used to provide an easy and readable way of referencing the files and directories that are being monitored.  The alias will appear verbatim in the TEP next to the line number 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 is assigned to the directive by the agent.

Path

The path string is the full absolute path to a file or directory the administrator wishes to monitor.  If the administrator wishes to monitor, for example, the cron log on a Unix system, they would use the value of “/var/log/cron” in this field.  If however, they wished to see that only the directory containing the log existed, they would use the value “/var/log”.  The resolution of which kind of file the path value yields is given in the TEP.  The Path value MUST be expressed by the administrator.  A directive containing no path is considered invalid, and will be only partially processed.  In that case, an error code and line number will be provided in the TEP for convenience.  For a list of available error codes, please see the Return Codes section.

Recursion

The recursion flag can be set to either “yes” or “no” by the administrator building the directive.  Setting the recursion flag to “yes” will cause the agent to include every subdirectory under the path.  It is advised that the recursion flag be set to “yes” with discretion.  Using recursion with the path of C:\ on a windows system will cause the agent to scan the entire system.  If the path resolves to a file and not a directory, the recursion flag will automatically be set to “no”.  If the user manually set recursion to “yes” under these conditions, an error code will be displayed in the TEP.  Directives such as this will still process.  If the path does resolve to a directory, the size of the directory will be sampled using the size of every file in that directory and sub directories.  File sizes will only be taken if the names of the files match the regular expression provided in the final field of the directive.

Regular Expression

When defined, regular expressions will cause the agent to only include files matching the regular expression pattern.  If this field is left blank, all files are included (the regular expression is set to /.*/ (dot star)).  Although the scope of regular expressions is beyond this document, some examples will given containing both simple and more complicated regular expressions.

Directive Examples

,/home/finck

This is an example of a minimal directive that may be specified in the directives file.  It has no alias, no recursion flag, and no regular expression.  The directive causes the agent to check for the existence of /home/finck.  If /home/finck is a file, it will report the path as a file in TEPS.  If the path resolves to a directory, the path will be reported as a directory in TEPS.  Recursion will be turned off implicitly, and the regular expression (if /home/finck is a directory) will be .* (dot star).  All regular and readable files in /home/finck will be counted and sampled for size.  The file count and total size will appear in the TEP. 

,/home/johnson,yes

This directive will include all subdirectories below /home/johnson in the filesystem hierarchy.

Files,/home/rubin,no

This directive provides a user friendly name which will be displayed in the TEP. 

Documents,/home/simmons,yes,.*\.rb

This directive will cause the agent to look for every file that ends in “.rb” in every subdirectory of /home/simmons.  The alias will appear as “Documents”.

Regular Expression Examples

The KP7 Files and Directories Monitoring agent implements Java regular expressions.  This section will provide a few simple regular expression examples that may be easily modified and included in the user's own directives file.  A more comprehensive tutorial and explanation on Java regular expressions may be found on the web at this address:

http://java.sun.com/docs/books/tutorial/essential/regex/

The sections describing string literals, character classes, quantifiers, boundaries, and groups will be the most helpful to the user.

.*+:  . (dot)  denotes any character.  The star will cause the parser to look for that character class (dot) zero or more times.  The '+' causes the parser to be possessive, meaning that it will scan the entire input string at once (the input strings will be the name of the files encountered by the agent).

.*\.log$:  A regular expression that will monitor a file that ends with “.log”.  The backslash is necessary because the . (dot) character has a special meaning in regular expression.  The backslash causes Java's regular expression parser to escape so that the . (dot) character is read literally.  The “log” part of the expression will be taken literally because the escape is only valid for one character, and the '$' says that the input string must end (or newline) as soon as 'log' has been read.

^K[PB]\d_.*\.log$:  This explicitly describes the beginning of the input string by including the ^ (carrot).  The first letter of this input must be K, and the next one may be P or B followed by a digit 0-9 and then an _ (underscore).  The rest of the expression operates  exactly the same as the one above it.

^(?i)kp7_.*_trace\.log:  This expression explicitly monitors the kp7 trace log for any instance of the agent.  The input string may be either KP7_.*_TRACE.LOG or kp7_.*_trace.log or may have any permutation of string cases in between.  The (?i) makes the matcher insensitive to case.

Return Codes

Return codes appear in the TEP along with the rest of the results for each directive given in the configuration file.

Success

0No Error

Error Codes

1General Error
2Invalid Configuration Record
3Improper Regular Expression Encountered
4Invalid Regular Expression Syntax

Warnings

27Regular Expression Entered with File for path
28Recursion specified with path


Scenarios and Use Cases

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

Example:  Monitoring a single log file

A user wants to monitor an application log file, “enterprise_log_file.log”, contained in the enterprise_application/logs directory.  They are not interested in anything else in the folder.  A directive line to monitor such a scenario would look like this:

        Enterprise Log File,/opt/enterprise_application/logs/enterprise_log_file\.log,no

The backslash is used to escape the meaning of “.” (dot) in regular expressions

Example:  Monitoring log files with a date pattern

A user wants monitor the size of the current log, and all the logs that have been rolled, to and keep an eye on their size.  The log files have a six digit date pattern so that the date is inserted before the file extension:

        Enterprise Log Files,/opt/enterprise_application/logs,no,enterprise_log_file_\d{6}\.log+

Example:  Monitoring the Size of a Directory

Now the user wants to monitor the size of an entire log directory.  They also wish to know if the log files are growing at a rate of more than one megabyte every ten minutes.  There are also logs that reside deeper in the directory structure, so monitoring just the directory specified explicitly in the path will not suffice.

        Enterprise Log Directory,C:\Program Files\enterprise_application\logs,yes

The agent's rate of growth measurements are taken when the agent collects the data from the system.  Since a situation must be based off of this metric, the user will have to make sure to configure the agent to poll its data from the system every 10 minutes, if the user wishes to have the rate of growth in Megs/10 Minutes.

Example:  Monitoring Larger Directories in addition to Smaller Ones

Monitoring a larger directory is not any harder, but the user should take care not to overextend the capabilities of the system they are trying to monitor.  Consider an example where a user wants to measure a file on the same system as the previous example, but did not want to poll a large directory every 10 minutes.
The user would set up another instance of the agent, and configure the agent to run 60 minutes, and would create a separate directives file.  The separate file would contain the large directory only to be polled every hour.

(In the original agent's directives file):

        Enterprise Log Directory,C:\Program Files\opt\enterprise_application\logs,yes

(In the second agent's directives file):

        Enterprise Applications,C:\Program Files,yes

Again, the user would have to configure two separate instances of the agent for this scenario to work, giving them two different configurations, and two different directives files (otherwise, both agents would perform all the directives in the shared file).

Remote installation and configuration

To deploy the FDM 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 FDM agent to a node, “pw3g1”.  “pw3g1” is already an ITM node.

C:\IBM\ITM>tacmd addsystem -t P7 -n Primary:PW3G1:NT -p 
CONFIGFILE.KP7_CONFIG_FILE="C:\IBM\ITM\TMAITM6\KP7_directive_sample.csv" 
CONFIGFILE.KP7_DATA_COLLECTION_INTERVAL="20" CONFIGFILE.KP7_LOG_LEVEL="DEBUG" 
INSTANCE="foo"

Java Installation on Windows

IBM JRE 1.5 or greater is required to run the agent on Microsoft Windows 2003 and 2008 Servers.  In certain scenarios where the IBM Tivoli Monitoring Windows OS Agent  has been remote deployed, IBM JRE 1.5 will not exist.  This can also also be the case when deployed an Blue Medora ITM agent onto a system that contains a TEMA installed by another agent other than a IBM Tivoli Monitoring OS Agent.  Performing a local installation of an IBM Tivoli Monitoring Windows OS Agent installs the required IBM JRE 1.5 as part of the it's installation process.

               "the command is not recognized as an internal or external command, operable program, or batch file."

Note: If the system-wide Java installation is not at least IBM JRE 1.5, the monitoring agent will not run. If the system Java installation cannot be upgraded, you can install a private IBM JRE 1.5 into another directory and manually configure the agent to use the newly installed 1.5 Java installation. To manually modify which version of Java the monitoring agent uses, edit the KP7_run.bat file that exists in the IBM Tivoli Monitoring installation directory. The exact location differs depending on platform. This batch file assume that a working JAVA_HOME and PATH exist in the environment, so you can change the batch files to set JAVA_HOME and PATH to a different Java installation.