Cisco IOS Embedded Event Manager (EEM)

Embedded Event Manager (EEM) is a technology on Cisco Routers that lets you run scripts or commands when a certain event happens. It’s probably best just to show you some examples to see how it works. This is the topology that I will use:

 

Syslog Events

Syslog messages are the messages that you see by default on your console. Interfaces going up or down, OSPF neighbors that disappear and such are all syslog messages. EEM can take action when one of these messages shows up. Let’s start with an example that enables an interface once it goes down.

Interface Recovery

R2(config)#
event manager applet INTERFACE_DOWN 
 event syslog pattern "Interface FastEthernet0/0, changed state to down"
 action 1.0 cli command "enable"
 action 2.0 cli command "conf term"
 action 3.0 cli command "interface fa0/0"
 action 4.0 cli command "no shut"

The applet is called “INTERFACE_DOWN” and the event is a syslog pattern that matches the text when an interface goes down. When this occurs, we run some commands. What happens is that whenever someone shuts the interface, EEM will do a “no shut” on it.

To demonstrate that this works, I’ll enable a debug:

R2#debug event manager action cli
Debug EEM action cli debugging is on

This will show the commands that EEM runs when the event occurs. Let’s do a shut on that interface:

R2(config)#interface FastEthernet 0/0
R2(config-if)#shutdown

Within a few seconds, you will see this:

R2#
%LINK-5-CHANGED: Interface FastEthernet0/0, changed state to administratively down
%LINEPROTO-5-UPDOWN: Line protocol on Interface FastEthernet0/0, changed state to down

%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : CTL : cli_open called.
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : OUT : R2>
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : IN  : R2>enable
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : OUT : R2#
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : IN  : R2#conf term
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : OUT : Enter configuration commands, one per line.  End with CNTL/Z.
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : OUT : R2(config)#
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : IN  : R2(config)#interface fa0/0
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : OUT : R2(config-if)#
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : IN  : R2(config-if)#no shut
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : OUT : R2(config-if)#
%HA_EM-6-LOG: INTERFACE_DOWN : DEBUG(cli_lib) : : CTL : cli_close called.

%LINK-3-UPDOWN: Interface FastEthernet0/0, changed state to up
%LINEPROTO-5-UPDOWN: Line protocol on Interface FastEthernet0/0, changed state to up

The interface went down, EEM ran the commands and the interface is up again. Simple, but I think this is a good example to demonstrate how EEM works. Let’s see what else we can do…

OSPF Adjacency Changes

The next example is perhaps useful. Whenever the OSPF adjacency disappears, you will see a syslog message on your console. We’ll use this message as the event, and once it occurs, we enable OSPF adjacency debugging and send an e-mail:

R2(config)#
event manager applet OSPF_DOWN 
 event syslog pattern "Nbr 192.168.12.1 on FastEthernet0/0 from FULL to DOWN"
 action 1.0 cli command "enable"
 action 2.0 cli command "debug ip ospf adj"
 action 3.0 mail server "smtp.ziggo.nl" to "info@networklessons.com" from "R2@networklessons.com" subject "OSPF IS DOWN" body "Please fix OSPF"

The event that I used is a syslog message that should look familiar. The first two actions are executed on the CLI, but the third action is for the e-mail. It will send a message to info@networklessons.com through SMTP-server “smtp.ziggo.nl”.

Let’s give it a try. I have to enable another debug if I want to see the mail action:

R2#debug event manager action mail 
Debug EEM action mail debugging is on

Once the OSPF neighbor adjacency is established, I’ll shut the interface on one of the routers so it breaks:

R1(config)#interface FastEthernet 0/0
R1(config-if)#shutdown

And this is what you’ll see:

R2#
Translating "smtp.ziggo.nl"...domain server (255.255.255.255)

%OSPF-5-ADJCHG: Process 1, Nbr 192.168.12.1 on FastEthernet0/0 from FULL to DOWN, Neighbor Down: Dead timer expired

%HA_EM-6-LOG: OSPF_DOWN : DEBUG(cli_lib) : : CTL : cli_open called.
%HA_EM-6-LOG: OSPF_DOWN : DEBUG(cli_lib) : : OUT : R2>
%HA_EM-6-LOG: OSPF_DOWN : DEBUG(cli_lib) : : IN  : R2>enable
%HA_EM-6-LOG: OSPF_DOWN : DEBUG(cli_lib) : : OUT : R2#
%HA_EM-6-LOG: OSPF_DOWN : DEBUG(cli_lib) : : IN  : R2#debug ip ospf adj
%HA_EM-6-LOG: OSPF_DOWN : DEBUG(cli_lib) : : OUT : OSPF adjacency events debugging is on
%HA_EM-6-LOG: OSPF_DOWN : DEBUG(cli_lib) : : OUT : R2#
%HA_EM-6-LOG: OSPF_DOWN : DEBUG(smtp_lib) : smtp_connect_attempt: 1

OSPF: Build router LSA for area 0, router ID 192.168.12.2, seq 0x8000000B, process 1
OSPF: No full nbrs to build Net Lsa for interface FastEthernet0/0
OSPF: Build network LSA for FastEthernet0/0, router ID 192.168.12.2
OSPF: Build network LSA for FastEthernet0/0, router ID 192.168.12.2

%HA_EM-6-LOG: OSPF_DOWN : DEBUG(smtp_lib) : fh_smtp_connect failed at attempt 1
Translating "smtp.ziggo.nl"...domain server (255.255.255.255)
%HA_EM-6-LOG: OSPF_DOWN : DEBUG(smtp_lib) : smtp_connect_attempt: 2

%HA_EM-6-LOG: OSPF_DOWN : DEBUG(smtp_lib) : fh_smtp_connect callback timer is awake
%HA_EM-3-FMPD_SMTP: Error occurred when sending mail to SMTP server: smtp.ziggo.nl : timeout error
%HA_EM-6-LOG: OSPF_DOWN : DEBUG(cli_lib) : : CTL : cli_close called.

My router isn’t connected to the Internet, but you can see it’s trying to contact the SMTP server and send an e-mail. It also enabled the OSPF adjacency debug, thanks to the CLI commands.

CLI Events

The previous two examples used syslog messages as the event, but you can also take action based on commands used on the CLI. The example below is a funny one. Whenever someone watches the running configuration it will exclude all lines with the word “interface” in it:

R2(config)#
event manager applet SHOW_RUN_NO_INTERFACES 
 event cli pattern "show run" sync yes
 action 1.0 cli command "enable"
 action 2.0 cli command "show run | exclude interface"
 action 3.0 puts "$_cli_result"
 action 4.0 set $_exit_status "0"

As you can see above, the event is a CLI pattern. The “sync yes” parameter is required. This tells EEM to run the script before running the show run command. When the script is done, it sets the exit status to 0. Basically, this means that whenever someone uses the show run command, the script will run show run | exclude interface instead and give you the output.

Let’s see what the result is…

R2#show running-config 

Building configuration...

You will see the output of the running configuration, and if you left the debug on, you’ll see what EEM is doing behind the scenes:

R2#
%HA_EM-6-LOG: SHOW_RUN_NO_INTERFACES : DEBUG(cli_lib) : : CTL : cli_open called.
%HA_EM-6-LOG: SHOW_RUN_NO_INTERFACES : DEBUG(cli_lib) : : OUT : R2>
%HA_EM-6-LOG: SHOW_RUN_NO_INTERFACES : DEBUG(cli_lib) : : IN  : R2>enable
%HA_EM-6-LOG: SHOW_RUN_NO_INTERFACES : DEBUG(cli_lib) : : OUT : R2#
%HA_EM-6-LOG: SHOW_RUN_NO_INTERFACES : DEBUG(cli_lib) : : IN  : R2#show run | exclude interface
%HA_EM-6-LOG: SHOW_RUN_NO_INTERFACES : DEBUG(cli_lib) : : OUT : Building configuration...

Somewhere further down the running-config, you can see that the lines with “interface” in them were removed:

!
 ip address 192.168.12.2 255.255.255.0
 duplex auto
 speed auto

While this isn’t very useful, I think this is a good example to see what it does. A good real-life scenario might be hiding all lines that have “username” or “enable secret” in them for certain users.

Interface Events

You have seen syslog and CLI pattern events, but we have others. What about interface counters? It might be useful to perform an action when some interface counters have a certain value. Here’s an example: