106
Netcool/OMNIbus Version 7 Release 4 Event Integration Facility Reference SC14-7533-01

IBM Omegamon Eif Master

Embed Size (px)

DESCRIPTION

IBM Omegamon Eif Master

Citation preview

  • Netcool/OMNIbusVersion 7 Release 4

    Event Integration Facility Reference

    SC14-7533-01

  • Netcool/OMNIbusVersion 7 Release 4

    Event Integration Facility Reference

    SC14-7533-01

  • NoteBefore using this information and the product it supports, read the information in Notices on page 87.

    This edition applies to version 7, release 4 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, 2012.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

  • ContentsAbout this publication . . . . . . . . vIntended audience . . . . . . . . . . . . vWhat this publication contains . . . . . . . . vPublications . . . . . . . . . . . . . . viAccessibility . . . . . . . . . . . . . . viiiTivoli technical training . . . . . . . . . . viiiSupport information . . . . . . . . . . . viiiConventions used in this publication . . . . . . ix

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

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

    Chapter 3. Event transport . . . . . . 15Event delivery methods . . . . . . . . . . 15

    Connection options . . . . . . . . . . . 15Transport options . . . . . . . . . . . 16Testing and scripting . . . . . . . . . . 20

    Event reception for applications . . . . . . . 25Sending events through firewalls . . . . . . . 26Event delivery when systems fail . . . . . . . 26

    Activating the cache . . . . . . . . . . 27Configuring backup servers to deliver events . . 28Using the portmapper keywords . . . . . . 29Configuring a reception application built withthe C API . . . . . . . . . . . . . . 30

    Chapter 4. Building an adapter . . . . 33Adapter files . . . . . . . . . . . . . . 33Identifying events to monitor . . . . . . . . 33Defining the source. . . . . . . . . . . . 34Defining event classes . . . . . . . . . . . 34Selecting event delivery methods . . . . . . . 35

    Configuring an EIF receiver application for SSL 36Configuring an EIF client application for SSL . . 38

    Programming the adapter . . . . . . . . . 40Upgrading existing adapters. . . . . . . . 41Configuration file APIs . . . . . . . . . 41Communications APIs . . . . . . . . . . 42Special considerations for Microsoft Windows . . 42Compiling the adapter built with the C API . . 42Linking the adapter built with the C API . . . 43

    Installing, configuring, and testing the adapter . . 44Running adapters built with the Event IntegrationFacility Java API. . . . . . . . . . . . . 44Configuring adapters for international environments 45

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

    Filtering events when systems fail . . . . . . 48Regular expressions in filters . . . . . . . 49

    Chapter 6. Troubleshooting . . . . . . 51Message logs . . . . . . . . . . . . . . 51Trace logs . . . . . . . . . . . . . . . 51Performance and availability . . . . . . . . 53

    Event reception connection parameters . . . . 53Common problems and scenarios . . . . . . . 54

    Building and running adapters . . . . . . . 54Making connections to the event server . . . . 55Sending events . . . . . . . . . . . . 55

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

    tec_agent_getenv . . . . . . . . . . . 57tec_agent_init. . . . . . . . . . . . . 57tec_create_EIF_handle . . . . . . . . . . 58tec_create_handle . . . . . . . . . . . 59tec_create_handle_c. . . . . . . . . . . 60tec_create_handle_r . . . . . . . . . . . 61tec_destroy_handle . . . . . . . . . . . 62tec_errno . . . . . . . . . . . . . . 62tec_get_event . . . . . . . . . . . . . 62tec_put_event. . . . . . . . . . . . . 63tec_register_callback . . . . . . . . . . 63

    Appendix B. Utilities for the C API . . . 65ed_scan_get_n . . . . . . . . . . . . . 65ed_scan_n . . . . . . . . . . . . . . . 65ed_sleep . . . . . . . . . . . . . . . 66

    Appendix C. Java language API . . . . 67disconnect . . . . . . . . . . . . . . . 67disconnect(time) . . . . . . . . . . . . . 67getConfigVal . . . . . . . . . . . . . . 67onMessage . . . . . . . . . . . . . . 68receiveEvent . . . . . . . . . . . . . . 68registerListener . . . . . . . . . . . . . 69sendEvent . . . . . . . . . . . . . . . 69TECAgent . . . . . . . . . . . . . . . 70TECEvent . . . . . . . . . . . . . . . 70

    Copyright IBM Corp. 2003, 2012 iii

  • Appendix D. Configuration keywords 73

    Notices . . . . . . . . . . . . . . 87Trademarks . . . . . . . . . . . . . . 89

    Index . . . . . . . . . . . . . . . 91

    iv IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • About this publicationThe 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

    What this publication containsThis publication contains reference information for the Tivoli Event IntegrationFacility.

    This publication contains the following sections:v Chapter 1, Overview of the Tivoli Event Integration Facility, on page 1Introduces the Event Integration Facility.

    v Installing the Tivoli Event Integration FacilityDescribes planning, installing and migrating for the Event Integration Facility.

    v Chapter 3, Event transport, on page 15Describes methods for sending information to the event server.

    v Chapter 4, Building an adapter, on page 33Describes how to build an adapter to help you monitor events.

    v Chapter 5, Filtering events at the source, on page 47Describes how to filter events at the source to deal with large numbers of events.

    v Chapter 6, Troubleshooting, on page 51Explains how to troubleshoot problems that can arise installing and using theEvent Integration Facility.

    v Appendix A, Application programming interfaces, on page 57Describes how to use APIs to build custom adapters or applications.

    v Appendix D, Configuration keywords, on page 73Contains the keywords common to most adapters.

    Copyright IBM Corp. 2003, 2012 v

  • 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, SC14-7526Includes 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, SC14-7527Describes 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, SC14-7528Describes how to perform administrative and event visualization tasks using theTivoli Netcool/OMNIbus Web GUI.

    v IBM Tivoli Netcool/OMNIbus User's Guide, SC14-7529Provides 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, SC14-7530Contains 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, SC14-7532Describes 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, SC14-7533Describes 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, SC14-7534Describes 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,SC22-7535Shows 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,SC27-5613Describes the URIs and common behaviors of the ApplicationProgramming Interface (API) that is called the ObjectServer HTTP Interface.Describes how to enable the API and provides examples of JSON payloads, andHTTP requests and responses.

    v IBM Tivoli Netcool/OMNIbus ObjectServer OSLC Interface Reference Guide,SC27-5613Describes the services, resources, and common behaviors of the OpenServices for Lifecycle Collaboration (OSLC) Application Programming Interface

    vi IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • (API) that is called the ObjectServer OSLC Interface. Describes how to enable theAPI and provides examples of service provider definitions, RDF/XML payloads,and HTTP requests and responses.

    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, SC321242Provides information about supported adapters, including how to install andconfigure these adapters.

    v IBM Tivoli Enterprise Console Installation Guide, SC321233Describes how to install, upgrade, and uninstall the IBM Tivoli EnterpriseConsole product.

    v IBM Tivoli Enterprise Console Command and Task Reference, SC321232Provides details about IBM Tivoli Enterprise Console commands, predefinedtasks shipped in the task library, and the environment variables that areavailable to tasks that run against an event.

    v IBM Tivoli Enterprise Console Rule Developer's Guide, SC321234Describes how to develop rules and integrate them for event correlation andautomated event management.

    v IBM Tivoli Enterprise Console User's Guide, SC321235Provides an overview of the IBM Tivoli Enterprise Console product anddescribes how to configure and use the IBM Tivoli Enterprise Console product tomanage events.

    v IBM Tivoli Enterprise Console Warehouse Enablement Pack: Implementation Guide,SC321236Describes how to install and configure the warehouse enablement pack for theIBM Tivoli Enterprise Console product and describes the data flow andstructures that are used by the warehouse pack.

    v IBM Tivoli Event Console Release Notes, SC321238Provides release-specific information that is not available until just before theproduct is sent to market.

    v IBM Tivoli Enterprise Console Rule Set Reference, SC321282Provides reference information about the IBM Tivoli Enterprise Console rule sets.

    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 Information Center Website at:

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

    About this publication vii

  • 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.

    Ordering publications

    You can order many Tivoli publications online at the following Web site:

    http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

    You can also order by telephone by calling one of these numbers:v In the United States: 800-879-2755v In Canada: 800-426-4968

    In other countries, contact your software account representative to order Tivolipublications. To locate the telephone number of your local representative, performthe following steps:1. Go to the following Web site:

    http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss2. Select your country from the list and click Go. The Welcome to the IBM

    Publications Center page is displayed for your country.3. On the left side of the page, click About this site to see an information page

    that includes the telephone number of your local representative.

    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 trainingFor 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.

    viii IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • 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 textItalic

    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 difficultto distinguish from surrounding text

    v 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 the

    About this publication ix

  • Windows 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.

    x IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • Chapter 1. Overview of the Tivoli Event Integration FacilityThe 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 network environment. The Event IntegrationFacility is a separate installation package from the main Tivoli Netcool/OMNIbusproduct. It does not require an instance of the Deployment Engine to run.

    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 theevent server.

    v Filter and correlate events near the source.v Create an application that can receive events.

    EventsThe central unit of information is the event. An event is any significant change inthe state of a system resource or application. Events can be generated for problemsand for successful 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. An adapter converts allevents into a format that provides consistency in information, such as the 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, 2012 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 is an applicationsuch as a database, or a system resource such as disk space. When an adapterreceives information from its source, the adapter formats the information andforwards 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 configurableintervals, and then interpret and forward the resulting information directly tothe event server.

    event:native format

    event:Tivoli format

    To event serverSystem

    Resource orApplication

    EventAdapter

    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.

    Note: Event classes are not the same as Tivoli objects.Related concepts:Defining event classes on page 34An 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 73Use the keywords in the configuration file to configure the behavior of theadapters.Directory structure on page 10The directory structure of the Event Integration Facility after you extract thecompressed EIF 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 Probe for Tivoli EIF acts as the event server for the Tivoli Event IntegrationFacility.

    Note: For previous versions of EIF, the Tivoli Enterprise Console Server fulfils thesame role.

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

    $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.

    Rules describe the actions that are performed when the event server receives aparticular system event. In some cases, you can customize other applications toreceive events from the event server.

    4 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • The event server validates incoming events. If an event is valid, the event serverassigns a unique identification (ID) and time stamp and stores it in an eventdatabase. The event server processes each incoming transaction before processingthe next transaction.

    The following example event has been processed by the Probe for Tivoli EIF andthe Tivoli Netcool/OMNIbus ObjectServer:Node Alias: 9.42.19.243TECEventHandle:Process Required: 0Prec. Entity ID: 0First Occurrence: 07/28/2009 02:17:23 PMRem. Sec Obj.:Port: 0Suppr./Escl.: NormalRem. Root Obj.:Extended Attributes:Slot: 0Local Node Alias:Managed Status: ManagedAlert Group: EVENTClass: TME10tecadFlash: NoURL:Summary: hello_eif_probeCause Type: UnknownCount: 1Poll: 0Agent: TECState Change: 07/28/2009 02:17:23 PMAlert Key: TECLocal Sec. Obj.:TaskList: Not in Task ListLocal Root Obj.:Group: PublicCard:Serial: 1950Manager: tivoli_eif probe on austin.tivlab.raleigh.ibm.comEvent Type: Not DefinedRem. Pri. Obj.:Customer:Expire Time: Not SetIdentifier: :TEC:EVENTPrec. Obj. Inst.: 0TECRepeatCount: 0Correlated Notif.:TECFQHostname:Specific Problem:Owner: NobodyLocation:Server Name: NCOMSService:Internal Timestamp: 07/28/2009 02:17:23 PMNode: 9.42.19.243TECStatus:TECDate:Probable Cause: Not DefinedRem. Node Alias:Severity: IndeterminateLast Occurrence: 07/28/2009 02:17:23 PMTECHostname:Grade: 1Server Serial: 1950TECDateReception:Local Pri. Obj.:

    Chapter 1. Overview of the Tivoli Event Integration Facility 5

  • TECServerHandle:Precision Domain:Type: ProblemEvent ID:Prec. Serial:Ack: No

    The following example event has been processed by the Tivoli Enterprise ConsoleServer:Su_Failure:server_handle=1;date_reception=784408852;event_handle=1;source=LOG;sub_source=login;origin=oak;sub_origin=;hostname=;last_modified_time=Nov 07, 1994 08:51:42;adapter_host=;status=OPEN;administrator=;acl=[admin];severity=WARNING;date=Nov 07, 1994 08:51:42;duration=0;msg=;msg_catalog=;msg_index=0;num_actions=1;credibility=0;repeat_count=0;cause_date_reception=0;cause_event_handle=0;from_user=don;to_user=root;END

    Related concepts:Events on page 1The central unit of information is the event. An event is any significant change inthe state of a system resource or application. Events can be generated for problemsand for successful completions of tasks.

    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 47One 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.

    6 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • 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 rulesgeared toward enhancing the usefulness of the adapter events.

    IBM Tivoli Netcool/OMNIbus automations are similar to EIF rules. Theautomations detect changes in the ObjectServer and respond to these changesautomatically, enabling the ObjectServer to process alerts 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.

    For more information about Tivoli Enterprise Console rules, see the IBM TivoliEnterprise Console Rule Developer's Guide in the IBM Tivoli Enterprise Consoleinformation center at http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.itecruledev.doc/ecodmst.htm

    Chapter 1. Overview of the Tivoli Event Integration Facility 7

  • 8 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • Chapter 2. Installing the Event Integration FacilityThe 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 Ensure that the Microsoft Visual C++ 2005 SP1 Redistributable Package isinstalled on the host. The package is required by EIF utilities, such asposteifmsg. The package is required because Tivoli Netcool/OMNIbus versionof EIF is compiled by Microsoft Visual C++ 2005 SP1. The user or applicationthat is installing EIF must install the Redistributable Package because EIF doesnot have an installer program and is not installed by Tivoli Netcool/OMNIbus.You can download the 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 Onlinewebsite, follow the instructions in the download document for your operatingsystem.

    Table 1. Location of the download documents for all supported operating systemsOperating 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.

    Copyright IBM Corp. 2003, 2012 9

  • Directory structureThe directory structure of the Event Integration Facility after you extract thecompressed EIF 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-r1v hpux10v hpuxiav linux-ix86v linux-ppcv linux-s390v linux-ia64v os390v solaris2v solaris2-ix86v w32-ix86Table 2. Event Integration Facility directory structureDirectory 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.

    default_sm Contains the default empty rule set for theTivoli Enterprise Console State CorrelationEngine. You can add rules, which are alsocalled state machines, as is required by yourenvironment.

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

    10 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • Table 2. Event Integration Facility directory structure (continued)Directory or file name Header

    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.

    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 11

  • 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.

    Procedurev 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 33Before 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=c1_Port=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

    12 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • 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 access the Tivoli Management Framework(TMF), locate the codeset file associated with your system environment, andthen convert it to UTF-8.

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

    Related reference:posteifmsg on page 21Use the posteifmsg utility to post events to the ObjectServer via the Probe forTivoli EIF. After you install the Event Integration Facility, the posteifmsg binary filethat is in the Event Integration Facility installation package can be copied to otherhosts.

    Chapter 2. Installing the Event Integration Facility 13

  • 14 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • Chapter 3. Event transportThe 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 35While 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 20You 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 methodestablishes and discards a new connection for each event or group of events.

    v For a connection-oriented event delivery, specify ConnectionMode=CO in theconfiguration 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 35While 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 73Use the keywords in the configuration file to configure the behavior of theadapters.

    Copyright IBM Corp. 2003, 2012 15

  • 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 35While 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 43These tables list the libraries required to link adapters developed with the C API.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 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:

    16 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • v C FIPS 140-2 mode is facilitated by the use of IBM Global Security Kit(GSKit) version 7. Ensure that the path to the GSKit libraries appears in thefollowing environment 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 EIFDatabase 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 to YES,clients must also present a certificate duringan SSL connection. The keystore of thereceiver 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 17

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

    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 to YES,clients must also present a certificate duringan SSL connection. The keystore of thereceiver 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 keydatabase 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 accessthe digital certificates, save the passwordfor a key or trust database in encryptedformat to a stash file. Whenever thekeystore or truststore is accessed, thesystem checks whether a stash file exists. Iffound, the file contents are decrypted andused as input for the password.

    Java To create and store encryptedpasswords for applications, use thecom.tivoli.tec.event_delivery.common.Encryption script.

    18 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

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

    Ciphers The sending and receiving ends of the EIFconnection must have at least one cipher incommon in order for the connection tosucceed. FIPS 1402 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 areavailable:

    v SSL_RC2_CBC_128_CBC_WITH_MD5v SSL_RC2_CBC_128_CBC_EXPORT40_WITH_MD5

    v SSL_DES_64_CBC_WITH_MD5v SSL_DES_192_EDE3_CBC_WITH_MD5v SSL_NULL_WITH_NULL_NULLv SSL_RSA_WITH_NULL_MD5v SSL_RSA_WITH_NULL_SHAv SSL_RSA_EXPORT_WITH_RC4_40_MD5v SSL_RSA_WITH_RC4_128_MD5v SSL_RSA_WITH_RC4_128_SHAv SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5

    v SSL_RSA_WITH_DES_CBC_SHA

    Java Any cipher that is supported bythe 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.

    Chapter 3. Event transport 19

  • Related concepts:Selecting event delivery methods on page 35While 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 38In 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 36In 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: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.Appendix D, Configuration keywords, on page 73Use 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.

    20 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • Related concepts:Event delivery methods on page 15Events 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 40To 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 16The 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 44After 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 filethat is in the Event Integration Facility installation package can be copied to otherhosts.

    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.

    Tip: The posteifmsg utility uses the same command-line options as the postemsgand postzmsg utilities that are included in Tivoli Enterprise Console.posteifmsg -S server [-p port]| -f configurationfile [-m "message"][-r severity] [attribute=value...] class source

    Where:v server is the host name or the IP address of the target server. The -Scommand-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 23if 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.

    Chapter 3. Event transport 21

  • 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 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 definedfor 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 classthat 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 utilityalways 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 23.

    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.

    22 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • 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 oneof 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_1ServerBackup : COL_B_1Buffering : 1BufferSize : 100FlushBufferInterval : 10PortNumber : 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

    Chapter 3. Event transport 23

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

    Probe for Tivoli EIF

    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 serverv 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 eventclass.

    v value is the value of a valid attribute. Ensure that the attribute is defined for theevent 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.Encryption createKey[-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 theencrypt command to generate the stash file.

    24 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • C Use the nc_gskcmd command-line utility or the iKeyman graphical utilityto 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.Encryption createkey-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 so that information can be receivedfrom multiple sources. The event listener listens to all of the channels that youspecify.

    The application can use the polling mechanism to retrieve events synchronously,by using the GET method of the API. With the non-polling mechanism, theapplication registers a listener or callback and receives events asynchronously.

    The EIF uses a cache for event reception. If the application has a listener, EIF alsoregisters a listener in the cache. Then, it notifies the application and passes theevent to the application listener. If the application does not use a listener, theapplication must request the retrieval of the next event.

    Example

    The following example shows a configuration file that enables the application touse sockets to receive events.BufferEvents=YESBufEvtPath=/tmp/eif_socket_recv.cache

    TransportList=t1

    t1Type=SOCKETt1Channels=t_t_ServerLocation=myserver.comt_Port=5151

    Example

    In the following example, the configuration file enables an application that iscreated from the C API to receive events by using SSL, with FIPS 140-2 encryption.

    Chapter 3. Event transport 25

  • 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 27By 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 73Use 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, use Tivoli Management Framework FirewallSecurity Toolbox. It collects events and sends them across the firewall using aproxy. To obtain Tivoli Management Framework Firewall Security Toolbox and itsdocumentation, contact Customer Support.

    To send events through firewalls in non-Tivoli environments, you configure yourfirewall to allow arbitrary TCP/IP connections on the port specified for youradapter. Ensure that the firewall allows inbound communication from thecomputer system hosting the adapter.Related reference:Appendix D, Configuration keywords, on page 73Use 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 or the application receivingevents.

    This repository stores events and removes those events from the cache when theyare delivered. Also, the Event Integration Facility ensures that the same event isnot delivered 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.

    26 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • Related tasks: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.Configuring backup servers to deliver events on page 28The 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 44After 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 cacheConfiguration 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 keywordset 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.

    Chapter 3. Event transport 27

  • Related concepts:Event delivery when systems fail on page 26To ensure that events are delivered after system failures, the Tivoli EventIntegration Facility provides a cache on the adapter or the application receivingevents.Performance and availability on page 53The Tivoli Event Integration Facility can control performance and availability forevent processing.Related tasks: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.Filtering events when systems fail on page 48When 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 25In 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=sslhost2

    28 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • c2Port=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

    Note: The backup type for both SOCKET and SSL transport type can be either SSLor SOCKET. The C API ignores the Java API keywords (TMEHost, TMEUserID,TMEPassword, and TMEPort).Related concepts:Event delivery when systems fail on page 26To ensure that events are delivered after system failures, the Tivoli EventIntegration Facility provides a cache on the adapter or the application receivingevents.Performance and availability on page 53The Tivoli Event Integration Facility can control performance and availability forevent processing.Related tasks:Activating the cache on page 27By 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 presentin 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.

    Chapter 3. Event transport 29

  • 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 value

    30 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • sets 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 3. Event transport 31

  • 32 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • Chapter 4. Building an adapterBefore 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 12If 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 73Use 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-commerceWeb sites, wide area networks, and so forth)

    v Performance requirements

    Copyright IBM Corp. 2003, 2012 33

  • v Important servers and network resourcesAfter 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 NetworkManagement Information Center athttp://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/topic/com.ibm.netcool_OMNIbus.doc/probes/tivoli_eif_v11/tivoli_eif_v11/wip/reference/tveifv11_intro.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.jsp

    34 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • Related 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.

    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.

    Chapter 4. Building an adapter 35

  • Related concepts:Event delivery methods on page 15Events 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 15The 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 16An 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 16The 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 73Use the keywords in the configuration file to configure the behavior of theadapters.

    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 aCA 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 it

    to be the default personal certificate.4. Create a configuration file for the EIF receiver. Start with the following code:

    36 IBM Tivoli Netcool/OMNIbus: Event Integration Facility Reference

  • 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 EIFconfiguration 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 fol