Downloads |
Table Of Contents
Prerequisites for Embedded Event Manager 2.2
Information About Embedded Event Manager 2.2
Embedded Event Manager Actions
Embedded Event Manager Environment Variables
Embedded Event Manager Policies
How to Configure Embedded Event Manager 2.2
Registering and Defining an Embedded Event Manager Applet
Registering and Defining an Embedded Event Manager Tcl Script
Registering and Defining an Embedded Event Manager Policy to Run Manually
Unregistering Embedded Event Manager Policies
Suspending Embedded Event Manager Policy Execution
Managing Embedded Event Manager Policies
Configuring and Tracking a Stub Object Using Embedded Event Manager
Displaying Embedded Event Manager History Data
Displaying Embedded Event Manager Registered Policies
Configuration Examples for Embedded Event Manager 2.2
Embedded Event Manager Applet Configuration: Example
Embedded Event Manager Manual Policy Execution: Example
Configuring and Tracking a Stub Object Using Embedded Event Manager: Example
Embedded Event Manager Watchdog System Monitor Event Detector Configuration: Example
EEM Event Detector Demo: Example
EEM Sample Policy Descriptions
Event Manager Environment Variables for the Sample Policies
Registration of Some EEM Policies
Basic Configuration Details for All Sample Policies
Embedded Event Manager 2.2
Embedded Event Manager (EEM) is a distributed, scalable, and customized approach to event detection and recovery offered directly in a Cisco IOS device. EEM offers the ability to monitor events and take informational or corrective action when the monitored events occur or when a threshold is reached. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs.
EEM 2.2 introduces some new event detectors and actions, including enhanced object tracking.
History for the Embedded Event Manager 2.2 Feature
Finding Support Information for Platforms and Cisco IOS Software Images
Use Cisco Feature Navigator to find information about platform support and Cisco IOS software image support. Access Cisco Feature Navigator at http://www.cisco.com/go/fn. You must have an account on Cisco.com. If you do not have an account or have forgotten your username or password, click Cancel at the login dialog box and follow the instructions that appear.
Contents
•
Prerequisites for Embedded Event Manager 2.2
•
•
•
Prerequisites for Embedded Event Manager 2.2
•
•
•
Information About Embedded Event Manager 2.2
To configure Embedded Event Manager 2.2, you should understand the following concepts:
•
•
•
Embedded Event Manager
Event tracking and management has traditionally been performed by devices external to the networking device. Embedded Event Manager (EEM) has been designed to offer event management capability directly in Cisco IOS based devices. The on-device, proactive event management capabilities of EEM are useful because not all event management can be done off router because some problems compromise communication between the router and the external network management device. Capturing the state of the router during such situations can be invaluable in taking immediate recovery actions and gathering information to perform root-cause analysis. Network availability is also improved if automatic recovery actions are performed without the need to fully reboot the routing device.
EEM is a flexible, policy-driven framework that supports in-box monitoring of different components of the system with the help of software agents known as event detectors. Figure 1 shows the relationship between the EEM server, core event publishers (event detectors), and the event subscribers (policies). Basically, event publishers screen events and publish them when there is a match on an event specification that is provided by the event subscriber. Event detectors notify the EEM when an event of interest occurs. The EEM policies that are configured using the Cisco IOS command-line interface (CLI) then implement recovery on the basis of the current state of the system and the actions specified in the policy for the given event.
Figure 1 Embedded Event Manager Core Event Detectors
EEM offers the ability to monitor events and take informational or corrective action when the monitored events occur or when a threshold is reached. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs. There are two types of EEM policies: an applet or a script. An applet is a simple form of policy that is defined within the CLI configuration. A script is a form of policy that is written in Tcl.
Embedded Event Manager 2.2
EEM 2.2 is supported in Cisco IOS Release 12.4(2)T and introduces some new features. EEM 2.2 introduces the following new event detectors:
•
Enhanced object tracking provides complete separation between the objects to be tracked and the action to be taken by a client when a tracked object changes. Thus, several clients such as EEM, Virtual Router Redundancy Protocol (VRRP), or Gateway Load Balancing Protocol (GLBP) can register their interest with the tracking process, track the same object, and each take different action when the object changes. Each tracked object is identified by a unique number that is specified on the tracking command-line interface (CLI). Client processes use this number to track a specific object. The tracking process periodically polls the tracked objects and notes any change of value. The changes in the tracked object are communicated to interested client processes, either immediately or after a specified delay. The object values are reported as either up or down.•
•
EEM 2.2 introduces the following actions:
•
•
Event Detectors
Embedded Event Manager (EEM) uses software programs known as event detectors to determine when an EEM event occurs. Event detectors are separate systems that provide an interface between the agent being monitored, for example Simple Network Management Protocol (SNMP), and the EEM policies where an action can be implemented. EEM 2.2 contains the following event detectors.
Application-Specific Event Detector
The application-specific event detector allows any Embedded Event Manager policy to publish an event.
CLI Event Detector
The CLI event detector screens command-line interface (CLI) commands for a regular expression match. When a match is found, an event is published. The match logic is performed on the fully expanded CLI command after the command is successfully parsed and before it is executed. The CLI event detector supports three publish modes:
•
•
•
Counter Event Detector
The counter event detector publishes an event when a named counter crosses a specified threshold. There are two or more participants that affect counter processing. The counter event detector can modify the counter, and one or more subscribers define the criteria that cause the event to be published. After a counter event has been published, the counter monitoring logic can be reset to start monitoring the counter immediately or it can be reset when a second threshold—called an exit value—is crossed.
Enhanced Object Tracking Event Detector
The enhanced object tracking event detector publishes an event when the status of a tracked object changes. Object tracking was first introduced into the Hot Standby Router Protocol (HSRP) as a simple tracking mechanism that allowed you to track the interface line-protocol state only. If the line-protocol state of the interface went down, the HSRP priority of the router was reduced, allowing another HSRP router with a higher priority to become active.
Object tracking was enhanced to provide complete separation between the objects to be tracked and the action to be taken by a client when a tracked object changes. Thus, several clients such as HSRP, VRRP, or GLBP can register their interest with the tracking process, track the same object, and each take different action when the object changes. Each tracked object is identified by a unique number that is specified on the tracking command-line interface (CLI). Client processes use this number to track a specific object. The tracking process periodically polls the tracked objects and notes any change of value. The changes in the tracked object are communicated to interested client processes, either immediately or after a specified delay. The object values are reported as either up or down.
Enhanced object tracking is now integrated with EEM to allow EEM to report on a status change of a tracked object and to allow enhanced object tracking to track EEM objects. A new type of tracking object—a stub object—is created. The stub object can be manipulated using the existing CLI commands that already allow tracked objects to be manipulated.
Interface Counter Event Detector
The interface counter event detector publishes an event when a generic Cisco IOS interface counter for a specified interface crosses a defined threshold. A threshold can be specified as an absolute value or an incremental value. If the incremental value is set to 50, for example, an event would be published when the interface counter increases by 50.
After an interface counter event has been published, the interface counter monitoring logic is reset using two methods. The interface counter is reset either when a second threshold—called an exit value—is crossed or when an elapsed period of time occurs.
None Event Detector
The none event detector publishes an event when the Cisco IOS event manager run CLI command executes an EEM policy. EEM schedules and runs policies on the basis of an event specification that is contained within the policy itself. An EEM policy must be identified and registered to be permitted to run manually before the event manager run command will execute.
OIR Event Detector
The online insertion and removal (OIR) event detector publishes an event when one of the following hardware insertion or removal events occurs:
•
•
Route Processors (RPs), line cards, or feature cards can be monitored for OIR events.
Resource Event Detector
The resource event detector publishes an event when the Embedded Resource Manager (ERM) reports an event for the specified policy. The ERM infrastructure tracks resource depletion and resource dependencies across processes and within a system to handle various error conditions. The error conditions are handled by providing an equitable sharing of resources between various applications. The ERM framework provides a communication mechanism for resource entities and allows communication between these resource entities from numerous locations. The ERM framework also helps in debugging the CPU and memory-related issues. The ERM monitors system resource usage to better understand scalability needs by allowing you to configure threshold values for resources such as the CPU, buffers, and memory. For more details about ERM, see the "Embedded Resource Manager" chapter of the
Cisco IOS Network Management Configuration Guide, Release 12.4.RF Event Detector
The redundancy framework (RF) event detector publishes an event when one or more RF events occur during synchronization in a dual Route Processor (RP) system. The RF event detector can also detect an event when a dual RP system continuously switches from one RP to another RP (referred to as a ping-pong situation).
SNMP Event Detector
The SNMP event detector allows a standard SNMP MIB object to be monitored and an event to be generated when the object matches specified values or crosses specified thresholds.
Syslog Event Detector
The syslog event detector allows for screening syslog messages for a regular expression pattern match. The selected messages can be further qualified, requiring that a specific number of occurrences be logged within a specified time. A match on a specified event criteria triggers a configured policy action.
Timer Event Detector
The timer event detector publishes events for the following four different types of timers:
•
•
•
•
Watchdog System Monitor Event Detector
The Cisco IOS watchdog system monitor event detector publishes an event when one of the following occurs:
•
•
Two events may be monitored at the same time, and the event publishing criteria can be specified to require one event or both events to cross their specified thresholds.
Embedded Event Manager Actions
The CLI-based corrective actions that are taken when event detectors report events enable a powerful on-device event management mechanism. EEM 2.2 supports the following actions:
•
•
•
•
•
•
•
•
•
•
•
•
•
Embedded Event Manager Environment Variables
Tool Command Language (Tcl) allows global variables to be defined that are known to all procedures within a Tcl script. EEM allows environment variables to be defined using a CLI command, the event manager environment command, for use within an EEM policy. All EEM environment variables are automatically assigned to Tcl global variables before a Tcl script is run. There are three different types of environment variables associated with Embedded Event Manager:
•
•
•
Cisco-defined environment variables (see Table 1) and Cisco system-defined environment variables (see Table 2) may apply to one specific event detector or to all event detectors. Environment variables that are user-defined or defined by Cisco in a sample policy are set using the event manager environment command. Variables that are used in the EEM policy must be defined before you register the policy. A policy contains a section called "Environment Must Define" that can be defined to check that any required environment variables are defined before the policy runs.
Note
Table 1 describes the Cisco-defined variables used in the sample EEM policies.
Table 2 describes the Cisco system-defined environment variables that are read only.
Embedded Event Manager Policies
EEM offers the ability to monitor events and take informational or corrective action when the monitored events occur or reach a threshold. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs. There are two types of EEM policies: an applet or a script. An applet is a simple form of policy that is defined within the CLI configuration. A script is a form of policy that is written in Tool Command Language (Tcl).
EEM Applet
An EEM applet is a concise method for defining event screening criteria and the actions to be taken when that event occurs. In EEM applet configuration mode, three types of configuration statements are supported. The event commands are used to specify the event criteria to trigger the applet to run, the action commands are used to specify an action to perform when the EEM applet is triggered, and the set command is used to set the value of an EEM applet variable. Currently only the _exit_status variable is supported for the set command.
Only one event configuration command is allowed within an applet configuration. When applet configuration submode is exited and no event command is present, a warning is displayed stating that no event is associated with this applet. If no event is specified, this applet is not considered registered and the applet is not displayed. When no action is associated with this applet, events are still triggered but no actions are performed. Multiple action configuration commands are allowed within an applet configuration. Use the show event manager policy registered command to display a list of registered applets.
Before modifying an EEM applet, be aware that the existing applet is not replaced until you exit applet configuration mode. While you are in applet configuration mode modifying the applet, the existing applet may be executing. It is safe to modify the applet without unregistering it, because changes are written to a temporary file. When you exit applet configuration mode, the old applet is unregistered and the new version is registered.
Action configuration commands are uniquely identified using the label argument, which can be any string value. Actions are sorted in ascending alphanumeric key sequence using the label argument as the sort key and are run using this sequence.
The Embedded Event Manager schedules and runs policies on the basis of an event specification that is contained within the policy itself. When applet configuration mode is exited, EEM examines the event and action commands that are entered and registers the applet to be run when a specified event occurs.
EEM Script
Scripts are defined off the networking device using an ASCII editor. The script is then copied to the networking device and registered with EEM. Tcl scripts are supported by EEM.
EEM allows you to write and implement your own policies using Tcl. Writing an EEM policy involves:
•
•
•
Cisco provides enhancements to Tcl in the form of keyword extensions that facilitate the development of EEM policies. The main categories of keywords identify the detected event, the subsequent action, utility information, counter values, and system information. For more details about the EEM event detectors and about creating EEM policies, see the Writing Embedded Event Manager Policies document.
Cisco includes a set of sample policies. You can copy the sample policies to a user directory and then modify the policies, or you can write your own policies. Tcl is currently the only Cisco-supported scripting language for policy creation. Tcl policies can be modified using a text editor such as Emacs. Policies must execute within a defined number of seconds of elapsed time and the time variable can be configured within a policy. The default is currently 20 seconds.
Table 3 describes the sample EEM policies.
The sample policies feature the timer and syslog event detectors. The timer event detector generates the following time-based events:
•
•
•
•
Watchdog timer events occur when a timer counts down to zero and automatically rearm when they reach zero. Countdown timer events occur when a timer counts down to zero without being rearmed. An absolute timer event occurs when an absolute time of day is passed. CRON timer events occur when the CRON string specification matches the current time.
The syslog event detector screens syslog messages using Posix regular expressions. An event can be triggered after one or more occurrences of a message match. An additional modifier can be specified to require that the number of message match occurrences happen within a set period of time in order for an event to be triggered.
For more details about the sample policies, see the "EEM Event Detector Demo: Example" section.
How to Configure Embedded Event Manager 2.2
This section contains the following tasks:
•
•
•
•
•
•
•
•
•
Registering and Defining an Embedded Event Manager Applet
Perform this task to register an applet with Embedded Event Manager and to define the EEM applet using event and action commands. Only one event command is allowed in an EEM applet. Multiple action commands are permitted. If no event and no action commands are specified, the applet is removed when you exit configuration mode.
EEM Policies
EEM offers the ability to monitor events and take informational or corrective action when the monitored events occur or when a threshold is reached. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs. There are two types of EEM policies: an applet or a script. An applet is a simple form of policy that is defined within the CLI configuration. A script is a form of policy that is written in Tcl.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
7.
DETAILED STEPS
Step 1
enable
Example:Router> enable
Enables privileged EXEC mode.
•
Step 2
configure terminal
Example:Router# configure terminal
Enters global configuration mode.
Step 3
event manager applet applet-name
Example:Router(config)# event manager applet memory-fail
Registers the applet with the Embedded Event Manager (EEM) and enters applet configuration mode.
Step 4
event snmp oid oid-value get-type {exact | next} entry-op operator entry-val entry-value [exit-comb {or | and}] [exit-op operator] [exit-val exit-value] [exit-time exit-time-value] poll-interval poll-int-value
Example:Router(config-applet)# event snmp oid 1.3.6.1.4.1.9.9.48.1.1.1.6.1 get-type exact entry-op lt entry-val 5120000 poll-interval 10
Specifies the event criteria that cause the EEM applet to run.
•
•
Step 5
action label syslog [priority priority-level] msg msg-text
Example:Router(config-applet)# action 1.0 syslog priority critical msg "Memory exhausted; current available memory is $_snmp_oid_val bytes"
Specifies the action to be taken when an EEM applet is triggered.
•
•
•
Step 6
Repeat Step 5.
Example:Router(config-applet)# action 2.0 force-switchover
(Optional) Repeat Step 5 to add other action CLI commands to the applet.
Step 7
end
Example:Router(config-applet)# end
Exits applet configuration mode and returns to privileged EXEC mode.
Troubleshooting Tips
Use the debug event manager command in privileged EXEC mode to troubleshoot EEM command operations. Use any debugging command with caution as the volume of generated output can slow or stop the router operations. We recommend that this command be used only under the supervision of a Cisco engineer.
Registering and Defining an Embedded Event Manager Tcl Script
Perform this task to configure environment variables and register an EEM policy. EEM schedules and runs policies on the basis of an event specification that is contained within the policy itself. When an EEM policy is registered, the software examines the policy and registers it to be run when the specified event occurs.
EEM Policies
EEM offers the ability to monitor events and take informational or corrective action when the monitored events occur or when a threshold is reached. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs. There are two types of EEM policies: an applet or a script. An applet is a simple form of policy that is defined within the CLI configuration. A script is a form of policy that is written in Tcl.
Prerequisites
You must have a policy available that is written in the Tcl scripting language. Three sample policies—sl_intf_down.tcl, tm_cli_cmd.tcl, and tm_crash_reporter.tcl—are provided, and these sample policies are stored in the system policy directory.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
7.
DETAILED STEPS
Step 1
enable
Example:Router> enable
Enables privileged EXEC mode.
•
Step 2
show event manager environment [all | variable-name]
Example:Router# show event manager environment all
(Optional) Displays the name and value of EEM environment variables.
•
•
Step 3
configure terminal
Example:Router# configure terminal
Enters global configuration mode.
Step 4
event manager environment variable-name string
Example:Router(config)# event manager environment _cron_entry 0-59/2 0-23/1 * * 0-6
Configures the value of the specified EEM environment variable.
•
Step 5
Repeat Step 4 for all the required environment variables.
Repeat Step 4 to configure all the environment variables required by the policy to be registered in Step 6.
Step 6
event manager policy policy-filename [type {system | user}] [trap]
Example:Router(config)# event manager policy tm_cli_cmd.tcl type system
Registers the EEM policy to be run when the specified event defined within the policy occurs.
•
•
•
Step 7
exit
Example:Router(config)# exit
Exits global configuration mode and returns to privileged EXEC mode.
Examples
In the following example, the show event manager environment privileged EXEC command is used to display the name and value of all EEM environment variables.
Router# show event manager environment allNo. Name Value1 _cron_entry 0-59/2 0-23/1 * * 0-62 _show_cmd show ver3 _syslog_pattern .*UPDOWN.*Ethernet1/0.*4 _config_cmd1 interface Ethernet1/05 _config_cmd2 no shutRegistering and Defining an Embedded Event Manager Policy to Run Manually
There are two ways to manually run an EEM policy. EEM usually schedules and runs policies on the basis of an event specification that is contained within the policy itself. The event none command allows EEM to identify an EEM policy that can either be run manually or be run when an EEM applet is triggered. To run the policy, use either the action policy command in applet configuration mode or the event manager run command in global configuration mode.
Perform this task to register an EEM policy to be run manually using the event manager run command. For an example of how to manually run a policy using the action policy command, see the "Embedded Event Manager Manual Policy Execution: Example" section.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
7.
DETAILED STEPS
Unregistering Embedded Event Manager Policies
Perform this task to remove an EEM policy from the running configuration file. Execution of the policy is canceled.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
DETAILED STEPS
Step 1
enable
Example:Router> enable
Enables privileged EXEC mode.
•
Step 2
show event manager policy registered [event-type event-name] [system | user] [time-ordered | name-ordered]
Example:Router# show event manager policy registered
(Optional) Displays the EEM policies that are currently registered.
•
•
Step 3
configure terminal
Example:Router# configure terminal
Enters global configuration mode.
Step 4
no event manager policy policy-filename
Example:Router(config)# no event manager policy pr_cdp_abort.tcl
Removes the EEM policy from the configuration, causing the policy to be unregistered.
•
Step 5
exit
Example:Router(config)# exit
Exits global configuration mode and returns to privileged EXEC mode.
Step 6
Repeat Step 2 to ensure that the policy is removed.
Example:Router# show event manager policy registered
—
Examples
In the following example, the show event manager policy registered privileged EXEC command is used to display the three EEM policies that are currently registered:
Router# show event manager policy registeredNo. Type Event Type Trap Time Registered Name1 system timer cron Off Sat Oct11 01:43:18 2003 tm_cli_cmd.tclname {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}nice 0 priority normal maxrun 240.0002 system syslog Off Sat Oct11 01:43:28 2003 sl_intf_down.tcloccurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}nice 0 priority normal maxrun 90.0003 system proc abort Off Sat Oct11 01:43:38 2003 pr_cdp_abort.tclinstance 1 path {cdp2.iosproc}nice 0 priority normal maxrun 20.000Suspending Embedded Event Manager Policy Execution
Perform this task to immediately suspend the execution of all EEM policies. Suspending instead of unregistering policies might be necessary for reasons of temporary performance or security.
SUMMARY STEPS
1.
2.
3.
4.
5.
DETAILED STEPS
Examples
In the following example, the show event manager policy registered privileged EXEC command is used to display all the EEM registered policies:
Router# show event manager policy registeredNo. Type Event Type Trap Time Registered Name1 system timer cron Off Sat Oct11 01:43:18 2003 tm_cli_cmd.tclname {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}nice 0 priority normal maxrun 240.0002 system syslog Off Sat Oct11 01:43:28 2003 sl_intf_down.tcloccurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}nice 0 priority normal maxrun 90.0003 system proc abort Off Sat Oct11 01:43:38 2003 pr_cdp_abort.tclinstance 1 path {cdp2.iosproc}nice 0 priority normal maxrun 20.000Managing Embedded Event Manager Policies
Perform this task to define a location in the local file system containing an installed modular Cisco IOS image to run on all the nodes in a system, or on just one specified node.
SUMMARY STEPS
1.
2.
3.
4.
