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