[Contents] [Prev] [Next] [Index] [Report an Error]

Executing Event Scripts in an Event Policy

Event scripts are Extensible Stylesheet Transformation (XSLT) or Stylesheet Language Alternative Syntax (SLAX) scripts that you write and that are run when triggered by an event policy. Event scripts can perform any function available through JUNOS XML or JUNOScript remote procedure calls (RPCs). Additionally, you can pass to an event script a set of arguments that you define.

A script can change the router configuration, build and run an operational mode command, receive the command output, inspect the output, and determine the next appropriate action. This process can be repeated until the source of the problem is determined. The script can then report the source of the problem to you on the CLI.

You can run an event script by configuring an event policy that causes event scripts to be run and the output of those scripts 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 {



event-script filename {



arguments {

parameter-name parameter-value;
}



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 event script is executed. 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:



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 Referencing Nonstandard Events.

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

In the event-script statement, you can specify a script to be executed on receipt of an event. The eventd process runs the scripts in the order in which they appear in the configuration. The scripts that you reference in the event-script statement must be located in the /var/db/scripts/event directory when event scripts are located on the router's hard drive and in the /config/scripts/event directory when event scripts are located in the flash drive. For more information on event script file location, see How Op Scripts Work.Furthermore, the event scripts must be enabled at the [edit event-options event-script file] hierarchy level. For more information, see Installing Op Scripts to a Router and Event Policy Examples.

You can include arguments to the script as name/value pairs. You can include variables in the argument values to allow data from the triggering event to be automatically included in the argument. The eventd process replaces each variable with values contained in the event that triggers the policy. You can use 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 you include an argument called interface and define the value as {$COSD_CHAS_SCHED_MAP_INVALID.interface-name}, the {$COSD_CHAS_SCHED_MAP_INVALID.interface-name} variable is replaced by the interface-name attribute of the most recent COSD_CHAS_SCHED_MAP_INVALID event cached by the eventd process.

For a given event, you can view a list of event attributes that you can reference by issuing the help syslog event command:



user@host> help syslog event-name

For example, in the following command output, text in angle brackets (< >) shows attributes of the COSD_CHASSIS_SCHEDULER_MAP_INVALID event:



user@host> help syslog COSD_CHASSIS_SCHEDULER_MAP_INVALID

Name:        COSD_CHASSIS_SCHEDULER_MAP_INVALID
Message:     Chassis scheduler map incorrectly applied to interface <interface-name>: <error-message>
...

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 error-message and interface-name are attributes of the cosd_chassis_scheduler_map_invalid event:



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

Possible completions:
  <from-event-attribute>  First attribute to compare
  cosd_chassis_scheduler_map_invalid.error-message
  cosd_chassis_scheduler_map_invalid.interface-name

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

To view a list of all event attributes 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
  ...

By default, the command output format is text. To change this, include the output-format xml statement.

In the optional output-filename statement, assign the name of the file to which to write script output for the specified script.

The filename format is hostname_filename_YYYYMMDD_HHMMSS_index-number.

For each uploaded file, a hostname and timestamp are automatically added to the filename to 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 router 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

In the optional 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.

For the output-filename and destination statements, there are four configuration scenarios:

Scenario 1

You can omit the output-filename and destination statements. This option makes sense when the event script has no output. For example, the event script might execute only request commands, which have no output.

Scenario 2

In the configuration, you can include the destination statement. You omit the output-filename statement in the configuration and specify an output filename in the event script instead. The script output is sent to the destination specified in the configuration. If you do not include the destination statement in the configuration, the script output is not uploaded.

In this scenario, the event policy extracts the filename from the event script. The event script writes the output filename as STDOUT. The XML syntax to use in the event script is:



<output>
    <event-script-output-filename>filename</event-script-output-filename>
</output>

The <event-script-output-filename> element must be the first child tag within the <output> parent tag.

Example: Scenario 2

On a router named router2, configure an event script action with a destination host, and omit the outut-filename statement. Define the destination host as ftp://user@router1//tmp.

In the script1.xsl event script, write the following output to STDOUT:



<event-script-output-filename>/var/cmd.txt</event-script-output-filename>

Configure the policy1 event policy as follows:



[edit event-options]
policy policy1 {


then {


event-script script1.xsl {
 destination host;
}


}


}
destinations {


host {


 archive-sites {
 "ftp://user@router1//tmp" password "$9$xkJNbYg4ZDH.oJ.fQnpuSyl";
## SECRET-DATA***
}


}


}

In this example, The /var/cmd.txt file resides on router router2. The event policy uses the File Transfer Protocol (FTP) to upload this file to the /tmp directory on router router1.

The event policy reads the output filename /var/cmd.txt from STDOUT. Then the event policy uploads the /var/cmd.txt file to the configured destination, which is the /tmp directory on router router1. The event policy renames the /var/cmd.txt file as router2_cmd.txt_YYYYMMDD_HHMMSS_range.

Scenario 3

You can include the output-filename and destination statements. If you include the output-filename statement in the configuration, you must also include the destination statement in the configuration. In this case, the script output is redirected to the output filename specified in the configuration and is sent to the destination specified in the configuration.

Scenario 4

You can include the output-filename and destination statements, and also specify an output filename directly within the event script. If you do this, the output filename specified in the configuration overrides the output filename specified in the event script.

[Contents] [Prev] [Next] [Index] [Report an Error]