Configuring an Event Policy to Execute Operational Mode Commands

Operational mode commands request that the device running Junos OS perform an operation or provide diagnostic output. They allow you to view statistics and information about a device’s current operating status. They also allow you to take corrective actions, such as restarting software processes, taking a PIC offline and back online, switching to redundant interfaces, and adjusting Label Switching Protocol (LSP) bandwidth. For more information about operational mode commands, see the following references:

Junos Interfaces Command Reference
Junos Routing Protocols and Policies Command Reference
Junos System Basics and Services Command Reference

You can configure a policy that causes operational mode commands to be issued and the output of those commands to be uploaded to a specified location for analysis.

To configure such a policy, include the following statements at the [edit event-options] hierarchy level:

[edit event-options]policy policy-name {events [ events ];then {execute-commands {commands {"command";}output-filename filename;output-format (text | xml);destination destination-name;}}}

In the events statement, you can list multiple events. If one or more of the listed events occurs, the operational mode commands are issued. To view a list of the events that can be referenced in an event policy, issue the set event-options policy policy-name events ? configuration mode command:

[edit]user@host# set event-options policy policy-name events ?Possible completions: <event> [ Open a set of values acct_accounting_ferror acct_accounting_fopen_error ...

Some of the system log messages that you can reference in an event policy are not listed in the output of the set event-options policy policy-name events ? command. For information about referencing these system log messages in your event policies, see Using Nonstandard System Log Messages to Trigger Event Policies.

In addition, you can reference internally generated events, which are discussed in Generating Internal Events to Trigger Event Policies.

In the commands statement, you can issue multiple operational mode commands upon receipt of a specific event. Enclose each command in quotation marks (“ ”). The eventd process issues the commands in the order in which they appear in the configuration. For example, in the following configuration, the execution of policy1 causes the show interfaces command to be issued first, followed by the show chassis alarms command:

[edit event-options policy policy1 then execute-commands]user@host# showcommands {"show interfaces";"show chassis alarms";}

You can include variables in the command to allow data from the triggering event to be automatically included in the command syntax. The eventd process replaces each variable with values contained in the event that triggers the policy. You can use command variables of the following forms:

{$$.attribute-name}—The double dollar sign ($$) notation represents the event that is triggering a policy. When combined with an attribute name, the variable is replaced by the value of the attribute name in the triggering event. For example, {$$.interface-name} stands for the value of the interface-name attribute in the triggering event.
{$event.attribute-name}—The {$event.attribute-name} notation represents the most recent event that matches the specified event. The variable is replaced by the value of the attribute name of the most recent event that matches event. For example, when a policy issues the show interfaces {$COSD_CHAS_SCHED_MAP_INVALID.interface-name} command, the {$COSD_CHAS_SCHED_MAP_INVALID.interface-name} variable is substituted by the interface-name attribute of the most recent COSD_CHAS_SCHED_MAP_INVALID event cached by the event process.

For a given event, you can view a list of event attributes that you can reference in an operational mode command by issuing the help syslog event-name command:

user@host> help syslog event-name

For example, in the following command output, text in angle brackets (< >) shows that classifier-type is an attribute of the cosd_unknown_classifier event:

user@host> help syslog cosd_unknown_classifier

Name:          COSD_UNKNOWN_CLASSIFIER
Message:       rtsock classifier type <classifier-type> is invalid
...

You can filter the output of a search by using the pipe (|) symbol. The following example lists the filters that can be used with the pipe symbol:

user@host# help syslog | ?

Possible completions:
  count                Count occurrences
  display              Show additional kinds of information
  except               Show only text that does not match a pattern
  find                 Search for first occurrence of pattern
  hold                 Hold text without exiting the --More-- prompt
  last                 Display end of output only
  match                Show only text that matches a pattern
  no-more              Don't paginate output
  request              Make system-level requests
  resolve              Resolve IP addresses
  save                 Save output text to file
  trim                 Trim specified number of columns from start of line

For more information about using the pipe symbol, see the Junos CLI User Guide.

Another way to view a list of event attributes is to issue the set attributes-match event? configuration mode command at the [edit event-options policy policy-name] hierarchy level:

[edit event-options policy policy-name]user@host# set attributes-match event ?

For example, in the following command output, the event.attribute list shows that classifier-type is an attribute of the cosd_unknown_classifier event:

[edit event-options policy policy-name]
user@host# set attributes-match cosd_unknown_classifier?
Possible completions:
  <from-event-attribute>  First attribute to compare
  cosd_unknown_classifier.classifier-type

Note: In this set command, there is no space between the event name and the question mark (?).

To view a list of all events that you can reference, issue the set attributes-match ? configuration mode command at the [edit event-options policy policy-name] hierarchy level:

[edit event-options policy policy-name]
user@host# set attributes-match ?
Possible completions:
  <from-event-attribute>  First attribute to compare
  acct_accounting_ferror
  acct_accounting_fopen_error
  ...

In the output-filename statement, assign the name of the file to which to write command output for the specified commands. The filename format is hostname_filename_YYYYMMDD_HHMMSS_index-number.

For each uploaded file, a hostname and timestamp ensure that the uploaded files have unique filenames. If a policy is triggered multiple times in a 1-second period, an index number is added to ensure the filenames are unique. The index number range is 001 through 999.

For example, on a device named r1, if you configure the output filename to be ifl-events, and this event policy is triggered three times in 1 second, the files are named:

r1_ifl-events_20060623_132333
r1_ifl-events_20060623_132333_001
r1_ifl-events_20060623_132333_002

By default, the command output format is Junos Extensible Markup Language (XML). To change this, include the output-format text statement. This causes the command output to be in formatted ASCII text.

In the destination statement, include the destination name that you configured at the [edit event-options destinations] hierarchy level. For more information, see Defining Destinations for File Archiving by Event Policies.

For a configuration example, see Example: Correlating Events Based on Receipt of Other Events Within a Specified Time Interval.