IBM Tivoli Enterprise Console. Adapters Guide. Version 3.9 SC

Transcription

1 IBM Tivoli Enterprise Console Adapters Guide Version 3.9 SC

2

3 IBM Tivoli Enterprise Console Adapters Guide Version 3.9 SC

4 Note Before using this information and the product it supports, read the information in Notices on page 221. First Edition (August 2003) This edition applies to version 3, release 9 of IBM Tivoli Enterprise Console (product number 5698-TEC) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents About this guide vii Who should read this guide vii Publications vii IBM Tivoli Enterprise Console library.... vii Related publications viii Accessing publications online viii Ordering publications viii Contacting software support ix Participating in newsgroups ix Conventions used in this guide x Typeface conventions x Operating system-dependent variables and paths x Command line syntax xi Chapter 1. Introduction to adapters... 1 Adapter overview How adapters on endpoints send events How adapters on managed nodes send events.. 3 How non-tme adapters send events Internationalization support for events Event information and attributes Adapter files Cache file Configuration file File location File format Example Keywords Event filtering Event buffer filtering BAROC file Rule file Format file Class definition statement file Error file Initial files Troubleshooting adapters Adapter startup errors Troubleshooting for all adapters Managed node adapter troubleshooting Endpoint adapter troubleshooting Non-TME adapter troubleshooting Chapter 2. Installing adapters Supported adapters Hardware and software requirements UNIX and Windows software requirements AS/400 software requirements OS/2 software requirements Installing an HP OpenView adapter on a managed node Installing from the Tivoli desktop Installing from the command line Installing an adapter on an endpoint Installing a non-tme adapter Installing on UNIX operating systems Installing on Windows operating systems Installing on the OS/2 operating system Installing AS/400 adapters Installing from CD Installing from CD on an AS/400 System Installing with English as a secondary language 39 Installing the NetWare logfile adapter Upgrading HP OpenView adapters Preparing to upgrade adapters Backing up object databases Upgrading adapters from the Tivoli desktop.. 40 Upgrading adapters from the command line.. 41 Upgrading adapters using the Software Installation Service Uninstalling adapters Uninstalling an HP OpenView adapter on a managed node Uninstalling an adapter on an endpoint Uninstalling a non-tme adapter Uninstalling on UNIX operating systems.. 42 Uninstalling on Windows operating systems 42 Uninstalling on the OS/2 operating system.. 42 Uninstalling an AS/400 adapter Uninstalling a NetWare logfile adapter Removing Version 3.8 enhanced adapters from the Tivoli environment Chapter 3. Adapter Configuration Facility Using adapter configuration profiles Adapter Configuration Facility roles Setting adapter configuration profiles as managed resources Setting adapter configuration profiles as managed resources from the Tivoli desktop Setting adapter configuration profiles as managed resources from the command line Creating an adapter configuration profile Creating an adapter configuration profile from the Tivoli desktop Creating an adapter configuration profile from the command line Cloning an adapter configuration profile Cloning an adapter configuration profile from the Tivoli desktop Cloning an adapter configuration profile from the command line Deleting an adapter configuration profile Deleting an adapter configuration profile from the Tivoli desktop Deleting an adapter configuration profile from the command line Setting adapter configuration profile defaults Renaming a profile Copyright IBM Corp iii

6 Getting a new copy of an adapter configuration profile Getting a new copy of an adapter configuration profile from the Tivoli desktop Getting a new copy of an adapter configuration profile from the command line Setting adapter configuration profile distribution defaults Modifying an adapter configuration profile default policy Modifying an adapter configuration profile default policy from the Tivoli desktop Modifying an adapter configuration profile default policy from the command line Modifying an adapter configuration profile validation policy Modifying an adapter configuration profile validation policy from the Tivoli desktop Modifying an adapter configuration profile validation policy from the command line Distributing an adapter configuration profile Distributing an adapter configuration profile from the Tivoli desktop Distributing an adapter configuration profile from the command line Adding an adapter configuration profile record.. 57 Endpoint adapters Editing an adapter configuration profile record.. 58 Adding a configuration option to an adapter configuration profile record Modifying a configuration option in an adapter configuration profile record Removing an environment variable from an adapter configuration profile record Adding a filter definition to an adapter configuration profile record Adding a filter cache definition to an adapter configuration profile record Adding a prefilter definition to an adapter configuration profile record Modifying a filter definition in an adapter configuration profile record Modifying a filter cache definition in an adapter configuration profile record Modifying a prefilter definition in an adapter configuration profile record Removing a filter cache definition in an adapter configuration profile record Removing a prefilter definition in an adapter configuration profile record Removing a filter definition from an adapter configuration profile record Adding a file to the distribution list of an adapter configuration profile record Removing a file from the distribution list of an adapter configuration profile record Modifying the adapter configuration file behavior 68 Modifying variable expansion behavior Adding a before or after script to an adapter configuration profile record Modifying a before or after script in an adapter configuration profile record Removing a before or after script from an adapter configuration profile record Enabling and disabling before and after scripts in an adapter configuration profile record Modifying before and after script reporting behavior Modifying the comment in an adapter configuration profile record Modifying the UID and GID in an adapter configuration profile record Specifying the adapter identifier name Copying an adapter configuration profile record.. 73 Copying an adapter configuration profile record from the Tivoli desktop Moving an adapter configuration profile record.. 74 Moving an adapter configuration profile Record from the Tivoli desktop Deleting an adapter configuration profile record.. 75 Deleting an adapter configuration profile record from the Tivoli desktop Deleting an adapter configuration profile record from the command line Locking and unlocking an adapter configuration profile record Locking and unlocking an adapter configuration profile Record from the Tivoli desktop Finding an adapter configuration profile record.. 76 Sorting adapter configuration profile records Sorting adapter configuration profile attributes.. 78 Starting the Logfile Format Editor from an adapter configuration profile Chapter 4. AS/400 alert adapter Adapter files Configuration file Class definition statement file SELECT statement example FETCH statement example Keywords Configuring the AS/400 alert filters Default alert filter Integrating with an existing alert filter Starting the adapter STRTECADP Stopping the adapter ENDTECADP Events Listing Event class structure Troubleshooting the AS/400 adapter Logging Events in Test Mode TCP/IP considerations Starting an AS/400 adapter after an IPL Adding an autostart job to QSYSWRK Changing the AS/400 startup program Multiple AS/400 alert adapters Configuration file QTMETECA/POSTEMSG Common tasks iv IBM Tivoli Enterprise Console: Adapters Guide

7 Chapter 5. AS/400 message adapter.. 99 Adapter Files Configuration file Class definition statement file SELECT statement example FETCH statement example MAP statement example Keywords Starting the adapter STRTECADP Stopping the adapter ENDTECADP Events listing Event class structure Troubleshooting the AS/400 adapter Logging Events in Test Mode TCP/IP considerations Starting an AS/400 adapter after an IPL Adding an autostart job to QSYSWRK Changing the AS/400 startup program Multiple AS/400 message queues Configuration file Using FTP to run AS/400 commands Common tasks Chapter 6. NetWare logfile adapter 115 NetWare logfile adapter reference information Adapter files Error file Prefiltering NetWare events Configuration file Format file Events listing Event class structure tecadnw4.nlm load tecadnw Troubleshooting the NetWare logfile adapter Chapter 7. OpenView adapter OpenView driver Reception of OpenView messages Determining the OpenView NNM version Incoming messages format Event correlation with NNM Determining the OVsnmpEventOpen filter value 127 Testing tools Testing event correlation with NNM Event correlation example Adapter files Configuration file Class definition statement file OpenView event example Keywords Object identifier file Error file LRF file Starting and stopping the adapter Events listing Event class structure OpenView traps SNMP traps OpenView traps Troubleshooting the OpenView adapter Chapter 8. OS/2 adapter Adapter files Configuration file Format file Starting the adapter Stopping the adapter Events listing Event class structure Troubleshooting the OS/2 adapter Chapter 9. SNMP adapter SNMP driver Reception of SNMP messages Incoming messages format Server configuration Adapter files Configuration file Class definition statement file SNMP event example Keywords Object identifier file Error file Starting and stopping the adapter Cold start Warm start Stopping the adapter Events listing Event class structure Rules listing SNMP traps Generic traps Enterprise-specific traps Creating a new SNMP trap event BAROC file changes Agent-independent data Class definition statement file changes Object identifier file changes Troubleshooting the SNMP adapter Chapter 10. UNIX logfile adapter Event server configuration Starting the adapter Stopping the adapter Reloading the adapter configuration Running multiple UNIX logfile adapters Adapter files Configuration file Format file Class definition statement file Error file Events listing Event class structure Default rules Troubleshooting the UNIX logfile adapter Contents v

8 Chapter 11. Windows event log adapter Adapter files Configuration file Prefiltering Windows log events Format file Registry variables Low memory registry variables Starting the adapter Stopping the adapter Reloading the adapter configuration Running multiple Windows event log adapters Events listing Event class structure tecad_win command tecad_win Troubleshooting the Windows event log adapter 182 Appendix A. Files shipped with adapters Appendix B. Format file reference Format file location Format specifications Log file example Windows example Mappings Additional mapping considerations Activating changes made with a format file Generating a new class definition statement file for a TME adapter Generating a new class definition statement file for a non-tme adapter Appendix C. Class definition statement file reference File format Operators Class definition statement file details SELECT statement FETCH statement MAP statement MAP_DEFAULT statement Example Object identifier to name translation Class definition statement file syntax diagrams Appendix D. Logfile Format Editor 207 Configuring a format file for a logfile adapter Notices Trademarks Index vi IBM Tivoli Enterprise Console: Adapters Guide

9 About this guide Who should read this guide Publications The IBM Tivoli Enterprise Console product is a rule-based, event management application that integrates system, network, database, and application management to help ensure the optimal availability of an organization s IT services. The IBM Tivoli Enterprise Console Adapters Guide describes the currently available Tivoli Enterprise Console adapters. This guide is for Tivoli Enterprise Console administrators who install and configure event adapters. You should have prior knowledge of the following software: v The operating systems that your enterprise uses v The Tivoli Management Framework v Adapter operating systems; for example, if you use an OpenView adapter, you should be familiar with Hewlett-Packard OpenView. This section lists publications in the Tivoli Enterprise Console library and related documents. It also describes how to access Tivoli publications online and how to order Tivoli publications. IBM Tivoli Enterprise Console library The following documents are available in the Tivoli Enterprise Console library: v IBM Tivoli Enterprise Console Adapters Guide, SC Provides information about supported adapters, including how to install and configure these adapters. v IBM Tivoli Enterprise Console Command and Task Reference, SC Provides details about IBM Tivoli Enterprise Console commands, predefined tasks that are shipped in the task library, and the environment variables that are available to tasks that run against an event. v IBM Tivoli Enterprise Console Installation Guide, SC Describes how to install, upgrade, and uninstall the IBM Tivoli Enterprise Console product. v IBM Tivoli Enterprise Console Release Notes, SC Provides release-specific information that is not available until just before the product is sent to market. v IBM Tivoli Enterprise Console Rule Developer s Guide, SC Describes how to develop rules and integrate them for event correlation and automated event management. v IBM Tivoli Enterprise Console Rule Set Reference, SC Provides reference information about the IBM Tivoli Enterprise Console rule sets. v IBM Tivoli Enterprise Console User s Guide, SC Copyright IBM Corp vii

10 v v Provides an overview of the IBM Tivoli Enterprise Console product and describes how to configure and use the IBM Tivoli Enterprise Console product to manage events. IBM Tivoli Enterprise Console Warehouse Enablement Pack: Implementation Guide, SC Describes how to install and configure the warehouse enablement pack for the IBM Tivoli Enterprise Console product and describes the data flow and structures that are used by the warehouse pack. Tivoli Event Integration Facility Reference, SC Describes how to develop your own event adapters that are tailored to your network environment and the specific needs of your enterprise. This reference also describes how to filter events at the source. Related publications The Tivoli Software Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Software Glossary is available, in English only, at the following Web site: Access the glossary by clicking the Glossary link on the left pane of the Tivoli software library window. Accessing publications online The documentation CD contains the publications that are in the product library. The format of the publications is PDF, HTML, or both. Refer to the readme file on the CD for instructions on how to access the documentation. IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the Tivoli Software Information Center Web site. Access the Tivoli Software Information Center by first going to the Tivoli software library at the following Web address: Scroll down and click the Product manuals link. In the Tivoli Technical Product Documents Alphabetical Listing window, click the IBM Tivoli Enterprise Console link to access the product library at the Tivoli Information Center. Note: If you print PDF documents on other than letter-sized paper, select the Fit to page check box in the Adobe Acrobat Print window. This option is available when you click File Print. Fit to page ensures that the full dimensions of a letter-sized page print on the paper that you are using. Ordering publications You can order many Tivoli publications online at the following Web site: cgibin/pbi.cgi You can also order by telephone by calling one of these numbers: v In the United States: v In Canada: viii IBM Tivoli Enterprise Console: Adapters Guide

11 Contacting software support Participating in newsgroups In other countries, see the following Web site for a list of telephone numbers: If you have a problem with any Tivoli product, refer to the following IBM Software Support Web site: If you want to contact software support, see the IBM Software Support Guide at the following Web site: The guide provides information about how to contact IBM Software Support, depending on the severity of your problem, and the following information: v Registration and eligibility v v Telephone numbers and addresses, depending on the country in which you are located Information you must have before contacting IBM Software Support User groups provide software professionals with a forum for communicating ideas, technical expertise, and experiences related to the product. They are located on the Internet and are available using standard news reader programs. These groups are primarily intended for user-to-user communication and are not a replacement for formal support. To access a newsgroup, use the instructions appropriate for your browser. Use these instructions for a Microsoft Internet Explorer browser. 1. Open an Internet Explorer browser. 2. From the Tools menu, click Internet Options. 3. On the Internet Options window, click the Programs tab. 4. In the Newsgroups list, click the Down Arrow and then click Outlook Express. 5. Click OK. 6. Close your Internet Explorer browser and then open it again. 7. Cut and paste the newsgroup address of a product into the browser Address field, and press Enter to open the newsgroup. Use these instructions for a Netscape Navigator browser. 1. Open a Netscape Navigator browser. 2. From the Edit menu, click Preferences. The Preferences window is displayed. 3. In the Category view, click Mail & Newsgroups to display the Mail & Newsgroups settings. 4. Select the Use Netscape mail as the default mail application check box. 5. Click OK. 6. Close your Netscape Navigator browser and then open it again. About this guide ix

12 7. Cut and paste the newsgroup address of a product into the browser Address field, and press Enter to open the newsgroup. IBM Tivoli Enterprise Console: news://news.software.ibm.com/ibm.software.tivoli.enterprise-console IBM Tivoli NetView for UNIX and IBM Tivoli NetView for Windows : news://news.software.ibm.com/ibm.software.tivoli.netview-unix-windows Conventions used in this guide This guide uses several conventions for special terms and actions, operating system-dependent commands and paths, and command syntax. Typeface conventions This guide uses the following typeface conventions: Bold v v v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) Keywords and parameters in text Italic v Words defined in text v Emphasis of words (words as words) v New terms in text (except in a definition list) v Variables and values you must provide Monospace v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options Operating system-dependent variables and paths This guide 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

13 Command line syntax This document uses the following special characters to define the command syntax: [] Identifies an optional argument. Arguments not enclosed in brackets are required.... Indicates that you can specify multiple values for the previous argument. Indicates mutually exclusive information. You can use the argument to the left of the separator or the argument to the right of the separator. You cannot use both arguments in a single use of the command. {} Delimits a set of mutually exclusive arguments when one of the arguments is required. If the arguments are optional, they are enclosed in brackets ([ ]). For example: wsetsrc [ S server] [ l label] [ n name] source The source argument is the only required argument for the wsetsrc command. The brackets around the other arguments indicate that these arguments are optional. Another example is the wlsac command: wlsac [ l f format] [key... ] profile In this example, the l and f format arguments are mutually exclusive and optional. The profile argument is required. The key argument is optional. Also, the ellipsis marks (...) following the key argument indicate that you can specify multiple key names. Another example is the wrb import command: wrb import {rule_pack rule_set}... In this example, the rule_pack and rule_set arguments are mutually exclusive, but one of the arguments must be specified. Also, the ellipsis marks (...) indicate that you can specify multiple rule packs or rule sets. About this guide xi

14 xii IBM Tivoli Enterprise Console: Adapters Guide

15 Chapter 1. Introduction to adapters Adapter overview Event adapters are software programs that collect information, perform local filtering, and convert relevant events into a format that can be used by the 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 Tivoli Enterprise Console product can seamlessly integrate alarms and events from all the major network management operating systems 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. 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: v An 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). v An adapter can check an ASCII log file for raw events at configured intervals if the source updates a log file with messages. Adapters can send events to the event server using a Tivoli interface or a non-tivoli 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 Tivoli interface establishes a connection using the oserv services provided by Tivoli Management Framework; adapters that use this interface are referred to as TME adapters. Anon-Tivoli interface establishes connections using standard interprocess communication mechanisms (for example, opening an IP socket); adapters that use this interface are called non-tme adapters. Note: If you are sending events from an adapter using a Tivoli connection to an event server in a remote Tivoli region, the connection must allow the adapter to send information to the remote event server. The adapter should be on the master side of a one-way connection or, more likely, the Copyright IBM Corp

16 connection should be a two-way connection. If you are sending events from a non-tme adapter, the type of interconnection with the Tivoli regions does not matter. How adapters on endpoints send events TME adapters installed on endpoints send their events to the lcfd process, which then sends the events to a Tivoli Enterprise Console gateway, which in turn bundles them up and forwards them on to an event server. A Tivoli interface is used for communication between the endpoint and the gateway. The default service to the server used by the Tivoli Enterprise Console gateway is a connection-oriented service to the server. 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 Tivoli Enterprise Console gateway runs on the same managed node as the Tivoli Management Framework gateway that is providing the endpoint gateway service. The Tivoli Enterprise Console gateway provides the following benefits: v v v Greater scalability, meaning you can manage many sources easier, with less software running on the endpoints. Greatly reduces the amount of communications tasks performed by the event server or the Tivoli management region server, as the Tivoli Enterprise Console gateway bundles a number of events before sending them to the event server. This improves event server performance. Easier deployment of adapters and updates to adapters using profiles in the Adapter Configuration Facility. The TME adapters currently supported for an endpoint are as follows: v UNIX log file v OS/2 v v SNMP Microsoft Windows event log You can configure these adapters to send their events to specific primary, secondary or both event servers, and the Tivoli Enterprise Console gateway forwards them appropriately. v v If the Tivoli Enterprise Console gateway, Tivoli Management Framework gateway, or lcfd process is down, events are buffered at the endpoint and are sent again when communication is restored, as follows: If the endpoint (lcfd process) is down, events are buffered at the endpoint. When the endpoint is restarted and logs in to the Tivoli Management Framework gateway, events are sent as usual. If the Tivoli Management Framework gateway is down, events are buffered at the endpoint. Events are not forwarded until the endpoint logs back in to the Tivoli Management Framework gateway. This delay can be as much as 5 minutes after the Tivoli Management Framework gateway is restarted but can be configured on the endpoint. If the Tivoli Enterprise Console gateway is down (but the lcfd process or the Tivoli Management Framework gateway are still up), the Tivoli Enterprise Console gateway is restarted, and events are sent as usual. If an event server is down (but the Tivoli Enterprise Console gateway, Tivoli Management Framework gateway, and lcfd processes are still up), events are buffered at the Tivoli Enterprise Console gateway. They are sent again when communication with the server is restored. 2 IBM Tivoli Enterprise Console: Adapters Guide

17 The following figure shows an example of the Tivoli Enterprise Console product and Tivoli Management Framework component relationships in a network with endpoints. Event Server Managed Node Endpoint Gateway Tivoli Enterprise Console Gateway Adapter Configuration Facility Adapters Managed Node Endpoint Gateway Tivoli Enterprise Console Gateway Adapter Configuration Facility Adapters Managed Node Tivoli Availability Intermediate Manager Endpoints Adapters Endpoints Adapters Figure 1. Components relationships of the Tivoli Enterprise Console product and Tivoli Management Framework How adapters on managed nodes send events For network management HP OpenView adapters, the managed node adapter sends events directly to the event server using a Tivoli interface. In other words, the oserv of the managed node that the adapter runs on sends the event to the oserv of the event server when these are separate nodes, which then forwards it on to the event server process. For the UNIX logfile, OS/2, Windows, and SNMP TME adapters, a managed node must also be configured as an endpoint to send events to the event server. How non-tme adapters send events A non-tme adapter sends events directly to the event server using an IP socket. Internationalization support for events The defaulting encoding that the following logfile adapters use to send their events to the event server is UTF-8 encoding: v UNIX logfile adapter v NetWare logfile adapter v OS/2 logfile adapter v Windows 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 Chapter 1. Introduction to adapters 3

18 Pre37ServerEncoding configuration file options are provided. See Keywords on page 10 for additional information about these options. 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 Tivoli Enterprise Console 3.7 product, the format files in the localization directories must remain in English. See Format file on page 24 and Appendix B, Format file reference, on page 187 for additional information. Tivoli Event Integration Facility provides support for creating new adapters (other than those shipped by the 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 Tivoli Enterprise Console product do not require updating; the new event server recognizes events sent from those adapters. See the Tivoli Event Integration Facility Reference for additional information. When a non-tme adapter is installed, a new codeset directory is created with the bin and etc directories under the $TECADHOME directory. If you install an adapter with an ID, the etc and codeset directories are created under the $TECADHOME/ID directory Event information and attributes 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 information that only 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. 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=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 4 IBM Tivoli Enterprise Console: Adapters Guide

19 (BAROC) file. An adapter can also contain adapter-specific or user-defined attributes. Table 1. Base event attributes Attribute Name Contents acl The list of authorization roles that an administrator uses 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_ reception cause_event_ handle credibility date date_reception duration event_handle fqhostname hostname msg msg_catalog msg_index num_actions origin repeat_count The cause_date_reception attribute is used to link an effect event to its cause event. This value is set to the value of the date_reception attribute of the cause event. 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. 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. The date and time the event was generated. 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, 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. 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). 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 increased by 1. The fully qualified host name of the system where the event originated. The name of the system on which the event occurred. A text summary of the event. For future support of internationalized event messages; not currently implemented. The message ID used to obtain the internationalized message. The number of actions (tasks or programs) currently being tracked by the event server for this event. The protocol address or host name of the source system. A counter for keeping track of the number of times a duplicate type of event has been received. Chapter 1. Introduction to adapters 5

20 Table 1. Base event attributes (continued) Attribute Name Contents 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. 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 where: severity source chair The rule engine identifier 1 The server number The event reception ID in server 1 3 The event handle for the event in server 1 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 MINOR 50 CRITICAL 60 FATAL You can also customize the severity settings. 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

21 Table 1. Base event attributes (continued) Attribute Name status Contents 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 sub_source A further categorization of the origin. This attribute is optional. A further categorization of the source. This attribute is optional. The adapter uses the following attributes to uniquely identify an event: v date_reception v event_handle v server_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 describe 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 183 for detailed information about which files are shipped with particular adapters. Table 2. Adapter files File Type Basic recorder of objects in C (BAROC) Description Defines event classes to the event server; must be part of the rule base. Chapter 1. Introduction to adapters 7

22 Table 2. Adapter files (continued) File Type Cache Class definition statement (CDS) Configuration Error Format Installation script Object identifier Registration Rules Description Stores buffered events. Defines event class definitions to the adapter. Defines configuration options for adapters. Defines error logging and tracing options for the adapter. Defines the format of messages and matches them to event classes for the UNIX logfile, NetWare logfile, OS/2, and Windows event log adapters. Configures the adapter to start when the operating system starts. Defines object-identifier-to-name mappings for the NetView/6000, OpenView, and SNMP adapters. The registration file generated by the installation script for NetView/6000 and OpenView. Defines rules to the event server; must be part of the rule base. An adapter uses the Tivoli Management Framework TIVOLI_COMM_DIR environment variable, if set, to determine which directory to use for its lock and pipe files. If the variable is not set, the /tmp/.tivoli directory 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 the BufEvtMaxSize keyword, 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 is to be written and where the next old event is to be removed. The format of the cache file is as follows: maxsz: XXXXXXXXXX head : XXXXXXXXXX tail : XXXXXXXXXX...event1 event2 event3 event4 event The first three lines in the cache file all have a fixed size of 18 bytes and contain the following data: maxsz head tail The maximum size of the cache file. 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. 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

23 The boundaries between events in the cache file are indicated by a ^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 An adapter expects its configuration file (along with its format, CDS, and error files) to be located in the default locations shown in the following table. For Windows, the syntax shown is correct when running the bash interpreter. Table 3. Location of adapter configuration files Adapter Type Node Type Location TME Managed node $BINDIR/TME/TEC/adapters/etc/ or /etc/tivoli/tecad/etc (which is a link to the 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 non-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: v To specify configuration options: v v keyword=value To specify event filters: Filter:Class=class_name;attribute=value; To specify event buffer filters: FilterCache:Class=class_name;attribute=value; Example # # Communication Parameters # TransportList=t1,t2_ t1type=socket t1channels=c1_,c2 c1_serverlocation=host1 c1_port=5529 c2serverlocation=host2 c2port=5529 t2_type=lcf Chapter 1. Introduction to adapters 9

24 t2_channels=c3_ # # Event Filters # Filter:Class=disk_event Filter:Class=Su_Success;origin= Keywords Keywords use the following format: keyword=value Type each keyword on a separate line. 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 for the HP Openview adapter. Do not use class names that are not defined in a BAROC file with configuration options. Note: Adapters do not issue error messages for misspelled keywords or keywords set to a value that is not valid. A configuration file can contain the following keywords, which are common to most adapters. Note: Not all keywords apply to all adapters, and some adapters have additional keywords specific to them. See each specific adapter chapter for descriptions of these keywords. 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. APPEND_CLASSPATH=string Specifies the string that is appended to the CLASSPATH environment variable before the Java -based State Correlation is called. The string is appended using the appropriate delimiter:, semicolon (;) for Windows systems or colon (:) for UNIX systems. The string must contain valid data for your environment; for example, APPEND_CLASSPATH=c: \my_product\my_java.class; d: \my_product\my_jar.jar for Windows systems or APPEND _CLASSPATH=/my_product/my_java.class: /my_product/my_jar.jar for UNIX systems. For the Tivoli Enterprise Console gateway the specified string is appeneded to the list of jar files needed for State Correlation. For an adapter written in C, the specified string is appended to the system environment CLASSPATH. Note: The system environment CLASSPATH is not changed. This CLASSPATH information is passed to Java during the State Correlation initialization. This keyword can be specified only once in your configuration file. APPEND_JVMPATH=string Specifies the string that is appended to the dynamic library path environment variable before the Java-based state correlation is called. The string is appended using the appropriate delimiter: semi-colon (;) for 10 IBM Tivoli Enterprise Console: Adapters Guide