IBM Tivoli Netcool/OMNIbus: Event Integration Facility ... · v IBM T ivoli Netcool/OMNIbus...

Netcool/OMNIbusVersion 8 Release 1

Event Integration Facility Reference

SC27-6267-00

IBM

Netcool/OMNIbusVersion 8 Release 1

Event Integration Facility Reference

SC27-6267-00

IBM

NoteBefore using this information and the product it supports, read the information in “Notices” on page 79.

This edition applies to version 8, release 1 of IBM Tivoli Netcool/OMNIbus (product number 5724-S44) and to allsubsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2003, 2017.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this publication . . . . . . . . vIntended audience . . . . . . . . . . . . vPublications . . . . . . . . . . . . . . vAccessibility . . . . . . . . . . . . . . viiTivoli technical training . . . . . . . . . . viiSupport information . . . . . . . . . . . viiConventions used in this publication . . . . . . vii

Chapter 1. Overview of the Tivoli EventIntegration Facility . . . . . . . . . . 1Events . . . . . . . . . . . . . . . . 1Adapters . . . . . . . . . . . . . . . 2Event classes . . . . . . . . . . . . . . 3Configuration files . . . . . . . . . . . . 3Event server . . . . . . . . . . . . . . 4Event filtering . . . . . . . . . . . . . . 6Rules . . . . . . . . . . . . . . . . . 6

Chapter 2. Installing the EventIntegration Facility . . . . . . . . . . 7Directory structure . . . . . . . . . . . . 8Migrating adapters . . . . . . . . . . . . 10Setting up the posteifmsg utility on z/OS using USS 10

Chapter 3. Event transport . . . . . . 13Event delivery methods . . . . . . . . . . 13

Connection options . . . . . . . . . . . 13Transport options . . . . . . . . . . . 14Testing and scripting . . . . . . . . . . 18

Event reception for applications . . . . . . . 22Sending events through firewalls . . . . . . . 23Event delivery when systems fail . . . . . . . 24

Activating the cache . . . . . . . . . . 24Configuring backup servers to deliver events . . 25Using the portmapper keywords . . . . . . 26Configuring a reception application built withthe C API . . . . . . . . . . . . . . 27

Chapter 4. Building an adapter . . . . 29Adapter files . . . . . . . . . . . . . . 29Identifying events to monitor . . . . . . . . 29Defining the source. . . . . . . . . . . . 30Defining event classes . . . . . . . . . . . 30Selecting event delivery methods . . . . . . . 31

Configuring an EIF receiver application for SSL 32Configuring an EIF client application for SSL . . 33

Programming the adapter . . . . . . . . . 35Upgrading existing adapters. . . . . . . . 36Configuration file APIs . . . . . . . . . 37Communications APIs . . . . . . . . . . 37Special considerations for Microsoft Windows . . 37Compiling the adapter built with the C API . . 38Linking the adapter built with the C API . . . 38

Installing, configuring, and testing the adapter . . 39

Running adapters built with the Event IntegrationFacility Java API. . . . . . . . . . . . . 39Configuring adapters for international environments 40

Chapter 5. Filtering events at thesource . . . . . . . . . . . . . . . 41Filtering with configuration files . . . . . . . 41

Filtering events when systems fail . . . . . . 42Regular expressions in filters . . . . . . . 43

Chapter 6. Troubleshooting . . . . . . 45Message logs . . . . . . . . . . . . . . 45Trace logs . . . . . . . . . . . . . . . 45Performance and availability . . . . . . . . 47

Event reception connection parameters . . . . 47Common problems and scenarios . . . . . . . 48

Building and running adapters . . . . . . . 48Making connections to the event server . . . . 49Sending events . . . . . . . . . . . . 49

Appendix A. Application programminginterfaces . . . . . . . . . . . . . 51C language API . . . . . . . . . . . . . 51

tec_agent_getenv . . . . . . . . . . . 51tec_agent_init. . . . . . . . . . . . . 51tec_create_EIF_handle . . . . . . . . . . 52tec_create_handle . . . . . . . . . . . 53tec_create_handle_c. . . . . . . . . . . 54tec_create_handle_r . . . . . . . . . . . 55tec_destroy_handle . . . . . . . . . . . 56tec_errno . . . . . . . . . . . . . . 56tec_get_event . . . . . . . . . . . . . 56tec_put_event. . . . . . . . . . . . . 57tec_register_callback . . . . . . . . . . 57

Appendix B. Utilities for the C API . . . 59ed_scan_get_n . . . . . . . . . . . . . 59ed_scan_n . . . . . . . . . . . . . . . 59ed_sleep . . . . . . . . . . . . . . . 60

Appendix C. Java language API . . . . 61disconnect . . . . . . . . . . . . . . . 61disconnect(time) . . . . . . . . . . . . . 61getConfigVal . . . . . . . . . . . . . . 61onMessage . . . . . . . . . . . . . . 62receiveEvent . . . . . . . . . . . . . . 62registerListener . . . . . . . . . . . . . 63sendEvent . . . . . . . . . . . . . . . 63TECAgent . . . . . . . . . . . . . . . 64TECEvent . . . . . . . . . . . . . . . 64

© Copyright IBM Corp. 2003, 2017 iii

Appendix D. Configuration keywords 67

Notices . . . . . . . . . . . . . . 79Trademarks . . . . . . . . . . . . . . 81

Index . . . . . . . . . . . . . . . 83

iv IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

About this publication

The Tivoli Event Integration Facility Reference contains reference material for theEvent Integration Facility toolkit (EIF).

Intended audienceThis guide explains the concepts to effectively develop new adapters or modifyexisting ones. This book is for developers who have programming knowledge andneed to create custom adapters and use the Tivoli Event Integration Facility withintheir applications. This book is also useful for Tivoli Netcool/OMNIbusadministrators who modify configuration files.

Readers should be familiar with the following software:v Java™ or C programming languagesv UNIX, Microsoft Windows, or other target operating systems

PublicationsThis section lists publications in the Tivoli Netcool/OMNIbus library and relateddocuments. The section also describes how to access Tivoli publications online andhow to order Tivoli publications.

Your Tivoli Netcool/OMNIbus library

The following documents are available in the Tivoli Netcool/OMNIbus library:v IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide,

Includes installation and upgrade procedures for Tivoli Netcool/OMNIbus, anddescribes how to configure security and component communications. Thepublication also includes examples of Tivoli Netcool/OMNIbus architectures anddescribes how to implement them.

v IBM Tivoli Netcool/OMNIbus Administration Guide,Describes how to perform administrative tasks using the TivoliNetcool/OMNIbus Administrator GUI, command-line tools, and process control.The publication also contains descriptions and examples of ObjectServer SQLsyntax and automations.

v IBM Tivoli Netcool/OMNIbus Web GUI Administration and User's Guide,Describes how to perform administrative and event visualization tasks using theTivoli Netcool/OMNIbus Web GUI.

v IBM Tivoli Netcool/OMNIbus User's Guide,Provides an overview of the desktop tools and describes the operator tasksrelated to event management using these tools.

v IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide,Contains introductory and reference information about probes and gateways,including probe rules file syntax and gateway commands.

v IBM Tivoli Monitoring for Tivoli Netcool/OMNIbus Agent User's Guide,Describes how to install the health monitoring agent for TivoliNetcool/OMNIbus and contains reference information about the agent.

v IBM Tivoli Netcool/OMNIbus Event Integration Facility Reference,

© Copyright IBM Corp. 2003, 2017 v

Describes how to develop event adapters that are tailored to your networkenvironment and the specific needs of your enterprise. This publication alsodescribes how to filter events at the source.

v IBM Tivoli Netcool/OMNIbus Error Messages Guide,Describes system messages in Tivoli Netcool/OMNIbus and how to respond tothose messages.

v IBM Tivoli Netcool/OMNIbus Web GUI Administration API (WAAPI) User's Guide,Shows how to administer the Tivoli Netcool/OMNIbus Web GUI using the XMLapplication programming interface named WAAPI

v IBM Tivoli Netcool/OMNIbus ObjectServer HTTP Interface Reference Guide, Describesthe URIs and common behaviors of the Application Programming Interface(API) that is called the ObjectServer HTTP Interface. Describes how to enable theAPI and provides examples of JSON payloads, and HTTP requests andresponses.

v IBM Tivoli Netcool/OMNIbus ObjectServer OSLC Interface Reference Guide, Describesthe services, resources, and common behaviors of the Open Services for LifecycleCollaboration (OSLC) Application Programming Interface (API) that is called theObjectServer OSLC Interface. Describes how to enable the API and providesexamples of service provider definitions, RDF/XML payloads, and HTTPrequests and responses.If you use other IBM products to extend the functionality of TivoliNetcool/OMNIbus, such as DB2, IBM Tivoli Monitoring, or Tivoli CommonReporting, see the information center for that product to obtain relevantpublications.

Related publications

The following documents should be consulted when using the IBM® TivoliEnterprise Console® as event server. They are available in the IBM Tivoli EnterpriseConsole library:v IBM Tivoli Enterprise Console Adapters Guide, SC32–1242

Provides information about supported adapters, including how to install andconfigure these adapters.

Accessing terminology online

The IBM Terminology Web site consolidates the terminology from IBM productlibraries in one convenient location. You can access the Terminology Web site at thefollowing Web address:

http://www.ibm.com/software/globalization/terminology

Accessing publications online

IBM posts publications for this and all other Tivoli products, as they becomeavailable and whenever they are updated, to the Tivoli Downloads site at:

ftp://public.dhe.ibm.com/software/tivoli/Netcool/NetcoolOmnibus/library/

Note: If you print PDF documents on other than letter-sized paper, set the optionin the File > Print window that allows Adobe Reader to print letter-sized pages onyour local paper.

vi IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

http://www.ibm.com/software/globalization/terminology

ftp://public.dhe.ibm.com/software/tivoli/Netcool/NetcoolOmnibus/library/

AccessibilityAccessibility features help users with a physical disability, such as restrictedmobility or limited vision, to use software products successfully.

With this product, you can use assistive technologies to hear and navigate theinterface. You can also use the keyboard instead of the mouse to operate somefeatures of the graphical user interface.

Tivoli technical training

For Tivoli technical training information, refer to the following IBM TivoliEducation Web site:

http://www.ibm.com/software/tivoli/education

Support informationIf you have a problem with your IBM software, you want to resolve it quickly. IBMprovides the following ways for you to obtain the support you need:

OnlineGo to the IBM Software Support site at http://www.ibm.com/software/support/probsub.html and follow the instructions.

IBM Support AssistantThe IBM Support Assistant (ISA) is a free local software serviceabilityworkbench that helps you resolve questions and problems with IBMsoftware products. The ISA provides quick access to support-relatedinformation and serviceability tools for problem determination. To installthe ISA software, go to http://www.ibm.com/software/support/isa.

DocumentationIf you have a suggestion for improving the content or organization of thisguide, send it to the Tivoli Netcool/OMNIbus Information Developmentteam at:

mailto://[email protected]

Conventions used in this publicationThis publication uses several conventions for special terms and actions andoperating system-dependent commands and paths.

Typeface conventions

This publication uses the following typeface conventions:

Bold

v Lowercase commands and mixed case commands that are otherwisedifficult to distinguish from surrounding text

v Interface controls (check boxes, push buttons, radio buttons, spinbuttons, fields, folders, icons, list boxes, items inside list boxes,multicolumn lists, containers, menu choices, menu names, tabs, propertysheets), labels (such as Tip: and Operating system considerations:)

v Keywords and parameters in text

About this publication vii

http://www.ibm.com/software/tivoli/education

http://www.ibm.com/software/support/probsub.html

http://www.ibm.com/software/support/probsub.html

http://www.ibm.com/software/support/isa

mailto://[email protected]

Italic

v Citations (examples: titles of publications, diskettes, and CDs)v Words defined in text (example: a nonswitched line is called a

point-to-point line)v Emphasis of words and letters (words as words example: "Use the word

that to introduce a restrictive clause."; letters as letters example: "TheLUN address must start with the letter L.")

v New terms in text (except in a definition list): a view is a frame in aworkspace that contains data

v Variables and values you must provide: ... where myname represents....

Monospace

v Examples and code examplesv File names, programming keywords, and other elements that are difficult

to distinguish from surrounding textv Message text and prompts addressed to the userv Text that the user must typev Values for arguments or command options

Operating system-dependent variables and paths

This publication uses the UNIX convention for specifying environment variablesand for directory notation.

When using the Windows command line, replace $variable with %variable% forenvironment variables, and replace each forward slash (/) with a backslash (\) indirectory paths. For example, on UNIX systems, the $NCHOME environmentvariable specifies the path of the Netcool® home directory. On Windows systems,the %NCHOME% environment variable specifies the path of the Netcool homedirectory. The names of environment variables are not always the same in theWindows and UNIX environments. For example, %TEMP% in Windowsenvironments is equivalent to $TMPDIR in UNIX environments.

If you are using the bash shell on a Windows system, you can use the UNIXconventions.

viii IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

Chapter 1. Overview of the Tivoli Event Integration Facility

The Event Integration Facility is a toolkit that expands the types of events andsystem information that you can monitor. You can use it to develop your ownadapters, which are tailored to your environment. The Event Integration Facility isa separate installation package from the main Tivoli Netcool/OMNIbus product.

The Event Integration Facility contains an event application programming interface(API) library for use with the Java and C programming languages. It also containsa debugging function that checks event syntax and sends events to a file.

You can use Event Integration Facility to do the following tasks:v Specify the event information to send to the ObjectServer for processing.v Create an adapter to filter, translate, and then forward event information to the

event server.v Filter events near the source.v Create an application that can receive events.

EventsThe central unit of information is the event. An event is any change in the state ofa system resource or application. Events can be generated for problems and forsuccessful completions of tasks.

Events provide many different types of information, for example when a host isdown, when someone unsuccessfully tries to log in to a host as an administrator,or when a hard drive is nearly full. Events can also be generated to clear otherevents.

An event begins as an error message, a trap, or a similar piece of information thatis displayed or written to a file. The information provided in an event isdependent on the source. Some sources provide detailed information about anevent, while other sources are brief in their descriptions. The role of the adapter isto convert all events into a format that provides consistency in information, such asthe source, location, date, and time of an event.

Some events, such as traps, contain data that you cannot read. In these cases, theadapter must translate the data into a format that you can read so that theinformation can be further processed. Some sources, such as a system log file,provide data that you can read without machine translation.

Adapters translate event information into a set of attributes. Each attribute ispredefined by the adapter and contains the attribute name and the attribute value.The adapter places the appropriate information in each attribute, and then sendsthe event to the event server.

This following figure illustrates how an event evolves:

© Copyright IBM Corp. 2003, 2017 1

The following example shows how log file information is translated into events. Inthis example, a failed attempt to run the su root command on the host oak iswritten to the system log file. You can read the resulting format:Nov 7 08:51:42 oak su: 'su root’ failed for don on /dev/ttyp0

The adapter then translates the log file information into an event as follows:Su_Failure:source=LOGFILE;origin=oak;date=”Nov 7 08:51:42 ”;host=oak;sub_source=login;from_user=don;tty=/dev/ttyp0to_user=root;END

Related concepts:“Event server” on page 4An event server is a central server that handles all events collected by thedistributed adapters. The event server creates an entry for each incoming eventand evaluates that event against a set of rules to determine if it can respond to theevent, or modify the event automatically.

AdaptersAdapters are processes that monitor managed sources. A source may be anapplication such as a database, or a system resource such as disk space. When anadapter receives information from its source, the adapter formats the informationand forwards it to the event server.

To monitor a source such as a third-party or custom application, you must use theEvent Integration Facility to create an adapter and event classes for each newsource.

Adapters monitor sources in the following ways:v An adapter can receive messages from a source that actively produces messages.

For example, adapters can receive messages that are sent by Tivoli softwareapplications.

v An adapter can check a file at configurable intervals if the source updates a file.v An adapter can poll a system resource or system condition at configurable

intervals, and then interpret and forward the resulting information directly tothe event server.

event:

native format

event:

Tivoli format

To event server

System

Resource or

Application

Event

Adapter

Figure 1. Evolution of an event

2 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

Event classesEvent classes are classifications of events. After separating information into eventclasses, adaptors format the information into messages that represent specificinstances of event classes. Then they send the information to the event server,which processes the information, along with information received from otheradapters.

Event classes can be divided into subclasses to facilitate a further breakdown ofinformation so that more detailed rules can be applied to the event information.Essentially, event classes are an agreement between the adapter and the eventserver about what information the adapter sends to the event server.Related concepts:“Defining event classes” on page 30An important task when you create an adapter is to determine the event classes forthe information that you want to monitor. To help you when you write rules tohandle the events, you must make event definitions as specific as possible.

Configuration filesUse the configuration file to control the behavior of adapters. You do not need tomodify multiple instances of an adapter to run in different environments. Modifyonly the configuration files.

The configuration file controls the following parameters:v The information that must be sent to the event server.v The connection interface that is used by the adapter.v The host on which the event server is located.v The event filtering to be performed by the adapter.v Any information that is unique to a particular adapter.

After information is separated into event classes, the adapter sends the informationto the event server for further processing. To reduce the load on the network, usethe configuration file to control the information that the adapter sends to the eventserver.

The configuration parameters are controlled by keywords. A sample configurationfile that contains all the available keywords is installed with the Event IntegrationFacility, in the misc directory.Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.“Directory structure” on page 8The directory structure of the Event Integration Facility after you extract thecompressed files.

Chapter 1. Overview of the Tivoli Event Integration Facility 3

Event serverAn event server is a central server that handles all events collected by thedistributed adapters. The event server creates an entry for each incoming eventand evaluates that event against a set of rules to determine if it can respond to theevent, or modify the event automatically.

The ObjectServer acts as the event server for the Tivoli Event Integration Facility.

The EIF probe is the means by which EIF events are forwarded to the ObjectServer.

An adapter does not typically provide values for all attributes of a particular event;some attribute values are provided by the EIF probe. The Probe for Tivoli EIF canprocess any well-formed EIF event. You have the option to define the followingattributes:

$ClassNameThe class name of the event.

$EventSeqNoThe sequence number of the event.

$EventStringThe entire event in a single string.

$date The date of the event in mm/dd/yy format.

$EventClassThe class of the event as assigned by the event source.

Note: The Probe for Tivoli EIF uses the event class to identify the formatof the message for each event type.

$hostnameThe host name of the system.

$msg The content of the message.

$peerhostThe secondary host.

$severityThe severity of the alarm.

$sourceThe type of application that has created the event.

$sub_originThe optional subcategorization of the event origin.

$sub_sourceA detailed description of the source.

The following example event has been processed by the Probe for Tivoli EIF andthe Tivoli Netcool/OMNIbus ObjectServer:Node Alias: 8.42.19.243TECEventHandle:Process Required: 0Prec. Entity ID: 0First Occurrence: 07/28/2014 02:17:23 PMRem. Sec Obj.:Port: 0Suppr./Escl.: Normal


Rem. Root Obj.:Extended Attributes:Slot: 0Local Node Alias:Managed Status: ManagedAlert Group: EVENTClass: NAD10tecadFlash: NoURL:Summary: hello_eif_probeCause Type: UnknownCount: 1Poll: 0Local Sec. Obj.:TaskList: Not in Task ListLocal Root Obj.:Group: PublicCard:Serial: 1950Manager: tivoli_eif probe on blackrock.tracy.ryan.comEvent Type: Not DefinedRem. Pri. Obj.:Customer:Expire Time: Not SetIdentifier: :EIF:EVENTPrec. Obj. Inst.: 0TECRepeatCount: 0Correlated Notif.:TECFQHostname:Specific Problem:Owner: NobodyLocation:Server Name: NCOMSService:Internal Timestamp: 07/28/2014 02:17:23 PMNode: 8.42.19.243TECStatus:TECDate:Probable Cause: Not DefinedRem. Node Alias:Severity: IndeterminateLast Occurrence: 07/28/2014 02:17:23 PMTECHostname:Grade: 1Server Serial: 1950TECDateReception:Local Pri. Obj.:TECServerHandle:Precision Domain:Type: ProblemEvent ID:Prec. Serial:Ack: No

Related concepts:“Events” on page 1The central unit of information is the event. An event is any change in the state ofa system resource or application. Events can be generated for problems and forsuccessful completions of tasks.

Chapter 1. Overview of the Tivoli Event Integration Facility 5

Event filteringEvent filtering reduces complexity for console operators and improves responsetimes for complex system errors.

You can filter events with the Tivoli Event Integration Facility by defining filterstatements in the configuration file.Related concepts:Chapter 5, “Filtering events at the source,” on page 41One of the problems associated with event management is working with the highvolume of events that devices can generate. You can address this problem byfiltering events at the source.

RulesThe event server uses rules to specify and control automatic responses to eventsthroughout an enterprise. If you develop a new adapter, you can write new rulesfor the EIF probe and you can create automations.

Automations in the ObjectServer enable it to process events without requiring anoperator to take action. For more information about Tivoli Netcool/OMNIbusautomations, see the IBM Tivoli Netcool/OMNIbus Administration Guide.

For more information about Probe for Tivoli EIF rules, see the IBM TivoliNetcool/OMNIbus Probe for Tivoli EIF Reference Guide in the Network AvailabilityManagement information center at http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp. Also see the IBM Tivoli Netcool/OMNIbus Probe and GatewayGuide.


http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp


Chapter 2. Installing the Event Integration Facility

The Tivoli Event Integration Facility is not installed by the TivoliNetcool/OMNIbus installer and needs to be installed separately from the mainproduct. The EIF SDK includes the JAR files and C libraries.

Before you beginv The user or application that is installing EIF must install the Microsoft Visual

C++ Redistributable Package because EIF does not have an installer programand is not installed by Tivoli Netcool/OMNIbus. You can download theMicrosoft Visual C++ Redistributable Package from the following locations:– For x86 operating systems: http://www.microsoft.com/downloads/

details.aspx?familyid=200b2fd9-ae1a-4a14-984d-389c36f85647– For x64 operating systems: http://www.microsoft.com/downloads/

details.aspx?familyid=EB4EBE2D-33C0-4A47-9DD4-B9A6D7BD44DAv If you are downloading the EIF from the IBM Passport Advantage® Online

website, follow the instructions in the download document for your operatingsystem.

Table 1. Location of the download documents for all supported operating systems

Operating system Download document location

AIX® http://www-01.ibm.com/support/docview.wss?rs=3120&uid=swg24033234

HP-UX Integrity http://www-01.ibm.com/support/docview.wss?rs=3120&uid=swg24033294

Linux http://www-01.ibm.com/support/docview.wss?rs=3120&uid=swg24033295

Linux for System z® http://www-01.ibm.com/support/docview.wss?rs=3120&uid=swg24033296

Solaris http://www-01.ibm.com/support/docview.wss?rs=3120&uid=swg24033297

Windows http://www-01.ibm.com/support/docview.wss?rs=3120&uid=swg24033298

Procedure1. Download the EIF bundle that is included in the Tivoli Netcool/OMNIbus

installation package to a temporary location.2. Extract the compressed EIF files to a separate directory from your IBM Tivoli

installation directory.


http://www.microsoft.com/downloads/details.aspx?familyid=200b2fd9-ae1a-4a14-984d-389c36f85647

http://www.microsoft.com/downloads/details.aspx?familyid=200b2fd9-ae1a-4a14-984d-389c36f85647

http://www.microsoft.com/downloads/details.aspx?familyid=EB4EBE2D-33C0-4A47-9DD4-B9A6D7BD44DA

http://www.microsoft.com/downloads/details.aspx?familyid=EB4EBE2D-33C0-4A47-9DD4-B9A6D7BD44DA

http://www-01.ibm.com/support/docview.wss?rs=3120&uid=swg24033234












Directory structureThe directory structure of the Event Integration Facility after you extract thecompressed files.

The following table describes the file and directory structure of the EventIntegration Facility. In this directory structure, interp can be one of the followingdirectory names, which map to the supported operating systems.v aix4-r1

v hpux10

v hpuxia

v linux-ix86

v linux-ppc

v linux-s390

v linux-ia64

v os390

v solaris2

v solaris2-ix86

v w32-ix86

Table 2. Event Integration Facility directory structure

Directory or file name Header

bin/interp Contains, for each supported operatingsystem that is represented by interp, the32-bit version of the posteifmsg commandthat is used to send EIF events.

bin64/interp Contains, for each supported operatingsystem that is represented by interp, the64-bit version of the posteifmsg commandthat is used to send EIF events.

codeset Contains the code pages.

contrib/interp Contains compiled sample 32-bit Cprograms for each supported operatingsystem that is represented by interp. Thesample receivers are eifrcv1, eifrcv2,eifrcv3, and eifrcv4. The sample sendersare eifsend1 and eifsend2.

contrib64/interp Contains compiled sample 64-bit Cprograms for each supported operatingsystem that is represented by interp. Thesample receivers are eifrcv1, eifrcv2,eifrcv3, and eifrcv4. The sample sendersare eifsend1 and eifsend2.

include Contains header files for building adapters.These files have a .h file extension. Thesefiles are common across all operatingsystems.

jars Contains all the JAR files that are necessaryto use the Java based EIF API. These filesare evd.jar and log.jar.

javadoc Contains the Javadoc for the Java based EIFAPI.


Table 2. Event Integration Facility directory structure (continued)

Directory or file name Header

lib/interp Contains the 32-bit static library for eachsupported operating system that isrepresented by interp. The library name islibeif.a.

lib64/interp Contains the 64-bit static library for eachsupported operating system that isrepresented by interp. The library name islibeif.a.

misc Contains a sample eif.conf file that you canuse to define your own configuration files,and various readme files that explain how touse the EIF and the purpose and usage ofthe sample files that are provided. Inparticular, the readme.tips file has usefulinformation about using the EIF.

samples Contains the following sample adaptersource code:

v Sample C-based receivers, which are asfollows:

– eifrcv1.c

– eifrcv2.c

– eifrcv3.c

– eifrcv4.c

v Sample C-based senders, which are asfollows:

– eifsend1.c

– eifsend2.c

v A sample C-based long running adapterthat is called sampleAdapter.c.

v A sample Java based long runningadapter that is called SampleAdapter.java

Tip: For more information about thepurpose and usage of each sample file, seethe misc/readme.samples file.

EIF.version A file that shows the current build versionof Event Integration Facility.

Related concepts:“Configuration files” on page 3Use the configuration file to control the behavior of adapters. You do not need tomodify multiple instances of an adapter to run in different environments. Modifyonly the configuration files.

Chapter 2. Installing the Event Integration Facility 9

Migrating adaptersIf you upgrade from a previous version of the Event Integration Facility, migrateany adapters that you built with the previous version. To migrate, ensure that filesthat are required by the latest version of the Event Integration Facility are includedin the adapter.

Custom adapters that were created with a previous version of the EventIntegration Facility can be migrated only when the SOCKET transport type is used.

Procedure

v C In the applications that ou want to migrate to the latest version of theEvent Integration Facility, relink the binary files that are dependent on the EventIntegration Facility. Set a static link to libeif.a (previously libteceeif.a).

v Java Ensure that the following new JAR files are included in theapplications that you want to migrate to the latest version of the EventIntegration Facility:– evd.jar

– log.jar

Related concepts:Chapter 4, “Building an adapter,” on page 29Before building an adapter, you must identify events to monitor. You then definethe event source and event classes and select the method for event delivery. Youprogram the event adapter, and install, configure and test it. You are then ready torun the adapter.

Setting up the posteifmsg utility on z/OS using USSTo set up the posteifmsg utility on z/OS® using USS, proceed as follows:

Procedure1. From the Tivoli Netcool/OMNIbus EIFSDK directory, copy the

bin/os390/posteifsg file to a location where the command will be run.2. Set up the appropriate posteifmsg configuration file. For example:

TransportList=t1t1_Channels=c1c1_ServerLocation=<IP_Address_Goes_Here>c1_Port=<EventServerListeningPortGoesHere>t1_Type=SOCKET

BufEvtPath=/tmp/posteifmsg.cache

3. In your USS environment, create the /etc/Tivoli/codeset directory. Thisdirectory contains the EBCDIC codeset files extracted from the TivoliNetcool/OMNIbus EIFSDK directory.

Tip: If you downloaded the files to another system, use FTP to transfer theEBCDIC codeset file or files in binary mode to your USS system, and copythem to the /etc/Tivoli/codeset directory.The file names correspond to the codepage number associated with the codeset.The following codepages are provided for EBCDIC:37, 273, 274, 277, 278, 280, 282, 284, 297, 424, 500,870, 875, 933, 935, 937, 939, 1025, 1026, 1047, 1112, 1122, 1388


The codepages correspond to the EBCDIC codesets used for Western, EastEuropean, Middle Eastern, and Asian languages. The default language isEnglish (codeset 1047). The posteifmsg utility uses only the files it requires.Therefore you can transfer all the codeset files to your USS environment.

4. Run the following command to set the TISDIR environment variable to thecorrect value:export TISDIR=/etc/Tivoli

The posteifmsg utility can now locate the codeset file associated with yoursystem environment, and then convert it to UTF-8.

5. Run the posteifmsg command to send events. For example:posteifmsg -f nameOfConfigFile -m testMessage EVENT TESTING

Related reference:“posteifmsg” on page 18Use the posteifmsg utility to post events to the ObjectServer via the Probe forTivoli® EIF. After you install the Event Integration Facility, the posteifmsg binaryfile can be copied to other hosts.

Chapter 2. Installing the Event Integration Facility 11


Chapter 3. Event transport

The Tivoli Event Integration Facility provides several methods for sendinginformation to the event server. The system on which an adapter is run mustprovide a TCP/IP-based interprocess communication facility.

Event delivery methodsEvents are delivered by an interprocess communication mechanism. To specify thedelivery methods for adapters and applications using the Tivoli Event IntegrationFacility, modify the configuration file and link to the applicable library. To delivertest events directly from a command prompt, use the command-line interface.Related concepts:“Selecting event delivery methods” on page 31While building an adapter, you also need to decide which event delivery methodthe adapter uses to communicate with the event server.Related reference:“Testing and scripting” on page 18You can use the posteifmsg command-line utility and a Java class to send eventsmanually. posteifmsg and the Java class are useful for using shell scripts todevelop new adapters and for testing adapters after you create event groups andassignments, edit rules, or change how a server processes events. You can also usethem to troubleshoot event deliveries after you develop a new adapter.

Connection optionsThe connection options are either connection-oriented or connectionless. Insituations where you want to send many events, you use the connection-orientedoption. In situations where you want to send few events over a period of time, youuse the connectionless option.

You can write a single adapter and use it with a connection-oriented or aconnectionless delivery method. You can specify a delivery method by modifyingthe configuration file.v The default setting for the connection option is connectionless. This method

establishes and discards a new connection for each event or group of events.v For a connection-oriented event delivery, specify ConnectionMode=CO in the

configuration file. This method keeps the channel to the event server open,which improves the performance when you are sending many events.

Related concepts:“Selecting event delivery methods” on page 31While building an adapter, you also need to decide which event delivery methodthe adapter uses to communicate with the event server.Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.


Transport optionsAn application can use the Event Integration Facility API to act as an event senderor an event receiver. The transport options for connections are either SOCKET orSecure Sockets Layer (SSL), and are defined in the EIF configuration file.

SOCKETCompatible with both IPv4 and IPv6.

Links to the libeif.a library.

Uses standard TCP/IP to establish connections.

SSL Compatible with both IPv4 and IPv6.

Links to the libeif.a library.

Performs the standard SSL handshake internally.

Can run in FIPS 140-2 mode.

Requires SSL keystores and a truststore from the application. The keystoresand truststore contain the digital certificates and keys that are required toestablish an SSL connection. Use the nc_gskcmd command-line utility or theiKeyman graphical utility, which are provided with GSKit to create thekeystores and the truststore. GSKit can be accessed from $NCHOME/bin onUNIX operating systems, or from %NCHOME%\bin on Windows operatingsystems.

Related concepts:“Selecting event delivery methods” on page 31While building an adapter, you also need to decide which event delivery methodthe adapter uses to communicate with the event server.Related reference:“Linking the adapter built with the C API” on page 38These tables list the libraries required to link adapters developed with the C API.“SSL and FIPS 140-2 support”The Tivoli Event Integration Facility supports the use of the Secure Sockets Layer(SSL) encryption and authentication protocol to send and receive events. Inaddition, EIF SSL connections can operate in FIPS 140-2 mode, which means theuse of FIPS 140-2 approved cryptographic providers.

SSL and FIPS 140-2 supportThe Tivoli Event Integration Facility supports the use of the Secure Sockets Layer(SSL) encryption and authentication protocol to send and receive events. Inaddition, EIF SSL connections can operate in FIPS 140-2 mode, which means theuse of FIPS 140-2 approved cryptographic providers.

SSL uses digital certificates for key exchange and authentication. When a clientinitiates an SSL connection, the server presents the client with a certificate that issigned by a certificate authority (CA). A CA is a trusted party that guarantees theidentity of the certificate and its creator. The server certificate contains the identityof the server, the public key, and the digital signature of the certificate issuer.

In FIPS 140-2 mode, all encryption and key generation functions that are requiredfor the secure SSL connections are provided by FIPS 140-2 approved cryptographicproviders. These providers are the same providers that are used for FIPS 140-2mode for the main Tivoli Netcool/OMNIbus product. For more information aboutFIPS 140-2 mode, see the IBM Tivoli Netcool/OMNIbus Installation and DeploymentGuide. FIPS 140-2 support is provided as follows for each version of the EIF API:


v C FIPS 140-2 mode is facilitated by the use of IBM Global Security Kit(GSKit). Ensure that the path to the GSKit libraries appears in the followingenvironment variables:

Operating system Environment variables

UNIX LIBPATH, SHLIB_PATH, orLD_LIBRARY_PATH

Windows PATH

GSKit can be accessed from $NCHOME/bin on UNIX operating systems, or from%NCHOME%\bin on Windows operating systems.

Restriction: SSL support is unavailable in the EIF C API for platforms that arenot supported by GSKit.

v Java FIPS 140-2 mode is facilitated by the use of IBM Java runtimeenvironment (JRE) 1.4.2 or higher. The JRE must be configured for FIPS 140-2mode.

Enabling FIPS 140-2 mode

To enable FIPS 140-2 mode:1. Edit the EIF configuration file and set the channel_nameSSLFIPSMode property to

ON.2. For all Java based applications, configure the Java runtime environment for

FIPS 140-2 mode.3. If an EIF receiver application is enabled for FIPS 140-2 mode, enable FIPS 140-2

mode for all EIF client programs that connect to the receiver.

Generating and managing key and digital certificates

If you configure SSL in the EIF configuration file, use the nc_gskcmd command-lineutility or the iKeyman graphical utility to generate and manage keys and digitalcertificates that are required for SSL communication. The following table describesthe keys and certificates to manage and explains them in the context of the EIF.

Table 3. Configuration and usage of key database file for SSL and FIPS 140-2 operations of the EIF

Database file Description Instructions

Keystores for the EIFreceiver applications

The keystore of the receiver is a keydatabase. The default personal certificate ofthe keystore is presented by the EIFreceiver to EIF clients during an SSLconnection. This certificate can be either aself-signed certificate that you create, or acertificate that is obtained from and signedby a CA. The certificate must be set as thedefault personal certificate in the keydatabase of the receiver. The followingdatabase formats are used:

v C CMS

v Java JKS

Create keystores for EIF receiverapplications.

Use the channel_nameSSLKeystoreconfiguration keyword to configure the EIFreceiver to use a key database as itskeystore. If an EIF receiver application usesthe configuration keyword, that is, if thechannel_nameSSLRequireClientAuthentication keyword is set toYES, clients must also present a certificateduring an SSL connection. The keystore ofthe receiver must then contain not only thepersonal certificate of the receiver, but alsothe default personal certificates of anytrusted clients. Import these trustedcertificates into the keystore of the receiver.

Chapter 3. Event transport 15

Table 3. Configuration and usage of key database file for SSL and FIPS 140-2 operations of the EIF (continued)


Keystores for EIF clientapplications

The keystore of the client is a key databasethat contains the default personalcertificates of any EIF receiver applicationsthat are trusted by the EIF client. Importthese trusted certificates into the keystore ofthe client so that the client can connect tothe EIF receiver that is using SSL. Thefollowing database formats are used:

v C CMS

v Java JKS

Create keystores for EIF client applications.

Use the channel_nameSSLKeystoreconfiguration keyword to configure the EIFreceiver to use a key database as itskeystore. If an EIF receiver application usesthe configuration keyword, that is, if thechannel_nameSSLRequireClientAuthentication keyword is set toYES, clients must also present a certificateduring an SSL connection. The keystore ofthe receiver must then contain not only thepersonal certificate of the receiver, but alsothe default personal certificates of anytrusted clients. Import these trustedcertificates into the keystore of the receiver.

Truststores Truststores are key databases that containcertificates that are trusted by an EIFapplication. Any EIF application, whetherclient or receiver, can use a single keydatabase to hold both trusted certificatesand the default personal certificate of theapplication.

Use the channel_nameSSLKeystore keywordto configure truststores.

Java

You can also use one key

database to hold trusted certificates, and asecond key database to hold the defaultpersonal certificate of the application. Usethe channel_nameSSLTruststore keyword tospecify the key database that contains thetrusted certificates. Use thechannel_nameSSLKeystore keyword tospecify the key database that contains thedefault personal certificate of theapplication.

Stash file C For automatic login to access thedigital certificates, save the password for akey or trust database in encrypted formatto a stash file. Whenever the keystore ortruststore is accessed, the system checkswhether a stash file exists. If found, the filecontents are decrypted and used as inputfor the password.

Java

To create and store encrypted

passwords for applications, use thecom.tivoli.tec.event_delivery.common.Encryption script.


Table 3. Configuration and usage of key database file for SSL and FIPS 140-2 operations of the EIF (continued)


Ciphers The sending and receiving ends of the EIFconnection must have at least one cipher incommon in order for the connection tosucceed. FIPS 140–2 mode restricts theciphers that are allowed for both the C andJava versions of EIF

Use the SSLCipherList keyword to specifythe ciphers that are permitted during SSLauthentication. If no ciphers are specified orrestricted, all available ciphers arepermitted.

C

The following ciphers are

available:

v SSL_RC2_CBC_128_CBC_WITH_MD5

v SSL_RC2_CBC_128_CBC_EXPORT40_WITH_MD5

v SSL_DES_64_CBC_WITH_MD5

v SSL_DES_192_EDE3_CBC_WITH_MD5

v SSL_NULL_WITH_NULL_NULL

v SSL_RSA_WITH_NULL_MD5

v SSL_RSA_WITH_NULL_SHA

v SSL_RSA_EXPORT_WITH_RC4_40_MD5

v SSL_RSA_WITH_RC4_128_MD5

v SSL_RSA_WITH_RC4_128_SHA

v SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5

v SSL_RSA_WITH_DES_CBC_SHA

Java

Any cipher that is supported by

the IBM JRE is valid. For all the supportedciphers, see the Java Secure Socket Extension(JSSE) IBMJSSE2 Provider Reference Guide forthe Java 2 SDK, Standard Edition, Version 5athttp://www.ibm.com/developerworks/java/jdk/security/50/secguides/jsse2Docs/JSSE2RefGuide.html.

Related concepts:“Selecting event delivery methods” on page 31While building an adapter, you also need to decide which event delivery methodthe adapter uses to communicate with the event server.Related tasks:“Configuring an EIF client application for SSL” on page 33In order to use SSL communication between EIF receiver and client applications,you must configure the EIF client application.“Configuring an EIF receiver application for SSL” on page 32In order to use Secure Sockets Layer (SSL) communication between EIF receiverapplications and client applications, you must configure the receiver application.Receivers require a personal certificate that is either self-signed or signed by acertificate authority (CA).Related reference:


http://www.ibm.com/developerworks/java/jdk/security/50/secguides/jsse2Docs/JSSE2RefGuide.html



“Testing and scripting”You can use the posteifmsg command-line utility and a Java class to send eventsmanually. posteifmsg and the Java class are useful for using shell scripts todevelop new adapters and for testing adapters after you create event groups andassignments, edit rules, or change how a server processes events. You can also usethem to troubleshoot event deliveries after you develop a new adapter.Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Testing and scriptingYou can use the posteifmsg command-line utility and a Java class to send eventsmanually. posteifmsg and the Java class are useful for using shell scripts todevelop new adapters and for testing adapters after you create event groups andassignments, edit rules, or change how a server processes events. You can also usethem to troubleshoot event deliveries after you develop a new adapter.

If you use a user ID other than Administrator or root, ensure that you have thecorrect permissions for creating the file. These permissions are specified by theBufEvtPath keyword.Related concepts:“Event delivery methods” on page 13Events are delivered by an interprocess communication mechanism. To specify thedelivery methods for adapters and applications using the Tivoli Event IntegrationFacility, modify the configuration file and link to the applicable library. To delivertest events directly from a command prompt, use the command-line interface.Related tasks:“Programming the adapter” on page 35To program an adapter, you implement the interfaces and the preferred settings forthe configuration file. You decide whether to define attribute values in theconfiguration file or the adapter code. You then compile and, if required, link theadapter.Related reference:“SSL and FIPS 140-2 support” on page 14The Tivoli Event Integration Facility supports the use of the Secure Sockets Layer(SSL) encryption and authentication protocol to send and receive events. Inaddition, EIF SSL connections can operate in FIPS 140-2 mode, which means theuse of FIPS 140-2 approved cryptographic providers.“Installing, configuring, and testing the adapter” on page 39After assembling all the files for the adapter, you need to install, configure, andtest the adapter before running it.

posteifmsgUse the posteifmsg utility to post events to the ObjectServer via the Probe forTivoli EIF. After you install the Event Integration Facility, the posteifmsg binary filecan be copied to other hosts.

Ensure that you copy the correct version of the binary file for your operatingsystem and bitness.

The posteifmsg utility is a replacement for the Tivoli Enterprise Console postemsgand postzmsg utilities. The posteifmsg utility performs the same event-sendingfunction for Tivoli Netcool/OMNIbus as the postemsg and postzmsg utilitiesperform for Tivoli Enterprise Console.


Syntax

The syntax of the posteifmsg utility is as follows.posteifmsg -S server [-p port]| -f configurationfile [-m "message"][-t timeout] [-l lockfile] [-r severity] [attribute=value...] class source

Where:v server is the host name or the IP address of the target server. The -S

command-line option assumes that the target server is a Tivoli EnterpriseConsole system that is hosted on a UNIX operating system, and that the portmapper service is in use. See “Configuring the Probe for Tivoli EIF” on page 20if you are sending events to the Probe for Tivoli EIF and Tivoli EnterpriseConsole is on the same host as the probe.

v configurationfile is the configuration file.v message is the text of the message, which is enclosed in double quotation marks

(" "). The maximum number of characters or bytes that can be passed with the-m command-line option is 4148 characters or bytes. If you specify anythinglonger, a segmentation fault and core file is generated.

v timeout is the maximum time, in seconds, for which an event is locked(prevented from sending) when the lock file (specified by the -l option) islocked. This option allows multiple instances of posteifmsg to issue commandsconcurrently, provided that each instance of posteifmsg uses the same lock file.The timeout option (-t) can only be used with the lock file option (-l). Thedefault timeout is 1000 seconds.When the lock timeout elapses, the event is dropped and error code 1 isreturned. To prevent dropped events, configure the timeout to handle the eventthroughput in your environment.

v lockfile is the name of the lock file used to enable concurrency. If the lock file thatyou specify does not already exist, it is automatically created. The lock filecontains no content and does not require any. The file is not deleted, so youmust manually remove it when it is no longer required.

v severity is a valid severity that is defined for the event class.v attribute=value assigns a value to any valid attribute. The value must be defined

for the event class. Separate multiple attribute=value expressions with a space.v class specifies the class of the event. The class that you specify must be a class

that is configured in the server. If the class name contains blank spaces, enclosethe class name in double quotation marks (" ").

v source specifies the source of the event. If the source name contains blank spaces,enclose the source name in double quotation marks (" ").

Important: Ensure that the class source pair is the final arguments in thecommand-line string. Otherwise, the command fails. For testing, the base of allclass source pairs is EVENT EVENT.

Configuration notes

The posteifmsg needs a configuration file to run. The configuration file useskeywords. The minimum configuration for the utility is to set only theServerLocation and ServerPort keywords. These keywords specify the host andport number on which the Probe for Tivoli EIF is running, as shown in thefollowing example.ServerLocation=10.10.10.10ServerPort=9998


Ensure that the ServerPort keyword is set to the same port number as the asPortNumber keyword in the Probe for Tivoli EIF properties file, tivoli_eif.props.

Further possible configurations are as follows:v Ensure that the value of the ServerPort keyword matches the value of the

PortNumber property of the Probe for Tivoli EIF.v Ensure that the BufferEvents keyword is set to YES, which is the default.v Leave the ConnectionMode keyword commented out. The posteifmsg utility

always uses the connection_less method to connect and disconnect. Thisbehavior applies even if you set the ConnectionMode keyword to CO.

v Optional: Set the BufEvtPath keyword. The default is $OMNIHOME/var/posteifmsg.cache.

See also “Example 1” on page 21.

The posteifmsg utility is not thread-safe or cache-secure. It is best suited tosending low numbers of events, at low frequencies. To send high volumes ofevents to the ObjectServer over short periods of time, you can use the nco_postmsgutility, which is in the Probe Support feature of Tivoli Netcool/OMNIbus. Unlikethe Event Integration Facility, the Probe Support feature of TivoliNetcool/OMNIbus needs an instance of the Deployment Engine to run. For moreinformation about the nco_postmsg utility, see the IBM Tivoli Netcool/OMNIbusAdministration Guide. For more information about the Deployment Engine and theinstallable features of Tivoli Netcool/OMNIbus, see the IBM TivoliNetcool/OMNIbus Installation and Deployment Guide.

Configuring the Probe for Tivoli EIF

Events from the posteifmsg must be sent to the Probe for Tivoli EIF, which sendsthe events to the ObjectServer. To use the posteifmsg utility to send events to theProbe for Tivoli EIF, note the following information.v To run the posteifmsg utility with -S command-line option, ensure that the

PortMapper property in the probe is set to TRUE.v If the probe is installed on the same host as Tivoli Enterprise Console, only one

of these products can use the portmapper. For example, if Tivoli EnterpriseConsole is installed on the host and is configured to use a port mapper, youcannot run the probe on the same host and set the PortMapper property to TRUE.The reverse also applies.

The following sample shows the configuration that is required in the probeproperties file, tivoli_eif.props, for the port mapper to work.Server : ’COL_P_1’ServerBackup : ’COL_B_1’PortNumber : 9998PortMapper : "true"PortMapperNumber : 100033057NetworkTimeout : 30PollServer : 60AutoSAF : 1

For more information about the Probe for Tivoli EIF, see the IBM TivoliNetcool/OMNIbus Probe for Tivoli EIF Reference Guide.


Configurations for firewalls

You can use the firewall bridge server that is in the main Tivoli Netcool/OMNIbusproduct for sending events via the posteifmsg utility. For example, you canconfigure posteifmsg utilities that are outside a firewall to connect to a Probe forTivoli EIF that is outside the firewall. Then, this instance of the Probe for Tivoli EIFconnects to a client access firewall bridge instead of the ObjectServer. The clientaccess bridge outside the firewall connects to a server access firewall bridge that isinside the firewall. The firewall bridge restricts port usage to a single port betweenthe client access firewall bridge and the server access firewall bridge. The serveraccess firewall bridge connects to the ObjectServer. Fore more information aboutthe firewall bridge server, see the IBM Tivoli Netcool/OMNIbus Administration Guide.

Example 1

The following example shows the posteifmsg utility used with a configuration filethat is called posteifmsg.conf.posteifmsg -f posteifmsg.conf source=MYTEST severity=HARMLESS hostname=testhostphysical_node=testhost.us.ibm.com sub_source=Heartbeat poll_time=3600host_type=WINDOWS msg="TEST HEARTBEST MESSAGE" origin=10.10.10.10 TEST TEMS

Example 2

The following example shows the posteifmsg used with the portmapper.posteifmsg -S 10.10.10.10 source=MYTEST severity=CRITICAL hostname=testhostphysical_node=testhost.us.ibm.com sub_source=posteifmsg poll_time=3600host_type=UNIX msg="This is a critical test event" origin=10.10.10.10 TEST TEMS

Related tasks:“Setting up the posteifmsg utility on z/OS using USS” on page 10To set up the posteifmsg utility on z/OS using USS, proceed as follows:Related reference:“Directory structure” on page 8The directory structure of the Event Integration Facility after you extract thecompressed files.

Java classesUse the com.tivoli.tec.event_delivery.TECAgent Java utility to post an event to theevent server. Use the com.tivoli.tec.event_delivery.common.Encryption Java utilityto create an encryption key for SSL communications.

com.tivoli.tec.event_delivery.TECAgentjava com.tivoli.tec.event_delivery.TECAgent SENDER -S server | -f configurationfile[-m "message"] [-r severity] [attribute=value...] class source

Wherev server

v configurationfile is the name of the configuration file.v message is the text of the event, in double quotation marks (" ").v severity is the severity of the event. The severity must be defined for the event

class.v value is the value of a valid attribute. Ensure that the attribute is defined for the

event class. Separate multiple attribute-value pairs with spaces, for exampleattribue1=1 attribute2=2, and so on.


Ensure that the class of the event is configured in the event server. Classes aredefined by the adapter. If the name of the class contains blank spaces, enclose thename in double quotation marks (" "). If the source of the event contains blankspaces, enclose the name in double quotation marks (" ").

The following example sends a test message that displays an Su_Failure event onthe event consoles:java com.tivoli.tec.event_delivery.TECAgent SENDER -f myconfig.conf-m "su login failure." Su_Failure LOGFILE

com.tivoli.tec.event_delivery.common.Encryptionjava -cp path_to_evd.jar com.tivoli.tec.event_delivery.common.EncryptioncreateKey [-k encryptionkeyfilepath] [-l keylength] -o outputfile-d texttoencrypt [-f]

Valid key lengths are 128, 192, and 256. If you do not specify a key length, thedefault is 128. The -f option turns on FIPS 140-2 mode. Both the EIF sender andthe EIF receiver must be in FIPS 140-2 mode. To create a stash file, create theencryption key file beforehand. When a stash file is used, an encryption key file isrequired.

Java

Use the createkey command to generate the encryption key file and the

encrypt command to generate the stash file.

C

Use the nc_gskcmd command-line utility or the iKeyman graphical utility

to create the stash file.

The following example shows the syntax ofcom.tivoli.tec.event_delivery.common.Encryption for creating an encryption key.java -cp ./evd.jar com.tivoli.tec.event_delivery.common.Encryptioncreatekey -l 128 -o ./mykey

The syntax of com.tivoli.tec.event_delivery.common.Encryption for using theencryption key to encrypt the password and saving the encrypted data to a stashfile is as follows:java -cp path_to_evd.jar com.tivoli.tec.event_delivery.common.Encryption encrypt-k encryptionkeyfilepath -o outputfilepath -d texttoencrypt [-f]

For example:java -cp ./evd.jar com.tivoli.tec.event_delivery.common.Encryption encrypt-k ./mykey -o ./mypass -d password

Event reception for applicationsIn addition to sending events, the Tivoli Event Integration Facility enables otherapplications to receive, that is, listen for, events.

The Event Integration Facility can instantiate one or more event listeners. Eachevent listener can have one or more channels. This allows information to flow frommultiple sources. You can specify multiple channels, and the event listener listensto all of those channels.

The polling mechanism enables the application to retrieve events synchronously, byusing the get method of the API. With the non-polling mechanism, the applicationregisters a listener or callback and receives events asynchronously.


Additionally, EIF uses a cache for event reception. If the application has a listener,EIF also registers a listener in the cache. Then it notifies the application and passesthe event to the application listener. If the application does not use a listener, theapplication must request the retrieval of the next event.

The following is an example of a configuration file that enables the application toreceive events using sockets:TransportList=t1

t1Type=SOCKETt1Channels=t_t_ServerLocation=myserver.comt_Port=5151

The following is an example of a configuration file that enables an applicationcreated using the C API to receive events using SSL, with FIPS 140-2 modeenabled:TransportList=t1_t1_Type=SSLt1_Channels=c1_c1_Port=3443

c1_ServerLocation=myserver.com

c1_SSLKeystore=/my/location/gbkeys.kdbc1_SSLKeystorePW=passwordc1_SSLCipherList=SSL_RSA_WITH_3DES_EDE_CBC_SHA

c1_SSLFIPSMode=ON

Related tasks:“Activating the cache” on page 24By default, the cache that ensures recovery after system failures stores events. Youcontrol the configuration of the cache with keywords in the configuration file.Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Sending events through firewallsYou can send events through firewalls depending on your environment andorganizational restrictions regarding firewall security.

To send events through firewalls you configure them to allow arbitrary TCP/IPconnections on the port specified for your adapter. Ensure that the firewall allowsinbound communication from the computer system hosting the adapter.Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.


Event delivery when systems failTo ensure that events are delivered after system failures, the Tivoli EventIntegration Facility provides a cache on the adapter.

This repository stores events. Events are removed from the cache when they aredelivered. Also, the Event Integration Facility ensures that the same event is notdelivered more than once.

To configure your environment for the reliable delivery of events, you activate thecache and specify backup servers to deliver events. You can further avoid deliveryfailure by specifying a list of servers.Related tasks:“Activating the cache”By default, the cache that ensures recovery after system failures stores events. Youcontrol the configuration of the cache with keywords in the configuration file.“Configuring backup servers to deliver events” on page 25The configuration uses TCP sockets to deliver events. You specify how to contactbackup servers by defining the transport channel to be the server name and theport number.Related reference:“Installing, configuring, and testing the adapter” on page 39After assembling all the files for the adapter, you need to install, configure, andtest the adapter before running it.

Activating the cacheBy default, the cache that ensures recovery after system failures stores events. Youcontrol the configuration of the cache with keywords in the configuration file.

About this task

You can use the following keywords to configure the cache.

Table 4. Keywords for configuring the cache

Configuration of the Cache Keywords

Activation of the cache BufferEvents

Rate to send events BufferFlushRateMaxPacketSize

Size of the cache BufEvtMaxSize

You can configure the cache in the following way:v Store events in memory only with the BufferEvents keyword.v Save these buffered events to a permanent file with the BufferEvents keyword

set to YES. Also, the BufEvtPath keyword specifies the location of the permanentfile.

The second configuration ensures that no events are lost during a system failure.

The following example from a configuration file demonstrates the use of cachekeywords:


BufferEvents=YESBufEvtPath=./bufferMaxPacketSize=130BufferFlushRate=96ConnectionMode=CO

When connections to the event server fail, events wait in the cache. The EventIntegration Facilityattempts to reconnect to each of the backup servers in turn. Ifno servers are available after all retries, the API caches the events until aconnection is made.

When enabling recovery features, it is important to determine the importance ofperformance and reliability. In some environments, the use of the cache candegrade performance depending on its configuration. Therefore you can bypassevent caching by setting the BufferEvents keyword to NO.Related concepts:“Event delivery when systems fail” on page 24To ensure that events are delivered after system failures, the Tivoli EventIntegration Facility provides a cache on the adapter.“Performance and availability” on page 47The Tivoli Event Integration Facility can control performance and availability forevent processing.Related tasks:“Configuring backup servers to deliver events”The configuration uses TCP sockets to deliver events. You specify how to contactbackup servers by defining the transport channel to be the server name and theport number.“Filtering events when systems fail” on page 42When an adapter is unable to connect to the event server , it sends the events to afile if the BufferEvents keyword is set to YES.Related reference:“Event reception for applications” on page 22In addition to sending events, the Tivoli Event Integration Facility enables otherapplications to receive, that is, listen for, events.

Configuring backup servers to deliver eventsThe configuration uses TCP sockets to deliver events. You specify how to contactbackup servers by defining the transport channel to be the server name and theport number.

About this task

You specify how to contact backup servers by completing the following steps:

Procedure1. Create names for connections you want to make to the backup servers. Use the

TransportList keyword to create this list.2. Specify either an SSL or a SOCKET connection for each of the items in this list

by using the Type keyword.3. Optional: Specify multiple channels as alternate paths for each type of

transport, using the ServerLocation keyword.


Example

The following is a backup example for the C API:TransportList=t1,t2t1Type=SSLt1Channels=c1,c2c1ServerLocation=sslhost1c1Port=1111

c1_SSLKeystore=/my/location/gbkeys.kdbc1_SSLKeystorePW=passwordc1_SSLKeystoreStashFile=/my/location/gbkeys.sthc1_SSLCipherList=SSL_RSA_WITH_3DES_EDE_CBC_SHA

c1_SSLFIPSMode=OFF

c2ServerLocation=sslhost2c2Port=2222

c2_SSLKeystore=/my/other/location/gbkeys.kdbc2_SSLKeystorePW=passwordc2_SSLCipherList=SSL_RSA_WITH_3DES_EDE_CBC_SHAc2_SSLFIPSMode=OFF

t2Type=SOCKETt2Channels=c3,c4c3ServerLocation=host1c3Port=1234c4ServerLocation=host2c4Port=5678

Related concepts:“Event delivery when systems fail” on page 24To ensure that events are delivered after system failures, the Tivoli EventIntegration Facility provides a cache on the adapter.“Performance and availability” on page 47The Tivoli Event Integration Facility can control performance and availability forevent processing.Related tasks:“Activating the cache” on page 24By default, the cache that ensures recovery after system failures stores events. Youcontrol the configuration of the cache with keywords in the configuration file.

Using the portmapper keywordsThe keywords for the portmapper channel enable the receiver applications toregister multiple ports under various portmapper program names, and the sendingapplications to access those registered names.

Note: The Event Integration Facility does not support the portmapper keywordsfor the 64-bit OS/390® library.

When the channel_namePortMapper keyword is set to YES, it forces the specifiedport to be registered with the portmapper for a receiver application. Thus, itignores the specified port in favor of the portmapper to obtain the correct port forsender code. The API ignores any other value for channel_namePortMapper.

The default values for the channel_namePortMapper,channel_namePortMapperNumber, and channel_namePortMapperVersionkeywords are the ones used by the event server. If these keywords are not present


in the configuration file for the sender application and the portmapper isrequested, a connection to the event server is attempted. In a receiver application,the port is only registered if the port is set to zero (0). In this case, the defaultvalues are used.

If a port is set to zero (0), EIF uses the channel_namePortMapper,channel_namePortMapperNumber, and channel_namePortMapperVersionkeywords. If any of their values are not specified, their default values are used.

If a port is set to a value greater than zero, the portmapper is only used if thechannel_namePortMapper keyword is set to YES. In this case, the specified port isignored for the sender side but used for the receiver side. Thechannel_namePortMapper keyword allows the port used for portmapper to bespecified. Thus, a port set to zero (0) will pick any available port. On the receiverside, it is advantageous to use the portmapper so that sending applications canconnect to the receiver by means of the portmapper.

Configuring a reception application built with the C APIA reception application built with the C API can be configured with keywords inthe configuration file.

Use the following keywords in the configuration file to configure a receptionapplication built with the C API.

ActiveConnections=nnThe number of active connections that the reception process should handle.

The number of possible connections range from 2 to 10000.

A number less than the minimum value sets the value to the minimumvalue unless that number is zero, which means unlimited connections. Anumber greater than the maximum value sets the value to the maximumvalue. Not specifying a value, yields the default value of 128.Applies to the C API only.

ActiveConnectionsSafety=nnThe percentage of ActiveConnections that the number of actual connectionspermits must be reduced to a specific number before connections can beprocessed again. This is a threshold value.

Setting ActiveConnections limits the numbers of active connectionshandled by the C Event Integration Facility reception process.

For example, if ActiveConnections equals 20 and theActiveConnectionsSafety equals 80, the reception process stops acceptingconnections when there are 20 connections. The percent can range from 10to 90. New connections resume when the number of active connections isreduced to 16 (80% of 20) or less.

The default value is 80 and is only used when ActiveConnections has beenspecified.

A number less than the minimum value sets the value to the minimumvalue. A number greater than the maximum value sets the value to themaximum value.Applies to the C API only.

ConnectionsQueued=nnThe approximate number of queued connections that the reception processwill handle.


The server socket queues up connections that are waiting to be accepted bythe reception process. Connection attempts fail after this limit has beenexceeded.

Use this option to limit the number of connections that can be queued. Theactual number of connections queued can be slightly more than or lessthan the value of ConnectionsQueued. The default is 1000. The range ofvalues can be between 1 and 1000. A number less than the minimum valuesets the value to the minimum value. A number greater than the maximumvalue sets the value to the maximum value.Applies to the C API only.

Example of a reception application build with the C API receiving events over aSOCKET connection:BufferEvents=YESBufEvtPath=/tmp/eif_socket_recv.cache

TransportList=t1t1Type=SOCKETt1Channels=t_t_ServerLocation=myserver.comt_Port=5151

Example of a reception application build with the C API receiving events over anSSL connection:BufferEvents=YESBufEvtPath=/tmp/eif_socket_recv.cache

TransportList=t1t1Type=SSLt1Channels=t_t_ServerLocation=myserver.comt_Port=5151

t_SSLKeystore=/my/other/location/gbkeys.kdbt_SSLKeystorePW=passwordt_SSLCipherList=SSL_RSA_WITH_3DES_EDE_CBC_SHAt_SSLFIPSMode=OFF

Note: The procedure to configure a keystore for a reception application is identicalto that of a sender application.


Chapter 4. Building an adapter

Before building an adapter, you must identify events to monitor. You then definethe event source and event classes and select the method for event delivery. Youprogram the event adapter, and install, configure and test it. You are then ready torun the adapter.Related tasks:“Migrating adapters” on page 10If you upgrade from a previous version of the Event Integration Facility, migrateany adapters that you built with the previous version. To migrate, ensure that filesthat are required by the latest version of the Event Integration Facility are includedin the adapter.

Adapter filesIn addition to the header file or Java package, a number of files are related to theadapter. This section lists these files and shows the relationship between them andevent processing.

There are several adapter files. In addition to the header file or Java package, thefollowing are files related to the adapter:

.conf fileThe configuration file controls filtering and buffering of events. It alsocontrols communications.

.rls fileThe rule file applies custom rules to events for filtering, tasks, and otheractions. Some rule files are installed on the event server by default. Youcan optionally specify other rules.

For a detailed description of adapter files, see the IBM Tivoli Enterprise ConsoleAdapters Guide in the IBM Tivoli Information Center athttp://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jspRelated reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Identifying events to monitorBefore you create an adapter, you must decide what types of events you need tomonitor.

Review the following factors to help you identify significant events:v Users of IT resourcesv Service level agreementsv Network requirements for down-time and up-timev Application and network dependencies (for example, databases, e-commerce

Web sites, wide area networks, and so forth)v Performance requirements



v Important servers and network resources

After creating a list of significant events, use this list to define the source.

Defining the sourceThe method used to retrieve event information depends on the resources.

When you develop a new adapter, you must determine how to gather informationabout the monitored resource. You must also determine a method for identifyingthe information that you want to send to the event server. For example, thenecessary information about a resource can be gathered from a system log file.Then this information must be formatted, and optionally filtered, before being sentto the event server.

Defining event classesAn important task when you create an adapter is to determine the event classes forthe information that you want to monitor. To help you when you write rules tohandle the events, you must make event definitions as specific as possible.

The Probe for Tivoli EIF has a set of default rules that map attributes of EventIntegration Facility events to columns in alerts.status. You must define thesecommon attributes so that the probe can process them.

Note: Event class names must be unique.

The event string is adapter-dependent. You can have as many as required pairs ofattributes and values. The following code fragment illustrates the assembly of anevent string:"MY_EVENT_CLASS;source=_ANY_DEFINED_SOURCE;application=myAppl1;origin=9.179.1.234;msg=Hello World;END\n\001"

In the code fragment, source and application are application-specific.

For more information about probe rules and attributes, see the IBM TivoliNetcool/OMNIbus Probe for Tivoli EIF guide in the IBM Tivoli Netcool/OMNIbusintegrationsInformation Center athttp://www.ibm.com/support/knowledgecenter/en/SSSHTQ/omnibus/common/kc_welcome-444.html

For more information about the default classes hierarchy, see the IBM TivoliEnterprise Console Adapters Guide in the IBM Tivoli Information Center athttp://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jspRelated concepts:“Event classes” on page 3Event classes are classifications of events. After separating information into eventclasses, adaptors format the information into messages that represent specificinstances of event classes. Then they send the information to the event server,which processes the information, along with information received from otheradapters.


http://www.ibm.com/support/knowledgecenter/en/SSSHTQ/omnibus/common/kc_welcome-444.html

http://www.ibm.com/support/knowledgecenter/en/SSSHTQ/omnibus/common/kc_welcome-444.html


Selecting event delivery methodsWhile building an adapter, you also need to decide which event delivery methodthe adapter uses to communicate with the event server.

You must define the connection and transport types. You do this by editing theappropriate keywords in the EIF configuration file. The following connection typesand transport types are available:

Connection optionsConnection-oriented

Connectionless

Transport optionsSOCKET

SSLv Normal SSL mode (non FIPS)v FIPS 140-2 mode

If you choose to use the SSL transport type, you must generate security certificatesand keys. You must also decide whether to operate the SSL connection in FIPS140-2 mode. If you do, you enable FIPS 140-2 mode by editing the configurationfile.Related concepts:“Event delivery methods” on page 13Events are delivered by an interprocess communication mechanism. To specify thedelivery methods for adapters and applications using the Tivoli Event IntegrationFacility, modify the configuration file and link to the applicable library. To delivertest events directly from a command prompt, use the command-line interface.“Connection options” on page 13The connection options are either connection-oriented or connectionless. Insituations where you want to send many events, you use the connection-orientedoption. In situations where you want to send few events over a period of time, youuse the connectionless option.Related reference:“Transport options” on page 14An application can use the Event Integration Facility API to act as an event senderor an event receiver. The transport options for connections are either SOCKET orSecure Sockets Layer (SSL), and are defined in the EIF configuration file.“SSL and FIPS 140-2 support” on page 14The Tivoli Event Integration Facility supports the use of the Secure Sockets Layer(SSL) encryption and authentication protocol to send and receive events. Inaddition, EIF SSL connections can operate in FIPS 140-2 mode, which means theuse of FIPS 140-2 approved cryptographic providers.Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Chapter 4. Building an adapter 31

Configuring an EIF receiver application for SSLIn order to use Secure Sockets Layer (SSL) communication between EIF receiverapplications and client applications, you must configure the receiver application.Receivers require a personal certificate that is either self-signed or signed by acertificate authority (CA).

Before you begin

About this task

To configure an EIF receiver application for SSL, complete the following procedure:

Procedure1. Create a key database for the EIF receiver:

a. Start the nc_ikeyman utility and create a new key database file.For C-based EIF applications, use the CMS key database type.For Java-based EIF applications, use the JKS key database type.

b. Choose a password for the key database.For CMS key databases, you can encrypt the password in a stash file.

2. Obtain a personal certificate in one of the following ways:v Use the nc_ikeyman utility to create a new self-signed certificate.v Use the nc_ikeyman utility to create a certificate request and submit it to a

CA for signing.v Obtain a signed certificate from a CA using another method.

3. Add the new personal certificate to the receiver key database and configure itto be the default personal certificate.

4. Create a configuration file for the EIF receiver. Start with the following code:TransportList=t1_t1_Type=SSLt1_Channels=c1_c1_Port=[Listening port of the EIF receiver]c1_ServerLocation=[Hostname or IP address of the EIF receiver]c1_SSLKeystore=[File location of the receiver key database]

5. Add the password of the receiver key database to the EIF configuration file.v To specify the password as plain text, add the following line to the EIF

configuration file:c1_SSLKeystorePW=password of the receiver key database

v To encrypt the password when using a CMS key database, you can use thestash file location associated with the key database. Add the following line tothe EIF configuration file:c1_SSLKeystoreStashFile=File location of the stash file

v To encrypt the password when using a JKS key database, you can use theJava EIF utility com.tivoli.tec.event_delivery.common.Encryption to create anencrypted password and an encryption key that will decode the password.Add the following lines to the EIF configuration file:c1_SSLKeystoreStashFile=File containing the encrypted passwordc1_SSLKeystoreEncryptionKeyFile=File containing the encryption key

6. Optional: Choose the ciphers that the EIF receiver will support.By default, a C-based EIF application will support all ciphers available in theIBM GSkit, and a Java-based EIF application will support all ciphers availablein the IBM JRE.Add the list of cipher names, separated by commas, to the EIF configuration


file, using the following format:c1_SSLCipherList=Cipher name 1,Cipher name 2, [...]

7. Optional: Enable FIPS 140-2 mode.By default, FIPS 140-2 mode is disabled. To enable FIPS 140-2 mode, add thefollowing line to the EIF configuration file: c1_SSLFIPSMode=ONFor Java-based EIF applications, the Java Runtime Environment must also beconfigured to use FIPS providers. Add the following entries to the list ofsecurity providers in the lib/java/java.security file of your JRE installation:security.provider.number=com.ibm.fips.jsse.IBMJSSEFIPSProvidersecurity.provider.number=com.ibm.crypto.fips.provider.IBMJCEFIPS

where number indicates the sequence that you want to allocate to each providerin the list.

8. Optional: Specify if clients must present a trusted certificate.By default, EIF does not require clients to present a trusted certificate.To add a trusted certificate, add the following line to the EIF configuration file:c1_SSLRequireClientAuthentication=YES

9. For C-based EIF applications, update the required environment variable withthe path to the GSKit library files.



Windows PATH


What to do next

You must configure the EIF client application for SSL next.Related reference:“SSL and FIPS 140-2 support” on page 14The Tivoli Event Integration Facility supports the use of the Secure Sockets Layer(SSL) encryption and authentication protocol to send and receive events. Inaddition, EIF SSL connections can operate in FIPS 140-2 mode, which means theuse of FIPS 140-2 approved cryptographic providers.Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Configuring an EIF client application for SSLIn order to use SSL communication between EIF receiver and client applications,you must configure the EIF client application.

Before you begin

You need to create the EIF receiver's personal certificate before you can configurethe client application.

About this task

To configure an EIF client application for SSL, complete the following procedure:


Procedure1. Create a key database for the EIF client:

a. Start the nc_ikeyman utility and create a new key database file.For C-based EIF applications, use the CMS key database type.For Java-based EIF applications, use the JKS key database type.

b. Choose a password for the key database.For CMS key databases, you can encrypt the password in a stash file.

2. Add the personal certificate of the EIF receiver to the client key database.a. Use the nc_ikeyman utility to export the default personal certificate from the

receiver key database.b. Use the nc_ikeyman utility to import the certificate into the client key

database.3. Create a configuration file for the EIF client. Start with the following:

TransportList=t1_t1_Type=SSLt1_Channels=c1_c1_Port=[Listening port of the EIF receiver]c1_ServerLocation=[Hostname or IP address of the EIF receiver]c1_SSLKeystore=[File location of the receiver key database]

4. Add the password of the client key database to the EIF configuration file.v To specify the password as plain text, add the following line to the EIF

configuration file:c1_SSLKeystorePW=password of the key database

v To encrypt the password when using a CMS key database, you can use thestash file location associated with the key database. Add the following line tothe EIF configuration file:c1_SSLKeystoreStashFile=File location of the stash file

v To encrypt the password when using a JKS key database, you can use theJava EIF utility com.tivoli.tec.event_delivery.common.Encryption to create anencrypted password and an encryption key that will decode the password.Add the following lines to the EIF configuration file:c1_SSLKeystoreStashFile=File containing the encrypted passwordc1_SSLKeystoreEncryptionKeyFile=File containing the encryption key

5. Optional: Specify the ciphers that are required by the EIF receiver. If thereceiver supports all ciphers, omit this step.Add the list of cipher names, separated by commas, to the EIF configurationfile, using the following format:c1_SSLCipherList=Cipher name 1,Cipher name 2, [...]

6. Optional: If the EIF receiver has been enabled for FIPS 140-2 mode, enable FIPS140-2 mode for the client as well. Otherwise, do not enable 140-2 mode for theclient.By default, FIPS 140-2 mode is disabled. To enable FIPS 140-2 mode, add thefollowing line to the EIF configuration file: c1_SSLFIPSMode=ONFor Java-based EIF applications, the Java Runtime Environment must also beconfigured to use FIPS providers. Add the following entries to the list ofsecurity providers in the lib/java/java.security file of your JRE installation:security.provider.number=com.ibm.fips.jsse.IBMJSSEFIPSProvidersecurity.provider.number=com.ibm.crypto.fips.provider.IBMJCEFIPS

where number indicates the sequence that you want to allocate to each providerin the list.

7. Optional: If the EIF receiver requires clients to present a trusted certificate,complete the following steps:


a. Obtain a trusted certificate. You can use the nc_ikeyman utility to create anew self-signed certificate, or use the nc_ikeyman utility to create acertificate request and submit it to a CA for signing. Alternatively, you canobtain a signed certificate from a CA using another method.

b. Add the new certificate to the client key database and configure it to be thedefault certificate.

c. Add the new certificate to the receiver key database, but do not configure itto be the default certificate.

8. For C-based EIF applications, update the required environment variable withthe path to the GSKit library files.



Windows PATH


Related reference:“SSL and FIPS 140-2 support” on page 14The Tivoli Event Integration Facility supports the use of the Secure Sockets Layer(SSL) encryption and authentication protocol to send and receive events. Inaddition, EIF SSL connections can operate in FIPS 140-2 mode, which means theuse of FIPS 140-2 approved cryptographic providers.Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Programming the adapterTo program an adapter, you implement the interfaces and the preferred settings forthe configuration file. You decide whether to define attribute values in theconfiguration file or the adapter code. You then compile and, if required, link theadapter.

Before you begin

Sample adapter codeSample adapter code for the C and Java languages can be found in theEIFSDK directory.

Data transfer APIsData is transferred to the event server by assembling an event string. Thetec_put_event function or sendEvent method sends the string to the eventserver.

Compiling the adapterAdapters can be built using either the C or Java API.

Adapters built using the Event Integration Facility are not thread-safe andcannot be multithreaded.

Compiling the adapter built with the Java APITo compile a Java source that uses the Event Integration Facility Java API,import evd.jar into your source file and ensure that evd.jar and log.jarare available on the compilation class path.


About this task

TheEvent Integration Facility provides a C API and a Java API to communicatewith the event server.

Table 5. APIs and their behaviors

Tasks Java API C API

Access configuration filesand read keyword data

TECAgent

getConfigVal

tec_agent_init

tec_agent_getenv

Establish and closecommunications with theevent server

TECAgent

disconnect

tec_create_handle

tec_destroy_handle

Send and receive events sendEvent

receiveEvent

registerListener

onMessage

tec_put_event

tec_get_event

tec_register_callback

tec_event_callback

Note: The locale is set independently of the Event Integration Facility, and calling thetec_create_handle API does not change the locale.

You use the functions and methods to handle the configuration files,communications, and data transfer.Related concepts:Appendix A, “Application programming interfaces,” on page 51The APIs for Tivoli Event Integration Facility are defined by C language functionsand Java methods and help you to build a custom adapter or an application thatreceives events.Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.“Testing and scripting” on page 18You can use the posteifmsg command-line utility and a Java class to send eventsmanually. posteifmsg and the Java class are useful for using shell scripts todevelop new adapters and for testing adapters after you create event groups andassignments, edit rules, or change how a server processes events. You can also usethem to troubleshoot event deliveries after you develop a new adapter.

Upgrading existing adaptersTo upgrade existing adapters, link your adapters to the libeif.a library.

When upgrading existing adapters, relink your Event Integration Facility adaptercode with the libeif.a stub library. If you receive an undefined symbol errormessage, it means that the EIF function that you have been using is no longersupported. Update your code and compile and link again.Related concepts:Appendix A, “Application programming interfaces,” on page 51The APIs for Tivoli Event Integration Facility are defined by C language functionsand Java methods and help you to build a custom adapter or an application thatreceives events.


Related reference:“Linking the adapter built with the C API” on page 38These tables list the libraries required to link adapters developed with the C API.

Configuration file APIsThe first task performed by the APIs is accessing information from theconfiguration files.

To enable the tec_agent_getenv function or getConfigVal method, you first call theinitialization API (tec_agent_init or TECAgent). The initialization API reads inconfiguration information that is used by all subsequent functions or methods.Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Communications APIsThe communications APIs provide a mechanism to communicate with the eventserver. The handle is specified when sending an event.

Regardless of the type of transport mechanism, use a single call totec_create_handle (or TECAgent) to establish communications with the server. Thefollowing code example instantiates TECAgent, passing as parameters theconfiguration file, the delivery mode, and the error-reporting mechanism:public TECAgent(reader configStream, int deliveryMode, int oneway)

Call the tec_destroy_handle function or disconnect method when you no longerwant to communicate with the event server. This call is optional, because thechannel automatically disconnects when the adapter exits.

Special considerations for Microsoft WindowsAn adapter built for Microsoft Windows operating systems must initialize theWinsock before calling tec_create_handle.

The following example of a Microsoft Windows adapter initializes Winsock beforecalling tec_create_handle:#ifdef WIN32#include <winsock.h>

WSADATA wsaData;

if ((rc = WSAStartup(MAKEWORD(1, 1), &wsaData)) != 0) {printf("error %d starting winsock.dll\n", rc);exit(1);

}

elseprintf("Winsock initialized successfully...\n");

#endif

An application must call the WSAStartup function to initialize Winsock, regardlessof which version of Winsock is being used.

WSAStartup initialized Winsock2.dll and a WSADATA structure that contains thedetails of the Winsock implementation. When an application or DLL has finished


using Winsock2.dll, it must call WSACleanup to enable Ws2.dll to free anyresources for the application. For every call to WSAStartup, there must be a call toWSACleanup.

If successful, WSAStartup returns 0. After WSAStartup returns, an applicationcannot call WSAGETLastError to determine the error value.

Compiling the adapter built with the C APITo compile a source file that uses the Event Integration Facility C API, you need toinclude the tec_eeif.h header file.

When compiling the sample adapter on Windows, you must specify the PC flag asa compiler argument to avoid compile-time errors.

To link the sample adapter, you must use the NODEFAULTLIB:LIBC.LIB optionwhen linking the adapter on Windows. This allows the linker to avoid conflictswith the default libraries.

If there are mutliple wsock32.lib files, you must use the FORCE:MULTIPLE optionwhen compiling the Windows adapter. This forces the compiler to pick one file toeliminate compile-time errors. In conjunction with the FORCE:MULTIPLE option,the INCREMENTAL:NO option must also be used.

Example

The following example shows how to compile and link a sample adapter using theoptions mentioned above:unsecure: adapter.c \$ (CC) -nologo -Ze -W3 -MD -DUNSECURE -D_WIN32 -DWIN32 -DPC \-Ic:/Tivoli/include/w32-ix86/TME/TEC -Id:/msdev/include -FosampleAdapter.obj-c sampleAdapter.c \slashes link -subsystem:console -L. -Ld:/msdev/lib -Lc:/Tivoli/lib/w32-ix86 \-out:sampleAdapter.exe sampleAdapter.obj msvcrt.lib libeif.a \libsunrpc.a -NODEFAULTLIB:LIBC.LIB -INCREMENTAL:NO -FORCE:MULTIPLE wsock32.lib

Linking the adapter built with the C APIThese tables list the libraries required to link adapters developed with the C API.

Table 6. Libraries for adapters developed with the Event Integration Facility C API

Libraries Provided by More details

libeif.a Tivoli Event IntegrationFacility

None

libdl.a Operating system Not on Windows andHPUX

libpthreads.a Operating system For adapters on AIX

libpthread.a Operating system For adapters on Linux

libnsl.a

libsocket.a

libthread.a

Operating system For adapters on the SolarisOperating Environment

libsunrpc.a Tivoli Event IntegrationFacility

For adapters on Windows


Table 6. Libraries for adapters developed with the Event Integration Facility CAPI (continued)

Libraries Provided by More details

Standard C libraries Operating system None

Related reference:“Transport options” on page 14An application can use the Event Integration Facility API to act as an event senderor an event receiver. The transport options for connections are either SOCKET orSecure Sockets Layer (SSL), and are defined in the EIF configuration file.“Upgrading existing adapters” on page 36To upgrade existing adapters, link your adapters to the libeif.a library.

Installing, configuring, and testing the adapterAfter assembling all the files for the adapter, you need to install, configure, andtest the adapter before running it.

After installing the adapter, you can also add other features to the adapter. Forexample, you can modify the adapter to enable the following features:v Event filteringv Event caching for failure and recovery

Before installing your new adapter in a production environment, test at aminimum the following functionality:v Does the adapter successfully install?v Are events mapped to the appropriate event classes?v Are events arriving and displaying on the console, if applicable?v Are events correctly filtered?Related concepts:“Event delivery when systems fail” on page 24To ensure that events are delivered after system failures, the Tivoli EventIntegration Facility provides a cache on the adapter.Related reference:“Testing and scripting” on page 18You can use the posteifmsg command-line utility and a Java class to send eventsmanually. posteifmsg and the Java class are useful for using shell scripts todevelop new adapters and for testing adapters after you create event groups andassignments, edit rules, or change how a server processes events. You can also usethem to troubleshoot event deliveries after you develop a new adapter.

Running adapters built with the Event Integration Facility Java APIThe Event Integration Facility Java API depends on other classes to accomplish itstasks. In addition to setting up the appropriate environment using the setup_envcommands, you must add the path to the Java executable file to your library pathenvironment variable.

The following tables list the Java jar files and libraries required to run an adapterthat is built using the Event Integration Facility Java API.


To run an adapter that uses the Java Event Integration Facility API, you must addthe required libraries to your CLASSPATH environment:

Table 7. Libraries required for adapters developed with the Event Integration Facility JavaAPI

Required Libraries Provided by More details

evd.jar

log.jar

Tivoli Event Integration Facility None.

ibmjssefips.jar

ibmjsseprovider2.jar

Tivoli Event Integration Facility Optional, for SSLsupport only.

Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Configuring adapters for international environmentsThe event server can receive events in both UTF-8 encoding or the encoding of theevent server host. The event server automatically determines the type of encoding(UTF-8 or non-UTF-8) of an event by evaluating a particular flag in the event data.Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.


Chapter 5. Filtering events at the source

One of the problems associated with event management is working with the highvolume of events that devices can generate. You can address this problem byfiltering events at the source.

A high volume of events can be generated, for example, if a router has droppedbelow a key performance threshold, such as the amount of time to return a ping.Typically, the router would be set to generate an event every 30 seconds until anoperator has found and addressed the underlying problem. This would causeredundant events to flood the event console, impacting the problem-solvingprocess.

Tivoli Event Integration Facility addresses this problem with two powerfultechniques for analyzing, summarizing, and distributing the incoming eventinformation:

Filtering with configuration filesBy using configuration files on adapters and gateways, you can filterevents based on matches to event classes.

This is the simpler and limited option in terms of capabilities.

When defined correctly, configuration files optimize event management byminimizing the number of events that each operator must monitor.Related concepts:“Event filtering” on page 6Event filtering reduces complexity for console operators and improves responsetimes for complex system errors.

Filtering with configuration filesNormally, an adapter sends all events to the event server. You can optionally listthe events that the adapter can or cannot send to the event server by using theFilter and FilterCache keywords. Similarly, you can modify the configuration file tofilter events.

About this task

A configuration file can contain as many filter entries as needed. You specify theevent class and information such as the origin, severity, or any other attribute andvalue pair that is defined for the event class. Depending on how you specify theFilter and FilterMode keywords, filtered events are either sent to the event serveror discarded.

Procedure

Define event filters as follows:v To send all events to the event server (the default behavior):

1. Set FilterMode to OUT.2. Do not specify any Filter statements.

v To send specific events to the event server:


1. Set FilterMode to IN.2. Create Filter statements to match the specific events that you want sent.

v To discard all events:1. Set FilterMode to IN.2. Do not specify any Filter statements.

v To discard specific events:1. Set FilterMode to OUT (the default value).2. Create Filter statements to match the specific events that you want discarded.

Example

The following example shows two filters. The first filter suppresses all events withthe class disk_event. The second filter suppresses all events with the classSu_Success from the IP address 126.32.2.14.## Event Filters#Filter:Class=disk_eventFilter:Class=Su_Success;origin=126.32.2.14

Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Filtering events when systems failWhen an adapter is unable to connect to the event server , it sends the events to afile if the BufferEvents keyword is set to YES.

About this task

You can filter events sent to a cache file, similar to filtering events for the eventserver, by using the FilterCache keyword.

Note: To prevent the loss of data, the cache must be large enough to store allgenerated events in the event of an outage.

The following procedures describe how to filter events with the FilterCache andFilterMode keywords, when the event server is unavailable:v To cache specific events:

1. Set FilterMode to IN.2. Set BufferEvents to YES (the default value).3. Create Filter and FilterCache statements to match the specific events that you

want cached.v To discard specific events:

1. Set FilterMode to OUT.2. Create Filter and FilterCache statements to match the specific events that you

want discarded.v To cache all events (the default behavior):

1. Set FilterMode to OUT.2. Set BufferEvents to YES.3. Do not specify any FilterCache statements.


Note: All events are discarded when the configuration is as follows:1. FilterMode is set to IN.2. No FilterCache statements are specified.Related tasks:“Activating the cache” on page 24By default, the cache that ensures recovery after system failures stores events. Youcontrol the configuration of the cache with keywords in the configuration file.

Regular expressions in filtersYou can use Tcl regular expressions in filtering statements.

The format of a regular expression is:re:’value_fragment’

A regular expression is zero or more branches, separated by a vertical bar (|). Aregular expression matches anything that matches one of the branches.

A branch is zero or more pieces that are concatenated. It matches a match for thefirst, followed by a match for the second, and so forth.

A piece is an atom possibly followed by an asterisk (*), a plus sign (+), or aquestion mark (?). An atom followed by an asterisk (*) matches a sequence of 0 ormore matches of the atom. An atom followed by a plus sign (+) matches asequence of 1 or more matches of the atom. An atom followed by a question mark(?) matches a match of the atom, or the null string.

An atom is a regular expression in parentheses (matching a match for the regularexpression), a range, a period (.) (matching any single character), a caret (^)(matching the null string at the beginning of the input string), a dollar sign ($)(matching the null string at the end of the input string), a back slash (\) followedby a single character (matching that character), or a single character with no othersignificance (matching that character).

A range is a sequence of characters enclosed in brackets [ ]. A range matches anysingle character from the sequence. If the sequence begins with a caret (^), itmatches any single character not from the rest of the sequence. If two characters inthe sequence are separated by minus sign (-), this represents the full list of ASCIIcharacters between them. For example, the range [0-9] matches any decimal digit.To include a literal right bracket (]) in the sequence, use the right bracket (]) as thefirst character, following a possible caret (^). To include a literal minus sign (-), usethe minus sign (-) as the first or last character.

A sample program named regtest and a sample input file named regtest.dataare provided in the EIFSDK directory for testing regular expressions. The sample isprovided for each operating system in the <eifsdk>/bin/$INTERP directory.

Restriction:

1. The regular expression code is a slightly altered version of code originallywritten by Henry Spencer, Copyright 1986 by the University of Toronto. It isnot derived from licensed software. Permission is granted to anyone to use thissoftware for any purpose on any computer system, and to redistribute it freely,subject to the following restrictions:a. The author is not responsible for the consequences of use of this software,

even if they arise from defects in it.

Chapter 5. Filtering events at the source 43

b. The origin of this software must not be misrepresented, either by explicitclaim or by omission.

c. Altered versions must be plainly marked as such, and must not bemisrepresented as being the original software.

2. The Event Integration Facility uses an exception to the Tcl regular expressionsyntax. The backslash character (\) in the Event Integration Facility indicatesthat the following literal character is the character to filter for, not some specialcharacter such as a tab. For example, \t means the tab character in Tcl, butmeans t in Event Integration Facility.

The following example shows a Filter statement with a regular expression. Thisfilter statement matches all events with a class name that starts with TEC_Filter:Class=re:’TEC_.*’

The following example shows a FilterCache statement with a narrower range. Thisfilter statement matches all events with a class name that starts with TEC_ and hasa severity of critical:FilterCache:Class=re:’TEC_.*’;severity=CRITICAL

For more information about Tcl regular expressions, see a Tcl user's guide.


Chapter 6. Troubleshooting

You can troubleshoot problems that can arise installing and using the Tivoli EventIntegration Facility. The logs and tracing utilities can help you determine thesource of problems when they occur. Before systems fail, you can configure the APIto insure the delivery of events. Additionally, you can improve the performance ofevent delivery with API configurations.

Message logsIn problem-solving situations, you need to understand how to interpret messagesand what actions you can take to resolve a problem. You use the message log filesto troubleshoot problems in your environment.

To generate log messages for the Java API, you specify keywords in theconfiguration file.

Use the LogLevel and LogFileName keywords to specify the amount anddestination of messages.

For the C API, you specify the ed_diag_config_file keyword.Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.

Trace logsTrace logs assist you in determining why a problem is occurring. Trace loggingcaptures information about the operating environment when the Tivoli EventIntegration Facility fails to operate as intended.

Customer Support personnel use the information captured by trace loggers to tracea problem to its source or to determine why an error occurred. These tools are notenabled by default. Because trace messages are intended for Customer Support,they are generally written to a file that can be viewed for later examination.

Note: Trace logging produces a lot of information and can result in large tracefiles. For this reason, enable trace logging only temporarily and disable it whenyou have enough information.

To generate trace messages for the Java API, you must specify keywords in theposteifmsg configuration file. Use the TraceLevel and TraceFileName keywords tospecify the amount and destination of tracing.

For the C API, you must specify the ed_diag_config_file keyword.

Typically, you will send the /tmp/tec_ed file and the EIF Probe debug log toCustomer Support.


Generating trace messages for the C API

To enable trace logging for the C API, use the following steps:1. In the /tmp directory, write the following contents to a file and name the file

.ed_diag_config:Highest_level trace2Truncate_on_restart true

tec_ed Highest_level trace2

# cache and buffering

tec_ed ed_buffer trace2 /tmp/tec_edtec_ed ed_cache trace2 /tmp/tec_edtec_ed ed_cache_controller trace2 /tmp/tec_ed

# cMain drivers

tec_ed ed_agent_comm trace2 /tmp/tec_edtec_ed ed_agent_util trace2 /tmp/tec_edtec_ed ed_tc trace2 /tmp/tec_ed

# TRANSPORTS

tec_ed ed_fwk_t trace2 /tmp/tec_edtec_ed ed_lcf_t trace2 /tmp/tec_edtec_ed ed_socket_t trace2 /tmp/tec_ed

# SOCKETS

tec_ed ed_eipc trace2 /tmp/tec_edtec_ed ed_socket_impl trace2 /tmp/tec_edtec_ed ed_socket_impl trace2 /tmp/tec_edtec_ed ed_socket_rcv trace2 /tmp/tec_ed

# API calls to eipc

tec_ed ed_c_recv_msg trace2 /tmp/tec_edtec_ed ed_c_ipc_poll trace2 /tmp/tec_edtec_ed ed_c_ipc trace2 /tmp/tec_edtec_ed ed_c_ipc_accept trace2 /tmp/tec_edtec_ed ed_c_pool trace2 /tmp/tec_edtec_ed ed_c_ipc_server trace2 /tmp/tec_ed

# API calls to ipc

tec_ed ed_recv_msg trace2 /tmp/tec_edtec_ed ed_ipc_poll trace2 /tmp/tec_edtec_ed ed_ipc trace2 /tmp/tec_edtec_ed ed_ipc_accept trace2 /tmp/tec_edtec_ed ed_pool trace2 /tmp/tec_edtec_ed ed_ipc_server trace2 /tmp/tec_edtec_ed ed_evmsg trace2 /tmp/tec_ed

# misc

tec_ed hn_target trace2 /tmp/tec_edtec_ed EdDiag trace2 /tmp/tec_ed

2. Add the following property setting to the posteifmsg configuration file:ed_diag_config_file=/tmp/.ed_diag_config

3. Replicate the problem that requires the trace information.4. Remove the ed_diag_config_file property setting from the posteifmsg

configuration file.


Related reference:Appendix D, “Configuration keywords,” on page 67Use the keywords in the configuration file to configure the behavior of theadapters.“posteifmsg” on page 18Use the posteifmsg utility to post events to the ObjectServer via the Probe forTivoli EIF. After you install the Event Integration Facility, the posteifmsg binary filecan be copied to other hosts.

Performance and availabilityThe Tivoli Event Integration Facility can control performance and availability forevent processing.

To prevent overloading with event delivery, you can add timers for event delivery,and specify the maximum number of events in the cache.

When using timers, the Event Integration Facility notifies the event receiver thatthere are cached events. This occurs when the timer expires or when the maximumnumber of events is exceeded. Therefore the receiver can process the whole cachecontents at once.

Additionally, you can increase the availability of events by setting up backupservers.Related tasks:“Activating the cache” on page 24By default, the cache that ensures recovery after system failures stores events. Youcontrol the configuration of the cache with keywords in the configuration file.“Configuring backup servers to deliver events” on page 25The configuration uses TCP sockets to deliver events. You specify how to contactbackup servers by defining the transport channel to be the server name and theport number.

Event reception connection parametersThe reception process creates a server socket that listens on a specified port. Thelistening process marks a connection-mode socket as accepting connections andlimits the number of outstanding connections in the queue of the listening socketto the value specified by the ConnectionsQueued value.

Note: This information is specific to the C API. The Java version of the EIF probedoes not operate as described here.

The implementation can include incomplete connections in the queue subject to thequeue limit. Implementations can limit the length of the queued listening socket byspecifying ConnectionsQueued.

TCP/IP allows data to be sent and the connection to be closed by the senderbefore the receiving application can receive the data. The reception processeventually accepts the connection and processes the data. ConnectionsQueuedallows these types of connections to be limited. Connection attempts are refusedwhen TCP/IP can no longer queue up connections.

Chapter 6. Troubleshooting 47

The number of active connections handled by the reception process can be limitedby the ActiveConnections keyword. This prevents the reception process fromaccumulating too many connections that consume system resources.

If all of the initial connections are ConnectionOriented and the ActiveConnectionshave been reached, then no more connections are accepted by the receptionprocess. However, connections are still being considered by the TCP/IP up to theamount of ConnectionsQueued has been reached and if all ActiveConnections areconnection oriented then the state remains unchanged until the number of activeconnections is reduced to the amount specified by the percentage ofActiveConnections through the use of ActiveConnectionsSafety.

Note: The connections that were handled by TCP/IP (ConnectionsQueued) arediscarded when the program ends. The connections that are in theActiveConnections list are all closed and any data, residing on the connections, isdiscarded.

Common problems and scenariosWhen using the Tivoli Event Integration Facility you can encounter a number ofcommon problems and scenarios.

Building and running adaptersA number of scenarios can occur when there are problems building, compiling,and running the adapter.

My adapter on a Windows operating system has compile-time errors

Cause There are multiple wsock32.lib files.

RemedyUse the FORCE:MULTIPLE option when compiling the WindowsNT adapter.

This forces the compiler to pick one file.

I changed the configuration file, but my changes do not take effect

Cause There could be improperly specified statements in theconfiguration file.

RemedyReview the following for the changed keywords:v Check for typos in the spelling of keywords.v Ensure that any blank spaces are enclosed in single quotation

marks.

I received a LOG0014E error

Cause The system cannot find the file specified by the LogFileNamekeyword.

RemedyCorrect the path name specified by the LogFileName keyword.


Making connections to the event serverA number of scenarios can occur when there are problems connecting to the eventserver.

I received a connection error when I use posteifmsg

Cause The error indicates that you might be using a user ID other thanAdministrator or root. Therefore your ID does not have the correctpermissions to create and write the file specified by the BufEvtPathkeyword.

RemedyEnsure that you have the correct permissions for creating the filespecified by the BufEvtPath keyword.

Related reference:“posteifmsg” on page 18Use the posteifmsg utility to post events to the ObjectServer via the Probe forTivoli EIF. After you install the Event Integration Facility, the posteifmsg binary filecan be copied to other hosts.

Sending eventsCommon problems that can occur when events are sent to the event server.

My adapter is not sending all the events to the event server.

Cause There is either a communication problem between the adapter andthe event server, or there is a problem internal to the adapter code.

RemedySend events to a file instead of directly to the event server. Then,verify the event delivery, as follows:1. Set the TestMode keyword to YES in the adapter configuration

file.2. Specify the file to receive the events with the ServerLocation

keyword.3. Restart the adapter.4. Review the file that is specified by the ServerLocation keyword

and check to see whether all the events appear there.

If all events appear in the file, then there is a communicationproblem with the event server. If the events are missing from thefile, then there is problem internal to the adapter. Check theadapter code.

After you test the adapter, reset the TestMode keyword so thatevents are sent to the event server and no longer directed to a file.

I am using the posteifmsg command to send events, but they are not arriving atthe event server

Cause The events are being sent to the cache on the adapter or gatewaybecause of one of the following situations:v The -S option expects that a portmapper, or similar program, is

running at the receiving machine. For Windows systems, there isno portmapper daemon.

v A non-valid port, host name, or event server was specified.

Chapter 6. Troubleshooting 49

RemedyResolve the non-valid name or port issues.

Multi-byte characters in an event that is generated by posteifmsg are garbledFor locales that use multibyte characters: A message in an event that isgenerated by posteifmsg is garbled. The garbled message can be seen inthe event list, the debug log of the Probe for Tivoli EIF, and the cache fileof the posteifmsg utility.

Cause The posteifmsg utility fails to convert local DBCS message, such asJapanese, to UTF-8 encoded characters if the TISDIR environmentvariable is not set.

RemedySet the TISDIR environment variable to the path to the codesetdirectory before you run the posteifmsg utility. This directory isincluded in the EIF SDK for Tivoli Netcool/OMNIbus.

To set this environment variable:1. Run the following command:

# export TISDIR=/path_to_extracted_eif-sdk_package/codeset

2. Then, run the following command:# posteifmsg -f /path_to_configuration_file -r CRITICAL-m "DBCS included message" CLASS SOURCE

posteifmsg processes do not completeIf a cache file is shared by multiple posteifmsg processes, someposteifmsg processes do not complete. Instead, the processes hang.

Cause Multiple instances of the posteifmsg utility cannot share asingle cache file.

RemedySpecify unique configuration files for each instance ofposteifmsg. You can specify a cache file in configurationfile for each instance of posteifmsg.

Alternatively, use the nco_postmsg utility, which can share asingle cache file across multiple instances. If you use thissolution, ensure that you specify a unique log file for eachinstance of nco_postmsg by using the -messagelogcommand-line option.

Related reference:“posteifmsg” on page 18Use the posteifmsg utility to post events to the ObjectServer via the Probe forTivoli EIF. After you install the Event Integration Facility, the posteifmsg binary filecan be copied to other hosts.


Appendix A. Application programming interfaces

The APIs for Tivoli Event Integration Facility are defined by C language functionsand Java methods and help you to build a custom adapter or an application thatreceives events.Related tasks:“Programming the adapter” on page 35To program an adapter, you implement the interfaces and the preferred settings forthe configuration file. You decide whether to define attribute values in theconfiguration file or the adapter code. You then compile and, if required, link theadapter.Related reference:“Upgrading existing adapters” on page 36To upgrade existing adapters, link your adapters to the libeif.a library.

C language APIIn order to build a custom adapter in the C language, you must have a C compiler.

tec_agent_getenvThe tec_agent_getenv function retrieves the value of the variable contained in theconfiguration file.

Synopsischar *tec_agent_getenv(char *keyword)

Arguments

keywordThe keyword variable to retrieve.

Examples#include "tec_eeif.h"char *serverLoc=tec_agent_getenv("ServerLocation")

Return codes

Returns a pointer to a string which is the value of the variable. Do not free thispointer. Returns a NULL if the keyword does not appear in the configuration file.

tec_agent_initThe tec_agent_init function is an initialization function that reads the configurationfile and caches the information.

Note: The tec_agent_init function is the first function called to initialize the TivoliEvent Integration Facility module. Only call the tec_agent_init function once foreach adapter, and call it before any of the other functions.

Synopsisint tec_agent_init(char *cfgfile)


Arguments

cfgfile The full path to the configuration file.

Examples#include "tec_eeif.h"tec_agent_init(“config”);

Return codes

Returns 0 if successful.

tec_create_EIF_handleThe tec_create_EIF_handle function establishes a handle for sending events to theevent server or receiving events from a source with the first argument specifying aconfiguration file. A handle is created using the configuration information specifiedin the configuration file. This function is similar to tec_create_handle.

Synopsistec_handle_t tec_create_EIF_handle(char *cfgfile, int oneway,delivery_mode mode)

Arguments


onewayUsed for managed node adapters only, and is used to designate whethercalls to tec_put_event returns exceptions to the caller in the event offailure. A value of one (1) means that exceptions, if any, are not returned tothe caller of tec_put_event because the caller does not wait for a responsefrom the oserv process. A value of zero (0) means that exceptions arereturned to the caller because the caller waits for the oserv process toreturn the success or failure of the method.

mode The possible values are the following:v submissionv reception

Use the submission mode when the handle is used for transmitting. Usethe reception mode when the handle is used for receiving.

Examples#include "tec_eeif.h"if((th =tec_create_EIF_handle("config",0,submission))==NULL){

fprintf(stderr,"%s:tec_create_handle failed errno=%d \n ",progname,tec_errno);

exit(1);}

Return codes

A handle to an internal data structure. The handle is used in calls to other APIfunctions.


tec_create_handleThe tec_create_handle function establishes a handle for sending events to theevent server.

Synopsistec_handle_t tec_create_handle(char *location, unsigned short port,int oneway, tec_delivery_type type)

Arguments

locationThe host name or host protocol address of the event server.


port The port the event server listens on.

type The possible values are the following:v connection_lessv connection_orientedv use_default

The use_default value reads the setting from the configuration file for theConnectionMode keyword and sets up a connectionless handle if theConnectionMode keyword is not specified.

Examples#include "tec_eeif.h"if((th = tec_create_handle(tec_server, port, oneway, type)) == NULL) {

fprintf(stderr, “%s: tec_create_handle failed errno=,progname, tec_errno);

exit(1);

}

Return codes

A handle to an internal data structure. The handle is used in calls totec_put_event. If the location is NULL, the configuration file ServerLocation entry isused to derive the location. If the port is zero, the ServerPort entry is used, if any;or else the portmapper is queried for the port on which the event server listens.

Appendix A. Application programming interfaces 53

tec_create_handle_cThe tec_create_handle_c function establishes a handle for sending events to theevent server or receiving events from a source with the first argument specifying aconfiguration file. A handle is created using the configuration information specifiedin the configuration file. This function is similar to tec_create_handle.

Synopsistec_handle_t tec_create_handle_c (char *cfgfile,char *location, unsigned shortport, int oneway, tec_delivery_type type, delivery_mode mode)

Arguments



mode The possible values are the following:v submissionv reception

Use the submission mode when the handle is used for transmitting. Usethe reception mode when the handle is used for receiving.


port The port the event server listens on for non-TME versions.



Examples#include "tec_eeif.h"if((th=tec_create_handle_c("config","tecserver.com",5529,0,connection_less,submission))

==NULL){fprintf(stderr,"%s:tec_create_handle failed errno=%d \n ",

progname,tec_errno);exit(1);

}

Return codes

A handle to an internal data structure. The handle is used in calls to tec_put_event.If the location is NULL, the configuration file ServerLocation entry is used toderive the location. If the port is zero, the ServerPort entry is used, if any; or else


the portmapper is queried for the port on which the event server listens.

tec_create_handle_rThe tec_create_handle_r function establishes a handle for sending events to theevent server with the first argument specifying a configuration file. A handle iscreated using the configuration information specified in the configuration file.Similar to tec_create_handle.

Synopsistec_handle_t tec_create_handle_r (char *cfgfile,char *location, unsigned shortport, int oneway, tec_delivery_type type)

Arguments




port The port the event server listens on for non-TME versions.



Examples#include "tec_eeif.h"th = tec_create_handle_r(“config”,“localhost”,1234, 0, use_default)) == NULL) */

Return codes

A handle to an internal data structure. The handle is used in calls to tec_put_event.If the location is NULL, the configuration file ServerLocation entry is used toderive the location. If the port is zero, the ServerPort entry is used, if any; or elsethe portmapper is queried for the port on which the event server listens.


tec_destroy_handleThe tec_destroy_handle function destroys the handle to the event server created bytec_create_handle, tec_create_handle_c, tec_create_EIF_handle, andtec_create_handle_r and closes any established connections.

Synopsisvoid tec_destroy_handle (tec_handle_t th)

Arguments

th The tec handle returned from a call to a create_handle function.

Examples#include "tec_eeif.h"tec_destroy_handle(th);

tec_errnoWhen a function returns an error, the tec_errno function is set to the appropriateerror code.

Synopsisextern int tec_errno

tec_get_eventThe tec_get_event function allows an application to receive events. It receivesevents from the configured transport, on demand. The data returned can containmore than one event. Use the ed_scan_n utility to determine the number of events.The memory allocated for the event must be freed.

Synopsislong tec_get_event (tec_handle_t th, unsigned char ** event_message);

Arguments

th The event server handle returned from a call to a create_handle function.

event_messageContains the event data of the message received from a transport.

Examples#include "tec_eeif.h"char *event;long event_len;int rc;

event=NULL;event_len = tec_get_event(th, &event);if (event && event_len){n =ed_scan_n (event,event_len);}if (event)

free(event)

Return codes

Returns the length of the event message. Returns 0 (zero) when no events areavailable.


tec_put_eventThe tec_put_event function sends an event to the event server.

Note: If buffering is enabled in the configuration file, events are placed into abuffer and then sent on a separate thread. If a call to tec_put_event is followed bya call to tec_destroy_handle, the handle might be destroyed before the event can besent. To prevent this from happening, use the ed_sleep utility function aftertec_put_event to allow time for the event to be sent:ed_sleep(0,100);

Synopsislong tec_put_event (tec_handle_t th, char *event)

Arguments

event The character string representing the event.


Examples#include "tec_eeif.h"if ( tec_put_event(th, event_string) == -1 {

fprintf(stderr, “%s: tec_put_event failed, errno=,progname, tec_errno);

exit(1);

}

Return codes

Returns the number of bytes sent to the event server, other applications listeningfor events, or the cache file. A zero return means the event is filtered out. Anegative return indicates an error.

tec_register_callbackThe tec_register_callback function allows an application to receive events throughan upcall. The application registers a callback, passing as a parameter the methodthat handles the received events.

tec_event_callback syntax

The syntax for tec_event_callback is as follows:int (*tec_event_callback)(tec_handle_t h, unsigned char *msg, long _msg_len);

The data returned can contain more than one event. Use the ed_scan_n utility todetermine the number of events returned. The memory allocated for the eventmust be freed.

The tec_event_callback function returns –1 or zero (0). A zero indicates that therewere no errors and that the event has been processed. A –1 indicates that there wasa problem processing the event and to not remove it from the cache if one isconfigured.

Synopsisvoid tec_register_callback(tec_handle_t th, tec_event_callback *fn)


Arguments


fn The function to be called when the event arrives.

Examples#include "tec_eeif.h"int on_message (tec_handle_t th, unsigned char *event, long event_len){long n;if (event && event_len){

int i;char *ev;long len;long idx = 1;

n =ed_scan_n (event,event_len);for(i =0;i <n;i++,idx++){

ev =(char *)ed_scan_get_n ((char *)event, idx, event_len, &len);free (ev);

}}return 0;}

tec_register_callback(th,on_message)


Appendix B. Utilities for the C API

Tivoli Event Integration Facility provides a number of utilities for the C API.

ed_scan_get_nEvents received through the reception API can contain more than one event. Usethe ed_scan_get_n utility to get the n'th event from the packet.

Synopsischar * ed_scan_get_n (char *packet,long index,long packet_len, long *result_len);

Arguments

packet The pointer returned by tec_get_event or passed to the callback whentec_register_callback is used.

index The n'th element in the packet starting at 1.

Packet_lenThe maximum length of the packet to search.

Result_lenContains the resulting length of the packet.

Examples#include "tec_eeif.h"char *packagechar *ev;int i;long n,len,idx=1;

package=tec_get_event(th);

n = ed_scan_n (package, strlen (package));for (i = 0; i < n; i++, idx++){ev =(char *) ed_scan_get_n ((char *) package, idx, strlen (package),&len);free (ev);}

Return codes

Returns a pointer to a newly allocated buffer containing the requested event. Thispointer must be freed.

ed_scan_nEvents received through the reception API can contain more than one event. Youuse the ed_scan_n utility to determine the number of events contained in thepacket.

Synopsis

long ed_scan_n (char *packet, long packet_len );


Arguments

packet The pointer returned by tec_get_event or passed to the callback whentec_register_callback is used.

Packet_lenThe maximum length of the packet to search.

Examples#include "tec_eeif.h"char *packagechar *ev;int i;long n,len,idx=1;

package=tec_get_event(th);

n = ed_scan_n (package, strlen (package));for (i = 0; i < n; i++, idx++){ev =(char *) ed_scan_get_n ((char *) package, idx, strlen (package),&len);free (ev);}

Return codes

Returns the number of events, zero (0) if none are found, and –1 when an erroroccurs.

ed_sleepThe ed_sleep utility pauses running for the specified duration, and allows threadsto switch. This utility is called by managed node adapters in the main loop torelease the execution of the internal threads.

Synopsis

int ed_sleep (long seconds, long millis);

Arguments

millis Specifies the amount of milliseconds.

secondsSpecifies the amount of seconds.

Examples#include "tec_eeif.h"/* pause for 3.5 seconds */ed_sleep (3, 500);

/* sleep duration is zero but yields briefly so other threads can run */ed_sleep (0, 0);

Return codes

Returns zero (0).


Appendix C. Java language API

To build an adapter in Java, you must have the Java compiler, version 6, 7 or 8.The Java API is provided in JAR files. After the Java 6 end of support, move toJava 7 or 8.

disconnectThe disconnect function closes any open connection to the event server.

Synopsisdisconnect()

Examplespublic synchronized void disconnect()

disconnect(time)The disconnect(time) function flushes the cache and then closes any openconnection to the event server.

Synopsisdisconnect (max_seconds_to_wait)

Arguments

Note: For all values, control is returned to the caller as soon as the cache isemptied.

< 0 Wait forever or until the cache is emptied. If the server is down, thisroutine will not return.

= 0 Send events from the cache while the connection remains up. This couldtake a long time if the cache is large.

>= 0 Stop emptying the cache after the specified number of seconds.

Examplespublic synchronized void disconnect(int max_seconds_to_wait)

getConfigValThe getConfigVal function retrieves the value of a variable contained in theconfiguration file.

SynopsisgetConfigVal (String key)

key Specifies the configuration keyword label.

Examplespublic String getConfigVal(String key)


Return codes

Returns the string value associated with key in the configuration file used toinitialize the TECAgent function.

If key is not in the configuration file, null is returned. For keywords such as Filter,which have multiple values, only the last value specified in the configuration filesis returned.

onMessageThe onMessage function handles the events received asynchronously from the API.

SynopsisonMessage (String event)

Arguments

event A string contained in the event, which is returned to the application.

Examplespublic void onMessage( String event )

Return codes

The application returns true if the received event was processed with success,indicating to the API to remove the event from the cache or persistent log, or bothto avoid resending the event in the future.

The application returns false if the event was not processed with success,indicating to the API to resend the event to the event server for further processing.In this case, the event is not removed from the cache or persistent log, or both.

receiveEventThe receiveEvent function enables an application to receive events synchronously.It receives events from all the event servers specified in the configuration file usedto initialize the TECAgent function.

SynopsisString receiveEvent()

Examplespublic synchronized String receiveEvent()

Return codes

Returns event data that was received by this API. The delimiterTECEvent.TECAD_EVENT_END_CHAR (A) separates the events returned in thisstring.Related reference:“registerListener” on page 63The registerListener function registers the calling application as a listener, enablingthe asynchronous reception of events. You must pass an object that implements theIEventProcessing interface as a parameter.


registerListenerThe registerListener function registers the calling application as a listener, enablingthe asynchronous reception of events. You must pass an object that implements theIEventProcessing interface as a parameter.

SynopsisregisterListener (IEventProcessing)

Arguments

IEventProcessingThe application class that implements the IEventProcessing callback.

Examplespublic void registerListener (IEventProcessing)

Related reference:“receiveEvent” on page 62The receiveEvent function enables an application to receive events synchronously.It receives events from all the event servers specified in the configuration file usedto initialize the TECAgent function.

sendEventThis function sends events to the event servers specified in the configuration fileused to initialize the TECAgent function. You must pass a serialized TECEvent as aparameter. If the BufferEvents=YES keyword is specified, the events are cachedand persistent before they are sent.

SynopsissendEvent (String event)

Arguments

event Event data to be sent to the event server. If event is non-null, it must be atleast TECEvent.MIN_EVENT_LEN characters long, or sendEvent returnsimmediately with an error.

Examplespublic synchronized int sendEvent(String event)

Return codes

Returns the number of bytes sent to the event server, other applications listeningfor events, or the cache file. A zero return means the event is filtered out. Anegative return indicates an error.

Appendix C. Java language API 63

TECAgentThe TECAgent function accesses the configuration file and sets the transportmechanism. It is the top-level object that enables the sending and receiving ofevents to and from the event server.

SynopsisTECAgent (Reader configStream, int deliveryMode, boolean oneway)

Arguments

configStreamObject that reads the configuration keywords.

deliveryModeSpecifies the delivery mode. The values are SENDER_MODE and RECEIVE_MODE.

onewayThis parameter has no meaning.

Examplespublic TECAgent(Reader configStream, int deliveryMode, boolean oneway)

Return codes

An exception is raised if the TECAgent cannot be created.

TECEventThe TECEvent function encapsulates the code for parsing event definitions into aclass name and attribute=value pairs.

SynopsisTECEvent()init(String event)

Arguments

event The event string to be parsed. Here are some examples of valid eventstrings:Class1;msg=’text.’;hostname=artemis;source=TEC;ENDClass2;ENDClass3;msg=theMessage;END

A valid event string has the following form:ID SEMICLN ( ID = (STRING | VALUE | EMPTY_STRING) SEMICLN )* "END"[CTRL_A]

The tokens for the event string grammar are explained as follows:SEMICLN := ";"

EQUALS := "="

CNTRL_A := "\001"

ID := Any non-empty sequence of characters from the seta-z, A-Z, 0-9, _, -, .

containing at least one character froma-z, A-Z


STRING :=

Begins and ends with either single quotes or double quotes. Anyembedded quotes that are the same as the quotes being used to delimit thestring must be escaped with the same quote character. For example:v ’embedded single(’)’ would be written ’embedded single(’’)’v "embedded double(")" would be written "embedded double("")"v "embedded single(’)" would be written "embedded single(’)"

Note: STRING tokens cannot contain the NUL character (’\000’) orcontrol-A (’\001’)VALUE :=

Any non-empty sequence of characters excluding the following:v all ASCII control characters ("" - "")v the space character (" ")v the single quote ("’")v the equal sign ("=")v the semi-colon (";")

EMPTY_STRING := This token represents an empty string. Quotes are notneeded for this value.

The first ID token is the class name of the event. The sequence of instancesof "ID=(STRING|VALUE);" specifies the slot/value pairs and"END" marks theend of the event. The terminating character Â is optional. Each ID used asa slot name must be unique with respect to all the other IDs used as slotnames and the slot name cannot be "END". There can be an arbitraryamount of whitespace (characters " ", "\t", "\r", "\n") before and afterany of the tokens in an event string, with the following exception. If aterminating Â is present, nothing can appear after it. Examples of validevent strings are as follows:Class1;

msg=’embedded quote ’’.’ ;hostname=artemis;

END

Class2;ENDÂClass3; msg = theMessage ; ENDClass4;

msg=’Here’’s a newlinerest of msg’;

END

Examplespublic boolean init(String event);

Return codes

The return code for the init() call is true when the event string is parsedsuccessfully, and false if it is not.

Appendix C. Java language API 65


Appendix D. Configuration keywords

Use the keywords in the configuration file to configure the behavior of theadapters.

Important: Not all keywords apply to all adapters. Some adapters have additionalkeywords that are specific to them. Adapters do not issue error messages formisspelled keywords or keywords that set to an invalid value.

Format

Keywords use the following format:keyword=value

Type each keyword on a separate line. Do not use blank spaces in keywordstatements unless enclosed in single quotation marks.

The following table lists the keywords that a configuration file can contain. Thesekeywords are common to most adapters. Some keywords are specific to the C APIor the Java API.

Table 8. Configuration keywords for the Event Integration Facility

Keyword Required or optional Description

BufEvtMaxSize Optional Specifies the maximum size, in kilobytes, of theadapter cache file. The default is 64 and theminimum size is 8. File sizes below this level areignored, and 8 KB is used. There is no upper limitfor the file size. The cache file stores events on diskwhen they cannot be sent to the event server andthe BufferEvents keyword is set to YES.Remember: If the cache file already exists, deletethe file for the changes to take effect.

BufEvtPath Required if theBufferEvents keywordis set to YES. Otherwiseoptional.

Specifies the full path of the adapter cache file. Thedefault is cache.dat.

BufferEvents Optional Specifies whether and how event buffering works.Possible values are as follows:

v YES (default): Events are stored in the file that isspecified by the BufEvtPath keyword.

v MEMORY_ONLY: Events are buffered in memory.

v NO: No events are stored or buffered.

If the BufferEvents keyword is set to YES, the APIalso stores the events in the files that are specifiedby the BufEvtPath keyword.

BufferFlushRate Optional Specifies the number of events that are sent perminute.

If a connection is lost and the buffer containsevents, the events are sent at this rate after theconnection is recovered.The default is 0, whichmeans that all events are sent at once.


Table 8. Configuration keywords for the Event Integration Facility (continued)


ConnectionMode Optional Specifies the connection mode that is used toconnect to the event server. Possible values are asfollows:

v connection_oriented (default): A connection isestablished when the adapter is initialization.The connection is maintained for all the eventsthat are sent. A new connection is establishedonly if the initial connection is lost. Theconnection is discarded after the adapter isstopped.

v connection_less: A new connection isestablished and discarded for each event orgroup of events that is sent.

Tip: You can shorten the connection_orientedoption to co or CO.

C

ed_diag_config_file Optional Writes log and trace messages to the ./diag_config

file, which is the default of this keyword. This filemust be present for logging and tracing to occur.

To enable logging, specify one of the followinglogging levels in the file:

v error

v warning

To enable tracing, specify one of the followingtracing levels in the file:

v trace0

v trace1

v trace2

If you increase the tracing level, the trace output isalso increased.

When the Event Integration Facility is restarted,the API truncates the /tmp/tec_ed trace file. Toavoid truncation, set the Truncate_on_restartkeyword to false.




Filter Required if theFilterCache keyword isset to YES. Otherwiseoptional.

Determines how events are filtered. This keywordis used in conjunction with the FilterModekeyword.

An event matches a filter statement when eachattribute=value pair in the filter statement isidentical to the corresponding attribute=valuepair in the event.

A filter statement must contain the event class.Optionally, it can also contain any otherattribute=value pair that is defined for the eventclass.

The format of a filter statement is as follows.

Filter:Class=class_name;[attribute=value;...;attribute=value]

Each statement must be on a single line. Theattribute=value pair is case sensitive.

FilterCache Optional Determines which events are stored in the cachewhen events cannot be sent to the event server.This keyword is used in conjunction with theFilterMode keyword and the Filter keyword.

To enable event caching, set the BufferEventskeyword to YES.

An event matches a FilterCache statement wheneach attribute=value pair in the FilterCachestatement is identical to the correspondingattribute=value pair in the event.

A FilterCache statement must contain the eventclass (class_name) and can include anyattribute=value pair that is defined for that eventclass.

The format of a filtering statement is as follows.

FilterCache:Class=class_name;[attribute=value;...;attribute=value]

Each statement must be on a single line. Theattribute=value pair is case sensitive. TheFilterCache statement must specify the same classor subset of classes that the filter statementspecifies.Note: If you use this keyword with endpointadapters, ensure that the filter statements at bothends are identical.

FilterMode Required if one or morefilter statements or filtercache statements aredefined. Otherwiseoptional.

Specifies whether events that match a filter or filtercache statement are sent to the event server ordiscarded. Possible values are as follows:

v IN: Events are sent to the event server.

v OUT (default): Events are discarded.




FQDomain Optional Valid only for the OpenView, SNMP, UNIX log file,and Windows event log adapters.

This keyword specifies how the adapter sets thevalue of the fqhostname attribute of events that aresent to the event server. This attribute is used tospecify the full qualified host name of theoriginating host. Possible values are as follows:

v YES: The adapter attempts to determine the fullyqualified host name. If the host name can bedetermined, the fqhostname attribute is set tothis host name. If not, the attribute has a nullvalue.

v NO: The fqhostname attribute has a null value.

v fully.qualified.domain.suffix: If you set thiskeyword to a fully qualified host name, thefqhostname attribute is set to the host nameappended with this value.

Java

LogFileName Optional Specifies the full path and file name of the log file.

The default is $TIVOLIHOME/tec/eif.log. If youspecify an invalid path name, the API returns thefollowing error:

LOG0014E Unable to open the handler outputfile <filename>.java.io.FileNotFoundException: <filename>(The system cannot find the path specified)

MaxPacketSize Optional Specifies the number of bytes to be sent at the ratethat is specified by the BufferFlushRate keyword.The default is 0, which means that one event issent at a time.

NO_UTF8_CONVERSION Optional Specifies whether the Event Integration Facilityencodes event data in UTF-8. Possible values are asfollows:

v YES: Event data is not encoded in UTF-8. Thedata is assumed to already be in UTF-8 encodingwhen it is passed to the Event IntegrationFacility. The data is prepended with the flagindicating that the data is in UTF-8 encoding ifthe flag does not exist at the beginning of theevent data.

v NO (default): Event data is encoded in UTF-8.

Pre37Server Required if you set thePre37ServerEncodingkeyword to a language.Otherwise optional.

Specifies whether the adapter sends events in thelanguage of the event server host or in UTF-8encoding. Possible values are as follows:

v YES: Disables UTF-8 encoding.

v NO (default): The adapter sends events in UTF-8encoding.

Pre37ServerEncoding Required if you set thePre37Server keyword toYES. Otherwise optional.

Determines which language to use when anon-TME adapter communicates with a non-UTF-8event server host.




RetryInterval Optional Used when the ConnectionMode keyword is set toconnection_oriented. This keyword specifies thetime, in seconds, that the adapter waits after theconnection to the event server is lost to reconnectto the primary or backup event server or buffer theevents. The adapter processes no new eventsduring this interval. The default is 120.

This keyword is useful because the adapter cansend all events to the primary event server even ifthe event server is briefly stopped, for example if anew rules base is loaded.Tip: If you use this keyword to wait for a restartedevent server, ensure that the interval is set tolonger than the time it takes to stop and restart theevent server.

ServerLocation Optional. This keywordis ignored if theTransportList keywordis set.

Specifies the host on which the EIF receiver isinstalled. Set the value of this keyword to eitherthe host name or the IP address. If you use the IPaddress, use the dotted format. The default islocalhost.

You can set a maximum of 8 values, separated bycommas (,). The first value defines the primaryevent server and any additional values are treatedas backup servers.Note: The ServerLocation keyword defines thepath and name of the file for logging events,instead of the event server, when used with theTestMode keyword.

ServerPort Depends on whichoperating system theevent server is installed:

v UNIX Linux

Optional

v Windows Required

This keyword is ignoredif the TransportListkeyword is set.

Specifies the port number on a non-TME adapteron which the event server only listens for events.

The default is 0, which means that the portnumber is retrieved by the portmapper. Changethis value only if the portmapper is not availableon the event server.

TestMode Optional Switches test mode on or off. Possible values are asfollows:

v YES: Test mode is switched on. Events are loggedin the file that is specified by the ServerLocationkeyword. The events are not sent to the eventserver.

v NO (default). Test mode is switched off. Eventsare sent to the event server.




Java TraceFileName Optional Specifies the full path and file name of the tracefile. The default is $TIVOLIHOME/tec/eif.trc. If youspecify an invalid path, the following error isreturned:

LOG0014E Unable to open the handler outputfile filename.java.io.FileNotFoundException: filename(The system cannot find the path specified)

Java TraceLevel Optional Switches on tracing. To generate the tracemessages, set this keyword to ALL. If you set thekeyword to any other value, no trace messages aregenerated.

Linux

Windows

AIX

Solaris

TransportList

Optional Defines the names of the transport mechanisms.Specify the transport mechanisms in acomma-separated list. For example:

TransportList=t1,t2,t3

If a transport mechanism fails when it is used by asender application, the API diverts to the transportmechanisms that are specified by this keyword, inthe order that they are specified. For receivingapplications, the API creates and uses all thetransport mechanisms.

This keyword is supported only for adapters onthe operating systems that are specified.

If you specify this keyword, also specify thetransport type and transport channel for transportmechanism. To specify this information, use theType and Channels keywords. For moreinformation about these keywords, see Table 9.

The following table describes the keywords for the transport type and transportchannel for each transport mechanism that is defined by the TransportListkeyword. In this table, each transport mechanism is represented by type_name.

Table 9. Keywords for transport mechanisms that are defined by the TransportList keyword

Header Header Header

type_nameType Required Specifies the transport type for a transport mechanism thatis defined by the TransportList keyword. Possible valuesare as follows:

v SOCKET

v SSL

The server for each transport mechanism, as defined bytype_name, is specified by the ServerLocation keyword.The port number is specified by the Port keyword.

If you set this keyword to SOCKET, also set the keywords inTable 10 on page 73. If you set this keyword to SSL, also setthe keywords in Table 11 on page 73.


Table 9. Keywords for transport mechanisms that are defined by the TransportList keyword (continued)

Header Header Header

type_nameChannels Required Specifies the user-supplied names of the channels for thetransport mechanisms that are specified by theTransportList keyword, in a comma-separated list. Forexample:

t1Channels=c1,c2,c3,c4

For each channel name, also set the channel_namePortkeyword.

channel_namePort Required Specifies the port number on which a transport mechanismlistens for a channel, as defined by the type_nameChannelskeyword.

If this keyword is set to 0, the portmapper is used.

channel_nameServerLocation=server[region]

Required Specifies the hostname or IP address of the server on whichthe EIF receiver is located for the specified channel.

Table 10. Additional keywords to set for SOCKET transport types

KeywordRequired oroptional Description

channel_namePortMapper Optional Switches the portmapper on or off. Possible values areas follows:

v YES: The portmapper is switched on.

v NO: The portmapper is switched off.

channel_namePortMapperName Optional Specifies the name of the portmapper, if theportmapper was switched on by setting thechannel_namePortMapper keyword.

channel_namePortMapperNumber Optional Specifies the ID that is registered by the remoteprocedure call.

channel_namePortMapperVersion Optional Specifies the version of the portmapper, if theportmapper was switched on by setting thechannel_namePortMapper keyword.

If the transport type for a transport mechanism, as defined by the TransportListkeyword, is set to SSL, set the keywords that described in the following table forthat transport mechanism.

Table 11. Additional keywords to set for SSL transport types


channel_nameSSLKeystore Required Specifies the path to the keystore thatcontains the keys and certificates thatare used for SSL authentication.

channel_nameSSLKeystorePW Required Specifies the password of thekeystore that is defined by thechannel_nameSSLKeystore password.Either this keyword or thechannel_nameSSLKeystoreStashFilekeyword must be used.


Table 11. Additional keywords to set for SSL transport types (continued)


channel_nameSSLKeystoreStashFile Required Specifies the path to the stash filethat contains the password of thekeystore that is defined by thechannel_nameSSLKeystore keyword.Either this keyword or thechannel_nameSSLKeystorePW keywordmust be used.

Java

channel_nameSSLKeystore

EncryptionKeyFile

Required if thechannel_nameSSLKeystoreStashFilekeyword is set.

Specifies the path to the file thatcontains the encryption key that isused to decode the data in the filethat is defined by thechannel_nameSSLKeystoreStashFilekeyword.

Java

channel_nameSSLTruststore

Required Specifies the path to the keystore thatcontains the keys and certificates thatare trusted by the Event IntegrationFacility for SSL authentication. If thiskeyword is not set, the file that isdefined by thechannel_nameSSLKeystore keyword isused as the truststore.

Java

channel_nameSSLTruststorePW

Required Specifies the password of thekeystore that is defined by thechannel_nameSSLTruststore keyword.

Java

channel_nameSSLTruststoreStashFile

Required Specifies the path to the stash filethat contains the password of thekeystore that is defined by thechannel_nameSSLTruststore keyword.

Java

channel_nameSSLTruststoreEncryptionKeyFile

Required if thechannel_nameSSLTruststoreStashFilekeyword is specified.

Specifies the path to the file thatcontains the encryption key that isused to decode the data that is in thefile that is defined by thechannel_nameSSLTruststoreStashFilekeyword.

channel_nameSSLCipherList Optional Specifies the ciphers that arepermitted for SSL authentication. Usea comma-separated list for multipleciphers. For example:

c1SSLCipherList=SSL_RC2_CBC_128_CBC_WITH_MD5,SSL_RC2_CBC_128_CBC_EXPORT40_WITH_MD5,SSL_DES_64_CBC_WITH_MD5

If no ciphers are specified, allavailable ciphers are permitted.


Table 11. Additional keywords to set for SSL transport types (continued)


channel_nameSSLFIPSMode Optional Controls whether the SSL handshakeoperates in FIPS 140-2 mode. Possiblevalues are as follows:

v ON: The handshake is in FIPS 140-2mode.

v OFF (default): The handshake is notin FIPS 140-2 mode.

FIPS 140-2 mode restricts the types ofcipher that can be used.

channel_nameSSLRequireClientAuthentication

Specifies whether an EventIntegration Facility application that isacting as a server requires acertificate from a client during an SSLhandshake.

This keyword is valid only in theserver SSL configuration. In the clientconfiguration, this keyword isignored.

Possible values are as follows:

v YES: An SSL handshake is required.

v NO (default): No SSL handshake isrequired.

The following example shows 2 transport mechanisms defined by theTransportList keyword and the associated keywords for the type_name andchannel_name keywords.TransportList=t1,t2t1Type=SSLt1Channels=c1,c2c1ServerLocation=sslhost1c1Port=1111

c1_SSLKeystore=/my/location/gbkeys.kdbc1_SSLKeystorePW=passwordc1_SSLKeystoreStashFile=/my/location/gbkeys.sthc1_SSLCipherList=SSL_RSA_WITH_3DES_EDE_CBC_SHA

c1_SSLFIPSMode=OFF

c2ServerLocation=sslhost2c2Port=2222

c2_SSLKeystore=/my/other/location/gbkeys.kdbc2_SSLKeystorePW=passwordc2_SSLCipherList=SSL_RSA_WITH_3DES_EDE_CBC_SHAc2_SSLFIPSMode=OFF

t2Type=SOCKETt2Channels=c3,c4c3ServerLocation=host1c3Port=1234c4ServerLocation=host2c4Port=5678

Related concepts:


“Configuration files” on page 3Use the configuration file to control the behavior of adapters. You do not need tomodify multiple instances of an adapter to run in different environments. Modifyonly the configuration files.“Connection options” on page 13The connection options are either connection-oriented or connectionless. Insituations where you want to send many events, you use the connection-orientedoption. In situations where you want to send few events over a period of time, youuse the connectionless option.“Selecting event delivery methods” on page 31While building an adapter, you also need to decide which event delivery methodthe adapter uses to communicate with the event server.“Configuration file APIs” on page 37The first task performed by the APIs is accessing information from theconfiguration files.“Configuring adapters for international environments” on page 40The event server can receive events in both UTF-8 encoding or the encoding of theevent server host. The event server automatically determines the type of encoding(UTF-8 or non-UTF-8) of an event by evaluating a particular flag in the event data.

“Message logs” on page 45In problem-solving situations, you need to understand how to interpret messagesand what actions you can take to resolve a problem. You use the message log filesto troubleshoot problems in your environment.“Trace logs” on page 45Trace logs assist you in determining why a problem is occurring. Trace loggingcaptures information about the operating environment when the Tivoli EventIntegration Facility fails to operate as intended.Related tasks:“Programming the adapter” on page 35To program an adapter, you implement the interfaces and the preferred settings forthe configuration file. You decide whether to define attribute values in theconfiguration file or the adapter code. You then compile and, if required, link theadapter.“Filtering with configuration files” on page 41Normally, an adapter sends all events to the event server. You can optionally listthe events that the adapter can or cannot send to the event server by using theFilter and FilterCache keywords. Similarly, you can modify the configuration file tofilter events.“Configuring an EIF receiver application for SSL” on page 32In order to use Secure Sockets Layer (SSL) communication between EIF receiverapplications and client applications, you must configure the receiver application.Receivers require a personal certificate that is either self-signed or signed by acertificate authority (CA).“Configuring an EIF client application for SSL” on page 33In order to use SSL communication between EIF receiver and client applications,you must configure the EIF client application.Related reference:“Sending events through firewalls” on page 23You can send events through firewalls depending on your environment andorganizational restrictions regarding firewall security.


“Event reception for applications” on page 22In addition to sending events, the Tivoli Event Integration Facility enables otherapplications to receive, that is, listen for, events.“SSL and FIPS 140-2 support” on page 14The Tivoli Event Integration Facility supports the use of the Secure Sockets Layer(SSL) encryption and authentication protocol to send and receive events. Inaddition, EIF SSL connections can operate in FIPS 140-2 mode, which means theuse of FIPS 140-2 approved cryptographic providers.“Adapter files” on page 29In addition to the header file or Java package, a number of files are related to theadapter. This section lists these files and shows the relationship between them andevent processing.“Running adapters built with the Event Integration Facility Java API” on page 39The Event Integration Facility Java API depends on other classes to accomplish itstasks. In addition to setting up the appropriate environment using the setup_envcommands, you must add the path to the Java executable file to your library pathenvironment variable.



Notices

This 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 inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, 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 IBMIntellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law: INTERNATIONALBUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULARPURPOSE. Some states do not allow disclaimer of express or implied warranties incertain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/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 forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct 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 itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation958/NH04IBM Centre, St Leonards601 Pacific HwySt Leonards, NSW, 2069Australia

IBM Corporation896471/H128B76 Upper GroundLondon SE1 9PZUnited Kingdom

IBM CorporationJBF1/SOM1294 Route 100Somers, NY, 10589-0100United States of America

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 document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have not


been thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs.

Portions of this product include software developed by Daniel Veillard.v libxml2-2.7.8

The libxml2-2.7.8 software is distributed according to the following licenseagreement:© Copyright 1998-2003 Daniel Veillard.All Rights Reserved. Permission is hereby granted, free of charge, to any personobtaining a copy of this software and associated documentation files (the“Software”), to deal in the Software without restriction, including withoutlimitation the rights to use, copy, modify, merge, publish, distribute, sublicense,and/or sell copies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIESOF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE ANDNONINFRINGEMENT. IN NO EVENT SHALL THE DANIEL VEILLARD BELIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER INAN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OFOR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHERDEALINGS IN THE SOFTWARE.Except as contained in this notice, the name of Daniel Veillard shall not be used inadvertising or otherwise to promote the sale, use or other dealings in this Softwarewithout prior written authorization from him.

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

TrademarksThese terms are trademarks of International Business Machines Corporation in theUnited States, other countries, or both:

AIXIBMNetcoolOS/390Passport AdvantageSystem zTivoliTivoli Enterprise ConsoleTMEz/OSzSeries

Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-basedtrademarks are either registered trademarks or trademarks of Adobe SystemsIncorporated in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries, or both.

Notices 81

Linux is a registered trademark of Linus Torvalds in the United States, othercountries, or both.

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

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

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


Index

Numerics64-bit libraries 1

Aaccessibility viiadapters

building 35overview 29

built with the C APIcompiling 38linking to libraries 38

C APIs 51compiling 35configuring 39event classes 30event delivery methods 31files 29identifying events 29installing 39internationalization 40Java API 61multithreaded 35overview 2required Java API files 39sample code 35testing 39upgrading 36Windows considerations 37

API utilitiesC

ed_scan_get_n 59ed_scan_n 59ed_sleep 60

APIsC 51

tec_agent_getenv 51tec_agent_init 51tec_create_EIF_handle 52tec_create_handle 53tec_create_handle_c 54tec_create_handle_r 55tec_destroy_handle 56tec_errno 56tec_get_event 56tec_put_event 57tec_register_callback 57

communications 37configuration files 37Java

disconnect 61disconnect(time) 61getConfigVal 61onMessage 62receiveEvent 62registerListener 63sendEvent 63TECAgent 64TECEvent 64

overview 51

attributesoverview 1

audience vavailability

events 47

Bbackup

servers configuration 25BAROC files 3

CC API

reception applicationconfiguration 27

utilities 59cache 24

activating 24certificate 14ciphers 14CLI commands 18communications

APIs 37configuration file

keywords 67configuration files

APIs 37filtering events 41

connection parametersevent reception 47

connectionsconnection-oriented delivery 13connectionless delivery 13

conventions, typeface vii

Ddaemon

portmapper 26directory structure 8disconnect 61disconnect(time) 61

Eed_scan_get_n 59ed_scan_n 59ed_sleep 60education

see Tivoli technical training viienvironment variables, notation viievent classes 30event delivery

connection options 13selecting methods 31transport options 14

Event Integration Facilityoverview 1what's new

64-bit libraries 1FIPS 140-2 1IPv6 support 1SSL 1transport types 1

event servers 4event transport

overview 13events 42

availability 47classes 3defining classes 30delivery methods 13delivery when systems fail 24example 4filtering 6, 41firewalls 23flow 29identification 4, 29monitoring 30reception

example 22reception connection parameters 47state correlation 41translated 1

Ffiles

root.baroc 3filtering

configuration files 41regular expressions 43state correlation 41

filtering eventssystem failures 42

filtering when system fails 42filters

event filtering overview 6FIPS 140-2 1, 14firewalls

sending events 23functions

disconnect 61disconnect(time) 61getConfigVal 61onMessage 62receiveEvent 62registerListener 63sendEvent 63tec_agent_getenv 51tec_agent_init 51tec_create_EIF_handle 52tec_create_handle 53tec_create_handle_c 54tec_create_handle_r 55tec_destroy_handle 56tec_errno 56


functions (continued)tec_get_event 56tec_put_event 57tec_register_callback 57TECAgent 64TECEvent 64

GgetConfigVal 61

IiKeyman 14installing 8IPv6 support 1

JJava API

overview 61

Kkeystore 14keywords

configuration file 67configuration files 3list 67

Llibeif.a library 14logs

messages 45trace 45

Mmanuals vmessage logs 45monitoring

events 30

Oonline publications vonMessage 62ordering publications v

Pperformance

preventing overloading 47portmapper daemon 26problem determination

troubleshooting 45publications v

RreceiveEvent 62

recoverysystems 24

registerListener 63regular expressions

filtering 43rules 6

SsendEvent 63SOCKET 14SSL 1, 14stash file 14support information viisystem failures 24

TTcl regular expressions

filtering events 43tec_agent_getenv 51tec_agent_init 51tec_create_EIF_handle 52tec_create_handle 53tec_create_handle_c 54tec_create_handle_r 55tec_destroy_handle 56tec_errno 56tec_get_event 56tec_put_event 57tec_register_callback 57TECAgent 64TECEvent 64Tivoli software information center vTivoli technical training viitrace logs 45training, Tivoli technical viitransport

options 14transport types 1troubleshooting

building and running adapters 48common scenarios 48connection error when using

posteifmsg 49event reception connection

parameters 47events sent error

general 49using posteifmsg 49

message logs 45overview 45trace logs 45

truststore 14typeface conventions vii

Uutilities

C API 59ed_scan_get_n 59ed_scan_n 59ed_sleep 60

Vvariables, notation for vii

WWindows

special considerations 37


IBM®

Printed in the Republic of Ireland

SC27-6267-00

Date post:	29-Aug-2018
Category:	Documents
Upload:	trancong
View:	255 times
Download:	2 times

IBM Tivoli Netcool/OMNIbus: Event Integration Facility ... · v IBM T ivoli Netcool/OMNIbus...

Documents