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