idnits 2.17.1
draft-ietf-netconf-subscribed-notifications-10.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 570 has weird spacing: '...ntifier sub...'
== Line 1005 has weird spacing: '...ntifier sub...'
== Line 1039 has weird spacing: '...ntifier sub...'
== Line 1198 has weird spacing: '...ro time yan...'
-- The document date (February 23, 2018) is 2254 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Outdated reference: A later version (-12) exists of
draft-ietf-rtgwg-ni-model-06
-- Possible downref: Normative reference to a draft: ref. 'RFC6536bis'
** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113)
-- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH'
Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 3 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 NETCONF E. Voit
3 Internet-Draft Cisco Systems
4 Intended status: Standards Track A. Clemm
5 Expires: August 27, 2018 Huawei
6 A. Gonzalez Prieto
7 VMWare
8 E. Nilsen-Nygaard
9 A. Tripathy
10 Cisco Systems
11 February 23, 2018
13 Custom Subscription to Event Streams
14 draft-ietf-netconf-subscribed-notifications-10
16 Abstract
18 This document defines capabilities and operations for the customized
19 establishment of subscriptions upon a publisher's event streams.
20 Also defined are delivery mechanisms for instances of the resulting
21 notification messages. Effectively this allows a subscriber to
22 request and receive a continuous, custom feed of publisher generated
23 information.
25 Status of This Memo
27 This Internet-Draft is submitted in full conformance with the
28 provisions of BCP 78 and BCP 79.
30 Internet-Drafts are working documents of the Internet Engineering
31 Task Force (IETF). Note that other groups may also distribute
32 working documents as Internet-Drafts. The list of current Internet-
33 Drafts is at https://datatracker.ietf.org/drafts/current/.
35 Internet-Drafts are draft documents valid for a maximum of six months
36 and may be updated, replaced, or obsoleted by other documents at any
37 time. It is inappropriate to use Internet-Drafts as reference
38 material or to cite them other than as "work in progress."
40 This Internet-Draft will expire on August 27, 2018.
42 Copyright Notice
44 Copyright (c) 2018 IETF Trust and the persons identified as the
45 document authors. All rights reserved.
47 This document is subject to BCP 78 and the IETF Trust's Legal
48 Provisions Relating to IETF Documents
49 (https://trustee.ietf.org/license-info) in effect on the date of
50 publication of this document. Please review these documents
51 carefully, as they describe your rights and restrictions with respect
52 to this document. Code Components extracted from this document must
53 include Simplified BSD License text as described in Section 4.e of
54 the Trust Legal Provisions and are provided without warranty as
55 described in the Simplified BSD License.
57 Table of Contents
59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
60 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3
61 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
62 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 4
63 1.4. Relationship to RFC-5277 . . . . . . . . . . . . . . . . 6
64 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 6
65 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 6
66 2.2. Event Stream Filters . . . . . . . . . . . . . . . . . . 7
67 2.3. QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
68 2.4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 8
69 2.5. Configured Subscriptions . . . . . . . . . . . . . . . . 14
70 2.6. Event Record Delivery . . . . . . . . . . . . . . . . . . 19
71 2.7. Subscription State Notifications . . . . . . . . . . . . 20
72 2.8. Subscription Monitoring . . . . . . . . . . . . . . . . . 24
73 2.9. Advertisement . . . . . . . . . . . . . . . . . . . . . . 24
74 3. YANG Data Model Trees . . . . . . . . . . . . . . . . . . . . 24
75 3.1. Event Streams Container . . . . . . . . . . . . . . . . . 25
76 3.2. Event Stream Filters Container . . . . . . . . . . . . . 25
77 3.3. Subscriptions Container . . . . . . . . . . . . . . . . . 25
78 4. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 26
79 5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 51
80 5.1. Implementation Considerations . . . . . . . . . . . . . . 51
81 5.2. IANA Considerations . . . . . . . . . . . . . . . . . . . 52
82 5.3. Security Considerations . . . . . . . . . . . . . . . . . 52
83 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53
84 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 53
85 7.1. Normative References . . . . . . . . . . . . . . . . . . 54
86 7.2. Informative References . . . . . . . . . . . . . . . . . 54
87 Appendix A. Changes between revisions . . . . . . . . . . . . . 55
88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 59
90 1. Introduction
92 This document defines capabilities and operations for the customized
93 establishment of subscriptions upon system generated event streams.
94 Effectively this enables a "subscribe then publish" capability where
95 the customized information needs of each target receiver are
96 understood by the publisher before subscribed event records are
97 marshaled and pushed. The receiver then gets a continuous, custom
98 feed of publisher generated information.
100 While the functionality defined in this document is transport-
101 agnostic, protocols like NETCONF [RFC6241] or RESTCONF [RFC8040] can
102 be used to configure or dynamically signal subscriptions, and there
103 are bindings defined for subscribed event record delivery for NETCONF
104 within [I-D.draft-ietf-netconf-netconf-event-notifications], and for
105 HTTP2 or HTTP1.1 within [I-D.draft-ietf-netconf-restconf-notif].
107 1.1. Motivation
109 There are various [RFC5277] limitations, many of which have been
110 exposed in [RFC7923] which needed to be solved. Key capabilities
111 supported by this document includes:
113 o multiple subscriptions on a single transport session
115 o support for dynamic and statically configured subscriptions
117 o modification of an existing subscription
119 o operational counters and instrumentation
121 o negotiation of subscription parameters (through the use of hints
122 returned as part of declined subscription requests)
124 o state change notifications (e.g., publisher driven suspension,
125 parameter modification)
127 o independence from transport protocol
129 1.2. Terminology
131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
133 document are to be interpreted as described in RFC 2119 [RFC2119].
135 Configured subscription: A subscription installed via a configuration
136 interface which persists across reboots.
138 Dynamic subscription: A subscription agreed between subscriber and
139 publisher created via an establish-subscription RPC.
141 Event: An occurrence of something that may be of interest. (e.g., a
142 configuration change, a fault, a change in status, crossing a
143 threshold, or an external input to the system.)
144 Event record: A set of information detailing an event.
146 NACM: NETCONF Access Control Model.
148 Notification message: A set of transport encapsulated information
149 intended for a receiver indicating that one or more event(s) have
150 occurred. A notification message may bundle multiple event records.
151 This includes the bundling of multiple, independent RFC 7950 YANG
152 notifications.
154 Publisher: An entity responsible for streaming notification messages
155 per the terms of a Subscription.
157 Receiver: A target to which a publisher pushes subscribed event
158 records. For dynamic subscriptions, the receiver and subscriber are
159 the same entity.
161 Stream (also referred to as "event stream"): A continuous ordered set
162 of events aggregated under some context.
164 Stream filter: Evaluation criteria which may be applied against event
165 records within a stream. Event records pass the filter when
166 specified criteria are met.
168 Subscribed event records: Event records which have met the terms of
169 the subscription. This include terms (such as security checks)
170 enforced by the publisher.
172 Subscriber: An entity able to request and negotiate a contract for
173 the generation and push of event records from a publisher.
175 Subscription: A contract with a publisher, stipulating which
176 information one or more receivers wish to have pushed from the
177 publisher without the need for further solicitation.
179 1.3. Solution Overview
181 This document describes a transport agnostic mechanism for
182 subscribing to and receiving content from a stream instantiated
183 within a publisher. This mechanism is through the use of a
184 subscription.
186 Two types of subscriptions are supported:
188 1. Dynamic subscriptions, where a subscriber initiates a
189 subscription negotiation with a publisher via RPC. If the
190 publisher wants to serve this request, it accepts it, and then
191 starts pushing notification messages. If the publisher does not
192 wish to serve it as requested, then an error response is
193 returned. This response MAY include hints at subscription
194 parameters which would have been accepted.
196 2. Configured subscriptions, which allow the management of
197 subscriptions via a configuration interface so that a publisher
198 can send notification messages to configured receiver(s).
199 Support for this capability is optional.
201 Additional characteristics differentiating configured from dynamic
202 subscriptions include:
204 o The lifetime of a dynamic subscription is bounded by the transport
205 session used to establish it. For connection-oriented stateful
206 transport like NETCONF, the loss of the transport session will
207 result in the immediate termination of any associated dynamic
208 subscriptions. For connectionless or stateless transports like
209 HTTP, a lack of receipt acknowledgment of a sequential set of
210 notification messages and/or keep-alives can be used to trigger a
211 termination of a dynamic subscription. Contrast this to the
212 lifetime of a configured subscription. This lifetime is driven by
213 relevant configuration being present within the publisher's
214 running configuration. Being tied to configuration operations
215 implies configured subscriptions can be configured to persist
216 across reboots, and implies a configured subscription can persist
217 even when its publisher is fully disconnected from any network.
219 o Configured subscriptions can be modified by any configuration
220 client with write permission on the configuration of the
221 subscription. Dynamic subscriptions can only be modified via an
222 RPC request made by the original subscriber.
224 Note that there is no mixing-and-matching of dynamic and configured
225 operations on a single subscription. Specifically, a configured
226 subscription cannot be modified or deleted using RPCs defined in this
227 document. Similarly, a subscription established via RPC cannot be
228 modified through configuration operations. Also note that transport
229 specific transport drafts based on this specification MUST detail the
230 life cycles of both dynamic and configured subscriptions.
232 The publisher MAY decide to terminate a dynamic subscription at any
233 time. Similarly, it MAY decide to temporarily suspend the sending of
234 notification messages for any dynamic subscription, or for one or
235 more receivers of a configured subscription. Such termination or
236 suspension is driven by internal considerations of the publisher.
238 1.4. Relationship to RFC-5277
240 This document is intended to provide a superset of the subscription
241 capabilities initially defined within [RFC5277]. Especially when
242 extending an existing [RFC5277] implementation, it is important to
243 understand what has been reused and what has been replaced. Key
244 relationships between these two documents include:
246 o the data model in this document replaces the data model in
247 [RFC5277].
249 o the RPC operations in this draft replaces the symmetrical
250 operations of [RFC5277], section 4.
252 o the one way operation of [RFC5277] is still used. However this
253 operation will no longer be required with the availability of
254 [I.D.draft-ietf-netconf-notification-messages].
256 o the definition and contents of the NETCONF stream are identical
257 between this document and [RFC5277].
259 o a publisher MAY implement both the data model and RPCs defined in
260 [RFC5277] and this new document concurrently, in order to support
261 old clients. However the use of both alternatives on a single
262 transport session is prohibited.
264 2. Solution
266 2.1. Event Streams
268 An event stream is a named entity on a publisher which exposes a
269 continuously updating set of event records. Each event stream is
270 available for subscription. It is out of the scope of this document
271 to identify a) how streams are defined, b) how event records are
272 defined/generated, and c) how event records are assigned to streams.
274 There is only one reserved event stream within this document:
275 NETCONF. The NETCONF event stream contains all NETCONF XML event
276 record information supported by the publisher, except for where it
277 has been explicitly indicated that this the event record MUST be
278 excluded from the NETCONF stream. The NETCONF stream will include
279 individual YANG notifications as per [RFC7950] section 7.16. Each of
280 these YANG notifications will be treated a distinct event record.
281 Beyond the NETCONF stream, implementations are free to add additional
282 event streams.
284 As event records are created by a system, they may be assigned to one
285 or more streams. The event record is distributed to subscription's
286 receiver(s) where: (1) a subscription includes the identified stream,
287 and (2) subscription filtering does not exclude the event record from
288 that receiver.
290 If access control permissions are in use to secure publisher content,
291 then for event records to be sent to a receiver, that receiver MUST
292 be allowed access to all the event records on the stream. If
293 subscriber permissions change during the lifecycle of a subscription
294 and stream access is no longer permitted, then the subscription MUST
295 be terminated.
297 2.2. Event Stream Filters
299 This document defines an extensible filtering mechanism. Two
300 optional stream filtering syntaxes supported are [XPATH] and subtree
301 [RFC6241]. A filter always removes a complete event record; a subset
302 of information is never stripped from an event record.
304 If no stream filter is provided within a subscription, all event
305 records on a stream are to be sent.
307 2.3. QoS
309 This document provides an optional feature describing QoS parameters.
310 These parameters indicate the treatment of a subscription relative to
311 other traffic between publisher and receiver. Included are:
313 o A "dscp" QoS marking to differentiate transport QoS behavior.
314 Where provided, this marking MUST be stamped on notification
315 messages.
317 o A "weighting" so that bandwidth proportional to this weighting can
318 be allocated to this subscription relative to other subscriptions
319 destined for that receiver.
321 o a "dependency" upon another subscription. Notification messages
322 MUST NOT be sent prior to other notification messages containing
323 update record(s) for the referenced subscription.
325 A subscription's weighting MUST work identically to stream dependency
326 weighting as described within RFC 7540, section 5.3.2.
328 A subscription's dependency MUST work identically to stream
329 dependency as described within [RFC7540], sections 5.3.1, 5.3.3, and
330 5.3.4. If a dependency is attempted via an RPC, but the referenced
331 subscription does not exist, the dependency will be silently removed.
333 2.4. Dynamic Subscriptions
335 Dynamic subscriptions are managed via RPC, and are made against
336 targets located within the publisher. These RPCs have been designed
337 extensibly so that they may be augmented for subscription targets
338 beyond event streams.
340 2.4.1. Dynamic Subscription State Model
342 Below is the publisher's state machine for a dynamic subscription.
343 It is important to note that such a subscription doesn't exist at the
344 publisher until an "establish-subscription" RPC is accepted. The
345 mere request by a subscriber to establish a subscription is
346 insufficient for that asserted subscription to be externally visible.
347 States that are reflected in the YANG model appear in upper-case
348 letters; in addition, start and end states are depicted to reflect
349 subscription creation and deletion events.
351 .........
352 : start :
353 :.......:
354 |
355 establish-subscription
356 |
357 | .------modify-subscription-------.
358 v v '
359 .-----------. .-----------.
360 .--------. | receiver |-subscription-suspended->| receiver |
361 modify- '| ACTIVE | | SUSPENDED |
362 subscription | |<--subscription-resumed--| |
363 ---------->'-----------' '-----------'
364 | |
365 delete/kill-subscription delete/kill-
366 | subscription
367 v |
368 ......... |
369 : end :<-------------------------------'
370 :.......:
372 Receiver state for a dynamic subscription
374 Of interest in this state machine are the following:
376 o Successful establish or modify RPCs put the subscription into an
377 active state.
379 o Failed modify RPCs will leave the subscription in its previous
380 state, with no visible change to any streaming updates.
382 o A delete or kill RPC will end the subscription.
384 o The two state change notifications "subscription-suspended" and
385 "subscription-resumed" are shown. These are under the control of
386 a publisher. There are no direct controls over suspend and resume
387 other than to attempt a modification of a subscription.
389 2.4.2. Establishing a Subscription
391 The "establish-subscription" operation allows a subscriber to request
392 the creation of a subscription via RPC. It MUST be possible to
393 support multiple establish subscription RPC requests made within the
394 same transport session. And it MUST be possible to support the
395 interleaving of RPC requests made on independent subscriptions.
397 The input parameters of the operation are:
399 o A stream name which identifies the targeted stream of events
400 against which the subscription is applied.
402 o A stream filter which may reduce the set of event records pushed.
404 o An optional encoding for the event records pushed. Note: If no
405 encoding is included, the encoding of the RPC MUST be used.
407 o An optional stop time for the subscription. If no stop-time is
408 present, notification messages will continue to be sent until the
409 subscription is terminated.
411 o An optional start time for the subscription. If the start-time is
412 in the past, it indicates that this subscription is requesting a
413 replay of previously generated information from the event stream.
414 For more on replay, see Section 2.4.2.1.
416 If the publisher can satisfy the "establish-subscription" request, it
417 provides an identifier for the subscription, and immediately starts
418 streaming notification messages.
420 +---x establish-subscription
421 +---w input
422 | +---w encoding? encoding
423 | +---w (target)
424 | | +--:(stream)
425 | | +---w (stream-filter)?
426 | | | +--:(by-reference)
427 | | | | +---w stream-filter-ref stream-filter-ref
428 | | | +--:(within-subscription)
429 | | | +---w (filter-spec)?
430 | | | +--:(stream-subtree-filter)
431 | | | | +---w stream-subtree-filter? {subtree}?
432 | | | +--:(stream-xpath-filter)
433 | | | +---w stream-xpath-filter?
434 | | | yang:xpath1.0 {xpath}?
435 | | +---w stream? stream-ref
436 | | +---w replay-start-time? yang:date-and-time {replay}?
437 | +---w stop-time? yang:date-and-time
438 | +---w dscp? inet:dscp {qos}?
439 | +---w weighting? uint8 {qos}?
440 | +---w dependency? sn:subscription-id {qos}?
441 +--ro output
442 +--ro identifier subscription-id
444 Figure 1: establish-subscription RPC
446 A publisher MAY reject this RPC for many reasons as described in
447 Section 2.4.6. The contents of the resulting RPC error response MAY
448 include one or more hints on alternative inputs which would have
449 resulted in a successfully established subscription. Any such hints
450 MUST be transported within a yang-data "establish-subscription-error-
451 stream" container included within the RPC error response.
453 yang-data establish-subscription-error-stream
454 +--ro establish-subscription-error-stream
455 +--ro reason? identityref
456 +--ro filter-failure-hint? string
457 +--ro replay-start-time-hint? yang:date-and-time
459 Figure 2: establish-subscription RPC yang-data
461 2.4.2.1. Replay Subscription
463 Replay provides the ability to establish a subscription which is also
464 capable of passing recently generated event records. In other words,
465 as the subscription initializes itself, it sends any previously
466 generated content from within target event stream which meets the
467 filter and timeframe criteria. These historical event records would
468 then be followed by event records generated after the subscription
469 has been established. All event records will be delivered in the
470 order generated.
472 Replay is an optional feature which is dependent on an event stream
473 supporting some form of logging. Replay puts no restrictions on the
474 size or form of the log, or where it resides within the device.
476 The inclusion of a replay-start-time within an "establish-
477 subscription" RPC indicates a replay request. If the "replay-start-
478 time" contains a value that is earlier than content stored within the
479 publisher's replay buffer, then the subscription MUST be rejected,
480 and the leaf "replay-start-time-hint" MUST be set in the reply.
482 If a "stop-time" parameter is included, it MAY also be earlier than
483 the current time and MUST be later than the "replay-start-time". The
484 publisher MUST NOT accept a "replay-start-time" for a future time.
486 If the "replay-start-time" is later than any information stored in
487 the replay buffer, then the publisher MUST send a "replay-completed"
488 notification immediately after the "subscription-started"
489 notification.
491 If a stream supports replay, the "replay-support" leaf is present in
492 the "/streams/stream" list entry for the stream. An event stream
493 that does support replay is not expected to have an unlimited supply
494 of saved notifications available to accommodate any given replay
495 request. To assess the availability of replay, subscribers can
496 perform a get on "replay-log-creation-time" and "replay-log-aged-
497 time". See Figure 10 for the tree describing these elements. The
498 actual size of the replay log at any given time is a publisher
499 specific matter. Control parameters for the replay log are outside
500 the scope of this document.
502 2.4.3. Modifying a Subscription
504 The "modify-subscription" operation permits changing the terms of an
505 existing dynamic subscription previously established on that
506 transport session via "establish-subscription". Dynamic
507 subscriptions can be modified one or multiple times. If the
508 publisher accepts the requested modifications, it acknowledges
509 success to the subscriber, then immediately starts sending event
510 records based on the new terms.
512 Dynamic subscriptions established via RPC can only be modified via
513 RPC using the same transport session used to establish that
514 subscription. Subscriptions created by configuration operations
515 cannot be modified via this RPC.
517 +---x modify-subscription
518 +---w input
519 +---w identifier? subscription-id
520 +---w (target)
521 | +--:(stream)
522 | +---w (stream-filter)?
523 | +--:(by-reference)
524 | | +---w stream-filter-ref stream-filter-ref
525 | +--:(within-subscription)
526 | +---w (filter-spec)?
527 | +--:(stream-subtree-filter)
528 | | +---w stream-subtree-filter? {subtree}?
529 | +--:(stream-xpath-filter)
530 | +---w stream-xpath-filter?
531 | yang:xpath1.0 {xpath}?
532 +---w stop-time? yang:date-and-time
534 Figure 3: modify-subscription RPC
536 If the publisher accepts the requested modifications on a currently
537 suspended subscription, the subscription will immediately be resumed
538 (i.e., the modified subscription is returned to an active state.)
539 The publisher MAY immediately suspend this newly modified
540 subscription through the "subscription-suspended" notification before
541 any event records are sent.
543 If the publisher rejects the RPC request, the subscription remains as
544 prior to the request. That is, the request has no impact whatsoever.
545 Rejection of the RPC for any reason is indicated by via RPC error as
546 described in Section 2.4.6. The contents of a such a rejected RPC
547 MAY include one or more hints on alternative inputs which would have
548 resulted in a successfully modified subscription. These hints MUST
549 be transported within a yang-data "modify-subscription-error-stream"
550 container inserted into the RPC error response.
552 yang-data modify-subscription-error-stream
553 +--ro modify-subscription-error-stream
554 +--ro reason? identityref
555 +--ro filter-failure-hint? string
557 Figure 4: modify-subscription RPC yang-data
559 2.4.4. Deleting a Subscription
561 The "delete-subscription" operation permits canceling an existing
562 subscription previously established on that transport session. If
563 the publisher accepts the request, and the publisher has indicated
564 success, the publisher MUST NOT send any more notification messages
565 for this subscription. If the publisher rejects the request, the
566 request has no impact whatsoever on any subscription.
568 +---x delete-subscription
569 +---w input
570 +---w identifier subscription-id
572 Figure 5: delete-subscription RPC
574 Dynamic subscriptions can only be deleted via this RPC using the same
575 transport session previously used for subscription establishment.
576 Configured subscriptions cannot be deleted using RPCs.
578 2.4.5. Killing a Subscription
580 The "kill-subscription" operation permits an operator to end a
581 dynamic subscription which is not associated with the transport
582 session used for the RPC. This operation MUST be secured so that
583 only connections with sufficiently privileged access rights are able
584 to invoke this RPC. A publisher MUST terminate any dynamic
585 subscription identified by RPC request. An operator may find
586 subscription identifiers which may be used with "kill-subscription"
587 by searching for the IP address of a receiver within
588 "subscriptions\subscription\receivers\receiver\address".
590 Configured subscriptions cannot be killed using this RPC. Instead,
591 configured subscriptions are deleted as part of regular configuration
592 operations. Publishers MUST reject any RPC attempt to kill a
593 configured subscription.
595 The tree structure of "kill-subscription" is almost identical to
596 "delete-subscription", with only the name of the RPC and yang-data
597 changing.
599 2.4.6. RPC Failures
601 Whenever an RPC is unsuccessful, the publisher returns relevant error
602 codes as part of the RPC error response. RPC error codes returned
603 include both existing transport layer RPC error codes, such as those
604 seen with NETCONF in [RFC6241] Appendix A, as well as subscription
605 specific errors such as those defined within this document's YANG
606 model. As a result of this mixture, how subscription errors are
607 encoded within an RPC error response is transport dependent.
609 There are elements of the RPC error mechanism which are transport
610 independent. Specifically, references to specific identities within
611 the YANG model MUST be returned as part of the error responses
612 resulting from failed attempts at event stream subscription.
613 Following are valid errors per RPC:
615 establish-subscription modify-subscription
616 ---------------------- -------------------
617 dscp-unavailable filter-unsupported
618 filter-unsupported insufficient-resources
619 history-unavailable no-such-subscription
620 insufficient-resources
621 replay-unsupported
623 delete-subscription kill-subscription
624 ---------------------- ----------------------
625 no-such-subscription no-such-subscription
627 There is one final set of transport independent RPC error elements
628 included in the YANG model. These are the following three yang-data
629 structures for failed event stream subscriptions:
631 1. yang-data establish-subscription-error-stream: This MUST be
632 returned if an RPC error reason has not been placed elsewhere
633 within the transport portion of a failed "establish-subscription"
634 RPC response. This MUST be sent if hints on how to overcome the
635 RPC error are included.
637 2. yang-data modify-subscription-error-stream: This MUST be returned
638 if an RPC error reason has not been placed elsewhere within the
639 transport portion of a failed "modify-subscription" RPC response.
640 This MUST be sent if hints on how to overcome the RPC error are
641 included.
643 3. yang-data delete-subscription-error: This MUST be returned if an
644 RPC error reason has not been placed elsewhere within the
645 transport portion of a failed "delete-subscription" or "kill-
646 subscription" RPC response.
648 2.5. Configured Subscriptions
650 A configured subscription is a subscription installed via a
651 configuration interface. Configured subscriptions may be modified by
652 any configuration client with the proper permissions. Subscriptions
653 can be modified or terminated via the configuration interface at any
654 point of their lifetime.
656 Configured subscriptions have several characteristics distinguishing
657 them from dynamic subscriptions:
659 o persistence across reboots,
660 o persistence even when transport is unavailable, and
662 o an ability to send notification messages to more than one receiver
663 (note that the publisher does not provide information to a
664 receiver about other receivers.)
666 Supporting configured subscriptions is optional and advertised using
667 the "configured" feature.
669 In addition to subscription parameters available to dynamic
670 subscriptions as described in Section 2.4.2, the following additional
671 parameters are also available to configured subscriptions:
673 o One or more receiver IP addresses (and corresponding ports)
674 intended as the destination for notification messages.
676 o Optional parameters to identify an egress interface, a host IP
677 address, a VRF (as defined by the network instance name within
678 [I-D.draft-ietf-rtgwg-ni-model]), or an IP address plus VRF out of
679 which notification messages are to be pushed from the publisher.
680 Where any of this info is not explicitly included, or where just
681 the VRF is provided, notification messages MUST egress the
682 publisher's default interface towards that receiver.
684 2.5.1. Configured Subscription State Model
686 Below is the state machine for a configured subscription. States
687 that are reflected in the YANG model appear in upper-case letters; in
688 addition, start and end states are depicted to reflect configured
689 subscription creation and deletion events. The creation or
690 modification of a configured subscription initiates a publisher
691 evaluation to determine if the subscription is valid or invalid. The
692 publisher uses its own criteria in making this determination. If
693 valid, the subscription becomes operational.
695 .........
696 : start :-.
697 :.......: |
698 create .---modify-----.----------------------------------.
699 | | | |
700 V V .-------. ....... .---------.
701 .----[evaluate]--no--->|INVALID|-delete->: end :<-delete-|CONCLUDED|
702 | '-------' :.....: '---------'
703 |----[evaluate]--no-. ^ ^ ^
704 | ^ | | | |
705 yes | '->unsupportable delete stop-time
706 | modify (subscription- (subscription- (subscription-
707 | | terminated) terminated) concluded)
708 | | | | |
709 | .---------------------------------------------------------------.
710 '-->| VALID |
711 '---------------------------------------------------------------'
713 State model for a configured subscription.
715 A valid subscription may become invalid on one of two ways. First,
716 it may be modified in a way which fails a re-evaluation. Second, the
717 publisher itself might itself determine that the subscription in no
718 longer supportable. In either case, a "subscription-terminated"
719 notification is sent to any active or suspended receivers. A valid
720 subscription may also transition to a concluded state if a configured
721 stop time has been reached. In this case, a "subscription-concluded"
722 is sent to any active or suspended receivers.
724 During any times a subscription is considered valid, a publisher will
725 attempt to connect with all configured receivers and deliver
726 notification messages. Below is the state machine for each receiver
727 of a configured subscription. This receiver state machine itself is
728 fully contained within the state machine of the configured
729 subscription, and is only relevant when the configured subscription
730 itself is determined to be valid.
732 .----------------------------------------------------------------.
733 | VALID |
734 | .----------. .--------. |
735 | | receiver |------------------timeout->|receiver| |
736 | |CONNECTING|<------------------reset---|TIMEOUT | |
737 | | |<-transport---. '--------' |
738 | '----------' loss,reset | |
739 | | | | |
740 | (subscription | | |
741 | started) .--------. | .---------. |
742 | '----->| | '----------------------| | |
743 | |receiver|-(subscription-suspended)-->|receiver | |
744 |(subscription-| ACTIVE | |SUSPENDED| |
745 | modified) | |<-(subscription-resumed,----| | |
746 | '---->'--------' subscription-modified) '---------' |
747 '----------------------------------------------------------------'
749 Receiver state for a configured subscription
751 When a subscription first becomes valid, the operational state of
752 each receiver is initialized to connecting. Individual receivers are
753 moved to an active state when a "subscription-started" state change
754 notification is successfully passed to that receiver. Configured
755 receivers remain active if transport connectivity is not lost, and
756 event records are not being dropped due to a publisher buffer
757 overflow. A configured subscription's receiver MUST be moved to
758 connecting if transport connectivity is lost, or if the receiver is
759 reset via configuration operations.
761 A configured subscription's receiver MUST be moved to a suspended
762 state if there is transport connectivity between the publisher and
763 receiver, but notification messages are not being generated for that
764 receiver. A configured subscription receiver MUST be returned to an
765 active state from the suspended state when notification messages are
766 again being generated and a receiver has successfully been sent a
767 "subscription-resumed" or a "subscription-modified".
769 Modification of a configured subscription is possible at any time. A
770 "subscription-modified" state change notification will be sent to all
771 active receivers, immediately followed by notification messages
772 conforming to the new parameters. Suspended receivers will also be
773 informed of the modification. However this notification will await
774 the end of the suspension for that receiver.
776 The mechanisms described above is mirrored in the RPCs and YANG
777 notifications within the document. It should be noted that these
778 RPCs and YANG notifications have been designed to be extensible and
779 allow subscriptions into targets other than event streams.
781 [I-D.ietf-netconf-yang-push] provides an example of such an
782 extension.
784 2.5.2. Creating a Configured Subscription
786 Configured subscriptions are established using configuration
787 operations against the top-level "subscriptions" subtree. There are
788 two key differences between the new RPCs defined in this document and
789 configuration operations for subscription creation. Firstly,
790 configuration operations install a subscription without question,
791 while the RPCs are designed to the support negotiation and rejection
792 of requests. Secondly, while the RPCs mandate that the subscriber
793 establishing the subscription is the only receiver of the
794 notification messages, configuration operations permit specifying
795 receivers independent of any tracked subscriber. Because there is no
796 explicit association with an existing transport session,
797 configuration operations require additional parameters beyond those
798 of dynamic subscriptions to indicate receivers, and possibly whether
799 the notification messages need to come from a specific egress
800 interface on the publisher.
802 After a subscription is successfully created, the publisher
803 immediately sends a "subscription-started" state change notification
804 to each receiver. It is quite possible that upon configuration,
805 reboot, or even steady-state operations, a transport session may not
806 be currently available to the receiver. In this case, when there is
807 something to transport for an active subscription, transport specific
808 call-home operations will be used to establish the connection. When
809 transport connectivity is available, notification messages may then
810 be pushed.
812 With active configured subscriptions, it is allowable to buffer event
813 records even after a "subscription-started" has been sent. However
814 if events are lost (rather than just delayed) due to replay buffer
815 overflow, a new "subscription-started" must be sent. This new
816 "subscription-started" indicates an event record discontinuity.
818 To see an example at subscription creation using configuration
819 operations over NETCONF, see Appendix A of
820 [I-D.draft-ietf-netconf-netconf-event-notifications].
822 Note that is possible to configure replay on a configured
823 subscription. This capability is to allow a configured subscription
824 to exist on a system so that event records generated during boot can
825 be buffered and pushed as soon as the transport session is
826 established.
828 2.5.3. Modifying a Configured Subscription
830 Configured subscriptions can be modified using configuration
831 operations against the top-level "subscriptions" subtree.
833 If the modification involves adding receivers, added receivers are
834 placed in the "connecting" state. If a receiver is removed, the
835 state change notification "subscription-terminated" is sent to that
836 receiver if that receiver is "active" or "suspended" .
838 If the modification involves changing the policies for the
839 subscription, the publisher sends to currently active receivers a
840 "subscription-modified" notification. For any suspended receivers, a
841 "subscription-modified" notification will be delayed until the
842 receiver is resumed. (Note: in this case, the "subscription-
843 modified" notification informs the receiver that the subscription has
844 been resumed, so no additional "subscription-resumed" need be sent.)
846 2.5.4. Deleting a Configured Subscription
848 Subscriptions can be deleted using configuration operations against
849 the top-level "subscriptions" subtree.
851 Immediately after a subscription is successfully deleted, the
852 publisher sends to all receivers of that subscription a state change
853 notification stating the subscription has ended (i.e., "subscription-
854 terminated").
856 2.5.5. Resetting a Configured Receiver
858 It is possible that a configured subscription to a receiver needs to
859 be reset. This re-initialization may be useful in cases where a
860 publisher has timed out trying to reach a receiver. When such a
861 reset occurs, a transport session will be initiated if necessary, and
862 a new "subscription-started" notification will be sent.
864 2.6. Event Record Delivery
866 Whether dynamic or configured, once a subscription has been set up,
867 the publisher streams event records via notification messages per the
868 terms of the subscription. For dynamic subscriptions set up via RPC
869 operations, notification messages are sent over the session used to
870 establish the subscription. For configured subscriptions,
871 notification messages are sent over the connections specified by the
872 transport, plus receiver IP address and port configured. In all
873 cases, a single transport session MUST be able to support the
874 interleaving of event records, RPCs, and state change notifications
875 from independent subscriptions.
877 A notification message is sent to a receiver when an event record is
878 able to traverse the specified filter criteria. This notification
879 message MUST be encoded as one-way notification element of [RFC5277],
880 Section 4. A subscription's events MUST NOT be sent to a receiver
881 until after a corresponding RPC response or state-change notification
882 has been passed receiver indicating that events should be expected.
883 The following example within [RFC7950] section 7.16.3 is an example
884 of a compliant message:
886
888 2007-09-01T10:00:00Z
889
890 so-1/2/3.0
891 up
892 down
893
894
896 Figure 6: subscribed notification message
898 This [RFC5277] section 4 one-way operation has the drawback of not
899 including useful header information such as a subscription
900 identifier. When using this mechanism, it is left up to
901 implementations or augmentations to this document to determine which
902 event records belong to which subscription.
904 These drawbacks, along with other useful common headers and the
905 ability to bundle multiple event records together is being explored
906 within [I.D.draft-ietf-netconf-notification-messages]. When the
907 notification-messages is supported, this document will be updated to
908 indicate support.
910 2.7. Subscription State Notifications
912 In addition to subscribed event records, a publisher MUST send
913 subscription state notifications to indicate to receivers that an
914 event related to the subscription management has occurred.
916 Subscription state notifications are unlike other notifications which
917 might be found in the event stream. They cannot be filtered out, and
918 they are delivered only to directly impacted receiver(s) of a
919 subscription. The identification of subscription state notifications
920 is easy to separate from other notification messages through the use
921 of the YANG extension "subscription-state-notif". This extension
922 tags a notification as subscription state notification.
924 The complete set of subscription state notifications is described in
925 the following subsections.
927 2.7.1. subscription-started
929 This notification indicates that a configured subscription has
930 started, and event records may be sent. Included in this state
931 change notification are all the parameters of the subscription,
932 except for the receiver(s) addressing information and origin
933 information indicating where notification messages will egress the
934 publisher. Note that if a referenced filter from the "filters"
935 container has been used within the subscription, the notification
936 will still provide the contents of that referenced filter under the
937 "within-subscription" subtree.
939 Note that for dynamic subscriptions, no "subscription-started"
940 notifications are ever sent.
942 +---n subscription-started {configured}?
943 +--ro identifier subscription-id
944 +--ro protocol transport {configured}?
945 +--ro encoding encoding
946 +--ro (target)
947 | +--:(stream)
948 | +--ro (stream-filter)?
949 | | +--:(by-reference)
950 | | | +--ro stream-filter-ref stream-filter-ref
951 | | +--:(within-subscription)
952 | | +--ro (filter-spec)?
953 | | +--:(stream-subtree-filter)
954 | | | +--ro stream-subtree-filter? {subtree}?
955 | | +--:(stream-xpath-filter)
956 | | +--ro stream-xpath-filter? yang:xpath1.0 {xpath}?
957 | +--ro stream stream
958 | +--ro replay-start-time? yang:date-and-time {replay}?
959 +--ro stop-time? yang:date-and-time
960 +--ro dscp? inet:dscp {qos}?
961 +--ro weighting? uint8 {qos}?
962 +--ro dependency? sn:subscription-id {qos}?
964 Figure 7: subscription-started notification
966 2.7.2. subscription-modified
968 This notification indicates that a subscription has been modified by
969 configuration operations. The same parameters of "subscription-
970 started" are provided via this notification. As a result, the tree
971 structure of "subscription-modified" is almost identical to
972 "subscription-started", with only the name of the notification
973 changing.
975 A publisher most often sends this notification directly after the
976 modification of any configuration parameters impacting a configured
977 subscription. But it may also be sent at two other times.
979 o First, where a configured subscription has been modified during
980 the suspension of a receiver, the notification will be delayed
981 until the receiver's suspension is lifted. In this situation, the
982 notification indicates that the subscription has been both
983 modified and resumed.
985 o Second, for dynamic subscriptions, there is one and only one time
986 this notification may be sent. A "subscription-modified" state
987 change notifications MUST be sent if the contents of a filter
988 identified by a "stream-filter-ref" has changed.
990 2.7.3. subscription-terminated
992 The publisher MAY decide to terminate the pushing of subscribed event
993 records to a receiver. This notification indicates that no further
994 notification messages should be expected from the publisher. Such a
995 decision may be made for two types of reasons. The first type of
996 reason is that a subscription's referenced objects are no longer
997 accessible via the YANG model. Identities within the YANG model
998 corresponding to such a loss include: "filter-unavailable", "no-such-
999 subscription", and "stream-unavailable". The second reason is that a
1000 suspended subscription has exceeded some timeout. This condition is
1001 indicated via the identity "suspension-timeout". Publisher-driven
1002 terminations are always notified to all receivers.
1004 +---n subscription-terminated
1005 +--ro identifier subscription-id
1006 +--ro reason identityref
1008 Figure 8: subscription-terminated notification
1010 Note: subscribers themselves can terminate existing subscriptions
1011 established via a "delete-subscription" RPC. In such cases, no
1012 "subscription-terminated" state change notifications are sent.
1013 However if a "kill-subscription" RPC is sent, or some other event
1014 other than reaching the subscription's stop time results in the end
1015 of a subscription, then this state change notification MUST be sent.
1017 2.7.4. subscription-suspended
1019 This notification indicates that a publisher has suspended the
1020 sending of event records to a receiver, and also indicates the
1021 possible loss of events. Suspension happens when capacity
1022 constraints stop a publisher from serving a valid subscription. The
1023 two conditions where is this possible are "insufficient-resources"
1024 and "unsupportable-volume". No further notification will be sent
1025 until the subscription resumes or is terminated.
1027 The tree structure of "subscription-suspended" is almost identical to
1028 "subscription-terminated", with only the name of the notification
1029 changing.
1031 2.7.5. subscription-resumed
1033 This indicates that a previously suspended subscription has been
1034 resumed under the unmodified terms previously in place. Subscribed
1035 event records generated after the generation of this state change
1036 notification will be sent.
1038 +---n subscription-resumed
1039 +--ro identifier subscription-id
1041 Figure 9: subscription-resumed notification
1043 2.7.6. subscription-completed
1045 This notification indicates that a subscription, which includes a
1046 "stop-time", has successfully finished passing event records upon the
1047 reaching of that time.
1049 The tree structure of "subscription-completed" is almost identical to
1050 "subscription-resumed", with only the name of the notification
1051 changing.
1053 2.7.7. replay-completed
1055 This notification indicates that all of the event records prior to
1056 the current time have been sent. This includes new event records
1057 generated since the start of the subscription. This notification
1058 MUST NOT be sent for any other reason.
1060 If subscription contains no "stop-time", or has a "stop-time" which
1061 has not been reached, then after the "replay-completed" notification
1062 has been sent, additional event records will be sent in sequence as
1063 they arise naturally on the publisher.
1065 The tree structure of "replay-completed" is almost identical to
1066 "subscription-resumed", with only the name of the notification
1067 changing.
1069 2.8. Subscription Monitoring
1071 Container "subscriptions" in the YANG module contains the state of
1072 all known subscriptions. This includes subscriptions that were
1073 established (and have not yet been deleted) using RPCs, as well as
1074 subscriptions that have been configured as part of configuration.
1075 Using the "get" operation with NETCONF, or subscribing to this
1076 information via [I-D.ietf-netconf-yang-push] allows the state of
1077 subscriptions and their connectivity to receivers to be monitored.
1079 Each subscription is represented as a list element. The associated
1080 information includes an identifier for the subscription, receiver
1081 counter information, the state of the receiver (e.g., is currently
1082 active or suspended), as well as the various subscription parameters
1083 that are in effect. Leaf "configured-subscription-state" indicates
1084 that the subscription came into being via configuration, and the
1085 current state of the configured subscription.
1087 Subscriptions that were established by RPC are removed from the list
1088 once they expire (reaching stop-time) or when they are terminated.
1089 Subscriptions that were established by configuration need to be
1090 deleted from the configuration by a configuration editing operation
1091 even if the stop time has been passed.
1093 2.9. Advertisement
1095 Publishers supporting this document MUST indicate support of the YANG
1096 model "ietf-subscribed-notifications" within the YANG library of the
1097 publisher. In addition support for optional features: "encode-xml",
1098 "encode-json", "configured" "supports-vrf", and "replay" MUST also be
1099 indicated if supported.
1101 If a publisher supports this specification but not subscriptions via
1102 [RFC5277], the publisher MUST NOT advertise
1103 "urn:ietf:params:netconf:capability:notification:1.0". Even without
1104 this advertisement however, the publisher MUST support the one-way
1105 notification element of [RFC5277] Section 4.
1107 3. YANG Data Model Trees
1109 This section contains tree diagrams for top level YANG Data Node
1110 containers defined in Section 4. If you would rather see tree
1111 diagrams for Notifications, see Section 2.7. Or for the tree
1112 diagrams for the RPCs, see Section 2.4.
1114 3.1. Event Streams Container
1116 A publisher maintains a list of available event streams as
1117 operational data. This list contains both standardized and vendor-
1118 specific event streams. The list of event streams that are supported
1119 by the publisher and against which subscription is allowed may be
1120 acquired from the "streams" container within the YANG module.
1122 +--rw streams
1123 +--rw stream* [name]
1124 +--rw name stream
1125 +--rw description string
1126 +--rw replay-support? empty {replay}?
1127 +--rw replay-log-creation-time? yang:date-and-time {replay}?
1128 +--rw replay-log-aged-time? yang:date-and-time {replay}?
1130 Figure 10: Stream Container
1132 3.2. Event Stream Filters Container
1134 The "filters" container maintains a list of all subscription filters
1135 which persist outside the life-cycle of a single subscription. This
1136 enables pre-defined and validated filters which may be referenced and
1137 used by more than one subscription.
1139 +--rw filters
1140 +--rw stream-filter* [identifier]
1141 +--rw identifier filter-id
1142 +--rw (filter-spec)?
1143 +--:(stream-subtree-filter)
1144 | +--rw stream-subtree-filter? {subtree}?
1145 +--:(stream-xpath-filter)
1146 +--rw stream-xpath-filter? yang:xpath1.0 {xpath}?
1148 Figure 11: Filter Container
1150 3.3. Subscriptions Container
1152 The "subscriptions" container maintains a list of all subscriptions
1153 on a publisher, both configured and dynamic. It can be used to
1154 retrieve information about the subscriptions which a publisher is
1155 serving.
1157 +--ro subscriptions
1158 +--ro subscription* [identifier]
1159 +--ro identifier subscription-id
1160 +--ro configured-subscription-state? enumeration {configured}?
1161 +--ro purpose? string {configured}?
1162 +--ro protocol transport {configured}?
1163 +--ro encoding encoding
1164 +--ro (target)
1165 | +--:(stream)
1166 | +--ro (stream-filter)?
1167 | | +--:(by-reference)
1168 | | | +--ro stream-filter-ref stream-filter-ref
1169 | | +--:(within-subscription)
1170 | | +--ro (filter-spec)?
1171 | | +--:(stream-subtree-filter)
1172 | | | +--ro stream-subtree-filter? {subtree}?
1173 | | +--:(stream-xpath-filter)
1174 | | +--ro stream-xpath-filter?
1175 | | yang:xpath1.0 {xpath}?
1176 | +--ro stream? stream-ref
1177 | +--ro replay-start-time? yang:date-and-time {replay}?
1178 +--ro stop-time? yang:date-and-time
1179 +--ro dscp? inet:dscp {qos}?
1180 +--ro weighting? uint8 {qos}?
1181 +--ro dependency? sn:subscription-id {qos}?
1182 +--ro (notification-message-origin)?
1183 | +--:(interface-originated)
1184 | | +--ro source-interface? if:interface-ref
1185 | +--:(address-originated)
1186 | +--ro source-vrf? ->
1187 | /ni:network-instances/network-instance/name {supports-vrf}?
1188 | +--ro source-address? inet:ip-address-no-zone
1189 +--ro receivers
1190 +--ro receiver* [address port]
1191 +--ro address inet:host
1192 +--ro port inet:port-number
1193 +--ro pushed-notifications? yang:counter64
1194 +--ro excluded-notifications? yang:counter64
1195 +--ro state enumeration
1196 +---x reset
1197 +--ro output
1198 +--ro time yang:date-and-time
1200 4. Data Model
1202 file "ietf-subscribed-notifications@2018-02-23.yang"
1203 module ietf-subscribed-notifications {
1204 yang-version 1.1;
1205 namespace
1206 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications";
1208 prefix sn;
1210 import ietf-yang-types {
1211 prefix yang;
1212 }
1213 import ietf-inet-types {
1214 prefix inet;
1215 }
1216 import ietf-interfaces {
1217 prefix if;
1218 }
1219 import ietf-network-instance {
1220 prefix ni;
1221 }
1222 import ietf-restconf {
1223 prefix rc;
1224 }
1226 organization "IETF";
1227 contact
1228 "WG Web:
1229 WG List:
1231 Editor: Alexander Clemm
1232
1234 Editor: Eric Voit
1235
1237 Editor: Alberto Gonzalez Prieto
1238
1240 Editor: Einar Nilsen-Nygaard
1241
1243 Editor: Ambika Prasad Tripathy
1244 ";
1246 description
1247 "Contains a YANG specification for subscribing to event records
1248 and receiving matching content within notification messages.";
1250 revision 2018-02-23 {
1251 description
1252 "Initial version";
1254 reference
1255 "draft-ietf-netconf-subscribed-notifications-10";
1256 }
1258 /*
1259 * FEATURES
1260 */
1262 feature encode-json {
1263 description
1264 "This feature indicates that JSON encoding of notification
1265 messages is supported.";
1266 }
1268 feature encode-xml {
1269 description
1270 "This feature indicates that XML encoding of notification
1271 messages is supported.";
1272 }
1274 feature configured {
1275 description
1276 "This feature indicates that configuration of subscription is
1277 supported.";
1278 }
1280 feature replay {
1281 description
1282 "This feature indicates that historical event record replay is
1283 supported. With replay, it is possible for past event records to
1284 be streamed in chronological order.";
1285 }
1287 feature xpath {
1288 description
1289 "This feature indicates support for xpath filtering.";
1290 reference "http://www.w3.org/TR/1999/REC-xpath-19991116";
1291 }
1293 feature subtree {
1294 description
1295 "This feature indicates support for YANG subtree filtering.";
1296 reference "RFC 6241, Section 6.";
1297 }
1299 feature supports-vrf {
1300 description
1301 "This feature indicates a publisher supports VRF configuration
1302 for configured subscriptions. VRF support for dynamic
1303 subscriptions does not require this feature.";
1304 reference "draft-ietf-rtgwg-ni-model";
1305 }
1307 feature qos {
1308 description
1309 "This feature indicates a publisher supports one or more optional
1310 Quality of Service (QoS) features to differentiate update record
1311 treatment between publisher and receiver.";
1312 }
1314 /*
1315 * EXTENSIONS
1316 */
1318 extension subscription-state-notification {
1319 description
1320 "This statement applies only to notifications. It indicates that
1321 the notification is a subscription state notification. Therefore
1322 it does not participate in a regular event stream and does not
1323 need to be specifically subscribed to in order to be received.
1324 This statement can only occur as a substatement to the YANG
1325 'notification' statement.";
1326 }
1328 /*
1329 * IDENTITIES
1330 */
1332 /* Identities for RPC and Notification errors */
1334 identity establish-subscription-error {
1335 description
1336 "Problem found while attempting to fulfill an
1337 'establish-subscription' rpc request. ";
1338 }
1340 identity modify-subscription-error {
1341 description
1342 "Problem found while attempting to fulfill a
1343 'modify-subscription' rpc request. ";
1344 }
1346 identity delete-subscription-error {
1347 description
1348 "Problem found while attempting to fulfill either a
1349 'delete-subscription' rpc request or a 'kill-subscription'
1350 rpc request. ";
1351 }
1353 identity subscription-terminated-reason {
1354 description
1355 "Problem condition communicated to a receiver as part of absolute
1356 'subscription-terminated' notification. ";
1357 }
1359 identity subscription-suspended-reason {
1360 description
1361 "Problem condition communicated to a receiver as part of absolute
1362 'subscription-terminated' notification. ";
1363 }
1365 identity dscp-unavailable {
1366 base establish-subscription-error;
1367 description
1368 "Requested DSCP marking not allocatable.";
1369 }
1371 identity filter-unavailable {
1372 base subscription-terminated-reason;
1373 description
1374 "Referenced filter does not exist. This means a receiver is
1375 referencing a filter which doesn't exist, or to which they do not
1376 have access permissions.";
1377 }
1379 identity filter-unsupported {
1380 base establish-subscription-error;
1381 base modify-subscription-error;
1382 description
1383 "Cannot parse syntax within the filter. This failure can be from
1384 a syntax error, or a syntax too complex to be processed by the
1385 publisher.";
1386 }
1388 identity history-unavailable {
1389 base establish-subscription-error;
1390 description
1391 "Replay request too far into the past. This means the publisher
1392 does store historic information for the requested stream, but
1393 not back to the requested timestamp.";
1394 }
1396 identity insufficient-resources {
1397 base establish-subscription-error;
1398 base modify-subscription-error;
1399 base subscription-suspended-reason;
1400 description
1401 "The publisher has insufficient resources to support the
1402 requested subscription.";
1403 }
1405 identity no-such-subscription {
1406 base modify-subscription-error;
1407 base delete-subscription-error;
1408 base subscription-terminated-reason;
1409 description
1410 "Referenced subscription doesn't exist. This may be as a result of
1411 a non-existent subscription ID, an ID which belongs to another
1412 subscriber, or an ID for configured subscription.";
1413 }
1415 identity replay-unsupported {
1416 base establish-subscription-error;
1417 description
1418 "Replay cannot be performed for this subscription. This means the
1419 publisher will not provide the requested historic information from
1420 the stream via replay to this receiver.";
1421 }
1423 identity stream-unavailable {
1424 base subscription-terminated-reason;
1425 description
1426 "Not a subscribable stream. This means the referenced stream is
1427 not available for subscription by the receiver.";
1428 }
1430 identity suspension-timeout {
1431 base subscription-terminated-reason;
1432 description
1433 "Termination of previously suspended subscription. The publisher
1434 has eliminated the subscription as it exceeded a time limit for
1435 suspension.";
1436 }
1438 identity unsupportable-volume {
1439 base subscription-suspended-reason;
1440 description
1441 "The publisher cannot support the volume of information intended
1442 to be sent for an existing subscription.";
1443 }
1445 /* Identities for encodings */
1446 identity encodings {
1447 description
1448 "Base identity to represent data encodings";
1449 }
1451 identity encode-xml {
1452 base encodings;
1453 if-feature "encode-xml";
1454 description
1455 "Encode data using XML";
1456 }
1458 identity encode-json {
1459 base encodings;
1460 if-feature "encode-json";
1461 description
1462 "Encode data using JSON";
1463 }
1465 /* Identities for transports */
1466 identity transport {
1467 description
1468 "An identity that represents a the underlying mechanism for
1469 passing notification messages.";
1470 }
1472 identity netconf {
1473 base transport;
1474 description
1475 "Netconf is used a transport for notification messages and state
1476 change notifications.";
1477 reference "draft-ietf-netconf-netconf-event-notifications";
1478 }
1480 identity http2 {
1481 base transport;
1482 description
1483 "HTTP2 is used a transport for notification messages and state
1484 change notifications.";
1485 reference "draft-ietf-netconf-restconf-notif-03, Sections 3.1.1" +
1486 "3.1.3";
1487 }
1489 identity http1.1 {
1490 base transport;
1491 description
1492 "HTTP1.1 is used a transport for notification messages and state
1493 change notifications.";
1495 reference "draft-ietf-netconf-restconf-notif-03, Section 3.1.2";
1496 }
1498 /*
1499 * TYPEDEFs
1500 */
1502 typedef subscription-id {
1503 type uint32;
1504 description
1505 "A type for subscription identifiers.";
1506 }
1508 typedef filter-id {
1509 type string;
1510 description
1511 "A type to identify filters which can be associated with a
1512 subscription.";
1513 }
1515 typedef encoding {
1516 type identityref {
1517 base encodings;
1518 }
1519 description
1520 "Specifies a data encoding, e.g. for a data subscription.";
1521 }
1523 typedef transport {
1524 type identityref {
1525 base transport;
1526 }
1527 description
1528 "Specifies protocol used to send notification messages to a
1529 receiver.";
1530 }
1532 typedef stream-ref {
1533 type leafref {
1534 path "/sn:streams/sn:stream/sn:name";
1535 }
1536 description
1537 "This type is used to reference a system-provided datastream.";
1538 }
1540 typedef stream-filter-ref {
1541 type leafref {
1542 path "/sn:filters/sn:stream-filter/sn:identifier";
1544 }
1545 description
1546 "This type is used to reference a configured stream filter.";
1547 }
1549 /*
1550 * GROUPINGS
1551 */
1553 grouping stream-filter-elements {
1554 description
1555 "This grouping defines the base for filters applied to event
1556 streams.";
1557 choice filter-spec {
1558 description
1559 "The content filter specification for this request.";
1560 anydata stream-subtree-filter {
1561 if-feature "subtree";
1562 description
1563 "Event stream evaluation criteria encoded in the syntax of a
1564 subtree filter as defined in RFC 6241, Section 6.
1566 The subtree filter is applied to the representation of
1567 individual, delineated event records as contained within the
1568 event stream. For example, if the notification message
1569 contains an instance of a notification defined in YANG, then
1570 the top-level element is the name of the YANG notification.
1572 If the subtree filter returns a non-empty node set, the filter
1573 matches the event record, and the it is included in the
1574 notification message sent to the receivers.";
1575 reference "RFC 6241, Section 6.";
1576 }
1577 leaf stream-xpath-filter {
1578 if-feature "xpath";
1579 type yang:xpath1.0;
1580 description
1581 "Event stream evaluation criteria encoded in the syntax of
1582 an XPath 1.0 expression.
1584 The XPath expression is evaluated on the representation of
1585 individual, delineated event records as contained within
1586 the event stream. For example, if the notification message
1587 contains an instance of a notification defined in YANG,
1588 then the top-level element is the name of the YANG
1589 notification, and the root node has this top-level element
1590 as the only child.
1592 The result of the XPath expression is converted to a
1593 boolean value using the standard XPath 1.0 rules. If the
1594 boolean value is 'true', the filter matches the event
1595 record, and the it is included in the notification message
1596 sent to the receivers.
1598 The expression is evaluated in the following XPath context:
1600 o The set of namespace declarations are those in scope on
1601 the 'xpath-filter' leaf element
1603 o The set of variable bindings is empty.
1605 o The function library is the core function library, and
1606 the XPath functions defined in section 10 in RFC 7950.
1608 o The context node is the root node.";
1609 reference
1610 "http://www.w3.org/TR/1999/REC-xpath-19991116
1611 RFC 7950, Section 10.";
1613 }
1614 }
1615 }
1617 grouping update-qos {
1618 description
1619 "This grouping describes Quality of Service information
1620 concerning a subscription. This information is passed to lower
1621 layers for transport prioritization and treatment";
1622 leaf dscp {
1623 if-feature "qos";
1624 type inet:dscp;
1625 default "0";
1626 description
1627 "The push update's IP packet transport priority. This is made
1628 visible across network hops to receiver. The transport
1629 priority is shared for all receivers of a given subscription.";
1630 }
1631 leaf weighting {
1632 if-feature "qos";
1633 type uint8 {
1634 range "0 .. 255";
1635 }
1636 description
1637 "Relative weighting for a subscription. Allows an underlying
1638 transport layer perform informed load balance allocations
1639 between various subscriptions";
1641 reference
1642 "RFC-7540, section 5.3.2";
1643 }
1644 leaf dependency {
1645 if-feature "qos";
1646 type subscription-id;
1647 description
1648 "Provides the Subscription ID of a parent subscription which
1649 has absolute priority should that parent have push updates
1650 ready to egress the publisher. In other words, there should be
1651 no streaming of objects from the current subscription if
1652 the parent has something ready to push.";
1653 reference
1654 "RFC-7540, section 5.3.1";
1655 }
1656 }
1658 grouping subscription-policy-modifiable {
1659 description
1660 "This grouping describes all objects which may be changed
1661 in a subscription via an RPC.";
1662 choice target {
1663 mandatory true;
1664 description
1665 "Identifies the source of information against which a
1666 subscription is being applied, as well as specifics on the
1667 subset of information desired from that source.";
1668 case stream {
1669 choice stream-filter {
1670 description
1671 "An event stream filter can be applied to a subscription.
1672 That filter will come either referenced from a global list,
1673 or be provided within the subscription itself.";
1674 case by-reference {
1675 description
1676 "Apply a filter that has been configured separately.";
1677 leaf stream-filter-ref {
1678 type stream-filter-ref;
1679 mandatory true;
1680 description
1681 "References an existing stream-filter which is to
1682 be applied to stream for the subscription.";
1683 }
1684 }
1685 case within-subscription {
1686 description
1687 "Local definition allows a filter to have the same
1688 lifecycle as the subscription.";
1690 uses stream-filter-elements;
1691 }
1692 }
1693 }
1694 }
1695 leaf stop-time {
1696 type yang:date-and-time;
1697 description
1698 "Identifies a time after which notification messages for a
1699 subscription should not be sent. If stop-time is not present,
1700 the notification messages will continue until the subscription
1701 is terminated. If replay-start-time exists, stop-time must be
1702 for a subsequent time. If replay-start-time doesn't exist,
1703 stop-time must be for a future time.";
1704 }
1705 }
1707 grouping subscription-policy-dynamic {
1708 description
1709 "This grouping describes information concerning a subscription
1710 which can just be passed over the RPCs defined in this model.";
1711 leaf encoding {
1712 type encoding;
1713 mandatory true;
1714 description
1715 "The type of encoding for the subscribed data.";
1716 }
1717 uses subscription-policy-modifiable {
1718 augment target/stream {
1719 description
1720 "Adds additional objects which can be modified by RPC.";
1721 leaf stream {
1722 type stream-ref {
1723 require-instance false;
1724 }
1725 mandatory true;
1726 description
1727 "Indicates the stream of event records to be considered for
1728 this subscription.";
1729 }
1730 leaf replay-start-time {
1731 if-feature "replay";
1732 type yang:date-and-time;
1733 description
1734 "Used to trigger the replay feature and indicate that the
1735 replay should start at the time specified. If
1736 replay-start-time is not present, this is not a replay
1737 subscription and event record push should start immediately.
1739 It is never valid to specify start times that are later than
1740 or equal to the current time.";
1741 }
1742 }
1743 }
1744 uses update-qos;
1745 }
1747 grouping subscription-policy {
1748 description
1749 "This grouping describes the full set of policy information
1750 concerning both dynamic and configured subscriptions, except for
1751 configured receivers.";
1752 leaf protocol {
1753 if-feature "configured";
1754 type transport;
1755 mandatory true;
1756 description
1757 "This leaf specifies the transport protocol used to deliver
1758 messages destined to all receivers of a subscription.";
1759 }
1760 uses subscription-policy-dynamic;
1761 }
1763 grouping notification-origin-info {
1764 description
1765 "Defines the sender source from which notification messages for a
1766 configured subscription are sent.";
1767 choice notification-message-origin {
1768 description
1769 "Identifies the egress interface on the Publisher from which
1770 notification messages are to be sent.";
1771 case interface-originated {
1772 description
1773 "When notification messages to egress a specific, designated
1774 interface on the Publisher.";
1775 leaf source-interface {
1776 type if:interface-ref;
1777 description
1778 "References the interface for notification messages.";
1779 }
1780 }
1781 case address-originated {
1782 description
1783 "When notification messages are to depart from a publisher
1784 using specfic originating address and/or routing context
1785 information.";
1786 leaf source-vrf {
1787 if-feature "supports-vrf";
1788 type leafref {
1789 path "/ni:network-instances/ni:network-instance/ni:name";
1790 }
1791 description
1792 "VRF from which notification messages should egress a
1793 publisher.";
1794 }
1795 leaf source-address {
1796 type inet:ip-address-no-zone;
1797 description
1798 "The source address for the notification messages. If a
1799 source VRF exists, but this object doesn't, a publisher's
1800 default address for that VRF must be used.";
1801 }
1802 }
1803 }
1804 }
1806 grouping receiver-info {
1807 description
1808 "Defines where and how to get notification messages for a
1809 configured subscriptions to one or more targeted recipient. This
1810 includes specifying the destination addressing as well as a
1811 transport protocol acceptable to the receiver.";
1812 container receivers {
1813 description
1814 "Set of receivers in a subscription.";
1815 list receiver {
1816 key "address port";
1817 min-elements 1;
1818 description
1819 "A single host or multipoint address intended as a target
1820 for the notification messages of a subscription.";
1821 leaf address {
1822 type inet:host;
1823 description
1824 "Specifies the address for the traffic to reach a remote
1825 host. One of the following must be specified: an ipv4
1826 address, an ipv6 address, or a host name.";
1827 }
1828 leaf port {
1829 type inet:port-number;
1830 description
1831 "This leaf specifies the port number to use for messages
1832 destined for a receiver.";
1833 }
1834 }
1836 }
1837 }
1839 /*
1840 * RPCs
1841 */
1843 rpc establish-subscription {
1844 description
1845 "This RPC allows a subscriber to create (and possibly negotiate)
1846 a subscription on its own behalf. If successful, the
1847 subscription remains in effect for the duration of the
1848 subscriber's association with the publisher, or until the
1849 subscription is terminated. In case an error occurs, or the
1850 publisher cannot meet the terms of a subscription, and RPC error
1851 is returned, the subscription is not created. In that case, the
1852 RPC reply's error-info MAY include suggested parameter settings
1853 that would have a higher likelihood of succeeding in a subsequent
1854 establish-subscription request.";
1855 input {
1856 uses subscription-policy-dynamic {
1857 refine "encoding" {
1858 mandatory false;
1859 description
1860 "The type of encoding for the subscribed data. If not
1861 included as part of the RPC, the encoding MUST be set by the
1862 publisher to be the encoding used by this RPC.";
1863 }
1864 }
1865 }
1866 }
1868 rc:yang-data establish-subscription-error-stream {
1869 container establish-subscription-error-stream {
1870 description
1871 "If any 'establish-subscription' RPC parameters are
1872 unsupportable against the event stream, a subscription is not
1873 created and the RPC error response MUST indicate the reason
1874 why the subscription failed to be created. This yang-data MAY be
1875 inserted as structured data within a subscription's RPC error
1876 response to indicate the failure reason. This yang-data MUST be
1877 inserted if hints are to be provided back to the subscriber.";
1878 leaf reason {
1879 type identityref {
1880 base establish-subscription-error;
1881 }
1882 description
1883 "Indicates the reason why the subscription has failed to
1884 be created to a targeted stream.";
1885 }
1886 leaf filter-failure-hint {
1887 type string;
1888 description
1889 "Information describing where and/or why a provided filter
1890 was unsupportable for a subscription.";
1891 }
1892 leaf replay-start-time-hint {
1893 type yang:date-and-time;
1894 description
1895 "If a replay has been requested, but the requested replay
1896 time cannot be honored, this may provide a hint at an
1897 alternate time which may be supportable.";
1898 }
1899 }
1900 }
1902 rpc modify-subscription {
1903 description
1904 "This RPC allows a subscriber to modify a subscription that was
1905 previously created using establish-subscription. If successful,
1906 the changed subscription remains in effect for the duration of
1907 the subscriber's association with the publisher, or until the
1908 subscription is again modified or terminated. In case of an
1909 error or an inability to meet the modified parameters, the
1910 subscription is not modified and the original subscription
1911 parameters remain in effect. In that case, the rpc error
1912 MAY include error-info suggested parameter hints that would have
1913 a high likelihood of succeeding in a subsequent
1914 modify-subscription request. A successful modify-subscription
1915 will return a suspended subscription to an active state.";
1916 input {
1917 leaf identifier {
1918 type subscription-id;
1919 description
1920 "Identifier to use for this subscription.";
1921 }
1922 uses subscription-policy-modifiable;
1923 }
1924 }
1926 rc:yang-data modify-subscription-error-stream {
1927 container modify-subscription-error-stream {
1928 description
1929 "This yang-data MAY be provided as part of a subscription's RPC
1930 error response when there is a failure of a
1931 'modify-subscription' RPC which has been made against a
1932 stream. This yang-data MUST be used if hints are to be
1933 provides back to the subscriber.";
1934 leaf reason {
1935 type identityref {
1936 base modify-subscription-error;
1937 }
1938 description
1939 "Information in a modify-subscription RPC error response which
1940 indicates the reason why the subscription to an event stream
1941 has failed to be modified.";
1942 }
1943 leaf filter-failure-hint {
1944 type string;
1945 description
1946 "Information describing where and/or why a provided filter
1947 was unsupportable for a subscription.";
1948 }
1949 }
1950 }
1952 rpc delete-subscription {
1953 description
1954 "This RPC allows a subscriber to delete a subscription that
1955 was previously created from by that same subscriber using the
1956 establish-subscription RPC.";
1957 input {
1958 leaf identifier {
1959 type subscription-id;
1960 mandatory true;
1961 description
1962 "Identifier of the subscription that is to be deleted.
1963 Only subscriptions that were created using
1964 establish-subscription can be deleted via this RPC.";
1965 }
1966 }
1967 }
1969 rpc kill-subscription {
1970 description
1971 "This RPC allows an operator to delete a dynamic subscription
1972 without restrictions on the originating subscriber or underlying
1973 transport session.";
1974 input {
1975 leaf identifier {
1976 type subscription-id;
1977 mandatory true;
1978 description
1979 "Identifier of the subscription that is to be deleted. Only
1980 subscriptions that were created using establish-subscription
1981 can be deleted via this RPC.";
1982 }
1983 }
1984 }
1986 rc:yang-data delete-subscription-error {
1987 container delete-subscription-error {
1988 description
1989 "If a 'delete-subscription' RPC or a 'kill-subscription' RPC
1990 fails, the subscription is not deleted and the RPC error
1991 response MUST indicate the reason for this failure. This
1992 yang-data MAY be inserted as structured data within a
1993 subscription's RPC error response to indicate the failure
1994 reason.";
1995 leaf reason {
1996 type identityref {
1997 base delete-subscription-error;
1998 }
1999 mandatory true;
2000 description
2001 "Indicates the reason why the subscription has failed to be
2002 deleted.";
2003 }
2004 }
2005 }
2007 /*
2008 * NOTIFICATIONS
2009 */
2011 notification replay-completed {
2012 sn:subscription-state-notification;
2013 if-feature "replay";
2014 description
2015 "This notification is sent to indicate that all of the replay
2016 notifications have been sent. It must not be sent for any other
2017 reason.";
2018 leaf identifier {
2019 type subscription-id;
2020 mandatory true;
2021 description
2022 "This references the affected subscription.";
2023 }
2024 }
2025 notification subscription-completed {
2026 sn:subscription-state-notification;
2027 description
2028 "This notification is sent to indicate that a subscription has
2029 finished passing event records.";
2030 leaf identifier {
2031 type subscription-id;
2032 mandatory true;
2033 description
2034 "This references the gracefully completed subscription.";
2035 }
2036 }
2038 notification subscription-started {
2039 sn:subscription-state-notification;
2040 if-feature "configured";
2041 description
2042 "This notification indicates that a subscription has started and
2043 notifications are beginning to be sent. This notification shall
2044 only be sent to receivers of a subscription; it does not
2045 constitute a general-purpose notification.";
2046 leaf identifier {
2047 type subscription-id;
2048 mandatory true;
2049 description
2050 "This references the affected subscription.";
2051 }
2052 uses subscription-policy {
2053 refine "target/stream/replay-start-time" {
2054 description
2055 "Indicates the time that a replay using for the streaming of
2056 buffered event records. This will be populated with the most
2057 recent of the following: replay-log-creation-time,
2058 replay-log-aged-time, replay-start-time, or the most recent
2059 publisher boot time.";
2060 }
2061 refine "target/stream/stream-filter/within-subscription" {
2062 description
2063 "Filter applied to the subscription. If the
2064 'stream-filter-ref' is populated, the filter within the
2065 subscription came from the 'filters' container. Otherwise it
2066 is populated in-line as part of the subscription.";
2067 }
2068 }
2069 }
2071 notification subscription-resumed {
2072 sn:subscription-state-notification;
2073 description
2074 "This notification indicates that a subscription that had
2075 previously been suspended has resumed. Notifications will once
2076 again be sent. In addition, a subscription-resumed indicates
2077 that no modification of parameters has occurred since the last
2078 time event records have been sent.";
2079 leaf identifier {
2080 type subscription-id;
2081 mandatory true;
2082 description
2083 "This references the affected subscription.";
2084 }
2085 }
2087 notification subscription-modified {
2088 sn:subscription-state-notification;
2089 description
2090 "This notification indicates that a subscription has been
2091 modified. Notification messages sent from this point on will
2092 conform to the modified terms of the subscription. For
2093 completeness, this state change notification includes both
2094 modified and non-modified aspects of a subscription.";
2095 leaf identifier {
2096 type subscription-id;
2097 mandatory true;
2098 description
2099 "This references the affected subscription.";
2100 }
2101 uses subscription-policy {
2102 refine "target/stream/stream-filter/within-subscription" {
2103 description
2104 "Filter applied to the subscription. If the
2105 'stream-filter-ref' is populated, the filter within the
2106 subscription came from the 'filters' container. Otherwise it
2107 is populated in-line as part of the subscription.";
2108 }
2109 }
2110 }
2112 notification subscription-terminated {
2113 sn:subscription-state-notification;
2114 description
2115 "This notification indicates that a subscription has been
2116 terminated.";
2117 leaf identifier {
2118 type subscription-id;
2119 mandatory true;
2120 description
2121 "This references the affected subscription.";
2122 }
2123 leaf reason {
2124 type identityref {
2125 base subscription-terminated-reason;
2126 }
2127 mandatory true;
2128 description
2129 "Identifies the condition which resulted in the termination .";
2130 }
2131 }
2133 notification subscription-suspended {
2134 sn:subscription-state-notification;
2135 description
2136 "This notification indicates that a suspension of the
2137 subscription by the publisher has occurred. No further
2138 notifications will be sent until the subscription resumes.
2139 This notification shall only be sent to receivers of a
2140 subscription; it does not constitute a general-purpose
2141 notification.";
2142 leaf identifier {
2143 type subscription-id;
2144 mandatory true;
2145 description
2146 "This references the affected subscription.";
2147 }
2148 leaf reason {
2149 type identityref {
2150 base subscription-suspended-reason;
2151 }
2152 mandatory true;
2153 description
2154 "Identifies the condition which resulted in the suspension.";
2155 }
2156 }
2158 /*
2159 * DATA NODES
2160 */
2162 container streams {
2163 config false;
2164 description
2165 "This container contains information on the built-in streams
2166 provided by the publisher.";
2167 list stream {
2168 key "name";
2169 description
2170 "Identifies the built-in streams that are supported by the
2171 publisher.";
2172 leaf name {
2173 type string;
2174 description
2175 "A handle for a system-provided datastream made up of a
2176 sequential set of event records, each of which is
2177 characterized by its own domain and semantics.";
2178 }
2179 leaf description {
2180 type string;
2181 mandatory true;
2182 description
2183 "A description of the event stream, including such information
2184 as the type of event records that are available within this
2185 stream.";
2186 }
2187 leaf replay-support {
2188 if-feature "replay";
2189 type empty;
2190 description
2191 "Indicates that event record replay is available on this
2192 stream.";
2193 }
2194 leaf replay-log-creation-time {
2195 if-feature "replay";
2196 type yang:date-and-time;
2197 description
2198 "The timestamp of the creation of the log used to support the
2199 replay function on this stream. Note that this might be
2200 earlier then the earliest available information contained in
2201 the log. This object is updated if the log resets for some
2202 reason. This object MUST be present if replay is supported.";
2203 }
2204 leaf replay-log-aged-time {
2205 if-feature "replay";
2206 type yang:date-and-time;
2207 description
2208 "The timestamp of the last event record aged out of the log.
2209 This object MUST be present if replay is supported and any
2210 event record have been aged out of the log.";
2211 }
2212 }
2213 }
2215 container filters {
2216 description
2217 "This container contains a list of configurable filters
2218 that can be applied to subscriptions. This facilitates
2219 the reuse of complex filters once defined.";
2220 list stream-filter {
2221 key "identifier";
2222 description
2223 "A list of pre-positioned filters that can be applied to
2224 subscriptions.";
2225 leaf identifier {
2226 type filter-id;
2227 description
2228 "An identifier to differentiate between filters.";
2229 }
2230 uses stream-filter-elements;
2231 }
2232 }
2234 container subscriptions {
2235 description
2236 "Contains the list of currently active subscriptions, i.e.
2237 subscriptions that are currently in effect, used for subscription
2238 management and monitoring purposes. This includes subscriptions
2239 that have been setup via RPC primitives as well as subscriptions
2240 that have been established via configuration.";
2241 list subscription {
2242 key "identifier";
2243 description
2244 "The identity and specific parameters of a subscription.
2245 Subscriptions within this list can be created using a control
2246 channel or RPC, or be established through configuration.";
2247 leaf identifier {
2248 type subscription-id;
2249 description
2250 "Identifier of a subscription; unique within a publisher";
2251 }
2252 leaf configured-subscription-state {
2253 if-feature "configured";
2254 type enumeration {
2255 enum valid {
2256 value 1;
2257 description
2258 "Connection is active and healthy.";
2259 }
2260 enum invalid {
2261 value 2;
2262 description
2263 "The subscription as a whole is unsupportable with its
2264 current parameters.";
2266 }
2267 enum concluded {
2268 value 3;
2269 description
2270 "A subscription is inactive as it has hit a stop time,
2271 but not yet been removed from configuration.";
2272 }
2273 }
2274 config false;
2275 description
2276 "The presence of this leaf indicates that the subscription
2277 originated from configuration, not through a control channel
2278 or RPC. The value indicates the system established state
2279 of the subscription.";
2280 }
2281 leaf purpose {
2282 if-feature "configured";
2283 type string;
2284 description
2285 "Open text allowing a configuring entity to embed the
2286 originator or other specifics of this subscription.";
2287 }
2288 uses subscription-policy {
2289 refine "target/stream/stream" {
2290 description
2291 "Indicates the stream of event records to be considered for
2292 this subscription. If a stream has been removed, and no
2293 longer can be referenced by an active subscription, send a
2294 'subscription-terminated' notification with
2295 'stream-unavailable' as the reason. If a configured
2296 subscription refers to a non-existent stream, move that
2297 subscription to the 'invalid' state.";
2298 }
2299 }
2300 uses notification-origin-info {
2301 if-feature "configured";
2302 }
2303 uses receiver-info {
2304 augment receivers/receiver {
2305 description
2306 "include operational data for receivers.";
2307 leaf pushed-notifications {
2308 type yang:counter64;
2309 config false;
2310 description
2311 "Operational data which provides the number of update
2312 notification messages pushed to a receiver.";
2313 }
2315 leaf excluded-notifications {
2316 type yang:counter64;
2317 config false;
2318 description
2319 "Operational data which provides the number of event
2320 records from a stream explicitly removed via filtering so
2321 that they are not sent to a receiver.";
2322 }
2323 leaf state {
2324 type enumeration {
2325 enum active {
2326 value 1;
2327 description
2328 "Receiver is currently being sent any applicable
2329 notification messages for the subscription.";
2330 }
2331 enum suspended {
2332 value 2;
2333 description
2334 "Receiver state is suspended, so the publisher
2335 is currently unable to provide notification messages
2336 for the subscription.";
2337 }
2338 enum connecting {
2339 value 3;
2340 if-feature "configured";
2341 description
2342 "A subscription has been configured, but a
2343 subscription-started state change notification needs
2344 to be successfully received before notification
2345 messages are sent.";
2346 }
2347 enum timeout {
2348 value 4;
2349 if-feature "configured";
2350 description
2351 "A subscription has failed in sending a subscription
2352 started state change to the receiver.
2353 Additional attempts at connection attempts are not
2354 currently being made.";
2355 }
2356 }
2357 config false;
2358 mandatory true;
2359 description
2360 "Specifies the state of a subscription from the
2361 perspective of a particular receiver. With this info it
2362 is possible to determine whether a subscriber is currently
2363 generating notification messages intended for that
2364 receiver.";
2365 }
2366 action reset {
2367 description
2368 "Allows the reset of this configured subscription receiver
2369 to the 'connecting' state. This enables the
2370 connection process to be reinitiated.";
2371 output {
2372 leaf time {
2373 type yang:date-and-time;
2374 mandatory true;
2375 description
2376 "Time a publisher returned the receiver to a
2377 connecting state.";
2378 }
2379 }
2380 }
2381 }
2382 }
2383 }
2384 }
2385 }
2386
2388 5. Considerations
2390 5.1. Implementation Considerations
2392 For a deployment including both configured and dynamic subscriptions,
2393 split subscription identifiers into static and dynamic halves. That
2394 way it is unlikely there will be collisions if the configured
2395 subscriptions attempt to set a subscription-id which might have
2396 already been dynamically allocated. The lower half the "identifier"
2397 object in the subscriptions container SHOULD be used when the
2398 "identifier" is selected and assigned by an external entity (such as
2399 with a configured subscription). And the upper half SHOULD be used
2400 for subscription identifiers dynamically chosen and assigned by the
2401 publisher
2403 Neither state change notification nor subscribed event records within
2404 notification messages may be sent before the transport layer,
2405 including any required capabilities exchange, has been established.
2407 An implementation may choose to transition between active and
2408 suspended subscription states more frequently than required by this
2409 specification. However if a subscription is unable to marshal all
2410 intended updates into a transmittable message in multiple successive
2411 intervals, the subscription SHOULD be suspended with the reason
2412 "unsupportable-volume".
2414 For configured subscriptions, operations are against the set of
2415 receivers using the subscription identifier as a handle for that set.
2416 But for streaming updates, state change notifications are local to a
2417 receiver. In this specification it is the case that receivers get no
2418 information from the publisher about the existence of other
2419 receivers. But if an operator wants to let the receivers correlate
2420 results, it is useful to use the subscription identifier handle
2421 across the receivers to allow that correlation.
2423 5.2. IANA Considerations
2425 This document registers the following namespace URI in the "IETF XML
2426 Registry" [RFC3688]:
2428 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications
2429 Registrant Contact: The IESG.
2430 XML: N/A; the requested URI is an XML namespace.
2432 This document registers the following YANG module in the "YANG Module
2433 Names" registry [RFC6020]:
2435 Name: ietf-subscribed-notifications
2436 Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications
2437 Prefix: sn
2438 Reference: draft-ietf-netconf-ietf-subscribed-notifications-08.txt
2439 (RFC form)
2441 5.3. Security Considerations
2443 For dynamic subscriptions the publisher MUST authenticate and
2444 authorize all RPC requests.
2446 Subscriptions could overload a publisher's CPU. For this reason, the
2447 publisher MUST have the ability to decline a dynamic subscription
2448 request, and provide the appropriate RPC error response to a
2449 subscriber should the proposed subscription overly deplete the
2450 publisher's resources.
2452 A publisher needs to be able to suspend an existing dynamic or
2453 configured subscription based on capacity constraints. When this
2454 occurs, the subscription state MUST be updated accordingly and the
2455 receivers notified with subscription state notifications.
2457 If a malicious or buggy subscriber sends an unexpectedly large number
2458 of RPCs, the result might be an excessive use of system resources.
2460 In such a situation, subscription interactions MAY be terminated by
2461 terminating the transport session.
2463 For both configured and dynamic subscriptions the publisher MUST
2464 authenticate and authorize a receiver via some transport level
2465 mechanism before sending any updates.
2467 A secure transport is highly recommended and the publisher MUST
2468 ensure that the receiver has sufficient authorization to perform the
2469 function they are requesting against the specific subset of content
2470 involved.
2472 A publisher MUST NOT include any content in a notification message
2473 for which the receiver has not been authorized.
2475 With configured subscriptions, one or more publishers could be used
2476 to overwhelm a receiver. No notification messages SHOULD be sent to
2477 any receiver which doesn't even support subscriptions. Receivers
2478 that do not want notification messages need only terminate or refuse
2479 any transport sessions from the publisher.
2481 The NETCONF Authorization Control Model [RFC6536bis] SHOULD be used
2482 to control and restrict authorization of subscription configuration.
2483 This control models permits specifying per-receiver permissions to
2484 receive event records from specific streams.
2486 Where NACM is available, the NACM "very-secure" tag MUST be placed on
2487 the "kill-subscription" RPC so that only administrators have access
2488 to use this.
2490 One subscription id can be used for two or more receivers of the same
2491 configured subscription. But due to the possibility of different
2492 access control permissions per receiver, it SHOULD NOT be assumed
2493 that each receiver is getting identical updates.
2495 6. Acknowledgments
2497 For their valuable comments, discussions, and feedback, we wish to
2498 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen,
2499 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan
2500 Hares, Michael Scharf, and Guangying Zheng.
2502 7. References
2503 7.1. Normative References
2505 [I-D.draft-ietf-rtgwg-ni-model]
2506 Berger, L., Hopps, C., and A. Lindem, "YANG Network
2507 Instances", draft-ietf-rtgwg-ni-model-06 (work in
2508 progress), January 2018.
2510 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2511 Requirement Levels", BCP 14, RFC 2119,
2512 DOI 10.17487/RFC2119, March 1997,
2513 .
2515 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2516 DOI 10.17487/RFC3688, January 2004,
2517 .
2519 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2520 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
2521 .
2523 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2524 the Network Configuration Protocol (NETCONF)", RFC 6020,
2525 DOI 10.17487/RFC6020, October 2010,
2526 .
2528 [RFC6536bis]
2529 Bierman, A. and M. Bjorklund, "Network Configuration
2530 Protocol (NETCONF) Access Control Model", draft-ietf-
2531 netconf-rfc6536bis-09 (work in progress), December 2017.
2533 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
2534 Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
2535 DOI 10.17487/RFC7540, May 2015,
2536 .
2538 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2539 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2540 .
2542 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath)
2543 Version 1.0", November 1999,
2544 .
2546 7.2. Informative References
2548 [I-D.draft-ietf-netconf-netconf-event-notifications]
2549 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto.,
2550 Nilsen-Nygaard, E., Tripathy, A., Chisholm, S., and H.
2551 Trevino, "NETCONF support for event notifications",
2552 October 2017, .
2555 [I-D.draft-ietf-netconf-restconf-notif]
2556 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen-
2557 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and
2558 HTTP transport for event notifications", January 2018,
2559 .
2562 [I-D.ietf-netconf-yang-push]
2563 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto.,
2564 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B.
2565 Lengyel, "YANG Datastore Subscription", December 2017,
2566 .
2569 [I.D.draft-ietf-netconf-notification-messages]
2570 Voit, Eric., Clemm, Alexander., Bierman, A., and T.
2571 Jenkins, "YANG Notification Headers and Bundles",
2572 September 2017, .
2575 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2576 and A. Bierman, Ed., "Network Configuration Protocol
2577 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2578 .
2580 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2581 for Subscription to YANG Datastores", RFC 7923,
2582 DOI 10.17487/RFC7923, June 2016,
2583 .
2585 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2586 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2587 .
2589 Appendix A. Changes between revisions
2591 (To be removed by RFC editor prior to publication)
2593 v09 - v10
2595 o Typos and tweaks
2596 v08 - v09
2598 o NMDA model supported. Non NMDA version at https://github.com/
2599 netconf-wg/rfc5277bis/
2601 o Error mechanism revamped to match to embedded implementations.
2603 o Explicitly identified error codes relevant to each RPC/
2604 Notification
2606 v07 - v08
2608 o Split YANG trees to separate document subsections.
2610 o Clarified configured state machine based on Balazs comments, and
2611 moved it into the configured subscription subsections.
2613 o Normative reference to Network Instance model for VRF
2615 o One transport protocol for all receivers of configured
2616 subscriptions.
2618 o QoS section moved in from yang-push
2620 v06 - v07
2622 o Clarification on state machine for configured subscriptions.
2624 v05 - v06
2626 o Made changes proposed by Martin, Kent, and others on the list.
2627 Most significant of these are Stream returned to string (with the
2628 SYSLOG identity removed), intro section on 5277 relationship, an
2629 identity set moved to an enumeration, clean up of definitions/
2630 terminology, state machine proposed for configured subscriptions
2631 with a clean-up of subscription state options.
2633 o JSON and XML become features. Also Xpath and subtree filtering
2634 become features
2636 o Terminology updates with event records, and refinement of filters
2637 to just stream filters.
2639 o Encoding refined in establish-subscription so it takes the RPC's
2640 encoding as the default.
2642 o Namespaces in examples fixed.
2644 v04 - v05
2646 o Returned to the explicit filter subtyping of v00
2648 o stream object changed to 'name' from 'stream'
2650 o Cleaned up examples
2652 o Clarified that JSON support needs notification-messages draft.
2654 v03 - v04
2656 o Moved back to the use of RFC5277 one-way notifications and
2657 encodings.
2659 v03 - v04
2661 o Replay updated
2663 v02 - v03
2665 o RPCs and Notification support is identified by the Notification
2666 2.0 capability.
2668 o Updates to filtering identities and text
2670 o New error type for unsupportable volume of updates
2672 o Text tweaks.
2674 v01 - v02
2676 o Subscription status moved under receiver.
2678 v00 - v01
2680 o Security considerations updated
2682 o Intro rewrite, as well as scattered text changes
2684 o Added Appendix A, to help match this to related drafts in progress
2686 o Updated filtering definitions, and filter types in yang file, and
2687 moved to identities for filter types
2689 o Added Syslog as a stream
2691 o HTTP2 moved in from YANG-Push as a transport option
2692 o Replay made an optional feature for events. Won't apply to
2693 datastores
2695 o Enabled notification timestamp to have different formats.
2697 o Two error codes added.
2699 v01 5277bis - v00 subscribed notifications
2701 o Kill subscription RPC added.
2703 o Renamed from 5277bis to Subscribed Notifications.
2705 o Changed the notification capabilities version from 1.1 to 2.0.
2707 o Extracted create-subscription and other elements of RFC5277.
2709 o Error conditions added, and made specific in return codes.
2711 o Simplified yang model structure for removal of 'basic' grouping.
2713 o Added a grouping for items which cannot be statically configured.
2715 o Operational counters per receiver.
2717 o Subscription-id and filter-id renamed to identifier
2719 o Section for replay added. Replay now cannot be configured.
2721 o Control plane notification renamed to subscription state
2722 notification
2724 o Source address: Source-vrf changed to string, default address
2725 option added
2727 o In yang model: 'info' changed to 'policy'
2729 o Scattered text clarifications
2731 v00 - v01 of 5277bis
2733 o YANG Model changes. New groupings for subscription info to allow
2734 restriction of what is changeable via RPC. Removed notifications
2735 for adding and removing receivers of configured subscriptions.
2737 o Expanded/renamed definitions from event server to publisher, and
2738 client to subscriber as applicable. Updated the definitions to
2739 include and expand on RFC 5277.
2741 o Removal of redundancy with other drafts
2743 o Many other clean-ups of wording and terminology
2745 Authors' Addresses
2747 Eric Voit
2748 Cisco Systems
2750 Email: evoit@cisco.com
2752 Alexander Clemm
2753 Huawei
2755 Email: ludwig@clemm.org
2757 Alberto Gonzalez Prieto
2758 VMWare
2760 Email: agonzalezpri@vmware.com
2762 Einar Nilsen-Nygaard
2763 Cisco Systems
2765 Email: einarnn@cisco.com
2767 Ambika Prasad Tripathy
2768 Cisco Systems
2770 Email: ambtripa@cisco.com