SPECTRUM PATROL Integration

Transcription

1 SPECTRUM PATROL Integration Administrator Guide Document 5170

2 Notice Copyright Notice Copyright 2002-present by Aprisma Management Technologies, Inc. All rights reserved worldwide. Use, duplication, or disclosure by the United States government is subject to the restrictions set forth in DFARS (c)(1)(ii) and FAR Liability Disclaimer Aprisma Management Technologies, Inc. ( Aprisma ) reserves the right to make changes in specifications and other information contained in this document without prior notice. In all cases, the reader should contact Aprisma to inquire if any changes have been made. The hardware, firmware, or software described in this manual is subject to change without notice. IN NO EVENT SHALL APRISMA, ITS EMPLOYEES, OFFICERS, DIRECTORS, AGENTS, OR AFFILIATES BE LIABLE FOR ANY INCIDENTAL, INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING BUT NOT LIMITED TO LOST PROFITS) ARISING OUT OF OR RELATED TO THIS MANUAL OR THE INFORMATION CONTAINED IN IT, EVEN IF APRISMA HAS BEEN ADVISED OF, HAS KNOWN, OR SHOULD HAVE KNOWN, THE POSSIBILITY OF SUCH DAMAGES. Trademark, Service Mark, and Logo Information SPECTRUM, IMT, and the SPECTRUM IMT/VNM logo are registered trademarks of Aprisma Management Technologies, Inc., or its affiliates. APRISMA, APRISMA MANAGEMENT TECHNOLOGIES, the APRISMA MANAGEMENT TECHNOLOGIES logo, MANAGE WHAT MATTERS, DCM, VNM, SpectroGRAPH, SpectroSERVER, Inductive Modeling Technology, Device Communications Manager, SPECTRUM Security Manager, and Virtual Network Machine are unregistered trademarks of Aprisma Management Technologies, Inc., or its affiliates. For a complete list of Aprisma trademarks, service marks, and trade names, go to: All referenced trademarks, service marks, and trade names identified in this document, whether registered or unregistered, are the intellectual property of their respective owners. No rights are granted by Aprisma Management Technologies, Inc., to use such marks, whether by implication, estoppel, or otherwise. If you have comments or concerns about trademark or copyright references, please send an to spectrum-docs@aprisma.com; we will do our best to help. Restricted Rights Notice (Applicable to licenses to the United States government only.) This software and/or user documentation is/are provided with RESTRICTED AND LIMITED RIGHTS. Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR (June 1987) Alternate III(g)(3) (June 1987), FAR (June 1987), or DFARS (c)(1)(ii) (June 1988), and/or in similar or successor clauses in the FAR or DFARS, or in the DOD or NASA FAR Supplement, as applicable. Contractor/manufacturer is Aprisma Management Technologies, Inc. In the event the government seeks to obtain the software pursuant to standard commercial practice, this software agreement, instead of the noted regulatory clauses, shall control the terms of the government's license. Virus Disclaimer Aprisma makes no representations or warranties to the effect that the licensed software is virus-free. Aprisma has tested its software with current virus-checking technologies. However, because no antivirus system is 100- percent effective, we strongly recommend that you write protect the licensed software and verify (with an antivirus system with which you have confidence) that the licensed software, prior to installation, is virus-free. Contact Information Aprisma Management Technologies, Inc., 273 Corporate Drive, Portsmouth, NH USA Phone: U.S. toll-free: Web site:

3 Contents How this guide is organized SPECTRUM Documentation Set PATROL Documentation Set Document Feedback Contacting Concord Communications Chapter 1: Overview About PATROL Integration for SPECTRUM PATROL Integration components PATROL components PATROL Event Translator for SPECTRUM external protocol interface PATROL Integration Configuration Utility PATROL Integration configuration file PATROL model types in SPECTRUM How PATROL Integration works PATROL Integration features Monitoring of PATROL Agent resources Propagation of alarms and events Event and alarm handling Information views How management and physical faults are isolated Example of fault isolation determining physical fault Example of fault isolation in management-level connectivity Fault isolation scenarios Chapter 2: PATROL Integration Configuration Using the PATROL Integration Configuration Utility Starting the PATROL Integration Configuration Utility Specifying the hosts that you want to manage Modifying host attributes Removing hosts from the configuration Setting the PATROL Alarm Filter Setting connection attributes Setting the connection tolerance values Setting attributes for diagnostic output messages Managing pet.log files Setting PET Autodiscovery attributes and adding autodiscovered hosts Setting server port, local port, and communications save time SPECTRUM PATROL Integration Administrator Guide 1

4 Contents Customizing PATROL event messages Preventing unwanted PATROL events Applying filter related keywords Preventing SPECTRUM from recreating application instances Saving and using configuration settings Using the Online Command Interface To Use the Online Command Interface Setting the PET_ACL Keyword SPECTRUM PATROL Integration Administrator Guide

5 Preface This administrator guide contains information about PATROL Integration for SPECTRUM, and is intended for system administrators. Specifically, this guide includes an overview of features and detailed information for configuring the integration. For additional information about using SPECTRUM or PATROL, we recommend consulting either the SPECTRUM or PATROL product documentation. How this guide is organized This guide is organized as follows: Chapter 1: Overview. This chapter provides an overview of the features, concepts, and processes inherent to the PATROL Integration for SPECTRUM. Chapter 2: PATROL Integration Configuration. This chapter describes how to use the configuration utility to enter keywords and parameters in the configuration file. SPECTRUM Documentation Set The SPECTRUM documentation set is available online at: Use this site to download the latest documentation updates and additions. To log onto the SPECTRUM Documentation site, you must supply your contract number and license number. For late-breaking information not included in the SPECTRUM manuals, see the SPECTRUM Software Release Notice (SRN). We recommend reviewing this file before working with SPECTRUM. Typically, the SRN offers information about the latest changes, fixes, Known Issues and Work- Arounds. You can access the SRN from the SPECTRUM product CD or from the SPECTRUM documentation web site. PATROL Documentation Set To view any online book that BMC Software offers, visit the support page of the BMC Software web site at 3

6 To log on, first time users can request a user name and password by registering at the support page or by contacting BMC Software sales representative. Document Feedback Please send feedback regarding SPECTRUM documents to the following address: spectrum-docs@aprisma.com Thank you for helping us improve our documentation. Contacting Concord Communications Contact information for Concord SPECTRUM Business Unit is available at: 4 SPECTRUM PATROL Integration Administrator Guide

7 Chapter 1: Overview This chapter provides an overview of Patrol Integration for SPECTRUM. It includes a discussion about the following topics: About PATROL Integration for SPECTRUM on page 5 PATROL Integration components on page 5 PATROL Integration features on page 10 How management and physical faults are isolated on page 12 About PATROL Integration for SPECTRUM PATROL Integration for SPECTRUM (PATROL Integration) provides a cost-effective, seamless, and transparent interface between resources that are managed by PATROL Agent software and SPECTRUM. PATROL Integration makes it possible to quickly and efficiently extend the monitoring capabilities of the SPECTRUM management solution to a wider range of systems, applications, databases, messaging and middleware systems, and internet and intranet servers that are being monitored by PATROL Agents. PATROL Integration components PATROL Integration consists of the following key components: PATROL Event Translator for SPECTRUM External Protocol Interface (PETEPI) PATROL Integration configuration utility PATROL Integration configuration file PATROL components The PATROL suite of application management products monitors critical resources on hosts within your enterprise. PATROL monitors applications, operating systems, databases, messaging and middleware systems, internet and intranet servers, and underlying resources. PATROL consists of the following key components: 5

8 Chapter 1: Overview PATROL Agents PATROL Knowledge Modules PATROL Consoles PATROL Agent configuration utility Figure 1-1 shows how PATROL components relate to SPECTRUM and PATROL Integration components within the network. Figure 1-1: PATROL Integration Components and PATROL SPECTRUM SpectroGRAPH PATROL Integration PATROL (Operator or Developer) Console IH for PATROL PATROL Integration SpectroSERVER DCM PATROL Agent TCP/IP+UDP Configuration File config.pet PETEPI PATROL API TCP/IP +UDP PATROL Knowledge Modules Configuration Files Event Repository For additional information about using the PATROL components, consult the PATROL documentation. PATROL Event Translator for SPECTRUM external protocol interface The PATROL Event Translator for SPECTRUM External Protocol Interface (PETEPI) is a process that receives PATROL events and translates them to a format that SPECTRUM can interpret. For SPECTRUM, the PETEPI translates the PATROL events into SPECTRUM events and alarms. The PETEPI can run on either the SPECTRUM server host, where PATROL Integration for SPECTRUM is installed, or on a different host. If you install on a different host, it must have same OS platform as the host on which PATROL Integration is installed. You can install PETEPIs on multiple hosts, but only one PETEPI can be installed per host. Additionally, when installing PETEPIs on multiple hosts it is recommended that each PETEPI runs a separate port to ensure receipt of all events. 6 SPECTRUM PATROL Integration Administrator GuideF

9 PATROL Integration components The PETEPI establishes connections with each PATROL Agent specified in the PATROL Integration configuration file. Once PATROL Agents are connected, the alarms and other events occurring on each managed host are forwarded to the PETEPI. The PETEPI filters events from each connected host based on values specified in the configuration file, translates the events, and passes the information to SPECTRUM. You can configure the PETEPI to filter out a different set of event types from each host on which PATROL Agents are running. PATROL Integration Configuration Utility You can use the PATROL Integration configuration utility as a graphical user interface tool to define various configuration and initialization values required by the PETEPI. For example, you can configure the following settings: Which hosts PATROL Integration will manage The TCP port number of the PATROL Agent on each managed host The user name and password for each PATROL Agent Which events you want to process Attributes of diagnostic messages Attributes of connections between the PETEPI and PATROL Agents PATROL Integration configuration file Configuration settings are stored by default in the PATROL Integration configuration file (config.pet). You can create several custom settings and save them with different file names. Configuration files can then be used for a variety of purposes, such as monitoring different sets of hosts, filtering a variety of event types, and more. Only one configuration file can be used at a time. For further details, see Saving and using configuration settings on page 58 PATROL model types in SPECTRUM Table 1-1 identifies the PATROL Integration model types supported in SPECTRUM: Table 1-1: PATROL Integration model types Model Type Name PatrolPET PatrolHost PATROL Application Class PATROL Application Instance PatrolGraph Description The PatrolPET model type. The PatrolHost model type. The PATROL Application Class model type. The PATROL Application Instance model type. The PatrolGraph model type. SPECTRUM PATROL Integration Administrator Guide 7

10 Chapter 1: Overview Model types are visually represented by icons in the SpectroGRAPH. For more information on these icons, see SPECTRUM Icon Reference Guide (2518). How PATROL Integration works PATROL Integration is tightly integrated into SPECTRUM The PETEPI connects the SpectroSERVER to multiple PATROL Agents and operates as follows: When the PETEPI starts, it uses the PATROL Application Program Interface (API) to initiate communication with Patrol Agents that have been added to the config.pet file. The PETEPI then waits for PATROL Agent information from the PATROL API. Port is the default TCP port used by the PETEPI and the SpectroSERVER to send and receive messages. You create a PatrolPET model in a SPECTRUM Universe View of the primary SpectroGRAPH landscape. The network address and the agent address specify the PETEPI with which the SpectroSERVER communicates. The SpectroSERVER sends messages to and receives messages from the PETEPI, interprets the received information, creates and manages PATROL models and alarms. PATROL objects and information are displayed in the SpectroGRAPH through different views and utilities. Figure 1-2 shows how PATROL Integration fits into the SPECTRUM environment. 8 SPECTRUM PATROL Integration Administrator GuideF

11 How PATROL Integration works Figure 1-2: PATROL Integration and SPECTRUM Architecture SpectroSERVER PATROL Integration SpectroGRAPH DCM EPI messages through default port optional PATROL Console PATROL Integration configuration utility (petconf) PETEPI PATROL API PATROL Integration configuration file (config.pet) PATROL information API PATROL Agent PATROL Knowledge Modules PATROL Managed Node SPECTRUM PATROL Integration Administrator Guide 9

12 Chapter 1: Overview PATROL Integration features PATROL Integration uses the following features as it interfaces between PATROL and SPECTRUM: communicates with and monitors the PATROL Agent receives events from the PATROL Agent and, based on filtering criteria specified in the config.pet file, filters out unwanted events and translates and forwards the remaining events to the SpectroSERVER automatically discovers PATROL objects and relates them to SPECTRUM models provides views for displaying PATROL information from the SpectroGRAPH Monitoring of PATROL Agent resources The PETEPI handles the transmission and reception of messages to and from the PATROL API and the SpectroSERVER as follows: When the PETEPI receives a response from a new PATROL Agent, it sends a message to the SpectroSERVER, which, in turn, creates a PatrolHost model. The PatrolHost model is saved in the SPECTRUM database and displays in the SpectroGRAPH PatrolHost icon view as a PET model. When a PATROL application is discovered by the PETEPI and the application data is forwarded to the SpectroSERVER through the PETEPI, PatrolAppClass models are created, saved to the SPECTRUM database, and displayed in the SpectroGRAPH application class icon view as a PATROL Host model. When a PATROL application instance is discovered by the PETEPI and the application instance data is forwarded to the SpectroSERVER, PatrolAppInst models are created, are saved in the SPECTRUM database, and are displayed in the SpectroGRAPH application instance view. PATROL parameters are attached to an application instance as SPECTRUM model attributes and are displayed in the SpectroGRAPH Model Information view of PatrolAppInst models. The PETEPI is configured to receive PATROL events from PATROL Agents. The PETEPI will translate these events to SPECTRUM EPI messages and forward them to the SpectroSERVER. PATROL Integration configures SPECTRUM to interpret these messages and display the messages in either the Event Log or the Enterprise Alarm Manager, depending on the event severity. Propagation of alarms and events The PETEPI is configured to send messages each time a PATROL-monitored object changes state. PATROL Integration inference handlers embedded in the SpectroSERVER interpret these messages. They then process events and generate alarms appropriately. For more information, see the Event Configuration Files Guide. Event and alarm handling Both the SpectroSERVER and the SpectroGRAPH use PATROL Integration supporting files to help display PATROL events and alarms within the Enterprise Alarm Manager. SPECTRUM APIs are used to forward PATROL events to the SPECTRUM environment. PATROL events forwarded to the 10 SPECTRUM PATROL Integration Administrator GuideF

13 PATROL Integration features SpectroSERVER by the PETEPI are used to generate SPECTRUM events and SPECTRUM alarms through the EventDisp file and the inference handlers. The SpectroGRAPH then uses the supporting file CsEvFormat to construct a full event text message. Probable cause files, called CsPCause, are mapped with the alarms by the Enterprise Alarm Manager. The event catalogs within PATROL have been translated into SPECTRUM event format files that provide all of the PATROL Knowledge Module (KM) knowledge that has been built into PATROL products. A PATROL KM contains definitions of each possible event that can be generated within the PATROL environment. The alarm handling process in SPECTRUM for PATROL events and alarms is displayed in Figure 1-3. Figure 1-3: PATROL Integration Event and Alarm Handling Supporting Files EventDisp CsEvFormat CsPCause inference handler PATROL model types SpectroSERV Alarm Event Info event code message alarm code probable PATROL event message SpectroGRAPH PETEPI PATROL model icon PATROL model alarm PATROL API PATROL Agent Information views SPECTRUM provides a collection of models that can display information about devices on the network. PATROL Integration provides several information views which are added to the SpectroGRAPH during the PATROL Integration installation that you can use to display PATROL Agent information from within the SpectroGRAPH. These views display general PATROL Agent information basic model information information about monitored application classes information about monitored application instances information about monitored application instance parameters SPECTRUM PATROL Integration Administrator Guide 11

14 Chapter 1: Overview parameter graphs How management and physical faults are isolated In the fault isolation process of PATROL Integration for SPECTRUM, fault isolation inference handlers act on behalf of the PatrolHost and PatrolPET models. The fault isolation process starts whenever a poll from the SpectroSERVER to a PatrolPET or PatrolHost device fails. When the poll fails, the inference handlers on behalf of the corresponding PatrolPET or PatrolHost model begin to poll and ping the model or its neighbors to determine the source of the management- or physicallevel fault. Models that are physically connected to each other are said to be neighbors. The SpectroSERVER routinely polls the PatrolHost and PatrolPET devices to check their responses. For example, if no response to the poll is received from a PatrolHost device, fault isolation inference handlers are initiated on behalf of the PatrolHost model. They poll the PatrolPET model to see if the PETEPI is up or down. Whether the PETEPI is up or down, the inference handlers start pinging the PatrolHost and the PatrolPET devices, as well as any network devices to which they are connected, to determine if there is physical connectivity. If a PatrolHost device fails to respond to the ping, the inference handlers are initiated on behalf of its model. They check the status of the neighboring models connected to the PatrolHost model. If any of the neighboring models are up, then the inference handlers determine that the PatrolHost device is at fault. The PatrolHost model displays a red alarm, indicating a physical fault. In this example, the contact between the PETEPI process and the PATROL Agent is disrupted because of a physical failure in the PatrolHost device. Strictly speaking, no management fault has occurred. Physical faults are always given precedence over management faults. If a PatrolHost or PatrolPET device is experiencing both management and physical faults, then its model displays a red alarm. Example of fault isolation determining physical fault Figure 1-4 depicts a simple network diagram. The SpectroSERVER and PETEPI processes are running on the same workstation. The workstation is connected to a device in the network cloud. The device in the network cloud is connected to a hub. Connected to the hub is a PATROL host computer running a PATROL Agent. 12 SPECTRUM PATROL Integration Administrator GuideF

15 How management and physical faults are isolated Figure 1-4: Fault Isolation and Physical Connectivity In this example, the SpectroSERVER loses contact with the network device, the hub. Because the PATROL host computer relies on the network device for its physical connection, it also loses contact to the SpectroSERVER. Fault determination is based in part on the proximity, in terms of the networking path, between the device in question and the device running the SpectroSERVER. All devices that are monitored by the SpectroSERVER are considered downstream to the SpectroSERVER workstation. The terms upstream and downstream are used to describe the location of models in relation to each other and to the SpectroSERVER workstation. The physical fault isolation process starts when a device fails to respond to a poll from the SpectroSERVER. After the fault isolation inference handlers complete the polling of the PETEPI on the PatrolPET model, they start to ping the neighboring devices. If they find that all the neighbors are down, they determine that the device is not at fault. If they find that any neighbors are up, they determine that the device is the source of the outage and is at fault. The inference handlers on behalf of models downstream of the at-fault device ping the neighboring models and find that all the neighbors are down. The inference handlers determine that their models are not at fault. The models turn gray in the SpectroGRAPH. The inference handlers on behalf of the at-fault model ping its neighboring models. They find that an upstream neighbor is up. The inference handlers assume that their model is at fault. The at- SPECTRUM PATROL Integration Administrator Guide 13

16 Chapter 1: Overview fault model goes into alarm and turns red in the SpectroGRAPH. Models that are upstream of the device at fault remain their original color in the SpectroGRAPH. In the example depicted in Figure 1-4, the hub, which is closer to the SpectroSERVER, is upstream of its neighbor, the PatrolHost device. The PatrolHost device is downstream of its neighbor, the hub. If a poll from the SpectroSERVER to the PatrolHost device fails first, then the fault isolation inference handlers on behalf of the PatrolHost device poll the PETEPI. When they find that the PETEPI is up, they try to ping the PatrolHost model s neighbor, the hub. Because the hub is down, the ping fails. The inference handlers determine that the PatrolHost device is not at fault. The PatrolHost model turns gray in the SpectroGRAPH. When the alarm condition of a model turns gray, all of its alarms are suppressed. The fault isolation inference handlers are triggered on behalf of the hub model. They try to ping its neighbor, the network device located upstream in the network cloud. This attempt succeeds. The inference handlers determine the hub to be the source of the outage. The hub model turns red in the SpectroGRAPH. 14 SPECTRUM PATROL Integration Administrator GuideF

17 How management and physical faults are isolated Example of fault isolation in management-level connectivity In PATROL Integration for SPECTRUM, management-level connectivity involves a proxy relationship. The PETEPI acts as an intermediary between the PATROL Agent and the SpectroSERVER. The PETEPI enables the SpectroSERVER to manage and monitor PATROL objects. Figure 1-5: Proxy Relationship Effecting Fault Isolation Behavior 1 SNMP SpectroSERVER Process Router 2 EPI/API Goal: To have the PETEPI proxy manage the PATROL Hosts on the other side of a firewall: 3 PSL PETEPI Process 1. SpectroSERVER uses SNMP to directly communicate with managed devices within the firewall. 2. SpectroSERVER uses EPI/ API to communicate with PETEPI process. (Note that the PETEPI process can be installed on the SpectroSERVER machine or a remote machine.) Network PATROL Host PATROL Agent 3. PETEPI uses PSL (Patrol Script Language) to communicate with PATROL Hosts. Failure of PETEPI or PATROL Agent - Management-level connection fault The failure of the PETEPI process or the PATROL Agent process is an example of a managementlevel connection fault. Figure 1-6 on page -16 depicts an example in which the PETEPI process, installed on the SpectroSERVER workstation, fails. The PatrolHost model is downstream of the workstation where the SpectroSERVER and PETEPI processes are running. SPECTRUM PATROL Integration Administrator Guide 15

18 Chapter 1: Overview Figure 1-6: Fault Isolation in Logical Connectivity When the PatrolHost device fails to respond to a poll from the SpectroSERVER, its fault isolation inference handlers attempt to poll its proxy, the PETEPI represented by the PatrolPET model. When the attempt by the PatrolHost model to poll its proxy fails, the inference handlers triggered on behalf of the PatrolPET model have nothing else to evaluate. In SPECTRUM topology, the PatrolPET model does not have neighbors. Both the PatrolHost and PatrolPET devices respond to pings, so physical fault is not determined. The PatrolPET model icon turns orange in the SpectroGRAPH, indicating a management fault. The icon representing the PatrolHost model turns gray. Gray indicates that the device has lost contact with the SpectroSERVER (the PETEPI acts as the proxy) but is not at fault. Its alarms are suppressed. 16 SPECTRUM PATROL Integration Administrator GuideF

19 How management and physical faults are isolated Fault isolation scenarios Table 1-2 shows a sampling of fault isolation cases that are possible in PATROL Integration for SPECTRUM. Table 1-2: Matrix of Possible Fault Isolation Cases Case PETEPI PETEPI Computer PATROL Agent PATROL Agent Computer Network Patrol- PET Model Patrol- Host Model 1 Up Up Up Up Up Green Green 2 Up Up Up Up Down Green Gray 3 Up Up Down 1 Down Up Green Red 4 Up Up Down Up Up Green Orange 5 Down 1 Down 2 Up Up Up Red Gray 6 Down Up Up Up Up Orange Gray 7 Up Up 2 Up Up Down Red Gray 8 Down Up Down Down Up Orange Red 1 In these cases, the PATROL Agent and the PETEPI process are down because the computers on which they are running are down. 2 In these cases, the PETEPI and the SpectroSERVER are running on different computers. Figure 1-7 depicts a network context that can represent cases 1, 2, 3, 4, 6, and 8, in which the PETEPI and the SpectroSERVER are running on the same workstation. SPECTRUM PATROL Integration Administrator Guide 17

20 Chapter 1: Overview Figure 1-7: PETEPI and SpectroSERVER on Same Workstation Figure 1-8 depicts a context that can represent cases 5 and 7, in which the PETEPI process and the SpectroSERVER are running on different workstations. 18 SPECTRUM PATROL Integration Administrator GuideF

21 How management and physical faults are isolated Figure 1-8: PETEPI and SpectroSERVER on Different Workstations Table 1-3 highlights some of the key points of each case scenario. Table 1-3: Case Descriptions of Fault Scenarios Case Description 1 indicates normal functioning 2 a physical fault A network device connecting the SpectroSERVER workstation with the downstream PatrolHost device has failed. The model icon representing the network device would flash red. The PatrolPET model, residing on the SpectroSERVER workstation, is upstream of the at-fault device, so it is unaffected and remains green. The PatrolHost computer is downstream of the at-fault network device, so it loses contact with the SpectroSERVER. However, it is not at fault. Its alarm condition is gray, and all alarms are suppressed on the model. SPECTRUM PATROL Integration Administrator Guide 19

22 Chapter 1: Overview Table 1-3: Case Descriptions of Fault Scenarios Case Description 3 a physical fault The SpectroSERVER has lost its connection with the PatrolHost computer running the PATROL Agent. When the PatrolHost device fails to respond to a poll, the PatrolHost model s fault isolation inference handlers are triggered. They are able to contact the proxy, the PETEPI represented by the PatrolPET model. When the PatrolHost device fails to respond to a ping, the inference handlers of the PatrolHost model are triggered and evaluate all of the neighbors of the PatrolHost model. They find that the neighbors of the PatrolHost model are up, and they determine that the PatrolHost model is at fault. Its alarm condition turns red. The PatrolPET model icon remains green. 4 a management fault The PATROL Agent process on the PatrolHost computer has failed. When the PatrolHost device fails to respond to a poll from the SpectroSERVER, the PatrolHost model s inference handlers are triggered. They are able to contact the proxy, the PETEPI represented by the PatrolPET model. The PatrolHost device responds to the ping from the SpectroSERVER, so physical fault isolation is not triggered. The fault isolation inference handlers determine that the PATROL Agent is down. The alarm condition on the PatrolHost model turns orange. The PatrolPET model icon remains green. 5 a physical fault The workstation on which the PETEPI runs has failed. (The SpectroSERVER is running on a different workstation. See Figure 1-8.) When the PatrolHost device fails to respond to a poll from the SpectroSERVER, the PatrolHost model s fault isolation inference handlers are triggered. They are not able to contact the proxy because the workstation on which the PETEPI resides is down. NOTE: Whenever the PETEPI is down, the PATROL Agents that the PETEPI is monitoring cannot respond to a poll from the SpectroSERVER. When the PatrolHost device fails to respond to a ping, the inference handlers of the PatrolHost model are triggered and evaluate all of its neighbors. They eventually find that the PETEPI workstation is down. The fault isolation inference handlers on the PatrolPET model have no neighbors to check. They determine that the PETEPI device is at fault. The PatrolPET model turns red in the SpectroGRAPH. The SpectroSERVER has lost contact with the PatrolHost device downstream of the PETEPI device. The PatrolHost device is not at fault. In the SpectroGRAPH, the PatrolHost model turns gray, and all alarms are suppressed on the model. 20 SPECTRUM PATROL Integration Administrator GuideF

23 How management and physical faults are isolated Table 1-3: Case Descriptions of Fault Scenarios Case Description 6 a management fault The PETEPI process, running on the same workstation as the SpectroSERVER, has failed. When the PatrolHost device fails to respond to a poll, the PatrolHost model s fault isolation inference handlers are triggered. They are not able to contact the proxy because the PETEPI process is down. NOTE: Whenever the PETEPI is down, the PATROL Agents that the PETEPI is monitoring cannot respond to a poll from the SpectroSERVER. The PatrolHost and PETEPI devices successfully respond to pings, so physical fault isolation is not triggered. The fault isolation inference handlers on the PatrolPET model have no neighbors to contact. The inference handlers determine that the PETEPI process on the PatrolPET device is at fault. In the SpectroGRAPH, the alarm condition on the PatrolPET model turns orange. The PATROL Agent on the PatrolHost computer has lost contact with the PETEPI. However, the PatrolHost device is not at fault. In the SpectroGRAPH, the PatrolHost model turns gray, and all alarms are suppressed on the model. SPECTRUM PATROL Integration Administrator Guide 21

24 Chapter 1: Overview Table 1-3: Case Descriptions of Fault Scenarios Case Description 7 a physical fault A network device connecting the SpectroSERVER workstation with the downstream PatrolPET and PatrolHost devices has failed. (Unlike case 2, the PETEPI resides a separate workstation from that of the SpectroSERVER. See Figure 1-8 on page -19.) The SpectroSERVER loses contact with both the PatrolPET and PatrolHost devices. When the PatrolHost device fails to respond to a poll from the SpectroSERVER, the PatrolHost model s fault isolation inference handlers are triggered. They are able to contact the proxy because the PETEPI process and device are running. When the PatrolHost device fails to respond to a ping, the inference handlers of the PatrolHost model are triggered and evaluate all of the neighbors of the PatrolHost model. They eventually find the PETEPI workstation. The inference handlers on the PatrolPET model where the PETEPI resides have no neighbors to evaluate. Its inference handlers assume that the PatrolPET model is at fault. In the SpectroGRAPH, the PatrolPET model turns red. In the SpectroGRAPH, the model icon representing the failed network device turns red also. The SpectroSERVER has lost contact with the PatrolHost device. However, it is not at fault. In the SpectroGRAPH, the PatrolHost model turns gray, and all alarms are suppressed. 8 physical and management faults The PETEPI process is down, the PATROL Agent process is down, and the PatrolHost device running the PATROL Agent also is down. When the PatrolHost device fails to respond to a poll, the PatrolHost model s fault isolation inference handlers are triggered. They are not able to contact the proxy because the PETEPI process is down. The PatrolPET device successfully responds to pings, so physical fault isolation is not triggered on behalf of the PatrolPET model. A management fault is asserted. In the SpectroGRAPH, the color of the PatrolPET model turns orange. When the PatrolHost device fails to respond to a ping, the inference handlers of the PatrolHost model are triggered and evaluate all of the neighbors of the PatrolHost model, including the PatrolPET model. They find that the neighbors of the PatrolHost model are up, and they determine that the PatrolHost model is at fault. In the SpectroGRAPH, the PatrolHost model turns red. The PATROL Agent process has lost contact with the SpectroSERVER because the PETEPI process is down. The PATROL Agent process is also down. However, the PatrolHost device running the PATROL Agent is also down. In this case, the physical fault (the down PatrolHost device) is asserted over the management fault (the down PATROL Agent process). 22 SPECTRUM PATROL Integration Administrator GuideF

25 Chapter 2: PATROL Integration Configuration This chapter discusses how to configure PATROL Integration with SPECTRUM. It includes information about the following configuration tasks: Prerequisites on page 23 Using the PATROL Integration Configuration Utility on page 24 Modifying host attributes on page 31 Removing hosts from the configuration on page 33 Setting the PATROL Alarm Filter on page 34 Setting connection attributes on page 36 Setting the connection tolerance values on page 38 Setting attributes for diagnostic output messages on page 40 Managing pet.log files on page 44 Setting PET Autodiscovery attributes and adding autodiscovered hosts on page 46 Setting server port, local port, and communications save time on page 50 Customizing PATROL event messages on page 52 Saving and using configuration settings on page 58 Prerequisites The following prerequisites should be met prior to configuring PATROL Integration with SPECTRUM. You must have PATROL Agent installed on each host that you want PATROL Integration to monitor. For further details, see the PATROL installation guide. You must have SPECTRUM installed with the PATROL Integration option (option provided in SPECTRUM installation program). For more information, see the SPECTRUM installation guide. 23

26 Chapter 2: PATROL Integration Configuration Note. If you want to install PETEPI on multiple hosts, you will need to copy the PETEPI files from the SPECTUM machine to the designated host machines. We recommend that you consult SPECTRUM Technical Assistance Center for additional assistance. Using the PATROL Integration Configuration Utility Use the PATROL Integration configuration utility to configure PATROL Integration to fit your environment. With this utility, you specify the hosts you want to manage, set attributes for connections between PATROL Integration and PATROL Agents, set attributes for internal diagnostic messages, and specify other settings that are required for PATROL Integration integrations. These settings are called PET-specific because they are used by the PATROL Event Translator for SPECTRUM EPI (PETEPI), a core component of PATROL Integration that establishes and maintains communication with PATROL Agents. BMC Software recommends that you use the PATROL Integration configuration utility to edit the configuration file. Do not use a text editor. Table 2-1 lists the tasks you can perform using the PATROL Integration configuration utility. Table 2-1: PATROL Integration Configuration Utility Tasks Task Optional or Required If you do not perform the optional tasks in Table 2-1 on page 24, the PETEPI uses the default configuration settings for those tasks. Page Start the PATROL Integration configuration utility. Required page 26 Specify which hosts you want to manage. Required page 27 Modify a managed host s identification attributes. Optional page 31 Remove a host from the list of managed hosts. Optional page 33 Set the PATROL alarm filter. Optional page 34 Set connection attributes between PATROL Agents and the PETEPI. Optional page 36 Set the connection tolerance values. Optional page 38 Set attributes for diagnostic output messages. Optional page 40 Manage pet.log files. Optional page 44 Set PET autodiscovery attributes and add autodiscovered hosts. Optional page 46 Set server port, local port, and communication save time. Optional page 50 Customize event messages. Optional page 52 Preventing PATROL events Optional page 55 Preventing SPECTRUM from recreating application instances Optional page 57 Save and use the configuration settings. Required page 58 Note: By default, PATROL Integration is not configured to output debugger messages. If you have trouble using PATROL Integration, set the diagnostic output attributes to output debugger messages (see Setting attributes for diagnostic output messages on page 40). 24 SPECTRUM PATROL Integration Administrator Guide

27 Using the PATROL Integration Configuration Utility PATROL Integration configuration file (config.pet) The PATROL Integration product is shipped with two default configuration files: config.pet and config.pet.sample. These two files are exactly the same and are installed in the PATROL Integration installation directory during the installation process. However, during installation, if a config.pet file already exists, it is not overwritten with the default file. Remember to use the PATROL Integration configuration utility to edit the configuration file. Do not use a text editor. Changing run-time configuration settings If you use the PATROL Integration configuration utility to change settings while the PATROL Integration server (PETEPI) is running, you must restart the PATROL Integration server for the changes to take effect. See the following topics for more information on starting and stopping the PETEPI: To start the PATROL Integration Configuration Utility on a Unix platform on page 26 To Start the PATROL Integration Configuration Utility on a Microsoft Windows Platform on page 27 Sample configuration file Figure 2-1 shows a sample configuration file, config.pet, as it appears after it has been modified. The unaltered file is installed in the PATROL Integration installation directory. The config.pet.sample file is the same as the unaltered config.pet file and should not be altered. Figure 2-1: Sample Configuration File The Unix and Microsoft Windows versions of the configuration file differ slightly. You should not attempt to use a Microsoft Windows configuration file on a Unix workstation or a Unix configuration SPECTRUM PATROL Integration Administrator Guide 25

28 Chapter 2: PATROL Integration Configuration file on a Windows workstation. The Microsoft Windows version has a different default path name specified for the PET_LOGFILE. Also, if the Microsoft Windows version is opened in a text editor (not recommended), control characters are added to the text that are not supported in Unix. Starting the PATROL Integration Configuration Utility In this task, you will start the PATROL Integration configuration utility. The PATROL Integration configuration utility is used to configure PATROL Integration to fit your environment. Under Unix, you can also start the PATROL Integration configuration utility from the SpectroGRAPH (see Starting the PATROL Integration Configuration Utility on page 26). Before you begin Ensure that you have met the following conditions: PATROL Integration must be installed. You have the proper write permission if you intend to change the configuration file. To start the PATROL Integration Configuration Utility on a Unix platform 1. Navigate to: <$SPECROOT>/SS/PETEPI 2. Type the following command at the Unix command line:./petconf config_file 3. Press Enter. The PATROL Integration configuration utility main window is displayed, as shown in Figure 2-2. Figure 2-2: PATROL Integration Configuration Utility Window 26 SPECTRUM PATROL Integration Administrator Guide

29 Using the PATROL Integration Configuration Utility To Start the PATROL Integration Configuration Utility on a Microsoft Windows Platform From the Windows toolbar, choose Start => Programs => PATROL Integration 2.3 for SPECTRUM => Configuration Utility for PATROL Integration. The PATROL Integration configuration utility main window appears. Table 2-2 explains the menu commands that you can access from the PATROL Integration configuration utility. Table 2-2: Configuration Utility Menu Commands Menu File Edit Command Descriptions Use this menu to open and save configuration settings. Use the Host Configuration command on this menu to add, modify, and delete PATROL Integration-managed hosts. The Integration Module command enables you to enter the keywords ALARM_FILTER, PET_AGENT_DISCONNECT_RETRIES, PET_SUSTAIN_CONNECT_DURATION, and PET_MAX_LOGFILES. Use the Event Translation command on this menu to customize PATROL event message text that will be displayed in the event tab of the Enterprise Alarm Manager. Options Use the Connection Attributes command on this menu to set attributes of communication connections between PATROL Integration and PATROL Agents. The AutoDiscovery command enables you to launch an autodiscovery search of host computers running PATROL Agents on specified ports. You can select and add autodiscovered host computers to the configuration file. Use the Other Attributes command on this menu to set diagnostic output, server port, local port, and communications save time. Where to go from here Once you have started the PATROL Integration configuration utility, you must specify the hosts that you want to manage (see Specifying the hosts that you want to manage on page 27). Specifying the hosts that you want to manage In this task, you will use the PATROL Integration configuration utility to specify the hosts in your enterprise on which PATROL Agents are installed. By doing this, you specify the hosts that you want to manage. You can also specify for each host which event types you want processed Information, State Change, Error, Warning, Alarm, or Response. Variable host names You define the host name in the Host Configuration window for the config.pet file. The PET creates an association between the host name you entered and the name of the agent s host name (the machine name). This feature allows you the flexibility of using: the host name the machine s full domain name SPECTRUM PATROL Integration Administrator Guide 27

30 Chapter 2: PATROL Integration Configuration the IP (Internet Protocol) address Table 2-3 shows examples of various entries made in the configuration utility, which are listed in the Name Defined in config.pet column. It compares them against an Agent host name, and it indicates how each entry will be read by the PET. Table 2-3: Host Name Resolution Agent Host Name Name Defined in config.pet Name Sent to the Integration Module by the PET host name host_name.domain.com host_name host_name.domain.com host_name host_name.domain.com host_name host_name.domain.com host_name host_name.domain.com Event Filter Information In the configuration utility, you can specify or modify the event types of the hosts that you want to manage. The descriptions of event types that follow are guidelines for events defined in the PATROL Knowledge Module (KM). PATROL Integration requires that certain events be specified. These required events are indicated in Table 2-4. Table 2-4: PATROL Event Types Event Type Description Required/Optional Information an event that is logged for informational purposes only Optional State Change Examples of typical information events include the following: A parameter is activated or deactivated. A global parameter is suspended or resumed. Application discovery occurs. an event that is triggered by any change of state that takes place on a resource monitored by PATROL Required Some examples of state changes are The state of an application class or an instance changes from Alarm to OK. A parameter description is changed for a class of objects. The connection status of a computer changes (to Void, for example). 28 SPECTRUM PATROL Integration Administrator Guide

31 Using the PATROL Integration Configuration Utility Table 2-4: PATROL Event Types Event Type Description Required/Optional Error an event that is the result of a failure or an error Optional Warning Alarm Response This event is not generated by the PATROLmonitored object. an event that occurs when a parameter value has exceeded the warning range A warning state may be raised for a parameter, an instance, or an application. an event that occurs when a parameter value has exceeded the alarm range An alarm state may be raised for a parameter, an instance, or an application. an event that is created by the Agent to indicate that some kind of user input is required at the PATROL Console Required Required Optional Before You Begin Ensure that you have met the following conditions: The PATROL Integration configuration utility must be running (see Starting the PATROL Integration Configuration Utility on page 26). You must have a PATROL Agent installed on each host that you want to manage (see the PATROL installation guide for your operating system for further details). You must know the host name, port number, and account user name and password for each PATROL Agent. To specify the hosts that you want to manage 1. Do one of the following: Choose Edit => Host Configuration => Add from the main menu bar. You can right-click in the top pane to open a pop-up window containing Add, Modify, and Delete menu commands. Choose Add. Under Unix, you can also press Ctrl+A to add hosts. The Host Configuration dialog box displays, as shown in Figure 2-3 on page 30. SPECTRUM PATROL Integration Administrator Guide 29

32 Chapter 2: PATROL Integration Configuration Figure 2-3: Host Configuration Dialog Box 2. Type or select the appropriate information for host name, port, user name, and password as described in Table 2-5. Table 2-5: Host Configuration Attributes Attribute Host Name Description specifies the name of a host that you want PATROL Integration to manage There is no default. Port specifies the port number of the PATROL Agent on the specified host The default is User Name specifies the user name for logging on to the PATROL Agent on the specified host There is no default. Password specifies the password for the user name The password is encrypted by the PATROL Integration configuration utility. There is no default. Event Filter specifies the type of events that you want PATROL Integration to process for the particular host By default, all event types are processed. Note: For further details about PATROL event types, see the PATROL user guide for your operating system. 3. Click the appropriate check boxes in the Event Filters pane to select or deselect event filters. You need to specify for each host which event types will be processed. If you do not specify or modify the event types, all event types are processed. For more information about PATROL event types, see the PATROL user guide for your operating system. 30 SPECTRUM PATROL Integration Administrator Guide

33 Modifying host attributes Under Unix, when an event is selected, its check box appears pushed in. When you select an event filter, you choose to receive the event. To filter out an event, make sure that the check box is not selected. 4. Do one of the following to complete the entry: Click OK to add the host name to the list of hosts in the PATROL Integration Configuration Utility window and to close the Host Configuration dialog box. Click Apply to add the host name but to keep the Host Configuration dialog box open with the same record. You can continue to add different host computers using the same information: port number, user name, and password. Modify the event filters if needed. Click OK when you are done. 5. From the PATROL Integration Configuration Utility menu bar, choose File => Save to save the updated configuration file. 6. Stop and restart the PATROL Integration server (PETEPI) to initialize the configuration values. To add hosts through the PET Autodiscovery feature You can also add hosts to the PATROL Integration configuration file through the PET autodiscovery feature. See Setting PET Autodiscovery attributes and adding autodiscovered hosts on page -46 for more information. Where to go from here Once you have specified the hosts that you want to manage, you can perform additional tasks. Task Reference setting connection attributes page 36 saving and using configuration settings page 58 modifying host attributes page 28 removing hosts from the configuration page 33 Modifying host attributes In this task, you will use the PATROL Integration configuration utility to modify the identification attributes and event filter of a managed host. Before you begin Ensure that you have met the following conditions: The PATROL Integration configuration utility must be running (see Starting the PATROL Integration Configuration Utility on page -26). The name of the host whose attributes and event filters you want to modify must already exist in the list of managed hosts (see Specifying the hosts that you want to manage on page -27). SPECTRUM PATROL Integration Administrator Guide 31

34 Chapter 2: PATROL Integration Configuration To modify a host s attributes 1. In the upper section of the utility s main window, select the name of the host that you want to modify. The name of the host is highlighted. 2. Perform one of the following options: From the PATROL Integration Configuration Utility menu bar, choose Edit => Host Configuration => Modify. You can right-click in the top pane to open a pop-up window containing Add, Modify, and Delete menu commands. Choose Modify. The Host Configuration dialog box is displayed. 3. Type or select the appropriate information, as described in Table 2-5, Host Configuration Attributes, on page Click OK. 5. From the PATROL Integration Configuration Utility menu bar, choose File => Save to save the updated configuration file. 6. Stop and restart the PATROL Integration server (PETEPI) to initialize the configuration values. Where to Go from Here Once you have modified host attributes, you can perform additional tasks. Task Reference setting connection attributes page 36 saving and using configuration settings page 58 removing hosts from the configuration page SPECTRUM PATROL Integration Administrator Guide

35 Removing hosts from the configuration Removing hosts from the configuration In this task, you will use the PATROL Integration configuration utility to remove hosts from the list of hosts that PATROL Integration manages. Before you begin Ensure that the PATROL Integration configuration utility is running (see Starting the PATROL Integration Configuration Utility on page -26). To remove a host from the configuration 1. In the upper section of the PATROL Integration configuration utility main window, select the name of the host that you want to remove. The name of the host is highlighted. 2. Perform one of the following options: From the PATROL Integration Configuration Utility menu bar, choose Edit => Host Configuration => Delete. Right-click in the top pane to open a pop-up window containing Add, Modify, and Delete menu commands. Choose Delete. 3. Click OK. The host is deleted from the list of hosts that PATROL Integration manages and no longer is displayed in the list of hosts in the upper section of the PATROL Integration configuration utility main window. 4. From the PATROL Integration Configuration Utility menu bar, choose File => Save to save the updated configuration file. 5. Stop and restart the PATROL Integration server (PETEPI) to initialize the configuration values. See the following topics for more information on starting and stopping the PETEPI: 6. Optional. You can do one or both of the following to check the connection status of the existing PatrolHost model in the SPECTRUM database: Check the PatrolHost View window. The PatrolHost model icons that represent the host computers which were removed from the configuration file are flashing orange. Open the Enterprise Alarm Manager at the PatrolPET view. You may receive an alarm message similar to the following example for each host removed from the configuration file: Device mycomputer.bmc.com of type PatrolHost is no longer responding to primary management requests (e.g. SNMP), but appears to be responsive to other communication protocol (e.g. ICMP). An alarm will be generated. 7. Optional, but recommended. After you remove a host or hosts from the configuration file, you can remove its associated objects and symbols from the SPECTRUM database. Where to Go from Here Once you have removed the hosts that you do not want to manage, you can perform additional tasks. SPECTRUM PATROL Integration Administrator Guide 33

36 Chapter 2: PATROL Integration Configuration Task Reference setting connection attributes page 36 saving and using configuration settings page 58 specifying other hosts that you want to manage page 27 Setting the PATROL Alarm Filter In this task, you define PATROL alarm filters to indicate which PATROL events are not generated as SPECTRUM alarms and hence should not be displayed in the Enterprise Alarm Manager. The standard PATROL alarm and warn events are generated as SPECTRUM alarms and displayed in the Enterprise Alarm Manager. A PATROL alarm is automatically generated in the SPECTRUM Enterprise Alarm Manager when the corresponding PATROL event occurs. It is automatically removed from the Enterprise Alarm Manager when the event state is updated. The PATROL alarm filter allows you to identify the PATROL events that you do not want to be generated as SPECTRUM alarms. The PATROL alarm filter consists of two identifiers: one for the PATROL event catalog; the other for the PATROL event class. When a PATROL event is forwarded to the inference handler, the inference handler determines whether the event has been defined by the alarm filter. If the event has been defined by the alarm filter, the inference handler disasserts the event and does not display it in the Enterprise Alarm Manager. If the event is not defined by the alarm filter, the inference handler asserts the event and displays it in the Enterprise Alarm Manager. Before you begin For background information, you can review Customizing PATROL event messages on page 52 Saving and using configuration settings on page 58 You should be familiar with PATROL event catalogs, event classes, and event message descriptions. See the following PATROL documentation for background information: PATROL Console for Unix User Guide PATROL for Windows 2000 User Guide Volume 2 Monitoring and Managing with PATROL PATROL for Windows 2000 User Guide Volume 3 Customizing PATROL PATROL Agent Reference Manual PATROL Script Language Reference Manual Related keywords In this task you are working with the ALARM_FILTER keyword. 34 SPECTRUM PATROL Integration Administrator Guide

37 Setting the PATROL Alarm Filter To define the Alarm Filter 1. From the PATROL Integration Configuration Utility window, click SPECTRUM displayed under the Module field in the middle panel. The selection becomes highlighted. 2. Perform one of the following options: From the PATROL Integration Configuration Utility menu bar, choose Edit => Integration Module => Edit Keywords. Right-click in the top pane to open a pop-up window containing a list of commands. Choose Edit Keywords. The Integration Module Keywords dialog box is displayed. Figure 2-4: Integration Module Keywords Dialog Box 3. Do one of the following: If the keyword ALARM_FILTER and a corresponding value are already entered in the Integration Module Keywords dialog box, then select the entry so that the keyword is displayed in the Keyword field and the value is displayed in the Value field. If no entries are displayed in the Integration Module Keywords dialog, then enter ALARM_FILTER in the Keyword field. 4. In the Value field, enter the identifiers of the PATROL event catalog and the PATROL event class. Separate the two with a slash (/). Use a semicolon (;) at the end of each event catalog/ event class entry. For example, the following value contains three alarm filter entries: 0/11;0/13;0/EventArchive; You can add multiple alarm filter entries as the value for the ALARM_FILTER keyword. Make sure that you add the semicolon at the end of each entry. BMC Software suggests that you do not enter the alarm filter with the following event catalog and event class combination: 0/9;. Event class 9 enables SPECTRUM to disassert alarms from the Enterprise Alarm Manager. If you filter event class 9, PATROL alarms and warnings will not automatically be removed from the Enterprise Alarm Manager when they change status. 5. Do one of the following tasks: Click Add to add a new ALARM_FILTER keyword and its value. SPECTRUM PATROL Integration Administrator Guide 35

38 Chapter 2: PATROL Integration Configuration Click Modify to update an existing ALARM_FILTER keyword value. Click Delete to remove an ALARM_FILTER keyword and its value. 6. Click Close to shut the dialog box. 7. From the PATROL Integration Configuration Utility menu bar, choose File => Save to save the updated configuration file. 8. Stop and restart the PATROL Integration server (PETEPI) to initialize the configuration values. Setting connection attributes In this task, you will use the PATROL Integration configuration utility to set the connection attributes that the PETEPI uses to communicate with PATROL Agents. You cannot set different connection attributes for different hosts connected to the same PETEPI. Before you begin The PATROL Integration configuration utility must be running (see Starting the PATROL Integration Configuration Utility on page 26). To set connection attributes 1. Choose Options => Connection Attributes from the utility s main menu bar. The Connection Attributes dialog box is displayed, as shown in Figure 2-5. Figure 2-5: Connection Attributes Dialog Box UDP or TCP Valid range = 60 to 1800 seconds Valid range = 3 to 10 retries Valid range = 1 to 180 seconds Valid range = 30 to 1800 seconds Valid range = 0 or greater Valid range = 3 to 30 seconds 1. Type or select the appropriate information, as described in Table 2-6. Table 2-6: Connection Attributes (Sheet 1 of 3) Attribute Connection Protocol Description specifies the transport protocol for PATROL Integration to use to connect to PATROL Agents The valid entries are UDP or TCP. The default is UDP. 36 SPECTRUM PATROL Integration Administrator Guide

39 Setting connection attributes Table 2-6: Connection Attributes (Sheet 2 of 3) Attribute Heartbeat (sec) Description specifies the number of seconds to use for as the interval for checking whether the PATROL Agent is still connected The valid range for the heartbeat value is 60 to 1800 seconds. The default is 300 seconds. Retries (times) specifies the number of times PATROL Integration should retry a request for data from PATROL Agents The valid range is 3 to 10 times. The default is 5 times. Time Out (sec) specifies the number of seconds PATROL Integration should use as the time-out period when attempting to communicate with PATROL Agents The valid range is 1 to 180 seconds. The default is 15 seconds. Note: The Time Out value is important because it is used to control the connection between the PETEPI and the PATROL Agent. If the assigned value is not high enough, no information will be relayed from the PATROL Agent to the PETEPI. Reconnect Interval (sec) specifies the number of seconds to use as the interval at which PATROL Integration should attempt to reconnect to PATROL Agents that are not currently connected but are defined in the config.pet file The valid range is 30 to 1800 seconds. The default is 600 seconds. Retry Agent Count under TCP mode, defines the maximum number of unconnected hosts to be contacted during a retry connection session The amount of time between each iteration is determined by the Retry Agent Interval. The valid range for the Retry Agent Count is 0 or greater. (Entering a 0 disables this feature.) The default value is 1.. SPECTRUM PATROL Integration Administrator Guide 37

40 Chapter 2: PATROL Integration Configuration Table 2-6: Connection Attributes (Sheet 3 of 3) Attribute Retry Agent Interval Description under TCP mode, defines the amount of time in seconds that the PATROL Integration server waits between attempts to connect with the number of hosts specified by the Retry Agent Count This interval is repeated between attempts until the total number of unconnected hosts is processed. The valid range is 3 to 30 seconds, inclusive. The Retry Agent Interval becomes effective only if the Retry Agent Count is entered in the configuration file with a value greater than 0. The default value is Click OK. 3. From the PATROL Integration Configuration Utility menu bar, choose File => Save to save the updated configuration file. 4. Stop and restart the PATROL Integration server (PETEPI) to initialize the configuration values. Where to go from here Once you have set connection attributes, you can perform additional tasks. Task Page setting attributes for diagnostic output messages page 40 saving and using configuration settings page 58 Setting the connection tolerance values In this task, you add two keywords to the configuration file: PET_AGENT_DISCONNECT_RETRIES and PET_SUSTAIN_CONNECT_DURATION. The PET_AGENT_DISCONNECT_RETRIES keyword works in tandem with the PET_SUSTAIN_CONNECT_DURATION keyword. Together, they help the PATROL Integration server to maintain a stable connection with the agents that are running on monitored host computers listed in the configuration file. Their processing is referred to as connection tolerance. Related Keywords PET_AGENT_DISCONNECT_RETRIES PET_SUSTAIN_CONNECT_DURATION To add the PET_AGENT_DISCONNECT_RETRIES AND PET_SUSTAIN_CONNECT_ DURATION keywords You add these keywords from the Integration Module Keywords dialog box. 38 SPECTRUM PATROL Integration Administrator Guide

41 Setting the connection tolerance values 1. Highlight the name of the integration module (SPECTRUM) in the middle pane of the PATROL Integration Configuration Utility window. 2. Perform one of the following options: From the PATROL Integration Configuration Utility menu bar, choose Edit => Integration Module => Edit Keywords. Right-click in the middle pane to open a pop-up window containing a list of commands. Choose Edit Keywords. The Integration Module Keywords dialog box is displayed, as shown in the following figure: These two keywords work in tandem, and they must be entered together. The following table describes these keywords and their values. Attribute PET_AGENT_DISCONNECT_RETRIES Description number of times that the PATROL Integration server tries to reconnect with a PATROL Agent with which it has had a stable connection but has lost contact The stable connection is defined by the PET_SUSTAIN_CONNECT_DURATION value. If the server reconnects with the PATROL Agent before the specified number of retries is reached, then a lost connection alarm is not generated. After the number of retries is reached, a lost connection alarm is generated. The server tries to reconnect based on the normal reconnect interval. The ranges of valid values is 0 to 5, inclusive. The default is 1 retry. If you enter 0, you disable this function. SPECTRUM PATROL Integration Administrator Guide 39

42 Chapter 2: PATROL Integration Configuration Attribute PET_SUSTAIN_CONNECT_DURATION Description defines in seconds a stable connection between the PATROL Integration server and the PATROL Agent If a connection is not maintained for the period of time specified by the Sustain Connect Duration, then it is considered unstable. The server tries to reestablish a connection using the normal reconnect interval process. Valid values are 60 seconds or higher. The default is Enter the PET_AGENT_DISCONNECT_RETRIES in the Keyword field and an appropriate value in the Value field. 4. Click Add. 5. Enter the PET_SUSTAIN_CONNECT_DURATION keyword in the Keyword field and an appropriate value in the Value field. 6. Click Add. Then click Close to shut the dialog box. 7. From the PATROL Integration Configuration Utility menu bar, choose File => Save to save the updated configuration file. 8. Stop and restart the PATROL Integration server (PETEPI) to initialize the configuration values. Setting attributes for diagnostic output messages In this task, you will specify what type of diagnostic messages you want to generate and where you want to send them. Diagnostic messages describe the results of monitoring the state of PATROL Integration. Output includes debugging, information, warning, and error messages. The message output can be sent to stderr stdout the log file the log file and stderr the log file and stdout Before you begin The PATROL Integration configuration utility must be running (see Starting the PATROL Integration Configuration Utility on page -26). To set attributes for diagnostic output messages 1. Choose Options => Other Attributes from the main menu bar. The Other Attributes dialog box is displayed, as shown in the following figure: 40 SPECTRUM PATROL Integration Administrator Guide

43 Setting attributes for diagnostic output messages Diagnostic Output section Unix path name 2. In the Diagnostic Output section, type or select the appropriate information, as described in the following table: Table 2-7: Attributes for Diagnostic Output Messages Attribute Message Output Description specifies where diagnostic messages are sent The default value is Log and Stdout. The following values are valid. Value Description Log File OnlySend output to the log file only stderr OnlySend output to stderr only Stdout OnlySend output to stdout only Log and StderrSend output to the log file and to stderr Log and StdoutSend output to the log file and to stdout None Turn off all message output SPECTRUM PATROL Integration Administrator Guide 41

44 Chapter 2: PATROL Integration Configuration Table 2-7: Attributes for Diagnostic Output Messages Attribute Message Level Description specifies which type of diagnostic messages you want to send. The default is Warning. The following values are valid. ValueDescriptionLevel Debug Debugger messageshighest Info Information messages Warning Warning messages ErrorError messages Lowest Note: Levels are listed in highest to lowest order. PATROL Integration sends only the messages with a level equal to or less than the selected level. Setting this option to a high level during normal runtime may cause some performance degradation. Log File specifies the path and file name of the file in which to write diagnostic messages Each time that you start the PETEPI server, a new log file is generated. This option is available only if Message Output is set to send output to the log file: Log File Only, Log and Stderr, or Log and Stdout. Under Unix, the default path name is /tmp/pet.log. Under Microsoft Windows, the product is shipped with the path name C:\Temp\pet.log. Under Unix and Microsoft Windows, you can specify the file name and directory location of the log file. Under Microsoft Windows, you must specify a drive letter and a directory path (drive letter:\directory\file name) if you change the default path name. 3. Click OK. 4. From the PATROL Integration Configuration Utility menu bar, choose File => Save to save the updated configuration file. 5. Stop and restart the PATROL Integration server (PETEPI) to initialize the configuration values. Where to Go from Here Once you have set the attributes for diagnostic output messages, you can perform additional tasks. 42 SPECTRUM PATROL Integration Administrator Guide

45 Setting attributes for diagnostic output messages Task setting server port, local port, and communication save time Page page 50 saving and using configuration settings page 58 SPECTRUM PATROL Integration Administrator Guide 43

46 Chapter 2: PATROL Integration Configuration Managing pet.log files In this task, you can specify the size and number of log files (the default pet.log) to be generated by the PATROL Integration server. By specifying the number of log files to generate, you have the flexibility to create one log file without a size restriction an infinite number of log files with a 2-MB restriction per file a specified maximum number of log files with a 2-MB restriction per file By default, the pet.log file is saved to the /tmp directory (Unix) or the C:\Temp (Microsoft Windows). How pet.log Files Change Date Stamps The pet.log file will change date stamps when the PATROL Integration server is restarted on a new day Each time that the PATROL Integration server is started, a new pet.log file is generated. the current pet.log file, which has a preceding day s date stamp, exceeds the 2-MB maximum on a new day If the current pet.log does not exceed the 2-MB maximum and does not carry today s date stamp in its file name, you can open the current pet.log file and view today s event messages in its text. A date change is always recorded in the text of the pet.log file. To specify the number of log files You enter and update the PET_MAX_LOGFILES keyword from the Integration Module Keywords dialog box. 1. Highlight the name of the integration module (SPECTRUM) in the middle pane of the PATROL Integration Configuration Utility window. 2. Perform one of the following options: From the PATROL Integration Configuration Utility menu bar, choose Edit => Integration Module => Edit Keywords. Right-click in the middle pane to open a pop-up window containing a list of commands. Choose Edit Keywords. The Integration Module Keywords dialog box is displayed, as shown in Figure SPECTRUM PATROL Integration Administrator Guide

47 Managing pet.log files Figure 2-6: Integration Module Keywords Dialog Box 3. Do one of the following: If the PET_MAX_LOGFILES keyword is displayed in the list, then highlight it so that it displays in the Keyword field. If the PET_MAX_LOGFILES keyword is not already displayed, then type PET_MAX_LOGFILES in the Keyword field. 4. Enter the log file parameter in the Value field. Decide from among the following options: 0 Zero indicates that no restriction is placed on the number of log files that are generated. A time stamp suffix is appended to each log file. The time stamp suffix takes the form YYMMDD_HHMMSS, where HHMMSS represents military time. For example, with zero as the value, the log files would be written as follows: pet.log _ (11/02/2000 at 3:20 P.M.) pet.log _ (11/02/2000 at 5.33 P.M.) pet.log _ (11/02/2000 at 11:06 P.M.) pet.log _ (11/03/2000 at 4:15 A.M.)... Each log file has a maximum size limit of 2 MB. After a file reaches the 2-MB maximum, another log file is created. These log files are not cycled. Because no restriction is placed on the number of log files and each log file can reach 2 MB in size, you must be mindful of the amount of available disk space. You should periodically remove older log files from the disk drive. 1 indicates that only one log file is generated during a PATROL Integration server session that is, between server startup and server stop. This file does not have a maximum size limit, and the file name does not have a suffix. The file size can become very large depending on the amount of event activity and the duration of the server session. positive integer greater than one SPECTRUM PATROL Integration Administrator Guide 45

48 Chapter 2: PATROL Integration Configuration This integer indicates the maximum number of log files that are generated. The log files are cycled in ascending order. The.1 file is the current log file. After the.1 file reaches the 2-MB limit, a new.1 log file is generated. The previous.1 log file then becomes.2, the.2 becomes.3, and so forth. When the specified maximum number of log files is exceeded, the oldest log file is deleted automatically. For example, suppose five log files are specified as the maximum, which is the default value. When a sixth log file is generated, the existing.5 file is deleted, and the current.4 log file becomes the.5 file. When the pet.log file changes its date stamp or when the PATROL Integration server is restarted, the counter (the.n or the.1,.2,.3, and so forth of the file name suffix) is reset to Click Add. Then click Close to shut the dialog box. 6. From the PATROL Integration Configuration Utility menu bar, choose File => Save to save the updated configuration file. 7. Stop and restart the PATROL Integration server (PETEPI) to initialize the configuration values. Setting PET Autodiscovery attributes and adding autodiscovered hosts In this task, you will specify the port range, host computer, and subnet that the PATROL Integration server uses to search for host computers that are running PATROL Agents. You also learn how to select and add autodiscovered host computers to the configuration file. Differences between PET autodiscovery and SPECTRUM autodiscovery PET autodiscovery is distinct from SPECTRUM autodiscovery. PET autodiscovery is a PATROL Integration configuration feature that enables the PETEPI to discover host computers that are running PATROL Agents in a specified subnet. Figure 2-7: PETEPI Autodiscovery PETEPI Autodiscovery discovers the PATROL Hosts Hosts PATROL Host running Agent Software SPECTRUM Management Station running PETEPI Process SPECTRUM autodiscovery discovers and finds connections in the larger network environment, as well as, discovers the connections between a PATROL Host and a monitored device as shown in Figure SPECTRUM PATROL Integration Administrator Guide

49 Setting PET Autodiscovery attributes and adding autodiscovered hosts Figure 2-8: SPECTRUM Autodiscovery SPECTRUM Autodiscovery discovers the connections between a PATROL Host and monitored devices. Connections Device PATROL Host Related keywords In this task you are defining the following configuration file keywords: PET_DISCOVERY_USERNAME PET_DISCOVERY_PASSWORD PET_DISCOVERY_PORT_RANGE Before you begin Ensure that the Packet Internet Groper (ping) program is functional and is not blocked. Otherwise, you will not be able to send packets and receive responses from the host computers you are trying to communicate with. To specify autodiscovery attributes 1. From the PATROL Integration Configuration Utility menu bar, choose Options => AutoDiscovery. The AutoDiscovery dialog box displays SPECTRUM PATROL Integration Administrator Guide 47

50 Chapter 2: PATROL Integration Configuration Table 2-8 describes the autodiscovery attributes, including the host or subnet discovery option and the autodiscovery result listing. Table 2-8: Autodiscovery Attributes and Discovery Parameters (Sheet 1 of 2) Attribute User Name Description specifies the user name that the PATROL Integration server uses to authenticate hosts when adding previously undefined host computers running PATROL Agents to the configuration file A user name entry is not required to search for host computers during the discovery process. It is required when you want to add the autodiscovered computers to your configuration file. The default is patrol. Password specifies the password that the PATROL Integration server uses to authenticate hosts when adding previously undefined host computers running PATROL Agents to the configuration file A password entry is not required to search for host computers during the discovery process. It is required when you want to add the autodiscovered computers to your configuration file. The password is encrypted by the PATROL Integration configuration utility. The default is changeme. Port Range the designated ports that the configuration utility searches to discover PATROL Agents within the subnet The port range is required to launch a search of host computers. The minimum port number is The maximum port number is The default minimum port number is 2000, and the default maximum port number is Host name of the host computer from which the discovery is launched The default is the local host name. Discover the subnet of the host the default option which enables the discovery process to search the same local area network or geographic location of the host computer Otherwise, if you deselect the option, the search is limited to the host computer. Each discovery attempt has a default timeout period of 5 seconds. If no discovery is made within the timeout period, the discovery process continues to the next host in the subnet or terminates if no other hosts are available. AutoDiscovery Result list box that displays the results of the discovery process It lists the discovered host computers by host name and by the port number on which the PATROL Agent is running. 48 SPECTRUM PATROL Integration Administrator Guide

51 Setting PET Autodiscovery attributes and adding autodiscovered hosts Table 2-8: Autodiscovery Attributes and Discovery Parameters (Sheet 2 of 2) Attribute I S E W A R (information filters) Description specifies the type of events that you want the PATROL Agent to forward from the specified host to the PATROL Integration server See the PATROL user guide for your operating system for detailed descriptions of the event types. See Table 2-4 on page -28 for a summary description. By default, when you add hosts, all event types are selected, meaning that all events are forwarded by the PATROL Agent to the PATROL Integration server. When you deselect an event type, the PATROL Agent does not transmit it to the PATROL Integration server. Exception: Only the event types State Change, Error, Warning, and Alarm are preselected for the default local host name in the Host field. Note: The PATROL Integration server receives all state change events from the PATROL Agent and filters them at the server level. The events are not filtered at the PATROL Agent. So if you choose not to receive state change events, the PATROL Integration server, through an internal mechanism, can filter out unnecessary event messages associated with state changes. Yet the PATROL Integration server still allows updates (color code changes) to the PATROL Integration icons when a parameter undergoes a state change. 2. Enter the port number range within which you are seeking PATROL Agents. You do not have to bind all PATROL Agents to the same port number. If you specify a range of port numbers, the PATROL Integration server searches within that range for the first agent to connect to. 3. Enter a user name and a password by which to connect to a PATROL Agent or Agents. You do not need to enter a user name and a password to launch the PET autodiscovery process; only the port range is required. However, the user name and password are required when you are adding autodiscovered host computers in this dialog box. It is helpful to use a single PATROL user name and password for the PATROL Agents installed across your enterprise. 4. If you are specifying autodiscovery attributes only and do not want to launch a search at this time, then do the following: a. Click OK in the Autodiscovery dialog box. b. Save the configuration file, and stop and start the PATROL Integration server so that the changes can take effect. The user name, password, and port range that you entered will be saved to be used in a later autodiscovery search. SPECTRUM PATROL Integration Administrator Guide 49

52 Chapter 2: PATROL Integration Configuration To start the discovery process To start the discovery process, you must first enter a port range as described in Step 2 on page - 49 under the procedure To Specify Autodiscovery Attributes. After you enter a port range, continue as follows: 1. Enter the name of the host computer from which you want to base the discovery. The default entry is the local host computer. 2. To include the subnet of the specified host computer in the search, ensure that the Discover the subnet of the host check box is selected. 3. Click Discover. The configuration utility searches the network for computers with PATROL Agents running on ports within the specified port range. The name of the computer and the port number on which the PATROL Agent is running are displayed in the AutoDiscovery Result list. If a computer has multiple agents running on different ports, its name is repeated for each agent/port connection. By default, all the information event filters are selected for the list of autodiscovered host computers in the AutoDiscovery Result list. To add autodiscovered host computers to the configuration file To add autodiscovered host computers, you must first launch the discovery process, making sure to enter a user name and a password. When the discovery process completes its cycle and all autodiscovered host computers are listed, you can continue as follows: 1. Highlight the port and host computer entries that you want to add. 2. Specify which event filters to apply to the selected host computers. 3. Click Add Selected. The selected host computers are added to the configuration file. If a duplicate host name is detected, you will be notified via a message dialog box, and the duplicate host name will not be added. 4. Save the configuration file, and stop and then restart the PATROL Integration server (PETEPI) so that the changes can take effect. Setting server port, local port, and communications save time In this task, you will specify the port number to be used by the PATROL Integration online command interface, the port number to be used if a firewall exists on a host computer, and how often you want to save communication data between PATROL Integration and PATROL Agents. To set server port, local port, and communications save time 1. In the PATROL Integration configuration utility window, choose Options => Other Attributes from the main menu bar. The Other Attributes dialog box appears. 50 SPECTRUM PATROL Integration Administrator Guide

53 Setting server port, local port, and communications save time Server Port Local Port Save Time 2. In the Server Port, Local Port, and Save Time fields, type the appropriate information, as described in the following table. Table 2-9: Server Port, Local Port, and Communication Save Time Attribute Server Port Description specifies the port number of a TCP socket to be used by the PATROL Integration online command interface This port number must be an available, unused port number and cannot be the same port number as the Local Port, below. If you do not select a Server Port, a 0 is displayed in the Server Port field, and the default Server Port number (5000) will be used. For further details about online commands, see Using the Online Command Interface on page 61. (This online command interface is not supported on Microsoft Windows systems.) SPECTRUM PATROL Integration Administrator Guide 51

54 Chapter 2: PATROL Integration Configuration Table 2-9: Server Port, Local Port, and Communication Save Time Attribute Local Port Description specifies the port number that you want PATROL Agents to use to send information to PATROL Integration if a firewall is present between the PATROL Agent and PATROL Integration If this number is not specified, or if it is set to 0, PATROL Agents use randomly available port numbers. The default is 0. Note: For more information on the procedure required to connect the PATROL Console and the PATROL Agent across a firewall, refer to the PATROL for Unix Installation Guide. Save Time specifies the number of seconds that PATROL Integration waits between saves of communication data Communication data is written to the timesave.pet file at the interval specified by this option. If PATROL Integration is restarted or communications are reestablished with a disconnected host, PATROL Integration requests all events that have occurred from each host since the last save. This prevents the loss of any events that occurred when PATROL Integration was disconnected from a host. Since the saves are made only periodically, events that occurred since the last save may be reported again when communications are reestablished. The valid range is 0 to 300 seconds. The default is 0, which indicates no save to be performed. 3. Click OK. 4. Stop and start the PATROL Integration server (PETEPI) to initialize your changes. Customizing PATROL event messages In this task, you will customize the text of PATROL event messages to accommodate the message format and syntax that you want to use. For example, you can make the message text look similar to standard SPECTRUM text. If you do not customize PATROL event messages, they will appear in the Enterprise Alarm Manager window in the same format as PATROL event descriptions do under their respective event classes. When customizing PATROL event messages, you can: change the order of the text in the string add or delete text add event translation variables BMC Software recommends that you do not remove the format descriptors (indicated by %) in the original PATROL event class description. Removing the format descriptors deletes the dynamic arguments that are unique to the PATROL event class. If you remove the dynamic arguments, you 52 SPECTRUM PATROL Integration Administrator Guide

55 Customizing PATROL event messages are changing the content of the PATROL event message. Instead, substitute the appropriate event translation variable ($n) for the format descriptors. Before you begin Be familiar with the PATROL standard event catalog, event classes, and event descriptions. Further reading See the following PATROL documentation for related information about event catalogs, event classes, and event message descriptions: PATROL Console for Unix User Guide PATROL for Windows 2000 User Guide Volume 2 Monitoring and Managing with PATROL PATROL for Windows 2000 User Guide Volume 3 Customizing PATROL PATROL Agent Reference Manual PATROL Script Language Reference Manual Related keyword In this task, you are defining the PET_EVENT_XLATE configuration file keyword. To customize event message formats 1. Do one of the following to add, modify, or delete event message formats: From the PATROL Integration Configuration Utility main bar (Figure on page -53), choose Edit => Event Translation => Add to add new event message formats. To modify or delete event message formats, select the line item containing the module/catalog/class/ message text, and choose the Modify or Delete menu item from the Edit => Event Translation menu. In the bottom pane of the PATROL Integration Configuration Utility window, right-click to open a pop-up window containing the Add, Modify, and Delete menu items. Choose the appropriate command. If you choose the Add or Modify commands, the Event Translation dialog box is displayed. The following figure shows the Event Translation dialog box on top of the PATROL Integration Configuration Utility window with multiple event translation message descriptions added to the third pane of the window. SPECTRUM PATROL Integration Administrator Guide 53

56 Chapter 2: PATROL Integration Configuration The following table describes the event translation attributes. Table 2-10: Event Translation Attributes Attribute Integration Module Event Catalog Description specifies the name of the integration module; should always be set to SPECTRUM specifies the name of the PATROL event catalog that contains the event classes that, in turn, contain the events you want to translate To translate events from the standard event catalog, type 0 in this field. The standard event catalog contains all predefined standard event classes. If you create your own PATROL event catalog, type the name of that event catalog in this field. Event Class specifies the event class that identifies the event message to be translated The event catalog uses numerals and character strings as event class names. Message Text specifies the translated message text This field can contain text and special variables that are replaced with data from a PATROL event. Each variable begins with the dollar sign ($). 54 SPECTRUM PATROL Integration Administrator Guide

57 Preventing unwanted PATROL events 2. In the Event Translation dialog box, enter the module name, the event catalog, and event class. Then enter the message text, using event translation variables as needed. A small set of special characters can be included in the message text. These special characters are identified by a preceding back slash (\) as follows: \ttab (Unix only) \\back slash \$dollar sign These special characters are the only special characters that are supported. The use of other characters can produce unexpected results. 3. Click OK in the Event Translation dialog box when you are finished. Save the configuration file, and then stop and start the PATROL Integration server so that the changes can take effect. Preventing unwanted PATROL events The keywords SPECTRUM _PATROL FILTERMODE and SPECTRUM_PATROLFILTER enable you to prevent unwanted PATROL events that originate from specified host computers, applications, and instances from being forwarded to the SpectroSERVER. You can specify the SPECTRUM_PATROLFILTERMODE and SPECTRUM PATROLFILTER keywords and their values in the PATROL Integration configuration utility. Table 2-11: PATROL Event Keyword SPECTRUM_PATROLFILTERMODE Specifies how the PATROL filter (see SPECTRUM_PATROLFILTER below) is to used. The available values are IN or OUT. IN indicates that only events from the specified object or objects are forwarded to the SpectroSERVER. IN is rarely used. OUT indicates that the events from the specified object or objects are NOT forwarded to the SpectroSERVER. The default value is OUT, which is a typical filter mode. SPECTRUM_PATROLFILTER Defines the object or objects that the filter will apply to. The available values are "hostname "patrol_application "patrol_instance These values have a hierarchical relationship, with hostname at the highest level and patrol_instance at the lowest level: hostname->patrol_application->patrol_instance. You can specify one or more filter objects. SPECTRUM PATROL Integration Administrator Guide 55

58 Chapter 2: PATROL Integration Configuration Applying filter related keywords The SPECTRUM_PATROLFILTERMODE parameter has two values: IN and OUT. OUT is the default value. When you choose OUT, you indicate that you do NOT want to forward PATROL events originating from the specified host, application, and/or parameter defined under the SPECTRUM_PATROLFILTER parameter. If you choose IN, you indicate that you want to forward ONLY the PATROL events originating from the specified host, application, and/or parameter. For example, suppose you entered the following values for the keywords in the PATROL Integration utility: Keyword SPECTRUM_PATROLFILTERMODE SPECTRUM_PATROLFILTER Value OUT patrol_application = FILESYSTEM patrol_instance = Houston-continuus This selection indicates that you do NOT want to forward events originating from the patrol_instance Houston-continuus of the patrol_application FILESYSTEM to the SpectroSERVER. In this example, events originating from the patrol_application/patrol_instance of FILESYSTEM/ Houston-continuus on all managed host computers are not forwarded. In the following example, you specify a host computer (the hostname value): Keyword SPECTRUM_PATROLFILTERMODE SPECTRUM_PATROLFILTER Value OUT hostname = pvsun1 patrol_application = DISK This selection indicates that you do not want to forward events originating from the patrol_application DISK on a specific host computer, pvsun1. However, events originating from the patrol_application DISK on other managed host computers are forwarded. NOTE. Normally, you would NOT specify just a host computer under the SPECTRUM_PATROLFILTER parameter. To prevent events from a specific computer from being forwarded, remove the host computer from the list of managed hosts in the config.pet file. You can make multiple, separate SPECTRUM_PATROLFILTER entries, as in the following example, which combines the previous two filters: Keyword SPECTRUM_PATROLFILTERMODE SPECTRUM_PATROLFILTER SPECTRUM_PATROLFILTER Value OUT hostname = pvsun1 patrol_application = DISK patrol_application = FILESYSTEM patrol_instance = Houston-continuus 56 SPECTRUM PATROL Integration Administrator Guide

59 Preventing SPECTRUM from recreating application instances This example indicates that you do not want to forward events originating from "the patrol_application DISK on the host computer pvsun1 "the patrol_instance Houston-continuus of the patrol_application FILESYSTEM on all managed host computers in the config.pet file Tip. To initialize changes to the configuration file, you must restart the PETEPI. Preventing SPECTRUM from recreating application instances The keywords SPECTRUM_IGNOREVOIDMODE and SPECTRUM_IGNOREVOIDFILTER enable you to prevent the SpectroSERVER from having to recreate application instance objects that are destroyed as the result of the PETEPI forwarding the SpecObjDelete command to the SpectroSERVER. The PATROL Agent uses the PSL () destroy command to remove an object whenever the state of a PATROL instance changes from OK to VOID. The object representing the instance is deleted. The PATROL Agent forwards the state change VOID to the PETEPI. The PETEPI, in turn, forwards a SpecObjDelete command to the SpectroSERVER to enable it to delete the corresponding PATROL object. Often the state change of these objects returns back to OK from VOID, and the corresponding objects are recreated. The SpectroSERVER must recreate the objects in the SpectroGRAPH for each time that they are deleted and then recreated. This process can sap system resources and reduce system performance. To tell the PETEPI to ignore the state change to VOID and not to forward the SpecObjDelete command to the SpectroSERVER, you must "set the SPECTRUM_IGNOREVOIDMODE value to YES "enter a value for the patrol_application, the patrol_instance, or both Do not specify a host name for the SPECTRUM_IGNOREVOIDFILTER parameter. Look at the following example: Keyword SPECTRUM_IGNOREVOIDMODE SPECTRUM_IGNOREVOIDFILTER Value YES patrol_application = FILESYSTEM patrol_instance = data-src The IGNOREVOIDMODE is turned on, indicated by the YES value assigned to the SPECTRUM_IGNOREVOIDMODE parameter. This selection shows that the PETEPI will ignore the state change to VOID and not forward the SpecObjDelete command for the state change events originating from the patrol_application and patrol_instance defined by the SPECTRUM_IGNOREVOIDFILTER parameter. In this case, for the state change VOID on the patrol_instance data-src of the patrol_application FILESYSTEM on all managed hosts in the config.pet, the SpecObjDelete command is filtered out. The SpectroSERVER does not delete the application instance objects for FILESYSTEM/data-src. SPECTRUM PATROL Integration Administrator Guide 57

60 Chapter 2: PATROL Integration Configuration You can make multiple, separate SPECTRUM_IGNOREVOIDFILTER entries, as in the following example: Keyword SPECTRUM_IGNOREVOIDMODE SPECTRUM_IGNOREVOIDFILTER SPECTRUM_IGNOREVOIDFILTER Value YES patrol_application = FILESYSTEM patrol_instance = data-src patrol_application = DISK patrol_instance = disk2 In this example, the PETEPI is instructed to ignore the state change to void that originates from two applications and instances-filesystem/data-src and DISK/disk2-on all managed hosts in the config.pet. The PETEPI does not forward the SpecObjDelete commands for these state changes to the SpectroSERVER. The corresponding application instance objects remain intact. Tip. To initialize changes to the configuration file, you must restart the PETEPI. Saving and using configuration settings In this task, you will use the PATROL Integration configuration utility to save the PATROL Integration configuration settings to a file. Notes on Saving and Using Configuration Settings You can save changes to the default configuration file (config.pet) or any custom configuration file you want to create. Using the Save As command, you can create several custom settings and save them with different file names. You can then use the configuration files for a variety of purposes, such as monitoring different sets of hosts and filtering a variety of different event types. You can use only one configuration file at a time. You can modify configurations at any time by using the PATROL Integration configuration utility. However, if you change the configuration while PATROL Integration is running, you must first save the settings and then restart PATROL Integration for the modified settings to take effect. You can protect access to the config.pet file by making it read-only for certain PATROL Integration users. Use only the PATROL Integration configuration utility to modify the configuration file; do not use any other method. Figure 2-1 on page -25 shows the sample configuration file, config.pet, that is installed in the PATROL Integration installation directory. To save the default configuration file with the same name 1. Choose File => Save from the PATROL Integration configuration utility main menu bar. The file is saved. To save a configuration file with a different name 1. Choose File => Save As from the PATROL Integration configuration utility main menu bar. 58 SPECTRUM PATROL Integration Administrator Guide

61 Saving and using configuration settings A file selection dialog box is displayed. 2. In the file name field at the bottom of the dialog box, type any valid file name that you want to assign to the current configuration settings. 3. Click OK. The file is saved and the file selection dialog box closes. If you save the configuration file as any name other than config.pet, you must specify the new configuration file when you start PATROL Integration. SPECTRUM PATROL Integration Administrator Guide 59

62 Chapter 2: PATROL Integration Configuration 60 SPECTRUM PATROL Integration Administrator Guide

63 Appendix A: The Online Command Interface (UNIX) This appendix describes how to use the online command interface to change the run-time configuration of the PETEPI and return information about configuration settings and attached hosts. Using the Online Command Interface on page 61 Setting the PET_ACL Keyword on page 67 Using the Online Command Interface In the task, you will change the run-time configuration of the PETEPI and return information about configuration settings and attached hosts. This can be done without stopping and restarting the PETEPI. Using the online command interface, you can add, modify, and remove hosts; stop and resume the transmission of event messages from selected hosts; modify connection attributes, and more. Beware of the security issues addressed in this section. By default, anyone using the patrol user account can change the configuration using the online command interface. Notes on Using the Online Command Interface The online command interface is for PETEPIs running on Unix systems only; it is not supported for PETEPIs running on Microsoft Windows systems. Changes made via the online command interface do not change the disk resident configuration file (config.pet). Changes effect the current run-time configuration of the PETEPI. These changes are lost when the PETEPI is stopped. Before You Begin You must specify a server port number to use on the computer where the PETEPI is installed is the default server port number. If you want to specify another port number, (refer to Setting server port, local port, and communications save time on page 50). You must set the PET_ACL keyword on the computer where the PETEPI is installed (refer to Setting the PET_ACL Keyword on page -67). 61

64 Appendix A: The Online Command Interface (UNIX) To Use the Online Command Interface 1. Start a telnet session to the host where the PETEPI is running, using the following: The host name that is running the PETEPI The server port number to use on the computer where the PETEPI is running (refer to Setting server port, local port, and communications save time on page 50) If the PETEPI is running on host C101 and was started with server port 5000, connect to the PETEPI with the following command: telnet C Use the uid command to identify yourself to the PETEPI. If the PET_ACL keyword has the following value: user1/host/* Enter the following command: uid user1 3. Type one of the commands listed in Table A-1 on page SPECTRUM PATROL Integration Administrator Guide

65 Using the Online Command Interface Command add host Table A-1: PATROL Integration Online Commands Description Specifies a computer that hosts a PATROL Agent that you want PATROL Integration to manage. The format is: add host <hostname> <port#> <username> <password> <filter list> where: <hostname> is the host name of the remote PATROL Agent. <port#> is the port number for connecting to the PATROL Agent. <username> is the user name for logging on to the remote PATROL Agent. <password> is the user name password, which is encrypted. Note: To find out what the encrypted password is, use the PATROL Integration Configuration Utility. Add the host you want to add, using the user name and password you want. Then save the configuration. Finally, look in the configuration file (config.pet) to find out what the encrypted password is (refer to page 25). <filter list> is defined by the first character of each event Type you want to have forwarded from a specific PATROL Agent. Separate the event Types with a comma. The event Types are as follows: (I)nformation (S)tate Change (E)rror (W)arning (A)larm (R)esponse This process returns the following information: success - hostname <hostname> updated fail - error: when updating host <hostname> An attempt is made to establish a connection to the host. The host is then treated like any other host, with connection successes and failures, and I/O processing. Example: add host host patrol QXYR I S E W A R update host Modifies configuration settings of a managed host. The format is: update host <hostname> <port#> <username> <password> <filter list> where the parameters are the same as for the add host command, This process returns the following information: success - hostname <hostname> updated fail- Can't find the host <hostname>. Try command status to list all the available host names The host is not modified if not found. If found, and something other then the filter list has changed, the host connection is terminated and a new connection is established with the new parameters. If only the filter list has changed, the new filters are set for the host. Example: update host host patrol QXYR I S E W A R SPECTRUM PATROL Integration Administrator Guide 63

66 Appendix A: The Online Command Interface (UNIX) Command delete host Description Removes a host from the list of managed hosts, which stops events from being forwarded from the PATROL Agent to the PETEPI. This is useful for when you do not want to receive anymore event messages from a particular node.. The format is: delete host <hostname> where: <hostname> is the host name of the remote PATROL Agent. This process returns the following information: success - hostname <hostname> deleted fail- Can't find the host <hostname>. Try command status to list all available host names. Any active connection to the host is stopped. To reactivate the connection, use the update host command. show hosts Displays the status of the PETEPI and managed hosts. The format is: show hosts This process returns the following information: Checking statistics... Current status:<dying running testing initializing> Patrol Event Translator <version> running since <starttime> Host NamePort NumUser NameStatus ================================ <hostname> <port #><username> <*> <hostname> <port #><username> <*>.. *Status = running, initializing, testing, die, error, closed, error on open connection, error filter setting. The return string is suitable for printing directly. set stop Stops a host from sending event messages to the PETEPI. This command is useful to use if you want to take a node offline (for example, for maintenance) and you do not want to receive the Host <hostname> offline: Retrying on port 1987 event messages while the node is offline. When you are ready to bring the node back online, use set start to resume forwarding event messages from the PATROL Agent to the PETEPI. The format is: set stop <hostname> where: <hostname> is the host name of the remote PATROL Agent. This process returns the following information: <hostname> stopped Any active connection to the host is stopped. To reactivate the connection, use the set start command. 64 SPECTRUM PATROL Integration Administrator Guide

67 Using the Online Command Interface Command set start Description For a host that was disconnected from the PETEPI with the set stop command, this command reconnects to that host so that event messages will be forwarded from the PATROL Agent to the PETEPI. The format is: set start <hostname> where: <hostname> is the host name of the remote PATROL Agent. This process returns the following information: <hostname> started The connection to the host is reestablished. set status Displays PATROL Integration s connection and messaging settings. The format is: set status This process returns the following information: log file:<logfile name> message output:<logfile STDERR STDOUT LOGERR LOGOUT NONE> message level:<debug INFO WARN ERROR> retry: <3-10> timeout: <1-180> heartbeat: < > The return string is suitable for printing directly. set log Specifies the name of the internal diagnostic messaging file. The format is: set log <filename> where: <filename> is the path and name of the log file. The default is /tmp/pet.log. This process returns the following information: new log file: <filename> This process closes any open log file. Changes take place immediately. SPECTRUM PATROL Integration Administrator Guide 65

68 Appendix A: The Online Command Interface (UNIX) Command set level Description Specifies the security level of internal diagnostic messages. The format is: set level <level> where: <level> is the message level desired. The following values are valid. Levels are listed lowest to highest. The default is WARN. ValueDescriptionLevel DEBUG Debug messageshighest INFO Information messages WARN Warning messages ERRORError messages Lowest Note: Levels are listed highest to lowest. PATROL Integration outputs only the messages with a level equal to or less than the selected level. Setting this option to a high level during normal run-time may cause some performance degradation. This process does not return any information. Changes take effect immediately. set output Specifies the output location of internal diagnostic messages. The format is: set output <outputlocation> where: <outputlocation> determines where to output messages. The following values are valid. The default LOGFILE. ValueDescription LOGFILE Output to the log file only STDERR Output to stderr only STDOUT Output to stdout only LOGERR Log in the log file and output to stderr LOGOUT Log in the log file and output to stdout NONE Turn off all message output This process does not return any information. Changes take effect immediately. 66 SPECTRUM PATROL Integration Administrator Guide

69 Using the Online Command Interface Command set retry Description Specifies the number of times the PETEPI will retry a request for data from hosts. The format is: set retry <n> where: <n> is the number of times to retry a request for data. Valid range is The default is 4. If a valid number is used, this process returns no information. If an invalid number is used, the following information is returned: Invalid retry value, using default set timeout Specifies the time-out period to use when attempting to communicate with PATROL Agents. The format is: set timeout <n> where: <n> is the time-out interval in seconds. Valid range is The default is 35. If a valid number is used, this process returns no information. If an invalid number is used, the following information is returned: Invalid timeout value, using default Setting the PET_ACL Keyword In this task, you will use the PATROL Integration Configuration Utility to set the PET_ACL keyword. This keyword provides a form of security through an access control list that specifies which users are allowed to access the PETEPI via the online command interface. This prevents an authorized user from changing the PETEPI configuration. The default setting for the PET_ACL keyword is patrol/*/*, which means anyone using the patrol user account will have access to the online command interface. To Set the PET_ACL Keyword 1. Start the PATROL Integration Configuration Utility on the node on which the PETEPI you want to access is installed. Refer to Setting server port, local port, and communications save time on page 50. The PATROL Integration Configuration Utility is displayed. 2. In the middle section of the window, click on SPECTRUM. 3. Choose Edit => Integration Module => Edit Keywords from the main menu bar. The Integration Module Keywords dialog box appears, as shown in the following figure: SPECTRUM PATROL Integration Administrator Guide 67

70 Appendix A: The Online Command Interface (UNIX) Click PET_ACL here The selected Keyword appears here The keyword s Value appears here Change entries here and click Modify to modify values 4. In the upper section of the window, click PET_ACL. The selected keyword and value appear in the fields at the bottom of the window. 5. To modify the value, type the value you want into the Value field, and click Modify. Values must be entered using the following format: <username/hostname/*>[,username/hostname/*][,...] where username is the name of the user you want to provide access to. This field may contain the * wildcard. PATROL Integration cannot determine the user name during a telnet session. This limitation forces the telnet users to identify themselves via the uid online command. This creates a potential security condition since any one that knows the user names listed for the PET_ACL keyword can use the online commands. Therefore, it is recommended that you use user names that are not easily recognized. These user names do not have to be valid Unix user names. hostname is the name of the host from which the user may access the PETEPI. This field may contain the * wildcard alone or as the first character of the hostname. If you want to allow user1 with encrypted password from host1 and user101 with encrypted password from host101 to access all the online commands, set the PET_ACL value to: user1/host1/*, user101/host101/* 6. When you are finished, click Close. The Integration Module Keywords window is closed. 7. Close the PATROL Integration Configuration Utility. Where to Go from Here Once you have set the PET_ACL keyword 68 SPECTRUM PATROL Integration Administrator Guide