Professional Documents
Culture Documents
Version 3.2.00
July 2003
Copyright 2003 BMC Software, Inc. All rights reserved. BMC Software, the BMC Software logos, and all other BMC Software product or service names are registered trademarks or trademarks of BMC Software, Inc. All other trademarks belong to their respective companies. BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation.
Telephone Fax
Customer Support
You can obtain technical support by using the Support page on the BMC Software Web site or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, please see Before Contacting BMC Software.
operating system and environment information machine type operating system type, version, and service pack or other maintenance level such as PUT or PTF system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or maintenance level
iii
sequence of events leading to the problem commands and options that you used messages received (and the time and date that you received them) product error messages messages from the operating system, such as file system full messages from related software
iv
Contents
Contents
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Chapter 1 BMC Impact Manager Overview
Understanding BMC Impact Manager . . . . . . . . . . . . . . . . . . . . . . . 1-2 Event Management with BMC EM . . . . . . . . . . . . . . . . . . . . . . 1-2 Service-Impact Management with BMC SIM . . . . . . . . . . . . . . 1-3 BMC Impact Manager Product Components . . . . . . . . . . . . . . . 1-4 About BMC Impact Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 About BMC Impact Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8 About BMC Impact Explorer Server . . . . . . . . . . . . . . . . . . . . . 1-9 About BMC Impact Event Adapters . . . . . . . . . . . . . . . . . . . . . . 1-9 BMC Impact Manager Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Understanding BMC Impact Manager Event Processing . . . . . . . . . 1-12 Event Flow Between Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13 Rule Phases for Event Processing . . . . . . . . . . . . . . . . . . . . . . . . 1-15 Understanding the BMC Impact Manager Knowledge Base . . . . . . 1-18 Knowledge Base Installation and Upgrade . . . . . . . . . . . . . . . . . 1-18 Components of the BMC Impact Manager Knowledge Base . . . . . . 1-19 Knowledge Base Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20 Knowledge Base Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
Chapter 2 The BAROC Language
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 BAROC Syntax Generalities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Class Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
BMC Software, Inc., Confidential and Proprietary Information
Contents
Class Definition Basic Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6 Slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-7 Slot Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-7 Universal Event and Data Identifiers . . . . . . . . . . . . . . . . . . . . . .2-7 Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-9 Class Definition Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10 Class Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12 Instance Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12 Instance Definition Example . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13 Enumeration Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13 Enumeration Definition Example . . . . . . . . . . . . . . . . . . . . . . . .2-14 Global Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14 Record Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14 Record Definition Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15 Addressing Global Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15 Product Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-16 Product Base Internal Classes . . . . . . . . . . . . . . . . . . . . . . . . . . .2-16 EVENT Root Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17 DATA Root Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-24 Internal Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25 Other Internal Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-26
Chapter 3 The Cell Rule Engine
Order of Rule Evaluation in the Knowledge Base . . . . . . . . . . . . . . .3-2 Incoming Event Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4 Internal Event Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5 Internal Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5 Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
Chapter 4 The Master Rule Language
General Rule Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-2 Objects, Types, and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-4 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-4 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5 Global Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-7 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-7 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-9 Selection Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-11 Event Selection Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-11
BMC Software, Inc., Confidential and Proprietary Information
vi
Where Clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 Using Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 When Clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19 Body Clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20 The if-then-else Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21 General Rule Writing Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Chapter 5 The Rule Phases
Refine Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Syntax: Refine Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Semantics: Refine Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Examples: Refine Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 Filter Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 Syntax: Filter Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 Semantics: Filter Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 Examples: Filter Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7 Regulate Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 Syntax: Regulate Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10 Semantics: Regulate Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11 Examples: Regulate Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12 New Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14 Syntax: New Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15 Semantics: New Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16 Examples: New Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16 Abstract Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18 Syntax: Abstract Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19 Semantics: Abstract Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19 Examples: Abstract Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21 Correlate Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23 Syntax: Correlate Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23 Semantics: Correlate Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24 Examples: Correlate Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25 Execute Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28 Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31 Propagate Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33 Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35
BMC Software, Inc., Confidential and Proprietary Information
Contents
vii
Timer Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-35 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-36 Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-36 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-38 Delete Rule Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-40 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-40 Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-40 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-41
Chapter 6 Collectors
Collector Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-3 Collector Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-4 Setting Up Collector Permissions . . . . . . . . . . . . . . . . . . . . . . . .6-5 How Collector Permissions Work . . . . . . . . . . . . . . . . . . . . . . . .6-6 Static and Dynamic Collectors . . . . . . . . . . . . . . . . . . . . . . . . . .6-8 Collector Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-8 BMC Impact Manager Default Collectors . . . . . . . . . . . . . . . . .6-8 Collector Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9 Static Collector Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-13 Dynamic Collector Examples . . . . . . . . . . . . . . . . . . . . . . . . . . .6-15 Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-17
Appendix A Master Rule Language Reference
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operator Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Boolean (Logical) Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . String Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cell Operation Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conversion Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Instance Control Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . List Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Run Program Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieve Data Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . String Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Time Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conditional Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Software, Inc., Confidential and Proprietary Information
A-2 A-3 A-4 A-12 A-13 A-14 A-14 A-16 A-17 A-19 A-24 A-29 A-32 A-33 A-38 A-42 A-45
viii
Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enumeration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieve Data Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Time Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MRL Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC Impact Manager Base Classes . . . . . . . . . . . . . . . . . . . . . . . .
Glossary Index
A-45 A-46 A-47 A-49 A-51 A-52 A-58 A-59 A-60 A-87
Contents
ix
About . . .
This book assumes that you are familiar with your host operating system. You should know how to perform basic actions in a window environment, such as choosing menu commands and dragging and dropping icons.
ix
Description
provides an overview of BMC Impact Manager and defines the Knowledge Base and provides information on how to configure the Knowledge Base files describes the BMC Impact Manager classes, their definitions and how they are used in the Knowledge Base rules and collectors describes the general behavior of the rule engine introduces the Master Rule Language (MRL) and how to use it in creating and using BMC Impact Manager rules and collectors in the Knowledge Base discusses the ten BMC Impact Manager rule phases and the event processing procedure provides procedures for creating collectors for the Knowledge Base contains reference information about rules and collectors, such as operators, primitives, functions, the syntax used in writing BMC Impact Manager rules and base classes
Chapter 3, The Cell Rule Engine Chapter 4, The Master Rule Language
Related Documentation
BMC Software products offer several types of documentation, including online and printed books and release notes. In addition to this book, you can find useful information in the publications listed in the following table. As Online and Printed Books on page xii explains, these publications are available on request from BMC Software.
Category
installation documents BMC Impact Manager core documents
Document
BMC Impact Manager Installation Guide BMC Impact Explorer Console User Guide BMC Impact Manager Administrator Guide Building a Service Model BMC Impact Event Adapters User Guide
Description
provides instructions for installing BMC Impact Manager and related software components contains instructions for accessing, analyzing, and responding to event and service model component data provides information and procedures for configuring BMC Impact Manager, BMC Impact Explorer Server, and BMC Impact Explorer provides information on designing, developing, and maintaining BMC Impact Manager service models contains descriptions of adapter files and instructions for configuring and running the event adapters contains information about exporting data from BMC Impact Manager into databases provides information about bidirectional integration between BMC Impact Manager servers and Remedy servers contains steps for streamlining TEC performance by using the BMC Impact Manager product provides instructions for sharing data between PATROL and BMC Impact Manager by using the BMC Impact Integration for PATROL product provides instructions for installing and configuring the component that connects BMC Impact Manager to PATROL EM so that they can share alerts and events
BMC Impact Database Gateway Administrator Guide BMC Impact Integration for Remedy AR System User Guide BMC Impact Integration for Tivoli User Guide BMC Impact Integration for PATROL User Guide BMC Impact Integration for PATROL Enterprise Manager User Guide
xi
Category
supplemental documents
Document
BMC Impact Manager Release Notes BMC Impact Explorer Release Notes BMC Impact Integration for Tivoli Release Notes BMC Impact Database Gateway Release Notes other release notes and technical bulletins
Description
contain last-minute information on the product and changes to the installation procedures
To view any online book that BMC Software offers, visit the Customer Support page of the BMC Software Web site at http://www.bmc.com/support.html. You can also access PDF books from the documentation compact disc (CD) that accompanies your product. Use the free Acrobat Reader from Adobe Systems to view, print, or copy PDF files. In some cases, installing the Acrobat Reader and downloading the online books is an optional part of the product-installation process. For information about downloading the free reader from the Web, go to the Adobe Systems site at http://www.adobe.com.
To Request Additional Printed Books
BMC Software provides some printed books with your product order. To request additional books, go to http://www.bmc.com/support.html.
xii
Release Notes
Printed release notes accompany each BMC Software product. Release notes provide up-to-date information such as updates to the installation instructions last-minute product information
The latest versions of the release notes are also available on the Web at http://www.bmc.com/support.html.
Conventions
The following conventions are used in this book: This book includes special elements called notes, warnings, examples, and tips:
Note
Warning
Warnings alert you to situations that can cause problems, such as loss of data, if you do not follow instructions carefully.
Example
Tip
Tips contain information that might improve product performance or that might make procedures easier to follow.
xiii
All syntax, operating system terms, and literal examples are presented in this typeface. In instructions, boldface type highlights information that you enter. File names, directories, Web addresses, e-mail addresses, and names of GUI elements also appear in boldface type. The symbol => connects items in a menu sequence. For example, Actions => Create Test instructs you to choose the Create Test command from the Actions menu. The symbol
In syntax, path names, or system messages, italic text represents a variable, as shown in the following examples: The table tableName is not available.
system/instance/fileName
In syntax, the following additional conventions apply: A vertical bar ( | ) separating items indicates that you must choose one item. In the following example, you would choose a, b, or c: a | b | c An ellipsis ( . . . ) indicates that you can repeat the preceding item or items as many times as necessary. Square brackets ( [ ] ) around an item indicate that the item is optional.
xiv
This chapter describes the BMC Impact Manager product and provides an introduction to the Knowledge Base. This chapter presents the following topics: Understanding BMC Impact Manager BMC Impact Manager Concepts Understanding BMC Impact Manager Event Processing Understanding the BMC Impact Manager Knowledge Base Components of the BMC Impact Manager Knowledge Base
1-1
1-2
the capturing of event details from its source Events are validated as close to their sources as possible, enabling the collection of any additional information needed for processing the event.
BMC EM includes a base set of these product components: BMC Impact Managerthe event-management technologies BMC Impact Explorerthe cross-platform GUI for the product Service Explorer Serverthe security and user access server BMC Impact Event Adaptersprocesses that convert data from various sources into BMC Impact Manager events
1-3
BMC SIM includes these product components: BMC Impact Managerthe event-management technologies BMC Impact Explorerthe cross-platform GUI for the product Service Explorer Serverthe security and user access server BMC Impact Event Adaptersprocesses that convert data from various sources into BMC Impact Manager events BMC Impact Manager Service componentscomponents to extend the service-management environment
In addition, BMC SIM provides integration with PATROL, PATROL Enterprise Manager, and Remedy AR System by means of the appropriate BMC Impact Integration product component.
Component
BMC Impact Manager (BMC IM)
Functionality
Provides event management and service-impact management technologies. It receives events, processes them, and provides service-impact and modeling functionality. Provides a Java GUI for the BMC Impact Manager product solutions. This cross-platform console enables secure, distributed access to EM or SIM information and functionality. Provides security and controls user access to BMC Impact Manager resources. Audits data from event sources, such as log files, event logs, or SNMP. The adapters evaluate the data for specific conditions and create events by transforming the data into the format understood by BMC Impact Manager.
Solution
BMC EM BMC SIM
Service Explorer Server (BMC IXS) BMC Impact Event Adapters (BMC IEA)
1-4
Table 1-1
Component
BMC Impact Manager Service components
Functionality
Enables customers to increase the IT assets represented in their Service Models and to scale their needs as their service-management environment grows. Enables the synchronized, bidirectional flow of events and data between BMC Impact Manager and PATROL Enterprise Manager. Enables the synchronized, bidirectional flow of events and data between BMC Impact Manager and PATROL. Enables the synchronized, bidirectional flow of events and data between BMC Impact Manager and Remedy AR System.
Solution
BMC SIM
BMC Impact Integration for PATROL Enterprise Manager (BMC II for PATROL EM) BMC Impact Integration for PATROL (BMC II for PATROL) BMC Impact Integration for Remedy AR System (BMC II for AR System)
1-5
Cell
The cell is the basic event-processing unit within the BMC Impact Manager product. Cells provide the following event-management capabilities in both the BMC EM and BMC SIM solutions: Receives eventsEvent sources connect to the cell and send it events. Analyzes and processes eventsA cell uses the definitions and rules in its associated Knowledge Base to determine how to process events, group events, and establish relationships between events. Stores eventsThe cell stores events in the repository maintained on a disk. The most recent events are held in memory and you can use the BMC Impact Explorer to view them. Responds to eventsThe cell can respond to events by executing actions, as defined in scripts or programs in the Knowledge Base. Propagates eventsThe cell can forward selected events to specified destinations, typically other cells. The cell maintains the currency of propagated events when those events are updated or changed at the event source.
In addition to the event-management tasks, the cell also performs the following service-management tasks: Builds associationsUsing the definitions and rules in its Knowledge Base, the cell can relate an event to the appropriate Service-Model component. Stores components and relationshipsThe cell stores Service-Model components and their relationships in its repository. Computes and propagates component statusUsing the designated status computation models, the cell computes the status of Service-Model components and propagates their status to the related components automatically.
1-6
Generates history eventsThe cell generates history events to record status changes of Service-Model components.
An individual cell can provide local event management or function as part of a larger distributed network of cells. When you install a cell, you also install a Knowledge Base in the cell along with the BMC Impact Manager CLI.
Knowledge Base
The Knowledge Base for the cell includes event class definitions, rules, executables, and collector definitions. The cell uses Knowledge Base data to determine which events are received and how the events are handled after receipt. The Knowledge Base is installed with a default set of rules that provide basic event processing in BMC EM and advanced service-impact management in BMC SIM. Rules are statements that combine tests and queries that are applied to events to determine how they are processed, such as discarding unneeded events or responding to significant events, and to perform actions on the events according to the rule type in the Knowledge Base. Event analysis is organized into a series of rule phases through which an event is processed when it is received by the cell. For further information, see Rule Phases for Event Processing on page 1-15. The BMC Impact Manager administrator maintains the Knowledge Base. Although many Knowledge Bases can exist within a distributed BMC Impact Manager environment, the following requirements apply:
Repository
Each cell must contain a Knowledge Base directory structure. Each cell can be associated with only one Knowledge Base at a time.
The repository is the persistent storage facility in which event information is stored. Events enter the repository after they have been processed by the cell.
1-7
Dynamic data is contextual reference data that is stored in a table in the repository (mc.db) and that can be updated during runtime. A dynamic data table is a set of data instances of a particular data class.
Command Line Interface (CLI)
The BMC Impact Manager CLI provides an extensive set of commands for executing product operations. For complete information on the BMC Impact Manager CLI, see the BMC Impact Manager Administrator Guide.
For complete information on BMC Impact Explorer, see the BMC Impact Explorer User Guide.
1-8
1-9
log file adapters (Windows and Unix)can monitor any text file. They extract data from log files and convert the data to the BAROC language, and create events Windows event log adapterreads the events generated by a Windows platform, translates the events into BAROC language structures and forwards the events to a cell. This adapter is the BMC Impact Adapter for Windows (BMC IELA)
Definition
An executable that can be run by a cell. Actions are called in an Execute rule. You can request the execution of actions in the BMC Impact Explorer. A background process that audits data from various sources, evaluates it for specific conditions, and creates the corresponding events. Adapters also transform event data into the format understood by BMC Impact Manager. Basic Recorder of Objects in C. A structured language used to create and modify class definitions. A class definition is similar to a structure in the C programming language. An interface that enables the synchronized, bidirectional flow of events and data between a BMC Impact Manager instance and another BMC Software product or a specific third-party product. The event-processing engine that collects, processes, and stores events within a BMC Impact Manager instance. Each cell uses the information in the associated Knowledge Base to identify the types of events to accept and how to process and distribute them. A BAROC-language data structure that defines a type of object used in this product. A class is made up of data fields, called slots, that define its properties. An event grouping whose content is defined by its collector rule. Collectors are displayed in the BMC Impact Explorer and are defined in the BMC Impact Manager Knowledge Base.
BAROC language
class
collector
1-10
Term
event event propagation Knowledge Base (KB)
Definition
A structured message passed to and from cells in a BMC Impact Manager environment. It is an instance of an event class. The act of forwarding events and maintaining their synchronization among multiple BMC Impact Managers. A collection of information that forms the intelligence of a BMC Impact Manager instance and enables it to process events and perform service-impact-management activities. This information includes event class definitions, Service-Model component definitions, record definitions, interface definitions, collector definitions, data associations, and processing rules. A conditional statement that, if determined to be true, executes actions. The cell evaluates events by comparing each event to a series of rules during event processing. Rules are grouped in phases that are processed one by one. An extensible system for defining the various resources that combine to deliver business services, for modeling their behaviors and functional relationships, and for managing the delivery of the resulting services. A logical or physical resource that participates in the delivery of services. There are the following types of Service-Model components: connectivity components, IT components, logical components, and service-levelagreement components. An SMC can provide services to or consume services from another component. In technical terms, a Service-Model component is any data class that is a subclass of the MC_SM_COMPONENT base class. An attribute in a BAROC class definition. A class definition consists of one or more slots. Each slot has a data type and can have specific attributes, called facets, that can control the values that the slot can have or control aspects of a class instances processing. A class that is a subclass to another class inherits all the slots of the parent class.
rule
slot
1-11
7. Repository 10. text editor 4. Knowledge Base CLI 6. Dynamic Data Tables 9. BMC Impact Explorer Server
Step
1 2 3
Process
Events occur in an enterprise. Event adapters monitor files or SNMP traps and translate event data into BAROC format. The cell checks whether the incoming events match the BAROC definitions in the cells Knowledge Base.
1-12
Table 1-2
Event Processing
Step
4 5
Process
The Knowledge Base determines the types of events that are received and how the events are handled once they reach the cell. The Command Line Interface (CLI) allows users to issue product commands on the OS command line for immediate execution and to automate product operations. The Dynamic Data Model feature uses dynamic data classes to define configuration data about types of machines, applications, services, and equipment available in an enterprise. The cell stores the events in the repository as an event class instance. BMC Impact Explorer connects to cells via the BMC Impact Explorer Server. Operators use BMC Impact Explorer to view events, change the status of events, and act on events stored in the repository.
7 8-9
1-13
Figure 1-2 illustrates a cell network that is collecting and processing numerous events. Based on configurable criteria, some of those events are propagated, or forwarded, for management by other cells.
Figure 1-2 Distributed Event Management
Some events are propagated for management by other cells in the cell network.
cell
cell
cell
cell
event sources
event sources
event sources
event sources
1-14
1-15
Figure 1-3
Event 1. Refine
2. Filter
3. Regulate
The New, Abstract, Correlate, and Execute phases can trigger Timer execution.
4.New
5. Abstract
6. Correlate
9. Timers
10. Delete
to other cells
When a record is deleted during repository cleanup, Delete rules are evaluated and actions are taken to ensure data integrity.
1-16
Table 1-3
Rule Phases
Phase
1. Refine 2. Filter 3. Regulate
Description
Refine rules are evaluated to validate incoming events and, if necessary, collect additional data needed before further event processing can occur. Filter rules are evaluated to determine which events need additional processing or are unneeded and are to be discarded. Regulate rules are evaluated and, if true, collect duplicate events for a time period and, if a specified threshold of duplicates is reached, passes an event to the next processing phase. New rules are evaluated to determine which events in the repository should be updated with new information from new incoming events. This is the last opportunity to prevent an event from entering the repository. Abstract rules are evaluated and, if conditions are met, abstraction events are generated. An abstraction event is a conceptual or summary event based on other events that are occurring. Correlate rules are evaluated to determine whether any events have a cause-and-effect relationship. Execute rules are evaluated and, if conditions are met, specified actions are performed. Propagate rules are evaluated to determine the events to be forwarded to another cell or to an Integration product. Timer rules for the delayed execution of another rule type are evaluated. The Timer phase spans the New, Abstract, Correlate, and Execute phases of event processing. When an event is deleted from the repository during the cleanup process, Delete rules are evaluated and actions are taken to ensure that data integrity is maintained.
4. New
5. Abstract
10. Delete
The Refine, Filter, and Regulate rules can discard an event before it reaches the repository. In that case the discarded events do not appear in BMC Impact Explorer. Once an event reaches the New rule phase it is stored in the repository. Rule phases in the shaded area can trigger timers within the rule. The Delete rule is triggered for events that are deleted from the repository. Details of each rule phase is available in Chapter 5, The Rule Phases.
1-17
1-18
1-19
Files
Classes, interfaces, data definitions Global records Data instances Rules Collectors Actions Action Executables
Directories
kb\classes kb\records kb\data kb\rules kb\collector kb\bin kb\bin\<architecture type>
1-20
The Knowledge Base must be recompiled each time a rule is added, deleted, or modified. You can compile the Knowledge Base by using the CLI command mccomp as follows:
cd %MCELL_HOME%\etc\<cell_name>\kb mccomp manifest.kb
-ORmccomp MCELL_HOME\etc\<cell_name>\kb\manifest.kb
The mccomp command parses event, data class and global records, and compiles the rules. Once the KB has been recompiled with the mccomp command, you can use the new mcontrol command to reload the Knowledge Base into the running cell.
mcontrol -n reconfigure kb
You also can use the mcontrol command to reload when collectors are added, deleted or modified.
mcontrol -n reconfigure collect
In prior versions of the BMC Impact Manager product the Knowledge Base compiled with the -t option could be deployed in a production environment. In the current version 3.2.00 of the BMC Impact Manager product, deploying a Knowledge Base compiled with the -t option may degrade performance by as much as 50%. It is strongly recommended that you not use the -t option when compiling the Knowledge Base.
Note
Any change to the cells Knowledge Base requires a recompilation of the Knowledge Base before the change is effective.
1-21
is the Knowledge Base during run time. The manifest.kb file points to directories for class events, interfaces, records, rules, libraries, and actions and its location is MCELL_HOME\etc\<CellName>\kb\manifest.kb.
1-22
bin = bin classes = classes collectors = collectors data = data lib = lib rules = rules records = records
Note
The manifest.kb file is used by the Knowledge Base compiler but not by the cell. It allows some flexibility when writing and testing Knowledge Bases.
1-23
kb bin A (Independent) h0 (HP10+) l2 (Linux Red Hat 7.0 and 7.1) p4 (AIX 4.3) s5 (Solaris 2.5+) w4 (Windows NT 4.0+) classes collectors data lib records rules manifest.kb (file)
The bin directory contains scripts and programs that execute during rule processing. The executables are in subdirectories specific to the host architecture. There is one default file, .load, in the bin directory. The .load file specifies in what order scripts and programs should be presented to clients. These three primitives in the bin directory execute programs.
execute runs an executable on the cell. The executable is located in the <arch> subdirectory. get_external runs an executable on the cell and passes
information back to the cell by means of an interface. The executable is located in the <arch> subdirectory.
confirm_external runs an executable on the cell and returns a boolean value. The executable is located in the <arch> subdirectory.
1-24
The default installation of the cell contains a Knowledge Base with a single base, or root, EVENT class definition. You may extend this base class definition by adding additional slots for custom or localized information. An example of the EVENT class definition is the following.
MC_EV_CLASS : MY_EVENT ISA EVENT DEFINES { source: default = MY_APPLICATION; my_slot: STRING, default = Version 3.2.00, parse = no; }; END
Collectors enable you to view events in an organized manner with the console. The collectors directory contains definitions of the collectors in .mrl files. The .load file indicates the order in which these files are loaded into the cell. You can define collectors hierarchically, which allows the console to display information that is easier to read. You also can specify the category of user who can view and act on the events in any collector. Here is an example of a top level, or supercollector, template:
collector <CollectorName> : {r[<Roles>]; w[<Roles>]; x[<Roles>]} END
1-25
User access to collectors is defined in the collectors.mrl file and any other .mrl file in the collector directory, as long as the collector file name is added to the .load file without the .mrl extension. In the collectors.mrl file you define access to collectors by assigning user roles and privileges to each collector. Privileges consist of read, write, and execute. User roles and the assignment of user roles are defined in the BMC Impact Explorer Server. See the BMC Impact Manager Administrator Guide for information on defining user roles and assigning roles to users.
The data Directory
The data directory contains instances of the base, or root, DATA class in .baroc files. The .load file indicates the order in which the files are loaded into the cell. A data class has the same definition as an event class. Chapter 2, The BAROC Language, and Chapter 4, The Master Rule Language, contain a detailed discussion of data classes.
The lib Directory
In prior releases the lib directory contained the declaration and implementation of primitives the rules use. These declarations and implementations are now contained within the cell for the Knowledge Base rules to use. Appendix A, Master Rule Language Reference, for details on primitives and their usage.
The records Directory
A global record stores persistent dynamic information in .baroc files. Many rule processing phases use global records to retrieve the information from the global record files. The .load file indicates the order in which the files are loaded into the cell.
1-26
RECORD test_rec DEFINES { slot_str: STRING ; slot_int: INTEGER ; slot_list_int: LIST_OF INTEGER ; default = [1, 2, 3] ; } END
The rules directory contains the rules definitions. The source for rules definitions are the files with an .mrl extension. The compiled versions of rules are contained in files with the .wic or .pkg extension. The .load file indicates the order in which the rules are loaded into the cell.
1-27
1-28
This chapter describes the fundamentals of the BAROC language. The following topics are discussed: Basic Concepts Inheritance BAROC Syntax Generalities Class Definitions Class Instances Enumerations Global Records Product Internals
2-1
Basic Concepts
The BAROC, Basic Recorder of Objects in C, language is a highly-structured language that provides the ability to capture the semantics of the events and physical and logical IT components in a format suitable for processing. BMC Impact Manager object class definitions and their instances are written in BAROC. This section describes the BAROC language syntax and properties and root class definitions. In the BMC Impact Manager product, the data structures (classes) that describe objects or entities are defined in the BAROC language. Classes are organized by their base internal class. Technically, a class is an instance of an internal base class. A class defines the attributes that describe an object type. The attribute fields are called slots in BAROC terminology. Slots are typed and have certain facets, that can control the values that the slot can have or control aspects of a class instances processing. You might think of a class definition as an empty form with its input fields representing slots. A class instance corresponds to a completed form. A valid instance must respect slot types, and if some slot values are not specified,- they are implicitly set to their default values (which can be inherited from parent classes).
Inheritance
BAROC class definitions can be organized in a hierarchy, allowing class specialization. This means that new classes can be introduced as subclasses of existing classes, called superclasses, and inherit automatically from the definitions of the superclasses. Inheritance implies that the structure defined for the superclass automatically applies to the subclass. Think of a subclass as a form with additional fields, as shown in the following illustration.
2-2
A subclass inherits all the slot definitions of the parent class and can have additional new slot definitions of its own. You can create subclasses with slot definitions that override a superclass slot definition. However, when overriding a superclass slot definition, you cannot change the data type of the inherited slot, but only its facet values. Also, no subclass can inherit from more then one superclass. There is no multiple inheritance. Any MRL rule defined for a class of object also applies to all instances of its subclasses. For example, a rule defined for the base event class EVENT applies to all events because all event classes are children of EVENT.
2-3
Symbols
In this syntax, these symbols have special meaning:
Table 2-1 Symbols
Symbols
<identifier>
Description or Usage
An identifier in angle brackets (<>) is a non-terminal symbol that is defined elsewhere in the language definition A block enclosed in brackets ([]) indicates it is an optional block. The brackets, themselves, are not language tokens. An asterisk (*) indicates a possible repetition of the preceding block. A plus sign (+) indicates one or more instances of the preceding block. A pound symbol (#) beginning a line denotes a comment line. Comments are not part of the language, they are not read by the BAROC parser
2-4
Syntax Rules
These rules apply to the BAROC language: The BAROC language is not sensitive to the number of space, tab and line break characters, with the exception of those inside quoted strings. In a class definition, there must be a trailing semicolon (;) after the last curly brace (}). This is unique to class definitions. The trailing semicolon is part of all class definitions and is required. The END keyword must be followed by new line. You can add comments to a BAROC file. A comment is a line beginning with the pound character (#).
2-5
Class Definitions
The BAROC class definitions of a Knowledge Base are stored in the classes subdirectory. The associated .load file determines the order in which the files load into the cell.
<MetaClassName> : <ClassName> [ISA <ClassName>] [DEFINES { [ <SlotName>: <SlotType> [, <SlotFacet>]* ;]* }]; END
where
<MetaClassName> = MC_EV_CLASS | MC_DATA_CLASS | MC_INTERFACE | TEC_CLASS <ClassName> and <SlotName> = an optionally quoted ( or ") sequence of characters excluding blanks " ; : , = ( ) [ ] { } <SlotType> = [ SINGLE | LIST_OF] INTEGER | REAL | STRING | <Enum> <SlotFacet>= default = <SlotValC> | parse = <YesOrNo> | dup_detect = <YesOrNo> | read_only = <YesOrNo> | key = <YesOrNo> | representation = <string>
2-6
Additional slot types INT32 and POINTER are supported for compatibility with the Tivoli TEC product.
Note
In a class definition, there must be a trailing semicolon (;) after the last curly brace (}). The trailing semicolon is inherited from the base internal class definition, it is required.
Slots
Slot definitions delimit the values that are acceptable from an incoming event as well as some characteristics of the slot called facets. In the form analogy earlier in this chapter, slots are equivalent to blank fields on the class-defined form.
Slot Types
Slot values can be simple or a list of simple values. The keyword SIMPLE identifies simple data type while LIST_OF identifies list data type. The keyword SIMPLE is optional and is generally omitted. There are four simple data types: INTEGER: 32-bits signed value REAL: 64-bit real value STRING: string (maximum 64 KB) <EnumName>: an enumeration whose definition must appear before the slot definition in the BAROC declaration file.
2-7
mc_uedid Slot
The slot mc_ueid, is the BMC Impact Manager Universal Event ID, uniquely identifies the event not only for a specific cell but also for all cells of the network. The mc_ueid slot is a very convenient way to retrieve an event in a cell hierarchy. When a cell receives a syntactically valid event with a non-empty mc_ueid, it verifies that no event has been received before with that same mc_ueid. If such event has been received, the new event is ignored. When a cell receives a syntactically valid event with an empty mc_ueid, it generates an mc_ueid of the form:
mc.<cell_name>.<event_handle> mc_udid Slot
The slot mc_udid, BMC Impact Manager Universal Data ID, uniquely identifies the data in the cell. If not set, the cell automatically generates an mc_udid of the form:
mc.<cell_name>.<data_handle>
Use this slot when importing data from an external system, such as an asset management system for example. By carefully selecting the mc_udid it is possible to identify the data in the cell that corresponds to a particular component defined in the external system.
2-8
Facets
Slot definitions can have slot facets that further define the slot by controlling the values that a slot can have or controlling aspects of a class instances processing. Slot facets include:
Table 2-2 Slot Facets
Facet default
Description
The value assigned to the slot if no value is provided in an instance. If no default facet is specified, zero (0) is the default for an INTEGER and a REAL, the empty string for a STRING and the empty list for a LIST_OF A flag that indicates whether the slot is protected against updates by incoming events. In other words, the slot value cannot be set by an incoming event. If the slot value is set by the incoming event, the cell drops the value before processing the event. Slots managed by the system usually have their parse facet set to no A flag that indicates whether the slot participates in the determination of duplicate events. This facet is used to determine whether two event instances are duplicates. For events to be considered duplicates, they must be of the same class and all their slots whose dup_detect facet is set to yes must have equal values. The concept of duplicate events is used by the cell during rule processing. When the cell is searching the cache for a duplicate event, it considers only the slots with the facet dup_detect=yes. A flag that indicates whether the slot is protected against modification by a command or a rule. A slot whose read_only facet is set to yes cannot be modified by a command or a rule. However, the system can modify this slot. A designator that specifies that the slot value is or is part of the unique key for the data object. This facet applies only to data objects. Using this facet, you can enforce the uniqueness of a class instance over the set of all key=yes slots. The facet key of a new slot (non-inherited) can only be set to yes if no inherited slots are already defined as key. A key is valid for the class and all its subclasses. An indicator that specifies how the slot should be displayed by the BMC Impact Explorer. A possible value is date.
parse
dup_detect
read_only
key
representation
2-9
This class definition example illustrates how a class hierarchy can be developed from an internal base class. For reference in this example, see the EVENT Root Class on page 2-17.
Superclass Definition
The SECURITY_EVENT class inherits all the slots of the EVENT base class.
LOGIN_EVENT inherits all the slots of SECURITY_EVENT and adds two new slots, hostname and user. These two new slots are declared with facet dup_detect=yes, indicating that two event instances of this class are duplicates if they have the same values for these slots.
2-10
MC_EV_CLASS : LOGIN_EVENT ISA SECURITY_EVENT DEFINES { hostname: dup_detect = yes ; user: STRING, dup_detect = yes ; }; END
Subclass Definition
The LOGIN_FAILURE class is a subclass of LOGIN_EVENT. It shares the same slots but the severity slot, inherited from the base EVENT class, default value is set to MINOR for this class.
AppByHost is a data class. It is a table that stores the list of applications present on each host. The host slot is defined to be the unique key of this table. The system will prevent the creation of two instances of this class or a subclass of it, that have the same host slot value.
2-11
Class Instances
Class instances represent the real and logical objects that exist in the environment.
Instance Syntax
The syntax for defining a BAROC instance is very simple, as the following illustrates.
<Class>; <Slot> = <SlotVal>;] * END
where
<SlotVal> = <SlotSmplVal> | <SlotListVal> <SlotSmplVal> = sequence of alphanumerical or _ characters |quoted ( or ") sequence of characters <SlotListVal> = [ [ <SlotSmplVal> { , <SlotSmplVal> } ] ]
2-12
Enumerations
An enumeration is a user-defined simple type. It is a list of symbols associated with an integer value. The symbolic values are ordered by their associated integer values. The cell uses the associated integer values in order to compare symbolic values.
Enumeration Syntax
The enumeration definition syntax is the following:
ENUMERATION <EnumName> [<NumVal> <SymbVal> ]* END
2-13
Several enumerations such as STATUS and SEVERITY are built into the cell.
Global Records
A global record is a class with a single instance that acts as a persistent structured global variable. The scope of global records is the entire Knowledge Base; any other variable has a scope limited to the rule in which it occurs. Global records are defined in the record subdirectory of a Knowledge Base. A record definition defines both the class and its unique instance at the same time.
Record Syntax
Global record syntax is the following:
RECORD <RecordName> DEFINES { [<Slot> : <SlotType> [, default = <DefaultValue>] ;]+ } END
2-14
In a rule, you can reference the records hosts slot using this syntax:
$UNDER_MAINTENANCE.hosts
2-15
Product Internals
In the BMC Impact Manager, cells contain a certain number of internal BAROC definitions. Some of these definitions, commonly called core definitions, can be modified to some degree in each Knowledge Base. Modifying a core definition should be done with caution. Whenever possible you should avoid working directly on the base event class, and use subclasses instead.
2-16
Slot adapter_host
Definition STRING
Description
The name of the machine on which the adapter that sent the message resides. Name of the entity that last modified the event, as user@host or package:rulename. If empty when entering the cell, it is set as the textual format of date_reception, as defined with the parameter DateFormat. Time stamp that is set by the adapter or gateway that sends the event. If not set by the source, on its arrival at a cell, its value is set to the value of incident_time. If there is no incident_time value, its value is set to the mc_arrival_time value. Elapsed time, in seconds, between the date_reception time and the time at which the event was closed. Event identifier in the local cell.
administrator
STRING
date
STRING
date_reception
duration
event_handle
2-17
Table 2-3
hostname
STRING
Name of source machine, as a fully qualified domain name, if available. This slot is deprecated and may be removed in the future. System reserved. System reserved. A list of the additional roles that can access the event. Role ownership for the event is determined by adding roles defined in this slot to those roles defined on a collector that contains the event. Event-level, role-based access is implemented in BMC Impact Explorer. Counter contains the number of programs run for this event. Time stamp at which the event arrived at the BMC Impact Manager network at either an adapter or a cell. Its value is never zero (0). System reserved. Names of slots with a parsing error. Corresponding values of slots with a parsing error. System reserved. System reserved. The effective IP address of the client that sent the event. This slot replaces the former mc_origin slot. Time stamp of last modification of certain slots. The slots are those mentioned in mcell.modify.
LIST_OF INTEGER, parse = no; LIST_OF INTEGER, parse = no; LIST OF STRING, parse = no;
mc_action_count mc_arrival_time
INTEGER INTEGER, representation = date; LIST_OF STRING; parse = no; LIST_OF STRING LIST_OF STRING INTEGER, parse = no; LIST_OF STRING; parse = no; STRING, parse = no; INTEGER, representation = date;
mc_date_ modification
2-18
Table 2-3
System reserved. System reserved. Fully-qualified name of the host on which the problem occurred. Typically, the network address corresponding to mc_host. Technically, this slot can contain some other type of information in situations in which a host value is not meaningful. A type of host. This field is important to implementing generic actions, such as rebooting a machine on which a problem has occurred. In the background, a generic action can be translated into a specific action based on this field. Time stamp corresponding to the time at which the incident causing the event occurred. Its value is zero (0) if the time unknown. This time stamp can be set by an adapter or a gateway. ITIL process that is influenced by this event. Possible examples are: AVAILABILITY, SECURITY, CHANGE, PERFORMANCE, INCIDENT, SLM, CHANGE. Time stamp when the event arrived in the local component. It is never zero (0). Location at which the managed object resides. System reserved.
mc_host_class
STRING;
mc_incident_time
mc_it_mgt_process
STRING;
2-19
Table 2-3
mc_notes
LIST_OF STRING;
A list of free text annotations added to the event. The contents of this slot is implementation-dependent. Rules or users should not rely on a particular value in this slot. To use this slots contents, you must use the appropriate access functions. String that identifies the subcomponent that caused the event on the host. If this value cannot be derived from the original event, it should be acquired as part of event enrichment, possibly during the Refine event-processing phase. String that identifies the class to which mc_object belongs. Event-management system that is as close as possible to the event source. For example, PATROL agent -> BMC II for PATROL ->BMC EM. The mc_origin value would be the PATROL agent name. The mc_tool value would be string composing the PATROL agent name and its port. This slot has been redefined. The former mc_origin slot is renamed to be mc_client_address slot.
mc_object
STRING;
mc_object_class mc_origin
STRING; STRING;
mc_origin_class
STRING;
Identifier that indicates the type of event-management system that originally issued the event. This slot may have the same value as the mc_tool_class slot. Unique key with which the originating event-management system enumerated the event. In a two-tiered, event-management system, this might as the same value as the mc_tool_key slot.
mc_origin_key
STRING;
2-20
Table 2-3
mc_origin_sev
STRING;
Severity value given by the mc_origin. In a two-tiered, event-management system, this might as the same value as the mc_tool_sev slot. Name of the parameter that by going into alarm or by triggering a state change caused the event. The actual value of the parameter that caused the event. System reserved. System reserved. System reserved. System reserved. System reserved. System reserved. Any value that can more closely identify the event provider (tool) within the specified mc_tool_class. A primary use of the field is to provide the information necessary to enable an external action to initiate communication with the event provider. For example, If the mc_tool_class is PATROL, the mc_tool value should be a string composing the PATROL agent name and its port value so that an external action can trigger communication with it.
mc_parameter
STRING;
STRING; LIST_OF STRING, parse = no; LIST_OF STRING, parse = no; LIST_OF STRING, parse = no; STRING INTEGER, Default = 0; STRING; STRING;
2-21
Table 2-3
mc_tool_class
STRING;
An identifier that indicates type of event provider (tool) that reported the event to the cell. Typically, each type of adapter has a specific mc_tool_class value; for example, SNMP. T The identifying value, itself, is not important, but different tools should not use the same identifier. The cell does not enforce this constraint. Unique key with which the sending tool enumerated the event. Severity value from the mc_tool. This value does not have to be the same as the severity assigned by BMC Impact Manager. For example, To the IT staff, a failed router is a critical alert. But, if there is a back-up router, the event is not critical from a service viewpoint. Universal event identifier. Text that describes the incident. IP address of source machine. This slot is deprecated and may be removed in the future.
mc_tool_key mc_tool_sev
STRING; STRING;
Number of times that the same event has been received. Severity of the event. Name of the source entity where the event occurred. This slot is deprecated and may be removed in the future. Status of the event.
status
STATUS, default=OPEN;
2-22
Table 2-3
sub_origin
STRING
Address of source component. This slot is deprecated and may be removed in the future.
sub_source
STRING
Component of the source. This slot is deprecated and may be removed in the future.
2-23
data_handle
INTEGER, parse = no, read_only = yes; STRING, read_only = yes; INTEGER, parse=no; read_only=yes, representation= date INTEGER, parse=no; read_only=yes, representation= date
mc_udid mc_creation_time
mc_modification_time
Modification time
2-24
Internal Enumerations
There are two internal enumerations: STATUS SEVERITY
Modifying these enumerations is not recommended, except to add new values. Removing some built-in values or modifying their order may render the cell unable to perform its tasks.
Event Status Enumeration
The event STATUS enumeration lists the possible status values for an event. They are:
ENUMERATION STATUS 0 OPEN 10 RESPONSE 20 ACK 30 CLOSED END
Severity Enumeration
The SEVERITY enumeration lists the possible severity values for an event. They are:
ENUMERATION SEVERITY 10 UNKNOWN 20 OK 30 INFO 40 WARNING 50 MINOR 60 MAJOR 70 CRITICAL 80 DOWN END
2-25
There are a number of internal, built-in enumeration, data, event and record classes defined in the cell that are used and maintained by each cell.
2-26
MC_CELL_CONTROL
MC_CELL_CONTROL is the base class of events generated internally by the cell. The hierarchy of these classes is:
MC_CELL_CONTROL MC_CELL_START MC_CELL_STOP MC_CELL_TICK MC_CELL_STATBLD_START MC_CELL_STATBLD_STOP MC_CELL_DB_CLEANUP MC_CELL_CONNECT MC_CELL_CONNECT_RESOURCES_EXPANDED MC_CELL_CONNECT_SUSPENDED MC_CELL_CONNECT_RESUMED MC_CELL_CLIENT MC_CELL_ALLOWED_CONNECT MC_CELL_UNALLOWED_CONNECT MC_CELL_DISCONNECT MC_CELL_MODIFIED_EVENT MC_CELL_DESTINATION_UNREACHABLE MC_CELL_HEARTBEAT_EVT MC_CELL_HEARTBEAT_ON MC_CELL_HEARTBEAT_FAILURE MC_CELL_PARSE_ERROR MC_CELL_UNDEFINED_CLASS MC_CELL_PROCESS_ERROR MC_CELL_RESOURCE MC_CELL_RESOURCE_OVERFLOW MC_CELL_RESOURCE_EXPANSION MC_CELL_ACTION_RESULT
See the BMC Impact Manager Administrator Guide for an explanation of these classes.
2-27
MC_CELL_DATA
Each cell maintains some internal data. Their base class is MC_CELL_DATA. The class hierarchy is:
MC_CELL_DATA MC_CELL_DIR_COMPONENT MC_CELL_REGULATE MC_CELL_HEARTBEAT MC_CELL_METRIC
See the BMC Impact Manager Administrator Guide for a detail discussion of these classes.
Service Management Specific Object Classes
A number of enumerations, event and data classes are also built-in for the Service Management feature of the BMC Impact Manager product. These are discussed in the Building a Service Model Guide.
2-28
The rule engine is part of the cells event processing capabilities. In order to create Knowledge Bases, it is important to understand how the engine works. This chapter presents an overview of the rule engine and the processes it performs. Topics are discussed in the following order. Order of Rule Evaluation in the Knowledge Base Incoming Event Processing Internal Event Processing Internal Requests Propagation
3-1
3-2
Event
Refine Discard Event Filter Regulate New Timer Abstract Correlate Delete Execute Propagate Repository
Although this illustration may seem to indicate that all events in all conditions follow the same phase order, this is not the case. In addition to new incoming events there are existing events that are reprocessed through the rule phases.
3-3
3-4
Internal Requests
During the processing of an event, the rule engine can generate requests that it processes later. These requests can be: Modifying a slot in an event. The When clauses of rules must be evaluated. Setting of timers. Timer rules execute at the end of the time window. Time windows on Regulate rules. Programs in the Refine phase returning. Monitored remote actions returning. Performing the cleanup. When the time comes, the rule engine removes the old events and evaluates the Delete rules.
All requests are executed in a first in, first out order before anything else is processed.
3-5
Propagation
Events that are to be propagated during the Propagate phase are queued in buffers as a precaution in case the destination is not available. Those failed destinations are retried according to the retry parameters. The rule engine processes retries between the processing of events.
3-6
The rule language, also called the Master Rule Language, or MRL, is a compact and powerful declarative language used to determine and control the behavior of the cells. Rules reside in the rules subdirectory of a Knowledge Base. Rule files have an .mrl extension. Rules must be compiled before they can be used by the cell. The compiled files have a .wic or .pkg extension and are in the same rules subdirectory as those files with an .mrl extension. The order of loading into the cell at startup, which determines the order of evaluation, is specified in the .load and .loadwic files (files with the compiler extensions). Chapter 5, The Rule Phases, addresses the purpose of each rule phase with programming examples. This chapter focuses on the syntax of rules and the roles of the different objects and syntactic constructs. The following topics are discussed: General Rule Syntax Objects, Types, and Variables Selection Criteria When Clauses Body Clauses General Rule Writing Constraints
4-1
<Type of Rule> <RuleName> : <ClassName> (<var>) where [<expression> <op> <expression>, . . ., <expression> <op> <expression>] using [ALL] where { <ClassName> (<var>) where [booleanExpression], . . ., <ClassName> (<var>) where [booleanExpression] } {<call>; . . .; <call>; <var>.<slot>=<expression>;} END
The preceding generic rule is not complete, nor absolutely correct from a syntactic point of view, but it illustrates an overview of all the syntax objects discussed in this chapter. For a complete and rigorous definition of the language, see Appendix A, Master Rule Language Reference. For details on particular rules, refer to Chapter 5, The Rule Phases. The portion of the rule syntax being discussed in the following paragraphs is in bold letters for ease of reference. The first line specifies the phase for which the rule is written. You may choose one of: refine, filter, regulate, new, abstract, correlate, execute, propagate, timer or delete. The next step is to give the rule a name, which must be unique across the entire Knowledge Base. It must be an alphanumeric string and may include underscores (_). The rule name should be descriptive because it appears in tracing and log output.
4-2
This section is called the selection or the Event Condition Formula (ECF). Its role is to specify the conditions that the event being processed must meet in order for the rule to be evaluated. The exact syntax is:
<ClassName> (<var>) where [<expression> <op> <expression>, . . ., <expression> <op> <expression>] using [ALL] where { <ClassName> (<var>) where [booleanExpression], . . ., <ClassName> (<var>) where [booleanExpression] }
This section is the part of the ECF called the Using clause. It is optional. Its use is primarily to direct the rule engine to retrieve data from the dynamic Data repository to be used in the remainder of the rule. The exact syntax is detailed below.
using [ALL] where { <ClassName> (<var>) where [booleanExpression], . . ., <ClassName> (<var>) where [booleanExpression] }
Note
This manual includes the optional Using clause when discussing the ECF. This section is called the body of the rule. It is here that actions are performed on the events, slots are modified and primitives are called. The syntax of the rule body and semantics of the primitives depends highly on the phase to which it belongs. Details of both are in Chapter 5, The Rule Phases.
4-3
The When clause syntax in the current version of the BMC Impact Manager product differs from that in prior versions in that the colon (:) notation is now optional and is maintained for backward compatibility only. Its use is discouraged because it is confusing with respect to the Where syntax in which $EV.slot: is illegal, although slot: is a shortcut for $EV.slot.
Events
Event classes and instances are discussed in detail in Chapter 2, The BAROC Language. Events are discussed here in the context of the rule engine. The rule engine deals with event instances.They can originate in an external source such as an adapter, another cell, or a CLI, or they can be generated internally by the rule engine. Event instances that have been processed once and reside in the repository can be reprocessed if their slot content is modified, usually by an operator or a rule.
4-4
The rule engine evaluates rules in the context of a single event instance at a time. There is always one, and only one, event under evaluation at a time. The rule engine may search for and modify other events while evaluating a rule, as discussed in the following section.
Data
Data or dynamic data objects are used as a dynamic, persistent repository. When the cell evaluates a rule for an incoming event, it can query the dynamic data tables to determine the context in which the rule is applicable. The data instances are not known when the rules are created, so the association statements must be expressed as queries on the set of data. The rules are then further evaluated using the results from these queries. In the following example, the business impact of an unavailable application governs the severity level of the associated APP_DOWN event. Upon receiving an APP_DOWN event, an Execute rule checks the instances of the SEVERITY_BY_APP_DOWN data class and retrieves the first instance that matches the application name set in the APP_DOWN event. The instance contains the appropriate severity to associate with the application, so the rule makes the assignment as the following indicates.
execute Set_App_Down_Severity : APP_DOWN ($AD) using SEVERITY_BY_APP_DOWN ($SBAD) where [$SBAD.application == $AD.application] when $AD.status == OPEN { $AD.severity = $SBAD.severity; } END
4-5
The rule searches the data instances to find the instance that equals the application in the APP_DOWN event. Once a match is found, the rule stops searching the data instances and continues processing with the matching instance, as follows.
The data must be populated beforehand, otherwise the rule engine does not find any instance and the remainder of the rule is skipped. In other words, when the Using clause is present in a rule it must return data or the selection fails and the remainder of the rule is skipped. Data tables can be indexed by specifying the key=yes facet for one or more slots of the data class definition. Keys must be unique and if a key is set, the rule engine prevents creation of multiple instances with the same key. Using an index dramatically improves the performance of a query in the data repository. This is particularly true for large tables, so be certain you are using keys and are writing rules that use key slots in the Using construct.
Note
Rules cannot update any slot that is part of the key. A dynamic data key record cannot be modified. It must be deleted and recreated with the new contents. A dynamic Data slot which is a key is implicitly read-only. The compiler refuses any modification to these slots.
4-6
Global Records
Global records are the ancestor of dynamic data. Global records can be understood as persistent structured global variables. The scope of these variables is the entire Knowledge Base; any other variable has a scope limited to the current rule. Global records are addressed by name and you must know the global record names to use them. For example, a global record called UNDER_MAINTENANCE has the following definition.
In a rule you can refer to one of the slots by using the following syntax:
$UNDER_MAINTENANCE.hosts
Interfaces
Interfaces are used only in Refine rules. In a Refine rule you can either confirm the information contained in the incoming event or complete it with additional information. Interfaces are used in conjunction with programs to pass information back to the rule engine. The refine rule is used to refine the information contained within the event. External information may be obtained for inclusion in the event through a call to the get_external() primitive. The first argument to get_external() is the name of the script or executable to be run. The second argument is a LIST_OF_STRING defining the arguments that will be passed to the script or executable. The third argument is the type of interface and the fourth, and last, argument is the variable that will hold the results of the action run. An example is the following call to get_external.
BMC Software, Inc., Confidential and Proprietary Information
4-7
The name of the file in which the results of the action are to be written in the BAROC format defined by the interface is prepended to the list of arguments. The data type expected in the file is of type location, defined in the following example.
An example of the script or executable passed as the first argument follows. For Microsoft Windows platforms the executable get_site.bat should be placed in the kb\bin\w4 directory.
For Unix environments the executable get_site.sh should be placed in the kb/bin/A directory.
#!/usr/bin/ksh echo location\; > $1 echo site=Austin\; >> $1 echo phone=512-219-5086\;>>$1 echo END >> $1 exit 0
4-8
Examples of Refine rules using this mechanism can be found in Chapter 5, The Rule Phases.
Types
Types used in rules are the same as those defined in the BAROC language. You should ensure that, in writing expressions, the types used in both sides of the expression are the same or at least compatible. Otherwise, the rule may fail to evaluate correctly. The compiler may not be able to detect an error when dynamic expressions from the dynamic data are computed at run time. Some type conversions are performed automatically. An enumerated type is automatically converted to an integer if assigned to a variable of type integer. The reverse conversion works as well, but the compiler will issue a warning saying that it cannot guarantee the conversion at run time, as the integer value may not be one of the enumerated values. The compiler checks the variable types and will flag all type incompatibilities, such as a comparison of two enumerated values of different types. Variables in MRL are declared automatically at the first occurrence in the text. The scope of a variable is from its declaration to the end of the rule. Apart from global records, there is no concept of global variables in MRL. A variable is an alphanumeric string that may include underscore are permitted) preceded by a dollar sign, such as $EV.
Note
BMC Impact Manager uses only short uppercase names, so you may want to use the same convention. Most variables are used to point to MRL objects such as events, data, global records or interfaces, but they can also be used to refer to results returned by a primitive. Variables are valued at first occurrence. The value cannot change during the life of the variable. For example, you cannot assign another value to a variable after the first occurrence in a rule. They also obtain their type at the moment of assignment.
BMC Software, Inc., Confidential and Proprietary Information
4-9
In the following construct, the variable $EV points to the event under analysis, so that $EV.<slotname> refers to that particular slot. The slot also must exist in the BAROC definition of that object class.
<ClassName> ($EV) where [<expression> <op> <expression>, . . ., <expression> <op> <expression>]
You then can use the variable in expressions later in the rule or in assignment statements. In the following example, the variable $DATA refers to the data object retrieved by the Using clause, so that the $DATA.<slotname> refers to that particular slot. The slot also must exist in the BAROC definition of that object class.
using [ALL] where <ClassName> ($DATA> where [booleanExpression], . . ., <ClassName> ($DATA) where [booleanExpression] }
You then can use the variable in expressions later in the rule or in assignment statements. The same principles apply to the interface objects where a variable points to the instance returned by the external program and allows the use of the individual slot values in subsequent expressions. Global records are somewhat different, as their instances are predefined in the Knowledge Base. The scope of those variables is, then, the entire Knowledge Base. A variable $UNDER_MAINTENANCE will refer to the unique instance of the UNDER_MAINTENANCE global record. You can use variables in primitives to obtain the values they return. For example:
4-10
The concat builtin concatenates a list of strings into another string. In the preceding example the $MSG variable obtains the result, so it can be used in subsequent clauses. The preceding example uses the result as an assignment. It is important to remember that variables can be assigned a value only once.
Selection Criteria
Selection criteria determines whether an event that is being processed is triggering execution of the rule, based on its conformance with the criteria specified in the rule.
4-11
A rule starting with the following will accept the instance and will be evaluated.
Note
Using EVENT as the name will accept ALL instances of incoming events.
4-12
Where Clauses
The Where clause allows you to establish more restrictive selection criteria. It consists of the keyword where followed by the criteria within square brackets:
where [ <criteria> ]
The <criteria> portion of the statement is a logical combination of expressions about the slots of the event. Following is a set of syntax examples valid for <criteria>.
The preceding syntax requires the hostname slot of the event under analysis to be literally thishost.
APPLICATION_EVENT ($APEV) where [ $APEV.hostname == thishost OR $APEV.hostname == thathost AND NOT $APEV.source contains NT; ]
The preceding shows a combination of the Boolean OR, AND, and NOT. Note that the AND has precedence over the OR, and the NOT has precedence over the AND. The same rule could be written using parentheses.
4-13
APPLICATION_EVENT ($APEV) where [ ($APEV.hostname == thishost) OR (($APEV.hostname == thathost) AND (NOT ($APEV.source contains NT))); ]
APPLICATION_EVENT ($APEV) where [ ($APEV.hostname == thishost OR $APEV.hostname == thathost) AND $APEV.source contains NT; ]
Previous releases of the MRL used the hostname:equals thathost notation and is permitted only for backward compatibility in the current version. In a Where clause slot: is a shortcut for $EV.slot. Note that $EV.slot: is syntactically correct.
4-14
Also,
is equivalent to:
$APEV.hostname == thishost AND $APEV.hostname == thathost
You also can refer to the class name in the Where clause, as the following illustrates.
EVENT ($EV) where [ $EV.CLASS == APPLICATION_EVENT ; ]
The line:
$EV.CLASS == APPLICATION_EVENT ;
However, the two are not equivalent. First, the class name is compared literally, by checking that the name of the class is the string APPLICATION_EVENT. This literal comparison does not take advantage of the inheritance mechanism. Second, not accessing the inheritance mechanism places a much heavier demand, in terms of performance, on the rule engine. The rule engine maintains an inheritance table that allows it to be extremely efficient at manipulating classes. Using class comparisons in the Where clause does not use that inheritance table optimization and results in performance degradation.
4-15
For performance reasons, try to select events based on the name as much as possible and design a good hierarchy of classes. Also, try to avoid performance intensive Where clauses when possible. In addition to the arithmetic and logic operators, the condition operators used in the Where clauses can be selected from a large list, as follows:
.
equals not_equals greater_than greater_or_equal smaller_than smaller_or_equals between within outside has_prefix has_suffix
contains contains_one_of contained_in matches ip_greater_or_equals ip_smaller_or_equals ip_matches ip_matched_by superclass_of subclass_of
MRL also contains a large list of primitives and functions that can be used in expressions. An exhaustive list of primitives, functions, and operations can be found in Appendix A, Master Rule Language Reference.
Using Clause
The Using clause retrieves information from the rule engines repository to be used in the context of the rule. It is used most often to fetch data instances for dynamic rules, but it can be used to retrieve instances of past events.
4-16
The syntax is very similar to the event selection criteria discussed above.
<EventClassName> (<Variable>) where [<Expression> <CondOperator> <Expression>, ...] using | using ALL {<DataClassName> (<Variable>) where [<Expression> <CondOperator> <Expression>, <Expression> <CondOperator> <Expression>, ...]; <DataClassName> (<Variable>) where [<Expression> <CondOperator> <Expression>, <Expression> <CondOperator> <Expression>, ...]; ... ; }
4-17
The example from the previous section follows for use in the current discussion of the Using clause.
execute Set_App_Down_Severity : APP_DOWN ($AD) using SEVERITY_BY_APP_DOWN ($SBAD) where [$SBAD.application == $AD.application] when $AD.status == OPEN { $AD.severity = $SBAD.severity; } END
The data impacts the processing of the rules, particularly in the following situations. If no data is found for the specified criteria, the remainder of the rule is skipped. If one instance of data is found, the rule is evaluated for that instance. If more than one instance exists, only the first will be fetched. This behavior can be altered by using the ALL keyword. If the ALL keyword is used and more than one instance of data is found, the rule is evaluated for each instance. ALL contains a hidden recursive mechanism that produces this result. If several blocks are present in a Using clause, the rule engine will search for an instance corresponding to the first criteria, then an instance for the second, and so on through each block. There must be at least one instance of each block for the rule to evaluate. If the ALL keyword is used, the rule will be evaluated for all combinations of the instances found. For example, if a Using clause has two blocks, the first one retrieves three instances and the second five, the rule will be evaluated a total of fifteen (3 x 5 = 15) times.
4-18
Using clauses also can search the repository for instances instead of data. In order to do this, simply write a valid criteria block with a valid Event Name instead of a Data Name.
Note
Exercise caution in searching the Repository for instances of events because the Events, unlike data, are not indexed, and this may result in dramatic loss of performance. The only queries that are optimized are those that use an equality constraint on the mc_ueid, such as $EV.mc_ueid == <expression>.
When Clauses
When clauses are present in Execute, Abstract, Correlate, and Propagate rule phases. These rules are evaluated in two different situations. A new event is processed and the condition is met. A previously received event is modified in such a way that the When condition is met.
Note
When an event slot is modified by a rule containing a when clause so that it becomes a candidate for evaluation by another rule, that evaluation does not take place immediately. Instead, the request is queued for the rule engine to process after it processes all other pending requests or events. In prior versions of the BMC Impact Manager product the following syntax supported the following notation:
when $EV.slot: [<cond> <expr>]
4-19
This syntax is supported in the current version of the BMC Impact Manager product for backward compatibility only. The slot: shortcut is not applicable in a when clause.
Body Clauses
Most rules allow slot assignments or primitives to be called in Body clauses. A generic Body clause is:
{ <Var>.<Slotname> = <Value>; <Call> ; }
All statements in a Body block must be terminated with a semicolon (;) except for the last of the block, which is optional. You can consider the semicolon as a statement separator. A slot assignment has the general form:
$EV.slotname = <expression>
A Body block is, in general, the place for calling a primitive or a function. Functions return an expression, while primitives return a Boolean value expressing the success or failure of the primitive. Most primitives have an equivalent function.
Note
When a primitive fails, that is, returns the value FALSE, the remainder of the block is not executed. Some primitives are not allowed in all rule phases. See Appendix A, Master Rule Language Reference. for more information on primitives and their use.
BMC Software, Inc., Confidential and Proprietary Information
4-20
If <Expression> is evaluated as TRUE, the statements of the then body are executed. Otherwise, if there is an optional else part, the statements of the else body are executed. It is possible to refer to a local variable declared in the then and else body after the if-then-else call, provided that this variable is declared in both the then and else body with the same type.
4-21
if <Boolean expression> then { ... $TEMP = yes ; ... } else { ... $TEMP = no; ... }; $EV.msg = $TEMP;
is not correct because $TEMP is declared as an INTEGER in the then body but it is a STRING in the else body. It also is incorrect to refer to a local variable that is not declared in both the then or else body.
4-22
Note that it is unnecessary to use an if-then-else construct to create a conditional affectation. A simpler solution is to use a conditional expression. For information about conditional constructs see Appendix A, Master Rule Language Reference.
4-23
4-24
This chapter discusses and illustrates with practical examples the syntax and the semantics that control the behavior of the rules for each of the ten (10) rules phases. An overview of the rule phases is available in Rule Phases for Event Processing, in Chapter 1, BMC Impact Manager Overview. The rule phases are addressed in the following order: Refine Rule Phase Filter Rule Phase Regulate Rule Phase New Rule Phase Abstract Rule Phase Correlate Rule Phase Execute Rule Phase Propagate Rule Phase Timer Rule Phase Delete Rule Phase
5-1
The Refine rule phase collects additional information about the event before further processing takes place. This may include verifying the validity of the incoming event. Refine rules can invoke external processes to confirm information or collect additional information about an event. Any new information returned by the query must conform to the events BAROC interface model.
5-2
An ECF (Event Condition Formula) definition included in a rule is similar to the following.
<ClassName> <Variable> where [<Expression> <CondOperator> <Expression>, <Expression> <CondOperator> <Expression>] using <DataName> <DataVariable> where [<Expression> <CondOperator> <Expression>, <Expression> <CondOperator> <Expression>]
The confirm_external primitive will execute an external program. Successful completion of the program will permit further processing of the event. A failure causes the event to drop from further processing. The program resides in the bin subdirectory of the Knowledge Base under the appropriate architecture directory. You can pass arguments to the program through the Arglist parameter, which is a list.
5-3
get_external will execute an external program. Arguments are passed through the Arglist parameter, which is a list. The output of the program is retrieved in a structure pointed to by the variable Var. That structure is an interface of class INTERF, that must be defined in the Knowledge Base. The results can be used in subsequent calls or assignment by manipulation of the variable.
Note
refine Disk_Full_Contact_Info : DISK_FULL ($DF) { get_external (get_site.sh, [], LOCATION, $LOC); $DF.msg = $LOC.site ; } END
get_external will call the script get_site.sh, with no arguments, as indicated by the empty list [ ] as second parameter. The return format follows the LOCATION syntax and the result is pointed to by the $LOC variable.
5-4
Finally, the site information is put in the msg slot of the incoming event.
5-5
5-6
The next step for an event that does not match the Filter is just the opposite. That is, an event that does not match the Filter is passed by a NOPASS Filter to the next Filter, and is discarded by a PASS Filter.
Rule f1 specifies that any events from hosts svr1 and svr2 and login events are accepted. Rule f2 says that any harmless events and all successful login events are discarded. Both rules must apply for an event to be accepted. The following events are processed by the two Filter rules set forth above. Event 1
5-7
This event is accepted by Filter f1 because it is a LOGIN_EVENT, even if its hostname is not svr1 or svr2. It then is discarded by Filter f2 because it is a LOGIN_SUCCESS. The event is dropped and undergoes no further processing. Event 2
LOGIN_FAILURE; hostname=clt1; severity=WARNING; END
The event is accepted by the Filter f1 because it is a LOGIN_EVENT. It is not discarded by Filter f2 because its severity is not HARMLESS and it is not a LOGIN_SUCCESS. The event is thus accepted for further processing. Event 3
5-8
This event is not accepted by f1 because hostname is not one of svr1 or svr2 and it is not a LOGIN_EVENT. Filter rule f2 is not considered, even if it would not discard the event, because the event is discarded by a previous rule f1. The event is discarded.
Note
The order of evaluation of the rules is not important from a functional point of view. An event must match all filters in order to be accepted. Regardless of the order in which an event is evaluated against the filters, if there is one non-matching instance the event will be discarded. From an operational point of view, the order of Filter rules does have an impact because evaluation of the event stops as soon as it is discarded by one of the filters. To improve processing efficiency, it is recommended that you place filters first in order of evaluation that will discard more events.
5-9
An event in the Hold queue is released when the Hold condition is met. It can be either the $FIRST, a literal string in the rule, $LAST, $HISEV, or $LOSEV event that triggered the Hold condition. A new event is generated and the rule defines its class type and its initial slot values.
The time windows for the Hold and Unless clauses are sliding windows. The Unless window resets the rule after it executes. After the Hold or Unless clause executes, all events in the window are dropped from consideration and the beginning point of the time window moves to the next event received for consideration. The time frame is specified in seconds, minutes, hours, or days.
regulate <RuleName> : ECF hold <#Events1> within <TimeFrame2> send { <ClassName> ; <SlotName> = <Value> ; ... } [ unless <#Events3> within <TimeFrame4> close ] END
5-10
The repeat_count slot of the forwarded event is set to the number of events in the Hold queue. Regulate rule form 2 sends an instance of a custom event. Of course a valid BAROC class definition must exist in the Knowledge Base. The send portion is much the same as a BAROC instance for the event, except that the right-hand side of the equal sign can contain expressions. The Unless clause may be used as a minimum threshold to reset the mechanism. If no Unless clause is present, a new time window is started. It is possible to write dynamic Regulate rules. The values for the number of events and the time windows (#Events1, TimeFrame2, #Events3, TImeFrame4) can be expressions. It is possible, by writing a Using clause in the ECF, to obtain values from the dynamic data tables and use them in these parameters.
5-11
regulate User_Authentication : LOGIN_FAILURE ($LF) where [ $LF.user outside [root, Administrator] ] hold 5 within 1m send $FIRST END
In the following second example, the Regulate rule monitors the availability of swap space and alerts the administrator of the condition by sending a Repeated_SwapAvail_Low event.
regulate Swap_Availability : SwapAvail ($SA) hold 4 within 2m send { Repeated_SwapAvail_Low ; hostname = $LAST.hostname ; origin = $LAST.origin ; msg = Swap space low condition ; } unless 2 within 5m close END
The Unless clause in the preceding example is used to determine whether the frequency of duplicate events decreases. If the number of SwapAvail events received by the cell decreases so that only one remains within five minutes, the Repeated_SwapAvail_Low event will be closed.
5-12
The following example of a dynamic Regulate rule is premised on the assumption that you have designed and populated a dynamic Data table similar to the following:
MC_DATA_CLASS : REGULATE_DATA ISA DATA DEFINES { rd_slot_str: STRING, key=yes; rd_slot_hold: INTEGER; rd_slot_hwithin: INTEGER; rd_slot_unless: INTEGER; rd_slot_uwithin: INTEGER; }; END
Assume further that machine names start with production or research, as in production23 or research08.
5-13
regulate dynamic_reg : SwapAvail ($REV) using REGULATE_DATA ($DATA) where [ $REV.hostname contains $DATA.rd_slot_str ] hold $DATA.rd_slot_hold within $DATA.rd_slot_hwithin send { Repeated_SwapAvail_Low ; hostname = $LAST.hostname ; origin = $LAST.origin ; msg = Swap space low condition ; } unless $DATA.rd_slot_unless within $DATA.rd_slot_uwithin close END
This compact rule will, in effect, use different constants for the regulation of SwapAvail_Low event, depending on whether the machine is a production machine or a research machine. During the evaluation of the Using clause the appropriate instance is retrieved from the dynamic data tables. Note that if no instance of data can be found by the evaluation of the Using clause, the regulate does not occur.
5-14
The dup_detect=yes slots cannot be changed after the event becomes permanent. Such slots can be modified in the Refine and New rule phases but not in subsequent rule phases. The duplicate aspect of the event is permanently set, and as a result the dup_detect slots cannot be modified. If an event is CLOSED before the New rule phase, a search for a duplicate event is conducted and, if found, is closed. The new event is dropped and no subsequent rule is executed. This is the default behavior. It can be disabled by setting the global configuration parameter EventAutoClose to No in the mcell.conf file. For more information on this topic see the BMC Impact Manager Administrator Guide.
5-15
The use of time windows limits the number of events that the rule engine has to search in the repository. Use time windows whenever possible as they have a positive impact on performance. The drop_new primitive can be used in a block to discard the incoming event. A typical use for this is when an event of a certain class is used only to close another event but otherwise does not need to enter the system. drop_new has no arguments and cannot be used in other rule phases.
5-16
new UpClosesDown : HOST_UP($IN_HU) where [ status: equals OPEN ] updates HOST_DOWN($ORIG_HD) where [ status: equals OPEN, hostname: equals $IN_HU.hostname ] { $ORIG_HD.status = CLOSED; drop_new; } END
Note that if there is no old HOST_DOWN event or if it is already closed, the block is not executed. In particular, the new event is not dropped. In order to drop it in all cases, you should use a Triggers block as well, similar to the following.
new UpClosesDown : HOST_UP($IN_HU) where [ status: equals OPEN ] triggers { drop_new; } updates HOST_DOWN($ORIG_HD) where [ status: equals OPEN, hostname: equals $IN_HU.hostname ] { $ORIG_HD.status = CLOSED; } END
The new event is dropped only at the end of the rule, so the drop_new primitive can be used anywhere in the blocks. The next example illustrates how to use the duplicate keyword to keep an old event updated while discarding all the new events.
5-17
new Duplicate_Disk_Used_Percentage: DISK_USED_PERCENTAGE ($IN_DUP) updates duplicate($ORG_DUP) where [ status: not_equals CLOSED ] { $ORG_DUP.value = $IN_DUP.value ; $ORG_DUP.repeat_count = $ORG_DUP.repeat_count + 1 ; drop_new ; } END
The rule searches the Repository for a another DISK_USED_PERCENTAGE event. If one is found, it is updatedthe old value is replaced by the new one and the repeat_count is incrementedthen the new event is dropped. Note that if no old event exists, the new event is not dropped. It enters the repository and will be updated by subsequent duplicate events.
5-18
A common use of abstraction rules is to keep lower level events in cells that are in the lower levels of the cell hierarchy, abstract them into high level events and propagate these high level events to a higher level cell. In this way the cell in a higher level of the hierarchy can consolidate abstraction events from several cells at lower levels and prevent a flood of large numbers of abstracted technical events for which no consolidating rules apply. A console user still has the option to explore the relationships from the higher cell to the lower cells to obtain specific details of abstracted events.
5-19
The rule performs an implicit duplicate detection. For example, assume that there are no events at all in the system. When the first event is received that matches the from ECF, a new abstract event is generated. When a second arrives that would lead to the same abstract event, the rule engine checks whether a duplicate of the candidate event exists. In this case, a duplicate exists, so the instance of the duplicate event is used in the remainder of the rule. The Setup block is executed every time the rule fires with a new low-level event. Note that because of the anti-duplication mechanism, the Setup block is executed either in the context of a new abstract event or in the context of the duplicate. In other words, the variable points to a new event or to an old one, depending on the circumstances. The Setup clause initializes, or updates, slots for the abstraction event. If slot values are not specified in the Setup clause, then the default values are assigned. The behavior of the Setup block makes it a poor location in which to use a primitive. If you need the functionality of a primitive in the Setup block, it is recommended that you use the primitives function equivalent. The When blocks are evaluated when a new event is received as well as when a slot change has occurred for either the abstract event or any of its related events. When an Abstract rule fires, events are updated to store references to their abstraction/abstracted from events: The mc_abstractions slot of the abstracted from event contains the list of abstraction, or high-level, events the low-level event generated. The mc_abstracted slot of the abstraction event contains the list of abstracted from, or low-level, events that created the high-level event.
5-20
The Setup clause populates the slots of the abstraction, or SERVERS_LOGIN_ATTACK, event. The When clauses keep a count of servers under login attack by incrementing the num_servers slot when the LOGIN_FAILURE events status is OPEN and decrementing the count when the event closes. In another example, an Abstract rule creates an abstraction event, APP_MISSING_PROCESS, upon receipt of a PROCESS_DOWN event. One abstract event will exist if any of the processes in question has failed. The Setup clause populates the new abstraction events slots. The When clauses add and remove processes from the list of down processes as their corresponding events open and close.
BMC Software, Inc., Confidential and Proprietary Information
5-21
abstract AMP : APP_MISSING_PROCESSES ($AMP) from PROCESS_DOWN ($PD) where [sub_origin: within [process1, process2, process3] ] setup { $AMP.date = $PD.date ; $AMP.hostname = $PD.hostname ; $AMP.origin = $PD.origin ; $AMP.application = ABC ; $AMP.msg = Processes missing for application abc; } when $PD.status: equals OPEN { add_to_list($PD.sub_origin, $AMP.processes) ; } when $PD.status: equals CLOSED { rem_from_list($PD.sub_origin, $AMP.processes) ; } END
5-22
5-23
5-24
The purpose of a Correlate rule is to build a relationship between an event that occurs because of another event. However, one event may have multiple potential causes. One primitive unique to the Correlate rule phase is unset_cause. It simply breaks the cause/effect relationship and, therefore, does not have arguments. Only the Correlate rule phase can use the unset_cause primitive.
correlate App_Down : APP_DOWN ($AD) with APP_MISSING_PROCESSES ($AMP) where [ $AMP.application equals $AD.application ] within 1m when $AMP.status equals OPEN { $AMP.severity=CRITICAL ; } END
5-25
Another example of a Correlate rule includes multiple potential causes for an NFS server not responding.
correlate nfs_and_hd : NFS_NO_RESP ($NFS) with HOST_DOWN ($HD) where [$HD.hostname equals $NFS.server] within 10m when $HD.status not_equals CLOSED { $NFS.severity=HARMLESS ; } when $HD.status equals CLOSED { reset_default($NFS.severity) ; unset_cause ; } with PROCESS_DOWN($PD) where [ $PD.hostname equals $NFS.server, $PD.sub_origin equals nfsd ] within 10m when $PD.status not_equals CLOSED { $NFS.severity=HARMLESS ; } when $PD.status equals CLOSED { reset_default ($NFS.severity) ; unset_cause ; } END
If an NFS_NO_RESP event and a HOST_DOWN event arrive within ten minutes of each other, the cell correlates the two events. By placing the HOST_DOWN event in the first With clause, the rule considers the HOST_DOWN event to be the most likely cause of the NFS_NO_RESP event and builds a relationship between the two events, even if events match in another With clause. In this case, the HOST_DOWN event is the cause.
5-26
If the cell receives an NFS_NO_RESP event and a PROCESS_DOWN event within ten (10) minutes, and no HOST_DOWN event has entered the cell, then the Correlate rule builds a relationship between the events. In this case, the PROCESS_DOWN event is the cause. Since the NFS_NO_RESP event is only the result of the problem, the first When clause contained in both with clauses demotes the status of the NFS_NO_RESP event while the cause is escalated and fixed. The second When clause resets the NFS_NO_RESP events severity after the cause event has been closed and breaks the cause-effect relationship.
5-27
Syntax
execute <RuleName> : ECF when <Var>.<SlotName> { <Call>; <Var>.<SlotName> = ... } when <Var>.<SlotName> { <Call>; <Var>.<SlotName> = ... } ... END
<CondOperator> <Value>
<Value>;
<CondOperator> <Value>
<Value>;
That form will execute the action block when the value of the slot changes, whatever the change.
5-28
Semantics
The When clauses execute if the ECF for the rule passes. The When clauses cause actions to occur and can generate or update existing events or create messages. The When clause in rule phases is re-evaluated whenever a slots value changes, provided the ECF condition is met. This means that if a rule phase subsequent to the Execute phase changes a slots values, and the ECF for the Execute rule phase passes, the When clause is re-evaluated for that event in the Execute rule phase.
Note
Dynamic data values as resulting from a Using clause in the ECF may not be used in the When clause. The Execute phase is often used to execute external programs in the context of an event. In order to do that, we use the execute primitive in a block. The syntax of the primitive is:
execute (Var, Program, [ArgList], Watch)
Execute runs a program with optional arguments on the cell. The arguments are as follows:
Var is the name of the variable containing the event in the context of
executable is in the architecture specific directory under the bin directory of the Knowledge Base.
[ArgList] contains the list of comma-separated arguments passed to the executable as positional arguments ($1, $2, and so on). Note that all the slots and slot values of the event on behalf of which the executable runs are passed to the latter via environment variables. Use [ ] if the list is empty.
5-29
Watch is a Boolean flag stating whether or not the execution result will generate an event containing the result of the action.
You can use environment variables in the executable script or program when creating an executable. The following is a list of available environment variables:
Variable MCELL_HOME CELL_NAME CELL_RELEASE CELL_BUILD CELL_DATE PKG_NAME RULE_NAME REQUESTOR Definitions
The home directory where the cell resides. The cell name. The release number, for example, 1.1 The build numbe as can be found in the About box of the console. The date when the build was made. The name of the rule package. The name of the rule that triggered this external action. The requestor of the external action, either user@host for an action from a client or package:rule for an action initiated from a rule. The class of the event under analysis. The list of slot names for this class. The home directory for the requestor. A logfile name. A shell program. A terminal type (Unix only). The window ID for the requestor console.
All slots are passed in the environment, in the form of variables (with the same names as the slot names) containing the slot values. All variables that exist in the environment in which the cell is started are also passed but they cannot be enumerated because they are determined by the actual runtime environment.
5-30
All external action primitives have the same environment. The environment variable REQUESTOR specifies the requestor of the external action. It is user@host for an action from a client and package:rule for an action initiated from a rule. All variables from the initial cell startup environment are passed to the environment of external actions launched from the cell.
Examples
The following example Execute rule executes upon receipt of a DiskUsedPercentage event. The When clause generates a new message for the event. The message that is sent by the event contains a value for the disk space used. The When clause uses primitives to convert the number received from the event to a whole number and then concatenates the message.
execute Disk_Msg : DiskUsedPercentage ($DUP) when $DUP.status: equals OPEN { $V1 = round($DUP.value * 100) ; concat([$DUP.sub_origin, : , $V1, % of space used], $V2) ; $DUP.msg = $V2 ; } END
This example contains three When clauses for the event APP_MISSING_PROCESSES. The first when clause fires upon receipt of an OPEN event. A new message is created with the concat primitive and a new event, APP_DOWN, is generated from the original event indicating the application is down.
5-31
execute Event_Status : APP_MISSING_PROCESSES ($AMP) when $AMP.status: equals OPEN { concat ([Application , $AMP.application, is down.], $MSG) ; generate_event (APP_DOWN, [hostname = $AMP.hostname, origin = $AMP.origin, date = $AMP.date, application = $AMP.application, msg = $MSG ]) ; } when $AMP.processes: equals [] { $AMP.status = CLOSED ; } when $AMP.status: equals CLOSED { generate_event (APP_UP, [hostname = $AMP.hostname, origin = $AMP.origin, application = $AMP.application]) ; execute ($AMP, make_noise, [], NO) ; } END
The second When clause fires to close the APP_MISSING_PROCESSES event when all processes for the application are running. The third When clause fires and generates a new event, APP_UP, indicating the application is up when the original event is CLOSED. In addition, an executable is fired that sends a sound to the system indicating the application is up again. This illustrates how to use primitives such as generate_event or execute. Parameters of primitives can be expressions.
5-32
Syntax
propagate <RuleName> : ECF to <CellName> | to all [<CellName>, ...] | to one_of [<CellName>, ...] when <Var>.<SlotName> <CondOperator> <Value> to <CellName> | to all [<CellName>, ...] | to one_of [<CellName>, ...] when <Var>.<SlotName> <CondOperator> <Value> ... END
Semantics
A Propagate rule starts with an ECF that must match the event under analysis to make the rule engine evaluate the rule. The rule is composed of one or more When parts. Note that this time the When keyword appears at the bottom of the block unlike the other rule phases allowing When parts (Execute, Abstract, Correlate). When an event is new, the When clauses are evaluated and propagation may be performed at that time. Afterwards, modifications are propagated according to the different When clauses.
BMC Software, Inc., Confidential and Proprietary Information
5-33
Typically, cells are tried in turn. The rule engine stops whenever propagation is successful.
Note
If there are two Propagate rules, one that forwards all OPEN events and one that forwards all CRITICAL events, then an event that arrives as OPEN and CRITICAL will be propagated twice, once for each Propagate rule. This is not a big problem as the receiving cell will discard the duplicate, but you should try to avoid it, as it generates unnecessary work for the rule engine. Two slots defined for each event contain information about the path an event followed in the cell hierarchy.
mc_history contains the list of cells, and the identification of the
event inside each cell, through which the event flowed before reaching the current cell.
mc_propagations contains the list of cells, and internal
identifications, to which the event was forwarded. Once events have been propagated once by using rules, some changes are propagated automatically without the need for propagate rules. The parameters for this mechanism reside in the mcell.propagate file. By default, status, severity and event-specific slot changes are propagated forward, while the status is propagated backward.
5-34
Examples
The following example shows a Propagate rule that sends all APP_DOWN events with a status of CRITICAL to the server1 and server2 cells. However, events from systems with an IP address of 172.16.23.[1-10] are sent only to the server1 cell. If the server1 cell is unavailable, the events are sent to the server2 cell.
propagate Prop_Critical : APP_DOWN ($AD) where [origin: ip_matches 172.16.23.* ] to all [ server1, server2, server3 ] when $AD.severity equals CRITICAL to one_of [ server1, server2 ] when $AD.origin ip_matches 172.16.23.<10 END
5-35
Syntax
The following gives syntax for a Timer rule.
timer <RuleName> : ECF timer_info : <RelationalOperator> <TimerTrigger1> { <Call> ; <Var>.<SlotName> = <Value> ; ... } timer_info : <RelationalOperator> <TimerTrigger2> { <Call> ; <Var>.<SlotName> = <Value> ; ... } ... END
Semantics
Timers can be set in the following rule phases: New Abstract Correlate Execute Timer
5-36
where:
event is a variable pointing to an event, in general the event under analysis, but not necessarily duration is the duration before the timer fires, expressed in
seconds
info_label is an arbitrary label, which will be tested in the Timer_info clauses of the Timer rule. It allows to pass information
to the Timer rule, without having to put it in the event, as the slot values may change before the Timer rules are executed. There are two ways of setting a timer. One way is to specify an interval with the set_timer primitive, as discussed above. The second is to specify a specific date and time using the set_timer_at primitive, of which there are two forms. One form does not specify a format, the other does. Syntax for the unformatted set_timer_at primitive is:
set_timer_at(<event>, <time_stamp>, <timer_info>)
See the set_timer_at primitives on page A-20 of Appendix A, Master Rule Language Reference, for more information and syntax. It is important to remember that setting a timer with set_timer_at requires a precise time and date. For example, specifying an hour and a minute without specifying a date is not sufficient and could lead to undetermined behavior, among which is the immediate execution of the timer rule.
5-37
An event for which a timer has expired goes through the Timer phase. After having been tested against the ECF, the timer_info value of the timer is tested against an expression. That value is in fact what was put in the info_label argument to the set_timer primitive. If the condition matches, the corresponding block is executed.
Note
Timer rules are maintained even if the cells service restarts. Timers that expired while the cells service was stopped fire immediately when the cells service is restarted. Timers not yet expired fire as soon as they expire, as if the cell had not restarted.
Examples
Timer rules are often used to achieve a form of escalation. Following is an example demonstrating how to perform a selective escalation for a problem that does not disappear spontaneously, in this case a problem with a low swap space. Different timers are set, according to the origin of the problem that is assumed to originate with a server that is located in the lowest portion of the address range. A second assumption is made that problems on servers are more severe than on other machines.
execute Timer_on_Rpt_Low_Swap : Repeated_Swap_Avail_Low($RSAL) where [$RSAL.status : equals OPEN] when $RSAL.origin : ip_matches 200.200.*.<25 { set_timer($RSAL, 120, CRITICAL) ; } when $RSAL.hostname : ip_matches 200.200.*.>25 { set_timer($RSAL, 600, MINOR) ; } END
5-38
timer Rpt_Low_Swap : Repeated_Swap_Avail_Low($RSAL) where [ status: equals OPEN] timer_info : equals CRITICAL { $RSAL.severity=CRITICAL ; } timer_info : equals MINOR { $RSAL.severity=MINOR ; } END
The timer rule checks that the status is still OPEN, then evaluates the timer_info clauses. In this case only one matches, causing the severity of the original event to be modified according to what was set in the timer.
5-39
Syntax
delete <RuleName> : ECF { <Call>; <Var>.<SlotName> = <Value>; ... } END
Semantics
A Delete rule starts with an ECF that the event under deletion must match. If a match is found, the block is simply executed.
5-40
Examples
One main reason for a Delete rule, is the cleanup of some information that was build while the event existed and is no longer needed when the event is removed. The following example shows how to clean event from a dynamic data table on an event deletion:
delete Remove_MyData : HOST_DOWN($EV) where [ $EV.status equals OPEN ] using ALL { MYDATA($MD) where <records relevant for this event> } { remove_data($MD); } END The definition for the data could be: MC_DATA_CLASS : MYDATA ISA DATA DEFINES { name : STRING ; number : INTEGER ; }; END
5-41
5-42
Collectors
Event collectors, how they operate, and how they can be created are discussed in this chapter. Topics are discussed in the following order: Collector Operation Collector Definition Performance Considerations
Collectors
6-1
Collectors are sets of events within a cell that meet specific, user defined criteria. These criteria determine how the events are displayed in the BMC Impact Explorer. The collectors defined for a cell are available to any console that connects to that cell. Collectors are organized into hierarchies within a cell so that specialized collectors at the lowest level of the hierarchy are combined into more generic collectors at successively higher levels. The console displays the collectors as an expandable tree with color-coded severity indicators, and permits you to view a list of all the events belonging to each collector. Collectors are defined in the Knowledge Base that is loaded by the cell. Events may appear in more than one collector tree, but not in several collectors within a single collector tree, depending on the criteria you specify. Collectors may be either static or dynamic. They also can be characterized by their respective positions in the hierarchy as either a parent collector (supercollector) or a child collector (subcollector). A parent collector contains one or more collectors from the level immediately below it in the hierarchy. Those collectors from the next lower level that belong to a higher level collector are child collectors. A child collector can, in turn, be a parent to collectors from the hierarchical level just below it. The collectors in the lowest level of the hierarchy can be only child collectors. A collector that contains grouped events from multiple cells is called a MetaCollector. The MetaCollector exists only in the console as a virtual collector that the user can customize according to specific requirements. The MetaCollector may contain collectors from multiple cells across the network of Event Processors. MetaCollectors are not part of any cell Knowledge Base, they exist instead only at the console level. MetaCollectors are discussed in the BMC Impact Explorer Console User Guide. Collectors are part of the Knowledge Base and are written in MRL language. Their definition resides in the collectors subdirectory of the Knowledge Base.
6-2
Collector Operation
Unlike rules, collectors can be viewed as labeled icons in the Events view navigation pane in the console window. The following illustrates the relationships among the cell London, a parent collector By Host, and its child collectors.
The cells Knowledge Base contains collector definitions that act as database queries. An event can appear in several collector trees simultaneously, but not in several collectors within a single collector tree. Since collectors are defined in the cells Knowledge Base, they appear in any console that displays the cell. Also, an incoming event that changes slot conditions can move from one collector to another within a cell. An event passes through a series of collector definitions upon entering the cell. If the event matches a collectors definitions, the collector displays the event. The collector tree resembles a directory tree. Each tree branch is a path the event follows, searching for matching criteria. If the event finds matching criteria, it ignores any remaining paths in the collector tree. The event continues to the end of the current path and searches for an accepting collector, with one of these results.
Collectors
6-3
The event is stored in the first accepting terminal collector it encounters. This is the events endpoint collector. For each collector tree the event can be stored in only one endpoint collector.
OR
The event proceeds to the next higher level and is stored in the first accepting collector it encounters there, if there is no collector on the current level that accepts it. This is the events endpoint collector.
The event proceeds to the next path if it encounters nonmatching criteria which blocks the current path. The event proceeds to the next collector tree when it has found one accepting endpoint collector.
Collector Security
The BMC Impact Manager administrator sets role permissions to specify the collectors in the cells Knowledge Base that a user can view and act on with the console. You may be able to connect to a cell but you may not be able to view all collectors, depending on how your administrator has specified the permissions for each collector. The standard roles and what they can access in the BMC Impact Manager product are: BMC Impact Manager Administrator Roles Membership in one or more is defined as one BMC Impact Manager Administrator license. MC_SuperAdmins manages everything in the BMC Impact Manager environment. MC_Admins manages the BMC Impact Manager infrastructure, events, and services. Service Manager Roles Membership in one or more is defined as one Service Manger license.
6-4
MC_Srvc_Mgrs_Sr manages services and events with full customization capabilities. MC_Srvc_Mgrs manages services and events with limited customization capabilities. BMC Impact Manager Operator Roles Membership in one or more is defined as one Operator license. MC_Operators_Sr manages events and services with full customization capabilities. MC_Operators manages events and services with limited customization capabilities.
granted here are inherited by all collectors below the cell in the hierarchy.
c1 is a subcollector of self. The MC_SuperAdmins role has been
explicitly assigned the read (r), write (w), and execute (x) privileges at the collector self. These privileges will be inherited by all subcollectors. Therefore, users assigned the MC_SuperAdmins role will have read, write, and execute privileges to both self and c1. The MC_Srvc_Mgrs_Sr and MC_Admins roles have been assigned read, write, and execute privileges at the collector c1 only. Users assigned to either role will have read, write, and execute privileges only to c1. The User role has been assigned the read permission at the collector c1. Users with this assignment will have only read permission to c1.
BMC Software, Inc., Confidential and Proprietary Information
Collectors
6-5
In this example, there are two collectors: a top-level (supercollector) self, and collector c1. A user with a MC_SuperAdmins role has read, write, and execute privileges at the collectors self and c1. A user with a MC_Srvc_Mgrs_Sr or MC_Admins role has read, write, and execute privileges at the collector c1 and read privileges at collector self. A user with a MC_Operators role has read permission at the collectors self and c1. The .mrl file can be named anything the author chooses, but it must be located in the Knowledge Bases collector directory, and it must be added to the .load file.
collector self : {r[MC_SuperAdmins]; w[MC_SuperAdmins]; x[MC_SuperAdmins]} END collector c1 : {r[MC_Srvc_Mgrs_Sr,MC_Admins,MC_Operators]; w[MC_Srvc_Mgrs_Sr,MC_Admins]; x[MC_Srvc_Mgrs_Sr,MC_Admins]} END
6-6
collector self : {r[MC_SuperAdmins]; w[MC_SuperAdmins]; x[MC_SuperAdmins]} END collector c1 : {r[MC_Admins,MC_Operators]; w[MC_Admins,MC_Operators]; x[MC_Admins,MC_Operators]} END collector c1.one : {r[MC_Srvc_Mgrs_Sr]} END collector c1.two : {r[MC_Srvc_Mgrs_Sr], w[MC_Srvc_Mgrs_Sr]} END collector c2 : {r[MC_Srvc_Mgrs_Sr,MC_Admins]; w[MC_Srvc_Mgrs_Sr,MC_Admins]; x[MC_Srvc_Mgrs_Sr,MC_Admins]} END collector c2.one : {r[MC_Operators], w[MC_Operators]} END collector c2.two : {r[MC_Operators]} END
The preceding example illustrates the following user roles and associated permissions. Users with a MC_SuperAdmins role have read, write, and execute permissions for all collectors and subcollectors shown. Users with MC_Admins and MC_Operators roles have read, write, and execute permissions on collector c1 and subcollectors c1.one and c1.two. Users with a MC_Srvc_Mgrs_Sr role have read permissions at collector c1, subcollector c1.one, and read and write permissions on subcollector c1.two. Users with MC_Srvc_Mgrs_Sr and MC_Admins roles have read, write, and execute permissions on collector c2, and subcollectors c2.one and c2.two.
Collectors 6-7
Users with a MC_Operators role have read permissions at collector c2, subcollector c2.two, and read and write permissions at subcollector c2.one.
Note
Any time you make changes to the collectors, dynamic data, or rules, you must recompile the Knowledge Base for that cell. In addition, if you do not see your cell in the Available Cells pane of the Event Processors tab of the Edit Configuration dialog in the console, you need to be sure you have created your collector definitions for that cell, stop the services, and recompile the Knowledge Base.
Collector Definition
BMC Impact Manager Default Collectors
The BMC Impact Manager software provides two default collectors, self and AllEvents. They are installed in the default KB directory during the product installation process. The definition for the self and AllEvents default collectors follow.
6-8
Use the CatchAll parameter in the root collector in the hierarchy to collect all events, including any events not picked up by the other collectors you define. When an event traverses the collector tree, it may not be evaluated by every collector. Once an event finds a match in the collector tree, it follows that branch of the tree and ignores all other branches, so the CatchAll parameter in the root collector will catch all events, regardless of the events path through the collector tree. As illustrated above, syntax for the CatchAll parameter in a collector is:
collector AllEvents : CatchAll END
Collector Syntax
The general syntax for a collector definition is:
collector <CollectorName> [: r | w | x <Role> ] [ create <Expression> [ delete ] ] [ CLASSEVENTNAME where [<slot_name>: <condition_operator> <slot_value>, ...]
BMC Software, Inc., Confidential and Proprietary Information
Collectors
6-9
| CatchAll ] END
The first section of the preceding collector definition, and in bold letters below, defines the Collector name, parent collector if applicable, access rights and roles.
collector <CollectorName> [: r | w | x <Role> ]
The <CollectorName> is assigned by: 1. 2. 3. 4. Defining the cell itself using the keyword self. Specifying the parent collector name, such as Network. Specifying the child collector name, such as Network.Subnet. Specifying the dynamic collector name using an asterisk, such as Network.*.
Collector names must begin with letters, not digits. The name of a collector can contain only alphanumeric characters plus the underscore (_). The <Role> definitions reside in the mccs.init file, along with the default roles. Multiple roles with unique access rights may be defined for any collector. In addition, the asterisk (*) creates dynamic role definitions. For more information on dynamic role creation, see the section Dynamic Collector Roles on page 6-16 in this chapter. The second and third lines in the preceding collector definition, and in bold letters below, defines optional Create and Delete clauses for the collector, as in the following lines:
6-10
These clauses define the dynamic collector name. The Create clause is required when using dynamic collectors. The <Expression> term sets the collector name. The format of the expression contains the keyword $THIS followed by an event slot name. $THIS substitutes the slot value in place of the * in the collector name. Some examples of Create clauses using the root class EVENT slot definitions include:
$THIS.origin
Substitutes the value of origin for the asterisk in the collector name
$THIS.hostname
Substitutes the value of hostname for the asterisk in the collector name
The Delete clause is optional. If used, the Delete clause specifies that the cell must delete an empty dynamic collector after it and its subcollectors have been empty for a defined period of time. The time period is specified in the CollectorKeepEmpty parameter in the mcell.conf configuration file. The default value is 600 seconds; the minimum value is 60. An empty dynamic collector with or without a Delete clause is deleted when empty for the specified time period and when the cell is restarted, if restarted before the end of the time specified in the CollectorKeepEmpty parameter.
Note
A Create or Delete clause always refers to the last named component only, defined as an asterisk (*). Collector definitions with a fixed last name component cannot use either a Create or a Delete clause.
Collectors
6-11
The third section in the collector definition is an Event Condition Formula, referred to as ECF, or the keyword CatchAll. When CatchAll is used, that collector displays all events not found in any of the previously defined collectors for that collector group. An ECF identifies appropriate events for further processing. The ECF format includes the name of the event class and all the slot conditions for that class. The last line, END, defines terminating limit of the collector definition.
Note
The ECF selection portion may contain references to the dynamic data by means of a Using clause. Use this feature with extreme care as it may result in a large performance degradation of the cell, particularly when large tables are searched on unindexed slots. For reference in the following discussion of an ECF in a top level collector, the By Host collector in the illustration on page 6-3 is a top level collector. All top level collectors occupy this position in the Events view navigation pane of the console window. You cannot have an ECF in a top level collector, by design. Top level collectors may have a tree structured hierarchy of subcollectors that, with the top level collector itself, constitute a collector set. An event is always assigned to, at most, one collector per collector set. However, it can occur once in every collector set. A collector set, in this context, must be conceptualized as a specific way to direct the events into separate buckets. These buckets are its collectors. From this conceptualization it is clear that it defeats the collector sets purpose to specify a condition on the collector set definition. Each event always goes into one of every collector set's collectors. The exception is that if it does not match any of the conditions of the collectors in the set, it still can be collected in the CatchAll collector. If you place an ECF in the top level collector the mccomp CLI fails to compile it.
6-12
Notice that the self collector definition has no roles or access rights defined. The parent collector, Networks, does not have an ECF, yet it defines read access rights for a user with the MC_Admins role. Both child collectors, Local and Remote, accept only those events whose value in the source field falls within the specified IP address range. The event class name may be the root class, EVENT, or it may be a subclass event. The collector Local inherits the rights and roles defined in the Networks collector and defines additional access rights for users with MC_Operators and MC_Admins roles. Remote inherits the Networks collectors rights and roles and defines additional access rights for users with MC_Admins roles.
Collectors
6-13
Example 2
The following is a more complex example of static collectors. They are defined with single and multiple ECFs.
collector AllEvents : { r [MC_Operators, MC_Admins, MC_SuperAdmins ] w [MC_Operators, MC_Admins, MC_SuperAdmins ] x [MC_Admins, MC_SuperAdmins] } END collector AllEvents.Open : EVENT where [status: equals OPEN] END collector AllEvents.Ack : { x [MC_Operators] } : EVENT where [status: equals ACK, severity: equals FATAL] EVENT where [severity: not_equals UNKNOWN] END collector AllEvents.NotOpen : EVENT where [status: not_equals OPEN] END
When using multiple ECFs, be sure the ECFs meet the desired outcome. For example, the AllEvents.Ack collector accepts only those events with an ACK status. The first ECF complies with that goal and adds another stipulation to it by accepting only events with an ACK status and a FATAL severity. The second ECF, however, states that the collector accepts an event with any status as long as its severity is not UNKNOWN. When multiple ECFs exist for a single collector, the cell interprets the ECFs using the OR operator. That is, if condition_1 or condition_2 match, then pass. When multiple slot conditions exist within the same ECF for a collector, the cell interprets the ECFs using the AND operator. That is, if slot_1 and slot_2, then pass.
6-14
The access rights and permissions set in the parent collector AllEvents are inherited by all of its children collectors. The only modification to the inherited permissions is in the collector AllEvents.Ack. This collector adds additional execute access rights for a user with the MC_Operators role.
Condition Operators
The valid conditional operators in an ECF, whether in a rule, in a collector or in an action, can be found in the Appendix A, Master Rule Language Reference.
collector Net : END collector Net.* : NET where [ subsystem: not_equals ] create $THIS.subsystem delete END collector Net.*.Server : NET where [ origin: equals SERVER ] END collector Net.*.Server.* : NET create $THIS.server_name END collector Net.*.Client : NET END collector Net.Global : NET END
Collectors
6-15
These examples define collectors for each of the subsystems and one for global events that is not related to a subsystem. The names of the subsystems running on a system are not known in advance. Thus, collectors with the correct subsystem name are created and deleted dynamically. Every incoming event associated with a subsystem slot, subsystem, resides in the corresponding Net.* collector. If this collector does not yet exist, the name is generated with the value of subsystem. Dynamic collector removal occurs after the collector and child collectors remain empty for the amount of time specified in the CollectorKeepEmpty parameter.
Dynamic Collector Roles
In a dynamic collector definition, dynamic role assignments may exist instead of static role assignment. The dynamic roles are created with the dynamic collector. The $THIS variable refers to the incoming event and is used in the role name definition, as the following illustrates.
This example assigns a read permission to a role having the same name as the slot value of slot server_name. For example, if the name of a server is host12 in a received event, this construct creates a new collector host12. A user must have host12 in the list of roles in order to see what is contained in that collector.
Note
The roles computed dynamically and assigned to dynamic collectors must be defined in the BMC Impact Explorer Server. In addition, users must receive these roles before they can access the collectors.
6-16
Modification of slot values in the collector condition (the Where clause) may allow the event to move to another collector. Modifying slots in the Create expression may allow the event to appear to move to another collector but it does not. The Create expression is evaluated only when events are created, not when slots are modified. To make changes to collectors effective with the cell, stop the cell service, save the modifications to the definitions file, recompile the Knowledge Base with the mccomp command, and restart the cell service, or use the mcontrol command.
Performance Considerations
In order to preserve the optimum cell performance, the following must be considered, as any new event or even any slot change will force the cell to reconfigure collector conditions. Try to express conditions on events (ECF) as simply as possible. Use narrowly defined classes rather than complex Where clauses. For example,
Collectors
6-17
If necessary, modify the design of the hierarchy and take full advantage of the specialization properties. In particular, writing a collector condition on a class will catch all events belonging to any of its subclasses. For example, assume that HOST_EVENT is a superclass of HOST_UP and HOST_DOWN. A collector such as the following will catch all instances of any HOST_DOWN or HOST_UP event.
Note that the following will not catch all instances of HOST_UP or HOST_DOWN events because the comparison will be literally done on the string HOST_EVENT. There are, in principle, no instances of such a class.
collector HostsEvents : EVENT where (CLASS: equals HOST_EVENT) END
If you want to use dynamic data in the Using clause of an ECF, keep tables short and always search on indexed slots.
6-18
This Appendix contains the data types, operators, primitives, arithmetic operators, and functions uses in writing and editing rules and collectors. Examples are provided where appropriate. Topics are covered the following order: Data Types Operators Primitives Functions MRL Syntax BMC Impact Manager Base Classes
Note
In this Appendix the term atomic may represent any of: string, integer, real, or pointer.
A-1
Data Types
The cell uses the following data types:
Type INTEGER REAL POINTER STRING <> <Enum> Default Value 0 0 0x0 Null
N/A The first ordinal value, that is, the value corresponding to the lowest numerial value.
The rules permit you to include arithmetic operations on INTEGER. The following identifies the only combinations in which pointers are permitted.
<pointer> <pointer> <pointer> <integer> pointer = pointer = = <pointer> + <integer> = <integer> + <pointer> = <pointer> - <integer> = <pointer> - <pointer> max( <pointer>, <pointer> ) min( <pointer>, <pointer> )
Enumeration names must be unique throughout the class and the enumeration names of the application.
A-2
Warning
Literal strings cannot contain more than 65535 characters in length. If you attempt to compile a rules file containing a slot assignment of a string greater than 65535 characters, the compiler replaces the string with an empty string.
Operators
The following operators can appear in a When clause or be used to construct boolean expressions. Boolean expressions are used in Where clauses, if-then-else constructs, and conditional expressions.
equals not_equals, or != within contains_one_of outside between greater_than, or > smaller_than, or less_than, or < greater_or_equals, or >= smaller_or_equals, or less_or_equals, or <= || (concatenation operator)
BMC Software, Inc., Confidential and Proprietary Information
equals, or == has_suffix contains contained_in matches ip_greater_or_equals ip_smaller_or_equals ip_matches superclass_of subclass_of
A-3
Operator Definitions
equals or ==
Tests the equality of the two members of a Boolean expression. It evaluates to TRUE if <expr1> and <expr2> have the same value. The operator works across valid data types for slots.
Syntax: where [ <expr1> equals <expr2> AND/OR ...] Example: where [ $THIS.hostname equals myhost ] where [ ($THIS.repeat_count + 1) == $THAT.value ] not_equals or !=
Tests the equality of the two members of a Boolean expression. It evaluates to TRUE if <expr1> and <expr2> do not have the same value. The operator works across valid data types for slots.
Syntax: where [ <expr1> not_equals <expr2> AND/OR ...] within
Evaluates to TRUE if the value of <expr1> is not contained in the list of values.
BMC Software, Inc., Confidential and Proprietary Information
A-4
Tests for the value of <expr1> between specified lower and upper limits.
Syntax: where [ <expr1> between [<minimum value>, <maximum value>] ] greater_than or >
Compares two expressions. It evaluates to TRUE if <expr1> has a value greater than <expr2>. The operator works across valid data types for slots.
Syntax: where [ <expr1> greater_than <expr2> AND/OR ... ] smaller_than or less_than or <
Compares two expressions. It evaluates to TRUE if <expr1> has a value smaller than <expr2>. The operator works across valid data types for slots.
Syntax: where [ <expr1> smaller_than <expr2> AND/OR ...] greater_or_equals or >=
Compares two expressions. It evaluates to TRUE if <expr1> has a value greater than or equal to <expr2>. The operator works across valid data types for slots.
A-5
Syntax: where [ <expr1> greater_or_equals <expr2> AND/OR ...] smaller_or_equals or less_or_equals or <=
Compares two expressions. It evaluates to TRUE if <expr1> has a value smaller than or equal to <expr2>. The operator works across valid data types for slots.
Syntax: where [ <expr1> smaller_or_equals <expr2> AND/OR ...] has_prefix
Tests the characters at the beginning of an expression of type STRING. The filter returns TRUE when <expr2> is a prefix of the STRING value contained in <expr1>.
Syntax: where [ <expr1> has_prefix <expr2> AND/OR ...] has_suffix
Tests the characters at the end of an expression of type STRING. The filter returns TRUE when <expr2> is a suffix of the STRING value contained in <expr1>.
Syntax: where [ <expr1> has_suffix <expr2> AND/OR ... ]
A-6
contains
Tests whether an expression of type STRING contains a specified string. You also can use this operator in combination with a list of strings. In this second situation, the goal is to determine whether the expression, of type STRING, contains each of the strings specified in the list that follows the operator. If the string specified after the operator is an empty string (), the test fails.
Syntax: where [ <expr1> contains [ <string1>,<string2>] | [ <list> contains <expr> ] AND/OR ... ] contains_one_of
Tests whether the expression, of type STRING, contains one of the strings specified in the list that follows the operator. If the string specified after the operator is an empty string (), the test fails.
Syntax: where [ <expr1> contains_one_of [ <string1>,<string2>] AND/OR ... ] contained_in
Enables testing for whether an expression of type STRING is found in the string provided after it. If the slot value to be tested is an empty string, the test fails.
Syntax: where [ <expr1> contained_in bbbbbb t:abcdef fgsg ]
If the event under analysis has msg = abcdef, the event filter is satisfied. If msg = abcdefg, it is not satisfied.
A-7
matches
Performs basic pattern matching to expressions of type STRING. It is less powerful than actual regular expressions but still offers valuable functionality while remaining simpler to use.
Syntax: where [ <expr1> matches <expression> ] Explanation
You must reduce a string to its components to determine whether a slot value of an event can be evaluated as a match by a rule. Some of these components are explicitly specified, others are defined as any decimal number (integer), any real number, or any string. These are designated by the strings %d (decimal number), %f (real number), and %s (a string). A string (%s) is terminated either by the first occurrence of the character that follows it in the pattern, or the end of the slot value text. A decimal is any series of integers, possibly preceded by a minus sign (-). A real number is a series of integers with an optional decimal point or period (.) anywhere in the sequence, possibly preceded by a minus sign. For example:
3 -3 3. -3. .3 -.3 3.3.2 [^a-z] Fred
matches %d, %f, or %s matches %d, %f, or %s matches %f or %s matches %f or %s matches %f or %s matches %f or %s matches only %s matches only %s matches only %s
A-8
Anything other than a string, decimal or real value must match exactly, with the exception of spaces. A single space in the pattern matching formula matches one or more contiguous spaces from the expressions <expr1>. For example,
where [ $THIS.msg matches %s %d ]
This matches Eagle 1 or [missing] 378 or even 12 34, but not Missing number or loopback 127.0.0.1.
ip_greater_or_equals
This operator is useful in testing slot values or expressions that represent IP addresses. These slot values are, in fact, of type STRING and it is only the interpretation of the string that determines whether it represents an IP address. The test succeeds if the slot value represents an IP address which is either equal to or greater than the one specified after the operator ip_greater_or_equals in the range of IP addresses.
Example: where [ $THIS.origin ip_greater_or_equals 10.10.10.100 ]
The rule executes if the value of the slot origin for the event under analysis represents an IP address in the range between 10.10.10.100 and 10.10.12.255. If the value of origin is 10.10.10.100 or 10.10.12.255 or 10.10.11.140 , the event filter is satisfied. An origin value of 10.10.10.99 or 10.10.13.1 or 10.12.10.150 does not satisfy the filter condition.
A-9
ip_smaller_or_equals
This operator is useful in testing slot values or expressions representing IP addresses. These slot values are, in fact, of type STRING and it is only the interpretation of the string that determines if it represents an IP address. The test succeeds if the slot value represents an IP address which is either equal to or less than the one specified after the operator ip_smaller_or_equals in the range of IP addresses.
Example: where [ <expr1> ip_smaller_or_equals 10.10.12.255]
The rule executes if the value of the slot origin for the event under analysis represents an IP address falling in the range between 10.10.10.100 and 10.10.12.255. If the value of origin is 10.10.10.100 or 10.10.12.255 or 10.10.11.140 , the event filter is satisfied. An origin value of 10.10.10.99 or 10.10.13.1 or 10.12.10.150 does not satisfy the filter condition.
ip_matches
Expresses combined conditions on the different bytes composing an IP address. This operator works on slot values or expressions that are of type STRING and assumes that the value represents an IP address. The value is matched against a formula built on the principle of the dot notation for IP addresses. The formula is composed of four components, one for each byte of the IP address, and the components are separated with dots.
Syntax: where [ <expr1> ip_matches 195.<128.*.>25 ]
Each of the four components can be one of the following: a number between 0 and 255 This number must be the value of the corresponding byte in the slot value representing an IP address.
A-10
The value of the corresponding byte in the slot value representing an IP address can be anything.
> followed by a number between 0 and 254
The value of the corresponding byte in the slot value representing an IP address must be greater than the number which follows the greater than sign (>).
< followed by a number between 1 and 255 The value of the corresponding byte in the slot value representing an IP address must be smaller than the number which follows the less than sign (<).
The ip_matches operator works on data type STRING. The operator assumes that <expr1> contains an IP address and <value> provides a pattern to match.
ip_matches
This operator can be used to compare two classes, either event classes or data classes. The comparative information may be a variable or hard-coded string. It succeeds if <CLASS1> is an equal or superclass of <CLASS2>.
Syntax: where [ <CLASS1> superclass_of <CLASS2> ]
The special slot CLASS can be used to reference the class of an instance, as in $EV.CLASS.
BMC Software, Inc., Confidential and Proprietary Information
A-11
subclass_of
This operator can be used to compare two classes, either event classes or data classes. The comparative information may be a variable or hard-coded string. Succeeds if <CLASS1> is an equal or a subclass of <CLASS2>.
Syntax: where [ <CLASS1> subclass_of <CLASS2> ]
The special slot CLASS can be used to reference the class of an instance, as in $EV.CLASS.
These Boolean operators are available for use in collector and select rules, and for writing test conditions in the Where clauses of event selection.
A-12
String Operators
The BMC Impact Manager product provides a concatenation operator, ||, that can be used to concatenate strings.
|| (concatenation operator)
A-13
Arithmetic Operators
These arithmetic operators are available in the cell:
addition subtraction multiplication division exponentiation exponentiation remainder division modulo division
<number> + <number> <number> <number> <number> * <number> <number> / <number> <number> ** <number> <number> ^ <number> <number> rem <number> <number> mod <number> Tip
When you use arithmetic operators in a rule, you must insert a blank space before and after the operator.
Primitives
Use the following primitives as calls in the rules. This section describes what the primitives do and how they operate. When writing literal strings you should place single quotes () around the text. This is mandatory for text that contains spaces but not for text without spaces. You should use single quotes for all literal strings. When a primitive has an argument that is a list <arg>, the argument must be coded so it is within square brackets ([ ]). The KB does not enforce syntax validation on primitive arguments. The primitives are categorized by function. The categories and the primitives they contain are:
A-14
Category
Cell operation control Conversion primitives
Primitives
cellcontrol stringtoint stringtopointer stringtoreal inttostring pointertostring realtostring tolowercase touppercase drop_new reset_default set_timer set_timer_at set_timer_at (formatted) unset_cause generate_event new_data remove_data send_to add_to_list rem_from_list listappend listdelete listdisjoint listgetelt listintersect listlen listmember listremdup listsubtract listunion listwalk execute confirm_external| get_external cellinfo get_env
List primitives
A-15
Category
String primitives
Primitives
concat match_regex strlen strmatch strpart strnpart strtolist str_to_time_stamp time_extract time_stamp time_stamp_to_cim
Time primitives
Controls the cell operation mode, depending on certain specific events that occur when used with one of the following arguments: stop shutdown pause restart reload statbld
The behavior is exactly the same as if that argument was posted to the cell through an external call of mcontrol. For example, the following use of the primitive puts the cell in pause mode, in which it does not accept incoming events.
cellcontrol(pause)
A-16
Conversion Primitives
stringtoint
A-17
A-18
Syntax: touppercase(src, cnv) IN : src = source string OUT: cnv = converted string
Use in the update rules only. It drops (discards) the event that just arrived.
Drop_new can be called only from a new (formerly update) rule. reset_default
Sets to the default value the slot value referenced as an argument to the primitive. The value is in the class definition file which is a .baroc file. If a default value is not provided, then the default value for that data type is used.
Syntax: reset_default(<slot_ref>) Example: reset_default ($EV.userpwd) set_timer
Sets a timer to execute at a period of time in the future. Duration is in seconds. <info> is the timer label. Use set_timer in a timer rule to determine which timer has expired.
Syntax: set_timer(<event>, <duration>, <info>)
A-19
Set_timer can be called only from a new, abstract, correlate, execute, timer or delete rule. set_timer_at
The set_timer_at primitive allows setting a timer for a specific time rather than after a specified delay.
Syntax: set_timer_at(<event>, <time_stamp>, <timer_info>)
See the str_to_time_stamp primitive on page A-38 of this Appendix for formatting information.
set_timer_at (formatted)
The set_timer_at primitive allows setting a timer for a specific time, in a specified format, rather than after a specified delay.
Syntax: set_timer_at(<event>, <formated_time>, <time_format>,<timer_info>)
See the str_to_time_stamp primitive on page A-38 of this Appendix for formatting information.
unset_cause
A-20
generate_event
In this case, the compiler issues a warning, saying that it cannot guarantee the validity of all arguments.
Generate_event can be called only from a new, abstract, correlate, execute, timer or delete rule.
The following are the primitives that operate on the data instances of dynamic data classes.
A-21
new_data (form 1)
Note that <data_classname> must be a constant and so must the slots that are mentioned in <list of slot specifiers>.
New_data can be called only from a refine, new, abstract, correlate, execute, timer, or delete rule. new_data (form 2)
Note that <base_data_classname> must be a constant but <data_classname> as well as the slot names mentioned in <list of slot specifiers> can be expressions. The <data_handle> is considered to be a data of class <base_data_classname> in the remainder of the rule body.
New_data can be called only from a refine, new, abstract, correlate, execute, timer, or delete rule.
BMC Software, Inc., Confidential and Proprietary Information
A-22
remove_data
The preceding syntax will remove only one instance of the data. To remove all instances you must employ the using ALL clause.
Remove_data can be called only from a new, abstract, correlate, execute, timer or delete rule. sendto
Allows a new event, or a modification of an existing event, to be sent to a destination cell or gateway. When a new event is sent with this primitive, its mc_history slot is cleared in the message but not in the cell. As a result, the receiving cell or gateway will not perform backward propagations on that event. This primitive can be used from within any type of rule.
send_to/2 send_to(<dest>,<obj>)
Sends an event with an object handle <obj> as a new event to a destination named <dest>.
send_to/3 send_to(<dest>,<obj>,<slots>)
Sends slots mentioned in the list <slots >of the event with an object handle <obj> as an event modification to a destination named <dest>.
A-23
In both forms of sendto, the mc_history slot of the new event is set to ([ ]) when sending to the destination, and the mc_propagations slot of the event at the originating cell is not modified. Unlike generate_event, send_to can be called from any rule phase.
List Primitives
add_to_list
Add
a <value> to a <slot_ref>. The <slot_ref> must be defined as a LIST OF, and the <value> type must match the type of the LIST. The <slot_ref> can be a global record.
Syntax: add_to_list(<value>, <slot_ref>) rem_from_list
A-24
listappend
Computes <arg3> from the list <arg1> by removing all the elements equal to <arg2>.
Syntax: listdelete(<list>, <elt>, <newlist>) IN: <list> = list <elt> = element OUT: <newlist> = list without <elt> listdisjoint
A-25
listgetelt
A-26
listmember
A-27
listunion
The only primitive with backtracking capability. Retrieves one by one in <arg2> the elements of the list <arg1>.
Syntax: listwalk(<list>, <elt>) IN: <list> = list OUT: <elt> = element Example:
The following is an example of listwalk, the only primitive available with backtracking capability. In this example, the slot minval is set to a minimum value of 1000 and the values contained in the slot list_of_int.
A-28
Optional arguments pass to the executable when execute is coded. The arguments must be enclosed in square brackets ([ ]). The arguments pass as command line options to the specified executable. An external program, executed on an event, will yield a result event if requested. Specify the last argument of the execute primitive to be YES or NO, depending on whether or not generation of a result event is desired. This event is similar to that of an action. It contains the package and rule name in the requestor slot. Optional arguments pass to the executable when confirm_external is coded. These arguments must be enclosed in square brackets ([ ]). The arguments pass as command line options to the specified executable. The return code from the executable determines whether further processing of the event is required. If the return code is zero (0), the event continues to process. A non-zero value discards the event.
A-29
confirm_external example:
The following is an example of a refine rule that invokes the confirm_external primitive when an event of class EVENT (or any of its subclasses) arrives at the cell.
SRM_EVENT ($EV) { confirm_external(refine_confirm.sh, [ $EV.hostname, $EV.source, $EV.severity] ); } END
In this example the shell script refine_confirm.sh executes. It passes three command line arguments: hostname, source, and severity. The values of these arguments are found within the event that caused this rule to execute. When the script terminates, the cell evaluates the return code and determines if further processing is required.
execute example
The following is an example of a Refine rule that invokes the execute primitive when an event of class EVENT, or any of its subclasses, arrives at the cell.
refine test_execute: EVENT ($EV) { execute($EV, refine_exec.sh, [$EV.hostname, $EV.severity], no); } END
A-30
In this example, the shell script refine_exec.sh executes. It passes two command line arguments: hostname, and severity. The values of these arguments are those found within the event that caused this rule to execute.
get_external
Use get_external to run an executable on the same machine on which the cell runs and have the executable pass information back to the cell through an interface.
Syntax: get_external(<pgm>, <[arg-list]>, <interface-name>, <var>) get_external can be called only from a Refine rule.
Optional arguments pass to the executable when get_external is coded. The arguments must be enclosed in square brackets ([ ]). The arguments pass as command line options to the specified executable. The third argument, interface-name, specifies which interface passes information back to the cell. The cell creates an instance of that interface and populates it with the information passed to it from the executable. Interfaces are defined in the following directory.
MCELL_HOME\etc\<CellName>\<kb-dir>\classes
A-31
The first argument, <pgm>, must have as its first input parameter the name of an output file to which it writes. The fourth argument, <var>, is a variable the rule uses to access the contents of the interface when the get_external primitive returns control to the rule. Note that the instance of the interface is deleted when the rule completes its execution. The return code from the executable determines whether further processing is required on the event. If the return code is zero (0), the event continues to process. A non-zero value discards the event.
A-32
<Field> also can be any parameter that can be set in the .conf file.
get_env
String Primitives
concat
A-33
Syntax: match_regex(<string>, <regex>, <options>) match_regex(<string>, <regex>, <options>, <list_of_fields>) match_regex(<string>, <regex>, <options>, <nb_fields>, <list_of_fields>)
where:
<string> is the string to be matched by the regular expression <regex>. <regex> is a Perl-like regular expression implemented with the PCRE library. <options> specifies options for the pattern matching. It is a possibly empty string of [i,m,s,x] characters: i m s
is a case-less string match. is multi-line mode. is dot all, that is, a dot metacharacter in the pattern matches all characters, including newlines. is extended mode. This option causes whitespace data characters in the pattern are ignored except when escaped or inside a character class, and characters between an unescaped # outside a character class and the next newline character, inclusive, are also ignored.
<list_of fields> is a list of strings which will receive the substrings of <string> matched by the place holders of <regex>. The <list_of_fields> is the only output produced by this primitive.
A-34
<nb_fields> represents the first substrings matched by the place holders of <regex>. It is an input parameter that limits the number of retrieved fields.
These primitives can fail for the following reasons.
When the primitive fails, a trace VERBOSE: REGEX appears in the cell and an exception will be thrown.
strextract
A-35
strlen
Pattern. Extracts values in the Fields. A pattern consists of literal text and value substitutes. Space characters in the Pattern are matched with any number of consecutive spaces. Non-printable or special characters can be specified in the text with escape sequences, including:
\\ Backslash \% Percent \s Space (single space) \n New line \r Carriage return \t Tab \Odd Character code in octal (0, 1, 2, or 3 digits) Syntax: strmatch ($EV.testmsg, yabola %s, $newstr); strpart
Checks whether the string <arg2> appears in the string <arg1>. If yes, <arg3> gives its starting position.
Syntax: strpart(<str>, <substr>, <pos>) IN: <str> = string IN: <substr> = substring OUT: <pos> = position of substring in string
BMC Software, Inc., Confidential and Proprietary Information
A-36
If output of strpart is to be used as input to substr, the value should be decremented by 1 to avoid an index out of range error.
strnpart
where
<string> is the string to be split. <separator> is the separator specified to use. <list_of_substrings> is the resulting list of substrings.
The list of substrings can be either a temporary variable, such as
$SLITTED_LIST, or a list of temporary string variables, such as [$STR1, $STR2]. Examples: strtolist(abc:def, :, $L); will set $L to [abc, def]. strtolist(abc:def, :, [$L1, $L2]); will set $L1 to abc and $L2 to def. strtolist(abc:def, :, [$L1, $L2, $L3]);
BMC Software, Inc., Confidential and Proprietary Information
A-37
will fail.
Time Primitives
str_to_time_stamp
Computes <arg3>, an integer representing a time_stamp, from <arg1>, a string representing a time that must match the format specified by <arg2>.
Syntax: str_to_time_stamp(<formatted_time>, <time_format>, <time_stamp>) IN: <arg1> string = time_stamp <arg2> format of <arg1> OUT: <arg3> integer = <arg1> of format <arg2>
The <time format> argument is a string that consists of field descriptors and text characters. Each field descriptor consists of a % character followed by another character that specifies the replacement for the field descriptor. All other characters in the format string must have a matching character in the input string, except for whitespace, which matches zero or more whitespace characters in the input string. The supported input field descriptors are listed below. In case a text string, such as a weekday or month name, is to be matched, the comparison is case insensitive. If a number is to be matched, leading zeros are permitted but not required. Modifiers E and O are ignored, as, for example, %Od is interpreted as %d. Value
%% %a or %A %b or %B or %h
Description
The % character. The weekday name according to the current locale, in abbreviated form or the full name. The month name according to the current locale, in abbreviated form or the full name.
A-38
Value
%C %d or %e %D %H or %k %I or %l %j %m %M %n or %t %p %r
Description
The century number (0-99). The day of month (1-31). Equivalent to %m/%d/%y. The hour (0-23). The hour on a 12-hour clock (1-12). The day number in the year (1-366). The month number (1-12). The minute (0-59). Arbitrary whitespace. The locales equivalent of AM or PM. (Note: there may be none.) The 12-hour clock time (using the locales AM or PM). In the POSIX locale equivalent to %I:%M:%S %p. If t_fmt_ampm is empty in the LC_TIME part of the current locale then the behaviour is undefined. Equivalent to %H:%M. The second (0-60; 60 may occur for leap seconds; earlier also 61 was allowed). Equivalent to %H:%M:%S. The day of the week as a decimal number (1-7, where Monday = 1). The week number with Sunday the first day of the week (0-53). The first Sunday of January is the first day of week 1. The ISO 8601:1988 week number as a decimal number (1-53). If the week (starting on Monday) containing 1 January has four or more days in the new year, then it is considered week 1. Otherwise, it is the last week of the previous year, and the next week is week 1. The weekday number (0-6) with Sunday = 0. The week number with Monday the first day of the week (0-53). The first Monday of January is the first day of week 1. The year within century (0-99). When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969-1999); values in the range 00-68 refer to years in the twenty-first century (2000-2068). The year, including century (for example, 1991).
%R %S %T or %X %u %U %V
%w %W %y
%Y
A-39
time_extract
Extracts one or more fields, as specified in <arg2> from time stamp <arg1>, into <arg3>. Time stamp is a value that occurs in the date_reception slot. One single field or a list of fields can be extracted. The corresponding value is either a single integer value, or a list with the integer values of the requested fields, on the same order as the request. The field names in fieldnames are extracted from the time stamp given in TimeStamp. They are returned in the same order in the fieldvalues argument. A time stamp is as retrieved by time_stamp/1 or from the date_reception slot. Field names may be one single field, in which case no list is needed, or a list of fields. The resulting argument takes exactly the same form as the field name argument.
Syntax: time_extract(<timestamp>, <fieldname>, <fieldvalue>) time_extract(<timestamp>, <fieldnamelist>, <fieldvaluelist>) IN: <arg1> MRL integer <arg2> string or list of string OUT: <arg3> MRL integer or list of MRL integer
Recognized fields and their acceptable values for the time_extract primitive are listed in the following table: Field
date time year month day
Time as HHMMSS Year (including century) Month (1..12) Day (range 1..31)
Value
Date as YYYYMMDD
A-40
Field
wday yday hour min sec
Value
Day of the week (Sunday=0) Day of the year (range 1..366) Hour (range 0..23) Minutes (range 0..59) Seconds (range 0..61 - for leap seconds)
The time stamp is interpreted as the local time zone on the machine on which the program is running. An example using the time_extract primitive follows.
time_extract($EV.date_reception,[date,time],[$DT,$TM]) time_stamp
A-41
Functions
The following function types are available in the cell.
Conditional Functions cond(<ExprC>) = TRUE/FALSE Conversion Functions <string> = touppercase(string) <string> = tolowercase(string) <integer> = stringtoint(atomic) <string> = intostring(integer) real = stringtoreal(atomic) <string> = realtostring(real) <pointer> = stringtopointer(string) <pointer> = stringtopointer(atomic) <string> = pointertostring(pointer) Enumeration Functions <enumeration_val>next(<enumeration_val>) <enumeration_val>prev(<enumeration_val>) List Functions <integer> = listlen(<list_of>) <list_of> = listappend(<list_of>, <list_of>) <list_of> = listdelete(<list_of>, <type>) <list_of> = listintersect(<list_of>, <list_of>) <type> = listmember(<list_of>) <type> = listgetelt(<list_of>, <integer>) <list_of> = listsubtract(<list_of>, <list_of>) <list_of> = listunion(<list_of>, <list_of>) <list_of> = listremdup(<list_of>) Mathematical Functions <number2> = abs(<number1>) <real> = exp(<number>) <real> = float(<number>) <integer> = gcd(<integer>, <integer>)
BMC Software, Inc., Confidential and Proprietary Information
A-42
<integer> = int(<number>) <real> = log(<number>) <real> = log10(<number>) <term> = max(<term>, <term>) <term> = min(<term>, <term>) <real> = pow(<number1>, <number2>) <integer> = random(<integer1>, <integer2>) <real> = real(<number>) <integer> = round(<number>) <integer> = sign(<number>) <real> = sqrt(<number>) <integer> = trunc(<number>) Retrieve Data Functions <string> = cellinfo(<string>) <string> = get_env(<string>) String Functions <integer> = len(<string>) <integer> = strlen(<string>) <integer> = strnpart(<string>, <string>, <integer>) <integer> = strpart(<string>, <string>) <list_of_fields> = match_regex(<string>, <regex>, <options>, <nb_fields>) <list_of_substrings> = strtolist<<string>, <separator> <string> = <list_of> strmatch(<string>, <string>) <string> = concat(<list_of>) <string> = mapslots(<list_of_object>, <list_of_string>) (form 1) <string> = mapslots(<list_of_object>, <string>, <list_of_string>) <string> = strextract(<string>, <integer>, <integer>) <string> = string(<string>) <string> = strip(<string>, <integer>) <string2> = strip(<string1>) <string3> = strip(<string1>, <integer>, <string2>) <string2> = lower(<string1>) <string2> = upper(<string1>) <string2> = substring(<string1>, <integer>) <string2> = substring(<string1>, <integer1>, <integer2>)
A-43
Time Functions <integer> = str_to_time_stamp(<formatted_time>,<time_format>) <integer> = time_stamp() <integer> = time_extract(<integer>, one_of([year,month,day,yday,wday,hour, mikn,sec,usec,date,time]) <list_of> = time_extract(<integer>, <list_of(one_of([year,month,day,yday,wday, hour,min,sec,usec,date,time]))) <string> = time_stamp_to_cim(<integer>) Trigonometric Functions <real> <real> <real> <real> <real> <real> <real> = = = = = = = asin(<number>) acos(<number>) atan(<number>) atan2(<number1>, <number2>) sin(<number>) cos(<number>) tan(<number>)
A-44
Conditional Function
cond(<ExprC>) = TRUE/FALSE
If the evaluation results in TRUE, the then expression <ExprT> is evaluated, and its result is the final result of the conditional expression. If the evaluation results in FALSE, the else expression <ExprE> is evaluated, and its result is the final result of the conditional expression. This conditional expression can be used in collector rules as well as in any other rule.
Conversion Functions
<string> = touppercase(<string>)
A-45
<integer> = stringtoint(atomic) <string> = intostring(integer) real = stringtoreal(atomic) <string> = realtostring(real) <pointer> = stringtopointer(String)
Enumeration Functions
The following two functions return the next or previous value of an enumeration type if it exists, otherwise they return its argument.
<enumeration_val> = next(<enumeration_val>) <enumeration_val> = prev(<enumeration_val>)
For example:
$EV.status = next($EV.status); $EV.severity = prev($EV.severity);
A-46
List Functions
<integer> = listlen(list_of(_type))
Builds a new list from a list by removing all occurrences of a specific element.
Syntax: IN: <arg1> = list_of(_type) <arg2> = _type (element to be removed) RET: <arg3> = <list_of(_type), list without the element
A-47
A-48
<list_of(_type_> = listunion(list_of(type),list_of(_type))
Mathematical Functions
<number2> = abs(<number1>)
A-49
<integer> = int(<number>)
A-50
<integer> = sign(<number>)
A-51
String Functions
<integer> = len(<string>)
A-52
Returns a list of strings, <list_of_fields>, that contain the substrings of its first argument ,<string>, matching the <nb_fields> place holders of <regex> first, if specified.
Syntax: <list_of_fields> = match_regex(<string>, <regex>, <options>) <list_of_fields> = match_regex(<string>, <regex>, <options>, <nb_fields>)
where:
<string> is the string to be matched by the regular expression <regex>. <regex> is a Perl-like regular expression implemented with the PCRE library. <options> specifies option for the pattern matching. It is a possibly empty string of [i,m,s,x] characters: i m s
is a case-less string match. is multi-line mode. is dot all, that is, a dot metacharacter in the pattern matches all characters, including newlines. is extended mode. This option causes whitespace data characters in the pattern are ignored except when escaped or inside a character class, and characters between an unescaped # outside a character class and the next newline character, inclusive, are also ignored.
<list_of_fields> is a list of strings which will receive the substrings of <string> matched by the place holders of <regex>.
BMC Software, Inc., Confidential and Proprietary Information
A-53
<nb_fields> represents the first substrings matched by the place holders of <regex>. It is an input parameter that limits the number of retrieved fields.
This function can fail for the following reasons.
When this function fails, a trace VERBOSE: REGEX appears in the cell and an exception will be thrown.
<list_of_substrings> = strtolist(<string>, <separator>)
where
<string> is the string to be split. <separator> is the separator specified to use. <list_of_substrings> is the resulting list of substrings.
The list of substrings can be either a temporary variable, such as
$SLITTED_LIST, or a list of temporary string variables, such as [$STR1, $STR2].
BMC Software, Inc., Confidential and Proprietary Information
A-54
will set $L1 to abc and $L2 to def. Note that the following will fail.
[$L1, $L2, $L3] = strtolist(abc:def, :, ); <string> = <list_of> strmatch(string, string)
A-55
<list_of_object> is a list_of objects, the second parameter is a list of strings: the fist element is a printf format, the remaining elements are strings containing MRL elements that are dynamically interpreted. The value of these expressions replace the corresponding place holders in the printf format to produce the output of the function. The expressions may reference the objects listed in <arg1> with the object variables $1, $2,... corresponding to the 1st, 2nd,... element of <arg1>. MINOR messages are produced in the SERV_MGT module in case of errors such as parsing error, compilation error, or incompatibility between the format and the values.
<string> = mapslots(<list_of_object>, <string>, <list_of_string>)
Same as above except that the printf format is in <arg2> and <arg3>. Contains only the expression for the place holders.
<list_of_classnames> = class_path(<classname>) class_path(<classname>, <list_of_classnames>)
Primitive class_path/2 return in its second argument the list of class name beginning with the class name contain in <arg1> then the names of successive super-classes up to the DATA or EVENT class. Function class_path/1 returns the class path of its argument.
A-56
<string> = strextract(string,integer,integer)
Returns <string1> with all spaces stripped from its beginning, middle, and/or end, depending upon the value of <integer>. Only the three (3) least significant bits (2, 1, 0) of <integer> are considered. Bit 2 represents the beginning, bit 1 the middle and bit 0 the end of <string1>.
<string2> = strip(<string1>)
Returns <string1> with all characters in <string2> stripped from its beginning, middle, and/or end, depending upon the value of <integer>. Only the three (3) least significant bits (2, 1, 0) of <integer> are considered. Bit 2 represents the beginning, bit 1 the middle and bit 0 the end of <string1>.
<string2> = lower(<string1>)
A-57
<string2> = upper(<string1>)
Returns a substring of <string1>; <integer> as the index of the first character of the substring; indexing starts with zero (0).
<string2> = substring(<string1>, <integer1>, <integer2>)
Returns a substring of <string1>; <integer1> as the index of the first character of the substring; <integer2> is the length of the substring; indexing starts with zero.
Time Functions
<integer> = str_to_time_stamp()
Computes an integer representing a time stamp from a string representing a time expressed in a specified format.
<time_stamp> str_to_time_stamp(<formatted_time>, <time_format>) <integer> = time_stamp()
A-58
Trigonometric Functions
Angles are expressed in radians.
<real> = asin(<number>)
A-59
<real> = atan(<number>)
MRL Syntax
This section contains the BNF syntax for the Master Rule Language.
Note
In the following BNF definition, the ClientObject section of the specification is used by the console and other clients and is not used when programming rules.
Meta-Syntax ------------<X> =
Introduces comment Defines rule X
A-60
X | Y X |c: Y [ X ] { X } .. X
Alternative X or Y Alternative X or, on condition c, Y Optional X (0 or 1) Multiple X (0, 1 or more) Range Literal X (used to quote meta-symbols)
-- Object
<Object>
<ServerObject>
<Definition> | <Event> | <Enumeration> | <RecordDef> | <RecordObj> | <Refine> | <Filter> | <Regulate> | <New> | <Abstract> | <Correlate> | <Execute> | <Timer>
A-61
<ClientObject>
<Modify> | <EDelete> | <RecordGet> | <RecordSet> | <Register> | <Unregister> | <Enums> | <Classes> | <Roles> | <Collectors> | <Actions> | <Heartbeat> | <ChngdSev> | <Severities> | <Select> | <QuerySeverity> | <ChngdSol> | <Get> | <Refresh> | <Close> | <Details> | <Eventid> | <EvtRoles> | <Getslot> | <DSelect>
A-62
| <DGet> | <DRefresh> | <DClose> | <DGetslot> | <DNew> | <DModify> | <DDelete> | <Perform> | <Result> | <NtAdd> | <NtCnt> | <NtGet> | <SmGraph> | <SmComps> | <SmSlots> | <Control> | <Info> | <Trace> | <Switch>
<MiscObject>
<ExpressionRl> | <Selection>
-- Definition
<Definition>
A-63
<ClassDef>
<> | <> DEFINES { { <SlotDef> } } | <> ISA <SuperDef> | <> ISA <SuperDef> DEFINES { { <SlotDef> } }
<SuperDef>
<>
<SlotDef>
<SlotFacet>
<SlotType> | key = <YesOrNo> | parse = <YesOrNo> | dup_detect = <YesOrNo> | read_only = <YesOrNo> | default = <SlotValC> | representation = <String> | reverse = <String> | print_ref = <PrintRefVal>
<SlotType>
[ <TypeStruct> ] <Type>
<TypeStruct>
SINGLE | LIST_OF
<Type>
<PrintRefVal>
A-64
<SlotAssignC>
<Slot> = <SlotValC> ;
<SlotAssignV>
<Slot> = <SlotValV> ;
<ObjectRef>
<NameValRef>
<Name> = <String>
-- Event
<Event>
-- Enumeration
<Enumeration>
<EnumDef>
<EnumNumVal> <EnumSymVal>
<EnumNumVal>
<Num>
<EnumSymVal>
<String>
-- RecordDef
<RecordDef>
A-65
<RecSlot>
-- RecordObj
<RecordObj>
-- Refine
<Refine>
-- Filter
<Filter>
<FilterMode>
PASS | NOPASS
-- Regulate
<Regulate>
regulate <RuleName> : <Selection> hold <Expression> within <Expression> send <RegulateEvent> [ unless <Expression> within <Expression> close ] END
<RegulateEvent>
<RegQSelect> | <RegCompose>
A-66
<RegQSelect>
<VarRef>
<RegCompose>
-- New/Update
<New>
<NewEffect>
<Updates> | <Triggers>
<Updates>
<Triggers>
triggers <CallList>
-- Delete
<Delete>
-- Abstract
<Abstract>
A-67
<AbsFrom>
-- Correlate
<Correlate>
<CorWith>
-- Execute
<Execute>
-- Timer
<Timer>
<TimerInfo>
-- Propagate
<Propagate>
<PropTo>
to <PropTarget> { <WhenCond> }
A-68
<PropTarget>
-- Collector
<Collector>
<CollectorPerm>
{ <CollPermSet> { <CollPermSet> } }
<CollPermSet>
<CollPermClass> <Roles> [ ; ]
<CollPermClass>
r | w | x
<CollectorDef>
<CollectorName>
<CollNameComp>
* | <String>
<Roles>
<Expression>
-- Action
<Action>
A-69
<ActionPerm>
{ [ <Role> { , <Role> } ] }
<ActionProgram>
<String>
<ActionName>
<String>
<ActionArg>
<String>
-- Modify
<Modify>
-- EDelete
<EDelete>
-- RecordGet
<RecordGet>
getrec <RecName>.<Slot>
-- RecordSet
<RecordSet>
A-70
<SlotModifyC>
-- Register
<Register>
register
-- Unregister
<Unregister>
unregister
-- Enums
<Enums>
-- Classes
<Classes>
-- Roles
<Roles>
A-71
-- Collectors
<Collectors>
-- Actions
<Actions>
actions [ <Mode> ]
<Interval>
<Num>
-- Heartbeat
<Heartbeat>
heartbeat <Interval>
<Interval>
<Num>
-- ChangedSeverities
<ChngdSev>
changed_severities
-- Severities
<Severities>
A-72
-- Select
<Select>
select <SelectSlots> [format <Format>] [ on <OIDFormula> ] [ from <Selection> [ <Sorting> ] ] [ options <SelectOptions> ] END
<SelectSlots>
<Format>
BAROC | quoted
<Sorting>
<SortCriterium>
<SelectOptions>
{ <SelectOption> { , <SelectOption> } }
<SelectOption>
-- QuerySeverity
<QuerySeverity>
QSEV <QueryID>
-- ChangedSolutions
<ChngdSol>
A-73
-- Get
<Get>
<QueryID>
<Num>
<StartIdx>
<Num>
<EndIdx>
<Num>
-- Refresh
<Refresh>
-- Close
<Close>
close <QueryID>
-- Details
<Details>
<SolutionIdx>
<Num>
-- Eventid
<Eventid>
A-74
| eventid <EventHandle> [ 0 ]
-- EvtRoles
<EvtRoles>
evtroles <EventID>
-- Getslot
<Getslot>
{ , <Slot>
-- DSelect
<DSelect>
dselect <SelectSlots> [format <Format>] [ on <OIDFormula> ] [ from <Selection> [ <Sorting> ] ] [ options <SelectOptions> ] END
-- DGet
<DGet>
-- DRefresh
<DRefresh>
-- DClose
<DClose>
dclose <QueryID>
A-75
-- DGetslot
<DGetslot>
{ , <Slot>
-- DNew
<DNew>
-- DModify
<DModify>
-- DDelete
<DDelete>
-- Perform
<Perform>
A-76
<CellName>
<String>
<ActionArgVal>
<String>
<ActionResult>
result | event
-- Result
<Result>
result <PerformID>
-- NtAdd
<NtAdd>
-- NtCnt
<NtCnt>
ntcnt <EventID>
-- NtGet
<NtGet>
-- SmGraph
<SmGraph>
smgraph <OptionList>
-- SmComps
<SmComps>
smcomps <OptionList>
A-77
-- SmSlots
<SmSlots>
smslots <OptionList>
-- Control
<Control>
control <CtrlCmd>
<CtrlCmd>
stop | pause | start | cellevt { on | off } | celltick { <Num> } | propagate { { <String> } } | lnsz { <Num> } | memstat | prolog { <String> }
-- Debugging
<Info>
info <InfoCategory>
<InfoCategory>
<String>
<Trace>
<Switch>
A-78
<SwitchOp>
<ModuleName>
<String>
<SwitchName>
<String>
<Destination>
<String>
-- When clause
<When>
<WhenCond> <CallList>
<WhenCond>
-- Execution of primitives
<CallList>
{ <Call> ; { <Call> ; } }
<Call>
<Assignment>
<VarRef> = <Expression>
<ProcCall>
A-79
<IfThenElse>
<Arg>
<Expression>
-- Units
<TimeFrame>
<Num> [ <TimeScale> ]
<TimeScale>
s | m | h | d
<Selection>
<Criteria>
[ where [ [
<SlotExp>
<SlotExp1>
<SlotExp2>
A-80
<SlotExp3>
<Cond>
<CondOp> <Expression>
<SlotValV>
<Expression>
-- Variables
<VarRef>
<Variable> | <VariableSlot>
<Variable>
$<VarName>
<VariableSlot>
$<VarName>.<Slot>
-- Expression
<ExpressionRl>
<Expression>
<SubTerm999>
<SubTermM>
<TermN>
<TermN>
<OpNfx> <SubTermN-1>
A-81
| <OpNfy> <SubTermN> | <SubTermN-1> <OpNxfx> <SubTermN-1> | <SubTermN-1> <OpNxfy> <SubTermN> | <SubTermN> <OpNyfx> <SubTermN-1> | <SubTermN-1> <OpNxf> | <SubTermN> <OpNyf>
<Term0>
<Op300xfx>
rem | mod | **
<Op300xfy>
<Op400yfx>
* | / | // | << | >>
<Op500fx>
+ | - | \
<Op500yfx>
+ | - | /\ | \/ | xor
<Op500xf>
s | m | h | d
<Op600yfx>
||
A-82
<Op700xfx>
<FuncName>
<FuncName1>
int | trunc | round | real | float | string | sign | abs | len | code | char | sqrt | exp | log | log10 | sin | cos | tan | asin | acos | atan | int_to_hex | lower | upper | strip
<FuncName2>
<FuncName3>
substring | strip
-- OID Formula
<OIDFormula>
<OIDSimple> { | <OIDSimple> }
<OIDSimple>
<OID> | <OID> +
A-83
-- Options - Common
<OptionList>
{ <Option> { , <Option> } }
<Option>
<String> = <SlotValC>
<CondOp>
equals | not_equals | greater_than | greater_or_equals | smaller_than | smaller_or_equals | between | within | outside | has_prefix | has_suffix | contains | contains_one_of | contained_in | matches | ip_greater_or_equals | ip_smaller_or_equals | ip_matches | ip_matched_by | superclass_of | subclass_of
<SlotValC>
<SlotSmplVal> | <SlotListVal>
<SlotSmplVal>
<Val> | <VariableSlot>
A-84
<SlotListVal>
[ [ <SlotSmplVal> ]
{ , <SlotSmplVal> } ]
-- Base
<IpAddress>
<SmallNum>.<SmallNum>.<SmallNum>.<Small Num>
<IpAddrForm>
<SmallForm>.<SmallForm>.<SmallForm>.<Small Form>
<SmallForm>
<SmallNum>
0 | 1 | .. | 255
<OID>
<Num> { . <Num> }
<YesOrNo>
<QualifiedName>
<String>.<String>
<RecName>
String>
<RuleName>
<String>
<ProcName>
<String>
<VarName>
<String>
A-85
<ArrName>
<String>
<Val>
<String>
<Enum>
<String>
<>
<StringX>
<Slot>
<StringX>
<Position>
<Num>
<StringX>
<String>
<Num>
<DecNum> | <HexNum>
<DecNum>
<HexNum>
A-86
#------------------------------------------------------------# Enumerations #------------------------------------------------------------ENUMERATION STATUS 0 OPEN 10 RESPONSE 20 ACK 30 CLOSED END ENUMERATION SEVERITY 10 UNKNOWN 20 HARMLESS 30 WARNING 40 MINOR 50 CRITICAL 60 FATAL END
#------------------------------------------------------------# Root classes #------------------------------------------------------------ROOT ROOT ROOT ROOT : : : : MC_EV_CLASS; END MC_DATA_CLASS; END MC_INTERFACE; END TEC_CLASS; END
A-87
#-------------------------------------------------------------# Core classes #-------------------------------------------------------------MC_EV_CLASS : EVENT DEFINES { event_handle : INTEGER, parse = no, read_only = yes; mc_ueid : STRING, read_only = yes; source : STRING sub_source : STRING hostname : STRING origin : STRING sub_origin : STRING mc_origin : STRING, parse = no mc_incident_time : INTEGER, representation = date mc_arrival_time : INTEGER, representation = date mc_local_reception_time : INTEGER, representation = date date_reception : INTEGER, representation = date date : STRING status : STATUS, default = OPEN severity : SEVERITY, default = WARNING msg : STRING duration : INTEGER, parse = no repeat_count : INTEGER mc_action_count : INTEGER, parse = no administrator : STRING mc_date_modification : INTEGER, representation = date mc_notes : LIST_OF STRING, read_only = yes mc_bad_slot_names : LIST_OF STRING mc_bad_slot_values : LIST_OF STRING mc_history : LIST_OF STRING mc_modhist : LIST_OF STRING mc_propagations : LIST_OF STRING, parse = no mc_collectors : LIST_OF STRING, parse = no mc_abstraction : LIST_OF INTEGER, parse = no mc_abstracted : LIST_OF INTEGER, parse = no mc_associations : LIST_OF STRING, parse = no mc_cause : INTEGER, parse = no mc_effects : LIST_OF INTEGER, parse = no mc_smc_id : STRING mc_smc_impact : INTEGER, default = 0 mc_smc_type : STRING }; END
BMC Software, Inc., Confidential and Proprietary Information
A-88
MC_DATA_CLASS : DATA DEFINES { data_handle : INTEGER, parse = no, read_only = yes; mc_udid : STRING, read_only = yes; mc_creation_time : INTEGER, parse = no, read_only = yes, representation = date; mc_modification_time : INTEGER, parse = no, read_only = yes, representation = date; }; END
#-------------------------------------------------------------# Enumerations #-------------------------------------------------------------ENUMERATION MC_COMPONENT 10 cell 20 gateway 30 adapter 40 cli 50 browser END
#-------------------------------------------------------------# Event classes #-------------------------------------------------------------MC_EV_CLASS : MC_CELL_CONTROL ISA EVENT DEFINES { cell_name : STRING, dup_detect = yes; cell_location : STRING, dup_detect = yes; }; END
A-89
MC_EV_CLASS : MC_CELL_START ISA MC_CELL_CONTROL DEFINES { severity : default = HARMLESS; pid : INTEGER; init_events : INTEGER; init_data : INTEGER; }; END MC_EV_CLASS : MC_CELL_STOP ISA MC_CELL_CONTROL DEFINES { severity : default = HARMLESS; pid : INTEGER; }; END MC_EV_CLASS : MC_CELL_TICK ISA MC_CELL_CONTROL DEFINES { severity : default = HARMLESS; time_to_next : INTEGER; }; END
MC_EV_CLASS : MC_CELL_STATBLD_START ISA MC_CELL_CONTROL DEFINES { severity : default = HARMLESS; pid : INTEGER; }; END MC_EV_CLASS : MC_CELL_STATBLD_STOP ISA MC_CELL_CONTROL DEFINES { severity : default = HARMLESS; pid : INTEGER; }; END
A-90
MC_EV_CLASS : MC_CELL_DB_CLEANUP ISA MC_CELL_CONTROL DEFINES { severity : default = HARMLESS; nr_closed_events_before : INTEGER; nr_non_closed_events_before : INTEGER; nr_closed_events_after : INTEGER; nr_non_closed_events_after : INTEGER; }; END MC_EV_CLASS : MC_CELL_CONNECT ISA MC_CELL_CONTROL DEFINES { descriptor_limit : INTEGER; connected_clients : INTEGER; }; END
MC_EV_CLASS : MC_CELL_CONNECT_RESOURCES_EXPANDED ISA MC_CELL_CONNECT DEFINES { severity : default = HARMLESS; }; END MC_EV_CLASS : MC_CELL_CONNECT_SUSPENDED ISA MC_CELL_CONNECT DEFINES { severity : default = CRITICAL; }; END MC_EV_CLASS : MC_CELL_CONNECT_RESUMED ISA MC_CELL_CONNECT DEFINES { severity : default = HARMLESS; }; END
A-91
MC_EV_CLASS : MC_CELL_CLIENT ISA MC_CELL_CONTROL DEFINES { client_type : STRING; client_name : STRING; client_location : STRING; }; END MC_EV_CLASS : MC_CELL_ALLOWED_CONNECT ISA MC_CELL_CLIENT DEFINES { severity : default = HARMLESS; }; END
MC_EV_CLASS : MC_CELL_UNALLOWED_CONNECT ISA MC_CELL_CLIENT DEFINES { severity : default = WARNING; }; END MC_EV_CLASS : MC_CELL_DISCONNECT ISA MC_CELL_CLIENT DEFINES { severity : default = HARMLESS; }; END
MC_EV_CLASS : MC_CELL_MODIFIED_EVENT ISA MC_CELL_CLIENT DEFINES { severity : default = HARMLESS; requestor: STRING; event: STRING; }; END
A-92
MC_EV_CLASS: MC_CELL_DESTINATION_UNREACHABLE ISA MC_CELL_CONTROL DEFINES { severity: default = WARNING; destination: STRING; }; END MC_EV_CLASS: MC_CELL_HEARTBEAT_EVT ISA MC_CELL_CONTROL DEFINES { cell: STRING; }; END
MC_EV_CLASS: MC_CELL_HEARTBEAT_ON ISA MC_CELL_HEARTBEAT_EVT DEFINES { severity: default = HARMLESS; down_time: INTEGER; }; END MC_EV_CLASS: MC_CELL_HEARTBEAT_FAILURE ISA MC_CELL_HEARTBEAT_EVT DEFINES { missed: INTEGER; }; END MC_EV_CLASS: MC_CELL_PARSE_ERROR ISA MC_CELL_CONTROL DEFINES { event_text: STRING; error_line: INTEGER; error_column: INTEGER; error_message: STRING; }; END
A-93
MC_EV_CLASS: MC_CELL_UNDEFINED_CLASS ISA MC_CELL_CONTROL DEFINES { class_name: STRING; }; END MC_EV_CLASS: MC_CELL_PROCESS_ERROR ISA MC_CELL_CONTROL DEFINES { event: STRING; error_goal: STRING; error_source: STRING; error_code: INTEGER; error_message: STRING; }; END MC_EV_CLASS: MC_CELL_ACTION_RESULT ISA MC_CELL_CONTROL DEFINES { severity : default = HARMLESS; name: STRING; action: STRING; event: STRING; requestor: STRING; arguments: LIST_OF STRING; start_time: INTEGER, representation = date; end_time: INTEGER, representation = date; exit: INTEGER; output_val: STRING; output_ref: STRING; error_val: STRING; error_ref: STRING; }; END
A-94
MC_DATA_CLASS : MC_CELL_DIR_COMPONENT ISA MC_CELL_DATA DEFINES { type : MC_COMPONENT, # Type of component read_only = yes; subtype : STRING, # Component subtype if any read_only = yes; name : STRING, # Name of component read_only = yes, key = yes; location : STRING, # Location as Address:Port read_only = yes; }; END MC_DATA_CLASS : MC_CELL_REGULATE ISA MC_CELL_DATA DEFINES { rule : STRING, # Regulate rule name read_only = yes, key = yes; event_handle : INTEGER, # ID of one of queued events read_only = yes, key = yes; class : STRING, # Queued event class name read_only = yes; low_severity : SEVERITY # Lowest severity of queued events read_only = yes; high_severity : SEVERITY, # Highest severity of queued events read_only = yes; repeat_count : INTEGER, # Number of events in Queue read_only = yes; first_time : INTEGER, # Reception time of first event read_only = yes, representation = date; last_time : INTEGER # Reception time of last event read_only = yes, representation = date; duration : INTEGER, # Time between first and last event read_only = yes; }; END
A-95
MC_DATA_CLASS : MC_CELL_HEARTBEAT ISA MC_CELL_DATA DEFINES { cell : STRING, # Source/destination Cell # name read_only = yes, key = yes; enable : INTEGER, # 0=disabled / 1=enabled default = 1; last_time : INTEGER, # Time of last succeeded # heartbeat read_only = yes, representation = date; interval : INTEGER, # Interval between heartbeats default = 300; # Minimum=10 missed_warning : INTEGER, # Number of misses for WARNING # event default = 2; # 0 to disable WARNING events missed_minor : INTEGER, # Number of misses for MINOR # event default = 4; # 0 to disable MINOR events missed_critical : INTEGER, # Number of misses for # CRITICAL event default = 6; # 0 to disable CRITICAL events missed : INTEGER, # Number of consecutive misses read_only = yes; }; END
A-96
MC_DATA_CLASS : MC_CELL_METRIC ISA MC_CELL_DATA DEFINES { subject : STRING, # Metric subject name read_only = yes, key = yes; description : STRING; # Metric description short_interval : INTEGER, # Short term interval # length(s) read_only = yes; short_total : INTEGER, # Short term total count read_only = yes; short_average : INTEGER, # Short term average (per s) read_only = yes; medium_interval : INTEGER, # Med. term interv. length(s) read_only = yes; medium_total : INTEGER, # Medium term total count read_only = yes; medium_average : INTEGER, # Medium term average (per s) read_only = yes; long_interval : INTEGER, # Long term interv. length(s) read_only = yes; long_total : INTEGER, # Long term total count read_only = yes; long_average : INTEGER, # Long term average (per s) read_only = yes; }; END
A-97
#-------------------------------------------------------------# Records #-------------------------------------------------------------RECORD MC_CELL_INFO DEFINES { cell_name : STRING; cell_description : STRING; cell_release : STRING; cell_build : STRING; cell_date : STRING; service_address : STRING; service_port : INTEGER; home_dir : STRING; start_date : INTEGER; platform : STRING; } END
# # # # # # # # # #
Cell name Cell description Cell release number Cell build number Cell build date IP Address of service Port number of service Home directory Time stamp of Cell start Platform code
A-98
Glossary
Glossary
$MCELL_HOME
The Unix platform environment variable that defines the home directory in which product files reside. Use this environment variable to find all product executables and configuration files. The Windows platform environment variable that defines the home directory in which product files reside. Use this environment variable to find all product executables and configuration files. On Unix platforms, the directory that contains the setup_env.sh and setup_env.csh scripts, which set the environment variables used by the product software. The event-processing phase in which Abstract rules are evaluated and, if conditions are met, abstraction events are generated. See also abstraction event. An event-processing rule that creates an abstraction event from one or more raw events. An event that contributes to the creation of an abstraction event. The abstracted event is the basis for inferring that some condition exists. For example, if a critical subprocess of an application is down, the application is down.
%MCELL_ HOME%
/etc/mcell
Abstract phase
Abstract rule
abstracted event
Glossary
abstraction event
A conceptual or summary event based on other events that are occurring. You cannot understand the context of an abstraction event by its details. To understand its context, you must view the relationships between the abstraction event and the events that triggered its creation in the BMC Impact Explorer Events Tab, Relationships window. See abstracted event. An executable that can be run by a cell. Actions are called in an Execute rule. Users can request the execution of actions in the BMC Impact Explorer. See also local action, remote action. A background process that audits data from various sources, evaluates it for specific conditions, and creates the corresponding events. Adapters also transform event data into the format understood by <Bold>BMC Impact Manager. The BMC Impact Explorer user interface for cell administration. Administrative users can start, pause, stop, and reconfigure a cell by using this interface. They can also make changes to a cells dynamic data tables. The person responsible for administrative tasks within the product. See Application Program Interface (API). A set of externalized functions that allow interaction with an applications. See slot. Basic Recorder of Objects in C. A structured language used to create and modify class definitions. A class definition is similar to a structure in the C programming language. The elements in a structure are called slots. In programming, a root superclass, a class from which all other classes of its type are derived.
action
adapter
Administration View
administrator
base class
The adapters that collect log file information, convert it to BMC Impact events, and send the events to a designated <Bold>BMC Impact Manager instance or instances. They are implemented in the Perl language. The native Windows platform executable that audits Windows event logs. It runs as a Windows service and checks for new event log records. See BMC Impact Database Gateway. See BMC Event Adapters. See BMC Event Log Adapter for Windows. See BMC Impact Integration product. See BMC Impact Manager. The interface that enables <Bold>BMC Impact Manager events to be exported to a relational database. A console with which you can connect to any number of <Bold>BMC Impact Managers, examine the events stored in them, and perform event and service management activities. The configuration server that administrators use to manage user access to <Bold>BMC Impact Managers resources. The Service Explorer Server runs as a daemon on Unix platforms and as a service on the supported Windows platforms. Synonym: MCCS. An interface that enables the synchronized, bidirectional flow of events and data between a <Bold>BMC Impact Manager instance and another BMC Software product or a specific third-party product.
BMC Event Log Adapter for Windows (BMC IELA) BMC IDG BMC IEA BMC IELA BMC II BMC IM BMC Impact Database Gateway (BMC IDG) BMC Impact Explorer (BMC IX)
Glossary
The BMC Impact product that provides automated event and service-impact management. It runs as a service on supported Windows platforms and as a daemon on Unix platforms, and can be distributed throughout a networked enterprise and connected in various topologies to support IT goals. See BMC Impact Explorer. See BMC Impact Explorer. The event processing engine that collects, processes, and stores events within a <Bold>BMC Impact Manager instance. Each cell uses the information in the associated Knowledge Base to identify the type of events to accept and how to process and distribute them. A collector contained within another collector. A BAROC-language data structure that defines a type of object used in <Bold>BMC Impact Manager. A class is made up of data fields, called slots, that define its properties. A product command that is issued on the OS command line for automation or immediate execution. For a complete list of command line interface (CLI) commands, see the BMC Impact Manager Administrator Guide. An event grouping whose content is defined by its collector rule. Collectors are displayed in the BMC Impact Explorer and are defined in the <Bold>BMC Impact Manager Knowledge Base. See also collector rule. A type of rule defined in the Knowledge Base that defines how events from a cell are organized and presented in the BMC Impact Explorer. Collector definitions are written in Master Rule Language (MRL).
CLI command
collector
collector rule
collector set
A group of collectors, organized in a parent-child hierarchy, that performs progressive filtering of those incoming events that match the top-level (parent collector) criteria. A collector set selects a set of events and organizes them for display in the BMC Impact Explorer. See Service-Model component (SMC). See Service-Model-component relationship. A type of service-model component that represents the types of connections between IT components. See BMC Impact Explorer. A <Bold>BMC Impact Manager instance that can receive and process events originating from other systems on the network. The event-processing phase in which the Correlate rules are evaluated to determine whether any events have a cause-and-effect relationship. See also Correlate rule. An event processing rule that establishes a cause-and-effect relationship between two events. Correlate rules represent a one-to-one relationship. A cause-and-effect relationship established between two events. A BAROC class that is a child of the base event class, DATA, and that defines a type of data. The event-processing phase in which Delete rules are evaluated and actions are taken to ensure that data integrity is maintained when an event is deleted from the repository during the cleanup process. An event-processing rule that is used to clean up obsolete information when an event is deleted from the repository. Delete rules are evaluated when an event is deleted, and they take actions to ensure that data integrity is maintained.
Glossary 5
Correlate phase
Correlate rule
Delete phase
Delete rule
dynamic collector
A special type of collector that, in response to events, can add or remove event collectors from the cell during runtime. Contextual reference data that is stored in a table in the repository (mc.db) and that can be updated during runtime. Administrators can use and manipulate dynamic data in the <Bold>BMC Impact Manager Administration View. Event Condition Formula. The section of an MRL rule definition that specifies the conditions that an incoming event must meet to trigger evaluation of the rule during processing. For example: APP_MISSING_PROCESSES where [hostname: == red1, sub_origin: contains System] is an ECF. A structured message passed to and from cells in a BMC Impact environment. It is an instance of an event class. See BMC Event Adapters. A BAROC class that is a child of the base event class, EVENT, and that defines a type of event. See BMC Log Adapter for Windows. Obsolete term. See cell. The act of forwarding events and maintaining their synchronization among multiple <Bold>BMC Impact Managers. See repository. The BMC Impact Explorer user interface for viewing and manipulating event data. The event-processing phase in which Execute rules are evaluated and, if conditions are met, specified actions are performed.
dynamic data
ECF
event
Execute phase
Execute rule
An event-processing rule that performs actions when a slot value changes in the event repository. Execute rules are evaluated during the Execute phase of event processing. Often, the resulting actions are internal actions, but you can use the execute primitive in a rule to call an external executable. The process used to view additional details about an event and its relationships. You can view event relationships in the BMC Impact Explorer Events Tab, Relationships window. A specific attribute of a class slot that either controls the values that the slot can have or controls aspects of a class instances processing. See slot. The event-processing phase in which Filter rules are evaluated to determine which events need additional processing or are unneeded and are to be discarded. An event-processing rule that determines whether a specific type of event should be passed as is, subjected to further processing, or discarded as unwanted during the Filter phase. See BMC Impact Manager Integration product. A special file that controls the propagation and synchronization of events to a BMC Impact Manager Integration product. The file is in the $MCELL_HOME/etc/ directory on Unix platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms. A special BAROC class instance that defines a persistent global variable. When a cell starts, it creates one instance of each global record defined in the Knowledge Base and restores any existing values. Global record definitions are stored in the record subdirectory of the Knowledge Base. You can get and set global record values in rules or using the CLI mgetrec and msetrec commands.
facet
Filter rule
global record
Glossary
An ordering of slots that is shared among users. A dynamic data object sent by which a cell to monitor other cells to verify that they remain active and accessible. A relationship between two components in a service infrastructure in which a consumer component depends on a provider component to deliver some resource to it. Changes in status of the provider affects (has an impact on) the status of the consumer component. See also null relationship. An object with specific attribute values created using a class definition. See BMC Impact Integration product. A BAROC class that defines the programming interface used by an MRL rule primitive, such as get_external, to return data from an external program. At cell startup, an interface class is loaded into memory. The cell invokes the executable defined in an argument of the primitive. The executables value is returned by the interface. A BAROC internal class that defines the required structure for the base class from which a group of product classes is derived. An event that is created by the cell during event processing. An internal event is processed in the same way as an incoming event. All internal events are processed before any new incoming external events are processed. A type of Service-Model component (SMC) that represents physical IT resources, such as hardware or application software. The default directory in which a <Bold>BMC Impact Manager Knowledge Base is located. The directory and basic product definitions are created during installation.
impact relationship
instance
internal event
IT component
kb directory
key
The seed encryption key. If the destination <Bold>BMC Impact Manager or BMC Impact Integration product has a key value, all clients must encrypt their communications using the same key value. A collection of information that forms the intelligence of a <Bold>BMC Impact Manager instance and enables it to process events and perform service-impact-management activities. This information includes event class definitions, Service-Model component definitions, record definitions, interface definitions, collector definitions, data associations, and processing rules. A file that specifies the order in which a directorys files are to be loaded and read by a <Bold>BMC Impact Manager instance. An executable that you can run directly from the BMC Impact Explorer. Local actions are written in xml and are stored in the OS-specific subdirectory of the bin directory of the Knowledge Base. A type of Service-Model component that represents logical resources involved in the delivery of business services, such as user groups. An executable used in MAP files to execute code that manipulates the fields used for event translation. A central locator file that specifies the locations of the directories that make up a Knowledge Base. The manifest.kb file is used by the compiler to load the Knowledge Base source files for compilation. A text file that defines the translation of a message between one event format and another. A compact, declarative language used to define rules and collectors for processing and organizing events. Uncompiled rule and collector source files have a .mrl file extension. See Service Explorer Server.
.load file
local action
logical component
macro
manifest.kb
MAP file
MCCS
Glossary
mccomp
The rules compiler. Rules are written in the Master Rule Language (MRL). The platform-independent compiler converts them to byte code that the cell can read and process. The configuration file that contains configuration options for a <Bold>BMC Impact Manager instance. It is in the $MCELL_HOME/etc/ directory on Unix platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms. The file that lists the cells to which a product component can connect and communicate. The information for each cell includes: its name, its encryption key, and its host name and port number. This file is in the $MCELL_HOME/etc/ directory on Unix platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms. The file that lists the slots that affect the mc_modification_date slot. When a specified slot is modified, the time stamp of the modification is reset in the mc_modification_date slot. The configuration file that specifies the slot values that are synchronized during event propagation between cells. It is in the $MCELL_HOME/etc/ directory on Unix platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms. The configuration file that specifies the <Bold>BMC Impact Manager trace information that should be recorded and the location to which it is written. It is in $MCELL_HOME/etc/ directory on Unix platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms. The configuration file that specifies the configurations for the <Bold>BMC Impact Manager command line interface (CLI) commands. It is in the $MCELL_HOME/etc/ directory on Unix platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.
mcell.conf file
mcell.dir file
mcell.modify file
mcell.propagate file
mcell.trace file
mclient.conf file
10
mclient.trace file
The configuration file that specifies the trace information that should be collected for the CLI commands and the location to which it should be written. This file is in the $MCELL_HOME/etc/ directory on Unix platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms. The CLI command that sends control commands to a <Bold>BMC Impact Manager instance. See internal base class. A virtual collector that contains a group of collectors from multiple <Bold>BMC Impact Manager instances. It exists only in the BMC Impact Explorer, and you can customize it. A file that contains rule and collector definitions written in the Master Rule Language (MRL). Event and service management processing rules and collectors are stored in .mrl files, and in compiled .wic files. The event-processing phase in which the New rules are evaluated to determine which events in the repository should be updated with new information from new incoming events. This is the last opportunity to prevent an event from entering the repository. An event processing rule that is evaluated during the New event processing phase, and can update events stored in the repository (mc.db) with fresh information from new incoming events. A <Bold>BMC Impact Manager instance that can receive only events originating on the local host system. A relationship between two components in a service infrastructure in which there is no impact to the consumer component. A null relationship only indicates that the two components are connected logically and are represented visually as linked. See also impact relationship.
mcontrol command
metaclass MetaCollector
.mrl file
New phase
New rule
node
null relationship
Glossary
11
open event
An event that may require action. An OPEN status indicates that an event has not yet been examined, or that neither an operator nor an automated process has been assigned responsibility for the event. A collector that contains child collectors to form a collector set. A specific stage of event processing. There are eight sequential phases to event processing and two nonsequential phases, each with a corresponding rule type. A number that designates a specific communication channel in TCP/IP networking. Ports are identified by numbers. <Bold>BMC Impact Manager communicates using the ports specified during installation. A user that can open the BMC Impact Explorer interface without entering a password on a machine to which he or she is authorized access. A function that is available in the MRL language. See the BMC Impact Manager Knowledge Base Reference Guide for information about the MRL primitives and how to use them. The event-processing rule phase in which Propagate rules are evaluated to determine the events to be forwarded to another cell or to an Integration product. An event-processing rule that is used to forward events to other <Bold>BMC Impact Managers in the managed domain. Propagate rules are evaluated during the Propagate phase of event processing. An event that is forwarded from one cell to another cell or to an Integration product during the Propagate phase of event processing. See global record.
port
pre-authenticated user
primitive
Propagate phase
Propagate rule
propagated event
record
12
Refine phase
The first phase of event processing in which Refine rules are evaluated to validate incoming events and, if necessary, collect additional data needed before further event processing can occur. A rule evaluated during the first phase of event processing to validate an incoming event and, if necessary, to collect any additional data needed before further processing can occur. The event-processing phase, in which Regulate rules are evaluated and, if true, collect duplicate events for a time period and, if a specified threshold of duplicates is reached, passes an event to the next processing phase. An event processing rule that processes repetitive (duplicate) events or events that occur with a specified frequency. With a Regulate rule, you can create a new event based on the detection of repetitive or frequent events. See also Regulate phase. An executable that can be run by a cell. Remote actions are written in the Master Rule Language (MRL) and are stored in the OS-specific subdirectory of the bin directory of the Knowledge Base. A user that is not granted access from a specific machine and that must enter a user name and password to open the BMC Impact Explorer. An event that has matching values for all the slots defined with the dup_detect=yes facet in the event class definition. You can use Regulate rules to detect and count repetitive events. See also facet. The storage facility in which event information is stored.
Refine rule
Regulate phase
Regulate rule
remote action
remote user
repetitive event
repository
Glossary
13
rule
A conditional statement that, if determined to be true, executes actions. The cell evaluates events by comparing each event to a series of rules during event processing. Rules are grouped in phases that are processed one by one. The order in which rules are evaluated during a particular phase is based on the order in which they were loaded. When all the rules in one phase are evaluated, the cell moves to the next phase. See cell. A designation of a rule that applies to a specific phase of event processing. The cell processes rules within the context of the associated event-processing phase and in the order in which the rules were loaded from the rule file. The state of a <Bold>BMC Impact Manager instance as determined by the StateBuilder utility, statbld.exe. The StateBuilder utility periodically consolidates the data in the transactions file (xact) to produce the saved state of the product instance. This information is stored in the mcdb file and the state is reloaded when <Bold>BMC Impact Manager restarts. Software Development Kit. A set of procedures and tools with which to develop a type of application. An agreement that defines the required availability of a business service to its consumers. A type of Service Model component that represents service-level agreements and metrics. A measurement of some aspect of service delivery. An extensible system for defining the various resources that combine to deliver business services, for modeling their behaviors and functional relationships, and for managing the delivery of the resulting services.
saved state
SDK
Service Level Agreement (SLA) service-levelagreement component service level metric (SLM) Service Model (SM)
14
A logical or physical resource that participates in the delivery of services. There are four types of Service-Model components: connectivity components, IT components, logical components, and service level agreement components. An SMC can provide services to or consume services from another component. In technical terms, a Service-Model component is any data class that is a subclass of the MC_SM_COMPONENT base class. The association of two Service-Model components. There are two types of component relationships: impact and null. See also impact relationship, null relationship. The BMC Impact Explorer user interface for viewing Service-Model components and their relationships and for viewing and managing the events that affect service availability. A component that is a copy of a component existing on another cell. Shadow components are used when setting up distributed Service Models. An attribute in a BAROC class definition. A class definition consists of one or more slots. Each slot has a data type and can have specific attributes, called facets, that can control the values that the slot can have or control aspects of a class instances processing. A class that is a subclass to another class inherits all the slots of the parent class. The process of updating the slot value of a class instance. See facet. The process by which slot changes are synchronized among cells. The value associated with a particular slot (attribute) of a class instance. A slot name and its associated slot value. See Service Model.
shadow component
slot
slot value
Glossary
15
See Service Model component. An adapter that listens at a port for SNMP traps. It evaluates the traps and formats them based on the configured event mapping. If the event-mapping conditions are satisfied, it sends the event to the cell. The configuration file for the StateBuilder utility. It is in the $MCELL_HOME/etc/ directory on Unix platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms. The configuration file that specifies the trace information to be collected for the StateBuilder utility and where it should be written. It is in the $MCELL_HOME/etc/ directory on Unix platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms. The utility, statbld, that periodically consolidates the data in a cells transactions file (xact) and writes the Saved State of the cell to a file (mcdb). (1) For events, an indication of the events management. Possible values are: Open, Acknowledged, Closed. (2) For Service-Model components, an indication of the relative availability of an IT resource. Possible values are: Unavailable, Impacted, At Risk, Maintenance, Available, Unknown, None.
statbld.conf file
statbld.trace file
StateBuilder utility
status
A dynamic data table that defines the different pairs of service component types whose instances can have a relationship and the status propagation model to be used for each relationship. A mechanism that ensures that if an event cannot reach its destination, it is saved in a file and sent when a viable connection to the destination becomes available.
16
stored event
An event that has been processed by the cell and stored in the event repository. Only stored events are returned by queries and are: displayed in BMC Impact Explorer, returned by the mquery CLI command, or referenced by the Using and Update clauses of an MRL rule. The status of a consumer component that is calculated from the status of the components on which it depends. If a component does not depend on any other components, it does not have a substatus. In the GUI, a components substatus is indicated graphically by an offset square in its background. A hierarchically superior event or data class. A class that is derived from another class inherits part of its attributes (slots) from its superclasses. An adapter that collects information from the log file generated by the Unix daemon syslogd. The Syslog adapter reads syslogd events and formats and sends them to the cell. The set of dynamic data instances of a particular data class. The entity designated to receive events from an adapter, an event generator, or a <Bold>BMC Impact Manager instance. Also, a cell whose content currently is displayed in a BMC Impact Explorer dialog. The event-processing phase in which Timer rules for the delayed execution of another rule type are evaluated. This phase spans the New, Abstract, Correlate, and Execute phases of event processing. An event-processing rule that triggers the delayed execution of another type of rule. See Timer rule. See New phase.
substatus (component)
superclass
Syslog adapter
table target
Timer phase
Timer rule
Glossary
17
Using clause
An MRL rule clause used to access dynamic data and to query events. A part of MRL rule syntax for Abstract, Correlate, Execute, Propagate, and Timer rules. Events must first meet the selection criteria in the rule before the When clause is evaluated. Changes to slot values cause When clauses to be re-evaluated. For details, see the <Bold>BMC Impact Manager Knowledge Base Reference Guide. A type of pattern matching that uses the asterisk character (*) to represent any number of different characters, and the question mark character (?) to represent a single unknown character.
When clause
wildcard
18
Index
Index
Symbols
#, usage in BAROC language 2-4 *,usage in BAROC language 2-4 +, usage in BAROC language 2-4 .baroc files 1-20 .load files 1-20, 2-6 .mrl files 1-19, 1-20 inheritance in 2-2 symbols 2-4 syntax 2-4 syntax rules 2-5 types supported 2-7 Basics of the Knowledge Base 1-18 Basics of the knowledge base 1-5 between operator A-5 bin directory 1-24 BMC Impact Explorer Server 1-12 BMC Impact Manager Overview 1-1 product components 1-4 BMC Impact Manager, technologies 1-5 BMC Software, contacting ii brackets, usage in BAROC language 2-4
A
Actions 1-19 Adapters Definition of 1-12 add_to_list primitive A-24 Arithmetic operators A-14 asterisk (*), usage in BAROC language 2-4 atomtopointer primitive A-17 atomtoreal primitive A-17
C
Catch all option 6-9 Cell Definition of 1-5 cell Definition of 1-12 Distributed network of 1-13 Network illustrated 1-13 cells
B
BAROC 1-12, 1-15, 1-19, 1-20 BAROC language class definitions 2-6 concepts 2-2
BMC Software, Inc., Confidential and Proprietary Information
Index
described 1-6 cells, internal classes MC_CELL_CONTROL 2-27 MC_CELL_DATA 2-28 Class definitions 1-19 classes DATA 2-24 definition of, basic syntax 2-6 definition of, overview 2-6 EVENT 2-17 inheritance in 2-2 instances, syntax of 2-12 internal base 2-16 internal base classes 2-2 Collector Catch all 6-9 Overview 3-1, 6-2 Collector definitions Overview 1-19 Collectors Dynamic 6-8 Setting up permissions 6-5 Static 6-8 collectors directory 1-25 Commands mccomp 1-21 concat A-33 concat primitive A-33 Condition operators 6-15 Console component Definition of 1-12 contained_in operator A-7 contains operator A-7 conventions, document xiii customer support iii
DATA base class, described 2-16 Data classes 1-19 data classes DATA base class 2-16 data directory 1-26 Data types A-2 default facet, described 2-9 Directories bin 1-24 collectors 1-25 data 1-26 lib 1-26 records 1-26 rules 1-27 Distributed network of cells 1-13 document conventions xiii documentation related xi drop_new primitive A-19, A-30 dup_detect facet, described 2-9 dynamic data described 1-8 Dynamic Data Model 1-13
E
enumerations SEVERITY 2-25 STATUS (event) 2-25 syntax of 2-13 equals operator A-4 Event Class definitions 1-19 Classes Defined in Cells knowledge base 1-7 EVENT base class 2-17 event classes EVENT base class 2-16 Event Condition Formula (ECF) 6-12
BMC Software, Inc., Confidential and Proprietary Information
D
DATA base class slot definitions 2-24
2
Event Repository 1-13 event STATUS enumeration 2-25 execute primitive A-19, A-29
I
inheritance class 2-2 instances of classes syntax of 2-12 interface classes MC_INTERFACE class 2-16 internal base classes 2-16 ip_greater_or_equals operator A-9 ip_matches operator A-10 ip_smaller_or_equals operator A-9
F
facets 2-9 default 2-9 dup_detect 2-9 key 2-9 parse 2-9 read_only 2-9 representation 2-9 Files .baroc 1-20 .load 1-20 .mrl 1-19, 1-20 mccs.init 6-10 files .load 2-6 Filter rule 5-6 Functions A-42
K
key facet, described 2-9 Knowledge Base Basics 1-18 Default location 1-22 described 1-7 Working location 1-22 Knowledge base Basics 1-5
G
generate_event primitive A-21 get_env primitive A-33 get_external primitive A-31 Global record definitions 1-19 greater_or_equals operator A-5 greater_than operator A-5
L
lib directory 1-26 listappend primitive A-25 listdelete primitive A-25 listdisjoint primitive A-25 listgetelt A-26 listgetelt primitive A-26 listintersect A-26 listintersect primitive A-26 listlen A-26 listlen primitive A-26 listremdup primitive A-27 listsubtract primitive A-27
H
has_prefix operator A-6 has_suffix operator A-6
Index
M
Master Rule Language (MRL) 1-19 matches operator A-8 MC_CELL_CONTROL internal class 2-27 MC_CELL_DATA internal class 2-28 MC_DATA_CLASS internal base class described 2-16 MC_EV_CLASS internal base class described 2-16 MC_INTERFACE internal base class described 2-16 mc_udid slot 2-8 mc_uedid slot described 2-8 mccomp command 1-21 mccs.init file 6-10 MetaCollector definition 2-11
has_prefix A-6 has_suffix A-6 ip_greater_or_equals A-9 ip_matches A-10 ip_smaller_or_equals A-9 matches A-8 not_equals A-4 outside A-4 smaller_or_equals A-6 smaller_than A-5 subclass_of A-12 superclass_of A-11 within A-4 outside operator A-4 Overview Collector definitions 1-19 Collectors 3-1, 6-2 Rules 1-19 Syntax A-1
P
Parent collector Catch all 6-9 parse facet, described 2-9 Permissions On collectors 6-5 Phases Filter 5-6 plus sign (+), usage in BAROC language 2-4 pointertoatom primitive A-18 pound sign (#), usage in BAROC language 2-4 Primitives A-14 add_to_list A-24 atomtopointer A-17 atomtoreal A-17 concat A-33 drop_new A-19, A-30 execute A-19, A-29
BMC Software, Inc., Confidential and Proprietary Information
N
new_data primitive A-22 not_equals operator A-4
O
Operators A-3 Arithmetic A-14 between A-5 contained_in A-7 contains A-7 equals A-4 greater_or_equals A-5 greater_than A-5
generate_event A-21 get_env A-33 get_external A-31 listappend A-25 listdelete A-25 listdisjoint A-25 listgetelt A-26 listintersect A-26 listlen A-26 listremdup A-27 listsubtract A-27 listunion A-28 listwalk A-28 new_data A-22 pointertoatom A-18 realtoatom A-18 rem_from_list A-24 remove_data A-23 reset_default A-19 set_timer A-19 strextract A-35 strlen A-36 strmatch A-36 strpart A-36 time_extract A-40 time_stamp A-41 time_stamp_to_cim A-41 product support iii Propagate Events 1-14
repository described 1-7 representation facet, described 2-9 reset_default primitive A-19 root classes DATA 2-24 EVENT 2-17 Rule phase Filter 5-6 Rules Directory 1-27 Overview 1-19
S
set_timer primitive A-19 Setting up collector permissions 6-5 SEVERITY enumeration 2-25 slots description of 2-7 facets, defined 2-9 types 2-7 smaller_or_equals A-6 smaller_than operator A-5 SNMP trap 1-12 STATUS (event) enumeration 2-25 strextract primitive A-35 strlen primitive A-36 strmatch primitive A-36 strpart primitive A-36 subclass_of operator A-12 superclass_of operator A-11 support, customer iii symbols BAROC language 2-4 Syntax Arithmetic operators A-14 Data types A-2 Functions A-42 Operators A-3
Index 5
R
read_only facet 2-9 realtoatom primitive A-18 records directory 1-26 related documentation xi release notes xiii rem_from_list primitive A-24 remove_data primitive A-23
BMC Software, Inc., Confidential and Proprietary Information
Overview A-1 Primitives A-14 syntax BAROC language 2-4 class definitions 2-6 rules of BAROC language 2-5
T
TEC_CLASS internal base class described 2-16 technical support iii time_extract primitive A-40 time_stamp primitive A-41 time_stamp_to_cim primitive A-41 types, listed 2-7
U
Understanding 1-12 universal data identifier 2-8 universal event identifier 2-8 universal identifiers mc_udid 2-7 mc_ueid 2-7
W
within operator A-4
TRIAL LICENSE. If, as part of the ordering process, the Product is provided on a trial basis, then these terms apply: (i) this license consists solely of a non-exclusive, non-transferable evaluation license to operate the Software for the period of time specified from BMC or, if not specified, a 30 day time period (Trial Period) only for evaluating whether You desire to acquire a capacity-based license to the Product for a fee; and (ii) Your use of the Product is on an AS IS basis without any warranty, and BMC, ITS AFFILIATES AND RESELLERS, AND LICENSORS DISCLAIM ANY AND ALL WARRANTIES (INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT) AND HAVE NO LIABILITY WHATSOEVER RESULTING FROM THE USE OF THIS PRODUCT UNDER THIS TRIAL LICENSE (Trial License). BMC may terminate for its convenience a Trial License upon notice to You. When the Trial Period ends, Your right to use this Product automatically expires. If You want to continue Your use of the Product beyond the Trial Period, contact BMC to acquire a capacity-based license to the Product for a fee. TERMINATION. This Agreement shall immediately terminate if You breach any of its terms. Upon termination, for any reason, You must uninstall the Software, and either certify the destruction of the Product or return it to BMC. OWNERSHIP OF THE PRODUCT. BMC or its Affiliates or licensors retain all right, title and interest to and in the BMC Product and all intellectual property, informational, industrial property and proprietary rights therein. BMC neither grants nor otherwise transfers any rights of ownership in the BMC Product to You. Products are protected by applicable copyright, trade secret, and industrial and intellectual property laws. BMC reserves any rights not expressly granted to You herein. CONFIDENTIAL AND PROPRIETARY INFORMATION. The Products are and contain valuable confidential information of BMC (Confidential Information). Confidential Information means non-public technical and non-technical information relating to the Products and Support, including, without limitation, trade secret and proprietary information, and the structure and organization of the Software. You may not disclose the Confidential Information to third parties. You agree to use all reasonable efforts to prevent the unauthorized use, copying, publication or dissemination of the Product. WARRANTY. Except for a Trial License, BMC warrants that the Software will perform in substantial accordance with the Documentation for a period of one year from the date of the order. This warranty shall not apply to any problems caused by software or hardware not supplied by BMC or to any misuse of the Software. EXCLUSIVE REMEDY. BMCs entire liability, and Your exclusive remedy, for any defect in the Software during the warranty period or breach of the warranty above shall be limited to the following: BMC shall use reasonable efforts to remedy defects covered by the warranty or replace the defective Software within a reasonable period of time, or if BMC cannot remedy or replace such defective copy of the Software, then BMC shall refund the amount paid by You for the License for that Software. BMC's obligations in this section are conditioned upon Your providing BMC prompt access to the affected Software and full cooperation in resolving the claim. DISCLAIMER. EXCEPT FOR THE EXPRESS WARRANTIES ABOVE, THE PRODUCT IS PROVIDED AS IS. BMC, ITS AFFILIATES AND LICENSORS SPECIFICALLY DISCLAIM ALL OTHER WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. BMC DOES NOT WARRANT THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR FREE, OR THAT ALL DEFECTS CAN BE CORRECTED. DISCLAIMER OF DAMAGES. IN NO EVENT IS BMC, ITS AFFILIATES OR LICENSORS LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES RELATING TO OR ARISING OUT OF THIS AGREEMENT, SUPPORT, AND/OR THE PRODUCT (INCLUDING, WITHOUT LIMITATION, LOST PROFITS, LOST COMPUTER USAGE TIME, AND DAMAGE OR LOSS OF USE OF DATA), EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND IRRESPECTIVE OF ANY NEGLIGENCE OF BMC OR WHETHER SUCH DAMAGES RESULT FROM A CLAIM ARISING UNDER TORT OR CONTRACT LAW. LIMITS ON LIABILITY. BMCS AGGREGATE LIABILITY FOR DAMAGES IS LIMITED TO THE AMOUNT PAID BY YOU FOR THE LICENSE TO THE PRODUCT. SUPPORT. If Your order includes support for the Software, then BMC agrees to provide support (24 hours a day/7 days a week) (Support). You will be automatically re-enrolled in Support on an annual basis unless BMC receives notice of termination from You as provided below. There is a free support period during the one year warranty period. (a) Support Terms. BMC agrees to make commercially reasonable efforts to provide the following Support: (i) For malfunctions of supported versions of the Software, BMC provides bug fixes, patches or workarounds in order to cause that copy of the Software to operate in substantial conformity with its then-current operating specifications; and (ii) BMC provides new releases or versions, so long as such new releases or versions are furnished by BMC to all other enrolled Support customers without additional charge. BMC may refuse to provide Support for any versions or releases of the Software other than the most recent version or release of such Software made available by BMC. Either party may terminate Your enrollment in Support upon providing notice to the other at least 30 days prior to the next applicable Support anniversary date. If You re-enroll in Support, BMC may charge You a reinstatement fee of 1.5 times what You would have paid if You were enrolled in Support during that time period. (b) Fees. The annual fee for Support is 20% of the Softwares list price less the applicable discount or a flat capacity based annual fee. BMC may change its prices for the Software and/or Support upon at least 30 days notice prior to Your support anniversary date.
VERIFICATION. If requested by BMC, You agree to deliver to BMC periodic written reports, whether generated manually or electronically, detailing Your use of the Software in accordance with this Agreement, including, without limitation, the License Capacity. BMC may, at its expense, perform an audit, at your facilities, of Your use of the Software to confirm Your compliance with the Agreement. If an audit reveals that You have underpaid fees, You agree to pay such underpaid fees. If the underpaid fees exceed 5% of the fees paid, then You agree to also pay BMCs reasonable costs of conducting the audit. EXPORT CONTROLS. You agree not to import, export, re-export, or transfer, directly or indirectly, any part of the Product or any underlying information or technology except in full compliance with all United States, foreign and other applicable laws and regulations. GOVERNING LAW. This Agreement is governed by the substantive laws in force, without regard to conflict of laws principles: (a) in the State of New York, if you acquired the License in the United States, Puerto Rico, or any country in Central or South America; (b) in the Province of Ontario, if you acquired the License in Canada (subsections (a) and (b) collectively referred to as the Americas Region); (c) in Singapore, if you acquired the License in Japan, South Korea, Peoples Republic of China, Special Administrative Region of Hong Kong, Republic of China, Philippines, Indonesia, Malaysia, Singapore, India, Australia, New Zealand, or Thailand (collectively, Asia Pacific Region); or (d) in the Netherlands, if you acquired the License in any other country not described above. The United Nations Convention on Contracts for the International Sale of Goods is specifically disclaimed in its entirety. ARBITRATION. ANY DISPUTE BETWEEN YOU AND BMC ARISING OUT OF THIS AGREEMENT OR THE BREACH OR ALLEGED BREACH, SHALL BE DETERMINED BY BINDING ARBITRATION CONDUCTED IN ENGLISH. IF THE DISPUTE IS INITIATED IN THE AMERICAS REGION, THE ARBITRATION SHALL BE HELD IN NEW YORK, U.S.A., UNDER THE CURRENT COMMERCIAL OR INTERNATIONAL, AS APPLICABLE, RULES OF THE AMERICAN ARBITRATION ASSOCIATION. IF THE DISPUTE IS INITIATED IN A COUNTRY IN THE ASIA PACIFIC REGION, THE ARBITRATION SHALL BE HELD IN SINGAPORE, SINGAPORE UNDER THE CURRENT UNCITRAL ARBITRATION RULES. IF THE DISPUTE IS INITIATED IN A COUNTRY OUTSIDE OF THE AMERICAS REGION OR ASIA PACIFIC REGION, THE ARBITRATION SHALL BE HELD IN AMSTERDAM, NETHERLANDS UNDER THE CURRENT UNCITRAL ARBITRATION RULES. THE COSTS OF THE ARBITRATION SHALL BE BORNE EQUALLY PENDING THE ARBITRATORS AWARD. THE AWARD RENDERED SHALL BE FINAL AND BINDING UPON THE PARTIES AND SHALL NOT BE SUBJECT TO APPEAL TO ANY COURT, AND MAY BE ENFORCED IN ANY COURT OF COMPETENT JURISDICTION. NOTHING IN THIS AGREEMENT SHALL BE DEEMED AS PREVENTING EITHER PARTY FROM SEEKING INJUNCTIVE RELIEF FROM ANY COURT HAVING JURISDICTION OVER THE PARTIES AND THE SUBJECT MATTER OF THE DISPUTE AS NECESSARY TO PROTECT EITHER PARTYS CONFIDENTIAL INFORMATION, OWNERSHIP, OR ANY OTHER PROPRIETARY RIGHTS. ALL ARBITRATION PROCEEDINGS SHALL BE CONDUCTED IN CONFIDENCE, AND THE PARTY PREVAILING IN ARBITRATION SHALL BE ENTITLED TO RECOVER ITS REASONABLE ATTORNEYS FEES AND NECESSARY COSTS INCURRED RELATED THERETO FROM THE OTHER PARTY. U.S. GOVERNMENT RESTRICTED RIGHTS. The Software under this Agreement is commercial computer software as that term is described in 48 C.F.R. 252.227-7014(a)(1). If acquired by or on behalf of a civilian agency, the U.S. Government acquires this commercial computer software and/or commercial computer software documentation subject to the terms of this Agreement as specified in 48 C.F.R. 12.212 (Computer Software) and 12.211 (Technical Data) of the Federal Acquisition Regulations (FAR) and its successors. If acquired by or on behalf of any agency within the Department of Defense (DOD), the U.S. Government acquires this commercial computer software and/or commercial computer software documentation subject to the terms of this Agreement as specified in 48 C.F.R. 227.7202 of the DOD FAR Supplement and its successors. MISCELLANEOUS TERMS. You agree to pay BMC all amounts owed no later than 30 days from the date of the applicable invoice, unless otherwise provided on the order for the License to the Products. You will pay, or reimburse BMC, for taxes of any kind, including sales, use, duty, tariffs, customs, withholding, property, value-added (VAT), and other similar federal, state or local taxes (other than taxes based on BMCs net income) imposed in connection with the Product and/or the Support. This Agreement constitutes the entire agreement between You and BMC and supersedes any prior or contemporaneous negotiations or agreements, whether oral, written or displayed electronically, concerning the Product and related subject matter. No modification or waiver of any provision hereof will be effective unless made in a writing signed by both BMC and You. You may not assign or transfer this Agreement or a License to a third party without BMCs prior written consent. Should any provision of this Agreement be invalid or unenforceable, the remainder of the provisions will remain in effect. The parties have agreed that this Agreement and the documents related thereto be drawn up in the English language. Les parties exigent que la prsente convention ainsi que les documents qui sy rattachent soient rdigs en anglais.
Notes