|
|
This chapter introduces Info Mediators, their key features, and how they are used. It helps you to understand what Info Mediators are, before you start to use them.
This chapter contains the following sections:
An Info Mediator is an application that acquires data from an event source. Info Mediators connect to an event source, detect and acquire events, and then forward them to the Cisco Info Server. They can acquire information from a number of sources, including:
Any stable data source can be used to form the basis of Info Mediator data acquisition.
Figure 1-1 shows how Info Mediators fit into the Cisco Info Center architecture.
Info Mediators are designed to be non-intrusive software agents that are flexible enough to process complex information and to be deployed rapidly. Info Mediator configurations can be developed, deployed, and applied to fit any enterprise architecture, ranging from simple, single Info Mediator configurations, to complex, integrated enterprise-wide configurations. Complex configurations work regardless of geographical location or underlying element management systems. This allows centralized operations and event management of decentralized and distributed environments.
An Info Mediator is made up of three primary components:
Each of these components is described in the following sections.
The executable file is the core of an Info Mediator. It manages the connection to the event source, the acquisition of events, and the forwarding of events to the Cisco Info Server.
All Info Mediator executable files are stored in the $OMNIHOME/probes/solaris2 directory. The following example shows where the Solaris executable for the nco_p_rttrapdInfo Mediator is stored.
$OMNIHOME/probes/solaris2/nco_p_rttrapdThe first thing an Info Mediator executable file does when it is run is to configure its environment. To do this, it reads the contents of the properties and rules files. Using the contents of these files, the executable file can define how it should control the connection between the event source and the Cisco Info Server. Once the rules file is correctly configured, it can read the event source and forward events to the Cisco Info Server.
Note that an Info Mediator may also be configured to run under Process Control.
The Info Mediator properties define the environment in which it works. For example, the Server property defines the server from which the Info Mediator acquires events. All of an Info Mediator's properties are stored in a properties file.
By default, all Info Mediator properties files are stored in the same directory as the executable file, with the extension .props. For example, the properties for the Rttrapd Info Mediator (nco_p_rttrapd) are stored in the file:
$OMNIHOME/probes/solaris2/rttrapd.propsProperties files are formed with name-value pairs, separated by a colon. For example:
Server: "INFOSERVER"
where Server is the name of the property and INFOSERVER is the value the property is set to. The value should be enclosed in double quotes when it is a string value. Other values can be specified without quotes.
Two types of properties are stored in each properties file: generic properties and Info Mediator specific properties. The generic properties are mandatory and are stored (with different values) in every properties file.
For example, the Server property is a generic property, because every Info Mediator needs to know where to acquire events. For more information about generic properties see "Generic Info Mediator Properties."
Info Mediator specific properties are different for each Info Mediator. Some Info Mediators do not have any specific properties, however, others need additional properties which relate to the environment in which they are working. For example, the Ping Info Mediator has a Pingfile property which defines the name of a file containing a list of all the machines to be pinged. For more information about Info Mediator specific properties, see the reference information for that Info Mediator in the following chapters.
You can display a list of all the generic and Info Mediator specific properties and command line options available for use with a specific Info Mediator by using the -help command line option. For example, to display a list of all the properties available for use with the SimNet Info Mediator, specify:
$OMNIHOME/Info Mediators/nco_p_simnet -helpYou can change Info Mediator properties by editing the properties file using a text editor, or by using the properties editor. See the "Editing Info Mediator Properties" section for more information.
Info Mediator properties are normally set in the properties file, but they can also be set on the command line using command line options. A command line option exists for each property. For example, the Server property can be set in a properties file as:
Server: "INFOSERVER"
It can also be set on the command line using the option:
nco_p_<mediatorname> -server STWOwhere <mediatorname> is the name of the Mediator being invoked.
When an Info Mediator has corresponding property and command line options set, the command line option overrides the property stored in the properties file. In the example above, where the command line option is set as STWO and the property is set as INFOSERVER, STWO is used as the server.
You should add as many properties as possible to the properties file rather than using the command line options. You can comment out any unwanted properties in the properties file by adding a hash symbol (#) to the beginning of the line, for example:
# Store_And_Forward: 1
For more information about command line options available for use with all Info Mediators, see "Default Info Mediator Command Line Options." For more information about command line options available for use with specific Info Mediators, see the reference information for that particular Info Mediator in the following chapters.
Not all of the data contained within an event is relevant to the processing of that event. The rules file defines how the Info Mediator should rationalize or add to the contents of an event to create a meaningful Cisco Info Center alert. In addition, the rules file creates a unique identifier for each event it acquires, See the "Identifier Field" section for more information.
By default, all Info Mediator rules files are stored in a subdirectory under the directory that contains the executable file, with the extension .rules. For example:
$OMNIHOME/probes/solaris2/cisco.rulesThe cisco.rules file contains include statements that point to subsidiary rules file that are stored in subdirectories of the $OMNIHOME/probes/solaris2/cisco.includes directory. All the field values of alerts.status are normally propagated by the rules file using the information from the incoming event. It is also possible at this level, to add extra information to the event. For example, you could add the name of the customer the device belongs, the department the device is in, or which applications are running on which machines.
Any changes made to the rules file requires the Info Mediator to be restarted or it must re-read the rules file (this is preferable, because the Info Mediator does not lose events). You can force the Info Mediator to re-read the rules file by issuing a kill -HUP pid command on the Info Mediator process ID (PID). See the ps and kill man pages for more information.
See "Rules File Processing," for more detailed information about rules files and how to create them. For detailed information on the cisco.rules file, refer to the Cisco Rules File Reference. This document is provided on the release CD-ROM and on the Cisco Connection Online (CCO).
The function of an Info Mediator is to acquire information from an event source and then forward it to the Cisco Info Server. When simple rules are defined, all of the data acquired from the event source can be mapped into the fields of a Cisco Info Center alert and forwarded to the Cisco Info Server. Figure 1-2 shows how events would be mapped to the Cisco Info Server with the use of a simple rules file.
Usually, the raw data an Info Mediator acquires contains information that cannot be sent directly to the Cisco Info Server. The rules in the rules file define how the raw data should be processed before it is sent to the Cisco Info Server.
Figure 1-3 shows how Info Mediators process the raw data acquired from the event source using rules.
When the Info Mediator acquires raw data from the event source, it breaks it down into tokens. Each token represents a piece of event data. The Info Mediator then parses these tokens into elements. Elements are identified within the rules file by the "$" symbol. For example, $Node is an element containing the node name of the event source.
The Info Mediator processes the elements according to the rules in the rules file to generate fields. When they have been processed, the fields contain the event details in the form used by the Cisco Info Server. At this stage, the unique @Identifier field is also generated, see the"Identifier Field" section for more information. The Info Mediator then forwards the fields to the Cisco Info Server as a Cisco Info Center alert.
Fields are identified within the rules file by the @ symbol. For example, @Node can be a field containing the node name of the event source. Three ways exist to assign elements to fields:
@Node=$Node.
@Summary=$Summary + $Group.
@Summary=$Node + "has problem" + $Summary.
For more information about manipulating fields and elements, see Chapter 2, "Rules File Processing".
You can assign the value of a property directly to a field. A property is represented by a % symbol in the rules file. For example, you could add the following statement to your rules file:
@Summary = "Server = " + %server
In this example, when the rules file is processed, the Info Mediator searches for a property named %server. When the property is found, its value is assigned to the @Summary field. When the property is not found, a null string is assigned in its place.
 |
Note You cannot assign values to a property in the rules file. |
Elements become details in the alert sent to the Cisco Info Server. The rules file allows you to dynamically create new elements. For example:
$newelem="Here is a new detail field"
When you refer to an element that has not been initialized in this way, the element returns a zero-length string. For example, assuming $a and $b are both uninitialized, you could create a new element $a as follows:
$a=$b
In this example, the element $b does not exist, so $a is set to the string "". In the following example, $b is created and set to setnow:
$b="setnow"
The following example would set $a to setnow:
$a=$b
You can delete these elements using the remove function, see Chapter 2, "Remove" for more information.
This section describes some of the key features of Info Mediator operation.
The identifier field, @Identifier, is the most important field built by the Info Mediator. It is used to uniquely identify an event. This allows the Cisco Info Server to correlate events so repeated events do not appear in the Event List more than once. The Cisco Info Server increments a tally field (@Tally) to identify a repeated event.
The identifier field is constructed from the fields the Info Mediator acquires from the event source according to the rules in the rules file. When the identifier field is too specific (for example, when it contains a time value), the Cisco Info Server is not able to correlate and deduplicate repeated events. However, when the identifier field is not specific enough (for example, when it only contains a node name), the Cisco Info Server correlates and deduplicates all of the events acquired from that node and forwards only one alert to the Cisco Info Server.
The identifier is created in the rules file where it can be changed easily. For example:
@Identifier=@Manager+@Node+@AlertKey+$(trap-type)
This statement creates unique identifier fields by using the manager (@Manager) name, node (@Node) name, alert key (@AlertKey) field, and the trap type (trap-type) element.
It is important to ensure the identifier is unique. For example, the following identifier may not be specific enough, resulting in the deletion of events that are not repeated:
@Identifier=@Manager+@Node
In this example, only one event from any node under that manager is recorded. Any other events from the same manager and node are treated as duplicates. Unless there is a specific reason for doing this, it should be avoided.
The ProbeWatch mechanism is a standardized way in which the Info Mediator can generate events. This mechanism is incorporated into all Info Mediators.
ProbeWatch events are generated to indicate some condition in the Info Mediator (typically, start-up and shutdown messages). The events are passed through the rules processor, allowing them to be modified or discarded as necessary. See "Error Messages," for more information about ProbeWatch events generated by all Info Mediators and to the following chapters for information about ProbeWatch events generated by individual Info Mediators.
Info Mediators can continue to run when the Cisco Info Server is down. When the Info Mediator detects that the Cisco Info Server is not present (usually by a failure to write an alert to the Cisco Info Server), it switches into store mode.
In this mode, the Info Mediator records all of the messages that it would normally send to the Cisco Info Server in a file named:
$OMNIHOME/var/<mediator_name>.<destserver>.storewhere <mediator_name> is the name of the Info Mediator and <destserver> is the name of the server to which the Info Mediator was attempting to send alerts.
When the Info Mediator detects the Cisco Info Server is back on-line, it switches into Forward mode and sends the alert information held in the .store file to the Cisco Info Server. Once all alerts in the .store file have been forwarded, the Info Mediator returns to normal operation.
This functionality is enabled by default, but can be disabled by setting the Store_And_Forward property to 0 (off/false) in the properties file.
|
Note Do not run Info Mediators in store and forward mode when the Cisco Info Server is taken off-line for changes to its database/table definitions. In this case, shut down the Info Mediators. If you do not shut down the Info Mediators, generated alerts are discarded by the Cisco Info Server, because the Cisco Info Server database/table definitions are not synchronized with the alerts from the Info Mediator. |
You can change the generic Info Mediator properties RetryConnectionCount, RetryConnectionTimeout, AutoSAF, and MaxSAFFileSize to control the operation of store and forward mode. See "Generic Info Mediator Properties," for more information about these properties.
Normally, store and forward mode only works when a connection to the Cisco Info Server has been established, used, and then lost. If the Cisco Info Server is not running when the Info Mediator starts, store and forward mode is not triggered and the Info Mediator terminates. You can change this functionality by setting the Info Mediator to run in automatic store and forward mode.
If you set the Info Mediator to run in automatic store and forward mode, it goes straight into store mode when the Cisco Info Server is down, provided the Info Mediator has already been connected to the Cisco Info Server at least once. You can run an Info Mediator in automatic store and forward mode by setting the AutoSAF property or by using the -autosaf command line option.
Raw capture mode allows you to redirect the complete stream of event data, acquired by a Info Mediator, into a file. This can be useful for auditing, recording, and debugging the operation of an Info Mediator.
An Info Mediator running in raw capture mode does not correlate the events it acquires, however, it continues to forward them to the Cisco Info Server where repeated events can be discarded when necessary. Data captured in raw capture mode is in a format that can be replayed by the generic Info Mediator.
A generic Mediator is designed to allow raw data from a platform or hardware to be passed through a configurable Info Mediator to allow for rapid prototyping of new Mediators. The Generic Info Mediator acquires raw data from the UNIX standard input.
Raw capture mode is enabled using the command line option -raw or the Info Mediator property RawCapture.
The Cisco Info Server can be run in secure mode. The -secure option controls the authentication of any Info Mediator or Cisco Info Gateway connection requests with a user name and an encrypted password. The default is unsecure mode. This is set with the -unsecure option.
When a connection request is sent, the Cisco Info Server issues an authentication message. The Info Mediator must respond with the correct user name and password. The user name and password are set in the Info Mediator properties file. When the user name and password are incorrect, the Cisco Info Server issues an error message and rejects the connection.
When you are running a Cisco Info Server in secure mode, you must add two properties to each of the Info Mediators connected to that Cisco Info Server: AuthUserName and AuthPassword. The AuthUserName property should contain a valid user name which is used to identify that Info Mediator. The AuthPassword property should contain a password.
The passwords used in secure mode must be encrypted. You can encrypt them using the nco_crypt utility. To enable an Info Mediator to run in secure mode:
Step 2 Specify a unique name for the Info Mediator as the AuthUserName property value.
Step 3 Create an encrypted password by specifying:
nco_crypt <password>where <password> is the unencrypted form of the password. The nco_crypt utility displays an encrypted version of the password.
Step 4 Copy the encrypted password to the AuthPassword property value.
Step 5 Run the Info Mediator.
Each Info Mediator has a short name that is used to identify the Info Mediator executable and all of its associated files. For example, SunNet Manager, is known as snmlog, HP Network Node Manager is known as nnm, and IBM Netview/6000 is known as nv. This name is used to reference the files. For example, the SunNet Manager Info Mediator has the following files:
The executable: $OMNIHOME/Info Mediators/<arch>/nco_p_snmlog
The properties file: $OMNIHOME/Info Mediators/<arch>/snmlog.prop
The rules file: $OMNIHOME/Info Mediators/<arch>/snmlog.rules
Where <arch> is the name of the architecture the Info Mediator is installed. See the following chapters for more details about specific Info Mediators, their defaults, and which of their properties can be changed.
Note, this section describes how to run an Info Mediator from the command line. It is recommended that you run Info Mediators through the Process Control application once you have tested them. For more information, see Section, "Running Info Mediators Under Process Control", and the Cisco Info Center Administrator Reference guide.
When necessary, once you have installed the Info Mediator, you must configure the properties and rules files to fit your environment. For example, when you are using the HTTP CLF Info Mediator, you must set the -logfile property, so the Info Mediator can connect to the event source. See the "Info Mediator Components" section, for more information about properties and rules.
To run an Info Mediator, enter the following command:
$OMNIHOME/probes/nco_p_<mediator_name>where <mediator_name> is the name of the Info Mediator that you want to run. You can also add optional command line options when you run an Info Mediator. For example, to run the Sybase Info Mediator in raw capture mode, specify:
$OMNIHOME/Info Mediators/nco_p_sybase -raw |
Note If you are running a Proxy Server, you may need to connect your Info Mediators to the Proxy Server rather than to the Cisco Info Server. To do this, use the Server property or the -server command line option and specify the name of the Proxy Server. |
See the "Properties and Command Line Options" section, and "Default Info Mediator Command Line Options," for more information about command line options.
You can test the syntax of a rules file by using the command: nco_p_syntax. This is more efficient than running a real Info Mediator to test whether the syntax of the rules file is correct.
The nco_p_syntax command has the following syntax:
nco_p_syntax -rulesfile /test/rulesfileThe syntax Info Mediator always runs in debug mode. It connects to the Cisco Info Server, tests the rules file, displays any errors to the screen, and then exits. When no errors are displayed, the syntax of the rules file is correct.
The syntax Info Mediator is supported on the Solaris 2 platform.
When making changes to the rules file, adding new rules, or creating lookup tables, it is useful to test the Info Mediator by executing it in debug mode. This shows exactly how an event is being parsed by the Info Mediator and any possible problems with the rules file.
You can set the Info Mediator to run in debug mode in two ways: on the command line or in the properties file. To enable debug mode on the command line, enter the following command:
$OMNIHOME/probes/arch/<mediator_name> -messagelevel DEBUG -messagelog STDOUTAlternatively, enter the following in the properties file:
If you omit the MessageLog option, the debug information is sent to the Info Mediator's log file in the $OMNIHOME/log directory, rather than to the screen.
You can edit Info Mediator properties with a text editor or through the Properties Editor window. The Properties Editor makes it easier for you to edit multiple properties files. You can also be sure any changes you make to a properties file are valid and the file is saved in the correct format, in the correct directory.
You can edit an Info Mediator's properties file while the Info Mediator is running. When you do this, the changes you make are used the next time you start the Info Mediator. For more information about properties, see "The Properties File" section.
To start the Properties Editor, complete these steps:
The Properties Editor window appears, shown in Figure 1-4.
Step 2 Select Info Mediator from the Type options list.
Step 3 Select the Info Mediator you want to change from the File options list.
Step 4 Click on the Open button.
The Properties Editor opens the Info Mediator's properties file and lists its properties and their values. Default properties are displayed in black. When you change a default property, it is displayed in white to show it has been modified.
To change the property values:
Step 2 Edit the value.
Step 3 Click on the Update button.
When you edit the property name, the button label changes to Add button. Click on the Add button to create a new property.
To delete a property from the list:
Step 2 Click on the Remove button.
To save the changed properties, click on the Save button.
Info Mediators should be run under the control of the Cisco Info Center Process Control system. Process control is described in detail in the Cisco Info Center Administrator Reference. Read the process control chapter of the Cisco Info Center Administrator Reference to understand the concept of a service, a process and process dependencies
Posted: Tue Jun 13 17:08:55 PDT 2000
Copyright 1989 - 2000©Cisco Systems Inc.