idnits 2.17.1
draft-ietf-netconf-subscribed-notifications-08.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 538 has weird spacing: '...-result sub...'
== Line 562 has weird spacing: '...ntifier sub...'
== Line 564 has weird spacing: '...-result sub...'
== Line 971 has weird spacing: '...ntifier sub...'
== Line 1131 has weird spacing: '...ro time yan...'
== (1 more instance...)
-- The document date (December 22, 2017) is 2316 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-03
== Outdated reference: A later version (-09) exists of
draft-ietf-netconf-rfc6536bis-01
-- 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 (~~), 9 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: June 25, 2018 Huawei
6 A. Gonzalez Prieto
7 VMWare
8 E. Nilsen-Nygaard
9 A. Tripathy
10 Cisco Systems
11 December 22, 2017
13 Custom Subscription to Event Streams
14 draft-ietf-netconf-subscribed-notifications-08
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 June 25, 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 . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . 13
70 2.6. Event Record Delivery . . . . . . . . . . . . . . . . . . 18
71 2.7. Subscription State Notifications . . . . . . . . . . . . 18
72 2.8. Subscription Monitoring . . . . . . . . . . . . . . . . . 22
73 2.9. Advertisement . . . . . . . . . . . . . . . . . . . . . . 22
74 3. YANG Data Model Trees . . . . . . . . . . . . . . . . . . . . 23
75 3.1. Event Streams Container . . . . . . . . . . . . . . . . . 23
76 3.2. Event Stream Filters Container . . . . . . . . . . . . . 23
77 3.3. Subscriptions Container . . . . . . . . . . . . . . . . . 23
78 3.4. Subscription-config Container . . . . . . . . . . . . . . 25
79 4. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 25
80 5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 51
81 5.1. Implementation Considerations . . . . . . . . . . . . . . 51
82 5.2. IANA Considerations . . . . . . . . . . . . . . . . . . . 52
83 5.3. Security Considerations . . . . . . . . . . . . . . . . . 52
84 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53
85 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 54
86 7.1. Normative References . . . . . . . . . . . . . . . . . . 54
87 7.2. Informative References . . . . . . . . . . . . . . . . . 55
88 Appendix A. Changes between revisions . . . . . . . . . . . . . 55
89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58
91 1. Introduction
93 This document defines capabilities and operations for the customized
94 establishment of subscriptions upon system generated event streams.
95 Effectively this enables a "subscribe then publish" capability where
96 the customized information needs of each target receiver are
97 understood by the publisher before subscribed event records are
98 marshalled and pushed. The receiver then gets a continuous, custom
99 feed of publisher generated information.
101 While the functionality defined in this document is transport-
102 agnostic, protocols like NETCONF [RFC6241] or RESTCONF [RFC8040] can
103 be used to configure or dynamically signal subscriptions, and there
104 are bindings defined for subscribed event record delivery for NETCONF
105 within [I-D.draft-ietf-netconf-netconf-event-notifications], and for
106 HTTP2 or HTTP1.1 within [I-D.draft-ietf-netconf-restconf-notif].
108 1.1. Motivation
110 There are various [RFC5277] limitations, many of which have been
111 exposed in [RFC7923] which needed to be solved. Key capabilities
112 supported by this document include:
114 o multiple subscriptions on a single transport session
116 o support for dynamic and statically configured subscriptions
118 o modification of an existing subscription
120 o operational counters and instrumentation
122 o negotiation of subscription parameters (through the use of hints
123 returned as part of declined subscription requests)
125 o state change notifications (e.g., publisher driven suspension,
126 parameter modification)
128 o independence from transport protocol
130 1.2. Terminology
132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
134 document are to be interpreted as described in RFC 2119 [RFC2119].
136 Configured subscription: A subscription installed via a configuration
137 interface which persists across reboots.
139 Dynamic subscription: A subscription agreed between subscriber and
140 publisher created via an establish-subscription RPC.
142 Event: An occurrence of something that may be of interest. (e.g., a
143 configuration change, a fault, a change in status, crossing a
144 threshold, or an external input to the system.)
145 Event record: A set of information detailing an event.
147 NACM: NETCONF Access Control Model.
149 Notification message: A set of transport encapsulated information
150 intended for a receiver indicating that one or more event(s) have
151 occurred. A notification message may bundle multiple event records.
152 This includes the bundling multiple, independent RFC 7950 YANG
153 notifications.
155 Publisher: An entity responsible for streaming notification messages
156 per the terms of a Subscription.
158 Receiver: A target to which a publisher pushes subscribed event
159 records. For dynamic subscriptions, the receiver and subscriber are
160 the same entity.
162 Stream (also referred to as "event stream"): A continuous ordered set
163 of events aggregated under some context.
165 Stream filter: Evaluation criteria which may be applied against event
166 records within a stream. Event records pass the filter when
167 specified criteria are met.
169 Subscribed event records: Event records which have met the terms of
170 the subscription. This include terms (such as security checks)
171 enforced by the publisher.
173 Subscriber: An entity able to request and negotiate a contract for
174 the generation and push of event records from a publisher.
176 Subscription: A contract with a publisher, stipulating which
177 information one or more receivers wish to have pushed from the
178 publisher without the need for further solicitation.
180 1.3. Solution Overview
182 This document describes a transport agnostic mechanism for
183 subscribing to and receiving content from a stream instantiated
184 within a publisher. This mechanism is through the use of a
185 subscription.
187 Two types of subscriptions are supported:
189 1. Dynamic subscriptions, where a subscriber initiates a
190 subscription negotiation with a publisher via RPC. If the
191 publisher wants to serve this request, it accepts it, and then
192 starts pushing notification messages. If the publisher does not
193 wish to serve it as requested, then an error response is
194 returned. This response MAY include hints at subscription
195 parameters which would have been accepted.
197 2. Configured subscriptions, which allow the management of
198 subscriptions via a configuration interface so that a publisher
199 can send notification messages to configured receiver(s).
200 Support for this capability is optional.
202 Additional characteristics differentiating configured from dynamic
203 subscriptions include:
205 o The lifetime of a dynamic subscription is bounded by the transport
206 session used to establish it. For connection-oriented stateful
207 transport like NETCONF, the loss of the transport session will
208 result in the immediate termination of any associated dynamic
209 subscriptions. For connectionless or stateless transports like
210 HTTP, a lack of receipt acknowledgement of a sequential set of
211 notification messages and/or keep-alives can be used to trigger a
212 termination of a dynamic subscription. Contrast this to the
213 lifetime of a configured subscription. This lifetime is driven by
214 relevant configuration being present within the publisher's
215 running configuration. Being tied to configuration operations
216 implies configured subscriptions can be configured to persist
217 across reboots, and implies a configured subscription can persist
218 even when its publisher is fully disconnected from any network.
220 o Configured subscriptions can be modified by any configuration
221 client with write permission on the configuration of the
222 subscription. Dynamic subscriptions can only be modified via an
223 RPC request made by the original subscriber.
225 Note that there is no mixing-and-matching of dynamic and configured
226 operations on a single subscriptions. Specifically, a configured
227 subscription cannot be modified or deleted using RPCs defined in this
228 document. Similarly, a subscription established via RPC cannot be
229 modified through configuration operations. Also note that transport
230 specific transport drafts based on this specification MUST detail the
231 life cycles of both dynamic and configured subscriptions.
233 The publisher MAY decide to terminate a dynamic subscription at any
234 time. Similarly, it MAY decide to temporarily suspend the sending of
235 notification messages for any dynamic subscription, or for one or
236 more receivers of a configured subscription. Such termination or
237 suspension is driven by internal considerations of the publisher.
239 1.4. Relationship to RFC-5277
241 This document is intended to provide a superset of the subscription
242 capabilities initially defined within [RFC5277]. Especially when
243 extending an existing [RFC5277] implementation, it is important to
244 understand what has been reused and what has been replaced. Key
245 relationships between these two documents include:
247 o the data model in this document replaces the data model in
248 [RFC5277].
250 o the RPC operations in this draft replaces the symmetrical
251 operations of [RFC5277], section 4.
253 o the one way operation of [RFC5277] is still used. However this
254 operation will no longer be required with the availability of
255 [I.D.draft-ietf-netconf-notification-messages].
257 o the definition and contents of the NETCONF stream are identical
258 between this document and [RFC5277].
260 o a publisher MAY implement both the data model and RPCs defined in
261 [RFC5277] and this new document concurrently, in order to support
262 old clients. However the use of both alternatives on a single
263 transport session is prohibited.
265 2. Solution
267 2.1. Event Streams
269 An event stream is a named entity on a publisher which exposes a
270 continuously updating set of event records. Each event stream is
271 available for subscription. It is out of the scope of this document
272 to identify a) how streams are defined, b) how event records are
273 defined/generated, and c) how event records are assigned to streams.
275 There is only one reserved event stream within this document:
276 NETCONF. The NETCONF event stream contains all NETCONF XML event
277 record information supported by the publisher, except for where it
278 has been explicitly indicated that this the event record MUST be
279 excluded from the NETCONF stream. The NETCONF stream will include
280 individual YANG notifications as per [RFC7950] section 7.16. Each of
281 these YANG notifications will be treated a distinct event record.
282 Beyond the NETCONF stream, implementations are free to add additional
283 event streams.
285 As event records are created by a system, they may be assigned to one
286 or more streams. The event record is distributed to subscription's
287 receiver(s) where: (1) a subscription includes the identified stream,
288 and (2) subscription filtering does not exclude the event record from
289 that receiver.
291 If access control permissions are in use to secure publisher content,
292 then for event records to be sent to a receiver, that receiver MUST
293 be allowed access to all the event records on the stream. If
294 subscriber permissions change during the lifecycle of a subscription,
295 then the subscription MUST be continued or terminated accordingly.
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 it 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.
348 .-------.
349 | start |
350 '-------'
351 |
352 establish-subscription
353 |
354 | .------modify-subscription-------.
355 v v '
356 .-----------. .-----------.
357 .--------. | receiver |-subscription-suspended->| receiver |
358 modify- '| active | | suspended |
359 subscription | |<--subscription-resumed--| |
360 ---------->'-----------' '-----------'
361 | |
362 delete/kill-subscription delete/kill-
363 | subscription
364 v |
365 .-------. |
366 | end |<-------------------------------'
367 '-------'
369 Dynamic subscription state
371 Of interest in this state machine are the following:
373 o Successful establish or modify RPCs put the subscription into an
374 active state.
376 o Failed modify RPCs will leave the subscription in its previous
377 state, with no visible change to any streaming updates.
379 o A delete or kill RPC will end the subscription.
381 o Suspend and resume state changes are driven by internal process
382 and prioritization. There are no direct controls over suspend and
383 resume other than modifying a subscription
385 2.4.2. Establishing a Subscription
387 The "establish-subscription" operation allows a subscriber to request
388 the creation of a subscription via RPC. It MUST be possible to
389 support multiple establish subscription RPC requests made within the
390 same transport session.
392 The input parameters of the operation are:
394 o A stream name which identifies the targeted stream of events
395 against which the subscription is applied.
397 o A stream filter which may reduce the set of event records pushed.
399 o An optional encoding for the event records pushed. Note: If no
400 encoding is included, the encoding of the RPC MUST be used.
402 o An optional stop time for the subscription. If no stop-time is
403 present, notification messages will continue to be sent until the
404 subscription is terminated.
406 o An optional start time which indicates that this subscription is
407 requesting a replay of previously generated information from the
408 event stream. For more on replay, see Section 2.4.2.1
410 If the publisher can satisfy the "establish-subscription" request, it
411 provides an identifier for the subscription, and immediately starts
412 streaming notification messages. If the subscriber has no
413 authorization to establish the subscription, transport protocol
414 specific replies are used to indicate an authorization error. If an
415 RPC request is properly framed, but publisher cannot satisfy the
416 "establish-subscription" request, the publisher MUST send a negative
417 "subscription-result" element describing the reason for the failure.
418 Optionally, the "subscription-result" MAY be accompanied by one or
419 more hints on alternative inputs which would have resulted in an
420 accepted subscription.
422 "establish-subscription" requests MUST fail if a filter with invalid
423 or unsupportable syntax is provided, or if a non-existent stream is
424 referenced.
426 +---x establish-subscription
427 +---w input
428 | +---w encoding? encoding
429 | +---w (target)
430 | | +--:(stream)
431 | | +---w (stream-filter)?
432 | | | +--:(by-reference)
433 | | | | +---w stream-filter-ref stream-filter-ref
434 | | | +--:(within-subscription)
435 | | | +---w (filter-spec)?
436 | | | +--:(stream-subtree-filter)
437 | | | | +---w stream-subtree-filter? {subtree}?
438 | | | +--:(stream-xpath-filter)
439 | | | +---w stream-xpath-filter?
440 | | | yang:xpath1.0 {xpath}?
441 | | +---w stream? stream-ref
442 | | +---w replay-start-time? yang:date-and-time {replay}?
443 | +---w stop-time? yang:date-and-time
444 | +---w dscp? inet:dscp {qos}?
445 | +---w weighting? uint8 {qos}?
446 | +---w dependency? sn:subscription-id {qos}?
447 +--ro output
448 +--ro subscription-result subscription-result
449 +--ro (result)?
450 +--:(no-success)
451 | +--ro filter-failure? string
452 | +--ro replay-start-time-hint? yang:date-and-time
453 +--:(success)
454 +--ro identifier subscription-id
456 Figure 1: establish-subscription RPC
458 2.4.2.1. Replay Subscription
460 Replay provides the ability to establish a subscription which is also
461 capable of passing recently generated event records. In other words,
462 as the subscription initializes itself, it sends any previously
463 generated content from within target event stream which meets the
464 filter and timeframe criteria. These historical event records would
465 then be followed by event records generated after the subscription
466 has been established. All event records will be delivered in the
467 order generated.
469 Replay is an optional feature which is dependent on an event stream
470 supporting some form of logging. Replay puts no restrictions on the
471 size or form of the log, or where it resides within the device.
473 The inclusion of a replay-start-time within an "establish-
474 subscription" RPC indicates a replay request. If the "replay-start-
475 time" contains a value that is earlier than content stored within the
476 publisher's replay buffer, then the subscription MUST be rejected,
477 and the leaf "replay-start-time-hint" MUST be set in the reply.
479 If a "stop-time" parameter is included, it MAY also be earlier than
480 the current time and MUST be later than the "replay-start-time". The
481 publisher MUST NOT accept a "replay-start-time" for a future time.
483 If the "replay-start-time" is later than any information stored in
484 the replay buffer, then the publisher MUST send a "replay-completed"
485 notification immediately after the "subscription-started"
486 notification.
488 If a stream supports replay, the "replay-support" leaf is present in
489 the "/streams/stream" list entry for the stream. An event stream
490 that does support replay is not expected to have an unlimited supply
491 of saved notifications available to accommodate any given replay
492 request. To assess the availability of replay, subscribers can
493 perform a get on "replay-log-creation-time" and "replay-log-aged-
494 time". See Figure 8 for the tree describing these elements. The
495 actual size of the replay log at any given time is a publisher
496 specific matter. Control parameters for the replay log are outside
497 the scope of this document.
499 2.4.3. Modifying a Subscription
501 The "modify-subscription" operation permits changing the terms of an
502 existing dynamic subscription previously established on that
503 transport session via "establish-subscription". Dynamic
504 subscriptions can be modified one or multiple times. If the
505 publisher accepts the requested modifications, it replies with "ok"
506 in the "subscription-result", then immediately starts sending event
507 records based on the new terms. If the publisher rejects the
508 request, the subscription remains as prior to the request. That is,
509 the request has no impact whatsoever. The contents of a such a
510 rejected modification MAY include one or more hints on alternative
511 inputs which would have resulted in a successfully modified
512 subscription.
514 If the publisher accepts the requested modifications on a currently
515 suspended subscription, the subscription will immediately be resumed
516 (i.e., the modified subscription is returned to an active status.)
517 The publisher MAY immediately suspend this newly modified
518 subscription through the "subscription-suspended" notification before
519 any event records are sent.
521 +---x modify-subscription
522 +---w input
523 | +---w identifier? subscription-id
524 | +---w (target)
525 | | +--:(stream)
526 | | +---w (stream-filter)?
527 | | +--:(by-reference)
528 | | | +---w stream-filter-ref stream-filter-ref
529 | | +--:(within-subscription)
530 | | +---w (filter-spec)?
531 | | +--:(stream-subtree-filter)
532 | | | +---w stream-subtree-filter? {subtree}?
533 | | +--:(stream-xpath-filter)
534 | | +---w stream-xpath-filter?
535 | | yang:xpath1.0 {xpath}?
536 | +---w stop-time? yang:date-and-time
537 +--ro output
538 +--ro subscription-result subscription-result
539 +--ro (result)?
540 +--:(no-success)
541 +--ro filter-failure? string
543 Figure 2: modify-subscription RPC
545 Dynamic subscriptions established via RPC can only be modified via
546 RPC using the same transport session used to establish that
547 subscription. Subscriptions created by configuration operations
548 cannot be modified via this RPC.
550 2.4.4. Deleting a Subscription
552 The "delete-subscription" operation permits canceling an existing
553 subscription previously established on that transport session. If
554 the publisher accepts the request, and the publisher has indicated
555 this success via an "ok" in the "subscription-result", the publisher
556 MUST NOT send any more notification messages for this subscription.
557 If the publisher rejects the request, the request has no impact
558 whatsoever on any subscription.
560 +---x delete-subscription
561 +---w input
562 | +---w identifier subscription-id
563 +--ro output
564 +--ro subscription-result subscription-result
566 Figure 3: delete-subscription RPC
568 Dynamic subscriptions can only be deleted via this RPC using the same
569 transport session previously used for subscription establishment.
570 Configured subscriptions cannot be deleted using RPCs.
572 2.4.5. Killing a Subscription
574 The "kill-subscription" operation permits an operator to end a
575 dynamic subscription which is not associated with the transport
576 session used for the RPC. This operation MUST be secured so that
577 only connections with sufficiently privileged access rights are able
578 to invoke this RPC. A publisher MUST terminate any dynamic
579 subscription identified by RPC request. An operator may find
580 subscription identifiers which may be used with "kill-subscription"
581 by searching for the IP address of a receiver within
582 "subscriptions\subscription\receivers\receiver\address".
584 Configured subscriptions cannot be killed using this RPC. Instead,
585 configured subscriptions are deleted as part of regular configuration
586 operations. Publishers MUST reject any RPC attempt to kill a
587 configured subscription.
589 The tree structure of "kill-subscription" is almost identical to
590 "delete-subscription", with only the name of the RPC changing.
592 2.5. Configured Subscriptions
594 A configured subscription is a subscription installed via a
595 configuration interface. Configured subscriptions may be modified by
596 any configuration client with the proper permissions. Subscriptions
597 can be modified or terminated via the configuration interface at any
598 point of their lifetime.
600 Configured subscriptions have several characteristics distinguishing
601 them from dynamic subscriptions:
603 o persistence across reboots,
605 o persistence even when transport is unavailable, and
607 o an ability to send notification messages to more than one receiver
608 (note that the publisher does not provide information to a
609 receiver about other receivers.)
611 Supporting configured subscriptions is optional and advertised using
612 the "configured" feature.
614 In addition to subscription parameters available to dynamic
615 subscriptions as described in Section 2.4.2, the following additional
616 parameters are also available to configured subscriptions:
618 o One or more receiver IP addresses (and corresponding ports)
619 intended as the destination for notification messages.
621 o Optional parameters to identify an egress interface, a host IP
622 address, a VRF (as defined by the network instance name within
623 [I-D.draft-ietf-rtgwg-ni-model]), or an IP address plus VRF out of
624 which notification messages are to be pushed from the publisher.
625 Where any of this info is not explicitly included, or where just
626 the VRF is provided, notification messages MUST egress the
627 publisher's default interface towards that receiver.
629 2.5.1. Configured Subscription State Model
631 Below is the state machine for a configured subscription. The
632 creation or modification of a configured subscription initiates a
633 publisher evaluation to determine if the subscription is valid or
634 invalid. The publisher uses its own criteria in making this
635 determination. If valid, the subscription becomes operational.
637 .-------.
638 | start |-.
639 '-------' |
640 create .---modify-----.----------------------------------.
641 | | | |
642 V V .-------. .-----. .---------.
643 .----[evaluate]--no--->|invalid|-delete->| end |<-delete-|concluded|
644 | '-------' '-----' '---------'
645 |----[evaluate]--no-. ^ ^ ^
646 | ^ | | | |
647 yes | '->unsupportable delete stop-time
648 | modify (subscription- (subscription- (subscription-
649 | | terminated) terminated) concluded)
650 | | | | |
651 | .---------------------------------------------------------------.
652 '-->| valid |
653 '---------------------------------------------------------------'
655 Configured subscription status.
657 A valid subscription may become invalid on one of two ways. First,
658 it may be modified in a way which fails a re-evaluation. Second, the
659 publisher itself might itself determine that the subscription in no
660 longer supportable. In either case, a "subscription-terminated"
661 notification is sent to any active or suspended receivers. A valid
662 subscription may also transtion to a concluded status if a configured
663 stop time has been reached. In this case, a "subscription-concluded"
664 is sent to any active or suspended receivers.
666 During any times a subscription is considered valid, a publisher will
667 attempt to connect with all configured receivers and deliver
668 notification messages. Below is the state machine for each receiver
669 of a configured subscription. This receiver state machine itself is
670 fully contained within the state machine of the configured
671 subscription, and is only relevant when the configured subscription
672 itself is determined to be valid.
674 .----------------------------------------------------------------.
675 | valid |
676 | .----------. .--------. |
677 | | receiver |------------------timeout->|receiver| |
678 | |connecting|<------------------reset---|timeout | |
679 | | |<-transport---. '--------' |
680 | '----------' loss,reset | |
681 | | | | |
682 | (subscription | | |
683 | started) .--------. | .---------. |
684 | '----->| | '----------------------| | |
685 | |receiver|-(subscription-suspended)-->|receiver | |
686 |(subscription-| active | |suspended| |
687 | modified) | |<-(subscription-resumed,----| | |
688 | '---->'--------' subscription-modified) '---------' |
689 '----------------------------------------------------------------'
691 Configured receiver state
693 When a subscription first becomes valid, the operational status of
694 each receiver is initialized to connecting. Individual are receivers
695 are moved to an active status when a "subscription-started" state
696 change notification is successfully passed to that receiver.
697 Configured receivers remain active if transport connectivity is not
698 lost, and event records are not being dropped due to a publisher
699 buffer overflow. A configured subscription's receiver MUST be moved
700 to connecting if transport connectivity is lost, or if the receiver
701 is reset via configuration operations.
703 A configured subscription's receiver MUST be moved to a suspended
704 state if there is transport connectivity between the publisher and
705 receiver, but notification messages are not being generated for that
706 receiver. A configured subscription receiver MUST be returned to an
707 active state from the suspended state when notification messages are
708 again being generated and a receiver has successfully been sent a
709 "subscription-resumed" or a "subscription-modified".
711 Modification of a configured subscription is possible at any time. A
712 "subscription-modified" state change notification will be sent to all
713 active receivers, immediately followed by notification messages
714 conforming to the new parameters. Suspended receivers will also be
715 informed of the modification. However this notification will await
716 the end of the suspension for that receiver.
718 The mechanisms described above is mirrored in the RPCs and YANG
719 notifications within the document. It should be noted that these
720 RPCs and YANG notifications have been designed to be extensible and
721 allow subscriptions into targets other than event streams.
722 [I-D.ietf-netconf-yang-push] provides an example of such an
723 extension.
725 2.5.2. Creating a Configured Subscription
727 Configured subscriptions are established using configuration
728 operations against the top-level subtree "subscription-config".
729 There are two key differences between the new RPCs defined in this
730 document and configuration operations for subscription creation.
731 Firstly, configuration operations install a subscription without
732 question, while the RPCs are designed to the support negotiation and
733 rejection of requests. Secondly, while the RPCs mandate that the
734 subscriber establishing the subscription is the only receiver of the
735 notification messages, configuration operations permit specifying
736 receivers independent of any tracked subscriber. Because there is no
737 explicit association with an existing transport session,
738 configuration operations require additional parameters beyond those
739 of dynamic subscriptions to indicate receivers, and possibly whether
740 the notification messages need to come from a specific egress
741 interface on the publisher.
743 After a subscription is successfully created, the publisher
744 immediately sends a "subscription-started" state change notification
745 to each receiver. It is quite possible that upon configuration,
746 reboot, or even steady-state operations, a transport session may not
747 be currently available to the receiver. In this case, when there is
748 something to transport for an active subscription, transport specific
749 call-home operations will be used to establish the connection. When
750 transport connectivity is available, notification messages may then
751 be pushed.
753 With active configured subscriptions, it is allowable to buffer event
754 records even after a "subscription-started" has been sent. However
755 if events are lost (rather than just delayed) due to replay buffer
756 overflow, a new "subscription-started" must be sent. This new
757 "subscription-started" indicates an event record discontinuity.
759 To see an example at subscription creation using configuration
760 operations over NETCONF, see Appendix A of
761 [I-D.draft-ietf-netconf-netconf-event-notifications].
763 Note that is possible to configure replay on a configured
764 subscription. This capability is to allow a configured subscription
765 to exist on a system so that event records generated during boot can
766 be buffered and pushed as soon as the transport session is
767 established.
769 2.5.3. Modifying a Configured Subscription
771 Configured subscriptions can be modified using configuration
772 operations against the top-level subtree "subscription-config".
774 If the modification involves adding receivers, added receivers are
775 placed in the "connecting" state. If a receiver is removed, the
776 state change notification "subscription-terminated" is sent to that
777 receiver if that receiver is "active" or "suspended" .
779 If the modification involved changing the policies for the
780 subscription, the publisher sends to currently active receivers a
781 "subscription-modified" notification. For any suspended receivers, a
782 "subscription-modified" notification will be delayed until the
783 receiver is resumed. (Note: in this case, the "subscription-
784 modified" notification informs the receiver that the subscription has
785 been resumed, so no additional "subscription-resumed" need be sent.)
787 2.5.4. Deleting a Configured Subscription
789 Subscriptions can be deleted using configuration operations against
790 the top-level subtree "subscription-config".
792 Immediately after a subscription is successfully deleted, the
793 publisher sends to all receivers of that subscription a state change
794 notification stating the subscription has ended (i.e., "subscription-
795 terminated").
797 2.5.5. Resetting a Configured Receiver
799 It is possible that a configured subscription to a receiver needs to
800 be reset. This re-initialization may be useful in cases where a
801 publisher has timed out trying to reach a receiver. When such a
802 reset occurs, a transport session will be initiated if necessary, and
803 a new "subscription-started" notification will be sent.
805 2.6. Event Record Delivery
807 Whether dynamic or configured, once a subscription has been set up,
808 the publisher streams event records via notification messages per the
809 terms of the subscription. For dynamic subscriptions set up via RPC
810 operations, notification messages are sent over the session used to
811 establish the subscription. For configured subscriptions,
812 notification messages are sent over the connections specified by the
813 transport, plus receiver IP address and port configured.
815 A notification message is sent to a receiver when an event record is
816 able to traverse the specified filter criteria. This notification
817 message MUST be encoded as one-way notification element of [RFC5277],
818 Section 4. The following example within [RFC7950] section 7.16.3 is
819 an example of a compliant message:
821
823 2007-09-01T10:00:00Z
824
825 so-1/2/3.0
826 up
827 down
828
829
831 Figure 4: subscribed notification message
833 This [RFC5277] section 4 one-way operation has the drawback of not
834 including useful header information such as a subscription
835 identifier. When using this mechanism, it is left up to
836 implementations or augmentations to this document to determine which
837 event records belong to which subscription.
839 These drawbacks, along with other useful common headers and the
840 ability to bundle multiple event records together is being explored
841 within [I.D.draft-ietf-netconf-notification-messages]. When the
842 notification-messages is supported, this document will be updated to
843 indicate support.
845 2.7. Subscription State Notifications
847 In addition to subscribed event records, a publisher will send
848 subscription state notifications to indicate to receivers that an
849 event related to the subscription management has occurred.
851 Subscription state notifications are unlike other notifications which
852 might be found in the event stream. They cannot be filtered out, and
853 they are delivered only to directly impacted receiver(s) of a
854 subscription. The identification of subscription state notifications
855 is easy to separate from other notification messages through the use
856 of the YANG extension "subscription-state-notif". This extension
857 tags a notification as subscription state notification.
859 The complete set of subscription state notifications is described in
860 the following subsections.
862 2.7.1. subscription-started
864 This notification indicates that a configured subscription has
865 started, and event records may be sent. Included in this state
866 change notification are all the parameters of the subscription,
867 except for the receiver(s) addressing information and origin
868 information indicating where notification messages will egress the
869 publisher. Note that if a referenced filter from the "filters"
870 container has been used within the subscription, the notification
871 will include the contents of that referenced under the "within-
872 subscription" subtree.
874 Note that for dynamic subscriptions, no "subscription-started"
875 notifications are ever sent.
877 +---n subscription-started {configured}?
878 +--ro identifier subscription-id
879 +--ro protocol transport {configured}?
880 +--ro encoding encoding
881 +--ro (target)
882 | +--:(stream)
883 | +--ro (stream-filter)?
884 | | +--:(by-reference)
885 | | | +--ro stream-filter-ref stream-filter-ref
886 | | +--:(within-subscription)
887 | | +--ro (filter-spec)?
888 | | +--:(stream-subtree-filter)
889 | | | +--ro stream-subtree-filter? {subtree}?
890 | | +--:(stream-xpath-filter)
891 | | +--ro stream-xpath-filter? yang:xpath1.0 {xpath}?
892 | +--ro stream stream
893 | +--ro replay-start-time? yang:date-and-time {replay}?
894 +--ro stop-time? yang:date-and-time
895 +--ro dscp? inet:dscp {qos}?
896 +--ro weighting? uint8 {qos}?
897 +--ro dependency? sn:subscription-id {qos}?
899 Figure 5: subscription-started notification
901 2.7.2. subscription-modified
903 This notification indicates that a subscription has been modified by
904 configuration operations. The same parameters of "subscription-
905 started" are provided via this notification. As a result, the tree
906 structure of "subscription-modified" is almost identical to
907 "subscription-started", with only the name of the notification
908 changing.
910 A publisher most often sends this notification directly after the
911 modification of any configuration parameters impacting a configured
912 subscription. But it may also be sent at two other times.
914 o First, where a configured subscription has been modified during
915 the suspension of a receiver, the notification will be delayed
916 until the receiver's suspension is lifted. In this situation, the
917 notification indicates that the subscription has been both
918 modified and resumed.
920 o Second, for dynamic subscriptions, there is one and only one time
921 this notification may be sent. A "subscription-modified" state
922 change notifications MUST be sent if the contents of a filter
923 identified by a "stream-filter-ref" has changed.
925 2.7.3. subscription-terminated
927 This notification indicates that a subscription has been terminated
928 on the publisher. The state change notification includes the reason
929 for the termination.
931 The publisher MAY decide to terminate a subscription rather than
932 continuing to serve it. Such a decision may be made when a publisher
933 runs out of resources, an internal error occurs, or some other
934 reason. Publisher-driven terminations are always notified to all
935 receivers.
937 Subscribers themselves can terminate existing subscriptions
938 established via a "delete-subscription" RPC. In such cases, no
939 "subscription-terminated" state change notifications are sent.
940 However if a "kill-subscription" RPC is sent, or some other event
941 other than reaching the subscription's stop time results in the end
942 of a subscription, then this state change notification MUST be sent.
944 +---n subscription-terminated
945 +--ro identifier subscription-id
946 +--ro error-id subscription-errors
947 +--ro filter-failure? string
949 Figure 6: subscription-terminated notification
951 2.7.4. subscription-suspended
953 This notification indicates that a publisher has suspended the
954 sending of event records to a receiver, and also indicates the
955 possible loss of events. The state change notification includes the
956 reason for the suspension. No further notification will be sent
957 until the subscription resumes.
959 The tree structure of "subscription-suspended" is almost identical to
960 "subscription-terminated", with only the name of the notification
961 changing.
963 2.7.5. subscription-resumed
965 This indicates that a previously suspended subscription has been
966 resumed under the unmodified terms previously in place. Subscribed
967 event records generated after the generation of this state change
968 notification will be sent.
970 +---n subscription-resumed
971 +--ro identifier subscription-id
973 Figure 7: subscription-resumed notification
975 2.7.6. subscription-completed
977 This notification indicates that a subscription, which includes a
978 "stop-time", has successfully finished passing event records upon the
979 reaching of that time.
981 The tree structure of "subscription-completed" is almost identical to
982 "subscription-resumed", with only the name of the notification
983 changing.
985 2.7.7. replay-completed
987 This notification indicates that all of the event records prior to
988 the current time have been sent. This includes new event records
989 generated since the start of the subscription. This notification
990 MUST NOT be sent for any other reason.
992 If subscription contains no "stop-time", or has a "stop-time" which
993 has not been reached, then after the "replay-completed" notification
994 has been sent, additional event records will be sent in sequence as
995 they arise naturally on the publisher.
997 The tree structure of "replay-completed" is almost identical to
998 "subscription-resumed", with only the name of the notification
999 changing.
1001 2.8. Subscription Monitoring
1003 Container "subscriptions" in the YANG module contains the state of
1004 all known subscriptions. This includes subscriptions that were
1005 established (and have not yet been deleted) using RPCs, as well as
1006 subscriptions that have been configured as part of configuration.
1007 Using the "get" operation with NETCONF, or subscribing to this
1008 information via [I-D.ietf-netconf-yang-push] allows the status of
1009 subscriptions to be monitored.
1011 Each subscription is represented as a list element. The associated
1012 information includes an identifier for the subscription, receiver
1013 counter information, the status of the subscription, as well as the
1014 various subscription parameters that are in effect. The subscription
1015 status indicates the subscription's state with each receiver (e.g.,
1016 is currently active or suspended). Leaf "configured-subscription"
1017 indicates whether the subscription came into being via configuration
1018 or via RPC.
1020 Subscriptions that were established by RPC are removed from the list
1021 once they expire (reaching stop-time) or when they are terminated.
1022 Subscriptions that were established by configuration need to be
1023 deleted from the configuration by a configuration editing operation
1024 even if the stop time has been passed.
1026 2.9. Advertisement
1028 Publishers supporting this document MUST indicate support the YANG
1029 model "ietf-subscribed-notifications" within the YANG library of the
1030 publisher. In addition support for optional features: "encode-xml",
1031 "encode-json", "configured" "supports-vrf", and "replay" MUST also be
1032 indicated if supported.
1034 If a publisher supports this specification but not subscriptions via
1035 [RFC5277], the publisher MUST NOT advertise
1036 "urn:ietf:params:netconf:capability:notification:1.0". Even without
1037 this advertisement however, the publisher MUST support the one-way
1038 notification element of [RFC5277] Section 4.
1040 3. YANG Data Model Trees
1042 This section contains tree diagrams for top level YANG Data Node
1043 containers defined in Section 4. If you would rather see tree
1044 diagrams for Notifications, see Section 2.7. Or for the tree
1045 diagrams for the RPCs, see Section 2.4.
1047 3.1. Event Streams Container
1049 A publisher maintains a list of available event streams as
1050 operational data. This list contains both standardized and vendor-
1051 specific event streams. The list of event streams that are supported
1052 by the publisher and against which subscription is allowed may be
1053 acquired from the "streams" container within the YANG module.
1055 +--rw streams
1056 +--rw stream* [name]
1057 +--rw name stream
1058 +--rw description string
1059 +--rw replay-support? empty {replay}?
1060 +--rw replay-log-creation-time? yang:date-and-time {replay}?
1061 +--rw replay-log-aged-time? yang:date-and-time {replay}?
1063 Figure 8: Stream Container
1065 3.2. Event Stream Filters Container
1067 The "filters" container maintains a list of all subscription filters
1068 which persist outside the life-cycle of a single subscription. This
1069 enables pre-defined and validated filters which may be referenced and
1070 used by more than one subscription.
1072 +--rw filters
1073 +--rw stream-filter* [identifier]
1074 +--rw identifier filter-id
1075 +--rw (filter-spec)?
1076 +--:(stream-subtree-filter)
1077 | +--rw stream-subtree-filter? {subtree}?
1078 +--:(stream-xpath-filter)
1079 +--rw stream-xpath-filter? yang:xpath1.0 {xpath}?
1081 Figure 9: Filter Container
1083 3.3. Subscriptions Container
1085 The "subscriptions" container maintains a list of all subscriptions
1086 on a publisher, both configured and dynamic. It can be used to
1087 retrieve information about the subscriptions which a publisher is
1088 serving.
1090 +--ro subscriptions
1091 +--ro subscription* [identifier]
1092 +--ro identifier subscription-id
1093 +--ro configured-subscription-state? enumeration {configured}?
1094 +--ro purpose? string {configured}?
1095 +--ro protocol transport {configured}?
1096 +--ro encoding encoding
1097 +--ro (target)
1098 | +--:(stream)
1099 | +--ro (stream-filter)?
1100 | | +--:(by-reference)
1101 | | | +--ro stream-filter-ref stream-filter-ref
1102 | | +--:(within-subscription)
1103 | | +--ro (filter-spec)?
1104 | | +--:(stream-subtree-filter)
1105 | | | +--ro stream-subtree-filter? {subtree}?
1106 | | +--:(stream-xpath-filter)
1107 | | +--ro stream-xpath-filter?
1108 | | yang:xpath1.0 {xpath}?
1109 | +--ro stream? stream-ref
1110 | +--ro replay-start-time? yang:date-and-time {replay}?
1111 +--ro stop-time? yang:date-and-time
1112 +--ro dscp? inet:dscp {qos}?
1113 +--ro weighting? uint8 {qos}?
1114 +--ro dependency? sn:subscription-id {qos}?
1115 +--ro (notification-message-origin)?
1116 | +--:(interface-originated)
1117 | | +--ro source-interface? if:interface-ref
1118 | +--:(address-originated)
1119 | +--ro source-vrf? ->
1120 | /ni:network-instances/network-instance/name {supports-vrf}?
1121 | +--ro source-address? inet:ip-address-no-zone
1122 +--ro receivers
1123 +--ro receiver* [address port]
1124 +--ro address inet:host
1125 +--ro port inet:port-number
1126 +--ro pushed-notifications? yang:counter64
1127 +--ro excluded-notifications? yang:counter64
1128 +--ro status enumeration
1129 +---x reset
1130 +--ro output
1131 +--ro time yang:date-and-time
1133 3.4. Subscription-config Container
1135 "Subscription-config" container contains the configuration of
1136 configured subscriptions.
1138 +--rw subscription-config {configured}?
1139 +--rw subscription* [identifier]
1140 +--rw identifier subscription-id
1141 +--rw purpose? string
1142 +--rw protocol transport {configured}?
1143 +--rw encoding encoding
1144 +--rw (target)
1145 | +--:(stream)
1146 | +--rw (stream-filter)?
1147 | | +--:(by-reference)
1148 | | | +--rw stream-filter-ref stream-filter-ref
1149 | | +--:(within-subscription)
1150 | | +--rw (filter-spec)?
1151 | | +--:(stream-subtree-filter)
1152 | | | +--rw stream-subtree-filter? {subtree}?
1153 | | +--:(stream-xpath-filter)
1154 | | +--rw stream-xpath-filter? yang:xpath1.0 {xpath}?
1155 | +--rw stream? stream-filter-ref
1156 | +--rw replay-start-time? yang:date-and-time {replay}?
1157 +--rw stop-time? yang:date-and-time
1158 +--rw dscp? inet:dscp {qos}?
1159 +--rw weighting? uint8 {qos}?
1160 +--rw dependency? sn:subscription-id {qos}?
1161 +--rw (notification-message-origin)?
1162 | +--:(interface-originated)
1163 | | +--rw source-interface? if:interface-ref
1164 | +--:(address-originated)
1165 | +--rw source-vrf? ->
1166 | | /ni:network-instances/network-instance/name {supports-vrf}?
1167 | +--rw source-address? inet:ip-address-no-zone
1168 +--rw receivers
1169 +--rw receiver* [address port]
1170 +--rw address inet:host
1171 +--rw port inet:port-number
1173 4. Data Model
1175 file "ietf-subscribed-notifications.yang"
1176 module ietf-subscribed-notifications {
1177 yang-version 1.1;
1178 namespace
1179 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications";
1181 prefix sn;
1183 import ietf-yang-types {
1184 prefix yang;
1185 }
1186 import ietf-inet-types {
1187 prefix inet;
1188 }
1189 import ietf-interfaces {
1190 prefix if;
1191 }
1192 import ietf-network-instance {
1193 prefix ni;
1194 }
1196 organization "IETF";
1197 contact
1198 "WG Web:
1199 WG List:
1201 Editor: Alexander Clemm
1202
1204 Editor: Eric Voit
1205
1207 Editor: Alberto Gonzalez Prieto
1208
1210 Editor: Einar Nilsen-Nygaard
1211
1213 Editor: Ambika Prasad Tripathy
1214 ";
1216 description
1217 "Contains a YANG specification for subscribing to event records
1218 and receiving matching content within notification messages.";
1220 revision 2017-12-20 {
1221 description
1222 "Initial version";
1223 reference
1224 "draft-ietf-netconf-subscribed-notifications-08";
1225 }
1227 /*
1228 * FEATURES
1229 */
1231 feature encode-json {
1232 description
1233 "This feature indicates that JSON encoding of notification
1234 messages is supported.";
1235 }
1237 feature encode-xml {
1238 description
1239 "This feature indicates that XML encoding of notification
1240 messages is supported.";
1241 }
1243 feature configured {
1244 description
1245 "This feature indicates that configuration of subscription is
1246 supported.";
1247 }
1249 feature replay {
1250 description
1251 "This feature indicates that historical event record replay is
1252 supported. With replay, it is possible for past event records to
1253 be streamed in chronological order.";
1254 }
1256 feature xpath {
1257 description
1258 "This feature indicates support for xpath filtering.";
1259 reference "http://www.w3.org/TR/1999/REC-xpath-19991116";
1260 }
1262 feature subtree {
1263 description
1264 "This feature indicates support for YANG subtree filtering.";
1265 reference "RFC 6241, Section 6.";
1266 }
1268 feature supports-vrf {
1269 description
1270 "This feature indicates a publisher supports VRF configuration
1271 for configured subscriptions. VRF support for dynamic
1272 subscriptions does not require this feature.";
1273 reference "draft-ietf-rtgwg-ni-model";
1274 }
1276 feature qos {
1277 description
1278 "This feature indicates a publisher supports one or more optional
1279 Quality of Service (QoS) features to differentiate update record
1280 treatment between publisher and receiver.";
1281 }
1283 /*
1284 * EXTENSIONS
1285 */
1287 extension subscription-state-notification {
1288 description
1289 "This statement applies only to notifications. It indicates that
1290 the notification is a subscription state notification. Therefore
1291 it does not participate in a regular event stream and does not
1292 need to be specifically subscribed to in order to be received.
1293 This statement can only occur as a substatement to the YANG
1294 'notification' statement.";
1295 }
1297 /*
1298 * IDENTITIES
1299 */
1301 /* Identities for subscription results */
1302 identity subscription-result {
1303 description
1304 "Base identity for RPC responses and State Change Notifications
1305 providing information on the creation, modification, deletion of
1306 subscriptions.";
1307 }
1309 identity ok {
1310 base subscription-result;
1311 description
1312 "OK - RPC was successful and was performed as requested.";
1313 }
1315 identity error {
1316 base subscription-result;
1317 description
1318 "Problem with subscription. Base identity for error return
1319 codes for RPCs and State Change Notifications.";
1320 }
1322 /* Identities for subscription errors */
1324 identity suspension-timeout {
1325 base error;
1326 description
1327 "Termination of previously suspended subscription. The publisher
1328 has eliminated the subscription as it exceeded a time limit for
1329 suspension.";
1330 }
1332 identity stream-unavailable {
1333 base error;
1334 description
1335 "Stream does not exist or is not available to the receiver.";
1336 }
1338 identity encoding-unavailable {
1339 base error;
1340 description
1341 "Encoding not supported";
1342 }
1344 identity replay-unsupported {
1345 base error;
1346 description
1347 "Replay cannot be performed for this subscription. The publisher
1348 does not provide the requested historic information via replay.";
1349 }
1351 identity history-unavailable {
1352 base error;
1353 description
1354 "Replay request too far into the past. The publisher does store
1355 historic information for all parts of requested subscription, but
1356 not back to the requested timestamp.";
1357 }
1359 identity filter-unavailable {
1360 base error;
1361 description
1362 "Referenced filter does not exist";
1363 }
1365 identity filter-type-unsupported {
1366 base error;
1367 description
1368 "Publisher does not support filters constructed using this
1369 filtering technology syntax.";
1370 }
1372 identity filter-unsupported {
1373 base error;
1374 description
1375 "Failure can be from a syntax error, or a syntax too complex to be
1376 processed by the platform. The supplemental info should include
1377 the invalid part of the filter.";
1378 }
1380 identity namespace-unavailable {
1381 base error;
1382 description
1383 "Referenced namespace doesn't exist or is unavailable
1384 to the receiver.";
1385 }
1387 identity no-such-subscription {
1388 base error;
1389 description
1390 "Referenced subscription doesn't exist. This may be as a result of
1391 a non-existent subscription ID, an ID which belongs to another
1392 subscriber, or an ID for acceptable subscription which has been
1393 statically configured.";
1394 }
1396 identity insufficient-resources {
1397 base error;
1398 description
1399 "The publisher has insufficient resources to support the
1400 subscription as requested by an RPC.";
1401 }
1403 identity unsupportable-volume {
1404 base error;
1405 description
1406 "The publisher cannot support the volume of information intended
1407 to be sent for an existing subscription.";
1408 }
1410 identity error-no-such-option {
1411 base error;
1412 description
1413 "A requested parameter setting is not supported.";
1414 }
1416 identity dscp-unavailable {
1417 base sn:error;
1418 description
1419 "Requested DSCP marking not allocatable.";
1420 }
1421 identity qos-unsupported {
1422 base sn:error;
1423 description
1424 "An included subscription QoS parameter or parameter value is not
1425 supported by the publisher.";
1426 }
1428 /* Identities for encodings */
1429 identity encodings {
1430 description
1431 "Base identity to represent data encodings";
1432 }
1434 identity encode-xml {
1435 base encodings;
1436 if-feature "encode-xml";
1437 description
1438 "Encode data using XML";
1439 }
1441 identity encode-json {
1442 base encodings;
1443 if-feature "encode-json";
1444 description
1445 "Encode data using JSON";
1446 }
1448 /* Identities for transports */
1449 identity transport {
1450 description
1451 "An identity that represents a the underlying mechanism for
1452 passing notification messages.";
1453 }
1455 identity netconf {
1456 base transport;
1457 description
1458 "Netconf is used a transport for notification messages and state
1459 change notifications.";
1460 reference "draft-ietf-netconf-netconf-event-notifications";
1461 }
1463 identity http2 {
1464 base transport;
1465 description
1466 "HTTP2 is used a transport for notification messages and state
1467 change notifications.";
1468 reference "draft-ietf-netconf-restconf-notif-03, Sections 3.1.1" +
1469 "3.1.3";
1470 }
1472 identity http1.1 {
1473 base transport;
1474 description
1475 "HTTP1.1 is used a transport for notification messages and state
1476 change notifications.";
1477 reference "draft-ietf-netconf-restconf-notif-03, Section 3.1.2";
1478 }
1479 /*
1480 * TYPEDEFs
1481 */
1483 typedef subscription-id {
1484 type uint32;
1485 description
1486 "A type for subscription identifiers.";
1487 }
1489 typedef filter-id {
1490 type string;
1491 description
1492 "A type to identify filters which can be associated with a
1493 subscription.";
1494 }
1496 typedef subscription-result {
1497 type identityref {
1498 base subscription-result;
1499 }
1500 description
1501 "The result of a subscription operation";
1502 }
1504 typedef subscription-errors {
1505 type identityref {
1506 base error;
1507 }
1508 description
1509 "The reason for the failure of an RPC request or the sending
1510 of a subscription suspension or termination state change
1511 notification";
1512 }
1514 typedef encoding {
1515 type identityref {
1516 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";
1543 }
1544 description
1545 "This type is used to reference a configured stream filter.";
1546 }
1548 /*
1549 * GROUPINGS
1550 */
1552 grouping stream-filter-elements {
1553 description
1554 "This grouping defines the base for filters applied to event
1555 streams.";
1556 choice filter-spec {
1557 description
1558 "The content filter specification for this request.";
1559 anydata stream-subtree-filter {
1560 if-feature "subtree";
1561 description
1562 "Event stream evaluation criteria encoded in the syntax of a
1563 subtree filter as defined in RFC 6241, Section 6.
1565 The subtree filter is applied to the representation of
1566 individual, delineated event records as contained within the
1567 event stream. For example, if the notification message
1568 contains an instance of a notification defined in YANG, then
1569 the top-level element is the name of the YANG notification.
1571 If the subtree filter returns a non-empty node set, the filter
1572 matches the event record, and the it is included in the
1573 notification message sent to the receivers.";
1574 reference "RFC 6241, Section 6.";
1575 }
1576 leaf stream-xpath-filter {
1577 if-feature "xpath";
1578 type yang:xpath1.0;
1579 description
1580 "Event stream evaluation criteria encoded in the syntax of
1581 an XPath 1.0 expression.
1583 The XPath expression is evaluated on the representation of
1584 individual, delineated event records as contained within
1585 the event stream. For example, if the notification message
1586 contains an instance of a notification defined in YANG,
1587 then the top-level element is the name of the YANG
1588 notification, and the root node has this top-level element
1589 as the only child.
1591 The result of the XPath expression is converted to a
1592 boolean value using the standard XPath 1.0 rules. If the
1593 boolean value is 'true', the filter matches the the event
1594 record, and the it is included in the notification message
1595 sent to the receivers.
1597 The expression is evaluated in the following XPath context:
1599 o The set of namespace declarations are those in scope on
1600 the 'xpath-filter' leaf element
1602 o The set of variable bindings is empty.
1604 o The function library is the core function library, and
1605 the XPath functions defined in section 10 in RFC 7950.
1607 o The context node is the root node.";
1608 reference
1609 "http://www.w3.org/TR/1999/REC-xpath-19991116
1610 RFC 7950, Section 10.";
1612 }
1613 }
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";
1640 reference
1641 "RFC-7540, section 5.3.2";
1642 }
1643 leaf dependency {
1644 if-feature "qos";
1645 type sn:subscription-id;
1646 description
1647 "Provides the Subscription ID of a parent subscription which
1648 has absolute priority should that parent have push updates
1649 ready to egress the publisher. In other words, there should be
1650 no streaming of objects from the current subscription if
1651 the parent has something ready to push.";
1652 reference
1653 "RFC-7540, section 5.3.1";
1654 }
1655 }
1657 grouping subscription-policy-modifiable {
1658 description
1659 "This grouping describes all objects which may be changed
1660 in a subscription via an RPC.";
1661 choice target {
1662 mandatory true;
1663 description
1664 "Identifies the source of information against which a
1665 subscription is being applied, as well as specifics on the
1666 subset of information desired from that source. This choice
1667 exists so that additional filter types can be added via
1668 augmentation.";
1669 case stream {
1670 choice stream-filter {
1671 description
1672 "An event stream filter can be applied to a subscription.
1673 That filter will come either referenced from a global list,
1674 or be provided within the subscription itself.";
1675 case by-reference {
1676 description
1677 "Apply a filter that has been configured separately.";
1678 leaf stream-filter-ref {
1679 type stream-filter-ref;
1680 mandatory true;
1681 description
1682 "References an existing stream-filter which is to
1683 be applied to stream for the subscription.";
1684 }
1685 }
1686 case within-subscription {
1687 description
1688 "Local definition allows a filter to have the same
1689 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 be passed over the RPCs defined in this model.";
1712 leaf encoding {
1713 type encoding;
1714 mandatory true;
1715 description
1716 "The type of encoding for the subscribed data.";
1717 }
1718 uses subscription-policy-modifiable {
1719 augment target/stream {
1720 description
1721 "Adds additional objects which must be set just by RPC.";
1722 leaf stream {
1723 type stream-ref {
1724 require-instance false;
1725 }
1726 description
1727 "Indicates a stream of event records against which to apply
1728 a stream filter. Require-instance is false in case a
1729 configured subscription reference a stream which is
1730 dynamically generated and only available at runtime.";
1731 }
1732 leaf replay-start-time {
1733 if-feature "replay";
1734 type yang:date-and-time;
1735 description
1736 "Used to trigger the replay feature and indicate that the
1737 replay should start at the time specified. If
1738 replay-start-time is not present, this is not a replay
1739 subscription and event record push should start immediately.
1740 It is never valid to specify start times that are later than
1741 or equal to the current time.";
1742 }
1743 }
1744 }
1745 uses update-qos;
1746 }
1748 grouping subscription-policy {
1749 description
1750 "This grouping describes the full set of policy information
1751 concerning both dynamic and configured subscriptions, except for
1752 configured receivers.";
1753 leaf protocol {
1754 if-feature "configured";
1755 type transport;
1756 mandatory true;
1757 description
1758 "This leaf specifies the transport protocol used to deliver
1759 messages destined to all receivers of a subscription.";
1761 }
1762 uses subscription-policy-dynamic;
1763 }
1765 grouping notification-origin-info {
1766 description
1767 "Defines the sender source from which notification messages for a
1768 configured subscription are sent.";
1769 choice notification-message-origin {
1770 description
1771 "Identifies the egress interface on the Publisher from which
1772 notification messages are to be sent.";
1773 case interface-originated {
1774 description
1775 "When notification messages to egress a specific, designated
1776 interface on the Publisher.";
1777 leaf source-interface {
1778 type if:interface-ref;
1779 description
1780 "References the interface for notification messages.";
1781 }
1782 }
1783 case address-originated {
1784 description
1785 "When notification messages are to depart from a publisher
1786 using specfic originating address and/or routing context
1787 information.";
1788 leaf source-vrf {
1789 if-feature "supports-vrf";
1790 type leafref {
1791 path "/ni:network-instances/ni:network-instance/ni:name";
1792 }
1793 description
1794 "VRF from which notification messages should egress a
1795 publisher.";
1796 }
1797 leaf source-address {
1798 type inet:ip-address-no-zone;
1799 description
1800 "The source address for the notification messages. If a
1801 source VRF exists, but this object doesn't, a publisher's
1802 default address for that VRF must be used.";
1803 }
1804 }
1805 }
1806 }
1808 grouping receiver-info {
1809 description
1810 "Defines where and how to get notification messages for a
1811 configured subscriptions to one or more targeted recipient. This
1812 includes specifying the destination addressing as well as a
1813 transport protocol acceptable to the receiver.";
1814 container receivers {
1815 description
1816 "Set of receivers in a subscription.";
1817 list receiver {
1818 key "address port";
1819 min-elements 1;
1820 description
1821 "A single host or multipoint address intended as a target
1822 for the notification messages of a subscription.";
1823 leaf address {
1824 type inet:host;
1825 description
1826 "Specifies the address for the traffic to reach a remote
1827 host. One of the following must be specified: an ipv4
1828 address, an ipv6 address, or a host name.";
1829 }
1830 leaf port {
1831 type inet:port-number;
1832 description
1833 "This leaf specifies the port number to use for messages
1834 destined for a receiver.";
1835 }
1836 }
1837 }
1838 }
1840 grouping error-identifier {
1841 description
1842 "A code passed back within an RPC response to describe why the RFC
1843 has failed, or within a state change notification to describe why
1844 the change has occurred.";
1845 leaf error-id {
1846 type subscription-errors;
1847 mandatory true;
1848 description
1849 "Identifies the subscription error condition.";
1850 }
1851 }
1853 grouping hints {
1854 description
1855 "Objects passed back within an RPC response to describe why the
1856 RFC has failed, or within a state change notification to
1857 describe why the change has occurred.";
1858 leaf filter-failure {
1859 type string;
1860 description
1861 "Information describing where and/or why a provided filter was
1862 unsupportable for a subscription.";
1863 }
1864 }
1866 grouping subscription-response-with-hints {
1867 description
1868 "Defines the output for the establish-subscription and
1869 modify-subscription RPCs.";
1870 leaf subscription-result {
1871 type subscription-result;
1872 mandatory true;
1873 description
1874 "Indicates whether subscription is operational, or if a problem
1875 was encountered.";
1876 }
1877 choice result {
1878 description
1879 "Depending on the subscription result, different data is
1880 returned.";
1881 case no-success {
1882 description
1883 "This case applies when a subscription request was not
1884 successful and no subscription was created (or modified) as a
1885 result. In this case, information MAY be returned that
1886 indicates suggested parameter settings that would have a
1887 high likelihood of succeeding in a subsequent establish-
1888 subscription or modify-subscription request.";
1889 uses hints;
1890 }
1891 }
1892 }
1894 /*
1895 * RPCs
1896 */
1898 rpc establish-subscription {
1899 description
1900 "This RPC allows a subscriber to create (and possibly negotiate)
1901 a subscription on its own behalf. If successful, the
1902 subscription remains in effect for the duration of the
1903 subscriber's association with the publisher, or until the
1904 subscription is terminated. In case an error (as indicated by
1905 subscription-result) is returned, the subscription is not
1906 created. In that case, the RPC reply MAY include suggested
1907 parameter settings that would have a higher likelihood of
1908 succeeding in a subsequent establish-subscription request.";
1909 input {
1910 uses subscription-policy-dynamic {
1911 refine "encoding" {
1912 mandatory false;
1913 description
1914 "The type of encoding for the subscribed data. If not
1915 included as part of the RPC, the encoding MUST be set by the
1916 publisher to be the encoding used by this RPC.";
1917 }
1918 }
1919 }
1920 output {
1921 uses subscription-response-with-hints {
1922 augment "result" {
1923 description
1924 "Allows information to be passed back as part of a
1925 successful subscription establishment.";
1926 case success {
1927 description
1928 "This case is used when the subscription request was
1929 successful.";
1930 leaf identifier {
1931 type subscription-id;
1932 mandatory true;
1933 description
1934 "Identifier used for this subscription.";
1935 }
1936 }
1937 }
1938 augment "result/no-success" {
1939 description
1940 "Contains establish RPC specific objects which can be
1941 returned as hints for future attempts.";
1942 leaf replay-start-time-hint {
1943 type yang:date-and-time;
1944 description
1945 "If a replay has been requested, but the requested replay
1946 time cannot be honored, this may provide a hint at an
1947 alternate time which may be supportable.";
1948 }
1949 }
1950 }
1951 }
1952 }
1953 rpc modify-subscription {
1954 description
1955 "This RPC allows a subscriber to modify a subscription that was
1956 previously created using establish-subscription. If successful,
1957 the changed subscription remains in effect for the duration of
1958 the subscriber's association with the publisher, or until the
1959 subscription is again modified or terminated. In case an error
1960 is returned (as indicated by subscription-result), the
1961 subscription is not modified and the original subscription
1962 parameters remain in effect. In that case, the rpc error
1963 response MAY include suggested parameter hints that would have
1964 a high likelihood of succeeding in a subsequent
1965 modify-subscription request. A successful modifiy-subscription
1966 will return a suspended subscription to an active state.";
1967 input {
1968 leaf identifier {
1969 type subscription-id;
1970 description
1971 "Identifier to use for this subscription.";
1972 }
1973 uses subscription-policy-modifiable;
1974 }
1975 output {
1976 uses subscription-response-with-hints;
1977 }
1978 }
1980 rpc delete-subscription {
1981 description
1982 "This RPC allows a subscriber to delete a subscription that
1983 was previously created from by that same subscriber using the
1984 establish-subscription RPC.";
1985 input {
1986 leaf identifier {
1987 type subscription-id;
1988 mandatory true;
1989 description
1990 "Identifier of the subscription that is to be deleted.
1991 Only subscriptions that were created using
1992 establish-subscription can be deleted via this RPC.";
1993 }
1994 }
1995 output {
1996 leaf subscription-result {
1997 type subscription-result;
1998 mandatory true;
1999 description
2000 "Indicates whether subscription has been deleted, or if a
2001 problem was encountered.";
2002 }
2003 }
2004 }
2006 rpc kill-subscription {
2007 description
2008 "This RPC allows an operator to delete a dynamic subscription
2009 without restrictions on the originating subscriber or underlying
2010 transport session.";
2011 input {
2012 leaf identifier {
2013 type subscription-id;
2014 mandatory true;
2015 description
2016 "Identifier of the subscription that is to be deleted. Only
2017 subscriptions that were created using establish-subscription
2018 can be deleted via this RPC.";
2019 }
2020 }
2021 output {
2022 leaf subscription-result {
2023 type subscription-result;
2024 mandatory true;
2025 description
2026 "Indicates whether subscription has been killed, or if a
2027 problem was encountered.";
2028 }
2029 }
2030 }
2032 /*
2033 * NOTIFICATIONS
2034 */
2036 notification replay-completed {
2037 sn:subscription-state-notification;
2038 if-feature "replay";
2039 description
2040 "This notification is sent to indicate that all of the replay
2041 notifications have been sent. It must not be sent for any other
2042 reason.";
2043 leaf identifier {
2044 type subscription-id;
2045 mandatory true;
2046 description
2047 "This references the affected subscription.";
2048 }
2050 }
2052 notification subscription-completed {
2053 sn:subscription-state-notification;
2054 description
2055 "This notification is sent to indicate that a subscription has
2056 finished passing event records.";
2057 leaf identifier {
2058 type subscription-id;
2059 mandatory true;
2060 description
2061 "This references the gracefully completed subscription.";
2062 }
2063 }
2065 notification subscription-started {
2066 sn:subscription-state-notification;
2067 if-feature "configured";
2068 description
2069 "This notification indicates that a subscription has started and
2070 notifications are beginning to be sent. This notification shall
2071 only be sent to receivers of a subscription; it does not
2072 constitute a general-purpose notification.";
2073 leaf identifier {
2074 type subscription-id;
2075 mandatory true;
2076 description
2077 "This references the affected subscription.";
2078 }
2079 uses subscription-policy {
2080 refine "target/stream/replay-start-time" {
2081 description
2082 "Indicates the time that a replay using for the streaming of
2083 buffered event records. This will be populated with the most
2084 recent of the following: replay-log-creation-time,
2085 replay-log-aged-time, replay-start-time, or the most recent
2086 publisher boot time.";
2087 }
2088 refine "target/stream/stream-filter/within-subscription" {
2089 description
2090 "Filter applied to the subscription. If the
2091 'stream-filter-ref' is populated, the filter within the
2092 subscription came from the 'filters' container. Otherwise it
2093 is populated in-line as part of the subscription.";
2094 }
2095 }
2096 }
2097 notification subscription-resumed {
2098 sn:subscription-state-notification;
2099 description
2100 "This notification indicates that a subscription that had
2101 previously been suspended has resumed. Notifications will once
2102 again be sent. In addition, a subscription-resumed indicates
2103 that no modification of parameters has occured since the last
2104 time event records have been sent.";
2105 leaf identifier {
2106 type subscription-id;
2107 mandatory true;
2108 description
2109 "This references the affected subscription.";
2110 }
2111 }
2113 notification subscription-modified {
2114 sn:subscription-state-notification;
2115 description
2116 "This notification indicates that a subscription has been
2117 modified. Notification messages sent from this point on will
2118 conform to the modified terms of the subscription. For
2119 completeness, this state change notification includes both
2120 modified and non-modified aspects of a subscription.";
2121 leaf identifier {
2122 type subscription-id;
2123 mandatory true;
2124 description
2125 "This references the affected subscription.";
2126 }
2127 uses subscription-policy {
2128 refine "target/stream/stream-filter/within-subscription" {
2129 description
2130 "Filter applied to the subscription. If the
2131 'stream-filter-ref' is populated, the filter within the
2132 subscription came from the 'filters' container. Otherwise it
2133 is populated in-line as part of the subscription.";
2134 }
2135 }
2136 }
2138 notification subscription-terminated {
2139 sn:subscription-state-notification;
2140 description
2141 "This notification indicates that a subscription has been
2142 terminated.";
2143 leaf identifier {
2144 type subscription-id;
2145 mandatory true;
2146 description
2147 "This references the affected subscription.";
2148 }
2149 uses error-identifier;
2150 uses hints;
2151 }
2153 notification subscription-suspended {
2154 sn:subscription-state-notification;
2155 description
2156 "This notification indicates that a suspension of the
2157 subscription by the publisher has occurred. No further
2158 notifications will be sent until the subscription resumes.
2159 This notification shall only be sent to receivers of a
2160 subscription; it does not constitute a general-purpose
2161 notification.";
2162 leaf identifier {
2163 type subscription-id;
2164 mandatory true;
2165 description
2166 "This references the affected subscription.";
2167 }
2168 uses error-identifier;
2169 uses hints;
2170 }
2172 /*
2173 * DATA NODES
2174 */
2176 container streams {
2177 description
2178 "This container contains information on the built-in streams
2179 provided by the publisher.";
2180 list stream {
2181 key "name";
2182 description
2183 "Identifies the built-in streams that are supported by the
2184 publisher.";
2185 leaf name {
2186 type string;
2187 description
2188 "A handle for a system-provided datastream made up of a
2189 sequential set of event records, each of which is
2190 characterized by its own domain and semantics.";
2191 }
2192 leaf description {
2193 type string;
2194 mandatory true;
2195 description
2196 "A description of the event stream, including such information
2197 as the type of event records that are available within this
2198 stream.";
2199 }
2200 leaf replay-support {
2201 if-feature "replay";
2202 type empty;
2203 description
2204 "Indicates that event record replay is available on this
2205 stream.";
2206 }
2207 leaf replay-log-creation-time {
2208 if-feature "replay";
2209 type yang:date-and-time;
2210 description
2211 "The timestamp of the creation of the log used to support the
2212 replay function on this stream. Note that this might be
2213 earlier then the earliest available information contained in
2214 the log. This object is updated if the log resets for some
2215 reason. This object MUST be present if replay is supported.";
2216 }
2217 leaf replay-log-aged-time {
2218 if-feature "replay";
2219 type yang:date-and-time;
2220 description
2221 "The timestamp of the last event record aged out of the log.
2222 This object MUST be present if replay is supported and any
2223 event record have been aged out of the log.";
2224 }
2225 }
2226 }
2228 container filters {
2229 description
2230 "This container contains a list of configurable filters
2231 that can be applied to subscriptions. This facilitates
2232 the reuse of complex filters once defined.";
2233 list stream-filter {
2234 key "identifier";
2235 description
2236 "A list of pre-positioned filters that can be applied to
2237 subscriptions.";
2238 leaf identifier {
2239 type filter-id;
2240 description
2241 "An identifier to differentiate between filters.";
2242 }
2243 uses stream-filter-elements;
2244 }
2245 }
2247 container subscription-config {
2248 if-feature "configured";
2249 description
2250 "Contains the list of subscriptions that are configured,
2251 as opposed to established via RPC or other means.";
2252 list subscription {
2253 key "identifier";
2254 description
2255 "The identity and specific parameters of a configured
2256 subscription.";
2257 leaf identifier {
2258 type subscription-id;
2259 description
2260 "Identifier to use for this subscription. Should only
2261 use the bottom half of the identifier's integer range.";
2262 }
2263 leaf purpose {
2264 type string;
2265 description
2266 "Open text allowing a configuring entity to embed the
2267 originator or other specifics of this subscription.";
2268 }
2269 uses subscription-policy;
2270 uses notification-origin-info;
2271 uses receiver-info;
2272 }
2273 }
2274 container subscriptions {
2275 config false;
2276 description
2277 "Contains the list of currently active subscriptions, i.e.
2278 subscriptions that are currently in effect, used for subscription
2279 management and monitoring purposes. This includes subscriptions
2280 that have been setup via RPC primitives as well as subscriptions
2281 that have been established via configuration.";
2282 list subscription {
2283 key "identifier";
2284 description
2285 "The identity and specific parameterst of a subscription.
2286 Subscriptions within this list can be created using a control
2287 channel or RPC, or be established through configuration.";
2288 leaf identifier {
2289 type subscription-id;
2290 description
2291 "Identifier of a subscription; unique within a publisher";
2292 }
2293 leaf configured-subscription-state {
2294 if-feature "configured";
2295 type enumeration {
2296 enum valid {
2297 value 1;
2298 description
2299 "Connection is active and healthy.";
2300 }
2301 enum invalid {
2302 value 2;
2303 description
2304 "The subscription as as whole is unsupportable with its
2305 current parameters.";
2306 }
2307 enum concluded {
2308 value 3;
2309 description
2310 "A subscription is inactive as it has hit a stop time,
2311 but not yet been removed from configuration.";
2312 }
2313 }
2314 description
2315 "The presence of this leaf indicates that the subscription
2316 originated from configuration, not through a control channel
2317 or RPC. The value indicates the system established status
2318 of the subscription.";
2319 }
2320 leaf purpose {
2321 if-feature "configured";
2322 type string;
2323 description
2324 "Open text allowing a configuring entity to embed the
2325 originator or other specifics of this subscription.";
2326 }
2327 uses subscription-policy;
2328 uses notification-origin-info {
2329 if-feature "configured";
2330 }
2331 uses receiver-info {
2332 augment receivers/receiver {
2333 description
2334 "include operational data for receivers.";
2335 leaf pushed-notifications {
2336 type yang:counter64;
2337 description
2338 "Operational data which provides the number of update
2339 notification messages pushed to a receiver.";
2340 }
2341 leaf excluded-notifications {
2342 type yang:counter64;
2343 description
2344 "Operational data which provides the number of event
2345 records from a stream explicitly removed via filtering so
2346 that they are not sent to a receiver.";
2347 }
2348 leaf status {
2349 type enumeration {
2350 enum active {
2351 value 1;
2352 description
2353 "Receiver is currently being sent any applicable
2354 notification messages for the subscription.";
2355 }
2356 enum suspended {
2357 value 2;
2358 description
2359 "Receiver status is suspended, so the publisher
2360 is currently unable to provide notification messages
2361 for the subscription.";
2362 }
2363 enum connecting {
2364 value 3;
2365 if-feature "configured";
2366 description
2367 "A subscription has been configured, but a
2368 subscription-started state change notification needs
2369 to be successfully received before notification
2370 messages are sent.";
2371 }
2372 enum timeout {
2373 value 4;
2374 if-feature "configured";
2375 description
2376 "A subscription has failed in sending a subscription
2377 started state change to the receiver.
2378 Additional attempts at connection attempts are not
2379 currently being made.";
2380 }
2381 }
2382 mandatory true;
2383 description
2384 "Specifies the status of a subscription from the
2385 perspective of a particular receiver. With this info it
2386 is possible to determine whether a subscriber is currently
2387 generating notification messages intended for that
2388 receiver.";
2389 }
2390 action reset {
2391 description
2392 "Allows the reset of this configured subscription receiver
2393 to the 'connecting' state. This enables the
2394 connection process to be reinitiated.";
2395 output {
2396 leaf time {
2397 type yang:date-and-time;
2398 mandatory true;
2399 description
2400 "Time a publisher returned the receiver to a
2401 connecting status.";
2402 }
2403 }
2404 }
2405 }
2406 }
2407 }
2408 }
2409 }
2410
2412 5. Considerations
2414 5.1. Implementation Considerations
2416 For a deployment including both configured and dynamic subscriptions,
2417 split subscription identifiers into static and dynamic halves. That
2418 way it is unlikely there will be collisions if the configured
2419 subscriptions attempt to set a subscription-id which might have
2420 already been dynamically allocated. The lower half the "identifier"
2421 object in the subscriptions container SHOULD be used when the
2422 "identifier" is selected and assigned by an external entity (such as
2423 with a configured subscription). And the upper half SHOULD be used
2424 for subscription identifiers dynamically chosen and assigned by the
2425 publisher
2427 Neither state change notification nor subscribed event records within
2428 notification messages may be sent before the transport layer,
2429 including any required capabilities exchange, has been established.
2431 An implementation may choose to transition between active and
2432 suspended subscription states more frequently than required by this
2433 specification. However if a subscription is unable to marshal all
2434 intended updates into a transmittable message in multiple successive
2435 intervals, the subscription SHOULD be suspended with the reason
2436 "unsupportable-volume".
2438 For configured subscriptions, operations are against the set of
2439 receivers using the subscription identifier as a handle for that set.
2440 But for streaming up dates, state change notifications are local to a
2441 receiver. In this specification it is the case that receivers get no
2442 information from the publisher about the existence of other
2443 receivers. But if an operator wants to let the receivers correlate
2444 results, it is useful to use the subscription identifier handle
2445 across the receivers to allow that correlation.
2447 5.2. IANA Considerations
2449 This document registers the following namespace URI in the "IETF XML
2450 Registry" [RFC3688]:
2452 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications
2453 Registrant Contact: The IESG.
2454 XML: N/A; the requested URI is an XML namespace.
2456 This document registers the following YANG module in the "YANG Module
2457 Names" registry [RFC6020]:
2459 Name: ietf-subscribed-notifications
2460 Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications
2461 Prefix: sn
2462 Reference: draft-ietf-netconf-ietf-subscribed-notifications-08.txt
2463 (RFC form)
2465 5.3. Security Considerations
2467 For dynamic subscriptions the publisher MUST authenticate and
2468 authorize all RPC requests.
2470 Subscriptions could overload a publisher's CPU. For this reason, the
2471 publisher MUST have the ability to decline a dynamic subscription
2472 request, and provide the appropriate RPC error response to a
2473 subscriber should the proposed subscription overly deplete the
2474 publisher's resources.
2476 A publisher needs to be able to suspend an existing dynamic or
2477 configured subscription based on capacity constraints. When this
2478 occurs, the subscription status MUST be updated accordingly and the
2479 receivers notified with subscription state notifications.
2481 If a malicious or buggy subscriber sends an unexpectedly large number
2482 of RPCs, the result might be an excessive use of system resources.
2483 In such a situation, subscription interactions MAY be terminated by
2484 terminating the transport session.
2486 For both configured and dynamic subscriptions the publisher MUST
2487 authenticate and authorize a receiver via some transport level
2488 mechanism before sending any updates.
2490 A secure transport is highly recommended and the publisher MUST
2491 ensure that the receiver has sufficient authorization to perform the
2492 function they are requesting against the specific subset of content
2493 involved.
2495 A publisher MUST NOT include any content in a notification message
2496 for which the receiver has not been authorized.
2498 With configured subscriptions, one or more publishers could be used
2499 to overwhelm a receiver. No notification messages SHOULD be sent to
2500 any receiver which doesn't even support subscriptions. Receivers
2501 that do not want notification messages need only terminate or refuse
2502 any transport sessions from the publisher.
2504 The NETCONF Authorization Control Model [RFC6536bis] SHOULD be used
2505 to control and restrict authorization of subscription configuration.
2506 This control models permits specifying per-receiver permissions to
2507 receive event records from specific streams.
2509 Where NACM is available, the NACM "very-secure" tag MUST be placed on
2510 the "kill-subscription" RPC so that only administrators have access
2511 to use this.
2513 One subscription id can be used for two or more receivers of the same
2514 configured subscription. But due to the possibility of different
2515 access control permissions per receiver, it SHOULD NOT be assumed
2516 that each receiver is getting identical updates.
2518 6. Acknowledgments
2520 For their valuable comments, discussions, and feedback, we wish to
2521 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen,
2522 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan
2523 Hares, Michael Scharf, and Guangying Zheng.
2525 7. References
2527 7.1. Normative References
2529 [I-D.draft-ietf-rtgwg-ni-model]
2530 Berger, L., Hopps, C., and A. Lindem, "YANG Network
2531 Instances", draft-ietf-rtgwg-ni-model-03 (work in
2532 progress), July 2017.
2534 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2535 Requirement Levels", BCP 14, RFC 2119,
2536 DOI 10.17487/RFC2119, March 1997,
2537 .
2539 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2540 DOI 10.17487/RFC3688, January 2004,
2541 .
2543 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2544 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
2545 .
2547 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2548 the Network Configuration Protocol (NETCONF)", RFC 6020,
2549 DOI 10.17487/RFC6020, October 2010,
2550 .
2552 [RFC6536bis]
2553 Bierman, A. and M. Bjorklund, "Network Configuration
2554 Protocol (NETCONF) Access Control Model", draft-ietf-
2555 netconf-rfc6536bis-01 (work in progress), September 2017.
2557 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
2558 Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
2559 DOI 10.17487/RFC7540, May 2015,
2560 .
2562 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2563 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2564 .
2566 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath)
2567 Version 1.0", November 1999,
2568 .
2570 7.2. Informative References
2572 [I-D.draft-ietf-netconf-netconf-event-notifications]
2573 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto.,
2574 Nilsen-Nygaard, E., Tripathy, A., Chisholm, S., and H.
2575 Trevino, "NETCONF support for event notifications",
2576 October 2016, .
2579 [I-D.draft-ietf-netconf-restconf-notif]
2580 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen-
2581 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and
2582 HTTP transport for event notifications", August 2016,
2583 .
2586 [I-D.ietf-netconf-yang-push]
2587 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto.,
2588 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B.
2589 Lengyel, "YANG Datastore Subscription", October 2017,
2590 .
2593 [I.D.draft-ietf-netconf-notification-messages]
2594 Voit, Eric., Clemm, Alexander., Bierman, A., and T.
2595 Jenkins, "YANG Notification Headers and Bundles",
2596 September 2017, .
2599 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2600 and A. Bierman, Ed., "Network Configuration Protocol
2601 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2602 .
2604 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2605 for Subscription to YANG Datastores", RFC 7923,
2606 DOI 10.17487/RFC7923, June 2016,
2607 .
2609 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2610 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2611 .
2613 Appendix A. Changes between revisions
2615 (To be removed by RFC editor prior to publication)
2617 v07 - v08
2618 o Split YANG trees to separate document subsections.
2620 o Clarified configured state machine based on Balazs comments, and
2621 moved it into the configured subscription subsections.
2623 o Normative reference to Network Instance model for VRF
2625 o One transport protocol for all receivers of configured
2626 subscriptions.
2628 o QoS section moved in from yang-push
2630 v06 - v07
2632 o Clarification on state machine for configured subscriptions.
2634 v05 - v06
2636 o Made changes proposed by Martin, Kent, and others on the list.
2637 Most significant of these are Stream returned to string (with the
2638 SYSLOG identity removed), intro section on 5277 relationship, an
2639 identity set moved to an enumeration, clean up of definitions/
2640 terminology, state machine proposed for configured subscriptions
2641 with a clean-up of susbcription state options.
2643 o JSON and XML become features. Also Xpath and subtree filtering
2644 become features
2646 o Terminology updates with event records, and refinement of filters
2647 to just stream filters.
2649 o Encoding refined in establish-subscription so it takes the RPC's
2650 encoding as the default.
2652 o Namespaces in examples fixed.
2654 v04 - v05
2656 o Returned to the explicit filter subtyping of v00
2658 o stream object changed to 'name' from 'stream'
2660 o Cleaned up examples
2662 o Clarified that JSON support needs notification-messages draft.
2664 v03 - v04
2665 o Moved back to the use of RFC5277 one-way notifications and
2666 encodings.
2668 v03 - v04
2670 o Replay updated
2672 v02 - v03
2674 o RPCs and Notification support is identified by the Notification
2675 2.0 capability.
2677 o Updates to filtering identities and text
2679 o New error type for unsupportable volume of updates
2681 o Text tweaks.
2683 v01 - v02
2685 o Subscription status moved under receiver.
2687 v00 - v01
2689 o Security considerations updated
2691 o Intro rewrite, as well as scattered text changes
2693 o Added Appendix A, to help match this to related drafts in progress
2695 o Updated filtering definitions, and filter types in yang file, and
2696 moved to identities for filter types
2698 o Added Syslog as a stream
2700 o HTTP2 moved in from YANG-Push as a transport option
2702 o Replay made an optional feature for events. Won't apply to
2703 datastores
2705 o Enabled notification timestamp to have different formats.
2707 o Two error codes added.
2709 v01 5277bis - v00 subscribed notifications
2711 o Kill subscription RPC added.
2713 o Renamed from 5277bis to Subscribed Notifications.
2715 o Changed the notification capabilities version from 1.1 to 2.0.
2717 o Extracted create-subscription and other elements of RFC5277.
2719 o Error conditions added, and made specific in return codes.
2721 o Simplified yang model structure for removal of 'basic' grouping.
2723 o Added a grouping for items which cannot be statically configured.
2725 o Operational counters per receiver.
2727 o Subscription-id and filter-id renamed to identifier
2729 o Section for replay added. Replay now cannot be configured.
2731 o Control plane notification renamed to subscription state
2732 notification
2734 o Source address: Source-vrf changed to string, default address
2735 option added
2737 o In yang model: 'info' changed to 'policy'
2739 o Scattered text clarifications
2741 v00 - v01 of 5277bis
2743 o YANG Model changes. New groupings for subscription info to allow
2744 restriction of what is changeable via RPC. Removed notifications
2745 for adding and removing receivers of configured subscriptions.
2747 o Expanded/renamed definitions from event server to publisher, and
2748 client to subscriber as applicable. Updated the definitions to
2749 include and expand on RFC 5277.
2751 o Removal of redundancy with other drafts
2753 o Many other clean-ups of wording and terminology
2755 Authors' Addresses
2757 Eric Voit
2758 Cisco Systems
2760 Email: evoit@cisco.com
2761 Alexander Clemm
2762 Huawei
2764 Email: ludwig@clemm.org
2766 Alberto Gonzalez Prieto
2767 VMWare
2769 Email: agonzalezpri@vmware.com
2771 Einar Nilsen-Nygaard
2772 Cisco Systems
2774 Email: einarnn@cisco.com
2776 Ambika Prasad Tripathy
2777 Cisco Systems
2779 Email: ambtripa@cisco.com