Guest

Cisco IOS Software Releases 12.3 T

Embedded Event Manager 2.1

Table Of Contents

Embedded Event Manager 2.1

Contents

Prerequisites for Embedded Event Manager 2.1

Information About Embedded Event Manager 2.1

Embedded Event Manager

Embedded Event Manager 2.1

Event Detectors

Embedded Event Manager Actions

Embedded Event Manager Environment Variables

Embedded Event Manager Policies

How to Configure Embedded Event Manager 2.1

Registering and Defining an Embedded Event Manager Applet

EEM Environment Variables

Troubleshooting Tips

Registering and Defining an Embedded Event Manager Policy to Run Manually

Displaying Embedded Event Manager Registered Policies

Unregistering Embedded Event Manager Policies

Examples

Suspending Embedded Event Manager Policy Execution

Examples

Modifying History Table Size and Displaying EEM History Data

Configuration Examples for Embedded Event Manager 2.1

Embedded Event Manager Applet Configuration: Examples

Embedded Event Manager Manual Policy Execution: Examples

Embedded Event Manager Watchdog System Monitor Event Detector Configuration: Example

Where to Go Next

Additional References

Related Documents

Standards

MIBs

RFCs

Technical Assistance

Command Reference

action cli

action cns-event

action counter

action force-switchover

action info

action mail

action policy

action publish-event

action reload

action snmp-trap

action syslog

debug event manager

event application

event cli

event counter

event interface

event ioswdsysmon

event manager applet

event manager directory user

event manager environment

event manager history size

event manager policy

event manager run

event manager scheduler suspend

event manager scheduler script

event manager session cli username

event none

event oir

event snmp

event syslog

event timer

set (EEM)

show event manager directory user

show event manager environment

show event manager history events

show event manager history traps

show event manager policy available

show event manager policy pending

show event manager policy registered

show event manager session cli username


Embedded Event Manager 2.1


Embedded Event Manager (EEM) is a distributed and customized approach to event detection and recovery offered directly in a Cisco IOS device. EEM offers the ability to monitor events and take informational, corrective, or any desired action when the monitored events occur or when a threshold is reached. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs.

EEM 2.1 introduces some new event detectors and actions, some new functionality to allow EEM policies to be run manually, and the ability to run multiple concurrent policies. Support for Simple Network Management Protocol (SNMP) event detector rate-based events is provided as is the ability to create policies using Tool Command Language (Tcl).

History for the Embedded Event Manager Feature

Release
Modification

12.0(26)S

This feature was introduced.

12.3(4)T

Additional functionality was added, and this feature was integrated into Cisco IOS Release 12.3(4)T.

12.3(2)XE

This feature was integrated into Cisco IOS Release 12.3(2)XE.

12.2(25)S

Additional functionality was added, and this feature was integrated into Cisco IOS Release 12.2(25)S.

12.3(14)T

Additional functionality was added.

12.2(28)SB

This feature was integrated into Cisco IOS Release 12.2(28)SB.


Finding Support Information for Platforms and Cisco IOS Software Images

Use Cisco Feature Navigator to find information about platform support and Cisco IOS software image support. Access Cisco Feature Navigator at http://www.cisco.com/go/fn. You must have an account on Cisco.com. If you do not have an account or have forgotten your username or password, click Cancel at the login dialog box and follow the instructions that appear.

Contents

Prerequisites for Embedded Event Manager 2.1

Information About Embedded Event Manager 2.1

How to Configure Embedded Event Manager 2.1

Configuration Examples for Embedded Event Manager 2.1

Where to Go Next

Additional References

Command Reference

Prerequisites for Embedded Event Manager 2.1

If the action cns-event command is used, access to a CNS Event gateway must be configured.

If the action force-switchover command is used, a secondary processor must be configured on the device.

If the action snmp-trap command is used, the snmp-server enable traps event-manager command must be enabled to permit SNMP traps to be sent from the Cisco IOS device to the SNMP server. Other relevant snmp-server commands must also be configured; for details see the action snmp-trap command page.

Information About Embedded Event Manager 2.1

To configure Embedded Event Manager, you should understand the following concepts:

Embedded Event Manager

Embedded Event Manager 2.1

Event Detectors

Embedded Event Manager Actions

Embedded Event Manager Environment Variables

Embedded Event Manager Policies

Embedded Event Manager

Event tracking and management has traditionally been performed by devices external to the networking device. Embedded Event Manager (EEM) has been designed to offer event management capability directly in Cisco IOS devices. The on-device, proactive event management capabilities of EEM are useful because not all event management can be done off router because some problems compromise communication between the router and the external network management device. Capturing the state of the router during such situations can be invaluable in taking immediate recovery actions and gathering information to perform root-cause analysis. Network availability is also improved if automatic recovery actions are performed without the need to fully reboot the routing device.

EEM is 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. Figure 1 shows the relationship between the EEM server, core event publishers (event detectors), and the event subscribers (policies). Basically, event publishers screen events and publish them when there is a match on an event specification that is provided by the event subscriber. Event detectors notify the EEM server when an event of interest occurs. The EEM policies that are configured using the Cisco IOS command-line interface (CLI) then implement recovery on the basis of the current state of the system and the actions specified in the policy for the given event.

Figure 1 Embedded Event Manager Core Event Detectors

EEM offers the ability to monitor events and take informational or corrective action when the monitored events occur or when a threshold is reached. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs. There are two types of EEM policies: an applet or a script. An applet is a simple form of policy that is defined within the CLI configuration. A script is a form of policy that is written in Tool Command Language (Tcl).

EEM Applet

An EEM applet is a concise method for defining event screening criteria and the actions to be taken when that event occurs. In applet configuration mode, three types of configuration statements are supported. The event commands are used to specify the event criteria to trigger the applet to run, the action commands are used to specify an action to perform when the EEM applet is triggered, and the set command is used to set the value of an EEM applet variable. Currently only the _exit_status variable is supported for the set command.

Only one event configuration command is allowed within an applet configuration. When applet configuration mode is exited and no event command is present, a warning is displayed stating that no event is associated with this applet. If no event is specified, this applet is not considered registered. When no action is associated with this applet, events are still triggered but no actions are performed. Multiple action configuration commands are allowed within an applet configuration. Use the show event manager policy registered command to display a list of registered applets.

Before modifying an EEM applet, be aware that the existing applet is not replaced until you exit applet configuration mode. While you are in applet configuration mode modifying the applet, the existing applet may be executing. It is safe to modify the applet without unregistering it. When you exit applet configuration mode, the old applet is unregistered and the new version is registered.

The action configuration commands are uniquely identified using the label argument, which can be any string value. Actions are sorted in ascending alphanumeric key sequence using the label argument as the sort key, and they are run using this sequence.

The Embedded Event Manager schedules and runs policies on the basis of an event specification that is contained within the policy itself. When applet configuration mode is exited, EEM examines the event and action commands that are entered and registers the applet to be run when a specified event occurs.

EEM Script

Scripts are defined off the networking device using an ASCII editor. The script is then copied to the networking device and registered with EEM. Tcl scripts are supported by EEM.

EEM allows you to write and implement your own policies using Tcl. Writing an EEM policy involves:

Selecting the event for which the policy is run.

Defining the event detector options associated with logging and responding to the event.

Choosing the actions to be followed when the event occurs.

Cisco provides enhancements to Tcl in the form of keyword extensions that facilitate the development of EEM policies. The main categories of keywords identify the detected event, the subsequent action, utility information, counter values, and system information. For more details about writing EEM policies using Tcl, see the "Writing Embedded Event Manager Policies Using Tcl" module.

Embedded Event Manager 2.1

EEM 2.1 is supported in Cisco IOS Release 12.3(14)T and 12.2(28)SB and later releases, and introduced some new features. EEM 2.1 introduces the following new event detectors:

CLI—The CLI event detector screens command-line interface (CLI) commands for a regular expression match.

None—The none event detector publishes an event when the Cisco IOS event manager run CLI command executes an EEM policy.

OIR—The online insertion and removal (OIR) event detector publishes an event when a particular hardware insertion or removal event occurs.

EEM 2.1 introduces the following actions:

Executing a Cisco IOS command-line interface (CLI) command.

Requesting system information when an event occurs.

Sending a short e-mail.

Manually running an EEM policy.

EEM 2.1 also permits multiple concurrent policies to be run using the new event manager scheduler script command. Support for Simple Network Management Protocol (SNMP) event detector rate-based events is provided as is the ability to create policies using Tool Command Language (Tcl).

Event Detectors

Embedded Event Manager (EEM) uses software programs known as event detectors to determine when an EEM event occurs. Event detectors are separate systems that provide an interface between the agent being monitored, for example Simple Network Management Protocol (SNMP), and the EEM policies where an action can be implemented. EEM 2.1 contains the following event detectors.

Application-Specific Event Detector

The application-specific event detector allows any Embedded Event Manager policy to publish an event. When an EEM policy publishes an event it must use an EEM subsystem number of 798 with any event type. If an existing policy is registered for subsystem 798 and a specified event type, a second policy of the same event type will trigger the first policy to run when the specified event is published.

CLI Event Detector

The CLI event detector screens command-line interface (CLI) commands for a regular expression match. When a match is found, an event is published. The match logic is performed on the fully expanded CLI command after the command is successfully parsed and before it is executed. The CLI event detector supports three publish modes:

Synchronous publishing of CLI events—The CLI command is not executed until the EEM policy exits, and the EEM policy can control whether the command is executed.

Asynchronous publishing of CLI events—The CLI event is published, and then the CLI command is executed.

Asynchronous publishing of CLI events with command skipping—The CLI event is published, but the CLI command is not executed.

Counter Event Detector

The counter event detector publishes an event when a named counter crosses a specified threshold. There are two or more participants that affect counter processing. The counter event detector can modify the counter, and one or more subscribers define the criteria that cause the event to be published. After a counter event has been published, the counter monitoring logic can be reset to start monitoring the counter immediately or it can be reset when a second threshold—called an exit value—is crossed.

Interface Counter Event Detector

The interface counter event detector publishes an event when a generic Cisco IOS interface counter for a specified interface crosses a defined threshold. A threshold can be specified as an absolute value or an incremental value. If the incremental value is set to 50, for example, an event would be published when the interface counter increases by 50.

After an interface counter event has been published, the interface counter monitoring logic is reset using two methods. The interface counter is reset either when a second threshold—called an exit value—is crossed or when an elapsed period of time occurs.

None Event Detector

The none event detector publishes an event when the Cisco IOS event manager run CLI command executes an EEM policy. EEM schedules and runs policies on the basis of an event specification that is contained within the policy itself. An EEM policy must be identified and registered to be permitted to be run manually before the event manager run command will execute

OIR Event Detector

The online insertion and removal (OIR) event detector publishes an event when one of the following hardware insertion or removal events occurs:

A card is removed.

A card is inserted.

The software on an inserted card becomes fully operational.

Route processors (RPs), line cards, or feature cards can be monitored for OIR events.

SNMP Event Detector

The SNMP event detector allows a standard SNMP MIB object to be monitored and an event to be generated when the object matches specified values or crosses specified thresholds.

Syslog Event Detector

The syslog event detector allows for screening syslog messages for a regular expression pattern match. The selected messages can be further qualified, requiring that a specific number of occurrences be logged within a specified time. A match on a specified event criteria triggers a configured policy action.

Timer Event Detector

The timer event detector publishes events for the following four different types of timers:

An absolute-time-of-day timer publishes an event when a specified absolute date and time occurs.

A countdown timer publishes an event when a timer counts down to zero.

A watchdog timer publishes an event when a timer counts down to zero and then the timer automatically resets itself to its initial value and starts to count down again.

A CRON timer publishes an event using a UNIX standard CRON specification to indicate when the event is to be published. A CRON timer never publishes events more than once per minute.

Watchdog System Monitor Event Detector

The Cisco IOS watchdog system monitor event detector publishes an event when one of the following occurs:

CPU utilization for a Cisco IOS process crosses a threshold.

Memory utilization for a Cisco IOS process crosses a threshold.

Two events may be monitored at the same time, and the event publishing criteria can be specified to require one event or both events to cross their specified thresholds.

Embedded Event Manager Actions

The CLI-based corrective actions that are taken when event detectors report events enable a powerful on-device event management mechanism. EEM 2.1 supports the following actions:

Executing a Cisco IOS command-line interface (CLI) command.

Generating a CNS event for upstream processing by Cisco CNS devices.

Setting or modifying a named counter.

Switching to a secondary processor in a fully redundant hardware configuration.

Requesting system information when an event occurs.

Sending a short e-mail.

Manually running an EEM policy.

Publishing an application-specific event.

Reloading the Cisco IOS software.

Generating an SNMP trap.

Generating prioritized syslog messages.

Embedded Event Manager Environment Variables

EEM allows environment variables to be used in EEM policies (applets and scripts). Tool Command Language (Tcl) permits global variables—called environment variables—to be defined for use within an EEM policy. 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—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 (see Table 1) may apply to one specific event detector or to all event detectors. Environment variables that are user-defined or defined by Cisco in a sample policy are set using the event manager environment command. Variables that are used in the EEM policy must be defined before you register the policy. A Tcl policy contains a section called "Environment Must Define" that can be defined to check that any required environment variables are defined before the policy runs.

Cisco built-in environment variables (see Table 2) are a subset of the Cisco-defined environment variables and the built-in variables are available to EEM applets only. The built-in variables can be read-only or can be read and write, and these variables may apply to one specific event detector or to all event detectors.


Note Cisco-defined environment variables begin with an underscore character (_). We strongly recommend that customers avoid the same naming convention to prevent naming conflicts.


Table 1 describes the Cisco-defined variables used in the sample EEM policies. Some of the environment variables do not have to be specified for the corresponding sample policy to run and these are marked as optional.

Table 1 Cisco-Defined Environmental Variables and Examples 

Environment Variable
Description
Example

_config_cmd1

The first configuration command that is executed.

interface Ethernet1/0

_config_cmd2

(Optional) The second configuration command that is executed.

no shutdown

_cron_entry

A CRON specification that determines when the policy will run. See the Writing Embedded Event Manager Policies Using Tcl document for more information about how to specify a cron entry.

0-59/1 0-23/1 * * 0-7

_email_server

A Simple Mail Transfer Protocol (SMTP) mail server used to send e-mail.

mailserver.example.com

_email_to

The address to which e-mail is sent.

engineering@example.com

_email_from

The address from which e-mail is sent.

devtest@example.com

_email_cc

The address to which the e-mail is to be copied.

manager@example.com

_show_cmd

The CLI show command to be executed when the policy is run.

show version

_syslog_pattern

A regular expression pattern match string that is used to compare syslog messages to determine when the policy runs.

.*UPDOWN.*FastEthernet
0/0.*


Table 2 describes the Cisco built-in environment variables.

Table 2 Cisco Built-In Environment Variables 

Environment Variable
Description
All Events

_event_pub_time

The time at which the event type was published.

_event_type_string

The event type that triggered the event.

Application-Specific Event Detector

_application_component_id

The event application component identifier.

_application_data1

The value of an environment variable, character text, or a combination of the two to be passed to an application-specific event when the event is published.

_application_data2

The value of an environment variable, character text, or a combination of the two to be passed to an application-specific event when the event is published.

_application_data3

The value of an environment variable, character text, or a combination of the two to be passed to an application-specific event when the event is published.

_application_data4

The value of an environment variable, character text, or a combination of the two to be passed to an application-specific event when the event is published.

_application_sub_system

The event application subsystem number.

_application_type

The type of application.

CLI Event Detector

_cli_msg

The fully expanded message that triggered the CLI event.

_cli_msg_count

The number of times that a message match occurred before the event was published.

Counter Event Detector

_counter_name

The name of the counter.

_counter_value

The value of the counter.

Interface Counter Event Detector

_interface_is_increment

A value to indicate whether the current interface counter value is an absolute value (0) or an increment value (1).

_interface_name

The name of the interface to be monitored.

_interface_parameter

The name of the interface counter to be monitored.

_interface_value

A value with which the current interface counter value is compared.

OIR Event Detector

_oir_event

Value of 1 indicates an insertion event; a value of 2 indicates a removal event.

_oir_slot

The slot number for the OIR event.

SNMP Event Detector

_snmp_exit_event

A value of 0 indicates that this is not an exit event; a value of 1 indicates an exit event.

_snmp_oid

The SNMP object ID that caused the event to be published.

_snmp_oid_val

The SNMP object ID value when the event was published.

Syslog Event Detector

_syslog_msg

The syslog message that caused the event to be published.

Timer Event Detector

_timer_remain

The time available before the timer expires.

Note This environment variable is not available for the CRON timer.

_timer_time

The time at which the last event was triggered.

_timer_type

The type of timer.

Watchdog System Monitor (Cisco IOS) Event Detector

_ioswd_node

The slot number for the route processor (RP) reporting node.

_ioswd_num_subs

The number of subevents present.

All Watchdog System Monitor (Cisco IOS) Subevents

_ioswd_sub1_present
_ioswd_sub2_present

A value to indicate whether subevent 1 or subevent 2 is present. A value of 1 means that the subevent is present; a value of 0 means that the subevent is not present.

_ioswd_sub1_type
_ioswd_sub2_type

The event type, either cpu_util or mem_used.

Watchdog System Monitor (Cisco IOS) cpu_util Events

_ioswd_sub1_path
_ioswd_sub2_path

The process name of subevents.

_ioswd_sub1_period
_ioswd_sub2_period

The time period, in seconds and optional milliseconds, used for measurement in subevents.

_ioswd_sub1_pid
_ioswd_sub2_pid

A process identifier of subevents.

_ioswd_sub1_taskname
_ioswd_sub2_taskname

The task name of subevents.

_ioswd_sub1_value
_ioswd_sub2_value

The CPU utilization of subevents measured as a percentage.

Watchdog System Monitor (Cisco IOS) mem_used Events

_ioswd_sub1_diff
_ioswd_sub2_diff

A percentage value of the difference that triggered the event.

Note This variable is set only when the _ioswd_subx_is_percent variable contains a value of 1.

_ioswd_sub1_is_percent
_ioswd_sub2_is_percent

A number that identifies whether the value is a percentage. A value of 0 means that the value is not a percentage; a value of 1 means that the value is a percentage.

_ioswd_sub1_path
_ioswd_sub2_path

A process name of subevents.

_ioswd_sub1_pid
_ioswd_sub2_pid

A process identifier of subevents.

_ioswd_sub1_taskname
_ioswd_sub2_taskname

The task name of subevents.

_ioswd_sub1_value
_ioswd_sub2_value

The CPU utilization of subevents measured as a percentage.


Embedded Event Manager Policies

EEM is a policy driven process in which the EEM policy engine receives notifications when faults and other events occur in the Cisco IOS software system. Embedded Event Manager policies implement recovery based on the current state of the system and the actions specified in the policy for a given event. Recovery actions are triggered when the policy is run.

Although there are some EEM CLI configuration and show commands, EEM is implemented through the creation of policies. An EEM policy is an entity that defines an event and the actions to be taken when that event occurs. There are two types of EEM policies: an applet or a script. An applet is a simple form of policy that is defined within the CLI configuration. A script is a form of policy that is written in Tcl.

The creation of an EEM policy involves:

Selecting the event for which the policy is run.

Defining the event detector options associated with logging and responding to the event.

Defining the environment variables, if required.

Choosing the actions to be performed when the event occurs.

There are two ways to create an EEM policy. The first method is to write applets using CLI commands, and the second method is to write Tcl scripts. Cisco provides enhancements to Tcl in the form of Tcl command extensions that facilitate the development of EEM policies. Scripts are defined off the networking device using an ASCII editor. The script is then copied to the networking device and registered with EEM. When a policy is registered with the Embedded Event Manager, the software examines the policy and registers it to be run when the specified event occurs. Policies can be unregistered or suspended. Both types of policies can be used to implement EEM in your network.

For details on writing EEM policies using the Cisco IOS CLI, see the "How to Configure Embedded Event Manager 2.1" section.

For details on writing EEM policies using Tcl and running the sample policies, see the "Writing Embedded Event Manager Policies Using Tcl" module.

How to Configure Embedded Event Manager 2.1

This section contains the following tasks:

Registering and Defining an Embedded Event Manager Applet

Registering and Defining an Embedded Event Manager Policy to Run Manually

Displaying Embedded Event Manager Registered Policies

Unregistering Embedded Event Manager Policies

Suspending Embedded Event Manager Policy Execution

Modifying History Table Size and Displaying EEM History Data

Registering and Defining an Embedded Event Manager Applet

Perform this task to register an applet with Embedded Event Manager and to define the EEM applet using the Cisco IOS CLI event and action commands. Only one event command is allowed in an EEM applet. Multiple action commands are permitted. If no event and no action commands are specified, the applet is removed when you exit configuration mode.

The SNMP event detector and the syslog action commands used in this task are just representing any event detector and action commands. For examples using other event detectors and action commands, see the "Embedded Event Manager Applet Configuration: Examples" section.


Note For details about how to register and define an Embedded Event Manager Tcl script, see the "Writing Embedded Event Manager Policies Using Tcl" module.


EEM Environment Variables

EEM environment variables for EEM policies are defined using the EEM event manager environment configuration command. By convention, all Cisco EEM environment variables begin with "_". In order to avoid future conflict, customers are urged not to define new variables that start with "_".

You can display the EEM environment variables set on your system by using the show event manager environment privileged EXEC command.

For example, you can create EEM policies that can send e-mails when an event occurs. Table 3 describes the e-mail-specific environment variables that can be used in EEM policies.

Table 3 EEM E-mail-Specific Environmental Variables 

Environment Variable
Description
Example

_email_server

A Simple Mail Transfer Protocol (SMTP) mail server used to send e-mail.

mailserver.yourdomain.com

_email_to

The address to which e-mail is sent.

engineering@yourdomain.com

_email_from

The address from which e-mail is sent.

devtest@yourdomain.com

_email_cc

The address to which the e-mail is copied.

manager@yourdomain.com


SUMMARY STEPS

1. enable

2. show event manager environment [all | variable-name]

3. configure terminal

4. event manager environment variable-name string

5. Repeat Step 4 for all the required environment variables.

6. event manager applet applet-name

7. event snmp oid oid-value get-type {exact | next} entry-op operator entry-val entry-value [exit-comb {or | and}] [exit-op operator] [exit-val exit-value] [exit-time exit-time-value] poll-interval poll-int-value

8. action label syslog [priority priority-level] msg msg-text

9. Repeat Step 8.

10. end

DETAILED STEPS

 
Command or Action
Purpose

Step 1 

enable

Example:

Router> enable

Enables privileged EXEC mode.

Enter your password if prompted.

Step 2 

show event manager environment [all | variable-name]

Example:

Router# show event manager environment all

(Optional) Displays the name and value of EEM environment variables.

The optional all keyword displays all the EEM environment variables.

The optional variable-name argument displays information about the specified environment variable.

Step 3 

configure terminal

Example:

Router# configure terminal

Enters global configuration mode.

Step 4 

event manager environment variable-name string

Example:

Router(config)# event manager environment _email_to engineering@yourdomain.com

Configures the value of the specified EEM environment variable.

In this example, the environment variable that holds the e-mail address to which e-mail is sent is set to engineering@yourdomain.com.

Step 5 

Repeat Step 4 for all the required environment variables.

Repeat Step 4 to configure all the environment variables required by the policy to be registered in Step 6.

Step 6 

event manager applet applet-name

Example:

Router(config)# event manager applet memory-fail

Registers the applet with the Embedded Event Manager (EEM) and enters applet configuration mode.

Step 7 

event snmp oid oid-value get-type {exact | next} entry-op operator entry-val entry-value [exit-comb {or | and}] [exit-op operator] [exit-val exit-value] [exit-time exit-time-value] poll-interval poll-int-value

Example:

Router(config-applet)# event snmp oid 1.3.6.1.4.1.9.9.48.1.1.1.6.1 get-type exact entry-op lt entry-val 5120000 poll-interval 10

Specifies the event criteria that cause the EEM applet to run.

In this example, an EEM event is triggered when free memory falls below the value of 5120000.

Exit criteria are optional, and if not specified, event monitoring is reenabled immediately.

Step 8 

action label syslog [priority priority-level] msg msg-text

Example:

Router(config-applet)# action 1.0 syslog priority critical msg "Memory exhausted; current available memory is $_snmp_oid_val bytes"

Specifies the action to be taken when an EEM applet is triggered.

In this example, the action to be taken is to write a message to syslog.

The optional priority keyword specifies the priority level of the syslog messages. If selected, the priority-level argument must be defined.

The msg-text argument can be character text, an environment variable, or a combination of the two.

Step 9 

Repeat Step 8.

Example:

Router(config-applet)# action 2.0 force-switchover

(Optional) Repeat Step 8 to add other action CLI commands to the applet.

Step 10 

end

Example:

Router(config-applet)# end

Exits applet configuration mode and returns to privileged EXEC mode.

Troubleshooting Tips

Use the debug event manager command in privileged EXEC mode to troubleshoot EEM command operations. Use any debugging command with caution as the volume of generated output can slow or stop the router operations. We recommend that this command be used only under the supervision of a Cisco engineer.

Registering and Defining an Embedded Event Manager Policy to Run Manually

There are two ways to manually run an EEM policy. EEM usually schedules and runs policies on the basis of an event specification that is contained within the policy itself. The event none command allows EEM to identify an EEM policy that can be manually triggered. To run the policy, use either the action policy command in applet configuration mode or the event manager run command in privileged EXEC mode.

Perform this task to register an EEM policy to be run manually using the event manager run command. For an example of how to manually run a policy using the action policy command, see the "Embedded Event Manager Manual Policy Execution: Examples" section.

SUMMARY STEPS

1. enable

2. configure terminal

3. event manager applet applet-name

4. event none

5. action label syslog [priority priority-level] msg msg-text

6. end

7. event manager run policy-filename

DETAILED STEPS

 
Command or Action
Purpose

Step 1 

enable

Example:

Router> enable

Enables privileged EXEC mode.

Enter your password if prompted.

Step 2 

configure terminal

Example:

Router# configure terminal

Enters global configuration mode.

Step 3 

event manager applet applet-name

Example:

Router(config)# event manager applet manual-policy

Registers the applet with the Embedded Event Manager and enters applet configuration mode.

Step 4 

event none policy-filename

Example:

Router(config-applet)# event none manual-policy

Specifies that an EEM policy is to be registered with the EEM and can be run manually.

Step 5 

action label syslog [priority priority-level] msg msg-text

Example:

Router(config-applet)# action 1.0 syslog msg "Manual-policy triggered"

Specifies the action to be taken when an EEM applet is triggered.

In this example, the action to be taken is to write a message to syslog.

The optional priority keyword specifies the priority level of the syslog messages. If selected, the priority-level argument must be defined.

The msg-text argument can be character text, an environment variable, or a combination of the two.

Step 6 

end

Example:

Router(config-applet)# end

Exits applet configuration mode and returns to privileged EXEC mode.

Step 7 

event manager run policy-filename

Example:

Router# event manager run manual-policy

Manually runs a registered EEM policy.

Displaying Embedded Event Manager Registered Policies

Perform this optional task to display EEM registered policies.

SUMMARY STEPS

1. enable

2. show event manager policy registered [event-type event-name] [time-ordered | name-ordered]

DETAILED STEPS


Step 1 enable

Enables privileged EXEC mode. Enter your password if prompted.

Router> enable

Step 2 show event manager policy registered [event-type event-name] [time-ordered | name-ordered]

Use this command with the time-ordered keyword to display information about currently registered policies sorted by time, for example:

Router# show event manager policy registered time-ordered

No.  Type    Event Type          Time                    Registered Name 
1    applet  snmp                Thu May30 05:57:16 2004 memory-fail 
 oid {1.3.6.1.4.1.9.9.48.1.1.1.6.1} get-type exact entry-op lt entry-val  
{5120000} poll-interval 10 
action 1.0 syslog priority critical msg Memory exhausted; current available memory  
is $_snmp_oid_val bytes 
 action 2.0 force-switchover 
2    applet  syslog              Wed Jul16 00:05:17 2004 intf-down
 pattern {.*UPDOWN.*Ethernet1/0.*}
 action 1.0 cns-event msg Interface state change: $_syslog_msg

Use this command with the name-ordered keyword to display information about currently registered policies sorted by name, for example:

Router# show event manager policy registered name-ordered

No.  Type    Event Type          Time Registered          Name 
1    applet  syslog              Wed Jul16  00:05:17 2004 intf-down
 pattern {.*UPDOWN.*Ethernet1/0.*}
 action 1.0 cns-event msg Interface state change: $_syslog_msg
2    applet  snmp                Thu May30 05:57:16 2004   memory-fail 
 oid {1.3.6.1.4.1.9.9.48.1.1.1.6.1} get-type exact entry-op lt entry-val  
{5120000} poll-interval 10 
 action 1.0 syslog priority critical msg Memory exhausted; current available memory  
is $_snmp_oid_val bytes 
 action 2.0 force-switchover

Use this command with the event-type keyword to display information about currently registered policies for the event type specified in the event-name argument, for example:

Router# show event manager policy registered event-type syslog

No.  Type    Event Type          Time Registered           Name 
1    applet  syslog              Wed Jul16  00:05:17 2004 intf-down
 pattern {.*UPDOWN.*Ethernet1/0.*}
 action 1.0 cns-event msg Interface state change: $_syslog_msg

Unregistering Embedded Event Manager Policies

Perform this task to remove an EEM policy from the running configuration file. Execution of the policy is canceled.

SUMMARY STEPS

1. enable

2. show event manager policy registered [event-type event-name] [system | user] [time-ordered | name-ordered]

3. configure terminal

4. no event manager policy policy-filename [type {system | user}] [trap]

5. exit

6. Repeat Step 2 to ensure that the policy is removed.

DETAILED STEPS

 
Command or Action
Purpose

Step 1 

enable

Example:

Router> enable

Enables privileged EXEC mode.

Enter your password if prompted.

Step 2 

show event manager policy registered [event-type event-name] [system | user] [time-ordered | name-ordered]

Example:

Router# show event manager policy registered

(Optional) Displays the EEM policies that are currently registered.

The optional system or user keyword displays the registered system or user policies.

If no keywords are specified, EEM registered policies for all event types are displayed in time order.

Step 3 

configure terminal

Example:

Router# configure terminal

Enters global configuration mode.

Step 4 

no event manager policy policy-filename [type {system | user}] [trap]

Example:

Router(config)# no event manager policy pr_cdp_abort.tcl

Removes the EEM policy from the configuration, causing the policy to be unregistered.

In this example, the no form of the command is used to unregister a specified policy.

Step 5 

exit

Example:

Router(config)# exit

Exits global configuration mode and returns to privileged EXEC mode.

Step 6 

Repeat Step 2 to ensure that the policy is removed.

Example:

Router# show event manager policy registered

Examples

In the following example, the show event manager policy registered privileged EXEC command is used to display the two EEM applets that are currently registered:

Router# show event manager policy registered

No.  Class   Type    Event Type          Trap  Time Registered           Name
1    applet  system  snmp                Off   Fri Aug 12 17:42:52 2005  IPSLAping1
 oid {1.3.6.1.4.1.9.9.42.1.2.9.1.6.4} get-type exact entry-op eq entry-val {1}
 exit-op eq exit-val {2} poll-interval 5.000
 action 1.0 syslog priority critical msg "Server IPecho Failed: OID=$_snmp_oid_val" 
 action 1.1 snmp-trap strdata "EEM detected server reachability failure to 10.1.88.9"
 action 1.2 publish-event sub-system 88000101 type 1 arg1 "10.1.88.9" arg2 "IPSLAEcho"
arg3 "fail"
 action 1.3 counter name _IPSLA1F op inc value 1
2    applet  system  snmp                Off   Thu Sep 15 05:57:16 2005  memory-fail
 oid {1.3.6.1.4.1.9.9.48.1.1.1.6.1} get-type exact entry-op lt entry-val {5120000} 
poll-interval 10 
 action 1.0 syslog priority critical msg Memory exhausted; current available memory is 
$_snmp_oid_val bytes 
 action 2.0 force-switchover

In the following example, the show event manager policy registered privileged EXEC command is used to show that applet IPSLAping1 has been removed after entering the no event manager policy command:

Router# show event manager policy registered

No.  Class   Type    Event Type          Trap  Time Registered           Name
1    applet  system  snmp                Off   Thu Sep 15 05:57:16 2005  memory-fail
 oid {1.3.6.1.4.1.9.9.48.1.1.1.6.1} get-type exact entry-op lt entry-val {5120000} 
poll-interval 10 
 action 1.0 syslog priority critical msg Memory exhausted; current available memory is 
$_snmp_oid_val bytes 
 action 2.0 force-switchover

Suspending Embedded Event Manager Policy Execution

Perform this task to immediately suspend the execution of all EEM policies. Suspending instead of unregistering policies might be necessary for reasons of temporary performance or security.

SUMMARY STEPS

1. enable

2. show event manager policy registered [event-type event-name] [system | user] [time-ordered | name-ordered]

3. configure terminal

4. event manager scheduler suspend

5. exit

DETAILED STEPS

 
Command or Action
Purpose

Step 1 

enable

Example:

Router> enable

Enables privileged EXEC mode.

Enter your password if prompted.

Step 2 

show event manager policy registered [event-type event-name] [system | user] [time-ordered | name-ordered]

Example:

Router# show event manager policy registered

(Optional) Displays the EEM policies that are currently registered.

The optional system or user keyword displays the registered system or user policies.

If no keywords are specified, EEM registered policies for all event types are displayed in time order.

Step 3 

configure terminal

Example:

Router# configure terminal

Enters global configuration mode.

Step 4 

event manager scheduler suspend

Example:

Router(config)# event manager scheduler suspend

Immediately suspends the execution of all EEM policies.

Step 5 

exit

Example:

Router(config)# exit

Exits global configuration mode and returns the router to privileged EXEC mode.

Examples

In the following example, the show event manager policy registered privileged EXEC command is used to display all the EEM registered policies:

Router# show event manager policy registered

No.  Type    Event Type          Trap  Time Registered           Name
1    system  timer cron          Off   Sat Oct11  01:43:18 2003  tm_cli_cmd.tcl
 name {crontimer2} cron entry {0-59/1 0-23/1 * * 0-7}
 nice 0 priority normal maxrun 240.0

2    system  syslog              Off   Sat Oct11  01:43:28 2003  sl_intf_down.tcl
 occurs 1 pattern {.*UPDOWN.*Ethernet1/0.*}
 nice 0 priority normal maxrun 90.0

Modifying History Table Size and Displaying EEM History Data

Perform this optional task to change the size of the history tables and to display EEM history data.

SUMMARY STEPS

1. enable

2. configure terminal

3. event manager history size {events | traps} [size]

4. exit

5. show event manager history events [detailed] [maximum number]

6. show event manager history traps {server | policy}

DETAILED STEPS


Step 1 enable

Enables privileged EXEC mode. Enter your password if prompted.

Router> enable

Step 2 configure terminal

Enters global configuration mode.

Router# configure terminal

Step 3 event manager history size {events | traps} [size]