Downloads |
Table Of Contents
Writing Embedded Event Manager Policies
Embedded Event Manager Overview
Embedded Event Manager Policies
General Flow of EEM Event Detection and Recovery
Tcl Policy Structure and Requirements
EEM Event Registration Keywords
event_register_timer_subscriber
EEM System Information Keywords
Debugging Embedded Event Manager Policies
Writing Embedded Event Manager Policies
This module describes how software developers can write and customize Embedded Event Manager (EEM) policies to handle Cisco IOS software faults and events. EEM is a policy driven process through which faults in the Cisco IOS software system are reported through a defined API. The EEM policy engine receives notifications when faults and other events occur. Embedded Event Manager policies implement recovery based on the current state of the system and the actions specified in the policy for a given event. Recovery actions are triggered when the policy is run.
History for the Writing Embedded Event Manager Policies Document
12.3(14)T
This document was introduced to support the Embedded Event Manager feature in Cisco IOS Release 12.3(14)T.
Finding Support Information for Platforms and Cisco IOS Software Images
Use Cisco Feature Navigator to find information about platform support and Cisco IOS software image support. Access Cisco Feature Navigator at http://www.cisco.com/go/fn. You must have an account on Cisco.com. If you do not have an account or have forgotten your username or password, click Cancel at the login dialog box and follow the instructions that appear.
Contents
•
Embedded Event Manager Overview
•
–
–
•
–
•
–
•
•
•
Embedded Event Manager Overview
Embedded Event Manager (EEM) is a distributed, scalable, and customized approach to event detection and recovery offered directly in a Cisco IOS device. EEM offers the ability to monitor events and take informational or corrective action when the monitored events occur or when a threshold is reached. EEM is a policy driven process through which faults in Cisco IOS software are reported through a defined API. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs.
The EEM policy engine receives notifications when faults and other events occur. EEM policies implement recovery based on the current state of the system and the actions specified in the policy for a given event. Recovery actions are triggered when the policy is run. Developers can write and customize EEM policies to handle Cisco IOS software faults and events.
Event Detectors
EEM uses software programs known as event detectors to determine when an EEM event occurs. Event detectors are separate systems that provide an interface between the agent being monitored, for example Simple Network Management Protocol (SNMP), and the EEM policies where an action can be implemented. EEM for Cisco IOS Release 12.3(14)T contains the following event detectors.
Application-Specific Event Detector
The application-specific event detector allows any Embedded Event Manager policy to publish an event.
CLI Event Detector
The CLI event detector screens command-line interface (CLI) commands for a regular expression match. When a match is found, an event is published. The match logic is performed on the fully expanded CLI command after the command has been successfully parsed and before the command is executed. The CLI event detector supports three publish modes:
•
•
•
Counter Event Detector
The counter event detector publishes an event when a named counter crosses a specified threshold. There are two or more participants that affect counter processing. The counter event detector can modify the counter, and one or more subscribers define the criteria that cause the event to be published. After a counter event has been published, the counter monitoring logic can be reset to start monitoring the counter immediately or it can be reset when a second threshold—called an exit value—is crossed.
Interface Counter Event Detector
The interface counter event detector publishes an event when a generic Cisco IOS interface counter for a specified interface crosses a defined threshold. A threshold can be specified as an absolute value or an incremental value. If the incremental value is set to 50, for example, an event would be published when the interface counter increases by 50.
After an interface counter event has been published, the interface counter monitoring logic is reset using two methods. The interface counter is reset either when a second threshold—called an exit value—is crossed or when an elapsed period of time occurs.
None Event Detector
The none event detector publishes an event when the Cisco IOS event manager run CLI command executes an EEM policy. EEM schedules and runs policies on the basis of an event specification that is contained within the policy itself. An EEM policy must be identified and registered to be permitted to be run manually before the event manager run command will execute
OIR Event Detector
The online insertion and removal (OIR) event detector publishes an event when one of the following hardware insertion or removal events occurs:
•
•
Route processors (RPs), line cards, or feature cards can be monitored for OIR events.
SNMP Event Detector
The SNMP event detector allows a standard SNMP MIB object to be monitored and an event to be generated when the object matches specified values or crosses specified thresholds.
Syslog Event Detector
The syslog event detector allows for screening syslog messages for a regular expression pattern match. The selected messages can be further qualified, requiring that a specific number of occurrences be logged within a specified time. A match triggers a policy to run.
Timer Event Detector
The timer event detector publishes events for the following four different types of timers:
•
•
•
•
Note
Watchdog System Monitor (Cisco IOS) Event Detector
The Cisco IOS watchdog system monitor event detector publishes an event when one of the following occurs:
•
•
Two events may be monitored at the same time, and the event publishing criteria can be specified to require one event or both events to cross their specified thresholds.
Recovery
Once an event or fault has been detected, recovery actions are initiated to minimize disruption to the system. Recovery actions are contained in routines called EEM policies. The nature of the recovery action for the responsible component depends on the type of event or fault detected. System information can be requested to facilitate recovery action decision making.
Hardware failure is detected and handled by platform services. This is necessary because the techniques used are platform-specific, and the speed of failover must be very fast to get maximum benefit from redundant hardware. Software process faults are handled by the Embedded Event Manager. The EEM determines what recovery action should be taken according to configured policies.
The CLI-based corrective actions that are taken when event detectors report events enable a powerful on-device event management mechanism. EEM for Cisco IOS Release 12.3(14)T supports the following actions:
•
•
•
•
•
•
•
•
•
•
•
Embedded Event Manager Policies
All Embedded Event Manager policies are written in Tcl. Tcl is a string-based command language that is interpreted at runtime. As an enforced rule, Embedded Event Manager policies are short-lived runtime routines that must be interpreted and executed in less than twenty seconds of elapsed time.
EEM policies use the full range of the Tcl language's capabilities. However, Cisco provides enhancements to the Tcl language in the form of keyword extensions that facilitate the writing of EEM policies.
EEM policy keywords identify the event or fault for which recovery actions or responsive actions are to be implemented. Keywords also register the policy with Embedded Event Manager to schedule the policy's execution.
In general, there are two parts of each EEM policy:
•
•
EEM Policy Keyword Categories
There are different categories of EEM policy keyword extensions.
Note
General Flow of EEM Event Detection and Recovery
EEM 2.1 is a flexible, policy-driven framework that supports in-box monitoring of different components of the system with the help of software agents known as event detectors. Figure 1 shows the relationship between the EEM server, core event publishers (event detectors), and the event subscribers (policies). Basically, event publishers screen events and publish them when there is a match on an event specification that is provided by the event subscriber. Event detectors notify the EEM when an event of interest occurs.
When an event or fault is detected, Embedded Event Manager determines from the Event Publishers (for example, 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 keyword event_register_xxx. The event information keyword 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
Programming Policies with Tcl
Cisco IOS Release 12.3(14)T delivers 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.
For more details about the sample policies available in Cisco IOS Release 12.3(14)T and how to run them, see the "EEM Event Detector Demo" section in the Embedded Event Manager 2.1 feature.
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 keyword and the body. The remaining parts of the policy are optional: environment must defines, namespace import, entry status, and exit status.
Figure 2 Suggested Tcl Policy Structure and Requirements
The start of every policy must describe and register the event to detect using the event register keyword. This part of the policy schedules the running of the policy.
The body of the policy, in general, is a required structure and might contain the following:
•
•
•
•
•
Figure 3 shows sample text from an EEM Tcl policy with some of the sections from Figure 2 highlighted to demonstrate what the structure looks like using an actual Tcl policy.
Figure 3 Example EEM Tcl Policy
Tcl Coding Conventions
Use the following Tcl coding conventions to write Embedded Event Manager policies.
•
Namespace Usage
Policy developers can use the new namespace ::cisco
in Tcl policies in order to group together all the extensions used by Cisco IOS EEM.There are two namespaces under the ::cisco hierarchy:
1.
This namespace includes all Tcl commands closely related to Embedded Event Manager. The commands which belong to this namespace are:
2.
This namespace includes auxiliary library commands that are not necessarily specific to the Embedded Event Manager. Currently the commands that belong to this namespace are:
Note
EEM Environment Variables
EEM environment variables are Tcl global variables that are defined external to the policy before the policy is run. Definition occurs using the Embedded Event Manager configuration command event manager environment varname varvalue, and should be in a separate line. By convention all Cisco EEM environment variables begin with "_". In order to avoid future conflict, customers are urged not to define new variables that start with "_".
You can display the Embedded Event Manager environment variables set on your system with the Privileged EXEC mode command:
show event manager environment [all | varname]
For example, Embedded Event Manager environment variables defined by the sample policies include e-mail variables. The sample policies that send e-mail need to have the variables shown in Table 2 set in order to function properly.
Table 2 describes the E-mail-specific environment variables used in the sample EEM policies.
Must defines
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.
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}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. 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).
EEM Exit Status
When a policy exits, 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 non-zero 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 keywords set a Cisco Error Number Tcl global variable _cerrno. Whenever _cerrno is set, four other Tcl global variables _cerr_sub_num, _cerr_sub_err, _cerr_posix_err, and _cerr_str are derived from _cerrno and are set along with it.
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}_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 keyword:
862439AEThis number is interpreted as the following 32-bit value:
10000110001001000011100110101110This 32-bit integer is divided up into 5 variables:
Error Class Encodings for XYZ
The first variable, XYZ, references the following 8 possible error class encodings:
:
An error return value of zero means SUCCESS.
Cisco File Naming Convention
All Embedded Event Manager policy names, policy support files (e.g., E-mail template files), and library file names are consistent with the Cisco File Naming Convention. In this regard, Embedded Event Manager policy filenames adhere to the following specification:
•
•
•
Embedded Event Manager library filenames consist of a filename body part containing the descriptive field identifying the usage of the library, followed by _lib, and a filename suffix part defined by .tcl
Embedded Event Manager E-mail template files consist of a filename prefix of email_template, followed by an abbreviation identifying the usage of the e-mail template.
EEM Event Registration Keywords
For all EEM Tcl commands, if there are no errors, the returned Tcl result string is as shown below. If there is an error, the returned Tcl result string contains the error information
Arguments for which no numeric range is specified take an integer number between -2147483648 to 2147483647 inclusive.
event_register_appl
Register for an application event.
Use this keyword to run a policy when an application event is triggered following another policy's execution of an event_publish keyword; event_publish publishes an application event.
In order to register for an application event, a component_id and the id value must be specified. Either a Tcl policy or the internal EEM API can publish an application event. If the event is being published by a policy, the comp_id reserved for a policy is 0x031E (Tcl accepts hex format input).
Syntax
event_register_appl [comp_id ?] [type ?] [priority low|normal|high] [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
Register for a CLI event. Use this keyword 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
Syntax
event_register_cli sync yes|no skip yes|nooccurs ? [period_sec ?] [period_nsec ?] pattern ?[priority normal|low|high] [maxrun ?] [nice 0|1]Arguments
If multiple conditions are specified, the syslog event will be raised when all the conditions are matched.
Result String:
none
Set_cerrno:
no
Note
event_register_counter
Register for a counter event as both a publisher and as a subscriber.
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, while policyA (although it does not need to be a counter policy) uses register_counter, counter_modify, or unregister_counter to manipulate the counter defined in policyB.
Syntax
event_register_counter name ? entry_op gt|ge|eq|ne|lt|le entry_val? [exit_op gt|ge|eq|ne|lt|le] [exit_val?] [priority low|normal|high] [maxrun ?] [nice 0|1]Arguments
Result string
None
Set _cerrno
No
event_register_interface
Generates an event when specified interface counters exceed specified thresholds.
Syntax
event_register_interface name ?parameter ? entry_op {gt | ge | eq | ne | lt | le}entry_val ? entry_val_is_increment {TRUE | FALSE|[exit_comb {or | and}[exit_op {gt | ge | eq | ne | lt | le}][exit_val ?] [exit_val_is_increment {TRUE | FALSE}][exit_time ?] [poll_interval ?][priority low | normal | high] [maxrun ?][nice 0 | 1]Arguments
event_register_ioswdsysmon
Generates 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 [node ?] [timewin ?] [sub12op {and|or}] [sub1 ?] [sub2 ?] [priority low|normal|high] [maxrun ?] [nice 0|1]Arguments
Sub-event Syntax
cpu_proc taskname ? op {gt|ge|eq|ne|lt|le} val ? [period ?]mem_proc taskname ? op {gt|ge|eq|ne|lt|le} val ? [is_percent {TRUE|FALSE}] [period ?]Sub-event Arguments
event_register_none
Register 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 queue_priority [priority low|normal|high] [maxrun ?] [nice 0|1]Arguments
For each optional argument, if it is unspecified, the event matches all possible values of the argument.
If multiple conditions are specified, the process event will be raised when all the conditions are matched.
Result string
None
Set _cerrno
No
event_register_oir
Register for an OIR event. These events are handled by the OIR Event Detector that screens for this event.
Syntax
event_register_oir [priority low|normal|high] [maxrun ?] [nice 0|1]Arguments
For each optional argument, if it is unspecified, the event matches all possible values of the argument. If multiple conditions are specified, the process event will be raised when all the conditions are matched.
Result string
None
Set _cerrno
No
event_register_snmp
Register for an SNMP statistics event.
Use this command to run a policy when a given counter specified by an SNMP object ID (oid) crosses a defined threshold.
oid's taken as input will be in SNMP dot notation (for example 1.3.6.1.2.1.2.1.0)
The types of oids allowed are:
•
•
•
•
•
•
•
Syntax
event_register_snmp oid ? get_type exact|nextentry_op gt | ge | eq | ne | lt | le entry_val ?[exit_comb or | and][exit_op gt | ge | eq | ne | lt | le] [exit_val ?][exit_time ?] [poll_interval ?][priority normal | low | high][maxrun ?] [nice 0 | 1]Arguments
event_register_syslog
Register for a syslog event.
Use this keyword to trigger a policy when a syslog message of a specific pattern is logged after a certain number of occurrence during a certain period of time.
Syntax
event_register_syslog [occurs ?] [period ?] pattern ? [priority low|normal|high] [maxrun ?] [nice 0|1]Arguments
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
Create a timer and register for a timer event as both a publisher and a subscriber. Use this keyword 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 it is subscribing.
Note
Syntax
event_register_timer watchdog|countdown|absolute|cron[name ?] [cron_entry ?] (for cron timer)[time ?] (for other types of timer)[priority low|normal|high] [maxrun ?][nice 0|1]Arguments
watchdog
Mandatory. Watchdog timer.
countdown
Mandatory. Countdown timer.
absolute
Mandatory. Absolute timer.
cron
Mandatory. Cron timer.
name
Mandatory. Name of the timer.
cron_entry
Mandatory. Must be specified if 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 4:
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", "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 "day of week" fields. Use the first three letters of the particular day or month (case doesn't matter). Ranges or lists of names are not allowed.
The day that a timer event is triggered can be specified by two fields -- day of month, and day of week. If both fields are restricted (ie, 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 am 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 5.
Example 1: "0 0 1,15 * 1" would trigger an event at midnight on the first and fifteenth 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:15PM 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
Mandatory. Must be specified if timer type other than cron is specified. Must not be specified if cron timer type is specified. For watchdog and countdown timers, the number of seconds and milliseconds until the timer expires; for absolute timer, the calendar time of the expiration time. Specified in SSSSSSSSSS[.MMM] format where SSSSSSSSSS must be an integer number representing seconds between 0 and 4294967295 inclusive. MMM represents milliseconds, and must be an integer number 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.
priority
Optional. Priority level the script will be queued. Priority not specified means normal priority, the default.
maxrun
Optional. Maximum runtime of the script (specified in SSSSSSSSSS[.MMM] format where SSSSSSSSSS must be an integer number representing seconds between 0 and 4294967295 inclusive. MMM represents nanoseconds, and must be an integer number between 0 and 999) If not specified, use the default 20 seconds runtime limit.
nice
Optional. When nice is set to 1, the policy is run at a runtime priority that is less than the default priority. The default value is 0.
See Also
event_register_timer_subscriber
Result string
None
Set _cerrno
No.
event_register_timer_subscriber
Register for a timer event as a subscriber.
This event timer, as a subscriber, identifies the name of the timer to which it wants to subscribe and depends on another policy or another process to actually manipulate the timer. For example, let policyB act as a timer subscriber policy, but policyA (although it does not need to be a timer policy) uses register_timer, timer_arm, or timer_cancel to manipulate the timer referenced in policyB.
Syntax
event_register_timer_subscriber watchdog|countdown|absolute|cron name ? [priority low|normal|high] [maxrun ?] [nice 0|1]Arguments
Note
Result string
None
Set _cerrno
No
See Also
event_register_timer
EEM Event Information Keyword
Note
event_reqinfo
Query information for the latest event that occurred.
Tcl result string (if successful):
For EEM_EVENT_APPLICATION:
"event_id %u event_type %u event_type_string {%s} event_pub_sec %u event_pub_msec %u""comp_id 0x%x type %u data1 {%s} data2 {%s} data3 {%s} data4 {%s}"
For EEM_EVENT_CLI:
"event_id %u event_type %u event_type_string {%s} event_pub_sec %u event_pub_msec %u""count %d msg {%s}"
For EEM_EVENT_INTERFACE:
"event_id %u event_type %u event_type_string {%s} %u event_pub_sec %u event_pub_msec %u""name {%s} parameter {%s} value %d"
For EEM_EVENT_SNMP:
"event_id %u event_type %u event_type_string {%s} %u event_pub_sec %u event_pub_msec %u""oid {%s} val {%s}"
For EEM_EVENT_IOSWDSYSMON:
"event_id %u event_type %u event_type_string {%s} %u event_pub_sec %u event_pub_msec %u""num_subs %u"If subevent1 is present, followed by "sub1 subevent info string".
If subevent2 is present, followed by "sub2 subevent info string".
Where the subevent info string is: for CPU_UTIL subevent,
"{type %s procname {%s} pid %u taskname {%s} taskid %u value %u sec %ld msec %ld}"
where the subevent info string is: for MEM_UTIL subevent,
"{type %s procname {%s} pid %u taskname {%s} taskid %u is_percent %s value %u diff %d""sec %ld msec %ld}"
For EEM_EVENT_TIMER_WATCHDOG:
EEM_EVENT_TIMER_COUNTDOWN:
EEM_EVENT_TIMER_ABSOLUTE:"event_id %u event_type %u event_type_string {%s} event_pub_sec %u event_pub_msec %u""timer_type %s timer_time_sec %ld timer_time_msec %ld""timer_remain_sec %ld timer_remain_msec %ld"
For EEM_EVENT_TIMER_CRON:
"event_id %u event_type %u event_type_string {%s} event_pub_sec %u event_pub_msec %u""timer_type {%s} timer_time_sec %ld timer_time_msec %ld"
For EEM_EVENT_COUNTER:
"event_id %u event_type %u event_type_string {%s} %u event_pub_sec %u event_pub_msec %u""name {%s}"
For EEM_EVENT_SYSLOG_MSG:
"event_id %u event_type %u event_type_string {%s} event_pub_sec %u event_pub_msec %u""msg {%s}"
For EEM_EVENT_NONE:
"event_id %u event_type %u event_type_string {%s} event_pub_sec %u event_pub_msec %u"
For EEM_EVENT_OIR:
"event_id %u event_type %u event_type_string {%s} event_pub_sec %u event_pub_msec %u""slot %u event %s"
EEM Event Publish Keyword
Note
event_publish
Publish an application specific event.
Syntax
event_publish comp_id ? type ? [arg1 ?] [arg2 ?] [arg3 ?] [arg4 ?]Arguments
Result string
None.
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
EEM Action Keywords
Note
action_policy
Start, restart, or kill a process.
Syntax
action_policy [policy_name ?]Arguments
Result string
None
Set _cerrno
Yes
action_syslog
Log a message.
Syntax
action_syslog [priority emerg|alert|crit|err|warning|notice|info|debug][msg ?]Arguments
priority
Optional. The action_syslog message facility level.
Not specified means default priority: LOG_INFO
msg
Mandatory. The message to be logged.
Result string
None
Set _cerrno
Yes
(_cerr_sub_err = 14) FH_ENOSUCHACTION (unknown action type)This error means that the action command requested was unknown.
action_reload
Reload the router.
Arguments
None
Result string
None
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 14) FH_ENOSUCHACTION (unknown action type)This error means that the action command requested was unknown.
action_script
Enable or disable script execution.
Syntax
action_script [status enable|disable]Argument
status
Mandatory. Flag to indicate script execution status. If set to enable, script execution is enabled; if set to disable, script execution is disabled.
Result string
None
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 14) FH_ENOSUCHACTION (unknown action type)This error means that the action command requested was unknown.
(_cerr_sub_err = 52) FH_ECONFIG (configuration error)This error means that a configuration error has occurred.
action_program
Run a program, optionally with a given argument string, environment string, stdin, stdout, or stderr.
Syntax
action_program [path ?] [argv ?] [envp ?] [stdin ?] [stdout ?] [stderr ?]Arguments
Result string
None
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 14) FH_ENOSUCHACTION (unknown action type)This error means that the action command requested was unknown.
(_cerr_sub_err = 34) FH_EMAXLEN (maximum length exceeded)This error means that the object length or number exceeded the maximum.
action_snmp_trap
Send an SNMP trap using the Embedded Event Manager Notification MIB.
Syntax
action_snmp_trap [intdata1 ?] [intdata2 ?] [strdata ?]Arguments
intdata1
Optional. Arbitrary integer sent in trap.
intdata2
Optional. Arbitrary integer sent in trap.
strdata
Optional. Arbitrary string data sent in trap.
Result string
None
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 14) FH_ENOSUCHACTION (unknown action type)This error means that the action command requested was unknown.EEM Utility Keywords
Note
register_timer
Register a timer and return a timer event id. A timer publisher must do this before using event id to manipulate the timer if it does not use event_register_timer to register as a publisher and subscriber.
Syntax
register_timer watchdog|countdown|absolute|cron[name ?]Argument
Result string
event_id %uwhere event_id is the timer event id for the specified timer (can be used to manipulate the timer by timer_arm or timer_cancel command).
Note
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 4) FH_EINITONCE (Init() is not yet done, or done twice.)This error means that the request to register the specific event was made before the EEM Event Detector had completed it's initialization.
(_cerr_sub_err = 6) FH_EBADEVENTTYPE (unknown EEM event type)This error means that the event type specified in the internal event specification was invalid.
(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)This error means that an internal EEM request for memory failed.
(_cerr_sub_err = 10) FH_ECORRUPT (internal EEM API context is corrupt)This error means that the internal EEM API context structure is corrupt.
(_cerr_sub_err = 11) FH_ENOSUCHESID (unknown event specification ID)This error means that the event specification ID could not be matched when the event was being registered or an Event Detector internal event structure is corrupt.
(_cerr_sub_err = 16) FH_EBADFMPPTR (bad ptr to fh_p data structure)This error means that the context ptr that is used with each EEM API call is incorrect
(_cerr_sub_err = 17) FH_EBADADDRESS (bad API control block address)This error means that a control block address that was passed in the EEM API was incorrect.
(_cerr_sub_err = 22) FH_ENULLPTR (event detector internal error - ptr is null)This error means that en internal EEM Event Detector pointer was null when it should contain a value.
(_cerr_sub_err = 25) FH_ESUBSEXCEED (number of subscribers exceeded)This error means that the number of timer or counter subscribers exceeded the maximum.
(_cerr_sub_err = 26) FH_ESUBSIDXINV (invalid subscriber index)This error means that the subscriber index was invalid.
(_cerr_sub_err = 54) FH_EFDUNAVAIL (connection to event detector unavailable)This error means that the Event Detector was unavailable.
(_cerr_sub_err = 56) FH_EFDCONNERR (event detector connection error)This error means that the EEM Event Detector that handles this request is not available.
timer_arm
Arm a timer. The type could be cron, watchdog, countdown, or absolute.
Syntax
timer_arm [event_id ?] [cron entry ?] (for cron timer)[period ?] (for other types of timer)Arguments
Result string
sec_remain %ld msec_remain %ldwhere sec_remain and msec_remain are the remaining time before the next expiration of the timer.
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 6) FH_EBADEVENTTYPE (unknown EEM event type)This error means that the event type specified in the internal event specification was invalid.
(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)This error means that an internal EEM request for memory failed.
(_cerr_sub_err = 11) FH_ENOSUCHESID (unknown event specification ID)This error means that the event specification ID could not be matched when the event was being registered or an Event Detector internal event structure is corrupt.
(_cerr_sub_err = 12) FH_ENOSUCHEID (unknown event ID)This error means that the event specification ID could not be matched when the event was being registered or an Event Detector internal event structure is corrupt.
(_cerr_sub_err = 22) FH_ENULLPTR (event detector internal error - ptr is null)This error means that en internal EEM Event Detector pointer was null when it should contain a value.
(_cerr_sub_err = 27) FH_ETMDELAYZR (zero delay time)This error means that the time specified to arm a timer was zero.
(_cerr_sub_err = 42) FH_ENOTREGISTERED (request for event spec that is unregistered)This error means that the event was not registered.
(_cerr_sub_err = 54) FH_EFDUNAVAIL (connection to event detector unavailable)This error means that the Event Detector was unavailable.
(_cerr_sub_err = 56) FH_EFDCONNERR (event detector connection error)This error means that the EEM Event Detector that handles this request is not available.
timer_cancel
Cancel a timer.
Syntax
timer_cancel [event_id ?]Argument
event_id
Mandatory. The timer event id returned by register_timer command.
Must be an integer number between 0 and 4294967295 inclusive.
Result string
sec_remain %ld msec_remain %ldwhere sec_remain and msec_remain are the remaining time before the next expiration of the timer.
Note
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 6) FH_EBADEVENTTYPE (unknown EEM event type)This error means that the event type specified in the internal event specification was invalid.
(_cerr_sub_err = 7) FH_ENOSUCHKEY (could not find key)This error means that the application Event Detector info key or other ID was not found.
(_cerr_sub_err = 11) FH_ENOSUCHESID (unknown event specification ID)This error means that the event specification ID could not be matched when the event was being registered or an Event Detector internal event structure is corrupt.
(_cerr_sub_err = 12) FH_ENOSUCHEID (unknown event ID)This error means that the event specification ID could not be matched when the event was being registered or an Event Detector internal event structure is corrupt.
(_cerr_sub_err = 22) FH_ENULLPTR (event detector internal error - ptr is null)This error means that en internal EEM Event Detector pointer was null when it should contain a value.
(_cerr_sub_err = 54) FH_EFDUNAVAIL (connection to event detector unavailable)This error means that the Event Detector was unavailable.
(_cerr_sub_err = 56) FH_EFDCONNERR (event detector connection error)This error means that the EEM Event Detector that handles this request is not available.
register_counter
Register a counter and return a counter event id. A counter publisher must perform this registration before using event id to manipulate the counter.
Syntax
register_counter [name ?]Argument
Result string
event_id %d event_spec_id %dwhere event_id is the counter event id for the specified counter; it can be used to manipulate the counter by unregister_counter or counter_modify command. event_spec_id is the event spec. id for the specified counter.
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 4) FH_EINITONCE (Init() is not yet done, or done twice.)This error means that the request to register the specific event was made before the EEM Event Detector had completed it's initialization.
(_cerr_sub_err = 6) FH_EBADEVENTTYPE (unknown EEM event type)This error means that the event type specified in the internal event specification was invalid.
(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)This error means that an internal EEM request for memory failed.
(_cerr_sub_err = 10) FH_ECORRUPT (internal EEM API context is corrupt)This error means that the internal EEM API context structure is corrupt.
(_cerr_sub_err = 11) FH_ENOSUCHESID (unknown event specification ID)This error means that the event specification ID could not be matched when the event was being registered or an Event Detector internal event structure is corrupt.
(_cerr_sub_err = 12) FH_ENOSUCHEID (unknown event ID)This error means that the event specification ID could not be matched when the event was being registered or an Event Detector internal event structure is corrupt.
(_cerr_sub_err = 16) FH_EBADFMPPTR (bad ptr to fh_p data structure)This error means that the context ptr that is used with each EEM API call is incorrect
(_cerr_sub_err = 17) FH_EBADADDRESS (bad API control block address)This error means that a control block address that was passed in the EEM API was incorrect.
(_cerr_sub_err = 22) FH_ENULLPTR (event detector internal error - ptr is null)This error means that en internal EEM Event Detector pointer was null when it should contain a value.
(_cerr_sub_err = 25) FH_ESUBSEXCEED (number of subscribers exceeded)This error means that the number of timer or counter subscribers exceeded the maximum.
(_cerr_sub_err = 26) FH_ESUBSIDXINV (invalid subscriber index)This error means that the subscriber index was invalid.
(_cerr_sub_err = 54) FH_EFDUNAVAIL (connection to event detector unavailable)This error means that the Event Detector was unavailable.
(_cerr_sub_err = 56) FH_EFDCONNERR (event detector connection error)This error means that the EEM Event Detector that handles this request is not available.
unregister_counter
Unregister a counter. A counter publisher uses this to unregister a counter previously registered with the register_counter keyword.
Syntax
unregister_counter [event_id ?] [event_spec_id ?]Arguments
Result string
None.
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)This error means that an internal EEM request for memory failed.
(_cerr_sub_err = 11) FH_ENOSUCHESID (unknown event specification ID)This error means that the event specification ID could not be matched when the event was being registered or an Event Detector internal event structure is corrupt.
(_cerr_sub_err = 22) FH_ENULLPTR (event detector internal error - ptr is null)This error means that en internal EEM Event Detector pointer was null when it should contain a value.
(_cerr_sub_err = 26) FH_ESUBSIDXINV (invalid subscriber index)This error means that the subscriber index was invalid.
(_cerr_sub_err = 54) FH_EFDUNAVAIL (connection to event detector unavailable)This error means that the Event Detector was unavailable.
(_cerr_sub_err = 56) FH_EFDCONNERR (event detector connection error)This error means that the EEM Event Detector that handles this request is not available.
counter_modify
Modify a counter value.
Syntax
counter_modify [event_id ?] [val ?] [op nop|set|inc|dec]Arguments
Result string
val_remain %dwhere val_remain is the current value of the counter.
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 11) FH_ENOSUCHESID (unknown event specification ID)This error means that the event specification ID could not be matched when the event was being registered or an Event Detector internal event structure is corrupt.
(_cerr_sub_err = 22) FH_ENULLPTR (event detector internal error - ptr is null)This error means that en internal EEM Event Detector pointer was null when it should contain a value.
(_cerr_sub_err = 30) FH_ECTBADOPER (bad counter threshold operator)This error means that the counter Event Detector set or modify operator was invalid.
appl_read
This keyword provides support for reading Embedded Event Manager application volatile data. EEM application volatile data can be published by a Cisco IOS software process that uses the EEM application publish API. EEM application volatile data cannot be published by a EEM policy.
Syntax
appl_read [name ?] [length ?]Arguments
name
Mandatory. Name of the application published string data.
length
Mandatory. Length of the string data to read. Must be an integer number between 1 and 4294967295 inclusive
Result string
data %swhere data is the application published string data read.
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 7) FH_ENOSUCHKEY (could not find key)This error means that the application Event Detector info key or other ID was not found.
(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)This error means that an internal EEM request for memory failed.
appl_setinfo
This keyword provides support for saving information in the Embedded Event Manager that can be retrieved later by the same or another policy. A unique key must be specified. This key allows the information to be retrieved later.
Syntax
appl_setinfo [key ?] [data ?]Arguments
Return string
None
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 8) FH_EDUPLICATEKEY (duplicate appl info key)This error means that the application Event Detector info key or other ID was a duplicate.
(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)This error means that an internal EEM request for memory failed.
(_cerr_sub_err = 34) FH_EMAXLEN (maximum length exceeded)This error means that the object length or number exceeded the maximum.
(_cerr_sub_err = 43) FH_EBADLENGTH (bad API length)This error means that API message length was invalid.
appl_reqinfo
This keyword provides support for retrieving information from the Embedded Event Manager that has been previously saved. A unique key must be specified. This key must be the same key that was used when the information was saved. Note that retrieving the information deletes it from the Embedded Event Manager. It must be resaved if it is to be retrieved again.
Syntax
appl_reqinfo [key ?]Arguments
Result string
data %swhere data is the application string data retrieved.
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 7) FH_ENOSUCHKEY (could not find key)This error means that the application Event Detector info key or other ID was not found.
fts_get_stamp
This keyword returns the number of nanoseconds since boot in an array "nsec nnnn" where nnnn is the number of nanoseconds.
Syntax
fts_get_stampArguments
None
Result string
nsec %dwhere nsec is the number of nanoseconds since boot.
Set _cerrno
No
EEM System Information Keywords
Note
Set _cerrno
Yes (for all sys_reqinfo_xxx commands)
sys_reqinfo_syslog_history
Query the history of the syslog message.
Syntax
sys_reqinfo_syslog_historyArguments
NoneResult string
rec_list {{log hist string 0}, {log hist str 1}, ...}where each log hist string is:
time_sec %ld time_msec %ld msg {%s}Value Definitions
time_sec,
time_msecSeconds and milliseconds since 1970 which represents the time the message was logged.
msg
Syslog message.
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 22) FH_ENULLPTR (event detector internal error - ptr is null)This error means that en internal EEM Event Detector pointer was null when it should contain a value.
(_cerr_sub_err = 44) FH_EHISTEMPTY (history list is empty)This error means that the history list was empty.
(_cerr_sub_err = 45) FH_ESEQNUM (sequence or workset number out of sync)This error means that the Event Detector sequence or workset number was invalid.
(_cerr_sub_err = 54) FH_EFDUNAVAIL (connection to event detector unavailable)This error means that the Event Detector was unavailable.
sys_reqinfo_syslog_freq
Query the frequency information of all syslog events.
Syntax
sys_reqinfo_syslog_freqArguments
None
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)This error means that an internal EEM request for memory failed.
(_cerr_sub_err = 22) FH_ENULLPTR (event detector internal error - ptr is null)This error means that en internal EEM Event Detector pointer was null when it should contain a value.
(_cerr_sub_err = 45) FH_ESEQNUM (sequence or workset number out of sync)This error means that the Event Detector sequence or workset number was invalid.
(_cerr_sub_err = 46) FH_EREGEMPTY (registration list is empty)This error means that the Event Detector registration list was emtpy.
(_cerr_sub_err = 54) FH_EFDUNAVAIL (connection to event detector unavailable)This error means that the Event Detector was unavailable.
Result string
rec_list {{event frequency string 0}, {log freq str 1}, ...}where each event frequency string is:
time_sec %ld time_msec %ld match_count %u raise_count %u occurs %uperiod_sec %ld period_msec %ld pattern {%s}Value Definitions
sys_reqinfo_cli_history
Query the history of CLI commands.
Syntax:
sys_reqinfo_cli_historySet_cerrno:
yes
Result string:
rec_list {{CLI history string 0}, {CLI history str 1},...}where each CLI history string is:
time_sec %ld time_nsec %ld cmd {%s}
rec_list
mark the start of CLI command history list.
time_sec
time_nsecthe time when the CLI command occurred.
cmd
text of the CLI command.
sys_reqinfo_cli_freq
Query the frequency information of all CLI events.
Syntax:
sys_reqinfo_cli_freqSet_cerrno:
yes
Result string:
rec_list {{CLI frequency string 0},{CLI frequency str 1}, ...}where each CLI frequency string is:
time_sec %ld time_nsec %ld match_count %u raise_count %u occurs %u period_sec %ld
period_nsec %ld pattern {%s}
sys_reqinfo_routername
Query the router name.
Syntax
sys_reqinfo_routernameArguments
None
Set _cerrno
Yes. None.
Result string
routername %swhere routername is the name of the router.
sys_reqinfo_snmp
Query the value of the entity specified by an SNMP object id.
Syntax:
sys_reqinfo_snmp oid ? get_type exact|next
Set _cerrno:
Yes.
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)This error means that the operating system reported an error. The Posix errno value that is reported with the error should be used to determine the cause of the operating system error.
(_cerr_sub_err = 22) FH_ENULLPTR (event detector internal error - ptr is null)This error means that en internal EEM Event Detector pointer was null when it should contain a value.
(_cerr_sub_err = 37) FH_ENOSNMPDATA (can't retrieve data from SNMP)This error means that there was no data for the SNMP object type.
(_cerr_sub_err = 51) FH_ESTATSTYP (invalid statistics data type)This error means that the SNMP statistics data type was invalid.
(_cerr_sub_err = 54) FH_EFDUNAVAIL (connection to event detector unavailable)This error means that the Event Detector was unavailable.
Result string:
oid {%s} value {%s}
EEM Tcl Library Routines
SMTP Library
All the SMTP library commands belong to the ::cisco::lib namespace.
To use this library, the user needs to provide an email template file. The template file can include Tcl global variables so that the e-mail service and the e-mail text can be configured through the event manager environment varname varvalue configuration command. There are commands in this library to substitute the global variables in the e-mail template file, and to send the desired email context with the To address, CC address, From address, and Subject line properly configured using the configured e-mail server.
E-mail template
The e-mail template file has the following format:
Mailservername:<space><the list of candidate SMTP server addresses>From:<space><the email address of sender>To:<space><the list of email addresses of recipients>Cc:<space><the list of email addresses that the email will be copied to>Subject:<subject line><a blank line><body>
Note
Below is a sample email template file:
Mailservername: $_email_serverFrom: $_email_fromTo: $_email_toCc: $_email_ccSubject: From router $routername: Process terminatedprocess name: $process_namecomponent: $component_idjob ID: $job_idexit status: $exit_statusrespawn count: $respawn_countExported commands
smtp_subst
Given an email template file email_template, substitute each global variable in the file by its user-defined value. Return the text of the file after substitution.
Syntax
smtp_subst email_templateArgument
Result string
The text of the email template file with all the global variables substituted.
Possible error raised
•
•
smtp_send_email
Given the text of an email template file with all global variables already substituted, send the email out using SMTP protocol. The email template specifies the candidate mail server addresses, To: addresses, CC: addresses, From address:, subject line, and email body.
Note that a list of candidate email servers can be provided so that the library will try to connect the servers on the list one by one until it can successfully connect to one of them.
Syntax
smtp_send_email textArgument
Result string
None
Possible errors raised
•
•
•
•
•
•
•
•
Sample scripts
After all needed global variables in the email template are defined:
if [catch {smtp_subst [file join $tcl_library email_template_sm]} result] {puts stderr $resultexit 1}if [catch {smtp_send_email $result} result] {puts stderr $resultexit 1}CLI Library
All CLI Library commands belong to the ::cisco::eem namespace.
This library provides users the ability to run CLI commands and get the output of the commands in Tcl. Users can use commands in this library to spawn an exec and open a Virtual Terminal channel to it, write the command to execute to the channel so that the command will be executed by exec, and read the output of the command back.
There are two types of CLI commands: interactive commands and non-interactive commands.
For interactive commands, after the command is entered, there will be a "Q&A" phase in which the router will prompt questions asking for different user options, and the user is supposed to type the answer for each question. Only after all the questions have been answered properly, will the command run according to the user's options until completion.
For non-interactive commands, once the command is entered, the command will run to completion. To run different types of commands, different CLI library command sequences should be used, which are documented in the "Using CLI library to run a non-interactive command" section and the "Using CLI library to run an interactive command" section.
Exported commands
cli_open
Spawn an exec, open a channel to it, and return the channel handler.
Syntax
cli_openArguments
None
Result string
An array string that contains:
•
•
•
•
Set_cerrno
•
•
•
cli_exec
Write the command cmd to the channel whose handler is given by fd to execute the command. Then read the output of the command from the channel and return the output.
Syntax
cli_exec fd cmdArguments
Result string
The output of the CLI command executed
Set_cerrno
Error reading the channel.
cli_close
Close the exec process and the CLI channel connected to it given the handler of the channel fd.
Syntax
cli_close fd tty_idArguments
Result string
None
Set_cerrno
Cannot close the channel.
cli_write
Write the command cmd to the channel whose handler is given by fd to execute the command.
Syntax
cli_write fd cmdArguments
Result string
None
Set_cerrno
None
cli_read_pattern
Read the command output from the CLI channel whose handler is given by fd until the pattern ptn occurs in the contents read. Return all the contents read up to the match.
Syntax
cli_read_pattern fd ptnArguments
fd
Mandatory; the CLI channel handler.
ptn
Mandatory; the pattern to match when reading the command output from the channel.
Result string
All the contents read.
Set_cerrno
None
Note
cli_read
Read the command output from the CLI channel whose handler is given by fd until the pattern of the router prompt occurs in the contents read. Return all the contents read up to the match.
Syntax
cli_read fdArgument
Result string
All the contents read.
Set_cerrno
Cannot get router name.
Note
cli_read_line
Read one line of the command output from the CLI channel whose handler is given by fd. Return the line read.
Syntax
cli_read_line fdArgument
Result string
The line read.
Set_cerrno
None
Note
cli_read_drain
Read and drain the command output of the CLI channel whose handler is given by fd. Return all the contents read.
Syntax
cli_read_drain fdArgument
Result string
All the contents read.
Set_cerrno
None
cli_get_ttyname
This keyword returns the real and pseudo tty names for a given TTY ID.
Syntax
cli_get_ttyname tty_idArgument
Result string
pty %s tty %sSet_cerrno
None
Sample Usage
As an example: use configuration CLI commands to bring up the Ethernet1/0 interface:
if [catch {cli_open} result] {puts stderr $resultexit 1} else {set fd $result}if [catch {cli_exec $fd "en"} result] {puts stderr $resultexit 1}if [catch {cli_exec $fd "config t"} result] {puts stderr $resultexit 1}if [catch {cli_exec $fd "interface Ethernet1/0"} result] {puts stderr $resultexit 1}if [catch {cli_exec $fd "no shut"} result] {puts stderr $resultexit 1}if [catch {cli_exec $fd "end"} result] {puts stderr $resultexit 1}if [catch {cli_close $fd} result] {puts stderr $resultexit 1Using CLI library to run a non-interactive command
To run a non-interactive command, use cli_exec to issue the command, then wait for the complete output and the router prompt. For example, the following show the use of configuration CLI commands to bring up the interface Ethernet1/0:
if [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 [catch {cli_exec $cli1(fd) "interface Ethernet1/0"} result] {error $result $errorInfo}if [catch {cli_exec $cli1(fd) "no shut"} result] {error $result $errorInfo}if [catch {cli_exec $cli1(fd) "end"} result] {error $result $errorInfo}if [catch {cli_close $cli1(fd)} result] {error $result $errorInfo}Using CLI library to run an interactive command
To run interactive commands, we need three phases:
•
•
•
For example, use CLI commands to do squeeze bootflash: and save the output of this command in the Tcl variable cmd_output.
if [catch {cli_open} result] {error $result $errorInfo} else {set fd $result}if [catch {cli_exec $fd "en"} result] {error $result $errorInfo}# Phase 1: issue the commandif [catch {cli_write $fd "squeeze bootflash:"} result] {error $result $errorInfo}# Phase 2: Q&A phase# wait for prompted question:# All deleted files will be removed. Continue? [confirm]if [catch {cli_read_pattern $fd "All deleted"} result] {error $result $errorInfo}# if the answer is a newline characterif [catch {cli_write $fd "\n"} result] {error $result $errorInfo}# wait for prompted question:# Squeeze operation may take a while. Continue? [confirm]if [catch {cli_read_pattern $fd "Squeeze operation"} result] {error $result $errorInfo}# if the answer is a newline characterif [catch {cli_write $fd "\n"} result] {error $result $errorInfo}# Phase 3: non-interactive phaseif [catch {cli_read $fd} result] {error $result $errorInfo} else {set cmd_output $result}if [catch {cli_close $fd} result] {error $result $errorInfo}The following example causes a router to be reloaded using the CLI reload command. Note that the EEM action_reload command accomplishes the same result in a more efficient manner but this example is presented to illustrate the flexibility of the CLI Library for interactive command execution.
# 1. execute the reload commandif [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_write $cli1(fd) "reload"} result] {error $result $errorInfo} else {set cmd_output $result}if [catch {cli_read_pattern $cli1(fd) ".*(System configuration has been modified. Save\\\? \\\[yes/no\\\]: )"} result] {error $result $errorInfo} else {set cmd_output $result}if [catch {cli_write $cli1(fd) "no"} result] {error $result $errorInfo} else {set cmd_output $result}if [catch {cli_read_pattern $cli1(fd) ".*(Proceed with reload\\\? \\\[confirm\\\])"} result] {error $result $errorInfo} else {set cmd_output $result}if [catch {cli_write $cli1(fd) "y"} result] {error $result $errorInfo} else {set cmd_output $result}if [catch {cli_close $cli1(fd) $cli1(tty_id)} result] {error $result $errorInfo}EEM Context Library
All the Tcl Context Library commands belong to the ::cisco::eem namespace.
Exported commands
context_save
Save Tcl variables that match the given pattern in current and global namespaces with the given context name as identification.
Use this keyword to save information outside of a policy. Saved information can be retrieved by a different policy using context_retrieve.
Note
Syntax
context_save ctxt patternArguments
Result string
None.
Set_cerrno
A string displaying _cerrno, _cerr_sub_num, _cerr_sub_err, _cerr_posix_err, _cerr_str due to appl_setinfo error.context_retrieve
Retrieve Tcl variable(s) identified by the given context name, and possibly the scalar variable name, the array variable name, and the array index. Retrieved information is automatically deleted (see Note section above).
Syntax
context_retrieve ctxt var index_if_arrayArguments
ctxt
Mandatory. Context name.
var
Optional. Scalar variable name or array variable name.
index_if_array
Optional. The array index.
Note
If var is unspecified, retrieve the whole variable table saved in the context.
If var is specified, and index_if_array is unspecified, or index_if_array is specified but var is a scalar variable, retrieve the value of var.
If var is specified, and index_if_array is specified, and var is an array variable, retrieve the value of the specified array element.
Set_cerrno
•
•
Sample Usage
Policy a.tcl
# Save all Tcl global variables whose names start with the string "EEMVars"# to the context name "EEMV". This is usually done right before exiting.if [catch {context_save "EEMV" "EEMVars*"} result] {error $result $errorInfo}Policy b.tcl
# Retrieve all Tcl global variables from the context name "EEMV"if [catch {context_retrieve "EEMV"} result] {error $result $errorInfo}EEM Sample Policy
This section contains the two sample policies that are included as EEM system policies in all IOS images. The procedures to run these policies are contained in the EEM Event Detector Demo: Example section of the Embedded Event Manager 2.1 feature in Cisco IOS Release 12.3(14)T.
•
tm_cli_cmd.tcl Sample Policy
The following sample runs a configurable CRON entry. The policy will execute a configurable Cisco IOS CLI command and e-mail the results.
::cisco::eem::event_register_timer cron name crontimer2 cron_entry $_cron_entry maxrun 240# register for cron timer using user-defined cron entry# 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 ""}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 show commandif [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) $_show_cmd} result] {error $result $errorInfo} else {set cmd_output $result}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. send the email outset 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 runs when a configurable syslog message is logged. The policy will execute a configurable CLI command and e-mail the results.
::cisco::eem::event_register_syslog occurs 1 pattern $_syslog_pattern maxrun 90# register for interface down event# 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_cmd.tmMailservername: $_email_serverFrom: $_email_fromTo: $_email_toCc: $_email_ccSubject: From router $routername: Periodic $_show_cmd Output$cmd_outputDebugging Embedded Event Manager Policies
cli_debug
This keyword prints a debug statement to syslog if the debug event manager tcl cli_lib is in effect.
Syntax
cli_debug spec_string debug_stringArguments
spec_string
Mandatory. The spec_string argument is used to indicate the type of debug statement.
debug_string
Mandatory. The debug_string argument is used to indicate the debugging text.
Result string
None.
Set_cerrno
No
Debugging the CLI Library
The CLI library allows users to run CLI commands and obtain the output of commands in Tcl. A 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 will display all data that is passed in, and read back from the TTY session that handles the CLI interactions. This data will help ensure users that the commands they are passing to the CLI are valid.
Example of "debug event manager tcl cli_library"
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 debug event manager tcl cli_library 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>en01: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#config t01: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 eve man env01: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 eve man env01:17:07: %SYS-5-CONFIG_I: Configured from console by vty0The output above shows that show eve man env is an invalid command in configuration mode.
The IN keyword signifies all data passed into the TTY through CLI library
The OUT keyword signifies all data read back from the TTY through CLI library
The CTL keyword signifies helper functions used in the CLI library. These commands are used to set up and remove connections to the CLI.
Debugging the SMTP Library
smtp_debug
This keyword prints a debug statement to syslog if the debug event manager tcl smtp_lib is in effect.
Syntax
smtp_debug spec_string debug_stringArguments
spec_string
Mandatory. The spec_string argument is used to indicate the type of debug statement.
debug_string
Mandatory. The debug_string argument is used to indicate the debugging text.
Result string
None.
Set_cerrno
No
The SMTP library allows users to send email messages to an SMTP email 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 will display all data that is passed in, and read back from the SMTP library routines. This data will help ensure users that the commands they are passing to the SMTP library are valid.
Example of "debug event manager tcl smtp_library"
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.
With debug event manager tcl smtp_library enabled the users sees the following on the console:
00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 220 XXXX.cisco.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.cisco.com00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 XXXX.cisco.com Hello XXXX.cisco.com [XXXX], pleased to meet you00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : MAIL FROM:<XX@cisco.com>00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 <XX@cisco.com>... Sender ok00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : RCPT TO:<XX@cisco.com>00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 <XX@cisco.com>... Recipient ok00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : RCPT TO:<XX@cisco.com>00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 <XX@cisco.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.cisco.com>00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : From: XX@cisco.com00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : To: XX@cisco.com00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : Cc: XX@cisco.com00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : Subject: From router nelson: Periodic show fau 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.cisco.com closing connectionThe output will help debug any issues related to using the SMTP library.
Tracing Tcl "set" Operations
Tcl allows you to override commands as it contains no reserved words. You can modify the set command to display a message when a scalar variable is 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 will be displayed anytime a scalar variable is set:Example:02:17:58: sl_intf_down.tcl[0]: setting test_var 1Safe-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 systems directories.
The following list of Tcl commands are restricted with a few exceptions. Restrictions are noted against each command or command keyword:
•
•
•
•
•
–
–
–
–
–
–
–
–
–
–
•
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
•
•
•
•
•
•
Additional References
The following sections provide references related to writing Embedded Event Manager policies.
Related Documents
EEM commands: complete command syntax, defaults, command mode, command history, usage guidelines, and examples
Cisco IOS Configuration Fundamentals and Network Management Command Reference, Release 12.3T
Embedded Event Manager 2.1
Embedded Event Manager 2.1 feature document, Release 12.3(14)T
Standards
No new or modified Standards are supported by this feature, and support for existing Standards has not been modified by this feature.
—
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
Copyright © 2005 Cisco Systems, Inc. All rights reserved.
