The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This module describes how software developers can write and customize Embedded Event Manager (EEM) policies using Tool command language (Tcl) scripts to handle Cisco IOS XE software faults and events. EEM is a policy-driven process by means of which faults in the Cisco IOS XE 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.
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 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.
•Prerequisites for Writing Embedded Event Manager Policies Using Tcl
•Information About Writing Embedded Event Manager Policies Using Tcl
•How to Write Embedded Event Manager Policies Using Tcl
•Configuration Examples for Writing Embedded Event Manager Policies Using Tcl
•EEM Policy Tcl Command Extension Reference
•Feature Information for Writing Embedded Event Manager Policies Using Tcl
•Before writing EEM policies, you should be familiar with the "Embedded Event Manager Overview" module.
•If you want to write EEM policies using the command-line interface (CLI) commands, you should be familiar with the "Writing Embedded Event Manager Policies Using the Cisco IOS XE software CLI" module.
To write EEM policies using Tcl, you should understand the following concepts:
•EEM Policy Tcl Command Extension Categories
•General Flow of EEM Event Detection and Recovery
•Cisco File Naming Convention for EEM
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 XE software CLI, see the "Writing Embedded Event Manager Policies Using the Cisco IOS XE software 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:
•Selecting the event Tcl command extension that establishes the criteria used to determine when the policy is run.
•Defining the event detector options associated with detecting the event.
•Choosing the actions to implement recovery or respond to the detected event.
The CLI-based corrective actions that are taken when event detectors report events enable a powerful on-device event management mechanism. The following actions are available in Cisco IOS XE software releases:
•Execute a CLI command
•Generate a CNS event
•Generate an SNMP trap
•Generate a prioritized syslog message
•Manually run an EEM policy
•Publish an application-specific event
•Reload the Cisco IOS XE software
•Request system information
•Send a short e-mail
•Set or modify a counter
•Switch to a secondary RP
For more details on each action, see the Embedded Event Actions concept in the "Embedded Event Manager Overview" module.
There are different categories of EEM policy Tcl command extensions.
Note The Tcl command extensions available in each of these categories for use in all EEM policies are described in later sections in this document.
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 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 XE software 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:
•cd—Change directory is not allowed to one of the restricted Cisco directory names.
•encoding—The commands encoding names, encoding convertfrom, and encoding convertto are permitted. The encoding system command with no arguments is permitted, but the encoding system command with the ?encoding? keyword is not permitted.
•exec—Not permitted.
•fconfigure—Permitted.
•file—The following are permitted:
–file dirname
–file exists
–file extension
–file isdirectory
–file join
–file pathtype
–file rootname
–file split
–file stat
–file tail
•file—The following are not permitted:
–file atime
–file attributes
–file channels
–file copy
–file delete
–file executable
–file isfile
–file link
–file lstat
–file mkdir
–file mtime
–file nativename
–file normalize
–file owned
–file readable
–file readlink
–file rename
–file rootname
–file separator
–file size
–file system
–file type
–file volumes
–file writable
•glob—The glob command is not permitted when searching in one of the restricted Cisco directories. Otherwise, it is permitted.
•load—Only files that are in the user policy directory or the user library directory are permitted to be loaded. Static packages (for example, libraries that consist of C code) are not permitted to be loaded with the load command.
•open—The open command is not allowed for a file that is located in one of the restricted Cisco directories.
•pwd—The pwd command is not permitted.
•socket—The socket command is permitted.
•source—The source command is permitted for files that are in the user policy directory or the user library directory.
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:
•An optional prefix—Mandatory.—indicating, if present, that this is a system policy that should be registered automatically at boot time if it is not already registered. For example: Mandatory.sl_text.tcl.
•A filename body part containing a two-character abbreviation (see Table 2) for the first event specified; an underscore part; and a descriptive field part that further identifies the policy.
•A filename suffix part defined as .tcl.
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.
This section contains the following tasks:
•Registering and Defining an EEM Tcl Script
•Displaying EEM Registered Policies
•Suspending EEM Policy Execution
•Modifying History Table Size and Displaying EEM History Data
•Modifying the Sample EEM Policies
•Programming EEM Policies with Tcl
•Creating an EEM User Tcl Library Index
•Creating an EEM User Tcl Package Index
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.
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.
1. enable
2. show event manager environment [all | variable-name]
3. configure terminal
4. event manager environment variable-name string
5. Repeat Step 4 to configure all the environment variables required by the policy to be registered in Step 6.
6. event manager policy policy-filename [type {system | user}] [trap]
7. exit
|
|
|
---|---|---|
Step 1 |
enable Router> enable |
Enables privileged EXEC mode. •Enter your password if prompted. |
Step 2 |
show event manager environment [all | variable-name] Router# show event manager environment all |
(Optional) Displays the name and value of EEM environment variables. •The optional all keyword displays all the EEM environment variables. •The optional variable-name argument displays information about the specified environment variable. |
Step 3 |
configure terminal Router# configure terminal |
Enters global configuration mode. |
Step 4 |
event manager environment variable-name string Router(config)# event manager environment _cron_entry 0-59/2 0-23/1 * * 0-6 |
Configures the value of the specified EEM environment variable. •In this example, the software assigns a CRON timer environment variable to be set to the second minute of every hour of every day. |
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] 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. •Use the system keyword to register a Cisco-defined system policy. •Use the user keyword to register a user-defined system policy. •Use the trap keyword to generate an SNMP trap when the policy is triggered. •In this example, the sample EEM policy named tm_cli_cmd.tcl is registered as a system policy. |
Step 7 |
exit Router(config)# exit |
Exits global configuration mode and returns to privileged EXEC mode. |
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 all
No. Name Value
1 _cron_entry 0-59/2 0-23/1 * * 0-6
2 _show_cmd show ver
3 _syslog_pattern .*UPDOWN.*FastEthernet1/0.*
4 _config_cmd1 interface FastEthernet1/0
5 _config_cmd2 no shut
Perform this optional task to display EEM registered policies.
1. enable
2. show event manager policy registered [event-type event-name] [time-ordered | name-ordered] [detailed policy-filename]
Step 1 enable
Enables privileged EXEC mode. Enter your password if prompted.
Router> enable
Step 2 show event manager policy registered [event-type event-name] [time-ordered | name-ordered] [detailed policy-filename]
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-ordered
No. Type Event Type Trap Time Registered Name
1 system timer cron Off Wed May11 01:43:18 2005 tm_cli_cmd.tcl
name {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}
nice 0 priority normal maxrun 240
2 system syslog Off Wed May11 01:43:28 2005 sl_intf_down.tcl
occurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}
nice 0 priority normal maxrun 90
3 system proc abort Off Wed May11 01:43:38 2005 pr_cdp_abort.tcl
instance 1 path {cdp2.iosproc}
nice 0 priority normal maxrun 20
Use 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-ordered
No. Type Event Type Trap Time Registered Name
1 system proc abort Off Wed May11 01:43:38 2005 pr_cdp_abort.tcl
instance 1 path {cdp2.iosproc}
nice 0 priority normal maxrun 20
2 system syslog Off Wed May11 01:43:28 2005 sl_intf_down.tcl
occurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}
nice 0 priority normal maxrun 90
3 system timer cron Off Wed May11 01:43:18 2005 tm_cli_cmd.tcl
name {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}
nice 0 priority normal maxrun 240
Use 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 syslog
No. Type Event Type Time Registered Name
1 system syslog Wed May11 01:43:28 2005 sl_intf_down.tcl
occurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}
nice 0 priority normal maxrun 90
Perform this task to remove an EEM policy from the running configuration file. Execution of the policy is canceled.
1. enable
2. show event manager policy registered [event-type event-name] [system | user] [time-ordered | name-ordered] [detailed policy-filename]
3. configure terminal
4. no event manager policy policy-filename
5. exit
6. Repeat Step 2 to ensure that the policy has been removed.
|
|
|
---|---|---|
Step 1 |
enable Router> enable |
Enables privileged EXEC mode. •Enter your password if prompted. |
Step 2 |
show event manager policy registered [event-type event-name] [system | user] [time-ordered | name-ordered] [detailed policy-filename] Router# show event manager policy registered |
(Optional) Displays the EEM policies that are currently registered. •The optional system or user keyword displays the registered system or user policies. •If no keywords are specified, EEM registered policies for all event types are displayed in time order. |
Step 3 |
configure terminal Router# configure terminal |
Enters global configuration mode. |
Step 4 |
no event manager policy policy-filename Router(config)# no event manager policy pr_cdp_abort.tcl |
Removes the EEM policy from the configuration, causing the policy to be unregistered. •In this example, the no form of the command is used to unregister a specified policy. |
Step 5 |
exit 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. Router# show event manager policy registered |
— |
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 registered
No. Type Event Type Trap Time Registered Name
1 system timer cron Off Tue Oct11 01:43:18 2005 tm_cli_cmd.tcl
name {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}
nice 0 priority normal maxrun 240.000
2 system syslog Off Tue Oct11 01:43:28 2005 sl_intf_down.tcl
occurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}
nice 0 priority normal maxrun 90.000
3 system proc abort Off Tue Oct11 01:43:38 2005 pr_cdp_abort.tcl
instance 1 path {cdp2.iosproc}
nice 0 priority normal maxrun 20.000
After 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 terminal
Router(config)# no event manager policy pr_cdp_abort.tcl
Router(config)# exit
The 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 registered
No. Type Event Type Trap Time Registered Name
1 system timer cron Off Tue Oct11 01:45:17 2005 tm_cli_cmd.tcl
name {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}
nice 0 priority normal maxrun 240.000
2 system syslog Off Tue Oct11 01:45:27 2005 sl_intf_down.tcl
occurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}
nice 0 priority normal maxrun 90.000
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.
1. enable
2. show event manager policy registered [event-type event-name] [system | user] [time-ordered | name-ordered] [detailed policy-filename]
3. configure terminal
4. event manager scheduler suspend
5. exit
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 registered
No. Type Event Type Trap Time Registered Name
1 system timer cron Off Sat Oct11 01:43:18 2003 tm_cli_cmd.tcl
name {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}
nice 0 priority normal maxrun 240.000
2 system syslog Off Sat Oct11 01:43:28 2003 sl_intf_down.tcl
occurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}
nice 0 priority normal maxrun 90.000
3 system proc abort Off Sat Oct11 01:43:38 2003 pr_cdp_abort.tcl
instance 1 path {cdp2.iosproc}
nice 0 priority normal maxrun 20.000
The event manager scheduler suspend command is entered to immediately suspend the execution of all EEM policies:
Router# configure terminal
Router(config)# event manager scheduler suspend
*Nov 2 15:34:39.000: %HA_EM-6-FMS_POLICY_EXEC: fh_io_msg: Policy execution has been suspended
Perform this task to specify a directory to use for storing user library files or user-defined EEM policies.
Note This task applies only to EEM policies that are written using Tcl scripts.
1. enable
2. show event manager directory user [library | policy]
3. configure terminal
4. event manager directory user {library path | policy path}
5. exit
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 library
disk0:/usr/lib/tcl
Perform this optional task to change the size of the history tables and to display EEM history data.
1. enable
2. configure terminal
3. event manager history size {events | traps} [size]
4. exit
5. show event manager history events [detailed] [maximum number]
6. show event manager history traps {server | policy}
Step 1 enable
Enables privileged EXEC mode. Enter your password if prompted.
Router> enable
Step 2 configure terminal
Enters global configuration mode.
Router# configure terminal
Step 3 event manager history size {events | traps} [size]
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 30
Step 4 exit
Exits global configuration mode and returns to privileged EXEC mode.
Router(config)# exit
Step 5 show event manager history events [detailed] [maximum number]
Use this command to display information about each EEM event that has been triggered.
Router# show event manager history events
No. Time of Event Event Type Name
1 Fri Sep 9 13:48:40 2005 syslog applet: one
2 Fri Sep 9 13:48:40 2005 syslog applet: two
3 Fri Sep 9 13:48:40 2005 syslog applet: three
4 Fri Sep 9 13:50:00 2005 timer cron script: tm_cli_cmd.tcl
5 Fri Sep 9 13:51:00 2005 timer cron script: tm_cli_cmd.tcl
Step 6 show event manager history traps [server | policy]
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 traps
No. Time Trap Type Name
1 Fri Sep 9 13:48:40 2005 server applet: four
2 Fri Sep 9 13:57:03 2005 policy script: no_snmp_test.tcl
Perform this task to modify one of the sample policies. Cisco IOS XE 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.
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: Example" section.
1. enable
2. show event manager policy available detailed policy-filename
3. Cut and paste the contents of the sample policy displayed on the screen to a text editor.
4. Edit the policy and save it with a new filename.
5. Copy the new file back to the router flash memory.
6. configure terminal
7. event manager directory user {library path | policy path}
8. event manager policy policy-filename [type {system | user}] [trap]
Step 1 enable
Enables privileged EXEC mode. Enter your password if prompted.
Router> enable
Step 2 show event manager policy available detailed policy-filename
Displays the actual specified sample policy including details about the environment variables used by the policy and instructions for running the policy. 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.tcl
Step 3 Cut and paste the contents of the sample policy displayed on the screen to a text editor.
Use the edit and copy functions to move the contents from the router to a text editor on another device.
Step 4 Edit the policy and save it with a new filename.
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 new file back to the router flash memory.
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 XE Software File System" chapter in the Cisco IOS XE Software Configuration Fundamentals Configuration Guide.
Step 6 configure terminal
Enters global configuration mode.
Router# configure terminal
Step 7 event manager directory user {library path | policy path}
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_library
Step 8 event manager policy policy-filename [type {system | user}] [trap]
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
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.
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 240
The 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 $errorInfo
The 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 event_reqinfo event information Tcl command extension that is used to query the EEM for information about the detected event. For a list of the available EEM event information Tcl command extensions, see the "EEM Event Information Tcl Command Extension" section.
•The action Tcl command extensions, such as action_syslog, that are used to specify EEM specific actions. For a list of the available EEM action Tcl command extensions, see the "EEM Action Tcl Command Extensions" section.
•The system information Tcl command extensions, such as sys_reqinfo_routername, that are used to obtain general system information. For a list of the available EEM system information Tcl command extensions, see the "EEM System Information Tcl Command Extensions" section.
•Use of the SMTP library (to send e-mail notifications) or the CLI library (to run CLI commands) from a policy. For a list of the available SMTP library Tcl command extensions, see the "SMTP Library Command Extensions" section. For a list of the available CLI library Tcl command extensions, see the "CLI Library Command Extensions" section.
•The context_save and context_retrieve Tcl command extensions that are used to save Tcl variables for use by other policies.
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_sec
set 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 $msg
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
}
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).
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.
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:
XYSSSSSSSSSSSSSEEEEEEEEPPPPPPPPP
For example, the following error return value might be returned from an EEM Tcl command extension:
862439AE
This number is interpreted as the following 32-bit value:
10000110001001000011100110101110
This 32-bit integer is divided up into the five variables shown in Table 4.
|
|
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 |
|
|
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.
:
00 |
CERR_CLASS_SUCCESS |
01 |
CERR_CLASS_INFO |
10 |
CERR_CLASS_WARNING |
11 |
CERR_CLASS_FATAL |
An error return value of zero means SUCCESS.
1. enable
2. show event manager policy available detailed policy-filename
3. Cut and paste the contents of the sample policy displayed on the screen to a text editor.
4. Define the required event_register Tcl command extension.
5. Add the appropriate namespace under the ::cisco hierarchy.
6. Program the must defines section to check for each environment variable that is used in this policy.
7. Program the body of the script.
8. Check the entry status to determine if a policy has previously run for this event.
9. Check the exit status to determine whether or not to apply the default action for this event, if a default action exists.
10. Set Cisco Error Number (_cerrno) Tcl global variables.
11. Save the Tcl script with a new filename, and copy the Tcl script to the router.
12. configure terminal
13. event manager directory user {library path | policy path}
14. event manager policy policy-filename [type {system | user}] [trap]
15. Cause the policy to execute, and observe the policy.
16. Use debugging techniques if the policy does not execute correctly.
Step 1 enable
Enables privileged EXEC mode. Enter your password if prompted.
Router> enable
Step 2 show event manager policy available detailed policy-filename
Displays the actual specified sample policy including details about the environment variables used by the policy and instructions for running the policy. 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.tcl
Step 3 Cut and paste the contents of the sample policy displayed on the screen to a text editor.
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 Define the required event_register Tcl command extension.
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 Add the appropriate namespace under the ::cisco hierarchy.
Policy developers can use the new namespace ::cisco in Tcl policies in order to group all the extensions used by Cisco IOS XE software 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 Make sure that you import the appropriate namespaces or use the qualified command names when using the above commands.
Step 6 Program the must defines section to check for each environment variable that is used in this policy.
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 You can display the Embedded Event Manager environment variables set on your system by using the show event manager environment privileged EXEC command.
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 Program the body of the script.
In this section of the script, you can define any of the following:
•The event_reqinfo event information Tcl command extension that is used to query the EEM for information about the detected event.
•The action Tcl command extensions, such as action_syslog, that are used to specify EEM specific actions.
•The system information Tcl command extensions, such as sys_reqinfo_routername, that are used to obtain general system information.
•The context_save and context_retrieve Tcl command extensions that are used to save Tcl variables for use by other policies.
•Use of the SMTP library (to send e-mail notifications) or the CLI library (to run CLI commands) from a policy.
Step 8 Check the entry status to determine if a policy has previously run for this 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).
Step 9 Check the exit status to determine whether or not to apply the default action for this event, if a default action exists.
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 Set Cisco Error Number (_cerrno) Tcl global variables.
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
}
Step 11 Save the Tcl script with a new filename, and copy the Tcl script to the router.
Embedded Event Manager policy filenames adhere to the following specification:
•An optional prefix—Mandatory.—indicating, if present, that this is a system policy that should be registered automatically at boot time if it is not already registered. For example: Mandatory.sl_text.tcl.
•A filename body part containing a two-character abbreviation (see Table 2) for the first event specified; an underscore character part; and a descriptive field part further identifying the policy.
•A filename suffix part defined as .tcl.
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 XE Software File System" chapter in the Cisco IOS XE Software Configuration Fundamentals Configuration Guide.
Step 12 configure terminal
Enters global configuration mode.
Router# configure terminal
Step 13 event manager directory user {library path | policy path}
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_library
Step 14 event manager policy policy-filename [type {system | user}] [trap]
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 user
Step 15 Cause the policy to execute, and observe the policy.
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 debugging techniques if the policy does not execute correctly.
Use the Cisco IOS XE software 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.
•Use the debug event manager tcl commands CLI command to debug issues with Tcl extension commands. 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 they are passing to the CLI are valid.
•The CLI library allows users to run CLI commands and obtain the output of commands in Tcl. Use the debug event manager tcl cli-library CLI command to debug issues with the CLI library.
•The SMTP library allows users to send e-mail messages to an SMTP e-mail server. Use the debug event manager tcl smtp_library CLI command to debug issues with the 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 they are passing to the SMTP library are valid.
•Tcl is a flexible language that allows you to override commands. For example, you can modify the set command and create a version of the set command that displays a message when a scalar variable is set. When the set command is entered in a policy, a message is displayed anytime a scalar variable is set, and this provides a way to debug scalar variables. To view an example of this debugging technique, see the "Tracing Tcl set Command Operations: Example" section.
To view examples of the some of these debugging techniques, see the "Debugging Embedded Event Manager Policies: Examples" section.
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.
1. On your workstation (UNIX, Linux, PC, or Mac) create a library directory and copy the Tcl library files into the directory.
2. tclsh
3. auto_mkindex directory_name *.tcl
4. Copy the Tcl library files from Step 1 and the tclIndex file from Step 3 to the directory used for storing user library files on the target router.
5. Copy a user-defined EEM policy file written in Tcl to the directory used for storing user-defined EEM policies on the target router.
6. enable
7. configure terminal
8. event manager directory user {library path | policy path}
9. event manager directory user {library path | policy path}
10. event manager policy policy-filename [type {system | user}] [trap]
11. event manager run policy-filename
Step 1 On your workstation (UNIX, Linux, PC, or Mac) create a library directory and copy the Tcl library files into the directory.
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 tclsh
Use this command to enter the Tcl shell.
workstation% tclsh
Step 3 auto_mkindex directory_name *.tcl
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 *.tcl
The 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 Copy the Tcl library files from Step 1 and the tclIndex file from Step 3 to the directory used for storing user library files on the target router.
Step 5 Copy a user-defined EEM policy file written in Tcl to the directory used for storing user-defined EEM policies on the target router. The directory can be the same directory used in Step 4.
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_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
global auto_index auto_path
puts [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 enable
Enables privileged EXEC mode. Enter your password if prompted.
Router> enable
Step 7 configure terminal
Enables global configuration mode.
Router# configure terminal
Step 8 event manager directory user {library path | policy path}
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_library
Step 9 event manager directory user {library path | policy path}
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_policies
Step 10 event manager policy policy-name [type {system | user} [trap]
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.tcl
Step 11 event manager run policy-name
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.tcl
The following output is displayed:
01:24:37: %HA_EM-6-LOG: libtest.tcl: In procedure test1
01:24:37: %HA_EM-6-LOG: libtest.tcl: In procedure test2
01:24:37: %HA_EM-6-LOG: libtest.tcl: In procedure test3
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.
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 Packages implemented in C programming code are not supported in EEM.
1. On your workstation (UNIX, Linux, PC, or Mac) create a library directory and copy the Tcl package files into the directory.
2. tclsh
3. pkg_mkIndex directory_name *.tcl
4. Copy the Tcl package files from Step 1 and the pkgIndex file from Step 3 to the directory used for storing user library files on the target router.
5. Copy a user-defined EEM policy file written in Tcl to the directory used for storing user-defined EEM policies on the target router.
6. enable
7. configure terminal
8. event manager directory user {library path | policy path}
9. event manager directory user {library path | policy path}
10. event manager policy policy-filename [type {system | user}] [trap]
11. event manager run policy-filename
Step 1 On your workstation (UNIX, Linux, PC, or Mac) create a library directory and copy the Tcl package files into the directory.
Step 2 tclsh
Use this command to enter the Tcl shell.
workstation% tclsh
Step 3 pkg_mkindex directory_name *.tcl
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 *.tcl
The 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 Copy the Tcl library files from Step 1 and the pkgIndex file from Step 3 to the directory used for storing user library files on the target router.
Step 5 Copy a user-defined EEM policy file written in Tcl to the directory used for storing user-defined EEM policies on the target router. The directory can be the same directory used in Step 4.
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 xmlrpc
puts "Did you get an error?"
Step 6 enable
Enables privileged EXEC mode. Enter your password if prompted.
Router> enable
Step 7 configure terminal
Enables global configuration mode.
Router# configure terminal
Step 8 event manager directory user {library path | policy path}
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_library
Step 9 event manager directory user {library path | policy path}
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_policies
Step 10 event manager policy policy-name [type {system | user} [trap]
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.tcl
Step 11 event manager run policy-name
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
This section contains the following configuration examples:
•Assigning a Username for a Tcl Session: Example
•EEM Event Detector Demo: Example
•Programming Policies with Tcl: Sample Scripts Example
•Debugging Embedded Event Manager Policies: Examples
•Tracing Tcl set Command Operations: Example
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 terminal
event manager session cli username yourname
end
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
•Event Manager Environment Variables for the Sample Policies
•Registration of Some EEM Policies
•Basic Configuration Details for All Sample Policies
EEM Sample Policy Descriptions
This configuration example features four of the sample EEM policies:
•sl_intf_down.tcl—Is run when a configurable syslog message is logged. It executes up to two configurable CLI commands and e-mails the results.
•tm_cli_cmd.tcl—Is run using a configurable CRON entry. It executes a configurable CLI command and e-mails the results.
•tm_crash_reporter.tcl—Is run 5 seconds after it is registered and 5 seconds after the router boots up. 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.
•tm_fsys_usage.tcl—This policy runs using a configurable CRON entry and monitors disk space usage. A syslog message is displayed if disk space usage crosses configurable thresholds.
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:
•_cron_entry in the tm_cli_cmd.tcl policy
•_syslog_pattern in the sl_intf_down.tcl policy
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 cpu
ip domain-name example.com
event manager environment _email_server ms.example.net
event manager environment _email_to username@example.net
event manager environment _email_from engineer@example.net
event manager environment _email_cc projectgroup@example.net
event manager environment _cron_entry 0-59/2 0-23/1 * * 0-7
event manager environment _show_cmd show event manager policy registered
event manager environment _syslog_pattern .*UPDOWN.*FastEthernet0/0
event manager environment _config_cmd1 interface FastEthernet1/0
event manager environment _config_cmd2 no shutdown
event manager environment _crash_reporter_debug 1
event manager environment _crash_reporter_url http://www.example.com/fm/interface_tm.cgi
end
Using 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
•Running the tm_cli_cmd.tcl Sample Policy
•Running the tm_crash_reporter.tcl Sample Policy
•Running the tm_fsys_usage.tcl Sample Policy
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.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy sl_intf_down.tcl
end
show event manager policy registered
show event manager environment
Running 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.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy tm_cli_cmd.tcl
end
show event manager policy registered
Running 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.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy tm_crash_reporter.tcl
end
show event manager policy registered
Running 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.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy tm_fsys_usage.tcl
end
show event manager policy registered
show event manager environment
This section contains two of the sample policies that are included as EEM system policies. For more details about these policies, see the "EEM Event Detector Demo: Example" section.
•sl_intf_down.tcl Sample Policy
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 quit
if {![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 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_sec
set 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 $msg
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
}
# 1. execute the command
if [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 command
set time_now [clock seconds]
# execute command
if [catch {cli_exec $cli1(fd) $_show_cmd} result] {
error $result $errorInfo
} else {
set cmd_output $result
# format output: remove trailing router prompt
regexp {\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 command
set msg [format "Command \"%s\" executed successfully" $_show_cmd]
action_syslog priority info msg $msg
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
}
# 3. if _log_file is defined, then attach it to the file
if {[info exists _log_file]} {
# attach output to file
if [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_output
close $fileD
}
# 4. if _email_server is defined send the email out
if {[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 FastEthernet1/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 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 $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 event
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
}
set msg $arr_einfo(msg)
set config_cmds ""
# 2. execute the user-defined config commands
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 {[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 email
set 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.tm
Mailservername: $_email_server
From: $_email_from
To: $_email_to
Cc: $_email_cc
Subject: From router $routername: Periodic $_show_cmd Output
$cmd_output
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 env
00:00:57:%SYS-5-CONFIG_I:Configured from console by vty0
Notice 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>enable
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#configure terminal
01: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 environment
01: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)#end
01: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#exit
01:17:07: sl_intf_down.tcl[0]: config_cmds are show event manager environment
01:17:07: %SYS-5-CONFIG_I: Configured from console by vty0
The 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.com
00:39:46: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 250 XXXX.example.com Hello XXXX.example.com [XXXX], pleased to meet you
00: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 ok
00: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 ok
00: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 ok
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : DATA
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 354 Enter mail, end with "." on a line by itself
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : Date: 25 Jun 2002 14:35:00 UTC
00: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.com
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : To: XX@example.com
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : Cc: XX@example.com
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : Subject: From router nelson: Periodic show eve man po ava system Output
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : No. Type Time Created Name
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 1 system Fri May3 20:42:34 2002 pr_cdp_abort.tcl
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 2 system Fri May3 20:42:54 2002 pr_iprouting_abort.tcl
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 3 system Wed Apr3 02:16:33 2002 sl_intf_down.tcl
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 4 system Mon Jun24 23:34:16 2002 tm_cli_cmd.tcl
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : 5 system Wed Mar27 05:53:15 2002 tm_crash_hist.tcl
00: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 delivery
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_write : QUIT
00:39:47: tm_cli_cmd.tcl[0]: DEBUG(smtp_lib) : smtp_read : 221 XXXX.example.com closing connection
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 _set
proc 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 1
•For information about EEM overview, go to "Embedded Event Manager Overview" module.
•For information about writing EEM policies using the Cisco IOS XE software CLI, go to the "Writing Embedded Event Manager Policies Using the Cisco IOS XE software CLI" module.
The following sections provide references related to writing Embedded Event Manager policies using Tcl.
|
|
---|---|
Embedded Event Manager overview |
|
Embedded Event Manager policy writing using the CLI |
"Writing Embedded Event Manager Policies Using the Cisco IOS XE Software CLI" module |
Embedded Resource Manager |
"Embedded Resource Manager" module |
Network Management commands (including EEM commands): complete command syntax, defaults, command mode, command history, usage guidelines, and examples |
|
|
---|---|
CISCO-EMBEDDED-EVENT-MGR-MIB |
To locate and download MIBs for selected platforms, Cisco IOS XE software releases, and feature sets, use Cisco MIB Locator found at the following URL: |
|
|
---|---|
No new or modified RFCs are supported by this feature, and support for existing RFCs has not been modified by this feature. |
— |
This section documents the following EEM policy Tcl command extension categories:
•EEM Event Registration Tcl Command Extensions
•EEM Event Information Tcl Command Extension
•EEM Event Publish Tcl Command Extension
•EEM Action Tcl Command Extensions
•EEM Utility Tcl Command Extensions
•EEM System Information Tcl Command Extensions
•EEM Library Debug Command Extensions
•SMTP Library Command Extensions
•CLI Library Command Extensions
•Tcl Context Library Command Extensions
Note For all EEM Tcl command extensions, if there is an error, the returned Tcl result string contains the error information.
Note Arguments for which no numeric range is specified take an integer from -2147483648 to 2147483647, inclusive.
The following conventions are used for the syntax documented on the Tcl command extension pages:
•An optional argument is shown within square brackets, for example:
[type ?]
•A question mark ? represents a variable to be entered.
•Choices between arguments are represented by pipes, for example:
priority low|normal|high
•event_register_timer_subscriber
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 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
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 The user can enter an abbreviated CLI command, such as sh mem summary, and the parser will expand the command to perform the matching.
Note The functionality provided in the CLI event detector only allows a regular expression pattern match on a valid IOS CLI command itself. This does not include text after a pipe character when redirection is used.
Syntax
event_register_cli sync yes|no skip yes|no
[occurs ?] [period ?] pattern ? [default ?]
[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 This policy runs before the CLI command is executed. For example, suppose policy_CLI is registered to run when the copy command is entered. When the copy command is entered, the CLI event detector finds a pattern match and triggers this policy to run. When the policy execution ends, the CLI event detector determines if the copy command needs to be executed according to "sync", "skip" (set in the policy), and the exit status of the policy execution if needed.
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 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
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.
Note GOLD is not supported on the Cisco ASR Series router.
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
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 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 ?]
[queue_priority low|normal|high|last] [maxrun ?]
[nice 0|1]
Arguments
Result String
None
Set _cerrno
No
Registers for an IOSWDSysMon event. Use this Tcl command extension to generate an event when a Cisco IOS XE software task exceeds specific CPU utilization or memory thresholds. A Cisco IOS XE software task is called a Cisco IOS XE software process in native Cisco IOS XE software.
Syntax
event_register_ioswdsysmon [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
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 [queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]
Arguments
Result String
None
Set _cerrno
No
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 [queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]
Arguments
Result String
None
Set _cerrno
No
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 XE 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 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
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
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 event ?
[queue_priority low|normal|high|last]
[maxrun ?] [nice 0|1]
Arguments
Result String
None
Set _cerrno
No
Registers for an 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 oid ? get_type exact|next
entry_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 ?
[queue_priority low|normal|high|last]
[maxrun ?] [nice 0|1]
Arguments
Result String
None
Set _cerrno
No
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 [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
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: •queue_priority low—Specifies that the script is to be queued at the lowest of the three priority levels. •queue_priority normal—Specifies that the script is to be queued at a priority level greater than low priority but less than high priority. •queue_priority high—Specifies that the script is to be queued at the highest of the three priority levels. •queue_priority last—Specifies that the script is to be queued at the lowest priority level. 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 The queue_priority argument specifies the queuing priority, but not the execution priority, of the script being registered. 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
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 Both the CRON and absolute time specifications work on local time.
Syntax
event_register_timer watchdog|countdown|absolute|cron
[name ?] [cron_entry ?]
[time ?]
[queue_priority low|normal|high|last] [maxrun ?]
[nice 0|1]
Arguments
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: •queue_priority low—Specifies that the script is to be queued at the lowest of the three priority levels. •queue_priority normal—Specifies that the script is to be queued at a priority level greater than low priority but less than high priority. •queue_priority high—Specifies that the script is to be queued at the highest of the three priority levels. •queue_priority last—Specifies that the script is to be queued at the lowest priority level. 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 The queue_priority argument specifies the queuing priority, but not the execution priority, of the script being registered. 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. |
|
|
minute |
0-59 |
hour |
0-23 |
day of month |
1-31 |
month |
1-12 (or names, see below) |
day of week |
0-7 (0 or 7 is Sun, or names; see Table 15) |
Result String
None
Set _cerrno
No
See Also
event_register_timer_subscriber
Registers for a timer event as a subscriber. Use this Tcl command extension to identify the name of the timer to which the event timer, as a subscriber, wants to subscribe. The event timer 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 Tcl command extensions to manipulate the timer referenced in policyB.
Syntax
event_register_timer_subscriber watchdog|countdown|absolute|cron name ? [queue_priority low|normal|high|last] [maxrun ?] [nice 0|1]
Arguments
Note An EEM policy that registers for a timer event or a counter event can act as both publisher and subscriber.
Result String
None
Set _cerrno
No
See Also
event_register_timer
Registers for a report event from the Cisco IOS XE software Object Tracking subsystem. Use this Tcl command extension to trigger a policy on the basis of a Cisco IOS XE software Object Tracking subsystem report for a specified object number.
Syntax
event_register_track ? [state up|down|any] [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.
Result String
None
Set _cerrno
No
Registers for a Watchdog system monitor event. Use this Tcl command extension to register for a composite event which is a combination of several subevents or conditions. For example, you can use this command to register for the combination of conditions wherein the CPU usage of a certain process is over 80 percent and the memory used by the process is greater than 50 percent of its initial allocation. This Tcl command extension is supported only in Software Modularity images.
Syntax
event_register_wdsysmon [timewin ?] [sub12_op and|or|andnot]
[sub23_op and|or|andnot]
[sub34_op and|or|andnot]
[sub1 subevent-description]
[sub2 subevent-description]
[sub3 subevent-description]
[sub4 subevent-description] [node ?]
[queue_priority low|normal|high|last]
[maxrun ?] [nice 0|1]
Each argument is position independent.
Note Operator definitions: and (logical and operation), or (logical or operation), andnot (logical and not operation). For example, "sub12_op and" is defined as raise an event when subevent 1 and subevent 2 are true; "sub23_op or" is defined as raise an event when the condition specified in sub12_op is true or subevent 3 is true. The logic can be diagrammed using:
if (((sub1 sub12_op sub2) sub23_op sub3) sub34_op sub4) is TRUE, raise event
Arguments
Subevents
The syntax of subevent descriptions can be one of seven cases.
For arguments in subevent description, the following constraints apply on the value of number arguments:
•For dispatch_mgr, val must be an integer between 0 and 4294967295, inclusive.
•For cpu_proc and cpu_tot, val must be an integer between 0 and 100, inclusive.
•For mem_proc, mem_tot_avail, and mem_tot_used, if is_percent is FALSE, val must be an integer between 0 and 4294967295, inclusive.
1. deadlock procname ?
Arguments
procname |
(Mandatory) A regular expression that specifies the process name that you wish to monitor for deadlock conditions. This subevent will ignore the time window even if it is given. |
2. dispatch_mgr [procname ?] [op gt|ge|eq|ne|lt|le] [val ?] [period ?]
Arguments
3. cpu_proc [procname ?] [op gt|ge|eq|ne|lt|le] [val ?] [period ?]
Arguments
4. cpu_tot [op gt|ge|eq|ne|lt|le] [val ?] [period ?]
Arguments
5. mem_proc [procname ?] [op gt|ge|eq|ne|lt|le] [val ?] [is_percent TRUE|FALSE] [period ?]
Arguments
6. mem_tot_avail [op gt|ge|eq|ne|lt|le] [val ?] [is_percent TRUE|FALSE] [period ?]
Arguments
7. mem_tot_used [op gt|ge|eq|ne|lt|le] [val ?] [is_percent TRUE|FALSE] [period ?]
Arguments
Result String
None
Set _cerrno
No
Note Inside a subevent description, each argument is position independent.
Queries information for the event that caused the current policy to run.
Syntax
event_reqinfo
Arguments
None
Result String
If the policy runs successfully, the characteristics for the event that triggered the policy will be returned. The following sections show the characteristics returned for each event detector.
For EEM_EVENT_APPLICATION
"event_id %u event_type %u event_type_string {%s} event_pub_sec %u event_pub_msec %u"
"sub_system 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_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_GOLD
"event_id %u event_type %u event_type_string {%s} %u card %u sub_card %u"
"event_severity {%s} event_pub_sec %u event_pub_msec %u overall_result %u"
"new_failure {%s} action_notify {%s} tt %u tc %u bl %u ci %u pc %u cn {%s}"
"sn {%s} tn# {%s} ta# %s ec# {%s} rc# %u lf# {%s} tf# %u cf# %u tr# {%s}"
"tr#p# {%s} tr#d# {%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_IOSWDSYSMON
"event_id %u event_type %u event_type_string {%s} %u event_pub_sec %u event_pub_msec %u"
"num_subs %u"
Where the subevent info string is for a 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 a 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_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"
For EEM_EVENT_PROCESS (Software Modularity Only)
"event_id %u event_type %u event_type_string {%s} event_pub_sec %u event_pub_msec %u"
"sub_system 0x%x instance %u process_name {%s} path {%s} exit_status 0x%x" "respawn_count %u last_respawn_sec %ld last_respawn_msec %ld fail_count %u" "dump_count %u node_name {%s}"
For EEM_EVENT_RESOURCE
"event_id %u event_type %u event_type_string {%s} %u event_pub_sec %u event_pub_msec %u"
"owner_id %lld user_id %lld" time_sent %llu dampen_time %d notify_data_flags %u"
"level {%s} direction {%s} configured_threshold %u current_value %u"
"policy_violation_flag {%s} policy_id %d"
For EEM_EVENT_RF
"event_id %u event_type %u event_type_string {%s} %u event_pub_sec %u event_pub_msec %u"
"event {%s}"
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} delta_val {%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_TIMER_ABSOLUTE
EEM_EVENT_TIMER_COUNTDOWN
EEM_EVENT_TIMER_WATCHDOG
"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_TRACK
"event_id %u event_type %u event_type_string {%s} %u event_pub_sec %u event_pub_msec %u"
"track_number {%u} track_state {%s}"
For EEM_EVENT_WDSYSMON (Software Modularity Only)
"event_id %u event_type %u event_type_string {%s} %u event_pub_sec %u event_pub_msec %u"
"num_subs %u"
Where the subevent info string is for a deadlock subevent:
"{type %s num_entries %u entries {entry 1, entry 2, ...}}"
|
|
type |
Type of wdsysmon subevent. |
num_entries |
Number of processes and threads in the deadlock. |
entries |
Information of processes and threads in the deadlock. |
Where each entry is:
"{node {%s} procname {%s} pid %u tid %u state %s b_node %s b_procname %s b_pid %u b_tid %u}"
Assume that the entry describes the scenario in which Process A thread m is blocked on process B thread n:
For dispatch_mgr Subevent
"{type %s node {%s} procname {%s} pid %u value %u sec %ld msec %ld}"
For cpu_proc Subevent
"{type %s node {%s} procname {%s} pid %u value %u sec %ld msec %ld}"
For cpu_tot Subevent
"{type %s node {%s} value %u sec %ld msec %ld}"
For mem_proc Subevent
"{type %s node {%s} procname {%s} pid %u is_percent %s value %u diff %d sec %ld msec %ld}"
If the is_percent argument is FALSE, and the sec and msec arguments are specified as 0 or are unspecified in the event registration Tcl command extension:
•value is the process used memory in the latest sample.
•diff is 0.
•sec and msec are both 0.
If the is_percent argument is FALSE, and a time window is specified as greater than zero in the event registration Tcl command extension:
•value is the averaged process used memory sample value in the specified time window.
•diff is 0.
•sec and msec are both the actual time difference between the time stamps of the oldest and latest samples in this time window.
If the is_percent argument is TRUE, and a time window is specified as greater than zero in the event registration Tcl command extension:
•value is 0.
•diff is the percentage difference between the oldest and latest process used memory samples in the specified time window.
•sec and msec are the actual time difference between the time stamps of the oldest and latest process used memory samples in this time window.
If the is_percent argument is TRUE, and the sec and msec arguments are specified as 0 or are unspecified in the event registration Tcl command extension:
•value is 0.
•diff is the percentage difference between the first process used memory sample ever collected and the latest process used memory sample.
•sec and msec are the actual time difference between the time stamps of the first process used memory sample ever collected and the latest process used memory sample.
For mem_tot_avail Subevent
"{type %s node {%s} is_percent %s used %u avail %u diff %d sec %ld msec %ld}"
If the is_percent argument is FALSE, and the sec and msec arguments are specified as 0 or are unspecified in the event registration Tcl command extension:
•used is the total used memory in the latest sample.
•avail is the total available memory in the latest sample.
•diff is 0.
•sec and msec are both 0.
If the is_percent argument is FALSE, and a time window is specified as greater than zero in the event registration Tcl command extension:
•used is 0.
•avail is the averaged total available memory sample value in the specified time window.
•diff is 0.
•sec and msec are both the actual time difference between the time stamps of the oldest and latest total available memory samples in this time window.
If the is_percent argument is TRUE, and a time window is specified as greater than zero in the event registration Tcl command extension:
•used is 0.
•avail is 0.
•diff is the percentage difference between the oldest and latest total available memory samples in the specified time window.
•sec and msec are both the actual time difference between the time stamps of the oldest and latest total available memory samples in this time window.
If the is_percent argument is TRUE, and the sec and msec arguments are specified as 0 or are unspecified in the event registration Tcl command extension:
•used is 0.
•avail is 0.
•diff is the percentage difference between the first total available memory sample ever collected and the latest total available memory sample.
•sec and msec are the actual time difference between the time stamps of the first total available memory sample ever collected and the latest total available memory sample.
For mem_tot_used Subevent
"{type %s node {%s} is_percent %s used %u avail %u diff %d sec %ld msec %ld}"
If the is_percent argument is FALSE, and the sec and msec arguments are specified as 0 or are unspecified in the event registration Tcl command extension:
•used is the total used memory in the latest sample,
•avail is the total available memory in the latest sample,
•diff is 0,
•sec and msec are both 0,
If the is_percent argument is FALSE, and a time window is specified as greater than zero in the event registration Tcl command extension:
•used is the averaged total used memory sample value in the specified time window,
•avail is 0,
•diff is 0,
•sec and msec are both the actual time difference between the time stamps of the oldest and latest total used memory samples in this time window,
If the is_percent argument is TRUE, and a time window is specified as greater than zero in the event registration Tcl command extension:
•used is 0.
•avail is 0.
•diff is the percentage difference between the oldest and latest total used memory samples in the specified time window.
•sec and msec are both the actual time difference between the time stamps of the oldest and latest total used memory samples in this time window.
If the is_percent argument is TRUE, and the sec and msec arguments are specified as 0 or are unspecified in the event registration Tcl command extension:
•used is 0.
•avail is 0.
•diff is the percentage difference between the first total used memory sample ever collected and the latest total used memory sample.
•sec and msec are the actual time difference between the time stamps of the first total used memory sample ever collected and the latest total used memory sample.
Set _cerrno
Yes
Publishes an application-specific event.
Syntax
event_publish sub_system ? 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.
Sample Usage
This example demonstrates how to use the event_publish Tcl command extension to execute a script n times repeatedly to perform some function (for example, to measure the amount of CPU time taken by a given group of Tcl statements). This example uses two Tcl scripts.
Script1 publishes a type 9999 EEM event to cause Script2 to run for the first time. Script1 is registered as a none event and is run using the Cisco IOS XE software CLI event manager run command. Script2 is registered as an EEM application event of type 9999, and this script checks to see if the application publish arg1 data (the iteration number) exceeds the EEM environment variable test_iterations value. If the test_iterations value is exceeded, the script writes a message and exits; otherwise the script executes the remaining statements and reschedules another run. To measure the CPU utilization for Script2, use a value of test_iterations that is a multiple of 10 to calculate the amount of average CPU time used by Script2.
To run the Tcl scripts, enter the following Cisco IOS XE software commands:
configure terminal
event manager environment test_iterations 100
event manager policy script1.tcl
event manager policy script2.tcl
end
event manager run script1.tcl
The Tcl script Script2 will be executed 100 times. If you execute the script without the extra processing and derive the average CPU utilization, and then add the extra processing and repeat the test, you can subtract the former CPU utilization from the later CPU utilization to determine the average for the extra processing.
Script1 (script1.tcl)
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
# Query the event info.
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
}
action_syslog priority info msg "EEM application_publish test start"
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
}
# Cause the first iteration to run.
event_publish sub_system 798 type 9999 arg1 0
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
}
Script2 (script2.tcl)
::cisco::eem::event_register_appl sub_system 798 type 9999
# Check if all the required environment variables exist.
# If any required environment variable does not exist, print out an error msg and quit.
if {![info exists test_iterations]} {
set result \
"Policy cannot be run: variable test_iterations has not been set"
error $result $errorInfo
}
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
# Query the event info.
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
}
# Data1 contains the arg1 value used to publish this event.
set iter $arr_einfo(data1)
# Use the arg1 info from the previous run to determine when to end.
if {$iter >= $test_iterations} {
# Log a message.
action_syslog priority info msg "EEM application_publish test end"
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
}
exit 0
}
set iter [expr $iter + 1]
# Log a message.
set msg [format "EEM application_publish test iteration %s" $iter]
action_syslog priority info msg $msg
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
}
# Do whatever processing that you want to measure here.
# Cause the next iteration to run. Note that the iteration is passed to the # next operation as arg1.
event_publish sub_system 798 type 9999 arg1 $iter
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
}
Switches processing to a secondary processor in a fully redundant environment. Before using the action_switch Tcl command extension, you must install a backup processor in the device. If the hardware is not fully redundant, the switchover action will not be performed..
Syntax
action_switch
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.
Allows a Tcl script to run an Embedded Event Manager (EEM) policy that has been registered with the None event detector. The action of running an EEM policy can also be performed using the event manager run command.
Syntax
action_policy ?
Arguments
? (represents a string) |
(Mandatory) The name of the EEM policy to be scheduled for execution. The policy must have been previously registered with the None event detector. |
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 = 12) FH_ENOSUCHEID (unknown event ID)
This error means that the policy is unknown because it is not registered.
(_cerr_sub_err = 14) FH_ENOSUCHACTION (unknown action type)
This error means that the action command requested was unknown.
Starts, restarts, or kills a Software Modularity process. This Tcl command extension is supported only in Software Modularity images.
Syntax
action_process start|restart|kill [job_id ?]
[process_name ?] [instance ?]
Arguments
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.
(_cerr_sub_num = 425, _cerr_sub_err = 1) SYSMGR_ERROR_INVALID_ARGS (Invalid arguments passed)
This error means that the arguments passed in were invalid.
(_cerr_sub_num = 425, _cerr_sub_err = 2) SYSMGR_ERROR_NO_MEMORY (Could not allocate required memory)
This error means that an internal SYSMGR request for memory failed.
(_cerr_sub_num = 425, _cerr_sub_err = 5) SYSMGR_ERROR_NO_MATCH (This process is not known to sysmgr)
This error means that the process name was not known.
(_cerr_sub_num = 425, _cerr_sub_err = 14) SYSMGR_ERROR_TOO_BIG (outside the valid limit)
This error means that an object size exceeded its maximum.
(_cerr_sub_num = 425, _cerr_sub_err = 15) SYSMGR_ERROR_INVALID_OP (Invalid operation for this process)
This error means that the operation was invalid for the process.
Allows a Tcl script to run a POSIX process (program), optionally with a given argument string, environment string, Standard Input (stdin) pathname, Standard Output (stdout) pathname, or Standard Error (stderr) pathname. This Tcl command extension is supported only in Software Modularity images.
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.
Reloads the router.
Syntax
action_reload
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.
Allows a Tcl script to enable or disable the execution of all Tcl scripts (enables or disables the script scheduler).
Syntax
action_script [status enable|disable]
Argument
status |
(Optional) Flag to indicate script execution status. If this argument is set to enable, script execution is enabled; if this argument is set to disable, script execution is disabled. |
s
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.
Sends a Simple Network Management Protocol (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.
Logs a message.
Syntax
action_syslog [priority emerg|alert|crit|err|warning|notice|info|debug]
[msg ?]
Arguments
priority |
(Optional) The action_syslog message facility level. If this argument is not specified, the default priority is LOG_INFO. |
msg |
(Optional) 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.
Reads the state of a tracked object when an Embedded Event Manager (EEM) applet is triggered.
Syntax
action_track_read ?
Arguments
? (represents a number) |
(Mandatory) Tracked object number in the range from 1 to 500, inclusive. |
Result String
number {%u}
state {%s}
Set _cerrno
Yes
FH_ENOTRACK
This error means that the tracked object number was not found.
Sets the state of a tracked object when an Embedded Event Manager (EEM) applet is triggered.
Syntax
action_track_set ? state up|down
Arguments
Result String
None
Set _cerrno
Yes
FH_ENOTRACK
This error means that the tracked object number was not found.
Reads Embedded Event Manager (EEM) application volatile data. This Tcl command extension provides support for reading EEM application volatile data. EEM application volatile data can be published by a Cisco IOS XE software process that uses the EEM application publish API. EEM application volatile data cannot be published by an EEM policy.
Note Currently there are no Cisco IOS XE software processes that publish application volatile data.
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 %s
Where data is the application published string data to be 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.
Retrieves previously saved information from the Embedded Event Manager (EEM). This Tcl command extension provides support for retrieving information from EEM that has been previously saved with a unique key, which must be specified in order to retrieve the information. Note that retrieving the information deletes it from EEM. It must be resaved if it is to be retrieved again.
Syntax
appl_reqinfo key ?
Arguments
|
(Mandatory) The string key of the data. |
Result String
data %s
Where data is the application string data to be 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.
Saves information in the Embedded Event Manager (EEM). This Tcl command extension provides support for saving information in the Embedded Event Manager that can be retrieved later by the same policy or by another policy. A unique key must be specified. This key allows the information to be retrieved later.
Syntax
appl_setinfo key ? data ?
Arguments
key |
(Mandatory) The string key of the data. |
data |
(Mandatory) The application string data to save. |
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 = 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 the API message length was invalid.
Modifies a counter value.
Syntax
counter_modify event_id ? val ? op nop|set|inc|dec
Arguments
Result String
val_remain %d
Where 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 that 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 an internal EEM event detector pointer was null when it should have contained 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.
Returns the time period elapsed since the last software boot. Use this Tcl command extension to return the number of nanoseconds since boot in an array "nsec nnnn" where nnnn is the number of nanoseconds.
Syntax
fts_get_stamp
Arguments
None
Result String
nsec %d
Where nsec is the number of nanoseconds since boot.
Set _cerrno
No
Registers a counter and returns a counter event ID. This Tcl command extension is used by a counter publisher to perform this registration before using the event ID to manipulate the counter.
Syntax
register_counter name ?
Arguments
name |
(Mandatory) The name of the counter to be manipulated. |
Result String
event_id %d
event_spec_id %d
Where event_id is the counter event ID for the specified counter; it can be used to manipulate the counter by the unregister_counter or counter_modify Tcl command extensions. The event_spec_id argument is the event specification 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 its 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 that an event detector internal event structure is corrupt.
(_cerr_sub_err = 12) FH_ENOSUCHEID (unknown event ID)
This error means that the event ID could not be matched when the event was being registered or that 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 pointer 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 an internal EEM event detector pointer was null when it should have contained 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.
Registers a timer and returns a timer event ID. This Tcl command extension is used by a timer publisher to perform this registration before using the event ID to manipulate the timer if it does not use the event_register_timer command extension to register as a publisher and subscriber.
Syntax
register_timer watchdog|countdown|absolute|cron name ?
Arguments
name |
(Mandatory) The name of the timer to be manipulated. |
Result String
event_id %u
Where event_id is the timer event ID for the specified timer (can be used to manipulate the timer by the timer_arm or timer_cancel command extensions).
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 its 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 that 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 pointer 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 an internal EEM event detector pointer was null when it should have contained 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.
Arms a timer. The type could be CRON, watchdog, countdown, or absolute.
Syntax
timer_arm event_id ? cron_entry ?|time ?
Arguments
Result String
sec_remain %ld msec_remain %ld
Where sec_remain and msec_remain are the remaining time before the next expiration of the timer.
Note A value of 0 will be returned for the sec_remain and msec_remain arguments if the timer type is CRON.
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 that an event detector internal event structure is corrupt.
(_cerr_sub_err = 12) FH_ENOSUCHEID (unknown event ID)
This error means that the event ID could not be matched when the event was being registered or that 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 an internal EEM event detector pointer was null when it should have contained 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.
Cancels a timer.
Syntax
timer_cancel event_id ?
Arguments
event_id |
(Mandatory) The timer event ID returned by the register_timer command extension. Must be an integer between 0 and 4294967295, inclusive. |
Result String
sec_remain %ld msec_remain %ld
Where sec_remain and msec_remain are the remaining time before the next expiration of the timer.
Note A value of 0 will be returned for sec_remain and msec_remain if the timer type is CRON.
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 that an event detector internal event structure is corrupt.
(_cerr_sub_err = 12) FH_ENOSUCHEID (unknown event ID)
This error means that the event ID could not be matched when the event was being registered or that 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 an internal EEM event detector pointer was null when it should have contained 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.
Unregisters a counter. This Tcl command extension is used by a counter publisher to unregister a counter that was previously registered with the register_counter Tcl command extension.
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 that 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 an internal EEM event detector pointer was null when it should have contained 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.
Note All EEM system information commands—sys_reqinfo_xxx—have the Set _cerrno section set to yes.
Queries the frequency information of all command-line interface (CLI) events.
Syntax
sys_reqinfo_cli_freq
Arguments
None
Result String
rec_list {{CLI frequency string 0},{CLI frequency str 1}, ...}
Where each CLI frequency string is:
time_sec %ld time_msec %ld match_count %u raise_count %u occurs %u period_sec %ld period_msec %ld pattern {%s}
Set _cerrno
Yes
Queries the history of command-line interface (CLI) commands.
Syntax
sys_reqinfo_cli_history
Arguments
None
Result String
rec_list {{CLI history string 0}, {CLI history str 1},...}
Where each CLI history string is:
time_sec %ld time_msec %ld cmd {%s}
rec_list |
Marks the start of the CLI command history list. |
time_sec time_msec |
Time when the CLI command was run. |
cmd |
Text of the CLI command. |
Set _cerrno
Yes
Queries the CPU utilization of the top processes (both POSIX processes and IOS processes) during a specified time period and in a specified order. This Tcl command extension is supported only in Software Modularity images.
Syntax
sys_reqinfo_cpu_all order cpu_used [sec ?] [msec ?] [num ?]
Arguments
Result String
rec_list {{process CPU info string 0},{process CPU info string 1}, ...}
Where each process CPU info string is:
pid %u name {%s} cpu_used %u
Set _cerrno
Yes
Queries the crash information of all processes that have ever crashed. This Tcl command extension is supported only in Software Modularity images.
Syntax
sys_reqinfo_crash_history
Arguments
None
Result String
rec_list {{crash info string 0},{crash info string 1}, ...}
Where each crash info string is:
job_id %u name {%s} respawn_count %u fail_count %u dump_count %u inst_id %d exit_status 0x%x exit_type %d proc_state {%s} component_id 0x%x crash_time_sec %ld crash_time_msec %ld
Set _cerrno
Yes
Queries the memory usage of the top processes (both POSIX and IOS) during a specified time period and in a specified order. This Tcl command extension is supported only in Software Modularity images.
Syntax
sys_reqinfo_mem_all order allocates|increase|used [sec ?] [msec ?] [num ?]
Arguments
Result String
rec_list {{process mem info string 0},{process mem info string 1}, ...}
Where each process mem info string is:
pid %u name {%s} delta_allocs %d initial_alloc %u current_alloc %u percent_increase %d
Set _cerrno
Yes
Queries the information about a single POSIX process. This Tcl command extension is supported only in Software Modularity images.
Syntax
sys_reqinfo_proc job_id ?
Arguments
job_id |
(Mandatory) System manager assigned job ID for the process. Must be an integer between 1 and 4294967295, inclusive. |
Result String
job_id %u component_id 0x%x name {%s} helper_name {%s} helper_path {%s} path {%s}
node_name {%s} is_respawn %u is_mandatory %u is_hold %u dump_option %d max_dump_count %u respawn_count %u fail_count %u dump_count %u last_respawn_sec %ld last_respawn_msec %ld inst_id %u proc_state %s level %d exit_status 0x%x exit_type %d
Set _cerrno
Yes
Queries the information of all POSIX processes. This Tcl command extension is supported only in Software Modularity images.
Syntax
sys_reqinfo_proc_all
Arguments
None
Result String
rec_list {{process info string 0}, {process info string 1},...}
Where each process info string is the same as the result string of the sysreq_info_proc Tcl command extension.
Set _cerrno
Yes
Queries the router name.
Syntax
sys_reqinfo_routername
Arguments
None
Result String
routername %s
Where routername is the name of the router.
Set _cerrno
Yes
Queries the value of the entity specified by a Simple Network Management Protocol (SNMP) object ID.
Syntax
sys_reqinfo_snmp oid ? get_type exact|next
Arguments
Result String
oid {%s} value {%s}
oid |
SNMP OID. |
value |
Value string of the associated SNMP data element. |
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 an internal EEM event detector pointer was null when it should have contained 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.
Queries the frequency information of all syslog events.
Syntax
sys_reqinfo_syslog_freq
Arguments
None
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 %u
period_sec %ld period_msec %ld pattern {%s}
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 an internal EEM event detector pointer was null when it should have contained 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.
Queries the history of the specified syslog message.
Syntax
sys_reqinfo_syslog_history
Arguments
None
Result 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}
time_sec time_msec |
Seconds and milliseconds since January 1, 1970, which represent 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 an internal EEM event detector pointer was null when it should have contained 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.
Prints a command-line interface (CLI) debug statement to syslog. This Tcl command extension is used to print a CLI debug statement to syslog if the debug event manager tcl cli_library Cisco IOS XE software CLI command is in effect.
Syntax
cli_debug spec_string debug_string
Arguments
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
Prints a a Simple Mail Transfer Protocol (SMTP) debug statement to syslog. This Tcl command extension prints a SMTP debug statement to syslog if the debug event manager tcl smtp_library Cisco IOS XE software command-line interface (CLI) command is in effect.
Syntax
smtp_debug spec_string debug_string
Arguments
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
All Simple Mail Transfer Protocol (SMTP) library command extensions belong to the ::cisco::lib namespace.
To use this library, the user needs to provide an e-mail 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 Cisco IOS XE software command-line interface (CLI) configuration command. There are commands in this library to substitute the global variables in the e-mail template file and to send the desired e-mail 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 e-mail address of sender>
To:<space><the list of e-mail addresses of recipients>
Cc:<space><the list of e-mail addresses that the e-mail will be copied to>
Subject:<subject line>
<a blank line>
<body>
Note Note that the template normally includes Tcl global variables to be configured.
Below is a sample e-mail template file:
Mailservername: $_email_server
From: $_email_from
To: $_email_to
Cc: $_email_cc
Subject: From router $routername: Process terminated
process name: $process_name
subsystem: $sub_system
exit status: $exit_status
respawn count: $respawn_count
Exported Tcl Command Extensions
Given the text of an e-mail template file with all global variables already substituted, sends the e-mail out using Simple Mail Transfer Protocol (SMTP). The e-mail template specifies the candidate mail server addresses, To addresses, CC addresses, From address, subject line, and e-mail body.
Note A list of candidate e-mail 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 text
Argument
text |
(Mandatory) The text of an e-mail template file with all global variables already substituted. |
s
Result String
None
Set _cerrno
•Wrong 1st line format—Mailservername:list of server names.
•Wrong 2nd line format—From:from-address.
•Wrong 3rd line format—To:list of to-addresses.
•Wrong 4th line format—CC:list of cc-addresses.
•Error connecting to mail server:—$sock closed by remote server (where $sock is the name of the socket opened to the mail server).
•Error connecting to mail server:—$sock reply code is $k instead of the service ready greeting (where $sock is the name of the socket opened to the mail server; $k is the reply code of $sock).
•Error connecting to mail server:—cannot connect to all the candidate mail servers.
•Error disconnecting from mail server:—$sock closed by remote server (where $sock is the name of the socket opened to the mail server).
Sample Scripts
After all needed global variables in the e-mail template are defined:
if [catch {smtp_subst [file join $tcl_library email_template_sm]} result] {
puts stderr $result
exit 1
}
if [catch {smtp_send_email $result} result] {
puts stderr $result
exit 1
}
Given an e-mail template file e-mail_template, substitutes each global variable in the file by its user-defined value. Returns the text of the file after substitution.
Syntax
smtp_subst e-mail_template
Argument
s
Result String
The text of the e-mail template file with all the global variables substituted.
Set _cerrno
•cannot open e-mail template file
•cannot close e-mail template file
All command-line interface (CLI) library command extensions 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 back the output of the command.
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 ask for different user options, and the user is supposed to enter 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 noninteractive commands, once the command is entered, the command will run to completion. To run different types of commands using an EEM script, different CLI library command sequences should be used, which are documented in the "Using the CLI Library to Run a Noninteractive Command" section and in the "Using the CLI Library to Run an Interactive Command" section.
Exported Tcl Command Extensions
Closes the exec process and releases the VTY and the specified channel handler connected to the command-line interface (CLI).
Syntax
cli_close fd tty_id
Arguments
fd |
(Mandatory) The CLI channel handler. |
tty_id |
(Mandatory) The TTY ID returned from the cli_open command extension. |
Result String
None
Set _cerrno
Cannot close the channel.
Writes the command to the specified channel handler to execute the command. Then reads the output of the command from the channel and returns the output.
Syntax
cli_exec fd cmd
Arguments
fd |
(Mandatory) The command-line interface (CLI) channel handler. |
cmd |
(Mandatory) The CLI command to execute. |
Result String
The output of the CLI command executed.
Set _cerrno
Error reading the channel.
Returns the real and pseudo tty names for a given TTY ID.
Syntax
cli_get_ttyname tty_id
Argument
tty_id |
(Mandatory) The TTY ID returned from the cli_open command extension. |
s
Result String
pty %s tty %s
Set _cerrno
None
Allocates a vty, creates an EXEC command-line interface (CLI) session, and connects the vty to a channel handler. Returns an array including the channel handler.
Note Each call to cli_open initiates a Cisco IOS XE software EXEC session that allocates a Cisco IOS XE software vty. The vty remains in use until the cli_close routine is called. Vtys are allocated from the pool of vtys that are configured using the line vty CLI configuration command. Be aware that the cli_open routine will fail when two or fewer vtys are available, preserving the remaining vtys for Telnet use.
Syntax
cli_open
Arguments
None
Result String
"tty_id {%s} pty {%d} tty {%d} fd {%d}"
|
|
---|---|
tty_id |
TTY ID. |
pty |
PTY device name. |
tty |
TTY device name. |
fd |
CLI channel handler. |
Set _cerrno
•Cannot get pty for EXEC.
•Cannot create an EXEC CLI session.
•Error reading the first prompt.
Reads the command output from the specified command-line interface (CLI) channel handler until the pattern of the router prompt occurs in the contents read. Returns all the contents read up to the match.
Syntax
cli_read fd
Arguments
fd |
(Mandatory) The CLI channel handler. |
Result String
All the contents read.
Set _cerrno
Cannot get router name.
Note This Tcl command extension will block waiting for the router prompt to show up in the contents read.
Reads and drains the command output of the specified command-line interface (CLI) channel handler. Returns all the contents read.
Syntax
cli_read_drain fd
Arguments
fd |
(Mandatory) The CLI channel handler. |
Result String
All the contents read.
Set _cerrno
None
Reads one line of the command output from the specified command-line interface (CLI) channel handler. Returns the line read.
Syntax
cli_read_line fd
Arguments
fd |
(Mandatory) The CLI channel handler. |
Result String
The line read.
Set _cerrno
None
Note This Tcl command extension will block waiting for the end of line to show up in the contents read.
Reads the command output from the specified command-line interface (CLI) channel handler until the pattern that is to be matched occurs in the contents read. Returns all the contents read up to the match.
Note The pattern matching logic attempts a match by looking at the command output data as it is delivered from the Cisco IOS XE software command. The match is always done on the most recent 256 characters in the output buffer unless there are fewer characters available, in which case the match is done on fewer characters. If more than 256 characters in the output buffer are required for the match to succeed, the pattern will not match.
Syntax
cli_read_pattern fd ptn
Arguments
fd |
(Mandatory) The CLI channel handler. |
ptn |
(Mandatory) The pattern to be matched when reading the command output from the channel. |
Result String
All the contents read.
Set _cerrno
None
Note This Tcl command extension will block waiting for the specified pattern to show up in the contents read.
Writes the command that is to be executed to the specified CLI channel handler. The CLI channel handler executes the command.
Syntax
cli_write fd cmd
Arguments
fd |
(Mandatory) The CLI channel handler. |
cmd |
(Mandatory) The CLI command to execute. |
Result String
None
Set _cerrno
None
Sample Usage
As an example, use configuration CLI commands to bring up FastEthernet interface 1/0:
if [catch {cli_open} result] {
puts stderr $result
exit 1
} else {
array set cli1 $result
}
if [catch {cli_exec $cli1(fd) "en"} result] {
puts stderr $result
exit 1
}
if [catch {cli_exec $cli1(fd) "config t"} result] {
puts stderr $result
exit 1
}
if [catch {cli_exec $cli1(fd) "interface FastEthernet1/0"} result] {
puts stderr $result
exit 1
}
if [catch {cli_exec $cli1(fd) "no shut"} result] {
puts stderr $result
exit 1
}
if [catch {cli_exec $cli1(fd) "end"} result] {
puts stderr $result
exit 1
}
if [catch {cli_close $cli1(fd) $cli1(tty_id)} } result] {
puts stderr $result
exit 1
Using the CLI Library to Run a Noninteractive Command
To run a noninteractive command, use the cli_exec command extension to issue the command, and then wait for the complete output and the router prompt. For example, the following shows the use of configuration CLI commands to bring up FastEthernet interface 1/0:
if [catch {cli_open} result] {
error $result $errorInfo
} else {
set fd $result
}
if [catch {cli_exec $fd "en"} result] {
error $result $errorInfo
}
if [catch {cli_exec $fd "config t"} result] {
error $result $errorInfo
}
if [catch {cli_exec $fd "interface FastEthernet1/0"} result] {
error $result $errorInfo
}
if [catch {cli_exec $fd "no shut"} result] {
error $result $errorInfo
}
if [catch {cli_exec $fd "end"} result] {
error $result $errorInfo
}
if [catch {cli_close $fd} result] {
error $result $errorInfo
}
Using the CLI Library to Run an Interactive Command
To run interactive commands, three phases are needed:
•Phase 1: Issue the command using the cli_write command extension.
•Phase 2: Q&A Phase. Use the cli_read_pattern command extension to read the question (the regular pattern that is specified to match the question text) and the cli_write command extension to write back the answers alternately.
•Phase 3: Noninteractive phase. All questions have been answered, and the command will run to completion. Use the cli_read command extension to wait for the complete output of the command and the router prompt.
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 {
array set cli1 $result
}
if [catch {cli_exec $cli1(fd) "en"} result] {
error $result $errorInfo
}
# Phase 1: issue the command
if [catch {cli_write $cli1(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 $cli1(fd) "All deleted"} result] {
error $result $errorInfo
}
# write a newline character
if [catch {cli_write $cli1(fd) "\n"} result] {
error $result $errorInfo
}
# wait for prompted question:
# Squeeze operation may take a while. Continue? [confirm]
if [catch {cli_read_pattern $cli1(fd) "Squeeze operation"} result] {
error $result $errorInfo
}
# write a newline character
if [catch {cli_write $cli1(fd) "\n"} result] {
error $result $errorInfo
}
# Phase 3: noninteractive phase
# wait for command to complete and the router prompt
if [catch {cli_read $cli1(fd) } result] {
error $result $errorInfo
} else {
set cmd_output $result
}
if [catch {cli_close $cli1(fd) $cli1(tty_id)} 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 command
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_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
}
All the Tcl context library command extensions belong to the ::cisco::eem namespace.
Exported Commands
Retrieves 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.
Note Once saved information is retrieved, it is automatically deleted. If that information is needed by another policy, the policy that retrieves it (using the context_retrieve command extension) should also save it again (using the context_save command extension).
Syntax
context_retrieve ctxt [var] [index_if_array]
Arguments
ctxt |
(Mandatory) Context name. |
var |
(Optional) Scalar variable name or array variable name. Defaults to a null string if this argument is not specified. |
index_if_array |
(Optional) The array index. |
Note The index_if_array argument will be ignored when the var argument is a scalar variable.
If var is unspecified, retrieves the whole variable table saved in the context.
If var is specified and index_if_array is not specified, or if index_if_array is specified but var is a scalar variable, retrieves the value of var.
If var is specified, and index_if_array is specified, and var is an array variable, retrieves the value of the specified array element.
Result String
Resets the Tcl global variables to the state that they were in when the save was performed.
Set _cerrno
•A string displaying _cerrno, _cerr_sub_num, _cerr_sub_err, _cerr_posix_err, _cerr_str due to appl_reqinfo error.
•Variable is not in the context.
Sample Usage
The following examples show how to use the context_save and context_retrieve command extension functionality to save and retrieve data. The examples are shown in save and retrieve pairs.
Example 1: Save
If var is unspecified or if a pattern if specified, saves multiple variables to the context.
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
set testvara 123
set testvarb 345
set testvarc 789
if {[catch {context_save TESTCTX "testvar*"} errmsg]} {
action_syslog msg "context_save failed: $errmsg"
} else {
action_syslog msg "context_save succeeded"
}
Example 1: Retrieve
If var is unspecified, retrieves multiple variables from the context.
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
if {[catch {foreach {var value} [context_retrieve TESTCTX] {set $var $value}} errmsg]} {
action_syslog msg "context_retrieve failed: $errmsg"
} else {
action_syslog msg "context_retrieve succeeded"
}
if {[info exists testvara]} {
action_syslog msg "testvara exists and is $testvara"
} else {
action_syslog msg "testvara does not exist"
}
if {[info exists testvarb]} {
action_syslog msg "testvarb exists and is $testvarb"
} else {
action_syslog msg "testvarb does not exist"
}
if {[info exists testvarc]} {
action_syslog msg "testvarc exists and is $testvarc"
} else {
action_syslog msg "testvarc does not exist"
}
Example 2: Save
If var is specified, saves the value of var.
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
set testvar 123
if {[catch {context_save TESTCTX testvar} errmsg]} {
action_syslog msg "context_save failed: $errmsg"
} else {
action_syslog msg "context_save succeeded"
}
Example 2: Retrieve
If var is specified and index_if_array is not specified, or if index_if_array is specified but var is a scalar variable, retrieves the value of var.
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
if {[catch {set testvar [context_retrieve TESTCTX testvar]} errmsg]} {
action_syslog msg "context_retrieve failed: $errmsg"
} else {
action_syslog msg "context_retrieve succeeded"
}
if {[info exists testvar]} {
action_syslog msg "testvar exists and is $testvar"
} else {
action_syslog msg "testvar does not exist"
}
Example 3: Save
If var is specified, saves the value of var even if it is an array.
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
array set testvar "testvar1 ok testvar2 not_ok"
if {[catch {context_save TESTCTX testvar} errmsg]} {
action_syslog msg "context_save failed: $errmsg"
} else {
action_syslog msg "context_save succeeded"
}
Example 3: Retrieve
If var is specified, and index_if_array is not specified, and var is an array variable, retrieves the entire array.
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
if {[catch {array set testvar [context_retrieve TESTCTX testvar]} errmsg]} {
action_syslog msg "context_retrieve failed: $errmsg"
} else {
action_syslog msg "context_retrieve succeeded"
}
if {[info exists testvar]} {
action_syslog msg "testvar exists and is [array get testvar]"
} else {
action_syslog msg "testvar does not exist"
}
Example 4: Save
If var is specified, saves the value of var even if it is an array.
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
array set testvar "testvar1 ok testvar2 not_ok"
if {[catch {context_save TESTCTX testvar} errmsg]} {
action_syslog msg "context_save failed: $errmsg"
} else {
action_syslog msg "context_save succeeded"
}
Example 4: Retrieve
If var is specified, and index_if_array is specified, and var is an array variable, retrieves the specified array element value.
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
if {[catch {set testvar [context_retrieve TESTCTX testvar testvar1]} errmsg]} {
action_syslog msg "context_retrieve failed: $errmsg"
} else {
action_syslog msg "context_retrieve succeeded"
}
if {[info exists testvar]} {
action_syslog msg "testvar exists and is $testvar"
} else {
action_syslog msg "testvar doesn't exist"
}
Saves Tcl variables that match a given pattern in current and global namespaces with the given context name as identification. Use this Tcl command extension to save information outside of a policy. Saved information can be retrieved by a different policy using the context_retrieve command extension.
Note Once saved information is retrieved, it is automatically deleted. If that information is needed by another policy, the policy that retrieves it (using the context_retrieve command extension) should also save it again (using the context_save command extension).
Syntax
context_save ctxt [pattern]
Arguments
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.
Sample Usage
For examples showing how to use the context_save and context_retrieve command extension functionality to save and retrieve data, see the "Sample Usage" section.
Only features that were introduced or modified in Cisco IOS Releases 12.3(14)T, 12.2(25)S, 12.0(26)S, 12.2(18)SXF4, 12.2(28)SB, 12.2(33)SRA, 12.2(33)SXH, 12.2(33)SXI, 12.4(20)T, 12.4(22)T, 15.0(1)M, 12.2(33)SRE or a later release appear in the table.
Not all commands may be available in your Cisco IOS software release. For release information about a specific command, see the command reference documentation.
Use Cisco Feature Navigator to find information about platform support and software image support. Cisco Feature Navigator enables you to determine which Cisco IOS and Catalyst OS software images support a specific software release, feature set, or platform. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn. An account on Cisco.com is not required.
Note Table 16 lists only the Cisco IOS software release that introduced support for a given feature in a given Cisco IOS software release train. Unless noted otherwise, subsequent releases of that Cisco IOS software release train also support that feature.
|
|
|
---|---|---|
Embedded Event Manager 2.1 |
12.3(14)T 12.2(18)SXF5 |
This document was introduced to support the ability to create policies using Tool Command Language (Tcl) that was introduced in the Embedded Event Manager 2.1 feature in Cisco IOS Release 12.3(14)T. |
Embedded Event Manager 2.1 (Software Modularity) |
12.2(18)SXF4 Cisco IOS Software Modularity images |
EEM 2.1 for Software Modularity images introduced the GOLD, system manager, and WDSysMon (Cisco IOS Software Modularity watchdog) event detectors and the ability to display Cisco IOS Software Modularity processes and process matrix. Six new sample policies were also introduced. The following sections provide information about this feature: •EEM Policy Tcl Command Extension Categories •Modifying the Sample EEM Policies •Modifying the Sample EEM Policies •EEM Policy Tcl Command Extension Reference The following commands were introduced by this feature: event gold, event process, show event manager metric process. Note EEM 2.1 for Software Modularity images also supports the resource and RF event detectors introduced in EEM 2.2, but it does not support the enhanced object tracking event detector or the actions to read and set tracked objects. |
Embedded Event Manager 2.2 |
12.4(2)T |
EEM 2.2 introduced the enhanced object tracking, resource, and RF event detectors. The actions of reading and setting the state of a tracked object were also introduced. The following sections provide information about this, feature: •EEM Policy Tcl Command Extension Categories •Modifying the Sample EEM Policies •EEM Policy Tcl Command Extension Reference The following commands were introduced or modified by this feature: action track read, action track set, default-state, event resource, event rf, event track, show track, track stub-object. |
SNMP event detector delta environment variable1 |
12.4(11)T |
A new SNMP event detector environment variable, delta_val, was introduced. |
Embedded Event Manager 2.3 |
12.2(33)SXH |
EEM 2.3 introduced some new features relative to the Generic Online Diagnostics (GOLD) Event Detector on the Cisco Catalyst 6500 Series switches. The event gold command was enhanced in addition to the Tcl keywords—action-notify, testing-type, test-name, test-id, consecutive-failure, platform-action, and maxrun—for improved reaction to GOLD test failures and conditions. The following sections were updated to describe the enhanced functionality of the event gold command: •EEM Event Registration Tcl Command Extensions Optional arguments were added to the event_register_gold EEM Event Registration Tcl command extension to support additional event configuration options. •EEM Event Information Tcl Command Extension Event types were added under the event_reqinfo EEM Event Information Tcl command extension to provide access to platform-wide and test-specific GOLD EEM Tcl policy information for a detected event. |
Embedded Event Manager 2.4 |
12.4(20)T |
EEM 2.4 is supported in Cisco IOS Release 12.4(20)T and later releases, and introduced several new features. The following sections were updated: •EEM Policy Tcl Command Extension Categories •Modifying the Sample EEM Policies •EEM Policy Tcl Command Extension Reference The following commands were introduced by this feature: attribute (EEM), correlate, event manager detector rpc, event manager directory user repository, event manager update user policy, event manager scheduler clear, event manager update user policy, event owner, event rpc, event snmp-notification, show event manager detector, show event manager version, trigger (EEM). |
Embedded Event Manger 3.0 |
12.4(22)T |
EEM 3.0 is supported in Cisco IOS Release 12.4(22)T and later releases, and introduced several new features. The following sections provide information about this feature: •EEM Policy Tcl Command Extension Categories •Modifying the Sample EEM Policies •EEM Policy Tcl Command Extension Reference The following commands were introduced or modified by this feature: action add, action append, action break, action comment, action context retrieve, action context save, action continue, action decrement, action divide, action else, action elseif, action end, action exit, action foreach, action gets, action if, action if goto, action increment, action info type interface-names, action info type snmp getid, action info type snmp inform, action info type snmp oid, action info type snmp trap, action info type snmp var, action multiply, action puts, action regexp, action set (EEM), action string compare, action string equal, action string first, action string index, action string last, action string length, action string match, action string range, action string replace, action string tolower, action string toupper, action string trim, action string trimleft, action string trimright, action subtract, action while, event cli, event ipsla, event manager detector routing, event manager scheduler, event manager scheduler clear, event manager scheduler hold, event manager scheduler modify, event manager scheduler release, event nf, event routing, show event manager policy active, show event manager policy pending, and show event manager scheduler. |
Embedded Event Manager 3.1 |
15.0(1)M |
EEM 3.1 is supported in Cisco IOS Release 15.0(1)M and later releases, and introduced several new features. The following sections provide information about this feature: •EEM Policy Tcl Command Extension Categories •Modifying the Sample EEM Policies •EEM Policy Tcl Command Extension Reference The following commands were introduced or modified by this feature: action syslog, description, event manager applet, event manager policy, event snmp-notification, event snmp-object, show event manager policy registered, and show event manager policy available. |
1 This is a minor enhancement. Minor enhancements are not typically listed in Feature Navigator. |