idnits 2.17.1 draft-ietf-netconf-subscribed-notifications-11.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 631 has weird spacing: '...ntifier sub...' == Line 660 has weird spacing: '...ntifier sub...' == Line 1186 has weird spacing: '...ntifier sub...' == Line 1219 has weird spacing: '...ntifier sub...' == Line 1236 has weird spacing: '...ntifier sub...' == (4 more instances...) -- The document date (April 6, 2018) is 2210 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: Non-RFC (?) normative reference: ref. 'XPATH' -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 0 errors (**), 0 flaws (~~), 8 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF E. Voit 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track A. Clemm 5 Expires: October 8, 2018 Huawei 6 A. Gonzalez Prieto 7 VMWare 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 April 6, 2018 13 Customized Subscriptions to a Publisher's Event Streams 14 draft-ietf-netconf-subscribed-notifications-11 16 Abstract 18 This document defines mechanisms and a YANG Data Model enabling 19 subscriber-specific subscriptions to a publisher's event streams. 20 Applying these elements allows a subscriber to request for and 21 receive a continuous, custom feed of publisher generated information. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on October 8, 2018. 40 Copyright Notice 42 Copyright (c) 2018 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 4 61 1.4. Relationship to RFC-5277 . . . . . . . . . . . . . . . . 6 62 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 6 64 2.2. Event Stream Filters . . . . . . . . . . . . . . . . . . 7 65 2.3. QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 2.4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 8 67 2.5. Configured Subscriptions . . . . . . . . . . . . . . . . 16 68 2.6. Event Record Delivery . . . . . . . . . . . . . . . . . . 22 69 2.7. Subscription State Notifications . . . . . . . . . . . . 23 70 2.8. Subscription Monitoring . . . . . . . . . . . . . . . . . 28 71 2.9. Advertisement . . . . . . . . . . . . . . . . . . . . . . 29 72 3. YANG Data Model Trees . . . . . . . . . . . . . . . . . . . . 29 73 3.1. Event Streams Container . . . . . . . . . . . . . . . . . 29 74 3.2. Event Stream Filters Container . . . . . . . . . . . . . 30 75 3.3. Subscriptions Container . . . . . . . . . . . . . . . . . 30 76 4. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 31 77 5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 57 78 5.1. Implementation Considerations . . . . . . . . . . . . . . 57 79 5.2. IANA Considerations . . . . . . . . . . . . . . . . . . . 58 80 5.3. Security Considerations . . . . . . . . . . . . . . . . . 58 81 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 61 82 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 83 7.1. Normative References . . . . . . . . . . . . . . . . . . 62 84 7.2. Informative References . . . . . . . . . . . . . . . . . 63 85 Appendix A. Changes between revisions . . . . . . . . . . . . . 64 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68 88 1. Introduction 90 This document defines mechanisms and a YANG Data Model enabling 91 subscriber-specific subscriptions to a publisher's event streams. 92 Effectively this enables a 'subscribe then publish' capability where 93 the customized information needs and access permissions of each 94 target receiver are understood by the publisher before subscribed 95 event records are marshaled and pushed. The receiver then gets a 96 continuous, custom feed of publisher generated information. 98 While the functionality defined in this document is transport- 99 agnostic, transports like NETCONF [RFC6241] or RESTCONF [RFC8040] can 100 be used to configure or dynamically signal subscriptions, and there 101 are bindings defined for subscribed event record delivery for NETCONF 102 within [I-D.draft-ietf-netconf-netconf-event-notifications], and for 103 HTTP2 or HTTP1.1 within [I-D.draft-ietf-netconf-restconf-notif]. 105 The YANG model in this document conforms to the Network Management 106 Datastore Architecture defined in 107 [I-D.draft-ietf-netmod-revised-datastores]. 109 1.1. Motivation 111 Various limitations in [RFC5277] are discussed in [RFC7923]. 112 Resolving these issues is the primary motivation for this work. Key 113 capabilities supported by this document include: 115 o multiple subscriptions on a single transport session 117 o support for dynamic and configured subscriptions 119 o modification of an existing subscription in progress 121 o per-subscription operational counters 123 o negotiation of subscription parameters (through the use of hints 124 returned as part of declined subscription requests) 126 o subscription state change notifications (e.g., publisher driven 127 suspension, parameter modification) 129 o independence from transport 131 1.2. Terminology 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL" in this document are to be interpreted as described in BCP 136 14 [RFC2119] [RFC8174] when, and only when, they appear in all 137 capitals, as shown here. 139 Configuration: defined in [I-D.draft-ietf-netmod-revised-datastores]. 141 Configuration datastore: defined in 142 [I-D.draft-ietf-netmod-revised-datastores]. 144 Configured subscription: A subscription installed via configuration 145 into a configuration datastore. 147 Dynamic subscription: A subscription agreed between subscriber and 148 publisher created via an "establish-subscription" RPC. 150 Event: An occurrence of something that may be of interest. Examples 151 include, a configuration change, a fault, a change in status, 152 crossing a threshold, or an external input to the system. 154 Event record: A set of information detailing an event. 156 Notification message: Information intended for a receiver indicating 157 that one or more event(s) have occurred. 159 Publisher: An entity responsible for streaming notification messages 160 per the terms of a subscription. 162 Receiver: A target to which a publisher pushes subscribed event 163 records. For dynamic subscriptions, the receiver and subscriber are 164 the same entity. 166 Stream (also referred to as "event stream"): A continuous, 167 chronologically ordered set of events aggregated under some context. 169 Stream filter: Evaluation criteria which may be applied against event 170 records within a stream. Event records pass the filter when 171 specified criteria are met. 173 Subscriber: An entity able to request and negotiate a contract for 174 the generation and push of event records from a publisher. For 175 dynamic subscriptions, the receiver and subscriber are the same 176 entity. 178 Subscription: A contract with a publisher, stipulating which 179 information one or more receivers wish to have pushed from the 180 publisher without the need for further solicitation. 182 All YANG tree diagrams used in this document follow the notation 183 defined in [I-D.ietf-netmod-yang-tree-diagrams]. 185 1.3. Solution Overview 187 This document describes a transport agnostic mechanism for 188 subscribing to and receiving content from a stream within a 189 publisher. This mechanism is through the use of a subscription. 191 Two types of subscriptions are supported: 193 1. Dynamic subscriptions, where a subscriber initiates a 194 subscription negotiation with a publisher via an RPC. If the 195 publisher is able to serve this request, it accepts it, and then 196 starts pushing notification messages back to the subscriber. If 197 the publisher is not able to serve it as requested, then an error 198 response is returned. This response MAY include hints at 199 subscription parameters that, had they been present, would have 200 enabled the dynamic subscription request to be accepted. 202 2. Configured subscriptions, which allow the management of 203 subscriptions via a configuration so that a publisher can send 204 notification messages to configured receiver(s). Support for 205 configured subscriptions is optional, with its availability 206 advertised via a YANG feature. 208 Additional characteristics differentiating configured from dynamic 209 subscriptions include: 211 o The lifetime of a dynamic subscription is bounded by the transport 212 session used to establish it. For connection-oriented stateful 213 transports like NETCONF, the loss of the transport session will 214 result in the immediate termination of any associated dynamic 215 subscriptions. For connectionless or stateless transports like 216 HTTP, a lack of receipt acknowledgment of a sequential set of 217 notification messages and/or keep-alives can be used to trigger a 218 termination of a dynamic subscription. Contrast this to the 219 lifetime of a configured subscription. This lifetime is driven by 220 relevant configuration being present within the publisher's 221 applied configuration. Being tied to configuration operations 222 implies configured subscriptions can be configured to persist 223 across reboots, and implies a configured subscription can persist 224 even when its publisher is fully disconnected from any network. 226 o Configured subscriptions can be modified by any configuration 227 client with write permission on the configuration of the 228 subscription. Dynamic subscriptions can only be modified via an 229 RPC request made by the original subscriber, or a change to 230 configuration data referenced by the subscription. 232 Note that there is no mixing-and-matching of dynamic and configured 233 operations on a single subscription. Specifically, a configured 234 subscription cannot be modified or deleted using RPCs defined in this 235 document. Similarly, a subscription established via RPC cannot be 236 modified through configuration operations. Also note that transport 237 specific transport drafts based on this specification MUST detail the 238 life cycles of both dynamic and configured subscriptions. 240 A publisher MAY terminate a dynamic subscription at any time. 241 Similarly, it MAY decide to temporarily suspend the sending of 242 notification messages for any dynamic subscription, or for one or 243 more receivers of a configured subscription. Such termination or 244 suspension is driven by internal considerations of the publisher. 246 1.4. Relationship to RFC-5277 248 This document is intended to provide a superset of the subscription 249 capabilities initially defined within [RFC5277]. Especially when 250 extending an existing [RFC5277] implementation, it is important to 251 understand what has been reused and what has been replaced. Key 252 relationships between these two documents include: 254 o this document defines a transport independent capability, 255 [RFC5277] is specific to NETCONF. 257 o the data model in this document is used instead of the data model 258 in [RFC5277], Section 3.4 for the new operations. 260 o the RPC operations in this draft replaces the operation "create- 261 subscription" defined in [RFC5277], section 4. 263 o the one way operation of [RFC5277], Section 4 is used. 265 o the included contents of the "NETCONF" stream are identical 266 between this document and [RFC5277]. 268 o a publisher MAY implement both the Notification Management Schema 269 and RPCs defined in [RFC5277] and this new document concurrently, 270 in order to support old clients. However the use of both 271 alternatives on a single transport session is prohibited. 273 o unlike [RFC5277], this document enables a single transport session 274 to intermix of notification messages and RPCs for different 275 subscriptions. 277 2. Solution 279 2.1. Event Streams 281 An event stream is a named entity on a publisher which exposes a 282 continuously updating set of event records. Each event stream is 283 available for subscription. It is out of the scope of this document 284 to identify a) how streams are defined (other than the NETCONF 285 stream), b) how event records are defined/generated, and c) how event 286 records are assigned to streams. 288 There is only one reserved event stream name within this document: 289 "NETCONF". The "NETCONF" event stream contains all NETCONF XML event 290 record information supported by the publisher, except for where it 291 has been explicitly indicated that this the event record MUST be 292 excluded from the "NETCONF" stream. The "NETCONF" stream will 293 include individual notifications as per [RFC7950] section 7.16. Each 294 of these notifications will be treated as a distinct event record. 295 Beyond the "NETCONF" stream, implementations MAY define additional 296 event streams. 298 As event records are created by a system, they may be assigned to one 299 or more streams. The event record is distributed to a subscription's 300 receiver(s) where: (1) a subscription includes the identified stream, 301 and (2) subscription filtering does not exclude the event record from 302 that receiver. 304 Access control permissions may be used to silently exclude event 305 records from within a stream for which the receiver has no read 306 access. As an example of how this might be accomplished, see 307 [RFC8341] section 3.4.6. Note that per Section 2.7 of this document, 308 subscription state change notifications are never filtered out. 310 If no access control permissions are in place for event records on a 311 stream, then a receiver MUST be allowed access to all the event 312 records. If subscriber permissions change during the lifecycle of a 313 subscription and stream access is no longer permitted, then the 314 subscription MUST be terminated. 316 2.2. Event Stream Filters 318 This document defines an extensible filtering mechanism. The filter 319 itself is a boolean test which is placed on the content of an event 320 record. A 'false' filtering result causes the event message to be 321 excluded from delivery to a receiver. A filter never results in 322 information being stripped from within an event record prior to that 323 event record being encapsulated within a notification message. The 324 two optional stream filtering syntaxes supported are [XPATH] and 325 subtree [RFC6241]. 327 If no stream filter is provided within a subscription, all event 328 records on a stream are to be sent. 330 2.3. QoS 332 This document provide for several QoS parameters. These parameters 333 indicate the treatment of a subscription relative to other traffic 334 between publisher and receiver. Included are: 336 o A "dscp" marking to differentiate transport prioritization during 337 network transit. Where provided, this marking MUST be stamped on 338 notification messages. 340 o A "weighting" so that bandwidth proportional to this weighting can 341 be allocated to this subscription relative to other subscriptions 342 destined for that receiver. 344 o a "dependency" upon another subscription. 346 For the "weighting" parameter, the dequeuing of notification messages 347 across independent subscriptions to a receiver MUST be allocated 348 bandwidth proportionally to each other based on each subscription's 349 weight. "Weigting" is an is an optional capability of the publisher; 350 support for it is identified via the "QoS" feature. 352 If a subscription has the "dependency" parameter set, then any 353 buffered notification messages containing event records selected by 354 the parent subscription MUST be dequeued prior to the notification 355 messages of the dependent subscription. If notification messages 356 have dependencies on each other, the notification message queued the 357 longest MUST go first. If a "dependency" included within an RPC 358 references a subscription which does not exist or is no longer 359 accessible to that subscriber, that "dependency" MUST be silently 360 removed. "Dependency" is an is an optional capability of the 361 publisher; support for it is identified via the "QoS" feature. 363 2.4. Dynamic Subscriptions 365 Dynamic subscriptions are managed via protocol operations (in the 366 form of [RFC7950], Section 7.14 RPCs) made against targets located 367 within the publisher. These RPCs have been designed extensibly so 368 that they may be augmented for subscription targets beyond event 369 streams. For examples of such augmentations, see the RPC 370 augmentations within [I-D.ietf-netconf-yang-push]'s YANG model. 372 2.4.1. Dynamic Subscription State Model 374 Below is the publisher's state machine for a dynamic subscription. 375 Each state is shown in its own box. It is important to note that 376 such a subscription doesn't exist at the publisher until an 377 "establish-subscription" RPC is accepted. The mere request by a 378 subscriber to establish a subscription is insufficient for that 379 subscription to be externally visible. States that are reflected in 380 the YANG model appear in upper-case letters; in addition, start and 381 end states are depicted to reflect subscription creation and deletion 382 events. 384 ......... 385 : start : 386 :.......: 387 | 388 establish-subscription 389 | 390 | .------modify-subscription-------. 391 v v | 392 .-----------. .-----------. 393 .--------. | receiver |-subscription-suspended*->| receiver | 394 modify- '| ACTIVE | | SUSPENDED | 395 subscription | |<--subscription-resumed*--| | 396 ---------->'-----------' '-----------' 397 | | 398 delete/kill-subscription delete/kill- 399 | subscription 400 v | 401 ......... | 402 : end :<-------------------------------' 403 :.......: 405 * indicates a state change notification 407 Figure 1: Publisher's state for a dynamic subscription 409 Of interest in this state machine are the following: 411 o Successful "establish-subscription" or "modify-subscription" RPCs 412 put the subscription into an active state. 414 o Failed "modify-subscription" RPCs will leave the subscription in 415 its previous state, with no visible change to any streaming 416 updates. 418 o A delete or kill RPC will end the subscription. 420 o The two state change notifications "subscription-suspended" and 421 "subscription-resumed" are shown. These are under the control of 422 a publisher. There are no direct controls over resuming a 423 subscription other than to attempt a modification of a 424 subscription in a way which reduces the resources consumed. 426 2.4.2. Establishing a Dynamic Subscription 428 The "establish-subscription" RPC allows a subscriber to request the 429 creation of a subscription. The transport selected by the subscriber 430 to reach the publisher MUST be able to support multiple "establish- 431 subscription" requests made within the same transport session. 433 The input parameters of the operation are: 435 o A "stream" name which identifies the targeted stream of events 436 against which the subscription is applied. 438 o A stream filter which may reduce the set of event records pushed. 440 o Where the transport used by the RPC supports multiple encodings, 441 an optional "encoding" for the event records pushed. Note: If no 442 "encoding" is included, the encoding of the RPC MUST be used. 444 o An optional "stop-time" for the subscription. If no "stop-time" 445 is present, notification messages will continue to be sent until 446 the subscription is terminated. 448 o An optional "start-time" for the subscription. Where there is no 449 "start-time", the subscription starts immediately. If the "start- 450 time" is in the past, it indicates that this subscription is 451 requesting a replay of previously generated information from the 452 event stream. For more on replay, see Section 2.4.2.1. 454 If the publisher can satisfy the "establish-subscription" request, it 455 replies with an identifier for the subscription, and then immediately 456 starts streaming notification messages. 458 Below is a tree diagram for "establish-subscription". All objects 459 contained in this tree are described within the included YANG model 460 within Section 4. 462 +---x establish-subscription 463 +---w input 464 | +---w (target) 465 | | +--:(stream) 466 | | +---w (stream-filter)? 467 | | | +--:(by-reference) 468 | | | | +---w stream-filter-ref 469 | | | | stream-filter-ref 470 | | | +--:(within-subscription) 471 | | | +---w (filter-spec)? 472 | | | +--:(stream-subtree-filter) 473 | | | | +---w stream-subtree-filter? 474 | | | | {subtree}? 475 | | | +--:(stream-xpath-filter) 476 | | | +---w stream-xpath-filter? 477 | | | yang:xpath1.0 {xpath}? 478 | | +---w stream stream-ref 479 | | +---w replay-start-time? yang:date-and-time {replay}? 480 | +---w stop-time? yang:date-and-time 481 | +---w dscp? inet:dscp 482 | +---w weighting? uint8 {qos}? 483 | +---w dependency? subscription-id {qos}? 484 | +---w encoding? encoding 485 +--ro output 486 +--ro identifier subscription-id 487 +--ro replay-start-time-revision? yang:date-and-time 488 {replay}? 490 Figure 2: establish-subscription RPC tree diagram 492 A publisher MAY reject the "establish-subscription" RPC for many 493 reasons as described in Section 2.4.6. The contents of the resulting 494 RPC error response MAY include details on input parameters which if 495 considered in a subsequent "establish-subscription" RPC, may result 496 in a successful subscription establishment. Any such hints MUST be 497 transported within a yang-data "establish-subscription-stream-error- 498 info" container included within the RPC error response. 500 yang-data establish-subscription-stream-error-info 501 +--ro establish-subscription-stream-error-info 502 +--ro reason? identityref 503 +--ro filter-failure-hint? string 505 Figure 3: establish-subscription RPC yang-data tree diagram 507 2.4.2.1. Requesting a replay of event records 509 Replay provides the ability to establish a subscription which is also 510 capable of passing recently generated event records. In other words, 511 as the subscription initializes itself, it sends any previously 512 generated content from within target event stream which meets the 513 filter and timeframe criteria. The end of these historical event 514 records is identified via a "replay-completed" state change 515 notification. Any event records generated since the subscription 516 establishment may then follow. All event records will be delivered 517 in the order they are placed into the stream. 519 Replay is an optional feature which is dependent on an event stream 520 supporting some form of logging. This document puts no on the size 521 or form of the log, or where it resides within the publisher. 523 The inclusion of a "replay-start-time" within an "establish- 524 subscription" RPC indicates a replay request. If the "replay-start- 525 time" contains a value that is earlier than what a publisher's 526 retained history supports, then if the subscription is accepted, the 527 actual publisher's revised start time MUST be set in the returned 528 "replay-start-time-revision" object. 530 A "stop-time" parameter may be included in a replay subscription. 531 For a replay subscription, the "stop-time" MAY be earlier than the 532 current time, but MUST be later than the "replay-start-time". 534 If the time the replay starts is later than the time marked within 535 any event records retained within the replay buffer, then the 536 publisher MUST send a "replay-completed" notification immediately 537 after a successful establish-subscription RPC response. 539 If a stream supports replay, the "replay-support" leaf is present in 540 the "/streams/stream" list entry for the stream. An event stream 541 that does support replay is not expected to have an unlimited supply 542 of saved notifications available to accommodate any given replay 543 request. To assess the timeframe available for replay, subscribers 544 can read the leafs "replay-log-creation-time" and "replay-log-aged- 545 time". See Figure 18 for the tree describing these elements. The 546 actual size of the replay log at any given time is a publisher 547 specific matter. Control parameters for the replay log are outside 548 the scope of this document. 550 2.4.3. Modifying a Dynamic Subscription 552 The "modify-subscription" operation permits changing the terms of an 553 existing dynamic subscription established on that transport session 554 via "establish-subscription". Dynamic subscriptions can be modified 555 any number of times. If the publisher accepts the requested 556 modifications, it acknowledges success to the subscriber, then 557 immediately starts sending event records based on the new terms. 559 Subscriptions created by configuration cannot be modified via this 560 RPC. However configuration may be used to modify objects referenced 561 by the subscription (such as a referenced filter). 563 Below is a tree diagram for "modify-subscription". All objects 564 contained in this tree are described within the included YANG model 565 within Section 4. 567 +---x modify-subscription 568 +---w input 569 +---w identifier subscription-id 570 +---w (target) 571 | +--:(stream) 572 | +---w (stream-filter)? 573 | +--:(by-reference) 574 | | +---w stream-filter-ref 575 | | stream-filter-ref 576 | +--:(within-subscription) 577 | +---w (filter-spec)? 578 | +--:(stream-subtree-filter) 579 | | +---w stream-subtree-filter? 580 | | {subtree}? 581 | +--:(stream-xpath-filter) 582 | +---w stream-xpath-filter? 583 | yang:xpath1.0 {xpath}? 584 +---w stop-time? yang:date-and-time 586 Figure 4: modify-subscription RPC tree diagram 588 If the publisher accepts the requested modifications on a currently 589 suspended subscription, the subscription will immediately be resumed 590 (i.e., the modified subscription is returned to the ACTIVE state.) 591 The publisher MAY immediately suspend this newly modified 592 subscription through the "subscription-suspended" notification before 593 any event records are sent. 595 If the publisher rejects the RPC request, the subscription remains as 596 prior to the request. That is, the request has no impact whatsoever. 597 Rejection of the RPC for any reason is indicated by via RPC error as 598 described in Section 2.4.6. The contents of such a rejected RPC MAY 599 include hints on inputs which (if considered) may result in a 600 successfully modified subscription. These hints MUST be transported 601 within a yang-data "modify-subscription-stream-error-info" container 602 inserted into the RPC error response. 604 Below is a tree diagram for "modify-subscription-RPC-yang-data". All 605 objects contained in this tree are described within the included YANG 606 model within Section 4. 608 yang-data modify-subscription-stream-error-info 609 +--ro modify-subscription-stream-error-info 610 +--ro reason? identityref 611 +--ro filter-failure-hint? string 613 Figure 5: modify-subscription RPC yang-data tree diagram 615 2.4.4. Deleting a Dynamic Subscription 617 The "delete-subscription" operation permits canceling an existing 618 subscription established on that transport session. If the publisher 619 accepts the request, and the publisher has indicated success, the 620 publisher MUST NOT send any more notification messages for this 621 subscription. If the delete request matches a known subscription 622 established on the same transport session, then it MUST be deleted; 623 otherwise it MUST be rejected with no changes to the publisher. 625 Below is a tree diagram for "delete-subscription". All objects 626 contained in this tree are described within the included YANG model 627 within Section 4. 629 +---x delete-subscription 630 +---w input 631 +---w identifier subscription-id 633 Figure 6: delete-subscription RPC tree diagram 635 Dynamic subscriptions can only be deleted via this RPC using the same 636 transport session previously used for subscription establishment. 637 Configured subscriptions cannot be deleted using RPCs. 639 2.4.5. Killing a Dynamic Subscription 641 The "kill-subscription" operation permits an operator to end a 642 dynamic subscription which is not associated with the transport 643 session used for the RPC. A publisher MUST terminate any dynamic 644 subscription identified by RPC request. An operator may find 645 subscription identifiers which may be used with "kill-subscription" 646 by searching for the IP address of a receiver within 647 "subscriptions/subscription/receivers/receiver/address". 649 Configured subscriptions cannot be killed using this RPC. Instead, 650 configured subscriptions are deleted as part of regular configuration 651 operations. Publishers MUST reject any RPC attempt to kill a 652 configured subscription. 654 Below is a tree diagram for "kill-subscription". All objects 655 contained in this tree are described within the included YANG model 656 within Section 4. 658 +---x kill-subscription 659 +---w input 660 +---w identifier subscription-id 662 Figure 7: kill-subscription RPC tree diagram 664 2.4.6. RPC Failures 666 Whenever an RPC is unsuccessful, the publisher returns relevant 667 information as part of the RPC error response. Transport level error 668 processing MUST be done before RPC error processing described in this 669 section. In all cases, RPC error information returned will use 670 existing transport layer RPC structures, such as those seen with 671 NETCONF in [RFC6241] Appendix A, or with RESTCONF in [RFC8040] 672 Section 7.1. These structures MUST be able to encode subscription 673 specific errors identified below and defined within this document's 674 YANG model. 676 As a result of this mixture, how subscription errors are encoded 677 within an RPC error response is transport dependent. Following are 678 valid errors which can occur for each RPC: 680 establish-subscription modify-subscription 681 ---------------------- ------------------- 682 dscp-unavailable filter-unsupported 683 filter-unsupported insufficient-resources 684 history-unavailable no-such-subscription 685 insufficient-resources 686 replay-unsupported 688 delete-subscription kill-subscription 689 ---------------------- ---------------------- 690 no-such-subscription no-such-subscription 692 To see a NETCONF based example of an error response from above, see 693 [I-D.draft-ietf-netconf-netconf-event-notifications], Figure 10. 695 There is one final set of transport independent RPC error elements 696 included in the YANG model. These are the following three yang-data 697 structures for failed event stream subscriptions: 699 1. "establish-subscription-stream-error-info": This MUST be returned 700 if an RPC error reason has not been placed elsewhere within the 701 transport portion of a failed "establish-subscription" RPC 702 response. This MUST be sent if hints on how to overcome the RPC 703 error are included. 705 2. "modify-subscription-stream-error-info": This MUST be returned if 706 an RPC error reason has not been placed elsewhere within the 707 transport portion of a failed "modify-subscription" RPC response. 708 This MUST be sent if hints on how to overcome the RPC error are 709 included. 711 3. "delete-subscription-error-info": This MUST be returned if an RPC 712 error reason has not been placed elsewhere within the transport 713 portion of a failed "delete-subscription" or "kill-subscription" 714 RPC response. 716 2.5. Configured Subscriptions 718 A configured subscription is a subscription installed via 719 configuration. Configured subscriptions may be modified by any 720 configuration client with the proper permissions. Subscriptions can 721 be modified or terminated via configuration at any point of their 722 lifetime. 724 Configured subscriptions have several characteristics distinguishing 725 them from dynamic subscriptions: 727 o persistence across publisher reboots, 729 o persistence even when transport is unavailable, and 731 o an ability to send notification messages to more than one receiver 732 (note that receivers are unaware of the existence of any other 733 receivers.) 735 Supporting configured subscriptions is optional and advertised using 736 the "configured" feature. 738 In addition to the subscription parameters available to dynamic 739 subscriptions described in Section 2.4.2, the following additional 740 parameters are also available to configured subscriptions: 742 o A "transport" which identifies the transport protocol to use to 743 connect with all subscription receivers. 745 o One or more receiver "address", where each address is intended as 746 the destination for event records. 748 o Optional parameters to identify where traffic should egress a 749 publisher: 751 * A "source-interface" which identifies the egress interface to 752 use from the publisher. Publisher support for this is optional 753 and advertised using the "interface-designation" feature. 755 * A "source-address" address, which identifies the IP address to 756 stamp on notification messages destined for the receiver. 758 * A "source-vrf" which identifies the VRF on which to reach 759 receivers. This VRF is a network instance as defined within 760 [I-D.draft-ietf-rtgwg-ni-model]. Publisher support for VRFs is 761 optional and advertised using the "supports-vrf" feature. 763 If none of the above parameters are set, notification messages 764 MUST egress the publisher's default interface. 766 A tree diagram describing these parameters is shown in Figure 20. 767 All parameters are described within the YANG model in Section 4. 769 2.5.1. Configured Subscription State Model 771 Below is the state machine for a configured subscription on the 772 publisher. This state machine describes the three states (VALID, 773 INVALID, and CONCLUDED), as well as the transitions between these 774 states. The creation or modification of a configured subscription 775 initiates an evaluation by the publisher to determine if the 776 subscription is in VALID or INVALID states. The publisher uses its 777 own criteria in making this determination. If in the VALID state, 778 the subscription becomes operational. 780 ......... 781 : start :-. 782 :.......: | 783 create .---modify-----.----------------------------------. 784 | | | | 785 V V .-------. ....... .---------. 786 .----[evaluate]--no--->|INVALID|-delete->: end :<-delete-|CONCLUDED| 787 | '-------' :.....: '---------' 788 |----[evaluate]--no-. ^ ^ ^ 789 | ^ | | | | 790 yes | '->unsupportable delete stop-time 791 | modify (subscription- (subscription- (subscription- 792 | | terminated*) terminated*) concluded*) 793 | | | | | 794 | (1) (2) (3) (4) 795 | .---------------------------------------------------------------. 796 '-->| VALID | 797 '---------------------------------------------------------------' 799 Legend: 800 dotted boxes: subscription creation and deletion events 801 dashed boxes with uppercase letters: states for a subscription 802 [evaluate]: decision point on whether the subscription is supportable 803 (*): resulting subscription state change notification 805 Figure 8: Publisher state model for a configured subscription 807 A subscription in the VALID state may move to the INVALID state in 808 one of two ways. First, it may be modified in a way which fails a 809 re-evaluation. See (1) in the diagram. Second, the publisher might 810 determine that the subscription is no longer supportable. This could 811 be for reasons of an unexpected but sustained increase in stream 812 events, degraded CPU capacity, a more complex referenced filter, or 813 other higher priority subscriptions which have usurped resources. 814 See (2) in the diagram. No matter the case, a "subscription- 815 terminated" notification is sent to any receivers in an ACTIVE or 816 SUSPENDED state. A subscription in the VALID state may also 817 transition to the CONCLUDED state via (4) if a configured stop time 818 has been reached. In this case, a "subscription-concluded" 819 notification is sent to any receivers in ACTIVE or SUSPENDED states. 820 Finally, a subscription may be deleted by configuration (3). 822 When a subscription is in the VALID state, a publisher will attempt 823 to connect with all configured receivers and deliver notification 824 messages. Below is the state machine for each receiver of a 825 configured subscription. This receiver state machine is fully 826 contained within the state machine of the configured subscription, 827 and is only relevant when the configured subscription is in the VALID 828 state. 830 .-----------------------------------------------------------------. 831 | VALID | 832 | .----------. .--------. | 833 | | receiver |------------------timeout->|receiver| | 834 | |CONNECTING|<----------------reset--(4)|TIMEOUT | | 835 | | |<-transport---. '--------' | 836 | '----------' loss,reset | | 837 | (1) | | | 838 | subscription- (3) | | 839 | started* .--------. | .---------. | 840 | '----->| | '--------------------(3)| | | 841 | |receiver|(2)-subscription-suspended*->|receiver | | 842 | subscription-| ACTIVE | |SUSPENDED| | 843 | modified* | |<--subscription-resumed*,----| | | 844 | '---->'--------' subscription-modified* '---------' | 845 '-----------------------------------------------------------------' 847 Legend: 848 dashed boxes which include the word 'receiver' show the possible 849 states for an individual receiver of a VALID configured subscription. 850 * indicates a state change notification 852 Figure 9: Receiver state for a configured subscription 854 When a configured subscription first moves the VALID state, the 855 "state" leaf of each receiver is initialized to "CONNECTING". If 856 transport connectivity is not available to any receiver, a transport 857 session is established (e.g., through [RFC8071]). Individual 858 receivers are moved to the ACTIVE state when a "subscription-started" 859 state change notification is successfully passed to that receiver 860 (1). Event records are only sent to ACTIVE receivers. Configured 861 receivers remain ACTIVE if both transport connectivity can be 862 verified to the receiver, and event records are not being dropped due 863 to a publisher buffer overflow. The result is that a receiver will 864 remain ACTIVE on the publisher as long as events aren't being lost, 865 or the receiver cannot be reached. However if there is buffer 866 overflow, or the publisher cannot generate notification messages for 867 a receiver, the receiver MUST be moved to SUSPENDED (2). In 868 addition, a configured subscription's receiver MUST be moved to 869 CONNECTING if transport connectivity cannot be achieved, or if the 870 receiver is reset via the "reset" action (3), (4). For more on 871 reset, see Section 2.5.5. 873 A configured subscription's receiver MUST be moved to the SUSPENDED 874 state if there is transport connectivity between the publisher and 875 receiver, but notification messages are not able to be generated for 876 that receiver. A configured subscription receiver MUST be returned 877 to the ACTIVE state from the SUSPENDED state when notification 878 messages are again being generated and a receiver has successfully 879 been sent a "subscription-resumed" or "subscription-modified" 880 notification. 882 Modification of a configured subscription is possible at any time. A 883 "subscription-modified" state change notification will be sent to all 884 active receivers, immediately followed by notification messages 885 conforming to the new parameters. Suspended receivers will also be 886 informed of the modification. However this notification will await 887 the end of the suspension for that receiver. 889 The mechanisms described above are mirrored in the RPCs and 890 notifications within the document. It should be noted that these 891 RPCs and notifications have been designed to be extensible and allow 892 subscriptions into targets other than event streams. The YANG model 893 of [I-D.ietf-netconf-yang-push] Section 4.1 provides many such 894 extensions; this includes the augmentation of "/modify- 895 subscription/input/target". 897 2.5.2. Creating a Configured Subscription 899 Configured subscriptions are established using configuration 900 operations against the top-level "subscriptions" subtree. 902 Because there is no explicit association with an existing transport 903 session, configuration operations require additional parameters 904 beyond those of dynamic subscriptions to indicate receivers, and 905 possibly whether the notification messages need to come from a 906 specific egress interface on the publisher. 908 After a subscription is successfully established, the publisher 909 immediately sends a "subscription-started" state change notification 910 to each receiver. It is quite possible that upon configuration, 911 reboot, or even steady-state operations, a transport session may not 912 be currently available to the receiver. In this case, when there is 913 something to transport for an active subscription, transport specific 914 call-home operations will be used to establish the connection. When 915 transport connectivity is available, notification messages may then 916 be pushed. 918 With active configured subscriptions, it is allowable to buffer event 919 records even after a "subscription-started" has been sent. However 920 if events are lost (rather than just delayed) due to replay buffer 921 overflow, a new "subscription-started" must be sent. This new 922 "subscription-started" indicates an event record discontinuity. 924 To see an example at subscription creation using configuration 925 operations over NETCONF, see Appendix A of 926 [I-D.draft-ietf-netconf-netconf-event-notifications]. 928 Note that is possible to configure replay on a configured 929 subscription. This capability is to allow a configured subscription 930 to exist on a system so that event records generated during boot can 931 be buffered and pushed as soon as the transport session is 932 established. 934 2.5.3. Modifying a Configured Subscription 936 Configured subscriptions can be modified using configuration 937 operations against the top-level "subscriptions" subtree. 939 If the modification involves adding receivers, added receivers are 940 placed in the CONNECTING state. If a receiver is removed, the state 941 change notification "subscription-terminated" is sent to that 942 receiver if that receiver is ACTIVE or SUSPENDED. 944 If the modification involves changing the policies for the 945 subscription, the publisher sends to currently active receivers a 946 "subscription-modified" notification. For any suspended receivers, a 947 "subscription-modified" notification will be delayed until the 948 receiver is resumed. (Note: in this case, the "subscription- 949 modified" notification informs the receiver that the subscription has 950 been resumed, so no additional "subscription-resumed" need be sent. 951 Also note that if multiple modifications have occurred during the 952 suspension, only the latest one need be sent to the receiver.) 954 2.5.4. Deleting a Configured Subscription 956 Subscriptions can be deleted through configuration against the top- 957 level "subscriptions" subtree. 959 Immediately after a subscription is successfully deleted, the 960 publisher sends to all receivers of that subscription a state change 961 notification stating the subscription has ended (i.e., "subscription- 962 terminated"). 964 2.5.5. Resetting a Configured Receiver 966 It is possible that a configured subscription to a receiver needs to 967 be reset. This is accomplished via the "reset" action within the 968 YANG model at "/subscriptions/subscription/receivers/receiver/reset". 969 This re-initialization may be useful in cases where a publisher has 970 timed out trying to reach a receiver. When such a reset occurs, a 971 transport session will be initiated if necessary, and a new 972 "subscription-started" notification will be sent. 974 2.5.6. Replay for a Configured Subscription 976 It is possible to place a start time on a configured subscription. 977 This enables functionality like immediately streaming boot log 978 information off of a publisher immediately after restart. 980 When any such configured subscription receivers become ACTIVE, 981 buffered event records (if any) will be sent immediately after the 982 "subscription-started" notification. The first event sent will be 983 the most recent following the latest of four different times: the 984 "replay-log-creation-time", "replay-log-aged-time", "replay-start- 985 time", or the most recent publisher boot time. 987 All other replay functionality remains the same as with dynamic 988 subscriptions as described in Section 2.4.2.1. 990 2.6. Event Record Delivery 992 Whether dynamic or configured, once a subscription has been set up, 993 the publisher streams event records via notification messages per the 994 terms of the subscription. For dynamic subscriptions, notification 995 messages are sent over the session used to establish the 996 subscription. For configured subscriptions, notification messages 997 are sent over the connections specified by the transport and each 998 configured receiver. In all cases, a single transport session MUST 999 be capable of supporting the intermixing of RPCs and notifications 1000 from different subscriptions. 1002 A notification message is sent to a receiver when an event record is 1003 not blocked by either the specified filter criteria or receiver 1004 permissions. This notification message MUST be encoded in a 1005 message as defined in [RFC5277], Section 4. 1007 The following example within [RFC7950] section 7.16.3 is an example 1008 of a compliant message: 1010 1012 2007-09-01T10:00:00Z 1013 1014 so-1/2/3.0 1015 up 1016 down 1017 1018 1020 Figure 10: subscribed notification message 1022 In the figure above, the "eventTime" is populated with a timestamp 1023 matching the time some originating process identified as when this 1024 event occurred. 1026 When a dynamic subscription has been started or modified, with 1027 "establish-subscription" or "modify-subscription" respectively, event 1028 records matching the newly applied filter criteria MUST NOT be sent 1029 until after the RPC reply has been sent. 1031 When a configured subscription has been started or modified, event 1032 records matching the newly applied filter criteria MUST NOT be sent 1033 until after the "subscription-started" or "subscription-modified" 1034 notifications has been sent, respectively. 1036 2.7. Subscription State Notifications 1038 In addition to sending event records to receivers, a publisher MUST 1039 also send subscription state notifications when events related to 1040 subscription management has occurred. 1042 Subscription state notifications are unlike other notifications in 1043 that they are never included in any stream. Instead, they are 1044 inserted (as defined in this section) within the sequence of 1045 notification messages sent to a particular receiver. Subscription 1046 state notifications cannot be filtered out, they cannot be stored in 1047 replay buffers, and they are delivered only to impacted receiver(s) 1048 of a subscription. The identification of subscription state 1049 notifications is easy to separate from other notification messages 1050 through the use of the YANG extension "subscription-state-notif". 1051 This extension tags a notification as subscription state 1052 notification. 1054 The complete set of subscription state notifications is described in 1055 the following subsections. 1057 2.7.1. subscription-started 1059 This notification indicates that a configured subscription has 1060 started, and event records may be sent. Included in this state 1061 change notification are all the parameters of the subscription, 1062 except for the receiver(s) addressing information and origin 1063 information indicating where notification messages will egress the 1064 publisher. Note that if a referenced filter from the "filters" 1065 container has been used within the subscription, the notification 1066 will still provide the contents of that referenced filter under the 1067 "within-subscription" subtree. 1069 Note that for dynamic subscriptions, no "subscription-started" 1070 notifications are ever sent. 1072 Below is a tree diagram for "subscription-started". All objects 1073 contained in this tree are described within the included YANG model 1074 within Section 4. 1076 +---n subscription-started {configured}? 1077 +--ro identifier subscription-id 1078 +--ro transport transport {configured}? 1079 +--ro encoding? encoding 1080 +--ro (target) 1081 | +--:(stream) 1082 | +--ro (stream-filter)? 1083 | | +--:(by-reference) 1084 | | | +--ro stream-filter-ref stream-filter-ref 1085 | | +--:(within-subscription) 1086 | | +--ro (filter-spec)? 1087 | | +--:(stream-subtree-filter) 1088 | | | +--ro stream-subtree-filter? 1089 | | | {subtree}? 1090 | | +--:(stream-xpath-filter) 1091 | | +--ro stream-xpath-filter? yang:xpath1.0 1092 | | {xpath}? 1093 | +--ro stream stream-ref 1094 | +--ro replay-start-time? yang:date-and-time 1095 | {replay}? 1096 +--ro stop-time? yang:date-and-time 1097 +--ro dscp? inet:dscp 1098 +--ro weighting? uint8 {qos}? 1099 +--ro dependency? subscription-id {qos}? 1101 Figure 11: subscription-started notification tree diagram 1103 2.7.2. subscription-modified 1105 This notification indicates that a subscription has been modified by 1106 configuration operations. It is delivered directly after the last 1107 event records processed using the previous subscription parameters, 1108 and before any event records processed after the modification. 1110 Below is a tree diagram for "subscription-modified". All objects 1111 contained in this tree are described within the included YANG model 1112 within Section 4. 1114 +---n subscription-modified 1115 +--ro identifier subscription-id 1116 +--ro transport transport {configured}? 1117 +--ro encoding? encoding 1118 +--ro (target) 1119 | +--:(stream) 1120 | +--ro (stream-filter)? 1121 | | +--:(by-reference) 1122 | | | +--ro stream-filter-ref stream-filter-ref 1123 | | +--:(within-subscription) 1124 | | +--ro (filter-spec)? 1125 | | +--:(stream-subtree-filter) 1126 | | | +--ro stream-subtree-filter? 1127 | | | {subtree}? 1128 | | +--:(stream-xpath-filter) 1129 | | +--ro stream-xpath-filter? yang:xpath1.0 1130 | | {xpath}? 1131 | +--ro stream stream-ref 1132 | +--ro replay-start-time? yang:date-and-time 1133 | {replay}? 1134 +--ro stop-time? yang:date-and-time 1135 +--ro dscp? inet:dscp 1136 +--ro weighting? uint8 {qos}? 1137 +--ro dependency? subscription-id {qos}? 1139 Figure 12: subscription-modified notification tree diagram 1141 A publisher most often sends this notification directly after the 1142 modification of any configuration parameters impacting a configured 1143 subscription. But it may also be sent at two other times: 1145 1. Where a configured subscription has been modified during the 1146 suspension of a receiver, the notification will be delayed until 1147 the receiver's suspension is lifted. In this situation, the 1148 notification indicates that the subscription has been both 1149 modified and resumed. 1151 2. While this state change will most commonly be used with 1152 configured subscriptions, with dynamic subscriptions, there is 1153 also one time this notification will be sent. A "subscription- 1154 modified" state change notification MUST be sent if the contents 1155 of the filter identified by the subscription's "stream-filter- 1156 ref" leaf has changed. 1158 2.7.3. subscription-terminated 1160 This notification indicates that no further event records for this 1161 subscription should be expected from the publisher. A publisher may 1162 terminate the sending event records to a receiver for the following 1163 reasons: 1165 1. Configuration which removes a configured subscription, or a 1166 "kill-subscription" RPC which ends a dynamic subscription. These 1167 are identified via the reason "no-such-subscription". 1169 2. A referenced filter is no longer accessible. This is identified 1170 by "filter-unavailable". 1172 3. The stream referenced by a subscription is no longer accessible 1173 by the receiver. This is identified by "stream-unavailable". 1175 4. A suspended subscription has exceeded some timeout. This is 1176 identified by "suspension-timeout". 1178 Each of the reasons above correspond one-to-one with a "reason" 1179 identityref specified within the YANG model. 1181 Below is a tree diagram for "subscription-terminated". All objects 1182 contained in this tree are described within the included YANG model 1183 within Section 4. 1185 +---n subscription-terminated 1186 +--ro identifier subscription-id 1187 +--ro reason identityref 1189 Figure 13: subscription-terminated notification tree diagram 1191 Note: this state change notification MUST be sent to a dynamic 1192 subscription's receiver when the "kill-subscription" RPC is 1193 successful, or other event other than reaching the subscription's 1194 "stop-time" results in the end of a subscription. 1196 2.7.4. subscription-suspended 1198 This notification indicates that a publisher has suspended the 1199 sending of event records to a receiver, and also indicates the 1200 possible loss of events. Suspension happens when capacity 1201 constraints stop a publisher from serving a valid subscription. The 1202 two conditions where is this possible are: 1204 1. "insufficient-resources" when a publisher is unable to produce 1205 the requested stream of notification messages, and 1207 2. "unsupportable-volume" when the bandwidth needed to get generated 1208 notification messages to a receiver exceeds a threshold. 1210 These conditions are encoded within the "reason" object. No further 1211 notification will be sent until the subscription resumes or is 1212 terminated. 1214 Below is a tree diagram for "subscription-suspended". All objects 1215 contained in this tree are described within the included YANG model 1216 within Section 4. 1218 +---n subscription-suspended 1219 +--ro identifier subscription-id 1220 +--ro reason identityref 1222 Figure 14: subscription-suspended notification tree diagram 1224 2.7.5. subscription-resumed 1226 This notification indicates that a previously suspended subscription 1227 has been resumed under the unmodified terms previously in place. 1228 Subscribed event records generated after the issuance of this state 1229 change notification may now be sent. 1231 Below is the tree diagram for "subscription-resumed". All objects 1232 contained in this tree are described within the included YANG model 1233 within Section 4. 1235 +---n subscription-resumed 1236 +--ro identifier subscription-id 1238 Figure 15: subscription-resumed notification tree diagram 1240 2.7.6. subscription-completed 1242 This notification indicates that a subscription, which includes a 1243 "stop-time", has successfully finished passing event records upon the 1244 reaching of that time. 1246 Below is a tree diagram for "subscription-completed". All objects 1247 contained in this tree are described within the included YANG model 1248 within Section 4. 1250 +---n subscription-completed 1251 +--ro identifier subscription-id 1253 Figure 16: subscription-completed notification tree diagram 1255 2.7.7. replay-completed 1257 This notification indicates that all of the event records prior to 1258 the current time have been passed to a receiver. It is sent before 1259 any notification message containing an event record with a timestamp 1260 later than (1) the "stop-time" or (2) the subscription's start time. 1262 If a subscription contains no "stop-time", or has a "stop-time" that 1263 has not been reached, then after the "replay-completed" notification 1264 has been sent, additional event records will be sent in sequence as 1265 they arise naturally on the publisher. 1267 Below is a tree diagram for "subscription-completed". All objects 1268 contained in this tree are described within the included YANG model 1269 within Section 4. 1271 +---n replay-completed 1272 +--ro identifier subscription-id 1274 Figure 17: replay-completed notification tree diagram 1276 2.8. Subscription Monitoring 1278 In the operational datastore, the container "subscriptions" maintains 1279 the state of all known subscriptions. This includes subscriptions 1280 that were established (and have not yet been deleted) using RPCs, as 1281 well as subscriptions that have been configured. Using datastore 1282 retrieval operations, or subscribing to this information via 1283 [I-D.ietf-netconf-yang-push] allows the state of subscriptions and 1284 their connectivity to receivers to be monitored. 1286 Each subscription is represented as a list element. While many 1287 subscription objects are shown as configurable, dynamic subscriptions 1288 are only included within the operational datastore and as a result 1289 are not configurable. Information for both dynamic and configured 1290 subscriptions may be monitored within the operational datastore. 1291 This information includes receiver event counters, the state of the 1292 receiver (e.g., is currently active or suspended), as well as the 1293 various subscription parameters that are in effect. The appearance 1294 of the leaf "configured-subscription-state" indicates both that the 1295 subscription came into being via configuration, and the current state 1296 of that configured subscription. 1298 Dynamic subscriptions are removed from the operational datastore once 1299 they expire (reaching stop-time) or when they are terminated. 1300 Configured subscriptions need to be deleted from the configuration by 1301 a configuration editing operation, even after the "stop-time" has 1302 been passed. 1304 2.9. Advertisement 1306 Publishers supporting this document MUST indicate support of the YANG 1307 model "ietf-subscribed-notifications" within the YANG library of the 1308 publisher. In addition support for optional features "encode-xml", 1309 "encode-json", "configured" "supports-vrf", "qos", "xpath", 1310 "subtree", "interface-designation", and "replay" MUST be indicated if 1311 supported. 1313 3. YANG Data Model Trees 1315 This section contains tree diagrams for nodes defined in Section 4. 1316 For tree diagrams of state change notifications, see Section 2.7. Or 1317 for the tree diagrams for the RPCs, see Section 2.4. 1319 3.1. Event Streams Container 1321 A publisher maintains a list of available event streams as 1322 operational data. This list contains both standardized and vendor- 1323 specific event streams. This enables subscribers to discover what 1324 streams a publisher supports. 1326 +--ro streams 1327 +--ro stream* [name] 1328 +--ro name string 1329 +--ro description string 1330 +--ro replay-support? empty {replay}? 1331 +--ro replay-log-creation-time yang:date-and-time {replay}? 1332 +--ro replay-log-aged-time? yang:date-and-time {replay}? 1334 Figure 18: Stream Container tree diagram 1336 Above is a tree diagram for the streams container. All objects 1337 contained in this tree are described within the included YANG model 1338 within Section 4. 1340 3.2. Event Stream Filters Container 1342 The "filters" container maintains a list of all subscription filters 1343 that persist outside the life-cycle of a single subscription. This 1344 enables pre-defined filters which may be referenced by more than one 1345 subscription. 1347 +--rw filters 1348 +--rw stream-filter* [identifier] 1349 +--rw identifier filter-id 1350 +--rw (filter-spec)? 1351 +--:(stream-subtree-filter) 1352 | +--rw stream-subtree-filter? {subtree}? 1353 +--:(stream-xpath-filter) 1354 +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 1356 Figure 19: Filter Container tree diagram 1358 Above is a tree diagram for the filters container. All objects 1359 contained in this tree are described within the included YANG model 1360 within Section 4. 1362 3.3. Subscriptions Container 1364 The "subscriptions" container maintains a list of all subscriptions 1365 on a publisher, both configured and dynamic. It can be used to 1366 retrieve information about the subscriptions which a publisher is 1367 serving. 1369 +--rw subscriptions 1370 +--rw subscription* [identifier] 1371 +--rw identifier subscription-id 1372 +--ro configured-subscription-state? enumeration 1373 | {configured}? 1374 +--rw purpose? string {configured}? 1375 +--rw transport transport 1376 | {configured}? 1377 +--rw encoding? encoding 1378 +--rw (target) 1379 | +--:(stream) 1380 | +--rw (stream-filter)? 1381 | | +--:(by-reference) 1382 | | | +--rw stream-filter-ref 1383 | | | stream-filter-ref 1384 | | +--:(within-subscription) 1385 | | +--rw (filter-spec)? 1386 | | +--:(stream-subtree-filter) 1387 | | | +--rw stream-subtree-filter? 1388 | | | {subtree}? 1389 | | +--:(stream-xpath-filter) 1390 | | +--rw stream-xpath-filter? 1391 | | yang:xpath1.0 {xpath}? 1392 | +--rw stream stream-ref 1393 | +--rw replay-start-time? 1394 | yang:date-and-time {replay}? 1395 +--rw stop-time? yang:date-and-time 1396 +--rw dscp? inet:dscp 1397 +--rw weighting? uint8 {qos}? 1398 +--rw dependency? subscription-id 1399 | {qos}? 1400 +--rw (notification-message-origin)? {configured}? 1401 | +--:(interface-originated) 1402 | | +--rw source-interface? 1403 | | if:interface-ref {interface-designation}? 1404 | +--:(address-originated) 1405 | +--rw source-vrf? 1406 | | -> /ni:network-instances/network-instance/name 1407 | | {supports-vrf}? 1408 | +--rw source-address? 1409 | inet:ip-address-no-zone 1410 +--rw receivers 1411 +--rw receiver* [name] 1412 +--rw name string 1413 +--rw address? inet:host 1414 +--ro pushed-notifications? yang:counter64 1415 +--ro excluded-notifications? yang:counter64 1416 +--ro state enumeration 1417 +---x reset 1418 +--ro output 1419 +--ro time yang:date-and-time 1421 Figure 20: Subscriptions tree diagram 1423 Above is a tree diagram for the subscriptions container. All objects 1424 contained in this tree are described within the included YANG model 1425 within Section 4. 1427 4. Data Model 1429 file "ietf-subscribed-notifications@2018-04-05.yang" 1430 module ietf-subscribed-notifications { 1431 yang-version 1.1; 1432 namespace 1433 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"; 1435 prefix sn; 1437 import ietf-yang-types { 1438 prefix yang; 1439 reference 1440 "RFC 6991: Common YANG Data Types"; 1441 } 1442 import ietf-inet-types { 1443 prefix inet; 1444 reference 1445 "RFC 6991: Common YANG Data Types"; 1446 } 1447 import ietf-interfaces { 1448 prefix if; 1449 reference 1450 "RFC 7223: A YANG Data Model for Interface Management"; 1451 } 1452 import ietf-network-instance { 1453 prefix ni; 1454 reference 1455 "draft-ietf-rtgwg-ni-model-11: YANG Model for Network Instances"; 1456 } 1457 import ietf-restconf { 1458 prefix rc; 1459 reference 1460 "RFC 8040 - RESTCONF Protocol"; 1461 } 1463 organization "IETF NETCONF (Network Configuration) Working Group"; 1464 contact 1465 "WG Web: 1466 WG List: 1468 Author: Alexander Clemm 1469 1471 Author: Eric Voit 1472 1474 Author: Alberto Gonzalez Prieto 1475 1477 Author: Einar Nilsen-Nygaard 1478 1480 Author: Ambika Prasad Tripathy 1481 "; 1483 description 1484 "Contains a YANG specification for subscribing to event records 1485 and receiving matching content within notification messages."; 1487 revision 2018-04-05 { 1488 description 1489 "Initial version"; 1490 reference 1491 "RFC XXXX: Customized Subscriptions to a Publisher's Event Streams"; 1492 } 1494 /* 1495 * FEATURES 1496 */ 1498 feature encode-json { 1499 description 1500 "This feature indicates that JSON encoding of notification 1501 messages is supported."; 1502 } 1504 feature encode-xml { 1505 description 1506 "This feature indicates that XML encoding of notification 1507 messages is supported."; 1508 } 1510 feature configured { 1511 description 1512 "This feature indicates that configuration of subscription is 1513 supported."; 1514 } 1516 feature replay { 1517 description 1518 "This feature indicates that historical event record replay is 1519 supported. With replay, it is possible for past event records to 1520 be streamed in chronological order."; 1521 } 1523 feature xpath { 1524 description 1525 "This feature indicates support for xpath filtering."; 1526 reference "http://www.w3.org/TR/1999/REC-xpath-19991116"; 1527 } 1528 feature subtree { 1529 description 1530 "This feature indicates support for YANG subtree filtering."; 1531 reference "RFC 6241, Section 6."; 1532 } 1534 feature supports-vrf { 1535 description 1536 "This feature indicates a publisher supports VRF configuration 1537 for configured subscriptions. VRF support for dynamic 1538 subscriptions does not require this feature."; 1539 reference "draft-ietf-rtgwg-ni-model"; 1540 } 1542 feature interface-designation { 1543 description 1544 "This feature indicates a publisher supports sourcing all receiver 1545 interactions for a configured subscription from a single 1546 designated egress interface."; 1547 } 1549 feature qos { 1550 description 1551 "This feature indicates a publisher supports absolute dependencies 1552 of one subscription's traffic over another, as well as weighted 1553 bandwidth sharing between subscriptions. Both of these are 1554 Quality of Service (QoS) features which allow differentiated 1555 treatment of notification messages between a publisher and a 1556 specific receiver."; 1557 } 1559 /* 1560 * EXTENSIONS 1561 */ 1563 extension subscription-state-notification { 1564 description 1565 "This statement applies only to notifications. It indicates that 1566 the notification is a subscription state notification. Therefore 1567 it does not participate in a regular event stream and does not 1568 need to be specifically subscribed to in order to be received. 1569 This statement can only occur as a substatement to the YANG 1570 'notification' statement."; 1571 } 1573 /* 1574 * IDENTITIES 1575 */ 1577 /* Identities for RPC and Notification errors */ 1579 identity establish-subscription-error { 1580 description 1581 "Problem found while attempting to fulfill an 1582 'establish-subscription' rpc request. "; 1583 } 1585 identity modify-subscription-error { 1586 description 1587 "Problem found while attempting to fulfill a 1588 'modify-subscription' rpc request. "; 1589 } 1591 identity delete-subscription-error { 1592 description 1593 "Problem found while attempting to fulfill either a 1594 'delete-subscription' rpc request or a 'kill-subscription' 1595 rpc request. "; 1596 } 1598 identity subscription-terminated-reason { 1599 description 1600 "Problem condition communicated to a receiver as part of a 1601 'subscription-terminated' notification. "; 1602 } 1604 identity subscription-suspended-reason { 1605 description 1606 "Problem condition communicated to a receiver as part of a 1607 'subscription-terminated' notification. "; 1608 } 1610 identity dscp-unavailable { 1611 base establish-subscription-error; 1612 description 1613 "The publisher is unable mark notification messages with a 1614 prioritization information in a way which will be respected during 1615 network transit."; 1616 } 1618 identity filter-unavailable { 1619 base subscription-terminated-reason; 1620 description 1621 "Referenced filter does not exist. This means a receiver is 1622 referencing a filter which doesn't exist, or to which they do not 1623 have access permissions."; 1624 } 1625 identity filter-unsupported { 1626 base establish-subscription-error; 1627 base modify-subscription-error; 1628 description 1629 "Cannot parse syntax within the filter. This failure can be from 1630 a syntax error, or a syntax too complex to be processed by the 1631 publisher."; 1632 } 1634 identity history-unavailable { 1635 base establish-subscription-error; 1636 description 1637 "Replay request too far into the past. This means the publisher 1638 does store historic information for the requested stream, but 1639 not back to the requested timestamp."; 1640 } 1642 identity insufficient-resources { 1643 base establish-subscription-error; 1644 base modify-subscription-error; 1645 base subscription-suspended-reason; 1646 description 1647 "The publisher has insufficient resources to support the 1648 requested subscription. An example might be that allocated CPU 1649 is too limited to generate the desired set of notification 1650 messages."; 1651 } 1653 identity no-such-subscription { 1654 base modify-subscription-error; 1655 base delete-subscription-error; 1656 base subscription-terminated-reason; 1657 description 1658 "Referenced subscription doesn't exist. This may be as a result of 1659 a non-existent subscription ID, an ID which belongs to another 1660 subscriber, or an ID for configured subscription."; 1661 } 1663 identity replay-unsupported { 1664 base establish-subscription-error; 1665 description 1666 "Replay cannot be performed for this subscription. This means the 1667 publisher will not provide the requested historic information from 1668 the stream via replay to this receiver."; 1669 } 1671 identity stream-unavailable { 1672 base subscription-terminated-reason; 1673 description 1674 "Not a subscribable stream. This means the referenced stream is 1675 not available for subscription by the receiver."; 1676 } 1678 identity suspension-timeout { 1679 base subscription-terminated-reason; 1680 description 1681 "Termination of previously suspended subscription. The publisher 1682 has eliminated the subscription as it exceeded a time limit for 1683 suspension."; 1684 } 1686 identity unsupportable-volume { 1687 base subscription-suspended-reason; 1688 description 1689 "The publisher does not have the network bandwidth needed to get 1690 the volume of generated information intended for a receiver."; 1691 } 1693 /* Identities for encodings */ 1695 identity configurable-encoding { 1696 description 1697 "If a transport identity derives from this identity, it means 1698 that it supports configurable encodings."; 1699 } 1701 identity encoding { 1702 description 1703 "Base identity to represent data encodings"; 1704 } 1706 identity encode-xml { 1707 base encoding; 1708 if-feature "encode-xml"; 1709 description 1710 "Encode data using XML as described in RFC 7950"; 1711 reference 1712 "RFC 7950 - The YANG 1.1 Data Modeling Language"; 1713 } 1715 identity encode-json { 1716 base encoding; 1717 if-feature "encode-json"; 1718 description 1719 "Encode data using JSON as described in RFC 7951"; 1720 reference 1721 "RFC 7951 - JSON Encoding of Data Modeled with YANG"; 1722 } 1724 /* Identities for transports */ 1725 identity transport { 1726 description 1727 "An identity that represents a the underlying mechanism for 1728 passing notification messages."; 1729 } 1731 identity inline-address { 1732 description 1733 "A transport identity can derive can derive from this identity 1734 in order to allow inline definition of the host address in the 1735 'receiver' list"; 1736 } 1738 /* 1739 * TYPEDEFs 1740 */ 1742 typedef subscription-id { 1743 type uint32; 1744 description 1745 "A type for subscription identifiers."; 1746 } 1748 typedef filter-id { 1749 type string; 1750 description 1751 "A type to identify filters which can be associated with a 1752 subscription."; 1753 } 1755 typedef encoding { 1756 type identityref { 1757 base encoding; 1758 } 1759 description 1760 "Specifies a data encoding, e.g. for a data subscription."; 1761 } 1763 typedef transport { 1764 type identityref { 1765 base transport; 1766 } 1767 description 1768 "Specifies transport used to send notification messages to a 1769 receiver."; 1770 } 1772 typedef stream-ref { 1773 type leafref { 1774 path "/sn:streams/sn:stream/sn:name"; 1775 } 1776 description 1777 "This type is used to reference a system-provided stream."; 1778 } 1780 typedef stream-filter-ref { 1781 type leafref { 1782 path "/sn:filters/sn:stream-filter/sn:identifier"; 1783 } 1784 description 1785 "This type is used to reference a stream filter."; 1786 } 1788 /* 1789 * GROUPINGS 1790 */ 1792 grouping stream-filter-elements { 1793 description 1794 "This grouping defines the base for filters applied to event 1795 streams."; 1796 choice filter-spec { 1797 description 1798 "The content filter specification for this request."; 1799 anydata stream-subtree-filter { 1800 if-feature "subtree"; 1801 description 1802 "Event stream evaluation criteria encoded in the syntax of a 1803 subtree filter as defined in RFC 6241, Section 6. 1805 The subtree filter is applied to the representation of 1806 individual, delineated event records as contained within the 1807 event stream. For example, if the notification message 1808 contains an instance of a notification defined in YANG, then 1809 the top-level element is the name of the YANG notification. 1811 If the subtree filter returns a non-empty node set, the filter 1812 matches the event record, and the it is included in the 1813 notification message sent to the receivers."; 1814 reference "RFC 6241, Section 6."; 1815 } 1816 leaf stream-xpath-filter { 1817 if-feature "xpath"; 1818 type yang:xpath1.0; 1819 description 1820 "Event stream evaluation criteria encoded in the syntax of 1821 an XPath 1.0 expression. 1823 The XPath expression is evaluated on the representation of 1824 individual, delineated event records as contained within 1825 the event stream. For example, if the notification message 1826 contains an instance of a notification defined in YANG, 1827 then the top-level element is the name of the YANG 1828 notification, and the root node has this top-level element 1829 as the only child. 1831 The result of the XPath expression is converted to a 1832 boolean value using the standard XPath 1.0 rules. If the 1833 boolean value is 'true', the filter matches the event 1834 record, and the it is included in the notification message 1835 sent to the receivers. 1837 The expression is evaluated in the following XPath context: 1839 o The set of namespace declarations are those in scope on 1840 the 'xpath-filter' leaf element 1842 o The set of variable bindings is empty. 1844 o The function library is the core function library, and 1845 the XPath functions defined in section 10 in RFC 7950. 1847 o The context node is the root node."; 1848 reference 1849 "http://www.w3.org/TR/1999/REC-xpath-19991116 1850 RFC 7950, Section 10."; 1852 } 1853 } 1854 } 1856 grouping update-qos { 1857 description 1858 "This grouping describes Quality of Service information 1859 concerning a subscription. This information is passed to lower 1860 layers for transport prioritization and treatment"; 1861 leaf dscp { 1862 type inet:dscp; 1863 default "0"; 1864 description 1865 "The desired network transport priority level. This is the 1866 priority set on notification messages encapsulating the results 1867 of the subscription. This transport priority is shared for all 1868 receivers of a given subscription."; 1869 } 1870 leaf weighting { 1871 if-feature "qos"; 1872 type uint8 { 1873 range "0 .. 255"; 1874 } 1875 description 1876 "Relative weighting for a subscription. Allows an underlying 1877 transport layer perform informed load balance allocations 1878 between various subscriptions"; 1879 reference 1880 "RFC-7540, section 5.3.2"; 1881 } 1882 leaf dependency { 1883 if-feature "qos"; 1884 type subscription-id; 1885 description 1886 "Provides the Subscription ID of a parent subscription which 1887 has absolute precedence should that parent have push updates 1888 ready to egress the publisher. In other words, there should be 1889 no streaming of objects from the current subscription if 1890 the parent has something ready to push. 1892 If a dependency is asserted via configuration or via RPC, but 1893 the referenced subscription-id does not exist, the dependency 1894 is silently discarded. If a referenced subscription is deleted 1895 this dependency is removed."; 1896 reference 1897 "RFC-7540, section 5.3.1"; 1898 } 1899 } 1901 grouping subscription-policy-modifiable { 1902 description 1903 "This grouping describes all objects which may be changed 1904 in a subscription via an RPC."; 1905 choice target { 1906 mandatory true; 1907 description 1908 "Identifies the source of information against which a 1909 subscription is being applied, as well as specifics on the 1910 subset of information desired from that source."; 1911 case stream { 1912 choice stream-filter { 1913 description 1914 "An event stream filter can be applied to a subscription. 1915 That filter will come either referenced from a global list, 1916 or be provided within the subscription itself."; 1917 case by-reference { 1918 description 1919 "Apply a filter that has been configured separately."; 1920 leaf stream-filter-ref { 1921 type stream-filter-ref; 1922 mandatory true; 1923 description 1924 "References an existing stream-filter which is to 1925 be applied to stream for the subscription."; 1926 } 1927 } 1928 case within-subscription { 1929 description 1930 "Local definition allows a filter to have the same 1931 lifecycle as the subscription."; 1932 uses stream-filter-elements; 1933 } 1934 } 1935 } 1936 } 1937 leaf stop-time { 1938 type yang:date-and-time; 1939 description 1940 "Identifies a time after which notification messages for a 1941 subscription should not be sent. If stop-time is not present, 1942 the notification messages will continue until the subscription 1943 is terminated. If replay-start-time exists, stop-time must be 1944 for a subsequent time. If replay-start-time doesn't exist, 1945 stop-time when established must be for a future time."; 1946 } 1947 } 1949 grouping subscription-policy-dynamic { 1950 description 1951 "This grouping describes information concerning a subscription 1952 which can just be passed over the RPCs defined in this model."; 1953 uses subscription-policy-modifiable { 1954 augment target/stream { 1955 description 1956 "Adds additional objects which can be modified by RPC."; 1957 leaf stream { 1958 type stream-ref { 1959 require-instance false; 1960 } 1961 mandatory true; 1962 description 1963 "Indicates the stream of event records to be considered for 1964 this subscription."; 1965 } 1966 leaf replay-start-time { 1967 if-feature "replay"; 1968 type yang:date-and-time; 1969 description 1970 "Used to trigger the replay feature and indicate that the 1971 replay should start at the time specified. If 1972 replay-start-time is not present, this is not a replay 1973 subscription and event record push should start immediately. 1974 It is never valid to specify start times that are later than 1975 or equal to the current time."; 1976 } 1977 } 1978 } 1979 uses update-qos; 1980 } 1982 grouping subscription-policy { 1983 description 1984 "This grouping describes the full set of policy information 1985 concerning both dynamic and configured subscriptions, except for 1986 configured receivers."; 1987 leaf transport { 1988 if-feature "configured"; 1989 type transport; 1990 mandatory true; 1991 description 1992 "This leaf specifies the transport used to deliver 1993 messages destined to all receivers of a subscription."; 1994 } 1995 leaf encoding { 1996 when 'derived-from(../transport, "sn:configurable-encoding")'; 1997 type encoding; 1998 description 1999 "The type of encoding for the subscribed data. If not 2000 included as part of the RPC, the encoding MUST be set by the 2001 publisher to be the encoding used by this RPC."; 2002 } 2003 uses subscription-policy-dynamic; 2004 } 2006 /* 2007 * RPCs 2008 */ 2010 rpc establish-subscription { 2011 description 2012 "This RPC allows a subscriber to create (and possibly negotiate) 2013 a subscription on its own behalf. If successful, the 2014 subscription remains in effect for the duration of the 2015 subscriber's association with the publisher, or until the 2016 subscription is terminated. In case an error occurs, or the 2017 publisher cannot meet the terms of a subscription, and RPC error 2018 is returned, the subscription is not created. In that case, the 2019 RPC reply's error-info MAY include suggested parameter settings 2020 that would have a higher likelihood of succeeding in a subsequent 2021 establish-subscription request."; 2022 input { 2023 uses subscription-policy-dynamic; 2024 leaf encoding { 2025 type encoding; 2026 description 2027 "The type of encoding for the subscribed data. If not 2028 included as part of the RPC, the encoding MUST be set by the 2029 publisher to be the encoding used by this RPC."; 2030 } 2031 } 2032 output { 2033 leaf identifier { 2034 type subscription-id; 2035 mandatory true; 2036 description 2037 "Identifier used for this subscription."; 2038 } 2039 leaf replay-start-time-revision { 2040 if-feature "replay"; 2041 type yang:date-and-time; 2042 description 2043 "If a replay has been requested, this represents the 2044 earliest time covered by the event buffer for the requested 2045 stream. The value of this object is the 2046 'replay-log-aged-time' if it exists. Otherwise it is the 2047 'replay-log-creation-time'. All buffered event records 2048 after this time will be replayed to a receiver. Note that 2049 this object will only be sent if the start time has been 2050 revised to be later than the time requested by the 2051 subscriber."; 2052 } 2053 } 2054 } 2055 rc:yang-data establish-subscription-stream-error-info { 2056 container establish-subscription-stream-error-info { 2057 description 2058 "If any 'establish-subscription' RPC parameters are 2059 unsupportable against the event stream, a subscription is not 2060 created and the RPC error response MUST indicate the reason 2061 why the subscription failed to be created. This yang-data MAY be 2062 inserted as structured data within a subscription's RPC error 2063 response to indicate the failure reason. This yang-data MUST be 2064 inserted if hints are to be provided back to the subscriber."; 2065 leaf reason { 2066 type identityref { 2067 base establish-subscription-error; 2068 } 2069 description 2070 "Indicates the reason why the subscription has failed to 2071 be created to a targeted stream."; 2072 } 2073 leaf filter-failure-hint { 2074 type string; 2075 description 2076 "Information describing where and/or why a provided filter 2077 was unsupportable for a subscription."; 2078 } 2079 } 2080 } 2082 rpc modify-subscription { 2083 description 2084 "This RPC allows a subscriber to modify a dynamic subscription's 2085 parameters. If successful, the changed subscription 2086 parameters remain in effect for the duration of the subscription, 2087 until the subscription is again modified, or until the 2088 subscription is terminated. In case of an error or an inability 2089 to meet the modified parameters, the subscription is not modified 2090 and the original subscription parameters remain in effect. 2091 In that case, the rpc error MAY include error-info suggested 2092 parameter hints that would have a high likelihood of succeeding 2093 in a subsequent modify-subscription request. A successful 2094 modify-subscription will return a suspended subscription to an 2095 active state."; 2096 input { 2097 leaf identifier { 2098 type subscription-id; 2099 mandatory true; 2100 description 2101 "Identifier to use for this subscription."; 2102 } 2103 uses subscription-policy-modifiable; 2104 } 2105 } 2107 rc:yang-data modify-subscription-stream-error-info { 2108 container modify-subscription-stream-error-info { 2109 description 2110 "This yang-data MAY be provided as part of a subscription's RPC 2111 error response when there is a failure of a 2112 'modify-subscription' RPC which has been made against a 2113 stream. This yang-data MUST be used if hints are to be 2114 provides back to the subscriber."; 2115 leaf reason { 2116 type identityref { 2117 base modify-subscription-error; 2118 } 2119 description 2120 "Information in a modify-subscription RPC error response which 2121 indicates the reason why the subscription to an event stream 2122 has failed to be modified."; 2123 } 2124 leaf filter-failure-hint { 2125 type string; 2126 description 2127 "Information describing where and/or why a provided filter 2128 was unsupportable for a subscription."; 2129 } 2130 } 2131 } 2133 rpc delete-subscription { 2134 description 2135 "This RPC allows a subscriber to delete a subscription that 2136 was previously created from by that same subscriber using the 2137 establish-subscription RPC. 2139 If an error occurs, the server replies with an 'rpc-error' where 2140 the 'error-info' field MAY contain an 2141 'delete-subscription-error-info' structure."; 2142 input { 2143 leaf identifier { 2144 type subscription-id; 2145 mandatory true; 2146 description 2147 "Identifier of the subscription that is to be deleted. 2148 Only subscriptions that were created using 2149 establish-subscription can be deleted via this RPC."; 2150 } 2152 } 2153 } 2155 rpc kill-subscription { 2156 description 2157 "This RPC allows an operator to delete a dynamic subscription 2158 without restrictions on the originating subscriber or underlying 2159 transport session. 2161 If an error occurs, the server replies with an 'rpc-error' where 2162 the 'error-info' field MAY contain an 2163 'delete-subscription-error-info' structure."; 2164 input { 2165 leaf identifier { 2166 type subscription-id; 2167 mandatory true; 2168 description 2169 "Identifier of the subscription that is to be deleted. Only 2170 subscriptions that were created using establish-subscription 2171 can be deleted via this RPC."; 2172 } 2173 } 2174 } 2176 rc:yang-data delete-subscription-error-info { 2177 container delete-subscription-error-info { 2178 description 2179 "If a 'delete-subscription' RPC or a 'kill-subscription' RPC 2180 fails, the subscription is not deleted and the RPC error 2181 response MUST indicate the reason for this failure. This 2182 yang-data MAY be inserted as structured data within a 2183 subscription's RPC error response to indicate the failure 2184 reason."; 2185 leaf reason { 2186 type identityref { 2187 base delete-subscription-error; 2188 } 2189 mandatory true; 2190 description 2191 "Indicates the reason why the subscription has failed to be 2192 deleted."; 2193 } 2194 } 2195 } 2197 /* 2198 * NOTIFICATIONS 2199 */ 2201 notification replay-completed { 2202 sn:subscription-state-notification; 2203 if-feature "replay"; 2204 description 2205 "This notification is sent to indicate that all of the replay 2206 notifications have been sent. It must not be sent for any other 2207 reason."; 2208 leaf identifier { 2209 type subscription-id; 2210 mandatory true; 2211 description 2212 "This references the affected subscription."; 2213 } 2214 } 2216 notification subscription-completed { 2217 sn:subscription-state-notification; 2218 description 2219 "This notification is sent to indicate that a subscription has 2220 finished passing event records, as the stop-time has been 2221 reached."; 2222 leaf identifier { 2223 type subscription-id; 2224 mandatory true; 2225 description 2226 "This references the gracefully completed subscription."; 2227 } 2228 } 2230 notification subscription-started { 2231 sn:subscription-state-notification; 2232 if-feature "configured"; 2233 description 2234 "This notification indicates that a subscription has started and 2235 notifications are beginning to be sent. This notification shall 2236 only be sent to receivers of a subscription; it does not 2237 constitute a general-purpose notification."; 2238 leaf identifier { 2239 type subscription-id; 2240 mandatory true; 2241 description 2242 "This references the affected subscription."; 2243 } 2244 uses subscription-policy { 2245 refine "target/stream/replay-start-time" { 2246 description 2247 "Indicates the time that a replay using for the streaming of 2248 buffered event records. This will be populated with the most 2249 recent of the following: replay-log-creation-time, 2250 replay-log-aged-time, replay-start-time, or the most recent 2251 publisher boot time."; 2252 } 2253 refine "target/stream/stream-filter/within-subscription" { 2254 description 2255 "Filter applied to the subscription. If the 2256 'stream-filter-ref' is populated, the filter within the 2257 subscription came from the 'filters' container. Otherwise it 2258 is populated in-line as part of the subscription."; 2259 } 2260 } 2261 } 2263 notification subscription-resumed { 2264 sn:subscription-state-notification; 2265 description 2266 "This notification indicates that a subscription that had 2267 previously been suspended has resumed. Notifications will once 2268 again be sent. In addition, a subscription-resumed indicates 2269 that no modification of parameters has occurred since the last 2270 time event records have been sent."; 2271 leaf identifier { 2272 type subscription-id; 2273 mandatory true; 2274 description 2275 "This references the affected subscription."; 2276 } 2277 } 2279 notification subscription-modified { 2280 sn:subscription-state-notification; 2281 description 2282 "This notification indicates that a subscription has been 2283 modified. Notification messages sent from this point on will 2284 conform to the modified terms of the subscription. For 2285 completeness, this state change notification includes both 2286 modified and non-modified aspects of a subscription."; 2287 leaf identifier { 2288 type subscription-id; 2289 mandatory true; 2290 description 2291 "This references the affected subscription."; 2292 } 2293 uses subscription-policy { 2294 refine "target/stream/stream-filter/within-subscription" { 2295 description 2296 "Filter applied to the subscription. If the 2297 'stream-filter-ref' is populated, the filter within the 2298 subscription came from the 'filters' container. Otherwise it 2299 is populated in-line as part of the subscription."; 2300 } 2301 } 2302 } 2304 notification subscription-terminated { 2305 sn:subscription-state-notification; 2306 description 2307 "This notification indicates that a subscription has been 2308 terminated."; 2309 leaf identifier { 2310 type subscription-id; 2311 mandatory true; 2312 description 2313 "This references the affected subscription."; 2314 } 2315 leaf reason { 2316 type identityref { 2317 base subscription-terminated-reason; 2318 } 2319 mandatory true; 2320 description 2321 "Identifies the condition which resulted in the termination ."; 2322 } 2323 } 2325 notification subscription-suspended { 2326 sn:subscription-state-notification; 2327 description 2328 "This notification indicates that a suspension of the 2329 subscription by the publisher has occurred. No further 2330 notifications will be sent until the subscription resumes. 2331 This notification shall only be sent to receivers of a 2332 subscription; it does not constitute a general-purpose 2333 notification."; 2334 leaf identifier { 2335 type subscription-id; 2336 mandatory true; 2337 description 2338 "This references the affected subscription."; 2339 } 2340 leaf reason { 2341 type identityref { 2342 base subscription-suspended-reason; 2343 } 2344 mandatory true; 2345 description 2346 "Identifies the condition which resulted in the suspension."; 2347 } 2348 } 2350 /* 2351 * DATA NODES 2352 */ 2354 container streams { 2355 config false; 2356 description 2357 "This container contains information on the built-in streams 2358 provided by the publisher."; 2359 list stream { 2360 key "name"; 2361 description 2362 "Identifies the built-in streams that are supported by the 2363 publisher."; 2364 leaf name { 2365 type string; 2366 description 2367 "A handle for a system-provided stream made up of a 2368 sequential set of event records, each of which is 2369 characterized by its own domain and semantics."; 2370 } 2371 leaf description { 2372 type string; 2373 mandatory true; 2374 description 2375 "A description of the event stream, including such information 2376 as the type of event records that are available within this 2377 stream."; 2378 } 2379 leaf replay-support { 2380 if-feature "replay"; 2381 type empty; 2382 description 2383 "Indicates that event record replay is available on this 2384 stream."; 2385 } 2386 leaf replay-log-creation-time { 2387 when "../replay-support"; 2388 if-feature "replay"; 2389 type yang:date-and-time; 2390 mandatory true; 2391 description 2392 "The timestamp of the creation of the log used to support the 2393 replay function on this stream. This time might be earlier 2394 than the earliest available information contained in the log. 2395 This object is updated if the log resets for some reason."; 2396 } 2397 leaf replay-log-aged-time { 2398 if-feature "replay"; 2399 type yang:date-and-time; 2400 description 2401 "The timestamp associated with last event record which has 2402 been aged out of the log. This timestamp identifies how far 2403 back into history this replay log extends, if it doesn't 2404 extend back to the 'replay-log-creation-time'. This object 2405 MUST be present if replay is supported and any event records 2406 have been aged out of the log."; 2407 } 2408 } 2409 } 2411 container filters { 2412 description 2413 "This container contains a list of configurable filters 2414 that can be applied to subscriptions. This facilitates 2415 the reuse of complex filters once defined."; 2416 list stream-filter { 2417 key "identifier"; 2418 description 2419 "A list of pre-configured filters that can be applied to 2420 subscriptions."; 2421 leaf identifier { 2422 type filter-id; 2423 description 2424 "An identifier to differentiate between filters."; 2425 } 2426 uses stream-filter-elements; 2427 } 2428 } 2430 container subscriptions { 2431 description 2432 "Contains the list of currently active subscriptions, i.e. 2433 subscriptions that are currently in effect, used for subscription 2434 management and monitoring purposes. This includes subscriptions 2435 that have been setup via RPC primitives as well as subscriptions 2436 that have been established via configuration."; 2437 list subscription { 2438 key "identifier"; 2439 description 2440 "The identity and specific parameters of a subscription. 2442 Subscriptions within this list can be created using a control 2443 channel or RPC, or be established through configuration. 2445 If configuration operations or the 'kill-subscription' rpc are 2446 used to delete a subscription, a 'subscription-terminated' 2447 message is sent to any ACTIVE or SUSPENDED receivers."; 2448 leaf identifier { 2449 type subscription-id; 2450 description 2451 "Identifier of a subscription; unique within a publisher"; 2452 } 2453 leaf configured-subscription-state { 2454 if-feature "configured"; 2455 type enumeration { 2456 enum VALID { 2457 value 1; 2458 description 2459 "Connection is active and healthy."; 2460 } 2461 enum INVALID { 2462 value 2; 2463 description 2464 "The subscription as a whole is unsupportable with its 2465 current parameters."; 2466 } 2467 enum CONCLUDED { 2468 value 3; 2469 description 2470 "A subscription is inactive as it has hit a stop time, 2471 but not yet been removed from configuration."; 2472 } 2473 } 2474 config false; 2475 description 2476 "The presence of this leaf indicates that the subscription 2477 originated from configuration, not through a control channel 2478 or RPC. The value indicates the system established state 2479 of the subscription."; 2480 } 2481 leaf purpose { 2482 if-feature "configured"; 2483 type string; 2484 description 2485 "Open text allowing a configuring entity to embed the 2486 originator or other specifics of this subscription."; 2487 } 2488 uses subscription-policy { 2489 refine "target/stream/stream" { 2490 description 2491 "Indicates the stream of event records to be considered for 2492 this subscription. If a stream has been removed, and no 2493 longer can be referenced by an active subscription, send a 2494 'subscription-terminated' notification with 2495 'stream-unavailable' as the reason. If a configured 2496 subscription refers to a non-existent stream, move that 2497 subscription to the 'invalid' state."; 2498 } 2499 } 2500 choice notification-message-origin { 2501 if-feature "configured"; 2502 description 2503 "Identifies the egress interface on the Publisher from which 2504 notification messages are to be sent."; 2505 case interface-originated { 2506 description 2507 "When notification messages to egress a specific, designated 2508 interface on the Publisher."; 2509 leaf source-interface { 2510 if-feature "interface-designation"; 2511 type if:interface-ref; 2512 description 2513 "References the interface for notification messages."; 2514 } 2515 } 2516 case address-originated { 2517 description 2518 "When notification messages are to depart from a publisher 2519 using specific originating address and/or routing context 2520 information."; 2521 leaf source-vrf { 2522 if-feature "supports-vrf"; 2523 type leafref { 2524 path "/ni:network-instances/ni:network-instance/ni:name"; 2525 } 2526 description 2527 "VRF from which notification messages should egress a 2528 publisher."; 2529 } 2530 leaf source-address { 2531 type inet:ip-address-no-zone; 2532 description 2533 "The source address for the notification messages. If a 2534 source VRF exists, but this object doesn't, a publisher's 2535 default address for that VRF must be used."; 2536 } 2537 } 2539 } 2540 container receivers { 2541 description 2542 "Set of receivers in a subscription."; 2543 list receiver { 2544 key "name"; 2545 min-elements 1; 2546 description 2547 "A host intended as a recipient for the notification 2548 messages of a subscription. For configured subscriptions 2549 the 'address' may identify a receiver. Additional ways of 2550 specifying configured receivers may be added through an 2551 augmentation to the objects within this list."; 2552 leaf name { 2553 type string; 2554 description 2555 "Identifies a unique receiver for a subscription."; 2556 } 2557 leaf address { 2558 when 2559 'derived-from(../../../transport, "sn:inline-address")'; 2560 type inet:host; 2561 description 2562 "Specifies the address for the traffic to reach a remote 2563 host using the subscription's transport. One of the 2564 following must be specified: an ipv4 address, an ipv6 2565 address, or a host name."; 2566 } 2567 leaf pushed-notifications { 2568 type yang:counter64; 2569 config false; 2570 description 2571 "Operational data which provides the number of update 2572 notification messages pushed to a receiver."; 2573 } 2574 leaf excluded-notifications { 2575 type yang:counter64; 2576 config false; 2577 description 2578 "Operational data which provides the number of event 2579 records from a stream explicitly removed either via a 2580 stream filter or an access control filter so that they 2581 are not passed to a receiver."; 2582 } 2583 leaf state { 2584 type enumeration { 2585 enum ACTIVE { 2586 value 1; 2587 description 2588 "Receiver is currently being sent any applicable 2589 notification messages for the subscription."; 2590 } 2591 enum SUSPENDED { 2592 value 2; 2593 description 2594 "Receiver state is SUSPENDED, so the publisher 2595 is currently unable to provide notification messages 2596 for the subscription."; 2597 } 2598 enum CONNECTING { 2599 value 3; 2600 if-feature "configured"; 2601 description 2602 "A subscription has been configured, but a 2603 subscription-started state change notification needs 2604 to be successfully received before notification 2605 messages are sent. 2607 If the 'reset' action is invoked for a receiver of an 2608 active configured subscription, the state must be 2609 moved to CONNECTING."; 2610 } 2611 enum TIMEOUT { 2612 value 4; 2613 if-feature "configured"; 2614 description 2615 "A subscription has failed in sending a subscription 2616 started state change to the receiver. 2617 Additional attempts at connection attempts are not 2618 currently being made."; 2619 } 2620 } 2621 config false; 2622 mandatory true; 2623 description 2624 "Specifies the state of a subscription from the 2625 perspective of a particular receiver. With this info it 2626 is possible to determine whether a subscriber is currently 2627 generating notification messages intended for that 2628 receiver."; 2629 } 2630 action reset { 2631 description 2632 "Allows the reset of this configured subscription receiver 2633 to the 'connecting' state. This enables the 2634 connection process to be re-initiated."; 2636 output { 2637 leaf time { 2638 type yang:date-and-time; 2639 mandatory true; 2640 description 2641 "Time a publisher returned the receiver to a 2642 connecting state."; 2643 } 2644 } 2645 } 2646 } 2647 } 2648 } 2649 } 2650 } 2651 2653 5. Considerations 2655 5.1. Implementation Considerations 2657 To support deployments including both configured and dynamic 2658 subscriptions, it is recommended to split subscription identifiers 2659 into static and dynamic halves. That way it eliminates the 2660 possibility of collisions if the configured subscriptions attempt to 2661 set a subscription-id which might have already been dynamically 2662 allocated. A best practice is to use lower half the "identifier" 2663 object's integer space when that "identifier" is assigned by an 2664 external entity (such as with a configured subscription). This 2665 leaves the upper half of subscription identifiers available to be 2666 dynamically assigned by the publisher. 2668 If a subscription is unable to marshal a series of filtered event 2669 records into transmittable notification messages, the receiver should 2670 be suspended with the reason "unsupportable-volume". 2672 For configured subscriptions, operations are against the set of 2673 receivers using the subscription identifier as a handle for that set. 2674 But for streaming updates, state change notifications are local to a 2675 receiver. In this specification it is the case that receivers get no 2676 information from the publisher about the existence of other 2677 receivers. But if a network operator wants to let the receivers 2678 correlate results, it is useful to use the subscription identifier 2679 handle across the receivers to allow that correlation. 2681 5.2. IANA Considerations 2683 This document registers the following namespace URI in the "IETF XML 2684 Registry" [RFC3688]: 2686 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2687 Registrant Contact: The IESG. 2688 XML: N/A; the requested URI is an XML namespace. 2690 This document registers the following YANG module in the "YANG Module 2691 Names" registry [RFC6020]: 2693 Name: ietf-subscribed-notifications 2694 Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2695 Prefix: sn 2696 Reference: draft-ietf-netconf-ietf-subscribed-notifications-11.txt 2697 (RFC form) 2699 5.3. Security Considerations 2701 The YANG module specified in this document defines a schema for data 2702 that is designed to be accessed via network management transports 2703 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 2704 layer is the secure transport layer, and the mandatory-to-implement 2705 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 2706 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 2707 transport is TLS [RFC5246]. 2709 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 2710 to restrict access for particular NETCONF or RESTCONF users to a 2711 preconfigured subset of all available NETCONF or RESTCONF operations 2712 and content. 2714 There are a number of data nodes defined in this YANG module that are 2715 writable/creatable/deletable (i.e., config true, which is the 2716 default). These data nodes may be considered sensitive or vulnerable 2717 in some network environments. Write operations (e.g., edit-config) 2718 to these data nodes without proper protection can have a negative 2719 effect on network operations. These are the subtrees and data nodes 2720 and their sensitivity/vulnerability: 2722 Container: "/filters" 2724 o "stream-subtree-filter": updating a filter could increase the 2725 computational complexity of all referencing subscriptions. 2727 o "stream-xpath-filter": updating a filter could increase the 2728 computational complexity of all referencing subscriptions. 2730 Container: "/subscriptions" 2732 The following considerations are only relevant for configuration 2733 operations made upon configured subscriptions: 2735 o "address": can be used to attempt to send traffic to an unwilling 2736 receiver. 2738 o "dependency": can be used to force important traffic to be queued 2739 behind less important updates. 2741 o "dscp": if unvalidated, can result in the sending of traffic with 2742 a higher priority marking that warranted. 2744 o "encoding": may be possible to set to a value which a receiver is 2745 unable to interpret. 2747 o "identifier": can overwrite an existing subscription, perhaps one 2748 configured by another entity. 2750 o "transport": none 2752 o "purpose": none 2754 o "replay-start-time": can be used to push very large logs, wasting 2755 resources. 2757 o "source-address": the configured address might not be able to 2758 reach a desired receiver. 2760 o "source-interface": the configured interface might not be able to 2761 reach a desired receiver. 2763 o "source-vrf": can place a subscription into a virtual network 2764 where receivers are not entitled to view the subscribed content. 2766 o "stop-time": could be used to terminate content at an inopportune 2767 time. 2769 o "stream": could set a subscription to a stream containing no 2770 content permitted for the targeted receivers. 2772 o "stream-filter-ref": could be set to a filter which is irrelevant 2773 to the event stream. 2775 o "stream-subtree-filter": a complex filter can increase the 2776 computational resources for this subscription. 2778 o "stream-xpath-filter": a complex filter can increase the 2779 computational resources for this subscription. 2781 o "weighting": placing a large weight can overwhelm the dequeuing of 2782 other subscriptions. 2784 Some of the readable data nodes in this YANG module may be considered 2785 sensitive or vulnerable in some network environments. It is thus 2786 important to control read access (e.g., via get, get-config, or 2787 notification) to these data nodes. These are the subtrees and data 2788 nodes and their sensitivity/vulnerability: 2790 Container: "/streams" 2792 o "name": if access control is not properly configured, can expose 2793 system internals to those who should have no access to this 2794 information. 2796 o "replay-support": if access control is not properly configured, 2797 can expose logs to those who should have no access. 2799 Container: "/subscriptions" 2801 o "subscription": different operational teams might have a desire to 2802 set varying subsets of subscriptions. Access control should be 2803 designed to permit read access to just the allowed set. 2805 o "pushed-notifications": will show the amount of events a 2806 particular subscriber actually received from a stream. 2808 o "excluded-notifications": will show the results of access control, 2809 and how many event records have been filtered out. 2811 Some of the RPC operations in this YANG module may be considered 2812 sensitive or vulnerable in some network environments. It is thus 2813 important to control access to these operations. These are the 2814 operations and their sensitivity/vulnerability: 2816 RPC: all 2818 o If a malicious or buggy subscriber sends an unexpectedly large 2819 number of RPCs, the result might be an excessive use of system 2820 resources on the publisher just to determine that these 2821 subscriptions should be declined. In such a situation, 2822 subscription interactions MAY be terminated by terminating the 2823 transport session. 2825 RPC: "delete-subscription" 2826 o No special considerations. 2828 RPC: "establish-subscription" 2830 o Subscriptions could overload a publisher's resources. For this 2831 reason, publishers MUST ensure that they have sufficient resources 2832 to fulfill this request or otherwise reject the request. 2834 RPC: "kill-subscription" 2836 o The "kill-subscription" RPC MUST be secured so that only 2837 connections with administrative rights are able to invoke this 2838 RPC. 2840 RPC: "modify-subscription" 2842 o Subscriptions could overload a publisher's resources. For this 2843 reason, Publishers MUST ensure that they have sufficient resources 2844 to fulfill this request or otherwise reject the request. 2846 For both configured and dynamic subscriptions the publisher MUST 2847 authenticate and authorize a receiver via some transport level 2848 mechanism before sending any updates. 2850 A secure transport is highly recommended and the publisher MUST 2851 ensure that the receiver has sufficient authorization to perform the 2852 function they are requesting against the specific subset of content 2853 involved. 2855 With configured subscriptions, one or more publishers could be used 2856 to overwhelm a receiver. Notification messages SHOULD NOT be sent to 2857 any receiver which does not support this specification. Receivers 2858 that do not want notification messages need only terminate or refuse 2859 any transport sessions from the publisher. 2861 One subscription identifier can be used for two or more receivers of 2862 the same configured subscription. But due to the possibility of 2863 different access control permissions per receiver, it cannot be 2864 assumed that each receiver is getting identical updates. 2866 6. Acknowledgments 2868 For their valuable comments, discussions, and feedback, we wish to 2869 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen, 2870 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan 2871 Hares, Michael Scharf, and Guangying Zheng. 2873 7. References 2875 7.1. Normative References 2877 [I-D.draft-ietf-netmod-revised-datastores] 2878 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2879 and R. Wilton, "Network Management Datastore 2880 Architecture", draft-ietf-netmod-revised-datastores-10 2881 (work in progress), February 2018. 2883 [I-D.draft-ietf-rtgwg-ni-model] 2884 Berger, L., Hopps, C., and A. Lindem, "YANG Network 2885 Instances", draft-ietf-rtgwg-ni-model-06 (work in 2886 progress), January 2018. 2888 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2889 Requirement Levels", BCP 14, RFC 2119, 2890 DOI 10.17487/RFC2119, March 1997, 2891 . 2893 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2894 DOI 10.17487/RFC3688, January 2004, 2895 . 2897 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2898 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2899 . 2901 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2902 the Network Configuration Protocol (NETCONF)", RFC 6020, 2903 DOI 10.17487/RFC6020, October 2010, 2904 . 2906 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2907 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2908 May 2017, . 2910 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2911 Access Control Model", STD 91, RFC 8341, 2912 DOI 10.17487/RFC8341, March 2018, 2913 . 2915 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 2916 Version 1.0", November 1999, 2917 . 2919 7.2. Informative References 2921 [I-D.draft-ietf-netconf-netconf-event-notifications] 2922 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 2923 Nilsen-Nygaard, E., Tripathy, A., Chisholm, S., and H. 2924 Trevino, "NETCONF support for event notifications", 2925 October 2017, . 2928 [I-D.draft-ietf-netconf-restconf-notif] 2929 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 2930 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 2931 HTTP transport for event notifications", January 2018, 2932 . 2935 [I-D.ietf-netconf-yang-push] 2936 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 2937 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 2938 Lengyel, "YANG Datastore Subscription", December 2017, 2939 . 2942 [I-D.ietf-netmod-yang-tree-diagrams] 2943 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 2944 ietf-netmod-yang-tree-diagrams-06 (work in progress), 2945 February 2018. 2947 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2948 (TLS) Protocol Version 1.2", RFC 5246, 2949 DOI 10.17487/RFC5246, August 2008, 2950 . 2952 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2953 and A. Bierman, Ed., "Network Configuration Protocol 2954 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2955 . 2957 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2958 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2959 . 2961 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2962 for Subscription to YANG Datastores", RFC 7923, 2963 DOI 10.17487/RFC7923, June 2016, 2964 . 2966 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2967 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2968 . 2970 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2971 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2972 . 2974 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2975 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2976 . 2978 Appendix A. Changes between revisions 2980 (To be removed by RFC editor prior to publication) 2982 v10 - v11 2984 o access control filtering of events in streams included to match 2985 RFC5277 behavior 2987 o security considerations updated based on YANG template. 2989 o dependency QoS made non-normative on HTTP2 QoS 2991 o tree diagrams referenced for each figure using them 2993 o reference numbers placed into state machine figures 2995 o broke configured replay into its own section 2997 o many tweaks updates based on LC and YANG doctor reviews 2999 o trees and YANG model reconciled were deltas existed 3001 o new feature for interface originated. 3003 o dscp removed from the qos feature 3005 o YANG model updated in a way which collapses groups only used once 3006 so that they are part of the 'subscriptions' container. 3008 o alternative encodings only allowed for transports which support 3009 them. 3011 v09 - v10 3013 o Typos and tweaks 3014 v08 - v09 3016 o NMDA model supported. Non NMDA version at https://github.com/ 3017 netconf-wg/rfc5277bis/ 3019 o Error mechanism revamped to match to embedded implementations. 3021 o Explicitly identified error codes relevant to each RPC/ 3022 Notification 3024 v07 - v08 3026 o Split YANG trees to separate document subsections. 3028 o Clarified configured state machine based on Balazs comments, and 3029 moved it into the configured subscription subsections. 3031 o Normative reference to Network Instance model for VRF 3033 o One transport for all receivers of configured subscriptions. 3035 o QoS section moved in from yang-push 3037 v06 - v07 3039 o Clarification on state machine for configured subscriptions. 3041 v05 - v06 3043 o Made changes proposed by Martin, Kent, and others on the list. 3044 Most significant of these are Stream returned to string (with the 3045 SYSLOG identity removed), intro section on 5277 relationship, an 3046 identity set moved to an enumeration, clean up of definitions/ 3047 terminology, state machine proposed for configured subscriptions 3048 with a clean-up of subscription state options. 3050 o JSON and XML become features. Also Xpath and subtree filtering 3051 become features 3053 o Terminology updates with event records, and refinement of filters 3054 to just stream filters. 3056 o Encoding refined in establish-subscription so it takes the RPC's 3057 encoding as the default. 3059 o Namespaces in examples fixed. 3061 v04 - v05 3062 o Returned to the explicit filter subtyping of v00 3064 o stream object changed to 'name' from 'stream' 3066 o Cleaned up examples 3068 o Clarified that JSON support needs notification-messages draft. 3070 v03 - v04 3072 o Moved back to the use of RFC5277 one-way notifications and 3073 encodings. 3075 v03 - v04 3077 o Replay updated 3079 v02 - v03 3081 o RPCs and Notification support is identified by the Notification 3082 2.0 capability. 3084 o Updates to filtering identities and text 3086 o New error type for unsupportable volume of updates 3088 o Text tweaks. 3090 v01 - v02 3092 o Subscription status moved under receiver. 3094 v00 - v01 3096 o Security considerations updated 3098 o Intro rewrite, as well as scattered text changes 3100 o Added Appendix A, to help match this to related drafts in progress 3102 o Updated filtering definitions, and filter types in yang file, and 3103 moved to identities for filter types 3105 o Added Syslog as a stream 3107 o HTTP2 moved in from YANG-Push as a transport option 3108 o Replay made an optional feature for events. Won't apply to 3109 datastores 3111 o Enabled notification timestamp to have different formats. 3113 o Two error codes added. 3115 v01 5277bis - v00 subscribed notifications 3117 o Kill subscription RPC added. 3119 o Renamed from 5277bis to Subscribed Notifications. 3121 o Changed the notification capabilities version from 1.1 to 2.0. 3123 o Extracted create-subscription and other elements of RFC5277. 3125 o Error conditions added, and made specific in return codes. 3127 o Simplified yang model structure for removal of 'basic' grouping. 3129 o Added a grouping for items which cannot be statically configured. 3131 o Operational counters per receiver. 3133 o Subscription-id and filter-id renamed to identifier 3135 o Section for replay added. Replay now cannot be configured. 3137 o Control plane notification renamed to subscription state 3138 notification 3140 o Source address: Source-vrf changed to string, default address 3141 option added 3143 o In yang model: 'info' changed to 'policy' 3145 o Scattered text clarifications 3147 v00 - v01 of 5277bis 3149 o YANG Model changes. New groupings for subscription info to allow 3150 restriction of what is changeable via RPC. Removed notifications 3151 for adding and removing receivers of configured subscriptions. 3153 o Expanded/renamed definitions from event server to publisher, and 3154 client to subscriber as applicable. Updated the definitions to 3155 include and expand on RFC 5277. 3157 o Removal of redundancy with other drafts 3159 o Many other clean-ups of wording and terminology 3161 Authors' Addresses 3163 Eric Voit 3164 Cisco Systems 3166 Email: evoit@cisco.com 3168 Alexander Clemm 3169 Huawei 3171 Email: ludwig@clemm.org 3173 Alberto Gonzalez Prieto 3174 VMWare 3176 Email: agonzalezpri@vmware.com 3178 Einar Nilsen-Nygaard 3179 Cisco Systems 3181 Email: einarnn@cisco.com 3183 Ambika Prasad Tripathy 3184 Cisco Systems 3186 Email: ambtripa@cisco.com