Downloads |
Table Of Contents
Prerequisites for Embedded Event Manager 2.1
Information About Embedded Event Manager 2.1
Embedded Event Manager Actions
Embedded Event Manager Environment Variables
Embedded Event Manager Policies
How to Configure Embedded Event Manager 2.1
Registering and Defining an Embedded Event Manager Applet
Registering and Defining an Embedded Event Manager Policy to Run Manually
Displaying Embedded Event Manager Registered Policies
Unregistering Embedded Event Manager Policies
Suspending Embedded Event Manager Policy Execution
Modifying History Table Size and Displaying EEM History Data
Configuration Examples for Embedded Event Manager 2.1
Embedded Event Manager Applet Configuration: Examples
Embedded Event Manager Manual Policy Execution: Examples
Embedded Event Manager Watchdog System Monitor Event Detector Configuration: Example
event manager scheduler suspend
event manager scheduler script
event manager session cli username
show event manager directory user
show event manager environment
show event manager history events
show event manager history traps
show event manager policy available
show event manager policy pending
show event manager policy registered
show event manager session cli username
Embedded Event Manager 2.1
Embedded Event Manager (EEM) is a distributed 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, corrective, or any desired 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.1 introduces some new event detectors and actions, some new functionality to allow EEM policies to be run manually, and the ability to run multiple concurrent policies. Support for Simple Network Management Protocol (SNMP) event detector rate-based events is provided as is the ability to create policies using Tool Command Language (Tcl).
History for the Embedded Event Manager 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.1
•
•
•
Prerequisites for Embedded Event Manager 2.1
•
•
•
Information About Embedded Event Manager 2.1
To configure Embedded Event Manager, 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 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 server 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 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 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 mode 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. 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. When you exit applet configuration mode, the old applet is unregistered and the new version is registered.
The 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 they 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 writing EEM policies using Tcl, see the "Writing Embedded Event Manager Policies Using Tcl" module.
Embedded Event Manager 2.1
EEM 2.1 is supported in Cisco IOS Release 12.3(14)T and 12.2(28)SB and later releases, and introduced some new features. EEM 2.1 introduces the following new event detectors:
•
•
•
EEM 2.1 introduces the following actions:
•
•
•
•
EEM 2.1 also permits multiple concurrent policies to be run using the new event manager scheduler script command. Support for Simple Network Management Protocol (SNMP) event detector rate-based events is provided as is the ability to create policies using Tool Command Language (Tcl).
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.1 contains the following event detectors.
Application-Specific Event Detector
The application-specific event detector allows any Embedded Event Manager policy to publish an event. When an EEM policy publishes an event it must use an EEM subsystem number of 798 with any event type. If an existing policy is registered for subsystem 798 and a specified event type, a second policy of the same event type will trigger the first policy to run when the specified event is published.
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.
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 be 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.
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.1 supports the following actions:
•
•
•
•
•
•
•
•
•
•
•
Embedded Event Manager Environment Variables
EEM allows environment variables to be used in EEM policies (applets and scripts). Tool Command Language (Tcl) permits global variables—called environment variables—to be defined for use within an EEM policy. There are three different types of environment variables associated with Embedded Event Manager:
•
•
•
Cisco-defined environment variables (see Table 1) 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 Tcl 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.
Cisco built-in environment variables (see Table 2) are a subset of the Cisco-defined environment variables and the built-in variables are available to EEM applets only. The built-in variables can be read-only or can be read and write, and these variables may apply to one specific event detector or to all event detectors.
Note
Table 1 describes the Cisco-defined variables used in the sample EEM policies. Some of the environment variables do not have to be specified for the corresponding sample policy to run and these are marked as optional.
Table 2 describes the Cisco built-in environment variables.
Embedded Event Manager Policies
EEM is a policy driven process in which the EEM policy engine receives notifications when faults and other events occur in the Cisco IOS software system. Embedded Event Manager policies implement recovery based on the current state of the system and the actions specified in the policy for a given event. Recovery actions are triggered when the policy is run.
Although there are some EEM CLI configuration and show commands, EEM is implemented through the creation of policies. 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.
The creation of an EEM policy involves:
•
•
•
•
There are two ways to create an EEM policy. The first method is to write applets using CLI commands, and the second method is to write Tcl scripts. Cisco provides enhancements to Tcl in the form of Tcl command extensions that facilitate the development of EEM policies. Scripts are defined off the networking device using an ASCII editor. The script is then copied to the networking device and registered with EEM. When a policy is registered with the Embedded Event Manager, the software examines the policy and registers it to be run when the specified event occurs. Policies can be unregistered or suspended. Both types of policies can be used to implement EEM in your network.
For details on writing EEM policies using the Cisco IOS CLI, see the "How to Configure Embedded Event Manager 2.1" section.
For details on writing EEM policies using Tcl and running the sample policies, see the "Writing Embedded Event Manager Policies Using Tcl" module.
How to Configure Embedded Event Manager 2.1
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 the Cisco IOS CLI 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.
The SNMP event detector and the syslog action commands used in this task are just representing any event detector and action commands. For examples using other event detectors and action commands, see the "Embedded Event Manager Applet Configuration: Examples" section.
Note
EEM Environment Variables
EEM environment variables for EEM policies are defined using the EEM event manager environment configuration command. By convention, all Cisco EEM environment variables begin with "_". In order to avoid future conflict, customers are urged not to define new variables that start with "_".
You can display the EEM environment variables set on your system by using the show event manager environment privileged EXEC command.
For example, you can create EEM policies that can send e-mails when an event occurs. Table 3 describes the e-mail-specific environment variables that can be used in EEM policies.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
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 _email_to engineering@yourdomain.com
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 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 7
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 8
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 9
Repeat Step 8.
Example:Router(config-applet)# action 2.0 force-switchover
(Optional) Repeat Step 8 to add other action CLI commands to the applet.
Step 10
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 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 be manually triggered. To run the policy, use either the action policy command in applet configuration mode or the event manager run command in privileged EXEC 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: Examples" section.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
7.
DETAILED STEPS
Displaying Embedded Event Manager Registered Policies
Perform this optional task to display EEM registered policies.
SUMMARY STEPS
1.
2.
DETAILED STEPS
Step 1
Enables privileged EXEC mode. Enter your password if prompted.
Router> enableStep 2
Use this command with the time-ordered keyword to display information about currently registered policies sorted by time, for example:
Router# show event manager policy registered time-orderedNo. Type Event Type Time Registered Name1 applet snmp Thu May30 05:57:16 2004 memory-failoid {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 10action 1.0 syslog priority critical msg Memory exhausted; current available memory is $_snmp_oid_val bytesaction 2.0 force-switchover2 applet syslog Wed Jul16 00:05:17 2004 intf-downpattern {.*UPDOWN.*Ethernet1/0.*}action 1.0 cns-event msg Interface state change: $_syslog_msgUse this command with the name-ordered keyword to display information about currently registered policies sorted by name, for example:
Router# show event manager policy registered name-orderedNo. Type Event Type Time Registered Name1 applet syslog Wed Jul16 00:05:17 2004 intf-downpattern {.*UPDOWN.*Ethernet1/0.*}action 1.0 cns-event msg Interface state change: $_syslog_msg2 applet snmp Thu May30 05:57:16 2004 memory-failoid {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 10action 1.0 syslog priority critical msg Memory exhausted; current available memory is $_snmp_oid_val bytesaction 2.0 force-switchoverUse this command with the event-type keyword to display information about currently registered policies for the event type specified in the event-name argument, for example:
Router# show event manager policy registered event-type syslogNo. Type Event Type Time Registered Name1 applet syslog Wed Jul16 00:05:17 2004 intf-downpattern {.*UPDOWN.*Ethernet1/0.*}action 1.0 cns-event msg Interface state change: $_syslog_msg
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 [type {system | user}] [trap]
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 two EEM applets that are currently registered:
Router# show event manager policy registeredNo. Class Type Event Type Trap Time Registered Name1 applet system snmp Off Fri Aug 12 17:42:52 2005 IPSLAping1oid {1.3.6.1.4.1.9.9.42.1.2.9.1.6.4} get-type exact entry-op eq entry-val {1}exit-op eq exit-val {2} poll-interval 5.000action 1.0 syslog priority critical msg "Server IPecho Failed: OID=$_snmp_oid_val"action 1.1 snmp-trap strdata "EEM detected server reachability failure to 10.1.88.9"action 1.2 publish-event sub-system 88000101 type 1 arg1 "10.1.88.9" arg2 "IPSLAEcho"arg3 "fail"action 1.3 counter name _IPSLA1F op inc value 12 applet system snmp Off Thu Sep 15 05:57:16 2005 memory-failoid {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 10action 1.0 syslog priority critical msg Memory exhausted; current available memory is $_snmp_oid_val bytesaction 2.0 force-switchoverIn the following example, the show event manager policy registered privileged EXEC command is used to show that applet IPSLAping1 has been removed after entering the no event manager policy command:
Router# show event manager policy registeredNo. Class Type Event Type Trap Time Registered Name1 applet system snmp Off Thu Sep 15 05:57:16 2005 memory-failoid {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 10action 1.0 syslog priority critical msg Memory exhausted; current available memory is $_snmp_oid_val bytesaction 2.0 force-switchoverSuspending 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.02 system syslog Off Sat Oct11 01:43:28 2003 sl_intf_down.tcloccurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}nice 0 priority normal maxrun 90.0Modifying History Table Size and Displaying EEM History Data
Perform this optional task to change the size of the history tables and to display EEM history data.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
DETAILED STEPS
Step 1
Enables privileged EXEC mode. Enter your password if prompted.
Router> enableStep 2
Enters global configuration mode.
Router# configure terminalStep 3
