VMware

agonzalezpri@vmware.com

Huawei

ludwig@clemm.org

Cisco Systems

evoit@cisco.com

Cisco Systems

einarnn@cisco.com

Cisco Systems

ambtripa@cisco.com

Operations & Management NETCONF Draft This document defines how to transport network subscriptions and event messages on top of the Network Configuration protocol (NETCONF). This includes the full set of RPCs, subscription state changes, and subscribed content needing asynchronous delivery.

This document defines mechanisms that provide a subscription and asynchronous message notification delivery service for the NETCONF protocol based on . This is an optional capability built on top of the base NETCONF definition.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. The following terms are defined in : client, server, operation, RPC. The following terms are defined in : event, event notification, stream, publisher, receiver, subscriber, subscription, configured subscription. Note that a publisher in corresponds to a server in . Similarly, a subscriber corresponds to a client. A receiver is also a client. In the remainder of this document, we will use the terminology in .

In this section, we describe and exemplify how is to be supported over NETCONF.

In the context of an event stream exposes a continuous set of events available for subscription. A NETCONF client can retrieve the list of available event streams from a NETCONF server using the "get" operation against the top-level container "/streams" defined in . The reply includes the list of streams supported on the NETCONF server. The following example illustrates the retrieval of the list of available event streams using the <get> operation.

]]>

The NETCONF server returns a list of event streams available. In this example, the list contains the NETCONF, SNMP, and SYSLOG streams.

NETCONF The NETCONF mandatory event stream SNMP The SNMP event stream SYSLOG The SYSLOG event stream 2015-03-09T19:14:55.233Z ]]>

For , a similar get is needed to retrieve available datastore names.

A NETCONF server implementation supporting must support dynamic subscriptions and the "NETCONF" notification event stream. The NETCONF event stream contains all NETCONF XML event information supported by the server. A NETCONF server implementation supporting must support the "running" datastore.

The dynamic subscription RFC and interactions operation is defined in .

An example of interactions over NETCONF transport for one sample subscription is below:

NETCONF xpath-event-filter ]]>

If the NETCONF server can satisfy the request, the server sends a positive <subscription-result> element, and the subscription-id of the accepted subscription.

ok 52 ]]>

If the NETCONF server cannot satisfy the request, or the client has no authorization to establish the subscription, the server will send a negative <subscription-result> element. For instance:

stream-unavailable ]]>

If the client request includes parameters the NETCONF server cannot serve, the negative <subscription-result> may include hints at subscription parameters which would have been accepted. For instance, consider the following subscription from , which augments the establish-subscription with some additional parameters, including "period". If the client requests a period which the NETCONF server cannot serve, the back-and-forth exchange may be:

running subtree select="/ex:foo" /> 10 encode-xml error-insufficient-resources 2000 ]]>

| | | | | | Establish Subscription | |----------------------------->| | RPC Reply: OK, id = 22 | |<-----------------------------| | | | Notification (id 22) | |<-----------------------------| | | | | | Establish Subscription | |----------------------------->| | RPC Reply: OK, id = 23 | |<-----------------------------| | | | | | Notification (id 22) | |<-----------------------------| | Notification (id 23) | |<-----------------------------| | | | | ]]>

This operation is defined in .

The following demonstrates modifying a subscription. Consider a subscription from , which augments the establish-subscription with some additional parameters, including "period". A subscription may be established and modified as follows.

running subtree-event-filter select="/ex:foo" /> 1000 ok 1922 1922 100 ]]>

If the NETCONF server can satisfy the request, the server sends a positive <subscription-result> element. This response is like that to an establish-subscription request, but without the subscription identifier.

ok ]]>

If the NETCONF server cannot satisfy the request, the server sends a negative <subscription-result> element. Its contents and semantics are identical to those in an establish-subscription request. For instance:

period-unsupported 500 ]]>

| | | | Establish Subscription | |----------------------------->| | RPC Reply: OK, id = 22 | |<-----------------------------| | | | Notification (id 22) | |<-----------------------------| | | | Modify Subscription (id 22) | |----------------------------->| | RPC Reply: OK | |<-----------------------------| | | | Notification (id 22) | |<-----------------------------| | | ]]>

This operation is defined in for events, and enhanced in for datastores.

The following demonstrates deleting a subscription.

1922 ]]>

If the NETCONF server can satisfy the request, the server sends a positive <subscription-result> element. For example:

ok ]]>

If the NETCONF server cannot satisfy the request, the server sends an <subscription-result> element indicating the deletion was not performed. For example:

no-such-subscription ]]>

Configured subscriptions are established, modified, and deleted using configuration operations against the top-level subtree of or via configuration interface. This document covers configured subscriptions where the chosen protocol to send the notifications to the receivers is NETCONF. Configured subscriptions are supported by NETCONF servers using NETCONF Call Home . Any configuration interface can be used to set a configured subscription that uses NETCONF to push notifications to receivers. Without loss of generality, the examples in this section, use a NETCONF interface to configure the subscriptions

For subscription establishment, a NETCONF client may send:

1922 foo

1.2.3.4

1234 netconf ]]>

if the request is accepted, the server would reply:

]]>

if the request is not accepted because the server cannot serve it, no configuration is changed. Int this case the server may reply:

error-insufficient-resources ]]>

For every configured receiver, once NETCONF transport session between the server and the receiver is recognized as active, the server will issue a "subscription-started" notification. After that, the server will send notifications to the receiver as per the subscription notification. Note that the server assumes that the receiver is ready to accept notifications on the NETCONF session. This may require coordination between the client that configures the subscription and the clients for which the notifications are intended. This coordination is out of the scope of this document. The session is only intended for pushing notifications. Client requests on that session SHOULD be ignored by the server. The contents sent by the server on the Call Home session, once established, are identical to those in a dynamic subscription.

Once the subscription configuration is active, if NETCONF transport is needed but does not exist to one or more target IP address plus port, the server initiates a transport session via to those receiver(s) in the subscription using the address and port specified.

| | | | | | | | | | | | Edit-config | | | |--------------------------->| | | | RPC Reply: OK | | | |<---------------------------| | | | | Call Home | | | |<-------------->| | | |<--------------------------->| | | | | | | Subscription | | | | Started | | | | (id 22) | | | |--------------->| | | |---------------------------->| | | | | | | Notification | | | | (id 22) | | | |--------------->| | | |---------------------------->| | | | | ]]>

Configured subscriptions can be modified using configuration operations against the top-level subtree subscription-config. For example, the subscription established in the previous section could be modified as follows, choosing a different receiver:

1922 foo

1.2.3.5

1234 ]]>

if the request is accepted, the server would reply:

]]>

| | | | | | | | | | | | Edit-config | | | |--------------------------->| | | | RPC Reply: OK | | | |<---------------------------| | | | | Call Home | | | |<-------------->| | | |<--------------------------->| | | | | | | Subscription | | | | Started | | | | (id 22) | | | |--------------->| | | |---------------------------->| | | | | | | Notification | | | | (id 22) | | | |--------------->| | | |---------------------------->| | | | | | Edit-config | | | |--------------------------->| | | | RPC Reply: OK | | | |<---------------------------| | | | | Subscription | | | | Modified | | | | (id 22) | | | |--------------->| | | |---------------------------->| | | | | | | Notification | | | | (id 22) | | | |--------------->| | | |---------------------------->| | | | | ]]>

Subscriptions can be deleted using configuration operations against the top-level subtree subscription-config. For example:

1922 ]]>

| | | | | | | | | | | | Edit-config | | | |--------------------------->| | | | RPC Reply: OK | | | |<---------------------------| | | | | Call Home | | | |<-------------->| | | |<--------------------------->| | | | | | | Subscription | | | | Started | | | | (id 22) | | | |--------------->| | | |---------------------------->| | | | | | | | | | | Notification | | | | (id 22) | | | |--------------->| | | |---------------------------->| | | | | | Edit-config | | | |--------------------------->| | | | RPC Reply: OK | | | |<---------------------------| | | | | Subscription | | | | Terminated | | | | (id 22) | | | |--------------->| | | |---------------------------->| | | | | ]]>

Once a dynamic or configured subscription has been created, the NETCONF server sends (asynchronously) event notifications from the subscribed stream to receiver(s) over NETCONF. We refer to these as data plane notifications. The data model for Event Notifications is defined in . The following is an example of an event notification from :

This notification might result in the following, prior to it being placed into NETCONF. Note that the mandatory eventTime and Subscription id have been added.

2007-09-01T10:00:00Z so-1/2/3.0 up down ]]>

In addition to data plane notifications, a publisher may send subscription state notifications (defined in ) to indicate to receivers that an event related to the subscription management has occurred. Subscription state notifications cannot be filtered out. Next we exemplify them:

A subscription-started would look like:

2007-09-01T10:00:00Z 39 NETCONF ]]>

The subscription-modified is identical, with just the word "started" being replaced by "modified".

A subscription-completed would look like:

2007-09-01T10:00:00Z 39 ]]>

The equivalent using JSON encoding would be:

2007-09-01T10:00:00Z { "sn:subscription-completed": { "identifier" : 39 } ]]>

The subscription-resumed and replay-complete are virtually identical, with "subscription-completed" simply being replaced by "subscription-resumed" and "replay-complete" in both encodings.

A subscription-terminated would look like:

2007-09-01T10:00:00Z 39 error-insufficient-resources ]]>

The above, and the subscription-suspended are virtually identical, with "subscription-terminated" simply being replaced by "subscription-suspended".

| | | | Establish Subscription | |<---------------------------->| | | | Notification | |<-----------------------------| | | | | | Subscription Suspended | |<-----------------------------| | | | | | | | Subscription Resumed | |<-----------------------------| | | | Notification | |<-----------------------------| | | ]]>

| | | | | | | | Edit-config | | | |--------------------------->| | | | RPC Reply: OK | | | |<---------------------------| | | | | Subscription | | | | Started | | | |--------------->| | | |---------------------------->| | | | | | | Notification | | | |--------------->| | | |---------------------------->| | | | | | | Subscription | | | | Suspended | | | |--------------->| | | | | | | | Notification | | | |---------------------------->| | | | | | | Subscription | | | | Resumed | | | |--------------->| | | | | | | | Notification | | | |--------------->| | | |---------------------------->| | | | | ]]>

The :interleave capability is originally defined in . It is incorporated in this document with essentially the same semantics. That is, the NETCONF server MUST receive, process, and respond to NETCONF requests on a session with active notification subscriptions. The :interleave capability is identified by the following string: urn:ietf:params:netconf:capability:interleave:1.0 Note that subscription operations MUST be received, processed, and responded on a session with active notification subscriptions That mandatory requirement together with the :interleave capability permits a client performing all operations against a server using a single connection, allowing for better scalability with respect to the number of NETCONF sessions required to manage an entity.

The <notification> elements are never sent before the transport layer and the NETCONF layer, including capabilities exchange, have been established and the manager has been identified and authenticated. A secure transport must be used and the server must ensure that the user has sufficient authorization to perform the function they are requesting against the specific subset of content involved. The contents of notifications, as well as the names of event streams, may contain sensitive information and care should be taken to ensure that they are viewed only by authorized users. The NETCONF server MUST NOT include any content in a notification that the user is not authorized to view. If a malicious or buggy NETCONF client sends a number of <establish-subscription>requests, then these subscriptions accumulate and may use up system resources. In such a situation, subscriptions MAY be terminated by terminating the suspect underlying NETCONF sessions. The server MAY also suspend or terminate a subset of the active subscriptions on the NETCONF session . Configured subscriptions from one or more publishers could be used to overwhelm a receiver, which perhaps doesn't even support subscriptions. Clients that do not want pushed data need only terminate or refuse any transport sessions from the publisher. The NETCONF Authorization Control Model SHOULD be used to control and restrict authorization of subscription configuration. This control models permits specifying per-user permissions to receive specific event notification types. The permissions are specified as a set of access control rules.

We wish to acknowledge the helpful contributions, comments, and suggestions that were received from: Andy Bierman, Yan Gang, Sharon Chisholm, Hector Trevino, Peipei Guo, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, and Guangying Zheng.

(To be removed by RFC editor prior to publication) Formal definition of: notification-contents-json, and incorporation of the subscription-id in the notifications. It depends on the formal definition of the notification element

(To be removed by RFC editor prior to publication)

Text presentation modifications throughout Modified examples to match the namespace, prefixes, and data node identifiers in and Modified examples to include <subscription-result> in all RPC responses Modified examples to include mandatory fields in and

Added additional detail to "configured subscriptions" Added interleave capability Adjusted terminology to that in draft-ietf-netconf-subscribed-notifications Corrected namespaces in examples

Text simplifications throughout v02 had no meaningful changes

Added Call Home in solution for configured subscriptions. Clarified support for multiple subscription on a single session. No need to support multiple create-subscription. Added mapping between terminology in and (the one followed in this document). Editorial improvements.