idnits 2.17.1 draft-ietf-netconf-subscribed-notifications-04.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 449 has weird spacing: '...-result sub...' == Line 455 has weird spacing: '...ntifier sub...' == Line 457 has weird spacing: '...-result sub...' == Line 460 has weird spacing: '...ntifier sub...' == Line 462 has weird spacing: '...-result sub...' == (3 more instances...) -- The document date (September 19, 2017) is 2404 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-09) exists of draft-ietf-netconf-rfc6536bis-01 -- Possible downref: Normative reference to a draft: ref. 'RFC6536bis' -- 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 (~~), 8 warnings (==), 4 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: March 23, 2018 Huawei 6 A. Gonzalez Prieto 7 VMWare 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 September 19, 2017 13 Custom Subscription to Event Notifications 14 draft-ietf-netconf-subscribed-notifications-04 16 Abstract 18 This document defines capabilities and operations for the customized 19 establishment of subscriptions upon a publisher's event streams. 20 Also defined are delivery mechanisms for instances of the resulting 21 events. Effectively this allows a subscriber to request and receive 22 a continuous, custom influx of publisher generated 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 March 23, 2018. 41 Copyright Notice 43 Copyright (c) 2017 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 5 62 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 6 64 2.2. Event Filters . . . . . . . . . . . . . . . . . . . . . . 6 65 2.3. Subscription State Model at the Publisher . . . . . . . . 7 66 3. Data Model Trees . . . . . . . . . . . . . . . . . . . . . . 8 67 4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . . . 12 68 4.1. Establishing a Subscription . . . . . . . . . . . . . . . 12 69 4.2. Modifying a Subscription . . . . . . . . . . . . . . . . 13 70 4.3. Deleting a Subscription . . . . . . . . . . . . . . . . . 14 71 4.4. Killing a Subscription . . . . . . . . . . . . . . . . . 14 72 5. Configured Subscriptions . . . . . . . . . . . . . . . . . . 14 73 5.1. Establishing a Configured Subscription . . . . . . . . . 15 74 5.2. Modifying a Configured Subscription . . . . . . . . . . . 17 75 5.3. Deleting a Configured Subscription . . . . . . . . . . . 17 76 6. Deleting a Configured Subscription . . . . . . . . . . . . . 18 77 7. Asynchronous Subscribed Content Delivery . . . . . . . . . . 18 78 8. Subscription State Notifications . . . . . . . . . . . . . . 19 79 8.1. subscription-started . . . . . . . . . . . . . . . . . . 19 80 8.2. subscription-modified . . . . . . . . . . . . . . . . . . 19 81 8.3. subscription-terminated . . . . . . . . . . . . . . . . . 19 82 8.4. subscription-suspended . . . . . . . . . . . . . . . . . 20 83 8.5. subscription-resumed . . . . . . . . . . . . . . . . . . 20 84 8.6. subscription-completed . . . . . . . . . . . . . . . . . 20 85 8.7. replay-completed . . . . . . . . . . . . . . . . . . . . 20 86 9. Administrative Functions . . . . . . . . . . . . . . . . . . 20 87 9.1. Subscription Monitoring . . . . . . . . . . . . . . . . . 21 88 9.2. Capability Advertisement . . . . . . . . . . . . . . . . 21 89 9.3. Event Stream Discovery . . . . . . . . . . . . . . . . . 21 90 10. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 22 91 11. Considerations . . . . . . . . . . . . . . . . . . . . . . . 44 92 11.1. Implementation Considerations . . . . . . . . . . . . . 44 93 11.2. Security Considerations . . . . . . . . . . . . . . . . 45 94 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46 95 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 46 96 13.1. Normative References . . . . . . . . . . . . . . . . . . 46 97 13.2. Informative References . . . . . . . . . . . . . . . . . 47 98 Appendix A. Changes between revisions . . . . . . . . . . . . . 48 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 101 1. Introduction 103 This document defines capabilities and operations for the customized 104 establishment of subscriptions upon system generated event streams. 105 Effectively this enables a "Subscribe then Publish" capability where 106 the customized information needs of each target receiver are 107 understood by the publisher before events are marshalled and pushed. 108 The receiver then gets a continuous, custom influx of publisher 109 generated events. 111 While the functionality defined in this document is transport- 112 agnostic, subscription control plane operations bindings exist for 113 both NETCONF [RFC6241] and RESTCONF [RFC8040]. In addition, bindings 114 for the pushed event instances have been defined for protocols such 115 as NETCONF and HTTP2 [RFC7540]. For specifics on these bindings see 116 [I-D.ietf-netconf-event-notif]) and 117 [I-D.ietf-netconf-restconf-notif]. 119 1.1. Motivation 121 There are various [RFC5277] limitations, many of which have been 122 exposed in [RFC7923] which needed to be solved. Key capabilities 123 supported by this document include: 125 o multiple subscriptions on a single transport session 127 o support for dynamic and statically configured subscriptions 129 o modification of an existing subscription 131 o operational counters and instrumentation 133 o negotiation of subscription parameters 135 o promise theory based interaction model 137 o state change notifications (e.g., publisher driven suspension, 138 parameter modification) 140 o independence from transport protocol 142 1.2. Terminology 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 146 document are to be interpreted as described in RFC 2119 [RFC2119]. 148 Configured subscription: A subscription installed via a configuration 149 interface which persists across reboots. 151 Dynamic subscription: A subscription agreed between subscriber and 152 publisher created via RPC subscription state signaling messages. 154 Event: An occurrence of something that may be of interest. (e.g., a 155 configuration change, a fault, a change in status, crossing a 156 threshold, or an external input to the system.) 158 Filter: Evaluation and/or selection criteria, which may be applied 159 against a targeted set of objects or events in a subscription. 160 Information traverses the filter only if specified filter criteria 161 are met. 163 NACM: NETCONF Access Control Model. 165 Notification message: A set of information intended for a Receiver 166 indicating that one or more Event(s) have occurred. Details of the 167 Event(s) may be included within the Notification. 169 Publisher: An entity responsible for streaming notification messages 170 per the terms of a Subscription. 172 Receiver: A target to which a publisher pushes subscribed content. 173 For dynamic subscriptions, the receiver and subscriber are the same 174 entity. 176 Stream (also referred to as "event stream"): A continuous ordered set 177 of events aggregated under some context. 179 Subscriber: An entity able to request and negotiate a contract for 180 the generation and push of event notifications from a publisher. 182 Subscription: A contract with a publisher, stipulating which 183 information one or more receivers wish to have pushed from the 184 publisher without the need for further solicitation. 186 1.3. Solution Overview 188 This document describes a transport protocol-agnostic mechanism for 189 subscribing to and receiving content from a stream instantiated 190 within an event publisher. This mechanism is through the use of a 191 subscription. 193 Two types of subscriptions are supported: 195 1. Dynamic subscriptions, where a subscriber initiates a 196 subscription negotiation with a publisher via RPC. If the 197 publisher wants to serve this request, it accepts it, and then 198 starts pushing notification messages. If the publisher does not 199 wish to serve it as requested, then an error response is 200 returned. This response MAY include hints at subscription 201 parameters which would have been accepted. 203 2. Configured subscriptions, which allow the management of 204 subscriptions via a configuration interface so that a publisher 205 can send notification messages to configured receiver(s). 206 Support for this capability is optional. 208 Additional characteristics differentiating configured from dynamic 209 subscriptions include: 211 o The lifetime of a dynamic subscription is bounded by the transport 212 session used to establish it. For connection-oriented stateful 213 transport like NETCONF, the loss of the transport session will 214 result in the immediate termination of associated dynamic 215 subscriptions. For connectionless or stateless transports like 216 HTTP, it is the lack of receipt acknowledgement of a sequential 217 set of notification messages and/or keep-alives which will 218 terminate dynamic subscriptions. The lifetime of a configured 219 subscription is driven by relevant configuration being present on 220 the running configuration. This implies configured subscriptions 221 persist across reboots, and persist even when transport is 222 unavailable. 224 o Configured subscriptions can be modified by any configuration 225 client with write permission on the configuration of the 226 subscription. Dynamic subscriptions can only be modified via an 227 RPC request made upon the original subscribing transport session. 229 Note that there is no mixing-and-matching of dynamic and configured 230 subscriptions. Specifically, a configured subscription cannot be 231 modified or deleted using RPC. Similarly, a subscription established 232 via RPC cannot be modified through configuration operations (if 233 needed, an operator may use a kill RPC however). 235 The publisher MAY decide to terminate a dynamic subscription at any 236 time. Similarly, it MAY decide to temporarily suspend the sending of 237 notification messages for either configured or dynamic subscriptions. 238 Such termination or suspension MAY be driven by the publisher running 239 out of resources to serve the subscription, or by internal errors on 240 the publisher. 242 2. Solution 244 2.1. Event Streams 246 An event stream is a named entity on a publisher which exposes a 247 continuously updating set of events. Each event stream is available 248 for subscription. It is out of the scope of this document to 249 identify a) how streams are defined, b) how events are defined/ 250 generated, and c) how events are assigned to streams. 252 There are two standardized event streams within this document: 253 NETCONF and SYSLOG. The NETCONF event stream contains all NETCONF 254 XML event information supported by the publisher, except for where it 255 has been explicitly indicated that this the event MUST be excluded 256 from the NETCONF stream. The SYSLOG event stream mirrors the 257 discrete set entries which are concurrently being placed into a 258 device's local Syslog. Beyond these two, additional streams can be 259 added via model augmentation. 261 As events are raised by a system, they may be assigned to one or more 262 streams. The event is distributed to receivers where: (1) a 263 subscription includes the identified stream, and (2) subscription 264 filtering allows the event to traverse. 266 If access control permissions are in use to secure publisher content, 267 then for notifications to be sent to a receiver, that receiver MUST 268 be allowed access to all the events on the stream. If permissions 269 change during the lifecycle of a subscription, then events MUST be 270 sent or restricted accordingly. This can be done by re-establishing 271 a subscription with the updated permissions, or by seamlessly 272 updating the permissions of an existing subscription. 274 2.2. Event Filters 276 A publisher implementation MUST support the ability to perform 277 filtering of events within a stream. Two filtering syntaxes 278 supported are [XPATH] and subtree [RFC6241]. The subsets of these 279 filtering syntaxes supported are left to each implementation. Events 280 which evaluate to "true", or return a non-null selection as a result 281 of the evaluation by the event filter MUST traverse the filter in 282 their entirety. A subset of information is never stripped from 283 within the event. 285 If no event filter is provided, all events on a stream are to be 286 sent. 288 2.3. Subscription State Model at the Publisher 290 Below is the state machine of a subscription for the publisher for a 291 dynamic subscription. It is important to note that such a 292 subscription doesn't exist at the publisher until it is accepted and 293 made active. The mere request by a subscriber to establish a 294 subscription is insufficient for that asserted subscription to be 295 externally visible via this state machine. 297 .-------. 298 | start | 299 '-------' 300 | 301 establish 302 | 303 | .----------modify------------. 304 v v ' 305 .-----------. .-----------. 306 .--------. | |-----suspend------->| | 307 modify '| active | | suspended | 308 '--------->| |<----resume---------| | 309 '-----------' '-----------' 310 | | 311 delete/kill delete/kill 312 | | 313 v | 314 .-------. | 315 | end |<---------------------------' 316 '-------' 318 Figure 1: Subscription states at publisher 320 Of interest in this state machine are the following: 322 o Successful establish or modify RPCs put the subscription into an 323 active state. 325 o Failed modify RPCs will leave the subscription in its previous 326 state, with no visible change to any streaming updates. 328 o A delete or kill RPC will end the subscription. 330 o Suspend and resume state changes are driven by internal process 331 and prioritization. There are no external controls over suspend 332 and resume. 334 An equivalent state machine exists for configured subscriptions. 335 However the transition between states is via configuration operations 336 rather than via RPC. 338 3. Data Model Trees 340 module: ietf-subscribed-notifications 341 +--ro streams 342 | +--ro stream* [stream] 343 | +--ro stream stream 344 | +--ro description string 345 | +--ro replay-support? empty 346 | +--ro replay-log-creation-time? yang:date-and-time 347 | +--ro replay-log-aged-time? yang:date-and-time 348 +--rw filters 349 | +--rw filter* [identifier] 350 | +--rw identifier filter-id 351 | +--rw (filter-type)? 352 | +--:(event-filter) 353 | +--rw event-filter-type event-filter-type 354 | +--rw event-filter-contents 355 +--rw subscription-config {configured-subscriptions}? 356 | +--rw subscription* [identifier] 357 | +--rw identifier subscription-id 358 | +--rw encoding? encoding 359 | +--rw (target) 360 | | +--:(stream) 361 | | +--rw (event-filter)? 362 | | | +--:(by-reference) 363 | | | | +--rw filter-ref filter-ref 364 | | | +--:(within-subscription) 365 | | | +--rw event-filter-type event-filter-type 366 | | | +--rw event-filter-contents 367 | | +--rw stream stream 368 | | +--rw replay-start-time? yang:date-and-time {replay}? 369 | +--rw stop-time? yang:date-and-time 370 | +--rw receivers 371 | | +--rw receiver* [address port] 372 | | +--rw address inet:host 373 | | +--rw port inet:port-number 374 | | +--rw protocol? transport-protocol 375 | +--rw (notification-origin)? 376 | +--:(interface-originated) 377 | | +--rw source-interface? if:interface-ref 378 | +--:(address-originated) 379 | +--rw source-vrf? string 380 | +--rw source-address? inet:ip-address-no-zone 381 +--ro subscriptions 382 +--ro subscription* [identifier] 383 +--ro identifier subscription-id 384 +--ro configured-subscription? 385 | empty {configured-subscriptions}? 386 +--ro encoding? encoding 387 +--ro (target) 388 | +--:(stream) 389 | +--ro (event-filter)? 390 | | +--:(by-reference) 391 | | | +--ro filter-ref filter-ref 392 | | +--:(within-subscription) 393 | | +--ro event-filter-type event-filter-type 394 | | +--ro event-filter-contents 395 | +--ro stream stream 396 | +--ro replay-start-time? yang:date-and-time {replay}? 397 +--ro stop-time? yang:date-and-time 398 +--ro (notification-origin)? 399 | +--:(interface-originated) 400 | | +--ro source-interface? if:interface-ref 401 | +--:(address-originated) 402 | +--ro source-vrf? string 403 | +--ro source-address? inet:ip-address-no-zone 404 +--ro receivers 405 +--ro receiver* [address port] 406 +--ro address inet:host 407 +--ro port inet:port-number 408 +--ro protocol? transport-protocol 409 +--ro pushed-notifications? yang:counter64 410 +--ro excluded-notifications? yang:counter64 411 +--ro status subscription-status 413 rpcs: 414 +---x establish-subscription 415 | +---w input 416 | | +---w encoding? encoding 417 | | +---w (target) 418 | | | +--:(stream) 419 | | | +---w (event-filter)? 420 | | | | +--:(by-reference) 421 | | | | | +---w filter-ref filter-ref 422 | | | | +--:(within-subscription) 423 | | | | +---w event-filter-type event-filter-type 424 | | | | +---w event-filter-contents 425 | | | +---w stream stream 426 | | | +---w replay-start-time? yang:date-and-time {replay}? 427 | | +---w stop-time? yang:date-and-time 428 | +--ro output 429 | +--ro subscription-result subscription-result 430 | +--ro (result)? 431 | +--:(no-success) 432 | | +--ro filter-failure? string 433 | | +--ro replay-start-time-hint? yang:date-and-time 434 | +--:(success) 435 | +--ro identifier subscription-id 436 +---x modify-subscription 437 | +---w input 438 | | +---w identifier? subscription-id 439 | | +---w (target) 440 | | | +--:(stream) 441 | | | +---w (event-filter)? 442 | | | +--:(by-reference) 443 | | | | +---w filter-ref filter-ref 444 | | | +--:(within-subscription) 445 | | | +---w event-filter-type event-filter-type 446 | | | +---w event-filter-contents 447 | | +---w stop-time? yang:date-and-time 448 | +--ro output 449 | +--ro subscription-result subscription-result 450 | +--ro (result)? 451 | +--:(no-success) 452 | +--ro filter-failure? string 453 +---x delete-subscription 454 | +---w input 455 | | +---w identifier subscription-id 456 | +--ro output 457 | +--ro subscription-result subscription-result 458 +---x kill-subscription 459 +---w input 460 | +---w identifier subscription-id 461 +--ro output 462 +--ro subscription-result subscription-result 464 notifications: 465 +---n replay-completed 466 | +--ro identifier subscription-id 467 +---n subscription-completed 468 | +--ro identifier subscription-id 469 +---n subscription-started 470 | +--ro identifier subscription-id 471 | +--ro encoding? encoding 472 | +--ro (target) 473 | | +--:(stream) 474 | | +--ro (event-filter)? 475 | | | +--:(by-reference) 476 | | | | +--ro filter-ref filter-ref 477 | | | +--:(within-subscription) 478 | | | +--ro event-filter-type event-filter-type 479 | | | +--ro event-filter-contents 480 | | +--ro stream stream 481 | | +--ro replay-start-time? yang:date-and-time {replay}? 482 | +--ro stop-time? yang:date-and-time 483 +---n subscription-resumed 484 | +--ro identifier subscription-id 485 +---n subscription-modified 486 | +--ro identifier subscription-id 487 | +--ro encoding? encoding 488 | +--ro (target) 489 | | +--:(stream) 490 | | +--ro (event-filter)? 491 | | | +--:(by-reference) 492 | | | | +--ro filter-ref filter-ref 493 | | | +--:(within-subscription) 494 | | | +--ro event-filter-type event-filter-type 495 | | | +--ro event-filter-contents 496 | | +--ro stream stream 497 | | +--ro replay-start-time? yang:date-and-time {replay}? 498 | +--ro stop-time? yang:date-and-time 499 +---n subscription-terminated 500 | +--ro identifier subscription-id 501 | +--ro error-id subscription-errors 502 | +--ro filter-failure? string 503 +---n subscription-suspended 504 +--ro identifier subscription-id 505 +--ro error-id subscription-errors 506 +--ro filter-failure? string 508 The top-level decompositions of data model are as follows: 510 o "Streams" contains a list of event streams that are supported by 511 the publisher and against which subscription is allowed. 513 o "Filters" contains a configurable list of filters that can be 514 applied to a subscription. This allows users to reference an 515 existing filter definition as an alternative to defining a filter 516 inline for each subscription. 518 o "Subscription-config" contains the configuration of configured 519 subscriptions. The parameters of each configured subscription are 520 a superset of the parameters of a dynamic subscription and use the 521 same groupings. In addition, the configured subscriptions MUST 522 also specify intended receivers and MAY specify the push source 523 from which to send the stream of notification messages. 525 o "Subscriptions" contains a list of all subscriptions on a 526 publisher, both configured and dynamic. It can be used to 527 retrieve information about the subscriptions which a publisher is 528 serving. 530 The data model also contains a number of notifications that allow a 531 publisher to signal information about a subscription. Finally, the 532 data model contains a number of RPC definitions that are used to 533 manage dynamic subscriptions. 535 4. Dynamic Subscriptions 537 Dynamic subscriptions are managed via RPC. 539 4.1. Establishing a Subscription 541 The operation allows a subscriber to request 542 the creation of a subscription via RPC. 544 The input parameters of the operation are: 546 o A stream which identifies the domain of events against which the 547 subscription is applied. 549 o A filter which may reduce the set of events pushed. 551 o The desired encoding for the returned events. By default, updates 552 are encoded using XML. Other encodings MAY be supported, such as 553 JSON. 555 o An optional stop time for the subscription. 557 o An optional start time which indicates that this subscription is 558 requesting a replay push of events previously generated. 560 If the publisher cannot satisfy the request, 561 it sends a negative element. If the subscriber 562 has no authorization to establish the subscription, the 563 indicates an authorization error. Optionally, 564 the MAY include one or more hints on 565 alternative input parameters and value which would have resulted in 566 an accepted subscription. 568 Subscription requests MUST fail if a filter with invalid syntax is 569 provided or if a non-existent stream is referenced. 571 4.1.1. Replay Subscription 573 Replay provides the ability to establish an event subscription which 574 is also capable of passing along recently generated events. In other 575 words, as the subscription initializes itself, it sends any 576 previously generated notifications for the target event stream which 577 meet the filter and timeframe criteria. These historical events 578 would then be followed by events generated after the subscription has 579 been established. All events will be delivered in the order 580 generated. Replay is only viable for dynamic subscriptions. Replay 581 is an optional feature. Replay is dependent on a notification stream 582 supporting some form of notification logging, although it puts no 583 restrictions on the size or form of the log, or where it resides 584 within the device. 586 The presence of a replay-start-time within an RPC is the way a replay may be been requested. The 588 provided start time MUST be earlier than the current time. If the 589 start time points earlier than the maintained history of Publisher's 590 event buffer, then the subscription MUST be rejected. In this case 591 the error response to the request SHOULD 592 include a start time supportable by the Publisher. An end time MAY 593 be specified using the optional stop-time parameter, which MAY also 594 be earlier than the current time. If no stop-time is present, 595 notifications will continue to be sent until the subscription is 596 terminated. 598 Not all streams will support replay. Those that do MUST include the 599 flag. In addition, a notification stream that 600 does support replay is not expected to have an unlimited supply of 601 saved notifications available to accommodate any given replay 602 request. Subscribers MAY do a get on and 603 to assess the availability of notifications 604 for replay. The actual number of stored notifications available for 605 retrieval at any given time is a publisher specific matter. Control 606 parameters for this aspect of the feature are outside the scope of 607 this document. 609 4.2. Modifying a Subscription 611 The operation permits changing the terms of an 612 existing dynamic subscription previously established on that 613 transport session. Subscriptions created by configuration operations 614 cannot be modified via this RPC. Dynamic subscriptions can be 615 modified one or multiple times. If the publisher accepts the 616 requested modifications, it immediately starts sending events based 617 on the new terms, completely ignoring the previous ones. If the 618 publisher rejects the request, the subscription remains as prior to 619 the request. That is, the request has no impact whatsoever. The 620 contents of a such a rejected modification MAY include one or more 621 hints on alternative input parameters and value which would have 622 resulted in a successfully modified subscription. 624 Dynamic subscriptions established via RPC can only be modified via 625 RPC using the same transport session used to establish that 626 subscription. 628 4.3. Deleting a Subscription 630 The operation permits canceling an existing 631 subscription previously established on that transport session. If 632 the publisher accepts the request, it immediately stops sending 633 events for the subscription. If the publisher rejects the request, 634 all subscriptions remain as prior to the request. That is, the 635 request has no impact whatsoever. 637 Subscriptions established via RPC can only be deleted via RPC using 638 the same transport session used for subscription establishment. 639 Configured subscriptions cannot be deleted using RPCs. 641 4.4. Killing a Subscription 643 The operation permits an operator to end any 644 dynamic subscription. A publisher MUST terminate any dynamic 645 subscription identified within a properly authenticated RPC request. 647 Configured subscriptions cannot be killed using this RPC. Instead, 648 configured subscriptions are deleted as part of regular configuration 649 operations. Publishers MUST reject any RPC attempt to kill a 650 configured subscription. 652 5. Configured Subscriptions 654 A configured subscription is a subscription installed via a 655 configuration interface. 657 Configured subscriptions persist across reboots, and persist even 658 when transport is unavailable. 660 Configured subscriptions can be modified by any configuration client 661 with write permissions for the configuration of the subscription. 662 Subscriptions can be modified or terminated via the configuration 663 interface at any point of their lifetime. 665 Supporting configured subscriptions is optional and advertised using 666 the "configured-subscriptions" feature. 668 In addition to subscription parameters that apply to dynamic 669 subscriptions, the following additional parameters apply to 670 configured subscriptions: 672 o One or more receiver IP addresses (and corresponding ports) 673 intended as the destination for push updates for each 674 subscription. In addition, the transport protocol for each 675 destination MAY be defined. 677 o Optional parameters to identify an egress interface or IP address 678 plus VRF out of which subscription updates should be pushed from 679 the publisher. Where these are not explicitly included, or where 680 just the VRF is provided, push updates MUST egress the publisher's 681 default interface towards a receiver. 683 5.1. Establishing a Configured Subscription 685 Configured subscriptions are established using configuration 686 operations against the top-level subtree subscription-config. There 687 are two key differences between RPC and RPC operations 688 for subscription establishment. Firstly, operations 689 install a subscription without question, while RPCs are designed to 690 the support negotiation and rejection of requests. Secondly, while 691 RPCs mandate that the subscriber establishing the subscription is the 692 only receiver of the notifications, operations permit 693 specifying receivers independent of any tracked subscriber. Because 694 there is no explicit association with an existing transport session, 695 operations require additional parameters beyond those 696 of dynamic subscriptions to indicate the receivers of the 697 notifications and possibly the source of the notifications such as a 698 specific egress interface. 700 Immediately after a subscription is successfully established, the 701 publisher sends to identified receivers a state change notification 702 stating the subscription has been established (i.e., subscription- 703 started). 705 It is quite possible that upon configuration, reboot, or even steady- 706 state operations, a transport session may not be currently available 707 to the receiver. In this case, when there is something to transport 708 for an active subscription, transport protocol specific call-home 709 operations will be used to establish the connection. 711 As an example at subscription establishment using over 712 NETCONF, a client might send: 714 717 718 719 720 721 724 725 1922 726 NETCONF 727 728
1.2.3.4
729 1234 730 731 732 733 734 736 Figure 2: Configured subscription creation via NETCONF 738 if the request is accepted, the publisher would reply: 740 742 743 745 Figure 3: Successful NETCONF configured subscription response 747 if the request is not accepted because the publisher cannot serve it, 748 the publisher may reply: 750 751 752 application 753 resource-denied 754 error 755 756 Temporarily the publisher cannot serve this 757 subscription due to the current workload. 758 759 760 762 Figure 4: A NETCONF response for a failed configured subscription 763 creation 765 5.2. Modifying a Configured Subscription 767 Configured subscriptions can be modified using configuration 768 operations against the top-level subtree subscription-config. 770 Immediately after a subscription is successfully modified, the 771 publisher sends to the existing receivers a state change notification 772 stating the subscription has been modified (i.e., subscription- 773 modified). 775 If the modification involved adding and/or removing receivers, those 776 modified receivers are sent state change notifications, indicating 777 they have been added (i.e, subscription-started to a specific 778 receiver) or removed (i.e., subscription-terminated to a specific 779 receiver.) 781 5.3. Deleting a Configured Subscription 783 Subscriptions can be deleted using configuration operations against 784 the top-level subtree subscription-config. For example, in RESTCONF: 786 DELETE /subscription-config/subscription=1922 HTTP/1.1 787 Host: example.com 789 HTTP/1.1 204 No Content 790 Date: Sun, 24 Jul 2016 11:23:40 GMT 791 Server: example-server 793 Figure 5: Deleting a configured subscription 795 Immediately after a subscription is successfully deleted, the 796 publisher sends to all receivers of that subscription a state change 797 notification stating the subscription has been terminated (i.e., 798 subscription-terminated). 800 6. Deleting a Configured Subscription 802 Configured subscriptions can be deleted using configuration 803 operations against the top-level subtree subscription-config. 805 Immediately after a subscription is successfully deleted, the 806 publisher sends to the existing receivers a state change notification 807 stating the subscription has been terminated (i.e., subscription- 808 terminated). 810 7. Asynchronous Subscribed Content Delivery 812 Once a subscription has been set up, the publisher streams 813 asynchronously push subscribed content via notification messages per 814 the terms of the subscription. For dynamic subscriptions set up via 815 RPC operations, notification messages are sent over the session used 816 to establish the subscription. For configured subscriptions, 817 notification messages are sent over the specified connections. 819 A notification message is sent to a receiver when something of 820 interest occurs which is able to traverse all specified filtering and 821 access control criteria. 823 This notification message MAY be encoded as one-way notification 824 element of [RFC5277], Section 4. The following example within 825 [RFC7950] section 7.16.3 is an example of a compliant message: 827 829 2007-09-01T10:00:00Z 830 831 so-1/2/3.0 832 up 833 down 834 835 837 Figure 6: subscribed content notification 839 This [RFC5277] section 4 has the drawback of not including useful 840 header information such as subscription-ID. When using this 841 mechanism, it is left up to implementations to determine which events 842 belong to which subscription. 844 This drawback, along with other useful common headers and the ability 845 to bundle multiple event notifications together is being explored 846 within [I-D.notification-messages]. 848 8. Subscription State Notifications 850 In addition to subscribed content, a publisher will send subscription 851 state notifications to indicate to receivers that an event related to 852 the subscription management has occurred. 854 Subscription state notifications are unlike other notifications in 855 that they are not general-purpose notifications. They cannot be 856 filtered out, and they are delivered only to directly impacted 857 receiver(s) of a subscription. The definition of subscription state 858 notifications is distinct from other notifications by making use of a 859 YANG extension tagging them as subscription state notification. 861 Subscription state notifications include indications that a replay of 862 events has been completed, that a subscription is done because an end 863 time has been reached, and that a subscription has started, been 864 modified, been terminated, or been suspended. They are described in 865 the following subsections. 867 8.1. subscription-started 869 This notification indicates that a configured subscription has 870 started and data updates are beginning to be sent. This notification 871 includes the parameters of the subscription, except for the 872 receiver(s) addressing information and push-source information. Note 873 that for RPC-based subscriptions, no such notifications are sent. 875 8.2. subscription-modified 877 This notification indicates that a configured subscription has been 878 modified successfully. This notification includes the parameters of 879 the subscription, except for the receiver(s) addressing information 880 and push-source information. Note that for RPC-based subscriptions, 881 no such notifications are sent. 883 8.3. subscription-terminated 885 This notification indicates that a subscription has been terminated 886 by the publisher. The notification includes the reason for the 887 termination. The publisher MAY decide to terminate a subscription 888 when it is running out of resources for serving it, an internal error 889 occurs, etc. Publisher-driven terminations are notified to all 890 receivers. Northbound systems MAY also terminate configured 891 subscriptions using configuration operations. 893 Subscribers can terminate via RPC subscriptions established via a 894 delete-subscription RPC. In such cases, no subscription-terminated 895 notifications are sent. However if a kill-subscription RPC is sent, 896 or some other event results in the end of a subscription, then there 897 MUST be a notification that the subscription has been ended. 899 8.4. subscription-suspended 901 This notification indicates that a publisher has suspended a 902 subscription. The notification includes the reason for the 903 suspension. A possible reason is the lack of resources to serve it. 904 No further subscribed content will be sent until the subscription 905 resumes. Suspensions are notified to the subscriber (in the case of 906 dynamic subscriptions) and all receivers (in the case of configured 907 subscriptions). 909 8.5. subscription-resumed 911 This notification indicates that a previously suspended subscription 912 has been resumed. Subscribed content generated after the generation 913 of this state change notification will be sent. These notifications 914 go to the subscriber (in the case of dynamic subscriptions) and all 915 receivers (in the case of configured subscriptions). 917 8.6. subscription-completed 919 This notification is sent to indicate that a subscription, which 920 includes a stop time, has successfully finished passing events upon 921 the reaching of that stop time. 923 8.7. replay-completed 925 This notification indicates that all of the events prior to the 926 current time have been sent. This includes new events generated 927 since the start of the subscription. This notification MUST NOT be 928 sent for any other reason. 930 If subscription contains no stop time, or has a stop time which has 931 not been reached, then after the replay-completed notification has 932 been sent events will be sent in sequence as they arise naturally 933 within the system. 935 9. Administrative Functions 936 9.1. Subscription Monitoring 938 Container "subscriptions" in the YANG module below contains the state 939 of all known subscriptions. This includes subscriptions that were 940 established (and have not yet been deleted) using RPCs, as well as 941 subscriptions that have been configured as part of configuration. 942 Using the operation with NETCONF, or subscribing to this 943 information via [I-D.ietf-netconf-yang-push] allows the status of 944 subscriptions to be monitored. 946 Each subscription is represented as a list element. The associated 947 information includes an identifier for the subscription, receiver 948 counter information, the status of the subscription, as well as the 949 various subscription parameters that are in effect. The subscription 950 status indicates the subscription's state with each receiver (e.g., 951 is currently active or suspended). Leaf "configured-subscription" 952 indicates whether the subscription came into being via configuration 953 or via RPC. 955 Subscriptions that were established by RPC are removed from the list 956 once they expire (reaching stop-time) or when they are terminated. 957 Subscriptions that were established by configuration need to be 958 deleted from the configuration by a configuration editing operation 959 even if the stop time has been passed. 961 9.2. Capability Advertisement 963 Capabilities are advertised in messages sent by each peer during 964 session establishment [RFC6241]. Publishers supporting the RPCs and 965 Notifications in this document MUST advertise the capability 966 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications:1.0". In 967 addition support for optional features: json, configured- 968 subscriptions, and replay MAY also be advertised. 970 If a subscriber only supports [RFC5277] and not this specification, 971 then they will recognize the capability 972 "urn:ietf:params:netconf:capability:notification:1.0" and ignore any 973 new subscription capabilities defined in this document. 975 If a publisher supports this specification but not [RFC5277], the 976 publisher MUST support the one-way notification element of [RFC5277] 977 Section 4 or [I-D.notification-messages]. 979 9.3. Event Stream Discovery 981 A publisher maintains a list of available event streams as 982 operational data. This list contains both standardized and vendor- 983 specific event streams. A client can retrieve this list like any 984 other YANG-defined data, for example using the operation when 985 using NETCONF. 987 10. Data Model 989 file "ietf-subscribed-notifications.yang" 990 module ietf-subscribed-notifications { 991 namespace 992 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"; 994 prefix sn; 996 import ietf-yang-types { 997 prefix yang; 998 } 999 import ietf-inet-types { 1000 prefix inet; 1001 } 1002 import ietf-interfaces { 1003 prefix if; 1004 } 1006 organization "IETF"; 1007 contact 1008 "WG Web: 1009 WG List: 1011 Editor: Alexander Clemm 1012 1014 Editor: Eric Voit 1015 1017 Editor: Alberto Gonzalez Prieto 1018 1020 Editor: Einar Nilsen-Nygaard 1021 1023 Editor: Ambika Prasad Tripathy 1024 "; 1026 description 1027 "Contains a conceptual YANG specification for subscribing to events 1028 and receiving matching content within notification messages."; 1030 revision 2017-09-15 { 1031 description 1032 "Filtering and stream structures updated, replay a feature."; 1033 reference 1034 "draft-ietf-netconf-subscribed-notifications-04"; 1035 } 1037 /* 1038 * FEATURES 1039 */ 1041 feature json { 1042 description 1043 "This feature indicates that JSON encoding of notifications 1044 is supported."; 1045 } 1047 feature configured-subscriptions { 1048 description 1049 "This feature indicates that management plane configuration 1050 of subscription is supported."; 1051 } 1053 feature replay { 1054 description 1055 "This feature indicates that historical event replay is 1056 supported. With replay, it is possible for past events to be 1057 will be streamed in chronological order."; 1058 } 1060 /* 1061 * EXTENSIONS 1062 */ 1064 extension subscription-state-notif { 1065 description 1066 "This statement applies only to notifications. It indicates that 1067 the notification is a subscription state notification. Therefore 1068 it does not participate in a regular event stream and does not 1069 need to be specifically subscribed to in order to receive 1070 notifications."; 1071 } 1073 /* 1074 * IDENTITIES 1075 */ 1077 /* Identities for streams */ 1078 identity stream { 1079 description 1080 "Base identity to represent a generic stream of event 1081 notifications exposed for subscription by a system."; 1082 } 1084 identity NETCONF { 1085 base stream; 1086 description 1087 "Default NETCONF event stream, containing events based on 1088 notifications defined as YANG modules that are supported by the 1089 system. As a historical reference, this contains the same set 1090 of events in a default RFC-5277 NETCONF stream."; 1091 } 1093 identity SYSLOG { 1094 base stream; 1095 description 1096 "A stream of events mirroring the discrete set entries 1097 concurrently being placed into a device's local Syslog."; 1098 } 1100 identity custom-stream { 1101 base stream; 1102 description 1103 "A supported stream not defined via an identity in this model"; 1104 } 1106 /* Identities for event filters */ 1108 identity event-filter { 1109 description 1110 "Evaluation criteria used as a pass/fail test against events. 1111 If a filter element is specified to look for data of a particular 1112 value, and the data item is not present within a particular event 1113 for its value to be checked against, the event will be filtered 1114 out. For example, if one were to check for 'severity=critical' in 1115 an event where this object does not exist, then the event would 1116 not traverse."; 1117 } 1119 identity subtree-event-filter { 1120 base event-filter; 1121 description 1122 "An RFC-6241 based filter which attempts to select nodes within an 1123 event. After evaluation, the return of a non-empty node set means 1124 that the filter is successfully traversed."; 1125 reference "RFC-6241, #5.1"; 1126 } 1127 identity xpath-event-filter { 1128 base event-filter; 1129 description 1130 "A filter applied to an event which follows the syntax specified 1131 in yang:xpath1.0. Success is indicated by either a positive 1132 boolean result, or a non-null node selection."; 1133 reference "XPATH: http://www.w3.org R/1999/REC-xpath-19991116"; 1134 } 1136 /* Identities for subscription results */ 1137 identity subscription-result { 1138 description 1139 "Base identity for RPC responses and State Change Notifications 1140 providing information on the creation, modification, deletion of 1141 subscriptions."; 1142 } 1144 identity ok { 1145 base subscription-result; 1146 description 1147 "OK - RPC was successful and was performed as requested."; 1148 } 1150 identity error { 1151 base subscription-result; 1152 description 1153 "Problem with subscription. Base identity for error return 1154 codes for RPCs and State Change Notifications."; 1155 } 1157 /* Identities for subscription stream status */ 1158 identity subscription-status { 1159 description 1160 "Base identity for the status of a subscription. This status 1161 indicates whether a subscriber is actively generating 1162 notifications intended for a particular receiver."; 1163 } 1165 identity active { 1166 base subscription-status; 1167 description 1168 "Status is active and healthy."; 1169 } 1171 identity inactive { 1172 base subscription-status; 1173 description 1174 "Status is inactive, for example after the stop time, but not 1175 yet deleted from the configuration."; 1176 } 1178 identity suspended { 1179 base subscription-status; 1180 description 1181 "The status is suspended, meaning that the publisher is currently 1182 unable to provide the negotiated updates for the subscription."; 1183 } 1185 identity in-error { 1186 base subscription-status; 1187 description 1188 "The status is in error or degraded, meaning that stream and/or 1189 subscription is currently unable to provide the negotiated 1190 notifications."; 1191 } 1193 /* Identities for subscription errors */ 1195 identity internal-error { 1196 base error; 1197 description 1198 "Error within publisher prohibits operation."; 1199 } 1201 identity suspension-timeout { 1202 base error; 1203 description 1204 "Termination of previously suspended subscription. The publisher 1205 has eliminated the subscription as it exceeded a time limit for 1206 suspension."; 1207 } 1209 identity stream-unavailable { 1210 base error; 1211 description 1212 "Stream does not exist or is not available to the receiver."; 1213 } 1215 identity encoding-unavailable { 1216 base error; 1217 description 1218 "Encoding not supported"; 1219 } 1221 identity replay-unsupported { 1222 base error; 1223 description 1224 "Replay cannot be performed for this subscription. The publisher 1225 does not provide the requested historic information via replay."; 1226 } 1228 identity history-unavailable { 1229 base error; 1230 description 1231 "Replay request too far into the past. The publisher does store 1232 historic information for all parts of requested subscription, but 1233 not back to the requested timestamp."; 1234 } 1236 identity filter-unavailable { 1237 base error; 1238 description 1239 "Referenced filter does not exist"; 1240 } 1242 identity filter-type-unsupported { 1243 base error; 1244 description 1245 "Publisher does not support filters constructed using this 1246 filtering technology syntax."; 1247 } 1249 identity filter-unsupported { 1250 base error; 1251 description 1252 "Failure can be from a syntax error, or a syntax too complex to be 1253 processed by the platform. The supplemental info should include 1254 the invalid part of the filter."; 1255 } 1257 identity namespace-unavailable { 1258 base error; 1259 description 1260 "Referenced namespace doesn't exist or is unavailable 1261 to the receiver."; 1262 } 1264 identity no-such-subscription { 1265 base error; 1266 description 1267 "Referenced subscription doesn't exist. This may be as a result of 1268 a non-existent subscription ID, an ID which belongs to another 1269 subscriber, or an ID for acceptable subscription which has been 1270 statically configured."; 1272 } 1274 identity error-insufficient-resources { 1275 base error; 1276 description 1277 "The server has insufficient resources to support the 1278 subscription as requested by an RPC."; 1279 } 1281 identity unsupportable-volume { 1282 base error; 1283 description 1284 "The publisher cannot support the volume of information intended 1285 to be sent for an existing subscription."; 1286 } 1288 identity error-no-such-option { 1289 base error; 1290 description 1291 "A requested parameter setting is not supported."; 1292 } 1294 /* Identities for encodings */ 1295 identity encodings { 1296 description 1297 "Base identity to represent data encodings"; 1298 } 1300 identity encode-xml { 1301 base encodings; 1302 description 1303 "Encode data using XML"; 1304 } 1306 identity encode-json { 1307 base encodings; 1308 description 1309 "Encode data using JSON"; 1310 } 1312 /* Identities for transports */ 1313 identity transport { 1314 description 1315 "An identity that represents a transport protocol for event 1316 notifications"; 1317 } 1319 identity netconf { 1320 base transport; 1321 description 1322 "Netconf notifications as a transport."; 1323 } 1325 identity http2 { 1326 base transport; 1327 description 1328 "HTTP2 notifications as a transport"; 1329 } 1331 /* 1332 * TYPEDEFs 1333 */ 1335 typedef subscription-id { 1336 type uint32; 1337 description 1338 "A type for subscription identifiers."; 1339 } 1341 typedef filter-id { 1342 type uint32; 1343 description 1344 "A type to identify filters which can be associated with a 1345 subscription."; 1346 } 1348 typedef subscription-result { 1349 type identityref { 1350 base subscription-result; 1351 } 1352 description 1353 "The result of a subscription operation"; 1354 } 1356 typedef subscription-errors { 1357 type identityref { 1358 base error; 1359 } 1360 description 1361 "The reason for the failure of an RPC request or the sending 1362 of a subscription suspension or termination notification"; 1363 } 1365 typedef encoding { 1366 type identityref { 1367 base encodings; 1369 } 1370 description 1371 "Specifies a data encoding, e.g. for a data subscription."; 1372 } 1374 typedef event-filter-type { 1375 type identityref { 1376 base event-filter; 1377 } 1378 description 1379 "Specifies a known type of event filter."; 1380 } 1382 typedef subscription-status { 1383 type identityref { 1384 base subscription-status; 1385 } 1386 description 1387 "Specifies the status of a subscription."; 1388 } 1390 typedef transport-protocol { 1391 type identityref { 1392 base transport; 1393 } 1394 description 1395 "Specifies transport protocol used to send notifications to a 1396 receiver."; 1397 } 1399 typedef notification-origin { 1400 type enumeration { 1401 enum "interface-originated" { 1402 description 1403 "Notifications will be sent from a specific interface on a 1404 publisher"; 1405 } 1406 enum "address-originated" { 1407 description 1408 "Notifications will be sent from a specific address on a 1409 publisher"; 1410 } 1411 } 1412 description 1413 "Specifies from where notifications will be sourced when 1414 being sent by the publisher."; 1415 } 1416 typedef stream { 1417 type identityref { 1418 base stream; 1419 } 1420 description 1421 "Specifies a system-provided datastream."; 1422 } 1424 typedef filter-ref { 1425 type leafref { 1426 path "/sn:filters/sn:filter/sn:identifier"; 1427 } 1428 description 1429 "This type is used to reference a filter."; 1430 } 1432 /* 1433 * GROUPINGS 1434 */ 1436 grouping base-filter { 1437 description 1438 "This grouping defines the base for filters for notification 1439 events."; 1441 leaf event-filter-type { 1442 type event-filter-type; 1443 mandatory true; 1444 description 1445 "A filter needs to be a known and understood syntax if it is 1446 to be interpretable by a device."; 1447 } 1448 anyxml event-filter-contents { 1449 mandatory true; 1450 description 1451 "Event stream evaluation criteria encoded in a syntax of a 1452 supported type of filter. If the filter is applied 1453 against an event stream and there is a non-empty or 1454 positive result, the event is passed along."; 1455 } 1456 } 1458 grouping subscription-policy-modifiable { 1459 description 1460 "This grouping describes all objects which may be changed 1461 in a subscription via an RPC."; 1462 choice target { 1463 mandatory true; 1464 description 1465 "A filter must be applied against some source of information. 1466 This identifies the target for the filter."; 1467 case stream { 1468 choice event-filter { 1469 description 1470 "A filter can be applied to a subscription. And that filter 1471 will come either referenced from a global list, or be 1472 provided within the subscription itself."; 1473 case by-reference { 1474 description 1475 "Apply a filter that has been configured separately."; 1476 leaf filter-ref { 1477 type filter-ref; 1478 mandatory true; 1479 description 1480 "References an existing filter which is to be applied to 1481 the subscription."; 1482 } 1483 } 1484 case within-subscription { 1485 description 1486 "Local definition allows a filter to have the same 1487 lifecycle as the subscription."; 1488 uses base-filter; 1489 } 1490 } 1491 } 1492 } 1493 leaf stop-time { 1494 type yang:date-and-time; 1495 description 1496 "Identifies a time after which notification events should not 1497 be sent. If stop-time is not present, the notifications will 1498 continue until the subscription is terminated. If 1499 replay-start-time exists, stop-time must for a subsequent time. 1500 If replay-start-time doesn't exist, stop-time must for a future 1501 time."; 1502 } 1503 } 1505 grouping subscription-policy { 1506 description 1507 "This grouping describes information concerning a subscription."; 1508 leaf encoding { 1509 type encoding; 1510 default "encode-xml"; 1511 description 1512 "The type of encoding for the subscribed data. Default is XML"; 1513 } 1514 uses subscription-policy-modifiable { 1515 augment target/stream { 1516 description 1517 "Adds additional objects which must be set just by RPC."; 1518 leaf stream { 1519 type stream; 1520 mandatory true; 1521 description 1522 "Indicates a stream of events against which to apply 1523 an event filter."; 1524 } 1525 leaf replay-start-time { 1526 if-feature "replay"; 1527 type yang:date-and-time; 1528 description 1529 "Used to trigger the replay feature and indicate that the 1530 replay should start at the time specified. If 1531 replay-start-time is not present, this is not a replay 1532 subscription and event pushes should start immediately. It 1533 is never valid to specify start times that are later than 1534 or equal to the current time."; 1535 } 1536 } 1537 } 1538 } 1540 grouping notification-origin-info { 1541 description 1542 "Defines the sender source from which notifications for a 1543 configured subscription are sent."; 1544 choice notification-origin { 1545 description 1546 "Identifies the egress interface on the Publisher from which 1547 notifications will or are being sent."; 1548 case interface-originated { 1549 description 1550 "When the push source is out of an interface on the 1551 Publisher established via static configuration."; 1552 leaf source-interface { 1553 type if:interface-ref; 1554 description 1555 "References the interface for notifications."; 1556 } 1557 } 1558 case address-originated { 1559 description 1560 "When the push source is out of an IP address on the 1561 Publisher established via static configuration."; 1562 leaf source-vrf { 1563 type string; 1564 description 1565 "Network instance name for the VRF. This could also have 1566 been a leafref to draft-ietf-rtgwg-ni-model, but that model 1567 is not complete, and might not be implemented on a box."; 1568 } 1569 leaf source-address { 1570 type inet:ip-address-no-zone; 1571 description 1572 "The source address for the notifications. If a source VRF 1573 exists, but this object doesn't, a default address for the 1574 VRF can be used."; 1575 } 1576 } 1577 } 1578 } 1580 grouping receiver-info { 1581 description 1582 "Defines where and how to get notifications for a configured 1583 subscriptions to one or more targeted recipient. This includes 1584 specifying the destination addressing as well as a transport 1585 protocol acceptable to the receiver."; 1586 container receivers { 1587 description 1588 "Set of receivers in a subscription."; 1589 list receiver { 1590 key "address port"; 1591 min-elements 1; 1592 description 1593 "A single host or multipoint address intended as a target 1594 for the notifications for a subscription."; 1595 leaf address { 1596 type inet:host; 1597 description 1598 "Specifies the address for the traffic to reach a remote 1599 host. One of the following must be specified: an ipv4 1600 address, an ipv6 address, or a host name."; 1601 } 1602 leaf port { 1603 type inet:port-number; 1604 description 1605 "This leaf specifies the port number to use for messages 1606 destined for a receiver."; 1608 } 1609 leaf protocol { 1610 type transport-protocol; 1611 default "netconf"; 1612 description 1613 "This leaf specifies the transport protocol used 1614 to deliver messages destined for the receiver. Each 1615 protocol may use the address and port information 1616 differently as applicable."; 1617 } 1618 } 1619 } 1620 } 1622 grouping error-identifier { 1623 description 1624 "A code passed back within an RPC response to describe why the RFC 1625 has failed, or within a state change notification to describe why 1626 the change has occurred."; 1627 leaf error-id { 1628 type subscription-errors; 1629 mandatory true; 1630 description 1631 "Identifies the subscription error condition."; 1632 } 1633 } 1635 grouping hints { 1636 description 1637 "Objects passed back within an RPC response to describe why the 1638 RFC has failed, or within a state change notification to 1639 describe why the change has occurred."; 1640 leaf filter-failure { 1641 type string; 1642 description 1643 "Information describing where and/or why a provided filter was 1644 unsupportable for a subscription."; 1645 } 1646 } 1648 grouping subscription-response-with-hints { 1649 description 1650 "Defines the output for the establish-subscription and 1651 modify-subscription RPCs."; 1652 leaf subscription-result { 1653 type subscription-result; 1654 mandatory true; 1655 description 1656 "Indicates whether subscription is operational, or if a problem 1657 was encountered."; 1658 } 1659 choice result { 1660 description 1661 "Depending on the subscription result, different data is 1662 returned."; 1663 case no-success { 1664 description 1665 "This case applies when a subscription request was not 1666 successful and no subscription was created (or modified) as a 1667 result. In this case, information MAY be returned that 1668 indicates suggested parameter settings that would have a 1669 high likelihood of succeeding in a subsequent establish- 1670 subscription or modify-subscription request."; 1671 uses hints; 1672 } 1673 } 1674 } 1676 /* 1677 * RPCs 1678 */ 1680 rpc establish-subscription { 1681 description 1682 "This RPC allows a subscriber to create (and possibly negotiate) 1683 a subscription on its own behalf. If successful, the 1684 subscription remains in effect for the duration of the 1685 subscriber's association with the publisher, or until the 1686 subscription is terminated. In case an error (as indicated by 1687 subscription-result) is returned, the subscription is not 1688 created. In that case, the RPC reply MAY include suggested 1689 parameter settings that would have a higher likelihood of 1690 succeeding in a subsequent establish-subscription request."; 1691 input { 1692 uses subscription-policy; 1693 } 1694 output { 1695 uses subscription-response-with-hints { 1696 augment "result" { 1697 description 1698 "Allows information to be passed back as part of a 1699 successful subscription establishment."; 1700 case success { 1701 description 1702 "This case is used when the subscription request was 1703 successful."; 1705 leaf identifier { 1706 type subscription-id; 1707 mandatory true; 1708 description 1709 "Identifier used for this subscription."; 1710 } 1711 } 1712 } 1713 augment "result/no-success" { 1714 description 1715 "Contains establish RPC specific objects which can be 1716 returned as hints for future attempts."; 1717 leaf replay-start-time-hint { 1718 type yang:date-and-time; 1719 description 1720 "If a replay has been requested, but the requested replay 1721 time cannot be honored, this may provide a hint at an 1722 alternate time which may be supportable."; 1723 } 1724 } 1725 } 1726 } 1727 } 1729 rpc modify-subscription { 1730 description 1731 "This RPC allows a subscriber to modify a subscription that was 1732 previously created using establish-subscription. If successful, 1733 the changed subscription remains in effect for the duration of 1734 the subscriber's association with the publisher, or until the 1735 subscription is again modified or terminated. In case an error 1736 is returned (as indicated by subscription-result), the 1737 subscription is not modified and the original subscription 1738 parameters remain in effect. In that case, the rpc error 1739 response MAY include suggested parameter hints that would have 1740 a high likelihood of succeeding in a subsequent 1741 modify-subscription request."; 1742 input { 1743 leaf identifier { 1744 type subscription-id; 1745 description 1746 "Identifier to use for this subscription."; 1747 } 1748 uses subscription-policy-modifiable; 1749 } 1750 output { 1751 uses subscription-response-with-hints; 1752 } 1754 } 1756 rpc delete-subscription { 1757 description 1758 "This RPC allows a subscriber to delete a subscription that 1759 was previously created from by that same subscriber using the 1760 establish-subscription RPC."; 1761 input { 1762 leaf identifier { 1763 type subscription-id; 1764 mandatory true; 1765 description 1766 "Identifier of the subscription that is to be deleted. 1767 Only subscriptions that were created using 1768 establish-subscription can be deleted via this RPC."; 1769 } 1770 } 1771 output { 1772 leaf subscription-result { 1773 type subscription-result; 1774 mandatory true; 1775 description 1776 "Indicates whether subscription has been deleted, or if a 1777 problem was encountered."; 1778 } 1779 } 1780 } 1782 rpc kill-subscription { 1783 description 1784 "This RPC allows an operator to delete a dynamic subscription 1785 without restrictions on the originating subscriber or underlying 1786 transport session."; 1787 input { 1788 leaf identifier { 1789 type subscription-id; 1790 mandatory true; 1791 description 1792 "Identifier of the subscription that is to be deleted. Only 1793 subscriptions that were created using establish-subscription 1794 can be deleted via this RPC."; 1795 } 1796 } 1797 output { 1798 leaf subscription-result { 1799 type subscription-result; 1800 mandatory true; 1801 description 1802 "Indicates whether subscription has been killed, or if a 1803 problem was encountered."; 1804 } 1805 } 1806 } 1808 /* 1809 * NOTIFICATIONS 1810 */ 1812 notification replay-completed { 1813 sn:subscription-state-notif; 1814 description 1815 "This notification is sent to indicate that all of the replay 1816 notifications have been sent. It must not be sent for any other 1817 reason."; 1818 leaf identifier { 1819 type subscription-id; 1820 mandatory true; 1821 description 1822 "This references the affected subscription."; 1823 } 1824 } 1826 notification subscription-completed { 1827 sn:subscription-state-notif; 1828 description 1829 "This notification is sent to indicate that a subscription has 1830 finished passing events."; 1831 leaf identifier { 1832 type subscription-id; 1833 mandatory true; 1834 description 1835 "This references the gracefully completed subscription."; 1836 } 1837 } 1839 notification subscription-started { 1840 sn:subscription-state-notif; 1841 description 1842 "This notification indicates that a subscription has started and 1843 notifications are beginning to be sent. This notification shall 1844 only be sent to receivers of a subscription; it does not 1845 constitute a general-purpose notification."; 1846 leaf identifier { 1847 type subscription-id; 1848 mandatory true; 1849 description 1850 "This references the affected subscription."; 1851 } 1852 uses subscription-policy; 1853 } 1855 notification subscription-resumed { 1856 sn:subscription-state-notif; 1857 description 1858 "This notification indicates that a subscription that had 1859 previously been suspended has resumed. Notifications will once 1860 again be sent."; 1861 leaf identifier { 1862 type subscription-id; 1863 mandatory true; 1864 description 1865 "This references the affected subscription."; 1866 } 1867 } 1869 notification subscription-modified { 1870 sn:subscription-state-notif; 1871 description 1872 "This notification indicates that a subscription has been 1873 modified. Notifications sent from this point on will conform to 1874 the modified terms of the subscription. For completeness, this 1875 notification includes both modified and non-modified aspects of 1876 a subscription "; 1877 leaf identifier { 1878 type subscription-id; 1879 mandatory true; 1880 description 1881 "This references the affected subscription."; 1882 } 1883 uses subscription-policy; 1884 } 1886 notification subscription-terminated { 1887 sn:subscription-state-notif; 1888 description 1889 "This notification indicates that a subscription has been 1890 terminated."; 1891 leaf identifier { 1892 type subscription-id; 1893 mandatory true; 1894 description 1895 "This references the affected subscription."; 1896 } 1897 uses error-identifier; 1898 uses hints; 1899 } 1901 notification subscription-suspended { 1902 sn:subscription-state-notif; 1903 description 1904 "This notification indicates that a suspension of the 1905 subscription by the publisher has occurred. No further 1906 notifications will be sent until the subscription resumes. 1907 This notification shall only be sent to receivers of a 1908 subscription; it does not constitute a general-purpose 1909 notification."; 1910 leaf identifier { 1911 type subscription-id; 1912 mandatory true; 1913 description 1914 "This references the affected subscription."; 1915 } 1916 uses error-identifier; 1917 uses hints; 1918 } 1920 /* 1921 * DATA NODES 1922 */ 1924 container streams { 1925 config false; 1926 description 1927 "This container contains information on the built-in streams 1928 provided by the publisher."; 1929 list stream { 1930 key "stream"; 1931 description 1932 "Identifies the built-in streams that are supported by the 1933 publisher."; 1934 leaf stream { 1935 type stream; 1936 description 1937 "A handle for a sequential set of events, each of which 1938 is characterized by its own domain and semantics. 1939 In case configurable custom streams are supported, 1940 as indicated by the custom-stream identity, the configuration 1941 of those custom streams is provided separately."; 1942 } 1943 leaf description { 1944 type string; 1945 mandatory true; 1946 description 1947 "A description of the event stream, including such information 1948 as the type of events that are sent over this stream."; 1949 } 1950 leaf replay-support { 1951 type empty; 1952 description 1953 "Indicates that event replay is available on this stream."; 1954 } 1955 leaf replay-log-creation-time { 1956 type yang:date-and-time; 1957 description 1958 "The timestamp of the creation of the log used to support the 1959 replay function on this stream. Note that this might be 1960 earlier then the earliest available notification in the log. 1961 This object is updated if the log resets for some reason. 1962 This object MUST be present if replay is supported."; 1963 } 1964 leaf replay-log-aged-time { 1965 type yang:date-and-time; 1966 description 1967 "The timestamp of the last notification aged out of the log. 1968 This object MUST be present if replay is supported and any 1969 notifications have been aged out of the log."; 1970 } 1971 } 1972 } 1974 container filters { 1975 description 1976 "This container contains a list of configurable filters 1977 that can be applied to subscriptions. This facilitates 1978 the reuse of complex filters once defined."; 1979 list filter { 1980 key "identifier"; 1981 description 1982 "A list of configurable filters that can be applied to 1983 subscriptions."; 1984 leaf identifier { 1985 type filter-id; 1986 description 1987 "An identifier to differentiate between filters."; 1988 } 1989 choice filter-type { 1990 description 1991 "A filter needs to be a single filter of a given type. Mixing 1992 and matching of multiple filters does not occur at the level 1993 of this grouping."; 1995 case event-filter { 1996 uses base-filter; 1997 } 1998 } 1999 } 2000 } 2002 container subscription-config { 2003 if-feature "configured-subscriptions"; 2004 description 2005 "Contains the list of subscriptions that are configured, 2006 as opposed to established via RPC or other means."; 2007 list subscription { 2008 key "identifier"; 2009 description 2010 "Content of a subscription."; 2011 leaf identifier { 2012 type subscription-id; 2013 description 2014 "Identifier to use for this subscription."; 2015 } 2016 uses subscription-policy; 2017 uses receiver-info; 2018 uses notification-origin-info; 2019 } 2020 } 2021 container subscriptions { 2022 config false; 2023 description 2024 "Contains the list of currently active subscriptions, i.e. 2025 subscriptions that are currently in effect, used for subscription 2026 management and monitoring purposes. This includes subscriptions 2027 that have been setup via RPC primitives as well as subscriptions 2028 that have been established via configuration."; 2029 list subscription { 2030 key "identifier"; 2031 description 2032 "Content of a subscription. Subscriptions can be created using 2033 a control channel or RPC, or be established through 2034 configuration."; 2035 leaf identifier { 2036 type subscription-id; 2037 description 2038 "Identifier of a subscription; unique within a publisher"; 2039 } 2040 leaf configured-subscription { 2041 if-feature "configured-subscriptions"; 2042 type empty; 2043 description 2044 "The presence of this leaf indicates that the subscription 2045 originated from configuration, not through a control channel 2046 or RPC."; 2047 } 2048 uses subscription-policy; 2049 uses notification-origin-info { 2050 if-feature "configured-subscriptions"; 2051 } 2052 uses receiver-info { 2053 augment receivers/receiver { 2054 description 2055 "include operational data for receivers."; 2056 leaf pushed-notifications { 2057 type yang:counter64; 2058 description 2059 "Operational data which provides the number of update 2060 notifications pushed to a receiver."; 2061 } 2062 leaf excluded-notifications { 2063 type yang:counter64; 2064 description 2065 "Operational data which provides the number of events 2066 from a stream explicitly removed via filtering so that 2067 they are not sent to a receiver."; 2068 } 2069 leaf status { 2070 type subscription-status; 2071 mandatory true; 2072 description 2073 "The status of the subscription."; 2074 } 2075 } 2076 } 2077 } 2078 } 2079 } 2080 2082 11. Considerations 2084 11.1. Implementation Considerations 2086 For a deployment including both configured and dynamic subscriptions, 2087 split subscription identifiers into static and dynamic halves. That 2088 way it is unlikely there will be collisions if the configured 2089 subscriptions attempt to set a subscription-id which might have 2090 already been dynamically allocated. The lower half SHOULD be used 2091 for configured subscriptions and upper half for dynamic. 2093 The elements are never sent before the transport 2094 layer, including capabilities exchange, has been established. 2096 It is left to an implementation to determine when to transition 2097 between active and suspended subscription states. However if a 2098 subscription is unable to marshal all intended updates into a 2099 transmittable message in multiple successive intervals, the 2100 subscription SHOULD be suspended with the reason "unsupportable- 2101 volume". 2103 11.2. Security Considerations 2105 For dynamic subscriptions the publisher MUST authenticate and 2106 authorize all RPC requests. 2108 Subscriptions could overload a publisher's CPU. For this reason, the 2109 publisher MUST have the ability to decline a dynamic subscription 2110 request, and provide the appropriate RPC error response to a 2111 subscriber should the proposed subscription overly deplete the 2112 publisher's resources. 2114 A publisher needs to be able to suspend an existing dynamic or 2115 configured subscription based on capacity constraints. When this 2116 occurs, the subscription status MUST be updated accordingly and the 2117 receivers notified with subscription state notifications. 2119 If a malicious or buggy subscriber sends an unexpectedly large number 2120 of RPCs, the result might be an exessive use of system resources. In 2121 such a situation, subscription interactions MAY be terminated by 2122 terminating the transport session. 2124 For both configured and dynamic subscriptions the publisher MUST 2125 authenticate and authorize a receiver via some transport level 2126 mechanism before sending any updates. 2128 A secure transport is highly recommended and the publisher MUST 2129 ensure that the user has sufficient authorization to perform the 2130 function they are requesting against the specific subset of content 2131 involved. 2133 A publisher MUST NOT include any content in a notification for which 2134 the user has not been authorized. 2136 With configured subscriptions, one or more publishers could be used 2137 to overwhelm a receiver. No push updates SHOULD be sent to any 2138 receiver which doesn't even support subscriptions. Subscribers that 2139 do not want pushed data need only terminate or refuse any transport 2140 sessions from the publisher. 2142 The NETCONF Authorization Control Model [RFC6536bis] SHOULD be used 2143 to control and restrict authorization of subscription configuration. 2144 This control models permits specifying per-user permissions to 2145 receive events from specific streams. 2147 Where NACM is available, the NACM "very-secure" tag MUST be placed on 2148 the RPC so that only administrators have access 2149 to use this. 2151 One subscription id can be used for two or more receivers of the same 2152 configured subscription. But due to the possibility of different 2153 access control permissions per receiver, it SHOULD NOT be assumed 2154 that each receiver is getting identical updates. 2156 12. Acknowledgments 2158 For their valuable comments, discussions, and feedback, we wish to 2159 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Balazs 2160 Lengyel, Sharon Chisholm, Hector Trevino, Susan Hares, Kent Watsen, 2161 Michael Scharf, and Guangying Zheng. 2163 13. References 2165 13.1. Normative References 2167 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2168 Requirement Levels", BCP 14, RFC 2119, 2169 DOI 10.17487/RFC2119, March 1997, 2170 . 2172 [RFC6536bis] 2173 Bierman, A. and M. Bjorklund, "Network Configuration 2174 Protocol (NETCONF) Access Control Model", draft-ietf- 2175 netconf-rfc6536bis-01 (work in progress), September 2017. 2177 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2178 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2179 . 2181 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 2182 Version 1.0", November 1999, 2183 . 2185 13.2. Informative References 2187 [I-D.ietf-netconf-event-notif] 2188 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 2189 Nilsen-Nygaard, E., Tripathy, A., Chisholm, S., and H. 2190 Trevino, "NETCONF support for event notifications", August 2191 2016, . 2194 [I-D.ietf-netconf-restconf-notif] 2195 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 2196 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 2197 HTTP transport for event notifications", August 2016, 2198 . 2201 [I-D.ietf-netconf-yang-push] 2202 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 2203 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 2204 Lengyel, "Subscribing to YANG datastore push updates", 2205 June 2017, . 2208 [I-D.notification-messages] 2209 Voit, Eric., Clemm, Alexander., Bierman, A., and T. 2210 Jenkins, "YANG Notification Headers and Bundles", 2211 September 2017, . 2214 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2215 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2216 . 2218 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2219 and A. Bierman, Ed., "Network Configuration Protocol 2220 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2221 . 2223 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2224 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2225 DOI 10.17487/RFC7540, May 2015, 2226 . 2228 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2229 for Subscription to YANG Datastores", RFC 7923, 2230 DOI 10.17487/RFC7923, June 2016, 2231 . 2233 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2234 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2235 . 2237 Appendix A. Changes between revisions 2239 (To be removed by RFC editor prior to publication) 2241 v03 - v04 2243 o Moved back to the use of RFC5277 one-way notifications and 2244 encodings. 2246 v03 - v04 2248 o Replay updated 2250 v02 - v03 2252 o RPCs and Notification support is identified by the Notification 2253 2.0 capability. 2255 o Updates to filtering identities and text 2257 o New error type for unsupportable volume of updates 2259 o Text tweaks. 2261 v01 - v02 2263 o Subscription status moved under receiver. 2265 v00 - v01 2267 o Security considerations updated 2269 o Intro rewrite, as well as scattered text changes 2271 o Added Appendix A, to help match this to related drafts in progress 2273 o Updated filtering definitions, and filter types in yang file, and 2274 moved to identities for filter types 2276 o Added Syslog as a stream 2278 o HTTP2 moved in from YANG-Push as a transport option 2279 o Replay made an optional feature for events. Won't apply to 2280 datastores 2282 o Enabled notification timestamp to have different formats. 2284 o Two error codes added. 2286 v01 5277bis - v00 subscribed notifications 2288 o Kill subscription RPC added. 2290 o Renamed from 5277bis to Subscribed Notifications. 2292 o Changed the notification capabilities version from 1.1 to 2.0. 2294 o Extracted create-subscription and other elements of RFC5277. 2296 o Error conditions added, and made specific in return codes. 2298 o Simplified yang model structure for removal of 'basic' grouping. 2300 o Added a grouping for items which cannot be statically configured. 2302 o Operational counters per receiver. 2304 o Subscription-id and filter-id renamed to identifier 2306 o Section for replay added. Replay now cannot be configured. 2308 o Control plane notification renamed to subscription state 2309 notification 2311 o Source address: Source-vrf changed to string, default address 2312 option added 2314 o In yang model: 'info' changed to 'policy' 2316 o Scattered text clarifications 2318 v00 - v01 of 5277bis 2320 o YANG Model changes. New groupings for subscription info to allow 2321 restriction of what is changeable via RPC. Removed notifications 2322 for adding and removing receivers of configured subscriptions. 2324 o Expanded/renamed definitions from event server to publisher, and 2325 client to subscriber as applicable. Updated the definitions to 2326 include and expand on RFC 5277. 2328 o Removal of redundancy with other drafts 2330 o Many other clean-ups of wording and terminology 2332 Authors' Addresses 2334 Eric Voit 2335 Cisco Systems 2337 Email: evoit@cisco.com 2339 Alexander Clemm 2340 Huawei 2342 Email: ludwig@clemm.org 2344 Alberto Gonzalez Prieto 2345 VMWare 2347 Email: agonzalezpri@vmware.com 2349 Einar Nilsen-Nygaard 2350 Cisco Systems 2352 Email: einarnn@cisco.com 2354 Ambika Prasad Tripathy 2355 Cisco Systems 2357 Email: ambtripa@cisco.com