Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

NETCONF Event Notifications

SUMMARY NETCONF clients can subscribe to event notifications in NETCONF sessions to receive alerts for events that might impact device operations or management activities.

NETCONF Event Notifications Overview

Certain devices running Junos OS Evolved support NETCONF event notifications, an asynchronous event notification service between a NETCONF server and a NETCONF client. After you enable the notification service, the NETCONF server sends event notifications, asynchronously as the events occur, to all NETCONF clients that subscribe to the notifications. Clients can subscribe to NETCONF notifications to receive alerts for events that might impact device operations or management activities.

The NETCONF server sends notifications for the following types of events:

  • netconf-session-start—Indicates when a NETCONF session starts and identifies the user who started the session.
  • netconf-session-end—Indicates when a NETCONF session ends and identifies the user who owned the session and the reason that the session was terminated.
  • netconf-config-change—Indicates when a management session commits changes to the active configuration and provides a summary of the changes.

  • OpenConfig ON_CHANGE events

You can enable the NETCONF event notification service on supported devices. See How to Enable and Subscribe to NETCONF Event Notifications for instructions. You can optionally configure the interleave capability, which enables NETCONF clients to subscribe to notifications and send RPCs in the same NETCONF session, as described in Interleave Capability.

After you enable NETCONF event notifications, the NETCONF server advertises the notification capability and the interleave capability in the capabilities exchange.

To subscribe to the notification service for events on a specific device, a NETCONF client sends a <create-subscription> RPC to the NETCONF server on the device and indicates the following:

  • <stream>—The stream of events that is of interest.

    A stream is a set of event notifications that matches some forwarding criteria. A subscription is bound to a single stream for the lifetime of the subscription. The NETCONF stream is the default and only supported stream on Junos devices. The NETCONF server returns an error if the subscription request is for any other stream. If you omit this parameter, the device treats the subscription request as a request for the NETCONF stream.

  • <filter>—A subtree filter that selects a subset of all possible events.

    If a NETCONF client specifies a filter, the server forwards only those events selected by the filter. If a client does not specify a filter, the server forwards all events. Junos OS Evolved supports only top-level filters and does not support using XPATH filters for this element. See Filtering Capability for more information.

After a NETCONF client subscribes to event notifications, the NETCONF server sends the notifications as they occur. The notifications continue until the NETCONF session terminates.

Note:

A NETCONF client receives all event notifications by default. There is no way to restrict or limit the content of a notification based on user privileges. Because some events, for example, netconf-config-change events, can contain sensitive information, it is important to control read access to the information.

For additional information about NETCONF event notifications, see the following RFCs:

  • RFC 5277, NETCONF Event Notifications

  • RFC 6470, Network Configuration Protocol (NETCONF) Base Notifications

NETCONF Event Notification Format

NETCONF event notifications are well-formed XML documents. When the NETCONF server receives an internal event, it converts it to an appropriate XML encoding with a top-level <notification> element and an <eventTime> child element. The actual content contained in the notification depends on the event.

A subscription request can include filters for specific types of notifications. If the subscription request includes filters, the user-defined filters are applied to each notification in the event stream, and the NETCONF server forwards only matching events to the client.

The following sample event notification contains a netconf-config-change event. The notification captures the event timestamp, the commit timestamp, the user who committed the configuration changes, and a summary of those changes.

The following notifications contain sample netconf-session-start and netconf-session-end events:

Interleave Capability

By default, after a NETCONF client subscribes to event notifications in a NETCONF session, the client cannot also send RPCs in the same session. The interleave capability enables the NETCONF client and server to continue exchanging RPCs and RPC replies within the same NETCONF session that is used for notifications. The interleave capability reduces the overall number of NETCONF sessions because you don’t need a dedicated NETCONF session for notifications. To use the interleave capability on devices that support this feature, you must configure the interleave statement at the [edit system services netconf notification] hierarchy level.

A NETCONF client ends a subscription by terminating either the NETCONF session or the NETCONF session’s underlying transport session, for example, with a <close-session> or <kill-session> operation. If you enable the interleave capability, a client can terminate the session by executing a <close-session> operation from within the same session. If you do not enable the interleave capability, the client can terminate the session, for example, by executing the <kill-session> operation from another session.

Filtering Capability

When a NETCONF client subscribes to event notifications, the client can subscribe to all event notifications in the stream, or the client can subscribe to a subset of event notifications. To subscribe to a subset of event notifications, the client includes the optional <filter> element in the <create-subscription> RPC. If the subscription request includes filters, the filters are applied to each notification in the event stream, and the NETCONF server forwards only matching events to the client. Otherwise, the server forwards all events.

The <filter> parameter format for the <create-subscription> operation is similar to the filter parameter format for other NETCONF operations. It encloses a subtree filter that selects the desired event notifications. In the case of the <create-subscription> operation, however, Junos devices only support subtree filters that match against the top-level element of the enclosed notification, for example, <netconf-config-change>. The filter is applied to the notifications in the stream and only against the contents of the <notification> wrapper.

Note:

Junos devices do not support using XPath to filter the notifications.

When you filter for specific notifications, you must include the appropriate namespace in the tag. If you do not specify the namespace, the event notifications will not match the filter, and the NETCONF server will not forward the notifications. In the following example, the subscription request returns a subset of all NETCONF event notifications. The filter selects and forwards only <netconf-config-change> events and <oc-ifl-event> events.

How to Enable and Subscribe to NETCONF Event Notifications

You must enable the NETCONF event notification service on a device before a NETCONF client can subscribe to event notifications in a NETCONF session. After the service is enabled, a NETCONF client subscribes to receive event notifications by sending a subscription request to the NETCONF server. The NETCONF server reply indicates if the request is successful. If the request is successful, the server sends asynchronous event notifications to the NETCONF client as the events occur and until the NETCONF session is terminated.

This example requires the following hardware and software:

  • Device running Junos OS Evolved Release 21.2R1 or later that supports the NETCONF event notification service. See Feature Explorer for supported devices.

To enable and subscribe to NETCONF event notifications, perform the following tasks:

Enable the NETCONF Event Notification Service

To enable a client to subscribe to event notifications in a NETCONF session:

  1. Enable the NETCONF event notification service by configuring the notification statement.
  2. (Optional) Configure the interleave option to enable a NETCONF client to execute RPCs in a NETCONF session that also subscribes to notifications.
  3. Configure the rfc-compliant statement to ensure the device is compliant with NETCONF RFC 4741.
  4. (Optional) Configure NETCONF tracing options for troubleshooting any issues.

    For example:

  5. Enable notification services on the default port for applications running on the device.

    In releases that require the allow-clients statement, you must also specify the clients (hostnames or IP addresses) that are allowed to subscribe to notifications.

    For example:

  6. Commit the configuration.

Subscribe to Receive Event Notifications

After you enable the NETCONF event notification service on a device, NETCONF clients can subscribe to receive event notifications in a NETCONF session. A NETCONF client can include the following optional parameters in the subscription request:

  • <stream>—Stream of events that is of interest. The default and only acceptable value is NETCONF.

  • <filter>—Subtree filter that selects a subset of all possible events.

To subscribe to event notifications in a NETCONF session:

  1. Start the NETCONF session.
  2. Verify that the NETCONF event notification service is enabled on the device by confirming that the notification capability is advertised in the capabilities exchange.
  3. Issue a create-subscription request, and optionally specify the NETCONF stream.

    • To subscribe to all notifications, omit the <filter> parameter.

    • To subscribe to a subset of notifications, include the <filter type="subtree"> element, and define one or more subtree filters for the notifications of interest. Junos devices only support subtree filters that match against the top-level element of the enclosed notification. You must include the appropriate namespace in the tag for the specific notification.

      For example:

  4. Verify that the subscription request is successful.

    The NETCONF server returns <ok/> if the request is successful or an <rpc-error> element if it cannot complete the subscription request.

    If the subscription request is successful, the NETCONF server starts sending event notifications asynchronously over the connection.

  5. If the interleave capability is enabled, the NETCONF client can continue to send RPCs within the same session.

Terminate the Subscription

A NETCONF client terminates a subscription to receive event notifications by terminating either the NETCONF session or the NETCONF session’s underlying transport session.

To terminate the NETCONF session and subscription, perform one of the following actions:

  • If the interleave capability is enabled, issue the <close-session/> operation in the NETCONF session.

  • Issue the <kill-session> operation from an external NETCONF session, and specify the session ID for the NETCONF session to end (as defined in the <session-id> element of the initial <hello> exchange).

  • Terminate the NETCONF session’s underlying transport session.