idnits 2.17.1 draft-ietf-netconf-subscribed-notifications-21.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 1310 has weird spacing: '... reason ide...' == Line 1345 has weird spacing: '... reason ide...' == Line 1361 has weird spacing: '...--ro id sub...' == Line 1376 has weird spacing: '...--ro id sub...' == Line 1397 has weird spacing: '...--ro id sub...' == (3 more instances...) -- The document date (January 9, 2019) is 1933 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) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 1 error (**), 0 flaws (~~), 7 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: July 13, 2019 Huawei 6 A. Gonzalez Prieto 7 Microsoft 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 January 9, 2019 13 Subscription to YANG Event Notifications 14 draft-ietf-netconf-subscribed-notifications-21 16 Abstract 18 This document defines a YANG data model and associated mechanisms 19 enabling subscriber-specific subscriptions to a publisher's event 20 streams. Applying these elements allows a subscriber to request for 21 and receive a continuous, custom feed of publisher generated 22 information. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on July 13, 2019. 41 Copyright Notice 43 Copyright (c) 2019 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 5 62 1.4. Relationship to RFC 5277 . . . . . . . . . . . . . . . . 6 63 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 7 65 2.2. Event Stream Filters . . . . . . . . . . . . . . . . . . 8 66 2.3. QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 2.4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 9 68 2.5. Configured Subscriptions . . . . . . . . . . . . . . . . 17 69 2.6. Event Record Delivery . . . . . . . . . . . . . . . . . . 24 70 2.7. subscription state change notifications . . . . . . . . . 25 71 2.8. Subscription Monitoring . . . . . . . . . . . . . . . . . 31 72 2.9. Advertisement . . . . . . . . . . . . . . . . . . . . . . 32 73 3. YANG Data Model Trees . . . . . . . . . . . . . . . . . . . . 32 74 3.1. Event Streams Container . . . . . . . . . . . . . . . . . 32 75 3.2. Filters Container . . . . . . . . . . . . . . . . . . . . 33 76 3.3. Subscriptions Container . . . . . . . . . . . . . . . . . 33 77 4. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 35 78 5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 62 79 5.1. IANA Considerations . . . . . . . . . . . . . . . . . . . 62 80 5.2. Implementation Considerations . . . . . . . . . . . . . . 63 81 5.3. Transport Requirements . . . . . . . . . . . . . . . . . 63 82 5.4. Security Considerations . . . . . . . . . . . . . . . . . 64 83 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 68 84 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 85 7.1. Normative References . . . . . . . . . . . . . . . . . . 68 86 7.2. Informative References . . . . . . . . . . . . . . . . . 70 87 Appendix A. Example Configured Transport Augmentation . . . . . 71 88 Appendix B. Changes between revisions . . . . . . . . . . . . . 72 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 77 91 1. Introduction 93 This document defines a YANG data model and associated mechanisms 94 enabling subscriber-specific subscriptions to a publisher's event 95 streams. Effectively this enables a 'subscribe then publish' 96 capability where the customized information needs and access 97 permissions of each target receiver are understood by the publisher 98 before subscribed event records are marshaled and pushed. The 99 receiver then gets a continuous, custom feed of publisher generated 100 information. 102 While the functionality defined in this document is transport- 103 agnostic, transports like NETCONF [RFC6241] or RESTCONF [RFC8040] can 104 be used to configure or dynamically signal subscriptions, and there 105 are bindings defined for subscribed event record delivery for NETCONF 106 within [I-D.draft-ietf-netconf-netconf-event-notifications], and for 107 RESTCONF within [I-D.draft-ietf-netconf-restconf-notif]. 109 The YANG model in this document conforms to the Network Management 110 Datastore Architecture defined in [RFC8342]. 112 1.1. Motivation 114 Various limitations in [RFC5277] are discussed in [RFC7923]. 115 Resolving these issues is the primary motivation for this work. Key 116 capabilities supported by this document include: 118 o multiple subscriptions on a single transport session 120 o support for dynamic and configured subscriptions 122 o modification of an existing subscription in progress 124 o per-subscription operational counters 126 o negotiation of subscription parameters (through the use of hints 127 returned as part of declined subscription requests) 129 o subscription state change notifications (e.g., publisher driven 130 suspension, parameter modification) 132 o independence from transport 134 1.2. Terminology 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 138 "OPTIONAL" in this document are to be interpreted as described in BCP 139 14 [RFC2119] [RFC8174] when, and only when, they appear in all 140 capitals, as shown here. 142 Client: defined in [RFC8342]. 144 Configuration: defined in [RFC8342]. 146 Configuration datastore: defined in [RFC8342]. 148 Configured subscription: A subscription installed via configuration 149 into a configuration datastore. 151 Dynamic subscription: A subscription created dynamically by a 152 subscriber via a remote procedure call. 154 Event: An occurrence of something that may be of interest. Examples 155 include a configuration change, a fault, a change in status, crossing 156 a threshold, or an external input to the system. 158 Event occurrence time: a timestamp matching the time an originating 159 process identified as when an event happened. 161 Event record: A set of information detailing an event. 163 Event stream: A continuous, chronologically ordered set of events 164 aggregated under some context. 166 Event stream filter: Evaluation criteria which may be applied against 167 event records within an event stream. Event records pass the filter 168 when specified criteria are met. 170 Notification message: Information intended for a receiver indicating 171 that one or more events have occurred. 173 Publisher: An entity responsible for streaming notification messages 174 per the terms of a subscription. 176 Receiver: A target to which a publisher pushes subscribed event 177 records. For dynamic subscriptions, the receiver and subscriber are 178 the same entity. 180 Subscriber: A client able to request and negotiate a contract for the 181 generation and push of event records from a publisher. For dynamic 182 subscriptions, the receiver and subscriber are the same entity. 184 Subscription: A contract with a publisher, stipulating which 185 information one or more receivers wish to have pushed from the 186 publisher without the need for further solicitation. 188 All YANG tree diagrams used in this document follow the notation 189 defined in [RFC8340]. 191 1.3. Solution Overview 193 This document describes a transport agnostic mechanism for 194 subscribing to and receiving content from an event stream within a 195 publisher. This mechanism is through the use of a subscription. 197 Two types of subscriptions are supported: 199 1. Dynamic subscriptions, where a subscriber initiates a 200 subscription negotiation with a publisher via an RPC. If the 201 publisher is able to serve this request, it accepts it, and then 202 starts pushing notification messages back to the subscriber. If 203 the publisher is not able to serve it as requested, then an error 204 response is returned. This response MAY include hints at 205 subscription parameters that, had they been present, may have 206 enabled the dynamic subscription request to be accepted. 208 2. Configured subscriptions, which allow the management of 209 subscriptions via a configuration so that a publisher can send 210 notification messages to a receiver. Support for configured 211 subscriptions is optional, with its availability advertised via a 212 YANG feature. 214 Additional characteristics differentiating configured from dynamic 215 subscriptions include: 217 o The lifetime of a dynamic subscription is bound by the transport 218 session used to establish it. For connection-oriented stateful 219 transports like NETCONF, the loss of the transport session will 220 result in the immediate termination of any associated dynamic 221 subscriptions. For connectionless or stateless transports like 222 HTTP, a lack of receipt acknowledgment of a sequential set of 223 notification messages and/or keep-alives can be used to trigger a 224 termination of a dynamic subscription. Contrast this to the 225 lifetime of a configured subscription. This lifetime is driven by 226 relevant configuration being present within the publisher's 227 applied configuration. Being tied to configuration operations 228 implies configured subscriptions can be configured to persist 229 across reboots, and implies a configured subscription can persist 230 even when its publisher is fully disconnected from any network. 232 o Configured subscriptions can be modified by any configuration 233 client with write permission on the configuration of the 234 subscription. Dynamic subscriptions can only be modified via an 235 RPC request made by the original subscriber, or a change to 236 configuration data referenced by the subscription. 238 Note that there is no mixing-and-matching of dynamic and configured 239 operations on a single subscription. Specifically, a configured 240 subscription cannot be modified or deleted using RPCs defined in this 241 document. Similarly, a dynamic subscription cannot be directly 242 modified or deleted by configuration operations. It is however 243 possible to perform a configuration operation which indirectly 244 impacts a dynamic subscription. By changing value of a pre- 245 configured filter referenced by an existing dynamic subscription, the 246 selected event records passed to a receiver might change. 248 Also note that transport specific transport drafts based on this 249 specification MUST detail the life cycle of dynamic subscriptions, as 250 well as the lifecycle of configured subscriptions (if supported). 252 A publisher MAY terminate a dynamic subscription at any time. 253 Similarly, it MAY decide to temporarily suspend the sending of 254 notification messages for any dynamic subscription, or for one or 255 more receivers of a configured subscription. Such termination or 256 suspension is driven by internal considerations of the publisher. 258 1.4. Relationship to RFC 5277 260 This document is intended to provide a superset of the subscription 261 capabilities initially defined within [RFC5277]. Especially when 262 extending an existing [RFC5277] implementation, it is important to 263 understand what has been reused and what has been replaced. Key 264 relationships between these two documents include: 266 o this document defines a transport independent capability, 267 [RFC5277] is specific to NETCONF. 269 o the data model in this document is used instead of the data model 270 in Section 3.4 of [RFC5277] for the new operations. 272 o the RPC operations in this draft replace the operation "create- 273 subscription" defined in [RFC5277], section 4. 275 o the message of [RFC5277], Section 4 is used. 277 o the included contents of the "NETCONF" event stream are identical 278 between this document and [RFC5277]. 280 o a publisher MAY implement both the Notification Management Schema 281 and RPCs defined in [RFC5277] and this new document concurrently. 283 o unlike [RFC5277], this document enables a single transport session 284 to intermix notification messages and RPCs for different 285 subscriptions. 287 2. Solution 289 Per the overview provided in Section 1.3, this section details the 290 overall context, state machines, and subsystems which may be 291 assembled to allow the subscription of events from a publisher. 293 2.1. Event Streams 295 An event stream is a named entity on a publisher which exposes a 296 continuously updating set of YANG encoded event records. An event 297 record is an intantiation of a "notification" YANG statement. If the 298 "notification" is defined as a child to a data node, the intantiation 299 includes the hierarchy of nodes that identifies the data node in the 300 datastore (see Section 7.16.2 of [RFC7950]). Each event stream is 301 available for subscription. It is out of the scope of this document 302 to identify a) how event streams are defined (other than the NETCONF 303 stream), b) how event records are defined/generated, and c) how event 304 records are assigned to event streams. 306 There is only one reserved event stream name within this document: 307 "NETCONF". The "NETCONF" event stream contains all NETCONF event 308 record information supported by the publisher, except where an event 309 record has explicitly been excluded from the stream. Beyond the 310 "NETCONF" stream, implementations MAY define additional event 311 streams. 313 As YANG encoded event records are created by a system, they may be 314 assigned to one or more streams. The event record is distributed to 315 a subscription's receiver(s) where: (1) a subscription includes the 316 identified stream, and (2) subscription filtering does not exclude 317 the event record from that receiver. 319 Access control permissions may be used to silently exclude event 320 records from within an event stream for which the receiver has no 321 read access. As an example of how this might be accomplished, see 322 [RFC8341] section 3.4.6. Note that per Section 2.7 of this document, 323 subscription state change notifications are never filtered out. 325 If no access control permissions are in place for event records on an 326 event stream, then a receiver MUST be allowed access to all the event 327 records. If subscriber permissions change during the lifecycle of a 328 subscription and event stream access is no longer permitted, then the 329 subscription MUST be terminated. 331 Event records MUST NOT be delivered to a receiver in a different 332 order than they were placed onto an event stream. 334 2.2. Event Stream Filters 336 This document defines an extensible filtering mechanism. The filter 337 itself is a boolean test which is placed on the content of an event 338 record. A 'false' filtering result causes the event message to be 339 excluded from delivery to a receiver. A filter never results in 340 information being stripped from within an event record prior to that 341 event record being encapsulated within a notification message. The 342 two optional event stream filtering syntaxes supported are [XPATH] 343 and subtree [RFC6241]. 345 If no event stream filter is provided within a subscription, all 346 event records on an event stream are to be sent. 348 2.3. QoS 350 This document provide for several QoS parameters. These parameters 351 indicate the treatment of a subscription relative to other traffic 352 between publisher and receiver. Included are: 354 o A "dscp" marking to differentiate prioritization of notification 355 messages during network transit. 357 o A "weighting" so that bandwidth proportional to this weighting can 358 be allocated to this subscription relative to other subscriptions. 360 o a "dependency" upon another subscription. 362 If the publisher supports the "dscp" feature, then a subscription 363 with a "dscp" leaf MUST result in a corresponding [RFC2474] DSCP 364 marking being placed within the IP header of any resulting 365 notification messages and subscription state change notifications. 367 For the "weighting" parameter, when concurrently dequeuing 368 notification messages from multiple subscriptions to a receiver, the 369 publisher MUST allocate bandwidth to each subscription proportionally 370 to the weights assigned to those subscriptions. "Weighting" is an 371 optional capability of the publisher; support for it is identified 372 via the "qos" feature. 374 If a subscription has the "dependency" parameter set, then any 375 buffered notification messages containing event records selected by 376 the parent subscription MUST be dequeued prior to the notification 377 messages of the dependent subscription. If notification messages 378 have dependencies on each other, the notification message queued the 379 longest MUST go first. If a "dependency" included within an RPC 380 references a subscription which does not exist or is no longer 381 accessible to that subscriber, that "dependency" MUST be silently 382 removed. "Dependency" is an optional capability of the publisher; 383 support for it is identified via the "qos" feature. 385 2.4. Dynamic Subscriptions 387 Dynamic subscriptions are managed via protocol operations (in the 388 form of [RFC7950], Section 7.14 RPCs) made against targets located 389 within the publisher. These RPCs have been designed extensibly so 390 that they may be augmented for subscription targets beyond event 391 streams. For examples of such augmentations, see the RPC 392 augmentations within [I-D.ietf-netconf-yang-push]'s YANG model. 394 2.4.1. Dynamic Subscription State Model 396 Below is the publisher's state machine for a dynamic subscription. 397 Each state is shown in its own box. It is important to note that 398 such a subscription doesn't exist at the publisher until an 399 "establish-subscription" RPC is accepted. The mere request by a 400 subscriber to establish a subscription is insufficient for that 401 subscription to be externally visible. Start and end states are 402 depicted to reflect subscription creation and deletion events. 404 ......... 405 : start : 406 :.......: 407 | 408 establish-subscription 409 | 410 | .-------modify-subscription--------. 411 v v | 412 .-----------. .-----------. 413 .--------. | receiver |--insufficient CPU, b/w-->| receiver | 414 modify- '| active | | suspended | 415 subscription | |<----CPU, b/w sufficient--| | 416 ---------->'-----------' '-----------' 417 | | 418 delete/kill-subscription delete/kill- 419 | subscription 420 v | 421 ......... | 422 : end :<---------------------------------' 423 :.......: 425 Figure 1: Publisher's state for a dynamic subscription 427 Of interest in this state machine are the following: 429 o Successful "establish-subscription" or "modify-subscription" RPCs 430 put the subscription into the active state. 432 o Failed "modify-subscription" RPCs will leave the subscription in 433 its previous state, with no visible change to any streaming 434 updates. 436 o A "delete-subscription" or "kill-subscription" RPC will end the 437 subscription, as will the reaching of a "stop-time". 439 o A publisher may choose to suspend a subscription when there is 440 insufficient CPU or bandwidth available to service the 441 subscription. This is notified to a subscriber with a 442 "subscription-suspended" subscription state change notification. 444 o A suspended subscription may be modified by the subscriber (for 445 example in an attempt to use fewer resources). Successful 446 modification returns the subscription to the active state. 448 o Even without a "modify-subscription" request, a publisher may 449 return a subscription to the active state should the resource 450 constraints become sufficient again. This is announced to the 451 subscriber via the "subscription-resumed" subscription state 452 change notification. 454 2.4.2. Establishing a Dynamic Subscription 456 The "establish-subscription" RPC allows a subscriber to request the 457 creation of a subscription. 459 The input parameters of the operation are: 461 o A "stream" name which identifies the targeted event stream against 462 which the subscription is applied. 464 o An event stream filter which may reduce the set of event records 465 pushed. 467 o Where the transport used by the RPC supports multiple encodings, 468 an optional "encoding" for the event records pushed. If no 469 "encoding" is included, the encoding of the RPC MUST be used. 471 o An optional "stop-time" for the subscription. If no "stop-time" 472 is present, notification messages will continue to be sent until 473 the subscription is terminated. 475 o An optional "replay-start-time" for the subscription. The 476 "replay-start-time" MUST be in the past and indicates that the 477 subscription is requesting a replay of previously generated 478 information from the event stream. For more on replay, see 479 Section 2.4.2.1. Where there is no "replay-start-time", the 480 subscription starts immediately. 482 If the publisher can satisfy the "establish-subscription" request, it 483 replies with an identifier for the subscription, and then immediately 484 starts streaming notification messages. 486 Below is a tree diagram for "establish-subscription". All objects 487 contained in this tree are described within the included YANG model 488 within Section 4. 490 +---x establish-subscription 491 +---w input 492 | +---w (target) 493 | | +--:(stream) 494 | | +---w (stream-filter)? 495 | | | +--:(by-reference) 496 | | | | +---w stream-filter-name 497 | | | | stream-filter-ref 498 | | | +--:(within-subscription) 499 | | | +---w (filter-spec)? 500 | | | +--:(stream-subtree-filter) 501 | | | | +---w stream-subtree-filter? 502 | | | | {subtree}? 503 | | | +--:(stream-xpath-filter) 504 | | | +---w stream-xpath-filter? 505 | | | yang:xpath1.0 {xpath}? 506 | | +---w stream stream-ref 507 | | +---w replay-start-time? 508 | | yang:date-and-time {replay}? 509 | +---w stop-time? 510 | | yang:date-and-time 511 | +---w dscp? inet:dscp 512 | | {dscp}? 513 | +---w weighting? uint8 514 | | {qos}? 515 | +---w dependency? 516 | | subscription-id {qos}? 517 | +---w encoding? encoding 518 +--ro output 519 +--ro id subscription-id 520 +--ro replay-start-time-revision? yang:date-and-time 521 {replay}? 523 Figure 2: establish-subscription RPC tree diagram 525 A publisher MAY reject the "establish-subscription" RPC for many 526 reasons as described in Section 2.4.6. The contents of the resulting 527 RPC error response MAY include details on input parameters which if 528 considered in a subsequent "establish-subscription" RPC, may result 529 in a successful subscription establishment. Any such hints MUST be 530 transported within a yang-data "establish-subscription-stream-error- 531 info" container included within the RPC error response. 533 yang-data establish-subscription-stream-error-info 534 +--ro establish-subscription-stream-error-info 535 +--ro reason? identityref 536 +--ro filter-failure-hint? string 538 Figure 3: establish-subscription RPC yang-data tree diagram 540 2.4.2.1. Requesting a replay of event records 542 Replay provides the ability to establish a subscription which is also 543 capable of passing recently generated event records. In other words, 544 as the subscription initializes itself, it sends any event records 545 within the target event stream which meet the filter criteria, which 546 have an event time which is after the "replay-start-time", and which 547 have an event time before the "stop-time" should this "stop-time" 548 exist. The end of these historical event records is identified via a 549 "replay-completed" subscription state change notification. Any event 550 records generated since the subscription establishment may then 551 follow. For a particular subscription, all event records will be 552 delivered in the order they are placed into the event stream. 554 Replay is an optional feature which is dependent on an event stream 555 supporting some form of logging. This document puts no restrictions 556 on the size or form of the log, where it resides within the 557 publisher, or when event record entries in the log are purged. 559 The inclusion of a "replay-start-time" within an "establish- 560 subscription" RPC indicates a replay request. If the "replay-start- 561 time" contains a value that is earlier than what a publisher's 562 retained history supports, then if the subscription is accepted, the 563 actual publisher's revised start time MUST be set in the returned 564 "replay-start-time-revision" object. 566 A "stop-time" parameter may be included in a replay subscription. 567 For a replay subscription, the "stop-time" MAY be earlier than the 568 current time, but MUST be later than the "replay-start-time". 570 If the given "replay-start-time" is later than the time marked within 571 any event records retained within the replay buffer, then the 572 publisher MUST send a "replay-completed" notification immediately 573 after a successful establish-subscription RPC response. 575 If an event stream supports replay, the "replay-support" leaf is 576 present in the "/streams/stream" list entry for the event stream. An 577 event stream that does support replay is not expected to have an 578 unlimited supply of saved notifications available to accommodate any 579 given replay request. To assess the timeframe available for replay, 580 subscribers can read the leafs "replay-log-creation-time" and 581 "replay-log-aged-time". See Figure 18 for the YANG tree, and 582 Section 4 for the YANG model describing these elements. The actual 583 size of the replay log at any given time is a publisher specific 584 matter. Control parameters for the replay log are outside the scope 585 of this document. 587 2.4.3. Modifying a Dynamic Subscription 589 The "modify-subscription" operation permits changing the terms of an 590 existing dynamic subscription. Dynamic subscriptions can be modified 591 any number of times. Dynamic subscriptions can only be modified via 592 this RPC using a transport session connecting to the subscriber. If 593 the publisher accepts the requested modifications, it acknowledges 594 success to the subscriber, then immediately starts sending event 595 records based on the new terms. 597 Subscriptions created by configuration cannot be modified via this 598 RPC. However configuration may be used to modify objects referenced 599 by the subscription (such as a referenced filter). 601 Below is a tree diagram for "modify-subscription". All objects 602 contained in this tree are described within the included YANG model 603 within Section 4. 605 +---x modify-subscription 606 +---w input 607 +---w id 608 | subscription-id 609 +---w (target) 610 | +--:(stream) 611 | +---w (stream-filter)? 612 | +--:(by-reference) 613 | | +---w stream-filter-name 614 | | stream-filter-ref 615 | +--:(within-subscription) 616 | +---w (filter-spec)? 617 | +--:(stream-subtree-filter) 618 | | +---w stream-subtree-filter? 619 | | {subtree}? 620 | +--:(stream-xpath-filter) 621 | +---w stream-xpath-filter? 622 | yang:xpath1.0 {xpath}? 623 +---w stop-time? 624 yang:date-and-time 626 Figure 4: modify-subscription RPC tree diagram 628 If the publisher accepts the requested modifications on a currently 629 suspended subscription, the subscription will immediately be resumed 630 (i.e., the modified subscription is returned to the active state.) 631 The publisher MAY immediately suspend this newly modified 632 subscription through the "subscription-suspended" notification before 633 any event records are sent. 635 If the publisher rejects the RPC request, the subscription remains as 636 prior to the request. That is, the request has no impact whatsoever. 637 Rejection of the RPC for any reason is indicated by via RPC error as 638 described in Section 2.4.6. The contents of such a rejected RPC MAY 639 include hints on inputs which (if considered) may result in a 640 successfully modified subscription. These hints MUST be transported 641 within a yang-data "modify-subscription-stream-error-info" container 642 inserted into the RPC error response. 644 Below is a tree diagram for "modify-subscription-RPC-yang-data". All 645 objects contained in this tree are described within the included YANG 646 model within Section 4. 648 yang-data modify-subscription-stream-error-info 649 +--ro modify-subscription-stream-error-info 650 +--ro reason? identityref 651 +--ro filter-failure-hint? string 653 Figure 5: modify-subscription RPC yang-data tree diagram 655 2.4.4. Deleting a Dynamic Subscription 657 The "delete-subscription" operation permits canceling an existing 658 subscription. If the publisher accepts the request, and the 659 publisher has indicated success, the publisher MUST NOT send any more 660 notification messages for this subscription. 662 Below is a tree diagram for "delete-subscription". All objects 663 contained in this tree are described within the included YANG model 664 within Section 4. 666 +---x delete-subscription 667 +---w input 668 +---w id subscription-id 670 Figure 6: delete-subscription RPC tree diagram 672 Dynamic subscriptions can only be deleted via this RPC using a 673 transport session connecting to the subscriber. Configured 674 subscriptions cannot be deleted using RPCs. 676 2.4.5. Killing a Dynamic Subscription 678 The "kill-subscription" operation permits an operator to end a 679 dynamic subscription which is not associated with the transport 680 session used for the RPC. A publisher MUST terminate any dynamic 681 subscription identified by the "id" parameter in the RPC request, if 682 such a subscription exists. 684 Configured subscriptions cannot be killed using this RPC. Instead, 685 configured subscriptions are deleted as part of regular configuration 686 operations. Publishers MUST reject any RPC attempt to kill a 687 configured subscription. 689 Below is a tree diagram for "kill-subscription". All objects 690 contained in this tree are described within the included YANG model 691 within Section 4. 693 +---x kill-subscription 694 +---w input 695 +---w id subscription-id 697 Figure 7: kill-subscription RPC tree diagram 699 2.4.6. RPC Failures 701 Whenever an RPC is unsuccessful, the publisher returns relevant 702 information as part of the RPC error response. Transport level error 703 processing MUST be done before RPC error processing described in this 704 section. In all cases, RPC error information returned will use 705 existing transport layer RPC structures, such as those seen with 706 NETCONF in [RFC6241] Appendix A, or with RESTCONF in [RFC8040] 707 Section 7.1. These structures MUST be able to encode subscription 708 specific errors identified below and defined within this document's 709 YANG model. 711 As a result of this mixture, how subscription errors are encoded 712 within an RPC error response is transport dependent. Following are 713 valid errors which can occur for each RPC: 715 establish-subscription modify-subscription 716 ---------------------- ------------------- 717 dscp-unavailable filter-unsupported 718 encoding-unsupported insufficient-resources 719 filter-unsupported no-such-subscription 720 insufficient-resources 721 replay-unsupported 723 delete-subscription kill-subscription 724 ---------------------- ---------------------- 725 no-such-subscription no-such-subscription 727 To see a NETCONF based example of an error response from above, see 728 [I-D.draft-ietf-netconf-netconf-event-notifications], Figure 10. 730 There is one final set of transport independent RPC error elements 731 included in the YANG model. These are three yang-data structures 732 which enable the publisher to provide to the receiver that error 733 information which does not fit into existing transport layer RPC 734 structures. These three yang-data structures are: 736 1. "establish-subscription-stream-error-info": This MUST be returned 737 with the leaf "reason" populated if an RPC error reason has not 738 been placed elsewhere within the transport portion of a failed 739 "establish-subscription" RPC response. This MUST be sent if 740 hints on how to overcome the RPC error are included. 742 2. "modify-subscription-stream-error-info": This MUST be returned 743 with the leaf "reason" populated if an RPC error reason has not 744 been placed elsewhere within the transport portion of a failed 745 "modify-subscription" RPC response. This MUST be sent if hints 746 on how to overcome the RPC error are included. 748 3. "delete-subscription-error-info": This MUST be returned with the 749 leaf "reason" populated if an RPC error reason has not been 750 placed elsewhere within the transport portion of a failed 751 "delete-subscription" or "kill-subscription" RPC response. 753 2.5. Configured Subscriptions 755 A configured subscription is a subscription installed via 756 configuration. Configured subscriptions may be modified by any 757 configuration client with the proper permissions. Subscriptions can 758 be modified or terminated via configuration at any point of their 759 lifetime. Multiple configured subscriptions MUST be supportable over 760 a single transport session. 762 Configured subscriptions have several characteristics distinguishing 763 them from dynamic subscriptions: 765 o persistence across publisher reboots, 767 o persistence even when transport is unavailable, and 769 o an ability to send notification messages to more than one receiver 770 (note that receivers are unaware of the existence of any other 771 receivers.) 773 On the publisher, supporting configured subscriptions is optional and 774 advertised using the "configured" feature. On a receiver of a 775 configured subscription, support for dynamic subscriptions is 776 optional except where replaying missed event records is required. 778 In addition to the subscription parameters available to dynamic 779 subscriptions described in Section 2.4.2, the following additional 780 parameters are also available to configured subscriptions: 782 o A "transport" which identifies the transport protocol to use to 783 connect with all subscription receivers. 785 o One or more receivers, each intended as the destination for event 786 records. Note that each individual receiver is identifiable by 787 its "name". 789 o Optional parameters to identify where traffic should egress a 790 publisher: 792 * A "source-interface" which identifies the egress interface to 793 use from the publisher. Publisher support for this is optional 794 and advertised using the "interface-designation" feature. 796 * A "source-address" address, which identifies the IP address to 797 stamp on notification messages destined for the receiver. 799 * A "source-vrf" which identifies the VRF on which to reach 800 receivers. This VRF is a network instance as defined within 801 [I-D.draft-ietf-rtgwg-ni-model]. Publisher support for VRFs is 802 optional and advertised using the "supports-vrf" feature. 804 If none of the above parameters are set, notification messages 805 MUST egress the publisher's default interface. 807 A tree diagram describing these parameters is shown in Figure 20 808 within Section 3.3. All parameters are described within the YANG 809 model in Section 4. 811 2.5.1. Configured Subscription State Model 813 Below is the state machine for a configured subscription on the 814 publisher. This state machine describes the three states (valid, 815 invalid, and concluded), as well as the transitions between these 816 states. Start and end states are depicted to reflect configured 817 subscription creation and deletion events. The creation or 818 modification of a configured subscription initiates an evaluation by 819 the publisher to determine if the subscription is in valid or invalid 820 states. The publisher uses its own criteria in making this 821 determination. If in the valid state, the subscription becomes 822 operational. See (1) in the diagram below. 824 ......... 825 : start :-. 826 :.......: | 827 create .---modify-----.----------------------------------. 828 | | | | 829 V V .-------. ....... .---------. 830 .----[evaluate]--no--->|invalid|-delete->: end :<-delete-|concluded| 831 | '-------' :.....: '---------' 832 |-[evaluate]--no-(2). ^ ^ ^ 833 | ^ | | | | 834 yes | '->unsupportable delete stop-time 835 | modify (subscription- (subscription- (subscription- 836 | | terminated*) terminated*) concluded*) 837 | | | | | 838 (1) | (3) (4) (5) 839 | .---------------------------------------------------------------. 840 '-->| valid | 841 '---------------------------------------------------------------' 843 Legend: 844 dotted boxes: subscription added or removed via configuration 845 dashed boxes: states for a subscription 846 [evaluate]: decision point on whether the subscription is supportable 847 (*): resulting subscription state change notification 849 Figure 8: Publisher state model for a configured subscription 851 A subscription in the valid state may move to the invalid state in 852 one of two ways. First, it may be modified in a way which fails a 853 re-evaluation. See (2) in the diagram. Second, the publisher might 854 determine that the subscription is no longer supportable. This could 855 be for reasons of an unexpected but sustained increase in an event 856 stream's event records, degraded CPU capacity, a more complex 857 referenced filter, or other higher priority subscriptions which have 858 usurped resources. See (3) in the diagram. No matter the case, a 859 "subscription-terminated" notification is sent to any receivers in an 860 active or suspended state. A subscription in the valid state may 861 also transition to the concluded state via (5) if a configured stop 862 time has been reached. In this case, a "subscription-concluded" 863 notification is sent to any receivers in active or suspended states. 864 Finally, a subscription may be deleted by configuration (4). 866 When a subscription is in the valid state, a publisher will attempt 867 to connect with all receivers of a configured subscription and 868 deliver notification messages. Below is the state machine for each 869 receiver of a configured subscription. This receiver state machine 870 is fully contained within the state machine of the configured 871 subscription, and is only relevant when the configured subscription 872 is in the valid state. 874 .-----------------------------------------------------------------. 875 | valid | 876 | .----------. .------------. | 877 | | receiver |---timeout---------------->| receiver | | 878 | |connecting|<----------------reset--(c)|disconnected| | 879 | | |<-transport '------------' | 880 | '----------' loss,reset------------------------------. | 881 | (a) | | | 882 | subscription- (b) (b) | 883 | started* .--------. .---------. | 884 | '----->| |(d)-insufficient CPU,------->| | | 885 | |receiver| buffer overflow |receiver | | 886 | subscription-| active | |suspended| | 887 | modified* | |<----CPU, b/w sufficient,-(e)| | | 888 | '---->'--------' subscription-modified* '---------' | 889 '-----------------------------------------------------------------' 891 Legend: 892 dashed boxes which include the word 'receiver' show the possible 893 states for an individual receiver of a valid configured subscription. 894 * indicates a subscription state change notification 896 Figure 9: Receiver state for a configured subscription on a Publisher 898 When a configured subscription first moves to the valid state, the 899 "state" leaf of each receiver is initialized to the connecting state. 900 If transport connectivity is not available to any receiver and there 901 are any notification messages to deliver, a transport session is 902 established (e.g., through [RFC8071]). Individual receivers are 903 moved to the active state when a "subscription-started" subscription 904 state change notification is successfully passed to that receiver 905 (a). Event records are only sent to active receivers. Receivers of 906 a configured subscription remain active if both transport 907 connectivity can be verified to the receiver, and event records are 908 not being dropped due to a publisher buffer overflow. The result is 909 that a receiver will remain active on the publisher as long as events 910 aren't being lost, or the receiver cannot be reached. In addition, a 911 configured subscription's receiver MUST be moved to the connecting 912 state if the receiver is reset via the "reset" action (b), (c). For 913 more on reset, see Section 2.5.5. If transport connectivity cannot 914 be achieved while in the connecting state, the receiver MAY be moved 915 to the disconnected state. 917 A configured subscription's receiver MUST be moved to the suspended 918 state if there is transport connectivity between the publisher and 919 receiver, but notification messages are failing to be delivered due 920 to publisher buffer overflow, or notification messages are not able 921 to be generated for that receiver due to insufficient CPU (d). This 922 is indicated to the receiver by the "subscription-suspended" 923 subscription state change notification. 925 A configured subscription receiver MUST be returned to the active 926 state from the suspended state when notification messages are able to 927 be generated, bandwidth is sufficient to handle the notification 928 messages, and a receiver has successfully been sent a "subscription- 929 resumed" or "subscription-modified" subscription state change 930 notification (e). The choice as to which of these two subscription 931 state change notifications is sent is determined by whether the 932 subscription was modified during the period of suspension. 934 Modification of a configured subscription is possible at any time. A 935 "subscription-modified" subscription state change notification will 936 be sent to all active receivers, immediately followed by notification 937 messages conforming to the new parameters. Suspended receivers will 938 also be informed of the modification. However this notification will 939 await the end of the suspension for that receiver (e). 941 The mechanisms described above are mirrored in the RPCs and 942 notifications within the document. It should be noted that these 943 RPCs and notifications have been designed to be extensible and allow 944 subscriptions into targets other than event streams. For instance, 945 the YANG module defined in Section 5 of [I-D.ietf-netconf-yang-push] 946 augments "/sn:modify-subscription/sn:input/sn:target". 948 2.5.2. Creating a Configured Subscription 950 Configured subscriptions are established using configuration 951 operations against the top-level "subscriptions" subtree. 953 Because there is no explicit association with an existing transport 954 session, configuration operations MUST include additional parameters 955 beyond those of dynamic subscriptions. These parameters identify 956 each receiver, how to connect with that receiver, and possibly 957 whether the notification messages need to come from a specific egress 958 interface on the publisher. Receiver specific transport connectivity 959 parameters MUST be configured via transport specific augmentations to 960 this specification. See Section 2.5.7 for details. 962 After a subscription is successfully established, the publisher 963 immediately sends a "subscription-started" subscription state change 964 notification to each receiver. It is quite possible that upon 965 configuration, reboot, or even steady-state operations, a transport 966 session may not be currently available to the receiver. In this 967 case, when there is something to transport for an active 968 subscription, transport specific call-home operations will be used to 969 establish the connection. When transport connectivity is available, 970 notification messages may then be pushed. 972 With active configured subscriptions, it is allowable to buffer event 973 records even after a "subscription-started" has been sent. However 974 if events are lost (rather than just delayed) due to replay buffer 975 overflow, a new "subscription-started" must be sent. This new 976 "subscription-started" indicates an event record discontinuity. 978 To see an example of subscription creation using configuration 979 operations over NETCONF, see Appendix A of 980 [I-D.draft-ietf-netconf-netconf-event-notifications]. 982 2.5.3. Modifying a Configured Subscription 984 Configured subscriptions can be modified using configuration 985 operations against the top-level "subscriptions" subtree. 987 If the modification involves adding receivers, added receivers are 988 placed in the connecting state. If a receiver is removed, the 989 subscription state change notification "subscription-terminated" is 990 sent to that receiver if that receiver is active or suspended. 992 If the modification involves changing the policies for the 993 subscription, the publisher sends to currently active receivers a 994 "subscription-modified" notification. For any suspended receivers, a 995 "subscription-modified" notification will be delayed until the 996 receiver is resumed. (Note: in this case, the "subscription- 997 modified" notification informs the receiver that the subscription has 998 been resumed, so no additional "subscription-resumed" need be sent. 999 Also note that if multiple modifications have occurred during the 1000 suspension, only the "subscription-modified" notification describing 1001 the latest one need be sent to the receiver.) 1003 2.5.4. Deleting a Configured Subscription 1005 Subscriptions can be deleted through configuration against the top- 1006 level "subscriptions" subtree. 1008 Immediately after a subscription is successfully deleted, the 1009 publisher sends to all receivers of that subscription a subscription 1010 state change notification stating the subscription has ended (i.e., 1011 "subscription-terminated"). 1013 2.5.5. Resetting a Configured Subscription Receiver 1015 It is possible that a configured subscription to a receiver needs to 1016 be reset. This is accomplished via the "reset" action within the 1017 YANG model at "/subscriptions/subscription/receivers/receiver/reset". 1018 This action may be useful in cases where a publisher has timed out 1019 trying to reach a receiver. When such a reset occurs, a transport 1020 session will be initiated if necessary, and a new "subscription- 1021 started" notification will be sent. This action does not have any 1022 effect on transport connectivity if the needed connectivity already 1023 exists. 1025 2.5.6. Replay for a Configured Subscription 1027 It is possible to do replay on a configured subscription. This is 1028 supported via the configuration of the "configured-replay" object on 1029 the subscription. The setting of this object enables the streaming 1030 of the buffered event records for the subscribed event stream. All 1031 buffered event records which have been retained since the last 1032 publisher restart will be sent to each configured receiver. 1034 Replay of events records created since restart is useful. It allows 1035 event records generated before transport connectivity establishment 1036 to be passed to a receiver. Setting the restart time as the earliest 1037 configured replay time precludes possibility of resending of event 1038 records logged prior to publisher restart. It also ensures the same 1039 records will be sent to each configured receiver, regardless of the 1040 speed of transport connectivity establishment to each receiver. 1041 Finally, establishing restart as the earliest potential time for 1042 event records to be included within notification messages, a well- 1043 understood timeframe for replay is defined. 1045 As a result, when any configured subscription receivers become 1046 active, buffered event records will be sent immediately after the 1047 "subscription-started" notification. If the publisher knows the last 1048 event record sent to a receiver, and the publisher has not rebooted, 1049 the next event record on the event stream which meets filtering 1050 criteria will be the leading event record sent. Otherwise, the 1051 leading event record will be the first event record meeting filtering 1052 criteria subsequent to the latest of three different times: the 1053 "replay-log-creation-time", "replay-log-aged-time", or the most 1054 recent publisher boot time. The "replay-log-creation-time" and 1055 "replay-log-aged-time" are discussed in Section 2.4.2.1. The most 1056 recent publisher boot time ensures that duplicate event records are 1057 not replayed from a previous time the publisher was booted. 1059 It is quite possible that a receiver might want to retrieve event 1060 records from an event stream prior to the latest boot. If such 1061 records exist where there is a configured replay, the publisher MUST 1062 send the time of the event record immediately preceding the "replay- 1063 start-time" within the "replay-previous-event-time" leaf. Through 1064 the existence of the "replay-previous-event-time", the receiver will 1065 know that earlier events prior to reboot exist. In addition, if the 1066 subscriber was previously receiving event records with the same 1067 subscription "id", the receiver can determine if there was a timegap 1068 where records generated on the publisher were not successully 1069 received. And with this information, the receiver may choose to 1070 dynamically subscribe to retrieve any event records placed into the 1071 event stream before the most recent boot time. 1073 All other replay functionality remains the same as with dynamic 1074 subscriptions as described in Section 2.4.2.1. 1076 2.5.7. Transport Connectivity for a Configured Subscription 1078 This specification is transport independent. However supporting a 1079 configured subscription will often require the establishment of 1080 transport connectivity. And the parameters used for this transport 1081 connectivity establishment are transport specific. As a result, the 1082 YANG model defined within Section 4 is not able to directly define 1083 and expose these transport parameters. 1085 It is necessary for an implementation to support the connection 1086 establishment process. To support this function, the YANG model does 1087 include a node where transport specific parameters for a particular 1088 receiver may be augmented. This node is 1089 "/subscriptions/subscription/receivers/receiver". By augmenting 1090 transport parameters from this node, system developers are able to 1091 incorporate the YANG objects necessary to support the transport 1092 connectivity establishment process. 1094 The result of this is the following requirement. A publisher 1095 supporting the feature "configured" MUST also support least one YANG 1096 model which augments transport connectivity parameters on 1097 "/subscriptions/subscription/receivers/receiver". For an example of 1098 such an augmentation, see Appendix A. 1100 2.6. Event Record Delivery 1102 Whether dynamic or configured, once a subscription has been set up, 1103 the publisher streams event records via notification messages per the 1104 terms of the subscription. For dynamic subscriptions, notification 1105 messages are sent over the session used to establish the 1106 subscription. For configured subscriptions, notification messages 1107 are sent over the connections specified by the transport and each 1108 receiver of a configured subscription. 1110 A notification message is sent to a receiver when an event record is 1111 not blocked by either the specified filter criteria or receiver 1112 permissions. This notification message MUST include an "eventTime" 1113 object as defined per [RFC5277] Section 4. This "eventTime" MUST be 1114 at the top level of YANG structured event record. 1116 The following example within [RFC7950] section 7.16.3 is an example 1117 of a compliant message: 1119 1121 2007-09-01T10:00:00Z 1122 1123 so-1/2/3.0 1124 up 1125 down 1126 1127 1129 Figure 10: subscribed notification message 1131 When a dynamic subscription has been started or modified, with 1132 "establish-subscription" or "modify-subscription" respectively, event 1133 records matching the newly applied filter criteria MUST NOT be sent 1134 until after the RPC reply has been sent. 1136 When a configured subscription has been started or modified, event 1137 records matching the newly applied filter criteria MUST NOT be sent 1138 until after the "subscription-started" or "subscription-modified" 1139 notifications has been sent, respectively. 1141 2.7. subscription state change notifications 1143 In addition to sending event records to receivers, a publisher MUST 1144 also send subscription state change notifications when events related 1145 to subscription management have occurred. 1147 subscription state change notifications are unlike other 1148 notifications in that they are never included in any event stream. 1149 Instead, they are inserted (as defined in this section) within the 1150 sequence of notification messages sent to a particular receiver. 1151 subscription state change notifications cannot be filtered out, they 1152 cannot be stored in replay buffers, and they are delivered only to 1153 impacted receivers of a subscription. The identification of 1154 subscription state change notifications is easy to separate from 1155 other notification messages through the use of the YANG extension 1156 "subscription-state-notif". This extension tags a notification as a 1157 subscription state change notification. 1159 The complete set of subscription state change notifications is 1160 described in the following subsections. 1162 2.7.1. subscription-started 1164 This notification indicates that a configured subscription has 1165 started, and event records may be sent. Included in this 1166 subscription state change notification are all the parameters of the 1167 subscription, except for the receiver(s) transport connection 1168 information and origin information indicating where notification 1169 messages will egress the publisher. Note that if a referenced filter 1170 from the "filters" container has been used within the subscription, 1171 the notification still provides the contents of that referenced 1172 filter under the "within-subscription" subtree. 1174 Note that for dynamic subscriptions, no "subscription-started" 1175 notifications are ever sent. 1177 Below is a tree diagram for "subscription-started". All objects 1178 contained in this tree are described within the included YANG model 1179 within Section 4. 1181 +---n subscription-started {configured}? 1182 +--ro id 1183 | subscription-id 1184 +--ro (target) 1185 | +--:(stream) 1186 | +--ro (stream-filter)? 1187 | | +--:(by-reference) 1188 | | | +--ro stream-filter-name 1189 | | | stream-filter-ref 1190 | | +--:(within-subscription) 1191 | | +--ro (filter-spec)? 1192 | | +--:(stream-subtree-filter) 1193 | | | +--ro stream-subtree-filter? 1194 | | | {subtree}? 1195 | | +--:(stream-xpath-filter) 1196 | | +--ro stream-xpath-filter? yang:xpath1.0 1197 | | {xpath}? 1198 | +--ro stream stream-ref 1199 | +--ro replay-start-time? 1200 | | yang:date-and-time {replay}? 1201 | +--ro replay-previous-event-time? 1202 | yang:date-and-time {replay}? 1203 +--ro stop-time? 1204 | yang:date-and-time 1205 +--ro dscp? inet:dscp 1206 | {dscp}? 1207 +--ro weighting? uint8 {qos}? 1208 +--ro dependency? 1209 | subscription-id {qos}? 1210 +--ro transport? transport 1211 | {configured}? 1212 +--ro encoding? encoding 1213 +--ro purpose? string 1214 {configured}? 1216 Figure 11: subscription-started notification tree diagram 1218 2.7.2. subscription-modified 1220 This notification indicates that a subscription has been modified by 1221 configuration operations. It is delivered directly after the last 1222 event records processed using the previous subscription parameters, 1223 and before any event records processed after the modification. 1225 Below is a tree diagram for "subscription-modified". All objects 1226 contained in this tree are described within the included YANG model 1227 within Section 4. 1229 +---n subscription-modified 1230 +--ro id 1231 | subscription-id 1232 +--ro (target) 1233 | +--:(stream) 1234 | +--ro (stream-filter)? 1235 | | +--:(by-reference) 1236 | | | +--ro stream-filter-name 1237 | | | stream-filter-ref 1238 | | +--:(within-subscription) 1239 | | +--ro (filter-spec)? 1240 | | +--:(stream-subtree-filter) 1241 | | | +--ro stream-subtree-filter? 1242 | | | {subtree}? 1243 | | +--:(stream-xpath-filter) 1244 | | +--ro stream-xpath-filter? yang:xpath1.0 1245 | | {xpath}? 1246 | +--ro stream stream-ref 1247 | +--ro replay-start-time? 1248 | yang:date-and-time {replay}? 1249 +--ro stop-time? 1250 | yang:date-and-time 1251 +--ro dscp? inet:dscp 1252 | {dscp}? 1253 +--ro weighting? uint8 {qos}? 1254 +--ro dependency? 1255 | subscription-id {qos}? 1256 +--ro transport? transport 1257 | {configured}? 1258 +--ro encoding? encoding 1259 +--ro purpose? string 1260 {configured}? 1262 Figure 12: subscription-modified notification tree diagram 1264 A publisher most often sends this notification directly after the 1265 modification of any configuration parameters impacting a configured 1266 subscription. But it may also be sent at two other times: 1268 1. Where a configured subscription has been modified during the 1269 suspension of a receiver, the notification will be delayed until 1270 the receiver's suspension is lifted. In this situation, the 1271 notification indicates that the subscription has been both 1272 modified and resumed. 1274 2. A "subscription-modified" subscription state change notification 1275 MUST be sent if the contents of the filter identified by the 1276 subscription's "stream-filter-ref" leaf has changed. This state 1277 change notification is to be sent for a filter change impacting 1278 any active receiver of a configured or dynamic subscription. 1280 2.7.3. subscription-terminated 1282 This notification indicates that no further event records for this 1283 subscription should be expected from the publisher. A publisher may 1284 terminate the sending event records to a receiver for the following 1285 reasons: 1287 1. Configuration which removes a configured subscription, or a 1288 "kill-subscription" RPC which ends a dynamic subscription. These 1289 are identified via the reason "no-such-subscription". 1291 2. A referenced filter is no longer accessible. This is identified 1292 by "filter-unavailable". 1294 3. The event stream referenced by a subscription is no longer 1295 accessible by the receiver. This is identified by "stream- 1296 unavailable". 1298 4. A suspended subscription has exceeded some timeout. This is 1299 identified by "suspension-timeout". 1301 Each of the reasons above correspond one-to-one with a "reason" 1302 identityref specified within the YANG model. 1304 Below is a tree diagram for "subscription-terminated". All objects 1305 contained in this tree are described within the included YANG model 1306 within Section 4. 1308 +---n subscription-terminated 1309 +--ro id subscription-id 1310 +--ro reason identityref 1312 Figure 13: subscription-terminated notification tree diagram 1314 Note: this subscription state change notification MUST be sent to a 1315 dynamic subscription's receiver when the subscription ends 1316 unexpectedly. The cases when this might happen are when a "kill- 1317 subscription" RPC is successful, or when some other event not 1318 including the reaching the subscription's "stop-time" results in a 1319 publisher choosing to end the subscription. 1321 2.7.4. subscription-suspended 1323 This notification indicates that a publisher has suspended the 1324 sending of event records to a receiver, and also indicates the 1325 possible loss of events. Suspension happens when capacity 1326 constraints stop a publisher from serving a valid subscription. The 1327 two conditions where is this possible are: 1329 1. "insufficient-resources" when a publisher is unable to produce 1330 the requested event stream of notification messages, and 1332 2. "unsupportable-volume" when the bandwidth needed to get generated 1333 notification messages to a receiver exceeds a threshold. 1335 These conditions are encoded within the "reason" object. No further 1336 notification will be sent until the subscription resumes or is 1337 terminated. 1339 Below is a tree diagram for "subscription-suspended". All objects 1340 contained in this tree are described within the included YANG model 1341 within Section 4. 1343 +---n subscription-suspended 1344 +--ro id subscription-id 1345 +--ro reason identityref 1347 Figure 14: subscription-suspended notification tree diagram 1349 2.7.5. subscription-resumed 1351 This notification indicates that a previously suspended subscription 1352 has been resumed under the unmodified terms previously in place. 1353 Subscribed event records generated after the issuance of this 1354 subscription state change notification may now be sent. 1356 Below is the tree diagram for "subscription-resumed". All objects 1357 contained in this tree are described within the included YANG model 1358 within Section 4. 1360 +---n subscription-resumed 1361 +--ro id subscription-id 1363 Figure 15: subscription-resumed notification tree diagram 1365 2.7.6. subscription-completed 1367 This notification indicates that a subscription that includes a 1368 "stop-time" has successfully finished passing event records upon the 1369 reaching of that time. 1371 Below is a tree diagram for "subscription-completed". All objects 1372 contained in this tree are described within the included YANG model 1373 within Section 4. 1375 +---n subscription-completed {configured}? 1376 +--ro id subscription-id 1378 Figure 16: subscription-completed notification tree diagram 1380 2.7.7. replay-completed 1382 This notification indicates that all of the event records prior to 1383 the current time have been passed to a receiver. It is sent before 1384 any notification message containing an event record with a timestamp 1385 later than (1) the "stop-time" or (2) the subscription's start time. 1387 If a subscription contains no "stop-time", or has a "stop-time" that 1388 has not been reached, then after the "replay-completed" notification 1389 has been sent, additional event records will be sent in sequence as 1390 they arise naturally on the publisher. 1392 Below is a tree diagram for "replay-completed". All objects 1393 contained in this tree are described within the included YANG model 1394 within Section 4. 1396 +---n replay-completed {replay}? 1397 +--ro id subscription-id 1399 Figure 17: replay-completed notification tree diagram 1401 2.8. Subscription Monitoring 1403 In the operational state datastore, the container "subscriptions" 1404 maintains the state of all dynamic subscriptions, as well as all 1405 configured subscriptions. Using datastore retrieval operations, or 1406 subscribing to the "subscriptions" container 1407 [I-D.ietf-netconf-yang-push] allows the state of subscriptions and 1408 their connectivity to receivers to be monitored. 1410 Each subscription in the operational state datastore is represented 1411 as a list element. Included in this list are event counters for each 1412 receiver, the state of each receiver, as well as the subscription 1413 parameters currently in effect. The appearance of the leaf 1414 "configured-subscription-state" indicates that a particular 1415 subscription came into being via configuration. This leaf also 1416 indicates if the current state of that subscription is valid, 1417 invalid, and concluded. 1419 To understand the flow of event records within a subscription, there 1420 are two counters available for each receiver. The first counter is 1421 "sent-event-records" which shows the quantity of events actually 1422 identified for sending to a receiver. The second counter is 1423 "excluded-event-records" which shows event records not sent to 1424 receiver. "excluded-event-records" shows the combined results of 1425 both access control and per-subscription filtering. For configured 1426 subscriptions, counters are reset whenever the subscription is 1427 evaluated to valid (see (1) in Figure 8). 1429 Dynamic subscriptions are removed from the operational state 1430 datastore once they expire (reaching stop-time) or when they are 1431 terminated. While many subscription objects are shown as 1432 configurable, dynamic subscriptions are only included within the 1433 operational state datastore and as a result are not configurable. 1435 2.9. Advertisement 1437 Publishers supporting this document MUST indicate support of the YANG 1438 model "ietf-subscribed-notifications" within the YANG library of the 1439 publisher. In addition if supported, the optional features "encode- 1440 xml", "encode-json", "configured" "supports-vrf", "qos", "xpath", 1441 "subtree", "interface-designation", "dscp", and "replay" MUST be 1442 indicated. 1444 3. YANG Data Model Trees 1446 This section contains tree diagrams for nodes defined in Section 4. 1447 For tree diagrams of subscription state change notifications, see 1448 Section 2.7. For the tree diagrams for the RPCs, see Section 2.4. 1450 3.1. Event Streams Container 1452 A publisher maintains a list of available event streams as 1453 operational data. This list contains both standardized and vendor- 1454 specific event streams. This enables subscribers to discover what 1455 streams a publisher supports. 1457 +--ro streams 1458 +--ro stream* [name] 1459 +--ro name string 1460 +--ro description string 1461 +--ro replay-support? empty {replay}? 1462 +--ro replay-log-creation-time yang:date-and-time 1463 | {replay}? 1464 +--ro replay-log-aged-time? yang:date-and-time 1465 {replay}? 1467 Figure 18: Stream Container tree diagram 1469 Above is a tree diagram for the "streams" container. All objects 1470 contained in this tree are described within the included YANG model 1471 within Section 4. 1473 3.2. Filters Container 1475 The "filters" container maintains a list of all subscription filters 1476 that persist outside the life-cycle of a single subscription. This 1477 enables pre-defined filters which may be referenced by more than one 1478 subscription. 1480 +--rw filters 1481 +--rw stream-filter* [name] 1482 +--rw name string 1483 +--rw (filter-spec)? 1484 +--:(stream-subtree-filter) 1485 | +--rw stream-subtree-filter? {subtree}? 1486 +--:(stream-xpath-filter) 1487 +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 1489 Figure 19: Filter Container tree diagram 1491 Above is a tree diagram for the filters container. All objects 1492 contained in this tree are described within the included YANG model 1493 within Section 4. 1495 3.3. Subscriptions Container 1497 The "subscriptions" container maintains a list of all subscriptions 1498 on a publisher, both configured and dynamic. It can be used to 1499 retrieve information about the subscriptions which a publisher is 1500 serving. 1502 +--rw subscriptions 1503 +--rw subscription* [id] 1504 +--rw id 1505 | subscription-id 1506 +--rw (target) 1507 | +--:(stream) 1508 | +--rw (stream-filter)? 1509 | | +--:(by-reference) 1510 | | | +--rw stream-filter-name 1511 | | | stream-filter-ref 1512 | | +--:(within-subscription) 1513 | | +--rw (filter-spec)? 1514 | | +--:(stream-subtree-filter) 1515 | | | +--rw stream-subtree-filter? 1516 | | | {subtree}? 1517 | | +--:(stream-xpath-filter) 1518 | | +--rw stream-xpath-filter? 1519 | | yang:xpath1.0 {xpath}? 1520 | +--rw stream stream-ref 1521 | +--ro replay-start-time? 1522 | | yang:date-and-time {replay}? 1523 | +--rw configured-replay? empty 1524 | {configured,replay}? 1525 +--rw stop-time? 1526 | yang:date-and-time 1527 +--rw dscp? inet:dscp 1528 | {dscp}? 1529 +--rw weighting? uint8 {qos}? 1530 +--rw dependency? 1531 | subscription-id {qos}? 1532 +--rw transport? transport 1533 | {configured}? 1534 +--rw encoding? encoding 1535 +--rw purpose? string 1536 | {configured}? 1537 +--rw (notification-message-origin)? {configured}? 1538 | +--:(interface-originated) 1539 | | +--rw source-interface? 1540 | | if:interface-ref {interface-designation}? 1541 | +--:(address-originated) 1542 | +--rw source-vrf? 1543 | | -> /ni:network-instances/network-instance/name 1544 | | {supports-vrf}? 1545 | +--rw source-address? 1546 | inet:ip-address-no-zone 1547 +--ro configured-subscription-state? enumeration 1548 | {configured}? 1549 +--rw receivers 1550 +--rw receiver* [name] 1551 +--rw name string 1552 +--ro sent-event-records? 1553 | yang:zero-based-counter64 1554 +--ro excluded-event-records? 1555 | yang:zero-based-counter64 1556 +--ro state enumeration 1557 +---x reset {configured}? 1558 +--ro output 1559 +--ro time yang:date-and-time 1561 Figure 20: Subscriptions tree diagram 1563 Above is a tree diagram for the subscriptions container. All objects 1564 contained in this tree are described within the included YANG model 1565 within Section 4. 1567 4. Data Model 1569 This module imports typedefs from [RFC6991], [RFC8343], and 1570 [RFC8040], and it references [I-D.draft-ietf-rtgwg-ni-model], 1571 [XPATH], [RFC6241], [RFC7540], [RFC7951] and [RFC7950]. 1573 [ note to the RFC Editor - please replace XXXX within this YANG model 1574 with the number of this document, and XXXY with the number of 1575 [I-D.draft-ietf-rtgwg-ni-model] ] 1577 [ note to the RFC Editor - please replace the two dates within the 1578 YANG module with the date of publication ] 1580 file "ietf-subscribed-notifications@2018-12-19.yang" 1581 module ietf-subscribed-notifications { 1582 yang-version 1.1; 1583 namespace 1584 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"; 1586 prefix sn; 1588 import ietf-inet-types { 1589 prefix inet; 1590 reference 1591 "RFC 6991: Common YANG Data Types"; 1592 } 1593 import ietf-interfaces { 1594 prefix if; 1595 reference 1596 "RFC 8343: A YANG Data Model for Interface Management"; 1597 } 1598 import ietf-netconf-acm { 1599 prefix nacm; 1600 reference 1601 "RFC 8341: Network Configuration Access Control Model"; 1602 } 1603 import ietf-network-instance { 1604 prefix ni; 1605 reference 1606 "draft-ietf-rtgwg-ni-model-12: YANG Model for Network Instances"; 1607 } 1608 import ietf-restconf { 1609 prefix rc; 1610 reference 1611 "RFC 8040: RESTCONF Protocol"; 1612 } 1613 import ietf-yang-types { 1614 prefix yang; 1615 reference 1616 "RFC 6991: Common YANG Data Types"; 1617 } 1619 organization "IETF NETCONF (Network Configuration) Working Group"; 1620 contact 1621 "WG Web: 1622 WG List: 1624 Author: Alexander Clemm 1625 1627 Author: Eric Voit 1628 1630 Author: Alberto Gonzalez Prieto 1631 1633 Author: Einar Nilsen-Nygaard 1634 1636 Author: Ambika Prasad Tripathy 1637 "; 1639 description 1640 "Contains a YANG specification for subscribing to event records 1641 and receiving matching content within notification messages. 1643 Copyright (c) 2018 IETF Trust and the persons identified as authors 1644 of the code. All rights reserved. 1646 Redistribution and use in source and binary forms, with or without 1647 modification, is permitted pursuant to, and subject to the license 1648 terms contained in, the Simplified BSD License set forth in Section 1649 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1650 (https://trustee.ietf.org/license-info). 1652 This version of this YANG module is part of RFC XXXX; see the RFC 1653 itself for full legal notices."; 1655 revision 2018-12-19 { 1656 description 1657 "Initial version"; 1658 reference 1659 "RFC XXXX:Customized Subscriptions to a Publisher's Event Streams"; 1660 } 1662 /* 1663 * FEATURES 1664 */ 1666 feature configured { 1667 description 1668 "This feature indicates that configuration of subscription is 1669 supported."; 1670 } 1672 feature dscp { 1673 description 1674 "This feature indicates a publisher supports the placement of 1675 suggested prioritization levels for network transport within 1676 notification messages."; 1677 } 1679 feature encode-json { 1680 description 1681 "This feature indicates that JSON encoding of notification 1682 messages is supported."; 1683 } 1685 feature encode-xml { 1686 description 1687 "This feature indicates that XML encoding of notification 1688 messages is supported."; 1689 } 1691 feature interface-designation { 1692 description 1693 "This feature indicates a publisher supports sourcing all 1694 receiver interactions for a configured subscription from a single 1695 designated egress interface."; 1696 } 1698 feature qos { 1699 description 1700 "This feature indicates a publisher supports absolute 1701 dependencies of one subscription's traffic over another, as well 1702 as weighted bandwidth sharing between subscriptions. Both of 1703 these are Quality of Service (QoS) features which allow 1704 differentiated treatment of notification messages between a 1705 publisher and a specific receiver."; 1706 } 1708 feature replay { 1709 description 1710 "This feature indicates that historical event record replay is 1711 supported. With replay, it is possible for past event records to 1712 be streamed in chronological order."; 1713 } 1715 feature subtree { 1716 description 1717 "This feature indicates support for YANG subtree filtering."; 1718 reference "RFC 6241, Section 6."; 1719 } 1721 feature supports-vrf { 1722 description 1723 "This feature indicates a publisher supports VRF configuration 1724 for configured subscriptions. VRF support for dynamic 1725 subscriptions does not require this feature."; 1726 reference "RFC XXXY, Section 6."; 1727 } 1729 feature xpath { 1730 description 1731 "This feature indicates support for XPath filtering."; 1732 reference "http://www.w3.org/TR/1999/REC-xpath-19991116"; 1733 } 1735 /* 1736 * EXTENSIONS 1737 */ 1739 extension subscription-state-notification { 1740 description 1741 "This statement applies only to notifications. It indicates that 1742 the notification is a subscription state change notification. 1743 Therefore it does not participate in a regular event stream and 1744 does not need to be specifically subscribed to in order to be 1745 received. This statement can only occur as a substatement to the 1746 YANG 'notification' statement. This statement is not for use 1747 outside of this YANG module."; 1748 } 1750 /* 1751 * IDENTITIES 1752 */ 1754 /* Identities for RPC and Notification errors */ 1756 identity delete-subscription-error { 1757 description 1758 "Problem found while attempting to fulfill either a 1759 'delete-subscription' RPC request or a 'kill-subscription' 1760 RPC request."; 1761 } 1763 identity establish-subscription-error { 1764 description 1765 "Problem found while attempting to fulfill an 1766 'establish-subscription' RPC request."; 1767 } 1769 identity modify-subscription-error { 1770 description 1771 "Problem found while attempting to fulfill a 1772 'modify-subscription' RPC request."; 1773 } 1775 identity subscription-suspended-reason { 1776 description 1777 "Problem condition communicated to a receiver as part of a 1778 'subscription-terminated' notification."; 1779 } 1781 identity subscription-terminated-reason { 1782 description 1783 "Problem condition communicated to a receiver as part of a 1784 'subscription-terminated' notification."; 1785 } 1787 identity dscp-unavailable { 1788 base establish-subscription-error; 1789 if-feature "dscp"; 1790 description 1791 "The publisher is unable mark notification messages with a 1792 prioritization information in a way which will be respected 1793 during network transit."; 1794 } 1796 identity encoding-unsupported { 1797 base establish-subscription-error; 1798 description 1799 "Unable to encode notification messages in the desired format."; 1800 } 1802 identity filter-unavailable { 1803 base subscription-terminated-reason; 1804 description 1805 "Referenced filter does not exist. This means a receiver is 1806 referencing a filter which doesn't exist, or to which they do not 1807 have access permissions."; 1808 } 1810 identity filter-unsupported { 1811 base establish-subscription-error; 1812 base modify-subscription-error; 1813 description 1814 "Cannot parse syntax within the filter. This failure can be from 1815 a syntax error, or a syntax too complex to be processed by the 1816 publisher."; 1817 } 1819 identity insufficient-resources { 1820 base establish-subscription-error; 1821 base modify-subscription-error; 1822 base subscription-suspended-reason; 1823 description 1824 "The publisher has insufficient resources to support the 1825 requested subscription. An example might be that allocated CPU 1826 is too limited to generate the desired set of notification 1827 messages."; 1828 } 1830 identity no-such-subscription { 1831 base modify-subscription-error; 1832 base delete-subscription-error; 1833 base subscription-terminated-reason; 1834 description 1835 "Referenced subscription doesn't exist. This may be as a result of 1836 a non-existent subscription id, an id which belongs to another 1837 subscriber, or an id for configured subscription."; 1839 } 1841 identity replay-unsupported { 1842 base establish-subscription-error; 1843 if-feature "replay"; 1844 description 1845 "Replay cannot be performed for this subscription. This means the 1846 publisher will not provide the requested historic information 1847 from the event stream via replay to this receiver."; 1848 } 1850 identity stream-unavailable { 1851 base subscription-terminated-reason; 1852 description 1853 "Not a subscribable event stream. This means the referenced event 1854 stream is not available for subscription by the receiver."; 1855 } 1857 identity suspension-timeout { 1858 base subscription-terminated-reason; 1859 description 1860 "Termination of previously suspended subscription. The publisher 1861 has eliminated the subscription as it exceeded a time limit for 1862 suspension."; 1863 } 1865 identity unsupportable-volume { 1866 base subscription-suspended-reason; 1867 description 1868 "The publisher does not have the network bandwidth needed to get 1869 the volume of generated information intended for a receiver."; 1870 } 1872 /* Identities for encodings */ 1874 identity configurable-encoding { 1875 description 1876 "If a transport identity derives from this identity, it means 1877 that it supports configurable encodings."; 1878 } 1880 identity encoding { 1881 description 1882 "Base identity to represent data encodings"; 1883 } 1885 identity encode-xml { 1886 base encoding; 1887 if-feature "encode-xml"; 1888 description 1889 "Encode data using XML as described in RFC 7950"; 1890 reference 1891 "RFC 7950 - The YANG 1.1 Data Modeling Language"; 1892 } 1894 identity encode-json { 1895 base encoding; 1896 if-feature "encode-json"; 1897 description 1898 "Encode data using JSON as described in RFC 7951"; 1899 reference 1900 "RFC 7951 - JSON Encoding of Data Modeled with YANG"; 1901 } 1903 /* Identities for transports */ 1904 identity transport { 1905 description 1906 "An identity that represents the underlying mechanism for 1907 passing notification messages."; 1908 } 1910 /* 1911 * TYPEDEFs 1912 */ 1914 typedef encoding { 1915 type identityref { 1916 base encoding; 1917 } 1918 description 1919 "Specifies a data encoding, e.g. for a data subscription."; 1920 } 1922 typedef stream-filter-ref { 1923 type leafref { 1924 path "/sn:filters/sn:stream-filter/sn:name"; 1925 } 1926 description 1927 "This type is used to reference an event stream filter."; 1928 } 1930 typedef stream-ref { 1931 type leafref { 1932 path "/sn:streams/sn:stream/sn:name"; 1933 } 1934 description 1935 "This type is used to reference a system-provided event stream."; 1936 } 1938 typedef subscription-id { 1939 type uint32; 1940 description 1941 "A type for subscription identifiers."; 1942 } 1944 typedef transport { 1945 type identityref { 1946 base transport; 1947 } 1948 description 1949 "Specifies transport used to send notification messages to a 1950 receiver."; 1951 } 1953 /* 1954 * GROUPINGS 1955 */ 1957 grouping stream-filter-elements { 1958 description 1959 "This grouping defines the base for filters applied to event 1960 streams."; 1961 choice filter-spec { 1962 description 1963 "The content filter specification for this request."; 1964 anydata stream-subtree-filter { 1965 if-feature "subtree"; 1966 description 1967 "Event stream evaluation criteria encoded in the syntax of a 1968 subtree filter as defined in RFC 6241, Section 6. 1970 The subtree filter is applied to the representation of 1971 individual, delineated event records as contained within the 1972 event stream. 1974 If the subtree filter returns a non-empty node set, the 1975 filter matches the event record, and the event record is 1976 included in the notification message sent to the receivers."; 1977 reference "RFC 6241, Section 6."; 1978 } 1979 leaf stream-xpath-filter { 1980 if-feature "xpath"; 1981 type yang:xpath1.0; 1982 description 1983 "Event stream evaluation criteria encoded in the syntax of 1984 an XPath 1.0 expression. 1986 The XPath expression is evaluated on the representation of 1987 individual, delineated event records as contained within 1988 the event stream. 1990 The result of the XPath expression is converted to a 1991 boolean value using the standard XPath 1.0 rules. If the 1992 boolean value is 'true', the filter matches the event 1993 record, and the event record is included in the notification 1994 message sent to the receivers. 1996 The expression is evaluated in the following XPath context: 1998 o The set of namespace declarations is the set of prefix 1999 and namespace pairs for all YANG modules implemented 2000 by the server, where the prefix is the YANG module 2001 name and the namespace is as defined by the 2002 'namespace' statement in the YANG module. 2004 If the leaf is encoded in XML, all namespace 2005 declarations in scope on the 'stream-xpath-filter' 2006 leaf element are added to the set of namespace 2007 declarations. If a prefix found in the XML is 2008 already present in the set of namespace declarations, 2009 the namespace in the XML is used. 2011 o The set of variable bindings is empty. 2013 o The function library is the core function library, and 2014 the XPath functions defined in section 10 in RFC 7950. 2016 o The context node is the root node."; 2017 reference 2018 "http://www.w3.org/TR/1999/REC-xpath-19991116 2019 RFC 7950, Section 10."; 2021 } 2022 } 2023 } 2025 grouping update-qos { 2026 description 2027 "This grouping describes Quality of Service information 2028 concerning a subscription. This information is passed to lower 2029 layers for transport prioritization and treatment"; 2030 leaf dscp { 2031 if-feature "dscp"; 2032 type inet:dscp; 2033 default "0"; 2034 description 2035 "The desired network transport priority level. This is the 2036 priority set on notification messages encapsulating the 2037 results of the subscription. This transport priority is 2038 shared for all receivers of a given subscription."; 2039 } 2040 leaf weighting { 2041 if-feature "qos"; 2042 type uint8 { 2043 range "0 .. 255"; 2044 } 2045 description 2046 "Relative weighting for a subscription. Allows an underlying 2047 transport layer perform informed load balance allocations 2048 between various subscriptions"; 2049 reference 2050 "RFC-7540, section 5.3.2"; 2051 } 2052 leaf dependency { 2053 if-feature "qos"; 2054 type subscription-id; 2055 description 2056 "Provides the 'subscription-id' of a parent subscription which 2057 has absolute precedence should that parent have push updates 2058 ready to egress the publisher. In other words, there should be 2059 no streaming of objects from the current subscription if 2060 the parent has something ready to push. 2062 If a dependency is asserted via configuration or via RPC, but 2063 the referenced 'subscription-id' does not exist, the 2064 dependency is silently discarded. If a referenced 2065 subscription is deleted this dependency is removed."; 2066 reference 2067 "RFC-7540, section 5.3.1"; 2068 } 2069 } 2071 grouping subscription-policy-modifiable { 2072 description 2073 "This grouping describes all objects which may be changed 2074 in a subscription."; 2075 choice target { 2076 mandatory true; 2077 description 2078 "Identifies the source of information against which a 2079 subscription is being applied, as well as specifics on the 2080 subset of information desired from that source."; 2081 case stream { 2082 choice stream-filter { 2083 description 2084 "An event stream filter can be applied to a subscription. 2085 That filter will come either referenced from a global list, 2086 or be provided within the subscription itself."; 2087 case by-reference { 2088 description 2089 "Apply a filter that has been configured separately."; 2090 leaf stream-filter-name { 2091 type stream-filter-ref; 2092 mandatory true; 2093 description 2094 "References an existing event stream filter which is to 2095 be applied to an event stream for the subscription."; 2096 } 2097 } 2098 case within-subscription { 2099 description 2100 "Local definition allows a filter to have the same 2101 lifecycle as the subscription."; 2102 uses stream-filter-elements; 2103 } 2104 } 2105 } 2106 } 2107 leaf stop-time { 2108 type yang:date-and-time; 2109 description 2110 "Identifies a time after which notification messages for a 2111 subscription should not be sent. If 'stop-time' is not 2112 present, the notification messages will continue until the 2113 subscription is terminated. If 'replay-start-time' exists, 2114 'stop-time' must be for a subsequent time. If 2115 'replay-start-time' doesn't exist, 'stop-time' when established 2116 must be for a future time."; 2117 } 2118 } 2120 grouping subscription-policy-dynamic { 2121 description 2122 "This grouping describes the only information concerning a 2123 subscription which can be passed over the RPCs defined in this 2124 model."; 2125 uses subscription-policy-modifiable { 2126 augment target/stream { 2127 description 2128 "Adds additional objects which can be modified by RPC."; 2129 leaf stream { 2130 type stream-ref { 2131 require-instance false; 2132 } 2133 mandatory true; 2134 description 2135 "Indicates the event stream to be considered for 2136 this subscription."; 2137 } 2138 leaf replay-start-time { 2139 if-feature "replay"; 2140 type yang:date-and-time; 2141 config false; 2142 description 2143 "Used to trigger the replay feature for a dynamic 2144 subscription, with event records being selected needing to 2145 be at or after the start at the time specified. If 2146 'replay-start-time' is not present, this is not a replay 2147 subscription and event record push should start 2148 immediately. It is never valid to specify start times that 2149 are later than or equal to the current time."; 2150 } 2151 } 2152 } 2153 uses update-qos; 2154 } 2156 grouping subscription-policy { 2157 description 2158 "This grouping describes the full set of policy information 2159 concerning both dynamic and configured subscriptions, with the 2160 exclusion of both receivers and networking information specific 2161 to the publisher such as what interface should be used to 2162 transmit notification messages."; 2163 uses subscription-policy-dynamic; 2164 leaf transport { 2165 if-feature "configured"; 2166 type transport; 2167 description 2168 "For a configured subscription, this leaf specifies the 2169 transport used to deliver messages destined to all receivers 2170 of that subscription."; 2171 } 2172 leaf encoding { 2173 when 'not(../transport) or derived-from(../transport, 2174 "sn:configurable-encoding")'; 2175 type encoding; 2176 description 2177 "The type of encoding for notification messages. For a 2178 dynamic subscription, if not included as part of an establish- 2179 subscription RPC, the encoding will be populated with the 2180 encoding used by that RPC. For a configured subscription, if 2181 not explicitly configured the encoding with be the default 2182 encoding for an underlying transport."; 2183 } 2184 leaf purpose { 2185 if-feature "configured"; 2186 type string; 2187 description 2188 "Open text allowing a configuring entity to embed the 2189 originator or other specifics of this subscription."; 2190 } 2191 } 2193 /* 2194 * RPCs 2195 */ 2197 rpc establish-subscription { 2198 description 2199 "This RPC allows a subscriber to create (and possibly negotiate) 2200 a subscription on its own behalf. If successful, the 2201 subscription remains in effect for the duration of the 2202 subscriber's association with the publisher, or until the 2203 subscription is terminated. In case an error occurs, or the 2204 publisher cannot meet the terms of a subscription, an RPC error 2205 is returned, the subscription is not created. In that case, the 2206 RPC reply's 'error-info' MAY include suggested parameter 2207 settings that would have a higher likelihood of succeeding in a 2208 subsequent 'establish-subscription' request."; 2209 input { 2210 uses subscription-policy-dynamic; 2211 leaf encoding { 2212 type encoding; 2213 description 2214 "The type of encoding for the subscribed data. If not 2215 included as part of the RPC, the encoding MUST be set by the 2216 publisher to be the encoding used by this RPC."; 2217 } 2218 } 2219 output { 2220 leaf id { 2221 type subscription-id; 2222 mandatory true; 2223 description 2224 "Identifier used for this subscription."; 2225 } 2226 leaf replay-start-time-revision { 2227 if-feature "replay"; 2228 type yang:date-and-time; 2229 description 2230 "If a replay has been requested, this represents the 2231 earliest time covered by the event buffer for the requested 2232 event stream. The value of this object is the 2233 'replay-log-aged-time' if it exists. Otherwise it is the 2234 'replay-log-creation-time'. All buffered event records 2235 after this time will be replayed to a receiver. This 2236 object will only be sent if the starting time has been 2237 revised to be later than the time requested by the 2238 subscriber."; 2239 } 2240 } 2241 } 2243 rc:yang-data establish-subscription-stream-error-info { 2244 container establish-subscription-stream-error-info { 2245 description 2246 "If any 'establish-subscription' RPC parameters are 2247 unsupportable against the event stream, a subscription is not 2248 created and the RPC error response MUST indicate the reason 2249 why the subscription failed to be created. This yang-data MAY 2250 be inserted as structured data within a subscription's RPC 2251 error response to indicate the failure reason. This yang-data 2252 MUST be inserted if hints are to be provided back to the 2253 subscriber."; 2254 leaf reason { 2255 type identityref { 2256 base establish-subscription-error; 2257 } 2258 description 2259 "Indicates the reason why the subscription has failed to 2260 be created to a targeted event stream."; 2261 } 2262 leaf filter-failure-hint { 2263 type string; 2264 description 2265 "Information describing where and/or why a provided filter 2266 was unsupportable for a subscription."; 2267 } 2268 } 2269 } 2270 rpc modify-subscription { 2271 description 2272 "This RPC allows a subscriber to modify a dynamic subscription's 2273 parameters. If successful, the changed subscription 2274 parameters remain in effect for the duration of the 2275 subscription, until the subscription is again modified, or until 2276 the subscription is terminated. In case of an error or an 2277 inability to meet the modified parameters, the subscription is 2278 not modified and the original subscription parameters remain in 2279 effect. In that case, the RPC error MAY include 'error-info' 2280 suggested parameter hints that would have a high likelihood of 2281 succeeding in a subsequent 'modify-subscription' request. A 2282 successful 'modify-subscription' will return a suspended 2283 subscription to an 'active' state."; 2284 input { 2285 leaf id { 2286 type subscription-id; 2287 mandatory true; 2288 description 2289 "Identifier to use for this subscription."; 2290 } 2291 uses subscription-policy-modifiable; 2292 } 2293 } 2295 rc:yang-data modify-subscription-stream-error-info { 2296 container modify-subscription-stream-error-info { 2297 description 2298 "This yang-data MAY be provided as part of a subscription's RPC 2299 error response when there is a failure of a 2300 'modify-subscription' RPC which has been made against an event 2301 stream. This yang-data MUST be used if hints are to be 2302 provided back to the subscriber."; 2303 leaf reason { 2304 type identityref { 2305 base modify-subscription-error; 2306 } 2307 description 2308 "Information in a 'modify-subscription' RPC error response 2309 which indicates the reason why the subscription to an event 2310 stream has failed to be modified."; 2311 } 2312 leaf filter-failure-hint { 2313 type string; 2314 description 2315 "Information describing where and/or why a provided filter 2316 was unsupportable for a subscription."; 2317 } 2319 } 2320 } 2322 rpc delete-subscription { 2323 description 2324 "This RPC allows a subscriber to delete a subscription that 2325 was previously created from by that same subscriber using the 2326 'establish-subscription' RPC. 2328 If an error occurs, the server replies with an 'rpc-error' where 2329 the 'error-info' field MAY contain an 2330 'delete-subscription-error-info' structure."; 2331 input { 2332 leaf id { 2333 type subscription-id; 2334 mandatory true; 2335 description 2336 "Identifier of the subscription that is to be deleted. 2337 Only subscriptions that were created using 2338 'establish-subscription' from the same origin as this RPC 2339 can be deleted via this RPC."; 2340 } 2341 } 2342 } 2344 rpc kill-subscription { 2345 nacm:default-deny-all; 2346 description 2347 "This RPC allows an operator to delete a dynamic subscription 2348 without restrictions on the originating subscriber or underlying 2349 transport session. 2351 If an error occurs, the server replies with an 'rpc-error' where 2352 the 'error-info' field MAY contain an 2353 'delete-subscription-error-info' structure."; 2354 input { 2355 leaf id { 2356 type subscription-id; 2357 mandatory true; 2358 description 2359 "Identifier of the subscription that is to be deleted. Only 2360 subscriptions that were created using 2361 'establish-subscription' can be deleted via this RPC."; 2362 } 2363 } 2364 } 2366 rc:yang-data delete-subscription-error-info { 2367 container delete-subscription-error-info { 2368 description 2369 "If a 'delete-subscription' RPC or a 'kill-subscription' RPC 2370 fails, the subscription is not deleted and the RPC error 2371 response MUST indicate the reason for this failure. This 2372 yang-data MAY be inserted as structured data within a 2373 subscription's RPC error response to indicate the failure 2374 reason."; 2375 leaf reason { 2376 type identityref { 2377 base delete-subscription-error; 2378 } 2379 mandatory true; 2380 description 2381 "Indicates the reason why the subscription has failed to be 2382 deleted."; 2383 } 2384 } 2385 } 2387 /* 2388 * NOTIFICATIONS 2389 */ 2391 notification replay-completed { 2392 sn:subscription-state-notification; 2393 if-feature "replay"; 2394 description 2395 "This notification is sent to indicate that all of the replay 2396 notifications have been sent. It must not be sent for any other 2397 reason."; 2398 leaf id { 2399 type subscription-id; 2400 mandatory true; 2401 description 2402 "This references the affected subscription."; 2403 } 2404 } 2406 notification subscription-completed { 2407 sn:subscription-state-notification; 2408 if-feature "configured"; 2409 description 2410 "This notification is sent to indicate that a subscription has 2411 finished passing event records, as the 'stop-time' has been 2412 reached."; 2413 leaf id { 2414 type subscription-id; 2415 mandatory true; 2416 description 2417 "This references the gracefully completed subscription."; 2418 } 2419 } 2421 notification subscription-modified { 2422 sn:subscription-state-notification; 2423 description 2424 "This notification indicates that a subscription has been 2425 modified. Notification messages sent from this point on will 2426 conform to the modified terms of the subscription. For 2427 completeness, this subscription state change notification 2428 includes both modified and non-modified aspects of a 2429 subscription."; 2430 leaf id { 2431 type subscription-id; 2432 mandatory true; 2433 description 2434 "This references the affected subscription."; 2435 } 2436 uses subscription-policy { 2437 refine "target/stream/stream-filter/within-subscription" { 2438 description 2439 "Filter applied to the subscription. If the 2440 'stream-filter-name' is populated, the filter within the 2441 subscription came from the 'filters' container. Otherwise it 2442 is populated in-line as part of the subscription."; 2443 } 2444 } 2445 } 2447 notification subscription-resumed { 2448 sn:subscription-state-notification; 2449 description 2450 "This notification indicates that a subscription that had 2451 previously been suspended has resumed. Notifications will once 2452 again be sent. In addition, a 'subscription-resumed' indicates 2453 that no modification of parameters has occurred since the last 2454 time event records have been sent."; 2455 leaf id { 2456 type subscription-id; 2457 mandatory true; 2458 description 2459 "This references the affected subscription."; 2460 } 2461 } 2462 notification subscription-started { 2463 sn:subscription-state-notification; 2464 if-feature "configured"; 2465 description 2466 "This notification indicates that a subscription has started and 2467 notifications are beginning to be sent. This notification shall 2468 only be sent to receivers of a subscription; it does not 2469 constitute a general-purpose notification."; 2470 leaf id { 2471 type subscription-id; 2472 mandatory true; 2473 description 2474 "This references the affected subscription."; 2475 } 2476 uses subscription-policy { 2477 refine "target/stream/replay-start-time" { 2478 description 2479 "Indicates the time that a replay using for the streaming of 2480 buffered event records. This will be populated with the 2481 most recent of the following: the event time of the previous 2482 event record sent to a receiver, the 2483 'replay-log-creation-time', the 'replay-log-aged-time', 2484 or the most recent publisher boot time."; 2485 } 2486 refine "target/stream/stream-filter/within-subscription" { 2487 description 2488 "Filter applied to the subscription. If the 2489 'stream-filter-name' is populated, the filter within the 2490 subscription came from the 'filters' container. Otherwise it 2491 is populated in-line as part of the subscription."; 2492 } 2493 augment "target/stream" { 2494 description 2495 "This augmentation adds additional parameters specific to a 2496 subscription-started notification."; 2497 leaf replay-previous-event-time { 2498 when "../replay-start-time"; 2499 if-feature "replay"; 2500 type yang:date-and-time; 2501 description 2502 "If there is at least one event in the replay buffer prior 2503 to 'replay-start-time', this gives the time of the event 2504 generated immediately prior to the 'replay-start-time'. 2506 If a receiver previously received event records for this 2507 configured subscription, it can compare this time to the 2508 last event record previously received. If the two are not 2509 the same (perhaps due to a reboot), then a dynamic replay 2510 can be initiated to acquire any missing event records."; 2511 } 2512 } 2513 } 2514 } 2516 notification subscription-suspended { 2517 sn:subscription-state-notification; 2518 description 2519 "This notification indicates that a suspension of the 2520 subscription by the publisher has occurred. No further 2521 notifications will be sent until the subscription resumes. 2522 This notification shall only be sent to receivers of a 2523 subscription; it does not constitute a general-purpose 2524 notification."; 2525 leaf id { 2526 type subscription-id; 2527 mandatory true; 2528 description 2529 "This references the affected subscription."; 2530 } 2531 leaf reason { 2532 type identityref { 2533 base subscription-suspended-reason; 2534 } 2535 mandatory true; 2536 description 2537 "Identifies the condition which resulted in the suspension."; 2538 } 2539 } 2541 notification subscription-terminated { 2542 sn:subscription-state-notification; 2543 description 2544 "This notification indicates that a subscription has been 2545 terminated."; 2546 leaf id { 2547 type subscription-id; 2548 mandatory true; 2549 description 2550 "This references the affected subscription."; 2551 } 2552 leaf reason { 2553 type identityref { 2554 base subscription-terminated-reason; 2555 } 2556 mandatory true; 2557 description 2558 "Identifies the condition which resulted in the termination ."; 2559 } 2560 } 2562 /* 2563 * DATA NODES 2564 */ 2566 container streams { 2567 config false; 2568 description 2569 "This container contains information on the built-in event 2570 streams provided by the publisher."; 2571 list stream { 2572 key "name"; 2573 description 2574 "Identifies the built-in event streams that are supported by 2575 the publisher."; 2576 leaf name { 2577 type string; 2578 description 2579 "A handle for a system-provided event stream made up of a 2580 sequential set of event records, each of which is 2581 characterized by its own domain and semantics."; 2582 } 2583 leaf description { 2584 type string; 2585 mandatory true; 2586 description 2587 "A description of the event stream, including such 2588 information as the type of event records that are available 2589 within this event stream."; 2590 } 2591 leaf replay-support { 2592 if-feature "replay"; 2593 type empty; 2594 description 2595 "Indicates that event record replay is available on this 2596 event stream."; 2597 } 2598 leaf replay-log-creation-time { 2599 when "../replay-support"; 2600 if-feature "replay"; 2601 type yang:date-and-time; 2602 mandatory true; 2603 description 2604 "The timestamp of the creation of the log used to support the 2605 replay function on this event stream. This time might be 2606 earlier than the earliest available information contained in 2607 the log. This object is updated if the log resets for some 2608 reason."; 2609 } 2610 leaf replay-log-aged-time { 2611 when "../replay-support"; 2612 if-feature "replay"; 2613 type yang:date-and-time; 2614 description 2615 "The timestamp associated with last event record which has 2616 been aged out of the log. This timestamp identifies how far 2617 back into history this replay log extends, if it doesn't 2618 extend back to the 'replay-log-creation-time'. This object 2619 MUST be present if replay is supported and any event records 2620 have been aged out of the log."; 2621 } 2622 } 2623 } 2625 container filters { 2626 description 2627 "This container contains a list of configurable filters 2628 that can be applied to subscriptions. This facilitates 2629 the reuse of complex filters once defined."; 2630 list stream-filter { 2631 key "name"; 2632 description 2633 "A list of pre-configured filters that can be applied to 2634 subscriptions."; 2635 leaf name { 2636 type string; 2637 description 2638 "An name to differentiate between filters."; 2639 } 2640 uses stream-filter-elements; 2641 } 2642 } 2644 container subscriptions { 2645 description 2646 "Contains the list of currently active subscriptions, i.e. 2647 subscriptions that are currently in effect, used for 2648 subscription management and monitoring purposes. This includes 2649 subscriptions that have been setup via RPC primitives as well as 2650 subscriptions that have been established via configuration."; 2651 list subscription { 2652 key "id"; 2653 description 2654 "The identity and specific parameters of a subscription. 2655 Subscriptions within this list can be created using a control 2656 channel or RPC, or be established through configuration. 2658 If configuration operations or the 'kill-subscription' RPC are 2659 used to delete a subscription, a 'subscription-terminated' 2660 message is sent to any active or suspended receivers."; 2661 leaf id { 2662 type subscription-id; 2663 description 2664 "Identifier of a subscription; unique within a publisher"; 2665 } 2666 uses subscription-policy { 2667 refine "target/stream/stream" { 2668 description 2669 "Indicates the event stream to be considered for this 2670 subscription. If an event stream has been removed, 2671 and no longer can be referenced by an active subscription, 2672 send a 'subscription-terminated' notification with 2673 'stream-unavailable' as the reason. If a configured 2674 subscription refers to a non-existent event stream, move 2675 that subscription to the 'invalid' state."; 2676 } 2677 refine "transport" { 2678 description 2679 "For a configured subscription, this leaf specifies the 2680 transport used to deliver messages destined to all 2681 receivers of that subscription. This object is mandatory 2682 for subscriptions in the configuration datastore. This 2683 object is not mandatory for dynamic subscriptions within 2684 the operational state datastore. The object should not 2685 be present for dynamic subscriptions."; 2686 } 2687 augment "target/stream" { 2688 description 2689 "Enables objects to added to a configured stream 2690 subscription"; 2691 leaf configured-replay { 2692 if-feature "configured"; 2693 if-feature "replay"; 2694 type empty; 2695 description 2696 "The presence of this leaf indicates that replay for the 2697 configured subscription should start at the earliest time 2698 in the event log, or at the publisher boot time, which 2699 ever is later."; 2700 } 2702 } 2703 } 2704 choice notification-message-origin { 2705 if-feature "configured"; 2706 description 2707 "Identifies the egress interface on the publisher from which 2708 notification messages are to be sent."; 2709 case interface-originated { 2710 description 2711 "When notification messages to egress a specific, 2712 designated interface on the publisher."; 2713 leaf source-interface { 2714 if-feature "interface-designation"; 2715 type if:interface-ref; 2716 description 2717 "References the interface for notification messages."; 2718 } 2719 } 2720 case address-originated { 2721 description 2722 "When notification messages are to depart from a publisher 2723 using specific originating address and/or routing context 2724 information."; 2725 leaf source-vrf { 2726 if-feature "supports-vrf"; 2727 type leafref { 2728 path "/ni:network-instances/ni:network-instance/ni:name"; 2729 } 2730 description 2731 "VRF from which notification messages should egress a 2732 publisher."; 2733 } 2734 leaf source-address { 2735 type inet:ip-address-no-zone; 2736 description 2737 "The source address for the notification messages. If a 2738 source VRF exists, but this object doesn't, a publisher's 2739 default address for that VRF must be used."; 2740 } 2741 } 2742 } 2743 leaf configured-subscription-state { 2744 if-feature "configured"; 2745 type enumeration { 2746 enum valid { 2747 value 1; 2748 description 2749 "Subscription is supportable with current parameters."; 2751 } 2752 enum invalid { 2753 value 2; 2754 description 2755 "The subscription as a whole is unsupportable with its 2756 current parameters."; 2757 } 2758 enum concluded { 2759 value 3; 2760 description 2761 "A subscription is inactive as it has hit a stop time, 2762 but not yet been removed from configuration."; 2763 } 2764 } 2765 config false; 2766 description 2767 "The presence of this leaf indicates that the subscription 2768 originated from configuration, not through a control channel 2769 or RPC. The value indicates the system established state 2770 of the subscription."; 2771 } 2772 container receivers { 2773 description 2774 "Set of receivers in a subscription."; 2775 list receiver { 2776 key "name"; 2777 min-elements 1; 2778 description 2779 "A host intended as a recipient for the notification 2780 messages of a subscription. For configured subscriptions, 2781 transport specific network parameters (or a leafref to 2782 those parameters) may augmentated to a specific receiver 2783 within this list."; 2784 leaf name { 2785 type string; 2786 description 2787 "Identifies a unique receiver for a subscription."; 2788 } 2789 leaf sent-event-records { 2790 type yang:zero-based-counter64; 2791 config false; 2792 description 2793 "The number of event records sent to the receiver. The 2794 count is initialized when a dynamic subscription is 2795 established, or when a configured receiver 2796 transitions to the valid state."; 2797 } 2798 leaf excluded-event-records { 2799 type yang:zero-based-counter64; 2800 config false; 2801 description 2802 "The number of event records explicitly removed either 2803 via an event stream filter or an access control filter so 2804 that they are not passed to a receiver. This count is 2805 set to zero each time 'sent-event-records' is 2806 initialized."; 2807 } 2808 leaf state { 2809 type enumeration { 2810 enum active { 2811 value 1; 2812 description 2813 "Receiver is currently being sent any applicable 2814 notification messages for the subscription."; 2815 } 2816 enum suspended { 2817 value 2; 2818 description 2819 "Receiver state is 'suspended', so the publisher 2820 is currently unable to provide notification messages 2821 for the subscription."; 2822 } 2823 enum connecting { 2824 value 3; 2825 if-feature "configured"; 2826 description 2827 "A subscription has been configured, but a 2828 'subscription-started' subscription state change 2829 notification needs to be successfully received before 2830 notification messages are sent. 2832 If the 'reset' action is invoked for a receiver of an 2833 active configured subscription, the state must be 2834 moved to 'connecting'."; 2835 } 2836 enum disconnected { 2837 value 4; 2838 if-feature "configured"; 2839 description 2840 "A subscription has failed in sending a subscription 2841 started state change to the receiver. 2842 Additional attempts at connection attempts are not 2843 currently being made."; 2844 } 2845 } 2846 config false; 2847 mandatory true; 2848 description 2849 "Specifies the state of a subscription from the 2850 perspective of a particular receiver. With this info it 2851 is possible to determine whether a subscriber is 2852 currently generating notification messages intended for 2853 that receiver."; 2854 } 2855 action reset { 2856 if-feature "configured"; 2857 description 2858 "Allows the reset of this configured subscription 2859 receiver to the 'connecting' state. This enables the 2860 connection process to be re-initiated."; 2861 output { 2862 leaf time { 2863 type yang:date-and-time; 2864 mandatory true; 2865 description 2866 "Time a publisher returned the receiver to a 2867 'connecting' state."; 2868 } 2869 } 2870 } 2871 } 2872 } 2873 } 2874 } 2875 } 2876 2878 5. Considerations 2880 5.1. IANA Considerations 2882 This document registers the following namespace URI in the "IETF XML 2883 Registry" [RFC3688]: 2885 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2886 Registrant Contact: The IESG. 2887 XML: N/A; the requested URI is an XML namespace. 2889 This document registers the following YANG module in the "YANG Module 2890 Names" registry [RFC6020]: 2892 Name: ietf-subscribed-notifications 2893 Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2894 Prefix: sn 2895 Reference: draft-ietf-netconf-ietf-subscribed-notifications-11.txt 2896 (RFC form) 2898 5.2. Implementation Considerations 2900 To support deployments including both configured and dynamic 2901 subscriptions, it is recommended to split the subscription "id" 2902 domain into static and dynamic halves. That way it eliminates the 2903 possibility of collisions if the configured subscriptions attempt to 2904 set a subscription-id which might have already been dynamically 2905 allocated. A best practice is to use lower half the "id" object's 2906 integer space when that "id" is assigned by an external entity (such 2907 as with a configured subscription). This leaves the upper half of 2908 subscription integer space available to be dynamically assigned by 2909 the publisher. 2911 If a subscription is unable to marshal a series of filtered event 2912 records into transmittable notification messages, the receiver should 2913 be suspended with the reason "unsupportable-volume". 2915 For configured subscriptions, operations are against the set of 2916 receivers using the subscription "id" as a handle for that set. But 2917 for streaming updates, subscription state change notifications are 2918 local to a receiver. In this specification it is the case that 2919 receivers get no information from the publisher about the existence 2920 of other receivers. But if a network operator wants to let the 2921 receivers correlate results, it is useful to use the subscription 2922 "id" across the receivers to allow that correlation. 2924 For configured replay subscriptions, the receiver is protected from 2925 duplicated events being pushed after a publisher is rebooted. 2926 However it is possible that a receiver might want to acquire event 2927 records which failed to be delivered just prior to the reboot. 2928 Delivering these event records be accomplished by leveraging the 2929 "eventTime" from the last event record received prior to the receipt 2930 of a "subscription-started" subscription state change notification. 2931 With this "eventTime" and the "replay-start-time" from the 2932 "subscription-started" notification, an independent dynamic 2933 subscription can be established which retrieves any event records 2934 which may have been generated but not sent to the receiver. 2936 5.3. Transport Requirements 2938 This section provides requirements for any subscribed notification 2939 transport supporting the solution presented in this document. 2941 The transport selected by the subscriber to reach the publisher MUST 2942 be able to support multiple "establish-subscription" requests made 2943 within the same transport session. 2945 For both configured and dynamic subscriptions the publisher MUST 2946 authenticate a receiver via some transport level mechanism before 2947 sending any event records for which they are authorized to see. In 2948 addition, the receiver MUST authenticate the publisher at the 2949 transport level. The result is mutual authentication between the 2950 two. 2952 A secure transport is highly recommended and the publisher MUST 2953 ensure that the receiver has sufficient authorization to perform the 2954 function they are requesting against the specific subset of content 2955 involved. 2957 A specific transport specification built upon this document may or 2958 may not choose to require the use of the same logical channel for the 2959 RPCs and the event records. However the event records and the 2960 subscription state change notifications MUST be sent on the same 2961 transport session to ensure the properly ordered delivery. 2963 Additional transport requirements will be dictated by the choice of 2964 transport used with a subscription. For an example of such 2965 requirements with NETCONF transport, see 2966 [I-D.draft-ietf-netconf-netconf-event-notifications]. 2968 5.4. Security Considerations 2970 The YANG module specified in this document defines a schema for data 2971 that is designed to be accessed via network management transports 2972 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 2973 layer is the secure transport layer, and the mandatory-to-implement 2974 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 2975 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 2976 transport is TLS [RFC5246]. 2978 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 2979 to restrict access for particular NETCONF or RESTCONF users to a 2980 preconfigured subset of all available NETCONF or RESTCONF operations 2981 and content. 2983 One subscription "id" can be used for two or more receivers of the 2984 same configured subscription. But due to the possibility of 2985 different access control permissions per receiver, it cannot be 2986 assumed that each receiver is getting identical updates. 2988 With configured subscriptions, one or more publishers could be used 2989 to overwhelm a receiver. Notification messages SHOULD NOT be sent to 2990 any receiver which does not support this specification. Receivers 2991 that do not want notification messages need only terminate or refuse 2992 any transport sessions from the publisher. 2994 When a receiver of a configured subscription gets a new 2995 "subscription-started" message for a known subscription where it is 2996 already consuming events, the receiver SHOULD retrieve any event 2997 records generated since the last event record was received. This can 2998 be accomplish by establishing a separate dynamic replay subscription 2999 with the same filtering criteria with the publisher, assuming the 3000 publisher supports the "replay" feature. 3002 For dynamic subscriptions, implementations need to protect against 3003 malicious or buggy subscribers which may send a large number 3004 "establish-subscription" requests, thereby using up system resources. 3005 To cover this possibility operators SHOULD monitor for such cases 3006 and, if discovered, take remedial action to limit the resources used, 3007 such as suspending or terminating a subset of the subscriptions or, 3008 if the underlying transport is session based, terminate the 3009 underlying transport session. 3011 There are a number of data nodes defined in this YANG module that are 3012 writable/creatable/deletable (i.e., config true, which is the 3013 default). These data nodes may be considered sensitive or vulnerable 3014 in some network environments. Write operations (e.g., edit-config) 3015 to these data nodes without proper protection can have a negative 3016 effect on network operations. These are the subtrees and data nodes 3017 where there is a specific sensitivity/vulnerability: 3019 Container: "/filters" 3021 o "stream-subtree-filter": updating a filter could increase the 3022 computational complexity of all referencing subscriptions. 3024 o "stream-xpath-filter": updating a filter could increase the 3025 computational complexity of all referencing subscriptions. 3027 Container: "/subscriptions" 3029 The following considerations are only relevant for configuration 3030 operations made upon configured subscriptions: 3032 o "configured-replay": can be used to send a large number of event 3033 records to a receiver. 3035 o "dependency": can be used to force important traffic to be queued 3036 behind less important updates. 3038 o "dscp": if unvalidated, can result in the sending of traffic with 3039 a higher priority marking than warranted. 3041 o "id": can overwrite an existing subscription, perhaps one 3042 configured by another entity. 3044 o "name": adding a new key entry can be used to attempt to send 3045 traffic to an unwilling receiver. 3047 o "replay-start-time": can be used to push very large logs, wasting 3048 resources. 3050 o "source-address": the configured address might not be able to 3051 reach a desired receiver. 3053 o "source-interface": the configured interface might not be able to 3054 reach a desired receiver. 3056 o "source-vrf": can place a subscription into a virtual network 3057 where receivers are not entitled to view the subscribed content. 3059 o "stop-time": could be used to terminate content at an inopportune 3060 time. 3062 o "stream": could set a subscription to an event stream containing 3063 no content permitted for the targeted receivers. 3065 o "stream-filter-name": could be set to a filter which is irrelevant 3066 to the event stream. 3068 o "stream-subtree-filter": a complex filter can increase the 3069 computational resources for this subscription. 3071 o "stream-xpath-filter": a complex filter can increase the 3072 computational resources for this subscription. 3074 o "weighting": placing a large weight can overwhelm the dequeuing of 3075 other subscriptions. 3077 Some of the readable data nodes in this YANG module may be considered 3078 sensitive or vulnerable in some network environments. It is thus 3079 important to control read access (e.g., via get, get-config, or 3080 notification) to these data nodes. These are the subtrees and data 3081 nodes and their sensitivity/vulnerability: 3083 Container: "/streams" 3085 o "name": if access control is not properly configured, can expose 3086 system internals to those who should have no access to this 3087 information. 3089 o "replay-support": if access control is not properly configured, 3090 can expose logs to those who should have no access. 3092 Container: "/subscriptions" 3094 o "excluded-event-records": leaf can provide information about 3095 filtered event records. A network operator should have 3096 permissions to know about such filtering. 3098 o "subscription": different operational teams might have a desire to 3099 set varying subsets of subscriptions. Access control should be 3100 designed to permit read access to just the allowed set. 3102 Some of the RPC operations in this YANG module may be considered 3103 sensitive or vulnerable in some network environments. It is thus 3104 important to control access to these operations. These are the 3105 operations and their sensitivity/vulnerability: 3107 RPC: all 3109 o If a malicious or buggy subscriber sends an unexpectedly large 3110 number of RPCs, the result might be an excessive use of system 3111 resources on the publisher just to determine that these 3112 subscriptions should be declined. In such a situation, 3113 subscription interactions MAY be terminated by terminating the 3114 transport session. 3116 RPC: "delete-subscription" 3118 o No special considerations. 3120 RPC: "establish-subscription" 3122 o Subscriptions could overload a publisher's resources. For this 3123 reason, publishers MUST ensure that they have sufficient resources 3124 to fulfill this request or otherwise reject the request. 3126 RPC: "kill-subscription" 3128 o The "kill-subscription" RPC MUST be secured so that only 3129 connections with administrative rights are able to invoke this 3130 RPC. 3132 RPC: "modify-subscription" 3134 o Subscriptions could overload a publisher's resources. For this 3135 reason, publishers MUST ensure that they have sufficient resources 3136 to fulfill this request or otherwise reject the request. 3138 6. Acknowledgments 3140 For their valuable comments, discussions, and feedback, we wish to 3141 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen, 3142 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan 3143 Hares, Michael Scharf, and Guangying Zheng. 3145 7. References 3147 7.1. Normative References 3149 [I-D.draft-ietf-rtgwg-ni-model] 3150 Berger, L., Hopps, C., and A. Lindem, "YANG Network 3151 Instances", draft-ietf-rtgwg-ni-model-12 (work in 3152 progress), March 2018. 3154 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3155 Requirement Levels", BCP 14, RFC 2119, 3156 DOI 10.17487/RFC2119, March 1997, 3157 . 3159 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3160 "Definition of the Differentiated Services Field (DS 3161 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3162 DOI 10.17487/RFC2474, December 1998, 3163 . 3165 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3166 DOI 10.17487/RFC3688, January 2004, 3167 . 3169 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3170 (TLS) Protocol Version 1.2", RFC 5246, 3171 DOI 10.17487/RFC5246, August 2008, 3172 . 3174 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3175 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 3176 . 3178 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 3179 the Network Configuration Protocol (NETCONF)", RFC 6020, 3180 DOI 10.17487/RFC6020, October 2010, 3181 . 3183 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3184 and A. Bierman, Ed., "Network Configuration Protocol 3185 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 3186 . 3188 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 3189 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 3190 . 3192 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 3193 RFC 6991, DOI 10.17487/RFC6991, July 2013, 3194 . 3196 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3197 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3198 . 3200 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3201 RFC 7951, DOI 10.17487/RFC7951, August 2016, 3202 . 3204 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 3205 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 3206 . 3208 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3209 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3210 May 2017, . 3212 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 3213 Access Control Model", STD 91, RFC 8341, 3214 DOI 10.17487/RFC8341, March 2018, 3215 . 3217 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 3218 and R. Wilton, "Network Management Datastore Architecture 3219 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 3220 . 3222 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 3223 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 3224 . 3226 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 3227 Version 1.0", November 1999, 3228 . 3230 7.2. Informative References 3232 [I-D.draft-ietf-netconf-netconf-event-notifications] 3233 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3234 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 3235 event notifications", May 2018, 3236 . 3239 [I-D.draft-ietf-netconf-restconf-notif] 3240 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 3241 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 3242 HTTP transport for event notifications", May 2018, 3243 . 3246 [I-D.ietf-netconf-yang-push] 3247 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3248 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 3249 Lengyel, "YANG Datastore Subscription", May 2018, 3250 . 3253 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 3254 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 3255 DOI 10.17487/RFC7540, May 2015, 3256 . 3258 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 3259 for Subscription to YANG Datastores", RFC 7923, 3260 DOI 10.17487/RFC7923, June 2016, 3261 . 3263 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 3264 RFC 8071, DOI 10.17487/RFC8071, February 2017, 3265 . 3267 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3268 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3269 . 3271 Appendix A. Example Configured Transport Augmentation 3273 This appendix provides a non-normative example of how the YANG model 3274 defined in Section 4 may be enhanced to incorporate the configuration 3275 parameters needed to support the transport connectivity process. In 3276 this example, connectivity via an imaginary transport type of "foo" 3277 is explored. For more on the overall need, see Section 2.5.7. 3279 The YANG model defined in this section contains two main elements. 3280 First is a transport identity "foo". This transport identity allows 3281 a configuration agent to define "foo" as the selected type of 3282 transport for a subscription. Second is a YANG case augmentation 3283 "foo" which is made to the "/subscriptions/subscription/receivers/ 3284 receiver" node of Section 4. Within this augmentation are the 3285 transport configuration parameters "address" and "port" which are 3286 necessary to make the connect to the receiver. 3288 module example-foo-subscribed-notifications { 3289 yang-version 1.1; 3290 namespace 3291 "urn:example:foo-subscribed-notifications"; 3293 prefix fsn; 3295 import ietf-subscribed-notifications { 3296 prefix sn; 3297 } 3298 import ietf-inet-types { 3299 prefix inet; 3300 } 3302 description 3303 "Defines 'foo' as a supported type of configured transport for 3304 subscribed event notifications."; 3306 identity foo { 3307 base sn:transport; 3308 description 3309 "Transport type 'foo' is available for use as a configured 3310 subscription transport protocol for subscribed notifications."; 3311 } 3313 augment 3314 "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 3315 when 'derived-from(../../../transport, "fsn:foo")'; 3316 description 3317 "This augmentation makes 'foo' specific transport parameters 3318 available for a receiver."; 3320 leaf address { 3321 type inet:host; 3322 mandatory true; 3323 description 3324 "Specifies the address to use for messages destined to a 3325 receiver."; 3326 } 3327 leaf port { 3328 type inet:port-number; 3329 mandatory true; 3330 description 3331 "Specifies the port number to use for messages destined to a 3332 receiver."; 3333 } 3334 } 3335 } 3337 Figure 21: Example Transport Augmentation for the fictitious protocol 3338 foo 3340 This example YANG model for transport "foo" will not be seen in a 3341 real world deployment. For a real world deployment supporting an 3342 actual transport technology, a similar YANG model must be defined. 3344 Appendix B. Changes between revisions 3346 (To be removed by RFC editor prior to publication) 3348 v20 - v21 3350 o Editorial change in Section 1.3 requested by Qin's Shepherd review 3351 of NETCONF-Notif and RESTCONF-Notif. Basically extra text was 3352 added further describing that dynamic subscriptions can have state 3353 change notifications. 3355 v18 - v20 3357 o XPath-stream-filter YANG object definition updated based on NETMOD 3358 discussions. 3360 v17 - v18 3362 o Transport optional in YANG model. 3364 o Modify subscription must come from the originator of the 3365 subscription. (Text got dropped somewhere previously.) 3367 o Title change. 3369 v16 - v17 3371 o YANG renaming: Subscription identifier renamed to id. Counters 3372 renamed. Filters id made into name. 3374 o Text tweaks. 3376 v15 - v16 3378 o Mandatory empty case "transport" removed. 3380 o Appendix case turned from "netconf" to "foo". 3382 v14 - v15 3384 o Text tweaks. 3386 o Mandatory empty case "transport" added for transport parameters. 3387 This includes a new section and an appendix explaining it. 3389 v13 - v14 3391 o Removed the 'address' leaf. 3393 o Replay is now of type 'empty' for configured. 3395 v12 - v13 3397 o Tweaks from Kent's comments 3399 o Referenced in YANG model updated per Tom Petch's comments 3401 o Added leaf replay-previous-event-time 3403 o Renamed the event counters, downshifted the subscription states 3405 v11 - v12 3407 o Tweaks from Kent's, Tim's, and Martin's comments 3409 o Clarified dscp text, and made its own feature 3411 o YANG model tweaks alphabetizing, features. 3413 v10 - v11 3415 o access control filtering of events in streams included to match 3416 RFC5277 behavior 3418 o security considerations updated based on YANG template. 3420 o dependency QoS made non-normative on HTTP2 QoS 3422 o tree diagrams referenced for each figure using them 3424 o reference numbers placed into state machine figures 3426 o broke configured replay into its own section 3428 o many tweaks updates based on LC and YANG doctor reviews 3430 o trees and YANG model reconciled were deltas existed 3432 o new feature for interface originated. 3434 o dscp removed from the qos feature 3436 o YANG model updated in a way which collapses groups only used once 3437 so that they are part of the 'subscriptions' container. 3439 o alternative encodings only allowed for transports which support 3440 them. 3442 v09 - v10 3444 o Typos and tweaks 3446 v08 - v09 3448 o NMDA model supported. Non NMDA version at https://github.com/ 3449 netconf-wg/rfc5277bis/ 3451 o Error mechanism revamped to match to embedded implementations. 3453 o Explicitly identified error codes relevant to each RPC/ 3454 Notification 3456 v07 - v08 3458 o Split YANG trees to separate document subsections. 3460 o Clarified configured state machine based on Balazs comments, and 3461 moved it into the configured subscription subsections. 3463 o Normative reference to Network Instance model for VRF 3465 o One transport for all receivers of configured subscriptions. 3467 o QoS section moved in from yang-push 3469 v06 - v07 3471 o Clarification on state machine for configured subscriptions. 3473 v05 - v06 3475 o Made changes proposed by Martin, Kent, and others on the list. 3476 Most significant of these are stream returned to string (with the 3477 SYSLOG identity removed), intro section on 5277 relationship, an 3478 identity set moved to an enumeration, clean up of definitions/ 3479 terminology, state machine proposed for configured subscriptions 3480 with a clean-up of subscription state options. 3482 o JSON and XML become features. Also Xpath and subtree filtering 3483 become features 3485 o Terminology updates with event records, and refinement of filters 3486 to just event stream filters. 3488 o Encoding refined in establish-subscription so it takes the RPC's 3489 encoding as the default. 3491 o Namespaces in examples fixed. 3493 v04 - v05 3495 o Returned to the explicit filter subtyping of v00 3497 o stream object changed to 'name' from 'stream' 3499 o Cleaned up examples 3501 o Clarified that JSON support needs notification-messages draft. 3503 v03 - v04 3505 o Moved back to the use of RFC5277 one-way notifications and 3506 encodings. 3508 v03 - v04 3510 o Replay updated 3512 v02 - v03 3513 o RPCs and Notification support is identified by the Notification 3514 2.0 capability. 3516 o Updates to filtering identities and text 3518 o New error type for unsupportable volume of updates 3520 o Text tweaks. 3522 v01 - v02 3524 o Subscription status moved under receiver. 3526 v00 - v01 3528 o Security considerations updated 3530 o Intro rewrite, as well as scattered text changes 3532 o Added Appendix A, to help match this to related drafts in progress 3534 o Updated filtering definitions, and filter types in yang file, and 3535 moved to identities for filter types 3537 o Added Syslog as an event stream 3539 o HTTP2 moved in from YANG-Push as a transport option 3541 o Replay made an optional feature for events. Won't apply to 3542 datastores 3544 o Enabled notification timestamp to have different formats. 3546 o Two error codes added. 3548 v01 5277bis - v00 subscribed notifications 3550 o Kill subscription RPC added. 3552 o Renamed from 5277bis to Subscribed Notifications. 3554 o Changed the notification capabilities version from 1.1 to 2.0. 3556 o Extracted create-subscription and other elements of RFC5277. 3558 o Error conditions added, and made specific in return codes. 3560 o Simplified yang model structure for removal of 'basic' grouping. 3562 o Added a grouping for items which cannot be statically configured. 3564 o Operational counters per receiver. 3566 o Subscription-id and filter-id renamed to identifier 3568 o Section for replay added. Replay now cannot be configured. 3570 o Control plane notification renamed to subscription state change 3571 notification 3573 o Source address: Source-vrf changed to string, default address 3574 option added 3576 o In yang model: 'info' changed to 'policy' 3578 o Scattered text clarifications 3580 v00 - v01 of 5277bis 3582 o YANG Model changes. New groupings for subscription info to allow 3583 restriction of what is changeable via RPC. Removed notifications 3584 for adding and removing receivers of configured subscriptions. 3586 o Expanded/renamed definitions from event server to publisher, and 3587 client to subscriber as applicable. Updated the definitions to 3588 include and expand on RFC 5277. 3590 o Removal of redundancy with other drafts 3592 o Many other clean-ups of wording and terminology 3594 Authors' Addresses 3596 Eric Voit 3597 Cisco Systems 3599 Email: evoit@cisco.com 3601 Alexander Clemm 3602 Huawei 3604 Email: ludwig@clemm.org 3605 Alberto Gonzalez Prieto 3606 Microsoft 3608 Email: alberto.gonzalez@microsoft.com 3610 Einar Nilsen-Nygaard 3611 Cisco Systems 3613 Email: einarnn@cisco.com 3615 Ambika Prasad Tripathy 3616 Cisco Systems 3618 Email: ambtripa@cisco.com