idnits 2.17.1 draft-wang-netconf-adaptive-subscription-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 3 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 9 instances of too long lines in the document, the longest one being 9 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (2 May 2022) is 696 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'RFC5277' is mentioned on line 153, but not defined == Missing Reference: 'RFC3198' is mentioned on line 153, but not defined == Missing Reference: 'RFC8639' is mentioned on line 366, but not defined == Missing Reference: 'IEEE754-2008' is mentioned on line 429, but not defined == Unused Reference: 'RFC8126' is defined on line 760, but no explicit reference was found in the text == Unused Reference: 'RFC8407' is defined on line 779, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group Q. Wu 3 Internet-Draft W. Song 4 Intended status: Experimental Huawei 5 Expires: 3 November 2022 P. Liu 6 China Mobile 7 Q. Ma 8 Huawei 9 W. Wang 10 China Telecom 11 Z. Niu 12 Microsoft 13 2 May 2022 15 Adaptive Subscription to YANG Notification 16 draft-wang-netconf-adaptive-subscription-10 18 Abstract 20 This document defines a YANG data model and associated mechanism 21 enabling the subscriber's adaptive subscriptions to a publisher's 22 event streams with various different period intervals to report 23 updates. Applying these elements allows servers automatically adjust 24 the rate and volume of telemetry traffic sent from a publisher to 25 receivers. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 3 November 2022. 44 Copyright Notice 46 Copyright (c) 2022 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Revised BSD License text as 55 described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Revised BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 62 2. Model Overview . . . . . . . . . . . . . . . . . . . . . . . 5 63 2.1. Subscription Configuration . . . . . . . . . . . . . . . 6 64 2.2. YANG RPC . . . . . . . . . . . . . . . . . . . . . . . . 7 65 2.2.1. "establish-subscription" RPC . . . . . . . . . . . . 7 66 2.3. Notifications for Adaptive Subscribed Content . . . . . . 8 67 3. XPath Complexity Evaluation . . . . . . . . . . . . . . . . . 9 68 4. Adaptive Subscription YANG Module . . . . . . . . . . . . . . 10 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 70 5.1. Updates to the IETF XML Registry . . . . . . . . . . . . 14 71 5.2. Updates to the YANG Module Names Registry . . . . . . . . 15 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 73 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 16 74 8. Acknowledges . . . . . . . . . . . . . . . . . . . . . . . . 16 75 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 76 9.1. Normative References . . . . . . . . . . . . . . . . . . 16 77 9.2. Informative References . . . . . . . . . . . . . . . . . 17 78 Appendix A. Example YANG Module . . . . . . . . . . . . . . . . 18 79 A.1. "example-wifi-mac" YANG Module . . . . . . . . . . . . . 18 80 Appendix B. Adaptive Subscription and Notification Example . . . 23 81 B.1. "edit-config" Example . . . . . . . . . . . . . . . . . . 23 82 B.2. Create Adaptive Subscription Example . . . . . . . . . . 24 83 B.3. "xpath-evaluation-unsupported" error response example . . 25 84 B.4. "adaptive-period-update" notification example . . . . . . 26 85 B.5. Changes between Revisions . . . . . . . . . . . . . . . . 27 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 88 1. Introduction 90 YANG-Push subscriptions [RFC8641] allow subscriber applications to 91 request a continuous customized stream of updates from a YANG 92 datastore without needing to poll. It defines a mechanism (i.e., 93 update trigger) to determine when an update record needs to be 94 generated. Two types of subscriptions are introduced in [RFC8641], 95 distinguished by how updates are triggered: periodic and on-change. 97 * Periodic subscription allows subscribed data to be streamed to the 98 destination at a configured fixed periodic interval; 100 * On-change subscription allows update to be triggered whenever a 101 change in the subscribed information is detected. 103 However in some large scale deployments (e.g., massive data 104 collection for wireless network performance monitoring) where an 105 increased data collection rate is used, it becomes more likely that 106 both clients and servers are temporarily overwhelmed with a burst of 107 streamed data and consumes expensive network resource (e.g., 108 bandwidth resource, radio resource) and computation resource, 109 therefore hard to continuously monitor operational data, especially 110 values that fall outside normal operational ranges. If the rate at 111 which we can collect a stream of data is set too low or chosen to get 112 low priority telemetry data dropped, these telemetry data are not 113 sufficient to detect and diagnose problems and verify correct network 114 behavior. 116 A client might choose to monitor the operational state and send a 117 request to modify the data collection rate on the server. But how 118 often the client evaluates if the modification of the data collection 119 rate is required highly depends on the current collection rate, 120 collecting a stream of data at a low rate prevents the subscriber 121 from capturing sufficient data for timely decision-making, which may 122 result in service discontinuity. In addition, when tens of thousands 123 of network devices need to be managed, frequent follow-up 124 modification requests are prone to errors. 126 There is a need for a service to balance between data management cost 127 and real time streaming telemetry. To achieve this, servers can be 128 configured with multiple different period intervals and corresponding 129 subscription update policy which allows servers/publishers 130 automatically switch to different period intervals according to the 131 network condition change without the interaction with the client for 132 policy update instruction, e.g., when the wireless signal strength 133 falls below a configured threshold, the subscribed data can be 134 streamed at a higher rate to capture potentially important data and 135 events (e.g., continuous service degeneration); while when the 136 wireless signal strength crosses a configured threshold, the 137 subscribed data can be streamed at a lower rate. 139 This document defines a YANG data model and associated mechanism 140 enabling the subscriber's adaptive subscriptions to a publisher's 141 event streams. Applying these elements allows servers to 142 automatically adjust the rate and volume of telemetry traffic sent 143 from a publisher to receivers. 145 1.1. Terminology 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 149 "OPTIONAL" in this document are to be interpreted as described in BCP 150 14 [RFC2119] [RFC8174] when, and only when, they appear in all 151 capitals, as shown here. 153 The following terms are defined in [RFC5277] [RFC7950] [RFC3198] 154 [RFC8342] [RFC8639] [RFC8641] and are not redefined here: 156 * Event 158 * Client 160 * Configuration 162 * Configured subscription 164 * Configuration datastore 166 * Notification message 168 * Publisher 170 * Receiver 172 * Subscriber 174 * Subscription 176 * On-change subscription 178 * Periodic subscription 180 * Selection filter 182 This document defines the following term: 184 Adaptive Subscription: Apply subscription update policy on the 185 servers and allow servers/publishers automatically switch to 186 different period intervals according to the network condition 187 change without the interaction with the client for update policy 188 instruction. 190 2. Model Overview 192 This document defines a YANG module "ietf-adaptive-subscription", 193 which augments the "update-trigger" choice defined in the "ietf-yang- 194 push" module [RFC8641] with subscription configuration parameters 195 that are specific to a subscriber's adaptive subscription. 197 In addition to subscription state notifications defined in [RFC8639] 198 and notifications for subscribed content defined in [RFC8641], "ietf- 199 adaptive-subscription" YANG module also defines "adaptive-period- 200 update" notification to report the update interval change. 202 The following tree diagrams [RFC8340] provide an overview of the data 203 model for "ietf-adaptive-subscription" module. 205 module: ietf-adaptive-subscription 206 augment /sn:subscriptions/sn:subscription/yp:update-trigger: 207 +--rw (adaptive-subscription)? 208 +--:(adaptive-subscriptions) 209 +--rw adaptive-subscriptions 210 +--rw adaptive-period* [name] 211 +--rw name string 212 +--rw xpath-external-eval string 213 +--rw period yp:centiseconds 214 +--rw anchor-time? yang:date-and-time 215 augment /sn:establish-subscription/sn:input/yp:update-trigger: 216 +-- (adaptive-subscription)? 217 +--:(adaptive-subscriptions) 218 +--rw adaptive-subscriptions 219 +--rw adaptive-period* [name] 220 +--rw name string 221 +--rw xpath-external-eval string 222 +--rw period yp:centiseconds 223 +--rw anchor-time? yang:date-and-time 224 notifications: 225 +---n adaptive-period-update 226 +--ro id? sn:subscription-id 227 +--ro period yp:centiseconds 228 +--ro anchor-time? yang:date-and-time 229 +--ro (selection-filter)? 230 +--:(by-reference) 231 | +--ro selection-filter-ref selection-filter-ref 232 +--:(within-subscription) 233 +--ro (filter-spec)? 234 +--:(datastore-subtree-filter) 235 | +--ro datastore-subtree-filter? {sn:subtree}? 236 +--:(datastore-xpath-filter) 237 +--ro datastore-xpath-filter? yang:xpath1.0 {sn:xpath}? 239 2.1. Subscription Configuration 241 For adaptive subscriptions, triggered updates will occur at the 242 boundaries of specified time intervals when a trigger condition is 243 satisfied. These boundaries can be calculated from the following 244 adaptive periodic parameters: 246 * a "name" represents the name of each adaptive period; 248 * a "period" that defines the new duration between push updates. 249 The period can be switched based on trigger conditions; 251 * an "anchor-time"; update intervals fall on the points in time that 252 are a multiple of a "period" from an "anchor-time". If an 253 "anchor-time" is not provided, then the "anchor-time" MUST be set 254 with the creation time of the initial update record. 256 * an "xpath-external-eval" represents a standard XPath evaluation 257 expression (See section 6.4 of [RFC7950]) that is applied against 258 the targeted data object, which is used to trigger/control the 259 update interval switching within the server. It follows the rules 260 defined in section 3.4 of [XPATH1.0] and contains comparisons of 261 the targeted datastore node with its value to the specific 262 threshold in the XPath format. Different from selection filter 263 defined in [RFC8641], 265 - it is applied against a single targeted object rather than a 266 set of target objects. 268 - it monitors a specific data object change and evaluates the 269 trigger condition associated with the targeted object to be 270 true or false using XPATH rules and does not influence the 271 event records output generation from a publisher. 273 How often the XPath expression criterion is evaluated is up to the 274 publisher's implementation. With minimal delay, the expression 275 can be evaluated whenever changes to targeted object occur, or at 276 the end of each high-frequency streaming update period. To reduce 277 the frequency of evaluation, the server can choose to check 278 targeted object change at every multiple (e.g.,2 or 3) high- 279 frequency streaming update periods. 281 The represented expression defined in "xpath-external-eval" is 282 evaluated in the following XPath context: 284 - The set of namespace declarations is the set of prefix and 285 namespace pairs for all YANG modules implemented by the server, 286 where the prefix is the YANG module name and the namespace is 287 as defined by the "namespace" statement in the YANG module. 289 - If the leaf is encoded in XML, all namespace declarations in 290 scope on the "xpath-external-eval" leaf element are added to 291 the set of namespace declarations. If a prefix found in the 292 XML is already present in the set of namespace declarations, 293 the namespace in the XML is used. 295 - The set of variable bindings is empty. 297 - The function library is the core function library defined in 298 [XPATH1.0] and the function defined in Section 10 in RFC 7950. 300 - The context node is the root node. 302 For the cases where multiple list instances are needed to handle 303 in "xpath-external-eval", XPath abbreviated syntax can be used to 304 identify a particular instance, e.g., to represent a comparison 305 for a leaf in a list entry: 307 /if:interfaces/if:interface[if:name="eth0"]/if:in-errors>1000. 309 The server MUST convert the XPath expression defined in "xpath- 310 external-eval" to a boolean value and internally apply the 311 "boolean" function defined in Section 4.3 in [XPATH1.0] if the 312 evaluated result is not a boolean. 314 Note that the adaptive subscription may not be supported by every 315 YANG datastore nodes. A publisher MAY decide to simply reject an 316 adaptive subscription with "adaptive-unsupported" (defined in 317 Section 2.2.1.1) if the scope of the subscription contains selected 318 data nodes for which adaptive subscription is not supported. 320 2.2. YANG RPC 322 2.2.1. "establish-subscription" RPC 324 The augmentation of YANG module "ietf-yang-push" made to RPCs 325 specified in YANG module "ietf-subscribed-notifications" [RFC8639] is 326 introduced. This augmentation concerns the "establish-subscription" 327 RPC, which is augmented with parameters that are needed to specify a 328 subscriber's adaptive subscriptions. These parameters are the same 329 as ones defined in Section 2.1. 331 2.2.1.1. RPC Failures 333 As specified in [RFC8639] and [RFC8641], RPC error responses from the 334 publisher are used to indicate a rejection of an RPC for any reason. 335 This document introduces three new RPC errors for "establish- 336 subscription" RPC. 338 establish-subscription 339 ----------------------------- 340 adaptive-unsupported 341 xpath-evaluation-unsupported 342 multi-xpath-criteria-conflict 344 Adaptive-unsupported is used to indicate that the adaptive 345 subscription is not supported for any objects that are selectable by 346 the filter. 348 Xpath-evaluation-unsupported is used to indicate that a server fails 349 to parse syntax defined in "xpath-external-eval". The failure can be 350 caused by either a syntax error or some XPath 1.0 syntax not 351 supported against the specific object. 353 Multi-xpath-criteria-conflict is used to indicate that the multiple 354 Xpath evaluation criteria represented by "xpath-external-eval" is 355 evaluated as conflict, i.e., more than one condition expressions are 356 evaluated to "true". Such a conflict may also cause an ongoing 357 adaptive-subscription terminated. 359 For an example of how above RPC errors can be returned, see the 360 "xpath-evaluation-unsupported" error response illustrated in 361 Appendix B.3. 363 2.3. Notifications for Adaptive Subscribed Content 365 The adaptive update notification is similar to subscription state 366 change notifications defined in [RFC8639]. It is inserted into the 367 sequence of notification messages sent to a particular receiver. The 368 adaptive update notification cannot be dropped or filtered out, it 369 cannot be stored in replay buffers, and it is delivered only to 370 impacted receivers of a subscription. The identification of adaptive 371 update notification is easy to separate from other notification 372 messages through the use of the YANG extension "subscription-state- 373 notif". This extension tags a notification as a subscription state 374 change notification. 376 The objects in the 'adaptive-period-update' notification include: 378 * a "period" that defines the duration between push updates, the 379 period can be changed based on trigger conditions. 381 * an "anchor-time"; update intervals fall on the points in time that 382 are a multiple of a "period" from an "anchor-time". If an 383 "anchor-time" is not provided, then the "anchor-time" MUST be set 384 with the creation time of the initial update record. 386 * A selection filter is to identify YANG nodes of interest in a 387 datastore. Filter contents are specified via a reference to an 388 existing filter or via an in-line definition for only that 389 subscription based on XPath Evaluation criteria defined in section 390 6.4 of [RFC7950]. Referenced filters allow an implementation to 391 avoid evaluating filter acceptability during a dynamic 392 subscription request. The "case" statement differentiates the 393 options. Note that filter contents are not affected by "xpath- 394 external-eval" parameter defined by the update trigger. 396 3. XPath Complexity Evaluation 398 YANG-Push subscriptions [RFC8641] specify selection filters to 399 identify targeted YANG datastore nodes and/or datastore subtrees for 400 which updates are to be pushed. In addition, it specifies update 401 policies which contain conditions that trigger generation and pushing 402 of new update records. To support a subscriber's adaptive 403 subscription defined in this document, the trigger condition can also 404 use similar selection filters to express a standard XPath Evaluation 405 criterion (section 6.4 of [RFC7950]) against targeted data objects. 407 Similar to on-change subscriptions, adaptive subscriptions are 408 particularly effective for data that changes infrequently, the 409 following complex design choices need to be cautious, although these 410 designs have already been well supported by the section 3.4 of 411 [XPATH1.0]: 413 * Support XPath Evaluation criteria against every data object; 415 * Support more than one target object selection and operation(e.g., 416 addition, subtraction, division and multiplication) in the XPath 417 evaluation criterion; 419 * Support any type of node set in the XPath evaluation criterion, 420 e.g., string,int64, uint64, and decimal64 types; 422 * Both objects in the XPath Evaluation criterion to be compared are 423 node-sets; 425 * Two objects to be compared are in different data types, e.g., one 426 is an integer, the other is a string 428 As described in section 6.4 of RFC7950, Numbers in XPath 1.0 are IEEE 429 754 [IEEE754-2008] double-precision floating-point values; some 430 values of int64, uint64, and decimal64 types cannot be exactly 431 represented in XPath expressions. 433 If two objects to be compared are in different data types, conversion 434 function is needed to convert different data types into numbers. 436 If both objects in XPath Evaluation criteria to be compared are node- 437 sets, more computation resources are required which add complexity. 439 To reduce these complexities, the following design principles are 440 recommended: 442 * XPath Evaluation criteria against a minimal set of data objects in 443 the data model, the minimal set of data objects can be advertised 444 using Notification capabilities model defined in [RFC9196]. 446 * XPath Evaluation criteria only support condition expressions that 447 filter updates based on numbers. 449 * One object to be compared in the XPath Evaluation criteria MUST be 450 a leaf data node. 452 * The other object to be compared in the XPath Evaluation criteria 453 MUST be a number data type. 455 If a server receives an XPath Evaluation criterion with some XPath 456 syntax unsupported against the specific object, an RPC error with 457 "xpath-evaluation-unsupported" should be returned. 459 4. Adaptive Subscription YANG Module 461 file "ietf-adaptive-subscription@2020-02-14.yang" 462 module ietf-adaptive-subscription { 463 yang-version 1.1; 464 namespace "urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription"; 465 prefix as; 466 import ietf-subscribed-notifications { 467 prefix sn; 468 } 469 import ietf-yang-push { 470 prefix yp; 471 } 472 import ietf-yang-types { 473 prefix yang; 474 } 476 organization 477 "IETF NETCONF (Network Configuration) Working Group"; 478 contact 479 ""; 480 description 481 "NETCONF Protocol Data Types and Protocol Operations. 482 Copyright (c) 2020 IETF Trust and the persons identified as 483 the document authors. All rights reserved. 485 Redistribution and use in source and binary forms, with or 486 without modification, is permitted pursuant to, and subject 487 to the license terms contained in, the Simplified BSD License 488 set forth in Section 4.c of the IETF Trust's Legal Provisions 489 Relating to IETF Documents 490 (http://trustee.ietf.org/license-info). 492 This version of this YANG module is part of RFC xxxx; see 493 the RFC itself for full legal notices."; 495 revision 2020-02-14 { 496 description 497 "Initial revision"; 498 reference 499 "RFCxxx Adaptive subscription to YANG notification."; 500 } 502 identity adaptive-unsupported { 503 base sn:establish-subscription-error; 504 description 505 "Adaptive-subscription is not supported for any objects 506 that are selectable by the filter."; 507 } 509 identity xpath-evaluation-unsupported { 510 base sn:establish-subscription-error; 511 description 512 "Unable to parse the xpath evaluation criteria defined in 513 ‘xpath-external-eval’ because of a syntax error or some 514 XPath 1.0 syntax not supported against the specific object."; 515 } 517 identity multi-xpath-criteria-conflict { 518 base sn:establish-subscription-error; 519 base sn:subscription-terminated-reason; 520 description 521 "Multiple Xpath evaluation criteria represented by 522 'xpath-external-eval' is evaluated as conflict, i.e., 523 more than one condition expressions are evaluated to 524 'true'."; 525 } 527 grouping adaptive-subscription-modifiable { 528 description 529 "This grouping describes the datastore-specific adaptive subscription 530 conditions that can be changed during the lifetime of the 531 subscription."; 532 choice adaptive-subscription { 533 description 534 "Defines necessary conditions for sending an event record to 535 the subscriber."; 536 container adaptive-subscriptions { 537 list adaptive-period { 538 key "name"; 539 description 540 "Defines necessary conditions to switch update interval for 541 sending an event record to the subscriber. The event record output 542 generation will not be influenced these conditions."; 543 leaf name { 544 type string { 545 length "1..64"; 546 } 547 description 548 "The name of the condition to be matched. A device MAY further 549 restrict the length of this name; space and special 550 characters are not allowed."; 551 } 552 leaf xpath-external-eval { 553 type string; 554 description 555 "A XPath string, representing a logical expression, 556 which can contain comparisons of datastore values 557 and logical operations in the XPath format."; 558 } 559 leaf period { 560 type yp:centiseconds; 561 mandatory true; 562 description 563 "Duration of time that should occur between periodic 564 push updates, in units of 0.01 seconds."; 565 } 566 leaf anchor-time { 567 type yang:date-and-time; 568 description 569 "Designates a timestamp before or after which a series 570 of periodic push updates are determined. The next 571 update will take place at a point in time that is a 572 multiple of a period from the 'anchor-time'. 573 For example, for an 'anchor-time' that is set for the 574 top of a particular minute and a period interval of a 575 minute, updates will be sent at the top of every 576 minute that this subscription is active."; 577 } 578 } 579 description 580 "Container for adaptive subscription."; 581 } 582 } 583 } 585 augment "/sn:subscriptions/sn:subscription/yp:update-trigger" { 586 description 587 "This augmentation adds additional subscription parameters 588 that apply specifically to adaptive subscription."; 589 uses adaptive-subscription-modifiable; 590 } 591 augment "/sn:establish-subscription/sn:input/yp:update-trigger" { 592 description 593 "This augmentation adds additional subscription parameters 594 that apply specifically to datastore updates to RPC input."; 595 uses adaptive-subscription-modifiable; 596 } 598 notification adaptive-period-update { 599 sn:subscription-state-notification; 600 description 601 "This notification contains a push update that in turn contains 602 data subscribed to via a subscription. In the case of a 603 periodic subscription, this notification is sent for periodic 604 updates. It can also be used for synchronization updates of 605 an on-change subscription. This notification shall only be 606 sent to receivers of a subscription. It does not constitute 607 a general-purpose notification that would be subscribable as 608 part of the NETCONF event stream by any receiver."; 609 leaf id { 610 type sn:subscription-id; 611 description 612 "This references the subscription that drove the 613 notification to be sent."; 614 } 615 leaf period { 616 type yp:centiseconds; 617 mandatory true; 618 description 619 "New duration of time that should occur between periodic 620 push updates, in units of 0.01 seconds."; 621 } 622 leaf anchor-time { 623 type yang:date-and-time; 624 description 625 "Designates a timestamp before or after which a series 626 of periodic push updates are determined. The next 627 update will take place at a point in time that is a 628 multiple of a period from the 'anchor-time'. 629 For example, for an 'anchor-time' that is set for the 630 top of a particular minute and a period interval of a 631 minute, updates will be sent at the top of every 632 minute that this subscription is active."; 633 } 634 uses yp:datastore-criteria { 635 refine "selection-filter/within-subscription" { 636 description 637 "Specifies the selection filter and where it originated 638 from. If the 'selection-filter-ref' is populated, the 639 filter in the subscription came from the 'filters' 640 container. Otherwise, it is populated in-line as part 641 of the subscription itself."; 642 } 643 } 644 } 645 } 646 648 5. IANA Considerations 650 5.1. Updates to the IETF XML Registry 652 This document registers one URI in the IETF XML registry [RFC3688]. 653 Following the format in [RFC3688], the following registration is 654 requested to be made: 656 --------------------------------------------------------------------- 657 URI: urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription 658 Registrant Contact: The IESG. 659 XML: N/A, the requested URI is an XML namespace. 660 --------------------------------------------------------------------- 662 5.2. Updates to the YANG Module Names Registry 664 This document registers one YANG module in the YANG Module Names 665 registry [RFC7950]. Following the format in [RFC6020], the following 666 registration is requested to be made: 668 --------------------------------------------------------------------- 669 Name: ietf-adaptive-subscription 670 Namespace: urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription 671 Prefix: as 672 Reference: RFC xxxx 673 --------------------------------------------------------------------- 675 6. Security Considerations 677 The YANG module specified in this document defines a schema for data 678 that is designed to be accessed via network management protocols such 679 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 680 is the secure transport layer, and the mandatory-to-implement secure 681 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 682 is HTTPS, and the mandatory-to-implement secure transport is TLS 683 [RFC8446]. 685 The NETCONF Configuration Access Control Model (NACM) [RFC8341] 686 provides the means to restrict access for particular NETCONF or 687 RESTCONF users to a preconfigured subset of all available NETCONF or 688 RESTCONF protocol operations and content. 690 There are a number of data nodes defined in this YANG module that are 691 writable/creatable/deletable (i.e., config true, which is the 692 default). These data nodes may be considered sensitive in some 693 network environments. Write operations (e.g., edit-config) to these 694 data nodes without proper protection can have a negative effect on 695 network operations. These are the subtrees and data nodes and their 696 sensitivity/vulnerability: 698 * /sn:subscriptions/sn:subscription/yp:update-trigger/as:adaptive- 699 subscriptions/as:adaptive-period/as:period 701 * /sn:subscriptions/sn:subscription/yp:update-trigger/as:adaptive- 702 subscriptions/as:adaptive-period/as:anchor-time 704 * /sn:establish-subscription/sn:input/yp:update-trigger/as:adaptive- 705 subscriptions/as:adaptive-period/as:period 707 * /sn:establish-subscription/sn:input/yp:update-trigger/as:adaptive- 708 subscriptions/as:adaptive-period/as:anchor-time 710 7. Contributors 712 Thanks Michael Wang, Liang Geng for their major contributions to the 713 initial modeling and use cases. 715 Michael Wang 716 Email: wangzitao@huawei.com 718 Liang Geng 719 China Mobile 720 32 Xuanwumen West St, Xicheng District 721 Beijing 10053 723 Email: gengliang@chinamobile.com 725 8. Acknowledges 727 We would like to thank Rob Wilton, Thomas Graf, Andy Bierman, Michael 728 Richardson, Henk Birkholz for valuable review on this document, 729 special thanks to Thomas and Michael for organizing the discussion on 730 several relevant drafts and reach the common understanding on the 731 concept and ideas. Thanks Michael for providing CHIP/Matter WIFI 732 statistics reference. 734 9. References 736 9.1. Normative References 738 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 739 Requirement Levels", BCP 14, RFC 2119, 740 DOI 10.17487/RFC2119, March 1997, 741 . 743 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 744 and A. Bierman, Ed., "Network Configuration Protocol 745 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 746 . 748 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 749 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 750 . 752 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 753 RFC 7950, DOI 10.17487/RFC7950, August 2016, 754 . 756 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 757 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 758 . 760 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 761 Writing an IANA Considerations Section in RFCs", BCP 26, 762 RFC 8126, DOI 10.17487/RFC8126, June 2017, 763 . 765 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 766 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 767 May 2017, . 769 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 770 Access Control Model", STD 91, RFC 8341, 771 DOI 10.17487/RFC8341, March 2018, 772 . 774 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 775 and R. Wilton, "Network Management Datastore Architecture 776 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 777 . 779 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 780 Documents Containing YANG Data Models", BCP 216, RFC 8407, 781 DOI 10.17487/RFC8407, October 2018, 782 . 784 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 785 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 786 . 788 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 789 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 790 September 2019, . 792 [RFC9196] Lengyel, B., Clemm, A., and B. Claise, "YANG Modules 793 Describing Capabilities for Systems and Datastore Update 794 Notifications", RFC 9196, DOI 10.17487/RFC9196, February 795 2022, . 797 9.2. Informative References 799 [CHIP] CSA, "Connected Home over IP Specification", April 2021. 801 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 802 DOI 10.17487/RFC3688, January 2004, 803 . 805 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 806 the Network Configuration Protocol (NETCONF)", RFC 6020, 807 DOI 10.17487/RFC6020, October 2010, 808 . 810 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 811 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 812 . 814 [XPATH1.0] W3C, "https://www.w3.org/TR/1999/REC-xpath-19991116/", 11 815 November 1999. 817 Appendix A. Example YANG Module 819 The example YANG module used in this document represents a Wi-Fi 820 Network Diagnostics data specified in [CHIP] which can be used by a 821 Node to assist a user or Administrative Node in diagnosing potential 822 problems. 824 YANG tree diagram for the "example-wifi-network-diagnostic" module: 826 module: example-wifi-network-diagnostic 827 +--rw server 828 | +--rw bssid? yang:mac-address 829 | +--rw security-type? enumeration 830 | +--rw wifi-version? enumeration 831 | +--rw channel-num? int8 832 | +--rw rssi? int8 833 | +--rw beacon-lost-count? int8 834 | +--rw beacon-rx-count? int8 835 | +--rw packet-multicast-rx-count? int8 836 | +--rw packet-multicast-tx-count? int8 837 | +--rw packet-unicast-rx-count? int8 838 | +--rw packet-unicast-tx-count? int8 839 | +--rw current-max-rate? int8 840 | +--rw overrun-count? int8 841 +--rw events 842 +--rw event* [name] 843 +--rw name string 844 +--rw disconnection? enumeration 845 +--rw association-failure? enumeration 846 +--rw connection-status? enumeration 848 A.1. "example-wifi-mac" YANG Module 849 module example-wifi-network-diagnostic { 850 yang-version 1; 851 namespace "http://example.com/yang/wifi-network-diagnostic"; 852 prefix wnd; 854 import ietf-yang-types { 855 prefix yang; 856 } 858 container server { 859 description 860 "Configuration of the WiFi Server logical entity."; 861 leaf bssid { 862 type yang:mac-address; 863 description 864 "The MAC address of a wireless access point."; 865 } 866 leaf security-type { 867 type enumeration { 868 enum unspecified { 869 value 0; 870 } 871 enum none { 872 value 1; 873 } 874 enum wep { 875 value 2; 876 } 877 enum wpa { 878 value 3; 879 } 880 enum wpa2 { 881 value 4; 882 } 883 enum wpa3 { 884 value 5; 885 } 886 } 887 description 888 "The type of Wi-Fi security used. A value of 0 889 indicate that the interface is not currently 890 configured or operational."; 891 } 892 leaf wifi-version { 893 type enumeration { 894 enum 80211a { 895 value 0; 896 } 897 enum 80211b { 898 value 1; 899 } 900 enum 80211g { 901 value 2; 902 } 903 enum 80211n { 904 value 3; 905 } 906 enum 80211ac { 907 value 4; 908 } 909 enum 80211ax { 910 value 5; 911 } 912 } 913 description 914 "The highest 802.11 standard version usable 915 by the Node."; 916 } 917 leaf channel-num { 918 type int8; 919 description 920 "The channel that Wi-Fi communication is currently 921 operating on. A value of 0indicates that the interface 922 is not currently configured or operational."; 923 } 924 leaf rssi { 925 type int8; 926 description 927 "The RSSI of the Node’s Wi-Fi radio in dBm."; 928 } 929 leaf beacon-lost-count { 930 type int8; 931 description 932 "The count of the number of missed beacons the 933 Node has detected."; 934 } 935 leaf beacon-rx-count { 936 type int8; 937 description 938 "The count of the number of received beacons. The 939 total number of expected beacons that could have been 940 received during the interval since association SHOULD 941 match the sum of BeaconRxCount and BeaconLostCount. "; 942 } 943 leaf packet-multicast-rx-count { 944 type int8; 945 description 946 "The number of multicast packets received by 947 the Node."; 948 } 949 leaf packet-multicast-tx-count { 950 type int8; 951 description 952 "The number of multicast packets transmitted by 953 the Node."; 954 } 955 leaf packet-unicast-rx-count { 956 type int8; 957 description 958 "The number of multicast packets received by 959 the Node."; 960 } 961 leaf packet-unicast-tx-count { 962 type int8; 963 description 964 "The number of multicast packets transmitted by 965 the Node."; 966 } 967 leaf current-max-rate { 968 type int8; 969 description 970 "The current maximum PHY rate of transfer of 971 data in bytes-per-second."; 972 } 973 leaf overrun-count { 974 type int8; 975 description 976 "The number of packets dropped either at ingress or 977 egress, due to lack of buffer memory to retain all 978 packets on the ethernet network interface. The 979 OverrunCount attribute SHALL be reset to 0 upon a 980 reboot of the Node.."; 981 } 982 } 983 container events { 984 description 985 "Configuration of WIFI Network Diagnostic events."; 986 list event { 987 key "name"; 988 description 989 "The list of event sources configured on the 990 server."; 991 leaf name { 992 type string; 993 description 994 "The unique name of an event source."; 995 } 996 leaf disconnection { 997 type enumeration { 998 enum de-authenticated { 999 value 1; 1000 } 1001 enum dis-association { 1002 value 2; 1003 } 1004 } 1005 description 1006 "A Node’s Wi-Fi connection has been disconnected as a 1007 result of de-authenticated or dis-association and 1008 indicates the reason."; 1009 } 1010 leaf association-failure { 1011 type enumeration { 1012 enum unknown { 1013 value 0; 1014 } 1015 enum association-failed { 1016 value 1; 1017 } 1018 enum authentication-failed { 1019 value 2; 1020 } 1021 enum ssid-not-found { 1022 value 3; 1023 } 1024 } 1025 description 1026 "A Node has attempted to connect, or reconnect, to 1027 a Wi-Fi access point, but is unable to successfully 1028 associate or authenticate, after exhausting all 1029 internal retries of its supplicant."; 1030 } 1031 leaf connection-status { 1032 type enumeration { 1033 enum connected { 1034 value 1; 1035 } 1036 enum notconnected { 1037 value 2; 1038 } 1039 } 1040 description 1041 "A Node's connection status to a Wi-Fi network has 1042 changed. Connected, in this context, SHALL mean that 1043 a Node acting as a Wi-Fi station is successfully 1044 associated to a Wi-Fi Access Point."; 1045 } 1046 } 1047 } 1048 } 1050 Appendix B. Adaptive Subscription and Notification Example 1052 The examples within this document use the normative YANG module 1053 "ietf-adaptive-subscription" defined in Section 4 and the non- 1054 normative example YANG module "example-wifi-network-diagnostic" 1055 defined in Appendix A.1. 1057 This section shows some typical adaptive subscription and 1058 notification message exchanges. 1060 B.1. "edit-config" Example 1062 The client configures adaptive subscription policy parameters on the 1063 server. The adaptive subscription configuration parameters require 1064 the server to support two update intervals (i.e., 5 seconds, 60 1065 seconds) and report updates every 60 seconds if the rssi value is 1066 greater than or equal to -65dB; If the rssi value is less than -65dB, 1067 switch to 5 seconds period value to report updates. 1069 1071 1072 1073 1074 1075 1077 1080 1082 ds:running 1083 1084 1086 /wnd:example-wifi-network-diagnostic 1087 1088 1090 1091 1092 /wnd:server/wnd:rssi<-65 1093 1094 5 1095 1096 1097 1098 /wnd:server/wnd:rssi>=-65 1099 1100 60 1101 1102 1103 1104 1105 1106 1108 B.2. Create Adaptive Subscription Example 1110 The subscriber sends an "establish-subscription" RPC with the 1111 parameters listed in to request the creation of an adaptive 1112 subscription. The adaptive subscription configuration parameters 1113 require the server to report updates every 5 seconds if the rssi 1114 value is less than -65dB; If the rssi value is greater than or equal 1115 to -65dB, switch to 60 seconds period value. (Section 2) 1116 1118 1121 1123 ds:running 1124 1125 1127 /wnd:example-wifi-network-diagnostic 1128 1129 1131 1132 1133 wnd:server/wnd:rssi<-65 1134 1135 5 1136 1137 1138 1139 wnd:server/wnd:rssi>=-65 1140 1141 60 1142 1143 1144 1145 1147 B.3. "xpath-evaluation-unsupported" error response example 1149 If the subscriber has authorization to establish the subscription 1150 with a server, but the server had not been able to fully satisfy the 1151 request from the subscriber, the server should send an RPC error 1152 response. 1154 For instance, if the XPATH 1.0 syntax against the targeted data 1155 object defined in "xpath-external-eval" is not supported by the 1156 server' s implementation, the server returns a reply indicating a 1157 failure. The following illustrates an example: 1159 1160 1161 1162 application 1163 invalid-value 1164 error 1165 1166 ietf-adaptive-subscription:xpath-evaluation-unsupported 1167 1168 1169 /wnd:server/wnd:rssi 1170 1171 1172 1174 Since adaptive subscription allows a server to be configured with 1175 multiple different period intervals and corresponding XPath 1176 evaluation criteria to trigger update interval switch in the server, 1177 it may be possible for the server to return multiple 1178 elements with "xpath-evaluation-unsupported" failure specified by 1179 different error paths. The subscriber can use this information in 1180 future attempts to establish a subscription. 1182 B.4. "adaptive-period-update" notification example 1184 Upon the server switches from the update interval 5 seconds to the 1185 new update interval 60 seconds, before sending event records to 1186 receivers, the "adaptive-period-update" notification should be 1187 generated and sent to the receivers to inform the receivers that the 1188 update interval value is switched to the new value. 1190 1193 2016-11-21T13:51:00Z 1194 1196 0 1197 60 1198 1200 ds:running 1201 1202 1204 /ex:example-wifi-network-diagnostic 1205 1206 1207 1209 B.5. Changes between Revisions 1211 v09 -v10 1213 * Change the draft intended status to "experimental" 1215 * Problem statement refinement 1217 v08 -v09 1219 * Define two new RPC errors to report when adaptive subscription 1220 unsupported or multiple XPath criteria conflict. 1222 * Remove the "watermark" parameter. 1224 * Add clarification about how to evaluate the XPath expression 1225 defined in "xpath-external-eval". 1227 * Add clarification about how to compare a targeted data object in a 1228 specific list entry. 1230 v07 -v08 1232 * Define a new RPC error to report when an XPath syntax defined in 1233 "xpath-external-eval" is unsupported by a server. 1235 * Add a new example showing how the RPC error being returned by a 1236 publisher. 1238 * The usage examples fixed in the Appendix. 1240 * Grammatical errors correction(missing articles, plurality 1241 mismatches, etc). 1243 v06 -v07 1245 * The usage examples typo fixed in the Appendix. 1247 * Add reference to RFC7950 XPATH Evaluation section and XPATH 1.0 1249 * Clarify the definitions of 'xpath-external-eval' and 'selection- 1250 filter' by reusing XPATH Evaluation rules in RFC7950. 1252 * Add a new terminology "adaptive subscription". 1254 * Add one section to discuss Arbitrary XPath Complexity. 1256 v05 -v06 1258 * Replace example-wifi-mac module with example-wifi-network- 1259 diagnostic using WIFI statistics specified in CHIP specification. 1261 * Update adaptive subscription Example to align with WIFI example 1262 module change. 1264 * Add one more reference to CHIP Specification. 1266 v04 -v05 1268 * Remove "modify-subscption" RPC usage. 1270 * Module update to fix the nits. 1272 * Update adaptive subscription Example. 1274 * Other Editorial changes. 1276 v03 - v04 1278 * Add missing subtrees and data nodes in the security section; 1280 * Change "adaptive-update" notification into "adaptive-period- 1281 update" notification; 1283 * Other Editorial changes. 1285 v02 - v03 1286 * Clarify the difference between low priority telemetry data 1287 dropping and collection rate switching in the introduction 1288 section; 1290 * Update the abstract and introduction section to focus on 1291 collection rate switching in the server without interaction with 1292 the remote client; 1294 * Format usage example and change ssid into rssi in the appendix; 1296 * Use boilerplate and reuse the terms in the terminology section. 1298 Authors' Addresses 1300 Qin Wu 1301 Huawei 1302 101 Software Avenue, Yuhua District 1303 Nanjing 1304 Jiangsu, 210012 1305 China 1306 Email: bill.wu@huawei.com 1308 Wei Song 1309 Huawei 1310 101 Software Avenue, Yuhua District 1311 Nanjing 1312 Jiangsu, 210012 1313 China 1314 Email: songwei80@huawei.com 1316 Peng Liu 1317 China Mobile 1318 32 Xuanwumen West St, Xicheng District 1319 Beijing 1320 Email: liupengyjy@chinamobile.com 1322 Qiufang Ma 1323 Huawei 1324 101 Software Avenue, Yuhua District 1325 Nanjing 1326 Jiangsu, 210012 1327 China 1328 Email: maqiufang1@huawei.com 1329 Wei Wang 1330 China Telecom 1331 32 Xuanwumen West St, Xicheng District 1332 Beijing 1333 Email: wangw36@chinatelecom.cn 1335 Zhixiong Niu 1336 Microsoft 1337 Email: Zhixiong.Niu@microsoft.com