ecoamst

IBM Tivoli Enterprise Console

Adapters GuideVersion 3.9

SC32-1242-00

��

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

First Edition (August 2003)

This edition applies to version 3, release 9 of IBM Tivoli Enterprise Console (product number 5698-TEC) and to allsubsequent releases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2003. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this guide . . . . . . . . . . viiWho should read this guide . . . . . . . . . viiPublications . . . . . . . . . . . . . . vii

IBM Tivoli Enterprise Console library . . . . viiRelated publications . . . . . . . . . . viiiAccessing publications online . . . . . . . viiiOrdering publications . . . . . . . . . viii

Contacting software support . . . . . . . . . ixParticipating in newsgroups . . . . . . . . . ixConventions used in this guide . . . . . . . . x

Typeface conventions . . . . . . . . . . xOperating system-dependent variables and paths xCommand line syntax . . . . . . . . . . xi

Chapter 1. Introduction to adapters . . . 1Adapter overview . . . . . . . . . . . . 1

How adapters on endpoints send events . . . . 2How adapters on managed nodes send events . . 3How non-TME adapters send events . . . . . 3

Internationalization support for events. . . . . . 3Event information and attributes. . . . . . . . 4Adapter files . . . . . . . . . . . . . . 7

Cache file . . . . . . . . . . . . . . 8Configuration file . . . . . . . . . . . . 9

File location . . . . . . . . . . . . 9File format . . . . . . . . . . . . . 9Example . . . . . . . . . . . . . . 9Keywords . . . . . . . . . . . . . 10Event filtering . . . . . . . . . . . 21Event buffer filtering . . . . . . . . . 22

BAROC file . . . . . . . . . . . . . 23Rule file . . . . . . . . . . . . . . 23Format file . . . . . . . . . . . . . 24Class definition statement file . . . . . . . 25Error file . . . . . . . . . . . . . . 26

Initial files . . . . . . . . . . . . . . . 27Troubleshooting adapters . . . . . . . . . . 27

Adapter startup errors . . . . . . . . . . 27Troubleshooting for all adapters . . . . . . 28Managed node adapter troubleshooting . . . . 28Endpoint adapter troubleshooting . . . . . . 28Non-TME adapter troubleshooting. . . . . . 29

Chapter 2. Installing adapters . . . . . 31Supported adapters. . . . . . . . . . . . 31Hardware and software requirements. . . . . . 32

UNIX and Windows software requirements. . . 32AS/400 software requirements . . . . . . . 32OS/2 software requirements . . . . . . . . 32

Installing an HP OpenView adapter on a managednode. . . . . . . . . . . . . . . . . 33

Installing from the Tivoli desktop . . . . . . 33Installing from the command line . . . . . . 33

Installing an adapter on an endpoint . . . . . . 33Installing a non-TME adapter . . . . . . . . 34

Installing on UNIX operating systems . . . . 35Installing on Windows operating systems . . . 36Installing on the OS/2 operating system. . . . 37

Installing AS/400 adapters . . . . . . . . . 37Installing from CD . . . . . . . . . . . 37Installing from CD on an AS/400 System . . . 38Installing with English as a secondary language 39

Installing the NetWare logfile adapter . . . . . 39Upgrading HP OpenView adapters . . . . . . 40

Preparing to upgrade adapters . . . . . . . 40Backing up object databases . . . . . . . 40

Upgrading adapters from the Tivoli desktop . . 40Upgrading adapters from the command line . . 41Upgrading adapters using the SoftwareInstallation Service . . . . . . . . . . . 41

Uninstalling adapters . . . . . . . . . . . 41Uninstalling an HP OpenView adapter on amanaged node . . . . . . . . . . . . 41Uninstalling an adapter on an endpoint . . . . 41Uninstalling a non-TME adapter . . . . . . 42

Uninstalling on UNIX operating systems . . 42Uninstalling on Windows operating systems 42Uninstalling on the OS/2 operating system . . 42

Uninstalling an AS/400 adapter . . . . . . 43Uninstalling a NetWare logfile adapter . . . . 43Removing Version 3.8 enhanced adapters fromthe Tivoli environment . . . . . . . . . 44

Chapter 3. Adapter ConfigurationFacility. . . . . . . . . . . . . . . 45Using adapter configuration profiles . . . . . . 45Adapter Configuration Facility roles . . . . . . 45Setting adapter configuration profiles as managedresources . . . . . . . . . . . . . . . 46

Setting adapter configuration profiles asmanaged resources from the Tivoli desktop. . . 46Setting adapter configuration profiles asmanaged resources from the command line. . . 46

Creating an adapter configuration profile . . . . 46Creating an adapter configuration profile fromthe Tivoli desktop . . . . . . . . . . . 47Creating an adapter configuration profile fromthe command line . . . . . . . . . . . 47

Cloning an adapter configuration profile . . . . 48Cloning an adapter configuration profile from theTivoli desktop . . . . . . . . . . . . 48Cloning an adapter configuration profile from thecommand line . . . . . . . . . . . . 48

Deleting an adapter configuration profile . . . . 49Deleting an adapter configuration profile fromthe Tivoli desktop . . . . . . . . . . . 49Deleting an adapter configuration profile fromthe command line . . . . . . . . . . . 49

Setting adapter configuration profile defaults . . . 50Renaming a profile . . . . . . . . . . . 50

© Copyright IBM Corp. 2003 iii

Getting a new copy of an adapter configurationprofile . . . . . . . . . . . . . . . . 50

Getting a new copy of an adapter configurationprofile from the Tivoli desktop . . . . . . . 50Getting a new copy of an adapter configurationprofile from the command line . . . . . . . 51Setting adapter configuration profile distributiondefaults. . . . . . . . . . . . . . . 51

Modifying an adapter configuration profile defaultpolicy . . . . . . . . . . . . . . . . 52

Modifying an adapter configuration profiledefault policy from the Tivoli desktop . . . . 53Modifying an adapter configuration profiledefault policy from the command line . . . . 54

Modifying an adapter configuration profilevalidation policy. . . . . . . . . . . . . 54

Modifying an adapter configuration profilevalidation policy from the Tivoli desktop . . . 55Modifying an adapter configuration profilevalidation policy from the command line . . . 56

Distributing an adapter configuration profile . . . 56Distributing an adapter configuration profilefrom the Tivoli desktop . . . . . . . . . 56Distributing an adapter configuration profilefrom the command line . . . . . . . . . 56

Adding an adapter configuration profile record . . 57Endpoint adapters . . . . . . . . . . . 57

Editing an adapter configuration profile record . . 58Adding a configuration option to an adapterconfiguration profile record . . . . . . . . 59Modifying a configuration option in an adapterconfiguration profile record . . . . . . . . 59Removing an environment variable from anadapter configuration profile record . . . . . 60Adding a filter definition to an adapterconfiguration profile record . . . . . . . . 61Adding a filter cache definition to an adapterconfiguration profile record . . . . . . . . 61Adding a prefilter definition to an adapterconfiguration profile record . . . . . . . . 62Modifying a filter definition in an adapterconfiguration profile record . . . . . . . . 63Modifying a filter cache definition in an adapterconfiguration profile record . . . . . . . . 64Modifying a prefilter definition in an adapterconfiguration profile record . . . . . . . . 64Removing a filter cache definition in an adapterconfiguration profile record . . . . . . . . 65Removing a prefilter definition in an adapterconfiguration profile record . . . . . . . . 65Removing a filter definition from an adapterconfiguration profile record . . . . . . . . 66Adding a file to the distribution list of anadapter configuration profile record . . . . . 66Removing a file from the distribution list of anadapter configuration profile record . . . . . 67Modifying the adapter configuration file behavior 68Modifying variable expansion behavior . . . . 68Adding a before or after script to an adapterconfiguration profile record . . . . . . . . 69

Modifying a before or after script in an adapterconfiguration profile record . . . . . . . . 69Removing a before or after script from anadapter configuration profile record . . . . . 70Enabling and disabling before and after scripts inan adapter configuration profile record . . . . 70Modifying before and after script reportingbehavior . . . . . . . . . . . . . . 71Modifying the comment in an adapterconfiguration profile record . . . . . . . . 72Modifying the UID and GID in an adapterconfiguration profile record . . . . . . . . 72Specifying the adapter identifier name . . . . 73

Copying an adapter configuration profile record . . 73Copying an adapter configuration profile recordfrom the Tivoli desktop . . . . . . . . . 74

Moving an adapter configuration profile record . . 74Moving an adapter configuration profile Recordfrom the Tivoli desktop . . . . . . . . . 74

Deleting an adapter configuration profile record . . 75Deleting an adapter configuration profile recordfrom the Tivoli desktop . . . . . . . . . 75Deleting an adapter configuration profile recordfrom the command line . . . . . . . . . 75

Locking and unlocking an adapter configurationprofile record . . . . . . . . . . . . . . 76

Locking and unlocking an adapter configurationprofile Record from the Tivoli desktop . . . . 76

Finding an adapter configuration profile record . . 76Sorting adapter configuration profile records . . . 77Sorting adapter configuration profile attributes . . 78Starting the Logfile Format Editor from an adapterconfiguration profile . . . . . . . . . . . 79

Chapter 4. AS/400 alert adapter . . . . 81Adapter files . . . . . . . . . . . . . . 81

Configuration file . . . . . . . . . . . 82Class definition statement file . . . . . . . 83

SELECT statement example . . . . . . . 83FETCH statement example . . . . . . . 83Keywords . . . . . . . . . . . . . 83

Configuring the AS/400 alert filters . . . . . . 84Default alert filter . . . . . . . . . . . 84Integrating with an existing alert filter . . . . 85

Starting the adapter . . . . . . . . . . . 85STRTECADP . . . . . . . . . . . . . 86

Stopping the adapter . . . . . . . . . . . 87ENDTECADP . . . . . . . . . . . . 88

Events Listing . . . . . . . . . . . . . 90Event class structure . . . . . . . . . . 90

Troubleshooting the AS/400 adapter . . . . . . 92Logging Events in Test Mode . . . . . . . . 93TCP/IP considerations. . . . . . . . . . . 93Starting an AS/400 adapter after an IPL . . . . . 93

Adding an autostart job to QSYSWRK . . . . 93Changing the AS/400 startup program . . . . 94

Multiple AS/400 alert adapters . . . . . . . . 94Configuration file . . . . . . . . . . . 95

QTMETECA/POSTEMSG . . . . . . . . . 96Common tasks . . . . . . . . . . . . . 97

iv IBM Tivoli Enterprise Console: Adapters Guide

Chapter 5. AS/400 message adapter . . 99Adapter Files . . . . . . . . . . . . . . 99


SELECT statement example. . . . . . . 101FETCH statement example . . . . . . . 101MAP statement example. . . . . . . . 101Keywords . . . . . . . . . . . . 102

Starting the adapter . . . . . . . . . . . 105STRTECADP . . . . . . . . . . . . 106

Stopping the adapter . . . . . . . . . . . 107ENDTECADP . . . . . . . . . . . . 108

Events listing . . . . . . . . . . . . . 110Event class structure . . . . . . . . . . 110

Troubleshooting the AS/400 adapter . . . . . . 111Logging Events in Test Mode . . . . . . . . 111TCP/IP considerations . . . . . . . . . . 111Starting an AS/400 adapter after an IPL . . . . 112

Adding an autostart job to QSYSWRK . . . . 112Changing the AS/400 startup program . . . . 112

Multiple AS/400 message queues. . . . . . . 113Configuration file . . . . . . . . . . . 113

Using FTP to run AS/400 commands . . . . . 113Common tasks . . . . . . . . . . . . . 114

Chapter 6. NetWare logfile adapter 115NetWare logfile adapter reference information . . 115Adapter files . . . . . . . . . . . . . 115Error file . . . . . . . . . . . . . . . 115Prefiltering NetWare events. . . . . . . . . 116Configuration file . . . . . . . . . . . . 116Format file . . . . . . . . . . . . . . 117Events listing . . . . . . . . . . . . . 118

Event class structure . . . . . . . . . . 118tecadnw4.nlm . . . . . . . . . . . . . 121

load tecadnw4 . . . . . . . . . . . . 122Troubleshooting the NetWare logfile adapter . . . 123

Chapter 7. OpenView adapter . . . . 125OpenView driver . . . . . . . . . . . . 125

Reception of OpenView messages . . . . . 125Determining the OpenView NNM version . . . 125Incoming messages format . . . . . . . . 126Event correlation with NNM 6 . . . . . . 126Determining the OVsnmpEventOpen filter value 127Testing tools . . . . . . . . . . . . . 128Testing event correlation with NNM 6 . . . . 128

Event correlation example . . . . . . . 129Adapter files . . . . . . . . . . . . . 129


OpenView event example . . . . . . . 131Keywords . . . . . . . . . . . . 132

Object identifier file . . . . . . . . . . 132Error file . . . . . . . . . . . . . . 133LRF file . . . . . . . . . . . . . . 133

Starting and stopping the adapter . . . . . . 133Events listing . . . . . . . . . . . . . 133

Event class structure . . . . . . . . . . 134OpenView traps . . . . . . . . . . . . 136

SNMP traps . . . . . . . . . . . . . 136OpenView traps . . . . . . . . . . . 136

Troubleshooting the OpenView adapter. . . . . 137

Chapter 8. OS/2 adapter . . . . . . . 139Adapter files . . . . . . . . . . . . . 139

Configuration file . . . . . . . . . . . 139Format file . . . . . . . . . . . . . 140

Starting the adapter . . . . . . . . . . . 140Stopping the adapter . . . . . . . . . . . 141Events listing . . . . . . . . . . . . . 141

Event class structure . . . . . . . . . . 141Troubleshooting the OS/2 adapter . . . . . . 142

Chapter 9. SNMP adapter . . . . . . 143SNMP driver . . . . . . . . . . . . . 143

Reception of SNMP messages . . . . . . . 143Incoming messages format . . . . . . . . 143

Server configuration . . . . . . . . . . . 143Adapter files . . . . . . . . . . . . . 143


SNMP event example. . . . . . . . . 144Keywords . . . . . . . . . . . . 144

Object identifier file . . . . . . . . . . 145Error file . . . . . . . . . . . . . . 145

Starting and stopping the adapter . . . . . . 145Cold start . . . . . . . . . . . . . 146Warm start . . . . . . . . . . . . . 146Stopping the adapter . . . . . . . . . . 146


Rules listing . . . . . . . . . . . . . . 148SNMP traps . . . . . . . . . . . . . . 148

Generic traps . . . . . . . . . . . . 148Enterprise-specific traps . . . . . . . . . 148

Creating a new SNMP trap event. . . . . . . 149BAROC file changes . . . . . . . . . . 150

Agent-independent data . . . . . . . . 150Class definition statement file changes . . . . 152Object identifier file changes . . . . . . . 153

Troubleshooting the SNMP adapter . . . . . . 154

Chapter 10. UNIX logfile adapter . . . 155Event server configuration . . . . . . . . . 155Starting the adapter . . . . . . . . . . . 155Stopping the adapter . . . . . . . . . . . 155Reloading the adapter configuration. . . . . . 156Running multiple UNIX logfile adapters . . . . 156Adapter files . . . . . . . . . . . . . 157

Configuration file . . . . . . . . . . . 157Format file . . . . . . . . . . . . . 158Class definition statement file . . . . . . . 159Error file . . . . . . . . . . . . . . 159


Default rules . . . . . . . . . . . . . 163Troubleshooting the UNIX logfile adapter . . . . 164

Contents v

Chapter 11. Windows event logadapter . . . . . . . . . . . . . . 167Adapter files . . . . . . . . . . . . . 167

Configuration file . . . . . . . . . . . 168Prefiltering Windows log events . . . . . 172

Format file . . . . . . . . . . . . . 173Registry variables . . . . . . . . . . . . 173

Low memory registry variables . . . . . . 176Starting the adapter . . . . . . . . . . . 176Stopping the adapter . . . . . . . . . . . 177Reloading the adapter configuration. . . . . . 177Running multiple Windows event log adapters . . 177Events listing . . . . . . . . . . . . . 178

Event class structure . . . . . . . . . . 178tecad_win command . . . . . . . . . . . 180

tecad_win . . . . . . . . . . . . . 181Troubleshooting the Windows event log adapter 182

Appendix A. Files shipped withadapters . . . . . . . . . . . . . 183

Appendix B. Format file reference . . 187Format file location . . . . . . . . . . . 187Format specifications . . . . . . . . . . . 187Log file example . . . . . . . . . . . . 189Windows example. . . . . . . . . . . . 191Mappings . . . . . . . . . . . . . . 191

Additional mapping considerations . . . . . 193

Activating changes made with a format file . . . 195Generating a new class definition statement filefor a TME adapter. . . . . . . . . . . 195Generating a new class definition statement filefor a non-TME adapter . . . . . . . . . 195

Appendix C. Class definitionstatement file reference . . . . . . . 197File format . . . . . . . . . . . . . . 197Operators . . . . . . . . . . . . . . 197Class definition statement file details . . . . . 198

SELECT statement. . . . . . . . . . . 199FETCH statement . . . . . . . . . . . 200MAP statement . . . . . . . . . . . . 201MAP_DEFAULT statement . . . . . . . . 201Example . . . . . . . . . . . . . . 201

Object identifier to name translation. . . . . . 202Class definition statement file syntax diagrams . . 202

Appendix D. Logfile Format Editor 207Configuring a format file for a logfile adapter . . 207

Notices . . . . . . . . . . . . . . 221Trademarks . . . . . . . . . . . . . . 223

Index . . . . . . . . . . . . . . . 225

vi IBM Tivoli Enterprise Console: Adapters Guide

About this guide

The IBM® Tivoli Enterprise Console® product is a rule-based, event managementapplication that integrates system, network, database, and application managementto help ensure the optimal availability of an organization’s IT services. The IBMTivoli Enterprise Console Adapters Guide describes the currently available TivoliEnterprise Console adapters.

Who should read this guideThis guide is for Tivoli Enterprise Console administrators who install andconfigure event adapters.

You should have prior knowledge of the following software:v The operating systems that your enterprise usesv The Tivoli® Management Frameworkv Adapter operating systems; for example, if you use an OpenView adapter, you

should be familiar with Hewlett-Packard OpenView.

PublicationsThis section lists publications in the Tivoli Enterprise Console library and relateddocuments. It also describes how to access Tivoli publications online and how toorder Tivoli publications.

IBM Tivoli Enterprise Console libraryThe following documents are available in the Tivoli Enterprise Console library:v IBM Tivoli Enterprise Console Adapters Guide, SC32-1242

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

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

v IBM Tivoli Enterprise Console Installation Guide, SC32-1233Describes how to install, upgrade, and uninstall the IBM Tivoli EnterpriseConsole product.

v IBM Tivoli Enterprise Console Release Notes, SC32-1238Provides release-specific information that is not available until just before theproduct is sent to market.

v IBM Tivoli Enterprise Console Rule Developer’s Guide, SC32-1234Describes how to develop rules and integrate them for event correlation andautomated event management.

v IBM Tivoli Enterprise Console Rule Set Reference, SC32-1282Provides reference information about the IBM Tivoli Enterprise Console rule sets.

v IBM Tivoli Enterprise Console User’s Guide, SC32-1235

© Copyright IBM Corp. 2003 vii

Provides 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,SC32-1236Describes 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 Tivoli Event Integration Facility Reference, SC32-1241Describes how to develop your own event adapters that are tailored to yournetwork environment and the specific needs of your enterprise. This referencealso describes how to filter events at the source.

Related publicationsThe Tivoli Software Glossary includes definitions for many of the technical termsrelated to Tivoli software. The Tivoli Software Glossary is available, in English only,at the following Web site:

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

Access the glossary by clicking the Glossary link on the left pane of the Tivolisoftware library window.

Accessing publications onlineThe documentation CD contains the publications that are in the product library.The format of the publications is PDF, HTML, or both. Refer to the readme file onthe CD for instructions on how to access the documentation.

IBM posts publications for this and all other Tivoli products, as they becomeavailable and whenever they are updated, to the Tivoli Software InformationCenter Web site. Access the Tivoli Software Information Center by first going to theTivoli software library at the following Web address:


Scroll down and click the Product manuals link. In the Tivoli Technical ProductDocuments Alphabetical Listing window, click the IBM Tivoli Enterprise Consolelink to access the product library at the Tivoli Information Center.

Note: If you print PDF documents on other than letter-sized paper, select the Fit topage check box in the Adobe Acrobat Print window. This option is availablewhen you click File → Print. Fit to page ensures that the full dimensions of aletter-sized page print on the paper that you are using.

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

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

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

viii IBM Tivoli Enterprise Console: Adapters Guide





In other countries, see the following Web site for a list of telephone numbers:

http://www.ibm.com/software/tivoli/order-lit/

Contacting software supportIf you have a problem with any Tivoli product, refer to the following IBM SoftwareSupport Web site:

http://www.ibm.com/software/sysmgmt/products/support/

If you want to contact software support, see the IBM Software Support Guide at thefollowing Web site:

http://techsupport.services.ibm.com/guides/handbook.html

The guide provides information about how to contact IBM Software Support,depending on the severity of your problem, and the following information:v Registration and eligibilityv Telephone numbers and e-mail addresses, depending on the country in which

you are locatedv Information you must have before contacting IBM Software Support

Participating in newsgroupsUser groups provide software professionals with a forum for communicating ideas,technical expertise, and experiences related to the product. They are located on theInternet and are available using standard news reader programs. These groups areprimarily intended for user-to-user communication and are not a replacement forformal support.

To access a newsgroup, use the instructions appropriate for your browser.

Use these instructions for a Microsoft Internet Explorer browser.1. Open an Internet Explorer browser.2. From the Tools menu, click Internet Options.3. On the Internet Options window, click the Programs tab.4. In the Newsgroups list, click the Down Arrow and then click Outlook Express.5. Click OK.6. Close your Internet Explorer browser and then open it again.7. Cut and paste the newsgroup address of a product into the browser Address

field, and press Enter to open the newsgroup.

Use these instructions for a Netscape Navigator browser.1. Open a Netscape Navigator browser.2. From the Edit menu, click Preferences. The Preferences window is displayed.3. In the Category view, click Mail & Newsgroups to display the Mail &

Newsgroups settings.4. Select the Use Netscape mail as the default mail application check box.5. Click OK.6. Close your Netscape Navigator browser and then open it again.

About this guide ix

http://www.ibm.com/software/tivoli/order-lit/

http://www.ibm.com/software/sysmgmt/products/support/

http://techsupport.services.ibm.com/guides/handbook.html

7. Cut and paste the newsgroup address of a product into the browser Addressfield, and press Enter to open the newsgroup.

IBM Tivoli Enterprise Console:

news://news.software.ibm.com/ibm.software.tivoli.enterprise-console

IBM Tivoli NetView® for UNIX® and IBM Tivoli NetView for Windows®:

news://news.software.ibm.com/ibm.software.tivoli.netview-unix-windows

Conventions used in this guideThis guide uses several conventions for special terms and actions, operatingsystem-dependent commands and paths, and command syntax.

Typeface conventionsThis guide 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

Italic

v Words defined in textv Emphasis of words (words as words)v New terms in text (except in a definition list)v Variables and values you must provide

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 pathsThis guide uses the UNIX convention for specifying environment variables and fordirectory notation.

When using the Windows command line, replace $variable with %variable% forenvironment variables and replace each forward slash (/) with a backslash (\) indirectory paths.

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

x IBM Tivoli Enterprise Console: Adapters Guide

news://news.software.ibm.com/ibm.software.tivoli.enterprise-console

news://news.software.ibm.com/ibm.software.tivoli.netview-unix-windows

Command line syntaxThis document uses the following special characters to define the command syntax:

[ ] Identifies an optional argument. Arguments not enclosed in brackets arerequired.

... Indicates that you can specify multiple values for the previous argument.

| Indicates mutually exclusive information. You can use the argument to theleft of the separator or the argument to the right of the separator. Youcannot use both arguments in a single use of the command.

{ } Delimits a set of mutually exclusive arguments when one of the argumentsis required. If the arguments are optional, they are enclosed in brackets ([]).

For example:

wsetsrc [–S server] [–l label] [–n name] source

The source argument is the only required argument for the wsetsrc command. Thebrackets around the other arguments indicate that these arguments are optional.

Another example is the wlsac command:

wlsac [–l | –f format] [key... ] profile

In this example, the –l and –f format arguments are mutually exclusive andoptional. The profile argument is required. The key argument is optional. Also, theellipsis marks (...) following the key argument indicate that you can specifymultiple key names.

Another example is the wrb –import command:

wrb –import {rule_pack | rule_set} ...

In this example, the rule_pack and rule_set arguments are mutually exclusive, butone of the arguments must be specified. Also, the ellipsis marks (...) indicate thatyou can specify multiple rule packs or rule sets.

About this guide xi

xii IBM Tivoli Enterprise Console: Adapters Guide

Chapter 1. Introduction to adapters

Event adapters are software programs that collect information, perform localfiltering, and convert relevant events into a format that can be used by the TivoliEnterprise Console product. Because adapters are located on or near their eventsources and can perform local filtering of events, the adapters create a minimalamount of additional network traffic. Adapters use a minimal amount of systemresources to perform their functions.

Network management applications have become an important part of monitoringthe availability of resources in the enterprise. The Tivoli Enterprise Consoleproduct can seamlessly integrate alarms and events from all the major networkmanagement operating systems and can correlate them with other system,database, and application events.

Adapters are passive collectors of all types of events from systems andapplications, including the network management applications. All of your existingnetwork management configuration and monitoring of events can be preserved;these events can simply be forwarded to the event server for correlation with otherevents, where automated responses can be triggered or Information Technology(IT) staff can be notified.

Adapter overviewAn adapter is a process that monitors resources so that they can be managed. Thesemonitored resources are called sources. A source is an application (for example, adatabase) or system resource (for example, an NFS server). When an adapterdetects an event generated from a source (generally called a raw event), it formatsthe event and sends it to the event server. The event server then further processesthe event.

Adapters can monitor sources in the following ways:v An adapter can receive events from any source that actively produces them. For

example, SNMP adapters can receive traps sent by the Simple NetworkManagement Protocol (SNMP).

v An adapter can check an ASCII log file for raw events at configured intervals ifthe source updates a log file with messages.

Adapters can send events to the event server using a Tivoli interface or anon-Tivoli interface. Both types of interfaces send events using an ordinary TCP/IPchannel. The difference between the two interfaces is the method used to establishthe connection. A Tivoli interface establishes a connection using the oserv servicesprovided by Tivoli Management Framework; adapters that use this interface arereferred to as TME® adapters. A non-Tivoli interface establishes connections usingstandard interprocess communication mechanisms (for example, opening an IPsocket); adapters that use this interface are called non-TME adapters.

Note: If you are sending events from an adapter using a Tivoli connection to anevent server in a remote Tivoli region, the connection must allow theadapter to send information to the remote event server. The adapter shouldbe on the master side of a one-way connection or, more likely, the

© Copyright IBM Corp. 2003 1

connection should be a two-way connection. If you are sending events froma non-TME adapter, the type of interconnection with the Tivoli regions doesnot matter.

How adapters on endpoints send eventsTME adapters installed on endpoints send their events to the lcfd process, whichthen sends the events to a Tivoli Enterprise Console gateway, which in turnbundles them up and forwards them on to an event server. A Tivoli interface isused for communication between the endpoint and the gateway. The defaultservice to the server used by the Tivoli Enterprise Console gateway is aconnection-oriented service to the server. A connection-oriented service means thata connection is established when the adapter is initialized and the connection ismaintained for all events to be sent. The Tivoli Enterprise Console gateway runs onthe same managed node as the Tivoli Management Framework gateway that isproviding the endpoint gateway service. The Tivoli Enterprise Console gatewayprovides the following benefits:v Greater scalability, meaning you can manage many sources easier, with less

software running on the endpoints.v Greatly reduces the amount of communications tasks performed by the event

server or the Tivoli management region server, as the Tivoli Enterprise Consolegateway bundles a number of events before sending them to the event server.This improves event server performance.

v Easier deployment of adapters and updates to adapters using profiles in theAdapter Configuration Facility.

The TME adapters currently supported for an endpoint are as follows:v UNIX log filev OS/2®

v SNMPv Microsoft® Windows event log

You can configure these adapters to send their events to specific primary,secondary or both event servers, and the Tivoli Enterprise Console gatewayforwards them appropriately.v If the Tivoli Enterprise Console gateway, Tivoli Management Framework

gateway, or lcfd process is down, events are buffered at the endpoint and aresent again when communication is restored, as follows:– If the endpoint (lcfd process) is down, events are buffered at the endpoint.

When the endpoint is restarted and logs in to the Tivoli ManagementFramework gateway, events are sent as usual.

– If the Tivoli Management Framework gateway is down, events are buffered atthe endpoint. Events are not forwarded until the endpoint logs back in to theTivoli Management Framework gateway. This delay can be as much as 5minutes after the Tivoli Management Framework gateway is restarted but canbe configured on the endpoint.

– If the Tivoli Enterprise Console gateway is down (but the lcfd process or theTivoli Management Framework gateway are still up), the Tivoli EnterpriseConsole gateway is restarted, and events are sent as usual.

v If an event server is down (but the Tivoli Enterprise Console gateway, TivoliManagement Framework gateway, and lcfd processes are still up), events arebuffered at the Tivoli Enterprise Console gateway. They are sent again whencommunication with the server is restored.

2 IBM Tivoli Enterprise Console: Adapters Guide

The following figure shows an example of the Tivoli Enterprise Console productand Tivoli Management Framework component relationships in a network withendpoints.

How adapters on managed nodes send eventsFor network management HP OpenView adapters, the managed node adaptersends events directly to the event server using a Tivoli interface. In other words,the oserv of the managed node that the adapter runs on sends the event to theoserv of the event server when these are separate nodes, which then forwards it onto the event server process.

For the UNIX logfile, OS/2, Windows, and SNMP TME adapters, a managed nodemust also be configured as an endpoint to send events to the event server.

How non-TME adapters send eventsA non-TME adapter sends events directly to the event server using an IP socket.

Internationalization support for eventsThe defaulting encoding that the following logfile adapters use to send their eventsto the event server is UTF-8 encoding:v UNIX logfile adapterv NetWare logfile adapterv OS/2 logfile adapterv Windows event log adapter

To change the default configuration of these adapters so they send events in theencoding of the event server host instead of UTF-8, the Pre37Server and

ManagedNode

Endpoint GatewayTivoli Enterprise

Console Gateway

Adapters

Adapter ConfigurationFacility

Endpoint GatewayTivoli Enterprise

Console Gateway

Adapters

Adapter ConfigurationFacility

ManagedNode

EndpointsAdapters

EndpointsAdapters

Event Server

Tivoli AvailabilityIntermediateManager

ManagedNode

Figure 1. Components relationships of the Tivoli Enterprise Console product and TivoliManagement Framework

Chapter 1. Introduction to adapters 3

Pre37ServerEncoding configuration file options are provided. See “Keywords” onpage 10 for additional information about these options.

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

The adapter automatically reads the format file from the appropriate directory. Ifthe adapter is sending events to an event server running a version earlier than theTivoli Enterprise Console 3.7 product, the format files in the localization directoriesmust remain in English. See “Format file” on page 24 and Appendix B, “Format filereference”, on page 187 for additional information.

Tivoli Event Integration Facility provides support for creating new adapters (otherthan those shipped by the Tivoli Enterprise Console product) or modifying existingadapters to send events to the latest version of the event server. Existing adaptersshipped in a previous release of the Tivoli Enterprise Console product do notrequire updating; the new event server recognizes events sent from those adapters.See the Tivoli Event Integration Facility Reference for additional information.

When a non-TME adapter is installed, a new codeset directory is created with thebin and etc directories under the $TECADHOME directory. If you install an adapterwith an ID, the etc and codeset directories are created under the $TECADHOME/IDdirectory

Event information and attributesEvent information is formatted as a set of attributes. Each attribute is predefinedand contains a name and value. Adapters separate information into event classes,format this information into attributes, and send this information to the eventserver. The event server then processes this information.

Event classes are a classification of events; do not confuse them with the termclasses in the traditional object-oriented sense. Event classes can be subclassed tofacilitate a further breakdown of information so that more detailed rules can beapplied to the information. In essence, event classes are an agreement between theadapter and the event server about what information the adapter sends to theevent server for a given class.

After event information is separated into attributes and the event is categorizedinto an event class, the adapter sends the information to the event server forfurther processing. Adapters are configured to send information that onlyadministrators are interested in; that is, filters are established on the local systemthat specify whether to discard an event or forward it to the event server. Thisminimizes any network loading that is related to enterprise monitoring.

An event class name is followed by attribute information.

An adapter supplies information in the form of attributes. An attribute has thefollowing format:

attribute=value

The following list describes base event attributes that can be contained in an eventsent to the event server. Base event attributes are standard for most event classesand are defined in the highest superclass of a basic recorder of objects in C


(BAROC) file. An adapter can also contain adapter-specific or user-definedattributes.

Table 1. Base event attributes

Attribute Name Contents

acl The list of authorization roles that an administrator uses to modifythe event.

adapter_host The host on which the adapter is running.

administrator The administrator who acknowledged or closed the event.

cause_date_reception

The cause_date_reception attribute is used to link an effect event toits cause event. This value is set to the value of the date_receptionattribute of the cause event.

cause_event_ handle The cause_event_handle attribute is used to link an effect event toits cause event. This value is set to the value of the event_handleattribute of the cause event.

credibility Indicates how the event was sent from the adapter. The value is 1 ifan event was sent using a communications channel provided byTivoli Management Framework services, as is the case for a TMEadapter. The value is zero (0) if an event was sent from a non-TMEadapter.

date The date and time the event was generated.

date_reception A time stamp indicating the time the event server received theevent. It is an integer representing the number of seconds since theepoch, which is January 1, 1970. This value is also used as acomponent to uniquely identify an event. An event is uniquelyidentified by a combination of the values for the date_reception,event_handle, and server_handle attributes.

duration For closed events, the age (in seconds) of the event from when itwas received by the event server until it was closed. For allnon-closed events, the value is zero (0).Note: If an event was closed by calling the set_event_statuspredicate from within a rule, this attribute is not modified to givethe age. The value remains at zero (0).

event_handle A number used to reference the event. An event is uniquelyidentified by a combination of the values of the date_reception,event_handle, and server_handle attributes. Events received withinthe same second are assigned an incremental number for thisattribute starting at 1 and increased by 1.

fqhostname The fully qualified host name of the system where the eventoriginated.

hostname The name of the system on which the event occurred.

msg A text summary of the event.

msg_catalog For future support of internationalized event messages; notcurrently implemented.

msg_index The message ID used to obtain the internationalized message.

num_actions The number of actions (tasks or programs) currently being trackedby the event server for this event.

origin The protocol address or host name of the source system.

repeat_count A counter for keeping track of the number of times a duplicate typeof event has been received.


Table 1. Base event attributes (continued)


server_handle A number identifying the event server that received this event. Anevent is uniquely identified by a combination of the values for thedate_reception, event_handle, and server_handle attributes.

server_path Stores information describing the rule engines that an event haspassed through. server_path has the following definition:

server_path list_of_strings;

Each element in the list represents one rule engine that the eventhas visited, and each element contains a rule engine identifier,server number, reception ID, and event handle. The following is anexample of a list:

chair 1 12121212 3

where:

chair The rule engine identifier

1 The server number

12121212The event reception ID in server 1

3 The event handle for the event in server 1

severity The severity of the event. The database stores the severity as anumber. This mapping is defined in the root.baroc rule base file andis set for the event server default severities as follows:

10 UNKNOWN

20 HARMLESS

30 WARNING

40 MINOR

50 CRITICAL

60 FATAL

You can also customize the severity settings.

source The source of the event (for example, the OpenView adapter). Thesource is defined by the adapter type.


Table 1. Base event attributes (continued)


status The status of an event. It is initially set to OPEN or to a defaultvalue specified by the event class. Possible values during an eventlifetime are as follows:

ACK An administrator or rule has acknowledged the event.

CLOSEDAn administrator or rule has fixed the problem that wasreported by the event. An event adapter can also send anevent with a status of CLOSED to indicate that apreviously received event of the specified class shouldhave its status changed to CLOSED; the previouslyreceived event to be closed is the most recent duplicate ofthe same event. The event being sent with a CLOSEDstatus is dropped and not stored in the event database.

custom_statusA status that has been added to the STATUS enumerationfor site-specific purposes. The STATUS enumeration isdefined in the root.baroc file. To add a new status, edit thisfile, recompile the rule base, and restart the event server.

OPEN The event has been received by the event server, but noadministrator or rule has acknowledged it.

RESPONSEA rule has automatically responded to the event. Thisstatus is assigned a rule language predicate. It is notavailable from an event console.

The database stores the status as a number. This mapping is definedin the root.baroc rule base file and is set for the event server defaultstatus as follows: zero (0) for OPEN, 10 for RESPONSE, 20 for ACK,30 for CLOSED.

sub_origin A further categorization of the origin. This attribute is optional.

sub_source A further categorization of the source. This attribute is optional.

The adapter uses the following attributes to uniquely identify an event:v date_receptionv event_handlev server_handle

Adapter filesAn adapter uses various files for its operations. The following table provides abrief description of the types of files that can be used. Subsequent sections describesome of the more common files you might need to view or modify forconfiguration or troubleshooting purposes. See Appendix A, “Files shipped withadapters”, on page 183 for detailed information about which files are shipped withparticular adapters.

Table 2. Adapter files

File Type Description

Basic recorder of objects in C(BAROC)

Defines event classes to the event server; must bepart of the rule base.


Table 2. Adapter files (continued)

File Type Description

Cache Stores buffered events.

Class definition statement (CDS) Defines event class definitions to the adapter.

Configuration Defines configuration options for adapters.

Error Defines error logging and tracing options for theadapter.

Format Defines the format of messages and matches them toevent classes for the UNIX logfile, NetWare logfile,OS/2, and Windows event log adapters.

Installation script Configures the adapter to start when the operatingsystem starts.

Object identifier Defines object-identifier-to-name mappings for theNetView/6000, OpenView, and SNMP adapters.

Registration The registration file generated by the installationscript for NetView/6000 and OpenView.

Rules Defines rules to the event server; must be part of therule base.

An adapter uses the Tivoli Management Framework TIVOLI_COMM_DIRenvironment variable, if set, to determine which directory to use for its lock andpipe files. If the variable is not set, the /tmp/.tivoli directory is used instead. Formore information about this environment variable, see the Tivoli ManagementFramework Release Notes.

Cache fileEvents are written to the cache file using a “circular” method; when the cache filehas reached the size limit set by the BufEvtMaxSize keyword, the next new eventis written to the beginning of the cache file (thus overwriting the existing data atthat location). Subsequent events continue being written in order until the end ofthe file is reached again, and the process starts over from the beginning of the file.A small header at the beginning of the file tracks where the next new event is to bewritten and where the next old event is to be removed.

The format of the cache file is as follows:maxsz: XXXXXXXXXXhead : XXXXXXXXXXtail : XXXXXXXXXX........................event1 event2event3 event4 event5................................................................................................................................

The first three lines in the cache file all have a fixed size of 18 bytes and containthe following data:

maxsz The maximum size of the cache file.

head The byte offset from the beginning of the file to the next event to send. Avalue of zero (0) indicates an empty cache file.

tail The byte offset from the beginning of the file to the first byte of free spacein the file.


The boundaries between events in the cache file are indicated by a ^A character atthe end of each event.

Configuration fileMost adapters come with a configuration file containing configuration options andfilters. This file is read by an adapter when it is started. By modifying this file, youcan reconfigure an adapter at anytime, without having to modify the adaptersource code. To have your configuration changes take effect, simply stop andrestart the adapter. A configuration file usually has an extension of .conf; see eachspecific adapter chapter for exact file names.

File locationAn adapter expects its configuration file (along with its format, CDS, and errorfiles) to be located in the default locations shown in the following table. ForWindows, the syntax shown is correct when running the bash interpreter.

Table 3. Location of adapter configuration files

Adapter Type Node Type Location

TME Managed node $BINDIR/TME/TEC/adapters/etc/ or/etc/Tivoli/tecad/etc (which is a link to the TMEadapter directory)

Endpoint $LCFROOT/bin/$INTERP/TME/TEC/adapters/etc or/etc/Tivoli/tecad/etc (which is a link to the TMEadapter directory)

non-TME Not applicable path/etc where the adapter was manually installed or/etc/Tivoli/tecad/etc (which is a link to the non-TMEadapter directory)

For information about directory structures and system variables (those beginningwith $), see the Tivoli Management Framework Planning for Deployment Guide.

File formatEach non-blank line that does not begin with the comment sign (#) is of one of thefollowing forms:v To specify configuration options:

keyword=value

v To specify event filters:

Filter:Class=class_name;attribute=value;

v To specify event buffer filters:

FilterCache:Class=class_name;attribute=value;

Example## Communication Parameters#TransportList=t1,t2_t1Type=SOCKETt1Channels=c1_,c2c1_ServerLocation=host1c1_Port=5529c2ServerLocation=host2c2Port=5529t2_Type=LCF


t2_Channels=c3_c3_ServerLocation=@EventServer## Event Filters#Filter:Class=disk_eventFilter:Class=Su_Success;origin=126.32.2.14

KeywordsKeywords 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; however, you cannot usequotation marks at all with the HPOVFilter keyword for the HP Openviewadapter. Do not use class names that are not defined in a BAROC file withconfiguration options.

Note: Adapters do not issue error messages for misspelled keywords or keywordsset to a value that is not valid.

A configuration file can contain the following keywords, which are common tomost adapters.

Note: Not all keywords apply to all adapters, and some adapters have additionalkeywords specific to them. See each specific adapter chapter for descriptionsof these keywords.

AdapterCdsFile=pathSpecifies the full path name of the CDS file. This keyword is required if theCDS file is not in the same directory as the configuration file.

AdapterErrorFile=pathSpecifies the full path name of the error file. This keyword is required ifthe error file is not in the same directory as the configuration file.

APPEND_CLASSPATH=string

Specifies the string that is appended to the CLASSPATH environmentvariable before the Java™-based State Correlation is called. The string isappended using the appropriate delimiter:, semicolon (;) for Windowssystems or colon (:) for UNIX systems. The string must contain valid datafor your environment; for example, APPEND_CLASSPATH=c:\my_product\my_java.class; d: \my_product\my_jar .jar for Windowssystems or APPEND _CLASSPATH=/my_product/my_java.class:/my_product/my_jar.jar for UNIX systems.

For the Tivoli Enterprise Console gateway the specified string isappeneded to the list of jar files needed for State Correlation. For anadapter written in C, the specified string is appended to the systemenvironment CLASSPATH.

Note: The system environment CLASSPATH is not changed. ThisCLASSPATH information is passed to Java during the StateCorrelation initialization. This keyword can be specified only once inyour configuration file.

APPEND_JVMPATH=stringSpecifies the string that is appended to the dynamic library pathenvironment variable before the Java-based state correlation is called. Thestring is appended using the appropriate delimiter: semi-colon (;) for


Windows systems or colon (:) for UNIX systems. The string must containvalid data for your environment; for example, APPEND_JVMPATH=c:\my_product\jre\bin;c:\my_product\jre\bin\classic for Windowssystems or APPEND_JVMPATH=/my_product/jre/bin:/my_product/jre/bin/classic for UNIX systems. Thiskeyword is valid only for adapters written in C and is appended to theappropriate dynamic library path environment variable. For theenvironment variable for each operating system, see the information aboutlibrary paths and directories for endpoint adapters developed with theEvent Integration Facility Java API in the Tivoli Event Integration FacilityReference.

Note: The system dynamic library path environment variable is notchanged. This keyword can be specified only once in yourconfiguration file.

BufEvtMaxSize=sizeSpecifies the maximum size, in kilobytes, of the adapter cache file. Thedefault value is 64. The cache file stores events on disk when they cannotbe sent to the event server.

The BufEvtMaxSize keyword is optional.

BufEvtPath=pathnameSpecifies the full path name of the adapter cache file. On endpointadapters, the BufEvtPath keyword uses the $TIVOLIHOME variable toresolve differences in file locations and drive letters across variousenvironments. The variable uses a path relative to the endpoint installation.The Adapter Configuration Facility defines $TIVOLIHOME on eachendpoint; you cannot change its value.

Table 4. Path name and variable for adapter cache

Operating System Default Path $TIVOLIHOME Value

UNIX $TIVOLIHOME/tec/cache /etc/Tivoli

Microsoft Windows %TIVOLIHOME%\tec\cache.dat

%SystemRoot%\system32\drivers\etc\Tivoli

The AS/400® adapters do not use this keyword.

This is a required keyword when the BufferEvents keyword is set to YES.

If the UseStateCorrelation keyword is set to YES, the BufEvtPath keywordalso specifies the path to store events for state correlation. Tivoli EventIntegration Facility adds the prefix _sc to the specified file name. Theprefix differentiates the adapter cache file from the event storage path forstate correlation. The default value for the path is$TIVOLIHOME/tec/cache_sc for UNIX systems and%TIVOLIHOME%\tec\cache_sc.dat for Windows systems.

Note: If more than one application on the same system uses Tivoli EventIntegration Facility, ensure that each application has unique valuesfor the path name.

BufferEvents=YES | NOSpecifies how event buffering is enabled.

YES Stores events in the file specified by the BufEvtPath keyword.


NO Does not store or buffer events.

If UseStateCorrelation=YES and BufferEvents=YES, the API also storesevents in files that are specified with the BufEvtPath keyword. TheStateCorrelationMaxFileSize and StateCorrelationTotalSize keywordscontrol the size and number of files.

The value is not case-sensitive. The default value is YES. This keyword isoptional.

BufferFlushRate=events_per_minuteSpecifies the number of events that are sent per minute. Once the adapterhas recovered the lost connection, and there are events in the buffer, theevents are sent at this rate per minute. The default value is 0 ;consequently all events are sent in one burst.

This keyword is optional.

ConnectionMode=connection_oriented | connection_lessSpecifies the connection mode to use to connect to the Tivoli EnterpriseConsole gateway or the event server. The default value is connection_less,except for the Tivoli Enterprise Console gateway, which hasconnection_oriented as the default value.

connection_orientedA connection is established at adapter initialization and ismaintained for all events sent. A new connection is establishedonly if the initial connection is lost. The connection is discardedwhen the adapter is stopped. This option can be abbreviated to coor CO.

connection_lessA new connection is established and discarded for each event orgroup of events that is sent.


ed_diag_config_file=filenameThe filename file must be present for logging and tracing to occur. To enablelogging, specify error or warning in the filename file. To enable tracing,specify trace0, trace1, or trace2 in the filename file. The filename file canbe either fully qualified or relative to the directory where the adapter isrunning. A sample file, .ed_diag_config, is in the EIFSDK directory on theIBM Tivoli Enterprise Console TME New Installations CD.

Each level of logging or tracing also includes all levels below it. Forexample, when you specify warning logging, error logging automatically isenabled.

Note: Be aware that increasing the level of tracing produces a large traceoutput. You can configure whether or not the file is recreated onrestarts.


Filter Works with the FilterMode keyword to determine how events are filtered.An event matches a Filter statement when each attribute=value pair in theFilter statement is identical to the corresponding attribute=value pair in theevent.


A Filter statement must contain the event class, and optionally can includeany other attribute=value pair that is defined for the event class. The formatof a filtering statement is as follows:Filter:Class=class_name;[attribute=value;...;attribute=value]

Each statement must be on a single line. The attribute=value pair is casesensitive.


FilterCacheWorks with the FilterMode and Filter keywords to determine which eventsare stored in the cache when events cannot be sent successfully to theevent server. To store events in the cache, you must set BufferEvents=YES.An event matches a FilterCache statement when each attribute=value pair inthe FilterCache statement is identical to the corresponding attribute=valuepair in the event.

A FilterCache statement must contain the event class (class_name) and caninclude any attribute=value pair that is defined for that event class. Theformat of a filtering statement is as follows:FilterCache:Class=class_name;[attribute=value;...;attribute=value]

Each statement must be on a single line. The attribute=value pair is casesensitive. You must specify the Filter keyword, when you use theFilterCache keyword. Additionally, the FilterCache statement must specifythe same class or subset of classes that the Filter statement specifies.


Note: When using the FilterCache keyword with endpoint adapters andthe Tivoli Enterprise Console gateway, you must set the filteringstatements at both locations to the same specifications.

FilterMode=IN | OUTSpecifies whether events that match a Filter or FilterCache statement aresent to the event server (FilterMode=IN) or discarded (FilterMode=OUT).The default value is OUT. The valid values are IN or OUT, without regardfor case. If you set FilterMode=IN, you must have one or more Filter andFilterCache statements defined.

For information about how to use filtering keywords to send, cache, anddiscard events, see “Event filtering” on page 21.


FQDomain= YES | NO | fqdomainSpecifies how the adapter should set the value of the fqhostname attributeof events sent to the event server. This attribute is used to specify the fullyqualified host name of the originating host. Possible values for thiskeyword are:

YES The adapter attempts to determine the fully qualified host name. Ifthis is successful, the fqhostname attribute is set to this value; ifnot, the attribute has a null value.

NO The fqhostname attribute has a null value. This is the default valueif the FQDomain keyword is not specified.


fqdomainfqdomain is appended to the host name, and the resulting string isused as the value of the fqhostname attribute. If the host namecontains periods (meaning that it is already fully qualified),fqdomain is not appended.

Note: This keyword is valid only for the OpenView, SNMP, UNIX log file,and Windows event log adapters.

getport_timeout_seconds=num_secondsSpecifies the number of seconds to wait before re-sending the UDP call fora port, if no response is heard. It re-transmits until the RPC call times out.The default value is zero (0) seconds.

getport_timeout_usec=num_microsecondsSpecifies the number of microseconds to add to the seconds specified withthe getport_timeout_seconds keyword. The default value is 50 000microseconds.

getport_total_timeout_seconds=num_secondsSpecifies the number of seconds to wait on getting a port after making acall to the portmapper. The default value is zero (0) seconds.

getport_total_timeout_usec=num_microsecondsSpecifies the number of microseconds to add to the seconds specified withthe getport_total_timeout_seconds keyword. The default value is 50 000microseconds.

LogFileName=pathnameSpecifies the full path name of the log file for the Java API. The defaultlocation for the file is $TIVOLIHOME/tec/eif.log.

If UseStateCorrelation=YES, the LogFileName keyword also defines thepath to store the log file for state correlation. Tivoli Event IntegrationFacility adds the prefix _sc to the specified file name. The prefixdifferentiates the log file for the Java API from the log file for statecorrelation. The default value for the path is$TIVOLIHOME/tec/eif_sc.log.

If you specify a non-valid path name, the API returns the following error:LOG0014E Unable to open the handler output file <filename>.java.io.FileNotFoundException: <filename> (The system cannot findthe path specified)


LogLevel=levelSpecifies whether the Java API generates log messages or not. By default,no messages are generated. Specify ALL to generate messages. If youspecify any other value or no value, the API does not generate messages.


MaxPacketSize=bytesSpecifies the number of bytes to be sent at the rate specified by theBufferFlushRate keyword. The default value is zero (0), where one event issent at a time.


NO_UTF8_CONVERSION=YES | NOSpecifies whether Tivoli Event Integration Facility encodes event data in


UTF-8. When this keyword is set to YES, Tivoli Event Integration Facilitydoes not encode event data in UTF-8. The data is assumed to already be inUTF-8 encoding when passed to Tivoli Event Integration Facility. It does,however, prepend the flag indicating that the data is in UTF-8 encoding ifthe flag does not exist at the beginning of the event data.

This keyword is optional. The default value for this keyword is NO.

Pre37Server=YES | NO

Specifies whether the adapter sends events in the encoding of the eventserver host or in UTF-8 encoding. Event server host versions earlier thanthe Tivoli Enterprise Console 3.7 product do not support UTF-8 encodingof events. The following values are not case-sensitive:

YES Disables UTF-8 encoding and allows the adapter to communicatewith event server host versions earlier than the Tivoli EnterpriseConsole 3.7 product. When this keyword is set to YES, you mustalso specify the Pre37ServerEncoding keyword.

NO The adapter sends events in UTF-8 encoding. The default value isNO.


Pre37ServerEncoding=language

Determines which language to use when a non-TME adaptercommunicates with a non-UTF-8 event server host (versions earlier thanthe Tivoli Enterprise Console 3.7 product). This keyword is active onlywhen the Pre37Server keyword is set to YES.


PREPEND_CLASSPATH=string

Specifies the string that is prepended to the CLASSPATH environmentvariable before the Java based State Correlation is called. The string isprepended using the appropriate delimiter: semicolon (;) for Windowssystems or colon (:) for UNIX systems. The string must contain valid datafor your environment; for example, PREPEND_CLASSPATH=c:\my_product\my_java.class; d: \my_product\my_jar .jar for Windowssystems or PREPEND _CLASSPATH=/my_product/my_java.class:/my_product/my_jar.jar for UNIX systems.

For the Tivoli Enterprise Console gateway the specified string is prependedto the list of jar files needed for State Correlation. For an adapter written inC, the specified string is prepended to the system environmentCLASSPATH.

Note: The system environment CLASSPATH is not changed. ThisCLASSPATH information is passed to Java during the StateCorrelation initialization. This keyword can be specified only once inyour configuration file.

PREPEND_JVMPATH=stringSpecifies the string that is prepended to the dynamic library pathenvironment variable before the Java-based state correlation is called. Thestring is prepended using the appropriate delimiter: semicolon (;) forWindows systems or colon (:) for UNIX systems. The string must containvalid data for your environment; for example, PREPEND_JVMPATH=c:\my_product\jre\bin;c:\my_product\jre\bin\classic for Windows


systems or PREPEND_JVMPATH=/my_product/jre/bin:/my_product/jre/bin/classic for UNIX systems. Thiskeyword is valid only for adapters written in C and is prepended to theappropriate dynamic library path environment variable. For theenvironment variable for each operating system, see the information aboutlibrary paths and directories for endpoint adapters developed with theEvent Integration Facility Java API in the Tivoli Event Integration FacilityReference.

Note: The system dynamic library path environment variable is notchanged. This keyword can be specified only once in yourconfiguration file.

RetryInterval=timeout

When ConnectionMode=connection_oriented, and the connection to theevent server is lost, an adapter waits the specified number of secondsbefore re-attempting to connect to the primary or secondary servers, or tobuffer the events. While the adapter is waiting for the expiration of thisinterval, no new events are processed by the adapter.

This option allows an adapter to send all events to the primary eventserver even if the primary event server is stopped briefly, such as whenloading a new rule base.

If you use this keyword to wait for restarting an event server, set the valuefor a period of time longer than necessary for the event server to bestopped and then restarted.

This keyword is optional. The default value is 120 seconds.

ServerLocation=hostSpecifies the name of the host on which the event server or TivoliEnterprise Console gateway is installed. The value of this field must be oneof the formats shown in Table 5, depending on whether the adapter is aTME adapter or a non-TME adapter, and whether the event server is partof an interconnected Tivoli management region:

Table 5. Formats for the ServerLocation keyword

Adapter Type Format

TME @EventServer

TME in an interconnectedTivoli management region

@EventServer#region_name

non-TME host_name or IP_address. Use the dotted formatfor IP_address.

For TME adapters on managed nodes and non-TME adapters, theServerLocation keyword can contain up to eight values, separated bycommas. The first location is the primary event server, while others aresecondary servers to be used in the order specified when the primaryserver is down.

For endpoint adapters, secondary event servers, if any, are defined in theTivoli Enterprise Console gateway configuration file. Only specify aprimary event server in the configuration file for an endpoint adapter.


For a non-TME adapter, the default value is localhost. For a TME adapteron a managed node, the default value is @EventServer. A TME adapter onan endpoint, by default, uses the configuration on the Tivoli EnterpriseConsole gateway. See the IBM Tivoli Enterprise Console User’s Guide formore information about the Tivoli Enterprise Console gateway.

For endpoint adapters, if you use an IP name or address in theServerLocation value, then the Tivoli Enterprise Console gateway uses thatvalue to send the event using non-Tivoli communication to the server.

For non-TME adapters, the ServerLocation keyword can contain the IPname or address of the Tivoli Enterprise Console gateway if reception ofevents from non-TME adapters is enabled at this gateway.

The ServerLocation keyword is optional and not used when theTransportList keyword is specified.

Note: The ServerLocation keyword defines the path and name of the filefor logging events, instead of the event server, when used with theTestMode keyword.

ServerPort=numberSpecifies the port number on which the event server or Tivoli EnterpriseConsole gateway listens for events. Set this keyword value to 0, the defaultvalue, unless the portmapper is not available on the event server, which isthe case if the event server is running on a Microsoft Windows system orthe event server is a Tivoli Availability Intermediate Manager (see thefollowing note). If the port number is specified as zero (0) or it is notspecified, the port number is retrieved using the portmapper.

Note: Portmapper is not supported for reception of events from non-TMEadapters at the Tivoli Enterprise Console gateway. If your non-TMEadapter is sending events to this gateway, then you must code theServerPort keyword to match the value in the gwr_ReceptionPortkeyword in the Tivoli Enterprise Console gateway configuration file.

The ServerPort keyword can contain up to eight values, separated bycommas. For non-TME adapters that send events to a UNIX event server,use the default value of 0 (only one value of 0, even if multiple UNIXevent servers are specified with the ServerLocation keyword). Fornon-TME adapters that send events to a Windows event server or a TivoliAvailability Intermediate Manager, specify one value for each event serverdefined with the ServerLocation keyword.

The ServerPort keyword is optional when the event server is running onthe UNIX operating system, but mandatory when running on Windowsoperating system. It is not used when the TransportList keyword isspecified.

Note: If the event server is running on Windows operating system: There is noportmapper daemon on a Windows system that allows the adapterto query the reception port at run time. The event server listens on afixed reception port (tec_recv_agent_port in .tec_config file) forconnection and adapter input. Set the ServerPort keyword to thevalue of the tec_recv_agent_port entry in the .tec_config file in the$BINDIR/TME/TEC directory. The default value is 5529. The Tivoli


Availability Intermediate Manager never uses the portmapper; theTivoli Availability Intermediate Manager server listens on a fixedport set in the Tivoli Availability Intermediate Manager graphicaluser interface.

StateCorrelationCleaningInterval=millisecondsSpecifies, in milliseconds, how often state correlation removes unnecessaryentries from its event storage files. The default value is one minute.


StateCorrelationConfigURL=pathnameSpecifies the directory and file name where the configuration for statecorrelation is stored. On Windows systems, an example of the path is asfollows: file:C:\work_dir\tstate\tecroot.xml. On UNIX systems, anexample of the path is as follows: file:///work_dir/tstate/tecroot.xml.

This keyword is required when the UseStateCorrelation keyword is set toYES.

StateCorrelationMaxFileSize=kilobytesSpecifies the maximum size, in kilobytes, for each event storage file createdby state correlation. This is an approximate value, due to the variable sizeof events.


StateCorrelationTotalSize=kilobytesSpecifies the maximum value, in kilobytes, allowed for the entire cachingmechanism for state correlation. This is an approximate value, due to thevariable size of events.

Note: The value must be at least double the value specified for theStateCorrelationMaxFileSize keyword. Thus, the doubled value cansupport at least two files:v Current event cache file, persist1.outv At least one file holding archived events, archive1.out

When calculating disk space for this cache, verify that you have a buffer of10% of the specified values, with a minimum of 4 KB. This configurationensures that the cache does not run out of disk space.

When the state correlation cache reaches its limit (the value specified bythis keyword), the following occurs:1. All subsequent events return a suspend exception to Tivoli Event

Integration Facility. In turn, Tivoli Event Integration Facility returns anerror to the application.

2. A forced cleanup of the cache is started; all removed events areeliminated from the persistence cache.

3. Remaining events are recovered and returned to Tivoli EventIntegration Facility. Then, Tivoli Event Integration Facility forwardsthose events.

4. The state correlation cache is re-initialized, and event processingresumes.



TestMode=YES | NOSpecifies whether test mode is turned on or off. When TestMode=YES, theServerLocation keyword specifies the file to which events are logged,instead of being sent to the event server. Valid values are YES and NO,without regard to case. The default value is NO.

The TestMode keyword is optional.

TraceFileName=pathnameSpecifies the full path name of the trace file for the Java API. The defaultlocation of the file is $TIVOLIHOME/tec/eif.trc.

If the UseStateCorrelation keyword is set to YES, the TraceFileNamekeyword also defines the path to store tracing for state correlation. TivoliEvent Integration Facility adds the prefix to the specified file name. Theprefix differentiates the trace file for the Java API from the trace file forstate correlation. The default value for the path is$TIVOLIHOME/tec/eif_sc.trc.

If you specify a non-valid path name, the API returns the following error:LOG0014E Unable to open the handler output file <filename>.java.io.FileNotFoundException: <filename> (The system cannot findthe path specified)


TraceLevel=levelSpecifies whether the Java API generates trace messages or not. By default,no messages are generated. Specify ALL to generate messages. If youspecify any other value or no value, the API does not generate messages.


TransportList=type_name,...Specifies the user-supplied names of the transport mechanisms, separatedby commas. When a transport mechanism fails for sender applications, theAPI uses the following transport mechanisms in the order specified in thelist. For receiving applications, the API creates and uses all the transportmechanisms.

Note: This keyword is supported only for Solaris, HP, AIX®, Linux, andWindows adapters. It is not supported for other adapters.

This keyword is optional. If it is specified, the transport type and channelfor each type_name must be specified using the Type and Channelskeywords:

type_nameType=LCF | SOCKET | TMESpecifies the transport type for the transport mechanism specifiedby the TransportList keyword.

This keyword is required.

The server and port for each channel_name are specified by theServerLocation and Port keywords.

type_nameChannels=channel_name,...Specifies the user-supplied names of the channels for the transportmechanism specified by the TransportList keyword, separated bycommas.

This keyword is required.


Depending on the Type specified (LCF, SOCKET, or TME), also useone or more of the following keywords:

channel_namePort=numberSpecifies the port number on which the transportmechanisms server listens for the specified channel (set bythe Channel keyword). When this keyword is set to zero(0), the portmapper is used. This keyword is requiredwhen the Type keyword is set to SOCKET. It is optional forendpoint adapters.

channel_namePortMapper=YESEnables the portmapper for the specified channel. Thisoptional keyword is valid only when the transport type isset to SOCKET.

channel_namePortMapperName=nameIf the portmapper is enabled, specifies the name of theportmapper. This optional keyword is valid only when thetransport type is set to SOCKET.

channel_namePortMapperNumber=rpc_idSpecifies the ID registered by the remote procedure call.This optional keyword is valid only when the transporttype is set to SOCKET.

channel_namePortMapperVersion=version_numberIf the portmapper is enabled, specifies the version of theportmapper. This optional keyword is valid only when thetransport type is set to SOCKET.

channel_nameServerLocation=server[region]Specifies the name of the event server and region on whichthe server for transport mechanisms is located for thespecified channel. The channel is set by the Channelkeyword. This keyword is required when the Typekeyword is set to TME, LCF, or SOCKET. See Table 5 onpage 16 for valid formats of the server and region fields.

channel_nameTMEHost=hostnameFor the Java API only, specifies the host name of themanaged node where the event server resides. This is arequired keyword when the Type keyword is set to TME.

channel_nameTMEPassword=passwordFor the Java API only, specifies the password for the Tivoliadministrator used to connect to the managed node. Thiskeyword is required when the Type keyword is set to TME.

channel_nameTMEPort=numberFor the Java API only, specifies the port number for themanaged node. The default value for this keyword is 94.This keyword is required when the Type keyword is set toTME.

channel_nameTMEUserID=nameFor the Java API only, specifies the Tivoli administrator forthe managed node. The required authorization role is user.This keyword is required when the Type keyword is set toTME.


UseStateCorrelation=YES | NOSpecifies if the API calls the state correlation engine. The default value isNO. If this keyword is set to YES, the BufferEvents and BufEvtPathkeywords control state correlation.


WIDTHSTRMEANING=YES | NOIndicates how the length modifier is interpreted, as follows:

NO Interprets the length modifier as a truncation indication; that is, itmatches the full string and truncates the associated variable to thelength specified. This is the default value.

YES Interprets the length modifier as in Tivoli Enterprise Console,Version 3.6.x, that is, as an exact specification of the length of thestring to match.

Event filteringUsually, an adapter sends all events to the event server. You can optionally specifyevents that can or cannot be sent to the event server. You can do this by specifyingthe event class and such information as the origin, severity, or any otherattribute=value pair that is defined for the event class. The class name specified foran event filter entry must match a defined class name; an adapter does notnecessarily have knowledge of the class hierarchy.

Depending on how you specify the Filter and FilterMode keywords, filtered eventsare either sent to the event server or discarded.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 specific events:1. Set FilterMode to OUT (the default value).2. Create Filter statements to match the specific events that you want discarded.

v To send all events to the event server (the default behavior):1. Set FilterMode to OUT.2. Do not specify any Filter statements.

Note: All events are discarded when the configuration is as follows:1. FilterMode is set to IN.2. No Filter statements are specified.

To use non-English characters in a Filter statement, you must enter the non-Englishcharacters in the local encodings.

Regular expressions in filters: You can also use Tcl regular expressions infiltering statements. The format of a regular expression is re:’value_fragment’.

Note: Tivoli Event Integration Facility uses an exception to the Tcl regularexpression syntax. The backslash character (\) in Tivoli Event IntegrationFacility indicates that the following literal character is the character to filterfor, not some special character such as a tab. For example, \t means the tabcharacter in Tcl, but means t in Tivoli Event Integration Facility.

The following example shows a Filter statement with a regular expression. Thisfilter statement matches any event whose class name begins with TEC_:


Filter:Class=re:’TEC_.*’

The following example shows a FilterCache statement with a narrower range. Thisfilter statement matches any event whose class name begins with TEC_ and whoseseverity is CRITICAL:FilterCache:Class=re:’TEC_.*’;severity=CRITICAL

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

Event filter examples: The following table shows some event filter examples for afew different adapters:

Table 6. Event filter examples

Adapter Example

AS/400 Alert The following entry matches all events of theSNA_Equipment_Malfunction class from the origin 1.2.3.4:

Filter:Class=SNA_Equipment_Malfunction;origin=1.2.3.4

UNIX Logfile The following entry matches all events of the Su_Success class fromthe origin 126.32.2.14:

Filter:Class=Su_Success;origin=126.32.2.14

OpenView The following entry matches all events of the OV_Message class fromthe origin 126.32.2.14:

Filter:Class=OV_Message;origin=126.32.2.14

Windows® The following entry matches all events of the NT_Power_Failure classfrom the origin 126.32.2.14:

Filter:Class=NT_Power_Failure;origin=126.32.2.14

Event buffer filteringWhen an adapter is unable to connect to the event server or Tivoli EnterpriseConsole gateway, it sends the events to a file if the BufferEvents keyword is set toYES. You can filter events sent to a cache file, similar to filtering events for theevent server by using the FilterCache keyword.

There are no default event cache filters in the configuration files shipped withadapters.

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.

Event buffer filter examples: The following table shows some event buffer filterexamples for a few different adapters:

Table 7. Event buffer filter examples

Adapter Example

AS/400 Alert The following entry matches all events of the SNA_Equipment_Malfunctionclass from the origin 1.2.3.4:

FilterCache:Class=SNA_Equipment_Malfunction;origin=1.2.3.4

UNIX Logfile The following entry matches all events of the Su_Success class from theorigin 126.32.2.14:

FilterCache:Class=Su_Success;origin=126.32.2.14

OpenView The following entry matches all events of the OV_Message class from theorigin 126.32.2.14:

FilterCache:Class=OV_Message;origin=126.32.2.14

Windows The following entry matches all events of the NT_Power_Failure class fromthe origin 126.32.2.14:

FilterCache:Class=NT_Power_Failure;origin=126.32.2.14

BAROC fileEach adapter comes with a BAROC file describing the classes of events the adaptersupports. This file is not used by the adapter itself, but serves as a mandatory linkbetween the adapter and the event server. The event server must load this filebefore it is able to understand events received from the adapter. A BAROC file hasan extension of .baroc; see each specific adapter chapter for exact file names. Theformat of a BAROC file is described in the IBM Tivoli Enterprise Console RuleDeveloper’s Guide.

The following fragment shows how an event class for reporting SNMPauthentication problems could be defined in a BAROC file:CLASS AUTHENTICATION_FAILURE ISA EVENTDEFINES {

source:default="SNMP";sub_source:default="NET";auth_source:STRING;};

END

Rule fileSome adapters come with a rule file describing the classes of events the adaptersupports. This file is not used by the adapter itself, but serves as a mandatory linkbetween the adapter and the event server. The event server must load this filebefore it is able to understand events received from the adapter. A rule file has anextension of .rls; see each specific adapter chapter for exact file names. The formatof a rule file is described in the IBM Tivoli Enterprise Console Rule Developer’s Guide.

The following fragment shows how an event class for reporting SNMPauthentication problems could be defined in a BAROC file:


CLASS AUTHENTICATION_FAILURE ISA EVENTDEFINES {

source:default="NET";sub_source:default="SNMP";auth_source:STRING;};

END

Format fileThe UNIX logfile, NetWare logfile, OS/2, and Windows event log adapters canextract information from system log messages, whose format and meaning canvary widely. This capability is necessary because similar sources can producemessages in different formats. For example, different NFS (network file system)implementations might report the file system full error in different formats. As aresult, you might need to match different messages to the same or different eventclasses. This type of matching is done with a format file.

The purposes of a format file are as follows:v Serves as the lookup file for matching messages to event classes. When the

format file is being used for this purpose, all format specifications in the file arecompared from top to bottom. In situations where there are multiple matchingclasses for a message, the last matching format specification is used. If no matchis found, the event is discarded.

v Serves as the source from which a CDS file is generated. See “Class definitionstatement file” on page 25 for additional information.

See Appendix B, “Format file reference”, on page 187 for details about format files.

The following examples show sample entries from the format file used by theWindows event log adapter.

Note: The format files for the logfile-type adapters are examples only;customization might be required. The message text must be no longer than1024 characters.

FORMAT NT_Base%t %s %s %s %s %s %s %s*hostname DEFAULTorigin DEFAULTcategory $3eventType $4sid $5sub_source $6id $7msg $8-date1 $1-date2 $2date PRINTF("%s %s", date1, date2)END

FORMAT NT_Share_Dir_Missing FOLLOWS NT_Base%t %s %s %s %s %s %s The server service was unable to recreatethe share %s because the directory %s no longer exists.sharename $8directoryname $9END

FORMAT NT_Service_Start FOLLOWS NT_Base%t %s %s %s %s %s %s %s* started successfully.service $8END


FORMAT NT_Service_Started FOLLOWS NT_Base%t %s %s %s %s %s %s The %s* service was started.service $8END

Class definition statement fileCDS files are used by an adapter to map incoming raw events to a particular classand to define event attributes before forwarding the event to the event server.

No alterations to this file are necessary to use an adapter unless you alter thecorresponding .fmt file (if any). If any event definition is changed in a CDS file, thecorresponding event class definition in the BAROC file might need changing aswell. Event definition content and syntax are described in the IBM Tivoli EnterpriseConsole Rule Developer’s Guide.

See Appendix C, “Class definition statement file reference”, on page 197 for detailsabout CDS files.

The following example shows a CDS file:## Default attribute values#MAP_DEFAULT

source = SNMP;sub_source = NET;

# forwarding_agent = $SOURCE_ADDR;origin = $AGENT_ADDR;adapter_host = $ADAPTER_HOST;

END

CLASS Authentication_Failure_CiscoSELECT

1: ATTR(=,$ENTERPRISE), VALUE(PREFIX, "1.3.6.1.4.1.9");2: $TYPE = 4;3: ATTR(=,"authAddr");

FETCH1: IPNAME($SOURCE_ADDR);

MAPhostname = $F1;originating_address = $V3;

END# For Cisco routers, because we know the interface generating the trap,# we map ’linkUp’ traps to ’linkDown’ CLOSED eventsCLASS Link_Down_Cisco

SELECT1: ATTR(=,$ENTERPRISE), VALUE(PREFIX, "1.3.6.1.4.1.9");2: $TYPE = 3;3: ATTR(=,"ifIndex");4: ATTR(=,"ifDescr");5: ATTR(=,"ifType");6: ATTR(=,"locIfReason");


MAPhostname = $F1;sub_origin = $V4;status = CLOSED;interface_index = $V3;interface_description = $V4;interface_type = $V5;reason = $V6;

END


Error fileIt is possible to selectively activate tracing for any module of an adapter (parser,kernel, select, fetch, map, driver, and so forth) and for any level of error tracing. Adifferent log file can be specified for each module/level pair. To see a continuousflow of adapter processing with tracing, change all occurrences of /dev/null to thesame output file. Keep in mind that these tracing features can consume largeamounts of disk space.

Note: The AS/400 adapters run in batch as an AS/400 job. Every job writesmessages (completion, error, and informational) to a job log. See the AS/400adapter chapters for more information about debugging and tracing options.

Using specifications in the error file, you can configure tracing options for anadapter. An error file usually has an extension of .err; see each specific adapterchapter for exact file names. An error file is located in the same directory as theadapter configuration file (see “File location” on page 9 for details).

Note: The error file name can be specified in the configuration file by theAdapterErrorFile keyword, as shown in the following example:AdapterErrorFile=/usr/tecad/tecad_adaptername.err

If you change event definitions in the CDS or format files, you can use the errorfile to confirm that the adapter works properly with the new event definitions.

To specify the exact path of the trace file, change all instances of /dev/null in theerror file a file name that you want.

Each line of the error file consists of the following information:

module_name error_level output_file

where:

module_name Specifies the type of function to trace. Valid values are as follows:

ERRORAn error function.

UTILSA utility function.

PARSERA parsing function.

KERNELA general kernel operation.

SELECTA selection process.

FETCHA fetch process.

MAP A mapping process.

DRIVERA driver main program.

DRVSPECAn adapter-specific driver part.


TECIOAn event server I/O.

error_level Specifies the type of error to look for or the type of trace toperform. Valid values are as follows:

MINORA minor error.

MAJORA major error (running continues).

FATALA fatal error (running ends).

LOW Minimal tracing.

NORMALNormal tracing.

VERBOSEVerbose tracing.

output_file Specifies the name of the file to write output to.

Initial filesEach adapter comes with an initial set of files that provides out-of-the-box supportfor a predefined set of events. The set of files is composed of the following files:v BAROC filev CDS filev For the adapters on NetWare, OS/2, UNIX, and Windows: format file

By modifying these files, a system administrator can add, modify, and specializeclasses of events.

The number of different events an adapter can receive is infinite. Therefore, themajor objective of the initial files provided with an adapter is not to be exhaustive,but essentially to support the most common type of events handled by this adapter(for example, SNMP generic traps), as well as to provide enough examples to thesystem administrator on which to build new event definitions.

The initial supported events for the adapters are described in each adapter chapterlater in this guide.

Troubleshooting adaptersThe following sections list troubleshooting guidelines for the different types ofadapters.

Adapter startup errorsIf the adapter fails to start, look in the /tmp directory for the tecadEH.log file. Youmight be able to learn why the adapter failed from reading this file. The followinglist shows examples of errors you might find in the tecadEH.log file:tecad EH : error 2 invalid error config line: Normaltecad EH : error 4 Init: Stat failed on error file </etc/tecad_hpov.err>


Troubleshooting for all adapters1. You receive a connection error when using wpostemsg or postemsg. The error

indicates that you might be using a user ID other than Administrator or root.Thus, your ID does not have the correct permissions to create and write the filespecified by the BufEvtPath keyword.

2. If the adapter receives the event and you can determine (through tracing ordebugging) that the event matches the correct class, use the tracing output toverify if the event was sent to the event server, not sent, or cached. If the eventwas not sent to the event server, check the adapter configuration file to see ifthat class was filtered out.

3. If the event was sent to the event server, verify that the event server is actuallyrunning. Then run the wtdumprl command to check to see if the event serverreceived the event but failed to parse the event correctly. Also check the currentrule base rules to see if the event was dropped. See the IBM Tivoli EnterpriseConsole Command and Task Reference for more information about the wtdumprlcommand.

4. Check the cache files to see if the event was cached.

Managed node adapter troubleshooting1. Use the tracing and debugging options detailed in each chapter. This helps

determine if the adapter receives the event and how the adapter handles theevent.

2. Use Tivoli Management Framework debugging output of the odstat and wtraceservices. These services show what occurs after the adapter tries to send anevent from the managed node oserv service to the Tivoli Enterprise Consoleoserv services, and they also help debug problems that occur during adapterconfiguration profile distributions.

3. Use the managed node wpostemsg command from the system the adapter isrunning on to see if the event arrives at the event server. See the IBM TivoliEnterprise Console Command and Task Reference for more information.

Endpoint adapter troubleshooting1. Use the wep ls command to make sure that the endpoint is shown under the

Tivoli Management Framework gateway you want. See the IBM Tivoli EnterpriseConsole Command and Task Reference for more information. Also make sure thatany Tivoli Management Framework gateway the endpoint can log on to has theAdapter Configuration Facility installed.

2. Source the endpoint environment and edit the last.cfg file in $LCF_DATDIR.Set log_threshold to 3 and then stop and restart the endpoint to enableendpoint tracing to the lcfd.log file. Check to make sure that the endpointlogged into an appropriate Tivoli Management Framework gateway.

3. If the endpoint has logged into a Tivoli Management Framework gatewaysuccessfully, create and distribute the adapter configuration profile (see the IBMTivoli Enterprise Console User’s Guide for details). Check the lcfd.log file if thereare further problems; you can also turn on tracing at the Tivoli ManagementFramework gateway and look in $DBDIR/gatelog for further debugginginformation.

4. If events do not arrive at the event server but are not incorrectly parsed, checkto see if the events are caching on the endpoint instead. If so, either the lcfdprocess cannot communicate to the Tivoli Management Framework gateway or


the event server, or the lcfd process itself is down. Verify that allcommunications among the event server, Tivoli Management Frameworkgateway, and endpoint are working.

5. Source the endpoint environment, then use the endpoint wpostemsg commandfrom the system the adapter is running on to see if the event arrives at theevent server. See the IBM Tivoli Enterprise Console Command and Task Referencefor more information.

Non-TME adapter troubleshootingUse the postemsg command from the system on which the adapter is running tosee if the event arrives at the event server. The postemsg command works inenvironments where Tivoli software is not installed. Thus, this standalonecommand displays error messages in English only, because the command does nothave access to the message catalogs for the language support packs. See the IBMTivoli Enterprise Console Command and Task Reference for more information.


Chapter 2. Installing adapters

This chapter describes how to install, upgrade, and uninstall adapters. After youinstall the event server, user interface (UI) server, sample event information, eventconsoles, and Adapter Configuration Facility, you can install selected adapters.

After installing and configuring adapters, you must configure event sources andevent groups to enable the event server to receive events from the adapters. Seethe IBM Tivoli Enterprise Console User’s Guide for information about configuringevent sources and event groups.

Notes:

1. The IBM Tivoli NetView for z/OS™ adapters are delivered with the TivoliNetView for z/OS product as part of the Event/Automation Service. Forinformation about installing these adapters, see the IBM Tivoli NetView for z/OSInstallation and Administration Guide.

2. The logfile_hpux10 profile type should be used for HP-UX 11 systems.3. The logfile_aix4-r1 profile type should be used for the 4.2 and 4.3 versions of

the AIX operating system.4. The following TME adapters can be installed only on an endpoint and must be

installed and configured using the Adapter Configuration Facility.v OS/2 adaptersv SNMP adaptersv UNIX logfile adaptersv Windows event log adapters

The non-TME versions of these adapters do not require the Tivoli ManagementFramework and, therefore, run on any supported operating system. To installone of these adapters on a managed node where an endpoint is not installed,you must use the non-TME version of the adapter; another option is to installan endpoint on the managed node.

5. NetWare can be installed only as a non-TME adapter.6. On the Windows 2000 operating system, the logfile adapter is referred to as the

Windows event log adapter.

Supported adaptersThis chapter describes how to install the following adapters.

Table 8. Supported adapters

Adapter Interface Install from For more information

AS/400 alertand message

Non-Tivoli Command line “Installing AS/400 adapters” onpage 37

OpenView Tivoli Tivoli desktop orcommand line

“Installing an HP OpenView adapter ona managed node” on page 33

Non-Tivoli Command line “Installing a non-TME adapter” onpage 34


Table 8. Supported adapters (continued)

Adapter Interface Install from For more information

OS/2 Tivoli Tivoli desktop “Installing an adapter on an endpoint”on page 33


SNMP Tivoli Tivoli desktop “Installing an adapter on an endpoint”on page 33


UNIX logfile Tivoli Tivoli desktop “Installing an adapter on an endpoint”on page 33


Windows Tivoli Tivoli desktop “Installing an adapter on an endpoint”on page 33


Hardware and software requirementsFor the disk space requirements for adapters that are shipped with the TivoliEnterprise Console product, refer to the IBM Tivoli Enterprise Console InstallationGuide.

The adapter should be installed on the host that contains the system resource orapplication to monitor. You might need to install more than one adapter on a host.

UNIX and Windows software requirementsBefore you can install a TME adapter on a managed node using the Tivoli desktop,you must have version 3.6.3 or later of the Tivoli Management Frameworkinstalled on the host on which you want to install the adapter.

To install a TME adapter on an endpoint, you must use the Adapter ConfigurationFacility from the Tivoli desktop.

AS/400 software requirementsThe following AS/400 program temporary fixes (PTFs) are the minimum required.You can install PTFs that supersede these. See http://www.ibm.com for the mostcurrent information on supported versions of the OS/400® system.

Table 9. AS/400 software requirements

OS/400 Version Minimum PTFs Required

V4R3M0 5769SS1 SF49876, 5769SS1 SF49877

OS/2 software requirementsBefore you can install an OS/2 adapter on a host, OS/2 Warp 4.0 or 4.5 must berunning on the host. The TME endpoint version of the OS/2 adapter must beinstalled with the Adapter Configuration Facility.


http://www.ibm.com

Installing an HP OpenView adapter on a managed nodeYou can install an HP OpenView adapter from the Tivoli desktop or from thecommand line.

Notes:

1. You can also install the HP OpenView adapter using the Tivoli EnterpriseConsole installation wizard; for detailed information, see the Tivoli EnterpriseConsole Installation Guide.

2. To successfully send events to the event server from a managed node, the HPOpenView adapter requires an administrator login ID with a resource role ofuser for the EventServer resource.

3. To install, upgrade, or uninstall components in a Tivoli environment, you mustbe a Tivoli root Administrator with all available roles. For more information onhow to become a Tivoli root Administrator, see the Tivoli Management FrameworkUser’s Guide.

Installing from the Tivoli desktopComplete the following steps to install an HP OpenView adapter on a managednode from the Tivoli desktop provided with the Tivoli Management Frameworkproduct services:1. From the Desktop menu, click Install —> Install Product.2. Click Select Media.3. Select the location where the Tivoli Enterprise Console media is located (for

example, the path where the installation image is located).4. Click Set Media & Close. A list of Tivoli Enterprise Console components

appears.5. In the Select Product to Install scrolling list, select the HP OpenView adapter.6. Click the managed nodes where you want to install the components.7. Click Install & Close.

Installing from the command lineYou can use the winstall command to install an HP OpenView adapter on amanaged node from the command line, as follows:winstall -c /cdmount -i HPOV.IND node

where:

-c /cdmountSpecifies the path to the installation image.

HPOV.INDSpecifies the product index file for the HP OpenView adapter component.

node Indicates the managed node on which the component is to be installed.

Installing an adapter on an endpointThe endpoint adapters (OS/2, SNMP, UNIX logfile, and Windows) are packagedwith the Adapter Configuration Facility. You must use the Adapter ConfigurationFacility to install these adapters on endpoints. The endpoint adapters are installedby creating an adapter configuration profile that adds entries for the adapters you

Chapter 2. Installing adapters 33

want to install, and distributing the adapter configuration profile to a list ofendpoint subscribers, similar in process to any profile distribution using the Tivolidesktop.

Note: Ensure that, for the endpoint adapters, you only distribute their profiles tothe endpoint label.

The Adapter Configuration Facility must be installed on the same managed node asthe endpoint gateway so that adapters and adapter-related files can be distributedto the endpoints. Therefore, it is important to install the Adapter ConfigurationFacility on every managed node that is configured as an endpoint gatewaythroughout a Tivoli region. The steps in this section assume you have the AdapterConfiguration Facility installed on the managed nodes providing the endpointgateway service for the endpoints where you want to install an adapter.

Follow these general steps to install an adapter on an endpoint:1. An adapter configuration profile must be a managed resource type. Set ACP as

a managed resource in the Set Managed Resources window for the policyregion where you will be installing the adapters.

2. Create a profile manager, specifying the Dataless Endpoint Mode option.3. Within the profile manager:

a. Create a profile.b. Name the profile and specify ACP as the profile type.c. In the adapter configuration profile, add an entry for each adapter to install

on the endpoints.

Note: Some logfile adapters are operating system-specific (for example,tecad_logfile_hpux10 and tecad_logfile_solaris2). If your endpointsare running on multiple operating systems, for example, somerunning on HP-UX 11 and some running in a Solaris OperatingEnvironment (hereinafter referred to as Solaris), and you want tomonitor the system log files for the endpoints, you must create anadapter configuration profile for each operating system and distributethem to the appropriate endpoints.

4. After selecting the adapter to install from the Add Adapter Configurationwindow, you are placed in edit mode so that you can change default settingsfor the adapter if you want. If you are going to install an additional adapterusing this adapter configuration profile, add another entry for the additionaladapter and repeat this step.

5. Create endpoint subscribers for the adapter configuration profile.6. Distribute the adapter configuration profile to the subscribing endpoints. The

adapters defined in the adapter configuration profile will be installed andstarted on the subscribing endpoints.

Installing a non-TME adapterThe following sections describe how to install a non–TME adapter using thecommand line. For CD installation, ensure that the IBM Tivoli Enterprise ConsoleNon-TME Installations CD has been mounted on the /cdrom (or applicable)directory or drive.

Note: BAROC files and rule bases are installed as part of the event serverinstallation procedure. They are not covered in these sections.


Installing on UNIX operating systemsTo install a non-TME adapter on a UNIX system, use the following steps:1. Create an installation directory (for example, /usr/tecad).

Note: If you have previously installed other adapters, you should install alladapters in the same directory. The following example uses /usr/tecadas the installation directory.

2. Change directories to the installation directory you created and make thatdirectory the default directory.

3. Untar the non-TME adapter from the CD using the following command:tar -xvf /PLATFORM/FILENAME.TAR

where:

PLATFORMThe operating system of the host specified in uppercase letters. Somevalid values are AIX4-R1, HPUX10, LINUX-IX86, LINUX-S390, andSOLARIS2.

FILENAMEThe adapter file name, which can be one of the following values:

Adapter FILENAME

HP OpenView HPOV

SNMP SNMP

UNIX logfile LOGFILE

4. Ensure that you are logged in as the root user and use the following steps toconfigure the adapter so that it starts along with the host. This command runsthe installation script for an adapter.a. Change directories to /usr/tecad/bin and set the $TECADHOME

environment variable to /usr/tecad.

Note: If you specify an alternate location to install the binaries, you mustmanually set the $TECADHOME variable as shown in step 4a andmanually copy the binary files into the same directory you specifiedin the Install Directory field during the installation process.

b. Run the following command:tecad_filename.cfg[ID]

where ID is an optional identifier for the adapter and filename can have thefollowing values:

Adapter filename

HP OpenView hpov

SNMP snmp

UNIX logfile logfile

c. Answer the questions asked by the script. This command also automaticallystarts the adapter on the host.


Note: The HP OpenView installation script registers the HP OpenViewadapter with HP OpenView local registration file. The HP OpenViewadapter automatically starts when the other HP OpenView daemonsare started.

5. Ensure that the configuration file for your adapter is properly configured foryour operational environment. The configuration options are described inChapter 10, “UNIX logfile adapter”, on page 155.

Installing on Windows operating systemsTo install a non-TME adapter on Windows system, use the following steps:1. Run the following command:

/W32_IX86/install_dir/setup.exe

where install_dir is the installation directory on the CD and can be one of thefollowing values:

Adapter install_dir

HP OpenView InstallHPOV

SNMP InstallSNMP

Windows InstallWin

Note: You can use InstallShield silent install feature to install the adapter in thebackground without user input. To do so, edit the InstallWin/SETUP.ISS(Windows) response file, for example, which provides installationinformation that the installer would typically query a user for during theinstall.

First, edit the following lines in the SETUP.ISS file as necessary:

Default Setting Change

[AskDestPath-0]szPath=C:\TECWIN (Windows2000)

TECWIN to the destination directory, ifnecessary

[AskText-0]szText=localhost

localhost to the name of the host whereevents are to be delivered

[AskText-1]szText=0

0 to the port number where the server hasbeen configured to listen for events

Then run setup /s from the InstallWin (Windows) directory to silentlyinstall the adapter. For more information on InstallShield and theSETUP.ISS file, go to:

http://www.installshield.com2. Make sure that the configuration file for your adapter is properly configured

for your operational environment. The configuration options are described inChapter 11, “Windows event log adapter”, on page 167.

Note: The non-TME adapters dynamically resolve the protocol address for theevent server if the protocol address changed after the adapter started. Inthis instance, you are not required to restart the adapter.


Installing on the OS/2 operating systemTo install a non-TME adapter on an OS/2 system, use the following steps:1. Create an installation directory (for example, c:\tecad). If you have previously

installed other adapters, you should install all adapters in the same directory.This example procedure uses c:\tecad as the installation directory.

2. Change directories to the installation directory.3. Run the following command from an OS/2 window:

drive:\install.exe

4. In the Instructions window, select Continue.5. In the Install window, select OK.6. In the Installed-directories window, specify a different installation directory for

the adapter-related files if the default is not satisfactory. If the specifieddirectory does not exist, it is created.

7. Select Install.8. In the Tivoli TEC Install Options window, type information for the following

fields:

TEC Server NameThe name of the event server.

TEC Server PortThe port number for the event server.

Options Optional command-line parameters for the tecadini.shprogram; for example, you could specify various debuggingparameters.

9. Select OK.The adapter is installed and automatically started. You do not need to rebootthe system to start it. The CONFIG.SYS file is modified to automatically startthe adapter whenever the system is rebooted.

10. Make sure that the configuration file for your adapter is properly configuredfor your operational environment. The configuration options are described inChapter 8, “OS/2 adapter”, on page 139.

Note: The non-TME adapters dynamically resolve the protocol address for theevent server if the protocol address changed after the adapter started. In thisinstance, you are not required to restart the adapter.

Installing AS/400 adaptersYou can install the AS/400 adapters from the Tivoli desktop or from the IBM TivoliEnterprise Console Non-TME Installations CD.

Installing from CDThe AS/400 adapters are shipped on the IBM Tivoli Enterprise Console Non-TMEInstallations CD in the form of AS/400 save files (*SAVF). To install these files onan AS/400, use the following steps:1. Create save files on the AS/400 system with the following commands:

CRTSAVF FILE(QUSRSYS/ATMETEC)

CRTSAVF FILE(QUSRSYS/filename)


where filename is one of the following files:

Adapter filename

Alert ATMETEC2

Message ATMETEC1

2. FTP the ATMETEC and filename files in the AS400 directory on the CD to theQUSRSYS library on the AS/400 system, using the following commands:ftp AS400.my.domain

bin

put /AS400/ATMETEC QUSRSYS/ATMETEC

put /AS400/filename QUSRSYS/filename

quit

where filename is one of the following files:

Adapter filename

Alert ATMETEC2

Message ATMETEC1

3. On the AS/400 system, install the adapter using the following AS/400commands:RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) \OPTION(*BASE) SAVF(QUSRSYS/ATMETEC)

RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) \

OPTION(x) SAVF(QUSRSYS/filename)

where x and filename are one of the following values:

Adapter x filename

Alert 2 ATMETEC2

Message 1 ATMETEC1

Installing from CD on an AS/400 SystemIf the AS/400 system is running the OS/400 V3R6M0 operating system, theAS/400 adapters can be installed directly onto the AS/400 system by loading theIBM Tivoli Enterprise Console Non-TME Installations CD onto the AS/400CD-ROM drive and issuing the following commands:RSTLICPGM LICPGM(1TMETEC) DEV(optical device) OPTION(*BASE)

RSTLICPGM LICPGM(1TMETEC) DEV(optical device) OPTION(x)

where x is one of the following values:

Adapter x

Alert 2

Message 1


Installing with English as a secondary languageIf your AS/400 system has a primary language other than English (2924), and youhave the English secondary language installed on your system, you can install theAS/400 adapters.

To install the AS/400 adapter into the English secondary language library, use thefollowing commands:RSTLICPGM LICPGM(1TMETEC) DEV(device) OPTION(*BASE) LNG(2924)

RSTLICPGM LICPGM(1TMETEC) DEV(device) OPTION(x) LNG(2924)


Adapter x

Alert 2

Message 1

Note: The secondary language library QTECA02924 is automatically added to yourlibrary list so that you can access the AS/400 adapter commands.

Installing the NetWare logfile adapterUse the following steps to install the NetWare logfile adapter (non-TME adapter)from a Windows NetWare client.1. Log in to the NetWare server on which the adapter will be installed from a

Windows client system. To perform the installation, you must have write accessto the root of the SYS volume on the server. Typically, the installation should becarried out by User Administration. The installation must be done from theWindows system from which you logged into the NetWare system.

2. Insert the IBM Tivoli Enterprise Console Non-TME Installations CD into theCD-ROM drive, and run the following command from a Windows system:drive:\NW4\InstallNW4\setup.exe

You can also run this command by double-clicking on the setup.exe program inthe \NW4\InstallNW4 directory.

3. At the Welcome window, select Next.4. Enter the host name of the NetWare server on which to install the adapter.5. Select Next.6. A dialog box presents the option of automatically editing the AUTOEXEC.NCF

file to start the adapter each time the NetWare server boots. Select either Yes orNo. If you select Yes, specify the directory in which the AUTOEXEC.NCF fileresides at the next window.The setup program installs the necessary components.

7. Enter the TCP/IP host name and port number of the Tivoli Enterprise Consoleserver to which the adapter is to send events. The port number is needed onlyif the Tivoli Enterprise Console server is running on a Windows system.

8. Select OK.9. When the installation process is complete, select OK.


Upgrading HP OpenView adaptersWhen you upgrade a previous release of the HP OpenView adapter component ofthe Tivoli Enterprise Console product, you install the upgrade image for theadapter component. You can upgrade the adapter component using either theSoftware Installation Service, the Tivoli desktop, or the command line.You can alsoupgrade the HP OpenView adapter using the Tivoli Enterprise Console installationwizard; for detailed information, see the Tivoli Enterprise Console Installation Guide.

Note: To install, upgrade, or uninstall components in a Tivoli environment, youmust be a Tivoli root Administrator with all available roles. For moreinformation on how to become a Tivoli root Administrator, see the TivoliManagement Framework User’s Guide.

Preparing to upgrade adaptersAfter installing the Tivoli Enterprise Console product, but before upgrading the HPOpenView adapter, you must follow these steps:1. Back up the affected object databases; see “Backing up object databases”.2. Ensure that you are running the appropriate version of the Tivoli Management

Framework product on all hosts for which you are upgrading adapters.3. Ensure that all Tivoli Enterprise Console product considerations are fulfilled.

Backing up object databasesBefore installing, upgrading, or uninstalling any Tivoli Enterprise Consolecomponents, you should back up the Tivoli object databases for all affectedcomputers in your Tivoli region. This backup enables you to return to a knownworking state. Having a backup is useful if you encounter problems whileinstalling the Tivoli Enterprise Console product.

From the Tivoli desktop, select Desktop —> Backup to perform a backup of theobject database for the Tivoli region server and managed nodes. You can also usethe wbkupdb command.

For example, to back up the object database for all managed nodes in a Tivoliregion, to the user-defined file /usr/backups/TMR1.bk, run the followingcommand:wbkupdb -d /usr/backups/TMR1.bk

For more information on this command, see the Tivoli Management FrameworkReference Manual.

Upgrading adapters from the Tivoli desktopYou can upgrade the HP OpenView adapter component of the Tivoli EnterpriseConsole product from the Tivoli desktop as follows:1. On the Desktop menu, click Install —>Install Patch.2. Click Select Media.3. Select the location where the Tivoli Enterprise Console media is located (for

example, the path where the upgrade image is located).4. Click Set Media & Close. A list of components that are available for upgrading

appears.5. Select the HP OpenView adapter component.


6. Select the managed nodes where you want to upgrade the HP OpenViewadapter.

7. Click Install & Close.

Upgrading adapters from the command lineYou can also upgrade the HP OpenView adapter component of the TivoliEnterprise Console product from the command line using the wpatch command asfollows:wpatch -c /cdmount -i HPOV_UPG node

where:

-c /cdmountSpecifies the path to the upgrade image.

HPOV_UPGSpecifies the product index file for the HP OpenView adapter component.

node Indicates the managed node on which the component is to be upgraded.

Upgrading adapters using the Software Installation ServiceYou can upgrade any Tivoli product or Tivoli Enterprise Console adaptercomponent using the Tivoli Software Installation Service. See the IBM TivoliEnterprise Console Installation Guide for more information. You must first import theupgrade images into the installation repository, and select which systems will beupgraded with which components.

Uninstalling adaptersAlthough you can install selected adapters through the standard Tivoli installationmechanisms, such as the Tivoli desktop, command line, and the SoftwareInstallation Service, you must uninstall them using different methods. Thefollowing sections describe how to uninstall the different kinds of adapters andhow to remove Tivoli Enterprise Console Version 3.8 enhanced adapters from theTivoli environment.

Uninstalling an HP OpenView adapter on a managed nodeHP OpenView adapters have an uninstall script that you can run from thecommand line on the system where the adapter is installed. From the managednode, run this remove script to uninstall the adapter:$BINDIR/TME/TEC/adapters/bin/tecad-remove-hpov.sh

Uninstalling an adapter on an endpointEndpoint adapters are uninstalled by deleting entries for them in the adapterconfiguration profile and then distributing that profile to the appropriate targets.You must use the Adapter Configuration Facility to uninstall a TME adapter on anendpoint. If you remove an endpoint manually, subsequent distributions of theadapter configuration profile might not reinstall the adapter. For step-by-stepprocedures for using the Adapter Configuration Facility, see Chapter 3, “AdapterConfiguration Facility”, on page 45. The following steps describe the general tasksfor uninstalling a TME adapter.1. From the adapter configuration profile that was used to install the adapter (or

an exact copy), delete the entry for the adapter you want to uninstall from theendpoint.


2. Distribute the adapter configuration profile to the endpoint. For moreinformation about distributing the adapter configuration profile to an endpoint,see “Distributing an adapter configuration profile” on page 56.

Uninstalling a non-TME adapterThe following sections describe how to uninstall a non-TME adapter on UNIX,Windows, and OS/2 systems.

Uninstalling on UNIX operating systemsThe non-TME adapters listed in the following table have an uninstall script youcan run from the command line on the system where the adapter is installed.

For other non-TME adapters on UNIX systems that do not currently have anuninstall script, after stopping the adapter you can delete the files that wererestored from the tar file during the installation process.

Adapter Script

Logfile (generic) install_path/bin/tecad-remove-logfile.sh

OpenView install_path/bin/tecad-remove-hpov.sh

SNMP install_path/bin/tecad-remove-snmp.sh

Uninstalling on Windows operating systemsTo uninstall an adapter on a Windows system, run the Uninstall Shield programfrom the Tivoli program group.

Uninstalling on the OS/2 operating systemTo uninstall an adapter on an OS/2 system, use the following steps:1. If the system has not been rebooted since the adapter has been installed, go to

the install_dir\os2-ix86\bin directory; otherwise, the uninstall procedure can berun from any directory.

2. From an OS/2 window, run the following command:tec_uninstal

3. From the Installation and Maintenance window, select the adapter from the listof installed products.

4. From the Action menu, select Delete.5. From the Delete confirmation window, select Delete.6. From the Installation and Maintenance window, select OK.7. From the File menu in the Installation and Maintenance window, select Exit.

Most of the adapter-related files are now deleted. Some are deleted upon reboot ofthe system. There might still be some that were not deleted upon reboot of thesystem. This is due to file operations performed when installing the adapter to theOS/2 system. Check for the following files on the OS/2 system and manuallydelete them if necessary to complete the uninstall procedure:v install_directory\os2-ix86\etc\tecados2.barocv install_directory\os2-ix86\etc\tecados2.confv install_directory\os2-ix86\bin\gen_message.exev install_directory\os2-ix86\bin\tec_uninstal.cmd


Uninstalling an AS/400 adapterPerform the following steps to uninstall an AS/400 adapter:1. On the AS/400 system, remove the adapter using the AS/400 command:

DLTLICPGM LICPGM(1TMETEC) OPTION(x)


Adapter x

Alert 2

Message 1

The AS/400 adapter is deleted. If no other adapters are installed on the AS/400system, you can also use the following command:DLTLICPGM LICPGM(1TMETEC) OPTION(*ALL) RLS(*ALL)

Note: You might have to pull the QTECA02924 library from your library listbefore the delete command deletes the base product.

2. Configuration files were copied into QUSRSYS during the installation of theadapter. If you no longer need them, you need to manually delete them byusing the following commands:Alert adapter:DLTF FILE(QUSRSYS/CFG_ALERT)

Message adapter:DLTF FILE(QUSRSYS/CFG_MSG)

3. Configuration files were copied into the IFS directory/QIBM/UserData/Tivoli/TEC/directory_name. Remove the directorydirectory_name and all of its subdirectories. directory_name can be one of thefollowing values:

Adapter directory_name

Alert ALERT

Message MSGQ

Alert and Message tis

4. If there are no other adapters installed on the system, then delete the directory/QIBM/UserData/Tivoli/TEC and all of its subdirectories.

Uninstalling a NetWare logfile adapterTo uninstall a NetWare logfile adapter, complete the following steps:1. Log in to the NetWare server from the same client you used for the installation.2. From the Add/Remove Programs window in the Control Panel, select the

Tivoli Logfile Adapter for NetWare option and click the Add/Remove button.3. If you selected the automatic startup option for the adapter, remove the

one-line entry that starts the adapter from the AUTOEXEC.NCF file.


Removing Version 3.8 enhanced adapters from the Tivolienvironment

To uninstall a Tivoli Enterprise Console 3.8 enhanced adapter, run this script fromthe managed node:/TME/TEC/tecad-enh-remove.sh

This script removes:v All enh directories and filesv The enh objects from the oserv databasev Any profiles that were using the enhanced adapter, if any remain


Chapter 3. Adapter Configuration Facility

The Adapter Configuration Facility provides a graphical user interface that you canuse to configure, customize, and distribute event adapters in a Tivoli environment.Rather than editing the actual adapter configuration files, you can create adapterconfiguration profiles. You can then create a record for each adapter and configureand customize the behavior for each adapter. Next, you can distribute thecustomized configuration files and executable files to specified endpoints. TheAdapter Configuration Facility is required to configure and install TME adapterson endpoints.

Using adapter configuration profilesYou can distribute an adapter configuration profile to any Tivoli managed node orendpoint. However, depending on the type of adapter being configured, aparticular set of adapter configuration files or other adapter details might applyonly to certain operating system types. For example, a configuration record for athird-party adapter that relays events from a database server can be distributed toany host, and the configuration files are written according to the data in the record.However, if the adapter itself is constructed such that event classes generated fromAIX operating systems differ from those generated on Solaris operating systems,the filter definitions in the record might not be effective if deposited on a systemthey were not intended for.

The simplest way to handle this issue is to maintain separate profile subscriptionlists and separate profiles for configuration records of such adapters. This keepsthe distinction between endpoints visible and reduces the chance for incorrectdistribution. Among Tivoli-supplied adapters, the logfile adapter is one with clearsystem dependencies, because log files that record similar information might differsignificantly in format from operating system to operating system. For this type ofconfiguration and similar adapters, we recommend management through separateprofiles.

Note: The job of tracking separate profiles can be made more convenient bygrouping related profiles together in simple collections. The hierarchy ofpolicy regions and profile managers can then be bypassed when navigatingfrom profile to profile on the desktop.

Adapter Configuration Facility rolesThe following Tivoli authorization roles are associated with the AdapterConfiguration Facility activities:

ACF_glopolUsed by an administrator to set the global adapter policy.

ACF_polmodUsed by an administrator to edit profile policy and create new profiles.

ACF_rwdistUsed by an administrator to edit and distribute adapter configurationprofiles.


ACF_readonlyUsed by an administrator to view adapter configuration profiles, but theadministrator cannot create, edit, or distribute the adapter configurationprofiles.

You can set these Tivoli management region and resource roles for anadministrator from the Tivoli Management Framework Administrators dialog box.

Setting adapter configuration profiles as managed resourcesEach policy region maintains a list of managed resource types that are valid ordefined for that specific policy region. You must add adapter configuration profilesas managed resources before you can use a policy region to manage adapterconfiguration profiles.

Note: This procedure is performed only once per policy region.

The following table lists the context and authorization role required to perform thistask.

Activity Context Required Role

Set policy region managedresources for an adapterconfiguration profile

Policy region senior

You can perform this task from the desktop or from the command line.

Setting adapter configuration profiles as managed resourcesfrom the Tivoli desktop

1. Right-click the policy region icon and select Managed Resources from thecontext menu. The Adapter Configuration Facility displays the Set ManagedResources dialog box.

2. Select the ACP managed resource from the Available Resources scrolling listand click the left arrow button to move the selected managed resources to theCurrent Resources scrolling list.

3. Click the Set & Close button to add the directory profile as a resource andclose the dialog box.

Setting adapter configuration profiles as managed resourcesfrom the command line

For more information about using the command line to add managed resources fora policy region, see the Tivoli Management Framework Reference Manual entry for thewsetpr command.

Creating an adapter configuration profileWhen you create an adapter configuration profile, the initial profile is empty; itdoes not contain any records. It does, however, contain a set of default andvalidation policies.




Create an adapterconfiguration profile

Profile manager senior

You can create a directory profile from the desktop or the command line.

Creating an adapter configuration profile from the Tivolidesktop

Perform the following steps to create an adapter configuration profile from theTivoli desktop. You must have previously created the policy region and profilemanager in which the directory profile is to reside. For more information aboutpolicy regions and profile managers, see the Tivoli Management Framework User’sGuide.

Note: If you have not already assigned managed resource roles to the policyregion that is to contain the profile you want to create, assign these rolesnow. For more information, see “Setting adapter configuration profiles asmanaged resources” on page 46.

1. Double-click the icon for the policy region in which you want to manage yourprofile. This opens the Policy Region window.

2. Create a profile manager by selecting Create —> Profile Manager from theCreate pull-down menu. The Create Profile Manager dialog displays.

3. Type the profile manager name in the Name/Icon Label text box.

Note: You must select the Dataless Endpoint Mode check box if you want tomanage any endpoints.

4. Double-click a profile manager icon to display the Profile Manager window.5. Select Profile from the Create pull-down menu. The Adapter Configuration

Facility displays the Create Profile dialog box.6. Enter a name for the profile in the Name/Icon Label text box. Each adapter

configuration profile must have a unique name within a Tivoli region.7. Select the ACP option from the Type scrolling list. If you have installed other

Tivoli products, other options might be displayed in the Type scrolling list.8. Click the Create & Close button to create the profile and return to the Profile

Manager window. The Adapter Configuration Facility creates the adapterconfiguration profile and displays the profile icon in the Profile Managerwindow.

Creating an adapter configuration profile from the commandline

The following example creates an adapter configuration profile from the commandline interface:wcrtprf “@ProfileManager:ACPM1” ACP Profile1

where:

ACPM1Specifies the name of the profile manager. You can use the wlookupcommand to return a list of available profile managers.

ACP Specifies the type of profile being created.

Chapter 3. Adapter Configuration Facility 47

Profile1Specifies the name of the new adapter configuration profile.

For more information about the wcrtprf and wlookup commands, see the TivoliManagement Framework Reference Manual.

Cloning an adapter configuration profileWhen you clone an adapter configuration profile, you create a new profile thatduplicates the default and validation policies associated with the original profile.However, it does not include the adapter configuration records of the originalprofile. The Adapter Configuration Facility does not permit two profiles of thesame type in the same profile manager to contain the same records.



Clone an adapterconfiguration profile


You can clone an adapter configuration profile from the desktop or the commandline.

Cloning an adapter configuration profile from the Tivolidesktop

Perform the following steps to clone an adapter configuration profile from theTivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile

Manager window.2. Click the icon for the adapter configuration profile you want to clone.3. Select the Profiles:Clone option from the Edit menu in the Profile Manager

window to copy the original profile and display the Clone Profile dialog box.4. Enter a new name for the profile in the Name/Icon Label text box. Each

adapter configuration profile must have a unique name within a Tivoli region.In this example dialog, the Name/Icon Label is Profile2.

5. Select the profile to clone from the Clone to Profile Manager scrolling list.6. Click the Clone & Close button to create the new profile and return to the

Profile Manager window. The Profile2 adapter configuration profile icondisplays in the Profile Manager window.

Cloning an adapter configuration profile from the commandline

The following example command clones an adapter configuration profile from thecommand line:wcrtprf -c @ACP:Profile1 @ACPM1:ACP Profile3

where:

-c @ACP:Profile1Specifies the Profile1 adapter configuration profile as the source profile thatis to be cloned to create the new profile.


ACPM1Specifies the name of the profile manager.

ACP Specifies the type of profile being cloned.

Profile3Specifies the name of the new adapter configuration profile.

For more information about the wcrtprf command, see to the Tivoli ManagementFramework Reference Manual.

Deleting an adapter configuration profileWhen you delete an adapter configuration profile, you remove the profile and allits records from the profile manager. This action also removes the associated copyof the profile for each subscriber. You can delete only a top-level profile. Youcannot delete a descendant of a profile.

Note: Deleting a profile does not delete information in system files.



Delete an adapterconfiguration profile


Deleting an adapter configuration profile from the Tivolidesktop

Perform the following steps to delete an adapter configuration profile from theTivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile

Manager window.2. Select the icon for the adapter configuration profile you want to delete.3. Select the Profiles:Delete option from the Edit menu in the Profile Manager

window to display the Delete Profiles dialog box.

Note: You can click the Cancel button to stop the operation.4. Click the Delete button to delete the profile and remove the icon from the

Profile Manager window.

Deleting an adapter configuration profile from the commandline

The following example command deletes an adapter configuration profile from thecommand line:wdel @ACP:Profile2

where:

@ACP:Profile2Specifies the Profile2 adapter configuration profile.

For more information about the wdel command, see the Tivoli ManagementFramework Reference Manual.


Setting adapter configuration profile defaultsYou can control the default settings that an adapter configuration profile useswhen the Adapter Configuration Facility distributes a profile. The default settingsdetermine which distribution settings are initially selected. An administrator withthe proper authorization role can override the default settings. Defaults are set ona per-profile basis. The default options for each profile can be different from thoseof other profiles. You can perform the following modifications to a profile:v Rename an adapter configuration profilev Set distribution defaultsv Modify an adapter configuration profile default policyv Modify an adapter configuration profile default validation policy

Renaming a profileYou can rename an adapter configuration profile only from the desktop.



Rename an adapterconfiguration profile

Adapter configuration profile admin

Perform the following steps to rename a profile from the Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile

Manager window.2. Double-click the adapter configuration profile icon to display the Adapter

Configuration Profile window.3. Enter the new name for the profile.4. Click the Set New Name button.

Getting a new copy of an adapter configuration profileYou can get a new copy of a profile from the profile manager that is one leveldown in the subscription hierarchy. This operation is making request to thesubscribed-to profile manager for distribution to a single subscriber.



Get a new copy of an adapterconfiguration profile

Adapter configuration profile senior

Getting a new copy of an adapter configuration profile fromthe Tivoli desktop

Perform the following steps to retrieve an adapter configuration profile copy fromanother profile from the Tivoli desktop:1. From a profile manager, double-click an icon for a profile manager subscriber

to display the Profile Manager window.


2. Double-click an adapter configuration profile icon to display the AdapterConfiguration Profile window.

3. Select the Get New Copy option from the Profile menu. The AdapterConfiguration Facility displays the Get Subscription Copy dialog box.

4. Click the Preserve profile record modifications made in profile manager radiobutton to retrieve the profile, but keep the values in the current profile. Use thisoption when your profile has differences you want to keep after retrieving thenew profile copy.Click the Make profile records an EXACT COPY of the retrieved profilerecords radio button to retrieve the profile and overwrite any values in thecurrent profile. Use this option when you do not want to keep the localchanges to the current profile.

5. To retrieve the profile at a later time, click the Schedule button to display theAdd Scheduled Job dialog box.For more information about the Tivoli scheduling facility, see the TivoliManagement Framework User’s Guide.

6. Click the Get Copy & Close button to immediately retrieve copies of theprofile records into the current profile and then close the dialog box.

Getting a new copy of an adapter configuration profile fromthe command line

The following example command retrieves a copy of a profile from another profilemanager from the command line:wgetprf -l maintain @ProfileManager:ACPsub

where:

–l maintainRetains any local modifications in subscribers’ copies of the profile.

ACPsubSpecifies the name of the subscriber to receive new profile copy.

For information about using the command line to retrieve profile information fromanother profile, see the Tivoli Management Framework Reference Manual entry for thewgetprf command.

Setting adapter configuration profile distribution defaultsYou can set the adapter configuration profile distribution file defaults for a profile.



Set distribution defaults Adapterconfiguration profile

admin

Perform the following steps to set distribution defaults for a profile from the Tivolidesktop:1. From a policy region, double-click a profile manager icon to display the Profile

Manager window.2. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.


3. Select Distribution Defaults from the Profile menu. The AdapterConfiguration Facility displays the Set Distribution Defaults dialog box.

4. Select one of the Distribute To options based on the following descriptions:v Next level of subscribers

Distributes the profile only to the subscribers named in the Distribute ToThese Subscribers scrolling list of the Distribute Profile dialog box.This selection distributes the profile only to the subscribers of the profilemanager. It does not distribute to lower-level subscribers. If a profilemanager with subscribers resides at the next-lower level, you might need toperform the distribution process from profile managers at more than onelevel to reach all the profile endpoints.

Note: The Adapter Configuration Facility does not update the files on anendpoint if you perform a single-level distribution from a profilemanager to an endpoint. To update the data files on the endpoints,you must either distribute the adapter configuration profile to theendpoint itself, or distribute the profile to all levels of subscribers.

v All levels of subscribers

Distributes the profile to all subscribers and all subscribers’ subscribers.Select this option if you want to distribute a profile in which your managednode is the only subscriber.

5. Select one of the Distribution Will options based on the following descriptions:v Preserve modifications in subscribers’ copy of the profile

Keeps entries that are in the subscribers’ profile, even though they are not inthe profile being distributed.

v Make subscriber’s profile an EXACT COPY of this profile

Overwrites the profile for the subscriber with an exact copy of the profilebeing distributed.

6. Click the Set & Close button to set the distribution defaults and dismiss thedialog box.

Modifying an adapter configuration profile default policyDefault policies define the default values to be used when an adapterconfiguration profile record is added or edited. An adapter configuration profilecontains a default policy for each attribute of an adapter configuration record.Although default policy can be defined for each attribute, the AdapterConfiguration Facility does not necessarily assign default values for all attributes.

You can create a default policy if you want a different attribute to always have adefault value. The three types of default policies are as follows:

Script Runs shell scripts. You can use only attributes as arguments for a script.

ConstantSets an attribute to a specified value.

None Indicates the attribute does not have a default setting.

If you define a default policy for an attribute to be of type Script, the AdapterConfiguration Facility ensures all the arguments for the script are defined before itruns the script.


If you add or edit a default policy script, you must make sure that all thearguments in that script have a default policy defined. If you create a situation inwhich two arguments require values from each other, the default policy fails, andyou cannot add new records.



Modify an adapterconfiguration profile defaultpolicy


You can set default policy from the desktop or the command line.

Modifying an adapter configuration profile default policy fromthe Tivoli desktop

Perform the following steps to set default policy in an adapter configuration profilefrom the Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile


Configuration Profile window.3. Select the Default Policies option from the Edit menu to display the Edit

Default Policies dialog box.4. Select an attribute from the Attributes scrolling list.5. Verify that the Subscribers can edit setting is correct for this attribute.

v Select No to prevent subscribers from editing their local copy of this defaultpolicy.

v Select Yes to allow subscribers to edit their local copy of this default policy.(This option is the default.)

6. Select a type from the Default Type drop-down list. You can choose None,Constant, or Script.

If you select None, there is no default policy.If you select Constant, the Edit Default Policies dialog displays a Value textbox, as shown in the previous dialog box. You must type a constant value inthe Value text box.If you select Script as the Default Type, the Edit Script Arguments and EditScript Body buttons are displayed as shown in the following dialog box.Complete the following steps:a. Click the Edit Script Arguments button to display the Policy Script

Arguments dialog box.b. Select the record attributes from the Attributes scrolling list that you want

to use as script arguments.c. Click the right arrow button to move the attributes into the Script

Arguments scrolling list.You can change the order in which an argument is passed by selecting theargument and clicking the up or down arrow button to move the argumentto a particular position.


d. Click the Set & Close button to add the new arguments and return to theEdit Default Policies dialog box.

Complete the following steps:a. Click the Edit Script Body button in the Edit Default Policies dialog to

display the Edit Policy Script dialog box.b. Enter or edit the body of the script.c. Click the Set & Close button to save the script to the database and return to

the Edit Default Policies dialog box.Repeat this procedure for each of the record attributes that you want to edit.

Modifying an adapter configuration profile default policy fromthe command line

The following example command sets a constant-valued default policy:wputpol -d -c STATIC @ACP:Profile1 comment

where:

–d Specifies the default policy is being set.

–c STATICSets the policy to the constant STATIC.


commentSpecifies the attribute that is to have the new policy.

For more information about the wputpol command, see the Tivoli ManagementFramework Reference Manual.

Modifying an adapter configuration profile validation policyYou can set validation policy for one or more of the attributes in an adapterconfiguration profile. You can also enable or disable validation for all attributes.

Validation runs when you populate or distribute a profile, add a new entry, orexplicitly request validation. The Adapter Configuration Facility uses validation toverify that a profile entry is compliant with established policy and prevents youfrom creating an entry that does not meet specific criteria. Validation policy can beenabled or disabled on a per-attribute basis within a profile. Therefore, it ispossible to disable validation on one or more attributes and add new entries thatare not subject to the validation check.



Modify an adapterconfiguration profilevalidation policy


You can set or edit validation policy from the desktop or the command line.


Modifying an adapter configuration profile validation policyfrom the Tivoli desktop

Perform the following steps to modify an adapter configuration profile validationpolicy from the Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile


Configuration Profile window.3. Select the Validation Policies option from the Edit menu to display the Edit

Validation Policies dialog box.4. If you want to disable validation for all attributes, click the Disabled radio

button. Otherwise, make sure the Enabled radio button is selected.5. Select an attribute from the Attributes scrolling list.6. Verify that the Subscribers can edit setting is correct for this attribute.

v Select No to prevent subscribers from editing their local copy of thisvalidation policy.

v Select Yes to allow subscribers to edit their local copy of this validationpolicy. (This option is the default.)

7. Select a type from the Default Type drop-down list. You can choose None,Constant, Script, or Regular Expression.If you select None, there is no validation policy.If you select Constant or Regular Expression, the Edit Default Policies dialogdisplays a Value text box. Enter a constant value in the Value text box. Whenconstant policy is used, validation passes only if the attribute value matches theconstant provided.If you select Script, the Edit Default Policies dialog displays the Edit ScriptArguments and Edit Script Body buttons.Perform the following steps to determine the order in which the scriptarguments are displayed from the Tivoli desktop:a. Click the Edit Script Arguments button on the Edit Default Policies dialog

to display the Policy Script Arguments dialog box. Use this dialog todetermine the order of the script arguments.

b. Select the record attributes from the Attributes scrolling list that you wantto use as script arguments.

c. Click the right arrow button to move the attributes into the ScriptArguments scrolling list.You can change the order in which an argument is called by selecting theargument and clicking on the up or down arrow button to move theargument to a particular position.

d. Click the Set & Close button to add the new arguments and return to theEdit Default Policies dialog box.

e. Click the Edit Script Body button in the Edit Default Policies dialog todisplay the Edit Policy Script dialog box.

f. Enter or edit the body of the script.g. Click the Set & Close button to save the script to the database and return to

the Edit Default Policies dialog box.

Repeat this procedure for each of the record attributes.


Modifying an adapter configuration profile validation policyfrom the command line

The following example command sets validation policy to none:wputpol -v -n @ACP:Profile1 comment

where:

–v Specifies the validation policy is being set.

–n Sets the policy to none.


commentSpecifies the attribute that is to have the new policy.

For more information about the wputpol command, see the Tivoli ManagementFramework Reference Manual.

Distributing an adapter configuration profileTo easily configure and customize multiple event adapters, you can distribute anadapter configuration profile to its subscribers.



Distribute an adapterconfiguration profile


You can distribute an adapter configuration profile from the desktop or thecommand line.

Distributing an adapter configuration profile from the Tivolidesktop

Perform the following steps to distribute an adapter configuration profile from theTivoli desktop:1. From a policy region, select the Distribute option from the context menu of a

profile manager icon. The Adapter Configuration Facility displays theDistribute Profiles dialog box.

2. Click the Distribute Now button to distribute the profiles immediately.—OR—Click the Schedule button to schedule a profile distribution. See the TivoliManagement Framework User’s Guide for information about using the TivoliScheduler.

Distributing an adapter configuration profile from thecommand line

The following example command distributes an adapter configuration profile:wdistrib @ACP:Profile1


where:

Profile1Specifies the name of the profile.

Note: When distributing adapter configuration profiles with the wdistribcommand, the –l maintain option is typically used to maintain localmodifications for adapter configurations.

An optional mode is available to distribute specified profiles only. The –lover_all_no_merge option eliminates the need to reinstall adapterconfigurations in profiles that are not explicitly requested. This optionshould be used whenever adapter configuration profiles are distributed andyou want to force the reinstallation of specific adapter configurations.

For more information about wdistrib command options, see the Tivoli ManagementFramework Reference Manual.

Adding an adapter configuration profile recordBefore you can use an adapter configuration profile to configure and customize aparticular event adapter, you must create a record for the event adapter.

Endpoint adaptersEndpoint adapters, which include the OS/2 adapter, SNMP adapter, UNIX logfileadapter, and Windows event log adapter, must use the Adapter ConfigurationFacility to distribute their binaries to their respective endpoints.

To configure the UNIX logfile adapter, you must distribute to the appropriateoperating system type. The Adapter Configuration Facility provides additionalUNIX logfile adapter types in the format of tecad_logfile_interp_type to coincidewith each supported operating system, as shown in the following table.

Adapter Type Operating System

tecad_logfile_aix4-r1 AIX 4

tecad_logfile_solaris2 Solaris 2

tecad_logfile_hpux10 HPUX 11

Additionally, the tecad_logfile adapter type is provided; however, you must editthe profile record and replace TARGTYPE (in the Adapter Configuration FacilityEdit Profile dialog) with the correct operating system type for the system to whichyou are distributing the adapter and profile. If you do not provide the correctoperating system type, you get an error message similar to this:File /AP/2/usr/local/Tivoli/bin/generic_unix/TME/ACF_REP/tecad_logfile_TARGTYPE.fmt not a regular file

The tecad_logfile adapter type is not a recommended choice and is provided foruse with custom adapter types.

Note: The TME version of the UNIX logfile, OS/2, SNMP, and Windows event logadapters can be installed only on an endpoint. To install one of theseadapters on a managed node that does not have an endpoint installed, youmust use the non-TME version, or make the managed node an endpointalso.




Add an adapter configurationprofile record


This task can be performed only from the desktop.

Perform the following steps to add an adapter configuration profile record fromthe Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile


Configuration Profile window.3. Click the Add Entry button. The Adapter Configuration Facility displays the

Add Adapter Configuration dialog box.4. Select the adapter type from the scrolling list.5. Click the Select & Close button. The Adapter Configuration Facility displays

the Edit Adapter dialog box.See “Editing an adapter configuration profile record” for information aboutediting adapter configuration profile record entries.

6. Click the Save & Close button to save the new record. The AdapterConfiguration Facility closes the Edit Adapter dialog and displays the newrecord in the Adapter Configuration Profile window.

Editing an adapter configuration profile recordYou can perform the following editing operations on adapter configurationprofiles:v Add, modify, or remove a configuration optionv Add, modify, or remove a filter definitionv Add or remove a file from the distribution listv Modify the delete configuration file behaviorv Add or remove a before or after scriptv Enable or disable a before or after scriptv Modify before and after script reporting behaviorv Modify the commentv Modify the UID and GIDv Modify the adapter identifier name

When editing an adapter configuration profile record, you might find twoenvironment variables within a profile record: $TECADHOME and$TIVOLIHOME. $TECADHOME represents the directory just above the locationthe adapter binaries are stored; $TECADHOME/bin for managed nodes andendpoints. $TIVOLIHOME represents the directory where the environment scriptsand oserv.rc binary files for the managed node are installed.

If you specify an alternate location to install the binaries, the followingcustomization is required:


v You must manually set the $TECADHOME variable.v You must manually copy the binary files into the same directory you specified in

the Install Directory field during the installation process.

Adding a configuration option to an adapter configurationprofile record

You can add a configuration option to a record. These environment variables arepassed to the subscribers of the profile. For example, if you want to specify amaximum event size of 4096 bytes, you can set the environment variableEventMaxSize=4096.

Note: The terms environment variable and configuration options are synonymousin an Adapter Configuration Facility context.



Add a configuration optionto an adapter configurationprofile record



Perform the following steps to add a configuration option to an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Click the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Environment radio button.5. Select the new environment variable from the Unset Variables scrolling list by

double-clicking. The new environment variable displays in the first text boxabove the Current EIF Environment scrolling list.

6. Enter the value for the new environment variable in the right-hand text box.7. Click the check button to display the new environment variable in the scrolling

list.8. Repeat steps 5–7 for each new environment variable that you want to add.9. Click the Save & Close button to save the new environment variable and close

the Edit Adapter dialog box.

Modifying a configuration option in an adapter configurationprofile record

You can modify the value of an existing environment variable in a record.




Modify an environmentvariable in an adapterconfiguration profile record



Perform the following steps to modify an environment variable in an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Environment radio button. The Adapter Configuration Facility

displays a dialog box.5. In the Current EIF Environment scrolling list, double-click the environment

variable to be edited. The environment variable and its current value aredisplayed in the text boxes.

6. Enter the new value for the environment variable in the right-hand text box.7. Click the check button. The Adapter Configuration Facility displays your

changes in the Current EIF Environment scrolling list.8. Click the Save & Close button. The Adapter Configuration Facility saves the

new value for the environment variable and closes the Edit Adapter dialog box.

Removing an environment variable from an adapterconfiguration profile record

You can remove an environment variable from a record.



Remove an environmentvariable from an adapterconfiguration profile



Perform the following steps to remove an environment variable from an adapterconfiguration profile from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Click the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Environment radio button to display a dialog box.5. From the Current EIF Environment scrolling list, select the environment

variable to be deleted.6. Click the trash can button to delete the environment variable.


7. Click the Save & Close button to save your change and close the Edit Adapterdialog box.

Adding a filter definition to an adapter configuration profilerecord

You can add filter definitions to a record. Filtering at the adapter level can helpreduce unnecessary network traffic.



Add a filter definition to anadapter configuration profilerecord



Perform the following steps to add a filter definition to an adapter configurationprofile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box. If not

already selected, click the Filters radio button to display the Select Event Classdialog box.

4. Click the New Filter button to display the Select Event Class dialog box.5. Select the rule base from the Available Rule Bases scrolling list and click the

right arrow button.6. Select the event class from the Event Classes scrolling list.7. Click the Select & Close button to close the Select Event Class dialog and

display the new filter in the scrolling list in the Edit Adapter dialog box.8. Select the filter from the right-hand scrolling list by double-clicking, or select

and click the up arrow button.9. From the left-hand scrolling list, select the variable value for which you want

to add a filter and click the right arrow button.10. Enter the value for the variable in the right-hand text box and click the check

button. The new filter displays.11. Repeat steps 9 and 10 for each variable for which you want to specify a value.12. Click the Save & Close button to save your changes and close the Edit

Adapter dialog box.

Adding a filter cache definition to an adapter configurationprofile record

You can add filter cache definitions to a record. Filtering which events to cache atthe adapter level can help reduce unnecessary network traffic.




Add a filter cache definitionto an adapter configurationprofile record



Perform the following steps to add a filter cache definition to an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the FilterCache radio button.5. Click the New FilterCache button to display the Select Event Class dialog box.6. Select the rule base event class from the Select Event Class dialog box.7. Click the Select & Close button to close the Select Event Class dialog and

display the new filter in the scrolling list in the Edit Adapter dialog box.8. Select the filter from the right-hand scrolling list by double-clicking, or select

and click the up arrow button.9. From the left-hand scrolling list, select the variable value for which you want

to add to the filter and click the right arrow button.10. Type the value for the variable in the right-hand text box and click the check

button. The new filter displays.11. Repeat steps 9 and 10 for each variable for which you want to specify a value.12. Click the Save & Close button to save your changes and close the Edit

Adapter dialog box.

Adding a prefilter definition to an adapter configuration profilerecord

You can add prefilter definitions to a record. Use prefiltering to define whichevents the adapter processes. Filtering at the adapter level can help reduceunnecessary network traffic. This option is available only for Windows event logadapters.



Add a prefilter definition toan adapter configurationprofile record



Perform the following steps to add a prefilter definition to an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.


2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the PreFilters radio button to display the prefiltering fields in the Edit

Adapter dialog box.5. Select the New Prefilter button to display the Select Log dialog box.6. Select the log from the Available Log Specifications scrolling list or click the

right-arrow button to move the selected log to the Selected Log pane.

Note: DNS, Directory, and FRS logs are applicable only to the tecad_winprofile, which is for the Windows event log adapter.

7. Click the Select & Close button to close the Select Log dialog and display thenew prefilter in the scrolling list in the Edit Adapter dialog box.

8. Select the log from the right-hand scrolling list by double-clicking, or selectand click the up arrow button.

9. From the left-hand scrolling list, select the attribute (EventId, EventType, orSource) for which you want to add a prefilter and click the right arrowbutton.

10. Enter the preferred value for the variable in the right-hand text box and clickthe check button. The new prefilter displays.

11. Repeat steps 9 and 10 for each attribute for which you want to specify a value.12. Click the Save & Close button to save your changes and close the Edit

Adapter dialog box.

Modifying a filter definition in an adapter configuration profilerecord

You can modify an existing filter definition in a record.



Modify a filter definition inan adapter configurationprofile record



Perform the following steps to modify a filter definition in an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog and click the

Filters radio button.4. In the scrolling list, double-click the variable.5. Enter the new filter value for the variable in the right-hand text box and click

the check button to update the dialog with the new value.6. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.


Modifying a filter cache definition in an adapter configurationprofile record

You can modify an existing filter cache definition in a record.



Modify a filter cachedefinition in an adapterconfiguration profile record



Perform the following steps to modify a filter cache definition in an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the FilterCache radio button.5. In the scrolling list, double-click the variable.6. Enter the new filter cache value for the variable in the right-hand text box and

click the Check button to update the dialog with the new value.7. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.

Modifying a prefilter definition in an adapter configurationprofile record

You can modify an existing prefilter definition in a record.



Modify a prefilter definitionin an adapter configurationprofile record



Perform the following steps to modify a prefilter definition in an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the PreFilters radio button to display the dialog box.4. In the scrolling list, double-click the variable.5. Enter the new prefilter value for the attribute in the right-hand text box and

click the Check button to update the dialog with the new value.


6. Click the Save & Close button to save your changes and close the Edit Adapterdialog box.

Removing a filter cache definition in an adapter configurationprofile record

You can remove an existing filter cache definition in a record.



Remove a filter cachedefinition in an adapterconfiguration profile record



Perform the following steps to remove a filter cache definition in an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the FilterCache radio button.5. In the scrolling list, select the filter to be removed.6. Click the trash can button to remove the filter from the scrolling list.7. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.

Removing a prefilter definition in an adapter configurationprofile record

You can remove an existing prefilter definition in a record.



Remove a prefilter definitionin an adapter configurationprofile record



Perform the following steps to remove a prefilter definition in an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the PreFilters radio button.


5. In the scrolling list, select the prefilter to be removed.6. Click the trash can button to remove the prefilter from the scrolling list.7. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.

Removing a filter definition from an adapter configurationprofile record

You can remove a filter definition from a record.



Remove a filter definitionfrom an adapterconfiguration profile record



Perform the following steps to remove a filter definition from an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an v icon to display the Adapter Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box. Click the

Filters radio button.4. From the scrolling list, select the filter to be removed.5. Click the trash can button to remove the filter from the scrolling list.6. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.

Adding a file to the distribution list of an adapterconfiguration profile record

You can add a file to the distribution list of a record.



Add a file to the distributionlist of an adapterconfiguration profile record



Note: If you do not specify an absolute path name, the target file is placed in thedirectory specified by the target directory specified on the adapterconfiguration profile selection panel.

Perform the following steps to add a file to the distribution list of an adapterconfiguration profile record from the Tivoli desktop:



2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Distribution radio button.5. Enter the destination file name in the left-hand text box.

Note: If you do not specify an absolute path name, the target file is placed inthe directory specified by the target directory.

6. Enter the source file name in the right-hand text box.7. Click the check button.8. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.

Note: The Adapter Configuration Facility has the ability to use localized formatfiles with Adapter Configuration Facility 3.7.1. The default action is thatall localized format files are distributed to the$TECADHOME/etc/language_identifier directory of the adapter. Eachlanguage is represented by a different set of characters used as thedirectory name. The format file is copied to the language directory foruse with the adapter. All files are currently in English, but can belocalized to one of the supported languages. If you do not wish todistribute all localized format files for an adapter, use the instructionsbelow for removing a file from the distribution list of an adapterconfiguration profile record.

Removing a file from the distribution list of an adapterconfiguration profile record

You can remove a file from the distribution list of a record.



Remove a file from thedistribution list of an adapterconfiguration profile record



Perform the following steps to remove a file from the distribution list of an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Distribution radio button.5. From the scrolling list, select the file to be deleted.6. Click the trash can button to delete the file from the distribution list.7. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.


Modifying the adapter configuration file behaviorYou can modify the endpoint behavior of a record.



Modify the adapterconfiguration file behavior



Perform the following steps to modify the configuration file behavior from theTivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Distribution radio button.5. Select Remove files from the when record is deleted drop-down list to delete

files at the endpoints when the corresponding files are removed from theprofile.—OR—Select Keep files from the when record is deleted drop-down list to retain filesat the endpoints when the corresponding files are removed from the profile.

6. Click the Save & Close button. The Adapter Configuration Facility saves yourchanges and closes the Edit Adapter dialog box.

Modifying variable expansion behaviorYou can modify the variable expansion behavior of a record.



Modify variable expansionbehavior



Perform the following steps to modify the variable expansion behavior of a recordfrom the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the General radio button.5. You can specify which variables should be expanded at the profile endpoints

by using the left and right arrow buttons to move entries between the Expandat Endpoints scrolling list and the Leave Alone scrolling list.



Adding a before or after script to an adapter configurationprofile record

To easily specify actions that should be taken before or after files are distributed,you can add a before or after script to a record. In addition, check the defaultsupplied actions and paths to ensure that they are correct for your systems.



Add a before or after scriptto an adapter configurationprofile record



Perform the following steps to add a before or after script to an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Actions radio button.5. Enter the script in the Before file distribution scrolling list or in the After file

distribution scrolling list. This script can contain anything that can beinterpreted by the shell. The Adapter Configuration Facility adds the script tothe scrolling list.


Modifying a before or after script in an adapter configurationprofile record

You can change a before or after script. The following table lists the context andauthorization role required to perform this task.


Modify a before or afterscript to an adapterconfiguration profile record


Each adapter configuration record can be configured to perform actions onsubscribing endpoints upon distribution. Actions can be enabled or disabled.Whether or not an action is performed is determined by the setting of the controlon the upper right corner of the Actions attribute group.


Actions can be performed both before and after configuration files are written.Actions performed before file distribution can halt an event adapter and possiblyremove the contents of a configuration directory. Actions performed after filedistribution can restart the adapter.

The following options are available when an action fails: the endpoint code canignore failures, report failures (using a notice logged to the Adapter ConfigurationFacility notice group), or stop the distribution by throwing an exception. Only oneoption can be applied to each record.

For information about commands, such as the wsetaddflt command, which can beused to set actions, see the IBM Tivoli Enterprise Console Command and TaskReference. Internally, you can use the wdepset command to perform differentactions for different interp types. You can also write your own actions and includeinterp checking within the action.

Removing a before or after script from an adapterconfiguration profile record

You can remove a before or after script from a record.



Remove a before or afterscript from an adapterconfiguration profile record



Perform the following steps to remove a before or after script from an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Actions radio button.5. Place the cursor in the Before file distribution scrolling list or the After file

distribution scrolling list and backspace over the script to be removed.6. Click the Save & Close button and save your changes and close the Edit

Adapter dialog box.

Enabling and disabling before and after scripts in an adapterconfiguration profile record

You can specify whether before and after scripts should be run when files aredistributed.




Enable or disable before andafter scripts in an adapterconfiguration profile record



Perform the following steps to enable or disable before and after scripts in anadapter configuration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Actions radio button.5. Select enabled from the Actions are pull-down menu to enable before and after

scripts.—OR—Select disabled from the Actions are option menu to disable before and afterscripts.


Modifying before and after script reporting behaviorYou can modify the reporting behavior of before and after scripts.



Modify before and afterscript reporting behavior



Perform the following steps to modify the reporting behavior of before and afterscripts from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the Actions radio button.5. Select ignore & continue from the When actions fail drop-down list to ignore

errors during the running of before and after scripts.—OR—Select report & continue from the When actions fail drop-down list to reporterrors during the running of before and after scripts.—OR—Select abort distribution from the When actions fail drop-down list to stop thedistribution if errors occur during the running of before or after scripts.



Modifying the comment in an adapter configuration profilerecord

You can modify the comment field of a record.



Modify the comment in anadapter configuration profilerecord



Perform the following steps to modify the comment in an adapter configurationprofile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the General radio button.5. Enter your comments in the Comments scrolling list.6. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.

Modifying the UID and GID in an adapter configuration profilerecord

You can modify the user ID (UID) and group ID (GID) that a record uses.



Modify the UID and GID inan adapter configurationprofile record



Perform the following steps to modify the UID and GID in an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the General radio button.5. Enter the UID in the User text box.


6. Enter the GID in the Group text box.7. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.

Specifying the adapter identifier nameUse an adapter identifier name to run multiple instances of an adapter. Forexample, you might want to run specific logfile adapter instances for individualapplications that are installed on a particular system. You can specify an adapteridentifier name for the following adapter types: tecad_logfile_aix4-r1,tecad_logfile_hpux10, tecad_logfile_linux_ix86, tecad_logfile_linux-ppc,tecad_logfile_linux-s390, tecad_logfile_solaris2, and tecad_win.



Modify the adapter identifiername



Perform the following steps to modify the adapter identifier in an adapterconfiguration profile record from the Tivoli desktop:1. Double-click an adapter configuration profile icon to display the Adapter

Configuration Profile window.2. Select the record to be edited.3. Click the Edit Entry button to display the Edit Adapter dialog box.4. Click the General radio button.5. Click the Identifier check box.6. Enter the identifier name in the Identifier Name text box.7. Click the Save & Close button to save your changes and close the Edit Adapter

dialog box.

Copying an adapter configuration profile recordYou can copy adapter configuration profile records from one adapter configurationprofile to another. The profiles must be in different profile managers.



Copy an adapterconfiguration profile record


You can copy an adapter configuration profile record from the desktop or thecommand line.


Copying an adapter configuration profile record from theTivoli desktop

Perform the following steps to copy an adapter configuration profile record fromthe Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile


Configuration Profile window.3. Select the record or records you want to copy.

Note: You can select multiple records by selecting one record and dragging themouse pointer up or down the profile entries, by pressing the Ctrl keyand selecting multiple records, or by using the Find Record dialog box.For information about using the Find Record dialog, see “Finding anadapter configuration profile record” on page 76.

4. Select Copy Entries from the Edit menu to display the Copy Profile Recordsdialog box.

5. Select the profile manager that contains the target adapter configuration profileyou want to copy the entry to from the Available Profile Managers scrollinglist.The adapter configuration profiles that are in the ACPM1 profile manager areshown in the Available Profiles scrolling list.

6. Select a target profile from the Available Profiles scrolling list.7. Click the right arrow button to move the selection to the Target Profiles

scrolling list.8. Click the Copy & Close button to copy the record and close the Copy Profile

Records dialog box.

Moving an adapter configuration profile recordMoving an adapter configuration profile record deletes the record from the sourceprofile and adds it to the target profile. The target and source profiles can be in thesame or in different profile managers.



Move an adapterconfiguration profile record


You can move an adapter configuration profile from the desktop or the commandline.

Moving an adapter configuration profile Record from the Tivolidesktop

Perform the following steps to move an adapter configuration profile record fromthe Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile

Manager window.



3. Select the adapter configuration profile record you want to move.4. Select Move Entries from the Edit menu to display the Move Records dialog

box.5. Select the profile manager that contains the target adapter configuration profile

you want to move the entry to from the list of Available Profile Managers. Theadapter configuration profiles that are in the ACPM1 profile manager areshown in the Available Profiles scrolling list.

6. Select the target profile from the Available Profiles scrolling list.7. Click the Move & Close button to move the adapter configuration profile

record to the target and close the Move Records dialog box.

Deleting an adapter configuration profile recordIf you no longer need an adapter configuration profile record, you can delete itfrom the adapter configuration profile. The Adapter Configuration Facility removesthe record from all copies of the profile.



Delete an adapterconfiguration profile record


You can delete an adapter configuration profile record from the desktop or thecommand line.

Deleting an adapter configuration profile record from theTivoli desktop

Perform the following steps to delete an adapter configuration profile record fromthe Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile


Configuration Profile window.3. Select the adapter configuration profile record you want to delete and click the

Delete Entries button.

Deleting an adapter configuration profile record from thecommand line

The following example command deletes an adapter configuration profile recordfrom the command line:wdelac rec_num ACPM1:Profile1

where:

rec_numSpecifies one or more record numbers to delete from the profile, separatedby spaces.


ACPM1:Profile1Specifies the name of the adapter configuration profile.

For more information about the wdelac command, see the Tivoli ManagementFramework Reference Manual.

Locking and unlocking an adapter configuration profile recordLocking an adapter configuration profile record prevents subscribers from editingor deleting the record. You must distribute the adapter configuration profile for thelock to take effect. Subscribers cannot edit or delete a record until you unlock therecord and distribute the profile again.

You can lock all the records in a top-level profile to help ensure that the copies ofthe profile are always similar. Since you cannot lock an entire profile, it is possiblefor an administrator to add a record to a lower-level profile copy.



Lock or unlock an adapterconfiguration profile record


Locking and unlocking an adapter configuration profileRecord from the Tivoli desktop

Perform the following steps to lock or unlock an adapter configuration profilerecord from the Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile


Configuration Profile window.3. Select the adapter configuration profile records you want to lock or unlock.4. Select Lock Entries from the Edit menu to lock the records, or select Unlock

Entries from the Edit menu to unlock the records.

Finding an adapter configuration profile recordYou can find and highlight adapter configuration profile records based on criteriayou set for searching within a profile. The find record feature is most useful whenyou have numerous records in an adapter configuration profile.



Find an adapterconfiguration profile record

Adapter configuration profile user



Perform the following steps to find an adapter configuration profile record fromthe Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile


Configuration Profile window.3. Select Find from the View menu to display the Find Records dialog box.4. Select the field to search from the Attributes scrolling list.5. Select one of the following types of searches:

v Contains

Specifies that the records found contain a string value.v Exact match

Specifies that the records found exactly match the search criteria.v Greater than

Specifies that the value of the chosen attribute for the records found begreater than the value of the search criteria.

v Less than

Specifies that the value of the chosen attribute for the records found be lessthan the value of the search criteria.

6. Enter a value for the search criteria. The search criteria can be any valid valuefor the selected attribute. A completed Find Records dialog is displayed.

7. Click Find First to select the first instance of a record that meets the criteria.

—OR—

Click Find Next to select the next instance of a record that meets the criteria.

—OR—

Click Find All to select all of the records that meet the criteria.

The Adapter Configuration Facility displays the Adapter Configuration Profilewindow with the records that meet the specified criteria selected.

Perform the following steps to narrow a record search from the Tivoli desktop:a. From the Adapter Configuration Profile window, select Show Selected

Records to eliminate the deselected records from view. (The records are stillin the profile, but they are not displayed.)

b. Enter additional search criteria in the Find Records dialog box.c. Click the Find First, Find Next, or Find All button to select the records that

meet the search criteria.d. Repeat steps a through c until you display only a few records.e. Click Close in the Find Record dialog to close the dialog and return to the

Adapter Configuration Profile window.

You can edit or delete or perform similar operations on the selected records.

Sorting adapter configuration profile recordsYou can sort records so that the records are easier to maintain and modify.




Sort adapter configurationprofile records



Perform the following steps to sort adapter configuration profile records from theTivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile


Configuration Profile window.3. Select Sort —> Records from the View menu to display the Sort Records dialog

box.4. Select the attribute you wish to sort by from the Sort By scrolling list.5. Select the attribute that you want to use as the record label from the Record

Label Field scrolling list.6. If you want to sort the adapter configuration profile records in alphanumeric

order, click the Descending Sort radio button. Otherwise, click the AscendingSort radio button to sort the records in reverse alphanumeric order.

7. Click the Sort & Close button to sort and label the entries.

Sorting adapter configuration profile attributesYou can set which attributes are displayed and the order in which they aredisplayed in the Adapter Configuration Profile window.



Sort adapter configurationprofile attributes



Perform the following steps to sort the attributes of an adapter configurationprofile from the Tivoli desktop:1. From a policy region, double-click a profile manager icon to display the Profile


Configuration Profile window.3. Select Sort —> Attributes from the View menu to display the Display

Attributes dialog box.4. Use the right arrow button to move the attributes you do not want to display

from the Attributes Displayed scrolling list to the Attributes Not Displayedscrolling list.


5. Select an attribute from the Attributes Displayed scrolling list and use the upor down arrow button to move it to the position in which it is to be displayedin the Adapter Configuration Profile window.Repeat this step until all the attributes are listed in the order you want themdisplayed.

6. Click Sort & Close to sort and display the attributes in the AdapterConfiguration Profile window and close the Display Attributes dialog box.When you close the Adapter Configuration Profile window or click the ShowAll button, the results of the sort are cleared. The records themselves areunchanged.

Starting the Logfile Format Editor from an adapter configuration profileYou can start the Logfile Format Editor from a logfile or Windows adapterconfiguration profile.



Start Logfile Format Editorfrom an adapterconfiguration profile



Perform the following steps to start the Logfile Format Editor from an adapterconfiguration profile from the Tivoli desktop:1. Select a record from an adapter configuration profile.2. Click the Edit Entry button to display the Edit Adapter dialog box.3. Click the Logfile Format Editor button to display the IBM Tivoli Enterprise

Console Logfile Format Editor window. See Appendix D, “Logfile FormatEditor”, on page 207 for information about using the Logfile Format Editor.


Chapter 4. AS/400 alert adapter

The AS/400 alert adapter forwards events from an AS/400 system to the eventserver. The adapter can be registered with the startup configuration of the AS/400so that the adapter is started with all the other applications when the system isstarted.

The AS/400 alert adapter is a program that performs the following actions:v Monitors AS/400 alert filters (using data queues) for alertsv Extracts information from the alertsv Creates IBM Tivoli Enterprise Console events, using a class definition statement

(CDS) filev Filters IBM Tivoli Enterprise Console events that are not important, using a

configuration filev Sends IBM Tivoli Enterprise Console events to an event server (using TCP/IP

sockets) that runs user-created rules against these events

AS/400 alert events can be gathered from any alert filter, or from the supplieddefault filter. Multiple AS/400 alert adapters can be running at the same time, eachmonitoring a different filter.

A few of the benefits are as follows:v Consolidates alert monitoringv Integrates with existing AS/400 alert filters already defined to your specific

business rulesv Filters out SNA (Systems Network Architecture) alerts that are not important

and notifies the Tivoli operators only when something critical happensv Automatically acts on events using customer defined rules and tasks (using the

event server)v Centrally configures adapter files that can be sent to the remote AS/400 systems

Adapter filesThe AS/400 alert adapter package consists of the following files:

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBRThe configuration file

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBRThe CDS file

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRBRC.MBRThe BAROC file

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRRLS.MBRThe rules file

Make a backup copy of the CFG_ALERT file before modifying the contents of anyof the members.

A backup copy of this file also resides in the CFG_ALERT file in libraryQTMETECA02.


The AS/400 adapter package also consists of the following commands, which arecopied into QSYS upon installation of the product:

STRTECADP Starts an AS/400 adapter.

ENDTECADPEnds an AS/400 adapter.

Before starting the event server and an AS/400 alert adapter, check theconfiguration file to determine if it defines the preferred adapter behavior.

Configuration fileThe configuration file for the AS/400 alert adapter defines the behavior of theadapter, which runs as a job on the AS/400.

A configuration file is created during the installation of the AS/400 alert adapter.The name of this file is/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR. This file mustspecify either ServerLocation or TransportList. All other keywords have defaultvalues that are used if values are not specified.

The configuration file can contain the common keywords described in“Configuration file” on page 9, as well as the following adapter-specific keywords:

AdapterType Specifies the type of resource to be monitored. The default value isMSGQ if this keyword is not defined, meaning that the adaptermonitors a message queue. The value provided in theconfiguration file is ALERT.

AdapterCdsFileSpecifies the CDS file to be used for the AS/400 alert adapter. Thisfile can reside in either the QSYS or IFS name space, but the pathmust be specified in IFS notation, for example:/QSYS.LIB/mylib.LIB/myfile.FILE/mymbr.MBR

The default path is as follows:/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR

BufEvtPath Specifies the path and name of the buffer file for the AS/400 alertadapter. The default path is /etc/Tivoli/tec, and the default bufferfile name is the value specified for the adapter name on theAS/400 command (STRTECADP), used to start the adapter.

Note: If an AS/400 alert adapter attempts to open a buffer file thatis in use by another adapter, the adapter (which runs as abatch job) attempting to open the file ends.

Filter The name of the AS/400 alert filter to be monitored. The defaultvalue is QTMETECA02/QYAAFTR.

FilterDataQueueThe specific data queue that the adapter is to monitor for incomingalerts. If the alert filter is registered with the system, this keywordis required and the data queue must be created by the user beforethe AS/400 alert adapter is started. This keyword is optional if thealert filter defined by the Filter keyword is not registered with thesystem, or if the Filter keyword is not specified.


JobDescriptionSpecifies an AS/400 job description that is to be used whenstarting the adapter. The default value is QGPL/QDFTJOBD.

LanguageID Specifies the AS/400 language ID in which alerts are to be sent tothe event server. If a value is specified for this keyword, theAS/400 secondary language must be installed for that language ID.The default value for this keyword is ENU.

ProcessExistingAlertsSpecifies whether to send existing alerts on the data queue definedby the FilterDataQueue keyword. NO sends any new alerts sent tothe data queue. YES sends the next alert received on the dataqueue. This can cause the adapter to send previously sent alertsagain and create duplicate events sent to the event server. Thedefault value is NO.

ServerCCSID Specifies the coded character set identifier (CCSID) of the eventserver. This is in case the event server has a special code page orgraphic character set that needs to be supported. The default valueis 00819.

Class definition statement fileThe CDS file defines how events are constructed from information sent by theAS/400 alert adapter. It is described in detail in “Class definition statement file” onpage 25.

SELECT statement exampleSELECT

1:ATTR(=,$ALERT_CDPT),VALUE(PREFIX, "10"); # 10xx codepoints

Here, $ALERT_CDPT is a custom keyword set by the adapter. These keywords canbe used to write shorthand notation for SELECT statements. The following isequivalent to the previous example:SELECT

1:$ALERT_CDPT=10";

FETCH statement exampleFETCH

1:SUBSTR($V1, 0, 3);

This FETCH statement sets variable $F1 to the substring of $V1, which is avariable, starting at character 0 for a length of 3 characters.

KeywordsTo customize events, the AS/400 alert adapter supports the following keywords inclass definition statements. Evaluation of these keywords is faster because access ofthem is direct. Event definition content and syntax are described in the IBM TivoliEnterprise Console Rule Developer’s Guide.

$ACTIONS Recommended actions to be taken for the alert.

$ACTION_CODEThe legacy action code for non-generic alerts (alert subvector X'91').

$ADAPTER_CORRELUnique alert identifier used to extract the alert from the alertdatabase on the AS/400 system.

Chapter 4. AS/400 alert adapter 83

$ADAPTER_HOSTThe protocol address of the host where the adapter is running.

$ADAPTER_HOST_SNANODEThe netID.nau name of the host where the adapter is running.

$ALERT_CDPTThe alert code point that provides an index into predefined textdescribing the alert condition.

$ALERT_ID The unique ID describing the alert.

$ARCH_TYPE Defines the alert type, either NONGENERIC_ALERT (alertsubvector X'91') or GENERIC_ALERT (alert subvector x’92’).

$BLOCK_ID The legacy block ID for non-generic alerts (alert subvector X'91').

$CAUSES Alert causes collected from alert subvectors X'93', X'94', X'95', X'96',and X'97'.

$DATE The date and time the event was generated.

$DETAILED_DATAProduct specific detail data from alert subvector X'98'.

$EVENT_CORRELAlert correlation data from alert subvector X'47'.

$EVENT_TYPEA value indicating the severity of the alert condition (for example,PERMANENT, TEMPORARY, or IMPENDING PROBLEM).

$HOSTNAMEThe netID.nau name of the host where the alert originated.

$INCIDENT_CORRELAlert correlation data from alert subvector X'4A'.

$MSG The alert code point text and the first probable cause text for thealert.

$ORIGIN The hierarchy list of the alert origin.

$PRODUCT_IDThe hardware and software identifier from alert subvector X'10'.

$SELF_DEF_MSGThe general message text from alert subvector X'31'.

$SEVERITY The severity of the event.

$SOURCE The source of the event. The source is defined by the adapter typeAS400_ALERT.

$SUB_ORIGINThe last member in the hierarchy list of the alert origin.

Configuring the AS/400 alert filters

Default alert filterThe AS/400 alert adapter creates a default alert filter, QTMETECA02/QYAAFTR,at installation time. This filter consists of a selection entry that maps all alerts tothe group QTECALERT. The corresponding action entry for QTECALERT is alsoprovided. When the AS/400 alert adapter is started, a data queue is created and


the QTECALERT action entry is updated with the data queue name so incomingalert information can be monitored by the adapter.

If you use the default filter provided, copy it into library QUSRSYS and modify itthere.

Integrating with an existing alert filterYou might have alert filters that are already in use on your AS/400 system. Thesefilters have been set up with the appropriate selection and action entries to filteralerts of interest and route them to predefined groups.

The Filter keyword in the configuration file is used to indicate the name of thefilter that the AS/400 alert adapter is to monitor. If a value for this keyword is notspecified, the default filter (QTMETECA02/QYAAFTR) is used.

The FilterDataQueue keyword in the configuration file is used to indicate the nameof the data queue that the adapter is to monitor. The adapter assumes that thisdata queue has been created properly and has been incorporated into theappropriate action entries data queue list for the filter defined by the Filterkeyword. To update an action entry, use the CHGALRACNE (Change Alert ActionEntry) command. Create the data queue with the Create Data Queue (CRTDTAQ)command as follows:CRTDTAQ DTAQ(library/name) TYPE(*STD) MAXLEN(592)

FORCE(*NO) SEQ(*FIFO)

Note: If the data queue is not created according to the previous specifications, theadapter will not start. Also, if the AS/400 alert adapter is not running, thesystem still sends alert information to this data queue. If the data queue isfilled to capacity, the filter might be automatically deregistered by thesystem. To prevent this problem, have the adapter automatically started by astartup program when the system is started (see “Starting the adapter” onpage 85).

The AS/400 Network Attributes define the filter that is registered with the system.If the specified alert filter is registered with the system, then the FilterDataQueuekeyword is required. If the filter is not registered with the system and theFilterDataQueue keyword is not specified, then a data queue is created andassociated with the QTECALERT group in that filter. Use the Change NetworkAttributes (CHGNETA) command if you want to register the filter on the AS/400system.

Starting the adapterThe AS/400 adapter includes the STRTECADP command that you can use to startan adapter. You can also automatically start the adapter; see “Starting an AS/400adapter after an IPL” on page 93. The command is described on the followingpages.


STRTECADP

Starts an AS/400 adapter.

SyntaxSTRTECADP EVTADP(name) CFGFILE(filename)

DescriptionThe AS/400 adapter runs as a batch job. The STRTECADP command starts anAS/400 adapter.

Authorization:

QSYSOPR*USE

PUBLIC*EXCLUDE

Note: To grant other users authority to this command, use the followingcommands on the AS/400 system:GRTOBJAUT OBJ(QSYS/STRTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)

GRTOBJAUT OBJ(QTMETECA/SBMEVTADAP) OBJTYPE(*PGM) USER(user) AUT(*USE)

GRTOBJAUT OBJ(QTMETECA02/STARTALERT) OBJTYPE(*PGM) USER(user) AUT(*USE)

GRTOBJAUT OBJ(QSYS/QNMRRGF) OBJECTYPE(*PGM) USER(user) AUT(*USE)

GRTOBJAUT OBJ(QSYS/QNMRGFN) OBJECTYPE(*PGM) USER(user) AUT(*USE)

GRTOBJAUT OBJ(QSYS/QNMDRGFN) OBJECTYPE(*PGM) USER(user) AUT(*USE)

Arguments:

EVTADP(name)Specifies a name for the adapter being started. This name is used on theENDTECADP AS/400 command. It can be any valid AS/400 job name;however, each adapter running on the AS/400 system must have a uniquename.

CFGFILE(filename)Specifies the full path name of the configuration file, in IFS format, to beused.

The following command starts an AS/400 alert adapter using the defaultconfiguration file.STRTECADP EVTADP(ALERTADP)

CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR’)

The following command starts the AS/400 alert adapter with the/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR configuration file.STRTECADP EVTADP(MYADP)

CFGFILE(’/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR’)


Stopping the adapterThe AS/400 adapter includes the ENDTECADP command that you can use to stopadapters individually or to stop all started adapters. The command is described onthe following pages.


ENDTECADP

Stops the AS/400 adapter.

SyntaxENDTECADP EVTADP(name | *ALL) [OPTION(*CNTRLD | *IMMED)][DELAY(seconds)]

DescriptionThe AS/400 adapter runs as a batch job. The ENDTECADP command stops anAS/400 adapter.

Authorization:

QSYSOPR*USE

PUBLIC*EXCLUDE

Note: To grant other users authority to this command, use the followingcommands on the AS/400 system:GRTOBJAUT OBJ(QSYS/ENDTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)

GRTOBJAUT OBJ(QTMETECA/ENDEVENTAD) OBJTYPE(*PGM) USER(user) AUT(*USE)

Arguments:

EVTADP Specifies the name of the adapter to stop. The following optionscan be specified:

name Specifies the name of the adapter being stopped. This filename matches the name specified on the STRTECADPcommand.

*ALL If *ALL is specified, then all adapters of all types arestopped.

OPTION Specifies the way the adapter stops. The following options can bespecified:

*CNTRLDThe adapter ends in a controlled manner. This lets theapplication program perform end-of-job processing.

*IMMEDThe adapter is ended immediately.

Stopping the adapter immediately does not allow theadapter to perform cleanup routines and is notrecommended.

DELAY(seconds)Specifies the amount of time in seconds allowed for the adapter tocomplete its cleanup processing during a controlled end. Thisparameter is not used if *IMMED is specified for the OPTIONparameter. If the cleanup is not completed before the end of thedelay time, the adapter is ended immediately.

ExamplesThe following command stops the AS/400 alert adapter, started with the adaptername ALERTADP.


ENDTECADP EVTADP(ALERTADP)

The following command stops the AS/400 alert adapter, started with the adaptername MYCFG, in a controlled manner with a delay time of 60 seconds.ENDTECADP EVTADP(MYCFG) OPTION(*CNTRLD) DELAY(60)


Events ListingThe following shows the class names and severities of all events defined for theAS/400 alert adapter. You can use it to get a sense of how AS/400 alert events aremapped to IBM Tivoli Enterprise Console events and to determine if you want tomake any changes. The events are defined in the tecad_snaevent.baroc file on theevent server.

See the IBM Tivoli Enterprise Console Rule Developer’s Guide for more informationabout customizing the BAROC file.

Event class structureEvent classes are defined hierarchically, with child classes inheriting attribute valuedefaults from the parent. The AS/400 alert event classes follow a simple hierarchy.The attribute value for source is AS400_MSGQ. The following events are definedin the sample BAROC file provided with this product:

Table 10. Event class structure

Event ClassDefault EventSeverity

AS400_TEC_ALERT_ADAPTER (based on AS/400alert type)

SNA_Event CRITICAL

SNA_1xxx_Hardware CRITICAL

SNA_Equipment_Malfunction CRITICAL

SNA_Input_Device_Error CRITICAL

SNA_Output_Device_Error CRITICAL

SNA_Input_Output_Device_Error CRITICAL

SNA_Loss_Of_Electrical_Power CRITICAL

SNA_Loss_Of_Equipment_Cooling_Or_ Heating CRITICAL

SNA_Subsystem_Failure CRITICAL

SNA_Hardware CRITICAL

SNA_2xxx_Software CRITICAL

SNA_Software_Program_Abnormally_ Terminated CRITICAL

SNA_Software_Program_Error CRITICAL

SNA_Software_Operation_Failure CRITICAL

SNA_Software CRITICAL

SNA_3xxx_Communications CRITICAL

SNA_Communication_Protocol_Error CRITICAL

SNA_SNA_Protocol_Error CRITICAL

SNA_LAN_Error CRITICAL

SNA_Link_Error CRITICAL

SNA_ISDN_Error CRITICAL

SNA_Local_Connection_Error CRITICAL

SNA_Link_Connection_Error CRITICAL

SNA_BBNS_Communications_Error CRITICAL

SNA_Communications CRITICAL


Table 10. Event class structure (continued)

Event ClassDefault EventSeverity

SNA_4xxx_Performance CRITICAL

SNA_Performance_Degraded CRITICAL

SNA_Performance CRITICAL

SNA_5xxx_Congestion CRITICAL

SNA_Congestion CRITICAL

SNA_Configurable_Capacity_Limit_Reached CRITICAL

SNA_Congestion_Other CRITICAL

SNA_6xxx_Microcode CRITICAL

SNA_Microcode_Program_Abnormally_ Terminated CRITICAL

SNA_Microcode_Program_Error CRITICAL

SNA_Microcode_Program_Mismatch CRITICAL

SNA_Microcode CRITICAL

SNA_7xxx_Operator CRITICAL

SNA_Operator_Procedural_Error CRITICAL

SNA_Operator CRITICAL

SNA_8xxx_Specification CRITICAL

SNA_Configuration_Or_Customization_Error CRITICAL

SNA_Specification CRITICAL

SNA_9xxx_Intervention_Required CRITICAL

SNA_Operator_Intervention_Required CRITICAL

SNA_Stock_Low CRITICAL

SNA_Stock_Exhausted CRITICAL

SNA_Depository_Full CRITICAL

SNA_Intervention_Required CRITICAL

SNA_Axxx_Problem_Resolved CRITICAL

SNA_Problem_Resolved CRITICAL

SNA_Bxxx_Notification CRITICAL

SNA_Operator_Notification CRITICAL

SNA_Environmental_Problem CRITICAL

SNA_Resent_Alert_With_Updated_Information CRITICAL

SNA_Notification CRITICAL

SNA_Cxxx_Security CRITICAL

SNA_Security_Event CRITICAL

SNA_Security CRITICAL

SNA_Exxx_Non_IBM_Codepoint CRITICAL

SNA_Fxxx_Undetermined CRITICAL

SNA_Undetermined_Error CRITICAL

SNA_NonGeneric_Undetermined CRITICAL

SNA_Reserved_By_IBM CRITICAL


You can set the severity of an AS/400 alert event on the event console as follows,based on the AS/400 alert type field specified in the message description:

Alert Type Default Severity

01 (permanent loss of availability) CRITICAL

04 (operator intervention required) CRITICAL

09 (unavailable network component) CRITICAL

0E (security problem) CRITICAL

10 (permanently affected resource) CRITICAL

03 (performance degradation) WARNING

0A (notification: loss impending) WARNING

0C (installation consistency) WARNING

0D (operational procedural error) WARNING

0F (delayed condition) WARNING

11 (impending problem) WARNING

14 (bypassed loss of availability) WARNING

16 (monitored situation event) WARNING

0B (environmental problem) MINOR

12 (unknown) UNKNOWN

02 (temporary loss of availability) HARMLESS

05 (reserved) HARMLESS




13 (retired) HARMLESS

other values HARMLESS

Troubleshooting the AS/400 adapterIf a problem occurs with the AS/400 adapter, you can perform problemdetermination by investigating the job the adapter is running in. Each time youstart an AS/400 adapter, a batch job is started. You can view the adapter job byissuing the following command:WRKJOB JOB(name)

where name is the name of the adapter job that matches the name specified on theSTRTECADP command. This displays the Work with Job dialog.

Note: Several adapter jobs might have existed on your AS/400 system with thesame name as the current adapter job. In this case, you are first presentedwith a list of jobs to choose from. Select the most recent job from the list.

From the Work with Job dialog, you can select option 10 to display the job log, orif the job has ended (selecting option 10 tells you so), you can view the job log thatwas generated by selecting option 4.

Examine the job log for messages indicating the error that occurred and follow thecorrective action specified. For further assistance, contact Customer Support.


Logging Events in Test ModeThe file to which events are logged in test mode (instead of being sent to an eventserver) is created with a record length of 240 bytes if it does not exist. Because anevent written to this file does not wrap to a new line if it is longer than 240 bytes,it is truncated. To avoid truncation, create the file ahead of time using the CRTPFor CRTSRCPF commands and specify a large enough record length toaccommodate your events. To utilize this file, ensure that it is specified for theServerLocation keyword. For additional information, see “Keywords” on page 10.

Also, be sure that you use the proper format, ABCLIB/TECMSGS(library/file_name). If the file does not exist, it is created automatically.

TCP/IP considerationsEnsure that the event server and the AS/400 are configured in your network NameServer, and that the AS/400 is configured to resolve to the Name Server.

If you do not use a Name Server in your network, make sure that an entry existson the AS/400 in the TCP/IP host table for both the event server and the AS/400system. Use the following commands to do this:ADDTCPHTE INTNETADR(’event server protocol address’)

HOSTNAME((event server host name))TEXT(’Tivoli Enterprise Console event server’)

ADDTCPHTE INTNETADR(AS/400 protocol address)HOSTNAME((AS/400 host name)) TEXT(‘AS/400’)

Starting an AS/400 adapter after an IPLThere are two methods that can be used to start an AS/400 alert adapterautomatically after an initial program load (IPL), as follows:v Adding an autostart job to a job queuev Modifying the AS/400 startup program to call the STRTECADP command

Adding an autostart job to QSYSWRK1. Create a Control Language (CL) program that calls the STRTECADP

command, for example:a. Edit a source file member to add CL statements:

STRSEU QGPL/QCLSRC STRADPCL

b. Enter the following in the source file member. You can have a STRTECADPcommand for each adapter you would like to start:PGM

STRTECADP EVTADP(NEWFILTER) +CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR’)

ENDPGM

Note: Ensure that the TCP/IP service is started on the AS/400 systembefore starting an adapter.

c. Create the program using the previous source program:CRTCLPGM PGM(QGPL/STRADPCL) SRCFILE(QGPL/QCLSRC)

2. Create a job description that calls the previous program and use QSYSNOMAXas the job queue:


CRTJOBD JOBD(QGPL/STARTADP)JOBQ(QSYSNOMAX)TEXT(’Start TEC adapter after IPL.’)RQSDTA(’CALL QGPL/STRADPCL’)

3. Add an auto start job entry in QSYSWRK using the previous job description:ADDAJE SBSD(QSYSWRK)JOB(TECAMSGQ)JOBD(QGPL/STARTADP)

This program runs at the start of QSYSWRK subsystem and ends quickly afterdoing the STRTECADP command.

Changing the AS/400 startup programThe system value QSTRUPPGM (startup program) contains the name of theprogram to run after IPL. This program can be modified to add the starting ofadapters.1. Retrieve the code in the startup program:

RTVCLSRC PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC)SRCMBR(program-name)

2. Modify the source:PGM

DCL VAR(&STRWTRS) TYPE(*CHAR) LEN(1)DCL VAR(&CTLSBSD) TYPE(*CHAR) LEN(20)QSYS/STRSBS SBSD(QCMN)STRTCPMONMSG MSGID(CPF0000)QSYS/STRSBS SBSD(QSERVER)MONMSG MSGID(CPF0000)

STRTECADP EVTADP(ALERTADP)+CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR’)

MONMSG MSGID(CPF0000)DONE:RETURNCHGVAR VAR(&CPYR) VALUE(&CPYR)

ENDPGM

3. Create the program and put it in the QSYS library:CRTCLPGM PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC)

SRCMBR(program-name)

Note: The startup program runs under user profile QPGMR. The defaultsetting is that QPGMR does not have authority to the AS/400 alertadapter commands and programs. You must either grant QPGMRauthority to the commands and programs (“Starting the adapter” onpage 85) or have the startup program adopt QSECOFR authority and beowned by QSECOFR.

Multiple AS/400 alert adaptersTo support another AS/400 alert adapter to monitor a different alert filter oranother data queue within the same filter, create the following additional files:v Configuration file: Specifies the filter to monitor and data queue to monitor.v CDS file: Defines new classes to match the alerts being monitored.v BAROC file: Required if new classes are identified in the CDS file.v Rules file: Required if new rules are added.


Configuration fileTo create the configuration file, perform the following steps:1. Copy the adapter files using the following commands:

CPYF FROMFILE(QUSRSYS/CFG_ALERT)TOFILE(QUSRSYS/MYFILE) FROMMBR(*ALL)TOMBR(*FROMMBR) CRTFILE(*YES)

2. Update the configuration file to show the keywords pointing to the newobjects, as follows:AdapterCdsFile=/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCFG.MBR

Filter=mylib/myfilter

FilterDataQueue=mylib/mydtaqueue

3. Update the CDS and the BAROC files to include any new classes and filters.4. Update the rules file to include any new rules.5. On the event server, import the BAROC file into the rule base; then, compile

and load the rule base.6. Start the adapter using the new adapter files as follows:

STRTECADP EVTADP(MYEVTADP)CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCFG.MBR’)


QTMETECA/POSTEMSG

Posts an event to the event server. See the IBM Tivoli Enterprise Console Commandand Task Reference for more details about this command.

SyntaxQTMETECA/POSTEMSG { –S<server> | –f<config_file> } [–r<severity>][–m<message>] [<slot_name=value>, ...] <class> <source>

Note: There cannot be a space between the option letter and the option value.

ExamplesCall QTMETECA/POSTEMSG PARM(‘–Sserver_name’ ‘–rHARMLESS’

‘–m”This is a message”’ AS400_MSG LOGFILE)Call QTMETECA/POSTEMSG

PARM(‘–f/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR’‘–rFATAL’ ‘–m”This is a message”’ AS400_MSG LOGFILE)


Common tasksUse these commands to perform common tasks related to the AS/400 alert adapter.v To load the AS/400 alert and message adapters with English as a primary

language:RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) SAVF(QUSRSYS /ATMETEC)RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(1) SAVF(QUSRSYS /ATMETEC1)RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(2) SAVF(QUSRSYS /ATMETEC2)

v To load the AS/400 message and alert adapters with English as a secondarylanguage:RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) LNG(2924) SAVF(QUSRSYS/ATMETEC)RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(1) LNG(2924) SAVF(QUSRSYS/ATMETEC1)RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(2) LNG(2924) SAVF(QUSRSYS/ATMETEC2)

v To delete all AS/400 adapters from the AS/400 system:DLTLICPGM LICPGM(1TMETEC)

v To delete only the AS/400 alert adapter from the AS/400 system:DLTLICPGM LICPGM(1TMETEC) OPTION(2) Delete the alert adapter (lib QTMETECA02)

v To start the AS/400 alert adapter:STRTECADP EVTADP(ALRNAME) CFGFILE(’QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR’)

v To stop the adapter:ENDTECADP EVTADP(ADPNAME)


Chapter 5. AS/400 message adapter

The AS/400 message adapter forwards events from an AS/400 system to the eventserver. It can be registered with the startup configuration of the AS/400 system sothat the adapter is started with all the other applications when the AS/400 systemis started. See “Starting an AS/400 adapter after an IPL” on page 112 forinstructions on starting the adapter automatically with the AS/400 system.

The AS/400 message adapter is a program that performs the following actions:v Reads messages from a message queue on an AS/400 systemv Extracts information from the messagev Creates IBM Tivoli Enterprise Console classes, using a class definition statement

(CDS) filev Filters IBM Tivoli Enterprise Console events that are not important, using a

configuration filev Sends IBM Tivoli Enterprise Console events to an event server (using TCP/IP

sockets) that runs user-created rules against these events

AS/400 message events can be gathered from any non-program message queue,including the system operator message queue QSYSOPR. Multiple AS/400 messageadapters can be running at the same time. One AS/400 message adapter canmonitor the system operator message queue while another is monitoring anapplication message queue.

A few of the benefits of the AS/400 message adapter are as follows:v Consolidates the system operator message console, QSYSOPR, for all the AS/400

systems in your enterprisev Monitors applications that use message queuesv Filters out messages that are not important and only notifies the Tivoli operators

when something critical happensv Automatically acts on events using customer-defined rules and tasks (using the

event server)v Centrally configures adapter files that can be sent to remote AS/400 systems

Adapter FilesThe AS/400 adapter package consists of the following files:

/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBRThe configuration file.

/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBRThe CDS file.

/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGBRC.MBRThe BAROC file. This file is located on the event server with thename of as400msg.baroc. It is automatically compiled into theactive rule base when the event server is installed.

Make a backup copy of the CFG_MSG file if you intend to modify the contents ofany of the members.


A backup copy of each of these files also resides in the CFG_MSG file in libraryQTMETECA01.

Before starting the event server and an AS/400 message adapter, check theconfiguration file to determine if it defines the preferred adapter behavior.

Configuration fileThe configuration file for the AS/400 message adapter defines the behavior of theadapter, which runs as a job on the AS/400 system.

A configuration file is created during the installation of the AS/400 messageadapter. The name of this file is/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR. The configuration filecan contain the keywords described in “Configuration file” on page 9, as well asthe following custom keywords:

AdapterType Specifies the type of resource to be monitored. The default value isMSGQ, meaning that the adapter monitors a message queue.

AdapterCdsFileSpecifies the CDS file to be used for the AS/400 message adapter.This file can reside in either the QSYS or IFS name space, but thepath must be specified in IFS notation, for example:/QSYS.LIB/mylib.LIB/myfile.FILE/mymbr.MBR

The default path is as follows:/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR

BufEvtPath Specifies the path and name of the buffer file for the AS/400message adapter. The default path is /etc/Tivoli/tec, and thedefault buffer file name is the value specified for the adapter nameon the AS/400 command (STRTECADP), used to start the adapter.

Note: If an AS/400 message adapter attempts to open a buffer filethat is in use by another adapter, the adapter (which runs asa batch job) attempting to open the file ends.

JobDescriptionSpecifies an AS/400 job description that is to be used whenstarting the adapter. The default value is QGPL/QDFTJOBD.

LanguageID Specifies the AS/400 language ID in which the AS/400 messagesare to be sent to the event server. The default value for thiskeyword is ENU. If a value is specified for this keyword, theAS/400 secondary language must be installed for that language ID.

MsgQueue Specifies the AS/400 message queue to poll. The complete nameneeds to be specified. The message queue must exist when theadapter is started. If the message queue is cleared while theadapter is active, the adapter starts with new messages that arewritten after the message queue was cleared. The value of this fieldmust be in the following format:

mylib/mymsgq

The default value is QSYS/QSYSOPR.

PollInterval Specifies the amount of time in seconds to return to a suspended


state between checking for new events that have been placed onthe message queue. The default value is 20. The following exampleshows the format:PollInterval=60

ProcessExistingMsgsSpecifies whether the AS/400 messages adapter resets back to thefirst message on the message queue when starting. NO sends anynew messages to the message queue. YES sends the first messageon the message queue. This could cause the adapter to resendpreviously sent messages and create duplicate events sent to theevent server. The default value is NO.

ServerCCSID Specifies the coded character set identifier (CCSID) of the eventserver. This is in case the event server has a special code page orgraphic character set that needs to be supported. The default valueis 0819.

Class definition statement fileThe file /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/ MSGCDS.MBR defines howevents are constructed from information sent by the AS/400 message adapter. It isdescribed in detail in “Class definition statement file” on page 25.

SELECT statement exampleSELECT

1:ATTR(=,$MSG_ID), VALUE(=,CPI5933);

Here, $MSG_ID is a custom keyword set by the adapter. These keywords can beused to write shorthand notation for SELECT statements. The following isequivalent to the previous example:SELECT

1:$MSG_ID=CPI5933;

For the $MSG_ID keyword, multiple low:high pairs can be specified with spaces asseparators. An example is as follows:SELECT

1:$MSG_ID=CPF 0100:02FF 1000:1FFF 5600:56FF;

FETCH statement exampleFETCH

1:SUBSTR($V1, 0, 3);

This FETCH statement sets variable $F1 to the substring of $V1, which is avariable, starting at character 0 for a length of 3 characters.

MAP statement exampleCLASS PerformanceInvestigatorSELECT

1:$MSG_ID=PNV *:*;FETCH

1:SUBSTR($V1, 0, 3);2:SUBSTR($V1, 3, 4);

MAPmy_field=PRINTF("attribute=%s has prefix=%s and id=%s", $V1,

$F1, $F2);status=OPEN

END

Chapter 5. AS/400 message adapter 101

KeywordsTo customize events, the AS/400 message adapter supports the followingkeywords in class definition statements. Evaluation of these keywords is fasterbecause access of them is direct. Event definition content and syntax are describedin the IBM Tivoli Enterprise Console Rule Developer’s Guide.

$ADAPTER_HOSTThe protocol address of the host where the adapter is running.

$ALERT_OPTIONIf and when an SNA alert is created and sent for the message. If amessage is received, the value is one of the following values:

*DEFERAn alert is sent after local problem analysis.

*IMMEDAn alert is sent immediately when the message is sent tothe QHST message queue.

*NO No alert is sent.

*UNATTENDAn alert is sent immediately when the system is running inunattended mode (when the value of the alert statusnetwork attribute, ALRSTS, is *UNATTEND).

$DATE The date and time the event was generated.

$DATA_CCSID_CONVERT_STATUSThe following are possible values returned:

0 No conversion was needed because the CCSID of thereplacement data or impromptu message text matched theCCSID you wanted the data or text converted to.

1 No conversion occurred because either the data was 65535or the CCSID you wanted the data converted to was 65535.

2 No conversion occurred because you did not supplyenough space for the data.

3 The data was converted to the CCSID specified using thebest fit conversion tables.

4 A conversion error occurred using the best fit conversiontables, so a default conversion was attempted. Thiscompleted without error.

–1 An error occurred on both the best fit and defaultconversions. The data was not converted.

$DATA_CCSID_RETURNEDThe CCSID of the replacement data or impromptu message text isreturned. If an impromptu message is received, this is the CCSIDof the impromptu message text. When replacement data isreceived, this is the CCSID of the replacement data fields definedas convertible character (*CCHAR) in the message description. Allother replacement data is not converted before it is returned. If aconversion error occurs or the CCSID you requested the data to beconverted to is 65535, the CCSID of the data or text is returned. Ifreplacement data is being returned and there is no *CCHAR


replacement data, 65535 is returned. Otherwise, the CCSID youwanted the data converted to is returned.

$HOSTNAMEThe name of the system on which the event occurred.

$MSG The default message used.

$MSG_FILE_NAMEThe name of the message file containing the message received.

$MSG_FILE_LIBRARYThe name of the library containing the message file. For the actuallibrary used when the message is sent, use the$MSG_LIBRARY_USED keyword.

$MSG_HELP The message help for the message received. If an immediatemessage is received, this field is blank.

$MSG_ID Indicates the AS/400 message identifier.

$MSG_KEY The key to the message received.

$MSG_LIBRARY_USEDThe name of the library used to send the message. Because thelibrary can contain override instructions, this is not necessarily thelibrary in which the message actually resides.

$MSG_SEVERITYSpecifies the severity. A two-digit value ranging from 0 through 99.The higher the value, the more severe or important the condition.

$MSG_TYPE The message type of the message received. The possible values andtheir meanings are as follows:

01 Completion

02 Diagnostic

04 Informational

05 Inquiry

06 Sender copy

08 Request

10 Request with prompting

14 Notify

15 Escape

21 Reply, not validity checked

22 Reply, validity checked

23 Reply, message default used

24 Reply, system default used

25 Reply, from system reply list

$ORIGIN The protocol address of the source system.

$SEND_DATEThe date on which the message was sent, in CYYMMDD (century,year, month, day) format.


$SEND_JOB The name of the job in which the message being received was sent.

$SEND_JOB_NUMBERThe job number of the job in which the message being receivedwas sent.

$SEND_PROGRAM_NAMEThe program name or Integrated Language Environment® (ILE)program name that contains the procedure sending the message.

$SEND_TIMEThe time at which the message being received was sent, inHHMMSS (hour, minute, second) format.

$SEND_USER_PROFILEThe name of the user profile that sent the message being received.

$SEVERITY The severity of the event.

$SOURCE The source of the event. The source is defined by the adapter type(AS400_MSGQ).

$SUB_ORIGINA further categorization of the origin.

$SUB_SOURCEA further categorization of the source.

$TEXT_CCSID_CONVERT_STATUSThe following are possible values returned:

0 No conversion was needed because the CCSID of themessage or message help text matched the CCSID youwanted the message or message help text converted to.

1 No conversion occurred because either the message ormessage help text was 65535 or the CCSID you wanted themessage or message help text converted to was 65535.

2 No conversion occurred because you did not supplyenough space for the message or message help.

3 The message or message help text was converted to theCCSID specified using the best fit conversion tables.

4 A conversion error occurred using the best fit conversiontables, so a default conversion was attempted. Thiscompleted without error.

–1 An error occurred on both the best fit and defaultconversions. The data was not converted.

$TEXT_CCSID_RETURNEDThe CCSID of the text in the message and message help fields isreturned. The inserted replacement data might not be the sameCCSID. Refer to the $DATA_CCSID_RETURNED keyword formore details. If a conversion error occurs or the CCSID yourequested the text to be converted to is 65535, the CCSID that themessage description is stored in is returned. Otherwise, the CCSIDyou wanted your text converted to is returned. If you do not wantthe text converted before it is returned to you but you do want toknow the CCSID that the message description is stored in, specify65535 on the coded character set identifier parameter. The CCSID


that the message description is stored in is returned in the CCSIDof message and message help output field.

$ARG1 – $ARG8Used to identify message replacement text or values.

Starting the adapterThe AS/400 message adapter includes the STRTECADP command that you canuse to start an adapter. The command is described on the following pages.


STRTECADP

Starts an AS/400 adapter.

SyntaxSTRTECADP EVTADP(name) CFGFILE(filename)

DescriptionThe AS/400 adapters run as a batch job. The STRTECADP command starts anAS/400 adapter.

Authorization:

QSYSOPR*USE

PUBLIC*EXCLUDE

To grant other users authority to this command, use the following commands onthe AS/400:GRTOBJAUT OBJ(QSYS/STRTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)

GRTOBJAUT OBJ(QTMETECA/SBMEVTADAP) OBJTYPE(*PGM) USER(user) AUT(*USE)

GRTOBJAUT OBJ(QTMETECA01/STARTMSGAD) OBJTYPE(*PGM) USER(user) AUT(*USE)

Arguments:

EVTADP(name)Specifies a name for the adapter being started. This name is usedon the End TEC Adapter (ENDTECADP) AS/400 command. It canbe any valid AS/400 job name; however, each adapter running onthe AS/400 system must have a unique name.

CFGFILE(filename)Specifies the full path name of the configuration file, in IFS format,to be used.

ExamplesThe following command starts an AS/400 message adapter using the defaultconfiguration file. The default configuration file monitors the system operatormessage queue, QSYSOPR:STRTECADP EVTADP(SYSOPR)

CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR’)

The following command starts the AS/400 message adapter with the/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR configuration file. Theconfiguration file could be set up to monitor an application specific messagequeue:STRTECADP EVTADP(MYAPP)

CFGFILE(’/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR’)


Stopping the adapterThe AS/400 adapter includes the ENDTECADP command that you can use to stopadapters individually or to stop all started adapters. The command is described onthe following pages.


ENDTECADP

Stops the AS/400 adapter.

SyntaxENDTECADP EVTADP(name | *ALL) [OPTION(*CNTRLD | *IMMED)][DELAY(seconds)]

DescriptionThe AS/400 adapters run as a batch job. The ENDTECADP command stops anAS/400 adapter.

Authorization:

QSYSOPR*USE

PUBLIC*EXCLUDE

To grant other users authority to this command, use the following commands onthe AS/400:GRTOBJAUT OBJ(QSYS/ENDTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)

GRTOBJAUT OBJ(QTMETECA/ENDEVENTAD) OBJTYPE(*PGM) USER(user) AUT(*USE)

Arguments:

EVTADPSpecifies the name of the adapter to stop. The following options can bespecified:

name Specifies the name of the adapter being stopped. This namematches the name specified on the Start TEC Event Adaptercommand.

*ALL If *ALL is specified, then all adapters of all types are stopped.

OPTIONSpecifies the way the adapter stops. The following options can be specified:

*CNTRLDThe adapter ends in a controlled manner. This lets the applicationprogram perform end-of-job processing.

*IMMEDThe adapter is ended immediately.

Note: Stopping the adapter immediately does not allow theadapter to perform cleanup routines and is notrecommended.

DELAY(seconds)Specifies the amount of time in seconds allowed for the adapter tocomplete its cleanup processing during a controlled end. This parameter isnot used if *IMMED is specified for the OPTION parameter. If the cleanupis not completed before the end of the delay time, the adapter is endedimmediately.


ExamplesThe following command stops the AS/400 message adapter, started with theadapter name SYSOPR, which was started to monitor the QSYSOPR messagequeue:ENDTECADP EVTADP(SYSOPR)

The following command stops the AS/400 message adapter, started with theadapter name MYAPP, in a controlled manner that was set up to monitor anapplication-specific message queue:ENDTECADP EVTADP(MYAPP) OPTION(*CNTRLD) DELAY(60)


Events listingThe following shows the class names and severities of all events defined for theAS/400 message adapter. You can use it to get a sense of how AS/400 messagesare mapped to IBM Tivoli Enterprise Console events and to determine if you wantto make any changes. The events are defined in the as400msg.baroc file on theevent server.


Event class structureEvent classes are defined hierarchically, with child classes inheriting attribute valuedefaults from the parent. The AS/400 message event classes follow a simplehierarchy. The AS/400 message adapter fills in the following attribute defaults. Theattributes are used in event group filters.

source AS400_MSGQ

sub_sourceFully qualified message queue name.

origin Protocol address of the system.

hostnameName of the system from the host name table.

date Date and time the message was sent.

msg First level message text with replacement values.

The following events are defined in the sample BAROC file provided with thisproduct:

Table 11. Events defined in the sample BAROC file

Event Class Default Severity

AS400_TEC_MSGQ_ADAPTER (Based on the AS/400 messageseverity)00-19 HARMLESS20-29 WARNING30-39 MINOR40-59 CRITICAL60-99 FATAL

AS400_MSG_BASE (Based on the AS/400 messageseverity)00-19 HARMLESS20-29 WARNING30-39 MINOR40-59 CRITICAL60-99 FATAL

AS400_MSG

AS400_Writer_Started

AS400_Writer_Ended_Normal

AS400_Device_No_Longer_Communicating

AS400_Controller_Failed

AS400_Controller_NotReplying


Table 11. Events defined in the sample BAROC file (continued)


AS400_Network_Session_Unavailable

AS400_Controller_Contacted_Line

AS400_Controller_Off_or_NotRecognized

AS400_Unable_Auto_VaryOn

Troubleshooting the AS/400 adapterIf a problem occurs with the AS/400 adapter, you can perform problemdetermination by investigating the job the adapter is running in. Each time youstart an AS/400 adapter, a batch job is started. You can view the adapter job byissuing the following command:WRKJOB JOB(name)

Where name is the name of the adapter job that matches the name specified on theSTRTECADP command. This displays the Work with Job dialog.

Note: Several adapter jobs might have existed on your AS/400 with the samename as the current adapter job. In this case, you are first presented with alist of jobs to choose from. Select the most recent job from the list.

From the Work with Job dialog, you can select option 10 to display the job log, orif the job has ended (selecting option 10 tells you so), you can view the job log thatwas generated by selecting option 4.

Examine the job log for messages indicating the error that occurred and follow thecorrective action specified. For further assistance, contact Customer Support.

Logging Events in Test ModeThe file to which events are logged in test mode (instead of being sent to an eventserver) is created with a record length of 240 bytes if it does not exist. Because anevent written to this file does not wrap to a new line if it is longer than 240 bytes,it is truncated. To avoid truncation, create the file ahead of time using the CRTPFor CRTSRCPF commands and specify a large enough record length toaccommodate your events. To utilize this file, ensure it is specified for theServerLocation keyword. For additional information, see “Keywords” on page 10.

Also, be sure that you use the proper format, ABCLIB/TECMSGS(library/file_name). If the file does not exist, it is created automatically.

TCP/IP considerationsEnsure that the event server and the AS/400 system are configured in yournetwork Name Server, and that the AS/400 system is configured to resolve to theName Server.

If you do not use a Name Server in your network, make sure that an entry existson the AS/400 system in the TCP/IP host table for both the event server and theAS/400 system. Use the following commands to do this:


ADDTCPHTE INTNETADR(event server protocol address)HOSTNAME((event server host name))TEXT(’Tivoli Enterprise Console event server’)

ADDTCPHTE INTNETADR(AS/400 protocol address)HOSTNAME((AS/400 host name)) TEXT(‘AS/400’)

Starting an AS/400 adapter after an IPLTwo methods can be used to automatically start an AS/400 message adapter afteran IPL:v Adding an autostart job to a job queuev Modifying the AS/400 startup program to call the STRTECADP command

Adding an autostart job to QSYSWRK1. Create a CL program that calls the STRTECADP command, for example:

a. Edit a source file member to add CL statements:STRSEU QGPL/QCLSRC STRADPCL

b. Enter the following in the source file member. You can have a STRTECADPcommand for each adapter you would like to start:PGM

STRTECADP EVTADP(SYSOPR) +CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR’)

ENDPGM

Note: Ensure that TCP/IP service is started on the AS/400 system beforestarting a message adapter.

c. Create the program using the previous source member:CRTCLPGM PGM(QGPL/STRADPCL) SRCFILE(QGPL/QCLSRC)

2. Create a job description that calls the previous program and use QSYSNOMAXas the Job Queue:CRTJOBD JOBD(QGPL/STARTADP)

JOBQ(QSYSNOMAX)TEXT(’Start TEC adapter after IPL.’)RQSDTA(’CALL QGPL/STRADPCL’)

3. Add an auto-start job entry in QSYSWRK using the previous job description:ADDAJE SBSD(QSYSWRK) JOB(TECAMSGQ) JOBD(QGPL/STARTADP)

This program runs at the start of QSYSWRK subsystem and ends quickly afterdoing the STRTECADP command.

Changing the AS/400 startup programThe system value QSTRUPPGM (startup program) contains the name of theprogram to run after IPL. This program can be modified to add the starting ofadapters.1. Retrieve the code in the startup program:

RTVCLSRC PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC)SRCMBR(program-name)

2. Modify the source:PGM

DCL VAR(&STRWTRS) TYPE(*CHAR) LEN(1)DCL VAR(&CTLSBSD) TYPE(*CHAR) LEN(20)QSYS/STRSBS SBSD(QCMN)STRTCPMONMSG MSGID(CPF0000)


QSYS/STRSBS SBSD(QSERVER)MONMSG MSGID(CPF0000)STRTECADP EVTADP(SYSOPR)+CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR’)MONMSG MSGID(CPF0000)DONE:RETURNCHGVAR VAR(&CPYR) VALUE(&CPYR)

ENDPGM

3. Create the program and put it in the QSYS library:CRTCLPGM PGM(QSYS/program-name)

SRCFILE(QGPL/QCLSRC) SRCMBR(program-name)

Note: The startup program runs under user profile QPGMR. The defaultsetting is that QPGMR does not have authority to change the AS/400message adapter commands and programs. You must either grantQPGMR authority to change the commands and programs (see “Startingthe adapter” on page 105) or have the startup program adopt QSECOFRauthority and be owned by QSECOFR.

Multiple AS/400 message queuesTo support another AS/400 message queue, create the following additional files:v Configuration file: specifies a different message queue for the MsgQueue

keyword and any new filtersv CDS file: defines new classes to match the messages being monitoredv BAROC file: required if new classes are identified in the CDS file

Configuration fileTo create the configuration file, perform the following steps:1. Copy the adapter files using the following commands:

CPYF FROMFILE(QUSRSYS/CFG_MSG)TOFILE(QUSRSYS/MYFILE) FROMMBR(*ALL)TOMBR(*FROMMBR) CRTFILE(*YES)

2. Update the configuration file to show the keywords pointing to the new objectsas follows:AdapterCdsFile=/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCDS.MBR

MsgQueue=QUSRSYS/MYMSGQ

3. Update the CDS and the BAROC files to include any new classes and filters.4. On the event server, import the BAROC file into the rule base; then, compile

and load the rule base.5. Start the adapter using the new configuration files as follows:

STRTECADP EVTADP(MYEVTADP)CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCFG.MBR’)

Using FTP to run AS/400 commandsYou can run AS/400 commands from an FTP session. This can be useful forreplying to inquiry messages. The following is an example of how to use FTP toremotely respond to an AS/400 inquiry message based on the message key that ispart of the event string:quote "RCMD SNDRPY MSGKEY(X’00022A00’) MSGQ(QSYSOPR) RPY(’The reply’) RMV(*NO)”


Common tasksUse these commands to perform common tasks related to the AS/400 alert adapter.v To load the AS/400 alert and message adapters with English as a primary

language:RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) SAVF(QUSRSYS /ATMETEC)RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(1) SAVF(QUSRSYS /ATMETEC1)RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(2) SAVF(QUSRSYS /ATMETEC2)

v To load the AS/400 message and alert adapters with English as a secondarylanguage:RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) LNG(2924) SAVF(QUSRSYS/ATMETEC)RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(1) LNG(2924) SAVF(QUSRSYS/ATMETEC1)RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(2) LNG(2924) SAVF(QUSRSYS/ATMETEC2)

v To delete all AS/400 adapters from the AS/400 system:DLTLICPGM LICPGM(1TMETEC)

v To delete only the AS/400 message adapter from the AS/400 system:DLTLICPGM LICPGM(1TMETEC) OPTION(1) Delete the message adapter (lib QTMETECA01)

v To start the AS/400 message adapter:STRTECADP EVTADP(ADPNAME) CFGFILE(’QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR’)

v To stop the adapter:ENDTECADP EVTADP(ADPNAME)


Chapter 6. NetWare logfile adapter

The following sections contain reference information about the NetWare logfileadapter.

NetWare logfile adapter reference informationThe logfile adapter for NetWare forwards events from a NetWare server to theevent server. The NetWare logfile adapter can be registered with the startupconfiguration of the NetWare server so that the logfile adapter is started when theNetWare server is started.

NetWare server events are gathered from any ASCII log file residing on theNetWare server, such as the SYS:SYSTEM\SYS$LOG.ERR file.

The NetWare logfile adapter is a NetWare Loadable Module (NLM) process thatreads events generated on a NetWare server, formats them according tospecifications in the format file, and forwards them to the event server for furtherprocessing.

The NetWare logfile adapter can run silently, without its own screen, or it can runin the debugging mode that displays screen messages for diagnostic purposes.

Adapter filesThe NetWare server adapter package consists of the following files:

tecadnw4.nlmThe adapter service executable file

tecadnw4.cnfThe configuration file

tecadnw4.cdsThe class definition statement (CDS) file

tecadnw4.brcThe BAROC file

postmsg.nlmThe command line interface program to send an event to the event server

nwgencds.nlmThe command line interface program to generate a CDS file from a formatfile

tecadnw4.errThe error file

Before starting the server, ensure that the configuration file defines the preferredadapter behavior.

Error fileUse the error file to configure debugging and tracing options. This file is describedin detail in “Error file” on page 26.


Prefiltering NetWare eventsYou can improve the performance of the NetWare logfile adapter by filteringevents, so that only important events are processed. This is called prefiltering andapplies only to events logged to the SYS$LOG.ERR file.

To use the prefiltering mechanism, you specify the prefilter statements in theconfiguration file using a format similar to that used for adapter filters. Theprefiltering statements (PreFilter and PreFilterMode) are described in“Configuration file” on page 116.

You must stop and restart the adapter for any changes to take effect.

The following attributes define prefilter statements:

SourceSpecifies the source or module that logged the event to the NetWare serverlog file. You can specify up to 16 sources. Multiple sources must beseparated by commas. Examples include SERVER, DS, TIMESYNC, andUPS.

EventIdSpecifies the message number assigned by NetWare. You can specify up to16 message numbers. Message numbers must be separated by commas.EventId is unique for each source.

SeveritySpecifies the NetWare-defined severity of the event. You can specify up to16 severities. Multiple severities must be separated by commas.

Locus Specifies the NetWare-defined locus. You can specify up to 16 loci. Multipleloci must be separated by commas.

Class Specifies the NetWare-defined class. You can specify up to 16 classes.Multiple classes must be separated by commas.

The following are examples of prefiltering statements:PreFilter:Source=SERVER;EventId=10,20,30;PreFilter:Source=DS; Severity=11;Class=5;

Configuration fileThe configuration file defines the behavior of the NetWare logfile adapter. This filecan contain the common keywords listed in “Configuration file” on page 9, as wellas the following adapter-specific keywords:

LogSourcesSpecifies the ASCII log files to poll for messages. The complete path toeach file must be specified, and file names must be separated by commas;no spaces or other separators can be used. A logfile source need not existwhen the adapter is started; it is polled when it is created.

If a file is truncated while the adapter is active, the adapter automaticallysets its internal pointer to the new end of the file and continues processingall new messages that are written after the file was truncated. If during thepolling interval the file is overwritten, removed, or recreated with morelines than the previous poll, only the number of lines greater than the


previous line count is read. For example, the file has one line. After thepoll interval elapses, the file is overwritten with two lines. Only the secondline is read on the next polling.

The default file that the adapter polls is the SYS:SYTEM\SYS$LOG.ERRfile. Additional files can be specified with the LogSources keyword.

PollIntervalSpecifies the frequency, in seconds, to poll each log file listed in theLogSources keyword for new messages. The default value is 120 seconds.

PreFilterAn event matches a PreFilter statement when each attribute=valuespecification in the PreFilter statement matches a message in the log file. APreFilter statement must contain at least the log file specification, and cancontain up to three additional specifications: event ID, event type, andevent source. The order of the attributes in the statement does not matter.

You can specify multiple values for each attribute by separating each witha comma.

Each PreFilter statement must be on and contained in a single line, nogreater than 512 characters.

The PreFilter keyword is optional. All NetWare server log events are sentto the adapter if prefilters are not specified.

PreFilterModeSpecifies whether NetWare server log events that match a PreFilterstatement are sent (PreFilterMode=IN) or ignored (PreFilterMode=OUT).Valid values are IN, in, OUT, or out. The default value is OUT.

The PreFilterMode keyword is optional; if PreFilterMode is not specified,only events that do not match any PreFilter statements are sent to theadapter.

If you set PreFilterMode=IN, make sure you have one or more PreFilterstatements defined as well.

Stop and restart the adapter for any changes to take effect.

Format fileThe format file contains message format descriptions and their mapping to BAROCevents. The message fields of a NetWare server event are matched against theformat descriptions in this file and when a match succeeds, the corresponding IBMTivoli Enterprise Console event is generated by the adapter. The format filecontains predefined mappings for some common NetWare server events and canbe customized to add new messages.

A standard NetWare server event from the SYS$LOG.ERR file is written to anASCII message in the following sequence. Consult the appropriate NetWaremanuals for the meanings:v The date (month-day-year) and time; for example: 7-25-98 1:33:57 amv Module version-ID; for example: SERVER-4.11-25v Severity, locus, and class; for example: Severity=10 Locus=1 Class=5

Note: The meanings of severity and class are not the same as those pertaining tothe IBM Tivoli Enterprise Console product.

v The message text

Chapter 6. NetWare logfile adapter 117

The following example shows a formatted IBM Tivoli Enterprise Console eventderived from an error message issued by the NetWare Directory Service (DS):7-16-98 5:08:46 pm:DS-5.73-12 Severity=10 Locus=2 Class=5Synthetic Time is being issued on partition “NOVELL_TREE.”

For details about format files, see “Format file” on page 24.

Events listingThe tables in the next section show the class names and severities of all eventsdefined for the NetWare logfile adapter. You can use this information to get a senseof how NetWare events are mapped to IBM Tivoli Enterprise Console events andto determine whether you want to make any changes. The events are defined inthe BAROC file, which must be imported into the rule base. See the IBM TivoliEnterprise Console Rule Developer’s Guide for more information about customizingthe BAROC file.

Event class structureEvent classes are defined hierarchically, with child classes inheriting attribute valuedefaults from the parent. The NetWare server event classes follow a simplehierarchy. The adapter fills in the following attribute default values, as shown inthe following table. The attributes are used in event group filters.

Table 12. Default attribute values for event group filters

Attribute Default Value

source NW4

sub_source NW4

When an event from the SYS$LOG.ERR file is sent, the sub_source attribute is setto the module that logged the event (for example, DS or SERVER). The defaultevent classes define the following attributes:

nw_msg_versionThis is the version of the module (sub_source) that is logging the message,for example, 4.10, 1.0, and so on.

nw_msg_idThis is an integer value specifying the message ID. A message ID is uniquewithin each sub_source.

alert_severitySpecified as an integer from zero (0) to 6, this value indicates the severitylevel defined by NetWare. The mapping between the NetWarealert_severity and Tivoli Enterprise Console severity level is defined inthe following table.

Alert Severity Definition Severity Level

0 (Informational) Counters or gauges reachedthresholds.

HARMLESS

1 (Warning) Configuration errors, and soon. No damage.

WARNING

2 (Recoverable) Hot Fix, and so on.Workaround made.

MINOR


Alert Severity Definition Severity Level

3 (Critical) Disk Mirror failure, and soon. Fix attempted.

CRITICAL

4 (Fatal) Resource fatally affected;shutdown.

FATAL

5 (Operation Aborted) The operation cannotcomplete.

FATAL

6 (Non OS unrecoverable) The operation cannotcomplete.

FATAL

alert_locusSpecified as an integer from zero (0) to 20, this value indicates the locationof the alert, as defined in the following table:

Alert_locus NetWare Definition

0 Unknown

1 Memory

2 File system

3 Disks

4 Lanboards

5 Comstacks

7 TTS

8 Bindery

9 Station

10 Router

11 Locks

12 Kernel

13 UPS

14 Service Protocol

15 SFTIII

16 Resource Tracking

17 NLM

18 OS Information

19 Cache

20 Domain

alert_classSpecified as an integer from zero (0) to 21, this value indicates the NetWarealert classes as defined in the following table:

Alert_class NetWare Definition

0 Unknown

1 Out of resource

2 Temporary situation

3 Authorization failure

4 Internal error


Alert_class NetWare Definition

5 Hardware failure

6 System failure

7 Request error

8 Not found

9 Bad format

10 Locked

11 Media failure

12 Item exists

13 Station failure

14 Limit exceeded

15 Configuration error

16 Limit almost exceeded

17 Security audit information

18 Disk information

19 General information

20 File compression

21 Protection violation

The following NetWare events are defined in the BAROC file:

Table 13. NetWare events


NW4_Base UNKNOWN

NW4_SysLog_Base UNKNOWN

NW4_ClassUnknown UNKNOWN

NW4_OutOfResource UNKNOWN

NW4_TempSituation UNKNOWN

NW4_AuthorizationFailure UNKNOWN

NW4_InternalError UNKNOWN

NW4_HardwareFailure UNKNOWN

NW4_SystemFailure UNKNOWN

NW4_RequestError UNKNOWN

NW4_NotFound UNKNOWN

NW4_BadFormat UNKNOWN

NW4_Locked UNKNOWN

NW4_MediaFailure UNKNOWN

NW4_ItemExists UNKNOWN

NW4_StationFailure UNKNOWN

NW4_LimitExceeded UNKNOWN

NW4_ConfigurationError UNKNOWN

NW4_LimitAlmostExceeded UNKNOWN


Table 13. NetWare events (continued)


NW4_SecurityAuditInfo UNKNOWN

NW4_DiskInformation UNKNOWN

NW4_GeneralInformation UNKNOWN

NW4_FileCompression UNKNOWN

NW4_ProtectionViolation UNKNOWN

NW4_AppMessage UNKNOWN

NW4_NLM_Loading UNKNOWN

NW4_NLM_Unloaded UNKNOWN

NW4_NLM_NotLoaded UNKNOWN

NW4_Abend UNKNOWN

tecadnw4.nlmThe NLM, tecadnw4.nlm, is the NetWare logfile adapter. The commands forloading and unloading the NLM are described on the following pages.


load tecadnw4Starts the NetWare logfile adapter in non-service mode.

Syntaxload tecadnw4 [–c ConfigFile] [–d]

DescriptionLoading tecadnw4.nlm starts the adapter. To stop the adapter, run the followingfrom the command line:unload tecadnw4

Authorization: None is required.

Arguments:

–c ConfigFileSpecifies the configuration file for the NetWare logfile adapter. If a value isnot specified, the TECADNW4.CNF file in the current directory is used. Ifthe –c argument is used, you can optionally specify a full path name forthe configuration file; otherwise, the default configuration file,SYS:ETC\TIVOLI\TECAD\ETC\ TECADNW4.CNF, is used.

–d Shows verbose diagnostic information in the NLM screen as events aregathered and transmitted. Press the Alt+Esc or Ctl+Esc keys to switch toother NLMs screens or to return to the console.

Note: Without the –d option, the adapter displays the initial startupmessages on its screen but closes it upon completion of initialization,and the adapter name is not displayed in the list of NLMs when theCtrl+Esc keys are pressed.

ExamplesThe following command starts the NetWare logfile adapter in debug mode:load tecadnw4 -d

The following command starts the NetWare logfile adapter with the myconf.cnfconfiguration file:load tecadnw4 -c sys:etc\tmp\myconf.cnf


Troubleshooting the NetWare logfile adapterPerform the following steps to troubleshoot the NetWare logfile adapter:1. Stop the NetWare logfile adapter that is currently running by unloading

tecadnw4.nlm:unload tecadnw4

2. Start the adapter in debug mode:load tecadnw4 -d -c Config_File

3. Generate some events and see if the adapter receives them.As events arrive, the adapter prints messages to the screen indicating the classand the attribute values in the class.

4. As messages are displayed, run the wtdumprl command on the event serverand verify that the messages are displayed or saved in the reception log. If not,the events were not received by the event server or there is a problem with theevent server reception process.

5. Check the adapter configuration file to verify that TransportList (orServerLocation and ServerPort) is properly defined. If the event class is in anyfilter entry in the configuration file, and FilterMode=OUT, the event is not sentto the event server.

6. If the reception log has a PARSING_FAILED error, the BAROC definition of theclass does not match the event that is being received from the adapter. Usuallythe error messages pinpoint the problem.

7. If the previous steps do not indicate any problems and you do not see the newevents in the event console, there might be a problem with the event groupfilters. Make sure the class filters match the classes defined in the BAROC files.

8. Change all /dev/null entries in the .err file to the file name you want. Stopand restart the adapter, send an event through, and then look in the trace file tosee what processing was done on the event.


Chapter 7. OpenView adapter

The IBM Tivoli Enterprise Console adapter for the Hewlett-Packard OpenView (HPOpenView) product forwards events from OpenView to the event server. Theadapter is registered with the startup configuration of the OpenView operatingsystem using ovaddobj, so it is started along with all the other applications thatuse the operating system. The OpenView ovspmd process manages the adapterand forwards all preferred events to the event server.

This chapter explains how to configure and start the OpenView adapter.

OpenView driverThe OpenView adapter collects OpenView trap messages that have been sent byOpenView trap daemon (ovtrapd) and processed by the ovspmd daemon. Theadapter translates the trap messages into the appropriate Tivoli Enterprise Consoleclass based on the entry that the trap matches in the CDS file.

Reception of OpenView messagesTo receive events generated by the OpenView Network Node Manager (NNM) andany events from all possible OpenView agents, the OpenView adapter registersitself into the NNM SUF startup file using the ovaddobj command. The ovspmddaemon reads SUF at startup and manages all the registered processes it finds,then receives events from the ovtrapd process and forwards the specified events tothe appropriate registered applications (such as the OpenView adapter).

The OpenView adapter must run as a well-behaved daemon process using theOVsPMD API (application programming interface) functions provided withOpenView. The OVsPMD API functions are used by object managers (agents) thatmust run as background processes in the OpenView program to be managed byovspmd, the process management daemon. The adapter interacts with ovspmdusing the SNMP API functions provided with OpenView NNM. This involves thefollowing steps:v In NNM 5, calling OVsnmpTrapOpen to establish a logical session with the

OVsnmpAPI to receive SNMP events through the OpenView Event Framework.v In NNM 6, calling OVsnmpEventOpen to establish a logical session with the

OVsnmpAPI to receive SNMP events through the OpenView Event Framework.v Calling OVsinit to get a socket for communication with the ovspmd process.v Calling OVslnitComplete to notify at the end of the initialization, the status of

the initialization process.v Calling OVsReceive to receive commands from the ovspmd process.v Calling OVsDone to notify ovspmd that the adapter is being shut down.

Determining the OpenView NNM versionTo determine which version of OpenView NNM you are running, use thefollowing command:$OV_BIN/ovnnmversion


Incoming messages formatMessages received from the ovtrapd process consist of SNMP Trap-PDUs asdefined in RFC 1157 (SNMPv l).

OpenView-specific events are defined as enterprise-specific traps and have thefollowing content:

enterprise1.3.6.1.4.1.11.2.17 for OpenView events

agent-addrSNMP agent or proxy agent address

generic-trap6

specific-trapNumber in the range 33554432 through 2147483647

time-stamp0

variable-bindingsThe adapter also receives SNMP traps because the ovtrapd process ismonitoring for any traps sent to port 162. The following list shows some ofthe specifics for OpenView events:

1. Descr:ObjId:Type:

OpenView Source ID number1.3.6.1.4.1.11.2.17.2.1.0INTEGER


OpenView Source Name1.3.6.1.4.1.11.2.17.2.2.0OCTET_STRING


OpenView Optional Object Id for event source1.3.6.1.4.1.11.2.17.2.3.0OCTET_STRING


Optional data1.3.6.1.4.1.11.2.17.2.4.0OCTET_STRING


Optional severity1.3.6.1.4.l.11.2.17.2.5.0OCTET_STRING


Optional category1.3.6 1.4.1.11.2.17.2.6.0OCTET_STRING

Event correlation with NNM 6You can configure the adapter to open a session with ovspmd so that ovspmdforwards only the correlated events you want to the adapter. This reduces theworkload on the adapter in proportion to the number of events discarded by theNNM circuit settings and therefore not forwarded to the adapter. If you arerunning NNM 5 or earlier, the adapter calls OVsnmpTrapOpen to open a session;with NNM 6 or later, the adapter calls OVsnmpEventOpen. OnlyOVsnmpEventOpen provides for event correlation of the events before they areforwarded to the adapter.

OVsnmpEventOpen contains a filter parameter that defines which events theapplication receives from ovspmd. A filter value of NULL or the empty string (“”)


prevents the adapter from receiving any events and makes the session a send-onlysession; therefore, this is not a recommended configuration. See the manual pagefor OVsnmpEventOpen for more information.

The configuration file keyword HPOVFilter passes the filter value you specify toOVsnmpEventOpen. HPOVFilter specifies what kind of events are forwarded tothe adapter from ovspmd and contains the value that is used for the filterparameter when calling the OVsnmpEventOpen API. If you have NNM 6 andHPOVFilter is not specified or is commented out, the default setting is for theadapter receives all events. For more information about HPOVFilter, see“Configuration file” on page 130.

Determining the OVsnmpEventOpen filter valueThe following examples show two ways to see how the value in HPOVFilter ispassed to OVsnmpEventOpen.v Example 1: NNM input event tracing is turned on and adapter tracing is turned

off.Look in the file $OV_LOG/ecs/<ecs-instance#>/ecsin.evt# and do a find onprevious tecad_hpov from the bottom of the file. The following example issimilar to what you can see (the filter in this example is {CORR{default}} .*):Trap-PDU {

enterprise {1 3 6 1 4 1 11 2 17 1},agent-addr internet : "\x92T$\057",generic-trap 6,specific-trap 59179056,time-stamp 0,variable-bindings {

{name {1 3 6 1 4 1 11 2 17 2 1 0},value simple : number : 14

},{

name {1 3 6 1 4 1 11 2 17 2 7 0},value simple : string : \ "{CORR{default}} .*"

},{

name {1 3 6 1 4 1 11 2 17 2 9 0},value application-wide : address : internet : "\x92T$\057"

},{

name {1 3 6 1 4 1 11 2 17 2 8 0},value simple : string : "tecad_hpov"

},{

name {1 3 6 1 4 1 11 2 17 2 10 0},value simple : number : 14128

}}

}% ber:Trap-PDU:

v Example 2: Adapter tracing is turned on by specifying output files in the .err fileinstead of /dev/null.You can find the NNM version and the specified filter value in the messagesdisplayed when you start the adapter. The messages are similar to the followingexample:Initializing T/EC interface ...T/EC interface initialization completeInitializing driver ...Initializing SNMP driver ...Running as a WellBehavedDaemon

Chapter 7. OpenView adapter 127

Enter in TECAD_OVsInit...HP NNM version running is: HP OpenView ov library \NNM Release B.06.10 @(#) PATCH PSOV_XXXXX, YYMMDD Oct 17 1999Stream filtering set to: {CORR{default}} .*

Testing toolsTo test the OpenView adapter, it is necessary to have OpenView installed on thesame system on which the adapter is running. Testing of the adapter behavior canbe achieved only by starting all daemon processes of OpenView and by sendingSNMP trap events to the ovtrapd process. Note that SNMP trap events can begenerated by sending SNMP traps to ovtrapd using the same testing tool as for theSNMP adapter.

With OpenView, it is also possible to simulate events occurring by usingsmnptrap(1), ovevent, or by using specific commands such as:v OV_Set_status_Color (specific trap number 58916871)v OV_Message (specific trap number 58916872)v OV_Popup_Message (specific trap number 58916873)v OV_Bell_Message (specific trap number 58916874)v OV_Highlight_Source (specific trap number 58916875)

An example using snmptrap(1) for creating a message and ringing a bell fromnode Bad_Node is presented as follows:snmptrap ’hostname’ \

1.3.6.1.4.1.11.2.17.1 ""6 58916874"" \1.3.6.1.4.1.11.2.17.2.1.0 Integer 14 \1.3.6.1.4.1.11.2.17.2.2.0 OctetString "Bad_Node" \1.3.6.1.4.1.11.2.17.2.4.0 OctetString "Bell Message"

Testing event correlation with NNM 6Stream and circuit tracing can help you see which events are to be forwarded tothe adapter. A stream with an output policy forwards any event unless you enableat least one circuit on the stream to discard a type of event. A stream with adiscard policy forwards an event only if you enable a circuit on the stream thatoutputs that type of event. An output file lists the forwarded events. For example,when a stream has an output policy, you can determine what events that thestream sent to the adapter by reading the events listed in the stream output file.

For complete details on streams and circuits, see the HP OpenView NNMdocumentation.

The following lists show some of the commands you can use with streams andcircuits:v To find details about the event correlation engine, use the following command:

ecsmgr -info

v To find details about event arrivals for the circuits and streams, use thefollowing command: ecsmgr -stats

v To turn on tracing to see the OpenView events received, use the followingcommand: ecsmgr -log_events input on

This trace file is located in $OV_LOG/ecs/<ecs-instance#>/ecsin.evt#v To turn on tracing to see the OpenView stream events received, use the

following command:ecsmgr -log_events stream <stream-name> on


The trace files for the stream output events are located in $OV_LOG/ecs/<ecs-instance#>/<stream-name>_sout.evt#

The trace files for the discarded stream events are located in$OV_LOG/ecs/<ecs-instance#>/<stream-name>_sdis.evt#

The following example turns on stream event tracing for a stream nameddefault:ecsmgr -log_events stream default on

v To turn on tracing to see the OpenView circuit events received, use the followingcommand:ecsmgr -log_events circuit <circuit-name> on

The trace files for the circuit output events are located in $OV_LOG/ecs/<ecs-instance#>/<circuit-name>_cout.evt#

The trace files for the discarded circuit events are located in$OV_LOG/ecs/<ecs-instance#>/<circuit-name>_cdis.evt#

The following example turns on circuit event tracing for a stream namedPairWise:ecsmgr -log_events circuit PairWise on

Event correlation exampleThe following event passes through circuits named PairWise and ConnectorDown.When the HPOVFilter value passed to OVsnmpEventOpen is .*, the event isforwarded to the adapter because the stream default is not being used. If theHPOVFilter value is {CORR{default}} .*, you can see the event only in the circuitdiscard trace file.snmptrap <boxname> "1.3.6.1.4.1.11.2.17.1" 146.84.36.175 6 40000084 0 \1.3.6.1.4.1.11.2.17.2.1.0 integer 7 \1.3.6.1.4.1.11.2.17.2.2.0 octetstringascii "snmp trap for connector down"

Note: You must watch the circuit and stream trace files to see when this event isdiscarded. This event sometimes is sent to the adapter instead. Keep themessage text changing slightly so that you can identify a specific event.Also, send multiple events until the discard trace file for the stream defaultshows the event is discarded, which indicates that the event was not sent tothe adapter.

The following event is sent to the adapter when HPOVFilter is set to{CORR{default}} .*:/opt/OV/bin/ovevent -s Major -c "Error Events" "" \

.1.3.6.1.4.1.11.2.17.1.0.58916872 \.1.3.6.1.4.1.11.2.17.2.1.0 Integer 14 \.1.3.6.1.4.1.11.2.17.2.2.0 OctetString "user@host" \.1.3.6.1.4.1.11.2.17.2.4.0 OctetString "major error message"

Adapter filesThe OpenView adapter package consists of the following files in the followingdirectories:v $TECADHOME/bin

tecad_hpov.cfgThe installation configuration script.


tecad_hpovThe adapter executable file.

tecad_hpov.shThe adapter shell script to set the environment and call the adapterexecutable file.

v $TECADHOME/etc

tecad_hpov.barocThe adapter BAROC file to define the classes to the rule base.

tecad_ov.barocAn additional BAROC file that precedes tecad_hpov.baroc in therulebase definitions to define the enumerations that tecad_hpov.barocuses.

tecad_hpov.cdsThe class definition statement (CDS) file. This file defines the adapterclass definitions.

tecad_hpov.confThe configuration file. This file defines the adapter startup configuration.

tecad_hpov.errThe error file. This file indicates where to write adapter trace messages.

tecad_hpov.lrfThe registration file. This file is generated by the installationconfiguration script and placed in the $OV_LRF directory. For UNIX, thedirectory is usually /opt/OV/share/lrf. For Microsoft Windows systems,the directory is usually c:/Openview/LRF/tecad_hpov.lrf.

tecad_hpov.oidThe object identifier file. This file matches object identifiers to variablenames.

ov_default.rlsThe default rule file for the OpenView adapter used in the rule base.

Before starting the adapter, check each adapter file to ensure that they define thepreferred adapter behavior.

Configuration fileThe configuration file of the OpenView adapter defines the behavior of the adapter,which runs as a server daemon. The configuration file can have common keywordsdescribed in “Configuration file” on page 9, as well as the followingadapter-specific keywords:

AdapterSpecificFile=pathSpecifies the full path name of the object identifier file. This keyword isrequired if the object identifier file is not in the same directory as theconfiguration file.

HPOVFilter=filterSpecifies the events the adapter receives from OpenView NNM 6. Thisvalue is ignored with OpenView NNM 5. The adapter can accept up to4096 bytes for this parameter; you must specify the value in onecontinuous line of input with no intervening line returns. Do not enclosethe value in quotation marks; if you enclose the value in quotation marksand turn on adapter tracing, the trace file displays the following error:


Stream filtering set to: "{CORR{default}} .*"Enter in TECAD_OVsInit...Unable to initialize SNMP session system error: Invalid event \filter (Filter parameter (""{CORR{default}}.*"") event \specification must be "" or start with a ’.’)Unable to initialize SNMP session system error: Bad file numberEnter in TECAD_OVsInitComplete...can not initialize specific driver

The adapter also fails to initialize, and ovspmd sends the followingmessage:# ovstart tecad_hpovobject manager name: tecad_hpovstate: FAILEDPID: 12901last message: Unable to initialize SNMP sessionsystem \error: Bad file numberexit status: -

Turn on adapter tracing when you change the value for HPOVFilter tomake sure that the value was specified correctly or to see the errorsgenerated by it.

See the manual page for OVsnmpEventOpen for details on HPOVFilterand the filter parameter.

WellBehavedDaemonSpecifies whether the adapter runs as an OpenView well-behaved daemon.This value should always be TRUE.

Class definition statement fileThe CDS file defines how events are constructed from the information that is sentby OpenView. It is described in detail in “Class definition statement file” onpage 25 and in Appendix C, “Class definition statement file reference”, on page 197.

Errors in the .cds file definitions cause the adapter to not start successfully, whichoften causes the adapter to exit with an exit (1). Therefore, change one definitionat a time and restart the adapter after each change to ensure that the newdefinition works. If you make many changes before restarting the adapter, it ismore difficult to troubleshoot any problems; turning on adapter tracing helps youlocate the errors.

OpenView event exampleThe class definition in the following example is taken from the .cds file:CLASS_OV_IF_FAULTSELECT1:ATTR(=,ENTERPRISE),VALUE(PREFIX, \"1.3.6.1.4.1.11.2.17.1");2:$SPECIFIC=40000000;3:ATTR(=, "openViewSourceName");4:ATTR(=, ’openViewData3");5:ATTR(=, "openViewData4");MAPorigin=$V3;sub_origin=$V4;severity=WARNING;OV_status=2; # Marginal


KeywordsThe OpenView adapter supports the use of the following keywords in classdefinition statements. These keywords can be useful if you want to customizeevents.

$COMMUNITYSpecifies the trap community string.

$ENTERPRISESpecifies the enterprise object identifier of the object generating thetrap.

$SOURCE_TIMESpecifies the value of sysUpTime of the object generating the trap.

$TYPE Specifies the generic trap type number (0-6).

$SPECIFIC Specifies the enterprise-specific trap type number.

$SOURCE_ADDRSpecifies the address of the object sending the trap.

$AGENT_ADDRSpecifies the address of the object generating the trap.

$VARBIND Specifies a list of all non-fixed attributes.

$VB_NUM_VARSSpecifies the number of elements in $VARBIND.

$ADAPTER_HOSTThe name of the host system where the adapter runs.

The following example shows how you can use the keywords:FETCH

1: IPNAME($SOURCE_ADDR);

SELECT1: ATTR(=, $ENTERPRISE);

Built-in variables for $VARBIND: $VARBIND is a list of all non-fixed attributes.To access the individual elements of $VARBIND, use the VB_# variables, where # isa number greater than 0. For example, if $VARBIND has three elements, you canuse VB_1, VB_2, and VB_3 as variables to access the data. The following exampleperforms string functions on the elements of $VARBIND.ATTR(=, "VB_1"), VALUE(CONTAINS, "some string")

Because $VARBIND is a list of strings, if it contains more than one element,performing a string function like CONTAINS against $VARBIND causes theadapter to stop unexpectedly.

Object identifier fileThe object identifier file maps object identifiers used by SNMP to names. Nochanges are necessary before the adapter is run.

Each line of this file has the following form:

"name" "object_identifier"

For example"sysUpTime" "1.3.6.1.2.1.1.3"


"ifIndex" "1.3.6.1.2.1.2.2.1.1"

"whyReload" "1.3.6.1.4.1.9.2.1.2"

Note: Object identifiers must occur in increasing order.

You can use the names that are mapped to object identifiers in the CDS file.

Error fileUse the error file to configure debugging and tracing options. This file is describedin detail in “Error file” on page 26.

LRF fileThe .lrf file registers the application when the NNM application starts up. The .lrffile is created and registered automatically when the adapter is installed. Fordetails on the syntax of the file, see the OpenView NNM documentation.

If you need to make changes to the tecad_hpov.lrf file, follow these steps:1. Stop the adapter.2. Change the .lrf file as needed and save it.3. Register the change with NNM by using $OV_BIN/ovaddobj

$OV_LRF/tecad_hpov.lrf.4. Restart the adapter.

If the tecad_hpov.lrf file has errors, the adapter might not start successfully.

Starting and stopping the adapterIf you have configured the host start-up file correctly, the adapter always startswhen the OpenView operating system starts up. You can also start an adaptermanually. When the adapter starts up, it gets new bindings, reads its adapter files,and restarts the daemon.

Use the following commands to start and stop the adapter. You can access theOpenView NNM environment variables by sourcing the NNM environment usingthe ov.envvars.sh file in the /bin directory in the OpenView NNM installationdirectory.. /opt/OV/bin/ov.evvars.sh # source the unix/bash environment

/opt/OV/bin/ov.envvars.bat # source the MS-DOS environment

$OV_BIN/ovstop tecad_hpov # stop the OpenView adapter

$OV_BIN/ovstart tecad_hpov # start the OpenView adapter

Events listingThe following table shows the class names and severities of all events defined forthe OpenView adapter. You can use it to get a sense of how OpenView events aremapped to Tivoli Enterprise Console events and to determine if you want to makeany changes. The events are defined in the BAROC file. See the IBM TivoliEnterprise Console Rule Developer’s Guide for more information about customizingthe BAROC file.


Event class structureEvent classes are defined hierarchically, with child classes inheriting defaultattribute values from the parent. The OpenView event classes follow a simplehierarchy.

The adapter fills in the following attribute default values. The attributes are usedin event group filters.

sourceHPOV

sub_sourceNET

originhostIPaddress where the event originated

hostnamehostname where the event originated

adapter_hostHost on which the adapter runs

forwarding_agentProxy agent that forwarded the event to the adapter

Additional information is provided where possible by using OpenView categoryand status codes. See the ENUMERATION statements at the beginning of theBAROC file for details.

The following table shows events defined in the BAROC file.

Table 14. OpenView events


OV_Event WARNING

OV_Bad_Subnet_Mask WARNING

OV_CMIS_Event WARNING

OV_Change_Polling_Period WARNING

OV_Chg_IF_Segment WARNING

OV_Connection_Added WARNING

OV_Connection_Deleted WARNING

OV_DataCollectThresh WARNING

OV_DataCollect_Rearm HARMLESS

OV_Error WARNING

OV_Fatal_Error FATAL

OV_Forw_Status_Chg MINOR

OV_IF_Added WARNING

OV_IF_Deleted WARNING

OV_IF_Descr_Chg MINOR

OV_IF_Fault WARNING

OV_IF_Down FATAL

OV_IF_Flags_Chg WARNING


Table 14. OpenView events (continued)


OV_IF_Type_Change MINOR

OV_Manage_IF WARNING

OV_Manage_Network WARNING

OV_Manage_Node WARNING

OV_Manage_Segment WARNING

OV_Network_Added HARMLESS

OV_Network_Deleted WARNING

OV_Network_Fault WARNING

OV_Network_Critical CRITICAL

OV_Network_Marginal WARNING

OV_Network_Normal HARMLESS

OV_Network_Flg_Chg WARNING

OV_No_SNMP_Reply CRITICAL

OV_Node_Added WARNING

OV_Node_Deleted WARNING

OV_Node_Fault FATAL

OV_Node_Down WARNING

OV_Node_Marginal WARNING

OV_Node_Flags_Chg WARNING

OV_Object_ID_Chg MINOR

OV_Phys_Addr_Chg MINOR

OV_Phys_Addr_Mismatch MINOR

OV_Segment_Added HARMLESS

OV_Segment_Deleted WARNING

OV_Segment_Fault WARNING

OV_Segment_Critical CRITICAL

OV_Segment_Marginal WARNING

OV_Segment_Normal HARMLESS

OV_Segment_Flag_Chg WARNING

OV_Subnet_Mask_Chg MINOR

OV_Sys_Contact_Chg HARMLESS

OV_Sys_Descr_Chg HARMLESS

OV_Sys_Location_Chg HARMLESS

OV_Sys_Name_Chg HARMLESS

OV_Unmanage_IF WARNING

OV_Unmanage_Network WARNING

OV_Unmanage_Node WARNING

OV_Unmanage_Segment WARNING

HPOV_Event WARNING

OV_ARP_Chg_New_Phys_Addr WARNING


Table 14. OpenView events (continued)


OV_ARP_Phys_Chg_Same_Src WARNING

OV_AppUngracefulExit WARNING

OV_Application_Alert WARNING

OV_Application_Down WARNING

OV_Application_Up WARNING

OV_Bad_Forw_To_Host WARNING

OV_Bad_Phys_Address WARNING

OV_ConnectionUnknown WARNING

OV_Connection_Down FATAL

OV_DataCollect_Check WARNING

OV_IF_Disconnected WARNING

OV_IF_IP_Addr_Chg WARNING

OV_IF_Unknown WARNING

OV_Map_Change WARNING

OV_Network_IPAddrChg WARNING

OV_Network_Name_Chg WARNING

OV_Network_SubMskChg WARNING

OV_Network_Unknown WARNING

OV_Node_SupportsSNMP WARNING

OV_Node_Unknown WARNING

OV_Segment_Unknown WARNING

OV_Trap_PDU_Error WARNING

OpenView traps

SNMP trapsAll SNMP generic traps and enterprise-specific traps supported by the SNMPadapter are also supported by the OpenView adapter.

OpenView trapsOpenView events are SNMP traps, and their content has been described within“OpenView driver” on page 125.

The specific-trap is the number identifying the sub-type of the trap. For OpenViewevents, the following list is used:

50462720 Warnings

50790400 Node Marginal

50790401 Segment Normal

50790402 Segment Marginal

50790403 Network Normal

50790404 Network Marginal


50790405 Segment Added

50790406 Segment Deleted

50790407 Network Added

50790408 Network Deleted

50790409 Connection Added

50790410 Connection Deleted

50790411 Change Polling Period

50790412 Forced Poll

50790418 Manage Node

50790419 Unmanage Node

50790420 Manage Segment

50790421 Unmanage Segment

All OpenView events are supported by the OpenView adapter.

Troubleshooting the OpenView adapterPerform the following steps to troubleshoot the OpenView adapter:1. Make sure that the tecad_hpov.lrf entry is correct and has been registered with

OpenView using the ovaddobj command.2. If the adapter does not start, look for errors in the .lrf, .oid, and .cds files.3. If the adapter stops unexpectedly, look for data that is not valid being passed

in a trap or functions. For example, PREFIX is called on a list of strings valueinstead of a string value.


5. Look in /tmp/hpov_start.err for possible startup errors from the tecad_hpov.shscript.


Chapter 8. OS/2 adapter

The Tivoli Enterprise Console adapter for OS/2 forwards events from an OS/2system to the event server. The adapter is registered with the startup configurationof OS/2 so that the adapter is started with all the other applications that areautomatically started when OS/2 is started.

The adapter is an OS/2 process that reads events generated by an OS/2 systemand forwards them to an event server for further processing.

OS/2 events are gathered from the First Failure Support Technology™ (FFST™)system, and from ASCII log files residing on the OS/2 system. The adaptertranslates a certain type of FFST events into IBM Tivoli Enterprise Console eventsand sends them to the event server. There are three types of FFST events: DET1,DET2, and DET4. DET1 events represent error conditions and are the only typesent to the event server. Entries in the ASCII log files are formatted according tothe format file.

This chapter describes how to configure and start the OS/2 adapter.

Adapter filesThe OS/2 adapter package consists of the following files:

readme The readme file.

tecadcfg.cmd The startup configuration script.

tecadini.sh The script to start or stop the adapter.

tecadrm.sh The TME adapter uninstall script.

tec_uninstal.cmdThe non-TME adapter uninstall batch file.

install.exe The adapter installation assist executable file.

tecados2.exe The adapter executable file.

tecados2.conf The configuration file.

tecados2.fmt The format file.

tecados2.cds The class definition statement (CDS) file.

tecados2.baroc The BAROC file.

tecados2.err The error file.

Configuration fileThe configuration file defines the behavior of the adapter. This file can contain thecommon keywords described in “Configuration file” on page 9, as well as thefollowing adapter-specific keywords:

LogSourcesSpecifies the ASCII log files to monitor for messages. The complete path toeach file must be specified, and file names must be separated by commas;no spaces or other separators can be used. A log file source need not existwhen the adapter is started; it is monitored when it is created.


If a file truncates while the adapter is active, the adapter automaticallyresets its internal pointer to the beginning of the file. If during the pollinginterval the file is overwritten, removed, or recreated with more lines thanthe previous poll, only the number of lines greater than the previous linecount is read. For example, the file has one line. After the poll intervalelapses, the file is overwritten with two lines. Only the second line is readon the next polling.

UnmatchLogSpecifies a file to log discarded events that cannot be parsed into an IBMTivoli Enterprise Console event class by the adapter. The discarded eventscan then be analyzed to determine if modifications are needed to theadapter format file.

Format fileThe format file contains message format descriptions and their mapping to BAROCevents. The message fields of an OS/2 event are matched against the formatdescriptions in this file and when a match succeeds, the corresponding IBM TivoliEnterprise Console event is generated by the adapter. The format file containspredefined mappings for some common OS/2 events and can be customized toadd any new messages.

The OS/2 adapter extracts the following information from an FFST event:v Date of the eventv Name of the host that issued the eventv Process name associated with the eventv Severity of the eventv Probe IDv Module namev Message text

For details about format files, see “Format file” on page 24 and Appendix B,“Format file reference”, on page 187.

Starting the adapterThe default action is for the adapter to be started when OS/2 is started. Tomanually start the adapter, perform the following steps from the OS/2 desktop:1. Open the System folder.2. Open the Startup folder.3. Double-click the TEC Adapter icon.

Note: The endpoint version of the adapter is started when the adapterconfiguration profile is distributed using the Adapter Configuration Facility.Non-TME adapters are started during adapter installation.

You can also manually start the adapter by entering the following commandsequence from the OS/2 command line:sh %LCF_BINDER%/../TME/TEC/ADAPTERS/BIN/tecadini.sh start


Stopping the adapterYou can manually stop the endpoint adapter by sourcing the endpointenvironment, and then entering the following command sequence from the OS/2command line:sh %LCF_BINDIR%/../TME/TEC/ADAPTERS/BIN/tecadini.sh stop

You can manually stop the non-TME adapter from the OS/2 command line withthe following command sequence:%INSTALL_DIR%\BIN\WOS2KILL.EXE -a

Events listingThe following table shows the class names and severities of all events defined forthe OS/2 adapter. You can use it to get a sense of how OS/2 events are mapped toTivoli Enterprise Console events and to determine if you want to make anychanges. The events are defined in the BAROC file.

See the IBM Tivoli Enterprise Console Rule Developer’s Guide for more informationabout customizing a BAROC file.

Event class structureEvent classes are defined hierarchically, with child classes inheriting attribute valuedefaults from the parent. The OS/2 event classes follow a simple hierarchy.


source OS2

sub_sourceOS2

The following events are defined in the BAROC file:

Table 15. OS/2 events


OS2_Base 4 (WARNING)

OS2_FFST_Base 4 (WARNING)

The severity is set using numeric values in the format file, which you can modifyto set the severity of a specific message. The following table shows the numericvalues and their literal values:

Numeric Value Literal Value

1 FATAL

2 CRITICAL

3 MINOR

4 WARNING

5 UNKNOWN

6 HARMLESS

Chapter 8. OS/2 adapter 141

Troubleshooting the OS/2 adapterPerform the following steps to troubleshoot the OS/2 adapter:1. Stop the OS/2 adapter that is currently running. See “Stopping the adapter” on

page 141 for details.2. Add a LogSources=c:\check.txt entry in the configuration file.3. Start the adapter as described in “Starting the adapter” on page 140.4. Add a few lines to c:\check.txt.5. Run the wtdumprl command on the event server and verify that the messages

are actually showing up in the reception log. If not, the events were notreceived by the event server or there is a problem with the event serverreception process. Check the adapter configuration file to verify thatTransportList (or ServerLocation and ServerPort) is properly defined. If theevent class is in any filter entry in the configuration file, the event is not sent tothe server. The administrator who started the adapter must have the requiredroles if running the TME version of the adapter. For a TME adapter, runningthe odstat command can offer some clues as to what could have failed.

6. If the reception log has a PARSING_FAILED error, the BAROC definition of theclass does not match the event that is being received from the adapter. Usuallythe error messages pinpoint the problem. If the previous steps do not indicateany problems and you do not see the new events in the Tivoli EnterpriseConsole product, there might be a problem with the event group filters. Makesure the class filters match the classes in the BAROC file.

7. Change all /dev/null entries in the .err file to the file name you want. Stop andrestart the adapter, send an event through, and then look in the trace file to seewhat processing was done on the event.


Chapter 9. SNMP adapter

The Simple Network Management Protocol (SNMP) adapter for the IBM TivoliEnterprise Console product forwards events from SNMP traps to the event server.

This chapter explains how to configure and start the SNMP adapter.

SNMP driverThe SNMP adapter serves the function of collecting SNMP trap messages directlyfrom the SNMP trap socket of a host and translating SNMP traps into appropriateIBM Tivoli Enterprise Console class instances.

The SNMP manipulation routines make use of SNMP Research SNMP libraries.

Reception of SNMP messagesThe SNMP adapter receives SNMP traps by listening directly on socket udp/162 ofthe host it runs on.

Incoming messages formatMessages received on the udp/162 socket consist only of SNMP Trap-PDUs asdefined in RFC 1157 (SNMPv1). Other types of messages are discarded.

Server configurationSince the SNMP trap adapter listens on UDP socket 162 for incoming SNMP traps,it must be run as root. Also, UDP socket 162 must not already be in use by anotherSNMP manager, such as the trapd daemon for IBM NetView for AIX or the SNMPtrap daemon itself.

Adapter filesThe SNMP adapter package consists of the following files:

tecad_snmp.cfgThe installation script.

tecad_snmp The adapter executable file.

tecad_snmp.barocThe BAROC file.

tecad_snmp.cdsThe class definition statement (CDS) file.

tecad_snmp.confThe configuration file.

tecad_snmp.errThe error file.

tecad_snmp.oidThe object identifier file.

init.tecad_snmpThe adapter startup and shutdown script.


Before starting the adapter, check each adapter file to determine if it defines thebehavior you want from the adapter.

Configuration fileThe configuration file defines the behavior of the adapter, which runs as a serverdaemon. The configuration file can have the common keywords described in“Configuration file” on page 9, as well as the following adapter-specific keywords:

AdapterSpecificFile=pathSpecifies the full path name of the object identifier file. Thiskeyword is required if the object identifier file is not in the samedirectory as the configuration file.

SNMP_PORT Specifies the port where the adapter listens for SNMP requests.

SNMP_TRAP Specifies the port where the adapter listens for SNMP traps. Onlychange this value if the producers of events are configured to sendto the alternate port.

Class definition statement fileThe CDS file defines how events are constructed from information sent by SNMP.It is described in detail in “Class definition statement file” on page 25 and inAppendix C, “Class definition statement file reference”, on page 197.

SNMP event exampleCLASS Port_Segmenting_CBTSELECT

1:ATTR(=,$ENTERPRISE),VALUE(PREFIX, "1.3.6.1.4.1.52") ;2:$SPECIFIC=258 ;3:ATTR(=,"boardIndex") ;4:ATTR(=,"portIndex") ;

FETCH1:IPNAME($SOURCE_ADDR) ;

MAPhostname=$F1 ;boardIndex=$V3 ;portIndex=$V4 ;sub_origin=PRINTF("board %s, port %s", $V3, $V4) ;status=CLOSED ;

END

KeywordsTo customize events, use the following keywords in class definition statements.Event definition content and syntax are described in the IBM Tivoli EnterpriseConsole Rule Developer’s Guide.

$COMMUNITYSpecifies the trap community string.

$ENTERPRISESpecifies the enterprise object identifier of the object generating thetrap.

$SOURCE_TIMESpecifies the value of sysUpTime of the object generating the trap.

$TYPE Specifies the generic trap type number (0-6).

$SPECIFIC Specifies the enterprise-specific trap type number.

$SOURCE_ADDRSpecifies the address of the object sending the trap.


$AGENT_ADDRSpecifies the address of the object generating the trap.

$VARBIND Specifies a list of all non-fixed attributes.

$VB_NUM_VARSSpecifies the number of elements in $VARBIND.

$ADAPTER_HOSTThe name of the host system where the adapter runs.

Built-in variables for $VARBIND: $VARBIND is a list of all non-fixed attributes.To access the individual elements of $VARBIND, use the VB_# variables, where # isa number greater than zero (0). For example, if $VARBIND has three elements, youcan use VB_1, VB_2, and VB_3 as variables to access the data. The followingexample performs string functions on the elements of $VARBIND:ATTR(=, "VB_1"), VALUE(CONTAINS, "some string")

Because $VARBIND is a list of strings, if it contains more than one element,performing a string function like CONTAINS against $VARBIND causes theadapter to end unexpectedly.

Object identifier fileThe object identifier file maps object identifiers used by SNMP to names. Nochanges are necessary before the adapter is run.

Each line of this file has the following form:

"name" "object_identifier"

For example"sysUpTime" "1.3.6.1.2.1.1.3"

"ifIndex" "1.3.6.1.2.1.2.2.1.1"

"whyReload" "1.3.6.1.4.1.9.2.1.2"

Note: Object identifiers must be shown in increasing order.

You can use the names that are mapped to object identifiers in the CDS file.

Error fileUse the error file to configure debugging and tracing options. The error file isdescribed in detail in “Error file” on page 26.

Starting and stopping the adapterThe default action is for the adapter to always be started when the host starts. Youcan also cold start or warm start an adapter manually. A cold start causes theadapter to get new bindings, read its adapter files, and restart the daemons. Awarm start causes the server only to re-read its adapter files.

Unless explicitly defined in the configuration file, the adapter searches for the CDS,error, and object identifier files in the same directory as the configuration file.

Chapter 9. SNMP adapter 145

Cold startThe endpoint adapter is automatically started as a step in the adapter installationprocess when the adapter configuration profile is distributed using the AdapterConfiguration Facility.

Manually start the adapter on the endpoint with the following command:init.tecad_snmp start

Warm startYou can restart a running adapter. Doing so is useful when you have changed oneof the adapter files and want to have it read in without bringing the adapter orhost down completely.

Use one of the following kill commands to force the adapter to restart:# kill -HUP process_number

—OR—# kill -1 process_number

Stopping the adapterYou can configure each adapter configuration record to perform actions onsubscribing endpoints upon distribution. You can configure actions that are to beperformed both before and after configuration files are written. Actions performedbefore file distribution can stop an event adapter and possibly remove the contentsof a configuration directory. Actions performed after file distribution can restart theadapter.

You can automatically stop the endpoint adapter by distributing an adapterconfiguration profile that has the adapter start command removed from theafter-file-distribution actions. See Chapter 3, “Adapter Configuration Facility”, onpage 45 for additional information.

Manually stop the adapter on the endpoint with the following command:init.tecad_snmp stop

Events listingThe following table shows the class names and severities of all events defined forthe SNMP adapter. You can use it to get a sense of how SNMP traps are mappedto Tivoli Enterprise Console events and to determine if you want to make anychanges. The events are defined in the BAROC file.


Event class structureEvent classes are defined hierarchically, with child classes inheriting attribute valuedefaults from the parent. The SNMP event classes follow a simple hierarchy.

The adapter fills in the following attribute defaults. The attributes are used inevent group filters.

sourceSNMP


sub_sourceNET

originhostIPaddress where the event originated


adapter_hostHost on which the adapter runs

forwarding_agentProxy agent that forwarded the event to the adapter

Additional information is provided where possible by using interface type andTCP connection status codes. See the ENUMERATION statements at the beginningof the BAROC file for details.

The following events are examples of the ones defined in the BAROC file:

Table 16. SNMP events

Event Class Event Severity

SNMP_Trap WARNING

Generic_SNMP_Trap WARNING

Cold_Start WARNING

Cold_Start_Cisco WARNING

Warm_Start WARNING

Link_Down FATAL

Link_Down_Cisco WARNING

Link_Up HARMLESS

Authentication_Failure WARNING

Authentication_Failure_Cisco WARNING

EGP_Neighbor_Loss CRITICAL

EGP_Neighbor_Loss_Cisco WARNING

Specific_SNMP_Trap WARNING

CBT_Trap WARNING

Port_Segmenting_CBT WARNING

Port_Link_Down_CBT WARNING

Source_Address_New_CBT WARNING

Source_Address_Timeout_CBT WARNING

Board_Removal_CBT WARNING

Board_Insertion_CBT WARNING

Active_Port_In_Redundant_Circuit_Failed_CBT

WARNING

Redundant_Port_Activated_CBT WARNING

Redundant_Port_Test_Failed_CBT WARNING

Device_Traffic_Threshold_Exceeded_CBT WARNING

Device_Error_Threshold_Exceeded_CBT WARNING


Table 16. SNMP events (continued)

Event Class Event Severity

Device_Collision_Threshold_Exceeded_CBT WARNING

Board_Traffic_Threshold_Exceeded_CBT WARNING

Board_Error_Threshold_Exceeded_CBT WARNING

Board_Collision_Threshold_Exceeded_CBT WARNING

Port_Traffic_Threshold_Exceeded_CBT WARNING

Port_Error_Threshold_Exceeded_CBT WARNING

Port_Collision_Threshold_Exceeded_CBT WARNING

Port_Type_Changed_CBT WARNING

Lock_Status_Changed_CBT WARNING

Port_Security_Violation_CBT WARNING

Port_Violation_Reset_CBT WARNING

Env_Temperature_CBT WARNING

Cisco_Trap WARNING

Reload_Cisco WARNING

TCP_Connection_Close_Cisco HARMLESS

The tecad_snmp.baroc file contains a complete listing of events including NetWare,Cisco, Cabeltron, and generic traps. Refer to the BAROC file for details.

Rules listingThere are no default rules for the SNMP adapter.

SNMP traps

Generic trapsAll SNMP generic traps (Cold_Start, Warm_Start, Link_Down, Link_Up,Authentication_Failure, Egp_Neighbor_Loss) are mapped to distinct event classes.

These generic SNMP event classes can be specialized to incorporate additionalinformation provided by some equipment. For instance, when a Cisco router issuesan Authentication_Failure trap, it provides an additional variable in the varbindlist that gives the protocol address of the device sending the badly authenticatedSNMP request. For Link_Down traps, Cisco routers provide additional informationdescribing which interface is going down and why it is going down. Since thecontent of the varbind list is not specified in the SNMP standard, it can vary fromone equipment to the next. This can impact the way event classes and subclassesare defined.

Enterprise-specific trapsBy definition, enterprise-specific traps vary from one equipment vendor to thenext.

Enterprise-specific traps can be handled by supporting Cisco routersenterprise-specific traps, as follows:

0 Reload


1 tcpConnectionClose

Additionally, enterprise-specific traps can be handled by supporting Cabletronhubs, as follows:

257 PortSegmenting

258 PortUnsegmenting

259 PortLinkUp

260 PortLinkDown

261 NewSourceAddress

262 SourceAddressTimeout

263 BoardRemoval

264 BoardInsertion

265 ActivePortInRedundantCircuitFailed

266 RedundantPortActivated

267 RedundantPortTesfFailed

268 DeviceTrafficThresholdExceeded

269 DeviceErrorThresholdExceeded

270 DeviceCollisionThresholdExceeded

271 BoardTrafficThresholdExceeded

272 BoardErrorThresholdExceeded

273 BoardCollisionThresholdExceeded

273 BoardCollisionThresholdExceeded

274 PortTrafficThresholdExceeded

275 PortErrorThresholdExceeded

276 PortCollisionThresholdExceeded

277 PortTypeChanged

278 LockSTATUSChanged

279 PortSecurityViolation

280 PortViolationReset

281 EnvTempWarm

282 EnvTempHot

283 EnvVoltageLow

Creating a new SNMP trap eventTo create a new SNMP trap event using an SNMP Management Information Base(MIB) file, change the following files:v tecad_snmp.barocv tecad_snmp.cdsv tecad_snmp.oid


This section describes traps from the LANAlert FSA for NetWare 3.x. Traps fromother agents are similar.

BAROC file changesFrom this partial MIB file, create a lanalertFSA-NW3-s1 event in thetecad_snmp.baroc file.-- LANAlert Forwarding Gateway MIB (partial)

-- NCI 27 June 1995

LANAlert-AFG-Trap DEFINITIONS ::=

BEGIN

IMPORTSenterprises FROM RFC1155-SMIOBJECT-TYPE FROM RFC-1212TRAP-TYPE FROM RFC1215;-- Network Computing Inc.nci OBJECT IDENTIFIER ::= { enterprises 768 }-- LANAlert alert packetslanalert OBJECT IDENTIFIER ::= { nci 2 }-- Agent-independent data itemslanalert-data OBJECT IDENTIFIER ::= { lanalert 2 }-- (NOTE: Some MIB processors have problems with the definition-- of lanalertFSA-NW2; this can be commented out if no-- NetWare 2.x File Server Agents are in use.)lanalert-agent OBJECT IDENTIFIER ::= { lanalert 3 }lanalertFSA-NW2 OBJECT IDENTIFIER ::= { lanalert-agent 0 }lanalertFSA-NW3o OBJECT IDENTIFIER ::= { lanalert-agent 1 }lanalertNA OBJECT IDENTIFIER ::= { lanalert-agent 2 }lanalertFSA-NW4o OBJECT IDENTIFIER ::= { lanalert-agent 3 }lanalertAFG OBJECT IDENTIFIER ::= { lanalert-agent 4 }lanalertFSA-NT OBJECT IDENTIFIER ::= { lanalert-agent 6 }lanalertSNMPMon OBJECT IDENTIFIER ::= { lanalert-agent 7 }lanalertMS OBJECT IDENTIFIER ::= { lanalert-agent 10 }lanalertFSA-NW3 OBJECT IDENTIFIER ::= { lanalert-agent 50 }lanalertFSA-NW4 OBJECT IDENTIFIER ::= { lanalert-agent 51 }

Agent-independent dataLANAlert alerts are assigned one of five priorities, from 1 (highest) through 5(lowest). The following values are used for the specific-trap field of AFG Trapprotocol data units (PDU) to represent the various priorities on set-alert andclear-alert messages. Pre-2.4.0 Management Servers do not identify the alertpriority when sending clears, so the value clear-unknown is used as thespecific-trap number in this case. Otherwise, one of the values clear-1 throughclear-5 is used to communicate the priority of a clear-alert message.

LANAlertPriority ::= INTEGER {set-1(1),set-2(2),set-3(3),set-4(4),set-5(5),clear-unknown(6),clear-1(7),clear-2(8),clear-3(9),clear-4(10),clear-5(11)

agentName OBJECT-TYPESYNTAX DisplayString (SIZE (1..15))ACCESS not-accessible


STATUS mandatoryDESCRIPTION

"The name of an agent reporting to a management server."::= { lanalert-data 1 }

nodeName OBJECT-TYPESYNTAX DisplayString (SIZE (1..15))ACCESS not-accessibleSTATUS mandatoryDESCRIPTION

"The name of a node on the monitored network.":= { lanalert-data 2 }

eventID OBJECT-TYPESYNTAX INTEGER (0..4294967295)ACCESS not-accessibleSTATUS mandatoryDESCRIPTION

"A number designating a monitored condition.":= { lanalert-data 3 }

thresholdID OBJECT-TYPESYNTAX INTEGER (1..4294967295)ACCESS not-accessibleSTATUS optionalDESCRIPTION

"A number designating a threshold set on amonitored condition."

:= { lanalert-data 4 }

alertText OBJECT-TYPESYNTAX DisplayString (SIZE (0..79))ACCESS not-accessibleSTATUS mandatoryDESCRIPTION

"A string describing an alert condition.":= { lanalert-data 5 }

managementServerName OBJECT-TYPESYNTAX DisplayString (SIZE (1..15))ACCESS not-accessibleSTATUS mandatoryDESCRIPTION

"The name of a LANAlert management server.":= { lanalert-data 6 }

nodeAddressIPX OBJECT-TYPESYNTAX OCTET STRING (SIZE (12))ACCESS not-accessibleSTATUS optionalDESCRIPTION

"The IPX network address of a node.":= { lanalert-data 7 }

nodeAddressAppleTalk OBJECT-TYPESYNTAX OCTET STRING (SIZE (4))ACCESS not-accessibleSTATUS optionalDESCRIPTION

"The AppleTalk network address of a node.":= { lanalert-data 8 }

nodeAddressIP OBJECT-TYPESYNTAX OCTET STRING (SIZE (4))ACCESS not-accessibleSTATUS optionalDESCRIPTION

"The IP network address of a node.":= { lanalert-data 9 }

alertType OBJECT-TYPESYNTAX INTEGER {

thresholdAlert(1),


changeAlert(2),resettableAlert(3)

}ACCESS not-accessibleSTATUS mandatoryDESCRIPTION

"The type of LANAlert alert packet.

Threshold alerts are generated when a condition crosses a preconfigured threshold,and are cleared by the agent when the condition crosses the preconfigured resetvalue.

Change alerts are generated when a condition changes state. These types of alertsare forwarded to any consoles and gateways that are currently attached to theagent management server. Change alerts cannot be cleared, since neither the agentor the management server maintains information about the alert (other thanlogging the alert). Console operators dismiss change alerts locally.

Resettable alerts are generated when a condition changes in a predefined manner.Resettable alerts can be cleared by a console operator, or by the agent itself forsome alerts.

lanalertFSA-NW3-s1 TRAP-TYPEENTERPRISE lanalertFSA-NW3VARIABLES { managementServerName,

nodeName,eventID,alertText

DESCRIPTION"The LANAlert File Server Agent on NetWare 3.x hasset a priority 1 alert."

:= 1 -- set-1

Class definition statement file changesThe following is the entry for lanalertFSA-NW3-s1 in the tecad_snmp.cds file:CLASS lanalertFSA-NW3-s1

SELECT1:ATTR(=,$ENTERPRISE),VALUE(PREFIX, "1.3.6.1.4.1.768.2");2:$SPECIFIC=1;3:ATTR(=,"managementServerName");4:ATTR(=,"nodeName");5:ATTR(=,"eventID");6:ATTR(=,"alertText");

MAPmanagementServerName=$V3;nodeName=$V4;eventID=$V5;alertText=$V6;msg=PRINTF("The LANAlert File Server Agent on %s has set

a priority 1 alert.",$V4);END

The first line is the attribute or trap name. The first attribute (1:ATTR(=,$ENTERPRISE) VALUE(PREFIX, "1.3.6.1.4.1.768.2") ;) specifies that this isan enterprise trap. The OID prefix is derived from the trap definition; traplanalertFSA-NW3-s1 is of type ENTERPRISE lanalertFSA-NW3.

The enterprise OID prefix is 1.3.6.1.4.1 as specified in RFC1155-SMI, plus theappropriate object identifiers. From the following lines in the MIB file, the prefixcan be expanded to 1.3.6.1.4.1.768.2:nci OBJECT IDENTIFIER ::= { enterprises 768 }


lanalert OBJECT IDENTIFIER ::= { nci 2 }

The specific trap number is just a sequential numbering of trap definitions asdefined in the MIB definition for lanalertFSA-NW3-s1 TRAP-TYPE. In this caselanalertFSA-NW3-s1 is the first and is denoted as follows:2:$SPECIFIC=1;

The other attributes are derived from the trap expected object types. The definitionfor lanalertFSA-NW3-s1 states that it contains the following information:

VARIABLES { managementServerName,nodeName,eventID,alertText }

These are denoted in the tecad_snmp.cds file as follows:3:ATTR(=,"managementServerName");4:ATTR(=,"nodeName");5:ATTR(=,"eventID");6:ATTR(=,"alertText");

You would add the following entry to the tecad_snmp.cds file to map the trapvariables to adapter variables:

MAPmanagementServerName=$V3;nodeName=$V4;eventID=$V5;alertText=$V6;msg=PRINTF("The LANAlert File Server Agent on %s has set

a priority 1 alert.",$V4);

These variable values are then mapped to event attributes defined in thetecad_snmp.baroc file. For example, the BAROC class definition for thelanalertFSA-NW3-s1 event is as follows:TEC_CLASS :

LANAlert_Trap ISA Specific_SNMP_TrapDEFINES {

source:default="LANA";sub_source:default="NET";severity:default="WARNING";trapTime:INT32;specificTrap:INT32;managementServerName:STRING;nodeName:STRING;eventID:INT32;alertText:STRING;};

END

TEC_CLASS :lanalertFSA-NW3-s1 ISA LANAlert_Trap;

END

Object identifier file changesThe entry in the tecad_snmp.oid file for this trap is composed of the enterpriseprefix plus the appropriate object identifiers (OID) plus the variable attribute OID.For example,#nci 1.3.6.1.4.1.768lanalert 1.3.6.1.4.1.768.2lanalert-data 1.3.6.1.4.1.768.2.2nodeName 1.3.6.1.4.1.768.2.2.2


eventID 1.3.6.1.4.1.768.2.2.3alertText 1.3.6.1.4.1.768.2.2.5managementServerName 1.3.6.1.4.1.768.2.2.6

Troubleshooting the SNMP adapter1. Make sure that no other processes such as SNMP or ovtrapd are already

listening on port 162. Use netstat –a | grep 162 to see if this port is in use. Thefirst process to start up gets the port and the other processes that follow neverreceive events from that port.

2. Use the following command to cold start the SNMP adapter:tecad_snmp [–d] [–c configuration_file]The following are the arguments for the tecad_snmp command:

–d Starts the adapter in debug mode. This argument prevents the daemonfrom forking itself.

–c configuration_fileSpecifies the location of the configuration file.

If –c is not specified, then the adapter searches$TECADHOME/etc/tecad_snmp.conf if the environment variableTECADHOME is set, or /etc/Tivoli/tecad/etc/tecad_snmp.conf for theconfiguration file.

3. Use snmptrap or the Tivoli Distributed Monitoring wsnmptrap commands tosend events to the adapter for testing.



Chapter 10. UNIX logfile adapter

The TME UNIX logfile adapter receives raw log file information from the UNIXsyslogd daemon, formats it, and sends it to the Tivoli Enterprise Console gateway.The Tivoli Enterprise Console gateway then sends the information to the eventserver. The non-TME UNIX logfile adapter sends information directly to the eventserver.

The UNIX logfile adapter adds entries into the /etc/syslog.conf file to enable theadapter to monitor events that the syslogd daemon writes to various log files. Theadapter can also be configured to monitor any ASCII log file for information that isimportant to the operation of your enterprise.

This chapter explains how to configure and start the UNIX logfile adapter.

Event server configurationAt the event server, the BAROC file and rule set file must be imported into a rulebase and then compiled. This rule base must then be loaded and made the activerule base. See the IBM Tivoli Enterprise Console Rule Developer’s Guide for additionalinformation about the steps to do these tasks.

Note: The Default rule base, as shipped, is already configured using the BAROCfile and default rule file for the UNIX logfile adapter.

Starting the adapterUse the init.tecad_logfile start [adapterID] command in the background tomanually start the adapter. Always use this command to ensure that the syslogddaemon is properly configured to send messages to the adapter.

In most situations, the start-up process takes 40 seconds, at which time the syslogddaemon is refreshed. If you want to give the adapter additional seconds tocomplete its startup, specify the –tstartup_time option for the init.tecad_logfile startcommand. There cannot be a space between the option letter and the option value.This option is useful if the adapter does not receive events because the syslogddaemon is not properly refreshed.

Note: The endpoint adapter is automatically started as a step in the adapterinstallation process when the adapter configuration profile is distributedusing the Adapter Configuration Facility.

Stopping the adapterYou can configure each adapter configuration record to perform actions onsubscribing endpoints upon distribution. You can configure actions that are to beperformed both before and after configuration files are written. Actions performedbefore file distribution can stop an event adapter and possibly remove the contentsof a configuration directory. Actions performed after file distribution can restart theadapter.



To manually stop the adapter, use the init.tecad_logfile stop [adapterID] command.This command ensures that the syslogd daemon is correctly configured to stopsending messages to the adapter. If the adapter is stopped with any other method,the syslogd daemon might exit because the adapter is no longer listening on thenamed pipe that the syslogd daemon is writing to.

Reloading the adapter configurationTo reload the adapter configuration and format files, issue the following command:kill -HUP pid

where pid is the process ID of the adapter. Use this command if you want tochange the adapter configuration without having to stop and restart the adapter.For example, you might want to temporarily add (and later remove) filters orentries in the format file when the system goes into maintenance mode. After youhave made the necessary changes to the configuration and format files, issue thiscommand to dynamically update the adapter configuration.

Running multiple UNIX logfile adaptersYou can run multiple instances of the UNIX logfile adapter on a single system. It isrecommended that additional adapters be run as non-TME adapters. To monitordifferent log files, each instance of the adapter must have its own configuration,format, class definition statement (CDS), and error files. If the adapters use eventbuffering (set using the BufferEvents keyword, which has a default value of YES),the adapters must also have their own cache files.

If you want to stop an adapter when multiple log files are running, you mustspecify the name of the adapter to stop. If you do not specify the adapter to stop,the default adapter without a name is stopped.

The syntax for the init.tecad_logfile command is as follows:

init.tecad_logfile [–s] {start | stop} [adapterID] &

If the –s flag (skip syslog) is specified, the adapter does not monitor the syslogddaemon.

If the –s flag is not specified, use & so that the command runs in the backgroundwhile returning a command prompt to your session. Otherwise, because anadapter started without the –s option forks a child process to run the adapter, theprocess does not return to the command line until the child process ends.

Note: If you start the adapter with the –s flag, you can also use the –s flag whenyou stop the adapter to avoid reconfiguring the syslogd daemon. You canalso stop the adapter without the –s flag and it still works. However, do notstop an adapter with the –s flag if you did not start it with the –s flag.

If the –s flag is not specified, the UNIX logfile adapter startup script uses a UNIXpipe to monitor the syslogd daemon and the syslogd daemon is configured towrite to the pipe, and the UNIX logfile adapter reads from that pipe. When the


adapter ends, the startup script reconfigures the syslogd daemon to stop writing tothe pipe before stopping the UNIX logfile adapter.

The following command starts a UNIX logfile adapter called syslog that monitorsall syslog messages:init.tecad_logfile start syslog &

Adapter filesThe UNIX logfile adapter package consists of the following files:

tecad_logfile.cfgThe installation script.

init.tecad_logfileThe adapter startup and shutdown script. Never stop the adapterusing signals. Use this script to ensure that the syslogd daemonremains running and functional.

tecad_logfile The executable file of the adapter that receives the log informationand transforms it into events.

logfile_gencdsThe executable file that converts a format file to a CDS file.

tecad_logfile.barocThe BAROC file.

tecad_logfile.cdsThe CDS file. This file is created by running logfile_gencds on theformat file.

tecad_logfile.confThe configuration file.

tecad_logfile.errThe error file.

tecad_logfile.fmtThe format file.

log_default.rlsThe default rule file.

Before you start the event server and UNIX logfile adapter, check each adapter fileto determine if it defines the behavior you want from the adapter.

Configuration fileThe configuration file defines the behavior of the adapter. The configuration filecan have the common keywords described in “Configuration file” on page 9, aswell as the following custom keywords:

LogSources

Specifies the log files to poll. The complete path to each file must bespecified, and file names must be separated by commas. Within each filename, you can also use an asterisk (*) to represent any sequence ofcharacters, or a question mark (?) to represent any single character. Forexample, mylog* would result in polling all log files whose names beginwith mylog, while mylog??? would result in polling all log files whose

Chapter 10. UNIX logfile adapter 157

names consist of mylog followed by exactly three characters. Thesewildcard characters are supported only within the file name; the path mustbe explicitly specified.

A log source need not exist when the adapter is started; it is polled when itis created.

Each line in the file must end with a newline character. If a file truncateswhile the adapter is active, the adapter automatically resets its internalpointer to the beginning of the file. If during the polling interval the file isoverwritten, removed, or recreated with more lines than the previous poll,only the number of lines greater than the previous line count is read. Forexample, the file has one line. After the poll interval elapses, the file isoverwritten with two lines. Only the second line is read on the nextpolling.

Note: The maximum number of lines that can be concatenated to a log fileis 16 384.

NewLogBasedOnSpecifies whether a log file should be treated as new when the time stampof the file changes but the size remains the same. When a file is treated asnew, the adapter re-sends every event contained in the file. The possiblevalue is:

mtime | MTIMEThe file is treated as new if the modification time stamp changes.

This keyword is optional. If NewLogBasedOn is not specified, a preexistinglog file is treated as new only if its size decreases.

PollIntervalSpecifies the frequency, in seconds, to poll each file listed in theLogSources field for new messages. The default value is 120 seconds.

ProcessPriorityClassSpecifies the process priority for the adapter. You can adjust this value toimprove system performance if the adapter processes large volumes ofevents and is using too many processor resources. The possible values are:A Very low priority (20)B Low priority (10)C Typical priority (0)D Above typical priority (-5)E High priority (-10)F Very high priority (-20)

The default value is C (typical priority).

UnmatchLogSpecifies a file to log discarded events that cannot be parsed into a TivoliEnterprise Console event class by the adapter. The discarded events canthen be analyzed to determine if modifications are needed to the adapterformat file.

Format fileThe format file is described in detail in “Format file” on page 24.


Class definition statement fileThe CDS file defines how an adapter constructs events. This file is derived fromthe format file using the logfile_gencds program. In general, you should neverhave to edit this file to add new mappings. The CDS file is described in detail in“Class definition statement file” on page 25 and in Appendix C, “Class definitionstatement file reference”, on page 197.

Error fileThe error file is described in detail in “Error file” on page 26.

Events listingThe following table shows the class names and severities of all events defined forthe UNIX logfile adapter. You can use the table to get a sense of how log fileevents are mapped to Tivoli Enterprise Console events and to determine if youwant to make any changes. The events are defined in the BAROC file. See the IBMTivoli Enterprise Console Rule Developer’s Guide for more information aboutcustomizing BAROC files.

Event class structureEvent classes are defined hierarchically, with child classes inheriting attribute valuedefaults from the parent.

The adapter fills in the following attribute defaults. The attributes are used inevent group filters.v source: LOGFILEv origin: hostIPaddress

v hostname: hostname

The following events are defined for the UNIX logfile adapter in thetecad_logfile.baroc file.

Table 17. UNIX logfile adapter events


Logfile_Base WARNING

Logfile_Automounter HARMLESS

Logfile_Amd WARNING

Amd_Mounted WARNING

Amd_Unmounted WARNING

Logfile_Automount WARNING

Logfile_Bootpd WARNING

Logfile_Comsat WARNING

Logfile_Cron HARMLESS

Logfile_Date HARMLESS

Logfile_Date_Set WARNING

Logfile_Ebbackupd WARNING

Ebbackupd_Waiting WARNING

Logfile_Ebcatcomp WARNING


Table 17. UNIX logfile adapter events (continued)


Logfile_Fsck WARNING

Logfile_Ftp WARNING

Logfile_Ftpd WARNING

Logfile_Gated WARNING

Logfile_Getty WARNING

Logfile_Halt WARNING

Logfile_Idi HARMLESS

Logfile_Inetd WARNING

Logfile_Init WARNING

Logfile_Innd WARNING

Logfile_Kernel WARNING

File_Write_Error MINOR

File_System_Full MINOR

NFS_Write_Error WARNING

Sendsig_Err CRITICAL

Kernel_Panic FATAL

NFS_No_Response WARNING

NFS_OK HARMLESS

Silo_Overflow MINOR

Logfile_Login WARNING

Root_Login MINOR

Root_Login_Failure WARNING

Root_Login_Failure_From WARNING

Root_Login_Success WARNING

Root_Login_Success_From WARNING

Repeated_Login_Failure WARNING

Repeated_Login_Failure_From WARNING

Logfile_Lpd WARNING

Logfile_Lpd_Get_Hostname WARNING

Logfile_Lpd_Lost_Connection WARNING

Logfile_Lpd_No_File WARNING

Logfile_Mosaic WARNING

Logfile_Mountd WARNING

Logfile_Named WARNING

Logfile_Nfsd WARNING

Logfile_Nnrpd WARNING

Logfile_Oserv WARNING




Oserv_Panic CRITICAL

Oserv_Graceful_Exit HARMLESS

Oserv_System_Error MINOR

Oserv_Fork_Failed CRITICAL

Oserv_Exec_Failed MINOR

Oserv_Comm_Error WARNING

Oserv_IPC_Dispatch_Failed MINOR

Oserv_Security WARNING

Oserv_Tmgr WARNING

Oserv_Event_Method_Failed MINOR

Logfile_Passwd WARNING

Logfile_Pcnfsd WARNING

Logfile_Printer WARNING

Printer_Connection_Abort WARNING

Printer_Error_Cleared HARMLESS

Printer_Door_Open WARNING

Printer_Offline WARNING

Printer_Output_Full WARNING

Printer_Page_Punt WARNING

Printer_Paper_Jam WARNING

Printer_Paper_Out WARNING

Printer_Powerup WARNING

Printer_Toner_Low WARNING

Logfile_Rarpd WARNING

Logfile_Reboot HARMLESS

Logfile_Rexecd WARNING

Logfile_Rftp WARNING

Logfile_Rlogind WARNING

Logfile_Routed WARNING

Logfile_Rquotad WARNING

Logfile_Rshd WARNING

Logfile_Rstatd WARNING

Logfile_Rtelnet WARNING

Logfile_Rwhod WARNING

Logfile_Sendmail HARMLESS

Sendmail_Loopback WARNING

Sendmail_No_Space MINOR

Logfile_Snmpd WARNING

Logfile_Sockd WARNING




Sockd_Connected HARMLESS

Sockd_Terminated WARNING

Sockd_Transfer WARNING

Logfile_Strerr HARMLESS

Logfile_Su WARNING

Su_Failure WARNING

Su_Success WARNING

Logfile_Syslogd WARNING

Syslogd_Nospace MINOR

Logfile_Talkd WARNING

Logfile_Telnetd WARNING

Logfile_Tftpd WARNING

Logfile_Xntpd WARNING

Xntpd_Clock_Reset WARNING

Xntpd_Ntpdate WARNING

Logfile_YP HARMLESS

Logfile_Ypbind WARNING

Logfile_Ypchfn WARNING

Logfile_Ypchsh WARNING

Logfile_Yppasswd WARNING

NIS_No_Response WARNING

NIS_OK HARMLESS

No_Permission WARNING

No_Resources CRITICAL

No_Disk_Space WARNING

File_System_Full MINOR

LOCAL_File_System_Full WARNING

NFS_File_System_Full WARNING

SWAP_File_System_Full WARNING

Sendmail_No_Space MINOR

Syslogd_Nospace MINOR

No_Memory WARNING

No_Proc_Attributes WARNING

Server_No_Response WARNING

NFS_No_Response WARNING

NIS_No_Response WARNING

Server_OK HARMLESS

NFS_OK HARMLESS

NIS_OK HARMLESS


Default rulesThe UNIX logfile adapter has a set of default rules that can be installed to enhanceevent server operation. Rules can enable the server to perform functions such asdeleting events and sending e-mail to alert administrators of an unresolvedproblem. The rules are contained in the log_default.rls file and perform thefollowing functions:v Duplicate events of the following classes are filtered out and the first event

repeat count is increased:– Printer_Paper_Out– Printer_Toner_Low– Printer_Offline– Printer_Output_Full– Printer_Paper_Jam– Printer_Door_Open

v Printer assistance can be called for when a printer condition persists for a periodof time greater than 90 seconds. If any of the following conditions persist forthat period of time, an e-mail message is sent to the e-mail alias tec_print torequest assistance with the printer condition. (The tec_print alias must be addedto the e-mail alias file before the messages can be delivered.)– Printer_Paper_Out– Printer_Toner_Low– Printer_Offline– Printer_Output_Full– Printer_Paper_Jam– Printer_Door_Open

v When a printer condition is cleared, the event server automatically closes theevent that indicated a problem. If e-mail was sent out notifying theadministrators of the printer problem, the server sends e-mail indicating thecondition has cleared up.

v The Su_Success and Su_Failure events indicate that a user attempted to use thesu command. If a Su_Success event is received within 90 seconds of theSu_Failure event, the server assumes that the Su_Failure was a mistake anddowngrades the event to HARMLESS and closes the Su_Failure event. The rulesensure that these two events are related by checking that they occurred on thesame host, the user attempting this was the same, and the user that they weretrying to change to was the same.

v Some of the log file events are relevant for a short amount of time. Theadministrators also do not want to be burdened with closing these eventsmanually. A rule is provided that closes the following event classes after onehour. You can edit this rule to change the time or the list of classes. Refer to theIBM Tivoli Enterprise Console Rule Builder’s Guide for information about editingrules.– Logfile_Amd– Logfile_Cron– Logfile_Oserv– Logfile_Date_Set

The event server also comes with some additional rules that you can install. The$BINDIR/TME/TEC/contrib/rules/security directory contains thesecurity_default.rls file, which provides the following behavior to the event server:


v When a host reports a repeated login failure attempt at least two times in a row,e-mail is sent to the e-mail alias tec_security notifying the administrators of theattempted security breach. (The tec_security alias must be added to the e-mailalias file before the messages can be delivered.)

v A rule is included that closes the following event classes after one hour:– Repeated_Login_Failure– Repeated_Login_Failure_From– Root_Login_Success_From

Troubleshooting the UNIX logfile adapterPerform the following steps to troubleshoot the UNIX logfile adapter:1. Stop any UNIX logfile adapters that are currently running:

init.tecad_logfile stop

2. Start the adapter in debug mode.init.tecad_logfile -d start

3. Generate some messages to determine if the adapter receives them. You cansend e-mail, perform an su, or perform any action that results in a write tosyslog. Alternatively, you can use the logger program to generate messages:logger -t oserv -i execve failed: path: errno 13

This generates an Oserv_Exec_Failed event. The message written by loggershould match one of the format specifications in the tecad_logfile.fmt file.

4. When events arrive, the adapter prints messages to the screen indicating theclass and the attribute values in the class.matched CREATED_PROFILE_MANAGER name is ’Profile1’’

If you do not see any messages, the adapter is not receiving events from thelog file.

Verify that the syslogd daemon is running and is writing any new messages tothe system log files in /var/adm or its equivalent, or to the system console,depending on how syslog.conf has been configured to write out messages. Fortesting purposes, you can temporarily add the following line to syslog.conf:*.info <Tab> <filename>

This enables all messages to be written to a file so you can see what messageshave arrived. This file grows large quickly, so make this a temporary changeonly. You need to refresh the syslogd daemon each time you change syslog.confto put these changes into effect.

5. If you see the messages, the adapter is receiving events and processing them.Run the wtdumprl command on the event server and verify that the messagesare actually showing up in the reception log. If not, the events were notreceived by event server or there is a problem with the event server receptionprocess. Check the adapter configuration file to verify that ServerLocation andServerPort are properly defined. Also check the parameters used in the startcommand to ensure that the ID provided is the same one used to configure theadapter. If the event class is in any filter entry in the configuration file, it is notsent to event server. The administrator who started the adapter must have therequired roles if you are running the TME version of the adapter. For a TMEadapter, running the odstat command can offer some clues as to what failed.



7. If the previous steps do not indicate any problem and you do not see the newevents in the Tivoli Enterprise Console product, there might be a problem withthe event group filters. Make sure the class filters match the classes in theBAROC files.



Chapter 11. Windows event log adapter

The adapter for the Microsoft Windows event log forwards events from a Windowssystem to the event server. It is registered with the startup configuration of aWindows 2000 system so that the adapter is started with all the other applicationsthat are automatically started when the Windows system is started.

The adapter is a WIN32 process that reads events generated on a Windows 2000system, formats them according to the specification in the format file, and forwardsthem using Winsock TCP/IP to an event server for further processing.

Events are gathered from up to six Windows event logs (System, Application,Security, DNS server, File Replication service, and Directory service) maintained bythe Windows Event Manager, and from any other ASCII log files residing on theWindows 2000 system. The Windows event log adapter tracks the messages readfrom the Windows event logs using up to six registry variables that contain themost recent highest message read for the System, Application, Security, DNSserver, File Replication service, and Directory service logs, whether the Windowsevent log adapter is running continuously or is restarted. You can alter thisbehavior using the appropriate switches when the Windows event log adapter isstarted.

Two versions of the Windows event log adapter are provided. One is built as aWindows service, while the other is a WIN32 process that is a command lineinterface version. Usually, you should run the Windows service version, because itruns even when no user is logged in. The command line interface can be used tohelp you view console messages for diagnostic purposes. Other than theservice-related differences, both versions perform identically.

This chapter describes how to configure and start the Windows event log adapter.

Adapter filesThe Windows event log adapter package consists of the following files:

README The readme file.

tecinstl_win.cmdThe adapter installation batch file.

instlsrv.exe The adapter installation assist executable file.

tecadwins.exeThe adapter service executable file.

tecad_win.exeThe adapter non-service executable file.

tecad_win.confThe configuration file.

tecad_win.fmtThe format file.

tecad_win.cds The class definition statement (CDS) file.


tecad_win.barocThe BAROC file.

postemsg.exe The command line interface program to send an event to an eventserver.

tecad_win.err The error file.

Before starting the event server, check the configuration file to determine if itdefines the preferred adapter behavior.

Configuration fileThe configuration file defines the behavior of the adapter. This file can contain thecommon keywords described in “Configuration file” on page 9, as well as thefollowing adapter-specific keywords:

BufferMaxSize=nSpecifies the number of events buffered in the adapter. If theadapter is operating under extreme loads, use this keyword tocontrol the amount of memory used by the adapter. If this is notspecified, the default value is 16384.

HostnameIsAdapterHostSpecifies whether the host name attribute for Windows event logevents is set to the host on which the adapter is running (thedefault) or the host where the event originated.

If set to NO or no, the host name attribute is set to theCOMPUTER field from the Windows event log.

Note: This applies only to events from the Windows event log, notthose generated from log files specified in LogSources. Thoseevents always have the host name attribute set to the hoston which the adapter is running.

The COMPUTER name returned from the Windows event logmight not be the same as the ManagedNode name (which iscase-sensitive) of the host where the event originated. You musttake this into consideration if you run tasks or programs from theTivoli Enterprise Console product or the rule base, because theymight use the host name attribute to determine where they run.

LanguageID Sets the language event log messages to be formatted in English orthe native language. Valid values are as follows:

ENGLISHMessages are formatted in English.

DEFAULTThe adapter attempts to format event log messages in thedefault language based on the local value set in Windows.If the adapter cannot use the default language, it usesEnglish. The value DEFAULT can be used only inlanguages that have 8-bit wide characters.

The format file is in English. The Windows event logs are in yournative language. If your native language is not English, you mustrewrite the format file in your native language.

LogSources


Specifies the ASCII log files to poll for messages. The completepath to each file must be specified, and file names must beseparated by commas. Within each file name, you can also use anasterisk (*) to represent any sequence of characters, or a questionmark (?) to represent any single character. For example, mylog*results in polling all log files whose names begin with mylog, whilemylog??? results in polling all log files whose names consist ofmylog followed by exactly three characters. These wildcardcharacters are supported only within the file name; the path mustbe explicitly specified.

A log file source need not exist when the adapter is started; it ispolled when it is created.

Each line in the file must end with a newline character. If a filetruncates while the adapter is active, the adapter automaticallyresets its internal pointer to the beginning of the file. If during thepolling interval the file is overwritten, removed, or recreated withmore lines than the previous poll, only the number of lines greaterthan the previous line count is read. For example, the file has oneline. After the poll interval elapses, the file is overwritten with twolines. Only the second line is read on the next polling.

NewLogBasedOnSpecifies whether a log file should be treated as new when thetime stamp of the file changes but the size remains the same. Whena file is treated as new, the adapter re-sends every event containedin the file. The possible values are:

ctime | CTIMEThe file is treated as new if the creation time stampchanges.

mtime | MTIMEThe file is treated as new if the modification time stampchanges.

cmtime | CMTIMEThe file is treated as new if the creation or modificationtime stamp changes.

This keyword is optional. If NewLogBasedOn is not specified, apreexisting log file is treated as new only if its size decreases.

NumEventsToCatchUp

Specifies which event in the Windows event logs that the adapterstarts with. This option provides some flexibility if the source beingmonitored is new or the adapter has been stopped for an extendedperiod of time. Valid values are as follows:

0 Start with the next event in the logs. This is the defaultvalue.

–1 Start with the oldest event in the logs.

n n represents any number other than zero (0) or –1. Startwith the nth event from the most current event in the logs;that is, start n events back from the most current event inthe logs. If n is greater than the number of events that areavailable, all the events that are available are processed.

Chapter 11. Windows event log adapter 169

PollInterval Specifies the frequency, in seconds, to poll each log file listed in theLogSources keyword for new messages. The default value is 120seconds.

If you have upgraded a Windows event log adapter from aprevious release and you have a value set for PollingInterval in theWindows registry, you must specify the PollInterval keyword inthe adapter configuration file with the same value used in theWindows registry.

PreFilter Specifies how events in a Windows event log are filtered beforeadapter processing. PreFilter statements are used by PreFilterModewhen determining which events are sent from an event log to theadapter. An event matches a PreFilter statement when eachattribute=value specification in the PreFilter statement matches anevent in the event log. A PreFilter statement must contain at leastthe log specification and can contain up to three additionalspecifications, which are all optional: event ID, event type, andevent source. The order of the attributes in the statement does notmatter.

The basic format of the PreFilter statement is as follows:PreFilter:Log=log_name;EventId=value; EventType=value;Source=value;

You can specify multiple values for each attribute by separatingeach with a comma.

Each PreFilter statement must be on a single line.

The PreFilter keyword is optional. All Windows log events are sentto the adapter if prefilters are not specified and PreFilterMode=OUT.

For additional information about prefiltering Windows log events,see “Prefiltering Windows log events” on page 172.

PreFilterMode

Specifies whether Windows log events that match a PreFilterstatement are sent (PreFilterMode=IN) or ignored(PreFilterMode=OUT). Valid values are IN, in, OUT, or out. Thedefault value is OUT.

The PreFilterMode keyword is optional; if PreFilterMode is notspecified, only events that do not match any PreFilter statementsare sent to the adapter.

Note: If you set PreFilterMode=IN, make sure you have one ormore PreFilter statements defined as well.

For additional information about prefiltering Windows event logevents, see “Prefiltering Windows log events” on page 172.

ProcessDisablePriorityBoostSpecifies whether the priority boost should be disabled for theadapter process. You can use this option to improve systemperformance if the adapter processes large volumes of events andis using too many processor resources. If this option is set toTRUE, the priority boost is disabled. The default value is FALSE.


ProcessPriorityClassSpecifies the process priority for the adapter. You can adjust thisvalue to to improve system performance if the adapter processeslarge volumes of events and is using too many processor resources.The possible values are:A IdlePriorityB BelowNormalPriorityC NormalPriorityD AboveNormalPriorityE HighPriorityF RealTimePriority

The default value is C (NormalPriority).

SpaceReplacementWhen SpaceReplacement is FALSE, any spaces in the security IDand subsource fields of the event log messages are left unchanged.When SpaceReplacement is TRUE, any spaces in the security IDand subsource fields of the event log messages are replaced withunderscores (_). Set SpaceReplacement to TRUE if the format fileexpects the security ID and subsource fields to be a single word(that is, uses a %s format specification for them). The adapter isconfigured for a setting of TRUE. If SpaceReplacement is not set toTRUE, the default value is FALSE.

UnmatchLog Specifies a file to log discarded events that cannot be parsed into aTivoli Enterprise Console event class by the adapter. The discardedevents can then be analyzed to determine if modifications areneeded to the adapter format file.

WINEVENTLOGSControls which Windows Event Logs are monitored; also controlsthe service version and overrides the command line interface.

The WINEVENTLOGS statement is a comma-delimited list with nospaces that can contain the following values: Application, Directory(Directory service), DNS, FRS, Security, System, All, and None.

In the following WINEVENTLOGS statement, the System, Security,and File Replication service event logs are monitored and all othersare ignored:WINEVENTLOGS=System,Security,FRS

In the following statement, all event logs are monitored:WINEVENTLOGS=All

If a statement contains one or more event logs as well as the All orNone option, the All or None option is used and the list of eventlogs is ignored. In the following example, all event logs aremonitored even though specific event logs are also listed:WINEVENTLOGS=DNS,Directory,All

If a statement contains both the All and None options, the Noneoption overrides all other options. In the following example, noevent logs are monitored:WINEVENTLOGS=Application,All,FRS,Directory,None


After changing the WINEVENTLOGS statement in thetecad_win.conf file, you must restart the adapter for the changes totake effect.

Prefiltering Windows log eventsYou can improve Windows event log adapter performance by filtering events inthe Windows event logs so only those events that are of importance toadministrators are processed by the adapter. This type of filtering is calledprefiltering because it specifies selection criteria based on the raw Windows eventrecord rather than the formatted Tivoli Enterprise Console event. The prefiltering isperformed before the event is formatted into a Tivoli Enterprise Console event andsubjected to any filtering specified with the Filter or FilterCache configuration filekeywords.

Like other adapter filtering, prefiltering is specified in the adapter configurationfile using a similar syntax. The prefiltering statements, PreFilter and PreFilterMode,are described in “Configuration file” on page 168.

As with any modification to an adapter configuration file, you must stop andrestart the adapter for the changes to take effect.

There are four attributes of the Windows event logs that you can use in definingprefilter statements. They are described in the following list:

Log Specifies one or more of the Windows event logs to prefilter. Valid valuesare System, Security, Application, DNS Server, File Replication Service,Directory Service, or any combination of these separated by commas. Thedefault value is all these event logs.

EventIdSpecifies the event number assigned by Windows. You can specify up tosixteen event numbers. Multiple event numbers must be separated bycommas.

SourceThe source that logged the event to the Windows event log. You canspecify up to sixteen sources. Multiple sources must be separated bycommas.

EventTypeThe classification of the event assigned by Windows. Valid values are asfollows:v Errorv Warningv Informationv AuditSuccessv AuditFailurev Unknown

The following examples show prefiltering statements. The first statement is onmultiple lines due to space restrictions.PreFilter:Log=Application;Source=MyApp;EventId=1000,2000, \3000;EventType=Warning,Information;

PreFilter:Log=Security;

PreFilter:Log=Application;Source=TECWinAdapter;


Format fileThe format file contains message format descriptions and their mappings toBAROC events. The message fields of a Windows event are matched against theformat descriptions in this file and when a match succeeds, the correspondingTivoli Enterprise Console event is generated by the adapter. The format filecontains predefined mappings for some common Windows events and can becustomized to add any new messages.

A Windows event is written to an ASCII message in the following sequence:v The date expressed as month, day, time, and year.v The event category, expressed as an integer.v The event type (Error, Warning, Information, AuditSuccess, AuditFailure,

Unknown).v The Windows security ID; any spaces in this field are replaced by an underscore

if the proper registry variable is set.v The Windows source; any spaces in this field are replaced by an underscore if

the proper registry variable is set.v The Windows event identifier.v The message text.

The subfields, except the message text field, are derived from the event header inthe Windows event object. The output message after formatting is bound against aformat description. A formatted error message from the Windows service controlmanager can look like the following example:Jan 15 15:06:19 1998 0 Error N/A Service_Control_Manager 7024 \The UPS service terminated with service-specific error 2481.

For details about format files, see “Format file” on page 24 and Appendix B,“Format file reference”, on page 187.

Registry variablesRegistry variables are used to control the operation of the Windows event logadapter. Changes made to registry variables take effect immediately; there is noneed to stop and restart the adapter. Use the registry editor (regedt32) provided byWindows to view and modify registry variables.

Note: It is not necessary to modify the registry variables for the Windows eventlog adapter to function. The registry variables are automatically set to thecorrect default values when the Windows event log adapter is installed.

All of the registry variables for the Windows event log adapter are located in the\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TECWinAdapter directory. The following are the adapter registry variables:

Note: When you change the registry entries for any registry variable with a nameending with EventsProcessedTimeStamp, you must also change the registryentries for the corresponding registry variable with a name ending withEventsProcessed. For example, if you change the registry entry forApplicationEventsProcessedTimeStamp, you must also changeApplicationEventsProcessed.


If both values are not changed, the adapter ends unexpectedly, thePollingInterval criteria are met, and a message similar to the following issent:msg=’TECWinAdapter shuts down.Error: older event on \ApplicationEventsProcessed : (1,920433843) vs last processed \event(1,923673952).’;

To prevent this, stop the adapter and then make the necessary registrychanges. When you restart the adapter, a consistency check updates theregistry entry for the appropriate variable ending with EventsProcessed tomatch the correct value based on the corresponding variable ending withEventsProcessedTimeStamp.

ApplicationEventsProcessedContains the highest event number in the Windows Application Log thatthe adapter has processed. The adapter uses this variable to keep track ofhow many events it has read and sent to the event server so that theadapter can start at the next event the next time it polls the log. You canlower the ApplicationEventsProcessed variable if you want an event to beread and processed again. To process all messages in the Application Log,set the ApplicationEventsProcessed variable to 1.

ApplicationEventsProcessedTimeStampContains the time stamp for the corresponding event identified by thevalue of the ApplicationEventsProcessed variable.

DirectoryEventsProcessedContains the highest event number in the Windows active directory serverlog that the adapter has processed. The adapter uses this variable to keeptrack of how many events it has read and sent to the event server so thatthe adapter can start at the next event the next time it polls the log. Youcan lower the DirectoryEventsProcessed variable if you want an event tobe read and processed again. To process all messages in the DirectoryService Log, set the DirectoryEventsProcessed variable to 1.

DirectoryEventsProcessedTimeStampContains the time stamp for the corresponding event identified by thevalue of the DirectoryEventsProcessed variable.

DNSEventsProcessedContains the highest event number in the Windows DNS Server Log thatthe adapter has processed. The adapter uses this variable to keep track ofhow many events it has read and sent to the event server so that theadapter can start at the next event the next time it polls the log. You canlower the DNSEventsProcessed variable if you want an event to be readand processed again. To process all messages in the DNS Server Log, setthe DNSEventsProcessed variable to 1.

DNSEventsProcessedTimeStampContains the time stamp for the corresponding event identified by thevalue of the DNSEventsProcessed variable.

FileReplicationEventsProcessedContains the highest event number in the Windows File Replication serviceevent log that the adapter has processed. The adapter uses this variable tokeep track of how many File Replication service log events it has read andsent to the event server so that the adapter can start at the next event thenext time it polls the log. You can lower the FileReplicationEventsProcessedvariable if you want an event to be read and processed again. To process


all messages in the File Replication service log, set theFileReplicationEventsProcessed variable to 1.

FileReplicationEventsProcessedTimeStampContains the time stamp for the corresponding event identified by thevalue of the FileReplicationEventsProcessed variable.

PollingIntervalThe adapter polls the Windows event logs for new events at intervalswhen it does not receive any events automatically. The PollingIntervalvariable specifies the upper frequency limit, in seconds, to poll theWindows event logs. The default value is 120 seconds.

Polling begins at 5 seconds. If a new event is detected, the next pollingfrequency begins at 5 seconds again. If no event is detected from a poll, thepolling interval is doubled, until the upper limit is reached. After theupper limit is reached, the polling frequency remains at that interval untila new event is detected; then, it is reset to 5 seconds.

Note: If there are buffered events, but no incoming events, the time stilldoubles until the set PollingInterval time. To avoid this, setPollingInterval to a lower number. The PollingInterval setting is inthe registry in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TECWinAdapter\. This is not set as adefault value and must be added to the registry to alter the defaultvalue of 120 seconds.

SecurityEventsProcessedContains the highest event number in the Windows Security Log that theadapter has processed. The adapter uses this variable to keep track of howmany events it has read and sent to the event server so that the adaptercan start at the next event the next time it polls the log. You can lower theSecurityEventsProcessed variable if you want an event to be read andprocessed again. To process all messages in the Security Log, set theSecurityEventsProcessed variable to 1.

SecurityEventsProcessedTimeStampContains the time stamp for the corresponding event identified by thevalue of the SecurityEventsProcessed variable.

SystemEventsProcessedContains the highest event number in the Windows event log that theadapter has processed. The adapter uses this variable to keep track of howmany log events it has read and sent to the event server so that theadapter can start at the next event the next time it polls the log. You canlower the SystemEventsProcessed variable if you want an event to be readand processed again. To process all messages in the event log, set theSystemEventsProcessed variable to 1.

SystemEventsProcessedTimeStampContains the time stamp for the corresponding event identified by thevalue of the SystemEventsProcessed variable.

TECInstallPathSpecifies the directory that contains the Windows event log adapterexecutable files and run-time files. This variable is usually set todrive:\adapter_dir, where drive and adapter_dir are the drive and directory,respectively, that contain the adapter executable files and run-time files.Change the TECInstallPath variable only if you move the adapterexecutable files and run-time files after you have installed the adapter.


Low memory registry variablesWhen enabled, this feature checks the amount of available memory before theWindows event log adapter attempts to send an event. If the amount of freememory is extremely low, the Windows event log adapter returns to a suspendedstate until more memory is available, which prevents the adapter from failing.However, because of the amount of resources this consumes, enable this featureonly when available memory is so low that the adapter is failing and you have noother way to solve the problem.

To enable this feature, you must set at least one of following registry variables inthe \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TECWinadapter\ registry path:

yellow_alert_limitWhen free memory is below this level, the adapter sends a warning thatindicates the adapter might return to a suspended state until more memoryis available and lists the amount of free memory. The default value is 40Mb.

red_alert_limitWhen free memory is below this level, the adapter sends a warning andlists the amount of free memory, then returns to a suspended state for 1minute. After 1 minute, the adapter checks free memory again; if freememory is still below this level, the adapter returns to a suspended statefor another minute and repeats until free memory is higher than this value.The default value is 20 Mb.

emergency_memsizeThis is the amount of memory the adapter keeps in reserve for lowmemory situations. When the red_alert_limit is reached, the adapter freesthis memory to make sure there is enough memory available to send thered_alert_limit warning. The default value is 2 Mb.

Any values that you do not set use the default values when you enable thisfeature. The adapter checks these values only at startup.

Starting the adapterThe default action is that the adapter is always started when Windows is started. Ifyou are using the Windows service version of the Windows event log adapter, youcan use the Windows tools to operate the adapter. For example, you can start andstop the adapter using Windows Control Panel Services. You can also manuallystart the adapter from the command line with the net startTECWinAdapter[_adapter_identifier] command where adapter_identifier is theadapter identifier; for example, manually start an adapter that has no identifierusing this command:net start TECWinAdapter

or, for an adapter with an identifier of toserver1, manually start it using thiscommand:net start TECWinAdapter_toserver1

Note: The endpoint adapter is automatically started as a step in the adapterinstallation process when the adapter configuration profile is distributedusing the Adapter Configuration Facility.


Stopping the adapterYou can configure each adapter configuration record to perform actions onsubscribing endpoints upon distribution. You can configure actions that are to beperformed both before and after configuration files are written. Actions performedbefore file distribution can halt an event adapter and possibly remove the contentsof a configuration directory. Actions performed after file distribution can restart theadapter.


You can manually stop the adapter from the command line with the net stopTECWinAdapter[_adapter_identifier] command where adapter_identifier is theadapter identifier; for example, manually stop an adapter that has no identifierusing this command:net stop TECWinAdapter

or, for an adapter with an identifier of toserver1, manually stop it using thiscommand:net stop TECWinAdapter_toserver1

Reloading the adapter configurationTo reload the adapter configuration and format files, use the wsighup command. Ifyou are running the service version of the adapter, issue this command:wsighup service_adapter_name

where service_adapter_name is the service name of the adapter. If you are runningthe command-line version of the adapter, issue this command:wsighup service_adapter_name pid

where service_adapter_name is the service name of the adapter and pid is the processID of the adapter.

Use this command if you want to change the adapter configuration without havingto stop and restart the adapter. For example, you might want to temporarily add(and later remove) filters or entries in the format file when the system goes intomaintenance mode. After you have made the necessary changes to theconfiguration and format files, issue this command to dynamically update theadapter configuration.

Running multiple Windows event log adaptersYou can run multiple instances of the Windows event log adapter on a singlesystem. It is recommended that additional adapters be run as non-TME adapters.To monitor different log files, each instance of the adapter must have its ownconfiguration, format, class definition statement (CDS), and error files. If theadapters use event buffering (set using the BufferEvents keyword, which has adefault value of YES), the adapters must also have their own cache files.

If you want to stop an adapter when multiple log files are running, you mustspecify the name of the adapter to stop with the net stop


TECWinAdapter[_adapter_identifier] command where adapter_identifier is theadapter identifier. If you do not specify the adapter to stop, the default adapterwithout a name is stopped.

Events listingThe following table shows the class names and severities of all events defined forthe Windows event log adapter. You can use it to get a sense of how Windowsevents are mapped to Tivoli Enterprise Console events and to determine if youwant to make any changes. The events are defined in the BAROC file.


Event class structureEvent classes are defined hierarchically, with child classes inheriting attribute valuedefaults from the parent. The Windows event classes follow a simple hierarchy.


source NT

sub_sourceNT


The following events are defined in BAROC file:

Table 18. Windows event log adapter events

Event Class Severity

NT_Base

NT_Base_Event

NT_Diskfull WARNING

NT_Share_Dir_Missing WARNING

NT_Service_Start WARNING

NT_Service_Stop WARNING

NT_Out_Of_Paper WARNING

NT_Printer_Out_Of_Paper WARNING

NT_Low_Virtual_Memory WARNING

NT_Security_Db_Not_In_Sync WARNING

NT_Registry_Bad_DB WARNING

NT_NCNB_Error WARNING

NT_Parity_Error WARNING

NT_Power_Failure WARNING

NT_Thread_Create_Fail WARNING

NT_Semaph_Create_Fail WARNING

NT_Monitor_Start WARNING

NT_TCPService_Fail


Table 18. Windows event log adapter events (continued)


NT_Master_Browser_Conflict

NT_Document_Print_Success

NT_Document_Print_Deleted

NT_Internal_Error_In_The_DHCP_Server

NT_Performance_Alert

NT_Capacity_Alert

NT_Performance_Monitor

NT_Trustee_Relationship_Failed

NT_Service_Started

NT_Service_Terminated

NT_Printer_Error

NT_Printer_Was_Set

NT_Printer_Was_Created

NT_Printer_Pending_Deletion

NT_Security_Database

NT_Security_Database_Error

NT_Insight_Agent_Disk_Alert

NT_DHCP_Rejected_Allocation_Request

NT_Domain_Not_Contactable

NT_WINS_Alert

NT_WINS_Server_Alert

NT_Master_Browser

NT_Trustee_Relationship

NT_Timeserv_Worked

NT_Timeserv_Failed_1






NT_License_Service_No_License_Available

NT_License_Service_Out_Of_Licenses

NT_Restore

NT_Backup

NT_Replicator_Did_Not_Send_Update

NT_Replicator_System_Error

NT_Replicator

NT_Tivoli_Courier

NT_Tivoli_TEC_Adapter

NT_Tivoli_TEC_Adapter_Error_Sending_Alert


Table 18. Windows event log adapter events (continued)


NT_Sophos_Sweep

NT_SNMP

NT_Insight_Manager_Error

NT_Insight_Manager

NT_Privileged_Service_Called

NT_Trusted_Process_Logon_Success

NT_Logon_Successful

NT_Logon_Failure

NT_User_Logoff

NT_Log_Clear_Successful

NT_Account_Management_Success

NT_Group_Management_Change_Success

NT_Global_Group_Changed

NT_Local_Group_Member_Removed

NT_Account_Password_Change_Success

NT_Server_Start

NT_Application_Error

NT_Table_Reached_Maximum_Size

NT_Handle_Closed

NT_Object_Open

NT_Audit_Policy_Change

NT_Duplicate_Name WARNING

tecad_win commandThe Windows event log adapter includes the tecad_win command, which you canuse to start the adapter in non-service mode. The command description is on thefollowing pages.


tecad_win

Starts the Windows event log adapter in non-service mode.

Syntaxtecad_win.exe [–d] [–c ConfigFile] [–L none | EventLog ...] [–i ID]

DescriptionThe tecad_win command starts the Windows event log adapter in non-servicemode. You can use the non-service mode for diagnostic purposes or to view eventmessages in a Windows console window. The Windows service mode adapter mustbe stopped before the non-service mode adapter is started. To stop the servicemode adapter, run the following from the command line:net stop TECWinAdapter

Before starting the non-service adapter, set the TECADHOME environmentvariable.

Authorization: none

Arguments:

–c ConfigFileSpecifies the configuration file for the Windows event log adapter. If avalue is not specified, the tecad_win.conf file in the current directory isused. If the –c argument is used, you can optionally specify a full pathname for the configuration file; otherwise, one of the appropriatedirectories specified in “File location” on page 9 is used.

–d Shows debug information as events are gathered and transmitted. Thisargument also selects a verbosity level of 1.

Note: When running a non-TME version of the Windows event logadapter in this mode, make sure that no other adapters of the samesource are running at the same time.

–i ID Specifies the identifier for the adapter. The ID is used to specify thedirectory containing the configuration and format files. It also enablesmultiple adapters to be run.

–L Specifies which Windows event logs, if any, to monitor.

none Specifies that no Windows event logs are monitored.

EventLog ...

Specifies which Windows event logs are monitored. Values areApplicationLog, DirectoryLog, DNSServerLog, FileReplicationLog,SecurityLog, and SystemLog. When specifying more than oneevent log, separate the entries with a space.

The following command starts the Windows event log adapter in diagnostic mode:tecad_win –d

The following command starts the Windows event log adapter with themyconfile.conf configuration file:tecad_win –c myconfile.conf

Note: The .conf file must be in the /etc directory where the adapter is installed.


Troubleshooting the Windows event log adapterPerform the following steps to troubleshoot the Windows event log adapter:1. Stop the Windows event log adapter that is currently running by pressing the

Esc key in the command window session that is running the Windows eventlog adapter. Pressing the Ctrl+c key combination in the command windowsession that is running the Windows event log adapter also stops the adapter.

2. Start the adapter in debug mode:tecad_win -d -c Config_File

3. Generate test events and see if the adapter receives them. Do this by startingand stopping a service that logs to the Windows Event Manager. For example,you can use the Windows Control Panel Services to stop the FTP Server andthen start it. This adds an event entry in the Windows Security Log that ispicked up by the Windows event log adapter.Another effective way to generate and monitor Windows events is to run theWindows User Manager application (located in the Administrative Toolsfolder). Select Audit from the Policies menu and choose from the differentactivities that Windows can monitor. You want these items to be audited andthen picked up by the Windows event log adapter.Yet another method is to set up an alert in Windows Performance Monitor(located in the Administrative Tools folder) to go off every 30 seconds whenthe processor usage is less than 100%.

4. When events arrive, the adapter prints messages to the screen indicating theclass and the attribute values in the class.If you do not see any messages, the adapter is not receiving events from theWindows event logs.For example, you should see a message that the FTP server has registered as atrusted login process. If you do not see this message, run the Windows UserManager application (located in the Administrative Tools folder), select Auditfrom the Policies menu and choose Restart, Shutdown, and System events tobe audited for Success and Failure. Then stop and restart the Windows FTPserver as described in steps 1 and 2.

5. If you see the messages, the adapter is receiving events and processing them.Run the wtdumprl command on the event server and verify that the messagesare actually showing up in the reception log. If not, the events were notreceived by the event server or there is a problem with the event serverreception process. Check the adapter configuration file to verify thatTransportList (or ServerLocation and ServerPort) is properly defined. If theevent class is in any filter entry in the configuration file, the event is not sent tothe event server. The administrator who started the adapter must have therequired roles if you are running the TME version of the adapter. For a TMEadapter, running the odstat command can offer some clues as to what failed.


7. If the previous steps do not indicate any problem and you do not see the newevents in the Tivoli Enterprise Console product, there might be a problem withthe event group filters. Make sure the class filters match the classes in theBAROC files.



Appendix A. Files shipped with adaptersNotes:

1. The IBM NetView for OS/390® adapters are delivered with Tivoli NetView forOS/390 as part of the Event/Automation Service. Although these adapters areshipped as part of that product, the BAROC files and rule files for them areshipped with the Tivoli Enterprise Console product. For information aboutadditional files shipped with these adapters, see the Tivoli NetView for OS/390documentation.

The following table lists some of the files used with the shipped adapters. An xindicates the file is used by an adapter.

Table 19. Files shipped with adapters

File Extension

Adapter

AS

/400

Ale

rt

AS

/400

Mes

sage

Net

War

e

Op

enV

iew

OS

/2

SN

MP

UN

IXL

ogFi

le

Win

dow

sE

ven

tL

og

BAROC .baroc x x x x x x x x

Class definition statement(CDS)

.cds x x x x x x x x

Configuration .conf 1 x x x x x x x x

Error .err x x x x x x

Format .fmt x x x

Installation script .cfg2 x x x x

Object identifier .oid x x

Registration .lrf x

Rules .rls3 x x x x

1. The AS/400 adapters use a .mbr extension.

2. The OS/2 adapter actually uses a command file (.cmd) for performing this function.

3. A rules file is not shipped with the AS/400 message adapter. You can create a rules fileif needed.

The following table lists the file names for some of the more significant files usedfor the IBM Tivoli Enterprise Console adapters:


Table 20. Adapter files

Adapter Extension File Name

AS/400 alert .baroc /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRBRC.MBRtecad_snaevent.baroc (on event server)

.cds /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR

.conf /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR

.rls /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRRLS.MBRtecad_snaevent.rls (on the event server)

AS/400 message .baroc /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGBRC.MBRas400msg.baroc (on the event server)

.cds /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR

.conf /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR

NetWare .brc tecadnw4.brc

.cds tecadnw4.cds

.cnf tecadnw4.cnf

.err tecadnw4.err

.fmt tecadnw4.fmt

OpenView .baroc tecad_hpov.baroc

.cds tecad_hpov.cds

.cfg tecad_hpov.cfg

.conf tecad_hpov.conf

.err tecad_hpov.err

.oid tecad_hpov.oid

.rls ov_default.rls

OS/2 .baroc tecados2.baroc

.cds tecados2.cds

.cmd tecados2.cmd

.conf tecados2.conf

.err tecados2.err

.fmt tecados2.fmt

SNMP .baroc tecad_snmp.baroc

.cds tecad_snmp.cds

.cfg tecad_snmp.cfg

.conf tecad_snmp.conf

.err tecad_snmp.err

.oid tecad_snmp.oid


Table 20. Adapter files (continued)

Adapter Extension File Name

UNIX log file .baroc tecad_logfile.baroc

.cds tecad_logfile.cds

.cfg tecad_logfile.cfg

.conf tecad_logfile.conf

.err tecad_logfile.err

.fmt tecad_logfile.fmt

.rls log_default.rls

Microsoft Windowsevent log

.baroc tecad_win.baroc

.cds tecad_win.cds

.conf tecad_win.conf

.err tecad_win.err

.fmt tecad_win.fmt

Appendix A. Files shipped with adapters 185

Appendix B. Format file reference

This appendix contains details about format files.

The format file usually has an extension of .fmt; see each specific adapter chapterfor exact file names. To use non-English characters in a format string, you mustenter the non-English characters in the local encodings.

Notes:

1. Although this section describes the manual text editing of a format file and thefile organization, you can accomplish the same results for TME adapters withthe Logfile Format Editor of the Adapter Configuration Facility. See the IBMTivoli Enterprise Console User’s Guide for information about using the LogfileFormat Editor.

2. The UNIX logfile adapter, NetWare logfile, and OS/2 adapter format files are inEnglish only. The Microsoft Windows event log format file is in English andlocalized into a sample file for the Tivoli supported languages. If you have asource that issues events in a non-English language and you are monitoringthat source with an adapter that uses a format file, and the format file has notbeen localized, you must localize the format file in that language.

Format file locationAn English-language format file is located in each of the language subdirectoriesthat are in the same directory as the adapter configuration file. The languagesubdirectories are as follows:

Table 21. Format file location

Language Subdirectory

English /C

German /de

Spanish /es

French /fr

Italian /it

Japanese /ja

Korean /ko

Brazilian Portuguese /pt_BR

Simplified Chinese /zh_CN

Traditional Chinese /zh_TW

See “File location” on page 9 for more details.

Format specificationsThe format file is made up of one or more format specifications. A formatspecification has the following parts:v Format header


The keyword FORMAT followed by the event class name. This is optionallyfollowed by the FOLLOWS keyword and a previously defined class name, asshown in the following example:FORMAT NT_Share_Dir_Missing FOLLOWS NT_Base

Note: A format specification with the same class name can be defined more thanonce. Be careful of using multiply-defined format specification classnames with the FOLLOWS keyword. Because there is no way to specifywhich actual format specification is intended, the last one defined in thefile that matches the class name is used.

v Format contentA format string optionally followed by a list of mappings, as shown in thefollowing example:%t %s %s %s %s %s %s The server service was unable to recreatethe share %s because the directory %s no longer exists.sharename $8directoryname $9

v The END keyword completes the format specification.

The format header, format string, each mapping, and the END keyword must eachbegin on a new line, as shown in the following example:FORMAT NT_Share_Dir_Missing FOLLOWS NT_Base%t %s %s %s %s %s %s The server service was unable to recreatethe share %s because the directory %s no longer exists.sharename $8directoryname $9END

The FOLLOWS relationship enables specific format specifications to be built fromgeneric format specifications using inheritance. When format B follows format A, Binherits all of the mappings (but not the format string) from A. Format B candefine any additional mappings, but any mappings redefined by B are notinherited from A; that is, format B can override inherited mappings by redefiningthem.

System log messages typically have a common format consisting of a time stamp, ahost name, and event text. These system log message components are representedin a format string using a component-specifier notation very similar to theprintf() notation used in the C programming language. The following formatstring describes the entire class of system log messages produced by the UNIXsyslogd daemon:%t %s %s*

System log messages are tokenized into constants and white space. A constant isany consecutive string of non-white spaces. The component specifiers enable theconstants and white space to be grouped into more complex tokens when trying tomatch a format string with a specific message. The component specifiers alwaysend in a constant and not white space. The component specifiers are as follows:v %[length]s

Matches one constant in the message. The optional length is a decimal numberof any size and indicates that the constant is to be truncated to the length if theconstant actual length is greater than the specifier length.

v %[length]s*


Matches zero or more constants in the system log message. The optional lengthis a decimal number of any size and indicates that any of the accumulatedconstants is to be truncated to the length if the constant actual length is greaterthan the specifier length.

v %[length]s+

Matches one or more constants in the message. The optional length is a decimalnumber of any size and allows any of the accumulated constants to be truncatedto the length if the constant actual length is greater than the specifier length.

v %t

Matches a time stamp of the following form:

month date time

v %n

Matches a carriage return in the message. Use this specification to matchmessages that span multiple lines.

Log file exampleThe following successful su message from a system log is an example of matchinga system log message to the generic format specification mentioned in thepreceding section:Sep 13 12:17:11 elcap su: ’su root’ succeeded for tjones on /dev/ttyp0

The component specifiers and matches are as follows:

%t Sep 13 12:17:11

%s elcap

%s* su: ’su root’ succeeded for tjones on /dev/ttyp0

The system log message contains some constant parts and some variable parts. Theconstant parts of the system log message are the same for any successful sumessage. The constant parts are as follows:v su: ’suv ’ succeeded forv on

The variable parts of the example system log message are as follows:v Sep 13 12:17:11v elcapv rootv tjonesv /dev/ttyp0

The following example shows how the variable data differs in another successfulsu message:Sep 29 14:57:28 aspen su: ’su root’ succeeded for jsmith on /dev/ttypd

The general format specification %t %s %s* can be specialized for the Su_Successevent class as follows:%t %s su: ’su %s’ succeeded for %s on %s

Appendix B. Format file reference 189

Using the system log message from the preceding September 29 example, thecomponent specifiers and matches are as follows:

%t Sep 29 14:57:28

%s aspen

su: ’susu: ’su

%s root

succeeded forsucceeded for

%s jsmith

on on

%s /dev/ttypd

The white space characters that separate the words of a system log message mustalso be present in the format string. A single space character (that is, one blank) inthe format string matches any number of white space characters in the message.For example, if the space between the colon (:) and the quotation mark (’) isdeleted in the preceding specialized format string, as shown in the followingexample, the system log message would no longer match it.%t %s su:’su %s’ succeeded for %s on %s

Care should be taken when using the arbitrary length repeater componentspecifiers (%s* and *s+). The following format string does not make much sense:This is not a good format %s* %s*

The first %s* matches everything through the end of the message, and the second%s* never matches anything. Although it might seem that this does not matter, theimportance is described in “Mappings” on page 191.

The following format string, however, is meaningful:This is a good format %s* : %s*

The first %s* matches everything up to the first colon (:), and the second %s* nowmatches everything through the end of the message.

The format string must also reflect whether white space precedes a constant orcomponent specifier. In the following example, both messages match a formatstring of %s*company_xyz because they are preceded by zero (0) or more constantsand no white space.company_xyz is logging messages

Acompany_xyz is logging messages

However, the following example requires a format string with a space after the %s*component specifier, as in %s* company_xyz, because it is preceded by white spaceand does not match the previous format string.the company_xyz is logging messages

From the preceding examples, you can see that you can specialize a generic formatstring to match a more specific event by either replacing component specifiers withconstants or by restricting the arbitrary length repeater specifiers to a fixed length,using constants to complete the specifier.


Windows exampleThe following example is a Windows message:Jan 15 15:06:19 1998 0 Error N/A Service_Control_Manager 7024 \The UPS service terminated with service-specific error 2481.

The variable parts are the time stamp (Jan 15 15:06:19 1998), possibly the securityID (N/A), the event ID (7024), the service name (UPS), and the error code (2481).Another system log message uses the same general format, as shown in thefollowing example:Sep 29 14:57:28 1998 0 Error N/A Service_Control_Manager 7025 \The SNMP service terminated with service-specific error 2482.

The constant parts of a system log message are defined by simply embedding themin the format string itself. The variable parts are defined using the componentspecifier. The format string for the preceding September 29 example could bewritten as follows:%t %s %s Error %s Service_Control_Manager %s The %s \service terminated with service-specific error %s.

The white space characters that separate the words of a system log message mustalso be present in the format string. A single space character (that is, one blank) inthe format string matches any number of white space characters in the message.

Care should be taken when using the arbitrary length repeater componentspecifiers (%s* and *s+). The following format specification does not make muchsense:This is not a good format %s* %s*

The first %s* matches everything through the end of the message, and the second%s* never matches anything. Although it might seem that this does not matter, theimportance is described in “Mappings” on page 191.

The following format string, however, is meaningful:This is a good format %s* : %s*

The first %s* matches everything up to the first colon (:), and the second %s* nowmatches everything through the end of the message.

MappingsThe logfile adapters translate system log messages into event class instancescontaining attribute name=value pairs. The event is then sent to the event server. Anassociated BAROC file containing class definitions at the event server is used tovalidate the incoming event before processing the event further.

For the logfile adapters, the event class for a system log message is determined atthe source by matching a system log message to a format string in the format file.After a class is determined by this matching, values must be assigned to theattributes. Attribute values can come from a variety of sources, such as from thesystem log message itself, from default values provided by the adapter, or frommappings within the format specification of a class in the format file. This sectiondescribes how the mappings in a format specification assign values to attributes.


The mapping part of a format specification consists of zero or more lines thatcontain a BAROC file attribute name followed by a value specifier. The valuespecifiers can be one of the following types:

$i Where i indicates the position of a component specifier in a format string.Each component specifier is numbered from 1 to the maximum number ofcomponent specifiers in the format string. For example, in the specializedformat specification for the Su_Success event shown following, the third%s component specifier (in bold) would be referred to in any mappings as$4.%t %s su: ’su %s’ succeeded for %s on %s

The value of a $i value specifier (also referred to as a variable) is theportion of the system log message that was consumed by the componentspecifier.

string constantThe value of the attribute is the specified string. If the string is a singleconstant, it can be specified without surrounding double quotation marks(" "); otherwise, double quotation marks must be used.

PRINTF statementCreates more complex attribute values from other attribute values. ThePRINTF statement consists of the keyword PRINTF followed by a printf()C-style format string and one or more attribute names. The format stringsupports only the %s component specifier. The values of the attributes thatare used in the PRINTF statement must also have been derived from eithera $i value specification or a constant string value specification (they cannotbe derived from another PRINTF statement). The value of the argumentattributes is used to compose a new constant string according to the formatstring. This new constant string becomes the value of the attribute.

The following example shows how the msg attribute is assigned theconstant string value of date set by mfoster. User ID mfoster wasderived from the value assigned to the set_by attribute.msg PRINTF("date set by %s", set_by)

DEFAULT keywordIndicates the adapter uses its internal logic to assign a value to theindicated attribute. For example, the UNIX syslogd messages contain thehost name where the message was logged; the adapter can use this nameto derive the origin attribute (the protocol address or host name of theoriginating host).

Note: Adding new DEFAULT mappings also requires changes to anadapter source code to add new logic for obtaining attribute values.

Because DEFAULT is a keyword, a constant mapping whose value is thestring DEFAULT must be specified in double quotation marks (" ").

FILENAME keywordIndicates the fully qualified file name (including path) of the log filecontaining the message. In cases where you are using a single adapter tomonitor multiple log files, you can use this key word to populate an eventattribute with the file name to identify the source of the event. If themessage comes from the system log, then mapping is set to "EventLog" forWindows adapters and "SysLogD" for UNIX logfile adapters.


LABEL keywordIndicates the type of system on which the adapter is running, whichprovides better control over the hostname attribute coming from theadapter. For a managed node, the value is the managed node name; in anendpoint, it is the endpoint name, which is listed in last.cfg aslcs.machine_name. In a non-TME adapter, the value is the host name of thesystem.

Additional mapping considerationsSpecify only one mapping for each BAROC file attribute.

A mapping can be inherited from a more generic format specification (using theFOLLOWS keyword) or can be explicitly defined on the format specification thatdirectly matches the message.

Because the adapter does not access the BAROC file, which resides on the eventserver, care must be taken to make sure that the format specifications agree withthe corresponding BAROC file definitions. If an attribute name is misspelled in amapping, the adapter does not report an error but does send the event to the eventserver as usual; however, the event is discarded by the event server because it doesnot exactly match a class definition.

There can be attributes in the system log message that do not directly correspondto any BAROC file attributes because the adapter might need to use these valuesto compose PRINTF style constant strings for assigning to attributes. This type ofdata needs to be assigned to temporary attributes that do not get sent to the eventserver, but are used in the PRINTF statement. Temporary attributes are designatedwith a hyphen (-) immediately preceding the attribute name in a mapping.

To illustrate the use of mappings in format specifications, a sample from thedefault tecad_logfile.fmt file is shown following with a few additions.FORMAT Logfile_Base%t %s %s*date $1hostname $2msg $3origin DEFAULTEND

/* login */// NOTE -- anything enclosed in ’/*’ and ’*/’ pairs is considered to// be a comment. These comments can extend across multiple lines.// Anything following a ’//’ is also considered to be a comment;// this comment only extends to the end of the line.

FORMAT Logfile_Login FOLLOWS Logfile_Base%t %s login: %s*sub_source loginEND

FORMAT Root_Login FOLLOWS Logfile_Login%t %s login: ROOT LOGIN %s*END

FORMAT Root_Login_Success FOLLOWS Root_Login%t %s login: ROOT LOGIN %son_tty $3msg PRINTF("root login %s", on_tty)END


FORMAT Root_Login_Success_From FOLLOWS Root_Login_Success%t %s login: ROOT LOGIN %s FROM %sfrom_host $4-extra ", with extra stuff!"msg PRINTF("root login from %s%s", from_host, extra)END

Now, assume that the following system log message is received by the logfileadapter:Dec 10 09:45:06 sawmill login: ROOT LOGIN ttyp6 FROM oak

The logfile adapter attempts to match this system log message to the most specificformat specification. In this case, the event matches the Root_Login_Success_Fromformat specification. The event created by the logfile adapter therefore has an eventclass of Root_Login_Success_From. The following mappings then take place:

Mapping Assignments Source of Mapping

$1="Dec 10 09:45:06" From the %t component specification

$2="sawmill" From the first %s component specification

$3="ttyp6" From the second %s component specification

$4="oak" From the third %s component specification

date="Dec 10 09:45:06" From $1

hostname="sawmill" From $2

origin= 9.37.43.12" From the default value of the originattribute, as derived by the logfile adapter

sub_source="login" From the constant string

on_tty="ttyp6" From $3

from_host="oak" From $4

-extra=", with extra stuff!" From the constant string

msg="root login from oak, with extrastuff!"

From the PRINTF statement

The following list describes how values were assigned:v The date and hostname attributes were inherited from the Logfile_Base class

(through the Logfile_Login, Root_Login, and Root_Login_Success classes).v The origin attribute was also inherited from the Logfile_Base class, and was

assigned the adapter default.v The msg attribute was not inherited from the Logfile_Base class, because it was

overridden by the Root_Login_Success_From class.v The sub_source attribute was inherited from the constant string defined in the

Logfile_Login class.v The on_tty attribute was inherited from the Root_Login_Success class.v The from_host attribute was explicitly defined on the Root_Login_Success_From

class.v The extra attribute was defined as a temporary attribute. It is not forwarded to

the event server as a part of this event.

There are a couple of other interesting items to note from this example:v In the PRINTF value specification for the msg attribute in the

Root_Login_Success_From class, two %s conversions are specified without any


intervening white space. This enables the final msg attribute value to be createdwithout any space between the string oak and the comma.

v In the Root_Login format specification, there are no explicit mappings; allmappings are inherited. This allows class name specialization without changingany attribute values. Any event that matches the Logfile_Login class has thesame attributes and values as those that match the Root_Login class, but theclass name is different.

v Variables are resolved from the matching format specification, even if they areinherited. For example, if the msg attribute had not been overridden with thePRINTF statement in the Root_Login_Success_From class, its value would havebeen ttyp6. This is because the msg attribute is inherited as the third componentspecification in the event, even though the third component in the originatingclass (Logfile_Base) would have yielded the value sawmill login: ROOT LOGINttyp6 FROM oak.

Activating changes made with a format fileIf you have made changes to a format file, you must generate a new classdefinition statement (CDS) file that contains those changes.

Generating a new class definition statement file for a TMEadapter

To generate a new CDS file for a TME adapter, simply distribute a profilecontaining the changed format file to the appropriate endpoints. The shippeddefault profile contains the appropriate commands to automatically perform thefollowing actions:1. Stop the adapter.2. Generate a new CDS file from the distributed format file.3. Restart the adapter.

These commands can be viewed for the profile being distributed by selectingActions in the Edit Adapter window of the Adapter Configuration Facility.

Generating a new class definition statement file for a non-TMEadapter

To generate a new CDS file for a non-TME adapter, you must perform thefollowing tasks:1. Stop the adapter.

NetWare logfileSee “tecadnw4.nlm” on page 121.

OS/2 See “Stopping the adapter” on page 141.

UNIX logfileSee “Stopping the adapter” on page 155.

Windows event logSee “Stopping the adapter” on page 177.

2. Generate a new CDS file using the following commands. The logfile_gencds,nw4gencds.nlm, os2gncds.exe, and win_gencds.exe programs are located inthe bin subdirectory of the directory where you installed the adapter. Theformat file is in the appropriate language subdirectory in the etc directory


where you installed the adapter (see “Format file location” on page 187 for theappropriate language subdirectory). Specify the appropriate path to create thenew CDS file in the etc directory.OS/2os2gncds /language/tecados2.fmt tecados2.cds

UNIX logfilelogfile_gencds /language/tecad_logfile.fmt > tecad_logfile.cds

Windows event logwin_gencds /language/tecad_win.fmt tecad_win.cds

3. Restart the adapter:

NetWare logfileSee “tecadnw4.nlm” on page 121.

OS/2 See “Starting the adapter” on page 140.

UNIX logfileSee “Starting the adapter” on page 155.

Windows event logSee “Starting the adapter” on page 176.


Appendix C. Class definition statement file reference

A class definition statement (CDS) file specifies SELECT, FETCH, and MAPstatements for all event classes supported by adapters that utilize a CDS file. Thisprovided file is required for most adapters and has the same format for alladapters that use it. A CDS file has an extension of .cds; see each adapter chapterfor exact file names.

File formatMost of the CDS file is composed of class definition statements. A CDS file has thefollowing format:MAP_DEFAULT

map_default_clauseEND

CLASS class_nameSELECT

select_clause ...FETCH

fetch_clause...

MAPmap_clause

END

Comment lines begin with a number sign (#). For syntax reference information inBNF notation, see “Class definition statement file syntax diagrams” on page 202.

OperatorsVarious operators are used in class definition statements, as follows:v The PREFIX and SUFFIX operators are valid only for string attribute names,

values, or keys.v The CONTAINS operator is valid only on string values.v The not equals (!=), greater than (>), greater than or equals (>=), less than (<),

and less than or equals (<=) operators are applicable only to integer values; theyare not implemented for integer keys.

The following is an example of the use of the operators. In this example, the codeis for an AS/400 message adapter:CLASS AS400_MSG

SELECT1: ATTR(=,$MSG), VALUE(PREFIX,"Job");2: ATTR(=,$MSG), VALUE(CONTAINS,"for User");3: ATTR(=,$MSG), VALUE(SUFFIX,"You must investigate.");

FETCH1: SUBSTR($MSG,4,8)2: SUBSTR($MSG,22,8)

MAP$severity = CRITICAL;$msg = PRINTF("Job %s for user %s is on message wait", $F1, $F2);

END

Table 22 on page 198 describes each statement in the example:


Table 22. Explanation of operators in example code

Code Explanation

SELECT

ATTR(=,$MSG), VALUE(PREFIX,"Job");

A match occurs when any message arrivingwith the Class=AS400_MSG, where the firstpart of the message field equals Job.

SELECT

ATTR(=,$MSG), VALUE(CONTAINS,"for User");

A match occurs when the message fieldcontains for User anywhere within themessage text.

SELECT

ATTR(=,$MSG), VALUE(SUFFIX,"You must investigate.");

To match, the end of the message field must bethe text You must investigate. The case of themessage must be exactly as shown in theexample.

FETCH

SUBSTR($MSG,4,8)SUBSTR($MSG,22,8)

This part of the FETCH statement pullscharacters from the message field. It starts atcharacter 5, because it is zero-based. It pulls atotal of eight characters. For example, themessage is Job 12345678 for User stephenshas stopped. You must investigate. Thestatement pulls 12345678 for the first line of theFETCH statement. The second line pulls thetext stephens.

MAP

$severity = CRITICAL;$msg = PRINTF("Job %s for user %s is on message wait", $F1, $F2);

The severity attribute is set to CRITICAL. Itprints using the two items that were pulledwith the FETCH statement.

Class definition statement file detailsFor each class of event supported by an adapter, one or more class definitionstatements are present in the CDS file. These statements define which incomingevent maps to a particular class and how the attributes of the formatted eventinstance going to the event server are filled with values. The class definitionstatements are described as follows:

SELECTSpecifies the criteria an incoming event must satisfy to match a class.

FETCHRetrieves data from the incoming event that is necessary to fill the attributevalues.

MAP Specifies how to fill attribute values for an event instance from dataretrieved by FETCH statements.

Class definition statements are evaluated in the order they occur in the CDS file.An incoming event is mapped to the class specified by the first class definitionstatement whose SELECT statement is evaluated successfully.

When more than one class definition statement is provided for a particular class ofevent, the class definition statement with the most restrictive SELECT statement isplaced before the less restrictive statements in the CDS file. Locating the mostrestrictive class definition statement first for a same-named class provides forbetter performance of the adapter.

If the class name equals *DISCARD*, any incoming event matching the SELECTstatement is discarded. Note that an event is also discarded if it does not matchany class definition statement. However, if a particular type of incoming eventmust always be discarded (for example, routine events that are of no importance toadministrators), it is more efficient to define a *DISCARD* class definition statement


and locate it at the beginning of the CDS file, rather than let the adapter evaluateall class definition statements and finally discard the event.

SELECT statementThere is one SELECT statement for each class definition statement. SELECTstatements have the following general format, where n is the identification numberof a clause within a SELECT statement:SELECTn: ATTR(a_op, a_op_value),

KEY(k_op, k_op_value),VALUE(v_op, v_op_value);

The ATTR part is mandatory and specifies a condition on the attribute name. TheKEY and VALUE parts are optional and respectively specify a condition on theattribute key and attribute value. a_op, k_op, and v_op are available operators toexpress conditions over the attribute name, key, or value (=, !=, <, <=, >, >=,PREFIX, SUFFIX, CONTAINS). a_op_value, k_op_value, and v_op_value specify thecomparison value.

In order for a SELECT statement to be evaluated successfully, the followingconditions must be met as follows:v The incoming event must contain an attribute whose name matches the ATTR

part. If the match is not unique (that is, several attributes can match the ATTRpart), only the first match is used. It is the key and value of this attribute that isreferred to in the rest of the statement. For example:ATTR(=,"ifDescr")

means that the incoming event must contain an attribute named ifDescr.v If a KEY part is present, the key of the attribute selected during the previous

step must match the condition expressed by the KEY() expression. For example:KEY(!=,1)

means that attribute ifDescr must have a key with a value other than 1.

Note: AS/400 adapters do not support KEY parts in CDS files.v If a VALUE part is present, the value of the attribute must match the condition

expressed by the VALUE expression. For example:VALUE(PREFIX,"Serial")

means that the value of attribute ifDescr must begin with Serial (for example,Serial1).

Using the previous examples, the complete clause of the SELECT statement readsas follows:SELECT1: ATTR(=,"ifDescr"), KEY(!=,1),

VALUE(PREFIX,"Serial");

SELECT statements and their associated clauses are evaluated in the order theyoccur in the CDS file. If all the clauses of a SELECT statement are evaluatedsuccessfully, the incoming event matches the corresponding class.

After an event is matched with a class because of successful SELECT statementevaluation, processing continues with the FETCH statement, unless the classis *DISCARD*, in which case the event is discarded. If the evaluation of a SELECT

Appendix C. Class definition statement file reference 199

statement fails, the kernel tries to match the event with the SELECT statement ofthe next class. If the incoming event cannot be matched with any class, it isdiscarded.

Each time a SELECT statement is evaluated successfully, the adapter kernel layercreates three temporary pseudo-variables: $Nn, $Kn, $Vn (where n is theidentification number of a clause in the SELECT statement). These variablescontain the name, key, and value of the attribute specified in the clause,respectively. The pseudo-variables can then be used in any following SELECT,FETCH, or MAP statement.

The default setting is that the attribute name specified in an ATTR() expression is astring, and the attribute matching this name is searched for sequentially in theincoming event. For most adapters, every incoming event contains a minimum setof mandatory fields. For this reason, each adapter supports built-in keywords thatcan be used to reference these mandatory attributes and thereby directly accesstheir values. These keywords have the format $attribute_name. Examples ofkeywords supported by the SNMP adapter are: $AGENT_ADDRESS,$COMMUNITY, $ENTERPRISE, $TYPE, and $SPECIFIC. These keywords refer tothe mandatory fields of an SNMP Trap-PDU. Each adapter can also define globalvariables, such as RECEPTION TIME, SVARBIND, and so forth.

Using the $ notation, a clause for SNMP authentication failure traps can be writtenas follows:1: ATTR(=,$TYPE),VALUE(=,4);

This notation is not simpler than the format shown in the previous example,ATTR(=, "type"), but evaluation is faster because it results in direct access to thevariable instead of a linear search.

The syntax shown in the preceding example is generic, and as such, it can berather verbose for commonly used criteria. Several shortcuts are provided toalleviate the notation. For example, the previous example can be written as follows:1:$TYPE=4;

Output from the class selection process is the name of the event class, a table ofpseudo-variables $Nn, $Kn, $Vn, and all adapter-specific variables (for example,$TYPE, $VARBIND, and so forth).

FETCH statementThe FETCH statement of a class definition statement enables manipulation andmodification to the attribute names, keys, and values retrieved by the SELECTstatement for the incoming event. Sometimes it is necessary to perform tasks suchas extracting a substring from an attribute value, adding two values, and so forth.

There can be one or more clauses within a FETCH statement. Each clause has thefollowing format:

n:expression;

where n is the identification number of a clause within a FETCH statement andexpression is an expression specifying the value to assign the pseudo-variable $Fn.Pseudo-variables are the output from a clause of a FETCH statement. Thisexpression can make reference to any pseudo-variable defined by the adapter,


which could have been created from the SELECT statement or from a previousclause within the FETCH statement for the class.

An example of a FETCH statement is as follows:FETCH

1:SUBSTR ($V2, 1, 5 );

MAP statementThe MAP statement of a class definition statement assigns values to the attributesof the event class instance.

There can be one or more clauses in a MAP statement. Each clause has one of thefollowing two formats:

attribute_name=variable;attribute_name=PRINTF(format_string,var1,...);

An example of a MAP statement is as follows:MAP

origin=$AGENT-ADDRESS;msg=PRINTF("Link %s is DOWN",$V3);

The output from a MAP statement is a list of attribute name=value pairs that isused to generate the outgoing event for the event server.

MAP_DEFAULT statementSome attributes, like source and sub_source, could have a constant value for all theevents generated by an adapter type. To not repeat identical clauses for MAPstatements in all class definition statements for an adapter, the CDS file can containa MAP_DEFAULT statement. The MAP_DEFAULT statement specifies defaultvalues for the mandatory attribute name=value pairs. The following exampleillustrates a MAP_DEFAULT statement:MAP_DEFAULT

source = SNMP;sub_source = NET;

# forwarding_agent = $SOURCE_ADDR;origin = $AGENT_ADDR;adapter_host = $ADAPTER_HOST;

END

ExampleThe following example shows a CDS file:## Default attribute values#MAP_DEFAULT

source=NET;sub_source=SNMP-TRAP;origin=$SOURCE_ADDR;

END

CLASS Authentication_Failure_CiscoSELECT

1: ATTR(=,$ENTERPRISE), VALUE(PREFIX, "1.3.6.1.4.1.9");2: $TYPE = 4;3: ATTR(=,"authAddr");



MAPhostname = $F1;originating_address = $V3;

END# For Cisco routers, because we know the interface generating the trap,# we map ’linkUp’ traps to ’linkDown’ CLOSED eventsCLASS Link_Down_Cisco

SELECT1: ATTR(=,$ENTERPRISE), VALUE(PREFIX, "1.3.6.1.4.1.9");2: $TYPE = 3;3: ATTR(=,"ifIndex");4: ATTR(=,"ifDescr");5: ATTR(=,"ifType");6: ATTR(=,"locIfReason");


MAPhostname = $F1;sub_origin = $V4;status = CLOSED;interface_index = $V3;interface_description = $V4;interface_type = $V5;reason = $V6;

END

Object identifier to name translationThe selection of an attribute is based on its name. With adapters that receiveSNMP trap messages, the standard way of naming attributes is to use objectidentifiers (OIDs). For example, SNMP variable ifDescr is named 1.3.6.1.2.1.2.2.1.2.Using SNMP object identifiers in SELECT statements is not very convenient.Additionally, because the SNMP variable ifDescr is part of a table, it is indexed bythe interface number. If the interface number is 2, the received object identifier is1.3.6.1.2.1.2.2.1.2.2. Without some knowledge of the Management Information Base(MIB), the SNMP adapter has no way to translate an object identifier into a moreunderstandable name, or to extract key parts from an object identifier.

An object identifier file (tecad_adaptername.oid) for SNMP-based adapters containsOID-to-name mappings for some SNMP variables. You can add or modify this fileas needed. The format of an object identifier file is:

name object_identifier

For example:"authAddr" "1.3.6.1.4.1.9.2.1.5""ifDescr" "1.3.6.1.2.1.2.2.1.2"

Class definition statement file syntax diagramsThis section describes the syntax for statements that can be used within a CDS file.The syntax is shown in BNF-like notation where the vertical bar (|) characterrepresents alternatives, and optional parts are contained within braces ({}).** FILE CONTENT*/

<file> ::= <statements> | /* empty */<statements> ::=

<statement>| <statement> <statements>


<statement> ::=<mapdefault_statement>

| <class_statement>

/** MAP_DEFAULT STATEMENT*/

<mapdefault_statement> ::=MAP DEFAULT

<mapdef_statements>END

<mapdef_statements> ::=<mapdef_statement>

| <mapdef_statement> <mapdef_statements>

<mapdef_Statement> ::=<attribute_name> ’=’ <constant> ’;’

| <attribute_name> ’=’ <keyword> ’;’<attribute_name> ::+ <atom>

/** CLASS STATEMENT*/

<class_statement> ::=CLASS <class_name>

{ SELECT<select_statements> }

{ FETCH<fetch_statements> }

{ MAP<map_statements> }

END

<class_name> ::+*DISCARD*

| <atom>

/** SELECT STATEMENT*/

<select_statements> ::=<select_statement>

| <select_statement> <select_statements>

<select_statement> ::=<number> ’:’ <attr_decl>

{ ’,’ <key_decl> }{ ’,’ <value_decl> }

’;’| <number> ’:’ <keyword> ’=’ <v_op_val> ’;"| <number> ’:’ <constant> ’=’ <v_op_val> ’;’

<attr_decl> ::=ATTR ’(’ <a_op> ’,’ <a_op_val> ’)’

<key_decl ::=KEY ’(’ <k_op> ’,’ <v_op_val> ’)’

<a_op> ::=’=’

| PREFIX| SUFFIX| EXISTS

<a_op_val> ::=<constant>

| <keyword>| <name_var>| <key_var>| <value_var>


<k_op> ::=’=’

| ’!=’| ’>’| ’>=’| ’<’| ’<=’| PREFIX| SUFFIX| EXISTS

<k_op_val> ::=<constant>


<v_op> ::=’=’

| ’!=’| ’>’| ’>=’| ’<’| ’<=’| PREFIX| SUFFIX| EXISTS

<v_op_val> ::=<constant>


/** FETCH STATEMENT*/

<fetch statements> ::=<fetch_statement>

| <fetch_statement> <fetch_statements>

<fetch_statement> ::= <number> ’:’ <fetch_expr> ’;’

<fetch_expr> ::=<fetch_value>

| <substr_expr>

<fetch value> ::=<constant>

| <keyword>| <name_var>| ckey_var>| <value_var>| <fetch_var>

<substr_expr> ::=SUBSTR ’(’ <fetch_expr> ’.’

<fetch_expr> ’,’<fetch_expr> ’)’

/** MAP STATEMENT*/

<map_statements> ::=<map_statement>

| <map_statement> <map_statements>


<map_statement> ::=<attribute_name> ’=’ <map value> ’;’

| <attribute_name> ’=’ PRINTF ’(’ <string> ’,’<map_args> ’)’ ’;’

<map_args> ::=<map_value>

| <map_value> ’,’ <map args>

<map value> ::=<constant>

| <keyword>| <name_var>| <value_var>| <fetch_var>

/** VARIOUS*/

<constant> ::=<string> e.g. hello, "hello"<number> 12

<keyword> ::= ’$<atom>’ e.g. $TARGET

<name_var> ::= ’$N<number>’ e.g. $N12

<key_var> ::= ’$K<number>’ e.g. $K12

<value_var> ::= ’$V<number>’ e.g. $V5

<fetch_var> ::= ’$F<number>’ e.g. $F2

<string> ::=-<quoted_string>

| <atom>

<quoted_string> ::= e.g. "sun", "a ""dog"" !"

<atom> ::= e.g. target, C3000, LINKD_DOWN, in-out


Appendix D. Logfile Format Editor

The Tivoli Enterprise Console Logfile Format Editor is used to add new formatdefinitions of event messages and their mapping to Tivoli Enterprise Consoleevents for the Tivoli logfile event adapter and Windows adapters.

The format file of the logfile adapter and the rule base that supplies the BAROCclasses must reside on the local host. In general, all rule bases should reside on theTivoli Enterprise Console server. The Logfile Format Editor is included with theTivoli Enterprise Console server.

Configuring a format file for a logfile adapterThe following table lists the context and authorization role required to perform thistask.


Configure a logfile adapter Event server user

You can perform this task only from the Tivoli desktop.

Use the following steps to configure format file for a logfile adapter:1. Select Configure Logfile from the context menu on the icon for the event

server. The Tivoli Enterprise Console product displays the Logfile FormatEditor window.


2. Select Open Format from the File menu to display the Select Format Filedialog box.

3. Enter the absolute path name of the directory that contains the logfile formatfile in the Path Name text box. The logfile adapter format file is typically acopy of the tecad_logfile.fmt file that resides in the adapter configuration files.

Note: Only one logfile format file can be edited at a time. There is typicallyone logfile format file for each system and interpreter type (operatingsystem).

For information about using file browser dialogs, see the Tivoli ManagementFramework User’s Guide.

4. Click the Set Path button.5. Select the logfile format file from the Files scrolling list.

6. Click the Set & Close button to open the specified logfile adapter format filefor editing and close the Select Format File dialog box.


7. Select the rule base you want to use from the Open Classes option of the Filemenu.

Note: The Open Format and Open Classes menu items are not active for theremainder of an editing session, because these files are only consultedinitially.

8. Select Open Logfile from the File menu to display the Select Log File dialogbox.

9. Specify the directory that contains the log file to read messages from in thePath Name text box. You can optionally specify the host name where the fileresides by specifying the host name followed by a colon (:), then the filename.

10. Select the log file from the Files scrolling list.11. Click the Set Path button.12. Click the Set & Close button to display a window similar to the following

example.

Note: The Open Logfile option of the File menu remains active throughoutan editing session. You can begin editing another logfile adapter formatfile at any time.

13. From the Logfile Messages to be matched scrolling list, select the logfilemessage to be matched. The following is an example of the dialog that is

Appendix D. Logfile Format Editor 209

displayed.

The event that the selected message would generate is displayed in the Thismessage matches scrolling text box. The Tivoli Enterprise Console productautomatically updates this information in the following steps.

Note: If the selected message does not map to an existing event, the followingmessage is displayed:Message not bound

The Logfile Format Editor displays the current format string in the Messagebeing formatted scrolling text box. This string is the actual message withvariable components replaced by one of the following specifiers:

%s Specifies a variable string.

%t Specifies a variable date of the form 'MMM DD hh:mm:ss', forexample,’Jun 26 10:23:02’.

%s+ Specifies one or more variable strings that are separated by spaces.

%s* Specifies zero or more strings separated by white space.

%n Specifies a new line (CR). This applies only to the following adapters:tecad_logfile_aix4-r1, tecad_logfile_hpux10, tecad_logfile_linux_ix86,tecad_logfile_linux-ppc, tecad_logfile_linux-s390, tecad_logfile_solaris2,and tecad_win.

Note: New line refers to a carriage return or a line feed as opposed tothe entire next line.


14. Click the Clear button to display the selected message in the Message beingformatted scrolling text box.

15. Select a portion of the message in the Message being formatted scrolling textbox by holding the left mouse button and dragging over a portion of themessage. The message portion that should be selected varies from message to


message. In the following example, the date portion is selected.

Note: If you accidentally select any unwanted spaces before or after thepreferred text, click the Clear button and repeat this step.

16. Click the Date button if the selected message text is a date.

—OR—

Click the String button if the selected message text is composed of one ormore strings.

—OR—

Click the FString button if the selected message text is a fixed-length string.For example, if the specifier %2s%3s%4s %3s* the %4s+ is used, the string hewas here but the bird flew away produces the following attribute values:v a = hev b = wasv c = herev d = butv e = bird flew away

In the following example, the Date button was clicked. Notice that theselected (date) portion of the message text has been replaced with a %t in the


Message being formatted scrolling text box.

17. Repeat steps 15 and 16 for the entire message text. After you have selectedand formatted all the message text, the message being formatted should becomposed of all %s or %t representations.

18. Click the Commit button to commit the message format.19. Repeat steps 1 – 18 for each logfile message that is to be matched.20. Click the Select Class button. The Logfile Format Editor displays the Select

Class window.

The Logfile Format Editor displays the defined event classes in the AvailableList scrolling list.

21. Select the event class that the message is to be mapped to from the AvailableList scrolling list.


—OR—Select New Class from the Class menu to create a new BAROC class. TheSelect BAROC file dialog is displayed.

Complete the following steps:a. Select the file that is to contain the new class from the Files scrolling list.

Note: When the event server starts, it reads the files in the order of thefiles in the rule_base_directory/TEC_CLASSES/.load_classes file. Ifyou are defining a subclass of a parent class, be sure to save thesubclass in the file where the parent class is defined, or in a file thatis read after the file where the parent class is defined.


b. Click the Set & Close button to display the Edit Event Class window.

c. Enter the name for the new class in the Class Name text box.d. Click the Add button to add a new attribute. The following is an example

of the dialog that is displayed:

Complete the following steps:


a. Select the attribute name in the Attribute Name text field and press theEnter key.

b. Select the attribute type from the Attribute Type drop-down list. Theattribute type can be String or Integer.

c. Select the default value for the attribute in the Default Value text box andpress the Enter key.

d. Select Yes from the Duplicate detection drop-down list to enable detectionof duplicate events.—OR—Select No from the Duplicate detection drop-down list to disable detectionof duplicate events.

e. Click the Set & Close button to save your changes and display the SelectClass dialog box.

f. Repeat steps b–e for each preferred attribute.22. Click the Set & Close button to close the Select Class dialog and display the

selected event class in the Logfile Format Editor.23. Click the Assign Attributes button to display the Assign Attribute Values

dialog box.

The current attribute mappings in the scrolling list are displayed at the top ofthe dialog box. The map type for each attribute is listed in the Map Typecolumn. The map type is one of the following types:

None Specifies that the attribute has no mapping defined; the adapter doesnot set a value for the attribute. The event server can still assign adefault value to the attribute when the event is received.

DefaultSpecifies that the value of the attribute is computed by the logfileadapter, possibly by using other attributes. Currently, only the originand hostname attributes can be set to Default. The origin address is


computed from the host name using the getbyhostname function. Thedefault host name is the host where the adapter is running.

ConstantSpecifies that the value of the attribute is a constant string.

VariableSpecifies that the value of the attribute is a variable component of themessage.

CustomSpecifies that the value of the attribute is the output of a C printf-stylestatement. Other attributes can be combined to form a compositestring.

24. From the scrolling list at the top of the dialog, select the attribute to be edited.The current map values for the attribute are displayed in the Edit Assignmentgroup box.

25. Select the map type from the Map Type drop-down list.

Note: Selecting a map type of None deletes an attribute mapping. Changing amap type from None to another map type creates a new attributemapping.

If you select a map type of Constant, a dialog similar to the followingexample is displayed:

Enter the attribute value in the Enter a String text box. Type a value betweenthe double quotation marks and press the Enter key.


If you select a map type of Variable, a dialog similar to the following exampleis displayed:

Select the preferred variable from the Select a Variable scrolling list.

If you select a map type of Custom, a dialog similar to the following exampleis displayed:

Complete the following steps:


a. Enter a printf-style format string in the Enter a Custom Message text boxand press the Return key. Only %s conversions are supported, and theremust be at least one %s conversion.

b. From the Available Attributes scrolling list, you must select an attribute asthe argument for each %s conversion. You can use the left and right arrowbuttons to move attribute arguments between the Available Attributesscrolling list and the Selected Attributes scrolling list. You can use the uparrow and down arrow buttons to reorder the attribute arguments in theSelected Attributes scrolling list.

26. Click the Set & Close button to save your changes and close the AssignAttribute Values dialog box.

27. Select Save from the File menu of the Logfile Format Editor window.28. To distribute the format changes made in the previous step to an endpoint,

distribute the adapter configuration profile entry for this adapter using anexact copy. Distribute the copy to the subscribing endpoints. For non-TMEadapters, run the logfile_gencds program for your adapter type to update thecds file for the adapter with the changes made to the format file. Whencomplete, restart the adapter for the changes to become effective.


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 give youany license to these patents.You can send license inquiries, in writing, to:

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

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certaintransactions, therefore, this statement might 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 Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758 U.S.A.

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

The licensed program described in this 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.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

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.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

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 notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,modify, and distribute these sample programs in any form without payment to


IBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces.

If you are viewing this information in softcopy form, the photographs and colorillustrations might not appear.

TrademarksThe following terms are trademarks of International Business MachinesCorporation in the United States, other countries, or both: AIX, AS/400, FFST, FirstFailure Support Technology, IBM, the IBM logo, Integrated Language Environment,NetView, OS/2, OS/390, OS/400, Tivoli, the Tivoli logo, Tivoli Enterprise Console,TME, and z/OS.

Microsoft, Windows, and Windows NT are registered trademarks of MicrosoftCorporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks orregistered trademarks of Sun Microsystems, Inc. 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, and service names may be trademarks or service marksof others.

Notices 223

Index

Special characters.baroc file

See BAROC files 23.cfg file

See installation script 8.conf file

See configuration file 9.ed_diag_config file 12.err file

See error file 26.oid file

See object identifier file 8.rls file

See rules file 8$LCF_DATDIR 28$TECADHOME 4$VARBIND, built-in variables for 132%s 210' (single quotation mark) 10

Aacl attribute 5Adapter Configuration Facility 11

advantages of 2described 45endpoints 45profiles 45role

ACF_glopol 45ACF_polmod 45ACF_readonly 46, 48, 49ACF_rwdist 45ACP 47ACPM1 47Profile1 48

adapter configuration profileadding

before or after scripts to records 69environment variables to records 59files to distribution lists of records 66filter definitions to records 61records 57

cloning 48copying 50copying records 73creating 46deleting 49deleting records 75disabling before or after scripts in records 70distributing 56editing records 58enabling before or after scripts in records 70finding records 76locking records 76modifying

before or after scripts to records 69comments in records 72default policy 52environment variables in records 59

adapter configuration profile (continued)modifying (continued)

filter definitions in records 63UID and GID in records 72validation policy 54

moving records 74removing

before or after scripts from records 70environment variables from records 60files from distribution lists of records 67filter definitions from records 66

setting as a managed resource 46setting distribution defaults 50sorting attributes 78sorting records 77specifying

adapter identifier name 73unlocking records 76

adapter identifier name 73adapter_host attribute 5adapter, HP OpenView

installing from the command line 33installing from the Tivoli desktop 33uninstalling on managed node 41upgrading from the command line 41

AdapterCdsFile keyword 10AdapterErrorFile keyword 10adapters

buffer filter 22description 1files, list 7installing from the command line 33installing non-TME 34installing on endpoint 33installing on managed node 33locations, files 9non-TME 1sending events to the event server 1startup errors 27Tivoli Enterprise Console 3.8 enhanced, removing 44TME 1troubleshooting 28, 29uninstalling HP Openview on managed node 41uninstalling non-TME 42uninstalling on endpoints 41upgrading from the command line 41

addingadapter configuration profile record 57before or after scripts to adapter configuration profile

records 69environment variables to adapter configuration profile

records 59files to distribution lists of adapter configuration profile

records 66filter definitions to adapter configuration profile

records 61administrator attribute 5administrators 5alert code point, AS/400 84alert filter, AS/400 84ALRBRC.MBR 81


ALRCDS.MBR 81ALRCFG.MBR 81ALRRLS.MBR 81APPEND_CLASSPATH keyword 10APPEND_JVMPATH keyword 10AS/400 alert adapter

alert filter 84BAROC file 90buffer files 82CDS file 83code pages 83configuration file 82configuring filters 84deregistered filters 85described 81ENDTECADP command 88event listing 92existing alert filters 85FETCH examples 83files 81, 184graphic character set 83job queue 93keywords, CDS file 83message queues 82multiple adapters 94Name Server 93POSTEMSG command 96QTMETECA command 96registering filters 85routing alerts 85save files 37SELECT examples 83severity levels, events 90starting 85, 93stopping 87STRTECADP command 86TCP/IP considerations 93test mode and events 93troubleshooting 92uninstalling the adapter 43

AS/400 message adapterattribute defaults 110CDS file 101commands 113configuration file 100described 99event listing 110files 99, 184FTP session 113message queues 113Name Server 111save files 37start up program, changing 112starting 105, 112stopping 107TCP/IP considerations 111test mode and events 111troubleshooting 111uninstalling the adapter 43

as400msg.baroc file 110ASCII log files 1attributes

acl 5adapter configuration profile, sorting 78adapter_host 5adapter-specific

AS/400 message adapter 110

attributes (continued)adapter-specific (continued)

NetWare adapter 118OpenView adapter 127, 130, 134OS/2 adapter 141SNMP adapter 147UNIX logfile adapter 159Windows event log adapter 178

administrator 5base event 4cause_date_reception 5cause_event_handle 5credibility 5date 5date_reception 5event_handle 5format 4fqhostname 5hostname 5list of 5msg 5msg_catalog 5msg_index 5num_actions 5origin 5overview 4repeat_count 5server_handle 6server_path 6severity 6source 6status 7sub_origin 7sub_source 7

Bbacking up

object database 40backup

servers 16backup copies

CFG_ALERT 81CFG_MSG 100

BAROC filesadapter-specific

AS/400 alert adapter 90AS/400 message adapter 110NetWare adapter 118OpenView adapter 133OS/2 adapter 141SNMP adapter 146UNIX logfile adapter 159Windows event log adapter 178

attributes list 4class names in configuration files 10description 23example 23root.baroc 6, 7superclass 4

base event attributes 4before or after script

adding to adapter configuration profile records 69disabling in adapter configuration profile records 70enabling in adapter configuration profile records 70modifying to adapter configuration profile records 69removing from adapter configuration profile records 70


blank spaces 10books

see publications viiiBufEvtMaxSize keyword 8, 11BufEvtPath keyword 11buffer file 82buffer files 11buffer files, AS/400 100buffer filters 22BufferEvents keyword 11, 22BufferFlushRate keyword 12

Ccache

endpoint adapters 11filtering 13keywords 11, 12path 11rate to send events 12, 14

cache, eventdescription 8file format 8size 11

cause events 5cause_date_reception attribute 5cause_event_handle attribute 5CCSID 83, 101, 102CDS file keywords

AS/400 alert adapter$ACTION_CODE 83$ACTIONS 83$ADAPTER_CORREL 83$ADAPTER_HOST 84$ADAPTER_HOST_SNANODE 84$ALERT_CDPT 84$ALERT_ID 84$ARCH_TYPE 84$BLOCK_ID 84$CAUSES 84$DATE 84$DETAILED_DATA 84$EVENT_CORREL 84$EVENT_TYPE 84$HOSTNAME 84$INCIDENT_CORREL 84$MSG 84$ORIGIN 84$PRODUCT_ID 84$SELF_DEF_MSG 84$SEVERITY 84$SOURCE 84$SUB_ORIGIN 84

AS/400 message adapter$ADAPTER_HOST 102$ALERT_OPTION 102$ARG1 - $ARG8 105$DATA_CCSID_CONVERT_STATUS 102$DATA_CCSID_RETURNED 102$DATE 102$HOSTNAME 103$MSG 103$MSG_FILE_LIBRARY 103$MSG_FILE_NAME 103$MSG_HELP 103$MSG_ID 103$MSG_KEY 103

CDS file keywords (continued)AS/400 message adapter (continued)

$MSG_LIBRARY_USED 103$MSG_SEVERITY 103$MSG_TYPE 103$ORIGIN 103$SEND_DATE 103$SEND_JOB 104$SEND_JOB_NUMBER 104$SEND_PROGRAM_NAME 104$SEND_TIME 104$SEND_USER_PROFILE 104$SEVERITY 104$SOURCE 104$SUB_ORIGIN 104$SUB_SOURCE 104$TEXT_CCSID_RETURNED 104

OpenView adapter$ADAPTER_HOST 132$AGENT_ADDR 132$COMMUNITY 132$ENTERPRISE 132$SOURCE_TIME 132$SPECIFIC 132$TYPE 132$VARBIND 132$VARBIND variables 132$VB_NUM_VARS 132

SNMP adapter$ADAPTER_HOST 145$AGENT_ADDR 145$COMMUNITY 144$ENTERPRISE 144$SOURCE_ADDR 132, 144$SOURCE_TIME 144$SPECIFIC 144$TYPE 144$VARBIND 145$VB_NUM_VARS 145

CDS filesadapter-specific

AS/400 alert adapter 83AS/400 message adapter 100OpenView adapter 131, 132SNMP adapter 144UNIX logfile adapter 159

example 25format files 24location 9, 10overview 25syntax 202

CFG_ALERT file 81CFG_MSG file 100Change Alert Action Entry command 85Change Network Attributes command 85Channels keyword 19CHGALRACNE command 85CHGNETA command 85circuit tracing, OpenView adapter 128class definition statement

FETCH statement 200MAP statement 201MAP_DEFAULT statement 201SELECT statement 199

class nameAS/400 alert adapter 90AS/400 message adapter 110

Index 227

class name (continued)NetWare adapter 118OpenView adapter 133OS/2 adapter 141SNMP adapter 146UNIX logfile adapter 159Windows event log adapter 178

class, description 4cloning, adapter configuration profile 48code pages

AS/400 101AS/400 alert adapter 83

coded character set identifier 83, 101codeset directory 4cold start

OpenView adapter 133SNMP adapter 154

commandsAS/400 113odstat 164syntax xiwbkupdb 40wcrtprf 47, 48, 49wdel 49wdelac 76wdeldir 75wdistrib 56, 57wep ls 28wgetprf 51winstall 33wlookup 47, 48wpatch 41wputpol 54, 56wsetpr 46wtdumprl 164

comments, modifying in adapter configuration profilerecords 72

condition, printer 163configuration file keywords

AS/400 alert adapterAdapterCdsFile 82AdapterType 82BufEvtName 82, 100Filter 82, 85FilterDataQueue 82, 85JobDescription 83LanguageID 83ProcessExistingAlerts 83ServerCCSID 83

AS/400 message adapterAdapterCdsFile 100AdapterType 100JobDescription 100LanguageID 100MsgQueue 100PollInterval 100ProcessExistingMsgs 101ServerCCSID 101

commonAdapterCdsFile 10AdapterErrorFile 10APPEND_CLASSPATH 10APPEND_JVMPATH 10BufEvtMaxSize 11BufEvtPath 11BufferEvents 11BufferFlushRate 12

configuration file keywords (continued)common (continued)

Channels 19ConnectionMode 12ed_diag_config_file 12Filter 12FilterCache 13FilterMode 13FQHostname 13getport_timeout_seconds 14getport_timeout_usec 14getport_total_timeout_ usec 14getport_total_timeout_seconds 14LogFileName 14LogLevel 14MaxPacketSize 14NO_UTF8_CONVERSION 14Port 20Pre37Server 3, 15Pre37ServerEncoding 4, 15PREPEND_CLASSPATH 15PREPEND_JVMPATH 15RetryInterval 16ServerLocation 16, 20ServerPort 17StateCorrelationCleaningInterval 18StateCorrelationConfigPath 18StateCorrelationMaxFileSize 18StateCorrelationTotalSize 18TestMode 19TraceFileName 19TraceLevel 19TransportList 19UseStateCorrelation 21WIDTHSTRMEANING 21

NetWare adapterLog Sources 116PollInterval 117PreFilter 117PreFilterMode 117

OpenView adapterAdapterSpecificFile 130HPOVFilter 130WellBehavedDaemon 131

OS/2 adapterLogSources 139UnmatchLog 140

SNMP adapterAdapterSpecificFile 144SNMP_PORT 144SNMP_TRAP 144

UNIX logfile adapterLogSources 157NewLogBasedOn 158PollInterval 158ProcessPriorityClass 158UnmatchLog 158

Windows event log adapterBufferMaxSize 168HostnameIsAdapterHost 168LanguageID 168LogSources 168NewLogBasedOn 169NumEventsToCatchUp 169PollInterval 170PreFilter 170PreFilterMode 170


configuration file keywords (continued)Windows event log adapter (continued)

ProcessDisablePriorityBoost 170ProcessPriorityClass 171SpaceReplacement 171UnmatchLog 171WINEVENTLOGS 171

configuration filesadapter-specific

AS/400 alert adapter 82AS/400 message adapter 100, 113OS/2 adapter 139SNMP adapter 144UNIX logfile adapter 157Windows event log adapter 168

adapter, modifying behavior 68example 9format 9location 9

configuring adaptersAS/400 alert adapter 84AS/400 message adapter 100logfile 207NetWare adapter 116OpenView adapter 130OS/2 adapter 139SNMP adapter 144UNIX logfile adapter 157Windows event log adapter 168

ConnectionMode keyword 12connections

connection-oriented 2keywords 12, 16retry 16using interprocess communication mechanisms 1using oserv services 1

conventionscommand syntax xitypeface x

copyingadapter configuration profile record 73adapter configuration profiles 50

Create Data Queue command 85creating

adapter configuration profile 46credibility attribute 5CRTDTAQ command 85CRTPF command 111CRTSRCPF command 111customer support

see software support ix

Ddaemon, portmapper 17, 20daemons

syslogd 155date attribute 5date_reception attribute 5date, events 5debugging

See troubleshooting 26deleting

adapter configuration profile 49adapter configuration profile records 75

directory names, notation x

disablingbefore or after scripts in adapter configuration profile

records 70before scripts in adapter configuration profile records 70

distributing an adapter configuration profile 56distribution defaults, setting adapter configuration profile 50duplicate events 5duration attribute 5

Eed_diag_config_file keyword 12editing, adapter configuration profile record 58effect events 5eif.log file 14enabling

before or after scripts in adapter configuration profilerecords 70

encoding, UTF-8 3, 14, 15, 21, 187endpoint adapters

cache 11endpoint gateway

See gateway, Tivoli Management Framework 2endpoints

Adapter Configuration Facility requirement 45description 2getting events to the event server from 2installing adapters on 33modifying behavior of 68TME adapters for 2uninstalling adapters on 41

ENDTECADP command, AS/400 alert adapter 88ENDTECADP command, AS/400 message adapter 108English, as secondary language for AS/400 39environment variables

adding to adapter configuration profile records 59modifying in adapter configuration profile records 59notation xremoving from adapter configuration profile records 60TIVOLI_COMM_DIR 8

error filesadapter-specific

NetWare adapter 115OpenView adapter 133OS/2 adapter 139SNMP adapter 145UNIX logfile adapter 159Windows event log adapter 168

description 26location 9, 10

error messages 10event classes

names 10event correlation

example 129OpenView NNM 6 126testing with OpenView NNM 6 128

event servergetting events to, from a managed node 3getting events to, from a non-TME adapter 3getting events to, from an endpoint 2performance 2primary and secondary 2remote, sending events to 1sending events to 1

event serversconnections, when stopped or started 16

Index 229

event servers (continued)port number 17

event tracing 26event_handle attribute 5events

attributes 4buffer 22buffer file 11cause 5class 4date 5duplicates 5effect 5filter 21getting to the event server from a managed node 3getting to the event server from a non-TME adapter 3internationalization support 3list 159sending to the event server 1status 7time 5

expressions, for filtering 21

Ffailures, systems 22FETCH statement

description 200examples 83, 101

files.ed_diag_config 12adapter-specific

AS/400 alert adapter 81AS/400 message adapter 99NetWare adapter 115OpenView adapter 129OS/2 adapter 139SNMP adapter 143UNIX logfile adapter 156Windows event log adapter 167, 177

adapters 7ALRBRC.MBR 81ALRCDS.MBR 81ALRCFG.MBR 81ALRRLS.MBR 81as400msg.baroc 99BAROC 10, 23buffer 11cache 8CDS 25eif.log 14error 26for logging and tracing 12format 24init.tecad_logfile

description 157syntax for using 156

init.tecad_snmp 143initial 27install.exe 139installation script 8log_default.rls 157, 163logfile_gencds 157, 159mail alias 163MSGBRC.MBR 99MSGCDS.MBR 99MSGCFG.MBR 99

files (continued)nwgencds.nlm 115object identifier 8ov_default.rls 130postmsg.nlm 115readme, OS/2 139registration 8rules 8, 23security_default.rls 163tec_uninstal.cmd 139tecad_hpov 130tecad_hpov.baroc 130tecad_hpov.cds 130, 133tecad_hpov.cfg 129tecad_hpov.conf 130tecad_hpov.err 130, 133tecad_hpov.lrf 130, 133tecad_hpov.oid 130tecad_hpov.sh 130tecad_logfile 157tecad_logfile.baroc 157, 159tecad_logfile.cds 157, 159tecad_logfile.cfg 157tecad_logfile.conf 157tecad_logfile.err 157, 159tecad_logfile.fmt 157, 158, 159, 164tecad_snaevent.baroc 90tecad_snmp 143tecad_snmp.baroc 143tecad_snmp.cds 143tecad_snmp.cfg 143tecad_snmp.conf 143tecad_snmp.err 143, 145tecad_snmp.oid 143tecad_win.baroc 168tecad_win.conf 167tecad_win.err 168tecad_win.exe 167tecad_win.fmt 167, 173tecadcfg.cmd 139tecadini.sh 139tecadnw4.brc 115tecadnw4.cds 115tecadnw4.cnf 115tecadnw4.err 115tecadnw4.nlm 115tecados2.baroc 139tecados2.cds 139tecados2.conf 139tecados2.err 139tecados2.exe 139tecados2.fmt 139tecadrm.sh 139tecadwins.exe 167tecinst_win.cmd 167

filter definitionadding to adapter configuration profile records 61modifying in adapter configuration profile records 63removing from adapter configuration profile records 66

Filter keyword 12FilterCache keyword 13filtering events

buffer 22cache 13, 22examples 22, 23keywords 12, 13overview 21


filtering events (continued)prefilter 116, 172regular expressions 21system failures 22

FilterMode keyword 13finding adapter configuration profile records 76format files

activating changes to 195adapter-specific

NetWare adapter 117OS/2 adapter 140UNIX logfile adapter 158, 189Windows event log adapter 173, 191

described 187description 24example 24modifying 187specifications 187

fqhostname attribute 5FQHostname keyword 13FTP session, AS/400 113

Ggatelog file 28gateway, IBM Tivoli Enterprise Console

endpoints and events 2gateway, Tivoli Enterprise Console

description 2gateway, Tivoli Management Framework 2gateways, IBM Tivoli Enterprise Console

connections 12getport_timeout_seconds keyword 14getport_timeout_usec keyword 14getport_total_timeout_ usec keyword 14getport_total_timeout_seconds keyword 14GID, modifying in adapter configuration profile records 72graphic character set

AS/400 101AS/400 alert adapter 83

Hhardware requirements, installation 32hostname attribute 5hosts, for adapters 5HP OpenView adapter

See OpenView adapter 125HPOVFilter attribute 127

Iinit.tecad_logfile 157

command syntax 156init.tecad_snmp 143initial files 27install.exe 139installation requirements

hardware 32software 32

installation script 8installing adapters

adapter files 35endpoint adapter 33English as secondary language, AS/400 39NetWare logfile adapter 39

installing adapters (continued)non-TME 34winstall command 33

instances of UNIX logfile adapter, running multiple 156instances of Windows event log adapter, running

multiple 177interfaces

non-Tivoli 1Tivoli 1

internationalizationfiltering events 21format files, encoding 187messages and postemsg 29support for events 3UTF-8 encoding 3, 14, 15

interprocess communication mechanisms 1IP sockets 1, 3

Jjob queue, AS/400 alert adapter 93

Kkeywords

See CDS file keywords 82See configuration file keywords 82

Llanalert entry, SNMP adapter 152language

English as secondary for AS/400 39primary, AS/400 39

language support packs and postemsg 29last.cfg file 28LCF transport type 19lcfd process 2, 28lcfd.log file 28list events 159localization directories 4locking, adapter configuration profile records 76log files, ASCII 1log_default.rls 157logfile adapter

configuring 207operating system-specific adapter types 57

Logfile Format Editor 207logfile_gencds 157, 219LogFileName keyword 14LogLevel keyword 14logs

messages 14

Mmail alias

tec_print 163tec_security 164

managed node, installing HP Openview adapter on 33managed node, uninstalling HP OpenView adapter on 41managed nodes

events sent to event server 3uninstalling HP OpenView adapters 41

Index 231

managed resources, setting adapter configuration profilesas 46

manualssee publications viii

MAP statementdescription 201examples 101

map type 216MAP_DEFAULT statement 201mappings, format file 191, 195MaxPacketSize keyword 14maxsz, cache 8message logs 12, 14message queues, AS/400 82, 100messages, events 5modifying

adapter configuration file behavior 68adapter configuration profile default policy 52adapter configuration profile validation policy 54before or after scripts to adapter configuration profile

records 69comments in adapter configuration profile records 72environment variables in adapter configuration profile

records 59filter definitions in adapter configuration profile

records 63UID and GID in adapter configuration profile records 72variable expansion behavior 68

moving, adapter configuration profile records 74msg attribute 5msg_catalog attribute 5msg_index attribute 5MSGBRC.MBR 99MSGCDS.MBR 99MSGCFG.MBR 99multiple instances, UNIX logfile adapter 156multiple instances, Windows event log adapter 177

NName Server

AS/400 alert adapter 93AS/400 message adapter 111

NetWare adapterattribute defaults 118BAROC file 118configuration file 116error file 115event listing 118files 115, 184loading (starting) 122prefiltering events 116troubleshooting 123unloading (stopping) 123

network traffic 1newsgroups ixNO_UTF8_CONVERSION keyword 14non-TME adapters

description 1event delivery 3installing 34troubleshooting 29uninstalling 42

notationenvironment variables xpath names xtypeface x

num_actions attribute 5nwgencds.nlm 115

Oobject database

backing up 40object identifier (OID) files

description 8tecad_hpov.oid, OpenView adapter 132tecad_snmp.oid, SNMP adapter 145

online publications, accessing viiiOpenView adapter

attribute defaults 134BAROC file 133CDS file 132circuit tracing 128cold start 133configuration file 130described 125error file 133event correlation with NNM 6 126, 128event listing 133files 129, 184ovspmd process 125ovtrapd process 125starting 133stopping 133stream tracing 128testing tool 128traps 136troubleshooting 137

OpenView NNM version, determining 125ordering publications viiiorigin attribute 5OS/2 adapter

attribute defaults 141BAROC file 141class name 141configuration file 139described 139error file 139files 184format file 140starting 140stopping 141troubleshooting 142

oserv 1, 3ov_default.rls 130OVsnmpEventOpen filter value 127ovspmd process, OpenView adapter 125ovtrapd process 125

Ppath names, notation xperformance, event server 2Port keyword 20port number, for event server 17portmapper daemon 17, 20ports

port mapper 14re-sending UDP calls 14

postemsg command 29, 96postmsg.nlm 115Pre37Server keyword 3, 15


Pre37ServerEncoding keyword 4, 15prefiltering events

NetWare adapter 116Windows event log adapter 172

PREPEND_CLASSPATH keyword 15PREPEND_JVMPATH keyword 15printer condition 163profiles

Adapter Configuration Facility 45See adapter configuration profile 46

publicationsaccessing online viiiordering viii

QQPGMR 94QSECOFR 94QSTRUPPGM 94QSYS 94QSYSOPR 99QSYSWRK 93QTECALERT 84, 85QTMETECA command 96QTMETECA02 library 81

Rreadme, OS/2 139record

addingbefore or after scripts to an adapter configuration

profile 69environment variables to an adapter configuration

profile 59files to distribution lists for an adapter configuration

profile 66filter definitions to an adapter configuration profile 61

copying an adapter configuration profile 73deleting an adapter configuration profile 75editing an adapter configuration profile 58enabling and disabling before and scripts in an adapter

configuration profile 70finding an adapter configuration profile 76modifying

adapter configuration profile 72before or after scripts to an adapter configuration

profile 69environment variable in an adapter configuration

profile 59filter definitions in an adapter configuration profile 63GID in an adapter configuration profile 72UID in an adapter configuration profile 72

moving an adapter configuration profile 74removing

before or after scripts from an adapter configurationprofile 70

environment variables from an adapter configurationprofile 60

files from an adapter configuration profile 67filter definitions from an adapter configuration

profile 66sorting adapter configuration profile records 77specifying

adapter identifier name 73reference information, NetWare adapter 115

registration filesdescription 8

registry variablesApplicationEventsProcessed 174ApplicationEventsProcessedTimeStamp 174DirectorEventsProcessed 174DirectorEventsProcessedTimeStamp 174DNSEventsProcessed 174DNSEventsProcessedTimeStamp 174FileReplicationEventsProcessed 174FileReplicationEventsProcessedTimeStamp 175PollingInterval 175SecurityEventsProcessed 175SecurityEventsProcessedTimeStamp 175SystemEventsProcessed 175SystemEventsProcessedTimeStamp 175TECInstallPath 175

regular expressions, for filtering 21removing

before or after scripts from adapter configuration profilerecords 70

environment variables from adapter configuration profilerecords 60

files from distribution lists of adapter configuration profilerecords 67

filter definitions from adapter configuration profilerecords 66

repeat_count attribute 5RetryInterval keyword 16roles, authorization 5root.baroc file 6, 7rules

description 8, 23engine 6example 23SNMP adapter 148UNIX logfile adapter 163

Ssecondary language, AS/400 83, 100SELECT statement

description 199examples 83, 101

server configuration, UNIX logfile adapter 155server_handle attribute 6server_path attribute 6ServerLocation keyword 16, 20, 82ServerPort keyword 17services, oserv 1setting

adapter configuration profile distribution defaults 50adapter configuration profiles as managed resources 46

severities, eventadapter-specific

AS/400 alert adapter 92AS/400 message adapter 110NetWare adapter 118OpenView adapter 133OS/2 adapter 141SNMP adapter 146UNIX logfile adapter 159Windows event log adapter 178

attribute 6severity attribute 6single quotation mark 10

Index 233

slotSee attribute 4

SNA alerts 81SNMP adapter

attribute defaults 146BAROC file 146CDS file 144cold start 154configuration file 144default rules 148described 143error file 145event listing 147files 143, 184lanalert entry 152object identifier (OID) file 145restarting 146starting 145, 146stopping 145, 146trapd daemon 143traps 148troubleshooting 154warm start 146

SOCKET transport type 19sockets 1, 3, 19software requirements, installation 32software support, contacting ixsorting

adapter configuration profile attributes 78adapter configuration profile records 77

sourceattribute 6description 1

spaces, blank 10specifying adapter identifier name 73starting adapters

AS/400 alert adapter 85, 93AS/400 message adapter 105, 112errors 27NetWare logfile adapter 122OpenView adapter 133OS/2 adapter 140SNMP adapter 145UNIX logfile adapter 155

state correlationcache 11, 18cleanup 18keywords 14XML 18

StateCorrelationCleaningInterval keyword 18StateCorrelationConfigPath keyword 18StateCorrelationMaxFileSize keyword 18StateCorrelationTotalSize keyword 18statements

FETCH 200MAP 201MAP_DEFAULT 201SELECT 199

status attribute 7stopping adapters

AS/400 alert adapter 87AS/400 message adapter 107NetWare logfile adapter 123OpenView adapter 133OS/2 adapter 141SNMP adapter 146UNIX logfile adapter 156

stopping adapters (continued)Windows event log adapter 177

stream tracing, OpenView adapter 128STRTECADP command 86, 106sub_origin attribute 7sub_source attribute 7subvectors 84summary, events 5superclass, BAROC file 4syntax

init.tecad_logfile command 156syntax for commands xisyntax, CDS file 202syslogd daemon 155system failures 22

TTcl expressions, for filtering 21TCP/IP

AS/400 alert adapter 93AS/400 message adapter 111host table 93, 111Windows event log adapter 167

tec_recv_agent_port entry 17tec_uninstal.cmd 139tecad_hpov 130tecad_hpov.baroc 130tecad_hpov.cds 130, 131tecad_hpov.cfg 129tecad_hpov.conf 130tecad_hpov.err 130tecad_hpov.lrf 130tecad_hpov.oid 130tecad_hpov.sh 130tecad_logfile 157tecad_logfile.baroc 157tecad_logfile.cds 157tecad_logfile.cfg 157tecad_logfile.conf 157tecad_logfile.fmt 157tecad_logfile.fmt file 208tecad_snaevent.baroc file 90tecad_snmp 143tecad_snmp.baroc 143, 147, 149tecad_snmp.cds 143, 144, 152tecad_snmp.cfg 143tecad_snmp.conf 143tecad_snmp.err 143tecad_snmp.oid 143tecadcfg.cmd 139tecadini.sh 139tecadnw4.brc 115tecadnw4.cds 115tecadnw4.cnf 115tecadnw4.err 115tecadnw4.nlm 115, 121tecados2.baroc 139tecados2.cds 139tecados2.conf 139tecados2.err 139tecados2.exe 139tecados2.fmt 139tecadrm.sh 139testing tool, OpenView adapter 128TestMode keyword 19, 93, 111time, events 5


Tivoli Availability Intermediate Manager 17Tivoli Enterprise Console, description 1Tivoli Event Integration Facility 4Tivoli Management Framework 5Tivoli Software Information Center viiiTIVOLI_COMM_DIR 8TIVOLIHOME variable 11, 14TME adapters

description 1event delivery 3for endpoints 2

TME transport type 19trace logs 12, 19TraceFileName keyword 19TraceLevel keyword 19tracing

circuit, OpenView adapter 128event 26stream, OpenView adapter 128

traffic, network 1transport type 19TransportList keyword 19trapd daemon, SNMP adapter 143traps

OpenView adapter 136SNMP adapter 148

troubleshootingall adapters 28AS/400 alert adapter 92AS/400 message adapter 111description 26endpoint adapters 28managed node adapters 28NetWare adapter 115, 123non-TME adapters 29OpenView adapter 133, 137OS/2 adapter 142SNMP adapter 154UNIX logfile adapter 164Windows event log adapter 182

typeface conventions x

UUDP calls 14UID, modifying in adapter configuration profile records 72uninstalling adapters

AS/400 adapters 43NetWare logfile adapter 43non-TME 42on endpoint 41OpenView adapters on managed node 41Tivoli Enterprise Console 3.8 enhanced, removing 44

UNIX log file adapterfiles 185

UNIX logfile adapterattribute defaults 159BAROC file 159CDS file 159configuration file 157configuring the adapter 157default rules 163description 155error file 159files 157format file 158, 189server configuration 155

UNIX logfile adapter (continued)starting 155stopping 156troubleshooting 164

unlocking, adapter configuration profile records 76upgrading adapters

wpatch command 41UseStateCorrelation keyword 21UTF-8 encoding 3, 14, 15, 21, 187

Vvariable expansion, modifying behavior of 68variables

built-in for $VARBIND 132environment

notation for xTIVOLI_COMM_DIR 8

TIVOLIHOME 11, 14

Wwarm start, SNMP adapter 146wbkupdb 40wcrtprf 49wdelac 76wdistrib 57wep ls command 28wgetprf 51WIDTHSTRMEANING keyword 21Windows event log adapter

attribute defaults 178BAROC file 178configuration file 168Control Panel Services Applet 176described 167error file 168event listing 178files 167, 185format file 167, 191prefiltering log events 172registry variables 173spaces, replaced with underscores 171stopping 177TCP/IP 167tecad_win command 180troubleshooting the adapter 182

winstall command 33wlookup 47wpatch command 41wpostemsg command 29wputpol 54wsetpr 46

Index 235

��

Program Number: 5698-TEC

Printed in U.S.A.

SC32-1242-00