- Preface
- New and Changed Information for this Release
- Overview
- Using Cisco Fabric Services
- Configuring PTP
- Configuring User Accounts and RBAC
- Configuring Session Manager
- Configuring the Scheduler
- Configuring Online Diagnostics
- Configuring the Embedded Event Manager
- Configuring System Message Logging
- Configuring Smart Call Home
- Configuring DNS
- Configuring SNMP
- Configuring RMON
- Configuring SPAN
- Configuring ERSPAN
- Index
- Information About Embedded Event Manager
- Configuring Embedded Event Manager
- Defining an Environment Variable
- Defining a User Policy Using the CLI
- Configuring Event Statements
- Configuring Action Statements
- Defining a Policy Using a VSH Script
- Registering and Activating a VSH Script Policy
- Overriding a System Policy
- Configuring Memory Thresholds
- Configuring Syslog as an EEM Publisher
- Verifying the Embedded Event Manager Configuration
- Configuration Examples for Embedded Event Manager
- Additional References
- Feature History for EEM
Configuring the Embedded Event Manager
This chapter contains the following sections:
- Information About Embedded Event Manager
- Configuring Embedded Event Manager
- Verifying the Embedded Event Manager Configuration
- Configuration Examples for Embedded Event Manager
- Additional References
- Feature History for EEM
Information About Embedded Event Manager
The ability to detect and handle critical events in the Cisco NX-OS system is important for high availability. The Embedded Event Manager (EEM) provides a central, policy-driven framework to detect and handle events in the system by monitoring events that occur on your device and taking action to recover or troubleshoot these events, based on your configuration..
EEM consists of three major components:
- Event statements
Events to monitor from another Cisco NX-OS component that may require some action, workaround, or notification.
- Action statements
An action that EEM can take, such as sending an e-mail or disabling an interface, to recover from an event.
- Policies
An event paired with one or more actions to troubleshoot or recover from the event.
Without EEM, each individual component is responsible for detecting and handling its own events. For example, if a port flaps frequently, the policy of "putting it into errDisable state" is built into ETHPM.
- Embedded Event Manager Policies
- Event Statements
- Action Statements
- VSH Script Policies
- Licensing Requirements for Embedded Event Manager
- Prerequisites for Embedded Event Manager
- Guidelines and Limitations for Embedded Event Manager
- Default Settings for Embedded Event Manager
Embedded Event Manager Policies
An EEM policy consists of an event statement and one or more action statements. The event statement defines the event to look for as well as the filtering characteristics for the event. The action statement defines the action EEM takes when the event occurs.
For example, you can configure an EEM policy to identify when a card is removed from the device and log the details related to the card removal. By setting up an event statement that tells the system to look for all instances of card removal and an then with an action statement that tells the system to log the details.
You can configure EEM policies using the command line interface (CLI) or a VSH script.
EEM gives you a device-wide view of policy management. Once EEM policies are configured, the corresponding actions are triggered. All actions (system or user-configured) for triggered events are tracked and maintained by the system.
Preconfigured System Policies
Cisco NX-OS has a number of preconfigured system policies. These system policies define many common events and actions for the device. System policy names begin with two underscore characters (__).
Some system policies can be overridden. In these cases, you can configure overrides for either the event or the action. The overrides that you configure take the place of the system policy.
Note | Override policies must include an event statement. Override policies without event statements override all possible events for the system policy. |
To view the preconfigured system polices and determine which polices you can override, use the show event manager system-policy command.
User-Created Policies
User-created policies allow you to customize EEM policies for your network. If a user policy is created for an event, actions in the policy are triggered only after EEM triggers the system policy actions related to the same event.
Log Files
The log file that contains data that is related to EEM policy matches is maintained in the event_archive_1 log file located in the /log/event_archive_1 directory.
Event Statements
Any device activity for which some action, such as a workaround or notification, is taken is considered an event by EEM. In many cases, events are related to faults in the device, such as when an interface or a fan malfunctions.
Event statements specify which event or events triggers a policy to run.
Tip | YOu can configure EEM to trigger an EEM policy that is based on a combination of events by creating and differentiating multiple EEM events in the policy and then defining a combination of events to trigger a custom action. |
EEM defines event filters so that only critical events or multiple occurrences of an event within a specified time period trigger an associated action.
Some commands or internal events trigger other commands internally. These commands are not visible, but will still match the event specification that triggers an action. You cannot prevent these commands from triggering an action, but you can check which event triggered an action.
Supported Events
EEM supports the following events in event statements:
Action Statements
Action statements describe the action that is triggered by a policy when an event occurs. Each policy can have multiple action statements. If no action is associated with a policy, EEM still observes events but takes no actions.
In order for triggered events to process default actions, you must configure the EEM policy to allow the default action. For example, if you match a CLI command in a match statement, you must add the event-default action statement to the EEM policy or EEM does not allow the command to execute.
Note | When configuring action statements within your user policy or overriding policy, it is important that you confirm that action statements do not negate each other or adversely affect the associated system policy. |
Supported Actions
EEM supports the following actions in action statements:
VSH Script Policies
You can write policies in a VSH script, by using a text editor. Policies that are written using a VSH script have an event statement and action statement(s) just as other policies, and these policies can either augment or override system policies.
After you define your VSH script policy, copy it to the device and activate it.
Licensing Requirements for Embedded Event Manager
This feature does not require a license. Any feature not included in a license package is bundled with the Cisco NX-OS system images and is provided at no extra charge to you. For a complete explanation of the Cisco NX-OS licensing scheme, see the Cisco NX-OS Licensing Guide.
Prerequisites for Embedded Event Manager
You must have network-admin privileges to configure EEM.
Guidelines and Limitations for Embedded Event Manager
When you plan your EEM configuration, consider the following:
The maximum number of configurable EEM policies is 500.
Action statements within your user policy or overriding policy should not negate each other or adversely affect the associated system policy.
If you want to allow a triggered event to process any default actions, you must configure the EEM policy to allow the default action. For example, if you match a command in a match statement, you must add the event-default action statement to the EEM policy or EEM does not allow the command to execute.
An override policy that consists of an event statement and no action statement triggers no action and no notification of failures.
An override policy without an event statement overrides all possible events in the system policy.
In regular command expressions: all keywords must be expanded, and only the asterisk (*) symbol can be used for replace the arguments.
EEM event correlation supports up to four event statements in a single policy. The event types can be the same or different, but only these event types are supported: cli, counter, snmp, syslog, and track.
When more than one event statement is included in an EEM policy, each event statement must have a tag keyword with a unique tag argument.
EEM event correlation does not override the system default policies.
Default action execution is not supported for policies that are configured with tagged events.
If your event specification matches a CLI pattern, you can use SSH-style wild card characters.
For example, if you want to match all show commands, enter the show * command. Entering the show . * command does not work.
If your event specification is a regular expression for a matching syslog message, you can use a proper regular expression.
For example, if you want to detect ADMIN_DOWN events on any port where a syslog is generated, use .ADMIN_DOWN.. Entering the ADMIN_DOWN command does not work.
In the event specification for a syslog, the regex does not match any syslog message that is generated as an action of an EEM policy.
If an EEM event matches a show command in the CLI and you want the output for that show command to display on the screen (and to not be blocked by the EEM policy), you must specify the event-default command for the first action for the EEM policy.
Default Settings for Embedded Event Manager
Parameters | Default |
---|---|
System Policies | Active |
Configuring Embedded Event Manager
Defining an Environment Variable
Defining an environment variable is an optional step but is useful for configuring common values for repeated use in multiple policies.
Configure a User Policy.
Defining a User Policy Using the CLI
Configure event statements and action statements.
Configuring Event Statements
Use one of the following commands in EEM configuration mode (config-applet) to configure an event statement:
Define a user policy.
Configure action statements.
If you have already configured action statements or choose not to, complete any of the optional tasks:
Configuring Action Statements
You can configure an action by using one of the following commands in EEM configuration mode (config-applet):
Note | If you want to allow a triggered event to process any default actions, you must configure the EEM policy to allow the default action. For example, if you match a command in a match statement, you must add the event-default action statement to the EEM policy or EEM does not allow the command to execute. You can use the terminal event-manager bypass command to allow all EEM policies with matches to execute the command. |
Define a user policy.
Configure event statements.
If you have already configured event statements or choose not to, complete any of the optional tasks:
Defining a Policy Using a VSH Script
This is an optional task. Complete the following steps if you are using a VSH script to write EEM policies:
What to Do Next
Register and activate a VSH script policy.
Registering and Activating a VSH Script Policy
This is an optional task. Complete the following steps if you are using a VSH script to write EEM policies.
Define a policy using a VSH script and copy the file to the system directory.
Complete any of the following, depending on your system requirements:
Overriding a System Policy
Configuring Memory Thresholds
Memory thresholds are used to trigger events and set whether the operating system should stop processes if it cannot allocate memory.
Complete any of the following, depending on your system requirements:
Configuring Syslog as an EEM Publisher
Configuring syslog as an EEM publisher allows you to monitor syslog messages from the switch.
Note | The maximum number of searchable strings to monitor syslog messages is 10. |
Verify your EEM configuration.
Verifying the Embedded Event Manager Configuration
Use one of the following commands to verify the configuration:
Command | Purpose |
---|---|
show event manager environment [variable-name | all] |
Displays information about the event manager environment variables. |
show event manager event-types [event | all | module slot] |
Displays information about the event manager event types. |
show event manager history events [detail] [maximum num-events] [severity {catastrophic | minor | moderate | severe}] |
Displays the history of events for all policies. |
show event manager policy internal [policy-name] [inactive] |
Displays information about the configured policies. |
show event manager policy-state policy-name |
Displays information about the policy state, including thresholds. |
show event manager script system [policy-name | all] |
Displays information about the script policies. |
show event manager system-policy [all] |
Displays information about the predefined system policies. |
show running-config eem |
Displays information about the running configuration for EEM. |
show startup-config eem |
Displays information about the startup configuration for EEM. |
Configuration Examples for Embedded Event Manager
The following example shows how to override the __lcm_module_failure system policy by changing the threshold for only module 3 hitless upgrade failures. It also sends a syslog message. The settings in the system policy, __lcm_module_failure, apply in all other cases.
event manager applet example2 override __lcm_module_failure event module-failure type hitless-upgrade-failure module 3 count 2 action 1 syslog priority errors msg module 3 "upgrade is not a hitless upgrade!" action 2 policy-default
The following example shows how to override the __ethpm_link_flap system policy and shut down the interface:
event manager applet ethport override __ethpm_link_flap event policy-default count 2 time 1000 action 1 cli conf t action 2 cli int et1/1 action 3 cli no shut
The following example shows how to create an EEM policy that allows the command to execute but triggers an SNMP notification when a user enters configuration mode on the device:
event manager applet TEST event cli match "conf t" action 1.0 snmp-trap strdata "Configuration change" action 2.0 event-default
Note | You must add the event-default action statement to the EEM policy or EEM does not allow the command to execute. |
The following example shows how to correlate multiple events in an EEM policy and execute the policy based on a combination of the event triggers. In this example, the EEM policy is triggered if one of the specified syslog patterns occurs within 120 seconds.
event manager applet eem-correlate event syslog tag one pattern "copy bootflash:.* running-config.*" event syslog tag two pattern "copy run start" event syslog tag three pattern "hello" tag one or two or three happens 1 in 120 action 1.0 reload module 1
Additional References
Related Documents
Related Topic | Document Title |
---|---|
EEM commands |
Cisco Nexus 3000 Series NX-OS System Management Command Reference |
Standards
There are no new or modified standards supported by this feature, and support for existing standards has not been modified by this feature.
Feature History for EEM
Feature Name | Release | Feature Information |
---|---|---|
EEM | 5.0(3)U3(1) | Feature added. |