Embedded Events Manager
Cisco IOS Embedded Event Manager (EEM) supports more than 20 event detectors that are highly integrated with different Cisco IOS Software components to trigger actions in response to network events. These scripts are programmed using either a simple command-line interface (CLI) or a scripting language called Tool Command Language (Tcl). In this section, we first review EEM and then look more closely at Tcl scripting.
EEM Architecture
EEM consists of three components:
▪ Policies: Policies, or scripts, are either applets or Tcl scripts configured by the administrator.
▪ EEM server: The EEM server is the director of EEM. When a configured event occurs, the associated action is implemented.
▪ Event detectors: An event detector is used as a trigger, based on certain conditions. Some of these conditions include monitoring for syslog events, online insertion and removal (IOR), CLI input, and timers.
Figure 3-6 illustrates the relationship between these three components.
)
Policies
Policies, or scripts, are either applets or Tcl scripts configured by the administrator:
▪ Applets: With applets, users do not need to know how to write Tcl scripts. The body of an applet appears in the configuration of a Cisco IOS device. Applets were designed to provide a simpler interface for EEM.
▪ Tcl scripts: Policies can be defined through the IOS CLI. Scripts provide more control than do applets.
EEM Server
The EEM server is a bridge between the policies and internal Cisco IOS subsystems used in the event detectors. Some of the functions of the EEM server are to register events seen in the IOS subsystems, store information about an events, publish events, request additional information about events, register internal script directories, register Tcl scripts and applets, and process actions taken by user-defined scripts.
Event Detectors
Event detectors monitor the operational state of processes on an IOS device. These processes run at medium priority and are always operational. On detecting an event, an event detector sends an alert that provides information about the specific event. The list that follows describes a few of the event detectors in Cisco IOS:
▪ Syslog event detector: This event detector is triggered when a syslog message match is seen in the output of the console. Additional granularity can be achieved depending on the number of occurrences for any given message. Console logging does not have to be active for the syslog event detector to generate events; this is completely independent of which logging targets are configured.
▪ SNMP event detector: A specific SNMP variable can be polled, and if the SNMP variable reaches a threshold, a trigger can be generated.
▪ IP SLA event detector: This detector publishes an event when an IP service-level agreement (SLA) reaction is triggered.
▪ Interface event detector: This detector monitors interface counters based on a defined threshold value. The threshold can be specified as an absolute value or as an incremental value.
▪ CLI event detector: This event detector triggers when a specified command is entered via a console or Telnet/SSH session. This detector screens CLI commands that match a regular expression. When a match is found, an event is published, and the CLI event detector can perform a logical match before the command is parsed and executed.
▪ NetFlow event detector: When a NetFlow event is triggered, the NetFlow event detector publishes an event.
▪ Enhanced object tracking event detector: This event detector is triggered when the status of the tracked object changes. A unique number identifies each tracked object. This number is specified on the tracking CLI, and the detector process uses this number to track a specific object. The tracking process periodically polls the tracked objects and notes any change in value. The changes in the tracked object are communicated to the event detector process either immediately or after a specified delay. The object values are reported as either up or down. Enhanced object tracking is now integrated with EEM to allow EEM to report on the status change of a tracked object. For example, the Hot Standby Router Protocol (HSRP) active router may change because of the loss of a neighbor router or due to an interface state change.
▪ Routing event detector: This event detector is invoked when information in the Routing Information Base (RIB) has been changed.
The EEM event detectors have evolved based on IOS releases. The functionality of event detection and action depends on the specific release. Use the Cisco Feature Navigator (https://cfnng.cisco.com/) or the show event manager version command to discover which version of EEM is supported on your device. The current latest version of EEM is 4.0.
Writing EEM Policies
As mentioned earlier, EEM offers the ability to monitor events and take informational or corrective action when monitored events occur or a threshold is reached. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs. There are two types of EEM policies: an applet or a script. An applet is a simple form of policy that is defined in the CLI configuration. A script is a form of policy that is written in Tcl.
The version of EEM is based on the IOS release cycle. It is important to understand the functionality of EEM based on the IOS image so that you fully understand the features and functionality of the event detectors and what is supported.
EEM Applet
Using an EEM applet is a concise method for defining event screening criteria and the actions to be taken when a particular event occurs. In applet configuration mode, three types of configuration statements are supported. The event commands are used to specify the event criteria that 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.
Only one event configuration command is allowed in an applet configuration. When applet configuration mode is exited and the 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 in an applet configuration. Use the show event manager policy registered command to display a list of registered applets.
Before modifying an EEM applet, you need to be aware that the existing applet is not replaced until you exit applet configuration mode. While you are in applet configuration mode modifying the applet, the existing applet may be executing. It is safe to modify the applet without unregistering it. When you exit applet configuration mode, the old applet is unregistered, and the new version is registered.
The action configuration commands are uniquely identified using the label argument, which can be any string value. Actions are sorted in ascending alphanumeric key sequence, using the label argument as the sort key, and they are run using this sequence.
The EEM schedules and runs policies on the basis of an event specification that is contained within a policy. When applet configuration mode is exited, EEM examines the event and action commands that are entered and registers the applet to be run when a specified event occurs.
EEM Script
You define scripts by using an ASCII editor and then copying the script to the networking devices to register them with EEM. EEM supports Tcl scripts.
EEM allows you to write and implement your own policies using Tcl. Writing an EEM policy involves several actions:
▪ Selecting the event for which the policy is run.
▪ Defining the event detector options associated with logging and responding to the event.
▪ Choosing the actions to be followed when the event occurs.
Cisco provides enhancements to Tcl in the form of keyword extensions that facilitate the development of EEM policies. The main categories of keywords identify the detected event, the subsequent action, utility information, counter values, and system information.
Writing an EEM Policy Using the Cisco IOS CLI
To register an applet with EEM, you can first define environment variables that the applet will use. EEM environment variables for EEM policies are defined using the EEM event manager environment configuration command. By convention, every Cisco EEM environment variable begins with an underscore (_). You can display the EEM environment variables set on a system by using the show event manager environment privileged EXEC command. For example, you can create EEM policies that can send emails when an event occurs. The variables could include _email_server, _email_to, _email_from, and _email_cc. These variables could then be used in the applet to generate email notifications when specific events occur.
Once the (optional) variables are defined, you use the event manager applet applet-name global configuration command to enter EEM configuration mode. You then use the event and action commands to build the applet. Only one event command is allowed in an EEM applet, but multiple action commands are permitted.
Some of the EEM events that are available are CLI events, config events, interface events, routing events, syslog events, SNMP events, and track events. EEM actions can be numerous, and it can be helpful to add labels so you can sort them.
Example 3-4 shows the creation of an applet that matches a syslog pattern using a regular expression. When the interface GigabitEthernet2/0 changes state to down, an event trigger is generated. The event in this case is to generate a syslog message and email the network administrator that there is an issue with the interface. Notice that environment variables are defined for use in the applet.
Example 3-4 EEM Applet Example
Using EEM and Tcl Scripts
Tool Command Language (Tcl), invented in the late 1980s, is a dynamic programming or scripting language, an interpreter, and a C library. Tcl helps users control other applications or utilities by using basic flow control.
Tcl is built into Cisco routers and switches to allow engineers to interact directly with a device by using various Tcl scripts. Tcl is a very useful scripting language that provides many ways to streamline different tasks that can help with day-to-day operations and monitoring of a network. The following are some of the tasks that can be automated by using these scripts:
▪ Verifying IP and IPv6 reachability by using ping
▪ Verifying IP and IPv6 reachability by using traceroute
▪ Checking interface statistics
▪ Retrieving SNMP information by accessing MIBs
▪ Sending email messages containing CLI output from Tcl scripts
Most often, basic Tcl scripts are entered line by line in the Tcl shell. However, for more advanced scripting methods, you can load a script into the flash memory of the device you are working on and execute the script from there.
You can also verify that an image you are using has the Tcl interpreter by just entering the command tclsh at the router prompt in privileged mode:
Router# tclsh Router(tcl)#
As you can see here, the command prompt changes to show that you are in Tcl mode. Commands entered at the (tcl) prompt will be handled by the Tcl interpreter if it understands them. If a command is not understood, it is passed along to the standard IOS command process.
Example 3-5 shows a simple Tcl script that pings three devices. That script is saved with the name ping_script.tcl and is copied to the router’s flash memory by using TFTP. An EEM applet called myping is then defined that calls the Tcl script. Notice that when the applet is executed, the router pings the three addresses defined in the Tcl script.