Configuring and Managing Embedded Event Manager Policies

The
Cisco IOS XR Software
Embedded Event Manager (EEM) functions as the central clearing house for the
events detected by any portion of the
Cisco IOS XR Software
processor failover services. The EEM is responsible for detection of fault
events, fault recovery, and process reliability statistics in a
Cisco IOS XR Software
system. The EEM events are notifications that something significant has
occurred within the system, such as:

The EEM relies on
software agents or event detectors to notify it when certain system events
occur. When the EEM has detected an event, it can initiate corrective actions.
Actions are prescribed in routines called
policies.
Policies must be registered before an action can be applied to collected
events. No action occurs unless a policy is registered. A registered policy
informs the EEM about a particular event that is to be detected and the
corrective action to be taken if that event is detected. When such an event is
detected, the EEM enables the corresponding policy. You can disable a
registered policy at any time.

The EEM monitors the
reliability rates achieved by each process in the system, allowing the system
to detect the components that compromise the overall reliability or
availability.

This module describes
the new and revised tasks you need to configure and manage EEM policies on your
the Cisco IOS XR Software network
and write and customize the EEM policies using Tool Command Language
(Tcl) scripts to handle
Cisco IOS XR Software
faults and events.

Note

For complete
descriptions of the event management commands listed in this module, see the
Related Documents section of this module.

Feature History
for Configuring and Managing Embedded Event Manager Policies

You must be in a user group associated with a task group that
includes the proper task IDs. The command reference guides include the task IDs
required for each command. If you suspect user group assignment is preventing
you from using a command, contact your AAA administrator for assistance.

Event
Management

Embedded Event
Management (EEM) in the
Cisco IOS XR Software
system essentially involves system event management. An event can be any
significant occurrence (not limited to errors) that has happened within the
system. The
Cisco IOS XR Software
EEM detects those events and implements appropriate responses. The EEM can also
be used to prevent or contain faults and to assist in fault recovery.

The EEM enables a
system administrator to specify appropriate action based on the current state
of the system. For example, a system administrator can use EEM to request
notification by e-mail when a hardware device needs replacement.

The EEM also maintains
reliability metrics for each process in the system.

System Event Detection

The EEM interacts with routines, “event detectors,” that actively monitor the system for events. The EEM relies on an event detector that it has provided to syslog to detect that a certain system event has occurred. It uses a pattern match with the syslog messages. It also relies on a timer event detector to detect that a certain time and date has occurred.

Policy-Based Event Response

When the EEM has detected an event, it can initiate actions in response. These actions are contained in routines called policy handlers. While the data for event detection is collected, no action occurs unless a policy for responding to that event has been registered. At registration, a policy informs the EEM that it is looking for a particular event. When the EEM detects the event, it enables the policy.

Reliability Metrics

The EEM monitors the reliability rates achieved by each process in the system. These metrics can be used during testing to determine which components do not meet their reliability or availability goals so that corrective action can be taken.

A difference
exists between scripts with policy actions and scripts that subscribe to
receive events. Scripts with policy actions are expected to implement a policy.
They are bound by a rule to prevent recursion. Scripts that subscribe to
notifications are not bound by such a rule.

Records
reliability metric data for each process in the system.

Provides access to
EEM-maintained system information through an application program interface
(API).

Embedded Event Manager Management Policies

When the EEM has detected an event, it can initiate corrective actions. Actions are prescribed in routines called policies. Policies are defined by Tcl scripts (EEM scripts) written by the user through a Tcl API. (See the Embedded Event Manager Scripts and the Scripting Interface (Tcl).) Policies must be registered before any action can be applied to collected events. No action occurs unless a policy is registered. A registered policy informs the EEM about a particular event to detect and the corrective action to take if that event is detected. When such an event is detected, the EEM runs the policy. You can disable a registered policy at any time.

Embedded Event
Manager Scripts and the Scripting Interface (Tcl)

EEM scripts are used
to implement policies when an EEM event is published. EEM scripts and policies
are identified to the EEM using the
event manager
policy configuration command. An EEM script remains available to
be scheduled by the EEM until the
no event manager
policy command is entered.

The EEM uses these two
types of EEM scripts:

Regular EEM
scripts identified to the EEM through the
eem script CLI
command. Regular EEM scripts are standalone scripts that incorporate the
definition of the event they will handle.

EEM callback scripts
identified to the EEM when a process or EEM script registers to handle an
event. EEM callback scripts are essentially named functions that are identified
to the EEM through the C Language API.

Script
Language

The scripting language
is Tool Command Language (Tcl) as implemented within the
Cisco IOS XR Software. All Embedded Event Manager scripts
are written in Tcl. This full Tcl implementation has been extended by Cisco,
and an
eem command has
been added to provide the interface between Tcl scripts and the EEM.

Tcl is a string-based
command language that is interpreted at run time. The version of Tcl supported
is Tcl version 8.3.4, plus added script support. Scripts are defined using an
ASCII editor on another device, not on the networking device. The script is
then copied to the networking device and registered with EEM. Tcl scripts are
supported by EEM. As an enforced rule, Embedded Event Manager policies are
short-lived, run-time routines that must be interpreted and executed in less
than 20 seconds of elapsed time. If more than 20 seconds of elapsed time are
required, the maxrun parameter may be specified in the event_register statement
to specify any desired value.

EEM policies use the
full range of the Tcl language's capabilities. However, Cisco provides
enhancements to the Tcl language in the form of Tcl command extensions that
facilitate the writing of EEM policies. The main categories of Tcl command
extensions identify the detected event, the subsequent action, utility
information, counter values, and system information.

EEM allows you to
write and implement your own policies using Tcl. Writing an EEM script
involves:

Selecting the
event Tcl command extension that establishes the criteria used to determine
when the policy is run.

Defining the event
detector options associated with detecting the event.

Choosing the
actions to implement recovery or respond to the detected event.

Regular Embedded Event Manager Scripts

Regular EEM scripts are used to implement policies when an EEM event is published. EEM
scripts are identified to the EEM using the event manager policy
configuration command. An EEM script remains available to be scheduled by the EEM until the
no event manager policy command is entered.

The first executable line of code within an EEM script must be the eem event
register keyword. This keyword identifies the EEM event for which that
script should be scheduled. The keyword is used by the event manager
policy configuration command to register to handle the specified EEM
event.

When an EEM script exits, it is responsible for setting a return code that is used to tell the EEM whether to run the default action for this EEM event (if any) or no other action. If multiple event handlers are scheduled for a given event, the return code from the previous handler is passed into the next handler, which can leave the value as is or update it.

Note

An EEM script cannot register to handle an event other than the event that caused it to be scheduled.

Embedded Event Manager Callback Scripts

EEM callback scripts are entered as a result of an EEM event being raised for a previously registered EEM event that specifies the name of this script in the eem_handler_spec.

When an EEM callback script exits, it is responsible for setting a return code that is used to tell the EEM whether or not to run the default action for this EEM event (if any). If multiple event handlers are scheduled for a given event, the return code from the previous handler is passed into the next handler, which can leave the value as is or update it.

Note

EEM callback scripts are free to use any of the EEM script services listed in Table 1, except for the eem event register keyword,
which is not allowed in an EEM callback script.

Embedded Event Manager Policy Tcl Command Extension Categories

This table
lists the different categories of EEM policy Tcl command extensions.

Note

The Tcl command extensions available in each of these categories for use in all EEM policies are described in later sections in this document.

These Tcl command extensions are represented by the
event_register_xxx family of event-specific
commands. There is a separate event information Tcl command extension in
this category as well: event_reqinfo. This is the
command used in policies to query the EEM for information about an event.
There is also an EEM event publish Tcl command extension
event_publish that publishes an
application-specific event.

EEM action Tcl command extensions

These Tcl command extensions (for example,
action_syslog) are used by policies to respond
to or recover from an event or fault. In addition to these extensions,
developers can use the Tcl language to implement any action desired.

EEM utility Tcl command extensions

These Tcl command extensions are used to retrieve, save, set, or modify application information, counters, or timers.

EEM system information Tcl command extensions

These Tcl command extensions are represented by the
sys_reqinfo_xxx family of system-specific
information commands. These commands are used by a policy to gather system
information.

EEM context Tcl command extensions

These Tcl command extensions are used to store and retrieve a Tcl context (the visible variables and their values).

Cisco File Naming
Convention for Embedded Event Manager

All EEM policy names,
policy support files (for example, e-mail template files), and library
filenames are consistent with the Cisco file-naming convention. In this regard,
EEM policy filenames adhere to the following specifications:

An optional
prefix—Mandatory.—indicating, if present, that this is a system policy that
should be registered automatically at boot time if it is not already
registered; for example, Mandatory.sl_text.tcl.

A filename body
part containing a two-character abbreviation (see table below) for the first
event specified; an underscore part; and a descriptive field part that further
identifies the policy.

A filename suffix
part defined as .tcl.

EEM e-mail template
files consist of a filename prefix of email_template, followed by an
abbreviation that identifies the usage of the e-mail template.

EEM library filenames
consist of a filename body part containing the descriptive field that
identifies the usage of the library, followed by _lib, and a filename suffix
part defined as .tcl.

Table 2 Two-Character
Abbreviation Specification

Two-Character
Abbreviation

Specification

ap

event_register_appl

ct

event_register_counter

st

event_register_stat

no

event_register_none

oi

event_register_oir

pr

event_register_process

rf

event_register_rf

sl

event_register_syslog

tm

event_register_timer

ts

event_register_timer_subscriber

wd

event_register_wdsysmon

Embedded Event
Manager Built-in Actions

EEM built-in actions
can be requested from EEM handlers when the handlers run.

This table describes
each EEM handler request or action.

Table 3 Embedded Event
Manager Built-In Actions

Embedded Event
Manager Built-In Action

Description

Log a message
to syslog

Sends a
message to the syslog. Arguments to this action are priority and the message to
be logged.

Execute a CLI
command

Writes the
command to the specified channel handler to execute the command by using the
cli_exec
command extension.

Generate a
syslog message

Logs a message
by using the
action_syslog
Tcl command extension.

Manually run
an EEM policy

Runs an EEM
policy within a policy while the
event manager
run command is running a policy in
EXEC mode.

Publish an
application-specific event

Publishes an
application-specific event by using the
event_publish
appl Tcl command extension.

Reload the
Cisco IOS software

Causes a
router to be reloaded by using the EEM
action_reload
command.

Request system
information

Represents the
sys_reqinfo_xxx family of system-specific information commands by a policy to
gather system information.

Send a short
e-mail

Sends the
e-mail out using Simple Mail Transfer Protocol (SMTP).

Set or modify
a counter

Modifies a
counter value.

EEM handlers require
the ability to run CLI commands. A command is available to the Tcl shell to
allow execution of CLI commands from within Tcl scripts.

Application-specific
Embedded Event Management

Any
Cisco IOS XR Software
application can define and publish application-defined events.
Application-defined events are identified by a name that includes both the
component name and event name, to allow application developers to assign their
own event identifiers. Application-defined events can be raised by a
Cisco IOS XR Software
component even when there are no subscribers. In this case, the EEM dismisses
the event, which allows subscribers to receive application-defined events as
needed.

An EEM script that
subscribes to receive system events is processed in the following order:

The EEM scans the
EEM script looking for an
eem event
event_type keyword and subscribes the EEM script to be scheduled
for the specified event.

The Event Detector
detects an event and contacts the EEM.

The EEM schedules
event processing, causing the EEM script to be run.

The EEM script
routine returns.

Event Detection and
Recovery

Events are detected by
routines called event
detectors. Event detectors are separate programs that provide an interface
between other
Cisco IOS XR Software
components and the EEM. They process information that can be used to publish
events, if necessary.

These event detectors
are supported:

An EEM event is
defined as a notification that something significant has happened within the
system. Two categories of events exist:

System EEM events

Application-defined events

System EEM events are
built into the EEM and are grouped based on the fault detector that raises
them. They are identified by a symbolic identifier defined within the API.

Some EEM system events
are monitored by the EEM whether or not an application has requested
monitoring. These are called
built-in EEM
events. Other EEM events are monitored only if an application has requested EEM
event monitoring. EEM event monitoring is requested through an EEM application
API or the EEM scripting interface.

Some event detectors
can be distributed to other hardware cards within the same secure domain router
(SDR) or within the administration plane to provide support for distributed
components running on those cards.

General Flow of EEM Event Detection and Recovery

EEM is a flexible, policy-driven framework that supports in-box monitoring of different components of the system with the help of software agents known as event detectors. The relationship is between the EEM server, the core event publishers (event detectors), and the event subscribers (policies). Event publishers screen events and publish them when there is a match on an event specification that is provided by the event subscriber. Event detectors notify the EEM server when an event of interest occurs.

When an event or fault is detected, Embedded Event Manager determines from the event publishers—an example would be the OIR events publisher —if a registration for the encountered fault or event has occurred. EEM matches the event registration information with the event data itself. A policy registers for the detected event with the Tcl command extension event_register_xxx. The event information Tcl command extension event_reqinfo is used in the policy to query the Embedded Event Manager for information about the detected event.

System Manager Event
Detector

The System Manager
Event Detector has four roles:

Records process
reliability metric data.

Screens for
processes that have EEM event monitoring requests outstanding.

Publishes events
for those processes that match the screening criteria.

Asks the System
Manager to perform its default action for those events that do not match the
screening criteria.

The System Manager
Event Detector interfaces with the System Manager to receive process startup
and termination notifications. The interfacing is made through a private API
available to the System Manager. To minimize overhead, a portion of the API
resides within the System Manager process space. When a process terminates, the
System Manager invokes a helper process (if specified in the process.startup
file) before calling the Event Detector API.

Processes can be
identified by component ID, System Manager assigned job ID, or load module
pathname plus process instance ID.
POSIX
wildcard filename pattern support using *, ?, or [...] is provided for load
module pathnames. Process instance ID is an integer assigned to a process
to differentiate it from other processes with the same pathname. The first
instance of a process is assigned an instance ID value of 1, the second 2, and
so on.

The System Manager
Event Detector handles EEM event monitoring requests for the EEM events shown
in this table.

Table 4 System Manager
Event Detector Event Monitoring Requests

Embedded Event
Manager Event

Description

Normal process
termination EEM event—built in

Occurs when a
process matching the screening criteria terminates.

Abnormal
process termination EEM event—built in

Occurs when a
process matching the screening criteria terminates abnormally.

Process
startup EEM event—built in

Occurs when a
process matching the screening criteria starts.

When System Manager
Event Detector abnormal process termination events occur, the default action
restarts the process according to the built-in rules of the System Manager.

The relationship
between the EEM and System Manager is strictly through the private API provided
by the EEM to the System Manager for the purpose of receiving process start and
termination notifications. When the System Manager calls the API, reliability
metric data is collected and screening is performed for an EEM event match. If
a match occurs, a message is sent to the System Manager Event Detector. In the
case of abnormal process terminations, a return is made indicating that the EEM
handles process restart. If a match does not occur, a return is made indicating
that the System Manager should apply the default action.

Timer Services Event Detector

The Timer Services Event Detector implements time-related EEM events. These events are identified through user-defined identifiers so that multiple processes can await notification for the same EEM event.

The Timer Services Event Detector handles EEM event monitoring requests for the Date/Time Passed EEM event. This event occurs when the current date or time passes the specified date or time requested by an application.

Syslog Event
Detector

The syslog Event
Detector implements syslog message screening for syslog EEM events. This
routine interfaces with the syslog daemon through a private API. To minimize
overhead, a portion of the API resides within the syslog daemon process.

Screening is provided
for the message severity code or the message text fields.
POSIX
regular expression pattern support is provided for the message text field.

The Syslog Event
Detector handles EEM event monitoring requests for the events are shown in this
table.

Table 5 Syslog Event
Detector Event Monitoring Requests

Embedded Event
Manager Event

Description

Syslog message
EEM event

Occurs for a
just-logged message. It occurs when there is a match for either the syslog
message severity code or the syslog message text pattern. Both can be specified
when an application requests a syslog message EEM event.

Process event
manager EEM event—built in

Occurs when
the event-processed count for a specified process is either greater than or
equal to a specified maximum or is less than or equal to a specified minimum.

None Event Detector

The None Event
Detector publishes an event when the
Cisco IOS XR Softwareevent manager
run CLI command executes an EEM policy. EEM schedules and runs
policies on the basis of an event specification that is contained within the
policy itself. An EEM policy must be identified and registered to be permitted
to run manually before the
event manager
run command will execute.

Event manager none
detector provides user the ability to run a tcl script using the CLI. The
script is registered first before running.
Cisco IOS XR Software
version provides similar syntax with Cisco IOS EEM (refer to the applicable EEM
Documentation for details), so scripts written using Cisco IOS EEM is run on
Cisco IOS XR Software
with minimum change.

Two events may be
monitored at the same time, and the event publishing criteria can be specified
to require one event or both events to cross their specified thresholds.

The
Cisco IOS XR Software
Watchdog System Monitor Event Detector handles the events as shown in this
table.

Table 6 Watchdog System
Monitor Event Detector Requests

Embedded
Event Manager Event

Description

Process
percent CPU EEM event—built in

Occurs when
the CPU time for a specified process is either greater than or equal to a
specified maximum percentage of available CPU time or is less than or equal to
a specified minimum percentage of available CPU time.

Total
percent CPU EEM event—built in

Occurs when
the CPU time for a specified processor complex is either greater than or equal
to a specified maximum percentage of available CPU time or is less than or
equal to a specified minimum percentage of available CPU time.

Process
percent memory EEM event—built in

Occurs when
the memory used for a specified process has either increased or decreased by a
specified value.

Total
percent available Memory EEM event—built in

Occurs when
the available memory for a specified processor complex has either increased or
decreased by a specified value.

Total
percent used memory EEM event—built in

Occurs when
the used memory for a specified processor complex has either increased or
decreased by a specified value.

Distributed Event
Detectors

Cisco IOS XR Software
components that interface to EEM event detectors and that have substantially
independent implementations running on a distributed hardware card should have
a distributed EEM event detector. The distributed event detector permits
scheduling of EEM events for local processes without requiring that the local
hardware card to the EEM communication channel be active.

These event detectors
run on a
Cisco IOS XR Software
line card:

System Manager
Fault Detector

Wdsysmon Fault
Detector

Counter Event
Detector

OIR Event Detector

Statistic Event
Detector

Embedded Event Manager Event Scheduling and Notification

When an EEM handler is scheduled, it runs under the context of the process that creates the event request (or for EEM scripts under the Tcl shell process context). For events that occur for a process running an EEM handler, event scheduling is blocked until the handler exits. The defined default action (if any) is performed instead.

Hardware Card Reliability Metric Data

Reliability metric data is kept for each hardware card in a processor complex. Data is recorded in a table indexed by disk ID.

Data maintained by the hardware card is as follows:

Most recent start time

Most recent normal end time (controlled switchover)

Most recent abnormal end time (asynchronous switchover)

Most recent abnormal type

Cumulative available time

Cumulative unavailable time

Number of times hardware card started

Number of times hardware card shut down normally

Number of times hardware card shut down abnormally

Process Reliability Metric Data

Reliability metric data is kept for each process handled by the System Manager. This data includes standby processes running on either the primary or backup hardware card. Data is recorded in a table indexed by hardware card disk ID plus process pathname plus process instance for those processes that have multiple instances.

Process terminations include the following cases:

Normal termination—Process exits with an exit value equal to 0.

Abnormal termination by process—Process exits with an exit value not equal to 0.

Abnormal termination by QNX—Neutrino operating system aborts the process.

Cumulative process run time (the time when the process is actually running on the CPU)

Number of times started

Number of times ended normally

Number of times ended abnormally

Number of abnormal failures within the past 60 minutes

Number of abnormal failures within the past 24 hours

Number of abnormal failures within the past 30 days

How to Configure and
Manage Embedded Event Manager Policies

Configuring Environmental Variables

EEM environmental variables are Tcl global variables that are defined external to the policy before the policy is run. The EEM policy engine receives notifications when faults and other events occur. EEM policies implement recovery, based on the current state of the system and actions specified in the policy for a given event. Recovery actions are triggered when the policy is run.

Environment
Variables

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

Spaces may be used
in the
var-value
argument of the
event manager
environment command. The command interprets everything after the
var-name
argument to the end of the line to be part of the
var-value
argument.

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

Registering Embedded Event Manager Policies

Embedded Event
Manager Policies

Registering an EEM
policy is performed with the
event manager
policy command in
global
configuration mode. An EEM
script is available to be scheduled by the EEM until the
no form of this
command is entered. Prior to registering a policy, display EEM policies that
are available to be registered with the
show event manager policy
available command.

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.

Username

To register an EEM
policy, you must specify the username that is used to run the script. 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 will run
the script. Otherwise, the script is not registered and the command is
rejected. In addition, the username that will run the script must have access
privileges to the commands run by the EEM policy being registered.

Note

AAA authorization
(such as the
aaa authorization
eventmanager command) must be configured before EEM policies can
be registered. See the
Configuring AAA
Services
module of
Configuring AAA
Services on
Cisco IOS XR Software for more information about AAA authorization configuration.

Persist-time

An optional
persist-time
keyword for the username can also be defined. The
persist-time
keyword defines the number of seconds the username authentication is valid.
When a script is first registered, the configured username for the script is
authenticated. After the script is registered, the username is authenticated
again each time a script is run. If the AAA server is down, the username
authentication can be read from memory. The
persist-time
keyword determines the number of seconds this username authentication is held
in memory.

If the AAA
server is down and the
persist-time
keyword has not expired, then the username is authenticated from memory and the
script runs.

If the AAA
server is down, and the
persist-time
keyword has expired, then user authentication will fail and the script will not
run.

The following values
can be used for the
persist-time
keyword.

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 0 to stop
the username authentication from being cached. If the AAA server is down, the
username will not authenticate and the script will 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 will
be authenticated from the cache.

System or
user
keywords

If you enter the
event manager
policy command without specifying either the
system or
user 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
is registered as a system policy.

Once policies have
been registered, their registration can be verified through the
show event manager policy
registered command. The output displays registered policy
information in two parts. The first line in each policy description lists the
index number assigned to the policy, the policy type (system or user), the type
of event registered, the time when the policy was registered, and the 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 Tcl command arguments that make up the policy file.

AAA
authorization (such as aaa authorization eventmanager) must be configured
before EEM policies can be registered. See the
Configuring AAA Services
module of
Cisco IOS XR System Security Configuration Guide for the
Cisco CRS Router for more information about AAA
authorization configuration.

Step 4

Repeat Step 3
for every EEM policy to be registered.

—

Step 5

commit

Step 6

show event manager policy registered

Example:

RP/0/RP0/CPU0:router# show event manager policy registered

Displays all
EEM policies that are already registered, allowing verification of Step 3.

Registering and
Defining an EEM Tcl Script

Perform this task to
configure environment variables and register an EEM policy. EEM schedules and
runs policies on the basis of an event specification that is contained within
the policy itself. When an EEM policy is registered, the software examines the
policy and registers it to be run when the specified event occurs.

Before You Begin

A policy must be
available that is written in the Tcl scripting language. Sample policies are
provided in the
Sample EEM Policies. Sample policies are stored in the
system policy directory.

SUMMARY STEPS

1.show
event manager environment [
all |
environment-name]

2.configure

3.event
manager environmentvar-name [
var-value ]

4.Repeat
Step 3 to configure all the environment
variables required by the policy to be registered in
Step 5.

Displays the
reliability metric data for processes. The system keeps a record of when
processes start and end, and this data is used as the basis for reliability
analysis.

Sample EEM
Policies

Cisco IOS XR Software
contains some sample policies in the images that contain the EEM. Developers of
EEM policies may modify these policies by customizing the event for which the
policy is to be run and the options associated with logging and responding to
the event. In addition, developers may select the actions to be implemented
when the policy runs.

The
Cisco IOS XR Software
includes a set of sample policies (see
Sample EEM Policy
Descriptions table). The sample policies can be copied to a user
directory and then modified. Tcl is currently the only scripting language
supported by Cisco for policy creation. Tcl policies can be modified using a
text editor such as Emacs. Policies must execute within a defined number of
seconds of elapsed time, and the time variable can be configured within a
policy. The default is 20 seconds.

Sample EEM
policies can be seen on the router using the CLI

Show event manager policy available system

This table
describes the sample EEM policies.

Table 7 Sample EEM
Policy Descriptions

Name of
Policy

Description

periodic_diag_cmds.tcl

This policy
is triggered when the _cron_entry_diag cron entry expires.Then, the output of
this fixed set is collect for the fixed set of commands and the output is sent
by email.

periodic_proc_avail.tcl

This policy
is triggered when the _cron_entry_procavail cron entry expires. Then the output
of this fixed set is collect for the fixed set of commands and the output is
sent by email.

periodic_sh_log.tcl

This policy
is triggered when the _cron_entry_log cron entry expires, and collects the
output for the show log command and a few other commands. If the environment
variable _log_past_hours is configured, it collects the log messages that are
generated in the last _log_past_hours hours. Otherwise, it collects the full
log.

sl_sysdb_timeout.tcl

This policy
is triggered when the script looks for the sysdb timeout ios_msgs and obtains
the output of the show commands. The output is written to a file named after
the blocking process.

tm_cli_cmd.tcl

This policy
runs using a configurable CRON entry. It executes a configurable CLI command
and e-mails the results.

tm_crash_hist.tcl

This policy
runs at midnight each day and e-mails a process crash history report to a
specified e-mail address.

Registers the
EEM policy to be run when the specified event defined within the policy occurs.

Step 5

commit

Programming EEM Policies with Tcl

Perform this task to help you program a policy using Tcl command extensions. We recommend that you copy an existing policy and modify it. There are two required parts that must exist in an EEM Tcl policy: the event_register Tcl command extension and the body. All other sections shown in the Tcl Policy Structure and Requirements are optional.

Tcl Policy Structure
and Requirements

All EEM policies share
the same structure, shown in
Figure 1. There are two parts of an EEM
policy that are required: the event_register Tcl command extension and the
body. The remaining parts of the policy are optional: environmental must
defines, namespace import, entry status, and exit status.

Figure 1. Tcl Policy
Structure and Requirements

The start of every
policy must describe and register the event to detect using an
event_register
Tcl command extension. This part of the policy schedules the running of the
policy. For a list of the available EEM
event_register
Tcl command extensions, see the
Embedded Event Manager Event Registration Tcl Command Extensions. The following example Tcl code
shows how to register the
event_register_timer Tcl command extension:

The following example
Tcl code shows how to check for, and define, some environment variables:

# Check if all the env variables that we need exist.
# If any of them does not exist, print out an error msg and quit.
if {![info exists _email_server]} {
set result \
"Policy cannot be run: variable _email_server has not been set"
error $result $errorInfo
}
if {![info exists _email_from]} {
set result \
"Policy cannot be run: variable _email_from has not been set"
error $result $errorInfo
}
if {![info exists _email_to]} {
set result \
"Policy cannot be run: variable _email_to has not been set"
error $result $errorInfo
)

The namespace import
section is optional and defines code libraries. The following example Tcl code
shows how to configure a namespace import section:

namespace import ::cisco::eem::*
namespace import ::cisco::lib::*

The body of the policy
is a required structure and might contain the following:

Use of the SMTP
library (to send e-mail notifications) or the CLI library (to run CLI commands)
from a policy. For a list of the available SMTP library Tcl command extensions,
see the
SMTP Library Command Extensions. For a list of the available CLI
library Tcl command extensions, see the
CLI Library Command Extensions.

The context_save and
context_retrieve Tcl command extensions that are used to save
Tcl variables for use by other policies.

The following example
Tcl code shows the code to query an event and to log a message as part of the
body section:

EEM Entry Status

The entry status part of an EEM policy is used to determine if a prior policy has been run for the same event, and to determine the exit status of the prior policy. If the _entry_status variable is defined, a prior policy has already run for this event. The value of the _entry_status variable determines the return code of the prior policy.

Entry status designations may use one of three possible values:

0 (previous policy was successful)

Not=0 (previous policy failed),

Undefined (no previous policy was executed).

EEM Exit Status

When a policy finishes running its code, an exit value is set. The exit value is used by the EEM to determine whether or not to apply the default action for this event, if any. A value of zero means that the default action should not be performed. A value of nonzero means that the default action should be performed. The exit status is passed to subsequent policies that are run for the same event.

EEM Policies and
Cisco Error Number

Some EEM Tcl command
extensions set a Cisco Error Number Tcl global variable _cerrno. Whenever
_cerrno is set, the other Tcl global variables are derived from _cerrno and are
set along with it (_cerr_sub_num, _cerr_sub_err,
_cerr_posix_err,
and _cerr_str).

For example, the
action_syslog
command in the following example sets these global variables as a side effect
of the command execution:

Cut and paste
the contents of the sample policy displayed on the screen to a text editor.

—

Step 3

Define the
required event_register Tcl command extension.

Choose the
appropriate event_register Tcl command extension for the event that you want to
detect, and add it to the policy. The following are valid Event Registration
Tcl Command Extensions:

event_register_appl

event_register_counter

event_register_stat

event_register_wdsysmon

event_register_oir

event_register_process

event_register_syslog

event_register_timer

event_register_timer_subscriber

event_register_hardware

event_register_none

Step 4

Add the
appropriate namespace under the ::cisco hierarchy.

Policy
developers can use the new namespace ::cisco in Tcl policies to group all the
extensions used by Cisco IOS XR EEM. There are two namespaces under the ::cisco
hierarchy. The following are the namespaces and the EEM Tcl command extension
categories that belongs under each namespace:

::cisco::eem

EEM
event registration

EEM
event information

EEM
event publish

EEM
action

EEM
utility

EEM
context library

EEM
system information

CLI
library

::cisco::lib

SMTP
library

Note

Ensure
that the appropriate namespaces are imported, or use the qualified command
names when using the preceding commands.

Step 5

Program the must
defines section to check for each environment variable that is used in this
policy.

This is an
optional step. Must defines is a section of the policy that tests whether any
EEM environment variables that are required by the policy are defined before
the recovery actions are taken. The must defines section is not required if the
policy does not use any EEM environment variables. EEM environment variables
for EEM scripts are Tcl global variables that are defined external to the
policy before the policy is run. To define an EEM environment variable, use the
EEM configuration command
event
manager environment. By convention, all Cisco EEM environment variables begin
with "_" (an underscore). To avoid future conflict, customers are urged not to
define new variables that start with "_".

Note

You can
display the Embedded Event Manager environment variables set on your system by
using the
show
event manager environment command in
EXEC mode.

For example,
EEM environment variables defined by the sample policies include e-mail
variables. The sample policies that send e-mail must have the following
variables set in order to function properly. The following are the
e-mail-specific environment variables used in the sample EEM policies.

_email_to—The address to which e-mail is sent (for example,
engineering@example.com)

_email_from—The address from which e-mail is sent (for
example, devtest@example.com)

_email_cc—The address to which the e-mail must be copied
(for example, manager@example.com)

Step 6

Program the
body of the script.

In this
section of the script, you can define any of the following:

The
event_reqinfo event information Tcl command extension that
is used to query the EEM for information about the detected event.

The action
Tcl command extensions, such as
action_syslog, that are used to specify actions specific to
EEM.

The system
information Tcl command extensions, such as
sys_reqinfo_routername, that are used to obtain general
system information.

The
context_save and
context_retrieve Tcl command extensions that are used to
save Tcl variables for use by other policies.

Use of the
SMTP library (to send e-mail notifications) or the CLI library (to run CLI
commands) from a policy.

Step 7

Check the
entry status to determine if a policy has previously run for this event.

If the prior
policy is successful, the current policy may or may not require execution.
Entry status designations may use one of three possible values: 0 (previous
policy was successful), Not=0 (previous policy failed), and Undefined (no
previous policy was executed).

Step 8

Check the exit
status to determine whether or not to apply the default action for this event,
if a default action exists.

A value of
zero means that the default action should not be performed. A value of nonzero
means that the default action should be performed. The exit status is passed to
subsequent policies that are run for the same event.

Step 9

Set Cisco
Error Number (_cerrno) Tcl global variables.

Some EEM Tcl
command extensions set a Cisco Error Number Tcl global variable _cerrno.
Whenever _cerrno is set, four other Tcl global variables are derived from
_cerrno and are set along with it (_cerr_sub_num, _cerr_sub_err,
_cerr_posix_err,
and _cerr_str).

Step 10

Save the Tcl
script with a new filename, and copy the Tcl script to the router.

Embedded Event
Manager policy filenames adhere to the following specification:

An
optional prefix—Mandatory.—indicating, if present, that this is a system policy
that should be registered automatically at boot time if it is not already
registered. For example: Mandatory.sl_text.tcl.

A filename
body part containing a two-character abbreviation (see
Table 1) for the first event specified, an
underscore character part, and a descriptive field part further identifying the
policy.

Registers the
EEM policy to be run when the specified event defined within the policy occurs.

Step 14

commit

Step 15

Cause the
policy to execute, and observe the policy.

—

Step 16

Use debugging
techniques if the policy does not execute correctly.

—

Creating an EEM User
Tcl Library Index

Perform this task to
create an index file that contains a directory of all the procedures contained
in a library of Tcl files. This task allows you to test library support in EEM
Tcl. In this task, a library directory is created to contain the Tcl library
files, the files are copied into the directory, and an index tclIndex) is
created that contains a directory of all the procedures in the library files.
If the index is not created, the Tcl procedures are not found when an EEM
policy that references a Tcl procedure is run.

Use the
auto_mkindex
command to create the tclIndex file. The tclIndex file contains a directory of
all the procedures contained in the Tcl library files. We recommend that you
run
auto_mkindex
inside a directory, because there can be only a single tclIndex file in any
directory and you may have other Tcl files to be grouped together. Running
auto_mkindex in
a directory determines which Tcl source file or files are indexed using a
specific tclIndex.

The following
sample TclIndex is created when the lib1.tcl and lib2.tcl files are in a
library file directory and the
auto_mkindex
command is run:

tclIndex

# Tcl autoload index file, version 2.0
# This file is generated by the "auto_mkindex" command
# and sourced to set up indexing information for one or
# more commands. Typically each line is a command that
# sets an element in the auto_index array, where the
# element name is the name of a command and the value is
# a script that loads the command.
set auto_index(test1) [list source [file join $dir lib1.tcl]]
set auto_index(test2) [list source [file join $dir lib1.tcl]]
set auto_index(test3) [list source [file join $dir lib2.tcl]]

Step 4

Copy the Tcl
library files from
Step 1and the tclIndex file from
Step 3to the directory used for storing
user library files on the target router.

—

Step 5

Copy a
user-defined EEM policy file written in Tcl to the directory used for storing
user-defined EEM policies on the target router.

Creating an EEM User
Tcl Package Index

Perform this task to
create a Tcl package index file that contains a directory of all the Tcl
packages and version information contained in a library of Tcl package files.
Tcl packages are supported using the Tcl
package
keyword.

Tcl packages are
located in either the EEM system library directory or the EEM user library
directory. When a
package require
Tcl command is executed, the user library directory is searched first for a
pkgIndex.tcl file. If the pkgIndex.tcl file is not found in the user directory,
the system library directory is searched.

In this task, a Tcl
package directory—the pkgIndex.tcl file—is created in the appropriate library
directory using the
pkg_mkIndex
command to contain information about all the Tcl packages contained in the
directory along with version information. If the index is not created, the Tcl
packages are not found when an EEM policy that contains a
package require
Tcl command is run.

Using the Tcl
package support in EEM, users can gain access to packages such as XML_RPC for
Tcl. When the Tcl package index is created, a Tcl script can easily make an
XML-RPC call to an external entity.

On your
workstation (UNIX, Linux, PC, or Mac) create a library directory and copy the
Tcl package files into the directory.

—

Step 2

tclsh

Example:

workstation% tclsh

Enters the Tcl
shell.

Step 3

pkg_mkindexdirectory_name*.tcl

Example:

workstation% pkg_mkindex eem_library *.tcl

Use the
pkg_mkindex
command to create the pkgIndex file. The pkgIndex file contains a directory of
all the packages contained in the Tcl library files. We recommend that you run
the
pkg_mkindex
command inside a directory, because there can be only a single pkgIndex file in
any directory and you may have other Tcl files to be grouped together. Running
the
pkg_mkindex
command in a directory determines which Tcl package file or files are indexed
using a specific pkgIndex.

The following
example pkgIndex is created when some Tcl package files are in a library file
directory and the pkg_mkindex command is run:

pkgIndex

# Tcl package index file, version 1.1
# This file is generated by the "pkg_mkIndex" command
# and sourced either when an application starts up or
# by a "package unknown" script. It invokes the
# "package ifneeded" command to set up package-related
# information so that packages will be loaded automatically
# in response to "package require" commands. When this
# script is sourced, the variable $dir must contain the
# full path name of this file's directory.
package ifneeded xmlrpc 0.3 [list source [file join $dir xmlrpc.tcl]]

Step 4

Copy the Tcl
package files from Step 1 and the pkgIndex file from Step 3 to the directory
used for storing user library files on the target router.

—

Step 5

Copy a
user-defined EEM policy file written in Tcl to the directory used for storing
user-defined EEM policies on the target router.

Display Embedded
Event Manager Process: Example

Reliability metric data is kept for each process handled
by the System Manager. This data includes standby processes running on either
the primary or backup hardware card. Data is recorded in a table indexed by
hardware card disk ID plus process pathname plus process instance for those
processes that have multiple instances. This is the sample output from the
show event manager metric
process command displaying reliability metric data:

EEM Sample Policy Descriptions

The configuration example features one sample EEM policy. The tm_cli_cmd.tcl runs using a configurable CRON entry. This policy executes a configurable CLI command and e-mails the results.

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; only _email_cc is optional. Other required and optional variable settings are outlined in the following tables.

This table describes a list of the e-mail variables.

Table 10 E-mail-Specific Environmental Variables Used by the Sample Policies

Environment Variable

Description

Example

_email_server

Simple Mail Transfer Protocol (SMTP) mail server used to send e-mail.

mailserver.example.com

_email_to

Address to which e-mail is sent.

engineering@example.com

_email_from

Address from which e-mail is sent.

devtest@example.com

_email_cc

Address to which the e-mail must be copied.

manager@example.com

This table 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

First configuration command that is run.

interface gigabitEthernet1/0/5/0

_config_cmd2

Second configuration command that is run. This variable is optional and need not be specified.

no shutdown

_syslog_pattern

Regular expression pattern match string that is used to compare syslog messages to determine when the policy runs.

.*UPDOWN.*FastEthernet0/0.*

This table
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

CRON specification that determines when the policy will run.

0-59/1 0-23/1 * * 0-7

_show_cmd

CLI command to be executed when the policy is run.

show version

This table
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

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

URL location to which the crash report is sent.

http://www.example.com/fm/interface_tm.cgi

This table 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

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 (EEM), the
hostname and
domain-name
commands must be configured. The EEM environment variables must also be set.
After a
Cisco IOS XR Software
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
Table 5) are all optional and are not listed
here:

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 run 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
EXEC mode, use
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, which displays policies that are available to
be installed. After you enter the
configure
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.

Running the
tm_cli_cmd.tcl Sample Policy

This sample policy
demonstrates the ability to periodically run 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
EXEC mode, 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, which displays the policies that are available
to be installed. After you enter the
configure
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.

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
EXEC mode, enter
the
show event manager policy
registered command to verify that no policies are currently
registered. Next, enter the
show event manager policy
available command to display which policies are available to be
installed. After you enter the
configure
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.

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
show event manager policy
registered command to verify that no policies are currently
registered. Next, enter the
show event manager
policyavailable command to display which policies are
available to be installed. After you enter the
configure
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.

tm_cli_cmd.tcl
Sample Policy

The following sample
policy runs a configurable CRON entry. The policy executes a configurable
Cisco IOS XR SoftwareCLI
command and e-mails the results. An optional log file can be defined to which
the output is appended with a time stamp.

Tracing Tcl set Command Operations: Example

Tcl is a flexible language. One of the flexible aspects of Tcl is that you can override
commands. In this example, the Tcl set command is renamed as
_set, and a new version of the set command is created that
displays a message containing the text "setting" and appends the scalar variable that is
being set. This example can be used to trace all instances of scalar variables being
set.

RFCs

RFCs

Title

No new or
modified RFCs are supported by this feature, and support for existing RFCs has
not been modified by this feature.

—

Technical
Assistance

Description

Link

The Cisco
Technical Support website contains thousands of pages of searchable technical
content, including links to products, technologies, solutions, technical tips,
and tools. Registered Cisco.com users can log in from this page to access even
more content.

event_register_appl

Registers for an application event. Use this Tcl command extension to run a policy when an application event is triggered following another policy's execution of an event_publish Tcl command extension; the event_publish command extension publishes an application event.

To register for an application event, a subsystem must be specified. Either a Tcl policy or
the internal EEM API can publish an application event. If the event is being published by a
policy, the sub_system argument that is reserved for a policy is
798.

Syntax

Arguments

sub_system

(Optional) Number assigned to the EEM policy that published the application event. The number is set to 798, because all other numbers are reserved for Cisco use. If this argument is not specified, all components are matched.

type

(Optional) Event subtype within the specified event. The
sub_system and
type arguments uniquely identify an
application event. If this argument is not specified, all types are
matched. If you specify this argument, you must choose an integer between
1 and 4294967295, inclusive.

There must be a match of component and type between the
event_publish command extension and the
event_register_appl command extension for
the publishing and registration to work.

queue_priority

(Optional) Priority level at which the script will be queued; normal priority is greater than low priority but less than high priority. The priority here is not execution priority, but queuing priority. If this argument is not specified, the default priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the nice argument is set to 1, the policy is run at a run-time priority that is less than the default priority. The default value is 0.

If multiple conditions exist, the application event is raised when all the conditions are satisfied.

Result String

None

Set _cerrno

No

event_register_cli

Registers for a CLI event. Use this Tcl command extension to run a policy when a CLI command of a specific pattern is entered based on pattern matching performed against an expanded CLI command. This will be implemented as a new process in IOS-XR which will be dlrsc_tracker. This ED will not do pattern match on admin commands of XR.

Note

You can enter an abbreviated CLI command, such as sh mem summary, and the parser will expand the command to show memory summary to perform the matching. The functionality provided in the CLI event detector only allows a regular expression pattern match on a valid XR CLI command itself. This does not include text after a pipe character when redirection is used.

Syntax

Arguments

tag

(Optional) String identifying a tag that can be used with the trigger Tcl command extension to support multiple event statements within a Tcl script.

occurs

(Optional) The number of occurrences before the event is raised. If this argument is not specified, the event is raised on the first occurrence. If this argument is specified, it must be an integer between 1 and 4294967295, inclusive.

period

(Optional) Specifies a backward looking time window in which all CLI events must occur (the occurs clause must be satisfied) in order for an event to be published (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the most recent event is used.

pattern

(Mandatory) Specifies the regular expression used to perform the CLI command pattern match.

default

(Optional) The time period during which the CLI event detector waits for the policy to exit (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If the default time period expires before the policy exits, the default action will be executed. The default action is to run the command. If this argument is not specified, the default time period is set to 30 seconds.

If multiple conditions are specified, the CLI event will be raised when all the conditions are matched.

Result String

None

Set _cerrno

No

event_register_config

Registers for a change in running configuration. Use this Tcl command extension to trigger a policy when there is any configuration change. This will be implemented as a new process in IOS-XR which will be dlrsc_tracker. This ED will not check for admin config changes in XR.

Syntax

Arguments

queue_priority low-Specifies that the script is to be queued at the lowest of the three priority levels.

queue_priority normal-Specifies that the script is to be queued at a priority level greater than low priority but less than high priority.

queue_priority high-Specifies that the script is to be queued at the highest of the three priority levels.

queue_priority last-Specifies that the script is to be queued at the lowest priority level.

If more than one script is registered with the "queue_priority_last" argument set, these scripts will execute in the order in which the events are published.

Note

The queue_priority argument specifies the queuing priority, but not the execution priority, of the script being registered.

If this argument is not specified, the default queuing priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the nice argument is set to 1, the policy is run at a run-time priority that is less than the default priority. The default value is 0.

If multiple conditions are specified, the syslog event will be raised when all the conditions are matched.

Result String

None

Set _cerrno

No

event_register_counter

Registers for a counter event as both a publisher and a subscriber. Use this Tcl command extension to run a policy on the basis of a named counter crossing a threshold. This event counter, as a subscriber, identifies the name of the counter to which it wants to subscribe and depends on another policy or another process to actually manipulate the counter. For example, let policyB act as a counter policy, whereas policyA (although it does not need to be a counter policy) uses register_counter, counter_modify, or unregister_counter Tcl command extensions to manipulate the counter defined in policyB.

Arguments

(Mandatory) Entry comparison operator used to compare the current counter value with the entry value; if true, an event is raised and event monitoring is disabled until exit criteria are met.

entry_val

(Mandatory) Value with which the current counter value should be compared, to decide if the counter event should be raised.

exit_op

(Mandatory) Exit comparison operator used to compare the current counter value with the exit value; if true, event monitoring for this event is reenabled.

exit_val

(Mandatory) Value with which the current counter value should be compared to decide if the exit criteria are met.

queue_priority

(Optional) Priority level at which the script will be queued; normal priority is greater than low priority but less than high priority. The priority here is not execution priority, but queuing priority. If this argument is not specified, the default priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the nice argument is set to 1, the policy is run at a run-time priority that is less than the default priority. The default value is 0.

Result String

None

Set _cerrno

No

event_register_hardware

Registers for an environmental monitoring hardware device that is specified by the hardware event and condition.

Syntax

Arguments

(Mandatory) Environmental device that is used to monitor.The integer number must be inclusively between 1 and 2147483647. This is a bit mask that monitors multiple types of environmental devices.

The following supported devices and their corresponding bitmasks are listed:

0x0001 chassis

0x0002 backplane

0x0004 slot

0x0008 card

0x0010 port

0x0020 fan

0x0040 group of power supplies

0x0080 power supply

0x0100 sensor

They can be bit wise OR'ed to monitor multiple devices.

env_cond

(Mandatory) Environmental condition that is used to monitor. This is a bit mask that monitors multiple kinds of environmental conditions. The following supported environmental conditions and their corresponding bitmasks are listed:

0x0001 low warning

0x0002 high warning

0x0004 warning

0x0010 low critical

0x0020 high critical

0x0040 critical

0x0100 pre-shutdown

0x0200 shutdown

priority

(Optional) Priority level that the script is queued. If not specified, the default uses the normal priority.

maxrun_sec, maxrun_nsec

(Optional) Maximum runtime of the script that is specified in seconds and nanoseconds. The integer number must be inclusively between 0 and 2147483647. If not specified, use the default 20-second run-time limit.

nice

(Optional) Maximum runtime of the script that is specified in seconds and nanoseconds. The integer number must be inclusively between 0 and 2147483647. If not specified, use the default 20-second run-time limit.

Result String

None

Set _cerrno

No

event_register_none

Registers for an event that is triggered by the event manager run command. These events are handled by the None event detector that screens for this event.

Syntax

Arguments

queue_priority

(Optional) Priority level at which the script will be queued; normal priority is greater than low priority but less than high priority. The priority here is not execution priority, but queuing priority. If this argument is not specified, the default priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the nice argument is set to 1, the policy is run at a run-time priority that is less than the default priority. The default value is 0.

Result String

None

Set _cerrno

No

event_register_oir

Registers for an online insertion and removal (OIR) event. Use this Tcl command extension to run a policy on the basis of an event raised when a hardware card OIR occurs. These events are handled by the OIR event detector that screens for this event.

Syntax

Arguments

queue_priority

(Optional) Priority level at which the script will be queued; normal priority is greater than low priority but less than high priority. The priority here is not execution priority, but queuing priority. If this argument is not specified, the default priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the
nice argument is set to 1, the policy is
run at a run-time priority that is less than the default priority. The
default value is 0.

Result String

None

Set _cerrno

No

event_register_process

Registers for a process event. Use this Tcl command extension to run a policy on the basis of an event raised when a Cisco IOS XR software modularity process starts or stops. These events are handled by the system manager event detector that screens for this event. This Tcl command extension is supported only in software modularity images.

Syntax

Arguments

abort

(Mandatory) Abnormal process termination. Process may abort because of exiting with a nonzero exit status, receiving a kernel-generated signal, or receiving a SIGTERM or SIGKILL signal that is not sent because of user request.

term

(Mandatory) Normal process termination.

start

(Mandatory) Process start.

job_id

(Optional) Number assigned to the EEM policy that published the process event. Number is set to 798, because all other numbers are reserved for Cisco use.

instance

(Optional) Process instance ID. If specified, this argument must be an integer between 1 and 4294967295, inclusive.

path

(Optional) Process pathname (regular expression string).

node

(Optional) The node name is a string that consists of the word "node" followed by two fields separated by a slash (/), using the following format:

node<slot-number>/<cpu-number>

The slot-number is the hardware slot number. The cpu-number is the hardware CPU number. For example, the SP CPU in a Supervisor card on a Cisco Catalyst 6500 series switch located in slot 0 would be specified as node0/0. The RP CPU in a Supervisor card on a Cisco Catalyst 6500 series switch located in slot 0 would be addressed as node0/1. If the node argument is not specified, the default node specification is always the regular expression pattern match of * representing all applicable nodes.

queue_priority

(Optional) Priority level at which the script will be queued; normal priority is greater than low priority but less than high priority. The priority here is not execution priority, but queuing priority. If this argument is not specified, the default priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the
nice argument is set to 1, the policy is
run at a run-time priority that is less than the default priority. The
default value is 0.

tag

Tag is acceptable but ignored. Cisco IOS EEM scripts with the tag option can run in an Cisco IOS XR software environment without any error. Since Cisco IOS XR software does not support multiple events, the tag has no effect.

If an optional argument is not specified, the event matches all possible values of the argument. If multiple arguments are specified, the process event will be raised when all the conditions are matched.

Result String

None

Set _cerrno

No

event_register_snmp

Registers for a Simple
Network Management Protocol (SNMP) statistics event. Use this Tcl command
extension to run a policy when a given counter specified by an SNMP object ID
(oid) crosses a defined threshold. When a snmp policy is registered, a poll
timer is specified. Event matching occurs when the poll timer for the
registered event expires. The
snmp-server
manager CLI command must be enabled for the SNMP notifications to work
using Tcl policies.

Aruguments

tag

(Optional) String identifying a tag that can be used with the trigger Tcl
command extension to support multiple event statements within a Tcl script.

entry_op

(Mandatory) Entry comparison operator used to compare the current OID data
value with the entry value; if true, an event will be raised and event
monitoring will be disabled until exit criteria are met.

get_type

(Mandatory) Type of SNMP get operation that needs to be applied to the OID
specified. If the get_type argument is "exact," the value of the specified OID
is retrieved; if the get_type argument is "next," the value of the
lexicographical successor to the specified OID is retrieved.

entry_val

(Mandatory) Value with which the current oid data value should be compared to
decide if the SNMP event should be raised.

entry-type

Specifies
a type of operation to be applied to the object ID specified by the entry-val
argument.

Value is
defined as the actual value of the entry-val argument.

Increment
uses the entry-val field as an incremental difference and the entry-val is
compared with the difference between the current counter value and the value
when the event was last triggered (or the first polled sample if this is a new
event). A negative value checks the incremental difference for a counter that
is decreasing.

Rate is
defined as the average rate of change over a period of time. The time period is
the average-factor value multiplied by the poll-interval value. At each poll
interval the difference between the current sample and the previous sample is
taken and recorded as an absolute value. An average of the previous
average-factor value samples is taken to be the rate of change.

exit_comb

(Optional) Exit combination operator used to indicate the combination of exit
condition tests required to decide if the exit criteria are met so that the
event monitoring can be reenabled. If it is "and," both exit value and exit
time tests must be passed to meet the exit criteria. If it is "or," either exit
value or exit time tests can be passed to meet the exit criteria

When
exit_comb is "and," exit_op, and exit_val (exit_time) must exist.

When
exit_comb is "or," (exit_op and exit_val) or (exit_time) must exist.

exit_op

(Optional) Exit comparison operator used to compare the current oid data value
with the exit value; if true, event monitoring for this event will be
reenabled.

exit_val

(Optional) Value with which the current oid data value should be compared to
decide if the exit criteria are met.

exit-type

(Optional) Specifies a type of operation to be applied to the object ID
specified by the exit-val argument. If not specified, the value is assumed.

Value is
defined as the actual value of the exit-val argument.

Increment
uses the exit-val field as an incremental difference and the exit-val is
compared with the difference between the current counter value and the value
when the event was last triggered (or the first polled sample if this is a new
event). A negative value checks the incremental difference for a counter that
is decreasing.

Rate is
defined as the average rate of change over a period of time. The time period is
the average-factor value multiplied by the poll-interval value. At each poll
interval the difference between the current sample and the previous sample is
taken and recorded as an absolute value. An average of the previous
average-factor value samples is taken to be the rate of change.

exit_time

(Optional) Number of
POSIX timer units after an event is
raised when event monitoring will be enabled again. Specified in
SSSSSSSSSS[.MMM] format where SSSSSSSSSS must be an integer number representing
seconds between 0 and 4294967295, inclusive. MMM represents milliseconds and
must be an integer number between 0 and 999.

poll_interval

(Mandatory) Interval between consecutive polls in
POSIX timer units. Currently the
interval is forced to be at least 1 second (specified in SSSSSSSSSS[.MMM]
format, where SSSSSSSSSS must be an integer representing seconds between 0 and
4294967295, inclusive, and where MMM must be an integer representing
milliseconds between 0 and 999).

average-factor

(Optional) Number in the range from 1 to 64 used to calculate the period used
for rate-based calculations. The average-factor value is multiplied by the
poll-interval value to derive the period in milliseconds. The minimum average
factor value is 1.

Result
string

None

Set
_cerrno

No

event_register_snmp_notification

Registers for a Simple Network Management Protocol (SNMP) notification trap event. Use this Tcl command extension to run a policy when an SNMP trap with the specified SNMP object ID (oid) is encountered on a specific interface or address. The snmp-server manager CLI command must be enabled for the SNMP notifications to work using Tcl policies.

Argument

tag

(Optional) String identifying a tag that can be used with the trigger Tcl command extension to support multiple event statements within a Tcl script.

oid

(Mandatory) OID number of the data element in SNMP dot notation (for example, 1.3.6.1.2.1.2.1.0). If the specified OID ends with a dot (.), then all OIDs that start with the OID number before the dot are matched. It supports all OID supported by SNMP in XR.

oid_val

(Mandatory) OID value with which the current OID data value should be compared to decide if the SNMP event should be raised.

op

(Mandatory) Comparison operator used to compare the current OID data value with the SNMP Protocol Data Unit (PDU) OID data value; if this is true, an event is raised.

src_ip_address

(Optional) Source IP address where the SNMP notification trap originates. The default is all; it is set to receive SNMP notification traps from all IP addresses. This option will not be supported in XR as src_ip_address is only for incoming trap which is not supported in EEM XR.

dest_ip_address

(Optional) Destination IP address where the SNMP notification trap is sent. The default is all; it is set to receive SNMP traps from all destination IP addresses.

default

(Optional) Specifies the time period in seconds during which the snmp notification event detector waits for the policy to exit. Thetime periodis specified in ssssssssss[.mmm] format, where ssssssssss must be an integer representing seconds between 0 and 4294967295 and mmm must be an integer representing milliseconds between 0 and 999

direction

(Optional) The direction of the incoming or outgoing SNMP trap or inform PDU to filter. The default value is outgoing. For XR direction incoming will not be supported and policy registration will fail if user provides direction as incoming.

msg_op

(Optional) The action to be taken on the SNMP PDU (drop it or send it) once the event is triggered. The default value is send. For XR msg_op drop will not be supported and policy registration will fail if user provides msg_op as drop.

Result String

None

Set _cerrno

No

event_register_stat

Registers for a
statistics event. Use this Tcl command extension to run a policy when a given
statistical counter crosses a defined threshold.

The following three
fields are listed to uniquely identify the statistics counter that the EEM
keyword monitors:

Data element name
corresponds to the argument name. For example, the ifstats-generic name is
defined as interface generic statistics.

The first modifier
of the data element corresponds to the
modifier_1
argument. For example, Ethernet1_0 is defined as the first modifier for
ifstats-generic, which qualifies the interface generic statistics to be
specific for the Ethernet interface.

The second
modifier of the data element corresponds to the
modifier_2
argument. For example, input-ptks is defined as the second modifier for
ifstats-generic, which further qualifies the interface statistics for the
specific Ethernet interface is the number of packets received.

Arguments

name

(Mandatory) Statistics data element name.

modifier_1

Mandatory
for interface statistics but optional for others. For interface statistics,
this variable is the interface name. To get the interface name, use the
show interface
brief command. This command lists all the currently configured
interface names designated by a slash (/), for example, Ethernet 1/0. When you
want this interface to be configured for the
modifier_1
argument, change the slash to an underscore.

modifier_2

Mandatory
for interface statistics but optional for others. For interface statistics,
this variable is the interface statistic name. To get the interface statistic
name, use the
show event manager statistics
-table command with the
all keyword to
list all the classes of statistics. Then, use the
show event manager statistics
-table command with the
name argument
to get the specific statistics name for modifier_2.

entry_op

(Mandatory) Entry comparison operator that is used to compare
the current statistics value with the entry value. If true, an event is raised
and event monitoring is disabled until the exit criteria is met.

entry_val

(Mandatory) Value in which the current statistical counter value
that is compared to decide if the statistical event can be raised.

exit_comb

(Mandatory) Exit combination operator that indicates the
combination of exit condition tests that are required to decide if the exit
criteria is met so that event monitoring is reenabled. If so, both exit value
and exit time tests must be passed to meet the exit criteria.Or either exit
value or exit time tests are passed to meet the exit criteria.

exit_comb argument or (exit_op and
exit_val
arguments) or (exit_time_sec
argument or
exit_time_nsec
argument) must exist.

exit_op

Exit
comparison operator that is used to compare the current statistics value with
the exit value. If true, event monitoring for this event is reenabled.

exit_val

Value in
which the current statistical counter value is compared to decide if the exit
criteria is met.

exit_time_sec

exit_time_nse

Number of
POSIX timer units after the event is
raised when event monitoring is enabled again. The integer number must be
between 0 and 2147483647, inclusive.

poll_interval_sec

poll_interval_nsec

Either the
poll_interval_sec or
poll_interval_nsec arguments must be specified.
The interval must be between the consecutive polls in
POSIX time units. Currently, it is
forced to be at least one second. The integer number must be between 0 and
2147483647, inclusive.

priority

(Optional)
Priority level that is queued for the script. If not specified, the default is
using the normal priority.

maxrun_sec,

maxrun_nsec

(Optional) Maximum run time of the script that is specified in
seconds and nanoseconds. If not specified, 20-second run-time limit is used as
the default. The integer number must be between 0 and 2147483647, inclusive.

nice

(Optional) When the
nice argument is set to the value of 1, the policy is run
at a run-time priority that is less than the default priority. The default
value is 0.

tag

Tag is
acceptable but ignored.Cisco IOS EEM scripts with the tag option can run in an
Cisco IOS XR software environment without any error. Since
Cisco IOS XR software does not support multiple events,
the tag has no effect.

Note

Exit criteria
can be time-based, value-based, or both. Event monitoring is not reenabled
until the exit criteria is met.

If multiple
conditions exist, the statistics event is raised when all of the conditions are
satisfied.

Reslt
String

None

Set _cerrno

No

event_register_syslog

Registers for a syslog event. Use this Tcl command extension to trigger a policy when a syslog message of a specific pattern is logged after a certain number of occurrences during a certain period of time.

Arguments

occurs

(Optional) Number of occurrences before the event is raised; if not specified, the event is raised on the first occurrence. If specified, the value must be greater than 0.

period

(Optional) Time interval, in seconds and milliseconds, during which the one or more occurrences must take place in order to raise an event (specified in SSSSSSSSSS[.MMM] format where SSSSSSSSSS must be an integer number representing seconds between 0 and 4294967295, inclusive, and where MMM represents milliseconds and must be an integer number between 0 and 999). If this argument is not specified, no period check is applied.

pattern

(Mandatory) Regular expression used to perform syslog message pattern match. This argument is what the policy uses to identify the logged syslog message.

priority

(Optional) Message priority to be screened. If this argument is specified, only messages that are at the specified logging priority level, or lower, are screened. If this argument is not specified, the default priority is 0.

queue_priority

(Optional) Priority level at which the script will be queued; normal priority is greater than low priority but less than high priority. The priority here is not execution priority, but queuing priority. If this argument is not specified, the default priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the
nice argument is set to 1, the policy is
run at a run-time priority that is less than the default priority. The
default value is 0.

If multiple conditions are specified, the syslog event is raised when all the conditions are matched.

Table 15 Severity Level Mapping For Syslog Events

Severity Keyword

Syslog Priority

Description

severity_fatal

LOG_EMERG (0)

System is unusable.

severity_critical

LOG_ALERT (1)

Critical conditions, immediate attention required.

severity_major

LOG_CRIT (2)

Major conditions.

severity_minor

LOG_ERR (3)

Minor conditions.

severity_warning

LOG_WARNING (4)

Warning conditions.

severity_notification

LOG_NOTICE (5)

Basic notification, informational messages.

severity_normal

LOG_INFO (6)

Normal event, indicates returning to a normal state.

severity_debugging

LOG_DEBUG (7)

Debugging messages.

Result String

None

Set _cerrno

No

event_register_timer

Creates a timer and registers for a timer event as both a publisher and a subscriber. Use this Tcl command extension when there is a need to trigger a policy that is time specific or timer based. This event timer is both an event publisher and a subscriber. The publisher part indicates the conditions under which the named timer is to go off. The subscriber part identifies the name of the timer to which the event is subscribing.

Syntax

Arguments

watchdog

(Mandatory) Watchdog timer.

countdown

(Mandatory) Countdown timer.

absolute

(Mandatory) Absolute timer.

cron

(Mandatory) CRON timer.

name

(Optional) Name of the timer.

cron_entry

(Optional) Entry must be specified if the CRON timer type is specified. Must not be specified if any other timer type is specified. A cron_entry is a partial UNIX crontab entry (the first five fields) as used with the UNIX CRON daemon.

A cron_entry specification consists of a text string with five fields. The fields are separated by spaces. The fields represent the time and date when CRON timer events will be triggered. The fields are described in Table 1 .

Ranges of numbers are allowed. Ranges are two numbers separated with a hyphen. The specified range is inclusive. For example, 8-11 for an hour entry specifies execution at hours 8, 9, 10, and 11.

A field may be an asterisk (*), which always stands for "first-last."

Lists are allowed. A list is a set of numbers (or ranges) separated by commas. Examples: "1,2,5,9" and "0-4,8-12".

Step values can be used in conjunction with ranges. Following a range with "/<number>" specifies skips of the number's value through the range. For example, "0-23/2" is used in the hour field to specify an event that is triggered every other hour. Steps are also permitted after an asterisk, so if you want to say "every two hours", use "*/2".

Names can also be used for the month and the day of week fields. Use the first three letters of the particular day or month (case does not matter). Ranges or lists of names are not allowed.

The day on which a timer event is triggered can be specified by two fields: day of month and day of week. If both fields are restricted (that is, are not *), an event will be triggered when either field matches the current time. For example, "30 4 1,15 * 5" would cause an event to be triggered at 4:30 a.m. on the 1st and 15th of each month, plus every Friday.

Instead of the first five fields, one of seven special strings may appear. These seven special strings are described in Table 2.

Example 1: "0 0 1,15 * 1" would trigger an event at midnight on the 1st and 15th of each month, as well as on every Monday. To specify days by only one field, the other field should be set to *; "0 0 * * 1" would trigger an event at midnight only on Mondays.

Example 2: "15 16 1 * *" would trigger an event at 4:15 p.m. on the first day of each month.

Example 3: "0 12 * * 1-5" would trigger an event at noon on Monday through Friday of each week.

Example 4: "@weekly" would trigger an event at midnight once a week on Sunday.

time

(Optional) Time must be specified if a timer type other than CRON is specified. Must not be specified if the CRON timer type is specified. For watchdog and countdown timers, the number of seconds and milliseconds until the timer expires; for the absolute timer, the calendar time of the expiration time. Time is specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999. An absolute expiration date is the number of seconds and milliseconds since January 1, 1970. If the date specified has already passed, the timer expires immediately.

queue_priority

(Optional) Priority level at which the script will be queued; normal priority is greater than low priority but less than high priority. The priority here is not execution priority, but queuing priority. If this argument is not specified, the default priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the
nice argument is set to 1, the policy is
run at a run-time priority that is less than the default priority. The
default value is 0.

Result String

Set _cerrno

See Also

event_register_timer_subscriber

Registers for a timer event as a subscriber. Use this Tcl command extension to identify the name of the timer to which the event timer, as a subscriber, wants to subscribe. The event timer depends on another policy or another process to actually manipulate the timer. For example, let policyB act as a timer subscriber policy, but policyA (although it does not need to be a timer policy) uses register_timer, timer_arm, or timer_cancel Tcl command extensions to manipulate the timer referenced in policyB.

Syntax

Arguments

watchdog

(Mandatory) Watchdog timer.

countdown

(Mandatory) Countdown timer.

absolute

(Mandatory) Absolute timer.

cron

(Mandatory) CRON timer.

name

(Mandatory) Name of the timer.

queue_priority

(Optional) Priority level at which the script will be queued; normal priority is greater than low priority but less than high priority. The priority here is not execution priority, but queuing priority. If this argument is not specified, the default priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the nice argument is set to 1, the policy is run at a run-time priority that is less than the default priority. The default value is 0.

Note

An EEM policy that registers for a timer event or a counter event can act as both publisher and subscriber.

Result String

None

Set _cerrno

No

See Also

event_register_track

Registers for a report event from the Object Tracking component in XR. Use this Tcl command extension to trigger a policy on the basis of a Object Tracking component report for a specified track. This will be implemented as a new process in IOS-XR which will be dlrsc_tracker. Please note that the manageability package should be installed for the track ED to be functional.

Syntax

Arguments

(Optional) String identifying a tag that can be used with the trigger Tcl command extension to support multiple event statements within a Tcl script.

state

(Optional) Specifies that the tracked object transition will cause an event to be raised. If up is specified, an event will be raised when the tracked object transitions from a down state to an up state. If down is specified, an event will be raised when the tracked object transitions from an up state to a down state. If any is specified, an event will be raised when the tracked object transitions to or from any state.

queue_priority

(Optional) Priority level at which the script will be queued:

queue_priority low-Specifies that the script is to be queued at the lowest of the three priority levels.

queue_priority normal-Specifies that the script is to be queued at a priority level greater than low priority but less than high priority.

queue_priority high-Specifies that the script is to be queued at the highest of the three priority levels.

queue_priority last-Specifies that the script is to be queued at the lowest priority level.

If more than one script is registered with the "queue_priority_last" argument set, these scripts will execute in the order in which the events are published.

Note

The queue_priority argument specifies the queuing priority, but not the execution priority, of the script being registered.

If this argument is not specified, the default queuing priority is normal.

maxrun

(Optional) Maximum run time of the script (specified in SSSSSSSSSS[.MMM] format, where SSSSSSSSSS must be an integer representing seconds between 0 and 4294967295, inclusive, and where MMM must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the nice argument is set to 1, the policy is run at a run-time priority that is less than the default priority. The default value is 0.

If an optional argument is not specified, the event matches all possible values of the argument.

Result String

None

Set _cerrno

No

event_register_wdsysmon

Registers for a Watchdog system monitor event. Use this Tcl command extension to register
for a composite event which is a combination of several subevents or conditions. For
example, you can use the event_register_wdsysmon command to
register for the combination of conditions wherein the CPU usage of a certain process is
over 80 percent, and the memory used by the process is greater than 50 percent of its
initial allocation. This Tcl command extension is supported only in Software Modularity
images.

Arguments

timewin

(Optional) Time window within which all of the subevents have to occur in order for an event to be generated and is specified in SSSSSSSSSS[.MMM] format. SSSSSSSSSS format must be an integer representing seconds between 0 and 4294967295, inclusive. MMM format must be an integer representing milliseconds between 0 and 999).

(Optional) Node name to be monitored for deadlock conditions is a string that consists of the word ‘node’, which is followed by two fields separated by a slash (/) using the following format:

node<slot-number>/<cpu-number>

The slot-number is the hardware slot number. The cpu-number is the hardware CPU number. For example, the SP CPU in a Supervisor card on a Cisco Catalyst 6500 Series Switch located in slot 0 is specified as node0/0. The RP CPU in a Supervisor card on a Cisco Catalyst 6500 Series Switch located in slot 0 is addressed as node0/1. If the node argument is not specified, the default node specification is the local node on which the registration is done.

queue_priority

(Optional) Priority level at which the script is queued; normal priority is greater than low priority but less than high priority. The priority here is not execution priority, but queuing priority. If this argument is not specified, the default priority is normal.

maxrun

(Optional) Maximum run time of the script that is specified in SSSSSSSSSS[.MMM] format. SSSSSSSSSS format must be an integer representing seconds between 0 and 4294967295, inclusive. MMM format must be an integer representing milliseconds between 0 and 999. If this argument is not specified, the default 20-second run-time limit is used.

nice

(Optional) Policy run-time priority setting. When the nice argument is set to 1, the policy is run at a run-time priority that is less than the default priority. The default value is 0.

Subevents

The syntax of subevent descriptions can be one of seven cases.

For arguments in subevent description, the following constraints apply on the value of number arguments:

For dispatch_mgr, val must be an integer between 0 and 4294967295, inclusive.

For cpu_proc and cpu_tot, val must be an integer between 0 and 100, inclusive.

For mem_proc, mem_tot_avail, and mem_tot_used, if is_percent is FALSE, val must be an integer between 0 and 4294967295, inclusive.

deadlock procname ?

Arguments

procname

(Mandatory) Regular expression that specifies the process name that you want to monitor for deadlock conditions. This subevent ignores the time window even if it is given.

dispatch_mgr [procname ?] [op gt|ge|eq|ne|lt|le] [val ?] [period ?]

Arguments

procname

(Optional) Regular expression that specifies the process name that you want to monitor for the dispatch_manager status.

op

(Optional) Comparison operator that is used to compare the collected number of events with the specified value. If true, an event is raised.

val

(Optional) Value in which the number of events that have occurred is compared.

period

(Optional) Time period for the number of events that have occurred and is specified in SSSSSSSSSS[.MMM] format. SSSSSSSSSS format must be an integer representing seconds between 0 and 4294967295, inclusive. MMM format must be an integer representing milliseconds between 0 and 999. If this argument is not specified, the most recent sample is used.

cpu_proc [procname ?] [op gt|ge|eq|ne|lt|le] [val ?] [period ?]

Arguments

procname

(Optional) Regular expression that specifies the process name that you want to monitor for CPU utilization conditions.

op

(Optional) Comparison operator that is used to compare the collected CPU usage sample percentage with the specified percentage value. If true, an event is raised.

val

(Optional) Percentage value in which the average CPU usage during the sample period is compared.

period

(Optional) Time period for averaging the collection of samples and is specified in SSSSSSSSSS[.MMM] format. SSSSSSSSSS format must be an integer representing seconds between 0 and 4294967295, inclusive. MMM format must be an integer representing milliseconds between 0 and 999. If this argument is not specified, the most recent sample is used.

cpu_tot [op gt|ge|eq|ne|lt|le] [val ?] [period ?]

Arguments

op

(Optional) Comparison operator that is used to compare the collected total system CPU usage sample percentage with the specified percentage value. If true, an event is raised.

val

(Optional) Percentage value in which the average CPU usage during the sample period is compared.

period

(Optional) Time period for averaging the collection of samples and is specified in SSSSSSSSSS[.MMM] format. SSSSSSSSSS format must be an integer representing seconds between 0 and 4294967295, inclusive. MMM format must be an integer representing milliseconds between 0 and 999. If this argument is not specified, the most recent sample is used.

Arguments

(Optional) Regular expression that specifies the process name that you want to monitor for memory usage.

op

(Optional) Comparison operator that is used to compare the collected memory used with the specified value. If true, an event is raised.

val

(Optional) Percentage or an absolute value that is specified in kilobytes. A percentage represents the difference between the oldest sample in the specified time period and the latest sample. If memory usage increased from 150 KB to 300 KB within the time period, the percentage increase is 100. This is the value in which the measured value is compared.

is_percent

(Optional) If set to TRUE, the percentage value is collected and compared. Otherwise, the absolute value is collected and compared.

period

(Optional) If is_percent is set to TRUE, the time period for the percentage is computed. Otherwise, the time period for the collection samples is averaged and is specified in SSSSSSSSSS[.MMM] format. SSSSSSSSSS format must be an integer representing seconds between 0 and 4294967295, inclusive. MMM format must be an integer representing milliseconds between 0 and 999. If this argument is not specified, the most recent sample is used.

Arguments

op

(Optional) Comparison operator that is used to compare the collected available memory with the specified value. If true, an event is raised.

val

(Optional) Percentage or an absolute value that is specified in kilobytes. A percentage represents the difference between the oldest sample in the specified time period and the latest sample. If available memory usage has decreased from 300 KB to 150 KB within the time period, the percentage decrease is 50. This is the value in which the measured value is compared.

is_percent

(Optional) If set to TRUE, the percentage value is collected and compared. Otherwise, the absolute value is collected and compared.

period

(Optional) If is_percent is set to TRUE, the time period for the percentage is computed. Otherwise, the time period for the collection samples is averaged and is specified in SSSSSSSSSS[.MMM] format. SSSSSSSSSS format must be an integer representing seconds between 0 and 4294967295, inclusive. MMM format must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the most recent sample is used.

Arguments

op

(Optional) Comparison operator that is used to compare the collected used memory with the specified value. If true, an event is raised.

val

(Optional) Percentage or an absolute value that is specified in kilobytes. A percentage represents the difference between the oldest sample in the specified time period and the latest sample. If memory usage has increased from 150 KB to 300 KB within the time period, the percentage increase is 100. This is the value in which the measured value is compared.

is_percent

(Optional) If set to TRUE, the percentage value is collected and compared. Otherwise, the absolute value is collected and compared.

period

(Optional) If is_percent is set to TRUE, the time period for the percentage is computed. Otherwise, the time period for the collection samples is averaged and is specified in SSSSSSSSSS[.MMM] format. SSSSSSSSSS format must be an integer representing seconds between 0 and 4294967295, inclusive. MMM format must be an integer representing milliseconds between 0 and 999). If this argument is not specified, the most recent sample is used.

Note

This argument is mandatory if is_percent is set to TRUE; otherwise, it is optional.

Result String

None

Set _cerrno

No

Note

Inside a subevent description, each argument is position as independent.

Embedded Event Manager Event Information Tcl Command Extension

The following EEM Event Information Tcl Command Extensions are supported:

Assume that the
entry describes the scenario in which Process A thread m is blocked on process
B thread n:

Subevent
Type

Description

node

Name of
the node that process A thread m is on.

procname

Name of
process A.

pid

Process
ID of process A.

tid

Thread
ID of process A thread m.

state

Thread
state of process A thread m. Can be one of the following:

STATE_CONDVAR

STATE_DEAD

STATE_INTR

STATE_JOIN

STATE_MUTEX

STATE_NANOSLEEP

STATE_READY

STATE_RECEIVE

STATE_REPLY

STATE_RUNNING

STATE_SEM

STATE_SEND

STATE_SIGSUSPEND

STATE_SIGWAITINFO

STATE_STACK

STATE_STOPPED

STATE_WAITPAGE

STATE_WAITTHREAD

b_node

Name of
the node that process B thread is on.

b_procname

Name of
process B.

b_pid

Process
ID of process B.

b_tid

Thread
ID of process B thread n; 0 means that process A thread m is blocked on all
threads of process B.

For
dispatch_mgr Subevent

"{type %s node {%s} procname {%s} pid %u value %u sec %ld msec %ld}"

Subevent
Type

Description

type

Type of
wdsysmon subevent.

node

Name of
the node that the
POSIX process is
on.

procname

POSIX process
name for this subevent.

pid

POSIX process ID
for this subevent.

Note

The
three preceding fields describe the owner process of this dispatch manager.

value

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the number of events processed by the
dispatch manager is in the latest sample. If a time window is specified and is
greater than zero in the event registration Tcl command extension, the total
number of events processed by this dispatch manager is in the given time
window.

secmsec

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, they are both 0. If a time window is
specified and is greater than zero in the event registration Tcl command
extension, the sec and msec variables are the actual time difference between
the time stamps of the oldest and latest samples in this time window.

For cpu_proc
Subevent

"{type %s node {%s} procname {%s} pid %u value %u sec %ld msec %ld}"

Subevent
Type

Description

type

Type of
wdsysmon subevent.

node

Name of
the node that the
POSIX process is
on.

procname

POSIX process
name for this subevent.

pid

POSIX process ID
for this subevent.

Note

The
three preceding fields describe the process whose CPU utilization is being
monitored.

value

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the process CPU utilization is in the
latest sample. If a time window is specified and is greater than zero in the
event registration Tcl command extension, the averaged process CPU utilization
is in the given time window.

secmsec

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, they are both 0. If a time window is
specified and is greater than zero in the event registration Tcl command
extension, the sec and msec variables are the actual time difference between
the time stamps of the oldest and latest samples in this time window.

For cpu_tot
Subevent

"{type %s node {%s} value %u sec %ld msec %ld}"

Subevent
Type

Description

type

Type of
wdsysmon subevent.

node

Name of
the node on which the total CPU utilization is being monitored.

value

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the total CPU utilization is in the latest
sample. If a time window is specified and is greater than zero in the event
registration Tcl command extension, the averaged total CPU utilization is in
the given time window.

secmsec

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, they are both 0. If a time window is
specified and is greater than zero in the event registration Tcl command
extension, the sec and msec variables are the actual time difference between
the time stamps of the oldest and latest samples in this time window.

The
three preceding fields describe the process whose memory usage is being
monitored.

is_percent

Can be
either TRUE or FALSE. TRUE means that the value is a percentage value; FALSE
means that the value is an absolute value (may be an averaged value).

value

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the process used memory is in the latest
sample. If a time window is specified and is greater than zero in the event
registration Tcl command extension, the averaged process used memory
utilization is in the given time window.

diff

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the diff is the percentage difference
between the first process used memory sample ever collected and the latest
process used memory sample. If a time window is specified and is greater than
zero in the event registration Tcl command extension, the diff is the
percentage difference between the oldest and latest process used memory
utilization in the specified time window.

secmsec

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, they are both 0. If a time window is
specified and is greater than zero in the event registration Tcl command
extension, the sec and msec variables are the actual time difference between
the time stamps of the oldest and latest samples in this time window.

If the
is_percent
argument is FALSE, and the
sec and
msec
arguments are specified as 0 or are unspecified in the event registration Tcl
command extension:

value is the
process used memory in the latest sample.

diff is 0.

sec and
msec are both
0.

If the
is_percent
argument is FALSE, and a time window is specified as greater than zero in the
event registration Tcl command extension:

value is the
averaged process used memory sample value in the specified time window.

diff is 0.

sec and
msec are both
the actual time difference between the time stamps of the oldest and latest
samples in this time window.

If the
is_percent
argument is TRUE, and a time window is specified as greater than zero in the
event registration Tcl command extension:

value is 0.

diff is the
percentage difference between the oldest and latest process used memory samples
in the specified time window.

sec and
msec are the
actual time difference between the time stamps of the oldest and latest process
used memory samples in this time window.

If the
is_percent
argument is TRUE, and the
sec and
msec
arguments are specified as 0 or are unspecified in the event registration Tcl
command extension:

value is 0.

diff is the
percentage difference between the first process used memory sample ever
collected and the latest process used memory sample.

sec and
msec are the
actual time difference between the time stamps of the first process used memory
sample ever collected and the latest process used memory sample.

For
mem_tot_avail Subevent

Name of
the node for which the total available memory is being monitored.

is_percent

Can be
either TRUE or FALSE. TRUE means that the value is a percentage value; FALSE
means that the value is an absolute value (may be an averaged value).

used

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the total used memory is in the latest
sample. If a time window is specified and is greater than zero in the event
registration Tcl command extension, the averaged total used memory utilization
is in the given time window.

avail

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the avail is in the latest total available
memory sample. If a time window is specified and is greater than zero in the
event registration Tcl command extension, the avail is the total available
memory utilization in the specified time window.

diff

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the diff is the percentage difference
between the first total available memory sample ever collected and the latest
total available memory sample. If a time window is specified and is greater
than zero in the event registration Tcl command extension, the diff is the
percentage difference between the oldest and latest total available memory
utilization in the specified time window.

secmsec

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, they are both 0. If a time window is
specified and is greater than zero in the event registration Tcl command
extension, they are the actual time difference between the time stamps of the
oldest and latest samples in this time window.

If the
is_percent
argument is FALSE, and the sec and msec arguments are specified as 0 or are
unspecified in the event registration Tcl command extension:

used is the
total used memory in the latest sample.

avail is the
total available memory in the latest sample.

diff is 0.

sec and
msec are
both 0.

If the
is_percent
argument is FALSE, and a time window is specified as greater than zero in the
event registration Tcl command extension:

used is 0.

avail is the
averaged total available memory sample value in the specified time window.

diff is 0.

sec and
msec are both
the actual time difference between the time stamps of the oldest and latest
total available memory samples in this time window.

If the
is_percent
argument is TRUE, and a time window is specified as greater than zero in the
event registration Tcl command extension:

used is 0.

avail is 0.

diff is the
percentage difference between the oldest and latest total available memory
samples in the specified time window.

sec and
msec are both
the actual time difference between the time stamps of the oldest and latest
total available memory samples in this time window.

If the
is_percent
argument is TRUE, and the
sec and
msec
arguments are specified as 0 or are unspecified in the event registration Tcl
command extension:

used is 0.

avail is 0.

diff is the
percentage difference between the first total available memory sample ever
collected and the latest total available memory sample.

sec and msec
are the actual time difference between the time stamps of the first total
available memory sample ever collected and the latest total available memory
sample.

Can be
either TRUE or FALSE. TRUE means that the value is a percentage value; FALSE
means that the value is an absolute value (may be an averaged value).

used

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the total used memory is in the latest
sample. If a time window is specified and is greater than zero in the event
registration Tcl command extension, the averaged total used memory utilization
is in the given time window.

avail

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the avail is in the latest total used
memory sample. If a time window is specified and is greater than zero in the
event registration Tcl command extension, the avail is the total used memory
utilization in the specified time window.

diff

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, the diff is the percentage difference
between the first total used memory sample ever collected and the latest total
used memory sample. If a time window is specified and is greater than zero in
the event registration Tcl command extension, the diff is the percentage
difference between the oldest and latest total used memory utilization in the
specified time window.

secmsec

If the
sec and msec variables are specified as 0 or are unspecified in the event
registration Tcl command extension, they are both 0. If a time window is
specified and is greater than zero in the event registration Tcl command
extension, the sec and msec variables are the actual time difference between
the time stamps of the oldest and latest samples in this time window.

If the
is_percent
argument is FALSE, and the
sec and
msec
arguments are specified as 0 or are unspecified in the event registration Tcl
command extension:

used is the
total used memory in the latest sample,

avail is the
total available memory in the latest sample,

diff is 0,

sec and
msec are both
0,

If the
is_percent
argument is FALSE, and a time window is specified as greater than zero in the
event registration Tcl command extension:

used is the
averaged total used memory sample value in the specified time window,

avail is 0,

diff is 0,

sec and
msec are both
the actual time difference between the time stamps of the oldest and latest
total used memory samples in this time window,

If the
is_percent
argument is TRUE, and a time window is specified as greater than zero in the
event registration Tcl command extension:

used is 0.

avail is 0.

diff is the
percentage difference between the oldest and latest total used memory samples
in the specified time window.

sec and
msec are both
the actual time difference between the time stamps of the oldest and latest
total used memory samples in this time window.

If the
is_percent
argument is TRUE, and the sec and msec arguments are specified as 0 or are
unspecified in the event registration Tcl command extension:

used is 0.

avail is 0.

diff is the
percentage difference between the first total used memory sample ever collected
and the latest total used memory sample.

sec and
msec are the
actual time difference between the time stamps of the first total used memory
sample ever collected and the latest total used memory sample.

Set
_cerrno

Yes

event_reqinfo_multi

Adds a new function
to retrieve the event_reqinfo data for every event that contributed to the
triggering of the script. The data returned will be a list of result strings
indexed by event specification tag. Error processing is the same as in
event_reqinfo function.

Syntax

event_reqinfo_multi

Arguments

None

Result
String

The following
section shows the result string from the event reqinfo multi call:

Embedded Event Manager Event Publish Tcl Command Extension

event_publish
appl

Syntax

Arguments

(Mandatory) Number assigned to the EEM policy that published the
application-specific event. Number is set to 798 because all other numbers are
reserved for Cisco use.

type

(Mandatory) Event subtype within the specified component. The
sub_system and type arguments uniquely identify an application event. Must be
an integer between 1 and 4294967295, inclusive.

[arg1
?]-[arg4 ?]

(Optional)
Four pieces of application event publisher string data.

Result
String

None

Set
_cerrno

Yes

(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)

This error means
that the operating system reported an error. The
POSIX errno
value that is reported with the error should be used to determine the cause of
the operating system error.

Sample
Usage

This example
demonstrates how to use the
event_publish
appl Tcl command extension to execute a script
n times
repeatedly to perform some function (for example, to measure the amount of CPU
time taken by a given group of Tcl statements). This example uses two Tcl
scripts.

Script1 publishes a
type 9999 EEM event to cause Script2 to run for the first time. Script1 is
registered as a none event and is run using the
Cisco IOS XR software CLI
event manager
run command. Script2 is registered as an EEM application event of
type 9999, and this script checks to see if the application publish arg1 data
(the iteration number) exceeds the EEM environment variable test_iterations
value. If the test_iterations value is exceeded, the script writes a message
and exits; otherwise the script executes the remaining statements and
reschedules another run. To measure the CPU utilization for Script2, use a
value of test_iterations that is a multiple of 10 to calculate the amount of
average CPU time used by Script2.

To run the Tcl
scripts, enter the following
Cisco IOS XR software commands:

The Tcl script
Script2 is executed 100 times. If you execute the script without the extra
processing and derive the average CPU utilization, and then add the extra
processing and repeat the test, you can subtract the former CPU utilization
from the later CPU utilization to determine the average for the extra
processing.

Attribute

Syntax

Arguments

Specifies a tag using the event-tag argument that can be used with the attribute command to associate an event.

occurs

(Optional) Specifies the number of occurrences before an EEM event is triggered. If not specified, an EEM event is triggered on the first occurrence. The range is from 1 to 4294967295

Result String

None

Example:

attribute tag 1 occurs 1

Correlate

Builds a single complex event and allows Boolean logic to relate events.

Syntax

correlate event ? event ?

Arguments

event

Specifies the event that can be used with the trigger command to support multiple event statements within an script.

If the event associated with the event-tag argument occurs for the number of times specified by the trigger command, the result is true. If not, the result is false.

andnot

(Optional) Specifies that if event 1 occurs the action is executed, and if event 2 and event 3 occur together the action is not executed.

and

(Optional) Specifies that if event 1 occurs the action is executed, and if event 2 and event 3 occur together the action is executed.

or

(Optional) Specifies that if event 1 occurs the action is executed, or else if event 2 and event 3 occur together the action is executed.

Result String

None

Example:

correlate event 1 or event 2 and event 3

Trigger

Specifies the multiple event configuration ability of Embedded Event Manager (EEM) events. A multiple event is one that can involve one or more event occurrences and a time period for the event to occur. The events are raised based on the specified parameters.

Syntax

trigger [occurs ?] [period ?] [period-start ?] [delay ?]

Arguments

occurs

(Optional) Specifies the number of times the total correlation occurs before an EEM event is raised. When a number is not specified, an EEM event is raised on the first occurrence. The range is from 1 to 4294967295.

period

(Optional) Time interval in seconds and optional milliseconds, during which the one or more occurrences must take place. This is specified in the format ssssssssss[.mmm], where ssssssssss must be an integer number representing seconds between 0 and 4294967295, inclusive and mmm represents milliseconds and must be an integer number between 0 to 999.

period-start

(Optional) Specifies the start of an event correlation window. If not specified, event monitoring is enabled after the first CRON period occurs.

delay

(Optional) Specifies the number of seconds and optional milliseconds after which an event will be raised if all the conditions are true (specified in the format ssssssssss[.mmm], where ssssssssss must be an integer number representing seconds between 0 and 4294967295, inclusive and mmm represents milliseconds and must be an integer number between 0 to 999).

Currently there are
no
Cisco IOS XR software processes that publish application
volatile data.

Syntax

appl_read name ? length ?

Arguments

name

(Mandatory) Name of the application published string data.

length

(Mandatory) Length of the string data to read. Must be an
integer number between 1 and 4294967295, inclusive.

Result
String

data %s

Where data is the
application published string data to be read.

Set
_cerrno

Yes

(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)

This error means
that the operating system reported an error. The POSIX errno
value that is reported with the error should be used to determine the cause of
the operating system error.

(_cerr_sub_err = 7) FH_ENOSUCHKEY (could not find key)

This error means
that the application event detector info key or other ID was not found.

(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)

This error means
that an internal EEM request for memory failed.

appl_reqinfo

Retrieves previously
saved information from the Embedded Event Manager (EEM). This Tcl command
extension provides support for retrieving information from EEM that has been
previously saved with a unique key, which must be specified in order to
retrieve the information. Note that retrieving the information deletes it from
EEM. It must be resaved if it is to be retrieved again.

Syntax

appl_reqinfo key ?

Arguments

key

(Mandatory) String key of the data.

Result
String

data %s

Where data is the
application string data to be retrieved.

Set
_cerrno

Yes

(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)

This error means
that the operating system reported an error. The
POSIX errno
value that is reported with the error should be used to determine the cause of
the operating system error.

(_cerr_sub_err = 7) FH_ENOSUCHKEY (could not find key)

This error means
that the application event detector info key or other ID was not found.

appl_setinfo

Saves information in
the EEM. This Tcl command extension provides support for saving information in
the EEM that can be retrieved later by the same policy or by another policy. A
unique key must be specified. This key allows the information to be retrieved
later.

Syntax

appl_setinfo key ? data ?

Arguments

key

(Mandatory) String key of the data.

data

(Mandatory) Application string data to save.

Result
String

None

Set
_cerrno

Yes

(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)

This error means
that the operating system reported an error. The
POSIX errno
value that is reported with the error should be used to determine the cause of
the operating system error.

(_cerr_sub_err = 8) FH_EDUPLICATEKEY (duplicate appl info key)

This error means
that the application event detector info key or other ID was a duplicate.

(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)

This error means
that an internal EEM request for memory failed.

(_cerr_sub_err = 34) FH_EMAXLEN (maximum length exceeded)

This error means
that the object length or number exceeded the maximum.

(_cerr_sub_err = 43) FH_EBADLENGTH (bad API length)

This error means
that the API message length was invalid.

counter_modify

Modifies a counter
value.

Syntax

counter_modify event_id ? val ? op nop|set|inc|dec

Arguments

event_id

(Mandatory) Counter event ID returned by the
register_counter Tcl command extension. Must be an
integer between 0 and 4294967295, inclusive.

val

(Mandatory)

If op
is set, this argument represents the counter value that is to be set.

If op
is inc, this argument is the value by which to increment the counter.

If op
is dec, this argument is the value by which to decrement the counter.

op

(Mandatory)

nop—Retrieves the current counter value.

set—Sets the counter value to the given value.

inc—Increments the counter value by the given value.

dec—Decrements the counter value by the given value.

Result
String

val_remain %d

Where val_remain is
the current value of the counter.

Set
_cerrno

Yes

(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)

This error means
that the operating system reported an error. The
POSIX errno
value that is reported with the error should be used to determine the cause of
the operating system error.

(_cerr_sub_err = 11) FH_ENOSUCHESID (unknown event specification ID)

This error means
that the event specification ID could not be matched when the event was being
registered or that an event detector internal event structure is corrupt.

This error means
that an internal EEM event detector pointer was null when it should have
contained a value.

(_cerr_sub_err = 30) FH_ECTBADOPER (bad counter threshold operator)

This error means
that the counter event detector set or modify operator was invalid.

fts_get_stamp

Returns the time period elapsed since the last software boot. Use this Tcl command extension to return the number of nanoseconds since boot in an array “nsec nnnn” where nnnn is the number of nanoseconds.

Syntax

fts_get_stamp

Arguments

None

Result String

nsec %d

Where nsec is the number of nanoseconds since boot.

Set _cerrno

No

register_counter

Registers a counter
and returns a counter event ID. This Tcl command extension is used by a counter
publisher to perform this registration before using the event ID to manipulate
the counter.

Syntax

register_counter name ?

Arguments

name

(Mandatory) The name of the counter to be manipulated.

Result
String

event_id %d
event_spec_id %d

Where event_id is
the counter event ID for the specified counter; it can be used to manipulate
the counter by the
unregister_counter or
counter_modify
Tcl command extensions. The event_spec_id argument is the event specification
ID for the specified counter.

Set
_cerrno

Yes

(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)

This error means
that the operating system reported an error. The
POSIX errno
value that is reported with the error should be used to determine the cause of
the operating system error.

This error means
that the EEM event detector that handles this request is not available.

register_timer

Registers a timer and
returns a timer event ID. This Tcl command extension is used by a timer
publisher to perform this registration before using the event ID to manipulate
the timer if it does not use the
event_register_timer command extension to register
as a publisher and subscriber.

Syntax

register_timer watchdog|countdown|absolute|cron name ?

Arguments

name

(Mandatory) Name of the timer to be manipulated.

Result
String

event_id %u

Where event_id is
the timer event ID for the specified timer (can be used to manipulate the timer
by the
timer_arm or
timer_cancel
command extensions).

Set
_cerrno

Yes

(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)

This error means
that the operating system reported an error. The
POSIX errno
value that is reported with the error should be used to determine the cause of
the operating system error.

This error means
that the EEM event detector that handles this request is not available.

timer_arm

Arms a timer. The type
could be CRON, watchdog, countdown, or absolute.

Syntax

timer_arm event_id ? cron_entry ?|time ?

Arguments

event_id

(Mandatory)Timer event ID returned by the
register_timer
command extension. Must be an integer between 0 and 4294967295, inclusive.

cron_entry

(Mandatory) Must exist if the timer type is CRON. Must not exist
for other types of timer. CRON timer specification uses the format of the CRON
table entry.

time

(Mandatory) Must exist if the timer type is not CRON. Must not
exist if the timer type is CRON. For watchdog and countdown timers, the number
of seconds and milliseconds until the timer expires; for an absolute timer, the
calendar time of the expiration time (specified in SSSSSSSSSS[.MMM] format,
where SSSSSSSSSS must be an integer representing seconds between 0 and
4294967295, inclusive, and where MMM must be an integer representing
milliseconds between 0 and 999). An absolute expiration date is the number of
seconds and milliseconds since January 1, 1970. If the date specified has
already passed, the timer expires immediately.

Result
String

sec_remain %ld msec_remain %ld

Where sec_remain and
msec_remain are the remaining time before the next expiration of the timer.

Note

A value of 0 is
returned for the sec_remain and msec_remain arguments if the timer type is
CRON.

Set
_cerrno

Yes

(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)

This error means
that the operating system reported an error. The
POSIX errno
value that is reported with the error should be used to determine the cause of
the operating system error.

(_cerr_sub_err = 6) FH_EBADEVENTTYPE (unknown EEM event type)

This error means
that the event type specified in the internal event specification was invalid.

(_cerr_sub_err = 9) FH_EMEMORY (insufficient memory for request)

This error means
that an internal EEM request for memory failed.

(_cerr_sub_err = 11) FH_ENOSUCHESID (unknown event specification ID)

This error means
that the event specification ID could not be matched when the event was being
registered or that an event detector internal event structure is corrupt.

(_cerr_sub_err = 12) FH_ENOSUCHEID (unknown event ID)

This error means
that the event ID could not be matched when the event was being registered or
that an event detector internal event structure is corrupt.

sys_reqinfo_cpu_all

Queries the CPU
utilization of the top processes
(both POSIX
processes and IOS processes) during a specified time period and in a
specified order. This Tcl command extension is supported only in Software
Modularity images.

Syntax

sys_reqinfo_cpu_all order cpu_used [sec ?] [msec ?] [num ?]

Arguments

order

(Mandatory) Order used for sorting the CPU utilization of
processes.

cpu_used

(Mandatory) Specifies that the average CPU utilization, for the
specified time window, will be sorted in descending order.

secmsec

(Optional)
Time period, in seconds and milliseconds, during which the average CPU
utilization is calculated. Must be integers in the range from 0 to 4294967295.
If not specified, or if both sec and msec are specified as 0, the most recent
CPU sample is used.

num

(Optional)
Number of entries from the top of the sorted list of processes to be displayed.
Must be an integer in the range from 1 to 4294967295. Default value is 5.

Specifies
that if sec and msec are specified with a number greater than zero, the average
percentage is calculated from the process CPU utilization during the specified
time period. If sec and msec are both zero or not specified, the average
percentage is calculated from the process CPU utilization in the latest sample.

Set
_cerrno

Yes

sys_reqinfo_crash_history

Queries the crash information of all processes that have ever crashed. This Tcl command extension is supported only in Software Modularity images.

Syntax

Arguments

(Mandatory) Specifies that the memory usage is sorted by the
number of process allocations during the specified time window, and in
descending order.

increase

(Mandatory) Specifies that the memory usage is sorted by the
percentage of process memory increase during the specified time window, and in
descending order.

used

(Mandatory) Specifies that the memory usage is sorted by the
current memory used by the process.

secmsec

(Optional)
Time period, in seconds and milliseconds, during which the process memory usage
is calculated. Must be integers in the range from 0 to 4294967295. If both sec
and msec are specified and are nonzero, the number of allocations is the
difference between the number of allocations in the oldest and latest samples
collected in the time period. The percentage is calculated as the the
percentage difference between the memory used in the oldest and latest samples
collected in the time period. If not specified, or if both sec and msec are
specified as 0, the first sample ever collected is used as the oldest sample;
that is, the time period is set to be the time from startup until the current
moment.

num

(Optional)
Number of entries from the top of the sorted list of processes to be displayed.
Must be an integer in the range from 1 to 4294967295. Default value is 5.

Specifies
the difference between the number of allocations in the oldest and latest
samples collected in the time period.

initial_alloc

Specifies
the amount of memory, in kilobytes, used by the process at the start of the
time period.

current_alloc

Specifies
the amount of memory, in kilobytes, currently used by the process.

percent_increase

Specifies
the percentage difference between the memory used in the oldest and latest
samples collected in the time period. The percentage difference can be
expressed as current_alloc minus initial_alloc times 100 and divided by
initial_alloc.

Set
_cerrno

Yes

sys_reqinfo_proc

Queries the information about a single POSIX process. This Tcl command extension is supported only in Software Modularity images.

Syntax

sys_reqinfo_proc job_id ?

Arguments

job_id

(Mandatory) System manager assigned job ID for the process. Must be an integer between 1 and 4294967295, inclusive.

Syntax

Arguments

(Mandatory) Type of SNMP get operation that needs to be applied to the specified oid. If the get_type is "exact," the value of the specified oid is retrieved; if the get_type is "next," the value of the lexicographical successor to the specified oid is retrieved.

SMTP Library Command Extensions

To use this library, the user needs to provide an e-mail template file. The template file
can include Tcl global variables so that the e-mail service and the e-mail text can be
configured through the event manager environmentCisco IOS XR software command-line interface (CLI)
configuration command. There are commands in this library to substitute the global
variables in the e-mail template file and to send the desired e-mail context with the To
address, CC address, From address, and Subject line properly configured using the
configured e-mail server.

smtp_subst

Given an e-mail template file e-mail_template, substitutes each global variable in the file by its user-defined value. Returns the text of the file after substitution.

Syntax

smtp_subst e-mail_template

Arguments

e-mail_template

(Mandatory) Name of an e-mail template file in which global variables need to be substituted by a user-defined value. An example filename could be /disk0://example.template which represents a file named example.template in a top-level directory on an ATA flash disk in slot 0.

Result String

The text of the e-mail template file with all the global variables substituted.

Set _cerrno

cannot open e-mail template file

cannot close e-mail template file

CLI Library Command Extensions

This library provides users the ability to run CLI commands and get the output of the commands in Tcl. Users can use commands in this library to spawn an exec and open a virtual terminal channel to it, write the command to execute to the channel so that the command will be executed by exec, and read back the output of the command.

There are two types of CLI commands: interactive commands and non-interactive commands.

For interactive commands, after the command is entered, there will be a “Q&A” phase in which the router will ask for different user options, and the user is supposed to enter the answer for each question. Only after all the questions have been answered properly will the command run according to the user’s options until completion.

Exported Tcl Command Extensions

cli_close

Closes the exec process and releases the VTY and the specified channel handler connected to the command-line interface (CLI).

Syntax

cli_close fd tty_id

Arguments

fd

(Mandatory) The CLI channel handler.

tty_id

(Mandatory) The TTY ID returned from the
cli_open command extension.

Result String

None

Set _cerrno

Cannot close the channel.

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.

Syntax

cli_exec fd cmd

Arguments

fd

(Mandatory) The command-line interface (CLI) channel handler.

cmd

(Mandatory) The CLI command to execute.

Result String

The output of the CLI command executed.

Set _cerrno

Error reading the channel.

cli_get_ttyname

Returns the real and pseudo tty names for a given TTY ID.

Syntax

cli_get_ttyname tty_id

Arguments

tty_id

(Mandatory) The TTY ID returned from the
cli_open command extension.

Result String

pty %s tty %s

Set _cerrno

None

cli_open

Calls vty_connect to
open a vty channel to an EXEC session and passes the username and associated taskmap value
for the script to be executed. The EXEC session first attempts to authorize the user using
whichever AAA method was configured for the EEM vty pool. If this fails, the EXEC session
attempts to authorize the user using the taskmap value. Returns an array including the vty
channel handler.

Note

To configure authorization methods for the EEM vty pool, you must configure an AAA method list, create a vty line template for the EEM vty pool, enable the AAA method list on the vty line template, and configure the EEM vty pool to use the vty line template you created. For information about AAA authorization configuration, see Configuring AAA Services module of Cisco IOS XR System Security Configuration Guide for the
Cisco CRS Router.

Note

Each call to cli_open initiates a Cisco IOS XR software EXEC session that allocates
a Cisco IOS XR software vty. The vty remains in
use until the cli_close routine is called. Vtys are allocated from the pool of vtys that
are configured using the line vtyvty-pool CLI configuration command. Be aware that the cli_open
routine fails when two or fewer vtys are available, preserving the remaining vtys for
Telnet use.

Syntax

cli_open

Arguments

None

Result String

"tty_id {%s} pty {%d} tty {%d} fd {%d}"

Event Type

Description

tty_id

TTY ID.

pty

PTY device name.

tty

TTY device name.

fd

CLI channel handler.

Set _cerrno

Cannot get pty for EXEC.

Cannot create an EXEC CLI session.

Error reading the first prompt.

cli_read

Reads the command output from the specified command-line interface (CLI) channel handler until the pattern of the router prompt occurs in the contents read. Returns all the contents read up to the match.

Syntax

cli_read fd

Arguments

fd

(Mandatory) CLI channel handler.

Result String

All the contents read.

Set _cerrno

Cannot get router name.

Note

This Tcl command extension blocks waiting for the router prompt to show up in the contents read.

cli_read_drain

Reads and drains the command output of the specified command-line interface (CLI) channel handler. Returns all the contents read.

Syntax

cli_read_drain fd

Arguments

fd

(Mandatory) The CLI channel handler.

Result String

All the contents read.

Set _cerrno

None

cli_read_line

Reads one line of the command output from the specified command-line interface (CLI) channel handler. Returns the line read.

Syntax

cli_read_line fd

Arguments

fd

(Mandatory) CLI channel handler.

Result String

The line read.

Set _cerrno

None

Note

This Tcl command extension blocks waiting for the end of line to show up in the contents read.

cli_read_pattern

Reads the command output from the specified command-line interface (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.

Note

The pattern matching logic attempts a match by looking at the command output data as it is delivered from the Cisco IOS XR software command. The match is always done on the most recent 256 characters in the output buffer unless there are fewer characters available, in which case the match is done on fewer characters. If more than 256 characters in the output buffer are required for the match to succeed, the pattern will not match.

Syntax

cli_read_pattern fd ptn

Arguments

fd

(Mandatory) CLI channel handler.

ptn

(Mandatory) Pattern to be matched when reading the command output from the channel.

Result String

All the contents read.

Set _cerrno

None

Note

This Tcl command extension blocks waiting for the specified pattern to show up in the contents read.

cli_write

Writes the command that is to be executed to the specified CLI channel handler. The CLI channel handler executes the command.

Syntax

cli_write fd cmd

Arguments

fd

(Mandatory) The CLI channel handler.

cmd

(Mandatory) The CLI command to execute.

Result String

None

Set _cerrno

None

Sample Usage

As an example, use configuration CLI commands to bring up Ethernet interface 1/0:

Using the CLI Library to Run a Noninteractive Command

To run a noninteractive command, use the cli_exec command
extension to issue the command, and then wait for the complete output and the router
prompt. For example, the following shows the use of configuration CLI commands to
bring up Ethernet interface 1/0:

Using the CLI Library to Run an Interactive Command

To run interactive commands, three phases are needed:

Phase 1: Issue the command using the cli_write command
extension.

Phase 2: Q&A Phase. Use the cli_read_pattern command
extension to read the question (the regular pattern that is specified to
match the question text) and the cli_write command
extension to write back the answers alternately.

Phase 3: Noninteractive phase. All questions have been answered, and the command
will run to completion. Use the cli_read command
extension to wait for the complete output of the command and the router
prompt.

For example, use CLI commands to do squeeze bootflash: and save the output of this command in the Tcl variable cmd_output.

The following example causes a router to be reloaded using the CLI
reload command. Note that the EEM
action_reload command accomplishes the same result
in a more efficient manner, but this example is presented to illustrate the
flexibility of the CLI library for interactive command execution.

Tcl Context Library Command Extensions

Exported Commands

context_retrieve

Retrieves Tcl
variable(s) identified by the given context name, and possibly the scalar
variable name, the array variable name, and the array index. Retrieved
information is automatically deleted.

Note

Once saved
information is retrieved, it is automatically deleted. If that information is
needed by another policy, the policy that retrieves it (using the
context_retrieve command extension) should also
save it again (using the
context_save
command extension).

Syntax

context_retrieve ctxt [var] [index_if_array]

Arguments

ctxt

(Mandatory) Context name.

var

(Optional)
Scalar variable name or array variable name. Defaults to a null string if this
argument is not specified.

index_if_array

(Optional)
Array index.

Note

The
index_if_array
argument is ignored when the
var argument is
a scalar variable.

If
var is
unspecified, retrieves the whole variable table saved in the context.

If
var is
specified and
index_if_array
is not specified, or if
index_if_array
is specified but
var is a scalar
variable, retrieves the value of
var.

If
var is
specified, and
index_if_array
is specified, and
var is an array
variable, retrieves the value of the specified array element.

Result
String

Resets the Tcl
global variables to the state that they were in when the save was performed.

context_save

Saves Tcl variables
that match a given pattern in current and global namespaces with the given
context name as identification. Use this Tcl command extension to save
information outside of a policy. Saved information can be retrieved by a
different policy using the
context_retrieve command extension.

Note

Once saved
information is retrieved, it is automatically deleted. If that information is
needed by another policy, the policy that retrieves it (using the
context_retrieve command extension) should also
save it again (using the
context_save
command extension).

Syntax

context_save ctxt [pattern]

Arguments

ctxt

(Mandatory) Context name.

pattern

(Optional)
Glob-style pattern as used by the
string match
Tcl command. If this argument is not specified, the pattern defaults to the
wildcard *.