SPECTRUM PATROL Integration Administrator Guide

SPECTRUM PATROL Integration

Administrator GuideDocument 5170

NoticeCopyright 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 252.227-7013(c)(1)(ii) and FAR 52.227-19.

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:

http://www.aprisma.com/support/secure/manuals/trademark-list.htm

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 e-mail to [email protected]; 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 52.227-14 (June 1987) Alternate III(g)(3) (June 1987), FAR 52.227-19 (June 1987), or DFARS 52.227-7013(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 03801 USA

Phone: 603.334.2100U.S. toll-free: 877.468.1448Web site: http://www.aprisma.com

http://www.aprisma.com/support/secure/manuals/trademark-list.htm

http://www.aprisma.com

SPECTRUM PATROL Integration Administrator Guide 1

Contents

How this guide is organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

SPECTRUM Documentation Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

PATROL Documentation Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Document Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Contacting Concord Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 1: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

About PATROL Integration for SPECTRUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

PATROL Integration components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

PATROL components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

PATROL Event Translator for SPECTRUM external protocol interface . . . . . . . . . . . . . . . 6

PATROL Integration Configuration Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

PATROL Integration configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

PATROL model types in SPECTRUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

How PATROL Integration works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

PATROL Integration features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Monitoring of PATROL Agent resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Propagation of alarms and events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Event and alarm handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Information views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

How management and physical faults are isolated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Example of fault isolation determining physical fault . . . . . . . . . . . . . . . . . . . . . . . . . 12

Example of fault isolation in management-level connectivity . . . . . . . . . . . . . . . . . . . 15

Fault isolation scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2: PATROL Integration Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Using the PATROL Integration Configuration Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Starting the PATROL Integration Configuration Utility . . . . . . . . . . . . . . . . . . . . . . . . 26

Specifying the hosts that you want to manage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Modifying host attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Removing hosts from the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Setting the PATROL Alarm Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Setting connection attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Setting the connection tolerance values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Setting attributes for diagnostic output messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Managing pet.log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Setting PET Autodiscovery attributes and adding autodiscovered hosts . . . . . . . . . . . . . . 46

Setting server port, local port, and communications save time . . . . . . . . . . . . . . . . . . . . 50

2 SPECTRUM PATROL Integration Administrator Guide

Contents

Customizing PATROL event messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Preventing unwanted PATROL events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Applying filter related keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Preventing SPECTRUM from recreating application instances . . . . . . . . . . . . . . . . . . . . . . 57

Saving and using configuration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Using the Online Command Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

To Use the Online Command Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Setting the PET_ACL Keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

3

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:

http://www.aprisma.com/support/secure/manuals/

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

http://www.aprisma.com/support/secure/manuals/


http://www.bmc.com/support.html

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 e-mail address:

[email protected]

Thank you for helping us improve our documentation.

Contacting Concord Communications

Contact information for Concord SPECTRUM Business Unit is available at:

http://www.aprisma.com/company/officelisting.shtml

mailto:[email protected]

http://www.aprisma.com/company/officelisting.shtml

http://www.bmc.com/support.html

5

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 SPECTRUMPATROL 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 componentsPATROL 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:

6 SPECTRUM PATROL Integration Administrator GuideF

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

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.

IH forPATROL

PATROL Knowledge

Modules

Configuration Files Event

Repository

PATROL (Operator or Developer)

Console

SpectroGRAPH

PATROL Integration

TCP/IP+UDP

SPECTRUM

ConfigurationFile

config.pet

SpectroSERVER

PATROL Integration

TCP/IP+UDP

DCM

PATROL API

PETEPI

PATROL Agent

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 Description

PatrolPET The PatrolPET model type.

PatrolHost The PatrolHost model type.

PATROL Application Class

The PATROL Application Class model type.

PATROL Application Instance

The PATROL Application Instance model type.

PatrolGraph The PatrolGraph model type.


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 worksPATROL 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 65535 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.

How PATROL Integration works


Figure 1-2: PATROL Integration and SPECTRUM Architecture

PATROL Managed Node

PETEPI

informationPATROL

PATROLAgent

PATROL Knowledge Modules

PATROL Integration configuration utility(petconf)

PATROL Integration configuration file(config.pet)

optional PATROL Console

SpectroSERVER

DCM

PATROL IntegrationSpectroGRAPH

API

PATROL API

EPI messagesthrough default

port 65535


Chapter 1: Overview

PATROL Integration featuresPATROL 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

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

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

PATROL Agent

PETEPI

SpectroSERV

SpectroGRAPH

CsPCause

event code

alarm code

message probable

Alarm Event Info

PATROL model icon PATROL model alarm

PATROL model types

inference handler

PATROL event message

CsEvFormatEventDisp

PATROL API


Chapter 1: Overview

• parameter graphs

How management and physical faults are isolatedIn 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 physical-level 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.

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-


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.



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

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 management-level 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.

SpectroSERVER

Process

Router

SNMP

EPI/API

PSLTo have the PETEPI proxy manage the PATROL Hosts on the other side of a firewall:

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

3. PETEPI uses PSL (Patrol Script Language) to communicate with PATROL Hosts.

1

2

3

Network

Goal:PETEPIProcess

PATROL Host

PATROL Agent


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.



Fault isolation scenarios

Table 1-2 shows a sampling of fault isolation cases that are possible in PATROL Integration for SPECTRUM.

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.

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


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.



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.


Chapter 1: Overview

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.


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.


Case Description


Chapter 1: Overview

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


Case Description

23

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.



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

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.

Table 2-1: PATROL Integration Configuration Utility Tasks

TaskOptional or Required 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).

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



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



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.

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

Table 2-2: Configuration Utility Menu Commands

Menu Command Descriptions

File Use this menu to open and save configuration settings.

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



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

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

host_name.domain.com

12.34.567.890

host_name


12.34.567.890

host_name.domain.com host_name


12.34.567.890

host_name


12.34.567.890

Table 2-4: PATROL Event Types

Event Type Description Required/Optional

Information an event that is logged for informational purposes only

Examples of typical information events include the following:

A parameter is activated or deactivated.

A global parameter is suspended or resumed.

Application discovery occurs.

Optional

State Change an event that is triggered by any change of state that takes place on a resource monitored by PATROL

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

Required



Before You Begin


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

Error an event that is the result of a failure or an error

This event is not generated by the PATROL-monitored object.

Optional

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

Required

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

Required

Response an event that is created by the Agent to indicate that some kind of user input is required at the PATROL Console

Optional

Table 2-4: PATROL Event Types

Event Type Description Required/Optional



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.

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.

Table 2-5: Host Configuration Attributes

Attribute Description

Host Name 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 3181.

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.

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.


Once you have specified the hosts that you want to manage, you can perform additional tasks.

Modifying host attributesIn 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


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

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



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

4. Click OK.



Where to Go from Here

Once you have modified host attributes, you can perform additional tasks.

Task Reference



removing hosts from the configuration page 33

Removing hosts from the configuration


Removing hosts from the configurationIn 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.


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

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.

3. Click OK.



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.


Once you have removed the hosts that you do not want to manage, you can perform additional tasks.



Setting the PATROL Alarm FilterIn 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.

Task Reference



specifying other hosts that you want to manage page 27

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.


• 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


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



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



Setting connection attributesIn 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

1. Type or select the appropriate information, as described in Table 2-6.

Table 2-6: Connection Attributes (Sheet 1 of 3)


Connection Protocol

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.

UDP or TCP

Valid range = 60 to 1800 seconds

Valid range = 3 to 10 retries



Valid range = 0 or greater


Setting connection attributes


Heartbeat (sec) 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.

.





2. Click OK.




Once you have set connection attributes, you can perform additional tasks.

Setting the connection tolerance valuesIn 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.

Retry Agent Interval

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

Task Page

setting attributes for diagnostic output messages page 40




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.



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


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



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



Setting attributes for diagnostic output messagesIn 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:

PET_SUSTAIN_CONNECT_DURATION 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 300.


Setting attributes for diagnostic output messages


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


Message Output 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

Diagnostic Output section

Unix path name



3. Click OK.




Once you have set the attributes for diagnostic output messages, you can perform additional tasks.

Message Level specifies which type of diagnostic messages you want to send.

The default is Warning.

The following values are valid.

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

Table 2-7: Attributes for Diagnostic Output Messages


Setting attributes for diagnostic output messages


Task Page

setting server port, local port, and communication save time

page 50




Managing pet.log filesIn 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.



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

Managing pet.log files


Figure 2-6: Integration Module Keywords Dialog Box


• 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.001102_152054 (11/02/2000 at 3:20 P.M.)

pet.log.001102_173326 (11/02/2000 at 5.33 P.M.)

pet.log.001102_230655 (11/02/2000 at 11:06 P.M.)

pet.log.001103_041522 (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



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

5. Click Add. Then click Close to shut the dialog box.



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

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 2-8.

PETEPI Autodiscovery discovers the PATROL Hosts

SPECTRUM Management PATROL Host

Hosts

Station running PETEPI Process

running AgentSoftware



Figure 2-8: SPECTRUM Autodiscovery

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

Connections

SPECTRUM Autodiscovery discovers the connections between a PATROL Host and monitored devices.

PATROL HostDevice



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)


User Name 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 1024. The maximum port number is 32767. The default minimum port number is 2000, and the default maximum port number is 4000.

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.



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.

I S E W A R (information filters)

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.

Table 2-8: Autodiscovery Attributes and Discovery Parameters (Sheet 2 of 2)




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

Setting server port, local port, and communications 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


Server Port 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.)

Server Port

Local Port

Save Time



3. Click OK.

4. Stop and start the PATROL Integration server (PETEPI) to initialize your changes.

Customizing PATROL event messagesIn 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

Local Port 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.

Table 2-9: Server Port, Local Port, and Communication Save Time


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.



The following table describes the event translation attributes.

Table 2-10: Event Translation Attributes


Integration Module specifies the name of the integration module; should always be set to SPECTRUM

Event Catalog 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 ($).

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



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:

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

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 Value

SPECTRUM_PATROLFILTERMODE OUT

SPECTRUM_PATROLFILTER patrol_application = FILESYSTEM

patrol_instance = Houston-continuus

Keyword Value


SPECTRUM_PATROLFILTER hostname = pvsun1

patrol_application = DISK

Keyword Value


SPECTRUM_PATROLFILTER hostname = pvsun1

patrol_application = DISK

SPECTRUM_PATROLFILTER patrol_application = FILESYSTEMpatrol_instance = Houston-continuus

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

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.

Keyword Value

SPECTRUM_IGNOREVOIDMODE YES

SPECTRUM_IGNOREVOIDFILTER patrol_application = FILESYSTEM

patrol_instance = data-src



You can make multiple, separate SPECTRUM_IGNOREVOIDFILTER entries, as in the following example:

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

Keyword Value

SPECTRUM_IGNOREVOIDMODE YES

SPECTRUM_IGNOREVOIDFILTER patrol_application = FILESYSTEM

patrol_instance = data-src

SPECTRUM_IGNOREVOIDFILTER patrol_application = DISK

patrol_instance = disk2

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.



61

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 InterfaceIn 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. 5000 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).



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 C101 5000

2. 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 63.

Using the Online Command Interface


Table A-1: PATROL Integration Online Commands

Command Description

add host 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 Typeyou 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 host1 1987 patrol “QXYR7234225242” “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,


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 host1 1987 patrol “QXYR7234225242” “I S E W A R”



delete host 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.


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


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>



<hostname> stopped

Any active connection to the host is stopped. To reactivate the connection, use the set start command.

Command Description



set start 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>



<hostname> started

The connection to the host is reestablished.

set status Displays PATROL Integration’s connection and messaging settings.

The format is:set status


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: <60-1800>

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.


new log file: <filename>

This process closes any open log file. Changes take place immediately.

Command Description



set level Specifies the security level of internal diagnostic messages.

The format is:

set level <level>

where:

<level> is the message level desired. The following values arevalid. 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.ValueDescriptionLOGFILE Output to the log file onlySTDERR 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 stdoutNONE Turn off all message output

This process does not return any information. Changes take effect immediately.

Command Description



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:

set retry 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 3-10. 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 1-180. 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

Command Description



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.


Once you have set the PET_ACL keyword

The selected Keyword appears here

Click PET_ACL here

The keyword’s Value appears here

Change entries here and click Modify to modify values



,

To ... Go to ...

save and use configuration settings page 58



71

Index

Symbols/tmp/pet.log 42

Aaccessing

configuration file 58ALARM_FILTER 34alarms

handling 10propagation 10

attributesconnection 36diagnostic output messages 41host configuration 30setting for diagnostic output messages 40

autodiscoverySee also PET autodiscoveryPET autodiscovery in configuration file 46PET procedure 46SPECTRUM and PET 46

AutoDiscovery Attributes dialog box 47

Bblacking out hosts during run-time 64

Cchanging

run-time configuration settings 25commands

Connection Attributes 27Ctrl+A 29

Event Translation 27Host Configuration 27Integration Module 27Other Attributes 27

communications save timesetting 52timesave.pet 52

componentsPATROL Integration 5

config.pet fileaccess to 58description 7protecting access to 58sample 25

configurationlist of PATROL Integration configuration utility

tasks 24online command interface 61utility, PATROL Integration 26

configuration fileaccess to 58adding autodiscovered hosts 50adding hosts through autodiscovery 31custom settings 7description 7host name options 27protecting access to 58sample 25saving and using configuration settings 58setting ALARM_FILTER 34setting autodiscovery parameters 46setting connection tolerance 38special characters 55stopping and starting server 25

connection attributesconnection protocol 36heartbeat 37


Index

reconnect interval 37retries 37setting 36time out 37

Connection Attributes command 27connection mode

connection tolerance 38connection protocol, setting 36connection tolerance

definition 38description 39, 40

Ctrl+A command 29

Ddeleting

hosts during run-time 64deleting hosts 33diagnostic output attributes

log file 42message level 42message output 41

dialog boxesAutoDiscovery Attributes 47Connection Attributes 36event translation 53Host Configuration 30Integration Module Keywords 35Other Attributes 40

EEnterprise Alarm Manager

ALARM_FILTER 34event catalog

ALARM_FILTER 35description 54

event classALARM_FILTER 35description 54

event filtermodifying during run-time 63specifying during run-time 63

event filtersin configuration file 49specifying 30

event message formatsevent catalog 54event class 54message text 54

Event Translation command 27events

ALARM_FILTER 34customizing message formats 53handling 10propagation 10types, specifying 27

Ffault isolation

process description 12proxy relationships 15scenarios 17

features of PATROL Integration 10files

config.pet 7, 25config.pet.sample 25log file 42timesave.pet 52

filtering eventsduring run-time 63

filtersspecifying 30

firewall 50

Hheartbeat

setting 37value 37

host attributes, modifying 32host configuration attributes

event filter 30host name 30password 30port 30user name 30

Host Configuration command 27host identification attributes, modifying 31host name

specifying to use online commands 62hosts

adding to run-time 63blacking out during run-time 64deleting 33deleting during run-time 64modifying during run-time 63removing 33restarting after blackout 65showing connection attributes 65showing during run-time 64specifying 27specifying name 30


with Agents 27

Iidentifying hosts 27inference handlers

in fault isolation 12, 13information views

overview 11Integration Module

command 27editing keywords 67

Kkeywords

ALARM_FILTER 34PET_AGENT_DISCONNECT_RETRIES 38PET_DISCOVERY_PASSWORD 47PET_DISCOVERY_PORT_RANGE 47PET_DISCOVERY_USERNAME 47PET_SUSTAIN_CONNECT_DURATION 38

Llocal port, setting 52log file, setting 42log files

date stamps 44disk space 45

Mmanagement fault

example in fault isolation 15menu commands

Connection Attributes 27Event Translation 27Host Configuration 27Integration Module 27Other Attributes 27PET autodisocovery 27

message levelchanging during run-time 66

message level valuesDEBUG 42ERROR 42INFO 42WARN 42

message level, setting attributes 42message output

changing during run-time 66message output values

LOGERR 41LOGFILE 41LOGOUT 41NONE 41STDERR 41STDOUT 41

message output, setting attributes 41message text, description 54model types 7modifying

host attributes 32hosts during run-time 63Integration Module keywords 68

Oonline commands

add host 63delete host 64set level 66set log 65set output 66set retry 67set start 65set status 65set stop 64set timeout 67show host 64update host 63

Other Attributes command 27overview

alarm handling 10alarm propagation 10event handling 10event propagation 10information views 11monitoring of PATROL Agent resources 10PATROL Event Translator for SPECTRUM EPI 6PATROL Integration 5PATROL Integration configuration file 7PATROL Integration configuration utility 7, 24PATROL Integration model types 7PETEPI 6

Ppassword

specifying 30PATROL Agents

autodiscovery 46


Index

specifying the port number 30PATROL Integration

components 5configuration file, overview 7features 10model types 7overview 5relationship to other components 6stopping and starting server 25

PATROL Integration configuration utilitymodifying host attributes 28overview 7, 24removing hosts 33saving configuration settings 58setting attributes for diagnostic output

messages 40setting connection attributes 36setting ports and communications save

time 50setting the PET_ACL keyword 67specifying hosts 27starting from Unix command line 26using configuration settings 58

PATROL Integration key componentsPATROL Event Translator for SPECTRUM EPI 5PATROL Integration configuration file 5PATROL Integration configuration utility 5PETEPI 5

PATROL Integration modeling 7PATROL key components

PATROL Agent configuration utility 6PATROL Agents 6PATROL Console 6PATROL Knowledge Modules 6

PET autodiscoveryadding hosts 50menu command 27password 48port range 48subnet 48timeout period 48user name 48

pet.logchanging during run-time 65date stamps 44default path 42disk space 45specifying size and number 44

PET_ACL keywordsetting 61

PET_AGENT_DISCONNECT_RETRIES 39PET_SUSTAIN_CONNECT_DURATION 40PETEPI

overview 6PET-specific keywords 61PET-specific settings 24physical fault

example in fault isolation 12port

65535 8specifying 30

port numbersPET autodiscovery port range 48specifying for online commands 62

protect access to configuration file 58proxy relationships 15

Rreconnect interval, setting 37reconnecting to PATROL Agents 37removing

hosts 33hosts during run-time 64

restarting hosts during run-time 65retries (PET Server)

changing during run-time 67retries, setting 37retry agent count

defined 37retry agent interval

defined 38run-time configuration

adding hosts 63blacking out hosts 64deleting hosts 64filtering events 63modifying hosts 63setting diagnostic log file name 65setting diagnostic message level 66setting diagnostic message output 66setting PET Server retries 67setting PET Server time-out period 67showing connection attributes 65showing hosts 64

run-time configuration settings, changing 25

Ssample configuration file 25saving

configuration file, with different name 58configuration file, with same name 58configuration settings 58

scenarios in fault isolation 17


server port numberspecifying to use online commands 62

server port, setting 51setting

ALARM_FILTER 34attributes for diagnostic output messages 40communications save time 50connection attributes 36connection protocol 36diagnostic output attributes 65, 66heartbeat 37local port 52log file 42message level 42message output 41PET_ACL 61reconnect interval 37retries 37, 67run-time configuration 61save time 52server port 51time out 37, 67

showingconnection attributes (during run-time) 65hosts (during run-time) 64

specifyingevent filter 30event types 27host name 30hosts 27hosts (during run-time) 63password 30port number 30user name 30

startinghosts during run-time 65PATROL Integration configuration utility, from

a Unix command line 26, 27stderr 40stdout 40

Ttelnet session

online commands 62time out

setting 67time out, setting 37timesave.pet 52

Uuid 68

specifying to use online commands 62user name

specifying 30using

configuration settings 58

Wwindows

PATROL Integration Configuration Utility 26


Index

Documents

SPECTRUM PATROL Integration Administrator Guide