IBM Enterprise Console User Manual

860.96 Kb
Loading...

IBM Tivoli Enterprise Console

Adapters Guide

Version 3.8

GC32-0668-01

IBM Tivoli Enterprise Console

Adapters Guide

Version 3.8

GC32-0668-01

Note

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

First Edition (September 2002)

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

© Copyright International Business Machines Corporation 2002. All rights reserved.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

Preface . . . . . . . . . . . . .

. vii

Chapter 2. AS/400 Alert Adapter . . .

.

23

Who Should Read This Guide . . . . . . .

. vii

Adapter Files . . . . . . . . . . . . .

.

23

What This Guide Contains . . . . . . . .

. vii

Configuration File . . . . . . . . . .

.

24

Publications . . . . . . . . . . . . .

. viii

Class Definition Statement File . . . . . .

.

25

IBM Tivoli Enterprise Console Library . . .

. viii

SELECT Statement Example . . . . . .

. 25

Prerequisite Publications. . . . . . . .

. viii

FETCH Statement Example . . . . . .

.

25

Related Publications . . . . . . . . .

. viii

Keywords . . . . . . . . . . . .

.

25

Accessing Publications Online . . . . . .

. ix

Configuring the AS/400 Alert Filters . . . . .

.

26

Providing Feedback about Publications . . .

. ix

Default Alert Filter . . . . . . . . . .

.

26

Contacting Customer Support . . . . . . .

. ix

Integrating with an Existing Alert Filter . . .

.

27

Conventions Used in this Guide . . . . . .

. ix

Starting the Adapter . . . . . . . . . .

.

27

Typeface Conventions . . . . . . . . .

. ix

STRTECADP . . . . . . . . . . . . .

.

28

Operating System-dependent Variables and Paths

 

x

Stopping the Adapter . . . . . . . . . .

. 29

 

 

 

 

ENDTECADP . . . . . . . . . . . .

.

30

Chapter 1. Understanding Adapters . .

. 1

Events Listing . . . . . . . . . . . .

.

32

Adapter Overview . . . . . . . . . .

.

.

1

Event Class Structure . . . . . . . . .

.

32

Troubleshooting the AS/400 Adapter . . . . .

. 34

How Events Get Sent to the Event Server. . . . 1

Logging Events in Test Mode . . . . . . .

.

35

How Events Get to the Event Server From an

 

 

 

 

TCP/IP Considerations . . . . . . . . .

.

35

Endpoint . . . . . . . . . . .

.

.

1

Starting an AS/400 Adapter after an IPL . . .

. 35

How Events Get to the Event Server From a

 

 

 

 

 

 

Adding an Autostart Job to QSYSWRK . . .

. 35

Managed Node . . . . . . . . .

.

.

3

Changing the AS/400 Startup Program . . .

. 36

How Events Get to the Event Server From a

 

 

 

 

 

 

Multiple AS/400 Alert Adapters . . . . . .

. 36

Non-TME Adapter . . . . . . . .

.

.

3

Configuration File . . . . . . . . . .

.

37

Internationalization Support for Events . . .

.

.

3

POSTEMSG . . . . . . . . . . . . . . 38

Event Information . . . . . . . . . .

.

.

4

 

 

 

Event Attributes . . . . . . . . . .

.

.

4

Chapter 3. AS/400 Message Adapter .

. 39

Adapter Files . . . . . . . . . . . .

.

.

7

Cache File . . . . . . . . . . . .

.

.

8

Adapter Files . . . . . . . . . . . . .

.

39

Configuration File . . . . . . . . .

.

.

9

Configuration File . . . . . . . . . .

.

40

File Location . . . . . . . . . .

.

.

9

Class Definition Statement File . . . . . .

.

41

File Format . . . . . . . . . . .

.

.

9

SELECT Statement Example . . . . . .

.

41

Example . . . . . . . . . . . .

.

.

9

FETCH Statement Example . . . . . .

.

41

Keywords . . . . . . . . . . .

.

.

9

MAP Statement Example . . . . . . .

.

41

Event Filtering . . . . . . . . . .

.

 

14

Keywords . . . . . . . . . . . .

.

41

Regular Expressions in Filters . . . .

.

 

15

Starting the Adapter . . . . . . . . . .

.

45

Event Filter Examples . . . . . . .

.

 

15

STRTECADP . . . . . . . . . . . . .

.

46

Event Buffer Filtering . . . . . . . .

.

 

15

Stopping the Adapter . . . . . . . . . .

.

47

Event Buffer Filter Examples . . . .

.

 

16

ENDTECADP . . . . . . . . . . . .

.

48

BAROC File . . . . . . . . . . . .

.

 

16

Events Listing . . . . . . . . . . . .

.

50

Example . . . . . . . . . . . .

.

 

16

Event Class Structure . . . . . . . . .

.

50

Rule File . . . . . . . . . . . . .

.

 

17

Troubleshooting the AS/400 Adapter . . . . .

.

51

Example . . . . . . . . . . . .

.

 

17

Logging Events in Test Mode . . . . . . .

.

51

Format File . . . . . . . . . . . .

.

 

17

TCP/IP Considerations . . . . . . . . .

.

51

Example . . . . . . . . . . . .

.

 

17

Starting an AS/400 Adapter after an IPL . . .

.

52

Class Definition Statement File . . . . . .

. 18

Adding an Autostart Job to QSYSWRK . . .

. 52

Example . . . . . . . . . . . .

.

 

18

Changing the AS/400 Startup Program . . .

.

52

Error File . . . . . . . . . . . . .

.

 

19

Multiple AS/400 Message Queues . . . . . .

.

53

Initial Files . . . . . . . . . . . . .

.

 

20

Configuration File . . . . . . . . . .

.

53

Troubleshooting Adapters . . . . . . . .

. 21

Using FTP to Execute AS/400 Commands . . .

. 53

Adapter Startup Errors . . . . . . . .

.

 

21

 

 

 

All Adapters . . . . . . . . . . . .

.

 

21

Chapter 4. NetWare Log File Adapter

 

55

Managed Node Adapters . . . . . . . .

. 21

NetWare Log File Adapter Reference Information. . 55

Endpoint Adapters . . . . . . . . . .

.

 

21

 

Adapter Files . . . . . . . . . . . . .

.

55

Non-TME Adapters. . . . . . . . . .

.

 

22

 

Error File . . . . . . . . . . . . . .

.

55

 

 

 

 

 

 

 

 

Prefiltering NetWare Events . . . . . . . .

.

56

© Copyright IBM Corp. 2002

 

 

 

 

 

iii

Configuration File . . . . . . . . . .

.

.

56

Warm Start . . . . . . . . . . .

.

.

86

Format File . . . . . . . . . . . .

.

.

57

Stopping the Adapter . . . . . . . .

.

.

86

Events Listing . . . . . . . . . . .

.

.

58

Events Listing . . . . . . . . . . .

.

.

86

Event Class Structure . . . . . . . .

.

.

58

Event Class Structure . . . . . . . .

.

.

86

TECADNW4.NLM . . . . . . . . . .

.

.

61

Rules Listing . . . . . . . . . . . .

.

.

88

tecadnw4.nlm . . . . . . . . . .

.

.

62

SNMP Traps . . . . . . . . . . . .

.

.

88

Troubleshooting the NetWare Log File Adapter

.

.

63

Generic Traps. . . . . . . . . . .

.

.

88

 

 

 

 

Enterprise-specific Traps . . . . . . .

.

.

88

Chapter 5. OpenView Adapter . . .

.

. 65

Creating a New SNMP Trap Event . . . .

.

. 89

OpenView Driver . . . . . . . . . .

.

.

65

BAROC File Changes . . . . . . . .

.

.

89

Agent-independent Data . . . . . .

.

.

90

Reception of OpenView Messages . . . .

.

. 65

Class Definition Statement File Changes . . . . 92

Determining the OpenView NNM Version .

.

. 65

Object Identifier File Changes . . . . .

.

.

93

Incoming Messages Format . . . . . .

.

. 66

Troubleshooting the SNMP Adapter . . . .

.

. 93

Event Correlation With NNM 6. . . . .

.

. 66

 

 

 

 

Determining the OVsnmpEventOpen Filter Value

67

Chapter 8. IBM Tivoli Enterprise

 

 

 

Testing Tools . . . . . . . . . . .

.

. 68

 

 

 

Testing Event Correlation With NNM 6 . .

.

. 68

Console Gateways. . . . . . . .

.

.

95

Event Correlation Example . . . . .

.

.

69

Controlling Event Traffic at the Gateway . .

.

. 95

Adapter Files . . . . . . . . . . . .

.

.

70

Example . . . . . . . . . . . .

.

.

95

Configuration File . . . . . . . . .

.

.

70

Worksheets and Calculations . . . . .

.

.

97

Class Definition Statement File . . . . .

.

.

71

Configuration File . . . . . . . . . .

.

.

97

OpenView Event Example . . . . .

.

. 71

 

 

 

 

Keywords . . . . . . . . . . .

.

.

72

Chapter 9. UNIX Log File Adapter . .

. 101

Built-in Variables for $VARBIND . .

.

. 72

Event Server Configuration. . . . . . .

.

.

101

Object Identifier File . . . . . . . .

.

.

72

Starting the Adapter . . . . . . . . .

.

.

101

Error File . . . . . . . . . . . .

.

.

73

Stopping the Adapter. . . . . . . . .

.

.

102

LRF File . . . . . . . . . . . .

.

.

73

Running Multiple UNIX Log File Adapters .

.

. 102

Starting and Stopping the Adapter . . . .

.

. 73

Adapter Files . . . . . . . . . . .

.

.

103

Events Listing . . . . . . . . . . .

.

.

74

Configuration File . . . . . . . . .

.

.

103

Event Class Structure . . . . . . . .

.

.

74

Format File . . . . . . . . . . .

.

.

104

OpenView Traps. . . . . . . . . . .

.

.

76

Class Definition Statement File . . . .

.

.

104

SNMP Traps . . . . . . . . . . .

.

.

76

Error File . . . . . . . . . . . .

.

.

104

OpenView Traps. . . . . . . . . .

.

.

76

Events Listing . . . . . . . . . . .

.

.

104

Troubleshooting the OpenView Adapter . . .

.

. 77

Event Class Structure . . . . . . . .

.

.

104

 

 

 

 

Chapter 6. OS/2 Adapter . . . . .

.

.

79

Default Rules . . . . . . . . . . .

.

.

108

Troubleshooting the UNIX Log File Adapter .

.

. 109

Adapter Files . . . . . . . . . . . .

.

.

79

 

 

 

 

Configuration File . . . . . . . . .

.

.

79

Chapter 10. Windows Event Log

 

 

 

Format File . . . . . . . . . . .

.

.

80

Adapter . . . . . . . . . . . . .

.

111

Starting the Adapter . . . . . . . . .

.

.

80

Adapter Files . . . . . . . . . . .

.

.

111

Stopping the Adapter . . . . . . . . .

.

.

81

Configuration File . . . . . . . . .

.

.

112

Events Listing . . . . . . . . . . .

.

.

81

Prefiltering Windows Log Events . . .

.

. 115

Event Class Structure . . . . . . . .

.

.

81

Format File . . . . . . . . . . .

.

.

116

Troubleshooting the OS/2 Adapter . . . .

.

. 82

Registry Variables . . . . . . . . . .

.

.

117

 

 

 

 

Chapter 7. SNMP Adapter. . . . .

.

.

83

Low Memory Registry Variables . . . .

.

. 119

Adapter Administrator Roles for Windows .

.

. 120

SNMP Driver . . . . . . . . . . . .

.

.

83

Starting the Adapter . . . . . . . . .

.

.

120

Reception of SNMP Messages . . . . .

.

. 83

Stopping the Adapter. . . . . . . . .

.

.

120

Incoming Messages Format . . . . . .

.

. 83

Events Listing . . . . . . . . . . .

.

.

120

Server Configuration . . . . . . . . .

.

.

83

Event Class Structure . . . . . . . .

.

.

121

Adapter Files . . . . . . . . . . . .

.

.

83

tecad_win Command . . . . . . . . .

.

.

123

Configuration File . . . . . . . . .

.

.

84

tecad_win . . . . . . . . . . .

.

.

124

Class Definition Statement File . . . . .

.

.

84

Troubleshooting the Windows Event Log Adapter

 

125

SNMP Event Example . . . . . . .

.

. 84

 

 

 

 

 

Keywords . . . . . . . . . . . .

.

84

Chapter 11. Windows NT Event Log

 

 

 

Built-in Variables for $VARBIND . .

.

. 85

 

 

 

Adapter . . . . . . . . . . . . .

.

127

Object Identifier File . . . . . . . .

.

.

85

Adapter Files . . . . . . . . . . .

.

.

127

Error File . . . . . . . . . . . .

.

.

85

Starting and Stopping the Adapter . . . .

.

.

85

Configuration File . . . . . . . . .

.

.

128

Cold Start . . . . . . . . . . . .

.

.

86

Prefiltering Windows NT Log Events .

.

.

130

iv IBM Tivoli Enterprise Console: Adapters Guide

Format File . . . . . . . . . . . .

.

131

Generating a New Class Definition Statement

 

 

Non-English Format Files . . . . . .

.

132

File for a TME Adapter . . . . . . . .

.

153

Registry Variables . . . . . . . . . . .

.

132

Generating a New Class Definition Statement

 

 

Low Memory Registry Variables . . . . .

. 134

File for a Non-TME Adapter . . . . . .

. 153

Adapter Administrator Roles for Windows NT .

. 134

 

 

 

Starting the Adapter . . . . . . . . . .

.

135

Appendix C. Class Definition

 

 

Stopping the Adapter. . . . . . . . . .

.

135

Statement File Reference . . . . . .

155

Events Listing . . . . . . . . . . . .

.

135

File Format . . . . . . . . . . . . .

.

155

Event Class Structure . . . . . . . . .

.

135

Operators . . . . . . . . . . . . .

.

155

tecad_nt Command . . . . . . . . . .

.

137

Class Definition Statement File Details . . . .

.

156

tecad_nt . . . . . . . . . . . . . .

138

SELECT Statement . . . . . . . . .

.

157

Troubleshooting the Windows NT Event Log

 

 

 

 

FETCH Statement . . . . . . . . . .

.

158

Adapter . . . . . . . . . . . . . .

.

139

MAP Statement. . . . . . . . . . .

.

159

 

 

 

Appendix A. Files Shipped with

 

 

MAP_DEFAULT Statement . . . . . . .

. 159

 

 

Example . . . . . . . . . . . . .

.

159

Adapters . . . . . . . . . . . . .

141

Object Identifier to Name Translation . . . .

.

160

 

 

 

Class Definition Statement File Syntax Diagrams

 

161

Appendix B. Format File Reference

145

Notices . . . . . . . . . . . . . .

165

Format File Location . . . . . . . . . .

.

145

Format Specifications . . . . . . . . . .

.

146

Trademarks . . . . . . . . . . . . .

.

167

Log File Example . . . . . . . . . . .

.

147

 

 

 

Windows NT Example . . . . . . . . .

. 149

Glossary . . . . . . . . . . . . .

169

Mappings . . . . . . . . . . . . .

.

149

 

 

 

Additional Mapping Considerations . . . .

. 151

Index . . . . . . . . . . . . . . . 171

Activating Changes Made with a Format File. . . 153

 

 

 

Contents v

vi IBM Tivoli Enterprise Console: Adapters Guide

Preface

The IBM® Tivoli Enterprise Console® Adapters Guide provides detailed descriptions for the currently available IBM Tivoli® Enterprise Console adapters.

Who Should Read This Guide

This guide is for IBM Tivoli Enterprise Console administrators who configure event adapters and IBM Tivoli Enterprise Console gateways.

You should have prior knowledge of the following:

vUNIX® operating system

vMicrosoft® Windows® 2000 or Windows NT® operating systems

vTivoli Management Framework

vAdapter operating system

For example, if you are using an OpenView adapter, you should be familiar with Hewlett-Packard OpenView.

What This Guide Contains

The IBM Tivoli Enterprise Console Adapters Guide contains the following sections:

vChapter 1, “Understanding Adapters”

Describes adapters, events, attributes, adapter architecture, and adapter files.

vThe following chapters provide information about how to configure and use each adapter:

Chapter 2, “AS/400 Alert Adapter”

Chapter 3, “AS/400 Message Adapter”

Chapter 4, “NetWare Log File Adapter”

Chapter 5, “OpenView Adapter”

Chapter 6, “OS/2 Adapter”

Chapter 7, “SNMP Adapter”

Chapter 9, “UNIX Log File Adapter”

Chapter 10, “Windows Event Log Adapter”

Chapter 11, “Windows NT Event Log Adapter”

vChapter 8, “IBM Tivoli Enterprise Console Gateways”

Provides information about how to configure the IBM Tivoli Enterprise Console gateway.

vAppendix A, “Files Shipped with Adapters”

Lists significant files shipped with and used by each adapter.

vAppendix B, “Format File Reference”

Contains details about format files, including organization, syntax, and how to modify them.

vAppendix C, “Class Definition Statement File Reference”

Contains details about class definition statement files, including organization, syntax, and how to modify them.

© Copyright IBM Corp. 2002

vii

Publications

This section lists publications in the IBM Tivoli Enterprise Console library and any other related documents. It also describes how to access Tivoli publications online and how to make comments on Tivoli publications.

IBM Tivoli Enterprise Console Library

The following documents are available in the IBM Tivoli Enterprise Console library:

vTivoli Event Integration Facility User’s Guide, GC32-0691

Discusses how to develop your own event adapters that are tailored to your network environment and your specific needs. Additionally, the guide describes how to filter events at the source.

vIBM Tivoli Enterprise Console Installation Guide, GC32-0823

Discusses how to install, upgrade, and remove IBM Tivoli Enterprise Console components.

vIBM Tivoli Enterprise Console Reference Manual, GC32-0666

Provides details about command-line commands applicable to using the IBM Tivoli Enterprise Console product, the predefined tasks shipped in the task library, and the environment variables available to tasks that execute with an event.

vIBM Tivoli Enterprise Console Rule Builder’s Guide, GC32-0669

Discusses how to develop rules and integrate them for event correlation and automated event management.

vIBM Tivoli Enterprise Console User’s Guide, GC32-0667

Discusses how to plan for and configure your event database environment and describes components, roles, and other information for using the IBM Tivoli Enterprise Console product.

Prerequisite Publications

To be able to use the information in this book effectively, you must have some prerequisite knowledge, which you can get from the following books:

vTivoli Management Framework Planning for Deployment Guide, GC32-0393

Introduces the Tivoli environment and provides detailed information about the desktop, managed nodes, administrators, policy regions, profiles, notices, tasks, and scheduling.

vTivoli Management Framework User’s Guide, GC31-8433

Describes the concepts and procedures for using Tivoli Management Framework services. It provides instructions for performing tasks from the Tivoli desktop and from the command line.

vTivoli Management Framework Reference Manual, SC31-8434

Provides information about the command line interface for Tivoli Management Framework.

Related Publications

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

http://www.tivoli.com/support/documents/glossary/termsm03.htm

viii IBM Tivoli Enterprise Console: Adapters Guide

Accessing Publications Online

Publications in the product libraries are included in PDF or HTML formats, or both, on the product CD. To access publications using a Web browser, open the infocenter.html file, which is located in the appropriate publications directory on the product CD.

When IBM publishes an updated version of one or more online or hardcopy publications, they are posted to the Tivoli Information Center. You can access updated publications in the Tivoli Information Center from the following Customer Support Web site:

http://www.tivoli.com/support/documents/

The Tivoli Information Center contains the most recent version of the books in the product library in PDF or HTML formats, or both. Translated documents are also available for some products.

Note: If you print PDF documents on other than letter-sized paper, select the Fit to page check box in the Adobe Acrobat Print dialog (which is available when you click File —> Print) to ensure that the full dimensions of a letter-sized page are printed on the paper that you are using.

Providing Feedback about Publications

If you have comments or suggestions about Tivoli products and documentation, send an e-mail to pubs@tivoli.com or complete the customer feedback survey at

the following Web site:

http://www.tivoli.com/support/survey/

Contacting Customer Support

If you have a problem with any Tivoli product, you can contact IBM Customer Support for Tivoli products. See the Tivoli Customer Support Handbook at the following Web site:

http://www.tivoli.com/support/handbook/

The handbook provides information about how to contact Customer Support, depending on the severity of your problem, and the following information:

vRegistration and eligibility

vTelephone numbers and e-mail addresses, depending on the country in which you are located

vWhat information you should gather before contacting Customer Support

Conventions Used in this Guide

This book uses several conventions for special terms, actions, operating system-dependent commands, and paths.

Typeface Conventions

The following typeface conventions are used in this book:

Bold

Commands, keywords, file names, authorization roles, URLs, or

Preface ix

 

other information that you must use literally appear in bold.

 

Names of windows, dialogs, and other controls also appear in

 

bold.

Italics

Variables and values that you must provide appear in italics. Words

 

and phrases that are emphasized also appear in italics.

Monospace

Code examples, output, and system messages appear in a

 

monospace font.

Operating System-dependent Variables and Paths

This book uses the UNIX convention for specifying environment variables and for directory notation.

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

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

x IBM Tivoli Enterprise Console: Adapters Guide

Chapter 1. Understanding Adapters

Event adapters are software programs that collect information, perform local filtering, and convert relevant events into a format that can be used by the IBM Tivoli Enterprise Console product. Because adapters are located on or near their event sources and can perform local filtering of events, the adapters create a minimal amount of additional network traffic. Adapters use a minimal amount of system resources to perform their functions.

Network management applications have become an important part of monitoring the availability of resources in the enterprise. The IBM Tivoli Enterprise Console product can seamlessly integrate alarms and events from all the major network management platforms and can correlate them with other system, database, and application events.

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

Adapter Overview

An adapter is a process that monitors resources so that they can be managed. These monitored resources are called sources. A source is an application (for example, a database) or system resource (for example, an NFS server). When an adapter detects an event generated from a source (generally called a raw event), it formats the event and sends it to the event server. The event server then further processes the event.

Adapters can monitor sources in the following ways:

vAn adapter can receive events from any source that actively produces them. For example, SNMP adapters can receive traps sent by the Simple Network Management Protocol (SNMP).

vAn adapter can check an ASCII log file for raw events at configurable intervals if the source updates a log file with messages.

How Events Get Sent to the Event Server

Adapters can send events to the event server using a TME® interface or a non-TME interface. Both types of interfaces send events using an ordinary TCP/IP channel. The difference between the two interfaces is the method used to establish the connection. A TME interface establishes a connection using the oserv services provided by Tivoli Management Framework; therefore, adapters that use this interface are referred to as TME adapters. A non-TME interface establishes connections using standard interprocess communication mechanisms (for example, opening an IP socket); therefore, adapters that use this interface are called non-TME adapters.

How Events Get to the Event Server From an Endpoint

TME adapters installed on endpoints send their events to the lcfd process, which then sends the events to an IBM Tivoli Enterprise Console gateway, which in turn

© Copyright IBM Corp. 2002

1

bundles them up and forwards them on to an event server. A TME interface is used for communications. The IBM Tivoli Enterprise Console gateway uses a connection-oriented service to the server by default. A connection-oriented service means that a connection is established when the adapter is initialized and the connection is maintained for all events to be sent. The IBM Tivoli Enterprise Console gateway runs on the same managed node as the Tivoli Management Framework gateway that is providing the endpoint gateway service. The IBM Tivoli Enterprise Console gateway provides the following benefits:

vGreater scalability, meaning you can manage many sources easier, with less software running on the endpoints.

vGreatly reduces the amount of communications tasks performed by the event server or the Tivoli management region server, as the IBM Tivoli Enterprise Console gateway bundles a number of events before sending them to the event server. This improves event server performance.

vEasier deployment of adapters and updates to adapters using profiles in the Adapter Configuration Facility (ACF).

The TME adapters currently supported for an endpoint are the following:

vUNIX log file

vOS/2®

vSNMP

vMicrosoft Windows event log

vWindows NT event log

You configure these adapters to send their events to specific primary, secondary or both event servers, and the IBM Tivoli Enterprise Console gateway forwards them appropriately. If the IBM Tivoli Enterprise Console gateway, Tivoli Management Framework gateway, or lcfd process is down, events are buffered at the endpoint. The events are re-sent when communication is restored and the next event is sent. If an event server is down (but the IBM Tivoli Enterprise Console gateway, Tivoli Management Framework gateway, and lcfd processes are still up), events are buffered at the IBM Tivoli Enterprise Console gateway. They are re-sent when communication with the server is restored and the next event is sent.

The IBM Tivoli Enterprise Console gateway has configuration options that can be specified similarly to how configuration options are specified for an adapter; that is, you can configure the IBM Tivoli Enterprise Console gateway with a configuration file that you distribute to the gateway node endpoint. For details about configuring an IBM Tivoli Enterprise Console gateway, see Chapter 8, “IBM Tivoli Enterprise Console Gateways” on page 95.

2 IBM Tivoli Enterprise Console: Adapters Guide

The following figure shows an example of the IBM Tivoli Enterprise Console product and Tivoli Management Framework component relationships in a network with endpoints.

How Events Get to the Event Server From a Managed Node

For network management OpenView adapters, events are sent from the managed node adapter directly to the event server using a TME interface. In other words, the oserv of the managed node that the adapter runs on sends the event to the oserv of the event server when these are separate nodes, which then forwards it on to the event server process.

For the UNIX log file, OS/2, Windows, Windows NT, and SNMP TME adapters, a managed node must also be configured as an endpoint to send events to the event server.

How Events Get to the Event Server From a Non-TME Adapter

A non-TME adapter sends events directly to the event server using an IP socket.

Internationalization Support for Events

By default, the following log file adapters send their events to the event server in UTF-8 encoding:

vUNIX log file adapter

vNetWare log file adapter

vOS/2 log file adapter

vWindows event log adapter

vWindows NT event log adapter

To change the default configuration of these adapters so they send events in the encoding of the event server host instead of UTF-8, the Pre37Server and Pre37ServerEncoding configuration file options are provided. See page 12 for additional information about these options.

Chapter 1. Understanding Adapters 3

The event server can receive events in both UTF-8 encoding or the encoding of the event 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. If the adapter is sending events to an event server running a version earlier than the IBM Tivoli Enterprise Console 3.7 product, the format files in the localization directories must remain in English. See “Format File” on page 17 and Appendix B, “Format File Reference” on page 145 for additional information.

Tivoli Event Integration Facility provides support for creating new adapters (other than those shipped by the IBM Tivoli Enterprise Console product) or modifying existing adapters to send events to the latest version of the event server. Existing adapters shipped in a previous release of the IBM Tivoli Enterprise Console product do not require updating; the new event server recognizes events sent from those adapters. See the Tivoli Event Integration Facility User’s Guide for additional information.

When the adapter is installed, a new codesets directory appears with the bin and etc directories under $TECADHOME.

Event Information

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

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

After event information is separated into attributes and the event is categorized into an event class, the adapter sends the information to the event server for further processing. Adapters are configured to send only information that administrators are interested in; that is, filters are established on the local system that specify whether to discard an event or forward it to the event server. This minimizes any network loading that is related to enterprise monitoring.

Event Attributes

An event class name is followed by attribute information.

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

attribute_name=value

The following list describes base event attributes that can be contained in an event sent to the event server. Base event attributes are standard for most event classes and 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-defined attributes.

4 IBM Tivoli Enterprise Console: Adapters Guide

Attribute Name

Contents

 

 

acl

The list of authorization roles that enables an administrator to

 

modify the event.

 

 

adapter_host

The host on which the adapter is running.

 

 

administrator

The administrator who acknowledged or closed the event.

 

 

cause_date_

The cause_date_reception attribute is used to link an effect event to

reception

its cause event. This value is set to the value of the date_reception

 

attribute of the cause event.

 

 

cause_event_ handle

The cause_event_handle attribute is used to link an effect event to

 

its cause event. This value is set to the value of the event_handle

 

attribute of the cause event.

 

 

credibility

Indicates how the event was sent from the adapter. The value is 1 if

 

an event was sent using a communications channel provided by

 

Tivoli Management Framework services, as is the case for a TME

 

adapter. The value is zero (0) if an event was sent from a non-TME

 

adapter.

 

 

date

The date and time the event was generated.

 

 

date_reception

A time stamp indicating the time the event server received the

 

event. It is an integer representing the number of seconds since the

 

epoch, which is January 1, 1970. This value is also used as a

 

component to uniquely identify an event. An event is uniquely

 

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

 

was received by the event server until it was closed. For all

 

non-closed events, the value is zero (0).

 

Note: If an event was closed by calling the set_event_status

 

predicate from within a rule, this attribute is not modified to give

 

the age. The value remains at zero (0).

 

 

event_handle

A number used to reference the event. An event is uniquely

 

identified by a combination of the values of the date_reception,

 

event_handle, and server_handle attributes. Events received within

 

the same second are assigned an incremental number for this

 

attribute starting at 1 and incremented by 1.

 

 

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; not

 

currently implemented.

 

 

msg_index

The message ID used to obtain the internationalized message.

 

 

num_actions

The number of actions (tasks or programs) currently being tracked

 

by 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 type

 

of event has been received.

 

 

server_handle

A number identifying the event server that received this event. An

 

event is uniquely identified by a combination of the values for the

 

date_reception, event_handle, and server_handle attributes.

 

 

Chapter 1. Understanding Adapters 5

Attribute Name

Contents

 

 

server_path

Stores information describing the rule engines that an event has

 

passed through. server_path has the following definition:

 

server_path list_of_strings;

 

Each element in the list represents one rule engine that the event

 

has visited, and each element contains a rule engine identifier,

 

server number, reception ID, and event handle. The following is an

 

example of a list:

 

chair 1

12121212 3

 

where:

 

 

chair

The rule engine identifier

 

1

The server number

 

12121212

 

 

 

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

 

number. This mapping is defined in the root.baroc rule base file

 

and is 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). The

 

source is defined by the adapter type.

 

 

 

6 IBM Tivoli Enterprise Console: Adapters Guide

Attribute Name

Contents

 

 

status

The status of an event. It is initially set to OPEN or to a default

 

value specified by the event class. Possible values during an event

 

lifetime are as follows:

 

ACK

An administrator or rule has acknowledged the event.

 

CLOSED

 

 

An administrator or rule has fixed the problem that was

 

 

reported by the event. An event adapter can also send an

 

 

event with a status of CLOSED to indicate that a

 

 

previously received event of the specified class should

 

 

have its status changed to CLOSED; the previously

 

 

received event to be closed is the most recent duplicate of

 

 

the same event. The event being sent with a CLOSED

 

 

status is dropped and not stored in the event database.

 

custom_status

 

 

A status that has been added to the STATUS enumeration

 

 

for site-specific purposes. The STATUS enumeration is

 

 

defined in the root.baroc file. To add a new status, edit this

 

 

file, recompile the rule base, and restart the event server.

 

OPEN

The event has been received by the event server, but no

 

 

administrator or rule has acknowledged it.

 

RESPONSE

 

 

A rule has automatically responded to the event. This

 

 

status is assigned a rule language predicate. It is not

 

 

available from an event console.

 

The database stores the status as a number. This mapping is defined

 

in the root.baroc rule base file and is set for the event server default

 

status 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:

vdate_reception

vevent_handle

vserver_handle

Adapter Files

An adapter uses various files for its operations. The following table provides a brief description of the types of files that can be used. Subsequent sections discuss some of the more common files you might need to view or modify for configuration or troubleshooting purposes. See Appendix A, “Files Shipped with Adapters” on page 141 for detailed information about which files are shipped with particular adapters.

File Type

Description

 

 

Basic recorder of objects in C

Defines event classes to the event server; must be

(BAROC)

part of the rule base.

 

 

Cache

Stores buffered events.

 

 

Class definition statement (CDS)

Defines event class definitions to the adapter.

 

 

Chapter 1. Understanding Adapters 7

File Type

Description

 

 

Configuration

Defines configuration options for adapters.

 

 

Error

Defines error logging and tracing options for the

 

adapter.

 

 

Format

Defines the format of messages and matches them to

 

event classes for the UNIX log file, NetWare log file,

 

OS/2, and Windows and Windows NT event log

 

adapters.

 

 

Installation script

Configures the adapter to start when the operating

 

system starts.

 

 

Object identifier

Defines object-identifier-to-name mappings for the

 

NetView®/6000, OpenView, and SNMP adapters.

Registration

The registration file generated by the installation

 

script for NetView/6000 and OpenView.

 

 

Rules

Defines rules to the event server; must be part of the

 

rule base.

 

 

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

Cache File

Events are written to the cache file using a “circular” method; when the cache file has reached the size limit set by BufEvtMaxSize, the next new event is written to the beginning of the cache file (thus overwriting the existing data at that location). Subsequent events continue being written in order until the end of the 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 will be written and where the next old event will be removed.

The format of the cache file is as follows:

Cache File Format:

-----------------

maxsz: XXXXXXXXXX

head : XXXXXXXXXX

tail : XXXXXXXXXX

........................event1 event2

event3 event4 event5.................

.....................................

.....................................

.....................................

The first three lines in the cache file all have a fixed size of 18 bytes and contain the 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. A value of zero (0) indicates an empty cache file.

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

8 IBM Tivoli Enterprise Console: Adapters Guide

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

Configuration File

Most adapters come with a configuration file containing configuration options and filters. This file is read by an adapter when it is started. By modifying this file, you can reconfigure an adapter at anytime, without having to modify the adapter source code. To have your configuration changes take effect, simply stop and restart the adapter. A configuration file usually has an extension of .conf; see each specific adapter chapter for exact file names.

File Location

By default, an adapter expects its configuration file (along with its format, CDS, and error files) to be located as shown in the following table. For Windows and Windows NT, the syntax shown is correct when running the bash interpreter.

Adapter Type

Node Type

Location

 

 

 

TME

Managed node

$BINDIR/TME/TEC/adapters/etc/ or /etc/Tivoli/tecad/etc

 

 

(which is a link to the TME adapter directory)

 

 

 

 

Endpoint

$LCFROOT/bin/$INTERP/TME/TEC/adapters/etc or

 

 

/etc/Tivoli/tecad/etc (which is a link to the TME adapter

 

 

directory)

 

 

 

non-TME

Not applicable

path/etc where the adapter was manually installed or

 

 

/etc/Tivoli/tecad/etc (which is a link to the TME adapter

 

 

directory)

 

 

 

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

File Format

Each non-blank line that does not begin with the comment sign (#) is of one of the following forms:

vTo specify configuration options: keyword=value

vTo specify event filters:

Filter:CLASS=class_name;attribute=value;

vTo specify event buffer filters:

FilterCache:CLASS=class_name;attribute=value;

Example

#

#Communication Parameters

ServerLocation=ravel

ServerPort=5529

#Event Filters

#

Filter:Class=disk_event Filter:Class=Su_Success;origin=126.32.2.14

Keywords

Keywords use the following format: keyword=value

Chapter 1. Understanding Adapters 9

Some adapters have additional keywords specific to them. See each specific adapter chapter for descriptions of these keywords. Adapters do not issue error messages for misspelled keywords or keywords set to a value that is not valid. Do not use blank spaces in keyword statements unless enclosed in single quotation marks (however, you cannot use quotation marks at all with the HPOVFilter keyword in the HPOV adapter). Do not use class names not defined in a BAROC file with configuration options.

A configuration file can contain the following keywords, which are common to most adapters:

AdapterCdsFile=path

Specifies the full path name of the CDS file. This keyword is required if the CDS file is not in the same directory as the configuration file.

AdapterErrorFile=path

Specifies the full path name of the error file. This keyword is required if the error file is not in the same directory as the configuration file.

BufEvtMaxSize

Specifies the maximum size, in kilobytes, of the adapter cache file. The default value is 64. The cache file stores events on disk when they cannot be sent to the event server.

The BufEvtMaxSize keyword is optional.

BufEvtPath

Specifies the full path name of the adapter cache file. On endpoint adapters, the BufEvtPath keyword uses the $TIVOLIHOME variable to resolve file location and drive letter differences over different environments by using a path relative to the endpoint installation. The ACF defines $TIVOLIHOME on each endpoint; you cannot change its value.

Operating System

Default Path

$TIVOLIHOME Value

 

 

 

UNIX

$TIVOLIHOME/tec/

/etc/Tivoli

 

tecad_adapter.cache

 

 

 

 

Windows, Windows

$TIVOLIHOME\tec\

%SystemRoot%\system32\

NT

tecad_adapter.cache

drivers\etc\Tivoli

 

 

 

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

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

BufferEvents

Specifies whether or not event caching is enabled. If BufferEvents is set to anything other than YES, events are not cached. The value is not case-sensitive. The default value is YES.

The BufferEvents keyword is optional.

BufferFlushRate

Specifies the number of events sent per minute. Once the adapter has recovered the lost connection, and there are events in the buffer, the events are sent at this rate per minute. The default value is zero (0); all events are sent in one burst.

The BufferFlushRate keyword is optional.

ConnectionMode

Specifies the connection mode to use to connect to the IBM Tivoli Enterprise Console gateway or event server. Valid values are

10 IBM Tivoli Enterprise Console: Adapters Guide

connection_oriented (or its abbreviations CO and co) and connection_less. The default value is connection_less, except for the AS/400 adapters and the IBM Tivoli Enterprise Console gateway, which have connection_oriented as the default value.

When connection_less is specified or used by default, a new connection is established (and discarded) for each event or group of events that is sent. When connection_oriented or one of its abbreviations is specified, a connection is established at adapter initialization and is maintained for all events sent. A new connection is established only if the initial connection is lost. The connection is discarded when the adapter is stopped.

The ConnectionMode keyword is optional.

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

A Filter statement must contain the event class, and optionally can include any other attribute=value pair that is defined for the event class. The format of a filtering statement is the following:

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

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

This keyword is optional.

FilterCache

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

A FilterCache statement must contain the event class (class_name) and can include any attribute=value pair that is defined for that event class. The format of a filtering statement is the following:

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

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

This keyword is optional.

Note: When using FilterCache with endpoint adapters and the IBM Tivoli Enterprise Console gateway, you must set the filtering statements at both locations to the same specifications.

FilterMode

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

Chapter 1. Understanding Adapters 11

For information about how to use filtering keywords to send, cache, and discard events, see “Event Filtering” on page 14.

This keyword is optional.

getport_timeout_seconds

Specifies the number of seconds to wait before re-sending the UDP call for a 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

Specifies the number of microseconds to add to the seconds specified with the getport_timeout_seconds keyword. The default value is 50 000 microseconds.

getport_total_timeout_seconds

Specifies the number of seconds to wait on getting a port after making a all to the portmapper. The default value is zero (0) seconds.

getport_total_timeout_usec

Specifies the number of microseconds to add to the seconds specified with the getport_total_timeout_seconds keyword. The default value is 50 000 microseconds.

NO_UTF8_CONVERSION

Specifies whether to encode event data in UTF-8. When this options is set to YES, the IBM Tivoli Enterprise Console product does not encode event data in UTF-8. The data is assumed to already be in UTF-8 encoding when passed to the IBM Tivoli Enterprise Console product. It does, however, prepend the flag indicating that the data is in UTF-8 encoding if the flag does not exist at the beginning of the event data.

The default value for this option is NO.

Pre37Server

Specifies whether the adapter is to send its events in the encoding of the event server host or in UTF-8 encoding. Event server host versions earlier than the IBM Tivoli Enterprise Console 3.7 product do not support UTF-8 encoding of events. When set to YES, this keyword disables UTF-8 encoding and allows the adapter to communicate with event server host versions earlier than the IBM Tivoli Enterprise Console 3.7 product. When this keyword is set to NO, the adapter sends events in UTF-8 encoding. The values are not case-sensitive. The default is NO.

When this keyword is set to YES, you must also specify the

Pre37ServerEncoding keyword.

Pre37ServerEncoding

Determines which language to use when a non-TME adapter communicates with a non-UTF-8 event server host (versions earlier than the IBM Tivoli Enterprise Console 3.7 product). This keyword is active only when Pre37Server is set to YES. This keyword only applies to the log file adapters (UNIX, NetWare, OS/2, Windows, and Windows NT).

RetryInterval

When ConnectionMode=connection_oriented, and the connection to the event server is lost, an adapter waits the specified number of seconds before connecting to a secondary server or buffering the events. While the adapter is waiting for the expiration of this interval, no new events are processed by the adapter.

12 IBM Tivoli Enterprise Console: Adapters Guide

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

If you use this option to wait for restarting an event server, set the value for a period of time longer than necessary for the event server to be stopped and then restarted.

The RetryInterval keyword is optional. The default is 120 seconds.

ServerLocation

Specifies the name of the host on which the event server is installed. The value of this field must be one of the formats shown in the following table, depending on whether the adapter is a TME adapter or a non-TME adapter, and whether the event server is part of an interconnected Tivoli management region:

Adapter Type

Format

 

 

TME

EventServer

 

 

TME in an interconnected

EventServer#region_name

Tivoli management region

 

 

 

non-TME

host_name or IP_address. Use the dotted format

 

for IP_address.

 

 

Note: AS/400 adapters are non-TME adapters.

For TME adapters on managed nodes and non-TME adapters, ServerLocation can contain up to eight values, separated by commas. The first location is the primary event server, while others are secondary servers to be used in the order specified when the primary server is down.

For endpoint adapters, secondary event servers, if any, are defined in the IBM Tivoli Enterprise Console gateway configuration file. Only specify a primary event server in an endpoint adapter configuration file.

The default is EventServer. To use a non-TME value for ServerLocation, see “Configuration File” on page 97 for more information.

The ServerLocation keyword is required.

Note: ServerLocation defines the path and name of the file for logging events, instead of the event server, when used with the TestMode keyword.

ServerPort

Specifies the port number on a non-TME adapter on which the event server listens for events. Set this keyword value to zero (0), the default value unless the portmapper is not available on the event server, which is the case if the event server is running on Windows or the event server is a Tivoli Availability Intermediate Manager (see the following note). If the port number is specified as zero (0) or it is not specified, the port number is retrieved using the portmapper.

The ServerPort keyword can contain up to eight values, separated by commas. For non-TME adapters that send events to a UNIX event server, use the default value of zero (0) (only one value of zero, even if multiple UNIX event servers are specified with the ServerLocation keyword). For

Chapter 1. Understanding Adapters 13

non-TME adapters that send events to a Windows event server or a Tivoli Availability Intermediate Manager (AIM), specify one value for each event server defined with the ServerLocation keyword.

The ServerPort keyword is optional when the event server is running on UNIX, but mandatory when running on Windows.

Note: If the event server is running on Windows: There is no portmapper daemon on a Windows machine that allows the adapter to query the reception port at runtime. The event server listens on a fixed reception port (tec_recv_agent_port in .tec_config) for connection and adapter input. Set ServerPort to the value of the tec_recv_agent_port entry in the .tec_config file in the $BINDIR/TME/TEC directory. The default is 5529. The Tivoli Availability Intermediate Manager never uses the portmapper; the Tivoli Availability Intermediate Manager server listens on a fixed port set in the Tivoli Availability Intermediate Manager graphical user interface.

TestMode

Specifies whether test mode is turned on or off. When TestMode=YES, the ServerLocation 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 is NO.

The TestMode keyword is optional.

Event Filtering

Normally, an adapter sends all events to the event server. You can optionally specify events that can or cannot be sent to the event server. You can do this by specifying the event class and such information as the origin, severity, or any other attribute=value pair that is defined for the event class. The class name specified for an event filter entry must match a defined class name; an adapter does not necessarily have knowledge of the class hierarchy.

Depending on how you specify the Filter and FilterMode keywords, filtered events are either sent to the event server or discarded.

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

vTo discard specific events:

1.Set FilterMode to OUT (the default value).

2.Create Filter statements to match the specific events that you want discarded.

vTo 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-English characters in the local encodings.

14 IBM Tivoli Enterprise Console: Adapters Guide

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

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

The following example shows a Filter statement with a regular expression. This filter statement matches all events with a class name that contains TEC_ somewhere in its name:

Filter:Class=re:’TEC_.*’

The following example shows a FilterCache statement with a narrower range. This filter statement matches all events with a class name that contains TEC_ somewhere in its name and has a severity of 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 a few different adapters:

Adapter

Example

 

 

AS/400 Alert

The following entry matches all events of the

 

SNA_Equipment_Malfunction class from the origin 1.2.3.4:

 

Filter:Class=SNA_Equipment_Malfunction;origin=1.2.3.4

 

 

UNIX Log File

The following entry matches all events of the Su_Success class from

 

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

 

the origin 126.32.2.14:

 

Filter:Class=OV_Message;origin=126.32.2.14

 

 

Windows NT

The following entry matches all events of the NT_Power_Failure

 

class from the origin 126.32.2.14:

 

Filter:Class=NT_Power_Failure;origin=126.32.2.14

 

 

Event Buffer Filtering

When an adapter is unable to connect to the event server or IBM Tivoli Enterprise Console gateway, it sends the events to a file if the BufferEvents keyword is set to YES. You can filter events sent to a cache file, similar to filtering events for the event server by using the FilterCache keyword.

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

The following procedures describe how to filter events with the FilterCache and FilterMode keywords, when the event server is unavailable:

vTo cache specific events:

1.Set FilterMode to IN.

2.Set BufferEvents to YES (the default value).

Chapter 1. Understanding Adapters 15

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.

vTo 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 filter examples for a few different adapters:

Adapter

Example

 

 

AS/400 Alert

The following entry matches all events of the

 

SNA_Equipment_Malfunction class from the origin 1.2.3.4:

 

FilterCache:Class=SNA_Equipment_Malfunction;origin=1.2.3.4

 

 

UNIX Log

The following entry matches all events of the Su_Success class from the

File

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

 

origin 126.32.2.14:

 

FilterCache:Class=OV_Message;origin=126.32.2.14

 

 

Windows NT

The following entry matches all events of the NT_Power_Failure class from

 

the origin 126.32.2.14:

 

FilterCache:Class=NT_Power_Failure;origin=126.32.2.14

 

 

BAROC File

Each adapter comes with a BAROC file describing the classes of events the adapter supports. This file is not used by the adapter itself, but serves as a mandatory link between the adapter and the event server. The event server must load this file before it is able to understand events received from the adapter. A BAROC file has an extension of .baroc; see each specific adapter chapter for exact file names. The format of a BAROC file is described in the IBM Tivoli Enterprise Console Rule Builder’s Guide.

Example

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

CLASS AUTHENTICATION_FAILURE ISA EVENT DEFINES {

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

}; END

16 IBM Tivoli Enterprise Console: Adapters Guide

Rule File

Some adapters come with a rule file describing the classes of events the adapter supports. This file is not used by the adapter itself, but serves as a mandatory link between the adapter and the event server. The event server must load this file before it is able to understand events received from the adapter. A rule file has an extension of .rls; see each specific adapter chapter for exact file names. The format of a rule file is described in the IBM Tivoli Enterprise Console Rule Builder’s Guide.

Example

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

CLASS AUTHENTICATION_FAILURE ISA EVENT DEFINES {

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

}; END

Format File

The UNIX log file, NetWare log file, OS/2, Windows, and Windows NT event log adapters can extract information from system log messages, whose format and meaning can vary widely. This capability is necessary because similar sources can produce messages in different formats. For example, different NFS (network file system) implementations might report the file system full error in different formats. As a result, you might need to match different messages to the same or different event classes. This type of matching is done with a format file.

The purposes of a format file are as follows:

vServes 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 are compared from top to bottom. In situations where there are multiple matching classes for a message, the last matching format specification is used. If no match is found, the event is discarded.

vServes as the source from which a CDS file is generated. See “Class Definition Statement File” on page 18 for additional information.

See Appendix B, “Format File Reference” on page 145 for details about format files.

Example

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

Note: The format files for the log file-type adapters are examples only; customization might be required. The message text must fit on one line and be no longer than 1024 characters.

FORMAT NT_Base

%t %s %s %s %s %s %s %s* hostname DEFAULT

origin DEFAULT category $3 eventType $4 sid $5 sub_source $6 id $7

msg $8

Chapter 1. Understanding Adapters 17

-date1 $1 -date2 $2

date 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 recreate the share %s because the directory %s no longer exists. sharename $8

directoryname $9 END

FORMAT NT_Service_Start FOLLOWS NT_Base

%t %s %s %s %s %s %s %s* started successfully. service $8

END

FORMAT NT_Service_Started FOLLOWS NT_Base

%t %s %s %s %s %s %s The %s* service was started. service $8

END

Class Definition Statement File

CDS files are used by an adapter to map incoming raw events to a particular class and 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 the corresponding .fmt file (if any). If any event definition is changed in a CDS file, the corresponding event class definition in the BAROC file might need changing as well. Event definition content and syntax are discussed in the IBM Tivoli Enterprise Console Rule Builder’s Guide.

See Appendix C, “Class Definition Statement File Reference” on page 155 for details about CDS files.

Example

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_Cisco

SELECT

1:ATTR(=,$ENTERPRISE), VALUE(PREFIX, "1.3.6.1.4.1.9");

2:$TYPE = 4;

3:ATTR(=,"authAddr");

FETCH

1: IPNAME($SOURCE_ADDR); MAP

hostname = $F1; originating_address = $V3;

END

#For Cisco routers, because we know the interface generating the trap,

#we map ’linkUp’ traps to ’linkDown’ CLOSED events

CLASS Link_Down_Cisco

SELECT

1:ATTR(=,$ENTERPRISE), VALUE(PREFIX, "1.3.6.1.4.1.9");

2:$TYPE = 3;

3:ATTR(=,"ifIndex");

18 IBM Tivoli Enterprise Console: Adapters Guide

4:ATTR(=,"ifDescr");

5:ATTR(=,"ifType");

6:ATTR(=,"locIfReason");

FETCH

1:IPNAME($SOURCE_ADDR);

MAP

hostname = $F1; sub_origin = $V4; status = CLOSED; interface_index = $V3;

interface_description = $V4; interface_type = $V5; reason = $V6;

END

Error File

It 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. A different log file can be specified for each module/level pair. To see a continuous flow of adapter processing with tracing, change all occurrences of /dev/null to the same output file. Keep in mind that these tracing features can consume large amounts of disk space.

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

Specifications in the error file allow you to configure tracing options for an adapter. An error file usually has an extension of .err; see each specific adapter chapter for exact file names. An error file is located in the same directory as the adapter configuration file (see “File Location” on page 9 for details).

Note: The error file name can be specified in the configuration file by the AdapterErrorFile 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 error file 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 the error 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 the following:

ERROR

An error function.

UTILS

A utility function.

PARSER

A parsing function.

Chapter 1. Understanding Adapters 19

KERNEL

A general kernel operation.

SELECT

A selection process.

FETCH

A fetch process.

MAP A mapping process.

DRIVER

A driver main program.

DRVSPEC

An SNMP specific driver part.

TECIO

An event server I/O.

error_level Specifies the type of error to look for or the type of trace to perform. Valid values are the following:

MINOR

A minor error.

MAJOR

A major error (running continues).

FATAL

A fatal error (running ends).

LOW Minimal tracing.

NORMAL

Normal tracing.

VERBOSE

Verbose tracing.

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

Initial Files

Each adapter comes with an initial set of files that provides out-of-the-box support for a predefined set of events. The set of files is composed of the following files:

vBAROC file

vCDS file

vFor the adapters on NetWare, OS/2, UNIX, Windows, and Windows NT: format file

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

The number of different events an adapter can receive is infinite. Therefore, the major 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 the system administrator on which to build new event definitions.

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

20 IBM Tivoli Enterprise Console: Adapters Guide

Troubleshooting Adapters

The following sections list troubleshooting guidelines for the different types of adapters.

Adapter Startup Errors

If the adapter fails to start, look in the /tmp directory for the tecadEH.log file. You might be able to learn why the adapter failed from reading this file. The following list shows examples of errors you might find in tecadEH.log:

tecad EH : error 2 invalid error config line: Normal

tecad EH : error 4 Init: Stat failed on error file </etc/tecad_hpov.err>

All Adapters

1.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 file specified by the BufEvtPath keyword.

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

3.If the event was sent to the event server, verify that the event server is actually running. Then run the wtdumprl command to check to see if the event server received the event but failed to parse the event correctly. Also check the current rule base rules to see if the event was dropped. See the IBM Tivoli Enterprise Console Reference Manual for more information about wtdumprl.

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

Managed Node Adapters

1.Use the tracing and debugging options detailed in each chapter. This helps determine if the adapter receives the event and how the adapter handles the event.

2.Use Tivoli Management Framework debugging output of the odstat and wtrace services. These services show what occurs after the adapter tries to send an event from the managed node oserv service to the IBM Tivoli Enterprise Console oserv services, and they also help debug problems that occur during Adapter Configuration Profile (ACP) distributions.

3.Use the managed node wpostemsg command from the system the adapter is running on to see if the event arrives at the event server. See the IBM Tivoli Enterprise Console Reference Manual for more information.

Endpoint Adapters

1.Use the wep ls command to make sure that the endpoint appears under the Tivoli Management Framework gateway you want. See the IBM Tivoli Enterprise Console Reference Manual for more information. Also make sure that any Tivoli Management Framework gateway the endpoint can log on to has ACF 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 enable endpoint tracing to the lcfd.log file. Check to make sure that the endpoint logged into an appropriate Tivoli Management Framework gateway.

Chapter 1. Understanding Adapters 21

3.If the endpoint has logged into a Tivoli Management Framework gateway successfully, create and distribute the ACP profile (see the IBM Tivoli Enterprise Console User’s Guide for details). Check the lcfd.log file if there are further problems; you can also turn on tracing at the Tivoli Management Framework gateway and look in $DBDIR/gatelog for further debugging information.

4.If events do not arrive at the event server but are not incorrectly parsed, check to see if the events are caching on the endpoint instead. If so, either the lcfd process cannot communicate to the Tivoli Management Framework gateway or the event server, or the lcfd process itself is down. Verify that all communications among the event server, Tivoli Management Framework gateway, and endpoint are working.

5.Source the endpoint environment, then use the endpoint wpostemsg command from the system the adapter is running on to see if the event arrives at the event server. See the IBM Tivoli Enterprise Console Reference Manual for more information.

Non-TME Adapters

Use the postemsg command from the system on which the adapter is running to see if the event arrives at the event server. The postemsg command works in environments where Tivoli software is not installed. Thus, this standalone command displays error messages in English only, because the command does not have access to the message catalogs for the language support packs. See the IBM Tivoli Enterprise Console Reference Manual for more information.

22 IBM Tivoli Enterprise Console: Adapters Guide

Chapter 2. AS/400 Alert Adapter

The AS/400 alert adapter forwards events from an AS/400 system to the event server. The adapter can be registered with the startup configuration of the AS/400 so that the adapter is started with all the other applications when the system is started.

The AS/400 alert adapter is a program that does the following:

vMonitors AS/400 alert filters (using data queues) for alerts

vExtracts information from the alerts

vCreates IBM Tivoli Enterprise Console events, using a class definition statement (CDS) file

vFilters IBM Tivoli Enterprise Console events that are not important, using a configuration file

vSends 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 supplied default filter. Multiple AS/400 alert adapters can be running at the same time, each monitoring a different filter.

A few of the benefits are as follows:

vConsolidates alert monitoring

vIntegrates with existing AS/400 alert filters already defined to your specific business rules

vFilters out SNA (Systems Network Architecture) alerts that are not important and only notifies the Tivoli operators when something critical happens

vAutomatically acts on events using customer defined rules and tasks (using the event server)

vCentrally configures adapter files that can be sent to the remote AS/400s

Adapter Files

The AS/400 alert adapter package consists of the following files:

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR

The configuration file

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR

The CDS file

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRBRC.MBR

The BAROC file

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRRLS.MBR

The rules file

Make a backup copy of the CFG_ALERT file before modifying the contents of any of the members.

A backup copy of this file also resides in the CFG_ALERT file in library

QTMETECA02.

© Copyright IBM Corp. 2002

23

The AS/400 adapter package also consists of the following commands, which are copied into QSYS upon installation of the product:

STRTECADP Starts an AS/400 adapter.

ENDTECADP

Ends an AS/400 adapter.

Before starting the event server and an AS/400 alert adapter, check the configuration file to determine if it defines the preferred adapter behavior.

Configuration File

The configuration file for the AS/400 alert adapter defines the behavior of the adapter, 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. The only keyword that is required to be set is ServerLocation. All other keywords have default values 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 is MSGQ if this keyword is not defined, meaning that the adapter monitors a message queue. The value provided in the configuration file is ALERT.

AdapterCdsFile

Specifies the CDS file to be used for the AS/400 alert adapter. This file can reside in either the QSYS or IFS name space, but the path must be specified in IFS notation, for example:

/QSYS.LIB/mylib.LIB/myfile.FILE/mymbr.MBR

 

The default is the following:

 

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR

BufEvtPath

Specifies the path and name of the buffer file for the AS/400 alert

 

adapter. The default path is /etc/Tivoli/tec, and the default buffer

 

file name is the value specified for the adapter name on the

 

AS/400 command (STRTECADP), used to start the adapter.

 

Note: If an AS/400 alert adapter attempts to open a buffer file that

 

is in use by another adapter, the adapter (which runs as a

 

batch job) attempting to open the file ends.

Filter

The name of the AS/400 alert filter to be monitored. The default

 

value is QTMETECA02/QYAAFTR.

FilterDataQueue

The specific data queue that the adapter is to monitor for incoming alerts. If the alert filter is registered with the system, this keyword is required and the data queue must be created by the user before the AS/400 alert adapter is started. This keyword is optional if the alert filter defined by the Filter keyword is not registered with the system, or if the Filter keyword is not specified.

24 IBM Tivoli Enterprise Console: Adapters Guide

JobDescription

Specifies an AS/400 job description that is to be used when starting the adapter. The default is QGPL/QDFTJOBD.

LanguageID Specifies the AS/400 language ID in which alerts are to be sent to the event server. If a value is specified for this keyword, the AS/400 secondary language must be installed for that language ID. The default value for this keyword is ENU.

ProcessExistingAlerts

Specifies whether to send existing alerts on the data queue defined by the FilterDataQueue keyword. NO sends any new alerts sent to the data queue. YES sends the next alert received on the data queue. This can cause the adapter to resend previously sent alerts and create duplicate events sent to the event server. The default is

NO.

ServerCCSID Specifies the coded character set identifier (CCSID) of the event server. This is in case the event server has a special code page or graphic character set that needs to be supported. The default is 00819.

Class Definition Statement File

The CDS file defines how events are constructed from information sent by the AS/400 alert adapter. It is described in detail in “Class Definition Statement File” on page 18.

SELECT Statement Example

SELECT

1:ATTR(=,$ALERT_CDPT),VALUE(PREFIX, "10"); # 10xx codepoints

Here, $ALERT_CDPT is a custom keyword set by the adapter. These keywords can be used to write shorthand notation for SELECT statements. The following is equivalent to the previous example:

SELECT 1:$ALERT_CDPT=10";

FETCH Statement Example

FETCH

1:SUBSTR(value, start, length);

Keywords

To customize events, the AS/400 alert adapter supports the following keywords in class definition statements. Evaluation of these keywords is faster because access of them is direct. Event definition content and syntax are described in the IBM Tivoli Enterprise Console Rule Builder’s Guide.

$ACTIONS Recommended actions to be taken for the alert.

$ACTION_CODE

The legacy action code for non-generic alerts (alert subvector x’91’).

$ADAPTER_CORREL

Unique alert identifier used to extract the alert from the alert database on the AS/400 system.

$ADAPTER_HOST

The protocol address of the host where the adapter is running.

Chapter 2. AS/400 Alert Adapter 25

$ADAPTER_HOST_SNANODE

The netID.nau name of the host where the adapter is running.

$ALERT_CDPT

The alert code point that provides an index into predefined text describing the alert condition.

$ALERT_ID The unique ID describing the alert.

$ARCH_TYPE Defines the alert type, either NONGENERIC_ALERT (alert subvector 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_DATA

Product specific detail data from alert subvector x’98’.

$EVENT_CORREL

Alert correlation data from alert subvector x’47’.

$EVENT_TYPE

A value indicating the severity of the alert condition (for example,

PERMANENT, TEMPORARY, or IMPENDING PROBLEM).

$HOSTNAME

The netID.nau name of the host where the alert originated.

$INCIDENT_CORREL

Alert correlation data from alert subvector x’4A’.

$MSG

The alert code point text and the first probable cause text for the

 

alert.

$ORIGIN The hierarchy list of the alert origin.

$PRODUCT_ID

The hardware and software identifier from alert subvector x’10’.

$SELF_DEF_MSG

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

AS400_ALERT.

$SUB_ORIGIN

The last member in the hierarchy list of the alert origin.

Configuring the AS/400 Alert Filters

Default Alert Filter

The 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 to the group QTECALERT. The corresponding action entry for QTECALERT is also provided. 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 incoming alert information can be monitored by the adapter.

26 IBM Tivoli Enterprise Console: Adapters Guide

If you use the default filter provided, copy it into library QUSRSYS and modify it there.

Integrating with an Existing Alert Filter

You might have alert filters that are already in use on your AS/400 system. These filters have been set up with the appropriate selection and action entries to filter alerts of interest and route them to predefined groups.

The Filter keyword in the configuration file is used to indicate the name of the filter that the AS/400 alert adapter is to monitor. If a value for this keyword is not specified, the default filter (QTMETECA02/QYAAFTR) is used.

The FilterDataQueue keyword in the configuration file is used to indicate the name of the data queue that the adapter is to monitor. The adapter assumes that this data queue has been created properly and has been incorporated into the appropriate action entries data queue list for the filter defined by the Filter keyword. To update an action entry, use the CHGALRACNE (Change Alert Action Entry) 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 per the previous specifications, the adapter will not start. Also, if the AS/400 alert adapter is not running, the system still sends alert information to this data queue. If the data queue is filled to capacity, the filter might be automatically deregistered by the system. To prevent this problem, have the adapter automatically started by a startup program when the system is started (see “Starting the Adapter” on page 27).

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 FilterDataQueue keyword is required. If the filter is not registered with the system and the FilterDataQueue keyword is not specified, then a data queue is created and associated with the QTECALERT group in that filter. Use the Change Network Attributes (CHGNETA) command if you want to register the filter on the AS/400 system.

Starting the Adapter

The AS/400 adapter includes the STRTECADP command that enables you to start an adapter. You can also automatically start the adapter; see “Starting an AS/400 Adapter after an IPL” on page 35. The command is described on the following pages.

Chapter 2. AS/400 Alert Adapter 27

STRTECADP

Starts an AS/400 adapter.

SYNOPSIS

STRTECADP EVTADP(name) CFGFILE(filename)

DESCRIPTION

The AS/400 adapter runs as a batch job. The STRTECADP command starts an AS/400 adapter.

Authorization

QSYSOPR *USE

PUBLIC *EXCLUDE

Note: To grant other users authority to this command, use the following commands 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 the ENDTECADP AS/400 command. It can be any valid AS/400 job name; however, each adapter running on the 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.

EXAMPLES

The following command starts an AS/400 alert adapter using the default configuration 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’)

28 IBM Tivoli Enterprise Console: Adapters Guide

Stopping the Adapter

The AS/400 adapter includes the ENDTECADP command that enables you to stop adapters individually or to stop all started adapters. The command is described on the following pages.

Chapter 2. AS/400 Alert Adapter 29

ENDTECADP

Stops the AS/400 adapter.

Context

ENDTECADP EVTADP(name | *ALL) [OPTION(*CNTRLD | *IMMED)] [DELAY(seconds)]

Comments

The AS/400 adapter runs as a batch job. The ENDTECADP command stops an AS/400 adapter.

Authorization

QSYSOPR *USE

PUBLIC *EXCLUDE

Note: To grant other users authority to this command, use the following commands 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 options can be specified:

name Specifies the name of the adapter being stopped. This file name matches the name specified on the STRTECADP command.

*ALL If *ALL is specified, then all adapters of all types are stopped.

OPTION Specifies the way the adapter stops. The following options can be specified:

*CNTRLD

The adapter ends in a controlled manner. This lets the application program perform end-of-job processing.

*IMMED

The adapter is ended immediately.

Stopping the adapter immediately does not allow the adapter to perform cleanup routines and is not recommended.

DELAY(seconds)

Specifies the amount of time in seconds allowed for the adapter to complete its cleanup processing during a controlled end. This parameter is not used if *IMMED is specified for the OPTION parameter. If the cleanup is not completed before the end of the delay time, the adapter is ended immediately.

30 IBM Tivoli Enterprise Console: Adapters Guide

Examples

The following command stops the AS/400 alert adapter, started with the adapter name ALERTADP.

ENDTECADP EVTADP(ALERTADP)

The following command stops the AS/400 alert adapter, started with the adapter name MYCFG, in a controlled manner with a delay time of 60 seconds.

ENDTECADP EVTADP(MYCFG) OPTION(*CNTRLD) DELAY(60)

Chapter 2. AS/400 Alert Adapter 31

Events Listing

The following shows the class names and severities of all events defined for the AS/400 alert adapter. You can use it to get a sense of how AS/400 alert events are mapped to IBM Tivoli Enterprise Console events and to determine if you want to make any changes. The events are defined in the tecad_snaevent.baroc file on the event server.

See the IBM Tivoli Enterprise Console Rule Builder’s Guide for more information about customizing the BAROC file.

Event Class Structure

Event classes are defined hierarchically, with child classes inheriting attribute value defaults 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 defined in the sample BAROC file provided with this product:

Event Class

Default Event

 

 

 

Severity

 

 

 

 

AS400_TEC_ALERT_ADAPTER

(based on AS/400

 

 

 

alert 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

 

 

 

 

32 IBM Tivoli Enterprise Console: Adapters Guide

Event Class

Default Event

 

 

 

Severity

 

 

 

 

 

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

 

 

 

 

Chapter 2. AS/400 Alert Adapter 33

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

 

 

 

06

(reserved)

HARMLESS

 

 

 

07

(reserved)

HARMLESS

 

 

 

08

(reserved)

HARMLESS

 

 

 

13

(retired)

HARMLESS

 

 

other values

HARMLESS

 

 

 

Troubleshooting the AS/400 Adapter

If a problem occurs with the AS/400 adapter, you can perform problem determination by investigating the job the adapter is running in. Each time you start an AS/400 adapter, a batch job is started. You can view the adapter job by issuing the following command:

WRKJOB JOB(name)

Where name is the name of the adapter job that matches the name specified on the STRTECADP command. This will display the Work with Job dialog.

Note: Several adapter jobs might have existed on your AS/400 system with the same name as the current adapter job. In this case, you are first presented with 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, or if the job has ended (selecting option 10 will tell you so), you can view the job log that was generated by selecting option 4.

Examine the job log for messages indicating the error that occurred and follow the corrective action specified. For further assistance, contact Customer Support.

34 IBM Tivoli Enterprise Console: Adapters Guide

Logging Events in Test Mode

The file to which events are logged in test mode (instead of being sent to an event server) is created with a record length of 240 bytes if it does not exist. Because an event 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 CRTPF or CRTSRCPF commands and specify a large enough record length to accommodate your events. To utilize this file, ensure that it is specified for the ServerLocation keyword. For additional information, see the ServerLocation and TestMode keywords on pages 13 and 14, respectively.

Also, be sure that you use the proper format, ABCLIB/TECMSGS (Library/Filename). If the file does not exist, it is created automatically.

TCP/IP Considerations

Ensure that the event server and the AS/400 are configured in your network Name Server, 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 exists on the AS/400 in the TCP/IP host table for both the event server and the AS/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 IPL

There are two methods that can be used to start an AS/400 alert adapter automatically after an initial program load (IPL), as follows:

vAdding an autostart job to a job queue

vModifying the AS/400 startup program to call the STRTECADP command

Adding an Autostart Job to QSYSWRK

1.Create a Control Language (CL) program that will invoke 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 STRTECADP command 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 system before 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 QSYSNOMAX as the job queue:

Chapter 2. AS/400 Alert Adapter 35

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 after doing the STRTECADP command.

Changing the AS/400 Startup Program

The system value QSTRUPPGM (startup program) contains the name of the program to execute after IPL. This program can be modified to add the starting of adapters.

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)

STRTCP

MONMSG 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:

RETURN

CHGVAR 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. By default, QPGMR does not have authority to the AS/400 alert adapter commands and programs. You must either grant QPGMR authority to the commands and programs (“Starting the Adapter” on page 27) or have the startup program adopt QSECOFR authority and be owned by

QSECOFR.

Multiple AS/400 Alert Adapters

To support another AS/400 alert adapter to monitor a different alert filter or another data queue within the same filter, create the following additional files:

vConfiguration file: Specifies the filter to monitor and data queue to monitor.

vCDS file: Defines new classes to match the alerts being monitored.

vBAROC file: Required if new classes are identified in the CDS file.

vRules file: Required if new rules are added.

36 IBM Tivoli Enterprise Console: Adapters Guide

Configuration File

To 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 new objects, 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’)

Chapter 2. AS/400 Alert Adapter 37

POSTEMSG

Posts an event to the event server. See the IBM Tivoli Enterprise Console Reference Manual for more details about this command.

Context

QTMETECA/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.

Examples

Call 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)

38 IBM Tivoli Enterprise Console: Adapters Guide

+ 144 hidden pages