Feedback
Contents
A through action snmp Commands
A through action snmp Commands
action add
To specify the action of adding values of two variables when an an Embedded Event Manager (EEM) applet is triggered, use the action add command in applet configuration mode. To undo the add action, use the no form of this command.
action label add { long-integer | variable-name } { long-integer | variable-name }
no action label add
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
add
Adds the values of two variables.
variable-name
String value to be placed as the variable name.
long-integer
Long integer value to be added to a variable.
Command Default
By default, there is no change in the value of variables configured within an EEM applet.
Usage Guidelines
You can use this command to add the values of two variables. The result is stored in the variable named $_result. The value of the variable must be a long integer, else the action will fail.
Examples
The following example shows how to configure an EEM applet to add the values of two variables:
Router(config)#event manager applet one Router(config-applet)#action 1.0 set $var1 10 Router(config-applet)#action 1.0 set $var2 20 Router(config-applet)#action 1.0 add $var1 $var2 Router(config-applet)#action append
To specify the action of appending the given string value to the current value of a variable when an Embedded Event Manager (EEM) applet is triggered, use the action append command in applet configuration mode. To undo the append action, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
append
Appends the given string value to the current value of the variable specified.
variable-name
String value to be placed as the variable name.
variable-value
(Optional) Long integer value to be appended tothe value of the variable name specified.
Command Default
By default, there is no change in the value of variables configured within an EEM applet.
Usage Guidelines
You can use this command to append the given string value to the current value of variable. If the variable does not exist, it will be created and set to the given value.
Examples
The following example shows how to configure an EEM applet to append given string value to the current value of the variable specified:
Router(config)#event manager applet one Router(config-applet)#action 1.0 set $var1 10 Router(config-applet)#action 1.0 append $var1 12 Router(config-applet)#action break
To specify the action of exiting from a loop of actions when an Embedded Event Manager (EEM) applet is triggered, use the action break command in applet configuration mode. To disable the break action, use the no form of this command.
Command Default
By default, there is no exit from a loop of actions configured within an EEM applet.
action cli
To specify the action of executing a Cisco IOS command-line interface (CLI) command when an Embedded Event Manager (EEM) applet is triggered, use the action clicommand in applet configuration mode. To remove the action of executing a CLI command, use the no form of this command.
action label cli command cli-string [ pattern pattern-string ]
no action label cli command cli-string
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
command
Specifies the message to be sent to the Cisco IOS CLI.
cli-string
CLI command to be executed. If the string contains embedded blanks, enclose it in double quotation marks.
pattern
(Optional) Specifies the regular expression response pattern for the command cli-stringonly when the command string solicits input.
pattern-string
(Optional) Specifies the action to be specified with the pattern keyword. You are required to specify a regular expression pattern-string that will match the next solicited prompt.
Command History
Release
Modification
12.3(14)T
This command was introduced.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
12.2(33)SXH
The pattern keyword was added.
Usage Guidelines
Use the action cli command to specify the action of executing a Cisco IOS CLI command when an EEM applet is triggered. The pattern keyword is optional and is used only when the command string solicits input.
There are two types of Cisco IOS CLI commands:
- Normal--Those Cisco IOS CLI commands that produce output followed by a display of the normal router prompt. The action cli command ends when the normal router prompt is received.
- Solicited--Those Cisco IOS CLI commands that ask one or more questions before the normal router prompt is displayed, such as “confirm,” which has to be completed with a “yes” or a “no”input.
The action clicommand ends when the solicited prompt as specified in the optional pattern keyword is received. You are required to specify a regular expression pattern that will match the next solicited prompt. Specifying an incorrect pattern will cause the action cli command to wait forever until the applet execution times out due to the maxrun timer expiration.
The vty lines are allocated from the pool of vty lines that are configured using the line vty CLI configuration command. EEM will use a vty line when a vty line is not being used by EEM and there are available vty lines. EEM will also use a vty line when EEM is already using a vty line and there are three or more vty lines available. Be aware that the connection will fail when fewer than three vty lines are available, preserving the remaining vty lines for Telnet use.
The table below shows the built-in variable that is set when the action cli command is run.
Examples
The following example shows how to specify an EEM applet to run when the Cisco IOS interface loopback CLI command is configured three times. The applet executes the no shutdown command to ensure that the loopback interfaces are operational.
Router(config)# event manager applet cli-match Router(config-applet)# event cli command {.*interface loopback*} sync yes occurs 3 Router(config-applet)# action 1.0 cli command "no shutdown"The following example shows how to specify an EEM applet to run when the pattern keyword specifies the confirm argument for the clear counters Ethernet0/1 command.
Router(config)# event manager applet cli-match Router(config-applet)# action 1.0 cli command "enable" Router(config-applet)# action 2.0 cli command "clear counters Ethernet0/1" pattern "confirm" Router(config-applet)# action 3.0 cli command "y" !action cns-event
To specify the action of sending a message to the CNS Event Bus when an Embedded Event Manager (EEM) applet is triggered, use the action cns-eventcommand in applet configuration mode. To remove the action of sending a message to the CNS Event Bus, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
msg
Specifies the message to be sent to the CNS Event Bus.
msg-text
Character text, an environment variable, or a combination of the two. If the string contains embedded blanks, enclose it in double quotation marks.
Command History
Release
Modification
12.0(26)S
This command was introduced.
12.3(4)T
This command was integrated into Cisco IOS Release 12.3(4)T.
12.3(2)XE
This command was integrated into Cisco IOS Release 12.3(2)XE.
12.2(25)S
This command was integrated into Cisco IOS Release 12.2(25)S.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
Examples
The following example shows how to specify a message to be sent to the CNS Event Bus when the memory-fail applet is triggered:
Router(config)# event manager applet memory-fail 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 Router(config-applet)# action 1.0 cns-event msg "Memory exhausted; current available memory is $_snmp_oid_val bytes"action comment
To specify the action of adding comments to an applet when an Embedded Event Manager (EEM) applet is triggered, use the action comment command in applet configuration mode. To disable the comment, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
comment
Adds comments to an applet.
string
Series of characters, including embedded spaces, to be placed as the comment.
Usage Guidelines
You can use this command to add comments to applets. This results in a no-op when the applet is run.
action context retrieve
To specify the action of retrieving variables identified by a given set of context name keys, when an Embedded Event Manager (EEM) applet is triggered, use the action context retrievecommand in applet configuration mode. To undo the retrieve action, use the no form of this command.
action label context retrieve key key-name variable variable-name-pattern
no action label context retrieve
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
context retrieve
Used to retrieve variables identified by the given context name keys.
key key-name
Provides the context name key.
variable variable-name-pattern
Provides description of the variable.
Command Default
By default, no variables specified by a given set of context name keys are retrieved.
Usage Guidelines
You can use this command to retrieve the variable(s) identified by a given set of context name keys. Information that is retrieved is automatically deleted from the context database.
The information for the variable specified in the command is retrieved, only if a variable with the same name was saved in the corresponding context save call, using the action context savecommand.
action context save
To specify the action of saving information across multiple policy triggers, when an Embedded Event Manager (EEM) applet is triggered, use the action context savecommand in applet configuration mode. To remove the saved the information, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
context save
Used to save information across multiple policy triggers.
key key-name
Provides the context name key.
variable variable-name-pattern
Provides description of the variable.
Usage Guidelines
You can use the action context savecommand to save information across multiple policy triggers. The command saves variables that match the given pattern with the context name key as identification. Saved information can be retrieved by a different applet using the action context retrievecommand.
Once the saved information is retrieved, it is automatically deleted from the context database. To save the same information from the applet that retrieved it, you must run the action context savecommand on that applet again.
action continue
To specify the action of continuing with a loop of actions, when an Embedded Event Manager (EEM) applet is triggered, use the action continuecommand in applet configuration mode. To stop the continue action, use the no form of this command.
Examples
The following example shows how to configure an EEM applet to continue with a loop of actions:
Router(config)# event manager applet loop Router(config-applet)# event none Router(config-applet)# action 1 while 1 eq 1 Router(config-applet)# action 2 continue Router(config-applet)# action 3 endaction counter
To specify the action of setting or modifying a named counter when an Embedded Event Manager (EEM) applet is triggered, use the action countercommand in applet configuration mode. To restore the default value to the counter, use the no form of this command.
action label counter name counter-name value counter-value op { dec | inc | nop | set }
no action label counter name counter-name value counter-value op { dec | inc | nop | set }
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
name
Specifies the name of the counter to be set or modified.
counter-name
Name of the counter to be set or modified. The counter name is referenced in a registered counter type policy.
value
Specifies the value to be used to set or modify the counter.
counter-value
Number in the range from -2147483648 to 2147483647, inclusive.
op
Indicates the operator to be used with the counter-value to set or modify the specified counter.
dec
Specifies that the counter is decreased in value by the amount specified in the counter-valueargument.
inc
Specifies that the counter is increased in value by the amount specified in the counter-valueargument.
nop
Specifies that the counter value is read from the environment variable $_counter_value_remain.
set
Specifies that the counter is set to the value specified in the counter-value argument.
Command History
Release
Modification
12.2(25)S
This command was introduced.
12.3(14)T
This command was integrated into Cisco IOS Release 12.3(14)T.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
Usage Guidelines
Use the action counter command when an event occurs periodically and you want an action to be implemented after a specified number of occurrences of that event. When the action counter command completes, an environment variable is updated as shown in the table below.
The table below shows the built-in variable that is set when the action counter command is run.
Table 2 EEM Built-in Variables for action counter Command Built-in Variable
Description
$_counter_value_remain
The value of the counter after the execution of the action counter command.
Use the event counter command with the action counter command when an event occurs periodically and you want an action to be implemented after a specified number of occurrences of the event.
Examples
The following example shows an EEM applet called IPSLAping1 being registered to run when there is an exact match on the value of a specified SNMP object ID that represents a successful IP SLA ICMP echo operation (this is equivalent to a ping command). Four actions are triggered when the echo operation fails, and event monitoring is disabled until after the second failure. A message saying that the ICMP echo operation to a server failed is sent to syslog, an SNMP trap is generated, EEM publishes an application-specific event, and a counter called IPSLA1F is incremented by a value of one.
Router(config)# event manager applet IPSLAping1 Router(config-applet)# event snmp 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 Router(config-applet)# action 1.0 syslog priority critical msg "Server IP echo failed: OID=$_snmp_oid_val" Router(config-applet)# action 1.1 snmp-trap strdata "EEM detected server reachability failure to 10.1.88.9" Router(config-applet)# action 1.2 publish-event sub-system 88000101 type 1 arg1 10.1.88.9 arg2 IPSLAEcho arg3 fail Router(config-applet)# action 1.3 counter name _IPSLA1F value 1 op incThe following example shows a policy--EventCounter_A--that is configured to run once a minute and to increment a well-known counter called critical_errors. A second policy--EventCounter_B--is registered to be triggered when the well-known counter called critical_errors exceeds a threshold of 3. When policy EventCounter_B runs, it resets the counter back to 0.
Router(config)# event manager applet EventCounter_A Router(config-applet)# event timer watchdog time 60.0 Router(config-applet)# action 1.0 syslog msg “EventCounter_A” Router(config-applet)# action 2.0 counter name critical_errors value 1 op inc Router(config-applet)# exitaction decrement
To specify the action of decrementing the value of a variable, when an Embedded Event Manager (EEM) applet is triggered, use the action decrement command in applet configuration mode. To remove the action from the applet, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
decrement
Decrements the value of the variable with the integer specified.
variable-name
String value to be placed as the variable name.
long-integer
Long integer value by which the variable gets decremented.
Command Default
By default, there is no change in the value of variables configured within an EEM applet.
action divide
To divide the dividend value by the given divisor value when an Embedded Event Manager (EEM) applet is triggered, use the action divide command in applet configuration mode. To remove the calculation process, use the no form of this command.
action label divide [ long-integer-1 | variable-name-1 ] [ long-integer-2 | variable-name-2 ]
no action label divide
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
long-integer-1
(Optional) First dividend integer value for the division.
variable-name-1
(Optional) First dividend variable name for the division. The value stored in the dividend variable name must be a long integer value or else the action will fail.
long-integer-2
(Optional) Second divisor integer value for the division.
variable-name-2
(Optional) Second divisor variable name for the division. The value stored in the divisor variable name must be a long integer value or else the action will fail.
Command Default
If the command is not entered within applet configuration mode, the respective applet is not registered when you exit the configuration.
Usage Guidelines
Use the action dividecommand to divide the dividend value with a given divisor value. All arithmetic calculations are performed as long integers without any checks for overflow. If a statement is not associated with this applet, events are still triggered without any action or result. A warning message stating that no statements are associated with this applet is displayed at the exit time of the configuration. All the results of the divide action command except the remainder value are saved in $_result. The remainder value of the divided integer is saved in $_remainder. Floating points (decimal) are not supported.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- Event specification criteria are written in Tcl in the Tcl-based implementation.
- Event specification data are written using the CLI applet submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet-based implementation because the Tcl-based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-name command after entering global configuration mode. In applet configuration mode, the config prompt changes to (config-applet)#. The applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that causes this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
Examples
The following example shows how to divide the value of the dividend by the value of the divisor.
Router(config)# event manager applet action Router(config-applet)# action label2 divide 45 15Related Commands
Command
Description
action add
Adds the value of the variable by the given value when an EEM applet is triggered.
action multiply
Multiplies the value of the variable by the given value when an EEM applet is triggered.
action subtract
Subtracts the value of the variable by the given value when an EEM applet is triggered.
action else
To identify the beginning of an else conditional action block in an if/else conditional action block when an Embedded Event Manager (EEM) applet is triggered, use the action else command in applet configuration mode. To remove the else conditional action block, use the no form of this command.
Command Default
If the command is not entered within applet configuration mode, the respective applet is not registered when you exit the configuration.
Usage Guidelines
Use the action elsecommand to identify the else conditional action block. If a statement is not associated with this applet, events are still triggered without any action or result. A warning message stating that no statements are associated with this applet is displayed at the exit time of the configuration.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- Event specification criteria are written in Tcl in the Tcl-based implementation.
- Event specification data are written using the CLI applet-submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet-based implementation because the Tcl-based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-name command after entering global configuration mode. In applet configuration mode the config prompt changes to (config-applet)#. The applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that causes this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
action elseif
To identify the beginning of the elseif conditional action block in the else/if conditional action block when an Embedded Event Manager (EEM) applet is triggered, use the action elseif command in applet configuration mode. To remove the elseif conditional action block, use the no form of this command.
action label elseif [string-op-1] { eq | gt | ge | lt | le | ne } [string-op-2]
no action label elseif
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
string-op-1
(Optional) Sequence of characters that will replace the range of characters in the string.
eq
Equal To keyword used for comparing two strings.
gt
Greater Than keyword used for comparing two strings.
ge
Greater Than or Equal To keyword used for comparing two strings.
lt
Less Than keyword used for comparing two strings.
le
Less Than or Equal To keyword used for comparing two strings.
ne
Not Equal To keyword used for comparing two strings.
string-op-2
(Optional) Sequence of characters that will replace the range of characters in the string.
Command Default
If the command is not specified within applet configuration mode, the respective applet is not registered when you exit the configuration.
Usage Guidelines
Use the action elseifcommand to identify the beginning of the else conditional action block in the else/if conditional action block. All arithmetic calculations are performed as long integers without any checks for overflow. If a statement is not associated with this applet, events are still triggered without any action or result. A warning message stating that no statements are associated with this applet is displayed at the exit time of the configuration.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- Event specification criteria are written in Tcl in the Tcl-based implementation.
- Event specification data is written using the CLI applet-submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet-based implementation because the Tcl-based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-name command in global configuration mode. In applet configuration mode, the config prompt changes to (config-applet)#. Applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that cause this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
Examples
The following example shows how to identify the beginning of the elseif conditional action block.
Router(config)# event manager applet action Router(config-applet)# event none Router(config-applet)# action 1.0 set x "5" Router(config-applet)# action 2.0 if $x lt 3 Router(config-applet)# action 3.0 puts "$x is less than 3" Router(config-applet)# action 4.0 elseif $x lt 10 Router(config-applet)# action 5.0 puts "$x is less than 10" Router(config-applet)# action 6.0 end Router# event manager run action 5 is less than 10 Router#Related Commands
Command
Description
action else
Identifies the beginning of the else conditional action block when an EEM applet is triggered.
action if
Identifies the beginning of an if conditional action block when an EEM applet is triggered.
action ifgoto
Signifies the applet to jump to the given label if the condition is true when an EEM applet is triggered.
action end
To identify the end of a conditional action block in the if/else and while conditional action block when an Embedded Event Manager (EEM) applet is triggered, use the action end command in applet configuration mode. To remove the end conditional action block, use the no form of this command.
Command Default
If the commands are not specified within applet configuration mode, the respective applet is removed when you exit the configuration.
Usage Guidelines
Use the action endcommand to identify the end of a conditional action block in the if/else and while conditional action block.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- Event specification criteria are written in Tcl in the Tcl-based implementation.
- Event specification data are written using the CLI applet submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet-based implementation because the Tcl-based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-name command after entering global configuration mode. In applet configuration mode the config prompt changes to (config-applet)#. The applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that causes this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
Examples
The following example shows hoe to identify the end of a conditional action block:
Router(config)# event manager applet action Router(config-applet)# event none Router(config-applet)# action 1.0 set x "5" Router(config-applet)# action 2.0 if $x lt 10 Router(config-applet)# action 3.0 puts "$x is less than 10" Router(config-applet)# action 4.0 endaction exit
To immediately exit from the running applet configuration when an Embedded Event Manager (EEM) applet is triggered, use the action exit command in applet configuration mode. To cancel the process of immediate exit from the running applet, use the no form of this command.
Command Default
If the commands are not specified within applet configuration mode, the respective applet is removed when you exit the configuration.
Usage Guidelines
Use the action exit command to immediately exit from the running applet configuration. All arithmetic calculations are performed as long integers without any checks for overflow. If a statement is not associated with this applet, events are still triggered without any action or result. A warning message stating that no statements are associated with this applet is displayed at the exit time of the configuration.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- The event specification criteria are written in Tcl in the Tcl-based implementation.
- The event specification data are written using the CLI applet submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet-based implementation because the Tcl-based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-name command after entering global configuration mode. In applet configuration mode the config prompt changes to (config-applet)#. The applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that causes this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
action file
To configure the Embedded Event Manager (EEM) applet file operations, use the action file command in applet configuration mode. To disable the configuration, use the no form of this command.
action label file { close file-descriptor | delete file-descriptor | gets file-descriptor variable-name | open file-descriptor file-name access-permission | puts file-descriptor { string | nonewline string } | read file-descriptor variable-name number | write file-descriptor string number }
no action label file
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
close
Specifies the file to close.
filename
Name of the file.
delete
Specifies the file to delete.
gets
Specifies the information or file to get.
variable-name
Variable name to store the get result.
open
Specifies the file to open
file-access
File access. Valid values are
puts
string
nonewline
Specifies that no new line should be added.
read
Specifies the file to read.
number
Specifies the file to write information.
write
action force-switchover
To specify the action of switching to a secondary processor in a fully redundant environment when an Embedded Event Manager (EEM) applet is triggered, use the action force-switchovercommand in applet configuration mode. To remove the action of switching to a secondary processor, use the no form of this command.
Command History
Release
Modification
12.0(26)S
This command was introduced.
12.3(4)T
This command was integrated into Cisco IOS Release 12.3(4)T.
12.3(2)XE
This command was integrated into Cisco IOS Release 12.3(2)XE.
12.2(25)S
This command was integrated into Cisco IOS Release 12.2(25)S.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
Usage Guidelines
Before using the action force-switchover command, you must install a backup processor in the device. If the hardware is not fully redundant, the switchover action will not be performed.
Examples
The following example shows how to specify a switch to the secondary Route Processor (RP) when the memory-fail applet is triggered:
Router(config)# event manager applet memory-fail 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 Router(config-applet)# action 2.0 force-switchoveraction foreach
To specify the iteration of an input string using the delimiter as a tokenizing pattern, use the action foreach command in applet configuration mode. To remove iteration of the input string, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
string-iterator
(Optional) Series of characters that acts as an iterator. If the string contains embedded blanks, enclose it in double quotation marks.
string-input
(Optional) Series of characters that acts as an input. If the string contains embedded blanks, enclose it in double quotation marks.
string-delimiter
(Optional) Series of characters that acts as a delimiter. If the string contains embedded blanks, enclose it in double quotation marks. The default delimiter is whitespace.
Command Default
If the commands are not specified within applet configuration mode, the respective applet is removed when you exit the configuration.
Usage Guidelines
Use the action foreach command to iterate an input string using the delimiter as a tokenizing pattern. The delimiter is a regular expression pattern string. The token found in each iteration is assigned to the given iterator variable. All arithmetic calculations are performed as long integers without any checks for overflow. If a statement is not associated with this applet, events are still triggered without any action or result. A warning message stating that no statements are associated with this applet is displayed at the exit time of the configuration.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- The event specification criteria are written in Tcl in the Tcl-based implementation.
- The event specification data are written using the CLI applet submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet-based implementation because the Tcl-based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-namecommand after entering global configuration mode. In applet configuration mode the config prompt changes to (config-applet)#. The applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that causes this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
Examples
The following example shows how to iterate an input string using the delimiter as a tokenizing pattern:
Router(config)# event manager applet action Router(config-applet)# event none Router(config-applet)# action 1 foreach _iterator "red blue green orange" Router(config-applet)# action 2 puts "iterator is $_iterator" Router(config-applet)# action 3 end Router# event manager run action iterator is red iterator is blue iterator is green iterator is orange Router#action gets
To get an input from the local tty in a synchronous applet and store the value in the given variable when an Embedded Event Manager (EEM) applet is triggered, use the action gets command in applet configuration mode. To cancel the process of receiving an input from the local tty, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
variable
Variable word that stores the input value from the synchronous applet.
Command Default
If the commands are not specified within applet configuration mode, the respective applet is removed when you exit the configuration.
Usage Guidelines
Use the action gets command to get an input from the local tty in a synchronous applet and store the value in the given variable. This command is not operational for asynchronous applets. The applet continues without any error but does not set the variable. All arithmetic calculations are performed as long integers without any checks for overflow. If a statement is not associated with this applet, events are still triggered without any action or result. A warning message stating that no statements are associated with this applet is displayed at the exit time of the configuration.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- Event specification criteria are written in Tcl in the Tcl-based implementation.
- Event specification data are written using the CLI applet submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet based implementation because the Tcl-based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-name command after entering the global configuration mode. In applet configuration mode the config prompt changes to (config-applet)#. The applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that causes this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
Examples
The following example shows how to get the input from the local tty in a synchronous applet and store the value:
Router(config)# event manager applet action Router(config-applet)# event none Router(config-applet)# action label2 gets input Router(config-applet)# action label3 syslog msg “Input entered was \”$input\“”action if
To identify the beginning of an if conditional block when an Embedded Event Manager (EEM) applet is triggered, use the action if command in applet configuration mode. To remove the if conditional action block, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
string-op-1
(Optional) Sequence of characters that will replace the range of characters in the string.
eq
Equal To keyword used for comparing two strings.
gt
Greater Than keyword used for comparing two strings.
ge
Greater Than or Equal To keyword used for comparing two strings.
lt
Less Than keyword used for comparing two strings.
le
Less Than or Equal To keyword used for comparing two strings.
ne
Not Equal To keyword used for comparing two strings.
string-op-2
(Optional) Sequence of characters that will replace the range of characters in the string.
Command Default
If the commands are not specified within applet configuration mode, the respective applet is removed when you exit the configuration.
Usage Guidelines
Use the action ifcommand to identify the beginning of the if conditional action block. All arithmetic calculations are performed as long integers without any checks for overflow. If the goto label option is used, the if functionality will not identify the beginning of a action block, but will signify the applet to jump to the given label if the condition is true.
If a statement is not associated with this applet, events are still triggered without any action or result. A warning message stating that no statements are associated with this applet is displayed at the exit time of the configuration.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- Event specification criteria are written in Tcl in the Tcl-based implementation.
- Event specification data are written using the CLI applet submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet based implementation because the Tcl based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-name command after entering global configuration mode. In applet configuration mode the config prompt changes to (config-applet)#. The applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that causes this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
Examples
The following example shows how to identify the beginning of an if conditional block:
Router(config)# event manager applet action Router(config-applet)# event none Router(config-applet)# action 1.0 set x "5" Router(config-applet)# action 2.0 if $x lt 10 Router(config-applet)# action 3.0 puts "$x is less than 10" Router(config-applet)# action 4.0 end Router# event manager run action 5 is less than 10 Router#action ifgoto
To instruct the applet to jump to a given label if the specified condition is true when an Embedded Event Manager (EEM) applet is triggered, use the action ifgoto command in applet configuration mode. To cancel the process of applet jump, use the no form of this command.
action label-1 if [string-op-1] { eq | gt | ge | lt | le | ne } [string-op-2] goto label-2
no action label ifgoto
Syntax Description
label-1
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
string-op-1
(Optional) Sequence of characters that will replace the range of characters in the string.
eq
Equal To keyword used for comparing two strings.
gt
Greater Than keyword used for comparing two strings.
ge
Greater Than Or Equal To keyword used for comparing two strings.
lt
Less Than keyword used for comparing two strings.
le
Less Than Or Equal To keyword used for comparing two strings.
ne
Not Equal To keyword used for comparing two strings.
string-op-2
(Optional) Sequence of characters that will replace the range of characters in the string.
label-2
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
Command Default
If the command is not specified within applet configuration mode, the respective applet is removed when you exit the configuration.
Usage Guidelines
Use the action ifgotocommand to signify the applet to jump to a given label if the specified condition is true. If the goto labeloption is used, the action if command will not identify the beginning of an action block. Goto actions are supported only within the if/goto format. To simulate a goto without if, use a test that is always true. All arithmetic calculations are performed as long integers without any checks for overflow. If a statement is not associated with this applet, events are still triggered without any action or result. A warning message stating that no statements are associated with this applet is displayed at the exit time of the configuration.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- Event specification criteria are written in Tcl in the Tcl-based implementation.
- Event specification data is written using the CLI applet submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet-based implementation because the Tcl-based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-name command in the global configuration mode. In applet configuration mode, the config prompt changes to (config-applet)#. Applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that cause this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
Examples
The following example shows how to instruct the applet to jump to a given label:
Router(config)# event manager applet action Router(config-applet)# event none Router(config-applet)# action 1 set x "5" Router(config-applet)# action 2 if $x lt 10 goto 4 Router(config-applet)# action 3 puts "skipping this" Router(config-applet)# action 4 puts "jumped to action 4" Router(config-applet)# action 5 end Router# event manager run action jumped to action 4action increment
To specify the action of incrementing the value of a variable, when an Embedded Event Manager (EEM) applet is triggered, use the action increment command in applet configuration mode. To remove the action from the applet, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
increment
Increments the value of the variable with the long integer specified.
variable-name
String value to be placed as the variable name.
long-integer
Long integer value by which the variable is incremented.
Command Default
By default, there is no change in the value of variables configured within an EEM applet.
Usage Guidelines
You can use this command to increment the value of a variable. The value of the variable must be a long integer, else the action will fail.
action info
To specify the action of obtaining system information when an Embedded Event Manager (EEM) applet is triggered, use the action infocommand in applet configuration mode. To remove the action info command from the configuration, use the no form of this command.
action label info type { cli frequency | cli history | syslog frequency | syslog history | routername | snmp oid oid-value get-type { exact | next } }
no action label info type { cli frequency | cli history | syslog frequency | syslog history | routername | snmp oid oid-value get-type { exact | next } }
Syntax Description
Command History
Release
Modification
12.3(14)T
This command was introduced.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
Usage Guidelines
Use the action info command when an event occurs and you want to request some system information. When the snmp oid keyword is used, an error message is returned when the OID is not one of the defined types.
The table below shows the built-in variables that are set for the various action info keywords. The notation [1-N] represents that the built-in variable ends in a sequential number starting at 1 up to the maximum number of entries returned.
Table 3 EEM Built-in Variables for action info Command Built-in Variable
Description
action info cli frequency
$_info_cli_freq_num_entries
The number of CLI event entries.
$_info_cli_freq_pattern_[1-N]
A regular expression used to perform CLI command pattern matching.
$_info_cli_freq_time_sec_[1-N]
The seconds in Posix timer units since January 1, 1970, which represents the time the last CLI event was raised.
$_info_cli_freq_time_msec_[1-N]
The milliseconds in Posix timer units since January 1, 1970, which represents the time the last CLI event was raised.
$_info_cli_freq_match_count_[1-N]
The number of times that a CLI command matches the pattern specified by this CLI event specification.
$_info_cli_freq_raise_count_[1-N]
The number of times that this CLI event was raised.
$_info_cli_freq_sync_[1-N]
A “yes” means that event publish should be performed sychronously. The event detector will be notified when the Event Manager Server has completed publishing the event. The Event Manager Server will return a code that indicates whether or not the CLI command should be executed.
$_info_cli_freq_skip_[1-N]
A “yes” means that the CLI command should not be executed if the sync flag is not set.
$_info_cli_freq_occurs_[1-N]
Number of occurrences before an event is raised; if this argument is not specified an event is raised on the first occurrence.
$_info_cli_freq_period_sec_[1-N]
Number of occurrences must occur within this number of seconds in order to raise event; if not specified, does not apply.
$_info_cli_freq_period_msec_[1-N]
The number of occurrences must occur within this number of milliseconds in order to raise the event; if not specified, the period check does not apply.
action info cli history
$_info_cli_hist_num_entries
The number of cli history entries.
$_info_cli_hist_cmd_[1-N]
The text of the CLI command.
$_info_cli_hist_time_sec_[1-N]
The time, in seconds, when the CLI command occurred.
$_info_cli_hist_time_msec_[1-N]
The time, in milliseconds, when the CLI command occurred.
action info routername
$_info_routername
The name of the router.
action info snmp
$_info_snmp_oid
The SNMP object ID.
$_info_snmp_value
The value string of the associated SNMP data element.
action info syslog frequency
$_info_syslog_freq_num_entries
The number of syslog entries.
$_info_syslog_freq_pattern_[1-N]
A regular expression used to perform syslog message pattern matching.
$_info_syslog_freq_time_sec_[1-N]
The seconds in Posix timer units since January 1, 1970, which represents the time the last event was raised.
$_info_syslog_freq_time_msec_[1-N]
The milliseconds in Posix timer units since January 1, 1970, which represents the time the last event was raised.
$_info_syslog_freq_match_count_[1-N]
The number of times that a syslog message matches the pattern specified by this syslog event specification since event registration.
$_info_syslog_freq_raise_count_[1-N]
The number of times that this syslog event was raised.
$_info_syslog_freq_occurs_[1-N]
The number of occurrences needed in order to raise the event; if not specified, the event is raised on the first occurrence.
$_info_syslog_freq_period_sec_[1-N]
The number of occurrences must occur within this number of Posix timer units in order to raise the event; if not specified, the period check does not apply.
$_info_syslog_freq_period_msec_[1-N]
The number of occurrences must occur within this number of Posix timer units in order to raise the event; if not specified, the period check does not apply.
action info syslog history
$_info_syslog_hist_num_entries
The number of syslog history entries.
$_info_syslog_hist_msg_[1-N]
The text of the syslog message.
$_info_syslog_hist_time_sec_[1-N]
The seconds since January 1, 1970 which represent the time the syslog message was logged.
$_info_syslog_hist_time_msec_[1-N]
The milliseconds since January 1, 1970 which represent the time the syslog message was logged.
Examples
The following example shows how to configure an EEM applet to intercept configuration commands that attempt to access any loopback interface. The applet also performs a no shutdown command on the interface that is selected, and logs a message with the number of times that any “interface loopback” has been attempted. The console output is shown with the configuration because the final line displays the log message.
NoteCLI commands that are issued from within a policy do not participate in CLI event pattern matching, and this prevents recursion.
Router# configure terminal Enter configuration commands, one per line. End with CNTL/Z. Router(config)# event manager applet cli-match Router(config-applet)# event cli pattern ".*interface Loopback.*" sync yes Router(config-applet)# action 1.0 cli command "enable" Router(config-applet)# action 1.1 cli command "$_cli_msg" Router(config-applet)# action 1.2 cli command "no shutdown" Router(config-applet)# action 1.3 info type cli frequency Router(config-applet)# action 1.4 syslog msg "There have been $_info_cli_freq_match_count_1 '$_info_cli_freq_pattern_1' matches." Router(config-applet)# set 1.5 _exit_status 0 Router(config-applet)# end Router# 00:37:30: %SYS-5-CONFIG_I: Configured from console by console Router# configure terminal Enter configuration commands, one per line. End with CNTL/Z. Router(config)# interface loopback0 Router(config)# 00:37:43: %HA_EM-6-LOG: cli-match: There have been 27 '.*interface Loopback.*' matches.action info type interface-names
To obtain interface names when an Embedded Event Manager (EEM) applet is triggered, use the action info type interface-namescommand in applet configuration mode. To disable the action of obtaining interface names, use the no form of this command.
action label info type interface-names [ include string-operator | exclude string-operator | regexp regular-expression ]
no action label info type
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
include
(Optional) Includes all interface names that contain the string pattern.
exclude
(Optional) Excludes all interface names that contain the string pattern.
string-operator
(Optional) String pattern for including or excluding the interface names.
regexp
(Optional) Obtains all the interfaces that match the specified regular expression.
regular-expression
(Optional) Regular expression pattern. For example, [^abc].
Usage Guidelines
The action info type interface-namescommand obtains the current interface names and stores them as a space-separated list in the $_info_interface_names built-in variable.
action info type snmp getid
To retrieve the individual variables from a Simple Network Management Protocol (SNMP) entity during the SNMP get operation, use the action info type snmp getidcommand in applet configuration mode. To disable the retrieving of individual variables from SNMP, use the no form of this command.
action label info type snmp getid oid-value [ community community-string ] [ ipaddr ip-address ]
no action label info type
Syntax Description
Usage Guidelines
The table below shows the built-in variables in which the variables retrieved from the SNMP get operation are stored.
Table 4 EEM Built-in Variables for action info Command Built-in Variable
Description
$_info_snmp_sysname_oid
The OID value of the sysName variable.
$_ info_snmp_sysname_value
The value string for the sysName variable.
$_info_snmp_syslocation_oid
The OID value of the sysLocation variable.
$_info_snmp_syslocation_value
The value string for the sysLocation variable.
$_info_snmp_sysdescr_oid
The OID value of the sysDescr variable.
$_info_snmp_sysdescr_value
The value string for the sysDescr variable.
$_info_snmp_sysobjectid_oid
The OID value of the sysObjectID variable.
$_info_snmp_sysobjectid_value
The value string for the sysObjectID variable.
$_info_snmp_sysuptime_oid
The OID value of the sysUptime variable.
$_info_snmp_sysuptime_value
The value string for the sysUptime variable.
$_info_snmp_syscontact_oid
The OID value of the sysContact variable.
$_info_snmp_syscontact_value
The value string for the sysContact variable.
action info type snmp inform
To send Simple Network Management Protocol (SNMP) inform requests when an Embedded Event Manager (EEM) applet is triggered, use the action info type snmp informcommand in applet configuration mode. To disable the sending of SNMP inform requests, use the no form of this command.
action label info type snmp inform trap-oid trap-oid-value trap-var trap-variable community community-string ipaddr ip-address
no action label info type
Syntax Description
Usage Guidelines
SNMP inform requests are the SNMP notifications that alert the SNMP manager to a network condition and request for confirmation of receipt from the SNMP manager.
Examples
The following example shows how to send an SNMP inform request:
Router(config)# event manager applet Router(config-applet)# action 1.4 info type snmp inform trap-oid 1.3.6.1.4.1.1.226.0.2.1 trap-var sysUpTime community public ipaddr 172.69.16.2 Router(config-applet)#action info type snmp oid
To specify the type of Simple Network Management Protocol (SNMP) get operation and the object to retrieve during the SNMP set operation, when an Embedded Event Manager (EEM) applet is triggered, use the action info type snmp oidcommand in applet configuration mode. To disable this function, use the no form of this command.
action label info type snmp oid oid-value { get-type { exact | next } [ community community-string ] | set-type oid-type oid-type-value community community-string } [ ipaddr ip-address ]
no action label info type
Syntax Description
Command Default
No requests for SNMP set or get operations are sent when the EEM applet is triggered.
Command History
Release
Modification
12.3(14)T
This command was introduced.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
12.4(22)T
The set-type, community,and ipaddr keywords were added.
Usage Guidelines
The SNMP set operation sets individual variables in the SNMP entity, whereas the SNMP get operation retrieves individual variables from the SNMP entity.
The table below shows the built-in variables in which the results of SNMP get and set operations are stored.
Examples
The following example shows how to retrieve individual variables of an object from the SNMP entity:
Router(config)# event manager applet Router(config-applet)# action 1.3 info type snmp oid 1.3.6.1.4.1.9.9.48.1.1.1.6.1 get-type exact community public ipaddr 172.17.16.69 Router(config-applet)#The following example shows how to set an individual variable in the SNMP entity:
Router(config)# event manager applet Router(config-applet)# action 1.4 info type snmp oid 1.3.6.1.4.1.9.9.48.1.1.1.6.1 set-type integer 42220 sysName.0 community public ipaddr 172.17.16.69 Router(config-applet)#action info type snmp trap
To send Simple Network Management Protocol (SNMP) trap requests when an Embedded Event Manager (EEM) applet is triggered, use the action info type snmp trapcommand in applet configuration mode. To disable the sending of SNMP trap requests, use the no form of this command.
action label info type snmp trap enterprise-oid enterprise-oid-value generic-trapnum generic-trap-number specific-trapnum specific-trap-number trap-oid trap-oid-value trap-var trap-variable
no action label info type
Syntax Description
Usage Guidelines
Traps are SNMP notifications that alert the SNMP manager or the NMS to a network condition. Unlike SNMP inform requests, traps do not request the receipt from the SNMP manager.
Examples
The following example shows how to send an SNMP trap request:
Router(config)# event manager applet Router(config-applet)# action 1.4 info type snmp trap enterprise-oid 1.3.6.1.4.1.1 generic-trapnum 4 specific-trapnum 7 trap-oid 1.3.6.1.4.1.1.226.0.2.1 trap-var sysUpTime Router(config-applet)#action info type snmp var
To create a variable for a Simple Network Management Protocol (SNMP) object identifier (OID) and its value from an Embedded Event Manager (EEM) applet, use the action info type snmp varcommand in applet configuration mode. To remove the variable, use the no form of this command.
action label info type snmp var variable-name oid oid-value oid-type oid-type-value
no action label info type
Syntax Description
Usage Guidelines
A variable is identified by its OID and its instance. The instance is generally specified by appending a .0 to its OID. For example, sysDescr.0.
action mail
To specify the action of sending a short e-mail when an Embedded Event Manager (EEM) applet is triggered, use the action mail command in applet configuration mode. To remove the action mailcommand from the configuration, use the no form of this command.
action label mail server server-address to to-address from from-address [ cc cc-address ] subject subject body body-text port port-number secure { none | tls } source-address { ipv4-address | ipv6-address } source-interface interface-type interface-number vrf vrf-name
no action label mail server server-address to to-address from from-address [ cc cc-address ] subject subject body body-text port port-number secure { none | tls } source-address { ipv4-address | ipv6-address } source-interface interface-type interface-number vrf vrf-name
Syntax Description
Command History
Release
Modification
12.3(14)T
This command was introduced.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
12.4(22)T
This command was modified. The server-address argument was modified to include an optional username and password.
15.2(2)T
This command was modified. The port, secure, none, tls, and vrf keywords were added.
15.1(1)SY
This command was integrated into Cisco IOS Release 15.1(1)SY.
Usage Guidelines
Use the action mail command when an event occurs about which you want to send an e-mail message, such as informing an administrator about the event.
In EEM 3.0 for Cisco IOS Release 12.4(22)T, the server-address argument includes an optional username and password along with the fully qualified domain name of the e-mail server to be used to forward the e-mail. The e-mail server name can be in any one of the following template formats:
For example, username:123456@mailserver.cisco.com, or username@mailserver.cisco.com, or mailserver.cisco.com. If a username is supplied, the router will attempt to authenticate using the LOGIN AUTH dialog. If no username is supplied, no authentication is performed.
Examples
The following example shows how to send an e-mail when an EEM applet executes. The applet named EventInterface is triggered every time the receive_throttle counter for Fast Ethernet interface 0/0 is incremented by 5. The polling interval to check the counter is specified to run once every 90 seconds. When the applet is triggered, a syslog message and an e-mail are sent.
Router(config)# event manager applet EventInterface Router(config-applet)# event interface name FastEthernet0/0 parameter receive_throttle entry-op ge entry-val 5 entry-val-is-increment true poll-interval 90 Router(config-applet)# action 1.0 syslog msg "Applet EventInterface" Router(config-applet)# action 1.1 mail server mailserver.example.com to example1@example.com from example2@example.com cc example-manager@example.com subject "Receive_throttle counter incremented" body "Receive_throttle counter for FastEthernet0/0 interface has incremented by 5"The following example shows how to configure SMTP secure TLS settings:
Router# configure terminal Router(config)# event manager applet TEST Router(config-applet)# event none Router(config-applet)# action 1.0 mail from example1@example.com to example2@example.com subject "Hello EEM World" body "I am a Router" server root:example@smtp-server.example.com port 587 secure tls Router(config-applet)# endThe following example shows how to configure SMTP custom port settings:
Router(config)#event manager applet TEST Router(config-applet)#event none Router(config-applet)#action 1.0 mail from Router@cisco.com to user@cisco.com subject "Hello EEM World" body "I am Router" server root:lab@smtp-server.cisco.com port 465 Router(config-applet)#endRelated Commands
Command
Description
event interface
Specifies the event criteria for an EEM applet that is run on the basis of a generic interface counter crossing a threshold or reaching exit criteria.
event manager applet
Registers an event applet with the Embedded Event Manager and enters applet configuration mode.
action multiply
To specify the action of multiplying the variable value with a specified given integer value when an Embedded Event Manager (EEM) applet is triggered, use the action multiply command in applet configuration mode. To remove the calculation process, use the no form of this command.
action label multiply [ long-integer-1 | variable-name-1 ] [ long-integer-2 | variable-name-2 ]
no action label multiply
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
long-integer-1
(Optional) First integer value for the multiplication.
variable-name-1
(Optional) First variable name for the multiplication. The value stored in the multiplier variable-name must be a long integer value or else the action will fail.
long-integer-2
(Optional) Second integer value for the multiplication.
variable-name-2
(Optional) Second variable name for the multiplication. The value stored in the multiplier variable-name must be a long integer value or else the action will fail.
Command Default
If the command is not entered within applet configuration mode, the respective applet is not registered when you exit the configuration.
Usage Guidelines
Use the action multiplycommand to multiply the value of the variable with a given integer value. All arithmetic calculations are performed as long integers without any checks for overflow. If a statement is not associated with this applet, events are still triggered without any action or result. A warning message stating that no statements are associated with this applet is displayed at the exit time of the configuration. All the results of the action multiply command are stored in $_result.
To provide a consistent user interface for the customers between the Tool Command Language (Tcl) and the CLI applet-based EEM policies, the following criteria are followed:
- Event specification criteria are written in Tcl in the Tcl-based implementation.
- Event specification data are written using the CLI applet submode configuration statements in the applet-based implementation.
Some of the keywords appear to be longer than necessary or hyphenated in the applet-based implementation because the Tcl-based implementation was developed and deployed first.
To enter applet configuration mode, use the event manager applet applet-name command after entering global configuration mode. In applet configuration mode the config prompt changes to (config-applet)# . Applet configuration mode supports three types of configuration statements:
- event --Specifies the event criteria that causes this applet to run.
- action --Performs a built-in action.
- set --Sets an applet variable (currently _exit_status is the only variable supported).
Examples
The following example shows how to multiply the stored variable value.
Router(config)# event manager applet action Router(config-applet)# action label2 multiply 23 25Related Commands
Command
Description
action add
Adds the value of the variable by the given value when an EEM applet is triggered.
action divide
Divides the value of the variable by the given value when an EEM applet is triggered.
action subtract
Subtracts the value of the variable by the given value when an EEM applet is triggered.
action policy
To specify the action of manually running an Embedded Event Manager (EEM) policy when an EEM applet is triggered, use the action policycommand in applet configuration mode. To remove the action policycommand from the configuration, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
policy-filename
Name of the EEM policy to be run manually. The policy must be previously registered using the event none command and must not be the same as the current policy.
Command History
Release
Modification
12.3(14)T
This command was introduced.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
Usage Guidelines
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 run manually or when an EEM applet is triggered. To run the policy, use either the action policy command in applet configuration mode or the event manager run command in global configuration mode.
action publish-event
To specify the action of publishing an application-specific event when the event specified for an Embedded Event Manager (EEM) applet is triggered, use the action publish-eventcommand in applet configuration mode. To remove the action of publishing an application-specific event, use the no form of this command.
action label publish-event sub-system sub-system-id type event-type arg1 argument-data [ arg2 argument-data ] [ arg3 argument-data ] [ arg4 argument-data ]
no action label publish-event
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
sub-system
Specifies an identifier for the subsystem named in the sub-system-id argument that will publish the application event.
sub-system-id
Identifier of the subsystem. Number in the range from 1 to 4294967295. If the event is to be published by an EEM policy, the sub-system-id reserved for a customer policy is 798.
type
Specifies the value of an event type within the specified event.
event-type
Event type value. Number in the range from 1 to 4294967295.
arg1
Specifies that argument data is to be passed to the application-specific event when the event is published.
argument-data
Character text, an environment variable, or a combination of the two. Optional when used with the arg2, arg3, or arg4 keywords.
arg2 arg3 arg4
(Optional) Specifies that argument data is to be passed to the application-specific event when the event is published.
Command History
Release
Modification
12.2(25)S
This command was introduced.
12.3(14)T
This command was integrated into Cisco IOS Release 12.3(14)T.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
Examples
The following example shows how a policy named EventPublish_A runs every 20 seconds and publishes an event to a well-known EEM event type numbered 1. A second policy named EventPublish_B is registered to run when the well-known EEM event type of 1 occurs. When policy EventPublish_B runs, it outputs a message to syslog containing the argument 1 argument data passed from EventPublish_A.
Router(config)# event manager applet EventPublish_A Router(config-applet)# event timer watchdog time 20.0 Router(config-applet)# action 1.0 syslog msg "Applet EventPublish_A" Router(config-applet)# action 2.0 publish-event sub-system 798 type 1 arg1 twenty Router(config-applet)# exit Router(config)# event manager applet EventPublish_B Router(config-applet)# event application sub-system 798 type 1 Router(config-applet)# action 1.0 syslog msg "Applet EventPublish_B arg1 $_application_data1"action puts
To enable the action of printing data directly to the local tty when an Embedded Event Manager (EEM) applet is triggered, use the action putscommand in applet configuration mode. To disable this function, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
nonewline
(Optional) Suppresses the display of the new line character.
string
Sequence of characters. If the string contains embedded blanks, enclose it in double quotation marks.
Usage Guidelines
The action puts command applies to synchronous events. The output of this command for a synchronous applet is directly displayed to the tty, bypassing the syslog. This command defaults to the syslog for asynchronous events. The nonewline keyword suppresses the display of the new line character. The output of the action puts command for an asynchronous applet is directed to the logger.
Examples
The following example shows how to print data directly to the local tty:
Router(config-applet)# event manager applet puts Router(config-applet)# event none Router(config-applet)# action 1 regexp "(.*) (.*) (.*)" "one two three" _match _sub1 Router(config-applet)# action 2 puts "match is $_match" Router(config-applet)# action 3 puts "submatch 1 is $_sub1" Router# event manager run puts match is one two three submatch 1 is one Router#action regexp
To match a regular expression pattern on an input string when an Embedded Event Manager (EEM) applet is triggered, use the action regexpcommand in applet configuration mode. To disable this function, use the no form of this command.
action label regexp string-pattern string-input [ string-match [string-submatch1] [string-submatch2] [string-submatch3] ]
no action label regexp
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
string-pattern
The sequence of characters to be used for regular expression pattern matching.
string-input
The sequence of characters to be used as input.
string-match
(Optional) The variable name to store the entire match.
string-submatch
(Optional) The variable name to store any submatches that are present. A maximum of three submatch strings can be specified.
Usage Guidelines
The string-pattern argument is a regular expression. If some part of the string matches the pattern, it returns 1; otherwise it returns 0. The optional string-match and string-submatch arguments store the results of the match.
The table below shows the built-in variable in which the results of the action regexpcommand are stored.
Examples
The following example shows how to define a regular expression match:
Router(config-applet)# event manager applet regexp Router(config-applet)# event none Router(config-applet)# action 1 regexp "(.*) (.*) (.*)" "one two three" _match _sub1 Router(config-applet)# action 2 puts "match is $_match" Router(config-applet)# action 3 puts "submatch 1 is $_sub1" Router# event manager run regexp match is one two three submatch 1 is one Router#action reload
To specify the action of reloading the Cisco IOS software when an Embedded Event Manager (EEM) applet is triggered, use the action reloadcommand in applet configuration mode. To remove the action of reloading the Cisco IOS software, use the no form of this command.
Command History
Release
Modification
12.0(26)S
This command was introduced.
12.3(4)T
This command was integrated into Cisco IOS Release 12.3(4)T.
12.3(2)XE
This command was integrated into Cisco IOS Release 12.3(2)XE.
12.2(25)S
This command was integrated into Cisco IOS Release 12.2(25)S.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
Usage Guidelines
Before configuring the action reload command, you should ensure that the device is configured to reboot the software version that you are expecting. Use the show startup-config command and look for any boot systemcommands.
Examples
The following example shows how to reload the Cisco IOS software when the memory-fail applet is triggered:
Router(config)# event manager applet memory-fail 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 Router(config-applet)# action 3.0 reloadRelated Commands
Command
Description
boot system
Configures the locations from which the router loads software when the router reboots.
event manager applet
Registers an event applet with the Embedded Event Manager and enters applet configuration mode.
show startup-config
Displays the configuration to be run when the router reboots.
action set (EEM)
To set the value of a variable when an Embedded Event Manager (EEM) applet is triggered, use the action setcommand in applet configuration mode. To remove the value of an EEM applet variable, use the no form of this command.
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
variable-name
Name assigned to the variable to be set.
variable-value
Value of the variable.
Usage Guidelines
Use the action set command to set the value of a variable when an EEM applet is triggered.
Examples
The following example shows how to set the value of a variable:
Router(config-applet)# event manager applet set Router(config-applet)# event none Router(config-applet)# action 1 set str “this is some text” Router(config-applet)# action 2 string range “$str” 0 6 Router(config-applet)# action 3 puts “$_string_result” Router# event manager run set “this is” Router#action snmp-object-value
To set the object ID and value to be returned by the Simple Network Management Protocol (SNMP) get request when an Embedded Event Manager (EEM) applet is triggered, use the action snmp-object-value command in applet configuration mode. To disable this function, use the no form of this command.
Syntax Description
Usage Guidelines
Use the action snmp-object-value command to set the object ID and value to be returned for the SNMP get request.
Examples
The following example shows how to set the object ID and value to be returned by the SNMP get request.
Router# configure terminal Router(config)# event manager applet action Router(config-applet)# event snmp-object oid 1.9.9.9.9 type gauge sync yes Router(config-applet)# action 1 syslog msg "oid = $_snmp_oid" Router(config-applet)# action 2 syslog msg "request = $_snmp_request" Router(config-applet)# action 3 syslog msg "request_type = $_snmp_request_type" Router(config-applet)# action 4 syslog msg "value = $_snmp_value" Router(config-applet)# action 5 snmp-object-value gauge 1111 next-oid 1.2.3.4 Router(config-applet)# action 6 exit 1action snmp-trap
To specify the action of generating a Simple Network Management Protocol (SNMP) trap when an Embedded Event Manager (EEM) applet is triggered, use the action snmp-trapcommand in applet configuration mode. To remove the action of generating an SNMP trap, use the no form of this command.
action label snmp-trap [ intdata1 integer ] [ intdata2 integer ] [ strdata string ]
no action label snmp-trap
Syntax Description
label
Unique identifier that can be any string value. Actions are sorted and run in ascending alphanumeric key sequence using the label as the sort key. If the string contains embedded blanks, enclose it in double quotation marks.
intdata1
(Optional) Specifies an integer to be sent in the SNMP trap message to the SNMP agent.
intdata2
(Optional) Specifies a second integer to be sent in the SNMP trap message to the SNMP agent.
integer
(Optional) Integer value.
strdata
(Optional) Specifies a string to be sent in the SNMP trap message to the SNMP agent.
string
(Optional) Sequence of up to 256 characters. If the string contains embedded blanks, enclose it in double quotation marks.
Command History
Release
Modification
12.2(25)S
This command was introduced.
12.3(14)T
This command was integrated into Cisco IOS Release 12.3(14)T.
12.2(28)SB
This command was integrated into Cisco IOS Release 12.2(28)SB.
12.2(18)SXF4
This command was integrated into Cisco IOS Release 12.2(18)SXF4 to support Software Modularity images only.
12.2(33)SRA
This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.2(18)SXF5
This command was integrated into Cisco IOS Release 12.2(18)SXF5.
Usage Guidelines
Before configuring this command, you must enable the snmp-server enable traps event-manager command 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.
This command generates an asynchronous message that is sent from the Cisco IOS device to the SNMP agent. The SNMP agent can be coded to understand customized data such as the optional integer and string data that can be sent in the SNMP trap message.
The SNMP trap that is generated uses the EEM MIB, CISCO-EMBEDDED-EVENT-MGR-MIB.my. Details about the MIB can be found using Cisco MIB Locator at the following URL:
Examples
The following example shows an EEM applet called IPSLAping1 being registered to run when there is an exact match on the value of a specified SNMP object ID that represents a successful IP SLA ICMP echo operation (this is equivalent to a ping command). Four actions are triggered when the echo operation fails, and event monitoring is disabled until after the second failure. A message that the ICMP echo operation to a server failed is sent to syslog, an SNMP trap is generated, EEM publishes an application-specific event, and a counter called IPSLA1F is incremented by a value of one.
Router(config)# event manager applet IPSLAping1 Router(config-applet)# event snmp 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 Router(config-applet)# action 1.0 syslog priority critical msg "Server IP echo failed: OID=$_snmp_oid_val" Router(config-applet)# action 1.1 snmp-trap strdata "EEM detected server reachability failure to 10.1.88.9" Router(config-applet)# action 1.2 publish-event sub-system 88000101 type 1 arg1 10.1.88.9 arg2 IPSLAEcho arg3 fail Router(config-applet)# action 1.3 counter name _IPSLA1F value 1 op inc
