idnits 2.17.1
draft-ietf-netconf-subscribed-notifications-07.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 :
----------------------------------------------------------------------------
** The document seems to lack an IANA Considerations section. (See Section
2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
when there are no actions for IANA.)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 438 has weird spacing: '...ter-ref str...'
== Line 452 has weird spacing: '...rotocol tra...'
== Line 502 has weird spacing: '...ter-ref str...'
== Line 527 has weird spacing: '...ter-ref str...'
== Line 536 has weird spacing: '...-result sub...'
== (10 more instances...)
-- The document date (October 30, 2017) is 2341 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 (-09) exists of
draft-ietf-netconf-rfc6536bis-01
-- Possible downref: Normative reference to a draft: ref. 'RFC6536bis'
-- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH'
Summary: 1 error (**), 0 flaws (~~), 8 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: May 3, 2018 Huawei
6 A. Gonzalez Prieto
7 VMWare
8 E. Nilsen-Nygaard
9 A. Tripathy
10 Cisco Systems
11 October 30, 2017
13 Custom Subscription to Event Streams
14 draft-ietf-netconf-subscribed-notifications-07
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 May 3, 2018.
42 Copyright Notice
44 Copyright (c) 2017 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 . . . . . . . . . . . . . . . . . . . . . . . . 3
60 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3
61 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
62 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 5
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. Subscription State Model at the Publisher . . . . . . . . 7
68 3. Data Model Trees . . . . . . . . . . . . . . . . . . . . . . 9
69 4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . . . 14
70 4.1. Establishing a Subscription . . . . . . . . . . . . . . . 14
71 4.2. Modifying a Subscription . . . . . . . . . . . . . . . . 16
72 4.3. Deleting a Subscription . . . . . . . . . . . . . . . . . 16
73 4.4. Killing a Subscription . . . . . . . . . . . . . . . . . 16
74 5. Configured Subscriptions . . . . . . . . . . . . . . . . . . 17
75 5.1. Creating a Configured Subscription . . . . . . . . . . . 17
76 5.2. Modifying a Configured Subscription . . . . . . . . . . . 18
77 5.3. Deleting a Configured Subscription . . . . . . . . . . . 18
78 6. Deleting a Configured Subscription . . . . . . . . . . . . . 19
79 7. Asynchronous Subscribed Event Delivery . . . . . . . . . . . 19
80 8. Subscription State Notifications . . . . . . . . . . . . . . 20
81 8.1. subscription-started . . . . . . . . . . . . . . . . . . 20
82 8.2. subscription-modified . . . . . . . . . . . . . . . . . . 21
83 8.3. subscription-terminated . . . . . . . . . . . . . . . . . 21
84 8.4. subscription-suspended . . . . . . . . . . . . . . . . . 21
85 8.5. subscription-resumed . . . . . . . . . . . . . . . . . . 21
86 8.6. subscription-completed . . . . . . . . . . . . . . . . . 22
87 8.7. replay-completed . . . . . . . . . . . . . . . . . . . . 22
88 9. Administrative Functions . . . . . . . . . . . . . . . . . . 22
89 9.1. Subscription Monitoring . . . . . . . . . . . . . . . . . 22
90 9.2. Advertisement . . . . . . . . . . . . . . . . . . . . . . 23
91 9.3. Event Stream Discovery . . . . . . . . . . . . . . . . . 23
92 10. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 23
93 11. Considerations . . . . . . . . . . . . . . . . . . . . . . . 46
94 11.1. Implementation Considerations . . . . . . . . . . . . . 46
95 11.2. Security Considerations . . . . . . . . . . . . . . . . 46
96 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47
97 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 48
98 13.1. Normative References . . . . . . . . . . . . . . . . . . 48
99 13.2. Informative References . . . . . . . . . . . . . . . . . 48
100 Appendix A. Changes between revisions . . . . . . . . . . . . . 49
101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52
103 1. Introduction
105 This document defines capabilities and operations for the customized
106 establishment of subscriptions upon system generated event streams.
107 Effectively this enables a "Subscribe then Publish" capability where
108 the customized information needs of each target receiver are
109 understood by the publisher before subscribed event records are
110 marshalled and pushed. The receiver then gets a continuous, custom
111 feed of publisher generated information.
113 While the functionality defined in this document is transport-
114 agnostic, protocols like NETCONF [RFC6241] or RESTCONF [RFC8040] can
115 be used to configure or dynamically signal subscriptions, and there
116 are bindings defined for subscribed event record delivery for NETCONF
117 within [I-D.draft-ietf-netconf-netconf-event-notifications], and for
118 HTTP2 or HTTP1.1 within [I-D.draft-ietf-netconf-restconf-notif].
120 1.1. Motivation
122 There are various [RFC5277] limitations, many of which have been
123 exposed in [RFC7923] which needed to be solved. Key capabilities
124 supported by this document include:
126 o multiple subscriptions on a single transport session
128 o support for dynamic and statically configured subscriptions
130 o modification of an existing subscription
132 o operational counters and instrumentation
134 o negotiation of subscription parameters (through the use of hints
135 returned as part of declined subscription requests)
137 o state change notifications (e.g., publisher driven suspension,
138 parameter modification)
140 o independence from transport protocol
142 1.2. Terminology
144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
146 document are to be interpreted as described in RFC 2119 [RFC2119].
148 Configured subscription: A subscription installed via a configuration
149 interface which persists across reboots.
151 Dynamic subscription: A subscription agreed between subscriber and
152 publisher created via RPC subscription state signaling messages.
154 Event: An occurrence of something that may be of interest. (e.g., a
155 configuration change, a fault, a change in status, crossing a
156 threshold, or an external input to the system.)
158 Event record: A set of information detailing an event.
160 NACM: NETCONF Access Control Model.
162 Notification message: A set of transport encapsulated information
163 intended for a receiver indicating that one or more event(s) have
164 occurred. A notification message may include event records.
166 Publisher: An entity responsible for streaming notification messages
167 per the terms of a Subscription.
169 Receiver: A target to which a publisher pushes subscribed event
170 records. For dynamic subscriptions, the receiver and subscriber are
171 the same entity.
173 Stream (also referred to as "event stream"): A continuous ordered set
174 of events aggregated under some context.
176 Stream filter: Evaluation criteria which may be applied against a
177 event records within a stream. Event records pass the filter when
178 specified criteria are met.
180 Subscribed event records: Event records which have met the terms of
181 the subscription. This include terms (such as security checks)
182 enforced by the publisher.
184 Subscriber: An entity able to request and negotiate a contract for
185 the generation and push of event records from a publisher.
187 Subscription: A contract with a publisher, stipulating which
188 information one or more receivers wish to have pushed from the
189 publisher without the need for further solicitation.
191 1.3. Solution Overview
193 This document describes a transport agnostic mechanism for
194 subscribing to and receiving content from a stream instantiated
195 within a publisher. This mechanism is through the use of a
196 subscription.
198 Two types of subscriptions are supported:
200 1. Dynamic subscriptions, where a subscriber initiates a
201 subscription negotiation with a publisher via RPC. If the
202 publisher wants to serve this request, it accepts it, and then
203 starts pushing notification messages. If the publisher does not
204 wish to serve it as requested, then an error response is
205 returned. This response MAY include hints at subscription
206 parameters which would have been accepted.
208 2. Configured subscriptions, which allow the management of
209 subscriptions via a configuration interface so that a publisher
210 can send notification messages to configured receiver(s).
211 Support for this capability is optional.
213 Additional characteristics differentiating configured from dynamic
214 subscriptions include:
216 o The lifetime of a dynamic subscription is bounded by the transport
217 session used to establish it. For connection-oriented stateful
218 transport like NETCONF, the loss of the transport session will
219 result in the immediate termination of associated dynamic
220 subscriptions. For connectionless or stateless transports like
221 HTTP, it is the lack of receipt acknowledgement of a sequential
222 set of notification messages and/or keep-alives which will
223 terminate dynamic subscriptions. The lifetime of a configured
224 subscription is driven by relevant configuration being present on
225 the running configuration. This implies configured subscriptions
226 persist across reboots, and persist even when transport is
227 unavailable.
229 o Configured subscriptions can be modified by any configuration
230 client with write permission on the configuration of the
231 subscription. Dynamic subscriptions can only be modified via an
232 RPC request made upon the original subscribing transport session.
234 Note that there is no mixing-and-matching of dynamic and configured
235 subscriptions. Specifically, a configured subscription cannot be
236 modified or deleted using RPC. Similarly, a subscription established
237 via RPC cannot be modified through configuration operations (if
238 needed, an operator may use a kill RPC however).
240 The publisher MAY decide to terminate a dynamic subscription at any
241 time. Similarly, it MAY decide to temporarily suspend the sending of
242 notification messages for either configured or dynamic subscriptions.
243 Such termination or suspension MAY be driven by the publisher running
244 out of resources to serve the subscription, or by internal errors on
245 the publisher.
247 1.4. Relationship to RFC-5277
249 This document is intended to provide a superset of the subscription
250 capabilities initially defined within [RFC5277]. Especially when
251 extending an existing [RFC5277] implementation, it is important to
252 understand what has been reused and what has been replaced. Key
253 realtionships between these two documents include:
255 o the data model in this document replaces the data model in
256 [RFC5277].
258 o the RPC operations in this draft replaces the symetrical
259 operations of [RFC5277], section 4.
261 o the one way operation of [RFC5277] is still used. However this
262 operation will no longer be required with the availability of
263 [I.D.draft-ietf-netconf-notification-messages].
265 o the definition and contents of the NETCONF stream are identical
266 between this document and [RFC5277].
268 o a publisher MAY implement both the data model and RPCs defined in
269 [RFC5277] and this new document concurrently, in order to support
270 old clients. However the use of both alternatives on a single
271 transport session is prohibited.
273 2. Solution
275 2.1. Event Streams
277 An event stream is a named entity on a publisher which exposes a
278 continuously updating set of events. Each event stream is available
279 for subscription. It is out of the scope of this document to
280 identify a) how streams are defined, b) how events are defined/
281 generated, and c) how events are assigned to streams.
283 There is only one reserved event stream within this document:
284 NETCONF. The NETCONF event stream contains all NETCONF XML event
285 record information supported by the publisher, except for where it
286 has been explicitly indicated that this the event record MUST be
287 excluded from the NETCONF stream. Beyond NETCONF, implementations
288 are free to add additional event streams.
290 As events are raised by a system, they may be assigned to one or more
291 streams. The event record is distributed to receivers where: (1) a
292 subscription includes the identified stream, and (2) subscription
293 filtering does not exclude the event record from that receiver.
295 If access control permissions are in use to secure publisher content,
296 then for notification messages to be sent to a receiver, that
297 receiver MUST be allowed access to all the event records on the
298 stream. If subscriber permissions change during the lifecycle of a
299 subscription, then the subscription MUST be continued or terminated
300 accordingly.
302 2.2. Event Stream Filters
304 This document defines an extensible filtering mechanism. Two
305 optional stream filtering syntaxes supported are [XPATH] and subtree
306 [RFC6241]. The subsets of these filtering syntaxes supported are
307 left to each implementation. A subset of information is never
308 stripped from within the event record.
310 If no stream filter is provided, all event records on a stream are to
311 be sent.
313 2.3. Subscription State Model at the Publisher
315 Below is the state machine of a subscription for the publisher for a
316 dynamic subscription. It is important to note that such a
317 subscription doesn't exist at the publisher until it is accepted and
318 made active. The mere request by a subscriber to establish a
319 subscription is insufficient for that asserted subscription to be
320 externally visible via this state machine.
322 .-------.
323 | start |
324 '-------'
325 |
326 establish
327 |
328 | .----------modify------------.
329 v v '
330 .-----------. .-----------.
331 .--------. | |-----suspend------->| |
332 modify '| active | | suspended |
333 '--------->| |<----resume---------| |
334 '-----------' '-----------'
335 | |
336 delete/kill delete/kill
337 | |
338 v |
339 .-------. |
340 | end |<---------------------------'
341 '-------'
343 Figure 1: Dynamic subscription states
345 Of interest in this state machine are the following:
347 o Successful establish or modify RPCs put the subscription into an
348 active state.
350 o Failed modify RPCs will leave the subscription in its previous
351 state, with no visible change to any streaming updates.
353 o A delete or kill RPC will end the subscription.
355 o Suspend and resume state changes are driven by internal process
356 and prioritization. There are no external controls over suspend
357 and resume.
359 As shown below, a very similar state machine exists for configured
360 subscriptions. Creation, modification, and deletion is via
361 configuration operations rather than via RPC. When a subscription is
362 first created, the operational status of each receiver is initially
363 set to connecting. Individual are receivers are moved to an active
364 status when a subscription-started state change notification is
365 successfully delivered. Configured subscriptions remain active if
366 transport connectivity is not lost and event records are not being
367 dropped due to buffer overflow. A configured subscription MUST be
368 moved connecting if transport connectivity is lost.
370 A configured subscription MUST be moved to a suspended status if
371 notification messages are being dropped despite the presence of
372 transport connectivity. A configured subscription MUST be returned
373 to an active status from the suspended status as soon as transport
374 connectivity is re-established, and a receiver acknowledges receipt
375 of a "subscription-resumed". Otherwise, it MUST be moved to
376 connecting.
378 .-------.
379 | start |
380 '-------'
381 |
382 create
383 |
384 v
385 .---------------------------------------------------.
386 .--------. | Subscription |
387 modify '| .---------------------. |
388 '--------->| .--| connecting receiver |--. |
389 | | '---------------------' | |
390 | V ^ ^ V |
391 | .---------------. -suspend-> .------------------. |
392 | |active receiver| |suspended receiver| |
393 | '---------------' <--resume- '------------------' |
394 '---------------------------------------------------'
395 |
396 delete
397 |
398 v
399 .-------.
400 | end |
401 '-------'
403 Figure 2: Configured subscription and receiver states
405 The interaction model described within this section is mirrored in
406 the RPCs and Notifications later in the document. It should be noted
407 that these RPCs and Notifications have been designed to be extensible
408 and allow subscriptions into targets other than event streams.
409 [I-D.ietf-netconf-yang-push] provides an example of such an
410 extension.
412 3. Data Model Trees
414 module: ietf-subscribed-notifications
415 +--ro streams
416 | +--ro stream* [name]
417 | +--ro name stream
418 | +--ro description string
419 | +--ro replay-support? empty {replay}?
420 | +--ro replay-log-creation-time? yang:date-and-time {replay}?
421 | +--ro replay-log-aged-time? yang:date-and-time {replay}?
422 +--rw filters
423 | +--rw stream-filter* [identifier]
424 | +--rw identifier filter-id
425 | +--rw (filter-spec)?
426 | +--:(subtree-filter)
427 | | +--rw subtree-filter? {subtree}?
428 | +--:(xpath-filter)
429 | +--rw xpath-filter? yang:xpath1.0 {xpath}?
430 +--rw subscription-config {configured}?
431 | +--rw subscription* [identifier]
432 | +--rw identifier subscription-id
433 | +--rw encoding encoding
434 | +--rw (target)
435 | | +--:(stream)
436 | | +--rw (stream-filter)?
437 | | | +--:(by-reference)
438 | | | | +--rw stream-filter-ref stream-filter-ref
439 | | | +--:(within-subscription)
440 | | | +--rw (filter-spec)?
441 | | | +--:(subtree-filter)
442 | | | | +--rw subtree-filter? {subtree}?
443 | | | +--:(xpath-filter)
444 | | | +--rw xpath-filter? yang:xpath1.0 {xpath}?
445 | | +--rw stream stream
446 | | +--rw replay-start-time? yang:date-and-time {replay}?
447 | +--rw stop-time? yang:date-and-time
448 | +--rw receivers
449 | | +--rw receiver* [address port]
450 | | +--rw address inet:host
451 | | +--rw port inet:port-number
452 | | +--rw protocol transport
453 | | +--rw status? enumeration
454 | +--rw (notification-message-origin)?
455 | +--:(interface-originated)
456 | | +--rw source-interface? if:interface-ref
457 | +--:(address-originated)
458 | +--rw source-vrf? string
459 | +--rw source-address? inet:ip-address-no-zone
460 +--ro subscriptions
461 +--ro subscription* [identifier]
462 +--ro identifier subscription-id
463 +--ro configured-subscription? empty {configured}?
464 +--ro encoding encoding
465 +--ro (target)
466 | +--:(stream)
467 | +--ro (stream-filter)?
468 | | +--:(by-reference)
469 | | | +--ro stream-filter-ref stream-filter-ref
470 | | +--:(within-subscription)
471 | | +--ro (filter-spec)?
472 | | +--:(subtree-filter)
473 | | | +--ro subtree-filter? {subtree}?
474 | | +--:(xpath-filter)
475 | | +--ro xpath-filter? yang:xpath1.0 {xpath}?
476 | +--ro stream stream
477 | +--ro replay-start-time? yang:date-and-time {replay}?
478 +--ro stop-time? yang:date-and-time
479 +--ro (notification-message-origin)?
480 | +--:(interface-originated)
481 | | +--ro source-interface? if:interface-ref
482 | +--:(address-originated)
483 | +--ro source-vrf? string
484 | +--ro source-address? inet:ip-address-no-zone
485 +--ro receivers
486 +--ro receiver* [address port]
487 +--ro address inet:host
488 +--ro port inet:port-number
489 +--ro protocol transport
490 +--ro pushed-notifications? yang:counter64
491 +--ro excluded-notifications? yang:counter64
492 +--ro status enumeration
494 rpcs:
495 +---x establish-subscription
496 | +---w input
497 | | +---w encoding? encoding
498 | | +---w (target)
499 | | | +--:(stream)
500 | | | +---w (stream-filter)?
501 | | | | +--:(by-reference)
502 | | | | | +---w stream-filter-ref stream-filter-ref
503 | | | | +--:(within-subscription)
504 | | | | +---w (filter-spec)?
505 | | | | +--:(subtree-filter)
506 | | | | | +---w subtree-filter? {subtree}?
507 | | | | +--:(xpath-filter)
508 | | | | +---w xpath-filter? yang:xpath1.0 {xpath}?
509 | | | +---w stream stream
510 | | | +---w replay-start-time? yang:date-and-time {replay}?
511 | | +---w stop-time? yang:date-and-time
512 | +--ro output
513 | +--ro subscription-result subscription-result
514 | +--ro (result)?
515 | +--:(no-success)
516 | | +--ro filter-failure? string
517 | | +--ro replay-start-time-hint? yang:date-and-time
518 | +--:(success)
519 | +--ro identifier subscription-id
520 +---x modify-subscription
521 | +---w input
522 | | +---w identifier? subscription-id
523 | | +---w (target)
524 | | | +--:(stream)
525 | | | +---w (stream-filter)?
526 | | | +--:(by-reference)
527 | | | | +---w stream-filter-ref stream-filter-ref
528 | | | +--:(within-subscription)
529 | | | +---w (filter-spec)?
530 | | | +--:(subtree-filter)
531 | | | | +---w subtree-filter? {subtree}?
532 | | | +--:(xpath-filter)
533 | | | +---w xpath-filter? yang:xpath1.0 {xpath}?
534 | | +---w stop-time? yang:date-and-time
535 | +--ro output
536 | +--ro subscription-result subscription-result
537 | +--ro (result)?
538 | +--:(no-success)
539 | +--ro filter-failure? string
540 +---x delete-subscription
541 | +---w input
542 | | +---w identifier subscription-id
543 | +--ro output
544 | +--ro subscription-result subscription-result
545 +---x kill-subscription
546 +---w input
547 | +---w identifier subscription-id
548 +--ro output
549 +--ro subscription-result subscription-result
551 notifications:
552 +---n replay-completed {replay}?
553 | +--ro identifier subscription-id
554 +---n subscription-completed
555 | +--ro identifier subscription-id
556 +---n subscription-started {configured}?
557 | +--ro identifier subscription-id
558 | +--ro encoding encoding
559 | +--ro (target)
560 | | +--:(stream)
561 | | +--ro (stream-filter)?
562 | | | +--:(by-reference)
563 | | | | +--ro stream-filter-ref stream-filter-ref
564 | | | +--:(within-subscription)
565 | | | +--ro (filter-spec)?
566 | | | +--:(subtree-filter)
567 | | | | +--ro subtree-filter? {subtree}?
568 | | | +--:(xpath-filter)
569 | | | +--ro xpath-filter? yang:xpath1.0 {xpath}?
570 | | +--ro stream stream
571 | | +--ro replay-start-time? yang:date-and-time {replay}?
572 | +--ro stop-time? yang:date-and-time
573 +---n subscription-resumed
574 | +--ro identifier subscription-id
575 +---n subscription-modified {configured}?
576 | +--ro identifier subscription-id
577 | +--ro encoding encoding
578 | +--ro (target)
579 | | +--:(stream)
580 | | +--ro (stream-filter)?
581 | | | +--:(by-reference)
582 | | | | +--ro stream-filter-ref stream-filter-ref
583 | | | +--:(within-subscription)
584 | | | +--ro (filter-spec)?
585 | | | +--:(subtree-filter)
586 | | | | +--ro subtree-filter? {subtree}?
587 | | | +--:(xpath-filter)
588 | | | +--ro xpath-filter? yang:xpath1.0 {xpath}?
589 | | +--ro stream stream
590 | | +--ro replay-start-time? yang:date-and-time {replay}?
591 | +--ro stop-time? yang:date-and-time
592 +---n subscription-terminated
593 | +--ro identifier subscription-id
594 | +--ro error-id subscription-errors
595 | +--ro filter-failure? string
596 +---n subscription-suspended
597 +--ro identifier subscription-id
598 +--ro error-id subscription-errors
599 +--ro filter-failure? string
601 The top-level decompositions of data model are as follows:
603 o "Streams" contains a list of event streams that are supported by
604 the publisher and against which subscription is allowed.
606 o "Filters" contains a configurable list of filters that can be
607 applied to a subscription. This allows users to reference an
608 existing filter definition as an alternative to defining a filter
609 inline for each subscription.
611 o "Subscription-config" contains the configuration of configured
612 subscriptions. The parameters of each configured subscription are
613 a superset of the parameters of a dynamic subscription and use the
614 same groupings. In addition, the configured subscriptions MUST
615 also specify intended receivers and MAY specify the push source
616 from which to send the stream of notification messages.
618 o "Subscriptions" contains a list of all subscriptions on a
619 publisher, both configured and dynamic. It can be used to
620 retrieve information about the subscriptions which a publisher is
621 serving.
623 The data model also contains a number of YANG Notifications that
624 allow a publisher to signal information about a subscription.
625 Finally, the data model contains a number of RPC definitions that are
626 used to manage dynamic subscriptions.
628 4. Dynamic Subscriptions
630 Dynamic subscriptions are managed via RPC, and are made against
631 targets located within the publisher. These RPCs have been designed
632 extensibly so that they may be augmented for targets beyond event
633 streams.
635 4.1. Establishing a Subscription
637 The "establish-subscription" operation allows a subscriber to request
638 the creation of a subscription via RPC. Multiple establish
639 subscription RPC requests can be made within the same transport
640 session.
642 The input parameters of the operation are:
644 o A stream name which identifies the continuous feed of events
645 against which the subscription is applied.
647 o A filter which may reduce the set of event records pushed.
649 o The desired encoding for the notification message.
651 o An optional stop time for the subscription.
653 o An optional start time which indicates that this subscription is
654 requesting a replay of previously generated information from the
655 event stream.
657 If the publisher cannot satisfy the "establish-subscription" request,
658 it sends a negative "subscription-result" element. If the subscriber
659 has no authorization to establish the subscription, the
660 "subscription-result" indicates an authorization error. Optionally,
661 the "subscription-result" MAY include one or more hints on
662 alternative input parameters and value which would have resulted in
663 an accepted subscription.
665 Subscription requests MUST fail if a filter with invalid syntax is
666 provided or if a non-existent stream is referenced.
668 4.1.1. Replay Subscription
670 Replay provides the ability to establish an subscription which is
671 also capable of passing along recently generated event records. In
672 other words, as the subscription initializes itself, it sends any
673 previously generated content from within target event stream which
674 meet the filter and timeframe criteria. These historical event
675 records would then be followed by event records generated after the
676 subscription has been established. All event records will be
677 delivered in the order generated. Replay is only viable for dynamic
678 subscriptions. Replay is an optional feature. Replay is dependent
679 on an event stream supporting some form of logging, although it puts
680 no restrictions on the size or form of the log, or where it resides
681 within the device.
683 The inclusion of a replay-start-time within an "establish-
684 subscription" RPC indicates a replay request. If the "replay-start-
685 time" contains a value that is earlier than content stored within the
686 publisher's replay buffer, then the subscription MUST be rejected,
687 and the leaf "replay-start-time-hint" MUST be set in the reply.
689 An end time MAY be specified using the optional stop-time parameter,
690 which only in the case of replay MAY also be earlier than the current
691 time. If no stop-time is present, notification messages will
692 continue to be sent until the subscription is terminated. The
693 publisher MUST NOT accept a replay-start-time for a future time.
695 If the replay-start-time is later than any information stored in the
696 replay buffer, then the publisher MUST send a "replay-completed"
697 notification immediately after the "subscription-started"
698 notification.
700 Not all streams will support replay. Those that do MUST include they
701 do via the "replay-support" object. In addition, a event stream that
702 does support replay is not expected to have an unlimited supply of
703 saved notifications available to accommodate any given replay
704 request. Subscribers MAY do a get on "replay-log-creation-time" and
705 "replay-log-aged-time" to assess the availability of replay. The
706 actual size of the replay log at any given time is a publisher
707 specific matter. Control parameters for this aspect of the feature
708 are outside the scope of this document.
710 4.2. Modifying a Subscription
712 The "modify-subscription" operation permits changing the terms of an
713 existing dynamic subscription previously established on that
714 transport session. Subscriptions created by configuration operations
715 cannot be modified via this RPC. Dynamic subscriptions can be
716 modified one or multiple times. If the publisher accepts the
717 requested modifications, it replies that this change has been made,
718 then immediately starts sending event records based on the new terms.
719 If the publisher rejects the request, the subscription remains as
720 prior to the request. That is, the request has no impact whatsoever.
721 The contents of a such a rejected modification MAY include one or
722 more hints on alternative input parameters and value which would have
723 resulted in a successfully modified subscription.
725 Dynamic subscriptions established via RPC can only be modified via
726 RPC using the same transport session used to establish that
727 subscription.
729 4.3. Deleting a Subscription
731 The "delete-subscription" operation permits canceling an existing
732 subscription previously established on that transport session. If
733 the publisher accepts the request, and the publisher has indicated
734 this successful reply has been sent, the publisher MUST NOT send any
735 more notification messages for this subscription. If the publisher
736 rejects the request, all subscriptions remain as prior to the
737 request. That is, the request has no impact whatsoever.
739 Subscriptions established via RPC can only be deleted via RPC using
740 the same transport session used for subscription establishment.
741 Configured subscriptions cannot be deleted using RPCs.
743 4.4. Killing a Subscription
745 The "kill-subscription" operation permits an operator to end a
746 dynamic subscription which is not associated the transport session
747 used for the RPC. This operation MUST be secured so that only
748 connections with sufficiently privileged access rights are able to
749 invoke this RPC. A publisher MUST terminate any dynamic subscription
750 identified by RPC request. An operator may find subscription
751 identifiers which may be used with "kill-subscription" by searching
752 for the ip address of a receiver within the yang tree.
754 Configured subscriptions cannot be killed using this RPC. Instead,
755 configured subscriptions are deleted as part of regular configuration
756 operations. Publishers MUST reject any RPC attempt to kill a
757 configured subscription.
759 5. Configured Subscriptions
761 A configured subscription is a subscription installed via a
762 configuration interface. Such a subscription MAY push notification
763 messages to more than one receiver. The publisher does not provide
764 information about receivers are provided no information about other
765 receivers. Supporting configured subscriptions is optional and
766 advertised using the "configured" feature.
768 Configured subscriptions persist across reboots, and persist even
769 when transport is unavailable.
771 Configured subscriptions can be modified by any configuration client
772 with write permissions for the configuration of the subscription.
773 Subscriptions can be modified or terminated via the configuration
774 interface at any point of their lifetime.
776 In addition to subscription parameters that apply to dynamic
777 subscriptions, the following additional parameters apply to
778 configured subscriptions:
780 o One or more receiver IP addresses (and corresponding ports)
781 intended as the destination for notification messages for each
782 subscription. In addition, the transport for each destination MAY
783 be defined.
785 o Optional parameters to identify an egress interface, a host IP
786 address, a VRF, or an IP address plus VRF out of which
787 notification messages should be pushed from the publisher. Where
788 any of this info is not explicitly included, or where just the VRF
789 is provided, notification messages MUST egress the publisher's
790 default interface towards that receiver.
792 5.1. Creating a Configured Subscription
794 Configured subscriptions are established using configuration
795 operations against the top-level subtree subscription-config. There
796 are two key differences between RPCs and configuration operations for
797 subscription creation. Firstly, configuration operations install a
798 subscription without question, while RPCs are designed to the support
799 negotiation and rejection of requests. Secondly, while RPCs mandate
800 that the subscriber establishing the subscription is the only
801 receiver of the notification messages, configuration operations
802 permit specifying receivers independent of any tracked subscriber.
803 Because there is no explicit association with an existing transport
804 session, configuration operations require additional parameters
805 beyond those of dynamic subscriptions to indicate receivers, and
806 possibly whether the notification messages need to come from a
807 specific egress interface on the publisher.
809 After a subscription is successfully created, the publisher
810 immediately sends a subscription-started state change notification to
811 each receiver. It is quite possible that upon configuration, reboot,
812 or even steady-state operations, a transport session may not be
813 currently available to the receiver. In this case, when there is
814 something to transport for an active subscription, transport specific
815 call-home operations will be used to establish the connection. When
816 transport connectivity is available, as successful receipt of the
817 subscription start change notification by a particular receiver
818 indicated, notification messages may then be pushed.
820 To see an example at subscription creation using configuration
821 operations over NETCONF, see Appendix A of
822 [I-D.draft-ietf-netconf-netconf-event-notifications].
824 Note that is possible to configure replay on a configured
825 subscription. This is to allows a configured subscription to exist
826 on a system so that event records generated during boot can be
827 buffered and pushed as soon as the transport session is established.
829 5.2. Modifying a Configured Subscription
831 Configured subscriptions can be modified using configuration
832 operations against the top-level subtree subscription-config.
834 Immediately after a subscription is successfully modified, the
835 publisher sends to the existing receivers a state change notification
836 stating the subscription has been modified (i.e., subscription-
837 modified).
839 If the modification involved adding and/or removing receivers, those
840 modified receivers are sent state change notifications, indicating
841 they have been added (i.e, subscription-started to a specific
842 receiver) or removed (i.e., subscription-terminated to a specific
843 receiver.)
845 5.3. Deleting a Configured Subscription
847 Subscriptions can be deleted using configuration operations against
848 the top-level subtree subscription-config. For example, in RESTCONF:
850 DELETE /subscription-config/subscription=1922 HTTP/1.1
851 Host: example.com
853 HTTP/1.1 204 No Content
854 Date: Sun, 24 Jul 2016 11:23:40 GMT
855 Server: example-server
857 Figure 3: Deleting a configured subscription
859 Immediately after a subscription is successfully deleted, the
860 publisher sends to all receivers of that subscription a state change
861 notification stating the subscription has been terminated (i.e.,
862 subscription-terminated).
864 6. Deleting a Configured Subscription
866 Configured subscriptions can be deleted using configuration
867 operations against the top-level subtree subscription-config.
869 Immediately after a subscription is successfully deleted, the
870 publisher sends to the existing receivers a state change notification
871 stating the subscription has been terminated (i.e., subscription-
872 terminated).
874 7. Asynchronous Subscribed Event Delivery
876 Once a subscription has been set up, the publisher streams subscribed
877 event records via notification messages per the terms of the
878 subscription. For dynamic subscriptions set up via RPC operations,
879 notification messages are sent over the session used to establish the
880 subscription. For configured subscriptions, notification messages
881 are sent over the specified connections.
883 A notification message is sent to a receiver when something of
884 interest occurs which is able to traverse all specified filtering and
885 access control criteria.
887 This notification message MUST be encoded as one-way notification
888 element of [RFC5277], Section 4. The following example within
889 [RFC7950] section 7.16.3 is an example of a compliant message:
891
893 2007-09-01T10:00:00Z
894
895 so-1/2/3.0
896 up
897 down
898
899
901 Figure 4: subscribed notification message
903 This [RFC5277] section 4 one-way operation has the drawback of not
904 including useful header information such as a subscription
905 identifier. When using this mechanism, it is left up to
906 implementations or augmentations to this document to determine which
907 event records belong to which subscription.
909 These drawbacks, along with other useful common headers and the
910 ability to bundle multiple event records together is being explored
911 within [I.D.draft-ietf-netconf-notification-messages]. When the
912 notification-messages is supported, this document will be updated to
913 indicate support.
915 8. Subscription State Notifications
917 In addition to subscribed event records, a publisher will send
918 subscription state notifications to indicate to receivers that an
919 event related to the subscription management has occurred.
921 Subscription state notifications are unlike other notifications which
922 might be found in the event stream. They cannot be filtered out, and
923 they are delivered only to directly impacted receiver(s) of a
924 subscription. The definition of subscription state notifications is
925 distinct from other notification messages by making use of a YANG
926 extension tagging them as subscription state notification.
928 Subscription state notifications include indications that a replay of
929 event records has been completed, that a subscription is done because
930 an end time has been reached, and that a subscription has started,
931 been modified, been terminated, or been suspended. They are
932 described in the following subsections.
934 8.1. subscription-started
936 This indicates that a configured subscription has started and data
937 updates are beginning to be sent. This state change notification
938 includes the parameters of the subscription, except for the
939 receiver(s) addressing information and origin information indicating
940 where notification messages will egress the publisher. Note that for
941 RPC-based subscriptions, no "subscription-started" notifications are
942 sent.
944 8.2. subscription-modified
946 This indicates that a configured subscription has been modified
947 successfully. This state change notification includes the parameters
948 of the subscription, except for the receiver(s) addressing
949 information and origin information indicating where notification
950 messages will egress the publisher. Note that for RPC-based
951 subscriptions, no "subscription-modified" state change notifications
952 are sent.
954 8.3. subscription-terminated
956 This indicates that a subscription has been terminated by the
957 publisher. The state change notification includes the reason for the
958 termination. The publisher MAY decide to terminate a subscription
959 when it is running out of resources for serving it, an internal error
960 occurs, etc. Publisher-driven terminations are notified to all
961 receivers. Northbound systems MAY also terminate configured
962 subscriptions using configuration operations.
964 Subscribers can terminate via RPC subscriptions established via a
965 delete-subscription RPC. In such cases, no subscription-terminated
966 state change notifications are sent. However if a kill-subscription
967 RPC is sent, or some other event other than reaching the
968 subscription's stop time results in the end of a subscription, then
969 there MUST be this state change notification that the subscription
970 has been ended.
972 8.4. subscription-suspended
974 This indicates that a publisher has suspended a subscription. The
975 state change notification includes the reason for the suspension. A
976 possible reason is the lack of resources to serve it. No further
977 subscribed event records will be sent until the subscription resumes.
978 Suspensions are notified to the subscriber (in the case of dynamic
979 subscriptions) and all receivers (in the case of configured
980 subscriptions).
982 8.5. subscription-resumed
984 This indicates that a previously suspended subscription has been
985 resumed. Subscribed event records generated after the generation of
986 this state change notification will be sent. These state change
987 notifications go to the subscriber (in the case of dynamic
988 subscriptions) and all receivers (in the case of configured
989 subscriptions).
991 8.6. subscription-completed
993 This indicates that a subscription, which includes a stop time, has
994 successfully finished passing event records upon the reaching of that
995 stop time.
997 8.7. replay-completed
999 This indicates that all of the event records prior to the current
1000 time have been sent. This includes new event records generated since
1001 the start of the subscription. This notification MUST NOT be sent
1002 for any other reason.
1004 If subscription contains no stop time, or has a stop time which has
1005 not been reached, then after the replay-completed notification has
1006 been sent event records will be sent in sequence as they arise
1007 naturally within the system.
1009 9. Administrative Functions
1011 9.1. Subscription Monitoring
1013 Container "subscriptions" in the YANG module below contains the state
1014 of all known subscriptions. This includes subscriptions that were
1015 established (and have not yet been deleted) using RPCs, as well as
1016 subscriptions that have been configured as part of configuration.
1017 Using the "get" operation with NETCONF, or subscribing to this
1018 information via [I-D.ietf-netconf-yang-push] allows the status of
1019 subscriptions to be monitored.
1021 Each subscription is represented as a list element. The associated
1022 information includes an identifier for the subscription, receiver
1023 counter information, the status of the subscription, as well as the
1024 various subscription parameters that are in effect. The subscription
1025 status indicates the subscription's state with each receiver (e.g.,
1026 is currently active or suspended). Leaf "configured-subscription"
1027 indicates whether the subscription came into being via configuration
1028 or via RPC.
1030 Subscriptions that were established by RPC are removed from the list
1031 once they expire (reaching stop-time) or when they are terminated.
1032 Subscriptions that were established by configuration need to be
1033 deleted from the configuration by a configuration editing operation
1034 even if the stop time has been passed.
1036 9.2. Advertisement
1038 Publishers supporting this document MUST indicate support the yang
1039 model "ietf-subscribed-notifications" within the YANG library of the
1040 publisher. In addition support for optional features: encode-xml,
1041 encode-json, configured, and replay MUST also be indicated if
1042 supported.
1044 If a publisher supports this specification but not subscriptions via
1045 [RFC5277], the publisher MUST NOT advertise
1046 "urn:ietf:params:netconf:capability:notification:1.0". Even without
1047 this advertisement however, the publisher MUST support the one-way
1048 notification element of [RFC5277] Section 4.
1050 9.3. Event Stream Discovery
1052 A publisher maintains a list of available event streams as
1053 operational data. This list contains both standardized and vendor-
1054 specific event streams. A client can retrieve this list like any
1055 other YANG-defined data.
1057 10. Data Model
1059 file "ietf-subscribed-notifications.yang"
1060 module ietf-subscribed-notifications {
1061 yang-version 1.1;
1062 namespace
1063 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications";
1065 prefix sn;
1067 import ietf-yang-types {
1068 prefix yang;
1069 }
1070 import ietf-inet-types {
1071 prefix inet;
1072 }
1073 import ietf-interfaces {
1074 prefix if;
1075 }
1077 organization "IETF";
1078 contact
1079 "WG Web:
1080 WG List:
1082 Editor: Alexander Clemm
1083
1085 Editor: Eric Voit
1086
1088 Editor: Alberto Gonzalez Prieto
1089
1091 Editor: Einar Nilsen-Nygaard
1092
1094 Editor: Ambika Prasad Tripathy
1095 ";
1097 description
1098 "Contains a YANG specification for subscribing to event records
1099 and receiving matching content within notification messages.";
1101 revision 2017-10-27 {
1102 description
1103 "Initial version";
1104 reference
1105 "draft-ietf-netconf-subscribed-notifications-06";
1106 }
1108 /*
1109 * FEATURES
1110 */
1112 feature encode-json {
1113 description
1114 "This feature indicates that JSON encoding of notification
1115 messages is supported.";
1116 }
1118 feature encode-xml {
1119 description
1120 "This feature indicates that XML encoding of notification
1121 messages is supported.";
1122 }
1124 feature configured {
1125 description
1126 "This feature indicates that configuration of subscription is
1127 supported.";
1128 }
1130 feature replay {
1131 description
1132 "This feature indicates that historical event record replay is
1133 supported. With replay, it is possible for past event records to
1134 be streamed in chronological order.";
1135 }
1137 feature xpath {
1138 description
1139 "This feature indicates support for xpath filtering.";
1140 reference "http://www.w3.org/TR/1999/REC-xpath-19991116";
1141 }
1143 feature subtree {
1144 description
1145 "This feature indicates support for YANG subtree filtering.";
1146 reference "RFC 6241, Section 6.";
1147 }
1149 /*
1150 * EXTENSIONS
1151 */
1153 extension subscription-state-notif {
1154 description
1155 "This statement applies only to notifications. It indicates that
1156 the notification is a subscription state notification. Therefore
1157 it does not participate in a regular event stream and does not
1158 need to be specifically subscribed to in order to be received.
1159 This statement can only occur as a substatement to the YANG
1160 'notification' statement.";
1161 }
1163 /*
1164 * IDENTITIES
1165 */
1167 /* Identities for subscription results */
1168 identity subscription-result {
1169 description
1170 "Base identity for RPC responses and State Change Notifications
1171 providing information on the creation, modification, deletion of
1172 subscriptions.";
1173 }
1175 identity ok {
1176 base subscription-result;
1177 description
1178 "OK - RPC was successful and was performed as requested.";
1179 }
1180 identity error {
1181 base subscription-result;
1182 description
1183 "Problem with subscription. Base identity for error return
1184 codes for RPCs and State Change Notifications.";
1185 }
1187 /* Identities for subscription errors */
1189 identity suspension-timeout {
1190 base error;
1191 description
1192 "Termination of previously suspended subscription. The publisher
1193 has eliminated the subscription as it exceeded a time limit for
1194 suspension.";
1195 }
1197 identity stream-unavailable {
1198 base error;
1199 description
1200 "Stream does not exist or is not available to the receiver.";
1201 }
1203 identity encoding-unavailable {
1204 base error;
1205 description
1206 "Encoding not supported";
1207 }
1209 identity replay-unsupported {
1210 base error;
1211 description
1212 "Replay cannot be performed for this subscription. The publisher
1213 does not provide the requested historic information via replay.";
1214 }
1216 identity history-unavailable {
1217 base error;
1218 description
1219 "Replay request too far into the past. The publisher does store
1220 historic information for all parts of requested subscription, but
1221 not back to the requested timestamp.";
1222 }
1224 identity filter-unavailable {
1225 base error;
1226 description
1227 "Referenced filter does not exist";
1229 }
1231 identity filter-type-unsupported {
1232 base error;
1233 description
1234 "Publisher does not support filters constructed using this
1235 filtering technology syntax.";
1236 }
1238 identity filter-unsupported {
1239 base error;
1240 description
1241 "Failure can be from a syntax error, or a syntax too complex to be
1242 processed by the platform. The supplemental info should include
1243 the invalid part of the filter.";
1244 }
1246 identity namespace-unavailable {
1247 base error;
1248 description
1249 "Referenced namespace doesn't exist or is unavailable
1250 to the receiver.";
1251 }
1253 identity no-such-subscription {
1254 base error;
1255 description
1256 "Referenced subscription doesn't exist. This may be as a result of
1257 a non-existent subscription ID, an ID which belongs to another
1258 subscriber, or an ID for acceptable subscription which has been
1259 statically configured.";
1260 }
1262 identity insufficient-resources {
1263 base error;
1264 description
1265 "The publisher has insufficient resources to support the
1266 subscription as requested by an RPC.";
1267 }
1269 identity unsupportable-volume {
1270 base error;
1271 description
1272 "The publisher cannot support the volume of information intended
1273 to be sent for an existing subscription.";
1274 }
1276 identity error-no-such-option {
1277 base error;
1278 description
1279 "A requested parameter setting is not supported.";
1280 }
1282 /* Identities for encodings */
1283 identity encodings {
1284 description
1285 "Base identity to represent data encodings";
1286 }
1288 identity encode-xml {
1289 base encodings;
1290 if-feature "encode-xml";
1291 description
1292 "Encode data using XML";
1293 }
1295 identity encode-json {
1296 base encodings;
1297 if-feature "encode-json";
1298 description
1299 "Encode data using JSON";
1300 }
1302 /* Identities for transports */
1303 identity transport {
1304 description
1305 "An identity that represents a the underlying mechanism for
1306 passing notification messages.";
1307 }
1309 identity netconf {
1310 base transport;
1311 description
1312 "Netconf is used a transport for notification messages and state
1313 change notifications.";
1314 reference "draft-ietf-netconf-netconf-event-notifications";
1315 }
1317 identity http2 {
1318 base transport;
1319 description
1320 "HTTP2 is used a transport for notification messages and state
1321 change notifications.";
1322 reference "draft-ietf-netconf-restconf-notif-03, Sections 3.1.1" +
1323 "3.1.3";
1324 }
1325 identity http1.1 {
1326 base transport;
1327 description
1328 "HTTP1.1 is used a transport for notification messages and state
1329 change notifications.";
1330 reference "draft-ietf-netconf-restconf-notif-03, Section 3.1.2";
1331 }
1332 /*
1333 * TYPEDEFs
1334 */
1336 typedef subscription-id {
1337 type uint32;
1338 description
1339 "A type for subscription identifiers.";
1340 }
1342 typedef filter-id {
1343 type string;
1344 description
1345 "A type to identify filters which can be associated with a
1346 subscription.";
1347 }
1349 typedef subscription-result {
1350 type identityref {
1351 base subscription-result;
1352 }
1353 description
1354 "The result of a subscription operation";
1355 }
1357 typedef subscription-errors {
1358 type identityref {
1359 base error;
1360 }
1361 description
1362 "The reason for the failure of an RPC request or the sending
1363 of a subscription suspension or termination state change
1364 notification";
1365 }
1367 typedef encoding {
1368 type identityref {
1369 base encodings;
1370 }
1371 description
1372 "Specifies a data encoding, e.g. for a data subscription.";
1374 }
1376 typedef transport {
1377 type identityref {
1378 base transport;
1379 }
1380 description
1381 "Specifies protocol used to send notification messages to a
1382 receiver.";
1383 }
1385 typedef stream {
1386 type string;
1387 description
1388 "Specifies a system-provided datastream.";
1389 }
1391 typedef stream-filter-ref {
1392 type leafref {
1393 path "/sn:filters/sn:stream-filter/sn:identifier";
1394 }
1395 description
1396 "This type is used to reference a stream filter.";
1397 }
1399 /*
1400 * GROUPINGS
1401 */
1403 grouping stream-filter-elements {
1404 description
1405 "This grouping defines the base for filters applied to event
1406 streams.";
1407 choice filter-spec {
1408 description
1409 "The content filter specification for this request.";
1410 anydata subtree-filter {
1411 if-feature "subtree";
1412 description
1413 "Event stream evaluation criteria encoded in a syntax of a
1414 supported type of an RFC 6241, Section 6 filter. The subtree
1415 filter is applied to the representation of individual,
1416 delineated event records as contained within the event
1417 stream. For example, if the notification message contains an
1418 instance of a notification defined in YANG, then the top-
1419 level element is the name of the YANG notification. If the
1420 stream filter matches an event record from the stream, the
1421 event record should be included in a notification message
1422 to the receiver(s).";
1423 }
1424 leaf xpath-filter {
1425 if-feature "xpath";
1426 type yang:xpath1.0;
1427 description
1428 "Event stream evaluation criteria encoded in a syntax of xpath
1429 1.0 and applied against an event stream. The result of
1430 applying XPath expression is converted to a boolean value
1431 using the standard XPath 1.0 rules. If the boolean value is
1432 'true', the stream filter matches an event record within the
1433 stream, and the notification message should be sent to the
1434 receiver(s).";
1435 }
1436 }
1437 }
1439 grouping subscription-policy-modifiable {
1440 description
1441 "This grouping describes all objects which may be changed
1442 in a subscription via an RPC.";
1443 choice target {
1444 mandatory true;
1445 description
1446 "Identifies the source of information against which a
1447 subscription is being applied, as well as specifics on the
1448 subset of information desired from that source. This choice
1449 exists so that additional filter types can be added via
1450 augmentation.";
1451 case stream {
1452 choice stream-filter {
1453 description
1454 "An event stream filter can be applied to a subscription.
1455 That filter will come either referenced from a global list,
1456 or be provided within the subscription itself.";
1457 case by-reference {
1458 description
1459 "Apply a filter that has been configured separately.";
1460 leaf stream-filter-ref {
1461 type stream-filter-ref;
1462 mandatory true;
1463 description
1464 "References an existing stream-filter which is to
1465 be applied to stream for the subscription.";
1466 }
1467 }
1468 case within-subscription {
1469 description
1470 "Local definition allows a filter to have the same
1471 lifecycle as the subscription.";
1472 uses stream-filter-elements;
1473 }
1474 }
1475 }
1476 }
1477 leaf stop-time {
1478 type yang:date-and-time;
1479 description
1480 "Identifies a time after which notification messages for a
1481 subscription should not be sent. If stop-time is not present,
1482 the notification messages will continue until the subscription
1483 is terminated. If replay-start-time exists, stop-time must be
1484 for a subsequent time. If replay-start-time doesn't exist,
1485 stop-time must be for a future time.";
1486 }
1487 }
1489 grouping subscription-policy {
1490 description
1491 "This grouping describes information concerning a subscription.";
1492 leaf encoding {
1493 type encoding;
1494 mandatory true;
1495 description
1496 "The type of encoding for the subscribed data.";
1497 }
1498 uses subscription-policy-modifiable {
1499 augment target/stream {
1500 description
1501 "Adds additional objects which must be set just by RPC.";
1502 leaf stream {
1503 type stream;
1504 mandatory true;
1505 description
1506 "Indicates a stream of event records against which to apply
1507 a stream filter.";
1508 }
1509 leaf replay-start-time {
1510 if-feature "replay";
1511 type yang:date-and-time;
1512 description
1513 "Used to trigger the replay feature and indicate that the
1514 replay should start at the time specified. If
1515 replay-start-time is not present, this is not a replay
1516 subscription and event record push should start immediately.
1517 It is never valid to specify start times that are later than
1518 or equal to the current time.";
1519 }
1520 }
1521 }
1522 }
1524 grouping notification-origin-info {
1525 description
1526 "Defines the sender source from which notification messages for a
1527 configured subscription are sent.";
1528 choice notification-message-origin {
1529 description
1530 "Identifies the egress interface on the Publisher from which
1531 notification messages are to be sent.";
1532 case interface-originated {
1533 description
1534 "When the push source is out of an interface on the
1535 Publisher established via static configuration.";
1536 leaf source-interface {
1537 type if:interface-ref;
1538 description
1539 "References the interface for notification messages.";
1540 }
1541 }
1542 case address-originated {
1543 description
1544 "When the push source is out of an IP address on the
1545 Publisher established via static configuration.";
1546 leaf source-vrf {
1547 type string;
1548 description
1549 "Network instance name for the VRF. This could also have
1550 been a leafref to draft-ietf-rtgwg-ni-model, but that model
1551 is not complete, and might not be implemented on a box.";
1552 }
1553 leaf source-address {
1554 type inet:ip-address-no-zone;
1555 description
1556 "The source address for the notification messages. If a
1557 source VRF exists, but this object doesn't, a publisher's
1558 default address for that VRF must be used.";
1559 }
1560 }
1561 }
1562 }
1564 grouping receiver-info {
1565 description
1566 "Defines where and how to get notification messages for a
1567 configured subscriptions to one or more targeted recipient. This
1568 includes specifying the destination addressing as well as a
1569 transport protocol acceptable to the receiver.";
1570 container receivers {
1571 description
1572 "Set of receivers in a subscription.";
1573 list receiver {
1574 key "address port";
1575 min-elements 1;
1576 description
1577 "A single host or multipoint address intended as a target
1578 for the notification messages of a subscription.";
1579 leaf address {
1580 type inet:host;
1581 description
1582 "Specifies the address for the traffic to reach a remote
1583 host. One of the following must be specified: an ipv4
1584 address, an ipv6 address, or a host name.";
1585 }
1586 leaf port {
1587 type inet:port-number;
1588 description
1589 "This leaf specifies the port number to use for messages
1590 destined for a receiver.";
1591 }
1592 leaf protocol {
1593 type transport;
1594 mandatory true;
1595 description
1596 "This leaf specifies the transport protocol used
1597 to deliver messages destined for the receiver. Each
1598 protocol may use the address and port information
1599 differently as applicable.";
1600 }
1601 }
1602 }
1603 }
1605 grouping error-identifier {
1606 description
1607 "A code passed back within an RPC response to describe why the RFC
1608 has failed, or within a state change notification to describe why
1609 the change has occurred.";
1610 leaf error-id {
1611 type subscription-errors;
1612 mandatory true;
1613 description
1614 "Identifies the subscription error condition.";
1615 }
1616 }
1618 grouping hints {
1619 description
1620 "Objects passed back within an RPC response to describe why the
1621 RFC has failed, or within a state change notification to
1622 describe why the change has occurred.";
1623 leaf filter-failure {
1624 type string;
1625 description
1626 "Information describing where and/or why a provided filter was
1627 unsupportable for a subscription.";
1628 }
1629 }
1631 grouping subscription-response-with-hints {
1632 description
1633 "Defines the output for the establish-subscription and
1634 modify-subscription RPCs.";
1635 leaf subscription-result {
1636 type subscription-result;
1637 mandatory true;
1638 description
1639 "Indicates whether subscription is operational, or if a problem
1640 was encountered.";
1641 }
1642 choice result {
1643 description
1644 "Depending on the subscription result, different data is
1645 returned.";
1646 case no-success {
1647 description
1648 "This case applies when a subscription request was not
1649 successful and no subscription was created (or modified) as a
1650 result. In this case, information MAY be returned that
1651 indicates suggested parameter settings that would have a
1652 high likelihood of succeeding in a subsequent establish-
1653 subscription or modify-subscription request.";
1654 uses hints;
1655 }
1656 }
1657 }
1659 /*
1660 * RPCs
1661 */
1663 rpc establish-subscription {
1664 description
1665 "This RPC allows a subscriber to create (and possibly negotiate)
1666 a subscription on its own behalf. If successful, the
1667 subscription remains in effect for the duration of the
1668 subscriber's association with the publisher, or until the
1669 subscription is terminated. In case an error (as indicated by
1670 subscription-result) is returned, the subscription is not
1671 created. In that case, the RPC reply MAY include suggested
1672 parameter settings that would have a higher likelihood of
1673 succeeding in a subsequent establish-subscription request.";
1674 input {
1675 uses subscription-policy {
1676 refine "encoding" {
1677 mandatory false;
1678 description
1679 "The type of encoding for the subscribed data. If not
1680 included as part of the RPC, the encoding MUST be set by the
1681 publisher to be the encoding used by this RPC.";
1682 }
1683 }
1684 }
1685 output {
1686 uses subscription-response-with-hints {
1687 augment "result" {
1688 description
1689 "Allows information to be passed back as part of a
1690 successful subscription establishment.";
1691 case success {
1692 description
1693 "This case is used when the subscription request was
1694 successful.";
1695 leaf identifier {
1696 type subscription-id;
1697 mandatory true;
1698 description
1699 "Identifier used for this subscription.";
1700 }
1701 }
1702 }
1703 augment "result/no-success" {
1704 description
1705 "Contains establish RPC specific objects which can be
1706 returned as hints for future attempts.";
1707 leaf replay-start-time-hint {
1708 type yang:date-and-time;
1709 description
1710 "If a replay has been requested, but the requested replay
1711 time cannot be honored, this may provide a hint at an
1712 alternate time which may be supportable.";
1713 }
1714 }
1715 }
1716 }
1717 }
1719 rpc modify-subscription {
1720 description
1721 "This RPC allows a subscriber to modify a subscription that was
1722 previously created using establish-subscription. If successful,
1723 the changed subscription remains in effect for the duration of
1724 the subscriber's association with the publisher, or until the
1725 subscription is again modified or terminated. In case an error
1726 is returned (as indicated by subscription-result), the
1727 subscription is not modified and the original subscription
1728 parameters remain in effect. In that case, the rpc error
1729 response MAY include suggested parameter hints that would have
1730 a high likelihood of succeeding in a subsequent
1731 modify-subscription request.";
1732 input {
1733 leaf identifier {
1734 type subscription-id;
1735 description
1736 "Identifier to use for this subscription.";
1737 }
1738 uses subscription-policy-modifiable;
1739 }
1740 output {
1741 uses subscription-response-with-hints;
1742 }
1743 }
1745 rpc delete-subscription {
1746 description
1747 "This RPC allows a subscriber to delete a subscription that
1748 was previously created from by that same subscriber using the
1749 establish-subscription RPC.";
1750 input {
1751 leaf identifier {
1752 type subscription-id;
1753 mandatory true;
1754 description
1755 "Identifier of the subscription that is to be deleted.
1756 Only subscriptions that were created using
1757 establish-subscription can be deleted via this RPC.";
1758 }
1760 }
1761 output {
1762 leaf subscription-result {
1763 type subscription-result;
1764 mandatory true;
1765 description
1766 "Indicates whether subscription has been deleted, or if a
1767 problem was encountered.";
1768 }
1769 }
1770 }
1772 rpc kill-subscription {
1773 description
1774 "This RPC allows an operator to delete a dynamic subscription
1775 without restrictions on the originating subscriber or underlying
1776 transport session.";
1777 input {
1778 leaf identifier {
1779 type subscription-id;
1780 mandatory true;
1781 description
1782 "Identifier of the subscription that is to be deleted. Only
1783 subscriptions that were created using establish-subscription
1784 can be deleted via this RPC.";
1785 }
1786 }
1787 output {
1788 leaf subscription-result {
1789 type subscription-result;
1790 mandatory true;
1791 description
1792 "Indicates whether subscription has been killed, or if a
1793 problem was encountered.";
1794 }
1795 }
1796 }
1798 /*
1799 * NOTIFICATIONS
1800 */
1802 notification replay-completed {
1803 sn:subscription-state-notif;
1804 if-feature "replay";
1805 description
1806 "This notification is sent to indicate that all of the replay
1807 notifications have been sent. It must not be sent for any other
1809 reason.";
1810 leaf identifier {
1811 type subscription-id;
1812 mandatory true;
1813 description
1814 "This references the affected subscription.";
1815 }
1816 }
1818 notification subscription-completed {
1819 sn:subscription-state-notif;
1820 description
1821 "This notification is sent to indicate that a subscription has
1822 finished passing event records.";
1823 leaf identifier {
1824 type subscription-id;
1825 mandatory true;
1826 description
1827 "This references the gracefully completed subscription.";
1828 }
1829 }
1831 notification subscription-started {
1832 sn:subscription-state-notif;
1833 if-feature "configured";
1834 description
1835 "This notification indicates that a subscription has started and
1836 notifications are beginning to be sent. This notification shall
1837 only be sent to receivers of a subscription; it does not
1838 constitute a general-purpose notification.";
1839 leaf identifier {
1840 type subscription-id;
1841 mandatory true;
1842 description
1843 "This references the affected subscription.";
1844 }
1845 uses subscription-policy {
1846 refine "target/stream/replay-start-time" {
1847 description
1848 "Indicates the time that a replay using for the streaming of
1849 buffered event records. This will be populated with the most
1850 recent of the following: replay-log-creation-time,
1851 replay-log-aged-time, replay-start-time, or the most recent
1852 publisher boot time.";
1853 }
1854 }
1855 }
1856 notification subscription-resumed {
1857 sn:subscription-state-notif;
1858 description
1859 "This notification indicates that a subscription that had
1860 previously been suspended has resumed. Notifications will once
1861 again be sent.";
1862 leaf identifier {
1863 type subscription-id;
1864 mandatory true;
1865 description
1866 "This references the affected subscription.";
1867 }
1868 }
1870 notification subscription-modified {
1871 sn:subscription-state-notif;
1872 if-feature "configured";
1873 description
1874 "This notification indicates that a subscription has been
1875 modified. Notification messages sent from this point on will
1876 conform to the modified terms of the subscription. For
1877 completeness, this state change notification includes both
1878 modified and non-modified aspects of a subscription.";
1879 leaf identifier {
1880 type subscription-id;
1881 mandatory true;
1882 description
1883 "This references the affected subscription.";
1884 }
1885 uses subscription-policy;
1886 }
1888 notification subscription-terminated {
1889 sn:subscription-state-notif;
1890 description
1891 "This notification indicates that a subscription has been
1892 terminated.";
1893 leaf identifier {
1894 type subscription-id;
1895 mandatory true;
1896 description
1897 "This references the affected subscription.";
1898 }
1899 uses error-identifier;
1900 uses hints;
1901 }
1903 notification subscription-suspended {
1904 sn:subscription-state-notif;
1905 description
1906 "This notification indicates that a suspension of the
1907 subscription by the publisher has occurred. No further
1908 notifications will be sent until the subscription resumes.
1909 This notification shall only be sent to receivers of a
1910 subscription; it does not constitute a general-purpose
1911 notification.";
1912 leaf identifier {
1913 type subscription-id;
1914 mandatory true;
1915 description
1916 "This references the affected subscription.";
1917 }
1918 uses error-identifier;
1919 uses hints;
1920 }
1922 /*
1923 * DATA NODES
1924 */
1926 container streams {
1927 config false;
1928 description
1929 "This container contains information on the built-in streams
1930 provided by the publisher.";
1931 list stream {
1932 key "name";
1933 description
1934 "Identifies the built-in streams that are supported by the
1935 publisher.";
1936 leaf name {
1937 type stream;
1938 description
1939 "A handle for a sequential set of event records, each of which
1940 is characterized by its own domain and semantics.";
1941 }
1942 leaf description {
1943 type string;
1944 mandatory true;
1945 description
1946 "A description of the event stream, including such information
1947 as the type of event records that are available within this
1948 stream.";
1949 }
1950 leaf replay-support {
1951 if-feature "replay";
1952 type empty;
1953 description
1954 "Indicates that event record replay is available on this
1955 stream.";
1956 }
1957 leaf replay-log-creation-time {
1958 if-feature "replay";
1959 type yang:date-and-time;
1960 description
1961 "The timestamp of the creation of the log used to support the
1962 replay function on this stream. Note that this might be
1963 earlier then the earliest available information contained in
1964 the log. This object is updated if the log resets for some
1965 reason. This object MUST be present if replay is supported.";
1966 }
1967 leaf replay-log-aged-time {
1968 if-feature "replay";
1969 type yang:date-and-time;
1970 description
1971 "The timestamp of the last event record aged out of the log.
1972 This object MUST be present if replay is supported and any
1973 event record have been aged out of the log.";
1974 }
1975 }
1976 }
1978 container filters {
1979 description
1980 "This container contains a list of configurable filters
1981 that can be applied to subscriptions. This facilitates
1982 the reuse of complex filters once defined.";
1983 list stream-filter {
1984 key "identifier";
1985 description
1986 "A list of pre-positioned filters that can be applied to
1987 subscriptions.";
1988 leaf identifier {
1989 type filter-id;
1990 description
1991 "An identifier to differentiate between filters.";
1992 }
1993 uses stream-filter-elements;
1994 }
1995 }
1997 container subscription-config {
1998 if-feature "configured";
1999 description
2000 "Contains the list of subscriptions that are configured,
2001 as opposed to established via RPC or other means.";
2002 list subscription {
2003 key "identifier";
2004 description
2005 "The identity and specific parameters of a subscription.";
2006 leaf identifier {
2007 type subscription-id;
2008 description
2009 "Identifier to use for this subscription.";
2010 }
2011 uses subscription-policy;
2012 uses receiver-info {
2013 augment receivers/receiver {
2014 description
2015 "include operational data for receivers.";
2016 leaf status {
2017 type enumeration {
2018 enum connecting {
2019 value 5;
2020 description
2021 "A subscription has been configured, and a
2022 subscription-started state change notification should
2023 be sent as quickly as possible.";
2024 }
2025 enum suspended {
2026 value 3;
2027 description
2028 "The status is suspended, meaning that the publisher is
2029 currently will not provide notification messages for
2030 the subscription until some status change.";
2031 }
2032 }
2033 default "connecting";
2034 description
2035 "Allows state initialization of a particular receiver.";
2036 }
2037 }
2038 }
2039 uses notification-origin-info;
2040 }
2041 }
2042 container subscriptions {
2043 config false;
2044 description
2045 "Contains the list of currently active subscriptions, i.e.
2046 subscriptions that are currently in effect, used for subscription
2047 management and monitoring purposes. This includes subscriptions
2048 that have been setup via RPC primitives as well as subscriptions
2049 that have been established via configuration.";
2050 list subscription {
2051 key "identifier";
2052 description
2053 "The identity and specific parameterst of a subscription.
2054 Subscriptions within this list can be created using a control
2055 channel or RPC, or be established through configuration.";
2056 leaf identifier {
2057 type subscription-id;
2058 description
2059 "Identifier of a subscription; unique within a publisher";
2060 }
2061 leaf configured-subscription {
2062 if-feature "configured";
2063 type empty;
2064 description
2065 "The presence of this leaf indicates that the subscription
2066 originated from configuration, not through a control channel
2067 or RPC.";
2068 }
2069 uses subscription-policy;
2070 uses notification-origin-info {
2071 if-feature "configured";
2072 }
2073 uses receiver-info {
2074 augment receivers/receiver {
2075 description
2076 "include operational data for receivers.";
2077 leaf pushed-notifications {
2078 type yang:counter64;
2079 description
2080 "Operational data which provides the number of update
2081 notification messages pushed to a receiver.";
2082 }
2083 leaf excluded-notifications {
2084 type yang:counter64;
2085 description
2086 "Operational data which provides the number of event
2087 records from a stream explicitly removed via filtering so
2088 that they are not sent to a receiver.";
2089 }
2090 leaf status {
2091 type enumeration {
2092 enum active {
2093 value 1;
2094 description
2095 "Connection is active and healthy.";
2097 }
2098 enum concluded {
2099 value 2;
2100 description
2101 "A subscription is inactive as it has hit a stop time,
2102 but not yet been removed.";
2103 }
2104 enum suspended {
2105 value 3;
2106 description
2107 "The status is suspended, meaning that the publisher
2108 is currently unable to provide notification messages
2109 for the subscription.";
2110 }
2111 enum in-error {
2112 value 4;
2113 description
2114 "The status is in error or degraded, meaning that a
2115 subscription is unsupportable with its current
2116 parameters.";
2117 }
2118 enum connecting {
2119 value 5;
2120 description
2121 "A subscription has been configured, but a
2122 subscription-started state change notification has not
2123 yet been succesfully received.";
2124 }
2125 }
2126 mandatory true;
2127 description
2128 "Specifies the status of a subscription from the
2129 perspective of a particular receiver. With this info it
2130 is possible to determine whether a subscriber is currently
2131 generating notification messages intended for that
2132 receiver.";
2133 }
2134 }
2135 }
2136 }
2137 }
2138 }
2139
2140 11. Considerations
2142 11.1. Implementation Considerations
2144 For a deployment including both configured and dynamic subscriptions,
2145 split subscription identifiers into static and dynamic halves. That
2146 way it is unlikely there will be collisions if the configured
2147 subscriptions attempt to set a subscription-id which might have
2148 already been dynamically allocated. The lower half SHOULD be used
2149 for subscriptions which will have subscription identifiers provided
2150 from outside the publisher, and upper half for subscription
2151 identifiers assigned by the publisher.
2153 No state change notification or nor subscribed event records within
2154 notification messages may be sent before the transport layer,
2155 including any requried capabilities exchange, has been established.
2157 An implementation may choose to transition between active and
2158 suspended subscription states more frequently than required by this
2159 specification. However if a subscription is unable to marshal all
2160 intended updates into a transmittable message in multiple successive
2161 intervals, the subscription SHOULD be suspended with the reason
2162 "unsupportable-volume".
2164 For configured subscriptions, operations are against the set of
2165 receivers using the subscription identifier as a handle for that set.
2166 But for streaming up dates, state change notifications are local to a
2167 receiver. In this specification it is the case that receivers get no
2168 information from the publisher about the existence of other
2169 receivers. But if an operator wants to let the receivers correlate
2170 results, it is useful to use the subscription identifier handle
2171 across the receivers to allow that correlation.
2173 11.2. Security Considerations
2175 For dynamic subscriptions the publisher MUST authenticate and
2176 authorize all RPC requests.
2178 Subscriptions could overload a publisher's CPU. For this reason, the
2179 publisher MUST have the ability to decline a dynamic subscription
2180 request, and provide the appropriate RPC error response to a
2181 subscriber should the proposed subscription overly deplete the
2182 publisher's resources.
2184 A publisher needs to be able to suspend an existing dynamic or
2185 configured subscription based on capacity constraints. When this
2186 occurs, the subscription status MUST be updated accordingly and the
2187 receivers notified with subscription state notifications.
2189 If a malicious or buggy subscriber sends an unexpectedly large number
2190 of RPCs, the result might be an excessive use of system resources.
2191 In such a situation, subscription interactions MAY be terminated by
2192 terminating the transport session.
2194 For both configured and dynamic subscriptions the publisher MUST
2195 authenticate and authorize a receiver via some transport level
2196 mechanism before sending any updates.
2198 A secure transport is highly recommended and the publisher MUST
2199 ensure that the user has sufficient authorization to perform the
2200 function they are requesting against the specific subset of content
2201 involved.
2203 A publisher MUST NOT include any content in a notification message
2204 for which the user has not been authorized.
2206 With configured subscriptions, one or more publishers could be used
2207 to overwhelm a receiver. No notification messages SHOULD be sent to
2208 any receiver which doesn't even support subscriptions. Subscribers
2209 that do not want notification messages need only terminate or refuse
2210 any transport sessions from the publisher.
2212 The NETCONF Authorization Control Model [RFC6536bis] SHOULD be used
2213 to control and restrict authorization of subscription configuration.
2214 This control models permits specifying per-user permissions to
2215 receive event records from specific streams.
2217 Where NACM is available, the NACM "very-secure" tag MUST be placed on
2218 the "kill-subscription" RPC so that only administrators have access
2219 to use this.
2221 One subscription id can be used for two or more receivers of the same
2222 configured subscription. But due to the possibility of different
2223 access control permissions per receiver, it SHOULD NOT be assumed
2224 that each receiver is getting identical updates.
2226 12. Acknowledgments
2228 For their valuable comments, discussions, and feedback, we wish to
2229 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen,
2230 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan
2231 Hares, Michael Scharf, and Guangying Zheng.
2233 13. References
2235 13.1. Normative References
2237 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2238 Requirement Levels", BCP 14, RFC 2119,
2239 DOI 10.17487/RFC2119, March 1997,
2240 .
2242 [RFC6536bis]
2243 Bierman, A. and M. Bjorklund, "Network Configuration
2244 Protocol (NETCONF) Access Control Model", draft-ietf-
2245 netconf-rfc6536bis-01 (work in progress), September 2017.
2247 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2248 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2249 .
2251 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath)
2252 Version 1.0", November 1999,
2253 .
2255 13.2. Informative References
2257 [I-D.draft-ietf-netconf-netconf-event-notifications]
2258 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto.,
2259 Nilsen-Nygaard, E., Tripathy, A., Chisholm, S., and H.
2260 Trevino, "NETCONF support for event notifications",
2261 October 2016, .
2264 [I-D.draft-ietf-netconf-restconf-notif]
2265 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen-
2266 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and
2267 HTTP transport for event notifications", August 2016,
2268 .
2271 [I-D.ietf-netconf-yang-push]
2272 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto.,
2273 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B.
2274 Lengyel, "YANG Datastore Subscription", October 2017,
2275 .
2278 [I.D.draft-ietf-netconf-notification-messages]
2279 Voit, Eric., Clemm, Alexander., Bierman, A., and T.
2280 Jenkins, "YANG Notification Headers and Bundles",
2281 September 2017, .
2284 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2285 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
2286 .
2288 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2289 and A. Bierman, Ed., "Network Configuration Protocol
2290 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2291 .
2293 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2294 for Subscription to YANG Datastores", RFC 7923,
2295 DOI 10.17487/RFC7923, June 2016,
2296 .
2298 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2299 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2300 .
2302 Appendix A. Changes between revisions
2304 (To be removed by RFC editor prior to publication)
2306 v06 - v07
2308 o Clarification on state machine for configured susbcriptions.
2310 v05 - v06
2312 o Made changes proposed by Martin, Kent, and others on the list.
2313 Most significant of these are Stream returned to string (with the
2314 SYSLOG identity removed), intro section on 5277 relationship, an
2315 identity set moved to an enumeration, clean up of definitions/
2316 terminology, state machine proposed for configured subscriptions
2317 with a clean-up of susbcription state options.
2319 o JSON and XML become features. Also Xpath and subtree filtering
2320 become features
2322 o Terminology updates with event records, and refinement of filters
2323 to just stream filters.
2325 o Encoding refined in establish-subscription so it takes the RPC's
2326 encoding as the default.
2328 o Namespaces in examples fixed.
2330 v04 - v05
2332 o Returned to the explicit filter subtyping of v00
2334 o stream object changed to 'name' from 'stream'
2336 o Cleaned up examples
2338 o Clarified that JSON support needs notification-messages draft.
2340 v03 - v04
2342 o Moved back to the use of RFC5277 one-way notifications and
2343 encodings.
2345 v03 - v04
2347 o Replay updated
2349 v02 - v03
2351 o RPCs and Notification support is identified by the Notification
2352 2.0 capability.
2354 o Updates to filtering identities and text
2356 o New error type for unsupportable volume of updates
2358 o Text tweaks.
2360 v01 - v02
2362 o Subscription status moved under receiver.
2364 v00 - v01
2366 o Security considerations updated
2368 o Intro rewrite, as well as scattered text changes
2370 o Added Appendix A, to help match this to related drafts in progress
2371 o Updated filtering definitions, and filter types in yang file, and
2372 moved to identities for filter types
2374 o Added Syslog as a stream
2376 o HTTP2 moved in from YANG-Push as a transport option
2378 o Replay made an optional feature for events. Won't apply to
2379 datastores
2381 o Enabled notification timestamp to have different formats.
2383 o Two error codes added.
2385 v01 5277bis - v00 subscribed notifications
2387 o Kill subscription RPC added.
2389 o Renamed from 5277bis to Subscribed Notifications.
2391 o Changed the notification capabilities version from 1.1 to 2.0.
2393 o Extracted create-subscription and other elements of RFC5277.
2395 o Error conditions added, and made specific in return codes.
2397 o Simplified yang model structure for removal of 'basic' grouping.
2399 o Added a grouping for items which cannot be statically configured.
2401 o Operational counters per receiver.
2403 o Subscription-id and filter-id renamed to identifier
2405 o Section for replay added. Replay now cannot be configured.
2407 o Control plane notification renamed to subscription state
2408 notification
2410 o Source address: Source-vrf changed to string, default address
2411 option added
2413 o In yang model: 'info' changed to 'policy'
2415 o Scattered text clarifications
2417 v00 - v01 of 5277bis
2418 o YANG Model changes. New groupings for subscription info to allow
2419 restriction of what is changeable via RPC. Removed notifications
2420 for adding and removing receivers of configured subscriptions.
2422 o Expanded/renamed definitions from event server to publisher, and
2423 client to subscriber as applicable. Updated the definitions to
2424 include and expand on RFC 5277.
2426 o Removal of redundancy with other drafts
2428 o Many other clean-ups of wording and terminology
2430 Authors' Addresses
2432 Eric Voit
2433 Cisco Systems
2435 Email: evoit@cisco.com
2437 Alexander Clemm
2438 Huawei
2440 Email: ludwig@clemm.org
2442 Alberto Gonzalez Prieto
2443 VMWare
2445 Email: agonzalezpri@vmware.com
2447 Einar Nilsen-Nygaard
2448 Cisco Systems
2450 Email: einarnn@cisco.com
2452 Ambika Prasad Tripathy
2453 Cisco Systems
2455 Email: ambtripa@cisco.com