The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes how to configure Embedded Event Manager (EEM) to detect and handle critical events on the Cisco 1000 Series Connected Grid Routers (hereafter referred to as the
Cisco CG-OS router).
EEM monitors events that occur on your device and takes action to recover or troubleshoot these events, based on your configuration.
This section includes the following topics:
EEM consists of three major components:
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.
Figure 4-1 shows the two basic statements in an EEM policy.
Figure 4-1 EEM Policy Statements
You can configure EEM policies using the CLI or a VSH script.
EEM gives you a device-wide view of policy management. You configure EEM policies on the supervisor, and EEM pushes the policy to the correct module based on the event type. EEM takes any actions for a triggered event either locally on the module or on the supervisor (the default option).
EEM maintains event logs on the Cisco CG-OS router.
Cisco CG-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 (__).
You can create user policies to suit your network. If you create a user policy, any actions in your policy occur after EEM triggers any system policy actions related to the same event as your policy. To configure a user policy, see Defining a User Policy.
You can also override some system policies. The overrides that you configure take the place of the system policy. You can override the event or the actions.
Use the show event manager system-policy command to view the preconfigured system policies and determine which policies that you can override.
To configure an overriding policy, see the Overriding a Policy.
Note You should use the show running-config eem command to check the configuration of each policy. An override policy that consists of an event statement and no action statement triggers no action and no notification of failures.
Note Your override policy should always include an event statement. An override policy without an event statement overrides all possible events in the system policy.
An event is any device activity for which some action, such as a workaround or a notification, should be taken. In many cases, these events are related to faults in the device such as when an interface or a fan malfunctions.
EEM defines event filters so only critical events or multiple occurrences of an event within a specified time period trigger an associated action.
Event statements specify the event that triggers a policy to run.
You can configure multiple event triggers. For more information on configuring multiple events, see the EEM Event Correlation.
EEM schedules and runs policies on the basis of event statements. EEM examines the event and action commands and runs them as defined.
Note If you want to allow the triggered event to process any default actions, you must configure the EEM policy to allow the event default action statement.
Action statements describe the action triggered by a policy. Each policy can have multiple action statements. If no action is associated with a policy, EEM still observes events but takes no actions.
EEM supports the following actions in action statements:
Note If you want to allow the triggered event to process any 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 will not allow the CLI command to execute.
Note Verify that your action statements within your user policy or overriding policy do not negate each other or adversely affect the associated system policy.
You can also write policies in a VSH script, using a text editor. These policies have an event statement and action statement(s) just as other policies, and these policies can either augment or override system policies. After you write your VSH script policy, copy it to the device and activate it. To configure a policy in a VSH script, see the Defining a Policy using a VSH Script.
You can define environment variables for EEM that are available for all policies. Environment variables are useful for configuring common values that you can use in multiple policies. For example, you can create an environment variable for the IP address of an external e-mail server.
You can use an environment variable in action statements by using the parameter substitution format.
Example 4-1 shows a sample action statement to force a module 1 shutdown, with a reset reason of “EEM action.”
If you define an environment variable for the shutdown reason, called default-reason, you can replace that reset reason with the environment variable, as shown in Example 4-2.
Example 4-2 Action Statement with Environment Variable
You can reuse this environment variable in any policy. For more information on environment variables, see the Defining an Environment Variable.
You can trigger an EEM policy based on a combination of events. First, you use the tag keyword to create and differentiate multiple events in the EEM policy. Then using a set of boolean operators ( and , or , andnot ), along with the count and time, you can define a combination of these events to trigger a custom action.
Note For information on configuring EEM event correlation, see Defining a User Policy.
The following rules apply to regular command expressions: all keywords must be expanded, and only the * symbol can be used for argument replacement.
The maximum number of configurable EEM policies is 500.
Action statements within your user policy or overriding policy must not negate each other or adversely affect the associated system policy.
You cannot override event statements. You can only override specific action statements (see Overriding a Policy)
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.
If you want to allow a triggered event to process any default actions, then 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 will not allow the CLI command to execute.
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.
Default action execution is not supported for policies that are configured with tagged events.
EEM event correlation is supported only on the Cisco CG-OS Router, not on individual interfaces.
EEM event correlation is not supported across different interfaces within a single policy.
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, syslog, and track.
EEM event correlation does not override the system default policies.
Table 4-1 lists the default settings for EEM parameters.
You can create policies that contain actions to take based on system policies. To display information about the system policies, use the show event manager system-policy command.
This section includes the following topics:
You can define a variable to serve as a parameter in an EEM policy.
Make sure that you are in the default VDC. The Cisco CG-OS router does not support any VDCs beyond the default.
Make sure that you are in the default VDC. The Cisco CG-OS router does not support any VDCs beyond the default.
Registers the applet with EEM and enters applet configuration mode. The applet-name can be any case-sensitive alphanumeric string up to 29 characters. |
||
(Optional) Configures a descriptive string for the policy. The string can be any alphanumeric string up to 80 characters. Enclose the string in quotation marks. |
||
Configures the event statement for the policy and enters the EEM configuration mode. For a list of all supported events statements, see Configuring Event Statements. |
||
tag tag { and | andnot | or } tag [ and | andnot | or { tag }] { happens occurs in seconds } |
(Optional) Correlates multiple events in the policy. The range for the occurs argument is from 1 to 4294967295. The range for the seconds argument is from 0 to 4294967295 seconds. |
|
Configures an action statement for the policy. For a list of all supported action statements, See Configuring Action Statements. |
||
(Optional) action number [ . number2 ] action-statement >> filename |
Enter this action statement for the policy if you want to export the output of an action statement to a specified flash or a directory. Note : The router does not have a default file to log these outputs. |
|
(Optional) Displays information about the status of the configured policy. |
||
Use one or more of the following commands in EEM configuration mode to configure an event statement as shown in Step 4 of the Defining a User Policy section.
Use the one or more of the following commands in EEM configuration mode to configure action statements as shown in Step 6 of the Defining a User Policy section.
Note When you want to allow the triggered event to process any 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, then you must add the event-default action statement to the EEM policy or EEM will not allow the CLI command to execute. You can use the terminal event-manager bypass command to allow all EEM policies with CLI matches to execute the CLI command.
Make sure that you are in the default VDC. The Cisco CG-OS router does not support any VDCs beyond the default.
Ensure that you are logged in with administrator privileges.
Ensure that your script name is the same name as the script filename.
Step 1 In a text editor, list the commands that define the policy.
Step 2 Name the text file and save it.
Step 3 Copy the file to the following system directory:
bootflash://eem/user_script_policies
You can register and activate a policy defined in a VSH script.
Make sure that you are in the default VDC. The Cisco CG-OS router does not support any VDCs beyond the default.
Make sure that you are in the default VDC. The Cisco CG-OS router does not support any VDCs beyond the default.
Overrides a system policy and enters applet configuration mode. The applet-name can be any case-sensitive alphanumeric string up to 29 characters. The system-policy must be one of the existing system policies. |
||
(Optional) Configures a descriptive string for the policy. The string can be any alphanumeric string up to 80 characters. Enclose the string in quotation marks. |
||
Configures an action statement for the policy. For details on action statements, see Configuring Action Statements. Repeat Step 6 in that section to create multiple action statements. |
||
(Optional) Displays information about the configured policy. |
||
This example shows how to override an action statement for a gold system policy.
You can monitor syslog messages from the router.
Note The maximum number of searchable strings to monitor syslog messages is 10.
EEM should be available for registration by syslog.
The syslog daemon must be configured and executed.
Note The maximum number of searchable strings to monitor syslog messages is 10.
To display EEM configuration information, perform one of the following tasks.
Note You must add the event-default action statement to the EEM policy, or EEM will not allow the CLI command to execute.
This example shows how to override the real_time clock.
This example creates an EEM policy that allows the CLI to execute but triggers an SNMP notification when the user enters configuration mode on the router.
This 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 software triggers the EEM policy if one of the specified syslog patterns occurs within 120 seconds.