Adapter for SiteScope...This document introduces the EMC Smarts Adapter for SiteScope, and describes configuration and operation of the Adapter. In addition, the guide briefly describes

EMC CorporationCorporate Headquarters:

Hopkinton, MA 01748-9103

1-508-435-1000www.EMC.com

EMC® Smarts®

Adapter for SiteScope1.1

User’s GuideP/N 300-004-005

REV A01

EMC Smarts Adapter for SiteScope User's Guideii

Copyright © 2005 - 2006 EMC Corporation. All rights reserved.EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com

All other trademarks used herein are the property of their respective owners.

Contents

Preface...................................................................................................................................................... v

Chapter 1 Introduction Overview................................................................................................................. 1-2

Architecture...................................................................................................... 1-2Event Processor................................................................................................ 1-3Alert Logger ..................................................................................................... 1-4Alert Processor ................................................................................................. 1-4Mapping notifications..................................................................................... 1-5SiteScope origin object identification............................................................ 1-5Event-to-Notification Processing .................................................................. 1-6Session monitoring .......................................................................................... 1-7

Deployment options.............................................................................................. 1-8

Chapter 2 Configuring the Adapter Deployment Prerequisites ........................................................................................................... 2-2 Configuration information ................................................................................... 2-3

Modifying Smarts configuration files........................................................... 2-3Location of configuration files ....................................................................... 2-3Customizing notification mapping............................................................... 2-4

Configuring the Adapter ...................................................................................... 2-5Configuring General Adapter Processing.................................................... 2-5Configuring the Event Processor .................................................................. 2-7Configuring the Alert Processor.................................................................... 2-8

Configuring Smarts event document templates ............................................. 2-10 Configuring the SiteScope platform.................................................................. 2-11

Copying the Alert Logger Script ................................................................. 2-11Configuring the Alert Logger process........................................................ 2-11Configuring the SiteScope GUI for log file processing ............................ 2-12Configuring the SiteScope GUI for script alert definition ....................... 2-12

Specifying the source Availability Managers .................................................. 2-13 Configuring the Adapter Platform.................................................................... 2-14

Adding a Domain section to the icoi.conf file ........................................... 2-14Forcing the Adapter Platform to re-process the icoi.conf file ................. 2-15

Defining system defaults .................................................................................... 2-16

EMC Smarts Adapter for SiteScope User's Guide iii

Contents

Chapter 3 Working with the Adapter Service Working with the Service Script.......................................................................... 3-2

Customizing the script variables .................................................................. 3-2Controlling the Adapter service ................................................................... 3-3Manually installing and uninstalling the Adapter service ....................... 3-3

Verify the EMC Smarts product status............................................................... 3-4

Chapter 4 Working with the Adapter in Non-Service Mode The ic-sitescope-adapter script............................................................................ 4-2

Customizing ic-sitescope-adapter script variables .................................... 4-2Controlling the adapter.................................................................................. 4-2

Chapter 5 Failure Scenarios Logging for Failure to Create Notifications and Topology ............................. 5-4 Types of Failure Scenario ..................................................................................... 5-5

SiteScope Server is Down .............................................................................. 5-5Adapter is Down............................................................................................. 5-5

Appendix A Default Mapping of Event Fields to Attributes

Appendix B SiteScope Monitor Types

Appendix C Working with AlertsProcessing overview ............................................................................................ C-2

Summary of alert processing tasks............................................................. C-2Implementing alert templates for processing SiteScope alerts ...................... C-3

Sample SiteScope alert template ................................................................. C-3Creating a script alert definition ........................................................................ C-4Defining a corresponding Smarts event document ......................................... C-5

Appendix D Special Handling for NoData AlertsTemplate for handling NoData alerts ................................................................ D-2Sample NoData.conf event document .............................................................. D-3Configuration parameter that controls NoData handling ............................. D-4

Appendix E Understanding the sm_edit Utility

Index ....................................................................................................................................................... i-1

EMC Smarts Adapter for SiteScope User's Guideiv

Preface

This document introduces the EMC Smarts Adapter for SiteScope, and describes configuration and operation of the Adapter. In addition, the guide briefly describes how events and topology from Mercury SiteScope are mapped to objects in the EMC Smarts Common Information Model for display as notifications in the Global Console.

Audience for this guideThis guide is intended for individuals responsible for installing and configuring the Adapter.

PrerequisitesTo deploy and configure the Adapter, you should be familiar with SiteScope.

EMC Smarts SAM Adapters Suite and Report Manager installation directoryIn this document, the term BASEDIR represents the location where EMC Smarts software is installed.

◆ For UNIX, this location is: /opt/InCharge<n>/<productsuite>.

◆ For Windows, this location is: C:\InCharge<n>\<productsuite>.

The <n> represents the software platform version number. The <productsuite> represents the EMC Smarts product suite to which the product belongs. For example, on UNIX operating systems, the EMC Smarts SAM Adapters Suite and Report Manager is, by default, installed to /opt/InCharge7/SAM/smarts. On Windows operating systems, this product is, by default, installed to: C:\InCharge7\SAM\smarts. This location is referred to as BASEDIR/smarts.

Optionally, you can specify the root of BASEDIR to be something other than /opt/InCharge7 (on UNIX) or C:\InCharge7 (on Windows), but you cannot change the <productsuite> location under the root directory.

For more information about the directory structure of EMC Smarts software, refer to the EMC Smarts System Administration Guide.

EMC Smarts SAM Adapters Suite and Report Manager productsThe SAM Adapters Suite and Report Manager offers the following products:

◆ EMC Smarts Adapter for BMC Patrol

◆ EMC Smarts Adapter for Concord eHealth

◆ EMC Smarts Adapter for HP-OVO/U

EMC Smarts Adapter for SiteScope User's Guide v

Preface

◆ EMC Smarts Adapter for InfoVista VF2

◆ EMC Smarts Adapter for Microsoft Operations Manager 2005

◆ EMC Smarts Adapter for NetIQ AppManager

◆ EMC Smarts Adapter for Remedy ARS

◆ EMC Smarts SQL Data Interface Adapter

◆ EMC Smarts Adapter for SiteScope

◆ EMC Smarts Report Manager

Related documentationIn addition to this document, EMC Corporation provides a Help system for command line programs as well as product documentation.

Help for command line programsDescriptions of command line programs are available as HTML pages. The index.html file, which provides an index to the various commands, is located in the BASEDIR/smarts/doc/html/usage directory.

EMC Smarts documentationReaders of this guide may find the following related documentation helpful. It can be found in the BASEDIR/smarts/doc/pdf directory.

Note: These documents are updated periodically. Electronic versions of the updated manuals are available on the Powerlink website:http://Powerlink.EMC.com.

◆ EMC Smarts Documentation Catalog

◆ EMC Smarts System Administration Guide

◆ EMC Smarts ICIM Reference

◆ EMC Smarts Common Information Model Infrastructure Models Chart

◆ EMC Smarts Common Information Model Application⁄Business Models Chart

◆ EMC Smarts ASL Reference Guide

◆ EMC Smarts Perl Reference Guide

◆ EMC Smarts Dynamic Modeling Tutorial

◆ EMC Smarts MODEL Reference Guide

EMC Smarts SAM Adapters Suite and Report Manager DocumentationThe following documents are relevant to the SAM Adapters Suite and Report Manager:

◆ EMC Smarts Adapter for BMC Patrol User’s Guide

◆ EMC Smarts Adapter for Concord eHealth User’s Guide

◆ EMC Smarts Adapter for HP-OVO/U User’s Guide

◆ EMC Smarts Adapter for InfoVista VF2 User’s Guide

◆ EMC Smarts Adapter for Microsoft Operations Manager User’s Guide

◆ EMC Smarts Adapter for NetIQ AppManager User’s Guide

◆ EMC Smarts Adapter for Remedy ARS User’s Guide

EMC Smarts Adapter for SiteScope User's Guidevi

http://Powerlink.EMC.com

Preface

◆ EMC Smarts SQL Data Interface Adapter User’s Guide

◆ EMC Smarts Adapter for SiteScope User’s Guide

◆ EMC Smarts Report Manager User’s Guide

◆ EMC Smarts SAM Adapters Suite and Report Manager Installation Guide

◆ EMC Smarts Adapters Event-to-Notification Tutorial

EMC Smarts Service Assurance Management SuiteThe following documents are relevant to users of the EMC Smarts Service Assurance Management Suite:

◆ EMC Smarts Service Assurance Manager Introduction

◆ EMC Smarts Service Assurance Management Suite Deployment Guide

◆ EMC Smarts Service Assurance Management Suite Installation Guide

◆ EMC Smarts Service Assurance Management Suite Migration Guide

◆ EMC Smarts Service Assurance Manager Operator’s Guide

◆ EMC Smarts Service Assurance Manager Configuration Guide

◆ EMC Smarts Service Assurance Manager Dashboard Configuration Guide

◆ EMC Smarts Business Impact Manager User’s Guide

◆ EMC Smarts Service Assurance Manager Failover System User’s Guide

◆ EMC Smarts Service Assurance Manager Adapter Platform User’s Guide

◆ EMC Smarts Service Assurance Manager Notification Adapters User’s Guide

◆ EMC Smarts XML Adapter User’s Guide

Refer to the EMC Smarts Documentation Catalog for documentation resources provided with other EMC Smarts product suites.

Suggestions for searching PDF filesYou may search across multiple PDF files using the Adobe Acrobat Reader software.

1. If the documentation is not accessible to all users of the EMC Smarts product suite, copy the contents of the BASEDIR/smarts/doc/pdf directory to a central location, such as a shared drive on your LAN, that operators and others may view.

2. To search throughout the documentation library, open the Acrobat Reader software.

1. Choose Edit > Search, and enter a word or phrase.

2. In the Where would you like to search option, select All PDF Documents in and type the pathname of the location where the PDF documents reside.

If you have more than one EMC Smarts product suite installed, you can set up cross-product document searches by copying files from the BASEDIR/smarts/doc/pdf directory for each product suite into this common documentation directory path.

Conventions used in this guideEMC uses the following conventions for notes and cautions.

Note: A note presents information that is important, but not hazard-related.

EMC Smarts Adapter for SiteScope User's Guide vii

Preface

IMPORTANT!An important notice contains information essential to the operation of the software.

CAUTION!A caution contains information essential to avoid data loss or damage to the system or equipment. The caution may apply to hardware or software.

Typographical conventionsEMC uses the following conventions in this guide:

Normal font In running text:• Interface elements (for example, button names, dialog box names) outside of

procedures• Items that the user selects outside of procedures• Java classes and interface names• Names of resources, attributes, pools, Boolean expressions, buttons, DQL

statements, keywords, clauses, environment variables, filenames, functions, menu names, utilities

• Pathnames, URLs, filenames, directory names, computer names, links, groups, service keys, file systems, environment variables (for example, command line and text), notifications

Bold In procedures:• Names of dialog boxes, buttons, icons, menus, fields, and maps• Selections from the user interface, including menu items, and field entries• Key names• Window names• Code examples• Commands• User interface tabs

Italic Used for:• Full publications titles referenced in textIn procedures:• Directory paths• Filenames• Scripts• Important/unique words• URLs• Utilities• Variables

Courier Used for:• System output• User entry

< > Angle brackets used to enclose parameter or variable values supplied by the user.

[ ] Square brackets used to indicate optional values.

| Vertical bar used to indicate alternate selections. The bar means “or”.

{ } Braces used to indicate content that you must specify (that is, x or y or z).

... Ellipses used to indicate nonessential information omitted from the example.

EMC Smarts Adapter for SiteScope User's Guideviii

Preface

Pathname conventionsDirectory pathnames are shown with forward slashes (/). Users of the Windows operating systems should substitute back slashes (\) for forward slashes.

Graphical conventionsIf there are figures illustrating consoles in this document, they represent the consoles as they appear in Windows. Under UNIX, the consoles appear with slight differences. For example, in views that display items in a tree hierarchy such as the Topology Browser, a plus sign displays for Windows and an open circle displays for UNIX.

Smarts ManagerUnless otherwise specified, the term Smarts Manager is used to refer to EMC Smarts programs such as Domain Managers, Global Managers, and adapters.

Where to get helpEMC support, product, and licensing information can be obtained as follows.

Product information — For documentation, release notes, software updates, or for information about EMC products, licensing, and service, go to the EMC Powerlink™ website (registration required) at:

http://Powerlink.EMC.com

Technical support — For technical support, go to EMC Customer Service on Powerlink. To open a service request through Powerlink, you must have a valid support agreement. Please contact your EMC sales representative for details about obtaining a valid support agreement or to answer any questions about your account.

Sales and customer service contacts — For the list of EMC sales locations, please access the EMC home page at:

http://EMC.com/contact

% Used to indicate a C shell prompt.

# Used to indicate a C shell superuser prompt.

▼▲ Used to indicate a command is wrapped over one or more lines. The command must be typed as one line.

EMC Smarts Adapter for SiteScope User's Guide ix

http://powerlink.emc.com

Preface

EMC Smarts Adapter for SiteScope User's Guidex

1

This chapter contains the following information:

◆ Overview ........................................................................................................................ 1-2◆ Deployment options ..................................................................................................... 1-8

Introduction

Introduction 1-1

Introduction

OverviewMercury SiteScope is an enterprise management tool for monitoring a large number of software products such as operating systems (Microsoft Windows, UNIX, Linux), databases (Oracle, MS-SQL, DB2), web servers, and more. SiteScope gathers information in the following ways:

◆ SiteScope maintains daily logs that record simple binary or thresholded events reporting on the availability of components in the infrastructure.

◆ SiteScope runs user-defined monitor scripts on monitored elements, creating alerts that use more powerful time-based detection of sequences of failures in order to derive more detailed alerts.

The EMC Smarts Adapter for SiteScope extracts both events and custom alerts from SiteScope and translates them into EMC Smarts notifications and topology. Using topology optionally imported from the EMC Smarts Availability Manager, the Adapter translates the SiteScope system identifiers such as router and host names into the UnitaryComputerSystem object references understood by all EMC Smarts Managers.

These notifications and topology may in turn be imported into the EMC Smarts Adapter Platform for use by other EMC Smarts Managers such as the Global Manager for display in the Global Console or EMC Smarts Application Insight for use in application root cause analysis.

ArchitectureThe Adapter processes two distinct event streams:

◆ SiteScope events

◆ SiteScope monitor alerts

Note: Each event stream is configured and processed independently.

To process events and alerts, the Adapter includes the following components:

◆ Event Processor

◆ Alert Logger

◆ Alert Processor

Figure 1-1 shows these components communicating with SiteScope and the EMC Smarts Adapter Platform and IP Availability Manager.

EMC Smarts Adapter for SiteScope User's Guide1-2

Introduction

.

Figure 1-1 SiteScope Adapter architecture

Event ProcessorThe Event Processor reads and processes the SiteScope daily log file, converting events to notifications. The Event Processor reads and processes events from the log file sequentially as they are entered, in the manner of the UNIX “tail” utility.

◆ Once daily or as configured, the Event Processor retrieves the daily log file from SiteScope

◆ The Event Processor determines whether there is an object in the repository for this element:

• If yes, the Processor creates a notification (maps the event properties to the notification fields, as configured) and sends the notification to the Adapter Platform for forwarding to the Global Manager.

• If no, the Processor optionally instantiates the object and then creates and forwards a notification to the Adapter Platform for distribution to the appropriate Domain Managers.

The Event Processor converts individual data fields to notification attributes, according to default or user-defined mapping information. Through the use of configurable notification templates, notification properties can be constructed from the event data fields to create notifications that accurately convey the meaning of the original SiteScope event.

In addition, the Event Processor can be configured to dynamically create topology that includes applications and to run user-defined scripts to perform customized parsing and processing tasks.

When SiteScope produces a new log file, the Event Processor switches automatically to it, and then processes the events contained in the new file.

SiteScope log filesWhen SiteScope runs an event monitor instruction to test monitored element availability, the monitor results are written to data log files. In the default configuration, these log files are tab-delimited text files. By default, SiteScope monitor results are saved to a new log file daily on an automated switchover basis. This

MS-MOM

Global Manager Adapter Platform

Alert Logger

Queue Files

SiteScope

Adapter for SiteScope

IP Availability Manager

Alert Processor

Event Processor

Daily Logs

Overview 1-3

Introduction

option allows creation of a new log file every day at midnight. The log file can also be configured to grow as new data is added, with no pre-defined stopping point.

Table 1-1 shows the standard initial columns of a log entry in a SiteScope monitor log file. These columns are the same for each monitor type; after these columns, however, the columns may vary according to monitor type.

“SiteScope Monitor Types” on page B-1 lists the SiteScope monitors and filenames used by the Adapter to create notifications.

Alert LoggerThe Alert Logger is used with specially formatted SiteScope alert templates to transfer information from SiteScope user-defined script alerts to the Smarts Alert Processor. When a monitored alert condition occurs, the user-defined SiteScope script alert is triggered causing the associated SiteScope alert template to be expanded by SiteScope to produce a formatted temporary file containing the alert information. The SiteScope Script Alert then runs the Smarts Alert Logger, which enqueues the file data for processing by the Adapter. The Alert Logger enqueues all alerts in intermediate queue files for processing by the Alert Processor. This ensures that SiteScope events are not lost even if Alert Processor execution is interrupted.

The Alert Logger operates independently of the Alert Processor.

Alert ProcessorThe Alert Processor reads and processes events from the queue file sequentially as they are entered in the manner of the UNIX “tail” utility. It deletes old queue files once all events have been processed and the Alert Logger has begun writing to a new queue file. This procedure performs automatic housekeeping, ensuring that queue files contain unprocessed event content only.

Table 1-1 Initial columns of SiteScope monitor log files

Column Content Description

1 Time and date Time and date the sample was recorded.

2 Current status of monitor Options:• nodata• good• warning• errorFor information about the "nodata" status, see “Special Handling for NoData Alerts” on page D-1

3 Monitor group name Name of the group to which the monitor belongs (also called ownerID)

4 Monitor name Monitor title text

5 StateString Current reading (this is the status string on the Monitor Group Detail Page).

6 Monitor ID and Sample number

Unique to each entry


Introduction

◆ The Alert Logger retrieves an alert event from SiteScope and places it in a file in the Message Queue.

◆ The Alert Processor retrieves the file from the message queue and determines whether there is an object in the repository for this element:

• If yes, the Processor creates a notification (maps the event properties to the notification fields, as configured) and sends the notification to the Adapter Platform for forwarding to the Global Manager.

• If no, the Processor optionally instantiates the object and then creates and forwards a notification to the Adapter Platform for distribution to the appropriate Domain Managers.

The Alert Processor translates each SiteScope event into an EMC Smarts notification. The Processor converts individual data fields to notification attributes, according to default or user-defined mapping information. Through the use of configurable notification templates, notification properties can be constructed from the event data fields to create notifications that accurately convey the meaning of the original SiteScope event.

In addition, the Adapter can be configured to dynamically create topology that includes applications and to run user-defined scripts to perform customized parsing and processing tasks.

Mapping notificationsThe Adapter uniquely identifies a notification by the following distinguishing attributes:

◆ Class

◆ Instance

◆ Event

Other attributes provide important status and informational data. For default mapping, see “Default Mapping of Event Fields to Attributes” on page A-1.

SiteScope origin object identificationThe SiteScope monitoring log files do not identify the origin object for events. Origin objects include hardware, such as a CPU, and software, such as a script or a service. In order to identify the origin object of the event, the Adapter uses the following file types:

◆ *.mg files: For each monitor group created by the user in the local SiteScope installation, there is a <monitor_group_name.mg> file that contains settings for individual monitors and the group in which they are contained.

◆ master.config file: Main SiteScope configuration file.

In addition, the Adapter uses a hash table to map individual monitor settings (identified by group_name or monitor_id) to IP addresses or hostnames.

Upon startup, the Adapter loads all of the monitor settings to the hash table. During operation, the Adapter updates the hash table in the following cases:

◆ The master.config file has changed from the last reading

◆ The requested monitor does not exist in the hash table.

Overview 1-5

Introduction

The adapter loads and maintains all of the origin objects to memory. The adapter correlates between one of the above properties and EMC Smarts object identification in order to assign the event to the appropriate object in the repository.

SiteScope uses two formats for the origin object: IP address or computer hostname.

Event-to-Notification ProcessingAn important feature of the Processors is the event document that includes the notification templates and template selection rules that together determine how the Adapter maps SiteScope events to notifications. These components function as follows:

◆ Notification Template—Describes the mapping from an SiteScope event into an EMC Smarts notification.

◆ Template Selection Rule—Selects the notification template that is appropriate for the particular event.

Note: This section provides a brief overview of event processing. The EMC Smarts Adapters Event-to-Notification Tutorial provides detailed explanations and configuration information.

Notification templatesEach template defines formulas for assembling data source system fields into notification attributes. The Adapter obtains values from one of these four sources:

◆ User-defined

◆ Imported event data

◆ Adapter-derived

◆ Script processing results

Notification templates can inherit property values from other templates, and can be configured to override inherited values. Use of notification templates can simplify administration of mapping of events to notifications, particularly in situations where many events generate similar notifications. For information about customizing the notification templates, see the EMC Smarts Adapters Event-to-Notification Templates Tutorial.

Selection rulesWhen the Alert Processor receives an event, it parses the message and then applies selection rules to determine which notification template applies. Selection rules compare and match data in an event in order to select the template to apply. When a match is found, the template is used to process the event and create a notification. If no rule matches and no additional mapping template is provided, the event is discarded.


Introduction

Session monitoringThe Adapter internally monitors sessions between the Event Logger and SiteScope, and between SiteScope and its agents, which monitor network elements. In addition, the Adapter Platform monitors the session with the Adapter.

The Adapter generates “Session disconnect” notifications if any of these sessions are disrupted, alerting the operator to connectivity problems. These notifications also allow Application Insight to adjust its analysis to compensate for suspect notifications, ensuring the best possible root cause analysis in all cases of connectivity loss, even those within SiteScope itself.

Overview 1-7

Introduction

Deployment optionsThe Adapter provides a variety of configuration files to address many standard SiteScope alerts and monitor events. A particular installation may be configured to use any or all of these options. In addition, these basic configurations may be customer-modified to alter the default behavior or to provide specialized handling for particular events.

The configuration files are designed to produce meaningful notifications for broad classes of events. Each category of alerts and monitor events is handled by a separate configuration file to simplify setup, versioning, and administration. Because of this, there is no specific list of supported alerts and events. Additionally, new files may be implemented to address new categories of alerts and events or to replace the pre-defined configuration files.

The Event and Alert processing capabilities of the Adapter are separate and distinct; it is essentially two adapters in one. The Event and Alert processors may be individually enabled or disabled, are individually configured, and use separate event documents. This affords means for the Adapter deployment to be matched to the particular SiteScope features used by a particular customer.


2

This chapter includes the following information:

◆ Prerequisites................................................................................................................... 2-2◆ Configuration information........................................................................................... 2-3◆ Configuring the Adapter.............................................................................................. 2-5◆ Configuring Smarts event document templates..................................................... 2-10◆ Configuring the SiteScope platform......................................................................... 2-11◆ Specifying the source Availability Managers .......................................................... 2-13◆ Configuring the Adapter Platform ........................................................................... 2-14◆ Defining system defaults............................................................................................ 2-16

Configuring theAdapter Deployment

Configuring the Adapter Deployment 2-1

Configuring the Adapter Deployment

PrerequisitesTo deploy and configure the Adapter, you should be familiar with SiteScope.

The following software must be installed before you configure the Adapter:

◆ Mercury SiteScope

◆ EMC Smarts Adapter for SiteScope. For installation information, see the EMC Smarts SAM Adapters Suite and Report Manager Installation Guide.

◆ Other required EMC Smarts applications: Service Assurance Management components, including

• Global Manager

• Global Console,

• Adapter Platform with Trap Manager.

For installation information, see the EMC Smarts Service Assurance Management Suite Installation Guide.

◆ Optionally, EMC Smarts IP Availability Manager. For installation information, see the EMC Smarts IP Management Suite Installation Guide.



Configuration informationThis section provides information for configuration tasks.

Modifying Smarts configuration filesTo edit Smarts configuration files, use the Smarts sm_edit command. For example, to open and modify the default adapter.conf file on UNIX, enter the following command from BASEDIR/smarts/bin:

# ./sm_edit conf/sitescope/adapter.conf

“Understanding the sm_edit Utility” on page E-1 describes the Smarts utility for editing local copies of configuration files.

Location of configuration filesThere are two event streams, Events and Alerts, which must be individually configured by means of three primary configuration files (adapter.conf, event.conf, and alert.conf) and a number of supporting hookscripts. For each processing stream, the Adapter uses two main configuration files (adapter.conf and event.conf) and a number of supporting hookscripts. In addition to the configuration files, the Adapter command-line utilities, ic-sitescope-service.cmd and ic-sitescope-adapter.cmd, must be configured before they can be used.

Table 2-1 provides the locations of the configuration files and scripts.

Table 2-1 SiteScope configuration files and scripts

Configuration file Description

BASEDIR/smarts/bin/sm_sitescopereadevents Event Processor file for processing events

BASEDIR/smarts/conf/sitescope/install/sm_sitescopewritealerts Alert Logger file for writing alerts to the queue files

BASEDIR/smarts/conf/sitescope/bin/sm_sitescopereadalerts Alert Processor file for processing alerts

BASEDIR/smarts/scripts/For UNIX:• ic-sitescope-service• ic-sitescope-adapterFor Windows:• ic-sitescope-service.cmd• ic-sitescope-adapter.cmd

Adapter service installation utility and start/stop utility.

BASEDIR/smarts/conf/ics/sitescope/adapter.conf Primary adapter configuration file.

BASEDIR/smarts/conf/ics/sitescope/event.conf Configuration file defining processing of each imported event. Describes event-to-notification template mapping.

BASEDIR/smarts/conf/ics/sitescope/alert.conf Configuration file defining processing of each imported alert. Describes alert-to-notification template mapping.

BASEDIR/local/rules/sitescope/hook/*.asl Adapter hookscripts invoked by notification templates.

Configuration information 2-3


Customizing notification mappingTo complete your deployment, you can customize mapping of SiteScope event and alert fields to the EMC Smarts notification attributes that are displayed in the Global Console. For detailed information about customizing the notification templates and working with the log files to test your customized deployment, see the EMC Smarts Adapters Event-to-Notification Templates Tutorial.



Configuring the AdapterThe main configuration file for the Adapter is adapter.conf. It includes the configuration parameters for the following:

◆ The Adapter itself (general adapter processing)

◆ Event Processor

◆ Alert Processor

Configuring General Adapter ProcessingThe following sections discuss configuration of the adapter.conf file. This file addresses general configuration of the Adapter and specific configuration of the Event and Alert processors. Figure 2-1 shows a schematic of the structure of the file. The three leading sections must be configured for all installations; each of the last major sections need only be configured if the associated event or alert stream is to be processed.

AdapterSection { }

SystemDefaultsSection { }

FilterSection { }

MonitorSection { ControlSection { } EventDocumentSection { } LogControlSection { }}

AlertSection { ControlSection { } EventDocumentSection { } LogControlSection { }}

Figure 2-1 Schematic of the adapter.conf file

To configure general SiteScope Adapter processing, edit the adapter.conf file and optionally change any of the parameters listed in Table 2-2, as needed for your deployment. Note that the adapter.conf file includes additional information about each of these parameters.

To edit the file, at BASEDIR/smarts/bin, issue the following command:


Table 2-2 Notification Processor configuration parameters

Parameter Description Default value

Adapter

SiteScope to EMC Smarts Severity Mapping severityMap_error = 1severityMap_warning = 3severityMap_good = 5

notificationExpirationDelay Notification Expiration Time in seconds 28800

Configuring the Adapter 2-5


epochRetryDelay Time in seconds to delay before attempting major error recovery

60

enableNotifiedElementCreation Enable creation of notified objects false

enableNotificationAggregation Enable creation of Aggregate Notifications true

sitescopeInstallationPath SiteScope home directory path /opt/SiteScope

System Defaults Section

serverAttachDelay Server Attach Delay 2400

serverDetachDelay Server Detach Delay 2400

Filter Section

acceptEventsFromUnknownHosts Accept Events from Unknown Hosts false

includedHostGlobExpr = "*";excludedHostGlobExpr = ""

Hostname inclusion/exclusion glob expressions matches allmatches none

Table 2-2 Notification Processor configuration parameters

Parameter Description Default value



Configuring the Event ProcessorTo configure the Event Processor, edit the adapter.conf file and optionally change any of the parameters listed in Table 2-3, as needed for your deployment. Note that the adapter.conf file includes additional information about each of these parameters.


# ./sm_edit conf/sitescope/adapter.conf.

Table 2-3 Event Processor configuration parameters

Parameter Name Description Default value

Control Section

enableEventImport Enable import of SiteScope Monitor Events

true

sitescopeSessionLossHeartbeatDelay

SiteScope Monitor Session loss heartbeat delay in seconds

600

sitescopeLogPollTime Time in seconds between polls of SiteScope Log

10

sitescopeMonitorGroupFilePollTime Time in seconds between reads of SiteScope Monitor Group files

900

syncTimePeriodDays Number of log files of historical events to read on Adapter startup

1

useSitescopeDailyLogs Use SiteScope Daily Logs true

Event Document Section

eventConfFile Name of Event Document file to configure Event to Notification translation

"event/Event.conf"

rootEventDocument Name of Event Document at which to begin the Notification Template search

Event

User-defined values for use in Selection Rules and Notification Templates

conf1 = "<CONF1>";conf2 = "<CONF2>";conf3 = "<CONF3>";conf4 = "<CONF4>";conf5 = "<CONF5>";conf6 = "<CONF6>";conf7 = "<CONF7>";conf8 = "<CONF8>";conf9 = "<CONF9>";conf10 = "450"## controls "no data" Notif expiration

Log Control Section

enableLogRawEvents Enable Raw Event Logging false

enableMissingUcsLogging Enable Missing UCS Event Logging false

enableUndefinedTemplateLogging Enable Undefined Template Logging

false



Configuring the Alert ProcessorTo configure the Alert Processor, edit the adapter.conf file and optionally change any of the parameters listed in Table 2-3, as needed for your deployment. Note that the adapter.conf file includes additional information about each of these parameters.



enableTemplateLogging Enable Template logging false

enableEventLogging Enable Event Logging false

enableEventDetailLogging Enable Event Detail Logging false

enableProposedNotifLogging Enable Proposed Notification Logging

false

enableRejectedNotifLogging Enable Rejected Notification Logging

false

enableAggregateLogging Enable Aggregate Notification Logging

false

enableHookScriptResultLogging Enable Hook Script Logging false

enableTemplateSelectionTrace Enable Template Selection Trace false

Table 2-3 Event Processor configuration parameters (continued)


Table 2-4 Alert Processor configuration parameters


Control Section

enableEventImport Enable import of SiteScope Alert Events

true

sitescopeSessionLossHeartbeatDelay Alert Session loss heartbeat delay in seconds

600

eventQueueFileDir Distinguished name of directory in which to place event queue files

<SMARTS_BASEDIR>/local/logs/event-queue-<adapterDomain>

Event Document Section

eventConfFile Name of Event Document file to configure Event to Notification translation

"event/Alert.conf"

rootEventDocument Name of Event Document at which to begin the Notification Template search

Alert



User-defined values for use in Selection Rules and Notification Templates

conf1 = "<CONF1>";conf2 = "<CONF2>";conf3 = "<CONF3>";conf4 = "<CONF4>";conf5 = "<CONF5>";conf6 = "<CONF6>";conf7 = "<CONF7>";conf8 = "<CONF8>";conf9 = "<CONF9>";conf10 = "450"## controls "no data" Notif expiration

Log Control Section

enableLogRawEvents Enable Raw Event Logging false

enableMissingUcsLogging Enable Missing UCS Event Logging false

enableUndefinedTemplateLogging Enable Undefined Template Logging false

enableTemplateLogging Enable Template logging false

enableEventLogging Enable Event Logging false

enableEventDetailLogging Enable Event Detail Logging false

enableProposedNotifLogging Enable Proposed Notification Logging false

enableRejectedNotifLogging Enable Rejected Notification Logging false

enableAggregateLogging Enable Aggregate Notification Logging

false

enableHookScriptResultLogging Enable Hook Script Logging false

enableTemplateSelectionTrace Enable Template Selection Trace false

Table 2-4 Alert Processor configuration parameters (continued)




Configuring Smarts event document templates Processing of SiteScope events and alerts is handled by separate sets of event documents. By default, the top level documents are event.conf and alert.conf respectively. For each alert, configure an EMC Smarts event document template for the Alert Processor to use when converting the alert data into a notification. You can use the default templates, or configure new templates. The EMC Smarts Adapters Event-to-Notification Tutorial provides detailed information about working with event documents.



Configuring the SiteScope platformAfter installing the Adapter software on the SiteScope host, configure SiteScope as follows:

◆ “Copying the Alert Logger Script” on page 2-11

◆ “Configuring the Alert Logger process” on page 2-11

◆ “Configuring the SiteScope GUI for log file processing” on page 2-12

◆ “Configuring the SiteScope GUI for log file processing” on page 2-12

◆ “Configuring the SiteScope GUI for script alert definition” on page 2-12

Copying the Alert Logger ScriptCopy the Alert Logger (sm_sitescopewritealerts process) files (the application and the configuration files) from the Adapter installation directory to the SiteScope directories, as follows.

1. At BASEDIR/smarts/bin/system, issue the following command to copy the Alert Logger application:

cp sm_sitescopewritealerts /SiteScope-BASEDIR/scripts/

2. At BASEDIR/smarts/conf, issue the following command to copy the Alert Logger configuration file:

cp sm_sitescopewritealerts.conf /SiteScope-BASEDIR/scripts/

3. Save and close the file.

Configuring the Alert Logger processAfter copying the files, configure the Alert Logger to specify where the Alert Logger places alerts from SiteScope. You may use the default values, or change them to suit your deployment needs.

To configure the Alert Logger process,

1. At BASEDIR/smarts/bin, issue the following command.

# ./sm_edit SiteScope-BASEDIR/scripts/sm_sitescopewritealerts

2. Optionally, change any of the parameters listed in Table 2-5, as needed for your deployment.

If necessary, change the UNIX executable permissions for the sm_sitescopewritealerts process; for example, chmod +x.

Table 2-5 Alert Logger configuration parameters


baseDirInCharge Adapter installation directory /opt/InCharge7/SAM/smarts

adapterDomainName Adapter domain name SITESCOPE

Configuring the SiteScope platform 2-11


Configuring the SiteScope GUI for log file processingConfigure the SiteScope GUI to control log file functions, such as which of the following options will be in effect:

◆ New log file created daily on an automated switchover basis

◆ Single log file grows as new data is added, with no pre-defined stopping point

To configure SiteScope log functions:

1. At SITESCOPEBASEDIR/groups, edit the master.config file using any editor.

2. Configure the parameters listed in Table 2-6, as needed for your deployment.

Configuring the SiteScope GUI for script alert definitionFor each alert, you configure a SiteScope script alert to invoke the Alert Logger application, which enqueues the alert in the queue files for processing by the Alert Processor. You can use the default templates, or configure new templates. “Creating SiteScope Script Alerts” on page D-1 provides information.

eventQueueFileDirPrefix Distinguished name of directory in which to place alert queue files

/local/logs/event-queue-

eventQueueBaseFilename Base file name of the queue files. sm_sitescopewritealerts.output

outputMaxLimit Limit in bytes for output file size Typically: 10000000

Table 2-5 Alert Logger configuration parameters


Table 2-6 master.config file

Parameter Description Default Value

SiteScope Lof file Preferences (controls the amount of SiteScope monitor data that is saved on the SiteScope server. )

dailyLogKeepDays the number of days of log information to keep before deleting old logs

40

dailyLogTotalLimit the maximum total size in bytes of primary log data before old logs are deleted

blank

Single Log File (using the single log file mode the following parameters control this log file)

_dailySiteScopeLogs Set to true to create a new, date-coded log file every day. Leave empty to write to SiteScope.log only.

true

_logKeepDays If daily logs are disabled, the number of days of data to keep in the main data log.

0

_maxLogSize If daily logs are disabled, the maximum size in bytes of the main log. Logs may grow beyond this size, and are then deleted at SiteScope restart. An empty log is then opened for use.

16000000



Specifying the source Availability ManagersUsing topology optionally imported from the EMC Smarts IP Availability Manager, the Adapter translates the SiteScope system identifiers such as router and host names into the UnitaryComputerSystem object references understood by all EMC Smarts Managers.

Note: Communications between EMC Smarts Domain Managers and the Global Manager should comply with current security best practices as supported by existing EMC Smarts solutions. The EMC Smarts System Administration Guide provides detailed information about EMC Smarts secure communications.

Specify one or more EMC Smarts IP Availability Managers from which to import the topology.

1. At BASEDIR/smarts/bin, issue the following command:

# ./sm_edit conf/sitescope/system.conf

2. Find the DomainType definition in the file and add a DomainType entry for each source Availability Manager. The portion of the system.conf file relevant to this discussion is shown in the following code snippet.

DomainSection{# DomainType { ConfFile = "dxa-ucsip.conf"; MinimumCertainty = 0.0; SmoothingInterval = 0; Name = "INCHARGE-AM"; }}

3. Set the Name field to the name of your Availability Manager instance; for example, INCHARGE-AM.

Note: You can use the default Availability Manager name and dxa filename, as shown.

4. Edit the MinimumCertainty and SmoothingInterval fields, as necessary for your deployment.

5. Save the system.conf file. The modified version of the file is saved to the BASEDIR/smarts/local/conf/sitescope directory in the Global Manager installation area.

Note: Availability Managers listed in the DomainSection of the system.conf file should match those listed in the DomainSection of the Global Manager’s ics.conf file. Do not add the Global Manager to the DomainSection of system.conf.

Specifying the source Availability Managers 2-13


Configuring the Adapter PlatformYou add a reference in the DomainSection of icoi.conf for the Adapter and for each IP Availability Manager you use as a source of topology.

Adding a Domain section to the icoi.conf fileTo edit the configuration file, use the EMC Smarts sm_edit command. For information about sm_edit, see “Understanding the sm_edit Utility” on page E-1.

1. At BASEDIR/smarts/bin, issue the following command:

# ./sm_edit conf/icoi/icoi.conf

2. Find the DomainType definition in the file and add a DomainType entry for each Availability Manager you use as a source of topology. In addition, add a DomainType entry for the Adapter.

The portion of the icoi.conf file relevant to this discussion is shown in the following display.

DomainSection{

DomainType { ConfFile = "dxa-ucsip.conf"; MinimumCertainty = 0.0; SmoothingInterval = 0; Name = "INCHARGE-AM";

}

DomainType { ConfFile = "dxa-sitescope.conf"; MinimumCertainty = 0.0; SmoothingInterval = 0; Name = "SITESCOPE"; }}

Note: Availability Managers listed in the DomainSection of the icoi.conf file should match those listed in the DomainSection of the Global Manager’s ics.conf file.

For dxa-sysip.conf:

• Set the Name field to the name of your Availability Manager instance; for example, INCHARGE-AM.

• Edit the MinimumCertainty and SmoothingInterval fields, as necessary for your deployment.

For dxa-sitescope.conf:

• Set the Name field to the name of your Adapter for SiteScope instance; for example, SITESCOPE.

• Edit the MinimumCertainty and SmoothingInterval fields, as necessary for your deployment.

3. Save the icoi.conf file. The modified version of the file is saved to the BASEDIR/smarts/local/conf/icoi directory in the Global Manager installation area.

4. Force the Adapter Platform to read the modified file, as described below.



Forcing the Adapter Platform to re-process the icoi.conf fileAt startup, the Adapter Platform reads the icoi.conf file and subscribes to the topology and notifications specified in the file.

If you make any change in the icoi.conf file known to a running Adapter Platform, enter the following command (on one line) to force the Adapter Platform to re-read its ics.conf file:

▼/opt/InCharge7/SAM/smarts/bin> sm_adapter -s <Adapter Platform Instance Name> /ics/ICS_RemoteConfig.asl▲

Note: ▼ ▲ Indicates that the command must be typed as one line.

For more information about the icoi.conf file, see the EMC Smarts Service Assurance Manager Adapter Platform User’s Guide.

Configuring the Adapter Platform 2-15


Defining system defaultsSystem defaults are system-wide settings that affect the Adapter and the notifications created by clients. There are three system default settings, all of which are specified in the SystemDefaultsSection of the system.conf file.

When specifying system defaults, keep in mind that events created in the Adapter Platform are not directly accessible. The Adapter Platform is used to normalize data so that it can propagate to and be managed from the Global Manager. Note that the same set of system defaults are also configurable for the Global Manager using the ics.conf file.

The following example illustrates the syntax of the SystemDefaultsSection.

SystemDefaultsSection{ # After how many seconds should an unowned inactive event # be automatically acknowledged? # AutoAcknowledgementInterval = 300;

# After how many seconds should an inactive acknowledged # event be archived? # InactiveAutoArchiveInterval = 14400;

# How large can the audit trail for a notification grow # before half of its contents are archived? # AuditTrailSizeLimit = 0; }

Table 2-7 describes the fields of the SystemDefaultsSection.

Table 2-7 Fields defining SystemDefaultsSection

Field Description

AutoAcknowledgementInterval Interval, in seconds, after which a cleared (that is, inactive and unowned) notification is automatically acknowledged by the Adapter Platform Server. Notifications that are auto acknowledged are owned by the user SYSTEM. Default is 300 seconds.An Acknowledged notification in the Adapter Platform does not propagate to the Global Manager.

InactiveAutoArchiveInterval Interval, in seconds, after which a cleared (inactive) and acknowledged notification is archived by the Adapter Platform Server. Default is 14400 seconds (4 hours). If this value is set to zero, archiving is disabled and events will not be deleted, causing the Adapter Platform to use more memory.

AuditTrailSizeLimit Number of audit log entries for each notification that are saved in the Adapter Platform before the log contents are archived. When this limit is reached, half of the entries are written to the notification archive. The archive is written, by default, to the BASEDIR/smarts/local/logs directory. The name of the file is taken from the name of the Adapter Platform Server and appended with .archive.


3


◆ Working with the Service Script.................................................................................. 3-2◆ Verify the EMC Smarts product status....................................................................... 3-4

Note: In a production environment, the Adapter is normally run as a service. However, in a pre-production environment, you may wish to modify the event mapping configuration for the Adapter. In this case, you may want to run the run the Adapter in non-service mode. For information, see “Working with the Adapter in Non-Service Mode” on page 4-1.

Working with theAdapter Service

Working with the Adapter Service 3-1

Working with the Adapter Service

Working with the Service ScriptAfter installing the Adapter service, you must start the service for the first time. To start the service, you use the ic-sitescope-service script, which allows you to manage the Adapter service.

This chapter describes the ic-sitescope-service script, and explains how to customize and use it to do the following:

◆ Start and stop the Adapter service

◆ Manually install and uninstall the Adapter service

The script is originally installed to the BASEDIR/smarts/script directory. If you modify the script using the sm_edit utility, the updated script is located in the BASEDIR/smarts/local/script directory.

Customizing the script variables The script uses variables to specify information such as the software installation location. Before running the script, you may customize the values of the variables listed in Table 3-1 as needed for your deployment.

To edit the script, open it with the sm_edit utility as described in “Understanding the sm_edit Utility” on page E-1.

Table 3-1 ic-sitescope-service variables

Variable Default value Description

SMHOME /opt/InCharge7/SAM/smarts

Adapter installation directory

DMNAME SITESCOPE Default name for the Adapter Domain.

BROKER localhost:426 Host and port where the Smarts Broker is listening. This variable is provided for circumstances where the Adapter does not use the broker location specified in runcmd_env.sh.

PORT 0 Port which the Adapter uses to communicate with other Smarts programs. When the value is 0, a random, unprivileged port is chosen at startup. To specify a specific port, set this variable.



Controlling the Adapter serviceOnce the Adapter service is installed either using the Installation Wizard or manually, you can control the Adapter service. To start the Adapter service, issue the following command, using the commands in Table 3-2:

./ic-sitescope-service <command>

For example, to start the adapter service, issue the following command:

./ic-sitescope-service start

Manually installing and uninstalling the Adapter serviceYou can use the ic-sitescope-service script to manually install the Adapter service when one of the following conditions occurs:

◆ You need to install multiple adapters on the same host.

◆ You need to provide alternate Service or Service Display names.

◆ You need start, stop, and control via the command line.

Note: The Installation Wizard mode supports installation of a single instance of the Adapter only, with the default domain name, SITESCOPE.

To install the Adapter service, issue the following command, using the commands listed in Table 3-3:

./ic-sitescope-service <command>

For example, to automatically start the Adapter service, issue the following command:

./ic-sitescope-service automatic

Table 3-2 Commands for controlling the Adapter service

Command Description

start Starts the adapter, if it is not running.

show Displays configuration information for the adapter.

stop Stops the adapter, if it is running.

Table 3-3 Commands for installing/uninstalling the Adapter service

Command Description

automatic Installs the Adapter as a service so that the service automatically starts whenever the system detects that the adapter is not running.

runonce Installs the Adapter service so that the service starts when the system starts.

manual Installs the Adapter service so that the service starts when invoked by the user.

disable Installs the Adapter service but prevents it from being started.

remove Uninstalls the Adapter service.

Working with the Service Script 3-3


Verify the EMC Smarts product statusYou can determine the current state of the products in the suite that register with the Broker by issuing the following command:

BASEDIR/smarts/bin/brcontrol

This command displays a list of EMC Smarts Managers and adapters registered with the broker, their states (RUNNING, DEAD, UNKNOWN), process IDs, port numbers, and the last time that their states changed.

Also check any log files for the products. Typically, these log files are in BASEDIR/smarts/local/logs.


4

In a production environment, the Adapter is normally run as a service. However, in a pre-production environment, you may wish to modify the event mapping configuration for the Adapter. In this case, you may prefer to run the Adapter in non-service mode.

This chapter describes the ic-sitescope-adapter script, and explains how to customize and use it to control the Adapter.

Note: EMC Corporation recommends that you do not intermix commands for ic-sitescope-service and ic-sitescope-adapter to control the same Adapter. Management operations performed by ic-sitescope-service are handled by sm_serviced, while those of ic-sitescope-adapter are not. Using both to control an Adapter may give sm_serviced an incorrect view of the desired Adapter state, resulting in improper or unexpected Adapter operation.


◆ The ic-sitescope-adapter script.................................................................................... 4-2

Working with theAdapter in

Non-Service Mode

Working with the Adapter in Non-Service Mode 4-1

Working with the Adapter in Non-Service Mode

The ic-sitescope-adapter scriptThe ic-sitescope-adapter script allows you to control the Adapter in non-service mode.

The script, ic-sitescope-adapter, is originally installed to the BASEDIR/smarts/script directory. If you modify the script using the sm_edit utility, the updated script is located in the BASEDIR/smarts/local/script directory.

Customizing ic-sitescope-adapter script variables Before running the ic-sitescope-adapter script, you may customize the values of the variables listed in Table 4-1, as needed for your deployment.

To edit the ic-sitescope-adapter script, open it with the sm_edit utility as described in “Understanding the sm_edit Utility” on page E-1.

Controlling the adapter Once the Adapter is installed in non-service mode, you can control the Adapter using the commands in Table 4-2. For example, to start the Adapter, issue the following command using the commands listed in Table 4-2:

./ic-sitescope-adapter <command>

For example, to start the Adapter, use the following command:

./ic-sitescope-adapter start

Table 4-1 ic-sitescope-service variables

Variable Default value Description

SMHOME /opt/InCharge7/SAM/smarts

Adapter installation location

DMNAME SITESCOPE Default name for the Adapter Domain.

BROKER localhost:426 Host and port where the Smarts Broker is listening. This variable is provided for circumstances where the Adapter does not use the broker location specified in runcmd_env.sh.

PORT 0 Port which the Adapter uses to communicate with other Smarts programs. When the value is 0, a random, unprivileged port is chosen at startup. To specify a specific port, set this variable.

Table 4-2 Commands for controlling the adapter

Command Description

start Starts the installed Adapter.

stop Stops the installed Adapter if it is running.

startclean Starts the Adapter with a clean topology

brcontrol Query status from configured Smarts Broker.


5


◆ Logging for Failure to Create Notifications and Topology ..................................... 5-4◆ Types of Failure Scenario ............................................................................................. 5-5

Failure Scenarios

Failure Scenarios 5-3

Failure Scenarios

Logging for Failure to Create Notifications and TopologyIn the event that the Adapter is unable to create a notification or topology information, it creates one of the following warning messages:

◆ Warning: Unable to create notification for <SiteScope information>

◆ Warning: Unable to create topology information for <SiteScope information>


Failure Scenarios

Types of Failure ScenarioThe chapter describes the following failure scenarios and explains how the Adapter functionality might be affected:

◆ SiteScope server is down

◆ Adapter is down

SiteScope Server is DownWhen the SiteScope server is down, no monitoring is done until the SiteScope server is up again.

The Event and Alert Processors each have a configuration parameter, sitescopeSessionLossHeartbeatDelay, that specified the maximum allowable number of seconds between alerts or events. If no event or alert occur within this period, a Session Down notification created to alert the operator. This detection may be disabled with a value of 0.

Adapter is DownWhen the Adapter is down, the following occurs:

◆ The Adapter Platform creates a Session Down notification to alert the operator of the problem.

◆ SiteScope continues to monitor.

◆ Alerts are written to the queue file until the Adapter is up again.

◆ Event are not processed by the Event Processor. When the Adapter is up, events are processed again, and the Session Down Notification is cleared.

Types of Failure Scenario 5-5

Failure Scenarios


A

The Adapter for SiteScope maps the values in the SiteScope log files to notification attributes.

Table A-1 lists the default mapping for the notification attributes.

Default Mapping ofEvent Fields to Attributes

Table A-1 Mapping of Event fields to notification attributes

Notification attribute Description SiteScopeEvent field

Category Category of this event. The event category represents a broad categorization of the event, e.g. availability vs. performance.

“Sitescope Event”

ClassName Class name of the object where this event occurred. This attribute along with InstanceName and EventName uniquely identify this event.

Monitor Group Name

ClearOnAcknowledge Indicates if this event should be cleared when it is acknowledged. Set this to TRUE only for events that do not expire nor have sources that generate a clear. Defaults to FALSE.

False

EventName Name of the event. This attribute along with ClassName and InstanceName uniquely identify this event.

Monitor name || Monitor ID || Monitor group name

EventText The textual representation of the event. State String || Monitor ID

EventType Indicates the nature of the event. A MOMENTARY event has no duration. An authentication failure is a good example. A DURABLE event has a period during which the event is active and after which the event is no longer active. An example of a durable event is a link failure. (Possible values: DURABLE, MOMENTARY)

“DURABLE”

InstanceName Instance name of the object where this event occurred. This attribute along with ClassName and EventName uniquely identify this event.

For host class: A_UcsName For application class: APP- || MONITOR_NAME || A_UcsName

OccurredOn The element the indication is associated with. Setting this value causes ElementClassName and ElementName to be set appropriately.

dest_host_name or sitescope server

Default Mapping of Event Fields to Attributes A-1

Default Mapping of Event Fields to Attributes

Severity An enumerated value that describes the severity of the event from the notifier's point of view: 1. Critical - used to indicate action is needed NOW and the scope is broad, e.g. an outage to a critical resource. 2. Major - used to indicate action is needed NOW. 3. Minor - should be used to indicate action is needed, but the situation is not serious at this time. 4. Unknown - indicates that the element is unreachable, disconnected or in an otherwise unknown state. 5. Normal - used when an event is purely informational.

SiteScope severity - value that describes the severity of the event according to the user definition: 1. Error – will be mapped to critical. 2. Warning - will be mapped to minor. 3. Nodata - will be mapped to Unknown. 4. Good - will be mapped to Normal.Default = 5For more information, see“Special Handling for NoData Alerts” on page D-1.

State Defines if this event is notification or if it is a clear of notification.(Possible values: CLEAR, NOTIFICATION)

"CLEAR" in case of: Severity = Good"NOTIFICATION" in case of • Severity = Error• Severity = Warning• Severity = Nodata

SourceDomainName The name(s) of the domain(s) that have originally diagnosed and notified - directly or indirectly - current occurrences of this event. If there are more than one original domain, the attribute lists each separated by a comma. When the notification is cleared, the last clearing domain stays in the value.

Default

TroubleTicketID Trouble ticket ID. Defaults to "". Default

UserDefined1 User defined field 1. Defaults to "". ORIG_MSG_TEXT

UserDefined2 User defined field 2. Defaults to "". Default









Category Category of this event. The event category represents a broad categorization of the event, e.g. availability vs. performance.

“Sitescope Event”

ClassName Class name of the object where this event occurred. This attribute along with InstanceName and EventName uniquely identify this event.

Monitor Group Name

Table A-1 Mapping of Event fields to notification attributes (continued)

Notification attribute Description SiteScopeEvent field

EMC Smarts Adapter for SiteScope User's GuideA-2

B

SiteScope uses a variety of monitor types to examine performance on different types of systems. The Adapter uses configuration files to map the output each kind of monitor to Smarts notifications.

Table B-1 lists the SiteScope monitor types and associated Adapter configuration files.

SiteScope MonitorTypes

Table B-1 Mapping of siteScope monitor types To Adapter configuration files

SiteScope monitor Adapter configuration document

OS monitors

Disk Space Monitor DiskSpaceMonitor.conf

Directory Monitor DirectoryMonitor.conf

File Monitor FileMonitor.conf

Log File Monitor LogMonitor.conf

CPU Utilization Monitor CPUMonitor.conf

Memory Monitor MemoryMonitor.conf

Script Monitor ScriptMonitor.conf

Network Monitor NetworkMonitor.conf

Ping Monitor PingMonitor.conf

Service Monitor ServiceMonitor.conf

Windows Event Log Monitor NTEventLogMonitor.conf

Windows Performance Counter Monitor NTCounterMonitor.conf

Windows Resources Monitor PDHMonitor.conf

MS_IIS monitors

IIS Server Monitor IISServerMonitor.conf

ASP Monitor ASPMonitor.conf

FTP Monitor FTPMonitor.conf

Web Server Monitor WebServerMonitor.conf

Web Service Monitor WebServiceMonitor.conf

SiteScope Monitor Types B-1

SiteScope Monitor Types

MS_SQL monitors

SQL Server Monitor SQLServerMonitor.conf

Database Query Monitor DatabaseMonitor.conf

Oracle monitors

Table B-1 Mapping of siteScope monitor types To Adapter configuration files (continued)

SiteScope monitor Adapter configuration document

EMC Smarts Adapter for SiteScope User's GuideB-2

C

This Appendix provides information about working with SiteScope alert templates.

◆ Processing overview .................................................................................................... C-2◆ Implementing alert templates for processing SiteScope alerts.............................. C-3◆ Creating a script alert definition ................................................................................ C-4◆ Defining a corresponding Smarts event document................................................. C-5

Working with Alerts

Working with Alerts C-1

Working with Alerts

Processing overviewAlert processing is based on this approach:

1. SiteScope Script alerts are configured to invoke scripts to handle alerts. In this case, the Adapter Alert Logger application is configured as the target "script" that handles alerts.

2. A SiteScope template is defined to convert the available monitor data in a strictly formatted file of "name=value" pairs that can be processed by the Alert Logger.

3. The Alert Logger processes the "name=value" pairs from the template and enqueues the data as an alert for processing by the Alert Processor.

4. The Alert Processor interprets the "name=value" data as the ${E_xxxx} field names and values of the alert. These exact field names are used to select and expand a particular Notification Template.

Summary of alert processing tasksSuccessful processing of user-defined SiteScope Alerts therefore requires these tasks:

1. Determine the desired SiteScope monitor on which to base the alert.

2. Implement a specially formatted SiteScope template to transform the desired available SiteScope monitor data into a file that can be processed by the Adapter Alert Logger. See “Implementing alert templates for processing SiteScope alerts” on page C-3

3. Using the SiteScope interface, define a Script Alert and associate the monitor, the custom template, and the Alert Logger. See “Creating a script alert definition” on page C-4.

4. Define a suitable Adapter event document to process the data resulting from the SiteScope template into the desired Smarts notification. See “Defining a corresponding Smarts event document” on page C-5.

EMC Smarts Adapter for SiteScope User's GuideC-2

Working with Alerts

Implementing alert templates for processing SiteScope alertsThe Adapter for SiteScope includes default templates for handling SiteScope alerts.The following is the format of the template data:

Note: “Special Handling for NoData Alerts” on page D-1 describes a special situation for template development.

Sample SiteScope alert templateThe Alert Definition in the SiteScope GUI invokes the Alert Logger, which runs the script template configured for that alert. The template specifies text to be formatted as name-value pairs, populates the pairs with values from the monitor output, and sends the text to the Alert Logger (sm_sitescopewritealerts) as a file, where it is read and sent to the Adapter queue file.

Each of the “names” of the “name = value” pairs becomes available for processing in the Adapter as a ${E_xxxx} variable e.g. ${E_MONITOR_GROUP_NAME}. Care must be given to ensure that the definition of these name in the alert template exactly matches variables used in the associated event document.

The following is a sample SiteScope alert template file (sm_CPUUtilization.txt) for the CPU Utilization alert:

#~ sm_CPUUtilization.txt - Sitescope template## File to define arbitrary <name> = <value> pairs to# be recognized by InCharge SiteScope Adapter.## Any <name> defined here must appear in an EventClass# definition in an Adapter Event Document.#CLASS = <_class>TIME_AND_DATE = <time>MONITOR_NAME = <name>MONITOR_GROUP_NAME = <group>MONITOR_ID = <_id>SAMPLE_NUMBER = <sample>MONITOR_CURRENT_STATUS = <category>STATE_STRING = <state>MACHINE = <_machine>REMOTEMACHINENAME = <remoteMachineName>UTILIZATIONPERCENTAGE = <utilizationPercentage>UTILIZATIONPERCENTAGE16 = <utilizationPercentage16>LASTMEASUREMENT = <lastMeasurement>LASTMEASUREMENT16 = <lastMeasurement16>CPUSNUM = <cpusNum>LASTMEASUREMENTTIME = <lastMeasurementTime>FREQUENCY = <_frequency>DISABLED = <_disabled>VERIFYERROR = <_verifyError>ERRORFREQUENCY = <_errorFrequency>SCHEDULE = <_schedule>

Implementing alert templates for processing SiteScope alerts C-3

Working with Alerts

Creating a script alert definitionUsing the SiteScope GUI, configure a Script Alert to invoke the Alert Logger as the target script. The actual name of this application is “sm_sitescopewritealerts”. Also, specify the associated alert template to use.

When SiteScope runs the Alert Logger, it will be passed various parameters including the filename of the template output as follows:

sm_sitescopewritealerts <ScriptsDirectoryPathname> // The pathname of the scripts directory. <MonitorNameCausedAlert> // The name of the monitor that caused the alert. <CurrentMonitorStatus> // The current status of the monitor. <AlertMessageFilePathname> // The pathname to the alert message file. <MonitorIdCode> // The id code of the monitor <MonitorGroup> // The group for the monitor [Optional:Parameters; for example, sm_CPUUtilization.txt]

Follow the steps below to create a SiteScope script alert definition.

1. In the SiteScope GUI, at the Monitors tab, right-click Group or Monitor, and then select New Alert.

2. In the right panel, click Script.

3. In the New Alert panel, enter the following:

• Name of the alert

• Script to be run:

– sm_sitescopewritealerts (Solaris) – sm_sitescopewritealerts.exe (Windows)

• Chose a template (for example, sm_CPUUtilizationTemplate).

• Template for apply (for example, sm_CPUUtilizationTemplate.

4. If necessary, configure the Advanced and Category settings, and then click OK.


Working with Alerts

Defining a corresponding Smarts event documentWhen the Alert Processor retrieves the alert from the queue, the value of each <xxxxx> parameter name will have been populated. As noted in the header of the sample file, any parameter name specified in the SiteScope template must also appear in an EventClass statement in a corresponding Adapter event document so that the parameter may be referenced by name in templates and selection rules via ${E_xxxxx}. For example, the template shown above could be processed with an event document as follows:

#~ AlertCPUUtilization.conf - rules for generic error reporting## Copyright (c) 2005 System Management ARTS (SMARTS)# All Rights Reserved### $Source: /src/MASTER/smarts/sitescope/conf/event/Attic/AlertCPUUtilization.conf,v $## Define common error events that are unable to be correlated but worthy of# operator alerts.#Document AlertCPUUtilization {

Imports event/AlertUnitaryComputerSystem.conf

# possible Event data fields (see SiteScope product doc) EventClass AlertCPUUtilization inherits AlertCommon {

E_CLASS = ''E_TIME_AND_DATE = ''E_MONITOR_NAME = ''E_MONITOR_GROUP_NAME = ''E_MONITOR_ID = ''E_SAMPLE_NUMBER = ''E_MONITOR_CURRENT_STATUS = ''E_STATE_STRING = ''E_MACHINE = ''E_REMOTEMACHINENAME = ''E_UTILIZATIONPERCENTAGE = ''E_UTILIZATIONPERCENTAGE16 = ''E_LASTMEASUREMENT = ''E_LASTMEASUREMENT16 = ''E_CPUSNUM = ''E_LASTMEASUREMENTTIME = ''E_FREQUENCY = ''E_DISABLED = ''E_VERIFYERROR = ''E_ERRORFREQUENCY = ''E_SCHEDULE = ''

}

## rule to invoke pattern matches for entire module - CPUMonitor Rule main { Match "$E_CLASS" == 'CPUMonitor' { Template inherits AlertUcsDegraded {

EventClass inherits AlertCPUUtilization {} OriginHook use_propertyIsSystemName-origin-Alert.asl { PROPERTY1 = 'E_REMOTEMACHINENAME' PROPERTY2 = 'E_MACHINE' PROPERTY3 = 'E_SITESCOPE_SERVER' }

} } }}

Defining a corresponding Smarts event document C-5

Working with Alerts


D

Many SiteScope events can include the 'NoData' STATE_STRING, which indicates that the monitor poll did not return data. This string usually reflects some error other than the one being monitored and so should not create a Notification specific to the particular monitor. This appendix describes how to configure the Adapter for appropriate NoData handling. It contains the following information:

◆ Template for handling NoData alerts........................................................................D-2◆ Sample NoData.conf event document ......................................................................D-3◆ Configuration parameter that controls NoData handling .....................................D-4

Special Handling forNoData Alerts

Special Handling for NoData Alerts D-1

Special Handling for NoData Alerts

Template for handling NoData alertsTo alert the operator to the data loss, you can use the following template to create a a special NoData notification.

#~ NoData.conf - rule to demote "No Data" error Events to "UnKnown"## Copyright (c) 2005 System Management ARTS (SMARTS)# All Rights Reserved#

Document NoData { Imports event/Base.conf ## uncorrelatable: Notification of "No Data" condition # # A Notification generated by this Template will CLEAR only by Expiration. # It is of 'MOMENTARY' type so that multiple 'NoData' events will increment # the Notification count without an intervening CLEAR. This Notification # is distinct from the normally generated monitor Notification and has an # 'Unknown' Severity. Subsequent 'good', 'warning', or 'error' Events will # affect changes to the primary Notification associated with that Monitor # but this NoData Notification will be unaffected. # # Expiration time of the special "no data" notification is controlled by the # "CONF10" parameter located in adapter.conf. It should be set to no less # than 150% of the normal Monitor polling rate. In instances where several # widely different polling rates exist, the Expiration may be explicitly # overridden on a case by case basis or the Template may be cloned into # versions with different explicit Expiration times. # Template NoData inherits Base { EventClass inherits Common { E_CLASS = '<UNKNOWN>' } ClassName= "${E_CLASS}" EventName= "NoData" Expiration= "${C_CONF10}" Severity= 'unknown' EventType= 'MOMENTARY' State= 'NOTIFY' }

Rule main {}} #### eof ####

EMC Smarts Adapter for SiteScope User's GuideD-2


Sample NoData.conf event documentThe NoData.conf Event Document is used as shown below to detect cases where data was not actually received from a monitor operation. Instead of discarding the event or making a true error notification, a special transient Notification is created that notifies the operator of the data loss then auto-clears after the 'conf10' period. Conf10 should be set to slightly longer than the polling period - if the 'no data' condition repeats before the Notification expires, the count increases and the Notification persists. This gives the operator an active display 'no data' problems for all such monitors.

#~ CPUMonitor.conf - Mercury SiteScope Windows Configuration scripts## Copyright (c) 2005 System Management ARTS (SMARTS)# All Rights Reserved#

Document CPUMonitor { #Imports event/Base.conf Imports event/UnitaryComputerSystem.conf Imports event/NoData.conf # possible Event data fields (see SiteScope product doc) EventClass CPUMonitor inherits Common { E_CLASSIFIER = '' E_DEPENDSCONDITION = '' E_DISABLED = 'false' E_ENCODING = '' E_FREQUENCY = '0' E_ID = '' E_INTERNALID = '' E_MACHINE = '' E_NAME = '' E_TIMEDDISABLE = '0' }

Rule main { Match "$E_CLASS" == 'CPUMonitor' { ## filter "no data" events and handle as special Notification Match "$E_STATE_STRING" == 'no data' { Template inherits NoData { EventClass inherits CPUMonitor {} OriginHook use_propertyIsRemoteFilename-origin.asl { PROPERTY = 'E_MACHINE' } } } Template inherits UcsDegraded { EventClass inherits CPUMonitor {} OriginHook use_propertyIsRemoteFilename-origin.asl { PROPERTY = 'E_MACHINE' } } } }} #### eof ####

Sample NoData.conf event document D-3


Configuration parameter that controls NoData handlingThe following code snippet is from the main configuration file, adapter.conf. It shows the relevant section, MonitorSection, with the default value for conf10, which spedifies NoData handling.

# User-defined values for use in Selection Rules and Notification # Templates # # These string values may be accessed in Event Documents as # ${C_conf<n>}. The values may be used in Selection Rules to # enable/disable branches of the selection tree or may be used in # Templates to provide specific customizations without the need to # support multiple suites of Event Documents ( e.g. use conf1 = # customerAccountName and set Template UserDefined1 = ${C_conf1} ). # conf1 = "<CONF1>"; conf2 = "<CONF2>"; conf3 = "<CONF3>"; conf4 = "<CONF4>"; conf5 = "<CONF5>"; conf6 = "<CONF6>"; conf7 = "<CONF7>"; conf8 = "<CONF8>"; conf9 = "<CONF9>"; conf10 = "450"; ## controls "no data" Notif expiration

EMC Smarts Adapter for SiteScope User's GuideD-4

E

As part of the EMC Smarts deployment and configuration process, you need to modify certain files. User modifiable files include configuration files, rule set files, templates, and files (such as seed files, and security configuration files) that contain encrypted passwords. Original versions of these files are installed into appropriate subdirectories under the BASEDIR/smarts/ directory.

Examples:

• The original versions of the Global Manager configuration files on UNIX are installed to /opt/InCharge7/SAM/smarts/conf/ics

• The original versions of the Console configuration files on Windows are installed on C:\InCharge7\SAM\smarts\conf\console

Original versions of files should not be altered. If a file requires modification, it must be stored as a local copy of the file in BASEDIR/smarts/local or one of its subdirectories.

Examples:

• A modified ics.conf file on UNIX should be saved to /opt/InCharge7/SAM/smarts/local/conf/ics

• A modified properties.conf file on Windows should be saved to C:\InCharge7\SAM\smarts\local\conf\console.

Smarts software is designed to first search for user modifiable files in BASEDIR/smarts/local or one of its subdirectories. If a modified version of a file is not found in the local area, Smarts software then searches appropriate nonlocal directories.

To facilitate proper file editing, EMC Corporation provides the sm_edit utility with every Smarts product suite. When used to modify an original version of a file, this utility automatically creates a local copy of the file and places it in the appropriate location under BASEDIR/smarts/local. This ensures that the original version of the file remains unchanged. You can invoke sm_edit from the command line. Optionally, you can configure Windows so that sm_edit is automatically invoked when user-modifiable files are double-clicked in Windows Explorer.

To invoke the sm_edit utility from the command line, specify the path and the name of the file to edit under BASEDIR/smarts. If multiple Smarts products are running on the same host, invoke sm_edit from the bin directory of the product suite with the files to edit.

Understanding thesm_edit Utility

Understanding the sm_edit Utility E-1

Understanding the sm_edit Utility

For example, to edit the configuration file for the Global Manager, invoke the sm_edit utility as follows:

# ./opt/InCharge7/SAM/smarts/bin>sm_edit conf/ics/ics.conf

In this example, the sm_edit utility automatically creates a local copy of the ics.conf file in the /opt/InCharge7/SAM/smarts/local/conf/ics directory and opens the file in a text editor. If a local version of the file already exists, the sm_edit utility opens the local version in a text editor. In addition, sm_edit creates any necessary subdirectories.

The EMC Smarts System Administration Guide provides additional information about the sm_edit utility.

EMC Smarts Adapter for SiteScope User's GuideE-2

Index

Aadapter.conf 2-3Availability Manager

specifying source 2-13

BBASEDIR 3-vBROKER variable 3-2, 4-2

CConfiguration Files

adapter.conf 2-3event.conf 2-3ic-niqam-adapter.cmd 2-3ic-niqam-service.cmd 2-3

DDMNAME variable 3-2, 4-2DomainType definition 2-13, 2-14

Eevent.conf 2-3

HHook Scripts 2-3

Iic-niqam-adapter.cmd 2-3ic-niqam-service.cmd 2-3icoi.conf

SystemDefaultSectionAuditTrailSizeLimit 2-16AutoAcknowledgementInterval 2-16InactiveAutoArchiveInterval 2-16

ics.conf 2-14

MMessage Queue 1-5

NNotification Templates 1-6

PPORT variable 3-2, 4-2

SSelection Rules 1-6Session monitoring 1-7sm_edit utility E-1SMHOME variable 3-2, 4-2System defaults 2-16

EMC Smarts Adapter for SiteScope User's Guide i-1

Index

EMC Smarts Adapter for SiteScope User's Guidei-2