Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Configure an Event Policy to Change the Configuration

You can configure an event policy action that uses the change-configuration statement to modify the configuration in response to an event.

An event policy performs actions in response to specific events. You can configure event policies that listen for a specific event or correlated events and then modify the configuration. For example, upon receipt of an SNMP_TRAP_LINK_DOWN or SNMP_TRAP_LINK_UP event for a given interface, an event policy might modify the configuration of a static route to adjust its metric or modify its next hop.

Event policies can modify the configuration using the following methods:

  • Invoking an event script that changes and commits the configuration.

  • Using the change-configuration event policy action. This action executes configuration mode commands to modify the configuration and then commits the configuration.

This topic discusses how to use the change-configuration statement hierarchy to update the configuration. For information about using an event script to change the configuration, see Change the Configuration Using an Event Script.

Note:

We do not recommend using the change-configuration statement to modify the configuration on dual Routing Engine devices that have nonstop active routing (NSR) enabled. In this case, both Routing Engines might attempt to acquire a lock on the configuration database, which can cause the commit to fail. To modify the configuration through an event policy on NSR-enabled devices, invoke an event script that executes the commit on the primary Routing Engine only.

Use the Event Policy change-configuration Action to Change the Configuration

To create an event policy that uses configuration mode commands to modify the configuration, configure the change-configuration statement at the [edit event-options policy policy-name then] hierarchy level. For example:

The commands statement specifies the configuration mode commands that the event policy executes upon receipt of the configured event or events. Enclose each command in quotation marks (" "). Specify the complete statement path to the element, identifier, or value as you do in configuration mode when issuing commands at the [edit] hierarchy level. The commands statement accepts the following configuration mode commands:

  • activate

  • deactivate

  • delete

  • set

The event process (eventd) executes the commands in the order in which the commands appear in the event policy configuration. The commands update the candidate configuration, which is then committed, provided that no commit errors occur. By default, the event policy executes the configuration changes and commit operation as the root user. To execute these actions under the privileges of a specific user, configure the user-name statement and specify the user.

In certain scenarios, the change configuration action can fail, for example, if it cannot acquire a lock on the configuration. Configure the retry statement to have the system attempt the change configuration action a specified number of times if the first attempt fails.

Additionally, you can configure the commit-options child statement to customize the event policy commit operation. Table 1 summarizes the options.

Table 1: change-configuration commit-options
Option Description
check

Verify the candidate configuration syntax without committing the changes.
check synchronize

Verify the candidate configuration syntax on both Routing Engines without committing the changes.
force

Force the commit on the other Routing Engine, ignoring any warnings, even if the candidate configuration contains uncommitted changes.

log

Log a commit comment.
synchronize

Synchronize the commit on both Routing Engines.

For example, if you are testing or troubleshooting an event policy, you can configure the check commit option to verify the candidate configuration syntax without committing the changes. On dual control plane systems, you can configure the check synchronize statement. The system copies the candidate configuration on one control plane to the other control plane and then verifies that both candidate configurations are syntactically correct. The check statement and the other commit-options statements are mutually exclusive.

You can commit the changes on a single Routing Engine, or you can configure the synchronize option to synchronize the commit on both Routing Engines. When you configure the synchronize option, the requesting Routing Engine copies and loads its candidate configuration to the other Routing Engine. Both Routing Engines perform a syntax check on the candidate configuration file. If no errors are found, the configuration is activated and becomes the current operational configuration on both Routing Engines. By default, the synchronize option fails if the responding Routing Engine has uncommitted configuration changes. However, you can enforce commit synchronization on the Routing Engines and ignore any warnings by configuring the force option.

The following configuration executes the specified configuration mode command and then commits the configuration on both Routing Engines. The log statement records the configured commit comment.

Example: Change the Configuration Using an Event Policy

It might be necessary to modify the configuration in response to a particular event. You can configure an event policy to change and commit the configuration when the event policy is triggered by one or more specific events.

This example simulates an SNMP_TRAP_LINK_DOWN event for a specific interface. Upon receipt of the event, the event policy uses the change-configuration action to modify the configuration. The event policy updates the configuration of a static route to use a new next-hop IP address through a different exit interface.

Requirements

  • A device running Junos OS or a device running Junos OS Evolved.

Overview

You can configure an event policy action to modify the configuration. Suppose you have a static route to the 10.1.10.0/24 network with a next-hop IP address of 10.1.2.1 through the exit interface ge-0/2/1. At some point, this interface goes down, triggering an SNMP_TRAP_LINK_DOWN event.

This example creates an event policy named update-on-snmp-trap-link-down. You configure the event policy so that the eventd process listens for an SNMP_TRAP_LINK_DOWN event associated with interface ge-0/2/1.0. If the interface goes down, the event policy executes a change configuration action with the following configuration changes:

  • Removes the static route through the ge-0/2/1 exit interface

  • Creates a new static route to the same target network with a next-hop IP address of 10.1.3.1 through the exit interface ge-0/3/1

The event policy executes the actions under the privileges of the user admin. The event policy also logs a commit comment specifying that the change was made through the associated event policy. The event policy uses a retry count of 5 and a retry interval of 4 seconds. If the initial configuration change attempt fails, the system attempts the change 5 additional times and waits 4 seconds between each attempt.

Although not presented here, you might have a second, similar event policy that executes a change configuration action to update the static route when the interface comes back up. In that case, the policy would trigger on the SNMP_TRAP_LINK_UP event for the same interface.

Configuration

CLI Quick Configuration

To quickly configure this example, copy the following commands, paste the commands in a text file, remove any line breaks, change any details necessary to match your network configuration, and then copy and paste the commands into the CLI at the [edit] hierarchy level:

Configuring the Event Policy

Step-by-Step Procedure

  1. Create and name the event policy.

  2. Configure the events statement so that the event policy triggers on the SNMP_TRAP_LINK_DOWN event.

    Set the attributes-match statement so that the policy triggers only if the SNMP_TRAP_LINK_DOWN event occurs for the ge-0/2/1.0 interface.

  3. Specify the configuration mode commands to execute if the event policy triggers.

    Configure each command on a single line, enclose the command string in quotes, and specify the complete statement path.

  4. (Optional) Configure the log option with a comment describing the configuration changes. The comment is added to the commit logs after a successful commit operation is made through the associated event policy.

  5. (Optional) If you have dual Routing Engines, configure the synchronize option to commit the configuration on both Routing Engines. Include the force option to force the commit on the other Routing Engine, ignoring any warnings. This example does not configure the synchronize and force options.

  6. (Optional) Configure the retry count and retry interval.

    In this example, count is set to 5 and the interval is 4 seconds.

  7. (Optional) Configure the username under whose privileges the configuration changes and commit are made.

    If you do not specify a username, the action is executed as user root.

  8. Configure a new log file at the [edit system syslog] hierarchy level to record syslog events of facility daemon and severity warning.

    This log captures the SNMP_TRAP_LINK_DOWN events.

  9. To test this example, configure a static route to the 10.1.10.0/24 network with a next hop IP address of 10.1.2.1.

  10. Commit the configuration.

  11. Review the [edit routing-options static] hierarchy level of the configuration before disabling the ge-0/2/1 interface, and note the next hop IP address.

  12. To manually test the event policy, take the ge-0/2/1 interface temporarily offline to generate the SNMP_TRAP_LINK_DOWN event.

Results

Verification

Confirm that the configuration is working properly.

Verify the Status of the Interface

Purpose

Verify that the ge-0/2/1 interface is down and that it triggered the SNMP_TRAP_LINK_DOWN event.

Action

Issue the show interfaces ge-0/2/1 operational mode command. The command output shows that the interface is administratively offline.

Review the contents of the system log file configured in Step 8. The output shows that the ge-0/2/1.0 interface generated an SNMP_TRAP_LINK_DOWN event.

Verify the Commit

Purpose

Verify that the event policy commit operation was successful by reviewing the commit log and the messages log file.

Action

Issue the show system commit operational mode command to view the commit log. In this example, the log confirms that the configuration was committed through the event policy under the privileges of user admin at the given date and time.

Review the messages log file. Upon receipt of the SNMP_TRAP_LINK_DOWN event, Junos OS executed the configured event policy action to modify and commit the configuration. The commit operation occurred under the privileges of user admin.

Note:

If you configure a different log file, review the file specific to your configuration.
Meaning

The output from the show system commit operational mode command and the messages log file verify that the commit operation, which was made through the event policy under the privileges of the user admin, was successful. The show system commit output and messages log file reference the commit comment specified in the configured commit options.

Verify the Configuration Changes

Purpose

Verify the configuration changes by reviewing the [edit routing-options static] hierarchy level of the configuration after disabling the ge-0/2/1 interface.

Action

Issue the following operational mode command:

Meaning

The event policy modified the configured next hop to use the new IP address 10.1.3.1. The exit interface for the new IP address is ge-0/3/1.

Troubleshooting

Troubleshoot Commit Errors

Problem

The triggered event policy does not make the specified configuration changes, and the logs verify that the commit was unsuccessful.

A failed commit might occur for different reasons, including but not limited to:

  • The candidate configuration is locked

  • The configuration mode commands have the incorrect syntax or order

  • The user configured for the event policy action does not have the appropriate privileges to make the requested changes.

Solution

Check the configuration mode commands at the [edit event-options policy update-on-snmp-trap-link-down then change-configuration commands] hierarchy level, and verify that the syntax and the order of execution are correct.

Additionally, increase the retry count and interval options so that if the configuration is locked, the event policy attempts the configuration changes a specified number of times after the first failed instance.

Also, verify that the configured user, if any, has appropriate privilege levels to make the requested changes.

Example: Change the Interface Configuration in Response to an Event

This example uses a real-time performance monitoring (RPM) probe to generate PING_TEST_FAILED events for a given interface. Upon receipt of the first instance of three PING_TEST_FAILED events within a 60-second period from the configured RPM probe, the event policy executes a change configuration event policy action. The action modifies the configuration to administratively disable the specified interface. This type of action might be necessary if you have an unstable, flapping interface that is consistently affecting network performance.

Requirements

  • A device running Junos OS or a device running Junos OS Evolved.

Overview

This example creates an event policy named disable-interface-on-ping-failure. You configure the event policy so that the eventd process listens for PING_TEST_FAILED events generated by a specific RPM probe and associated with the ge-0/3/1 interface. If three PING_TEST_FAILED events occur for the given interface within a 60-second interval, the event policy executes a change configuration action. The event policy configuration commands administratively disable the interface.

To test the event policy, the example configures an RPM probe that pings the IP address associated with the ge-0/3/1 interface. In this example, the ge-0/3/1.0 interface is configured with the IPv4 address 10.1.4.1/26. By default, one probe is sent per test, and the example uses a 5-second pause between tests. After three successive probe losses, the RPM probe generates a PING_TEST_FAILED event. Because multiple RPM tests could be running simultaneously, the event policy matches the owner-name and test-name attributes of the received PING_TEST_FAILED events to the RPM probe owner name and test name. When the RPM probe generates three PING_TEST_FAILED events in a 60-second interval, it triggers the event policy, which disables the interface.

This event policy also demonstrates how to restrict the execution of the same configuration change multiple times because of occurrences of the same event or correlated events. In this example, the within 60 trigger on 3 statement specifies that the configuration change is only triggered on the third occurrence of a PING_TEST_FAILED event within a 60-second interval. The trigger until 4 statement specifies that subsequent occurrences of the PING_TEST_FAILED event should not cause the event policy to re-trigger.

Note:

If you only configure the trigger on 3 condition, the commit operation might go into a loop. The combination of trigger on 3 and trigger until 4 prevents the event policy from repeatedly making the same configuration change.

Configuration

Configure the RPM Probe

CLI Quick Configuration

To quickly configure this section of the example, copy the following commands, paste them into a text file, remove any line breaks, change any details necessary to match your network configuration, copy and paste the commands into the CLI at the [edit] hierarchy level, and then enter commit from configuration mode.

Step-by-Step Procedure

To configure the RPM probe, which creates the PING_TEST_FAILED events for this example:

  1. Create an RPM probe named ping-probe-test with owner icmp-ping-probe.

  2. Configure the RPM probe to send ICMP echo requests.

    Configure the RPM probe to send the ICMP echo requests to the ge-0/3/1 interface at IP address 10.1.4.1.

  3. Configure a 5-second pause between test windows.

  4. Configure the RPM probe threshold so that the PING_TEST_FAILED event is triggered after three successive probe losses.

  5. Configure a new log file at the [edit system syslog] hierarchy level to record syslog events of facility daemon and severity info.

    This captures the events sent during the probe tests.

  6. Commit the configuration.

Results

From configuration mode, confirm your configuration by entering the show services and show system syslog commands. If the output does not display the intended configuration, repeat the instructions in this example to correct the configuration.

Configure the Event Policy

CLI Quick Configuration

To quickly configure this section of the example, copy the following commands, paste them into a text file, remove any line breaks, change any details necessary to match your network configuration, copy and paste the commands into the CLI at the [edit] hierarchy level, and then enter commit from configuration mode.

Step-by-Step Procedure

  1. Create and name the event-policy.

  2. Configure the event policy to match on the PING_TEST_FAILED event.

  3. Configure the policy to trigger when three PING_TEST_FAILED events occur within 60 seconds.

  4. Configure the within 65 trigger until 4 statement to prevent the policy from re-triggering if more than three PING_TEST_FAILED events occur.

  5. Configure the attributes-match statement so that the event policy is only triggered by the PING_TEST_FAILED events generated by the associated RPM probe.

  6. Specify the configuration mode commands to execute if the event policy triggers.

    Configure each command on a single line, enclose the command string in quotes, and specify the complete statement path.

  7. (Optional) Configure the log option with a comment describing the configuration changes.

    The comment is added to the commit logs after a successful commit operation is made through the associated event policy.

  8. (Optional) If you have dual Routing Engines, configure the synchronize option to commit the configuration on both Routing Engines. Include the force option to force the commit on the other Routing Engine, ignoring any warnings. This example does not configure the synchronize and force options.

  9. (Optional) Configure the username under whose privileges the configuration changes and commit are made.

    If you do not specify a username, the action is executed as user root.

  10. Review the output of the show interfaces ge-0/3/1 operational mode command before the configuration change takes place.

    Note:

    The interface should be enabled.

  11. Commit the configuration.

Results

From configuration mode, confirm your configuration by entering the show event-options command. If the output does not display the intended configuration, repeat the instructions in this example to correct the configuration.

Verification

Confirm that the configuration is working properly.

Verify the Events

Purpose

To manually test the event policy, take the ge-0/3/1 interface offline until three PING_TEST_FAILED events are generated.

Action

Review the configured syslog file. Verify that the RPM probe generates a PING_TEST_FAILED event after successive lost probes.

Verify the Commit

Purpose

Verify that the event policy commit operation was successful by reviewing the commit log and the messages log file.

Action

Issue the show system commit operational mode command to view the commit log.

Review the messages log file.

Meaning

The output from the show system commit operational mode command and the messages log file verify that Junos OS executed the configured event policy action to modify and commit the configuration. The commit operation, which was made through the event policy under the privileges of the user admin at the given date and time, was successful. The show system commit output and messages log file reference the commit comment specified in the configured commit options.

Verify the Configuration Changes

Purpose

Verify the configuration changes by reviewing the [edit interfaces ge-0/3/1] hierarchy level of the configuration.

Action
Meaning

The ge-0/3/1 configuration hierarchy was modified through the event policy to add the disable statement.

Verify the Status of the Interface

Purpose

Review the output of the show interfaces ge-0/3/1 operational mode command after the configuration change takes place.

Action

Issue the show interfaces ge-0/3/1 operational mode command. After the event policy configuration change action disables the interface, the status changes from "Enabled" to "Administratively down".

Related Documentation