IBM...IBM® Tivoli® Netcool/OMNIbus Probe for Tivoli EIF Version 13.0 Reference Guide March 14,...

IBM® Tivoli® Netcool/OMNIbus Probe forTivoli EIFVersion 13.0

Reference GuideMarch 14, 2017

IBM

SC22-5421-03

Note

Before using this information and the product it supports, read the information in Appendix A, “Noticesand Trademarks,” on page 19.

Edition Notice

This edition (SC22-5421-03) applies to version 13.0 of IBM Tivoli Netcool/OMNIbus Probe for Tivoli EIF and to allsubsequent releases and modifications until otherwise indicated in new editions.

This edition replaces (SC22-5421-02).© Copyright International Business Machines Corporation 2011, 2017.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

About this guide.................................................................................................... vDocument control page................................................................................................................................ vConventions used in this guide.................................................................................................................. vii

Chapter 1. Probe for IBM Tivoli EIF........................................................................ 1Summary...................................................................................................................................................... 1Installing probes.......................................................................................................................................... 3Running the Configuration Analyser............................................................................................................ 3Integrating the Probe for IBM Tivoli EIF with IBM Tivoli monitoring devices............................................ 4

Configuring the Probe for IBM Tivoli EIF rules file................................................................................ 5Configuring the ObjectServer.......................................................................................................................5Using different connection modes to receive events..................................................................................6Data acquisition........................................................................................................................................... 6

Unicode Transformation Format (UTF-8) mode on Windows............................................................... 6Probe operation...................................................................................................................................... 7Threading................................................................................................................................................ 7Heartbeat events.................................................................................................................................... 7Data stream capture...............................................................................................................................7Parsing malformed alarms..................................................................................................................... 8Peer-to-peer failover functionality.........................................................................................................8Deploying the probe using a TCP load balancer.................................................................................... 9

Properties and command line options........................................................................................................ 9Elements.................................................................................................................................................... 14Error messages.......................................................................................................................................... 15Error messages generated by the Configuration Analyser....................................................................... 15ProbeWatch messages.............................................................................................................................. 16Known Issues.............................................................................................................................................17

Appendix A. Notices and Trademarks................................................................... 19Notices....................................................................................................................................................... 19Trademarks................................................................................................................................................ 20

iii

About this guide

The following sections contain important information about using this guide.

Document control pageUse this information to track changes between versions of this guide.

The IBM Tivoli Netcool/OMNIbus Probe for Tivoli EIF documentation is provided in softcopy format only.To obtain the most recent version, visit the IBM® Tivoli® Netcool® Information Center:

http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp?topic=/com.ibm.tivoli.nam.doc/welcome_ptsm.htm

Table 1. Document modification history

Document version Publication date Comments

SC23-6072-00 December 07, 2006 First IBM publication.

SC23-6072-01 March 28, 2008 Summary section updated.

Elements section updated.

HandleMalformedAlarms property added.

Error messages section updated.

SC23-6072-02 July 25, 2008 Support for Linux for zSeries added.

Summary section updated.

BufferEvents property added.

Elements section updated.

Error messages section updated.

SC23-6072-03 December 19, 2008 Summary table updated.

IPv6 support information added.

FIPS information added.

Installation section added.

Support for managing IBM TPC and IBM TSM added.

Topic added to describe how configure the probe whenusing the Process Agent.

Descriptions for the MaxEventQueueSize,PortMapper, and PortMapperNumber propertiesadded.

© Copyright IBM Corp. 2011, 2017 v



Table 1. Document modification history (continued)


SC23-6072-04 April 30, 2009 Configuring the probe environment topic added.

Support for the Configuration Analyser added.

Summary section updated.

Installing the Configuration Analyser topic added.

Running the Configuration Analyser topic added.

Section added to describe the error messages that aregenerated by the Configuration Analyser.

SC23-6072-05 October 31, 2009 Guide updated to describe running the probe in UTF-8mode on Windows.

Description for FlushBufferInterval added.

Description for the -utf8enabled command lineoption added.

SC23-6072-06 February 25, 2011 Installation section replaced by “Installing probes” onpage 3.

Descriptions for the EIFLogFileName, EIFLogLevel,EIFTraceFileName, EIFTraceLevel,EIFReadRetryInterval, and BufEvtMaxSize propertieswere added to “Properties and command line options”on page 9.

SC22-5421-00 November 4, 2011 This guide replaces the documentation for IBM TivoliNetcool/OMNIbus Probe for Tivoli EIF Version 10(SC23-6072-06)

The following properties were removed from the“Properties and command line options” on page 9section:

• BufferEvents• BufEvtMaxSize• EIFCacheFile• Inactivity• Retry

The following properties were added to the “Propertiesand command line options” on page 9 section:

• EIFHeartBeatInterval• EIFHeartBeatFailures

SC22-5421-01 July 5, 2013 “Summary” on page 1 updated.

vi IBM® Tivoli® Netcool/OMNIbus Probe for Tivoli EIF: Reference Guide

Table 1. Document modification history (continued)


SC22-5421-02 November 8, 2013 “Summary” on page 1 updated.

Support for following rules has been moved to the IBMTivoli Netcool/OMNIbus Probe Extension Package.

• tivoli_eif_tec.rules• tivoli_eif_tpc.rules• tivoli_eif_tsm.rules

The known issue of the probe not shutting down cleanlyadded to “Known Issues” on page 17

SC22-5421-03 March 14,2017 “Data acquisition” on page 6 updated.

“Example property file settings for peer-to-peerfailover” on page 8 updated.

“Using different connection modes to receive events”on page 6 added.

“Deploying the probe using a TCP load balancer” onpage 9 added.

Fixes: Version 13 of the Probe for Tivoli EIF ReferenceGuide has been updated to address the following APAR:

• IV89955: Events arrive on the server malformedbecause class names and attribute names arenumeric. Class names and attribute names must bealphanumeric.

Conventions used in this guideAll probe guides use standard conventions for operating system-dependent environment variables anddirectory paths.

Operating system-dependent variables and paths

All probe guides use standard conventions for specifying environment variables and describing directorypaths, depending on what operating systems the probe is supported on.

For probes supported on UNIX and Linux operating systems, probe guides use the standard UNIXconventions such as $variable for environment variables and forward slashes (/) in directory paths. Forexample:

$OMNIHOME/probes

For probes supported only on Windows operating systems, probe guides use the standard Windowsconventions such as %variable% for environment variables and backward slashes (\) in directory paths.For example:

%OMNIHOME%\probes

For probes supported on UNIX, Linux, and Windows operating systems, probe guides use the standardUNIX conventions for specifying environment variables and describing directory paths. When using theWindows command line with these probes, replace the UNIX conventions used in the guide with Windowsconventions. If you are using the bash shell on a Windows system, you can use the UNIX conventions.

About this guide vii

Note: The names of environment variables are not always the same in Windows and UNIX environments.For example, %TEMP% in Windows environments is equivalent to $TMPDIR in UNIX and Linuxenvironments. Where such variables are described in the guide, both the UNIX and Windows conventionswill be used.

Operating system-specific directory names

Where Tivoli Netcool/OMNIbus files are identified as located within an arch directory under NCHOME orOMNIHOME, arch is a variable that represents your operating system directory. For example:

$OMNIHOME/probes/arch

The following table lists the directory names used for each operating system.

Note: This probe may not support all of the operating systems specified in the table.

Table 2. Directory names for the arch variable

Operating system Directory name represented by arch

AIX® systems aix5

Red Hat Linux and SUSE systems linux2x86

Linux for System z linux2s390

Solaris systems solaris2

Windows systems win32

OMNIHOME location

Probes and older versions of Tivoli Netcool/OMNIbus use the OMNIHOME environment variable in manyconfiguration files. Set the value of OMNIHOME as follows:

• On UNIX and Linux, set $OMNIHOME to $NCHOME/omnibus.• On Windows, set %OMNIHOME% to %NCHOME%\omnibus.

viii IBM® Tivoli® Netcool/OMNIbus Probe for Tivoli EIF: Reference Guide

Chapter 1. Probe for IBM Tivoli EIF

A range of Tivoli products generates Event Integration Facility (EIF) messages. The Probe for Tivoli EIFcan receive EIF events sent from any of these Tivoli devices and sends them to the ObjectServer.

This guide contains the following sections:

• “Summary” on page 1• “Installing probes” on page 3• “Running the Configuration Analyser” on page 3• “Integrating the Probe for IBM Tivoli EIF with IBM Tivoli monitoring devices” on page 4• “Configuring the ObjectServer to manage events from TEC” on page 5• “Using different connection modes to receive events” on page 6• “Data acquisition” on page 6• “Properties and command line options” on page 9• “Elements” on page 14• “Error messages” on page 15• “Error messages generated by the Configuration Analyser” on page 15• “ProbeWatch messages” on page 16

SummaryEach probe works in a different way to acquire event data from its source, and therefore has specificfeatures, default values, and changeable properties. Use this summary information to learn about thisprobe.

The following table summarizes the probe.

Table 3. Summary

Probe target Devices that generate Tivoli EIF version 3.9 messages.

Probe executable file name nco_p_tivoli_eif.jar

nco_p_tivoli_eif.bat

tivoli_eif.check.jar (enables the probe to run with theConfiguration Analyser)

Package version 13.0

Probe supported on For details of supported operating systems, see the following ReleaseNotice on the IBM Software Support website:

Properties file $OMNIHOME/probes/arch/nco_p_tivoli_eif.props

Note: While running the probe on Windows, the directory file namespecified in the path to the location of the properties file getstruncated to eight characters.

© Copyright IBM Corp. 2011, 2017 1

http://www-01.ibm.com/support/docview.wss?uid=swg21647306

Table 3. Summary (continued)

Configuration files $OMNIHOME/probes/arch/tivoli_eif.rules

Note: The tivoli_eif.rules file contains commented outreferences to tivoli_eif_tec.rules, tivoli_eif_tpc.rulesand tivoli_eif_tsm.rules. These rules are now supported in theProbe Extension Package. If the probe receives events from IBM TECLogFile agent, IBM TPC or IBM TSM, you must uncomment theseinclude statements reference. See “Integrating the Probe for IBMTivoli EIF with IBM Tivoli monitoring devices” on page 4 for details.

Note: Additional rules are available to use with this probe in the IBMTivoli Netcool/OMNIbus Probe Extension Package. For moreinformation about downloading and using these additional rules, seethe IBM Tivoli Netcool/OMNIbus Probe Extension Package(SC27-5682-00).

Requirements IBM Tivoli Netcool/OMNIbus 7.4.0.

Note: If you are running IBM Tivoli Netcool/OMNIbus V7.4.0, youmust have Fix Pack 1 or later installed.

probe-nonnative-base-13

Note: probe-nonnative-base-13 does not require probe-sdk-java installation prior to nonnative installation. For IBM TivoliNetcool/OMNIbus V7.4.0 and higher the probe-sdk-java iscompiled in the COI package to include probe-nonnative-base-13 and therefore does not require installation of probe-sdk-java.

Java 1.6 (this is supplied with Netcool/OMNIbus V7.4.0).

If you are using Config Analyser you must install tools-config-analyser-1_2.

Connection method EIF Java API

Remote connectivity The probe can remotely connect to a Tivoli device.

Multicultural support Available

Peer-to-peer failoverfunctionality

Available

IP environment IPv4 and IPv6

Federal Information ProcessingStandards (FIPS)

IBM Tivoli Netcool/OMNIbus uses the FIPS 140-2 approvedcryptographic provider: IBM Crypto for C (ICC) certificate 384 forcryptography. This certificate is listed on the NIST website at http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htm. For details about configuring Netcool/OMNIbus for FIPS 140-2 mode, see the IBM Tivoli Netcool/OMNIbusInstallation and Deployment Guide.

2 IBM® Tivoli® Netcool/OMNIbus Probe for Tivoli EIF: Reference Guide

http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htm



Installing probesAll probes are installed in a similar way. The process involves downloading the appropriate installationpackage for your operating system, installing the appropriate files for the version of Netcool/OMNIbusthat you are running, and configuring the probe to suit your environment.

The installation process consists of the following steps:

1. Downloading the installation package for the probe from the Passport Advantage Online website.

Each probe has a single installation package for each operating system supported. For details abouthow to locate and download the installation package for your operating system, visit the following pageon the IBM Tivoli Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_download_intro.html

2. Installing the probe using the installation package.

The installation package contains the appropriate files for all supported versions of Netcool/OMNIbus.For details about how to install the probe to run with your version of Netcool/OMNIbus, visit thefollowing page on the IBM Tivoli Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_install_intro.html

3. Configuring the probe.

This guide contains details of the essential configuration required to run this probe. It combines topicsthat are common to all probes and topics that are peculiar to this probe. For details about additionalconfiguration that is common to all probes, see the IBM Tivoli Netcool/OMNIbus Probe and GatewayGuide.

Running the Configuration AnalyserEach probe that supports the Configuration Analyser is supplied with a JAR file(probe_name.check.jar). This file contains details of the tests to be performed and a set of predefinedmessages library. Using this JAR file, the analyser runs the tests against the probe configuration test file,and writes the related messages taken from the messages library to the probe log file.

When the probe launches the Configuration Analyser, the analyser runs a series of checks on the probe.The resultant output is stored in $OMNIHOME/log/probe_name.check.log (the test file).

The Configuration Analyser checks the syntax of the test file against the rules defined in the $OMNIHOME/probes/arch/ConfigAnalyser.xsd file.

The Configuration Analyser then runs sequentially through all the tests detailed in the xml file inside$OMNIHOME/probes/arch/probe_name.check.jar, outputting any appropriate suggestions from theinternationalized message file also in the jar file.

Checks performed by the Configuration Analyser

The Configuration Analyser performs the following checks for all probes:

• Whether the primary ObjectServer is running.• Whether the rules and properties files are present.• Whether a secondary ObjectServer is configured.• Whether the Probes Rules Syntax Checker is installed.• Whether the rules file is syntactically correct.• Whether there is space for log files.

All other tests that the analyser performs are specific to each individual probe.

Probe for IBM Tivoli EIF 3





Running the Configuration Analyser on UNIX and Linux operating systems

To run the Configuration Analyser on UNIX and Linux operating systems, run the probe from the commandline using -check as an additional argument.

Note: You can specify additional arguments on the command line along with -check; these will overrideany equivalent settings found in the properties file.

Running the Configuration Analyser on Windows operating systems

The way you run the Configuration Analyser on Windows operating systems depends on how you run theprobe.

If you run the probe using a batch file, run the following command:

probe_batch -check

Note: You can specify additional arguments on the command line along with -check; these will overrideany found in the properties file.

Where probe_batch is the name of the batch file that you use to run the probe.

If you run the probe directly, without using a batch file, run the following command:

run_analyser.bat -probebin probe_script -probename probe_name

Where probe_script is the probe binary name or the launcher script and probe_name is the name ofthe probe binary without the nco_p_ prefix.

Note: You can specify additional arguments on the command line along with -check; these will overrideany found in the properties file. For example, the following command runs the Configuration Analyser onthe ODBC Probe specifying that the server is set to RAG:

run_analyser.bat -probebin nco_p_odbc -probename odbc -server RAG

Configuration Analyser Log file

On completion of these tests, the Configuration Analyser outputs a status message. This status messagestates that either all the tests were successful, or that details of any configuration errors or suggestionshave been written to the probe log file $OMNIHOME/log/probe_name.check.log.

Consult the log file for information about how to correct or improve the configuration of the probe.

Integrating the Probe for IBM Tivoli EIF with IBM Tivoli monitoring devicesYou can integrate the Probe for IBM Tivoli EIF with all IBM Tivoli Monitoring (ITM) devices by editing thestandard rules file (tivoli_eif.rules) supplied with the probe. This enables the probe to use thevirtualization and predictive events capabilities of ITM.

To integrate the Probe for IBM Tivoli EIF with other IBM Tivoli monitoring devices use the following steps:

1. Set up event forwarding to the ObjectServer on the device you want the Probe for IBM Tivoli EIF tomonitor.

2. Copy the subordinate rules file from the $NCHOME/omnibus/extensions directory to the followingprobe directory:

$OMNIHOME/probes/arch/

Note: Additional rules are available in the Probe Extension Package. For more information aboutdownloading and using these additional rules, see the IBM Tivoli Netcool/OMNIbus Probe ExtensionPackage (SC27-5682-00).

3. Edit the tivoli_eif.rules file to include the subordinate rules file in the Probe for IBM Tivoli EIFmonitoring process.

4. Restart the probe.


Configuring the Probe for IBM Tivoli EIF rules fileThe tivoli_eif.rules file contains a set of commented-out include statements, each of whichdeclares a subordinate rules file. To enable the Probe for IBM Tivoli EIF to monitor the target device, thecommented-out include statement must be uncommented so that the probe includes the target devicewhen monitoring events.

When a subordinate rules file is included in the tivoli_eif.rules file the probe will read this file in$OMNIHOME/probes/arch/ and monitor events generated on the target device.

Note: The following rules have been moved to the Probe Extensions Package; tivoli_eif_tpc.rules,tivoli_eif_tsm.rules and tivoli_eif_tec.rules. Where the $NC_PROBE_EXT is the homedirectory of the Probe Extension Package installation.

The following code extract from the rules file shows an example of these commented-out includestatements:

# include "tivoli_eif_virtualization_pt1.rules"

# include "tivoli_eif_zos_tbsm.rules"

# include "$NC_PROBE_EXT/eif/IBM_TPC/tivoli_eif_tpc.rules"

# include "$NC_PROBE_EXT/eif/IBM_TSM/tivoli_eif_tsm.rules"

# include "tivoli_eif_taddm.rules"

# include "$NC_PROBE_EXT/eif/IBM_TEC/tivoli_eif_tec.rules"

# include "itm_event.rules"

# include "kvm_tbsm.rules"

# include "predictive_event.rules"

# include "tivoli_eif_virtualization_pt2.rules"

# include "kd4_tbsm.rules"

# include "zos_event.rules"

# include "zos_event_user_defined.rules"

# include "zos_identity.rules"

Note: Both virtualization rules files are supplied with Netcool/OMNIbus V7.4.0, so this functionality isonly supported with Netcool/OMNIbus V7.4.0 or later.

Configuring the ObjectServer to manage events from TECThis section describes how to configure the ObjectServer to map all Tivoli Enterprise Console (TEC) fieldsto Netcool/OMNIbus ObjectServer fields.

To map all TEC fields to IBM Tivoli Netcool/OMNIbus ObjectServer fields, you must add some extra fieldsto the ObjectServer.

Note: If you have already installed the Netview to OMNIbus or TEC to OMNIbus SQL updates, you do notneed to perform this step.

On UNIX platforms, run the following command:

$OMNIHOME/bin/nco_sql -user user -password password -server server_name <$NC_PROBE_EXT/eif/IBM_TEC/tec_db_update.sql

On Windows, run the following commands:

%NCHOME%\bin\redist\isql.exe -S server_name -U username -P password <%NC_PROBE_EXT%\eif\IBM_TEC\tec_db_update.sql


For example:

"%NCHOME%\bin\redist\isql.exe" -S NCOMS -U root -P "" < %NC_PROBE_EXT%\eif\IBM_TEC\tec_db_update.sql

Note: You need to update the tivoli_eif_tec.rules and tec_db_update.sql to take account ofthe additional fields.

Using different connection modes to receive eventsThere are two connection modes on top of the transport mechanism, connection-less (CL) andconnection-oriented (CO). Events processed by the Probe for Tivoli EIF are not processed in the order inwhich the events are sent. This may effect custom triggers that process events in a specific sequence ororder.

Connection-less

In connection-less mode, the source establishes a TCP/IP connection to the receiver, sends one EIFmessage and immediately closes the connection. If the sender is required to send another message, itestablishes a new TCP/IP connection to the receiver, sends one EIF message and again immediatelycloses the connection.

Connection-oriented

In connection-oriented mode, the source establishes a TCP/IP connection to the receiver, sends an EIFmessage, after which the connection remains open. If the sender is required to send another message, itsimply uses the already established connection. In either case, the TCP/IP protocol takes care ofassembling the data stream in the correct order and resending packets if there are problems duringtransmission.

Data acquisitionWhen the Probe for Tivoli EIF starts, it monitors the port specified in the properties file, and uses the EIFJava API to receive and parse the events. Based on these events, the probe generates alerts and sendsthem to the ObjectServer.

Note: The events that the probe receives must have alphanumeric class names and attribute names. Theprobe considers events that contain class names or attribute names that are solely numeric as malformedand discards them, unless you set the HandleMalformedAlarms property to true.

The following topics describe how the probe acquires data:

• “Unicode Transformation Format (UTF-8) mode on Windows” on page 6• “Probe operation” on page 7• “Threading” on page 7• “Heartbeat events” on page 7• “Data stream capture” on page 7• “Parsing malformed alarms” on page 8• “Peer-to-peer failover functionality” on page 8

Unicode Transformation Format (UTF-8) mode on WindowsUnicode Transformation Format (UTF-8) encoding is a variable length character encoding for Unicode. Itcan represent any character in the Unicode standard.

If you are running the probe on a Windows machine and want to use UTF-8 mode, you must set the -utf8enabled command line option. This controls how the inputs to the probe (for example, the


properties file, rules file, and event stream) are encoded and how the probe encodes its output (forexample, log files and events). When -utf8enabled is set to TRUE, these inputs are UTF8 encoded.

Note: This command line option is only used by the Windows version of this probe.

Probe operationThe probe receives alarms from the IBM Tivoli EIF device through the OMNIBUS TEC Java API(subsequently referred to in this guide as EIF Java API). It then sends the parsed data to theObjectServer.

The following overview outlines how the probe interacts with the device:

1. The probe starts.2. The probe listens to the port specified by the PortNumber property using the EIF Java API.3. The IBM Tivoli EIF device sends events to the configured port number.4. The probe listens for events.5. The probe reads and parses any available data.6. The probe sends the alerts generated to the ObjectServer.

ThreadingThe probe comprises two types of threads: one set of threads (the thread pool) to process events readfrom a client; and one thread to send the structured events to the ObjectServer.

Heartbeat eventsThe probe has a heartbeat facility that allows it to send an event to the Tivoli EIF device.

You can specify the frequency (in seconds) with which the probe sends a heartbeat event to the Tivoli EIFdevice using the EIFHeartBeatInterval property. This heartbeat event can be used to check that theprobe is gathering events from the Tivoli EIF device.

You can configure the probe to shutdown if it detects that the probe is not gathering Tivoli EIF events byusing the EIFHeartBeatFailures property. Set the number of successive heartbeat failures the probecounts before automatically shutting down. If you set the property to 0, the probe will not automaticallyshut down.

If you set the EIFHeartBeatInterval property to 0, the probe will not generate heartbeat intervalmessages and will ignore the value set for the EIFHeartBeatFailures property. The probe will notgenerate heartbeat messages and therefore, will not detect failures, and will not shut down automatically.

Data stream captureThe Probe for Tivoli EIF can capture the data stream sent to it from a TEC Adapter or an IBM TivoliMonitoring (ITM) device. This data is stored in a log file and can be used for debugging purposes, todevelop new features for the probe, or to pass to other management systems that require the same data.To enable stream capture, set the StreamCapture property to true and specify a log file to store the datausing the StreamCaptureFilename property.

Note: The data stream capture function generates a lot of data and should be used with caution. Whenyou no longer require data for debugging, set the StreamCapture property to false to disable the streamcapture function.

Example data stream capture file settingsThe following example shows the stream capture settings used to log events to the default location:

1. Specify the following properties in the properties file $OMNIHOME/probes/arch/tivoli_eif.props:

PortNumber : 9999MessageLevel : "debug"StreamCapture : "true"


2. Start the probe using the following command:

$OMNIHOME/probes/nco_ p_tivoli_eif -messagelog stdout -messagelevel debug

The probe processes the incoming events and the streamcapture file is found in $OMNIHOME/var/

Logging stream capture to a specified location

The following example shows the stream capture settings used to log events to a specific location:

1. Specify the following properties in the properties file $OMNIHOME/probes/arch/tivoli_eif.props:

PortNumber : 9999MessageLevel : "debug"StreamCapture : "true"StreamCaptureFilename : "./testcapture"

2. Start the probe with the following command:

$OMNIHOME/probes/nco_p_tivoli_eif -messagelog stdout -messagelevel debug

The probe processes the incoming events and the streamcapture file is found in the current workingdirectory.

Parsing malformed alarmsThe Probe for Tivoli EIF can perceive an alarm that has a back slash (\) in its messages as a malformedalarm. However, parsing of these malformed alarms occurs only when the HandleMalformedAlarmsproperty is set to true. If the property is set to false, the probe rejects the malformed alarms and sends anerror message.

The Probe for Tivoli EIF only accepts ClassName in the following forms:

• 'a-z'• 'A-Z'• '0-9'• '_'• '.'

Note: Alarms with any other characters such as '\' or '/' will be treated as invalid.

Peer-to-peer failover functionalityThe probe supports failover configurations where two probes run simultaneously. One probe acts as themaster probe, sending events to the ObjectServer; the other acts as the slave probe on standby. If themaster probe fails, the slave probe activates.

While the slave probe receives heartbeats from the master probe, it does not forward events to theObjectServer. If the master probe shuts down, the slave probe stops receiving heartbeats from the masterand any events it receives thereafter are forwarded to the ObjectServer on behalf of the master probe.When the master probe is running again, the slave probe continues to receive events, but no longer sendsthem to the ObjectServer.

Example property file settings for peer-to-peer failover

You set the peer-to-peer failover mode in the properties files of the master and slave probes. The settingsdiffer for a master probe and slave probe.

Note: In the examples, make sure to use the full path for the property value. In other words replace$OMNIHOME with the full path. For example: /opt/IBM/tivoli/netcool.

The following example shows the peer-to-peer settings from the properties file of a master probe:


Server : "NCOMS" RulesFile : "master_rules_file"MessageLog : "master_log_file"PeerHost : "slave_hostname"PeerPort : 6789 # [communication port between master and slave probe]Mode : "master"PidFile : "master_pid_file"

The following example shows the peer-to-peer settings from the properties file of the corresponding slaveprobe:

Server : "NCOMS" RulesFile : "slave_rules_file"MessageLog : "slave_log_file"PeerHost : "master_hostname"PeerPort : 6789 # [communication port between master and slave probe]Mode : "slave"PidFile : "slave_pid_file"

Deploying the probe using a TCP load balancerLoad balancing is a computer networking method used to distribute workload across multiple computers.It is used to provision probe capacity for the reception of EIF messages.

Note: The events that the probe receives must have alphanumeric class names and attribute names. Theprobe considers events that contain class names or attribute names that are solely numeric as malformedand discards them, unless the HandleMalformedAlarms property is set to true.

Properties and command line optionsYou use properties to specify how the probe interacts with the device. You can override the default valuesby using the properties file or the command line options.

The following table describes the properties and command line options specific to this probe. For moreinformation about generic Netcool/OMNIbus properties and command line options, see the IBM TivoliNetcool/OMNIbus Probe and Gateway Guide.

Table 4. Properties and command line options

Property name Command line option Description

EIFDebugFileName string -eifldebugfilename string Use this property to specify thepath to the debug file generatedby the Java API.

The default is $OMNIHOME/var/debug_eif.trc.


Table 4. Properties and command line options (continued)


EIFDebugLevel string -eifdebuglevel string Use this property to specifywhether or not the Java APIgenerates debug messages. Thisproperty takes the followingvalues:

ALL: The EIF Java API generatesdebug messages of all types(WARN, FATAL, DEBUG, INFO,and ERROR).

NO: The API generates no debugmessages.

The default is NO.

EIFHeartBeatInterval integer -eifHeartBeatInterval integer Use this property to specify thefrequency (in seconds) that theprobe sends a heartbeatmessage through the probe EIFlayer.

The default is 0 (which instructsthe probe to not send heartbeatmessages to the device).

EIFHeartBeatFailures integer -eifHeartBeatFailures integer Use this property to specify thenumber of successive EIFheartbeat failures that the probedetects before shutting downautomatically.

The default is 0 (which instructsthe probe to ignore heartbeatfailures).

EIFReadRetryInterval integer -eifReadRetryInterval integer Use this property to specify thetime (in seconds) that the EIFAPI waits to receive eventsbefore retrying the connection.

The default is 120.

Note: See ReadRetryInterval ifusing the Probe for IBM TivoliEIF V9 or lower.

EIFLogFileName string -eiflogfilename string Use this property to specify thepath of the log file generated bythe EIF Java API.

The default is $OMNIHOME/var/tivoli_eif.log.




EIFLogLevel string -eifloglevel string Use this property to specifywhether or not the EIF Java APIgenerates log messages. Thisproperty takes the followingvalues:

ALL: The EIF Java API generateslog messages of all types(WARN, FATAL, DEBUG, INFO,and, ERROR).

NO: The API generates no logmessages.

The default is NO.

EIFTraceFileName string -eiftracefilename string Use this property to specify thepath of the trace file generatedby the EIF Java API.

The default is $OMNIHOME/var/tivoli_eif.trc.

EIFTraceLevel string -eiftracelevel string Use this property to specifywhether or not the EIF Java APIgenerates trace messages. Thisproperty takes the followingvalues:

ALL: The EIF Java API generatestrace messages of all types(WARN, FATAL, DEBUG, INFO,and ERROR).

NO: The API generates no tracemessages.

The default is NO.

EventCopies integer -eventcopies integer Use this property to specify thenumber of times the probe mustsend each event to theObjectServer.

The default is 1.

FlushBufferInterval integer -flushbufferinterval integer Use this property to specify howoften (in seconds) the probeflushes all alerts in the buffer tothe ObjectServer.

The default is 0 (which instructsthe probe to never flush thealerts to the ObjectServer).




HandleMalformedAlarmsstring

-handlemalformedalarms (This isequivalent toHandleMalformedAlarms with avalue of true.)

-nohandlemalformedalarms (This isequivalent toHandleMalformedAlarms with avalue of false.)

Use this property to specifywhether the probe parsesmalformed alarms from IBMTivoli TEC. This property takesthe following values:

false: The probe does not parsemalformed alarms.

true: The probe parsesmalformed alarms.

The default is true.

MaxEventQueueSize integer -maxeventqueuesize integer Use this property to specify themaximum number of events thatcan be queued between thenative process and theObjectServer.

The default is 10000.

PortMapper string -portmapper (This is equivalent toPortMapper with a value of true.)

-noportmapper (This is equivalent toPortMapper with a value of false.)

Use this property to specifywhether or not the proberegisters with a port mapper.

The default is false.

Note: This property is notavailable when running the probeon Windows operating systems.

PortMapperNumber integer -portmappernumber integer Use this property to specify theidentifier that the probe will useto register with the port mapper.

The default is 100033057 (whichallows the probe to appear to bea TEC server).

Note: This property is notavailable when running the probeon Windows operating systems.

PortNumber integer -portnumber integer Use this property to specify theactive port to which the probelistens for connections from thehost system.

The default is 9998.




ReadRetryInterval integer -readretryinterval integer Use this property to specify thetime (in seconds) that the EIFAPI waits to receive eventsbefore retrying the connection.

The default is 120.

Note: The ReadRetryIntervalproperty is valid with the Probefor IBM Tivoli EIF V11 but it is adeprecated property for thepurpose of backwardcompatibility. The properties filefor the Probe for IBM Tivoli EIFversion 9 and earlier contains theReadRetryInterval property. Ifyou are using an older propertiesfile you will not have any issuesstarting the probe due to thisproperty. EIFReadRetryIntervalis the equivalent property for theProbe for IBM Tivoli EIF version11.

StreamCapture string -streamcapture (This is equivalent toStreamCapture with a value oftrue.)

-nostreamcapture (This is equivalentto StreamCapture with a value offalse)

Use this property to specifywhether the stream capturefeature is enabled for debuggingpurposes. This property takesthe following values:

false: The probe disables thestream capture feature.

true: The probe enables thestream capture feature.

The default is false.

Note: If you set this property totrue, the probe stores the data inthe file specified in theStreamCaptureFile property.When you no longer require datafor debugging, set theStreamCapture property to falseto disable the stream capturefunction.

StreamCaptureFile string -streamcapturefile string Use this property to specify thefile the probe uses to store theinput data stream.

The default is $OMNIHOME/var/tivoli_eif.stream.




N/A -utf8enabled string Use this command line option tocontrol the encoding of data thatis passed into, or generated by,the Windows version of theprobe .

Set this command line option toTRUE to run the probe in UTF-8mode.

The default is FALSE (whichinstructs the probe to use thedefault system code page).

ElementsThe probe breaks event data down into tokens and parses them into elements. Elements are used toassign values to ObjectServer fields; the field values contain the event details in a form that theObjectServer understands.

Static elements

The following table describes the elements that the probe generates. Not all the elements described aregenerated for each event; the elements that the probe generates depend on the event type.

Table 5. Static elements

Element name Element description

$ClassName This element contains the class name of the event.

$EventSeqNo This element indicates the sequence number of the event.

$EventString This element contains the entire event in a single string.

Dynamic elements

The probe also creates dynamic elements. Creation of these elements depends on how an alarm isdefined within Tivoli EIF. There is no guarantee that you will find all these elements with every alarm youencounter. Generic alarms have all of them.

The following table describes the elements that the probe generates. Not all the elements described aregenerated for each event; the elements that the probe generates depend on the event type.

Table 6. Dynamic elements


$date This element contains the date of the event in mm/dd/yyformat.

$EventClass This element indicates the class of the event as assignedby the event source. The probe uses this to identify theformat of the message for each event type.

$hostname This element contains the host name of the system.

$msg This element contains the content of the message.


Table 6. Dynamic elements (continued)


$peerhost This element identifies the secondary host.

$severity This element indicates the severity of the alarm.

$source This element indicates the type of application that hascreated the event.

$sub_origin This element contains the optional sub-categorization ofthe event origin.

$sub_source This element contains a detailed description of the source.

Error messagesError messages provide information about problems that occur while running the probe. You can use theinformation that they contain to resolve such problems.

The following table describes the error messages specific to this probe. For information about genericNetcool/OMNIbus error messages, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide.

Table 7. Error messages

Error message Description Action

Failed to open streamcapture file

Failed to write tostream capture file

Failed to closestream capture file

The probe could not open, writeto, or close the stream capturefile even though the streamcapture is enabled.

Check that the file namespecified by theStreamCaptureFile property inthe properties file is valid.

Check that the file and directorypermissions are set correctly.

Check that there is enough spaceon the disk.

Check that the file is not beingused by another application.

Failed to parse event

The probe was unable to parsethe data specified.

Check that the device is runningproperly.

Handling malformed alarms disabled. Discarding thisevent

The probe has discardedmalformed alarms as specified bythe settings.

Change the value of theHandleMalformedAlarmsproperty to true to allowmalformed alarms to be parsed.

Invalid event The probe found that the eventwas not in the correct format.

Check that the sender complieswith the EIF message format.

Error messages generated by the Configuration Analyser

The following table describes the error messages generated by the Configuration Analsyer.


Table 8. Error messages

Error message Description Action

An error has caused theprogram to terminateabnormally. Please re-runit and set CheckLevel toDEBUG_MIN in the probeproperties file, and thencheck $OMNIHOME/log/probe_name.check.log formore details.

There was an internal error in theConfiguration Analyser.

Check the $OMNIHOME/log/probe_name.check.log filefor more details.

Parse Error: ****** There was a parsing error in thetest XML file shipped with theprobe.

Check that $OMNIHOME/probes/arch/configAnalyser.xsd exists.

Check that $OMNIHOME/probes/arch/probe_name.check.jarexists.

If the problem persists acrossseveral probes, reinstall theConfiguration Analyser.Otherwise, reinstall the probe.

ProbeWatch messagesDuring normal operations, the probe generates ProbeWatch messages and sends them to theObjectServer. These messages tell the ObjectServer how the probe is running.

The following table describes the ProbeWatch messages that the probe generates. For information aboutgeneric Netcool/OMNIbus ProbeWatch messages, see the IBM Tivoli Netcool/OMNIbus Probe andGateway Guide.

Table 9. ProbeWatch messages

ProbeWatch message Description Triggers or causes

Unable to get events; Caused by: EIF Hearbeat failures exceeded: no events received for HeartBeatInterval seconds.

The number of heartbeat failuresspecified by theEIFHeartBeatFailures propertyhas been exceeded and theprobe will shut down.

The probe will automaticallyshutdown when the number offailed heartbeat messagesexceeds the number specified bythe EIFHeartbeatFailuresproperty.

Failed to open stream capture file

Failed to write to stream capture file

Failed to close stream capture file

The probe has encountered anerror with the stream capture file.

The specified file name or the setfile permissions are incorrect.

Going down The probe is shutting down. The probe is shutting down afterreceiving a CTRL-C command.


Table 9. ProbeWatch messages (continued)

ProbeWatch message Description Triggers or causes

EIF Heartbeat test failed

Unhandled EIFHeartbeat Port

The probe has failed to send aheartbeat interval message to theTivoli EIF device.

The probe is not receiving eventsfrom Tivoli EIF.

The probe shuts downautomatically when the numberof failed heartbeat messagesexceeds the number specified bythe EIFHeartbeatFailuresproperty.

Running The probe has started. The probe has started.

Known IssuesThe following issue is a known problem with Probe for IBM Tivoli EIF.

The probe fails to shutdown the probe-nonnative wrapper cleanly under Windows PA control

To work around the problem you must configure the process agent configuration file. The process agentsare programmes that manage a process within the system. To shut down the probe-nonnative wrappercleanly under Windows PA control you must specify the following command in the process agentconfiguration file:

Command '%OMNIHOME%\probes\win32\nco_p_nonnative %NCHOME%\platform\win32\jre_1.5.6\jre\bin\javaw -Xrs -cp %OMNIHOME%\probes\win32\nco_p_tivoli_eif.jar;%OMNIHOME%\probes\win32\NSProbe.jar;%OMNIHOME%\java\jars\evd.jar;%OMNIHOME%\java\jars\log.jar nco_p_tivoli_eif' run as 0

The default process agent configuration file is in the following location: $NCHOME/omnibus/etc/nco_pa.conf

For more information about configuring the process agent configuration file, see Administration the servercomponents in the Netcool/OMNIbus Administration Guide (SC23-9681-00).


Appendix A. Notices and TrademarksThis appendix contains the following sections:

• Notices• Trademarks

NoticesThis information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries.Consult your local IBM representative for information on the products and services currently available inyour area. Any reference to an IBM product, program, or service is not intended to state or imply that onlythat IBM product, program, or service may be used. Any functionally equivalent product, program, orservice that does not infringe any IBM intellectual property right may be used instead. However, it is theuser's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document.The furnishing of this document does not grant you any license to these patents. You can send licenseinquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual PropertyDepartment in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing 2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATIONPROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer ofexpress or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodicallymade to the information herein; these changes will be incorporated in new editions of the publication.IBM may make improvements and/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not inany manner serve as an endorsement of those Web sites. The materials at those Web sites are not part ofthe materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:

© Copyright IBM Corp. 2011, 2017 19

IBM CorporationSoftware Interoperability Coordinator, Department 49XA3605 Highway 52 NRochester, MN 55901U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases,payment of a fee.

The licensed program described in this information and all licensed material available for it are providedby IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, orany equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements may havebeen made on development-level systems and there is no guarantee that these measurements will be thesame on generally available systems. Furthermore, some measurements may have been estimatedthrough extrapolation. Actual results may vary. Users of this document should verify the applicable datafor their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal withoutnotice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subject to change withoutnotice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject to change before theproducts described become available.

This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms.

Each copy or any portion of these sample programs or any derivative work, must include a copyrightnotice as follows:© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©Copyright IBM Corp. _enter the year or years_. All rights reserved.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

TrademarksIBM, the IBM logo, ibm.com, AIX, Tivoli, zSeries, and Netcool are trademarks of International BusinessMachines Corporation in the United States, other countries, or both.


Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-based trademarks are eitherregistered trademarks or trademarks of Adobe Systems Incorporated in the United States, othercountries, or both.

Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation in the United States,other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in theUnited States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, othercountries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, or service names may be trademarks or service marks of others.

Notices and Trademarks 21

IBM®

SC22-5421-03

IBM...IBM® Tivoli® Netcool/OMNIbus Probe for Tivoli EIF Version 13.0 Reference Guide March 14,...

Documents

Transcript of IBM...IBM® Tivoli® Netcool/OMNIbus Probe for Tivoli EIF Version 13.0 Reference Guide March 14,...