draft-ietf-netconf-netconf-event-notifications-05.txt   draft-ietf-netconf-netconf-event-notifications-06.txt 
NETCONF A. Gonzalez Prieto NETCONF A. Gonzalez Prieto
Internet-Draft VMware Internet-Draft VMware
Intended status: Standards Track A. Clemm Intended status: Standards Track E. Voit
Expires: April 5, 2018 Huawei Expires: May 3, 2018 Cisco Systems
E. Voit A. Clemm
Huawei
E. Nilsen-Nygaard E. Nilsen-Nygaard
A. Tripathy A. Tripathy
Cisco Systems Cisco Systems
October 2, 2017 October 30, 2017
NETCONF Support for Event Notifications NETCONF Support for Event Notifications
draft-ietf-netconf-netconf-event-notifications-05 draft-ietf-netconf-netconf-event-notifications-06
Abstract Abstract
This document defines how to transport network subscriptions and This document provides a NETCONF binding for
event messages on top of the Network Configuration protocol [I-D.draft-ietf-netconf-subscribed-notifications]. Included are:
(NETCONF). This includes the full set of RPCs, subscription state
changes, and subscribed content needing asynchronous delivery. o Transport mappings for subscription RPCs, state change
notifications, and notification messages
o Functionality which must be supported with NETCONF
o Examples in appendices
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 5, 2018. This Internet-Draft will expire on May 3, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Interleave Capability . . . . . . . . . . . . . . . . . . . . 3
3.1. Event Stream Discovery . . . . . . . . . . . . . . . . . 3 4. Mandatory stream and datastore support . . . . . . . . . . . 3
3.2. Mandatory NETCONF support . . . . . . . . . . . . . . . . 4 5. Transport connectivity . . . . . . . . . . . . . . . . . . . 4
3.3. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 4 5.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 4
3.4. Configured Subscriptions . . . . . . . . . . . . . . . . 11 5.2. Configured Subscriptions . . . . . . . . . . . . . . . . 4
4. Interleave Capability . . . . . . . . . . . . . . . . . . . . 23 6. Notification Messages . . . . . . . . . . . . . . . . . . . . 4
5. Security Considerations . . . . . . . . . . . . . . . . . . . 24 7. Security Considerations . . . . . . . . . . . . . . . . . . . 4
6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 5
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 5
7.1. Normative References . . . . . . . . . . . . . . . . . . 25 9.1. Normative References . . . . . . . . . . . . . . . . . . 5
7.2. Informative References . . . . . . . . . . . . . . . . . 25 9.2. Informative References . . . . . . . . . . . . . . . . . 6
Appendix A. Open Items . . . . . . . . . . . . . . . . . . . . . 26 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 6
Appendix B. Changes between revisions . . . . . . . . . . . . . 26 A.1. Event Stream Discovery . . . . . . . . . . . . . . . . . 6
B.1. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 26 A.2. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 7
B.2. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 26 A.3. Configured Subscriptions . . . . . . . . . . . . . . . . 12
B.3. v01 to v03 . . . . . . . . . . . . . . . . . . . . . . . 26 A.4. Subscription State Notifications . . . . . . . . . . . . 17
B.4. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 26 Appendix B. Changes between revisions . . . . . . . . . . . . . 19
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 B.1. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 19
B.2. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 19
B.3. v01 to v03 . . . . . . . . . . . . . . . . . . . . . . . 20
B.4. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 20
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20
1. Introduction 1. Introduction
This document defines mechanisms that provide a subscription and This document defines a binding for notification message delivery for
asynchronous message notification delivery service for the NETCONF [I-D.draft-ietf-netconf-subscribed-notifications] transported over
protocol [RFC6241] based on [subscribe]. This is an optional the NETCONF protocol [RFC6241]. In addition, as
capability built on top of the base NETCONF definition. [I-D.ietf-netconf-yang-push] is itself built upon
[I-D.draft-ietf-netconf-subscribed-notifications], this document
enables a NETCONF client to maintain a subset/extract of an actively
changing YANG datastore located on a NETCONF server.
This document is broken into two main parts. The first contains
normative requirements which are incremental to
[I-D.draft-ietf-netconf-subscribed-notifications] when NETCONF
transport is used. The second are examples and are included as
appendices.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119].
The following terms are defined in [RFC6241]: client, server, The following terms are defined in
operation, RPC. [I-D.draft-ietf-netconf-subscribed-notifications]: notification
message, stream, publisher, receiver, subscriber, subscription,
The following terms are defined in [subscribe]: event, event
notification, stream, publisher, receiver, subscriber, subscription,
configured subscription. configured subscription.
Note that a publisher in [subscribe] corresponds to a server in 3. Interleave Capability
[RFC6241]. 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 [RFC6241].
3. Solution To support multiple subscriptions on a single session, a NETCONF
publisher MUST support the :interleave capability as defined in
[RFC5277]. Such support MUST be indicated by the following
capability: "urn:ietf:params:netconf:capability:interleave:1.0".
Advertisement of this capability along with support
[I-D.draft-ietf-netconf-subscribed-notifications] will indicate that
a NETCONF publisher is able to receive, process, and respond to
NETCONF requests and
[I-D.draft-ietf-netconf-subscribed-notifications] subscription
operations on a session with active subscriptions.
In this section, we describe and exemplify how [subscribe] is to be 4. Mandatory stream and datastore support
supported over NETCONF.
3.1. Event Stream Discovery A NETCONF publisher supporting
[I-D.draft-ietf-netconf-subscribed-notifications] MUST support the
"NETCONF" event stream identified in that draft.
In the context of [subscribe] an event stream exposes a continuous A NETCONF publisher supporting [I-D.ietf-netconf-yang-push] MUST
set of events available for subscription. A NETCONF client can support the "running" datastore as defined by
retrieve the list of available event streams from a NETCONF server [I.D.draft-ietf-netmod-revised-datastores].
using the "get" operation against the top-level container "/streams"
defined in [subscribe]. The reply includes the list of streams
supported on the NETCONF server.
The following example illustrates the retrieval of the list of 5. Transport connectivity
available event streams using the <get> operation.
<rpc message-id="101" 5.1. Dynamic Subscriptions
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"/>
</filter>
</get>
</rpc>
Figure 1: Get streams request For dynamic subscriptions, if the NETCONF session involved with the
"establish-subscription" terminates, the subscription MUST be
deleted.
The NETCONF server returns a list of event streams available. In 5.2. Configured Subscriptions
this example, the list contains the NETCONF, SNMP, and SYSLOG
streams.
<rpc-reply message-id="101" For a configured subscription, there is no guarantee a transport
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> session is currently in place with associated receiver(s). So where
<data> a configured subscription has a receiver in the connecting state, but
<streams no NETCONF transport exists to that receiver, the publisher MUST be
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> able to initiate a NETCONF transport session via NETCONF call home
<stream> [RFC8071], section 4.1 to that receiver. Until NETCONF connectivity
<stream>NETCONF</stream> is established and a subscription-started state change notification
<description>The NETCONF mandatory event stream</description> is successfully sent, that receiver MUST remain in its status of a
</stream> "connecting".
<stream>
<stream>SNMP</stream>
<description>The SNMP event stream</description>
</stream>
<stream>
<stream>SYSLOG</stream>
<description>The SYSLOG event stream</description>
<replay-support/>
<replay-log-creation-time>
2015-03-09T19:14:55.233Z</replay-log-creation-time>
</stream>
</streams>
</data>
</rpc-reply>
Figure 2: Get streams response If the call home fails because the publisher receives receiver
credentials which are subsequently declined as part [RFC8071],
Section 4.1, step S5 authentication, then that receiver MUST be
assigned a "suspended" status.
For [yang-push], a similar get is needed to retrieve available If the call home fails to establish for any other reason, the
datastore names. publisher MAY leave the receiver in a "connecting" status, and retry
the call home at a future time. Alternatively, the publisher MAY
place the receiver into a "suspended" status after a predetermined
number of call home attempts.
3.2. Mandatory NETCONF support NETCONF Transport session connectivity SHOULD be verified via
Section 4.1, step S7.
A NETCONF server implementation supporting [subscribe] must support Failure of an active NETCONF session MUST reset the restart the call
dynamic subscriptions and the "NETCONF" notification event stream. home process, and return the receiver to "connecting".
The NETCONF event stream contains all NETCONF XML event information
supported by the server.
A NETCONF server implementation supporting [yang-push] must support 6. Notification Messages
the "running" datastore.
3.3. Dynamic Subscriptions Notification messages transported over NETCONF will be identical in
format and content to those encoded using one-way operations defined
within [RFC5277], section 4.
3.3.1. Establishing Dynamic Subscriptions 7. Security Considerations
The dynamic subscription RFC and interactions operation is defined in Notification messages (including state change notifications) are
[subscribe]. never sent before the NETCONF capabilities exchange has completed.
3.3.1.1. Usage Example If a malicious or buggy NETCONF subscriber 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 publisher MAY also suspend or terminate a
subset of the active subscriptions on the NETCONF session.
An example of interactions over NETCONF transport for one sample The NETCONF Authorization Control Model [RFC6536] SHOULD be used to
subscription is below: control and restrict authorization of subscription configuration.
<netconf:rpc netconf:message-id="102" 8. Acknowledgments
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
<stream>NETCONF</stream>
<event-filter-type>xpath-event-filter</event-filter-type>
<event-filter-contents xmlns:ex="http://example.com/event/1.0"
select="/ex:event[ex:eventClass='fault' and
(ex:severity='minor' or ex:severity='major'
or ex:severity='critical')]" />
</establish-subscription>
</netconf:rpc>
Figure 3: establish-subscription over NETCONF 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.
3.3.1.2. Positive Response 9. References
If the NETCONF server can satisfy the request, the server sends a 9.1. Normative References
positive <subscription-result> element, and the subscription-id of
the accepted subscription.
<rpc-reply message-id="102" [I-D.draft-ietf-netconf-subscribed-notifications]
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
<subscription-result and E. Nilsen-Nygaard, "Custom Subscription to Event
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> Streams", draft-ietf-netconf-subscribed-notifications-06
ok (work in progress), October 2017.
</subscription-result>
<identifier
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
52
</identifier>
</rpc-reply>
Figure 4: Successful establish-subscription [I-D.ietf-netconf-yang-push]
Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto.,
Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B.
Lengyel, "YANG Datastore Subscription", October 2017,
<https://datatracker.ietf.org/doc/
draft-ietf-netconf-yang-push/>.
3.3.1.3. Negative Response [I.D.draft-ietf-netmod-revised-datastores]
Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore
Architecture", draft-ietf-netmod-revised-datastores-04
(work in progress), August 2017.
If the NETCONF server cannot satisfy the request, or the client has [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
no authorization to establish the subscription, the server will send Requirement Levels", BCP 14, RFC 2119,
a negative <subscription-result> element. For instance: DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
<rpc-reply message-id="103" [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
<subscription-result <https://www.rfc-editor.org/info/rfc5277>.
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
stream-unavailable
</subscription-result>
</rpc-reply>
Figure 5: Unsuccessful establish subscription [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<https://www.rfc-editor.org/info/rfc6241>.
3.3.1.4. Subscription Negotiation [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6536, March 2012,
<https://www.rfc-editor.org/info/rfc6536>.
If the client request includes parameters the NETCONF server cannot [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
serve, the negative <subscription-result> may include hints at RFC 8071, DOI 10.17487/RFC8071, February 2017,
subscription parameters which would have been accepted. For <https://www.rfc-editor.org/info/rfc8071>.
instance, consider the following subscription from [yang-push], 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:
<netconf:rpc message-id="101" 9.2. Informative References
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
<datastore>running</datastore>
<event-filter-type>
subtree</event-filter-type>
<event-filter-contents
xmlns:ex="http://example.com/sample-data/1.0">
select="/ex:foo" />
<dampening-period>10</dampening-period>
<encoding>encode-xml</encoding>
</establish-subscription>
</netconf:rpc>
<rpc-reply message-id="101" [I.D.draft-ietf-netconf-notification-messages]
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> Voit, Eric., Clemm, Alexander., Bierman, A., and T.
<subscription-result Jenkins, "YANG Notification Headers and Bundles",
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> September 2017, <https://datatracker.ietf.org/doc/
error-insufficient-resources draft-ietf-netconf-notification-messages>.
</subscription-result>
<period-hint
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
2000
</period-hint>
</rpc-reply>
Figure 6: Subscription establishment negotiation Appendix A. Examples
3.3.1.5. Message Flow Examples A.1. Event Stream Discovery
+------------+ +-----------+ As defined in [I-D.draft-ietf-netconf-subscribed-notifications] an
| Client | | Server | 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 publisher using the "get" operation
| Capability Exchange | against the top-level container "/streams" defined in
|<---------------------------->| [I-D.draft-ietf-netconf-subscribed-notifications]. Any reply will
| | include the stream identities supported on the NETCONF publisher
| | which may be available to that client.
| Establish Subscription |
|----------------------------->|
| RPC Reply: OK, id = 22 |
|<-----------------------------|
| |
| Notification (id 22) |
|<-----------------------------|
| |
| |
| Establish Subscription |
|----------------------------->|
| RPC Reply: OK, id = 23 |
|<-----------------------------|
| |
| |
| Notification (id 22) |
|<-----------------------------|
| Notification (id 23) |
|<-----------------------------|
| |
| |
Figure 7: Multiple subscription establishments over a single NETCONF The following example illustrates the retrieval of the list of
session available event streams using the "get" operation.
3.3.2. Modifying a Subscription <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
</filter>
</get>
</rpc>
This operation is defined in [subscribe]. Figure 1: Get streams request
3.3.2.1. Usage Example After such a request, the NETCONF publisher returns a list of event
streams available. In the example reply below, the list contains
just the NETCONF stream.
The following demonstrates modifying a subscription. Consider a <rpc-reply message-id="101"
subscription from [yang-push], which augments the establish- xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
subscription with some additional parameters, including "period". A <data>
subscription may be established and modified as follows. <streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<name>NETCONF</name>
</streams>
</data>
</rpc-reply>
<netconf:rpc message-id="101" Figure 2: Get streams response
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
<datastore xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
running</datastore>
<event-filter-type>subtree-event-filter</event-filter-type>
<event-filter-contents
xmlns:ex="http://example.com/sample-data/1.0">
select="/ex:foo" />
<period xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
1000
</period>
</establish-subscription>
</netconf:rpc>
<rpc-reply message-id="101" A.2. Dynamic Subscriptions
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<subscription-result
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
ok
</subscription-result>
<identifier
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
1922
</identifier>
</rpc-reply>
<netconf:rpc message-id="102" The dynamic subscription RPCs and interactions operation are defined
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> in [I-D.draft-ietf-netconf-subscribed-notifications] and enhanced in
<modify-subscription [I-D.ietf-netconf-yang-push].
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
<identifier>1922</identifier>
<period>100</period>
</modify-subscription>
</netconf:rpc>
Figure 8: Subscription modification A.2.1. Establishing Dynamic Subscriptions
3.3.2.2. Positive Response An example of establish-subscription interactions over NETCONF
transport for a sample subscription is described below:
If the NETCONF server can satisfy the request, the server sends a <rpc netconf:message-id="102"
positive <subscription-result> element. This response is like that xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
to an establish-subscription request, but without the subscription <establish-subscription
identifier. xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<stream>
<name>NETCONF</name>
<xpath-filter xmlns:ex="http://example.com/events">
/ex:foo
</xpath-filter>
</stream>
</establish-subscription>
</rpc>
<rpc-reply message-id="102" Figure 3: establish-subscription over NETCONF
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<subscription-result
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
ok
</subscription-result>
</rpc-reply>
Figure 9: Successful modify subscription If the NETCONF publisher can satisfy the request, the publisher sends
a positive "subscription-result" element, and the subscription-id of
the accepted subscription.
3.3.2.3. Negative Response <rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<subscription-result
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
ok
</subscription-result>
<identifier
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
22
</identifier>
</rpc-reply>
If the NETCONF server cannot satisfy the request, the server sends a Figure 4: Successful establish-subscription
negative <subscription-result> element. Its contents and semantics
are identical to those in an establish-subscription request. For
instance:
<rpc-reply message-id="102" If the NETCONF publisher cannot satisfy the request, or subscriber
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> has no authorization to establish the subscription, the publisher
<subscription-result will send a negative "subscription-result" element. For instance:
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
period-unsupported
</subscription-result>
<period-hint>500</period-hint>
</rpc-reply>
Figure 10: Unsuccessful modify subscription <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<subscription-result
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
stream-unavailable
</subscription-result>
</rpc-reply>
3.3.2.4. Message Flow Example Figure 5: Unsuccessful establish subscription
+------------+ +-----------+
| Client | | Server |
+------------+ +-----------+
| |
| Capability Exchange |
|<---------------------------->|
| |
| Establish Subscription |
|----------------------------->|
| RPC Reply: OK, id = 22 |
|<-----------------------------|
| |
| Notification (id 22) |
|<-----------------------------|
| |
| Modify Subscription (id 22) |
|----------------------------->|
| RPC Reply: OK |
|<-----------------------------|
| |
| Notification (id 22) |
|<-----------------------------|
| |
Figure 11: Message flow for successful subscription modification To get an idea of the interaction model, the following figure shows
two separate establish subscriptions RPC being made. The first is
given subscription id 22, the second, id 23.
3.3.3. Deleting a Subscription +------------+ +-----------+
| Subscriber | | Publisher |
+------------+ +-----------+
| |
| Capability Exchange |
|<---------------------------->|
| |
| |
| Establish Subscription |
|----------------------------->|
| RPC Reply: OK, id = 22 |
|<-----------------------------|
| |
| notification message (for 22)|
|<-----------------------------|
| |
| |
| Establish Subscription |
|----------------------------->|
| RPC Reply: OK, id = 23 |
|<-----------------------------|
| |
| |
| notification message (for 22)|
|<-----------------------------|
| notification message (for 23)|
|<-----------------------------|
| |
This operation is defined in [subscribe] for events, and enhanced in Figure 6: Multiple subscription establishments over a single NETCONF
[yang-push] for datastores. session
3.3.3.1. Usage Example In the example above, it is important to note that the subscription
ids of 22 and 23 are not included in the notification messages of
[I-D.draft-ietf-netconf-subscribed-notifications]. However because
[I-D.ietf-netconf-yang-push] has defined its own notifications,
subscription identifiers are available within those notification
messages. With the availability of
[I.D.draft-ietf-netconf-notification-messages], all notification
messages will be able to transport a subscription identifier.
The following demonstrates deleting a subscription. A.2.2. Modifying Dynamic Subscriptions
<netconf:rpc message-id="101" The following demonstrates modifying a dynamic subscription.
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> Consider a subscription from [I-D.ietf-netconf-yang-push]. An
<delete-subscription established may have a new filter applied. The desired modification
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> is the application of a new filter.
<identifier>1922</identifier>
</delete-subscription>
</netconf:rpc>
Figure 12: Delete subscription <rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<modify-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"
xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<yp:datastore>
<yp:xpath-filter xmlns="http://example.com/datastore">
/interfaces-state/interface/oper-status
</yp:xpath-filter>
</yp:datastore>
<identifier>
22
</identifier>
</modify-subscription>
</rpc>
3.3.3.2. Positive Response Figure 7: Subscription modification
If the NETCONF server can satisfy the request, the server sends a If the NETCONF publisher can satisfy the request, the publisher sends
positive <subscription-result> element. For example: a positive "subscription-result". This response is like that to an
establish-subscription request, but without the subscription
identifier.
<rpc-reply message-id="103" <rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<subscription-result <subscription-result
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
ok ok
</subscription-result> </subscription-result>
</rpc-reply> </rpc-reply>
Figure 13: Successful delete subscription Figure 8: Successful modify-subscription
3.3.3.3. Negative Response If the NETCONF publisher cannot satisfy the request, the publisher
sends a negative "subscription-result" element. Its contents and
semantics match those from an establish-subscription request.
If the NETCONF server cannot satisfy the request, the server sends an To get an idea of the interaction model, the following figure shows a
<subscription-result> element indicating the deletion was not successful RPC modification request to subscription with an
performed. For example: identifier of 22.
<rpc-reply message-id="101" +------------+ +-----------+
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | Subscriber | | Publisher |
<subscription-result +------------+ +-----------+
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> | |
no-such-subscription | notification message |
</subscription-result> |<-----------------------------|
</rpc-reply> | |
| Modify Subscription |
|----------------------------->|
| RPC Reply: OK |
|<-----------------------------|
| |
| notification message |
|<-----------------------------|
| |
Figure 14: Unsuccessful delete subscription Figure 9: Interaction model for successful subscription modification
3.4. Configured Subscriptions A.2.3. Deleting Dynamic Subscriptions
Configured subscriptions are established, modified, and deleted using The following demonstrates deleting a subscription.
configuration operations against the top-level subtree of [subscribe]
or [yang-push] 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 <rpc message-id="103"
NETCONF Call Home [RFC8071]. xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<delete-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<identifier>22</identifier>
</delete-subscription>
</rpc>
Any configuration interface can be used to set a configured Figure 10: Delete subscription
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
3.4.1. Establishing a Configured Subscription If the NETCONF publisher can satisfy the request, the publisher sends
an OK element. For example:
For subscription establishment, a NETCONF client may send: <rpc-reply message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<rpc message-id="101" Figure 11: Successful delete subscription
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<subscription-config
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
<subscription>
<identifier>
1922
</identifier>
<stream>
foo
</stream>
<receiver>
<address>
1.2.3.4
</address>
<port>
1234
</port>
<protocol>
netconf
</protocol>
</receiver>
</subscription>
</subscription-config>
</edit-config>
</rpc>
Figure 15: Establish configured subscription If the NETCONF publisher cannot satisfy the request, the publisher
sends an error-rpc element indicating the modification didn't work.
One way this could happen is if an existing valid subscription
identifier was given, but that subscription was created on a
different NETCONF transport session:
if the request is accepted, the server would reply: <rpc-reply message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>invalid-value</error-tag>
<error-severity>error</error-severity>
<error-path
xmlns:sn="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
sn:identifier
</error-path>
<error-message xml:lang="en">
no-such-subscription
</error-message>
</rpc-error>
</rpc-reply>
<rpc-reply message-id="101" Figure 12: Unsuccessful delete subscription
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
Figure 16: Response to a successful configuration subscription A.3. Configured Subscriptions
establishment
if the request is not accepted because the server cannot serve it, no Configured subscriptions may be established, modified, and deleted
configuration is changed. Int this case the server may reply: using configuration operations against the top-level subtree of
[I-D.draft-ietf-netconf-subscribed-notifications] or
[I-D.ietf-netconf-yang-push].
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> In this section, we present examples of how to manage the
<subscription-result configuration subscriptions using a NETCONF client. Key differences
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> from dynamic subscriptions over NETCONF is that subscription
error-insufficient-resources lifetimes are decoupled from NETCONF sessions.
</subscription-result>
A.3.1. Creating Configured Subscriptions
For subscription creation, a NETCONF client may send:
<rpc message-id="201"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<subscription-config
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<subscription>
<identifier>22</identifier>
<encoding>encode-xml</encoding>
<stream>
<name>NETCONF</name>
<receiver>
<address>1.2.3.4</address>
<port>1234</port>
</receiver>
</stream>
</subscription>
</subscription-config>
</edit-config>
</rpc>
Figure 13: Create a configured subscription
If the request is accepted, the publisher would reply:
<rpc-reply message-id="201"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply> </rpc-reply>
Figure 17: Response to a failed configured subscription establishment Figure 14: Response to a successful configuration subscription
establishment
For every configured receiver, once NETCONF transport session between If the request is not accepted because the publisher cannot serve it,
the server and the receiver is recognized as active, the server will no configuration is changed. In this case the publisher may reply:
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 <rpc-reply message-id="201"
requests on that session SHOULD be ignored by the server. xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>resource-denied</error-tag>
<error-severity>error</error-severity>
<error-message xml:lang="en">
Temporarily the publisher cannot serve this
subscription due to the current workload.
</error-message>
</rpc-error>
</rpc-reply>
The contents sent by the server on the Call Home session, once Figure 15: Response to a failed configured subscription establishment
established, are identical to those in a dynamic subscription.
3.4.2. Call Home for Configured Subscriptions After a subscription has been created, NETCONF connectivity to each
receiver's IP address and port will be established if it does not
already exist. This will be accomplished via [RFC8071].
Once the subscription configuration is active, if NETCONF transport To get an idea of the interaction model, the following figure shows a
is needed but does not exist to one or more target IP address plus successful configuration based creation of a subscription.
port, the server initiates a transport session via [RFC8071] to those
receiver(s) in the subscription using the address and port specified.
3.4.3. Full Establish Message Flow +----------+ +-----------+ +---------+
+----------+ +-----------+ +---------+ +---------+ |Config Ops| | Publisher | | 1.2.3.4 |
| Client | | Server | | Rcver A | | Rcver B | +----------+ +-----------+ +---------+
+----------+ +-----------+ +---------+ +---------+ | | |
| | | | | Capability Exchange | |
| Capability Exchange | | | |<-------------------------->| |
|<-------------------------->| | | | | |
| | | | | | |
| | | | | Edit-config | |
| Edit-config | | | |--------------------------->| |
|--------------------------->| | | | RPC Reply: OK | |
| RPC Reply: OK | | | |<---------------------------| |
|<---------------------------| | | | | Call Home |
| | Call Home | | | |<-------------->|
| |<-------------->| | | | |
| |<--------------------------->| | | Subscription |
| | | | | | Started |
| | Subscription | | | |--------------->|
| | Started | | | | |
| | (id 22) | | | | notification |
| |--------------->| | | | message |
| |---------------------------->| | |--------------->|
| | | |
| | Notification | |
| | (id 22) | |
| |--------------->| |
| |---------------------------->|
| | | |
Figure 18: Message flow for configured subscription establishment Figure 16: Interaction model for configured subscription
establishment
3.4.4. Modifying a Configured Subscription A.3.2. Modifying Configured Subscriptions
Configured subscriptions can be modified using configuration Configured subscriptions can be modified using configuration
operations against the top-level subtree subscription-config. operations against the top-level subtree subscription-config.
For example, the subscription established in the previous section For example, the subscription established in the previous section
could be modified as follows, choosing a different receiver: could be modified as follows, here a adding a second receiver:
<rpc message-id="102" <rpc message-id="202"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
<edit-config> xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<target> <edit-config>
<running/> <target>
</target> <running/>
<subscription-config </target>
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> <subscription-config
<subscription> xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<identifier> <subscription>
1922 <identifier>
</identifier> 1922
<stream> </identifier>
foo <receiver>
</stream> <address>
<receiver> 1.2.3.5
<address> </address>
1.2.3.5 <port>
</address> 1234
<port> </port>
1234 </receiver>
</port> </subscription>
</receiver> </subscription-config>
</subscription> </edit-config>
</subscription-config> </rpc>
</edit-config>
</rpc>
Figure 19: Modify configured subscription Figure 17: Modify configured subscription
if the request is accepted, the server would reply: If the request is accepted, the publisher would reply:
<rpc-reply message-id="102" <rpc-reply message-id="202"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
Figure 20: A successful configured subscription modification Figure 18: A successful configured subscription modification
And the previous interaction model would be extended as follows.
3.4.4.1. Message Flow Example
+----------+ +-----------+ +---------+ +---------+ +----------+ +-----------+ +---------+ +---------+
| Client | | Server | | Rcver A | | Rcver B | |Config Ops| | Publisher | | 1.2.3.4 | | 1.2.3.5 |
+----------+ +-----------+ +---------+ +---------+ +----------+ +-----------+ +---------+ +---------+
| | | | | | | |
| Capability Exchange | | |
|<-------------------------->| | |
| | | | | | | |
| | notification | |
| | message | |
| |--------------->| |
| | | | | | | |
| Edit-config | | | | Edit-config | | |
|--------------------------->| | | |--------------------------->| | |
| RPC Reply: OK | | | | RPC Reply: OK | | |
|<---------------------------| | | |<---------------------------| | |
| | Call Home | | | | Call Home | |
| |<-------------->| |
| |<--------------------------->| | |<--------------------------->|
| | | |
| | Subscription | | | | Subscription | |
| | Started | | | | Started | |
| | (id 22) | |
| |--------------->| |
| |---------------------------->|
| | | |
| | Notification | |
| | (id 22) | |
| |--------------->| |
| |---------------------------->| | |---------------------------->|
| | | | | | | |
| Edit-config | | | | | notification | |
|--------------------------->| | | | | message | |
| RPC Reply: OK | | |
|<---------------------------| | |
| | Subscription | |
| | Modified | |
| | (id 22) | |
| |--------------->| |
| |---------------------------->|
| | | |
| | Notification | |
| | (id 22) | |
| |--------------->| | | |--------------->| |
| |---------------------------->| | |---------------------------->|
| | | | | | | |
Figure 21: Message flow for subscription modification (configured Figure 19: Interaction model for configured subscription modification
subscription)
3.4.5. Deleting a Configured Subscription
Subscriptions can be deleted using configuration operations against
the top-level subtree subscription-config. For example:
<rpc message-id="103" Note in the above that in the specific example above, modifying a
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> configured subscription actually resulted in subscription-started
<edit-config> notification. If the edit of the configuration had also added a
<target> filter, a separate modify-subscription would have gone to the
<running/> original receiver.
</target>
<subscription-config
xmlns:xc="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
<subscription xc:operation="delete">
<identifier>
1922
</identifier>
</subscription>
</subscription-config>
</edit-config>
</rpc>
<rpc-reply message-id="103" A.3.3. Deleting Configured Subscriptions
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
Figure 22: Deleting a configured subscription Configured subscriptions can be deleted using configuration
operations against the top-level subtree subscription-config.
Deleting the subscription above would result in the following flow
impacting all receivers.
3.4.5.1. Message Flow Example
+----------+ +-----------+ +---------+ +---------+ +----------+ +-----------+ +---------+ +---------+
| Client | | Server | | Rcver A | | Rcver B | |Config Ops| | Publisher | | 1.2.3.4 | | 1.2.3.5 |
+----------+ +-----------+ +---------+ +---------+ +----------+ +-----------+ +---------+ +---------+
| | | | | | | |
| Capability Exchange | | | | | notification | |
|<-------------------------->| | | | | message | |
| | | |
| | | |
| Edit-config | | |
|--------------------------->| | |
| RPC Reply: OK | | |
|<---------------------------| | |
| | Call Home | |
| |<-------------->| |
| |<--------------------------->|
| | | |
| | Subscription | |
| | Started | |
| | (id 22) | |
| |--------------->| |
| |---------------------------->|
| | | |
| | | |
| | Notification | |
| | (id 22) | |
| |--------------->| | | |--------------->| |
| |---------------------------->| | |---------------------------->|
| | | | | | | |
| Edit-config | | | | Edit-config | | |
|--------------------------->| | | |--------------------------->| | |
| RPC Reply: OK | | | | RPC Reply: OK | | |
|<---------------------------| | | |<---------------------------| | |
| | Subscription | | | | Subscription | |
| | Terminated | | | | Terminated | |
| | (id 22) | |
| |--------------->| | | |--------------->| |
| |---------------------------->| | |---------------------------->|
| | | | | | | |
Figure 23: Message flow for subscription deletion (configured Figure 20: Interaction model for configured subscription deletion
subscription)
3.4.6. Event (Data Plane) Notifications
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 [subscribe].
The following is an example of an event notification from [RFC6020]:
notification link-failure {
description "A link failure has been detected";
leaf if-name {
type leafref {
path "/interface/name";
}
}
leaf if-admin-status {
type admin-status;
}
leaf if-oper-status {
type oper-status;
}
}
Figure 24: Definition of an event notification
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.
<notification
xmlns=" urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<link-failure xmlns="http://acme.example.com/system">
<if-name>so-1/2/3.0</if-name>
<if-admin-status>up</if-admin-status>
<if-oper-status>down</if-oper-status>
</link-failure>
</notification>
Figure 25: Event notification
3.4.7. Subscription State Notifications A.4. Subscription State Notifications
In addition to data plane notifications, a publisher may send A publisher will send subscription state notifications according to
subscription state notifications (defined in [subscribe]) to indicate the definitions within
to receivers that an event related to the subscription management has [I-D.draft-ietf-netconf-subscribed-notifications]).
occurred. Subscription state notifications cannot be filtered out.
Next we exemplify them:
3.4.7.1. subscription-started and subscription-modified A.4.1. subscription-started and subscription-modified
A subscription-started would look like: A subscription-started over NETCONF encoded in XML would look like:
<notification <notification
xmlns=" urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> xmlns=" urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime> <eventTime>2007-09-01T10:00:00Z</eventTime>
<subscription-started <subscription-started
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"/> xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
<identifier>39</identifier> <identifier>39</identifier>
<stream>NETCONF</stream> <encoding>encode-xml</encoding>
</subscription-started/> <stream>
</notification> <name>NETCONF</name>
<xpath-filter xmlns:ex="http://example.com/events">
/ex:foo
</xpath-filter>
</stream>
</subscription-started/>
</notification>
Figure 26: subscription-started subscription state notification Figure 21: subscription-started subscription state notification
The subscription-modified is identical, with just the word "started" The subscription-modified is identical, with just the word "started"
being replaced by "modified". being replaced by "modified".
3.4.7.2. subscription-completed, subscription-resumed, and replay- A.4.2. subscription-completed, subscription-resumed, and replay-
complete complete
A subscription-completed would look like: A subscription-completed would look like:
<notification <notification
xmlns=" urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime> <eventTime>2007-09-01T10:00:00Z</eventTime>
<subscription-completed <subscription-completed
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<identifier>39</identifier> <identifier>39</identifier>
</subscription-completed> </subscription-completed>
</notification> </notification>
Figure 27: subscription-completed notification in XML
The equivalent using JSON encoding would be:
<notification
xmlns=" urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<notification-contents-json>
{
"sn:subscription-completed": {
"identifier" : 39
}
</notification-contents-json>
</notification>
Figure 28: subscription-completed notification in JSON Figure 22: subscription-completed notification in XML
The subscription-resumed and replay-complete are virtually identical, The subscription-resumed and replay-complete are virtually identical,
with "subscription-completed" simply being replaced by "subscription- with "subscription-completed" simply being replaced by "subscription-
resumed" and "replay-complete" in both encodings. resumed" and "replay-complete" in both encodings.
3.4.7.3. subscription-terminated and subscription-suspended A.4.3. subscription-terminated and subscription-suspended
A subscription-terminated would look like: A subscription-terminated would look like:
<notification <notification
xmlns=" urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> xmlns=" urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime> <eventTime>2007-09-01T10:00:00Z</eventTime>
<subscription-terminated <subscription-terminated
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push:1.0"> xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<identifier>39</identifier> <identifier>39</identifier>
<error-id>error-insufficient-resources</error-id> <error-id>
</subscription-terminated> unsupportable-volume
</notification> </error-id>
</subscription-terminated>
Figure 29: subscription-modified subscription state notification </notification>
The above, and the subscription-suspended are virtually identical,
with "subscription-terminated" simply being replaced by
"subscription-suspended".
3.4.7.4. Notification Message Flow Examples
+------------+ +-----------+
| Client | | Server |
+------------+ +-----------+
| |
| Capability Exchange |
|<---------------------------->|
| |
| Establish Subscription |
|<---------------------------->|
| |
| Notification |
|<-----------------------------|
| |
| |
| Subscription Suspended |
|<-----------------------------|
| |
| |
| |
| Subscription Resumed |
|<-----------------------------|
| |
| Notification |
|<-----------------------------|
| |
Figure 30: subscription-suspended and resumed notifications
+----------+ +-----------+ +---------+ +---------+
| Client | | Server | | Rcver A | | Rcver B |
+----------+ +-----------+ +---------+ +---------+
| | | |
| Capability Exchange | | |
|<-------------------------->| | |
| | | |
| Edit-config | | |
|--------------------------->| | |
| RPC Reply: OK | | |
|<---------------------------| | |
| | Subscription | |
| | Started | |
| |--------------->| |
| |---------------------------->|
| | | |
| | Notification | |
| |--------------->| |
| |---------------------------->|
| | | |
| | Subscription | |
| | Suspended | |
| |--------------->| |
| | | |
| | Notification | |
| |---------------------------->|
| | | |
| | Subscription | |
| | Resumed | |
| |--------------->| |
| | | |
| | Notification | |
| |--------------->| |
| |---------------------------->|
| | | |
Figure 31: Suspended and resumed notifications for a single
configured receiver
4. Interleave Capability
The :interleave capability is originally defined in [RFC5277]. 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.
5. Security Considerations
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 [RFC6536] 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.
6. Acknowledgments
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.
7. References
7.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
<https://www.rfc-editor.org/info/rfc5277>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<https://www.rfc-editor.org/info/rfc6241>.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6536, March 2012,
<https://www.rfc-editor.org/info/rfc6536>.
[RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
RFC 8071, DOI 10.17487/RFC8071, February 2017,
<https://www.rfc-editor.org/info/rfc8071>.
7.2. Informative References
[subscribe] Figure 23: subscription-terminated subscription state notification
Voit, Eric., Clemm, A., Gonzalez Prieto, A., Nilsen-
Nygaard, E., and A. Tripathy, "Custom Subscription to
Event Notifications", September 2017,
<https://datatracker.ietf.org/doc/
draft-ietf-netconf-subscribed-notifications/>.
[yang-push] The subscription-suspended is virtually identical, with
Clemm, A., Gonzalez Prieto, A., Voit, Eric., Tripathy, A., "subscription-terminated" simply being replaced by "subscription-
Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, suspended".
"Subscribing to YANG datastore push updates", September
2017, <https://datatracker.ietf.org/doc/
draft-ietf-netconf-yang-push/>.
Appendix A. Open Items Appendix B. Changes between revisions
(To be removed by RFC editor prior to publication) (To be removed by RFC editor prior to publication)
o Formal definition of: notification-contents-json, and B.1. v05 to v06
incorporation of the subscription-id in the notifications. It
depends on the formal definition of the notification element
Appendix B. Changes between revisions
(To be removed by RFC editor prior to publication) o Moved examples to appendices
B.1. v04 to v05 o All examples rewritten based on namespace learnings
o Text presentation modifications throughout o Normative text consolidated in front
o Modified examples to match the namespace, prefixes, and data node o Removed all mention of JSON
identifiers in [subscribe] and [yang-push]
o Modified examples to include <subscription-result> in all RPC o Call home process detailed
responses
o Modified examples to include mandatory fields in [subscribe] and o Note: this is a major revision attempting to cover those comments
[yang-push] received from two week review.
B.2. v03 to v04 B.2. v03 to v04
o Added additional detail to "configured subscriptions" o Added additional detail to "configured subscriptions"
o Added interleave capability o Added interleave capability
o Adjusted terminology to that in draft-ietf-netconf-subscribed- o Adjusted terminology to that in draft-ietf-netconf-subscribed-
notifications notifications
skipping to change at page 27, line 5 skipping to change at page 20, line 18
o v02 had no meaningful changes o v02 had no meaningful changes
B.4. v00 to v01 B.4. v00 to v01
o Added Call Home in solution for configured subscriptions. o Added Call Home in solution for configured subscriptions.
o Clarified support for multiple subscription on a single session. o Clarified support for multiple subscription on a single session.
No need to support multiple create-subscription. No need to support multiple create-subscription.
o Added mapping between terminology in [yang-push] and [RFC6241] o Added mapping between terminology in yang-push and [RFC6241] (the
(the one followed in this document). one followed in this document).
o Editorial improvements. o Editorial improvements.
Authors' Addresses Authors' Addresses
Alberto Gonzalez Prieto Alberto Gonzalez Prieto
VMware VMware
Email: agonzalezpri@vmware.com Email: agonzalezpri@vmware.com
Alexander Clemm
Huawei
Email: ludwig@clemm.org
Eric Voit Eric Voit
Cisco Systems Cisco Systems
Email: evoit@cisco.com Email: evoit@cisco.com
Alexander Clemm
Huawei
Email: ludwig@clemm.org
Einar Nilsen-Nygaard Einar Nilsen-Nygaard
Cisco Systems Cisco Systems
Email: einarnn@cisco.com Email: einarnn@cisco.com
Ambika Prasad Tripathy Ambika Prasad Tripathy
Cisco Systems Cisco Systems
Email: ambtripa@cisco.com Email: ambtripa@cisco.com
 End of changes. 147 change blocks. 
859 lines changed or deleted 589 lines changed or added

This html diff was produced by rfcdiff 1.46. The latest version is available from http://tools.ietf.org/tools/rfcdiff/