Table Of Contents
Writing Embedded Event Manager Policies Using Tcl
Prerequisites for Writing Embedded Event Manager Policies Using Tcl
Information About Writing Embedded Event Manager Policies Using Tcl
EEM Event Detectors Available by Cisco IOS Release
EEM Actions Available by Cisco IOS Release
EEM Policy Tcl Command Extension Categories
General Flow of EEM Event Detection and Recovery
Cisco File Naming Convention for EEM
How to Write Embedded Event Manager Policies Using Tcl
Registering and Defining an EEM Tcl Script
Displaying EEM Registered Policies
Suspending EEM Policy Execution
Modifying History Table Size and Displaying EEM History Data
Displaying Software Modularity Process Reliability Metrics Using EEM
Modifying the Sample EEM Policies
Programming EEM Policies with Tcl
Tcl Policy Structure and Requirements
EEM Policies and Cisco Error Number
Creating an EEM User Tcl Library Index
Creating an EEM User Tcl Package Index
Configuration Examples for Writing Embedded Event Manager Policies Using Tcl
Assigning a Username for a Tcl Session: Example
EEM Event Detector Demo: Example
Programming Policies with Tcl: Sample Scripts Example
Debugging Embedded Event Manager Policies: Examples
Tracing Tcl set Command Operations: Example
EEM Policy Tcl Command Extension Reference
EEM Event Registration Tcl Command Extensions
event_register_timer_subscriber
EEM Event Information Tcl Command Extension
EEM Event Publish Tcl Command Extension
EEM Action Tcl Command Extensions
EEM Utility Tcl Command Extensions
EEM System Information Tcl Command Extensions
EEM Library Debug Command Extensions
SMTP Library Command Extensions
CLI Library Command Extensions
Tcl Context Library Command Extensions
Feature Information for Writing Embedded Event Manager Policies Using Tcl
Writing Embedded Event Manager Policies Using Tcl
First Published: October 31, 2005Last Updated: February 28, 2007This module describes how software developers can write and customize Embedded Event Manager (EEM) policies using Tool command language (Tcl) scripts to handle Cisco IOS software faults and events. EEM is a policy-driven process by means of which faults in the Cisco IOS software system are reported through a defined application programing interface (API). The EEM policy engine receives notifications when faults and other events occur. EEM policies implement recovery on the basis of 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.
Finding Feature Information in This Module
Your Cisco IOS software release may not support all of the features documented in this module. To reach links to specific feature documentation in this module and to see a list of the releases in which each feature is supported, use the "Feature Information for Writing Embedded Event Manager Policies Using Tcl" section.
Finding Support Information for Platforms and Cisco IOS and Catalyst OS Software Images
Use Cisco Feature Navigator to find information about platform support and Cisco IOS and Catalyst OS software image support. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn. An account on Cisco.com is not required.
Contents
•
Prerequisites for Writing Embedded Event Manager Policies Using Tcl
•
•
•
•
•
Prerequisites for Writing Embedded Event Manager Policies Using Tcl
•
•
Information About Writing Embedded Event Manager Policies Using Tcl
To write EEM policies using Tcl, you should understand the following concepts:
•
•
•
•
•
EEM 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 command-line interface (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 the applet. If no event is specified, the applet is not considered registered. When no action is associated with the 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 within an applet are uniquely identified using the label argument, which can be any string value. Actions are sorted within an applet in ascending alphanumeric key sequence using the label argument as the sort key, and they are run using this sequence. The same label argument can be used in different applets; the labels must be unique only within one applet.
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.
For more details about writing EEM policies using the Cisco IOS CLI, see the "Writing Embedded Event Manager Policies Using the Cisco IOS CLI" module.
EEM Script
All Embedded Event Manager scripts are written in Tcl. Tcl is a string-based command language that is interpreted at run time. The version of Tcl supported is Tcl version 8.3.4 plus added script support. Scripts are defined using an ASCII editor on another device, not on the networking device. The script is then copied to the networking device and registered with EEM. Tcl scripts are supported by EEM. As an enforced rule, Embedded Event Manager policies are short-lived run time routines that must be interpreted and executed in less than 20 seconds of elapsed time. If more than 20 seconds of elapsed time are required, the maxrun parameter may be specified in the event_register statement to specify any desired value.
EEM policies use the full range of the Tcl language's capabilities. However, Cisco provides enhancements to the Tcl language in the form of Tcl command extensions that facilitate the writing of EEM policies. The main categories of Tcl command extensions identify the detected event, the subsequent action, utility information, counter values, and system information.
EEM allows you to write and implement your own policies using Tcl. Writing an EEM script involves:
•
•
•
EEM Event Detectors Available by Cisco IOS Release
EEM uses software programs known as event detectors to determine when an EEM event occurs. Some event detectors are available in every Cisco IOS release, but most event detectors have been introduced in a specific release. Use Table 1 to determine which event detectors are available in your specific Cisco IOS release. A blank entry (—) indicates that the event detector is not available; the text "Yes" indicates that the event detector is available. The event detectors shown in Table 1 are supported in later releases of the same Cisco IOS release train. For more details on each event detector, see the Event Detectors concept in the "Embedded Event Manager Overview" module.
EEM Actions Available by Cisco IOS Release
The CLI-based corrective actions that are taken when event detectors report events enable a powerful on-device event management mechanism. Some actions are available in every Cisco IOS release, but most actions have been introduced in a specific release. Use Table 2 to determine which actions are available in your specific Cisco IOS release. A blank entry (—) indicates that the action is not available; the text "Yes" indicates that the action is available. The actions shown in Table 2 are supported in later releases of the same Cisco IOS release train. For more details on each action, see the Embedded Event Actions concept in the "Embedded Event Manager Overview" module.
EEM Policy Tcl Command Extension Categories
There are different categories of EEM policy Tcl command extensions.
Note
General Flow of EEM Event Detection and Recovery
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, the 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.
When an event or fault is detected, Embedded Event Manager determines from the event publishers—an example would be the OIR events publisher in Figure 1—if a registration for the encountered fault or event has occurred. EEM matches the event registration information with the event data itself. A policy registers for the detected event with the Tcl command extension event_register_xxx. The event information Tcl command extension event_reqinfo is used in the policy to query the Embedded Event Manager for information about the detected event.
Figure 1 Embedded Event Manager Core Event Detectors
Safe-Tcl
Safe-Tcl is a safety mechanism that allows untrusted Tcl scripts to run in an interpreter that was created in the safe mode. The safe interpreter has a restricted set of commands that prevent accessing some system resources and harming the host and other applications. For example, it does not allow commands to access critical Cisco IOS file system directories.
Cisco-defined scripts run in full Tcl mode, but user-defined scripts run in Safe-Tcl mode. Safe-Tcl allows Cisco to disable or customize individual Tcl commands. For more details about Tcl commands, go to http://www.tcl.tk/man/.
The following list of Tcl commands are restricted with a few exceptions. Restrictions are noted against each command or command keyword:
•
•
•
•
•
–
–
–
–
–
–
–
–
–
–
•
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
•
•
•
•
•
•
Cisco File Naming Convention for EEM
All Embedded Event Manager policy names, policy support files (for example, e-mail template files), and library filenames are consistent with the Cisco file naming convention. In this regard, Embedded Event Manager policy filenames adhere to the following specification:
•
•
•
Embedded Event Manager e-mail template files consist of a filename prefix of email_template, followed by an abbreviation that identifies the usage of the e-mail template.
Embedded Event Manager library filenames consist of a filename body part containing the descriptive field that identifies the usage of the library, followed by _lib, and a filename suffix part defined as .tcl.
How to Write Embedded Event Manager Policies Using Tcl
This section contains the following tasks:
•
•
•
•
•
•
•
•
•
Registering and Defining an EEM 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.
Prerequisites
You must have a policy available that is written in the Tcl scripting language. Sample policies are provided—see the details in the "Sample EEM Policies" section to see which policies are available for the Cisco IOS release image that you are using—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 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 shutDisplaying EEM 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 Trap Time Registered Name1 system timer cron Off Wed May11 01:43:18 2005 tm_cli_cmd.tclname {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}nice 0 priority normal maxrun 2402 system syslog Off Wed May11 01:43:28 2005 sl_intf_down.tcloccurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}nice 0 priority normal maxrun 903 system proc abort Off Wed May11 01:43:38 2005 pr_cdp_abort.tclinstance 1 path {cdp2.iosproc}nice 0 priority normal maxrun 20Use 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 Trap Time Registered Name1 system proc abort Off Wed May11 01:43:38 2005 pr_cdp_abort.tclinstance 1 path {cdp2.iosproc}nice 0 priority normal maxrun 202 system syslog Off Wed May11 01:43:28 2005 sl_intf_down.tcloccurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}nice 0 priority normal maxrun 903 system timer cron Off Wed May11 01:43:18 2005 tm_cli_cmd.tclname {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}nice 0 priority normal maxrun 240Use 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 system syslog Wed May11 01:43:28 2005 sl_intf_down.tcloccurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}nice 0 priority normal maxrun 90
Unregistering EEM 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] [detailed policy-filename]
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 has been 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 Tue Oct11 01:43:18 2005 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 Tue Oct11 01:43:28 2005 sl_intf_down.tcloccurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}nice 0 priority normal maxrun 90.0003 system proc abort Off Tue Oct11 01:43:38 2005 pr_cdp_abort.tclinstance 1 path {cdp2.iosproc}nice 0 priority normal maxrun 20.000After the current policies are displayed, it is decided to delete the pr_cdp_abort.tcl policy using the no form of the event manager policy command:
Router# configure terminalRouter(config)# no event manager policy pr_cdp_abort.tclRouter(config)# exitThe show event manager policy registered privileged EXEC command is entered again to display the EEM policies that are currently registered. The policy pr_cdp_abort.tcl is no longer registered.
Router# show event manager policy registeredNo. Type Event Type Trap Time Registered Name1 system timer cron Off Tue Oct11 01:45:17 2005 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 Tue Oct11 01:45:27 2005 sl_intf_down.tcloccurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}nice 0 priority normal maxrun 90.000Suspending EEM Policy Execution
Perform this task to immediately suspend the execution of all EEM policies. Suspending policies, instead of unregistering them, 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.000The event manager scheduler suspend command is entered to immediately suspend the execution of all EEM policies:
Router# configure terminalRouter(config)# event manager scheduler suspend*Nov 2 15:34:39.000: %HA_EM-6-FMS_POLICY_EXEC: fh_io_msg: Policy execution has been suspendedManaging EEM Policies
Perform this task to specify a directory to use for storing user library files or user-defined EEM policies.
Note
SUMMARY STEPS
1.
2.
3.
4.
5.
DETAILED STEPS
Examples
In the following example, the show event manager directory user privileged EXEC command is used to display the directory, if it exists, to use for storing EEM user library files:
Router# show event manager directory user librarydisk0:/usr/lib/tclModifying 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
Use this command to change the size of the EEM event history table or the size of the EEM SNMP trap history table. In the following example, the size of the EEM event history table is changed to 30 entries:
Router(config)# event manager history size events 30Step 4
Exits global configuration mode and returns to privileged EXEC mode.
Router(config)# exitStep 5
Use this command to display information about each EEM event that has been triggered.
Router# show event manager history eventsNo. Time of Event Event Type Name1 Fri Sep 9 13:48:40 2005 syslog applet: one2 Fri Sep 9 13:48:40 2005 syslog applet: two3 Fri Sep 9 13:48:40 2005 syslog applet: three4 Fri Sep 9 13:50:00 2005 timer cron script: tm_cli_cmd.tcl5 Fri Sep 9 13:51:00 2005 timer cron script: tm_cli_cmd.tclStep 6
Use this command to display the EEM SNMP traps that have been sent either from the EEM server or from an EEM policy.
Router# show event manager history trapsNo. Time Trap Type Name1 Fri Sep 9 13:48:40 2005 server applet: four2 Fri Sep 9 13:57:03 2005 policy script: no_snmp_test.tcl
Displaying Software Modularity Process Reliability Metrics Using EEM
Perform this optional task to display reliability metrics for Cisco IOS Software Modularity processes. The show event manager metric processes command was introduced in Cisco IOS Release 12.2(18)SXF4 and later releases and is supported only in Software Modularity images.
SUMMARY STEPS
1.
