Prerequisites for the EEM Python Module
Guest Shell must be working within the container. Guest Shell is not enabled by default. For more information see the Guest Shell feature.
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.
Embedded Event Manager (EEM) policies support Python scripts. Python scripts can be executed as part of EEM actions in EEM applets.
Guest Shell must be working within the container. Guest Shell is not enabled by default. For more information see the Guest Shell feature.
Information About EEM Python Module
Embedded Event Manager (EEM) policies support Python scripts. You can register Python scripts as EEM policies, and execute the registered Python scripts when a corresponding event occurs. The EEM Python script has the same event specification syntax as the EEM TCL policy.
Configured EEM policies run within the Guest Shell. Guest Shell is a virtualized Linux-based environment, designed to run custom Linux applications, including Python for automated control and management of Cisco devices. The Guest Shell container provides a Python interpreter.
The EEM Python package can be imported to Python scripts for running EEM-specific extensions.
Note |
The EEM Python package is available only within the EEM Python script (The package can be registered with EEM, and has the EEM event specification in the first line of the script.) and not in the standard Python script (which is run using the Python script name). |
The Python package includes the following application programming interfaces (APIs):
Action APIs—Perform EEM actions and have default parameters.
CLI-execution APIs—Run IOS commands, and return the output. The following are the list of CLI-execution APIs:
eem_cli_open()
eem_cli_exec()
eem_cli_read()
eem_cli_read_line()
eem_cli_run()
eem_cli_run_interactive()
eem_cli_read_pattern()
eem_cli_write()
eem_cli_close()
Environment variables-accessing APIs—Get the list of built-in or user-defined variables. The following are the environment variables-accessing APIs:
eem_event_reqinfo ()-Returns the built-in variables list.
eem_user_variables()-Returns the current value of an argument.
The Python package (is available only within the EEM script, and not available for the standard Python script) supports the following EEM actions:
Syslog message printing
Send SNMP traps
Reload the box
Switchover to the standby device
Run a policy
Track Object read
Track Object Set
Cisco Networking Services event generation
The EEM Python package exposes the interfaces for executing EEM actions. You can use the Python script to call these actions, and they are forwarded from the Python package via Cisco Plug N Play (PnP) to the action handler.
An EEM policy can have the following types of variables:
Event-specific built-in variables—A set of predefinied variables that are populated with details about the event that triggered the policy. The eem_event_reqinfo () API returns the builtin variables list. These variables can be stored in the local machine and used as local variables. Changes to local variables do not reflect in builtin variables.
User-defined variables—Variables that can be defined and used in policies. The value of these variables can be referred in the Python script. While executing the script, ensure that the latest value of the variable is available. The eem_user_variables() API returns the current value of the argument that is provided in the API.
The following CLI library commands are available within EEM for the Python script to work:
eem_cli_close()—Closes the EXEC process and releases the VTY and the specified channel handler connected to the command.
eem_cli_exec—Writes the command to the specified channel handler to execute the command. Then reads the output of the command from the channel and returns the output.
eem_cli_open—Allocates a VTY, creates an EXEC CLI session, and connects the VTY to a channel handler. Returns an array including the channel handler.
eem_cli_read()—Reads the command output from the specified CLI channel handler until the pattern of the device prompt occurs in the contents read. Returns all the contents read up to the match.
eem_cli_read_line()—Reads one line of the command output from the specified CLI channel handler. Returns the line read.
eem_cli_read_pattern()—Reads the command output from the specified CLI channel handler until the pattern that is to be matched occurs in the contents read. Returns all the contents read up to the match.
eem_cli_run()—Iterates over the items in the clist and assumes that each one is a command to be executed in the enable mode. On success, returns the output of all executed commands and on failure, returns error.
eem_cli_run_interactive()—Provides a sublist to the clist which has three items. On success, returns the output of all executed commands and on failure, returns the error. Also uses arrays when possible as a way of making things easier to read later by keeping expect and reply separated.
eem_cli_write()—Writes the command that is to be executed to the specified CLI channel handler. The CLI channel handler executes the command.
For the Python script to work, you must enable the Guest Shell. For more information, see the Guest Shell chapter.
Command or Action | Purpose | |||
---|---|---|---|---|
Step 1 |
enable Example:
|
Enables privileged EXEC mode.
|
||
Step 2 |
configure terminal Example:
|
Enters global configuration mode. |
||
Step 3 |
event manager directory user policy path Example:
|
Specifies a directory to use for storing user library files or user-defined EEM policies.
|
||
Step 4 |
event manager policy policy-filename Example:
|
Registers a policy with EEM.
|
||
Step 5 |
exit Example:
|
Exits global configuration mode and returns to privileged EXEC mode. |
||
Step 6 |
show event manager policy registered Example:
|
Displays the registered EEM policies. |
||
Step 7 |
show event manager history events Example:
|
Displays EEM events that have been triggered. |
Device# show event manager policy registered
No. Class Type Event Type Trap Time Registered Name
1 script user multiple Off Tue Aug 2 22:12:15 2016 multi_1.py
1: syslog: pattern {COUNTER}
2: none: policyname {multi_1.py} sync {yes}
trigger delay 10.000
correlate event 1 or event 2
attribute tag 1 occurs 1
nice 0 queue-priority normal maxrun 100.000 scheduler rp_primary Secu none
2 script user multiple Off Tue Aug 2 22:12:20 2016 multi_2.py
1: syslog: pattern {COUNTER}
2: none: policyname {multi_2.py} sync {yes}
trigger
correlate event 1 or event 2
nice 0 queue-priority normal maxrun 100.000 scheduler rp_primary Secu none
3 script user multiple Off Tue Aug 2 22:13:31 2016 multi.tcl
1: syslog: pattern {COUNTER}
2: none: policyname {multi.tcl} sync {yes}
trigger
correlate event 1 or event 2
attribute tag 1 occurs 1
nice 0 queue-priority normal maxrun 100.000 scheduler rp_primary Secu none
An EEM applet can include a Python script with an action command. In this example, an user is trying to run a standard Python script as part of the EEM action, however; EEM Python package is not available in the standard Python script. The standard Python script in IOS has a package named from cli import cli,clip and this package can be used to execute IOS commands.
import sys
from cli import cli,clip,execute,executep,configure,configurep
intf= sys.argv[1:]
intf = ''.join(intf[0])
print ('This script is going to unshut interface %s and then print show ip interface brief'%intf)
if intf == 'loopback55':
configurep(["interface loopback55","no shutdown","end"])
else :
cmd='int %s,no shut ,end' % intf
configurep(cmd.split(','))
executep('show ip interface brief')
This following is sample output from the guestshell run python command.
Device# guestshell run python /flash/eem_script.py loop55
This script is going to unshut interface loop55 and then print show ip interface brief
Line 1 SUCCESS: int loop55
Line 2 SUCCESS: no shut
Line 3 SUCCESS: end
Interface IP-Address OK? Method Status Protocol
Vlan1 unassigned YES NVRAM administratively down down
GigabitEthernet0/0 5.30.15.37 YES NVRAM up up
GigabitEthernet1/0/1 unassigned YES unset down down
GigabitEthernet1/0/2 unassigned YES unset down down
GigabitEthernet1/0/3 unassigned YES unset down down
GigabitEthernet1/0/4 unassigned YES unset up up
GigabitEthernet1/0/5 unassigned YES unset down down
GigabitEthernet1/0/6 unassigned YES unset down down
GigabitEthernet1/0/7 unassigned YES unset down down
GigabitEthernet1/0/8 unassigned YES unset down down
GigabitEthernet1/0/9 unassigned YES unset down down
GigabitEthernet1/0/10 unassigned YES unset down down
GigabitEthernet1/0/11 unassigned YES unset down down
GigabitEthernet1/0/12 unassigned YES unset down down
GigabitEthernet1/0/13 unassigned YES unset down down
GigabitEthernet1/0/14 unassigned YES unset down down
GigabitEthernet1/0/15 unassigned YES unset down down
GigabitEthernet1/0/16 unassigned YES unset down down
GigabitEthernet1/0/17 unassigned YES unset down down
GigabitEthernet1/0/18 unassigned YES unset down down
GigabitEthernet1/0/19 unassigned YES unset down down
GigabitEthernet1/0/20 unassigned YES unset down down
GigabitEthernet1/0/21 unassigned YES unset down down
GigabitEthernet1/0/22 unassigned YES unset down down
GigabitEthernet1/0/23 unassigned YES unset up up
GigabitEthernet1/0/24 unassigned YES unset down down
GigabitEthernet1/1/1 unassigned YES unset down down
GigabitEthernet1/1/2 unassigned YES unset down down
GigabitEthernet1/1/3 unassigned YES unset down down
GigabitEthernet1/1/4 unassigned YES unset down down
Te1/1/1 unassigned YES unset down down
Te1/1/2 unassigned YES unset down down
Te1/1/3 unassigned YES unset down down
Te1/1/4 unassigned YES unset down down
Loopback55 10.55.55.55 YES manual up up
Device#
Jun 7 12:51:20.549: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback55,
changed state to up
Jun 7 12:51:20.549: %LINK-3-UPDOWN: Interface Loopback55, changed state to up
The following is a sample script for printing messages to the syslog. This script must be stored in a file, copied to the file system on the device, and registered using the event manager policy file.
::cisco::eem::event_register_syslog tag "1" pattern COUNTER maxrun 200
import eem
import time
eem.action_syslog("SAMPLE SYSLOG MESSAGE","6","TEST")
The following is sample script to print EEM environment variables. This script must be stored in a file, copied to the file system on the device, and registered using the event manager policy file.
::cisco::eem::event_register_syslog tag "1" pattern COUNTER maxrun 200
import eem
import time
c = eem.env_reqinfo()
print "EEM Environment Variables"
for k,v in c.iteritems():
print "KEY : " + k + str(" ---> ") + v
print "Built in Variables"
for i,j in a.iteritems() :
print "KEY : " + i + str(" ---> ") + j
Command or Action | Purpose | |
---|---|---|
Step 1 |
enable Example:
|
Enables privileged EXEC mode.
|
Step 2 |
configure terminal Example:
|
Enters global configuration mode. |
Step 3 |
event manager applet applet-name Example:
|
Registers an applet with the Embedded Event Manager (EEM) and enters applet configuration mode. |
Step 4 |
event [tag event-tag] syslog pattern regular-expression Example:
|
Specifies a regular expression to perform the syslog message pattern match. |
Step 5 |
action label cli command cli-string Example:
|
Specifies the IOS command to be executed when an EEM applet is triggered. |
Step 6 |
action label cli command cli-string [ pattern pattern-string ] Example:
|
Specifies the action to be specified with the pattern keyword.
|
Step 7 |
end Example:
|
Exits applet configuration mode and returns to privileged EXEC mode. |
Step 8 |
show event manager policy active Example:
|
Displays EEM policies that are executing. |
Step 9 |
show event manager history events Example:
|
Displays the EEM events that have been triggered. |
Device(config)# interface loopback 55
Device(config-if)# shutdown
Device(config-if)# end
Device#
Mar 13 10:53:22.358 EDT: %SYS-5-CONFIG_I: Configured from console by console
Mar 13 10:53:24.156 EDT: %LINK-5-CHANGED: Line protocol on Interface Loopback55, changed state to down
Mar 13 10:53:27.319 EDT: %LINK-3-UPDOWN: Interface Loopback55, changed state to administratively down
Enter configuration commands, one per line. End with CNTL/Z.
Mar 13 10:53:35.38 EDT: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback55, changed state to up
*Mar 13 10:53:35.39 EDT %LINK-3-UPDOWN: Interface Loopback55, changed state to up
+++ 10:54:33 edi37(default) exec +++
show ip interface br
Interface IP-Address OK? Method Status Protocol
GigabitEthernet0/0/0 unassigned YES unset down down
GigabitEthernet0/0/1 unassigned YES unset down down
GigabitEthernet0/0/2 10.1.1.31 YES DHCP up up
GigabitEthernet0/0/3 unassigned YES unset down down
GigabitEthernet0 192.0.2.1 YES manual up up
Loopback55 198.51.100.1 YES manual up up
Loopback66 172.16.0.1 YES manual up up
Loopback77 192.168.0.1 YES manual up up
Loopback88 203.0.113.1 YES manual up up
Related Topic | Document Title |
---|---|
EEM configuration |
|
EEM commands |
|
Guest Shell configuration |
Description | Link |
---|---|
The Cisco Support website provides extensive online resources, including documentation and tools for troubleshooting and resolving technical issues with Cisco products and technologies. To receive security and technical information about your products, you can subscribe to various services, such as the Product Alert Tool (accessed from Field Notices), the Cisco Technical Services Newsletter, and Really Simple Syndication (RSS) Feeds. Access to most tools on the Cisco Support website requires a Cisco.com user ID and password. |
The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Feature Name |
Release |
Feature Information |
---|---|---|
EEM Python Module |
Cisco IOS XE Everest 16.5.1a Cisco IOS XE Everest 16.5.1b |
This feature supports Python scripts as EEM policies. No new commands were introduced. In Cisco IOS XE Everest 16.5.1a, this feature was implemented on the following platforms:
In Cisco IOS XE Everest 16.5.1b, this feature was implemented on the following platforms:
|
Cisco IOS XE Everest 16.6.2 |
In Cisco IOS XE Everest 16.6.2, this feature was implemented on Cisco Catalyst 9400 Series Switches. |