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.