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 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: Examples
EEM Event Detector Demo: Examples
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_snmp_notification
event_register_timer_subscriber
EEM Event Information Tcl Command Extension
EEM Event Tcl Command Extension
EEM Multiple Event Support Tcl Command Extensions
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: November 20, 2009This 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
Your software release may not support all the features documented in this module. For the latest feature information and caveats, see the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the "Feature Information for Writing Embedded Event Manager Policies Using Tcl" section.
Use Cisco Feature Navigator to find information about platform support and Cisco IOS, Catalyst OS, and Cisco IOS XE 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 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:
•
•
•
•
•
–
–
–
–
–
–
–
–
–
–
•
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
•
•
•
•
•
•
Bytecode Support for EEM 2.4
In Cisco IOS Release 12.4(20)T, EEM 2.4 introduces bytecode language (BCL) support by accepting files with the standard bytecode script extension .tbc. Tcl version 8.3.4 defines a BCL and includes a compiler that translates Tcl scripts into BCL. Valid EEM policy file extensions in EEM 2.4 for user and system policies are .tcl (Tcl Text files) and .tbc (Tcl bytecode files).
Storing Tcl scripts in bytecode improves the execution speed of the policy because the code is precompiled, creates a smaller policy size, and obscures the policy code. Obfuscation makes it a little more difficult to modify scripts and hides logic to preserve intellectual property rights.
Support for bytecode is being added to provide another option for release of supported and trusted code. We recommend that you only run well understood, or trusted and supported software on network devices. To generate Tcl bytecode for IOS EEM support, use TclPro versions 1.4 or 1.5.
To translate a Tcl script to bytecode you can use procomp, part of Free TclPro Compiler, or Active State Tcl Development Kit. When a Tcl script is compiled using procomp, the code is scrambled and a .tbc file is generated. The bytecode files are platform-independent and can be generated on any operating system on which TclPro is available, including Windows, Linux, and UNIX. Procomp is part of TclPro and available from http://www.tcl.tk/software/tclpro.
Registration Substitution
In addition to regular Tcl substitution, EEM 2.3 (in Cisco IOS Releases 12.2(33)SXH and 12.2(33)SB, and later releases) permits the substitution of an individual parameter in an EEM event registration statement line with an environment variable.
EEM 2.4 in Cisco IOS Release 12.4(20)T introduces the ability to replace multiple parameters in event registration statement lines with a single environment variable.
Note
To illustrate the substitution, a single environment variable, $_eem_syslog_statement is configured as:
::cisco::eem::event_register_syslog pattern COUNTUsing the registration substitution, the $_eem_syslog_statement environment variable is used in the following EEM user policy:
$_eem_syslog_statement occurs $_eem_occurs_valaction_syslog "this is test 3"Environment variables must be defined before a policy using them is registered. To define the $_eem_syslog_statement environment variable:
Router(config)# event manager environment eem_syslog_statement ::cisco::eem::event_register_syslog pattern COUNTRouter(config)# event manager environment eem_occurs_val 2Cisco 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.
2.
DETAILED STEPS
Step 1
Enables privileged EXEC mode. Enter your password if prompted.
Router> enableStep 2
Use this command to display the reliability metric data for processes. The system keeps a record of when processes start and end, and this data is used as the basis for reliability analysis. In this partial example, the first and last entries showing the metric data for the processes on all the cards inserted in the system are displayed.
Router# show event manager metric process all=====================================process name: devc-pty, instance: 1sub_system id: 0, version: 00.00.0000--------------------------------last event type: process startrecent start time: Fri Oct10 20:34:40 2005recent normal end time: n/arecent abnormal end time: n/anumber of times started: 1number of times ended normally: 0number of times ended abnormally: 0most recent 10 process start times:--------------------------Fri Oct10 20:34:40 2005--------------------------most recent 10 process end times and types:cumulative process available time: 6 hours 30 minutes 7 seconds 378 millisecondscumulative process unavailable time: 0 hours 0 minutes 0 seconds 0 millisecondsprocess availability: 0.100000000number of abnormal ends within the past 60 minutes (since reload): 0number of abnormal ends within the past 24 hours (since reload): 0number of abnormal ends within the past 30 days (since reload): 0...=====================================process name: cdp2.iosproc, instance: 1sub_system id: 0, version: 00.00.0000--------------------------------last event type: process startrecent start time: Fri Oct10 20:35:02 2005recent normal end time: n/arecent abnormal end time: n/anumber of times started: 1number of times ended normally: 0number of times ended abnormally: 0most recent 10 process start times:--------------------------Fri Oct10 20:35:02 2005--------------------------most recent 10 process end times and types:cumulative process available time: 6 hours 29 minutes 45 seconds 506 millisecondscumulative process unavailable time: 0 hours 0 minutes 0 seconds 0 millisecondsprocess availability: 0.100000000number of abnormal ends within the past 60 minutes (since reload): 0number of abnormal ends within the past 24 hours (since reload): 0number of abnormal ends within the past 30 days (since reload): 0
Troubleshooting Tips
Use the debug event manager command in privileged EXEC mode to troubleshoot EEM command operations. Use any debugging command with caution because the volume of output generated can slow or stop the router operations. We recommend that this command be used only under the supervision of a Cisco engineer.
Modifying the Sample EEM Policies
Perform this task to modify one of the sample policies. Cisco IOS software contains some sample policies in the images that contain the Embedded Event Manager. Developers of EEM policies may modify these policies by customizing the event for which the policy is to be run and the options associated with logging and responding to the event. In addition, developers may select the actions to be implemented when the policy runs.
Sample EEM Policies
Cisco includes a set of sample policies shown in Table 3. 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.
For more details about the sample policies available and how to run them, see the "EEM Event Detector Demo: Examples" section.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
7.
8.
DETAILED STEPS
Step 1
Enables privileged EXEC mode. Enter your password if prompted.
Router> enableStep 2
Displays the actual specified sample policy including details about the environment variables used by the policy and instructions for running the policy. In Cisco IOS 12.2(18)SXF4, the detailed keyword was introduced for the show event manager policy available and the show event manager policy registered commands. In Cisco IOS releases prior to 12.2(18)SXF4, you must copy one of the two Tcl scripts from the configuration examples section in this document (see the "Programming Policies with Tcl: Sample Scripts Example" section). In the following example, details about the sample policy tm_cli_cmd.tcl are displayed on the screen.
Router# show event manager policy available detailed tm_cli_cmd.tclStep 3
Use the edit and copy functions to move the contents from the router to a text editor on another device.
Step 4
Use the text editor to modify the policy as a Tcl script. For file naming conventions, see the "Cisco File Naming Convention for EEM" section.
Step 5
Copy the file to the flash file system on the router—typically disk0:. For more details about copying files, see the "Using the Cisco IOS File System" chapter in the Cisco IOS Configuration Fundamentals Configuration Guide.
Step 6
Enters global configuration mode.
Router# configure terminalStep 7
Specifies a directory to use for storing user library files or user-defined EEM policies. In the following example, the user_library directory on disk0 is specified as the directory for storing user library files.
Router(config)# event manager directory user library disk0:/user_libraryStep 8
Registers the EEM policy to be run when the specified event defined within the policy occurs. In the following example, the new EEM policy named test.tcl is registered as a user-defined policy.
Router(config)# event manager policy test.tcl type user
Programming EEM Policies with Tcl
Perform this task to help you program a policy using Tcl command extensions. We recommend that you copy an existing policy and modify it. There are two required parts that must exist in an EEM Tcl policy: the event_register Tcl command extension and the body. All other sections shown in the "Tcl Policy Structure and Requirements" concept are optional.
Tcl Policy Structure and Requirements
All EEM policies share the same structure, shown in Figure 2. There are two parts of an EEM policy that are required: the event_register Tcl command extension and the body. The remaining parts of the policy are optional: environment must defines, namespace import, entry status, and exit status.
Figure 2 Tcl Policy Structure and Requirements
The start of every policy must describe and register the event to detect using an event_register Tcl command extension. This part of the policy schedules the running of the policy. For a list of the available EEM event_register Tcl command extensions, see the "EEM Event Registration Tcl Command Extensions" section. The following example Tcl code shows how to register the event_register_timer Tcl command extension:
::cisco::eem::event_register_timer cron name crontimer2 cron_entry $_cron_entry maxrun 240The environment must defines section is optional and includes the definition of environment variables. The following example Tcl code shows how to check for, and define, some environment variables.
# Check if all the env variables that we need exist.# If any of them does not exist, print out an error msg and quit.if {![info exists _email_server]} {set result \"Policy cannot be run: variable _email_server has not been set"error $result $errorInfo}if {![info exists _email_from]} {set result \"Policy cannot be run: variable _email_from has not been set"error $result $errorInfo}if {![info exists _email_to]} {set result \"Policy cannot be run: variable _email_to has not been set"error $result $errorInfoThe namespace import section is optional and defines code libraries. The following example Tcl code shows how to configure a namespace import section.
namespace import ::cisco::eem::*namespace import ::cisco::lib::*The body of the policy is a required structure and might contain the following:
•
•
•
•
•
The following example Tcl code shows the code to query an event and log a message as part of the body section.
# Query the event info and log a message.array set arr_einfo [event_reqinfo]if {$_cerrno != 0} {set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]error $result}global timer_type timer_time_secset timer_type $arr_einfo(timer_type)set timer_time_sec $arr_einfo(timer_time_sec)# Log a message.set msg [format "timer event: timer type %s, time expired %s" \$timer_type [clock format $timer_time_sec]]action_syslog priority info msg $msgif {$_cerrno != 0} {set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]error $result}EEM Entry Status
The entry status part of an EEM policy is used to determine if a prior policy has been run for the same event, and to determine the exit status of the prior policy. If the _entry_status variable is defined, a prior policy has already run for this event. The value of the _entry_status variable determines the return code of the prior policy.
Entry status designations may use one of three possible values: 0 (previous policy was successful), Not=0 (previous policy failed), and Undefined (no previous policy was executed).
EEM Exit Status
When a policy finishes running its code, an exit value is set. The exit value is used by the Embedded Event Manager to determine whether or not to apply the default action for this event, if any. A value of zero means do not perform the default action. A value of nonzero means perform the default action. The exit status will be passed to subsequent policies that are run for the same event.
EEM Policies and Cisco Error Number
Some EEM Tcl command extensions set a Cisco Error Number Tcl global variable _cerrno. Whenever _cerrno is set, four other Tcl global variables are derived from _cerrno and are set along with it (_cerr_sub_num, _cerr_sub_err, _cerr_posix_err, and _cerr_str).
For example, the action_syslog command in the example below sets these global variables as a side effect of the command execution:
action_syslog priority warning msg "A sample message generated by action_syslog"if {$_cerrno != 0} {set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]error $result}_cerrno: 32-Bit Error Return Values
The _cerrno set by a command can be represented as a 32-bit integer of the following form:
XYSSSSSSSSSSSSSEEEEEEEEPPPPPPPPPFor example, the following error return value might be returned from an EEM Tcl command extension:
862439AEThis number is interpreted as the following 32-bit value:
10000110001001000011100110101110This 32-bit integer is divided up into the five variables shown in Table 4.
Table 4 _cerrno: 32-Bit Error Return Value Variables
XY
The error class (indicates the severity of the error). This variable corresponds to the first two bits in the 32-bit error return value; 10 in the case above, which indicates CERR_CLASS_WARNING:
See Table 5 for the four possible error class encodings specific to this variable.
SSSSSSSSSSSSSS
The subsystem number that generated the most recent error
(13 bits = 8192 values). This is the next 13 bits of the 32-bit sequence, and its integer value is contained in $_cerr_sub_num.EEEEEEEE
The subsystem specific error number (8 bits = 256 values). This segment is the next 8 bits of the 32-bit sequence, and the string corresponding to this error number is contained in $_cerr_sub_err.
PPPPPPPP
The pass-through POSIX error code (9 bits = 512 values). This represents the last of the 32-bit sequence, and the string corresponding to this error code is contained in $_cerr_posix_err.
Error Class Encodings for XY
The first variable, XY, references the possible error class encodings shown in Table 5.
:
Table 5 Error Class Encodings
00
CERR_CLASS_SUCCESS
01
CERR_CLASS_INFO
10
CERR_CLASS_WARNING
11
CERR_CLASS_FATAL
An error return value of zero means SUCCESS.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
DETAILED STEPS
Step 1
Enables privileged EXEC mode. Enter your password if prompted.
Router> enableStep 2
Displays the actual specified sample policy including details about the environment variables used by the policy and instructions for running the policy. In Cisco IOS 12.2(18)SXF4, the detailed keyword was introduced for the show event manager policy available and the show event manager policy registered commands. In Cisco IOS releases prior to 12.2(18)SXF4, you must copy one of the two Tcl scripts from the configuration examples section in this document (see the "Programming Policies with Tcl: Sample Scripts Example" section). In the following example, details about the sample policy tm_cli_cmd.tcl are displayed on the screen.
Router# show event manager policy available detailed tm_cli_cmd.tclStep 3
Use the edit and copy functions to move the contents from the router to a text editor on another device. Use the text editor to edit the policy as a Tcl script.
Step 4
Choose the appropriate event_register Tcl command extension from Table 6 for the event that you want to detect, and add it to the policy.
Step 5
Policy developers can use the new namespace ::cisco in Tcl policies in order to group all the extensions used by Cisco IOS EEM. There are two namespaces under the ::cisco hierarchy, and Table 7 shows which category of EEM Tcl command extension belongs under each namespace.
Note
Step 6
This is an optional step. Must defines are a section of the policy that tests whether any EEM environment variables that are required by the policy are defined before the recovery actions are taken. The must defines section is not required if the policy does not use any EEM environment variables. EEM environment variables for EEM scripts are Tcl global variables that are defined external to the policy before the policy is run. To define an EEM environment variable, use the Embedded Event Manager configuration command event manager environment CLI command. By convention all Cisco EEM environment variables begin with "_" (an underscore). In order to avoid future conflict, customers are urged not to define new variables that start with "_".
Note
For example, Embedded Event Manager environment variables defined by the sample policies include e-mail variables. The sample policies that send e-mail must have the variables shown in Table 8 set in order to function properly.
Table 8 describes the e-mail-specific environment variables used in the sample EEM policies.
The following example of a must define section shows how to program a check for e-mail-specific environment variables.
Example 1 Example of Must Defines
if {![info exists _email_server]} {set result \"Policy cannot be run: variable _email_server has not been set"error $result $errorInfo}if {![info exists _email_from]} {set result \"Policy cannot be run: variable _email_from has not been set"error $result $errorInfo}if {![info exists _email_to]} {set result \"Policy cannot be run: variable _email_to has not been set"error $result $errorInfo}if {![info exists _email_cc]} {set result \"Policy cannot be run: variable _email_cc has not been set"error $result $errorInfo}Step 7
In this section of the script, you can define any of the following:
•
•
•
•
•
Step 8
If the prior policy is successful, the current policy may or may not require execution. Entry status designations may use one of three possible values: 0 (previous policy was successful), Not=0 (previous policy failed), and Undefined (no previous policy was executed).
Step 9
A value of zero means do not perform the default action. A value of nonzero means perform the default action. The exit status will be passed to subsequent policies that are run for the same event.
Step 10
Some EEM Tcl command extensions set a Cisco Error Number Tcl global variable _cerrno. Whenever _cerrno is set, four other Tcl global variables are derived from _cerrno and are set along with it (_cerr_sub_num, _cerr_sub_err, _cerr_posix_err, and _cerr_str).
For example, the action_syslog command in the example below sets these global variables as a side effect of the command execution:
action_syslog priority warning msg "A sample message generated by action_syslogif {$_cerrno != 0} {set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]error $result}Step 11
Embedded Event Manager policy filenames adhere to the following specification:
•
•
•
For more details, see the "Cisco File Naming Convention for EEM" section.
Copy the file to the flash file system on the router—typically disk0:. For more details about copying files, see the "Using the Cisco IOS File System" chapter in the Cisco IOS Configuration Fundamentals Configuration Guide.
Step 12
Enters global configuration mode.
Router# configure terminalStep 13
Specifies a directory to use for storing user library files or user-defined EEM policies. In the following example, the user_library directory on disk0 is specified as the directory for storing user library files.
Router(config)# event manager directory user library disk0:/user_libraryStep 14
Registers the EEM policy to be run when the specified event defined within the policy occurs. In the following example, the new EEM policy named cl_mytest.tcl is registered as a user-defined policy.
Router(config)# event manager policy cl_mytest.tcl type userStep 15
To test that the policy runs, generate the conditions that will cause the policy to execute and observe that the policy runs as expected.
Step 16
Use the Cisco IOS debug event manager CLI command with its various keywords to debug issues. Refer to the "Troubleshooting Tips" section for details about using Tcl-specific keywords.
Troubleshooting Tips
•
•
•
•
To view examples of the some of these debugging techniques, see the "Debugging Embedded Event Manager Policies: Examples" section.
Creating an EEM User Tcl Library Index
Perform this task to create an index file that contains a directory of all the procedures contained in a library of Tcl files. This task allows you to test library support in EEM Tcl. In this task, a library directory is created to contain the Tcl library files, the files are copied into the directory, and an index tclIndex) is created that contains a directory of all the procedures in the library files. If the index is not created, the Tcl procedures will not be found when an EEM policy is run that references a Tcl procedure.
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
DETAILED STEPS
Step 1
The following example files can be used to create a tclIndex on a workstation running the Tcl shell:
lib1.tcl
proc test1 {} {puts "In procedure test1"}proc test2 {} {puts "In procedure test2"}lib2.tcl
proc test3 {} {puts "In procedure test3"}Step 2
Use this command to enter the Tcl shell.
workstation% tclshStep 3
Use the auto_mkindex command to create the tclIndex file. The tclIndex file that contains a directory of all the procedures contained in the Tcl library files. We recommend that you run auto_mkindex inside a directory because there can only be a single tclIndex file in any directory and you may have other Tcl files to be grouped together. Running auto_mkindex in a directory determines which tcl source file or files are indexed using a specific tclIndex.
workstation% auto_mkindex eem_library *.tclThe following example TclIndex is created when the lib1.tcl and lib2.tcl files are in a library file directory and the auto_mkindex command is run.
tclIndex
# Tcl autoload index file, version 2.0# This file is generated by the "auto_mkindex" command# and sourced to set up indexing information for one or# more commands. Typically each line is a command that# sets an element in the auto_index array, where the# element name is the name of a command and the value is# a script that loads the command.set auto_index(test1) [list source [file join $dir lib1.tcl]]set auto_index(test2) [list source [file join $dir lib1.tcl]]set auto_index(test3) [list source [file join $dir lib2.tcl]]Step 4
Step 5
The directory for storing user-defined EEM policies can be the same directory used in Step 4. The following example user-defined EEM policy can be used to test the Tcl library support in EEM.
libtest.tcl
::cisco::eem::event_register_nonenamespace import ::cisco::eem::*namespace import ::cisco::lib::*global auto_index auto_pathputs [array names auto_index]if { [catch {test1} result]} {puts "calling test1 failed result = $result $auto_path"}if { [catch {test2} result]} {puts "calling test2 failed result = $result $auto_path"}if { [catch {test3} result]} {puts "calling test3 failed result = $result $auto_path"}Step 6
Enables privileged EXEC mode. Enter your password if prompted.
Router> enableStep 7
Enables global configuration mode.
Router# configure terminalStep 8
Use this command to specify the EEM user library directory; this is the directory to which the files in Step 4 were copied.
router(config)# event manager directory user library disk2:/eem_libraryStep 9
Use this command to specify the EEM user policy directory; this is the directory to which the file in Step 5 was copied.
router(config)# event manager directory user policy disk2:/eem_policiesStep 10
Use this command to register a user-defined EEM policy. In this example, the policy named libtest.tcl is registered.
router(config)# event manager policy libtest.tclStep 11
Use this command to manually run an EEM policy. In this example, the policy named libtest.tcl is run to test the Tcl support in EEM. The example output shows that the test for Tcl support in EEM was successful.
router(config)# event manager run libtest.tclThe following output is displayed:01:24:37: %HA_EM-6-LOG: libtest.tcl: In procedure test101:24:37: %HA_EM-6-LOG: libtest.tcl: In procedure test201:24:37: %HA_EM-6-LOG: libtest.tcl: In procedure test3
Creating an EEM User Tcl Package Index
Perform this task to create a Tcl package index file that contains a directory of all the Tcl packages and version information contained in a library of Tcl package files. Tcl packages are supported using the Tcl package keyword, and this support was introduced in Cisco IOS Release 12.4(11)T.
Tcl packages are located in either the EEM system library directory or the EEM user library directory. When a package require Tcl command is executed, the user library directory is searched first for a pkgIndex.tcl file. If the pkgIndex.tcl file is not found in the user directory, the system library directory is searched. In this task, a Tcl package directory—the pkgIndex.tcl file—is created in the appropriate library directory using the pkg_mkIndex command to contain information about all of the Tcl packages contained in the directory along with version information. If the index is not created, the Tcl packages will not be found when an EEM policy is run that contains a package require Tcl command.
Using the Tcl package support in EEM, users can gain access to packages such as XML_RPC for Tcl. When the Tcl package index is created, a Tcl script can easily make an XML-RPC call to an external entity.
Note
SUMMARY STEPS
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
DETAILED STEPS
Step 1
Step 2
Use this command to enter the Tcl shell.
workstation% tclshStep 3
Use the pkg_mkindex command to create the pkgIndex file. The pkgIndex file contains a directory of all the packages contained in the Tcl library files. We recommend that you run pkg_mkindex inside a directory because there can only be a single pkgIndex file in any directory and you may have other Tcl files to be grouped together. Running pkg_mkindex in a directory determines which Tcl package file or files are indexed using a specific pkgIndex.
workstation% pkg_mkindex eem_library *.tclThe following example pkgIndex is created when some Tcl package files are in a library file directory and the pkg_mkindex command is run.
pkgIndex
# Tcl package index file, version 1.1# This file is generated by the "pkg_mkIndex" command# and sourced either when an application starts up or# by a "package unknown" script. It invokes the# "package ifneeded" command to set up package-related# information so that packages will be loaded automatically# in response to "package require" commands. When this# script is sourced, the variable $dir must contain the# full path name of this file's directory.package ifneeded xmlrpc 0.3 [list source [file join $dir xmlrpc.tcl]]Step 4
Step 5
The directory for storing user-defined EEM policies can be the same directory used in Step 4. The following example user-defined EEM policy can be used to test the Tcl package support in EEM.
packagetest.tcl
::cisco::eem::event_register_none maxrun 1000000.000## test if xmlrpc available### Namespace imports#namespace import ::cisco::eem::*namespace import ::cisco::lib::*#package require xmlrpcputs "Did you get an error?"Step 6
Enables privileged EXEC mode. Enter your password if prompted.
Router> enableStep 7
Enables global configuration mode.
Router# configure terminalStep 8
Use this command to specify the EEM user library directory; this is the directory to which the files in Step 4 were copied.
router(config)# event manager directory user library disk2:/eem_libraryStep 9
Use this command to specify the EEM user policy directory; this is the directory to which the file in Step 5 was copied.
router(config)# event manager directory user policy disk2:/eem_policiesStep 10
Use this command to register a user-defined EEM policy. In this example, the policy named packagetest.tcl is registered.
router(config)# event manager policy packagetest.tclStep 11
Use this command to manually run an EEM policy. In this example, the policy named packagetest.tcl is run to test the Tcl package support in EEM.
router(config)# event manager run packagetest.tcl
Configuration Examples for Writing Embedded Event Manager Policies Using Tcl
This section contains the following configuration examples:
•
•
•
•
•
Assigning a Username for a Tcl Session: Examples
The following example shows how to set a username to be associated with a Tcl session. If you are using authentication, authorization, and accounting (AAA) security and implement authorization on a command basis, you should use the event manager session cli username command to set a username to be associated with a Tcl session. The username is used when a Tcl policy executes a CLI command. TACACS+ verifies each CLI command using the username associated with the Tcl session that is running the policy. Commands from Tcl policies are not usually verified because the router must be in privileged EXEC mode to register the policy. In the example, the username is yourname, and this is the username that is used whenever a CLI command session is initiated from within an EEM policy.
configure terminalevent manager session cli username yournameendEEM Event Detector Demo: Examples
This example uses the sample policies to demonstrate how to use Embedded Event Manager policies. Proceed through the following sections to see how to use the sample policies:
•
•
•
•
EEM Sample Policy Descriptions
This configuration example features four of the sample EEM policies:
•
•
•
•
Event Manager Environment Variables for the Sample Policies
Event manager environment variables are Tcl global variables that are defined external to the EEM policy before the policy is registered and run. The sample policies require three of the e-mail environment variables to be set (see Table 8 for a list of the e-mail variables); only _email_cc is optional. Other required and optional variable settings are outlined in the following tables.
Table 9 describes the EEM environment variables that must be set before the sl_intf_down.tcl sample policy is run.
Table 10 describes the EEM environment variables that must be set before the tm_cli_cmd.tcl sample policy is run.
Table 11 describes the EEM environment variables that must be set before the tm_crash_reporter.tcl sample policy is run.
Table 12 describes the EEM environment variables that must be set before the tm_fsys_usage.tcl sample policy is run.
Registration of Some EEM Policies
Some EEM policies must be unregistered and then reregistered if an EEM environment variable is modified after the policy is registered. The event_register_xxx statement that appears at the start of the policy contains some of the EEM environment variables, and this statement is used to establish the conditions under which the policy is run. If the environment variables are modified after the policy has been registered, the conditions may become invalid. To avoid any errors, the policy must be unregistered and then reregistered. The following variables are affected:
•
•
Basic Configuration Details for All Sample Policies
To allow e-mail to be sent from the Embedded Event Manager, the hostname and ip domain-name commands must be configured. The EEM environment variables must also be set. After a Cisco IOS image has been booted, use the following initial configuration, substituting appropriate values for your network. The environment variables for the tm_fsys_usage sample policy (see Table 12) are all optional and are not listed here:
hostname cpuip domain-name example.comevent manager environment _email_server ms.example.netevent manager environment _email_to username@example.netevent manager environment _email_from engineer@example.netevent manager environment _email_cc projectgroup@example.netevent manager environment _cron_entry 0-59/2 0-23/1 * * 0-7event manager environment _show_cmd show event manager policy registeredevent manager environment _syslog_pattern .*UPDOWN.*FastEthernet0/0event manager environment _config_cmd1 interface Ethernet1/0event manager environment _config_cmd2 no shutdownevent manager environment _crash_reporter_debug 1event manager environment _crash_reporter_url http://www.example.com/fm/interface_tm.cgiendUsing the Sample Policies
This section contains the following configuration scenarios to demonstrate how to use the four sample Tcl policies:
•
•
•
•
Running the sl_intf_down.tcl Sample Policy
This sample policy demonstrates the ability to modify the configuration when a syslog message with a specific pattern is logged. The policy gathers detailed information about the event and uses the CLI library to execute the configuration commands specified in the EEM environment variables _config_cmd1 and, optionally, _config_cmd2. An e-mail message is sent with the results of the CLI command.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode, where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the sl_intf_down.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command again to verify that the policy has been registered.
The policy runs when an interface goes down. Enter the show event manager environment command to display the current environment variable values. Unplug the cable (or configure a shutdown) for the interface specified in the _syslog_pattern EEM environment variable. The interface goes down, prompting the syslog daemon to log a syslog message about the interface being down, and the syslog event detector is called.
The syslog event detector reviews the outstanding event specifications and finds a match for interface status change. The EEM server is notified, and the server runs the policy that is registered to handle this event—sl_intf_down.tcl.
enableshow event manager policy registeredshow event manager policy availableconfigure terminalevent manager policy sl_intf_down.tclendshow event manager policy registeredshow event manager environmentRunning the tm_cli_cmd.tcl Sample Policy
This sample policy demonstrates the ability to periodically execute a CLI command and to e-mail the results. The CRON specification "0-59/2 0-23/1 * * 0-7" causes this policy to be run on the second minute of each hour. The policy gathers detailed information about the event and uses the CLI library to execute the configuration commands specified in the EEM environment variable _show_cmd. An e-mail message is sent with the results of the CLI command.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the tm_cli_cmd.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command to verify that the policy has been registered.
The timer event detector triggers an event for this case periodically according to the CRON string set in the EEM environment variable _cron_entry. The EEM server is notified, and the server runs the policy that is registered to handle this event—tm_cli_cmd.tcl.
enableshow event manager policy registeredshow event manager policy availableconfigure terminalevent manager policy tm_cli_cmd.tclendshow event manager policy registeredRunning the tm_crash_reporter.tcl Sample Policy
This sample policy demonstrates the ability to send an HTTP-formatted crash report to a URL location. If the policy registration is saved in the startup configuration file, the policy is triggered 5 seconds after bootup. When triggered, the script attempts to find the reload reason. If the reload reason was due to a crash, the policy searches for the related crashinfo file and sends this information to a URL location specified by the user in the environment variable _crash_reporter_url. A CGI script, interface_tm.cgi, has been created to receive the URL from the tm_crash_reporter.tcl policy and save the crash information in a local database on the target URL machine.
A Perl CGI script, interface_tm.cgi, has been created and is designed to run on a machine that contains an HTTP server and is accessible by the router that runs the tm_crash_reporter.tcl policy. The interface_tm.cgi script parses the data passed into it from tm_crash_reporter.tcl and appends the crash information to a text file, creating a history of all crashes in the system. Additionally, detailed information on each crash is stored in three files in a crash database directory that is specified by the user. Another Perl CGI script, crash_report_display.cgi, has been created to display the information stored in the database created by the interface_tm.cgi script. The crash_report_display.cgi script should be placed on the same machine that contains interface_tm.cgi. The machine should be running a web browser such as Internet Explorer or Netscape. When the crash_report_display.cgi script is run, it displays the crash information in a readable format.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the tm_crash_reporter.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command to verify that the policy has been registered.
enableshow event manager policy registeredshow event manager policy availableconfigure terminalevent manager policy tm_crash_reporter.tclendshow event manager policy registeredRunning the tm_fsys_usage.tcl Sample Policy
This sample policy demonstrates the ability to periodically monitor disk space usage and report through syslog when configurable thresholds have been crossed.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode, where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the tm_fsys_usage.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command again to verify that the policy has been registered. If you had configured any of the optional environment variables that are used in the tm_fsys_usage.tcl policy, the show event manager environment command displays the configured variables.
enableshow event manager policy registeredshow event manager policy availableconfigure terminalevent manager policy tm_fsys_usage.tclendshow event manager policy registeredshow event manager environmentProgramming Policies with Tcl: Sample Scripts Example
This section contains two of the sample policies that are included as EEM system policies. These two policies were introduced in Cisco IOS Release 12.3(14)T and 12.2(18)SXF5 images. For more details about these policies, see the "EEM Event Detector Demo: Examples" section.
•
tm_cli_cmd.tcl Sample Policy
The following sample policy runs a configurable CRON entry. The policy executes a configurable Cisco IOS CLI command and e-mails the results. An optional log file can be defined to which the output is appended with a timestamp.
::cisco::eem::event_register_timer cron name crontimer2 cron_entry $_cron_entry maxrun 240#------------------------------------------------------------------# EEM policy that will periodically execute a cli command and email the# results to a user.## July 2005, Cisco EEM team## Copyright (c) 2005 by cisco Systems, Inc.# All rights reserved.#------------------------------------------------------------------### The following EEM environment variables are used:###### _cron_entry (mandatory) - A CRON specification that determines### when the policy will run. See the### IOS Embedded Event Manager### documentation for more information### on how to specify a cron entry.### Example: _cron_entry 0-59/1 0-23/1 * * 0-7###### _log_file (mandatory without _email_....)### - A filename to append the output to.### If this variable is defined, the### output is appended to the specified### file with a timestamp added.### Example: _log_file disk0:/my_file.log###### _email_server (mandatory without _log_file)### - A Simple Mail Transfer Protocol (SMTP)### mail server used to send e-mail.### Example: _email_server mailserver.example.com###### _email_from (mandatory without _log_file)### - The address from which e-mail is sent.### Example: _email_from devtest@example.com###### _email_to (mandatory without _log_file)### - The address to which e-mail is sent.### Example: _email_to engineering@example.com###### _email_cc (optional) - The address to which the e-mail must### be copied.### Example: _email_cc manager@example.com###### _show_cmd (mandatory) - The CLI command to be executed when### the policy is run.### Example: _show_cmd show version#### check if all required environment variables exist# If any required environment variable does not exist, print out an error msg and quitif {![info exists _log_file]} {if {![info exists _email_server]} {set result \"Policy cannot be run: variable _log_file or _email_server has not been set"error $result $errorInfo}if {![info exists _email_from]} {set result \"Policy cannot be run: variable _log_file or _email_from has not been set"error $result $errorInfo}if {![info exists _email_to]} {set result \"Policy cannot be run: variable _log_file ore _email_to has not been set"error $result $errorInfo}if {![info exists _email_cc]} {#_email_cc is an option, must set to empty string if not set.set _email_cc ""}}if {![info exists _show_cmd]} {set result \"Policy cannot be run: variable _show_cmd has not been set"error $result $errorInfo}namespace import ::cisco::eem::*namespace import ::cisco::lib::*# query the event info and log a messagearray set arr_einfo [event_reqinfo]if {$_cerrno != 0} {set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]error $result}global timer_type timer_time_secset timer_type $arr_einfo(timer_type)set timer_time_sec $arr_einfo(timer_time_sec)# log a messageset msg [format "timer event: timer type %s, time expired %s" \$timer_type [clock format $timer_time_sec]]action_syslog priority info msg $msgif {$_cerrno != 0} {set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]error $result}# 1. execute the commandif [catch {cli_open} result] {error $result $errorInfo} else {array set cli1 $result}if [catch {cli_exec $cli1(fd) "en"} result] {error $result $errorInfo}# save exact execution time for commandset time_now [clock seconds]# execute commandif [catch {cli_exec $cli1(fd) $_show_cmd} result] {error $result $errorInfo} else {set cmd_output $result# format output: remove trailing router promptregexp {\n*(.*\n)([^\n]*)$} $result dummy cmd_output}if [catch {cli_close $cli1(fd) $cli1(tty_id)} result] {error $result $errorInfo}# 2. log the success of the CLI commandset msg [format "Command \"%s\" executed successfully" $_show_cmd]action_syslog priority info msg $msgif {$_cerrno != 0} {set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]error $result}# 3. if _log_file is defined, then attach it to the fileif {[info exists _log_file]} {# attach output to fileif [catch {open $_log_file a+} result] {error $result}set fileD $result# save timestamp of command execution# (Format = 00:53:44 PDT Mon May 02 2005)set time_now [clock format $time_now -format "%T %Z %a %b %d %Y"]puts $fileD "%%% Timestamp = $time_now"puts $fileD $cmd_outputclose $fileD}# 4. if _email_server is defined send the email outif {[info exists _email_server]} {set routername [info hostname]if {[string match "" $routername]} {error "Host name is not configured"}if [catch {smtp_subst [file join $tcl_library email_template_cmd.tm]} \result] {error $result $errorInfo}if [catch {smtp_send_email $result} result] {error $result $errorInfo}}sl_intf_down.tcl Sample Policy
The following sample policy runs when a configurable syslog message is logged. The policy executes a configurable CLI command and e-mails the results.
::cisco::eem::event_register_syslog occurs 1 pattern $_syslog_pattern maxrun 90#------------------------------------------------------------------# EEM policy to monitor for a specified syslog message.# Designed to be used for syslog interface-down messages.# When event is triggered, the given config commands will be run.## July 2005, Cisco EEM team## Copyright (c) 2005 by cisco Systems, Inc.# All rights reserved.#------------------------------------------------------------------### The following EEM environment variables are used:###### _syslog_pattern (mandatory) - A regular expression pattern match string### that is used to compare syslog messages### to determine when policy runs### Example: _syslog_pattern .*UPDOWN.*FastEthernet0/0.*###### _email_server (mandatory) - A Simple Mail Transfer Protocol (SMTP)### mail server used to send e-mail.### Example: _email_server mailserver.example.com###### _email_from (mandatory) - The address from which e-mail is sent.### Example: _email_from devtest@example.com###### _email_to (mandatory) - The address to which e-mail is sent.### Example: _email_to engineering@example.com###### _email_cc (optional) - The address to which the e-mail must### be copied.### Example: _email_cc manager@example.com###### _config_cmd1 (optional) - The first configuration command that### is executed.### Example: _config_cmd1 interface Ethernet1/0###### _config_cmd2 (optional) - The second configuration command that### is executed.### Example: _config_cmd2 no shutdown#### check if all the env variables we need exist# If any of them doesn't exist, print out an error msg and quitif {![info exists _email_server]} {set result \"Policy cannot be run: variable _email_server has not been set"error $result $errorInfo}if {![info exists _email_from]} {set result \"Policy cannot be run: variable _email_from has not been set"error $result $errorInfo}if {![info exists _email_to]} {set result \"Policy cannot be run: variable _email_to has not been set"error $result $errorInfo}if {![info exists _email_cc]} {#_email_cc is an option, must set to empty string if not set.set _email_cc ""}namespace import ::cisco::eem::*namespace import ::cisco::lib::*# 1. query the information of latest triggered eem eventarray set arr_einfo [event_reqinfo]if {$_cerrno != 0} {set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]error $result}set msg $arr_einfo(msg)set config_cmds ""# 2. execute the user-defined config commandsif [catch {cli_open} result] {error $result $errorInfo} else {array set cli1 $result}if [catch {cli_exec $cli1(fd) "en"} result] {error $result $errorInfo}if [catch {cli_exec $cli1(fd) "config t"} result] {error $result $errorInfo}if {[info exists _config_cmd1]} {if [catch {cli_exec $cli1(fd) $_config_cmd1} result] {error $result $errorInfo}append config_cmds $_config_cmd1}if {[info exists _config_cmd2]} {if [catch {cli_exec $cli1(fd) $_config_cmd2} result] {error $result $errorInfo}append config_cmds "\n"append config_cmds $_config_cmd2}if [catch {cli_exec $cli1(fd) "end"} result] {error $result $errorInfo}if [catch {cli_close $cli1(fd) $cli1(tty_id)} result] {error $result $errorInfo}after 60000# 3. send the notification emailset routername [info hostname]if {[string match "" $routername]} {error "Host name is not configured"}if [catch {smtp_subst [file join $tcl_library email_template_cfg.tm]} result] {error $result $errorInfo}if [catch {smtp_send_email $result} result] {error $result $errorInfo}The following e-mail template file is used with the EEM sample policy above:
email_template_cfg.tmMailservername: $_email_serverFrom: $_email_fromTo: $_email_toCc: $_email_ccSubject: From router $routername: Periodic $_show_cmd Output$cmd_outputDebugging Embedded Event Manager Policies: Examples
The following examples show how to debug the CLI library and the SMTP library.
Debugging the CLI Library
The CLI library allows users to run CLI commands and obtain the output of commands in Tcl. An Embedded Event Manager debug command has been provided for users of this library. The command to enable CLI library debugging is debug event manager tcl cli_library. When enabled, this command displays all data that is passed in and read back from the TTY session that handles the CLI interactions. This data helps ensure users that the commands that they are passing to the CLI are valid.
Example of the debug event manager tcl cli_library Command
This example uses the sample policy sl_intf_down.tcl. When triggered, sl_intf_down.tcl passes a configuration command to the CLI through the CLI library. The command passed in below is show event manager environment. This command is not a valid command in configuration mode. Without the debug command enabled, the output is shown below:
00:00:57:sl_intf_down.tcl[0]:config_cmds are show eve man env00:00:57:%SYS-5-CONFIG_I:Configured from console by vty0Notice that with the output above the user would not know whether or not the command succeeded in the CLI. With the debug event manager tcl cli_library command enabled, the user sees the following:
01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : CTL : cli_open called.01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : OUT : nelson>01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : IN : nelson>enable01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : OUT : nelson#01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : IN : nelson#configure terminal01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : OUT : Enter configuration commands, one per line. End with CNTL/Z.01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : OUT : nelson(config)#01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : IN : nelson(config)#show event manager environment01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : OUT : ^01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : OUT : % Invalid input detected at '^' marker.01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : OUT : nelson(config)#01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : IN : nelson(config)#end01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : OUT : nelson#01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : CTL : cli_close called.01:17:07: sl_intf_down.tcl[0]: DEBUG(cli_lib) : IN : nelson#exit01:17:07: sl_intf_down.tcl[0]: config_cmds are show event manager environment01:17:07: %SYS-5-CONFIG_I: Configured from console by vty0The output above shows that show event manager environment is an invalid command in configuration mode. The IN keyword signifies all data passed in to the TTY through the CLI library. The OUT keyword signifies all data read back from the TTY through the CLI library. The CTL keyword signifies helper functions used in the CLI library. These helper functions are used to set up and remove connections to the CLI.
Debugging the SMTP Library
The SMTP library allows users to send e-mail messages to an SMTP e-mail server. An Embedded Event Manager debug command has been provided for users of this library. The command to enable SMTP library debugging is debug event manager tcl smtp_library. When enabled, this command displays all data that is passed in and read back from the SMTP library routines. This data helps ensure users that the commands that they are passing to the SMTP library are valid.
Example of the debug event manager tcl smtp_library Command
This example uses the sample policy tm_cli_cmd.tcl. When triggered, tm_cli_cmd.tcl runs the command show event manager policy available system through the CLI library. The result is then mailed to a user through the SMTP library. The output will help debug any issues related to using the SMTP library.
With the debug event manager tcl smtp_library command enabled, the users see the following on the console:
00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 220 XXXX.example.com ESMTP XXXX 1.1.0; Tue, 25 Jun 2002 14:20:39 -0700 (PDT)00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : HELO XXXX.example.com00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 XXXX.example.com Hello XXXX.example.com [XXXX], pleased to meet you00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : MAIL FROM:<XX@example.com>00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 <XX@example.com>... Sender ok00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : RCPT TO:<XX@example.com>00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 <XX@example.com>... Recipient ok00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : RCPT TO:<XX@example.com>00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 <XX@example.com>... Recipient ok00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : DATA00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 354 Enter mail, end with "." on a line by itself00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : Date: 25 Jun 2002 14:35:00 UTC00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : Message-ID: <20020625143500.2387058729877@XXXX.example.com>00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : From: XX@example.com00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : To: XX@example.com00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : Cc: XX@example.com00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : Subject: From router nelson: Periodic show eve man po ava system Output00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : No. Type Time Created Name00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 1 system Fri May3 20:42:34 2002 pr_cdp_abort.tcl00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 2 system Fri May3 20:42:54 2002 pr_iprouting_abort.tcl00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 3 system Wed Apr3 02:16:33 2002 sl_intf_down.tcl00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 4 system Mon Jun24 23:34:16 2002 tm_cli_cmd.tcl00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 5 system Wed Mar27 05:53:15 2002 tm_crash_hist.tcl00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : nelson#00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write :00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : .00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 ADE90179 Message accepted for delivery00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : QUIT00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 221 XXXX.example.com closing connectionTracing Tcl set Command Operations: Example
Tcl is a flexible language. One of the flexible aspects of Tcl is that you can override commands. In this example, the Tcl set command is renamed as _set and a new version of the set command is created that displays a message containing the text "setting" and appends the scalar variable that is being set. This example can be used to trace all instances of scalar variables being set.
rename set _setproc set {var args} {puts [list setting $var $args]uplevel _set $var $args};When this is placed in a policy, a message is displayed anytime a scalar variable is set, for example:
02:17:58: sl_intf_down.tcl[0]: setting test_var 1RPC Event Detector: Example
TCL script (rpccli.tcl):::cisco::eem::event_register_rpcnamespace import ::cisco::eem::*namespace import ::cisco::lib::*proc run_cli { clist } {set rbuf ""if {[llength $clist] < 1} {return -code ok $rbuf}if {[catch {cli_open} result]} {return -code error $result} else {array set cliarr $result}if {[catch {cli_exec $cliarr(fd) "enable"} result]} {return -code error $result}if {[catch {cli_exec $cliarr(fd) "term length 0"} result]} {return -code error $result}foreach cmd $clist {if {[catch {cli_exec $cliarr(fd) $cmd} result]} {return -code error $result}append rbuf $result}if {[catch {cli_close $cliarr(fd) $cliarr(tty_id)} result]} {puts "WARNING: $result"}return -code ok $rbuf}proc run_cli_interactive { clist } {set rbuf ""if {[llength $clist] < 1} {return -code ok $rbuf}if {[catch {cli_open} result]} {return -code error $result} else {array set cliarr $result}if {[catch {cli_exec $cliarr(fd) "enable"} result]} {return -code error $result}if {[catch {cli_exec $cliarr(fd) "term length 0"} result]} {return -code error $result}foreach cmd $clist {array set sendexp $cmdif {[catch {cli_write $cliarr(fd) $sendexp(send)} result]} {return -code error $result}foreach response $sendexp(responses) {array set resp $responseif {[catch {cli_read_pattern $cliarr(fd) $resp(expect)} result]} {return -code error $result}if {[catch {cli_write $cliarr(fd) $resp(reply)} result]} {return -code error $result}}if {[catch {cli_read $cliarr(fd)} result]} {return -code error $result}append rbuf $result}if {[catch {cli_close $cliarr(fd) $cliarr(tty_id)} result]} {puts "WARNING: $result"}return -code ok $rbuf}array set arr_einfo [event_reqinfo]set args $arr_einfo(argc)set cmds [list]for { set i 0 } { $i < $args } { incr i } {set arg "arg${i}"# Split each argument on the '^' character. The first element is# the command, and each subsequent element is a prompt followed by# a response to that prompt.set cmdlist [split $arr_einfo($arg) "^"]set cmdarr(send) [lindex $cmdlist 0]set cmdarr(responses) [list]if { [expr ([llength $cmdlist] - 1) % 2] != 0 } {return -code 88}set cmdarr(responses) [list]for { set j 1 } { $j < [llength $cmdlist] } { incr j 2 } {set resps(expect) [lindex $cmdlist $j]set resps(reply) [lindex $cmdlist [expr $j + 1]]lappend cmdarr(responses) [array get resps]}lappend cmds [array get cmdarr]}set rc [catch {run_cli_interactive $cmds} output]if { $rc != 0 } {error $output $errorInforeturn -code 88}puts $outputWhere to Go Next
•
•
Additional References
The following sections provide references related to writing Embedded Event Manager policies using Tcl.
Related Documents
Cisco IOS commands
Network Management commands (including EEM commands): complete command syntax, defaults, command mode, command history, usage guidelines, and examples
Embedded Event Manager overview
Embedded Event Manager Overview module.
Embedded Event Manager policy writing using the CLI
Writing Embedded Event Manager Policies Using the Cisco IOS CLI module
Embedded Resource Manager
Embedded Resource Manager module
MIBs
CISCO-EMBEDDED-EVENT-MGR-MIB
To locate and download MIBs for selected platforms, Cisco IOS releases, and feature sets, use Cisco MIB Locator found at the following URL:
RFCs
No new or modified RFCs are supported by this feature, and support for existing RFCs has not been modified by this feature.
—
Technical Assistance
EEM Policy Tcl Command Extension Reference
This section documents the following EEM policy Tcl command extension categories:
•
•
•
•
•
•
•
•
•
•
Note
Note
The following conventions are used for the syntax documented on the Tcl command extension pages:
•
[type ?]
•
•
priority low|normal|high
EEM Event Registration Tcl Command Extensions
•
•
event_register_appl
Registers for an application event. Use this Tcl command extension to run a policy when an application event is triggered following another policy's execution of an event_publish Tcl command extension; the event_publish command extension publishes an application event.
In order to register for an application event, a subsystem must be specified. Either a Tcl policy or the internal Embedded Event Manager (EEM) API can publish an application event. If the event is being published by a policy, the sub_system argument that is reserved for a policy is 798.
Syntax
event_register_appl [tag ?] sub_system ? type ? [queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]Arguments
If multiple conditions exist, the application event will be raised when all the conditions are satisfied.
Result String
None
Set _cerrno
No
event_register_cli
Registers for a CLI event. Use this Tcl command extension to run a policy when a CLI command of a specific pattern is entered based on pattern matching performed against an expanded CLI command.
Note
Note
Syntax
event_register_cli [tag ?] sync yes|no skip yes|no[occurs ?] [period ?] pattern ? [default ?] [enter] [questionmark] [tab] [mode][queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]Arguments
If multiple conditions are specified, the CLI event will be raised when all the conditions are matched.
Result String
None
Set _cerrno
No
Note
event_register_counter
Registers for a counter event as both a publisher and a subscriber. Use this Tcl command extension to run a policy on the basis of a named counter crossing a threshold. This event counter, as a subscriber, identifies the name of the counter to which it wants to subscribe and depends on another policy or another process to actually manipulate the counter. For example, let policyB act as a counter policy, whereas policyA (although it does not need to be a counter policy) uses register_counter, counter_modify, or unregister_counter Tcl command extensions to manipulate the counter defined in policyB.
Syntax
event_register_counter [tag ?] name ? entry_op gt|ge|eq|ne|lt|le entry_val ? exit_op gt|ge|eq|ne|lt|le exit_val ? [queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]Arguments
Result String
None
Set _cerrno
No
event_register_gold
Registers for a Generic Online Diagnostic (GOLD) failure event. Use this Tcl command extension to run a policy on the basis of a Generic Online Diagnostic (GOLD) failure event for the specified card and subcard.
Syntax
event_register_gold card all|card_number[subcard all|subcard_number][new_failure TRUE|FALSE][severity_major TRUE][severity_minor TRUE][severity_normal TRUE][action_notify TRUE|FALSE][testing_type [bootup|ondemand|schedule|monitoring]][test_name [testname]][test_id [testnumber]][consecutive_failure consecutive_failure_number][platform_action [action_flag]][maxrun ?][queue_priority low|normal|high|last][nice 0|1]Arguments
Result String
None
Set _cerrno
No
event_register_interface
Registers for an interface counter event. Use this Tcl command extension to generate an event when specified interface counters exceed specified thresholds.
Syntax
event_register_interface [tag ?] name ?parameter ? entry_op gt|ge|eq|ne|lt|leentry_val ? entry_val_is_increment TRUE|FALSEentry_type value|increment|rate[exit_comb or|and][exit_op gt|ge|eq|ne|lt|le][exit_val ?] [exit_val_is_increment TRUE|FALSE][exit_type value|increment|rate][exit_time ?] [poll_interval ?][average_factor ?] [queue_priority low|normal|high|last][maxrun ?] [nice 0|1]Arguments
Result String
None
Set _cerrno
No
event_register_ioswdsysmon
Registers for an IOSWDSysMon event. Use this Tcl command extension to generate an event when a Cisco IOS task exceeds specific CPU utilization or memory thresholds. A Cisco IOS task is called a Cisco IOS process in native Cisco IOS.
Syntax
event_register_ioswdsysmon [tag ?] [timewin ?] [sub12op and|or] [sub1 ?] [sub2 ?] [queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]Arguments
Subevent Syntax
cpu_proc path ? taskname ? op gt|ge|eq|ne|lt|le val ? [period ?]mem_proc path ? taskname ? op gt|ge|eq|ne|lt|le val ? [is_percent TRUE|FALSE] [period ?]Subevent Arguments
Result String
None
Set _cerrno
No
event_register_ipsla
Registers for an event that is triggered by the event ipsla command. Use this Tcl command to publish an event when an IPSLA reaction is triggered. The group ID or the operation ID is required to register the event.
Syntax
event_register_ipsla [tag ?] group_name ? operation_id ? [reaction_type ?] [dest_ip_addr ?][queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]Arguments
Result String
None
Set _cerrno
No
event_register_nf
Registers for an event when a NetFlow event is triggered by the event nf command. Use this Tcl command to publish an event when an NetFlow reaction is triggered..
Syntax
event_register_nf [tag ?] monitor_name ? event_type create|update|delete exit_event_type create|update|delete event1-event4 ? [maxrun ?] [nice 0|1]Arguments
Subevent Syntax
field ? rate_interval ? event1 only entry_value ? entry_op eq|ge|gt|le|lt|wc [exit_value ?] [exit_op eq|ge|gt|le|lt|wc] [exit_rate_interval ? event1 only]Subevent Arguments
Result String
None
Set _cerrno
No
event_register_none
Registers for an event that is triggered by the event manager run command. These events are handled by the None event detector that screens for this event.
Syntax
event_register_none [tag ?] [queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]Arguments
Result String
None
Set _cerrno
No
event_register_oir
Registers for an online insertion and removal (OIR) event. Use this Tcl command extension to run a policy on the basis of an event raised when a hardware card OIR occurs. These events are handled by the OIR event detector that screens for this event.
Syntax
event_register_oir [tag ?] [queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]Arguments
Result String
None
Set _cerrno
No
event_register_process
Registers for a process event. Use this Tcl command extension to run a policy on the basis of an event raised when a Cisco IOS Software Modularity process starts or stops. These events are handled by the System Manager event detector that screens for this event. This Tcl command extension is supported only in Software Modularity images.
Syntax
event_register_process [tag ?] abort|term|start|user_restart|user_shutdown[sub_system ?] [version ?] [instance ?] [path ?] [node ?][queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]Arguments
If an optional argument is not specified, the event matches all possible values of the argument. If multiple arguments are specified, the process event will be raised when all the conditions are matched.
Result String
None
Set _cerrno
No
event_register_resource
Registers for an Embedded Resource Manager (ERM) event. Use this Tcl command extension to run a policy on the basis of an ERM event report for a specified policy. ERM events are screened by the EEM Resource event detector, allowing an EEM policy to be run when a match occurs for the specified ERM policy.
Syntax
event_register_resource policy policy-name [queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]Arguments
Result String
None
Set _cerrno
No
event_register_rf
Registers for a Redundancy Facility (RF) event. Use this Tcl command extension to run a policy when an RF progression or status event notification occurs.
Syntax
event_register_rf [tag ?] event ?[queue_priority low|normal|high|last][maxrun ?] [nice 0|1]Arguments
Result String
None
Set _cerrno
No
event_register_routing
Registers for an event that is triggered by the event routing command. These events are handled by the routing event detector to publish an event when route entries change in Routing Information Base (RIB) infrastructure. Use this Tcl command extension to run a routing policy for this script. The network IP address for the route to be monitored must be specified.
Syntax
event_register_routing [tag ?] network ? length [ge|le|ne] [type add|remove|modify|all] [protocol ?] [queue_priority normal|low|high|last] [maxrun ?] [nice {0 | 1}]Arguments
Result String
None
Set _cerrno
No
event_register_rpc
Registers for an event that is triggered by the EEM SSH Remote Procedure Call (RPC) command. These events are handled by the RPC event detector that screens for this event. Use this Tcl command extension to run a RPC policy for this script.
Syntax
event_register_rpc [queue_priority {normal | low | high | last}] [maxrun <sec.msec>] [nice {0 | 1}] [default <sec.msec>]Arguments
Result String
None
Set _cerrno
No
event_register_snmp
Registers for a Simple Network Management Protocol (SNMP) statistics event. Use this Tcl command extension to run a policy when a given counter specified by an SNMP object ID (oid) crosses a defined threshold.
Syntax
event_register_snmp [tag ?] oid ? get_type exact|nextentry_op gt|ge|eq|ne|lt|le entry_val ?entry_type value|increment|rate[exit_comb or|and][exit_op gt|ge|eq|ne|lt|le] [exit_val ?][exit_type value|increment|rate][exit_time ?] poll_interval ? [average_factor ?][queue_priority low|normal|high|last][maxrun ?] [nice 0|1]Arguments
Result String
None
Set _cerrno
No
event_register_snmp_notification
Registers for a Simple Network Management Protocol (SNMP) notification trap event. Use this Tcl command extension to run a policy when an SNMP trap with the specified SNMP object ID (oid) is encountered on a specific interface or address. The snmp-server manager CLI command must be enabled for the SNMP notifications to work using Tcl policies.
Syntax
event_register_snmp_notification [tag ?] oid ? oid_val ?op {gt|ge|eq|ne|lt|le}[maxrun ?][src_ip_address ?][dest_ip_address ?][queue_priority {normal|low|high|last}][maxrun ?][nice {0|1}][default ?][direction {incoming|outgoing}][msg_op {drop|send}]Arguments
Result String
None
Set _cerrno
No
event_register_snmp_object
Registers for a Simple Network Management Protocol (SNMP) object event. Use this Tcl command extension to replace the value when an SNMP with the specified SNMP-object ID (OID) is encountered on a specific interface or address.
Syntax
event_register_snmp_object oid ?type {int|unit|counter|gauge|ipv4|octect|string}sync {yes|no}skip {yes|no}[istable {yes|no}][default ?][queue_priority {normal|low|high|last}][maxrun ?][nice {0|1}]Arguments
Result String
None
Set _cerrno
No
event_register_syslog
Registers for a syslog event. Use this Tcl command extension to trigger a policy when a syslog message of a specific pattern is logged after a certain number of occurrences during a certain period of time.
Syntax
event_register_syslog [tag ?] [occurs ?] [period ?] pattern ?[priority all|emergencies|alerts|critical|errors|warnings|notifications| informational|debugging|0|1|2|3|4|5|6|7][queue_priority low|normal|high|last][severity_fatal] [severity_critical] [severity_major][severity_minor] [severity_warning] [severity_notification][severity_normal] [severity_debugging][maxrun ?] [nice 0|1]Arguments
tag
(Optional) String identifying a tag that can be used with the trigger Tcl command extension to support multiple event statements within a Tcl script.
occurs
(Optional) Number of occurrences before the event is raised; if not specified, the event is raised on the first occurrence. If specified, the value must be greater than 0.
period
(Optional) Time interval, in seconds and milliseconds, during which the one or more occurrences must take place in order to raise an event (specified in SSSSSSSSSS[.MMM] format where SSSSSSSSSS must be an integer number representing seconds between 0 and 4294967295, inclusive, and where MMM represents milliseconds and must be an integer number between 0 and 999). If this argument is not specified, no period check is applied.
pattern
(Mandatory) A regular expression used to perform syslog message pattern match. This argument is what the policy uses to identify the logged syslog message.
priority
(Optional) The message priority to be screened. If this argument is specified, only messages that are at the specified logging priority level, or lower, are screened. If this argument is not specified, the default priority is 0.
queue_priority
(Optional) Priority level at which the script will be queued:
•
•
•
•
If more than one script is registered with the "queue_priority_last" argument set, these scripts will execute in the order in which the events are published.
Note
If this argument is not specified, the default queuing priority is normal.
maxrun
(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.
nice
(Optional) Policy run-time priority setting. When the nice argument is set to 1, the policy is run at a run-time priority that is less than the default priority. The default value is 0.
severity_xxx
(Optional) The event severity to be screened. If this argument is specified, only messages that are at the specified severity level are screened. See Table 13 for the severity level mapping for syslog events.
If multiple conditions are specified, the syslog event will be raised when all the conditions are matched.
Result String
None
Set _cerrno
No
event_register_timer
Creates a timer and registers for a timer event as both a publisher and a subscriber. Use this Tcl command extension when there is a need to trigger a policy that is time specific or timer based. This event timer is both an event publisher and a subscriber. The publisher part indicates the conditions under which the named timer is to go off. The subscriber part identifies the name of the timer to which the event is subscribing.
Note
Syntax
event_register_timer [tag ?] watchdog|countdown|absolute|cron[name ?] [cron_entry ?][time ?][queue_priority low|normal|high|last] [maxrun ?][nice 0|1]Arguments
tag
(Optional) String identifying a tag that can be used with the trigger Tcl command extension to support multiple event statements within a Tcl script.
watchdog
(Mandatory) Watchdog timer.
countdown
(Mandatory) Countdown timer.
absolute
(Mandatory) Absolute timer.
cron
(Mandatory) CRON timer.
name
(Optional) Name of the timer.
cron_entry
(Optional) Must be specified if the CRON timer type is specified. Must not be specified if any other timer type is specified. A cron_entry is a partial UNIX crontab entry (the first five fields) as used with the UNIX CRON daemon.
A cron_entry specification consists of a text string with five fields. The fields are separated by spaces. The fields represent the time and date when CRON timer events will be triggered. The fields are described in Table 14.
Ranges of numbers are allowed. Ranges are two numbers separated with a hyphen. The specified range is inclusive. For example, 8-11 for an hour entry specifies execution at hours 8, 9, 10, and 11.
A field may be an asterisk (*), which always stands for "first-last."
Lists are allowed. A list is a set of numbers (or ranges) separated by commas. Examples: "1,2,5,9" and "0-4,8-12".
Step values can be used in conjunction with ranges. Following a range with "/<number>" specifies skips of the number's value through the range. For example, "0-23/2" can be used in the hour field to specify an event that is triggered every other hour. Steps are also permitted after an asterisk, so if you want to say "every two hours", use "*/2".
Names can also be used for the month and the day of week fields. Use the first three letters of the particular day or month (case does not matter). Ranges or lists of names are not allowed.
The day on which a timer event is triggered can be specified by two fields: day of month and day of week. If both fields are restricted (that is, are not *), an event will be triggered when either field matches the current time. For example, "30 4 1,15 * 5" would cause an event to be triggered at 4:30 a.m. on the 1st and 15th of each month, plus every Friday.
Instead of the first five fields, one of seven special strings may appear. These seven special strings are described in Table 15.
Example 1: "0 0 1,15 * 1" would trigger an event at midnight on the 1st and 15th of each month, as well as on every Monday. To specify days by only one field, the other field should be set to *; "0 0 * * 1" would trigger an event at midnight only on Mondays.
Example 2: "15 16 1 * *" would trigger an event at 4:15 p.m. on the first day of each month.
Example 3: "0 12 * * 1-5" would trigger an event at noon on Monday through Friday of each week.
Example 4: "@weekly" would trigger an event at midnight once a week on Sunday.
time
(Optional) Must be specified if a timer type other than CRON is specified. Must not be specified if the CRON timer type is specified. For watchdog and countdown timers, the number of seconds and milliseconds until the timer expires; for the absolute timer, the calendar time of the expiration time. Time is specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999. An absolute expiration date is the number of seconds and milliseconds since January 1, 1970. If the date specified has already passed, the timer expires immediately.
queue_priority
(Optional) Priority level at which the script will be queued:
•
•
•
•
Guest
