This example uses the sample policies to demonstrate how to use Embedded Event Manager policies. Proceed through the following sections to see how to use the sample policies:
EEM Sample Policy Descriptions
This configuration example features some of the sample EEM policies:
-
ap_perf_test_base_cpu.tcl--Is run to measure the the CPU performance of EEM policies.
-
no_perf_test_init.tcl--Is run to measure the CPU performance of EEM policies.
-
sl_intf_down.tcl--Is run when a configurable syslog message is logged. It executes up to two configurable CLI commands and e-mails the results.
-
tm_cli_cmd.tcl--Is run using a configurable CRON entry. It executes a configurable CLI command and e-mails the results.
-
tm_crash_reporter.tcl--Introduced in Cisco IOS Release 12.4(2)T, 12.2(31)SB3, and 12.2(33)SRB. Is run 5 seconds after it is registered and 5 seconds after the router boots up. When triggered, the script attempts to find the reload reason. If the reload reason was due to a crash, the policy searches for the related crashinfo file and sends this information to a URL location specified by the user in the environment variable _crash_reporter_url.
-
tm_fsys_usage.tcl--Introduced in Cisco IOS Release 12.2(18)SXF4 Cisco IOS Software Modularity images. This policy runs using a configurable CRON entry and monitors disk space usage. A syslog message is displayed if disk space usage crosses configurable thresholds.
Event Manager Environment Variables for the Sample Policies
Event manager environment variables are Tcl global variables that are defined external to the EEM policy before the policy is registered and run. The sample policies require three of the e-mail environment variables to be set (see EEM Event Detector Demo Examples for a list of the e-mail variables); only _email_cc is optional. Other required and optional variable settings are outlined in the following tables.
The table below describes the EEM environment variables that must be set before the ap_perf_test_base_cpu.tcl sample policy is run.
Table 9 |
Environment Variables Used in the ap_perf_test_base_cpu.tcl Policy |
Environment Variable |
Description |
Example |
_perf_iterations |
The number of iterations over which to run the measurement. |
100 |
_perf_cmd1 |
The first non interactive CLI command that is executed as part of the measurement test. This variable is optional and need not be specified. |
enable |
_perf_cmd2 |
The second non interactive CLI command that is as part of the measurement test. To use _perf_cmd2, _perf_cmd1 must be defined. This variable is optional and need not be specified. |
show version |
_perf_cmd3 |
The third non interactive CLI command that is as part of the measurement test. To use _perf_cmd3, _perf_cmd1 must be defined. This variable is optional and need not be specified. |
show interface counters protocol status |
The table below describes the EEM environment variables that must be set before the no_perf_test_init.tcl sample policy is run.
Table 10 |
Environment Variables Used in the no_perf_test_init.tcl Policy |
Environment Variable |
Description |
Example |
_perf_iterations |
The number of iterations over which to run the measurement. |
100 |
_perf_cmd1 |
The first non interactive CLI command that is executed as part of the measurement test. This variable is optional and need not be specified. |
enable |
_perf_cmd2 |
The second non interactive CLI command that is as part of the measurement test. To use _perf_cmd2, _perf_cmd1 must be defined. This variable is optional and need not be specified. |
show version |
_perf_cmd3 |
The third non interactive CLI command that is as part of the measurement test. To use _perf_cmd3, _perf_cmd1 must be defined. This variable is optional and need not be specified. |
show interface counters protocol status |
The table below describes the EEM environment variables that must be set before the sl_intf_down.tcl sample policy is run.
Table 11 |
Environment Variables Used in the sl_intf_down.tcl Policy |
Environment Variable |
Description |
Example |
_config_cmd1 |
The first configuration command that is executed. |
interface Ethernet1/0 |
_config_cmd2 |
The second configuration command that is executed. This variable is optional and need not be specified. |
no shutdown |
_syslog_pattern |
A regular expression pattern match string that is used to compare syslog messages to determine when the policy runs. |
.*UPDOWN.*FastEthernet0/0.* |
The table below describes the EEM environment variables that must be set before the tm_cli_cmd.tcl sample policy is run.
Table 12 |
Environment Variables Used in the tm_cli_cmd.tcl Policy |
Environment Variable |
Description |
Example |
_cron_entry |
A CRON specification that determines when the policy will run. |
0-59/1 0-23/1 * * 0-7 |
_show_cmd |
The CLI command to be executed when the policy is run. |
show version |
The table below describes the EEM environment variables that must be set before the tm_crash_reporter.tcl sample policy is run.
Table 13 |
Environment Variables Used in the tm_crash_reporter.tcl Policy |
Environment Variable |
Description |
Example |
_crash_reporter_debug |
A value that identifies whether debug information for tm_crash_reporter.tcl will be enabled. This variable is optional and need not be specified. |
1 |
_crash_reporter_url |
The URL location to which the crash report is sent. |
http://www.example.com/fm/interface_tm.cgi |
The table below describes the EEM environment variables that must be set before the tm_fsys_usage.tcl sample policy is run.
Table 14 |
Environment Variables Used in the tm_fsys_usage.tcl Policy |
Environment Variable |
Description |
Example |
_tm_fsys_usage_cron |
A CRON specification that is used in the event_register Tcl command extension. If unspecified, the tm_fsys_usage.tcl policy is triggered once per minute. This variable is optional and need not be specified. |
0-59/1 0-23/1 * * 0-7 |
_tm_fsys_usage_debug |
When this variable is set to a value of 1, disk usage information is displayed for all entries in the system. This variable is optional and need not be specified. |
1 |
_tm_fsys_usage_ freebytes |
Free byte threshold for systems or specific prefixes. If free space falls below a given value, a warning is displayed. This variable is optional and need not be specified. |
disk2:98000000 |
_tm_fsys_usage_percent |
Disk usage percentage thresholds for systems or specific prefixes. If the disk usage percentage exceeds a given percentage, a warning is displayed. If unspecified, the default disk usage percentage is 80 percent for all systems. This variable is optional and need not be specified. |
nvram:25 disk2:5 |
Registration of Some EEM Policies
Some EEM policies must be unregistered and then reregistered if an EEM environment variable is modified after the policy is registered. The event_register_xxx statement that appears at the start of the policy contains some of the EEM environment variables, and this statement is used to establish the conditions under which the policy is run. If the environment variables are modified after the policy has been registered, the conditions may become invalid. To avoid any errors, the policy must be unregistered and then reregistered. The following variables are affected:
-
_cron_entry in the tm_cli_cmd.tcl policy
-
_syslog_pattern in the sl_intf_down.tcl policy
Basic Configuration Details for All Sample Policies
To allow e-mail to be sent from the Embedded Event Manager, the hostname and ip domain-name commands must be configured. The EEM environment variables must also be set. After a Cisco IOS image has been booted, use the following initial configuration, substituting appropriate values for your network. The environment variables for the tm_fsys_usage sample policy (see the table above) are all optional and are not listed here:
hostname cpu
ip domain-name example.com
event manager environment _email_server ms.example.net
event manager environment _email_to username@example.net
event manager environment _email_from engineer@example.net
event manager environment _email_cc projectgroup@example.net
event manager environment _cron_entry 0-59/2 0-23/1 * * 0-7
event manager environment _show_cmd show event manager policy registered
event manager environment _syslog_pattern .*UPDOWN.*FastEthernet0/0
event manager environment _config_cmd1 interface Ethernet1/0
event manager environment _config_cmd2 no shutdown
event manager environment _crash_reporter_debug 1
event manager environment _crash_reporter_url
http://www.example.com/fm/interface_tm.cgi
end
Using the Sample Policies
This section contains the following configuration scenarios to demonstrate how to use the some sample Tcl policies:
Running the Mandatory.go_*.tcl Sample Policy
There are GOLD TCL scripts for each test which runs as a part of GOLD EEM Policy. You can modify the TCL script for the test, specify the consecutive failure count, and also change the default corrective action. For example, one could chose to power down a linecard card, instead of reset or other CLI based actions.
For each registered test, a default TCL script is available, which can be registered with the system, and matches with the default action. This can be then overridden by modifying these scripts.
The following table shows a list of the mandatory polices that GOLD installed into EEM. Each of the policies performs some sort of action such as resetting the card or disabling the port.
GOLD Tcl Scripts |
Test |
Mandatory.go_asicsync.tcl |
TestAsicSync |
Mandatory.go_bootup.tcl |
Common for all bootup tests. |
Mandatory.go_fabric.tcl |
TestFabricHealth |
Mandatory.go_fabrich0.tcl |
TestFabricCh0Health |
Mandatory.go_fabrich1.tcl |
TestFabricCh1Health |
Mandatory.go_ipsec.tcl |
TestIPSecEncrypDecrypPkt |
Mandatory.go_mac.tcl |
TestMacNotification |
Mandatory.go_nondislp.tcl |
TestNonDisruptiveLoopback |
Mandatory.go_scratchreg.tcl |
TestScratchRegister |
Mandatory.go_sprping.tcl |
TestSPRPInbandPing |
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode, where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the mandatory.go_*.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command again to verify that the policy has been registered.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy Mandatory.go_spuriousisr.tcl
end
show event manager policy registered
show event manager environment
Running the ap_perf_test_base_cpu.tcl and no_perf_test_init.tcl Sample Policies
These sample policies measures the CPU performance of EEM policies. The policies help find the average execution time of each EEM policy and uses the CLI library to execute the configuration commands specified in the EEM environment variables _perf_cmd1 and, optionally, _perf_cmd2 and _perf_cmd3.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode, where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, enter the service timestamps debug datetime msec command and then you can register the ap_perf_test_base_cpu.tcl and no_perf_test_init.tcl policies with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command again to verify that the policy has been registered.
The policies ap_perf_test_base_cpu.tcl and no_perf_test_init.tcl need to be registered together, as they run as a test suite. You can run the no_perf_test_init.tcl policy to start the tests. Analyze the results using the syslog messages from each iteration. The total number of iteration is specified by the variable _perf_iterations. Take the time difference and divide it by the total number of iterations to get the average execution time of each EEM policy.
enable
show event manager policy registered
show event manager policy available
show event manager environment
configure terminal
service timestamps debug datetime msec
event manager environment _perf_iterations 100
event manager policy ap_perf_test_base_cpu.tcl
event manager policy no_perf_test_init.tcl
end
show event manager policy registered
show event manager policy available
show event manager environment
event manager run no_perf_test_init.tcl
Running the no_perf_test_init.tcl Sample Policy
This sample policy measures the the cpu performance of EEM policies. The policy helps to find the average execution time of each EEM policy and uses the CLI library to execute the configuration commands specified in the EEM environment variables _perf_cmd1 and, optionally, _perf_cmd2 and _perf_cmd3.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode, where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the no_perf_test_init.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command again to verify that the policy has been registered.
Analyze the results using the syslog messages from each iteration. The total number of iteration is specified by the variable _perf_iterations. Take the time difference and divide it by the total number of iterations to get the average execution time of each EEM policy.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy no_perf_test_init.tcl
end
show event manager policy registered
show event manager environment
Running the sl_intf_down.tcl Sample Policy
This sample policy demonstrates the ability to modify the configuration when a syslog message with a specific pattern is logged. The policy gathers detailed information about the event and uses the CLI library to execute the configuration commands specified in the EEM environment variables _config_cmd1 and, optionally, _config_cmd2. An e-mail message is sent with the results of the CLI command.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode, where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the sl_intf_down.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command again to verify that the policy has been registered.
The policy runs when an interface goes down. Enter the show event manager environment command to display the current environment variable values. Unplug the cable (or configure a shutdown) for the interface specified in the _syslog_pattern EEM environment variable. The interface goes down, prompting the syslog daemon to log a syslog message about the interface being down, and the syslog event detector is called.
The syslog event detector reviews the outstanding event specifications and finds a match for interface status change. The EEM server is notified, and the server runs the policy that is registered to handle this event--sl_intf_down.tcl.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy sl_intf_down.tcl
end
show event manager policy registered
show event manager environment
Running the tm_cli_cmd.tcl Sample Policy
This sample policy demonstrates the ability to periodically execute a CLI command and to e-mail the results. The CRON specification “0-59/2 0-23/1 * * 0-7” causes this policy to be run on the second minute of each hour. The policy gathers detailed information about the event and uses the CLI library to execute the configuration commands specified in the EEM environment variable _show_cmd. An e-mail message is sent with the results of the CLI command.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the tm_cli_cmd.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command to verify that the policy has been registered.
The timer event detector triggers an event for this case periodically according to the CRON string set in the EEM environment variable _cron_entry. The EEM server is notified, and the server runs the policy that is registered to handle this event--tm_cli_cmd.tcl.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy tm_cli_cmd.tcl
end
show event manager policy registered
Running the tm_crash_reporter.tcl Sample Policy
This sample policy demonstrates the ability to send an HTTP-formatted crash report to a URL location. If the policy registration is saved in the startup configuration file, the policy is triggered 5 seconds after bootup. When triggered, the script attempts to find the reload reason. If the reload reason was due to a crash, the policy searches for the related crashinfo file and sends this information to a URL location specified by the user in the environment variable _crash_reporter_url. A CGI script, interface_tm.cgi, has been created to receive the URL from the tm_crash_reporter.tcl policy and save the crash information in a local database on the target URL machine.
A Perl CGI script, interface_tm.cgi, has been created and is designed to run on a machine that contains an HTTP server and is accessible by the router that runs the tm_crash_reporter.tcl policy. The interface_tm.cgi script parses the data passed into it from tm_crash_reporter.tcl and appends the crash information to a text file, creating a history of all crashes in the system. Additionally, detailed information on each crash is stored in three files in a crash database directory that is specified by the user. Another Perl CGI script, crash_report_display.cgi, has been created to display the information stored in the database created by the interface_tm.cgi script. The crash_report_display.cgi script should be placed on the same machine that contains interface_tm.cgi. The machine should be running a web browser such as Internet Explorer or Netscape. When the crash_report_display.cgi script is run, it displays the crash information in a readable format.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the tm_crash_reporter.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command to verify that the policy has been registered.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy tm_crash_reporter.tcl
end
show event manager policy registered
Running the tm_fsys_usage.tcl Sample Policy
This sample policy demonstrates the ability to periodically monitor disk space usage and report through syslog when configurable thresholds have been crossed.
The following sample configuration demonstrates how to use this policy. Starting in user EXEC mode, enter the enable command at the router prompt. The router enters privileged EXEC mode, where you can enter the show event manager policy registered command to verify that no policies are currently registered. The next command is the show event manager policy available command to display which policies are available to be installed. After you enter the configure terminal command to reach global configuration mode, you can register the tm_fsys_usage.tcl policy with EEM using the event manager policy command. Exit from global configuration mode and enter the show event manager policy registered command again to verify that the policy has been registered. If you had configured any of the optional environment variables that are used in the tm_fsys_usage.tcl policy, the show event manager environment command displays the configured variables.
enable
show event manager policy registered
show event manager policy available
configure terminal
event manager policy tm_fsys_usage.tcl
end
show event manager policy registered
show event manager environment