Embedded Event Manager (EEM) provides real-time event detection and automation directly on Cisco IOS, IOS-XR and NX-OS platform. EEM offers the ability to monitor events and take informational, corrective, or any desired EEM action when the monitored events occur or when a threshold is reached.
EEM provides 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. The diagram below outlines how the components interact.
An EEM policy is an entity that defines an event and the actions to be taken when that event occurs. The number of ‘Event Detectors’ vary specific between the different IOS versions.
There are three different types of environment variables associated with Embedded Event Manager:
- User-defined : Defined by you if you create an environment variable in a policy that you have written.
- Cisco-defined :Defined by Cisco for a specific sample policy.
- Cisco built-in (available in EEM applets) : Defined by Cisco and can be read only or read/write. The read only variables are set by the system before an applet starts to execute. The single read/write variable, _exit_status, allows you to set the exit status at policy exit for policies triggered from synchronous events.
Cisco-defined environment variables begin with an underscore character (_). Cisco strongly recommend that customers avoid the same naming convention to prevent naming conflicts.
To create a user defined global variable we use the “event manager environment” command :
event manager environment my_var1 my string
To view the global user defined variables and their values use the “show event manager environment” command.
To view the built-in environment variables for the cli event detector you would use the “show event manager detector cli detailed” command.
As outlined above there are many event detectors, you should seek to use the appropriate detector for you requirement.
I’m going to look at one of the most common event detectors, the CLI. Lets look a simple example:
1:event manager environment my_var1 test variable
2:event manager applet TEST
3: event cli pattern “reload” sync yes (command is blocked/replaced and script runs before command)
4: action 1.0 puts “Cannot reload the router”
5: action 1.1 puts “Hello CLI this is my $my_var1”
6: action 1.2 cli command “enable”
7: action 1.3 cli command “show run | section event”
8: action 1.5 puts “$_cli_result”
Lets break this down line by line.
The 1st line just defines a global variable called “my_var1” that we can use to read or write the value “my string”.
Line 2 is where we define our event manager applet named TEST
Line 3 uses the CLI event detector to match on a pattern based on a regular expression
Line 4-8 defines the actions we want to take when the event is detected and matches our pattern
Line 5 adds some text and prints our value defined in my_var1
Line 6 runs the CLI command “enable”
Line 7 runs the CLI command “show run | section event”
Line 8 prints the output of the CLI commands defined in our applet
Line 3 needs expanding, the CLI detector needs one or two options to define how the EEM policy and CLI commands are executed. We have two options Synchronous or Asynchronous. Sync yes means the CLI command is not executed until the EEM policy exits and allows us to control if the command is executed or not or even replace the command.
When the sync yes option is selected you cannot set the second option skip. The skip option determines whether to skip CLI command execution and has to options yes|no. With the sync no option configured, the policy is run asynchronously and you can choose to set the skip option to yes or no.
In the above example the reload command is NOT run, even at the end of the script, we replace the command with our own. If we wanted our CLI commands to run and to execute the reload command at the end of the script we could set the _exit_status variable to 1 this will run the script first and then the reload command at the end.
action 1.6 set _exit_status “1”
With sync no skip yes the command is not run even if you set the _exit_status to 1
With sync no skip no the command is run run before the script
The _exit_status applies to synchronous publishing of CLI events not asynchronous events.
The 1.0 – 1.6 are nothing more than labels and and can be defined in a number of ways from 1 – 6,1a – 1f and 001 -099 are nothing but stings, which means 10.0 would come after 1.0, not 9.0 as one might expect.
An EEM script that is configured with the “event none” command means that there is no automatic event that the applet is monitoring and that this applet will only run when it is triggered manually.
To manually run an EEM applet, the “event manager run” must be executed.
We can use the following show and debug commands if we need to troubleshoot our scripts.
debug event manager action cli (enables debug messages for EEM)
show event manager environment all (displays the name and value of all the EEM environment variables)
show event manager policy registered ? (displays the registered policys)
show event manager detector cli detailed (shows the built-in environment variables for the CLI detector)
no event manager directory user policy <- disables all TCL policys
CTRL-V lets you add a question mark to the script of output if needed.
The “file prompt quiet” command disables the IOS confirmation mechanism that asks you to confirm your actions.
If you are using AAA command authorization, you will want to include the event manager session cli username username command. Otherwise, the CLI commands in the applet will fail. In EEM 3.1 and above you can bypass the authorization.
Here are some EEM Applet examples:
Backup Configuration to TFTP server
event manager environment filename router.cfg
event manager environment tftpserver tftp://10.10.10.10/
event manager applet BACKUP_DEVICE_CONFIG
event cli pattern "write mem.*" sync yes
action 001 info type routername
action 002 cli command "enable"
action 003 cli command "configure terminal"
action 004 cli command "file prompt quiet"
action 005 cli command "end"
action 006 cli command "copy start $tftpserver$_info_routername$filename"
action 007 cli command "configure terminal"
action 008 cli command "no file prompt quiet"
action 009 syslog priority informational msg "Configuration File Changed! TFTP backup successful."
Applet calling a TCL script
event manager applet Ping
event none
action 1.0 cli command "enable"
action 1.1 cli command "tclsh flash:/ping.tcl"
Router# more flash:ping.tcl
foreach ip_address {
192.168.0.1
192.168.0.2
192.168.0.3
192.168.0.4
192.168.0.5
192.168.0.6
192.168.0.8
192.168.0.9
} { ping $ip_address}
Router# event manager run Ping
You can also run TCL scripts from the tcl application itself.
Router# tclsh
Router(tcl)# source flash:ping.tcl
EEM Links
https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/eem/configuration/15-mt/eem-15-mt-book/eem-overview.html
https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/eem/command/eem-cr-book.html
https://community.cisco.com/t5/networking-documents/cisco-eem-best-practices/ta-p/3127596
https://www.marcuscom.com/convert_applet/ (Convert an EEM Applet Policy into a Tcl Script Policy)