Usage Guidelines

Cisco IOS XR software supports only the policy files that are created by using the Tool Command Language (TCL) scripting language. The TCL software is provided in the Cisco IOS XR software image when the EEM is installed on the network device. Files with the .tcl extension can be EEM policies, TCL library files, or a special TCL library index file named tclindex. The tclindex file contains a list of user function names and library files that contain the user functions (procedures). The EEM searches the user library directory when the TCL starts to process the tclindex file.

User Library

A user library directory is needed to store user library files associated with authoring EEM policies. If you do not plan to write EEM policies, you do not have to create a user library directory.

To create user library directory before identifying it to the EEM, use the mkdir command in XR EXEC mode. After creating the user library directory, use the copy command to copy the .tcl library files into the user library directory.

User Policy

A user policy directory is essential to store the user-defined policy files. If you do not plan to write EEM policies, you do not have to create a user policy directory. The EEM searches the user policy directory when you enter the event manager policy policy-name user command.

To create a user policy directory before identifying it to the EEM, use the mkdir command in XR EXEC mode. After creating the user policy directory, use the copy command to copy the policy files into the user policy directory.

Usage Guidelines

Environment variables are available to EEM policies when you set the variables using the event manager environment command. They become unavailable when you remove them with the no form of this command.

By convention, the names of all the environment variables defined by Cisco begin with an underscore character (_) to set them apart, for example, _show_cmd.

Spaces can be used in the var-value argument. This command interprets everything after the var-name argument uptil the end of the line in order to be a part of the var-value argument.

Use the event manager environment command to display the name and value of all EEM environment variables before and after they have been set using the event manager environment command.

Usage Guidelines

The EEM schedules and runs policies on the basis of an event specification that is contained within the policy itself. When the event manager policy command is invoked, the EEM examines the policy and registers it to be run when the specified event occurs. An EEM script is available to be scheduled by the EEM until the no form of this command is entered.

Note

AAA authorization (such as the aaa authorization command with the eventmanager and default keywords) must be configured before the EEM policies can be registered. The eventmanager and default keywords must be configured for policy registration. See the Configuring AAA Services module of System Security Configuration Guide for Cisco NCS 5000 Series Routers for more information on AAA authorization configuration.

Username

Enter the username that should execute the script with the username username keyword and argument. This name can be different from the user who is currently logged in, but the registering user must have permissions that are a superset of the username that runs the script. Otherwise, the script will not be registered, and the command will be rejected. In addition, the username that runs the script must have access privileges to the commands issued by the EEM policy being registered.

Persist-time

When a script is first registered, the configured username for the script is authenticated. If authentication fails, or if the AAA server is down, the script registration fails.

After the script is registered, the username is authenticated each time a script is run.

If the AAA server is down, the username authentication can be read from memory. The persist-time determines the number of seconds this username authentication is held in memory.

• If the AAA server is down and the persist-time has not expired, the username is authenticated from memory, and the script runs.
• If the AAA server is down, and the persist-time has expired, user authentication fails, and the script does not run.

Note	EEM attempts to contact the AAA server and refresh the username reauthenticate whenever the configured refresh-time expires. See the event manager refresh-time command for more information.

These values can be used for the persist-time:

• The default persist-time is 3600 seconds (1 hour). Enter the event manager policy command without the persist-time keyword to set the persist-time to 1 hour.
• Enter zero to stop the username authentication from being cached. If the AAA server is down, the username is not authenticated and the script does not run.
• Enter infinite to stop the username from being marked as invalid. The username authentication held in the cache will not expire. If the AAA server is down, the username is authenticated from the cache.

Type

If you enter the event manager policy command without specifying the type keyword, the EEM first tries to locate the specified policy file in the system policy directory. If the EEM finds the file in the system policy directory, it registers the policy as a system policy. If the EEM does not find the specified policy file in the system policy directory, it looks in the user policy directory. If the EEM locates the specified file in the user policy directory, it registers the policy file as a user policy. If the EEM finds policy files with the same name in both the system policy directory and the user policy directory, the policy file in the system policy directory takes precedence, and the policy file is registered as a system policy.

Usage Guidelines

EEM attempts to contact the AAA server and refresh the username reauthentication whenever the configured refresh-time expires.

Usage Guidelines

EEM usually schedules and runs policies on the basis of an event specification that is contained within the policy itself. The event manager run command allows policies to be run manually.

You can query the arguments in the policy file by using the TCL command event_reqinfo , as shown in this example:

 array set arr_einfo [event_reqinfo] set argc $arr_einfo(argc) set arg1
            $arr_einfo(arg1) 

Use the event manager run command to register the policy before using the event manager run command to run the policy. The policy can be registered with none as the event type.

Usage Guidelines

Use the event manager scheduler suspend command to suspend all the policy scheduling requests, and do not perform scheduling until you enter the no form of this command. The no form of this command resumes policy scheduling and runs pending policies, if any.

It is recommended that you suspend policy execution immediately instead of unregistering policies one by one, for the following reasons:

• Security—If you suspect that the security of your system has been compromised.
• Performance—If you want to suspend policy execution temporarily to make more CPU cycles available for other functions.

Usage Guidelines

Use the show event manager directory user command to display the current value of the EEM user library or policy directory.

Usage Guidelines

Use the show event manager environment command to display the names and values of the EEM environment variables.

Usage Guidelines

No specific guidelines impact the use of this command.

Usage Guidelines

The system maintains a record of when processes start and end. This data is used as the basis for reliability analysis.

Use the show event manager metric process command to obtain availability information for a process or group of processes. A process is considered available when it is running.

Usage Guidelines

Use the show event manager policy available command to find out what policies are available to be registered just prior to using the event manager policy command to register policies.

This command is also useful if you forget the exact name of a policy that is required for the event manager policy command.

Usage Guidelines

The output of the show event manager policy registered command is most beneficial if you are writing and monitoring the EEM policies. The output displays registered policy information in two parts. The first line in each policy description lists the index number assigned to the policy, policy type (system or user), type of event registered, time at which the policy was registered, and name of the policy file. The remaining lines of each policy description display information about the registered event and how the event is to be handled, and come directly from the Tool Command Language (TCL) command arguments that make up the policy file.

Registered policy information is documented in the Cisco publication Writing Embedded Event Manager Policies Using Tcl .

Usage Guidelines

The output of the show event manager refresh-time command is the refresh time, in seconds.

Usage Guidelines

Use the show event manager statistics-table all command to display the output for all the statistics types.