Skip to content
Log in Sign up My account

6.6 Embedded Event Manager Applets

Blueprint 6.6: Construct an EEM applet to automate configuration, troubleshooting, or data collection

  • EEM architecture: event detectors, the EEM server, policies (applets and Tcl scripts)
  • Event detectors: syslog, timer (cron, watchdog, countdown), CLI, track, interface counters, none
  • Actions: cli command, syslog msg, mail, wait, set, regexp, if/else/end
  • Built-in variables such as $_cli_result and $_syslog_msg
  • Label ordering, privilege and AAA, maxrun
  • Verification and debugging

The verb is construct. Expect to read an applet and say what it does, put applet lines in the right order, fix one that does not work, or type one in a simulation (see Sim 12). EEM works the same on IOS and IOS XE, so you can practise on IOSv.

What EEM is

Embedded Event Manager is an automation engine that runs on the device. It watches for an event and, when the event occurs, runs a list of actions. No external server, script host or network connection is needed, which makes EEM the right tool when the device must react on its own, for example when it has just lost its uplink.

graph LR
  subgraph Device ["IOS XE device"]
    ED["Event detectors<br/>syslog, timer, cli, track, interface"] --> SRV["EEM server"]
    SRV --> POL["Policies<br/>applets (CLI) and Tcl scripts"]
    POL --> ACT["Actions<br/>cli, syslog, mail, set, if"]
  end
  ACT --> OUT["Config change, saved output, log message, email"]
Policy type Written in Where it lives Exam relevance
Applet IOS configuration commands Running configuration This is what 6.6 tests
Tcl script Tcl A file on flash, registered with event manager policy Recognise the name only

Applet structure

event manager applet NAME
 event <detector> <parameters>        ! exactly one trigger
 action <label> <action> <arguments>  ! as many actions as needed
 action <label> <action> <arguments>

Rules that questions are built on:

  1. An applet has one event statement. (Recent releases can correlate several events with event tag and trigger, but the exam's applets use one.)
  2. Actions run in label order, and labels are sorted as strings. 1.0, 2.0, 10.0 sorts as 1.0, 10.0, 2.0. Use labels with the same number of digits, such as 010, 020, 030, or decimals that stay below 10 (1.0 to 9.9), or the order will surprise you.
  3. cli actions start in user EXEC mode. An applet that changes configuration or runs privileged commands needs action ... cli command "enable" first, then configure terminal.
  4. An applet has a maximum run time, 20 seconds by default, set with the maxrun option on the event line. An action that waits for an interactive prompt that never comes holds the applet until maxrun kills it.
  5. If AAA command authorization is enabled, EEM CLI commands are authorised too. Either set a user with event manager session cli username NAME, or add authorization bypass to the applet name line.

Exam trap

An applet whose actions start with configure terminal and no enable silently fails, because the CLI session starts unprivileged. In "what is wrong with this applet" questions, check the first action first.

Event detectors

Detector Syntax example Fires when
Syslog event syslog pattern "LINEPROTO-5-UPDOWN.*Gi.*down" A log message matches the regular expression
Syslog with count event syslog pattern "SEC_LOGIN-4-LOGIN_FAILED" occurs 5 period 60 The pattern appears 5 times within 60 seconds
Cron timer event timer cron cron-entry "30 23 * * 1-5" At a calendar time (here 23:30 Monday to Friday)
Watchdog timer event timer watchdog time 300 Every 300 seconds, repeatedly
Countdown timer event timer countdown time 600 Once, 600 seconds after the applet is configured
CLI event cli pattern "^write erase" sync no skip yes A user enters a command matching the pattern
Track event track 10 state down Tracked object 10 changes to down
Interface counter event interface name GigabitEthernet2 parameter input_errors entry-op ge entry-val 100 entry-type increment poll-interval 60 Input errors rise by 100 or more between polls
None (manual) event none An administrator runs event manager run NAME

The cron entry has five fields: minute, hour, day of month, month, day of week.

Cron entry Runs
0 2 * * * 02:00 every day
*/15 * * * * Every 15 minutes
0 8 1 * * 08:00 on the 1st of each month
0 22 * * 0 22:00 every Sunday

The syslog pattern is a regular expression matched against the message. A dot matches any character, .* matches anything, and ^ anchors the start. You do not need the timestamp or sequence number in the pattern.

For the CLI detector, sync no skip yes runs the applet in parallel and skips (blocks) the typed command, sync no skip no runs the applet and lets the command run, and sync yes runs the applet first and lets its exit status decide. The pattern is matched against the fully expanded command, so wr er matches ^write erase.

Actions

Action Example Does
cli command action 2.0 cli command "show ip route" Runs a command; output goes to $_cli_result
cli command with pattern action 3.0 cli command "delete flash:old.txt" pattern "confirm" Runs a command that prompts, and waits for the prompt text
syslog msg action 4.0 syslog msg "Uplink lost" Writes a log message (as %HA_EM-6-LOG: NAME: Uplink lost)
syslog priority action 4.0 syslog priority critical msg "BGP down" Same, with a severity
mail action 5.0 mail server "10.1.1.25" to "[email protected]" from "[email protected]" subject "R1 alert" body "$_cli_result" Sends an email
wait action 6.0 wait 10 Pauses, in seconds
set action 1.0 set count "0" Sets a variable
regexp action 3.0 regexp "down" "$_cli_result" Sets $_regexp_result to 1 on a match, 0 otherwise
if / else / end action 4.0 if $_regexp_result eq "1" Conditional block
puts action 2.0 puts "$_cli_result" Prints to the terminal (useful with event none)
reload action 9.0 reload Reloads the device

Useful built-in variables:

Variable Contains
$_cli_result Output of the most recent cli command
$_syslog_msg The syslog message that triggered the applet (syslog detector)
$_cli_msg The command that triggered the applet (CLI detector)
$_event_pub_time When the event was published
$_regexp_result 1 if the last regexp matched

Global variables defined with event manager environment NAME value can be used in any applet, such as event manager environment _noc_email [email protected] and then $_noc_email.

Four applets to know

event manager applet GI2-DOWN-CAPTURE
 event syslog pattern "LINEPROTO-5-UPDOWN.*GigabitEthernet2, changed state to down"
 action 1.0 cli command "enable"
 action 2.0 cli command "show clock | append flash:gi2-down.txt"
 action 3.0 cli command "show interfaces GigabitEthernet2 | append flash:gi2-down.txt"
 action 4.0 cli command "show logging | include GigabitEthernet2 | append flash:gi2-down.txt"
 action 5.0 cli command "show ip route summary | append flash:gi2-down.txt"
 action 6.0 syslog msg "Gi2 down, diagnostics saved to flash:gi2-down.txt"

Troubleshooting data is captured at the moment of failure, before anyone logs in. | append adds to the file; | redirect would overwrite it.

track 10 ip sla 10 reachability
!
event manager applet TUNNEL-RESET
 event track 10 state down maxrun 60
 action 1.0 cli command "enable"
 action 2.0 cli command "configure terminal"
 action 3.0 cli command "interface Tunnel10"
 action 4.0 cli command "shutdown"
 action 5.0 wait 5
 action 6.0 cli command "no shutdown"
 action 7.0 cli command "end"
 action 8.0 syslog priority warnings msg "IP SLA 10 failed, Tunnel10 bounced"

The 5-second wait counts toward maxrun, so it is raised to 60 seconds.

event manager applet NIGHTLY-SAVE
 event timer cron cron-entry "0 2 * * *"
 action 1.0 cli command "enable"
 action 2.0 cli command "show running-config | redirect flash:nightly.cfg"
 action 3.0 cli command "write memory"
 action 4.0 syslog msg "Nightly backup and save complete"

write memory and | redirect do not prompt, which keeps the applet from hanging. copy running-config startup-config asks for a destination filename unless file prompt quiet is configured.

event manager applet NO-WRITE-ERASE
 event cli pattern "^write erase" sync no skip yes
 action 1.0 syslog priority critical msg "Blocked command: $_cli_msg"

The command is never executed. $_cli_msg is set by the CLI detector to the command that matched the pattern.

An applet with logic

event manager applet CHECK-BGP
 event timer watchdog time 300
 action 010 cli command "enable"
 action 020 cli command "show ip bgp summary | include 10.1.2.2"
 action 030 regexp "Idle|Active" "$_cli_result"
 action 040 if $_regexp_result eq "1"
 action 050  syslog priority errors msg "BGP to 10.1.2.2 is not Established"
 action 060  cli command "clear ip bgp 10.1.2.2 soft"
 action 070 end

Every five minutes the applet reads the BGP summary line for neighbor 10.1.2.2. A neighbor that is not established shows Idle or Active in the state column (an established one shows a prefix count), so the regular expression matches and the applet logs an error and requests a soft refresh. The three-digit labels keep the order correct past nine actions.

graph TB
  T["Watchdog timer, every 300 s"] --> C1["cli: show ip bgp summary, include neighbor"]
  C1 --> R["regexp Idle or Active in cli_result"]
  R --> D{"regexp_result eq 1?"}
  D -->|"yes"| A1["syslog error and clear ip bgp soft"]
  D -->|"no"| E["end, nothing to do"]

Exam trap

Watch for an applet that triggers on its own output. If a syslog applet's pattern is "down" and its action logs "Interface went down", the action generates a new matching message and the applet can retrigger itself. Make patterns specific (include the mnemonic such as LINEPROTO-5-UPDOWN and the interface) and keep action messages different from the pattern.

Exam trap

event timer watchdog repeats; event timer countdown fires once; event timer cron follows the calendar. If the question says "every hour on the hour", the answer is cron 0 * * * *, not a watchdog of 3600 seconds, because the watchdog counts from when the applet was registered.

Verification

Command Shows
show event manager policy registered Registered applets, their event type and full definition
show event manager history events When each applet ran and whether it succeeded
show event manager environment Global environment variables
event manager run NAME Runs an event none applet by hand
debug event manager action cli Each CLI command an applet sends and the output it gets back
show logging \| include HA_EM Messages written by action syslog 
R1# show event manager policy registered
No.  Class     Type    Event Type          Trap  Time Registered           Name
1    applet    user    syslog              Off   Wed Oct 7 10:20:11 2026   GI2-DOWN-CAPTURE
 pattern {LINEPROTO-5-UPDOWN.*GigabitEthernet2, changed state to down}
 maxrun 20.000
 action 1.0 cli command "enable"
 action 2.0 cli command "show clock | append flash:gi2-down.txt"
 ...

The column layout varies slightly by release; what matters is that the applet is listed, with the event type you expect. An applet with a typo in its event line is not registered at all, so if it is missing here, re-enter the event line and read the error.

Lab: build and test four applets

Topology: R1 and R2 connected on Gi2, addressing per the course convention. R1 is a Catalyst 8000v (IOSv works too, with GigabitEthernet0/1 in place of GigabitEthernet2).

graph LR
  R1["R1<br/>Lo0 10.255.255.1"] -- "Gi2 10.1.2.1/30 to Gi2 10.1.2.2/30" --- R2["R2<br/>Lo0 10.255.255.2"]

  1. Base configuration:

    hostname R1
interface GigabitEthernet2
 ip address 10.1.2.1 255.255.255.252
 no shutdown
!
ip sla 10
 icmp-echo 10.1.2.2 source-interface GigabitEthernet2
 frequency 5
ip sla schedule 10 life forever start-time now
track 10 ip sla 10 reachability

    Configure R2 Gi2 as 10.1.2.2/30 and confirm ping 10.1.2.2 from R1 succeeds.

  2. Enter the Collect data on failure, Scheduled task and Block a command applets from the tabs above. For the TUNNEL-RESET applet, replace Tunnel10 with Loopback50 (create interface Loopback50 first) so you can watch it bounce without building a tunnel.

  3. Confirm all four are registered with show event manager policy registered.

  4. Test the capture applet by shutting R1 Gi2 and bringing it back:

    R1(config)# interface GigabitEthernet2
R1(config-if)# shutdown
%LINK-5-CHANGED: Interface GigabitEthernet2, changed state to administratively down
%LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet2, changed state to down
%HA_EM-6-LOG: GI2-DOWN-CAPTURE: Gi2 down, diagnostics saved to flash:gi2-down.txt
R1(config-if)# no shutdown
R1(config-if)# end
R1# more flash:gi2-down.txt

    The file contains the clock, the interface output, the matching log lines and the route summary.

  5. The interface shutdown also makes IP SLA 10 fail. Within a few seconds track 10 goes down and the TUNNEL-RESET applet fires:

    %TRACK-6-STATE: 10 ip sla 10 reachability Up -> Down
%HA_EM-4-LOG: TUNNEL-RESET: IP SLA 10 failed, Tunnel10 bounced

    Edit the message text if you used Loopback50. Check show logging for the Loopback50 down and up messages in between.

  6. Type write erase and confirm the command is blocked and logged. Then type wr er and confirm the abbreviation is blocked too.

  7. Test the scheduled applet without waiting until 02:00: change its event line to event timer cron cron-entry "*/2 * * * *", wait two minutes, then run dir flash: | include nightly and show event manager history events. Restore the original cron entry afterwards.
  8. Break it on purpose: renumber the capture applet's actions so one label is 10.0 and the others are 1.0 to 6.0, and use debug event manager action cli to watch the order in which they run.

Quick check

An applet has event timer countdown time 3600. How often does it run?

Once, 3600 seconds after it is registered (or after the countdown is restarted). Use watchdog to repeat or cron for calendar times.

Which variable holds the output of the last cli command action?

$_cli_result.

An applet's actions are enable, configure terminal, interface Gi2, shutdown, and the event is event none. How do you trigger it?

With event manager run NAME from privileged EXEC mode. event none has no automatic trigger.

References

  • Embedded Event Manager Configuration Guide, Cisco IOS XE, including "EEM CLI Library Command Extensions" and "Writing Embedded Event Manager Policies Using the Cisco IOS CLI" (search on cisco.com)
  • Cisco IOS Embedded Event Manager Command Reference (search on cisco.com)
  • Cisco DevNet: on-box automation learning labs
  • Cisco Live On-Demand Library: search "Embedded Event Manager"