EEM Demystified, part 1

A discussion / introduction to EEM, and basic configurations.
Why EEM?
Embedded Event Manager (EEM) allows you to have event tracking and management functionality directly on the Cisco IOS device, rather than on an external device. By having the configuration locally, actions can still be taken, even if the connection to an external monitoring station is unavailable. Plus, it is a great topic that can be used to challenge (or torment) CCIE candidates.

EEM Components:
Let’s start by taking a look at the components of EEM: EEM server, event publishers, and event subscribers.
EEM server – an internal process that handles the interaction between the publishers and subscribers.
EEM publisher (detector) – software that screens events, publishes if there is a policy match. Some of the different detectors are CLI, NetFlow, SNMP, syslog, timers and counters. Newer releases have more options available.
EEM subscriber (policy) – defines an event and actions to be taken. There are two policy types, applets and scripts. Applets are defined within CLI, scripts are written using TCL.
For this section, we are just going to look at some of the basic applet configurations, which are defined using the CLI.
Policy Creation:
Basic steps for creating a policy:
1. Select event
2. Define detector options for the event
3. Define variables (if needed)
4. Define actions (optional)
Variables will be covered more in part two. This section is focusing on events and actions.
Start off by creating the applet with the CLI command event manager applet YYY, where YYY is the applet name that you want to use.
For a basic applet configuration, we will have an event and one or more actions.
Defining the event:
For the command syntax, we have the option of just specifying an event, or specifying an event with a tag value. Newer versions allow multiple events to be specified, and the tag values are used to correlate to attribute tags. We will come back to attribute tags in a later example, for now, just be aware that if you only have a single event, the tag is optional. Here are some sample event config lines. As mentioned earlier, without tags and additional configuration, you would only have one of these lines within your applet.

event syslog pattern ".*UPDOWN.*FastEthernet1/0.*"

event none

event track 99 state any

event timer cron cron-entry "15 13 * * 1-5"

There are a variety of different event detectors. For some of these we will go into greater detail, but here is a quick list of what some of the various options watch:
cli – screening CLI input for regex
counter – watch a named counter
interface – generic interface counters / thresholds (absolute or incremental)
ioswdsysmon – watchdog – CPU / memory values/ thresholds
ipsla – watch for SLA events
nf – watch for NetFlow events
none – allows an event to be run manually
oir – hardware – online insertion removal events
resource – event from embedded resource manager
rf – dual RP – redundancy framework
routing – changes to RIB
rpc – invoke from off-box using SSH/SOAP encoding to exchange XML messages
snmp – monitor a MIB object for values / thresholds
snmp-notification – match info in trap/inform messages
syslog – screen for regex match
timer – absolute time of day, countdown, watchdog, CRON
track – Tracking object event
Note: If you do not configure an event, your applet will not show as registered, and you will receive an error message when exiting applet configuration mode.
Detectors:
Let’s take a look at some of the detectors in more detail.
None
This detector will let you manually trigger, using the event manager applet YYY run command, where YYY is the name of your applet.
CLI Detector
This detector allows for regex matching of CLI input.
Some of the various options that we have within the CLI detector:
Synchronous vs. Asynchronous
With Synchronous ( sync yes), the CLI command in question is not executed until the policy exits. Whether or not the command runs depends on the value for the variable _exit_status. If _exit_status is 1, the command runs, if it is 0, the command is skipped. (More on configuring variables later in part two.)
With Asynchronous (sync no), the event is published, and is the command can be suppressed (skip yes) or executed (skip no)
Timer Detector
Some of the various options include:
absolute
countdown – counts down to 0
watchdog – counts down to 0 and then resets to initial value
CRON – uses CRON specification
For those of you not familiar with CRON, here is a basic field listing and examples:
minute – range 0 to 59
hour – range 0 to 23
day of month 1 to 31
month of year 1 to 12
day of week – 0 to 6 (Sunday is 0)
For individual fields, an asterisk represents all valid values, a comma can specify a list of values, and a hyphen can specify a range.
“1 1 1 1 *” 1:01 AM, 1 January
“1 9 * * 1-5″ 9:01 AM, Monday-Friday
“5 8,16 * * 0,6″ 8:05 AM or 4:05 PM, Saturday or Sunday
SNMP trap detector
watch for a trap with a specified OID.
Track detector
Watch for change in a defined track object. Can watch for going down to up (up), up to down (down), or either of those two changes (any)
Actions:
Compared to the event types, the IOS descriptions for actions are a lot more straightforward.
With multiple actions, the tags will be sorted in ascending alphanumeric (lexicographical) order, using the label. Most examples use labels like 1.0, 2.0, 3.0, but using numbers and decimal values is not required.
Here is a sample list of action commands with various tag values, as sorted by the device. Notice that numbers come before letters, and that upper case letters come before lower case. Also, notice that 11 comes before 2 in the sort order, since it is sorted by the order of the individual characters.

action ... puts "where"
action 1.0 puts "Reno"
action 11.0 puts "Today"
action 2.0 puts "EEM"
action RRR puts "ABC"
action abc puts "12345"
action nnn puts nonewline "test123"
action rrr puts "hellothere"

Action prerequisites
This may be self-explanatory, but there are times when you need to have additional configuration outside of the applet. Here are some examples, as well as items that may not already be configured.
Action:   Requirement:
Track      -  Define objects
SNMP     – Trap Basic snmp config, enable traps event-manager
Syslog     - Logging enabled
Individual Actions
OK, so let’s look at some of the actions, grouped by functions:
cli – execute a CLI command
gets/puts – used to send to or pull from tty.
mail/syslog/snmp-trap/cns-event – used to send messages
increment/decrement/append – changing variables
if/else/elseif/while/end/break/continue/foreach – conditional operators
wait – pause for a period of time
track – read or set a tracking object
regexp – match
reload/force-switchover – system actions
add/subtract/multiply/divide – hopefully self-explanatory, if you have no idea what these might be used for, then perhaps you have much bigger issues than EEM to worry about.
Applet Examples:
OK, now lets take a look at some examples. Since we are focusing on the available actions, we will use the event value of none, so that we can manually run these, and don’t have to wait for an event to be triggered.
Basic example to “no shut” for an interface, and save the config afterwards.

event manager applet NOSHUT

event none

action 1.0 cli command "enable"

action 2.0 cli command "config term"

action 3.0 cli command "interface Ser0/0/0"

action 4.0 cli command "no shut"

action 5.0 cli command "end"

action 6.0 cli command "write mem"

Basic track and put example. Define the Track object first, configure the applet to read the object state. Object state will be stored by default with the variable _track_state. The puts command can output the value of the variable.

track 1 stub-object
default-state down

event manager applet EOT
 event none
 action 110 track read 1
 action 111 puts "Object 1 is $_track_state."

! Run the applet

Router#event manager run EOT

down

!
Next example, still using track and puts. Here, we want to set the value for the object as well. Even though the applet sets the state of the object, that state is not entered into the variable _track_state unless you read the value. Additional discussion on variables will be covered in part two of this blog entry.

event manager applet EOT2

event none

action 110 track set 1 state up

action 110a track read 1

action 111 puts "$_track_state"

action 112 track set 1 state down

action 112a track read 1

action 113 puts "$_track_state"

Router#event manager run EOT2

up

down

If you look at the output of show track, it will show that EEM made the state changes.

Router#show track 1

Track 1

Stub-object

State is Down

3 changes, last change 00:00:10, by EEM

Router#

Basic example using gets, puts, and wait:

event manager applet G

event none maxrun 300

action 1 gets LINE1

action 2 puts "$LINE1"

action 3 puts "start"

action 4 wait 50

action 5 puts "end wait"

action 6 gets LINE2

action 7 puts "$LINE2"

Note:  If you don’t configure the “maxrun” parameter when configuring “wait”, you may think the applet is broken, and you may not see the items after the wait. The default for “maxrun” is 20 seconds.
Once you have an applet defined, you may want to use it in other locations.  Here, we have the applet titled RUNTEST2 configured to call the applet TEST2 after sending a message to the tty line.

event manager applet TEST2

event none

action 1.0 cli command "enable"

action 2.0 cli command "config term"

action 3.0 cli command "interface Ser0/0/0"

action 4.0 cli command "no shut"

action 5.0 cli command "end"

action 6.0 cli command "write mem"

event manager applet RUNTEST2

event none

action 1 puts "Enabling Ser0/0/0 Interface"

action 2 policy TEST2

Router#event manager run RUNTEST2

Enabling Ser0/0/0 Interface
Router#

Jan 18 12:15:57.063: %SYS-5-CONFIG_I: Configured from console by on vty0 (EEM:TEST2)

Router#

Jan 18 12:15:59.071: %LINK-3-UPDOWN: Interface Serial0/0/0, changed state to up

Router#

Jan 18 12:16:00.131: %LINEPROTO-5-UPDOWN: Line protocol on Interface Serial0/0/0, changed state to up

Router#

As mentioned earlier, the variable “_exit_status” can be used with synchronous CLI events. Here, we are setting the exit status to 0, so that the command isn’t run. In addition, a syslog message with priority 0 is configured.

event manager applet NOSAVE
event cli pattern "write mem.*" sync yes
action 1.0 syslog priority emergencies msg "Not Allowed"
action 2.0 set _exit_status "0"

For asynchronous events, you can determing whether the command runs (skip no), or doesn’t run (skip yes) keyword options within the event command. Here, we have an applet that is setting a syslog message, and is not allowing the command to execute.

event manager applet NOSAVE2
event cli pattern "write mem.*" sync no skip yes
action 1.0 syslog priority emergencies msg "NO!"

As mentioned earlier, it is possible to have an event without an action. You may receive a warning message that you do not have an action configured, but the event will still trigger. In the case below, the CLI interception will prevent someone from using the write mem command.

event manager applet NOSAVE2
event cli pattern "write me.*" sync no skip yes

More examples, in addition to some more complex configurations, will be covered in part two.