idnits 2.17.1 draft-wang-netconf-adaptive-subscription-03.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 : ---------------------------------------------------------------------------- ** There are 7 instances of too long lines in the document, the longest one being 6 characters in excess of 72. == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 20, 2021) is 1191 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) == Missing Reference: 'RFC5277' is mentioned on line 131, but not defined == Missing Reference: 'RFC3198' is mentioned on line 131, but not defined == Missing Reference: 'RFC8639' is mentioned on line 261, but not defined == Unused Reference: 'RFC8126' is defined on line 613, but no explicit reference was found in the text == Unused Reference: 'RFC8407' is defined on line 632, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 7 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: Standards Track Huawei 5 Expires: July 24, 2021 P. Liu 6 China Mobile 7 Q. Ma 8 Huawei 9 January 20, 2021 11 Adaptive Subscription to YANG Notification 12 draft-wang-netconf-adaptive-subscription-03 14 Abstract 16 This document defines a YANG data model and associated mechanism 17 enabling subscriber's adaptive subscriptions to a publisher's event 18 streams with various different period intervals to report updates. 19 Applying these elements allows publishers automatically adjust the 20 volume of telemetry traffic sent from publisher to the receivers. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on July 24, 2021. 39 Copyright Notice 41 Copyright (c) 2021 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Model Overview . . . . . . . . . . . . . . . . . . . . . . . 4 59 2.1. Subscription Configuration . . . . . . . . . . . . . . . 5 60 2.2. YANG RPC . . . . . . . . . . . . . . . . . . . . . . . . 6 61 2.2.1. "establish-subscription" RPC . . . . . . . . . . . . 6 62 2.2.2. "modify-subscription" RPC . . . . . . . . . . . . . . 6 63 2.3. Notifications for Adaptive Subscribed Content . . . . . . 6 64 3. Adaptive Subscription YANG Module . . . . . . . . . . . . . . 7 65 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 66 4.1. Updates to the IETF XML Registry . . . . . . . . . . . . 12 67 4.2. Updates to the YANG Module Names Registry . . . . . . . . 12 68 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 69 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 13 70 7. Acknowledges . . . . . . . . . . . . . . . . . . . . . . . . 13 71 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 72 8.1. Normative References . . . . . . . . . . . . . . . . . . 13 73 8.2. Informative References . . . . . . . . . . . . . . . . . 15 74 Appendix A. Example YANG Module . . . . . . . . . . . . . . . . 15 75 A.1. "example-wifi-mac" YANG Module . . . . . . . . . . . . . 16 76 Appendix B. Adaptive Subscription and Notification Example . . . 18 77 B.1. "edit-config" Example . . . . . . . . . . . . . . . . . . 19 78 B.2. Create Adaptive Subscription Example . . . . . . . . . . 20 79 B.3. "adaptive-update" notification example . . . . . . . . . 22 80 B.4. Changes between Revisions . . . . . . . . . . . . . . . . 23 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 83 1. Introduction 85 YANG-Push subscriptions [RFC8641] allow client applications to 86 subscribe to continuous datastore updates without needing to poll. 87 It defines a mechanism (i.e.,update trigger) to determine when an 88 update record needs to be generated. Two type of subscriptions are 89 introduced in [RFC8641], distinguished by how updates are triggered: 90 periodic and on-change. 92 o Periodic subscription allows subscribed data to be streamed to the 93 destination at a configured fixed periodic interval 95 o On-change subscription allows update to be triggered whenever a 96 change in the subscribed information is detected. The periodic 97 interval is set to zero value in the on-change subscription case. 99 However in some large scale deployments (e.g., wireless network 100 performance monitoring) where an increased data collection rate is 101 being used, it becomes more likely that a burst of streamed data may 102 temporarily overwhelm a receiver and consume expensive network 103 resource (e.g., radio resource). If the rate at which we can collect 104 a stream of data is set too low or getting low priority telemetry 105 data dropped, these telemetry data are not sufficient to detect and 106 diagnose problems and verify correct network behavior. There is a 107 need for a service to configure both collectors and publishers with 108 multiple different period intervals and corresponding subscription 109 policy which allows publishers automatically switch to different 110 period intervals according to resource usage change without the 111 interaction with the remote client, e.g., when the wireless signal 112 strength falls below a configured low watermark, the subscribed data 113 can be streamed at a higher rate while when the wireless signal 114 strength crosses a configured high watermark, the subscribed data can 115 be streamed at lower rate. 117 This document defines a YANG data model and associated mechanism 118 enabling subscriber's adaptive subscriptions to a publisher's event 119 streams. Applying these elements allows both subscriber and 120 publisher to automatically adjust the volume of telemetry traffic 121 sent from publisher to the receivers. 123 1.1. Terminology 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 127 "OPTIONAL" in this document are to be interpreted as described in BCP 128 14 [RFC2119] [RFC8174] when, and only when, they appear in all 129 capitals, as shown here. 131 The following terms are defined in [RFC5277] [RFC7950] [RFC3198] 132 [RFC8342] [RFC8639] and are not redefined here: 134 o Event 136 o Client 138 o Configuration 140 o Configured subscription 142 o Configuration datastore 143 o Notification message 145 o Publisher 147 o Receiver 149 o Subscriber 151 o Subscription 153 o On-change subscription 155 o Periodic subscription 157 2. Model Overview 159 This document defines a YANG module "ietf-adaptive-subscription", 160 which augments the "update-trigger" choice defined in the "ietf-yang- 161 push" module [RFC8641] with subscription configuration parameters 162 that are specific to adaptive subscription. 164 In addition to Subscription state notifications defined in [RFC8639] 165 and Notifications for Subscribed Content defined in [RFC8641], "ietf- 166 adaptive-subscription" YANG module also defines "adaptive-update" 167 notification to report update interval change. 169 The following tree diagrams [RFC8340] provide an overview of the data 170 model for "ietf-adaptive-subscription.yang" module. 172 module: ietf-adaptive-subscription 173 augment /sn:subscriptions/sn:subscription/yp:update-trigger: 174 +--rw (adaptive-subscription)? 175 +--:(adaptive-subscriptions) 176 +--rw adaptive-subscriptions 177 +--rw adaptive-period* [name] 178 +--rw name string 179 +--rw xpath-external-eval string 180 +--rw watermark? uint32 181 +--rw period centiseconds 182 +--rw anchor-time? yang:date-and-time 183 augment /sn:establish-subscription/sn:input/yp:update-trigger: 184 +-- (adaptive-subscription)? 185 +--:(adaptive-subscriptions) 186 +--rw adaptive-subscriptions 187 +--rw adaptive-period* [name] 188 +--rw name string 189 +--rw xpath-external-eval string 190 +--rw watermark? uint32 191 +--rw period centiseconds 192 +--rw anchor-time? yang:date-and-time 193 notifications: 194 +---n adaptive-period-update 195 +--ro id? sn:subscription-id 196 +--ro period centiseconds 197 +--ro anchor-time? yang:date-and-time 198 +--ro (selection-filter)? 199 +--:(by-reference) 200 | +--ro selection-filter-ref selection-filter-ref 201 +--:(within-subscription) 202 +--ro (filter-spec)? 203 +--:(datastore-subtree-filter) 204 | +--ro datastore-subtree-filter? {sn:subtree}? 205 +--:(datastore-xpath-filter) 206 +--ro datastore-xpath-filter? yang:xpath1.0 {sn:xpath}? 208 2.1. Subscription Configuration 210 For adaptive subscriptions, triggered updates will occur at the 211 boundaries of specified time intervals when a trigger condition is 212 satisfied. These boundaries can be calculated from the adaptive 213 periodic parameters: 215 o a "period" that defines the new duration between push updates, the 216 period can be changed based on trigger condition. 218 o an "anchor-time" update intervals fall on the points in time that 219 are a multiple of a "period" from an "anchor-time". If an 220 "anchor-time" is not provided, then the "anchor-time" MUST be set 221 with the creation time of the initial update record. 223 o a "watermark" that defines the threshold value of the targeted 224 data object, e.g., it can be lower boundary or upper boundary of 225 targeted data object. 227 o a "xpath-external-eval" represents an Evaluation criteria that may 228 be applied against event records in an event stream, which is used 229 to trigger update interval switch in the server. It contains 230 comparisons of datastore node with its value to the specific 231 threshold (i.e., watermark) and associated logical operation in 232 the XPath format. Different from stream-xpath-filter defined in 233 [RFC8639], it doesn't influence the event records output 234 generation from a publisher. 236 2.2. YANG RPC 238 2.2.1. "establish-subscription" RPC 240 The augmentation of YANG module ietf-yang-push made to RPCs specified 241 in YANG module ietf-subscribed-notifications [RFC8639] is introduced. 242 This augmentation concerns the "establish- subscription" RPC, which 243 is augmented with parameters that are needed to specify adaptive 244 subscriptions. These parameters are same as one defined in 245 Section 2.1. 247 2.2.2. "modify-subscription" RPC 249 The subscriber MAY invoke the "modify-subscription" RPC for a 250 subscription it previously established. The subscriber will include 251 newly desired values in the "modify-subscription" RPC. Parameters 252 not included MUST remain unmodified. Section 4.4.2 of [RFC8641] 253 provides an example where a subscriber attempts to modify the period 254 and datastore XPath filter of a subscription using NETCONF. The 255 period can be the 'period' parameter defined by ietf-adaptive- 256 subscription. 258 2.3. Notifications for Adaptive Subscribed Content 260 The adaptive update notification is similar to Subscription state 261 change notifications defined in [RFC8639]. It is inserted into the 262 sequence of notification messages sent to a particular receiver. The 263 adaptive update notification cannot be dropped or filtered out, it 264 cannot be stored in replay buffers, and it is delivered only to 265 impacted receivers of a subscription. The identification of adaptive 266 update notification is easy to separate from other notification 267 messages through the use of the YANG extension "subscription-state- 268 notif". This extension tags a notification as a subscription state 269 change notification. 271 The objects in the 'adpative-update' notification include: 273 o a "period" that defines the duration between push updates, the 274 period can be changed based on trigger condition. 276 o an "anchor-time"; update intervals fall on the points in time that 277 are a multiple of a "period" from an "anchor-time". If an 278 "anchor-time" is not provided, then the "anchor-time" MUST be set 279 with the creation time of the initial update record. 281 o A selection filter identifying YANG nodes of interest in a 282 datastore. Filter contents are specified via a reference to an 283 existing filter or via an in-line definition for only that 284 subscription. Referenced filters allow an implementation to avoid 285 evaluating filter acceptability during a dynamic subscription 286 request. The "case" statement differentiates the options. Note 287 that filter contents are not affected by "xpath-external-eval" 288 parameter and "watermark" parameter defined by update trigger. 290 3. Adaptive Subscription YANG Module 292 file "ietf-adaptive-subscription@2020-02-14.yang" 293 module ietf-adaptive-subscription { 294 yang-version 1.1; 295 namespace "urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription"; 296 prefix as; 298 import ietf-subscribed-notifications { 299 prefix sn; 300 } 301 import ietf-yang-push { 302 prefix yp; 303 } 304 import ietf-yang-types { 305 prefix yang; 306 } 308 organization 309 "IETF NETCONF (Network Configuration) Working Group"; 310 contact 311 ""; 312 description 313 "NETCONF Protocol Data Types and Protocol Operations. 314 Copyright (c) 2020 IETF Trust and the persons identified as 315 the document authors. All rights reserved. 317 Redistribution and use in source and binary forms, with or 318 without modification, is permitted pursuant to, and subject 319 to the license terms contained in, the Simplified BSD License 320 set forth in Section 4.c of the IETF Trust's Legal Provisions 321 Relating to IETF Documents 322 (http://trustee.ietf.org/license-info). 324 This version of this YANG module is part of RFC xxxx; see 325 the RFC itself for full legal notices."; 327 revision 2019-12-15 { 328 description 329 "Initial revision"; 330 reference 331 "RFCxxx Adaptive subscription to YANG notification."; 332 } 334 typedef centiseconds { 335 type uint32; 336 description 337 "A period of time, measured in units of 0.01 seconds."; 338 } 340 typedef seconds { 341 type uint32; 342 description 343 "A period of time, measured in units of 1 seconds."; 344 } 346 typedef operator { 347 type enumeration { 348 enum unequal { 349 description 350 "Indicates that the comparision type is unequal to."; 351 } 352 enum equal { 353 description 354 "Indicates that the comparision type is equal to."; 355 } 356 enum less { 357 description 358 "Indicates that the comparision type is less than."; 359 } 360 enum less-or-equal { 361 description 362 "Indicates that the comparision type is less than 363 or equal to."; 364 } 365 enum greater { 366 description 367 "Indicates that the comparision type is greater than."; 368 } 369 enum greater-or-equal { 370 description 371 "Indicates that the comparision type is greater than 372 or equal to."; 373 } 374 } 375 description 376 "definition of the operator"; 377 } 379 grouping adaptive-subscription-modifiable { 380 description 381 "This grouping describes the datastore-specific adaptive subscription 382 conditions that can be changed during the lifetime of the 383 subscription."; 384 choice adaptive-subscription { 385 description 386 "Defines necessary conditions for sending an event record to 387 the subscriber."; 388 container adaptive-subscriptions { 389 list adaptive-period { 390 description 391 "Defines necessary conditions to switch update interval for 392 sending an event record to the subscriber. The event record output 393 generation will not be influeced these conditions."; 394 key "name"; 395 leaf name { 396 type string { 397 length "1..64"; 398 } 399 description 400 "The name of the condition to be matched. A device MAY further 401 restrict the length of this name; space and special 402 characters are not allowed."; 403 } 404 leaf xpath-external-eval { 405 type string; 406 description 407 "A XPath string, representing a logical expression, 408 which can contain comparisons of datastore values 409 and logical operations in the XPath format."; 410 } 411 leaf watermark { 412 type uint32; 413 description 414 "The watermark for targeted data object. The high 415 watermark, lowe watermark can be specified for the 416 targeted data object."; 417 } 418 leaf period { 419 type centiseconds; 420 mandatory true; 421 description 422 "Duration of time that should occur between periodic 423 push updates, in units of 0.01 seconds."; 424 } 425 leaf anchor-time { 426 type yang:date-and-time; 427 description 428 "Designates a timestamp before or after which a series 429 of periodic push updates are determined. The next 430 update will take place at a point in time that is a 431 multiple of a period from the 'anchor-time'. 432 For example, for an 'anchor-time' that is set for the 433 top of a particular minute and a period interval of a 434 minute, updates will be sent at the top of every 435 minute that this subscription is active."; 436 } 437 } 438 description 439 "Container for adaptive subscription."; 440 } 441 } 442 } 444 augment "/sn:subscriptions/sn:subscription/yp:update-trigger" { 445 description 446 "This augmentation adds additional subscription parameters 447 that apply specifically to adaptive subscription."; 448 uses adaptive-subscription-modifiable; 449 } 450 augment "/sn:establish-subscription/sn:input/yp:update-trigger" { 451 description 452 "This augmentation adds additional subscription parameters 453 that apply specifically to datastore updates to RPC input."; 454 uses adaptive-subscription-modifiable; 455 } 457 notification adaptive-period-update { 458 sn:subscription-state-notification; 459 description 460 "This notification contains a push update that in turn contains 461 data subscribed to via a subscription. In the case of a 462 periodic subscription, this notification is sent for periodic 463 updates. It can also be used for synchronization updates of 464 an on-change subscription. This notification shall only be 465 sent to receivers of a subscription. It does not constitute 466 a general-purpose notification that would be subscribable as 467 part of the NETCONF event stream by any receiver."; 468 leaf id { 469 type sn:subscription-id; 470 description 471 "This references the subscription that drove the 472 notification to be sent."; 473 } 474 leaf period { 475 type centiseconds; 476 mandatory true; 477 description 478 "New duration of time that should occur between periodic 479 push updates, in units of 0.01 seconds."; 480 } 481 leaf anchor-time { 482 type yang:date-and-time; 483 description 484 "Designates a timestamp before or after which a series 485 of periodic push updates are determined. The next 486 update will take place at a point in time that is a 487 multiple of a period from the 'anchor-time'. 488 For example, for an 'anchor-time' that is set for the 489 top of a particular minute and a period interval of a 490 minute, updates will be sent at the top of every 491 minute that this subscription is active."; 492 } 493 uses yp:datastore-criteria { 494 refine "selection-filter/within-subscription" { 495 description 496 "Specifies the selection filter and where it originated 497 from. If the 'selection-filter-ref' is populated, the 498 filter in the subscription came from the 'filters' 499 container. Otherwise, it is populated in-line as part 500 of the subscription itself."; 501 } 502 } 503 } 504 } 505 506 4. IANA Considerations 508 4.1. Updates to the IETF XML Registry 510 This document registers two URIs in the IETF XML registry [RFC3688]. 511 Following the format in [RFC3688], the following registrations are 512 requested to be made: 514 --------------------------------------------------------------------- 515 URI: urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription 516 Registrant Contact: The IESG. 517 XML: N/A, the requested URI is an XML namespace. 518 --------------------------------------------------------------------- 520 4.2. Updates to the YANG Module Names Registry 522 This document registers two YANG modules in the YANG Module Names 523 registry [RFC7950]. . Following the format in [RFC6020], the 524 following registration has been made: 526 --------------------------------------------------------------------- 527 Name: ietf-adaptive-subscription 528 Namespace: urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription 529 Prefix: as 530 Reference: RFC xxxx 531 --------------------------------------------------------------------- 533 5. Security Considerations 535 The YANG module specified in this document defines a schema for data 536 that is designed to be accessed via network management protocols such 537 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 538 is the secure transport layer, and the mandatory-to-implement secure 539 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 540 is HTTPS, and the mandatory-to-implement secure transport is TLS 541 [RFC8446]. 543 The NETCONF Configuration Access Control Model (NACM) [RFC8341] 544 provides the means to restrict access for particular NETCONF or 545 RESTCONF users to a preconfigured subset of all available NETCONF or 546 RESTCONF protocol operations and content. 548 There are a number of data nodes defined in this YANG module that are 549 writable/creatable/deletable (i.e., config true, which is the 550 default). These data nodes may be considered sensitive in some 551 network environments. Write operations (e.g., edit-config) to these 552 data nodes without proper protection can have a negative effect on 553 network operations. These are the subtrees and data nodes and their 554 sensitivity/vulnerability: 556 o /sn:subscriptions/sn:subscription/yp:update-trigger/as:adaptive- 557 subscriptions/as:adaptive-period/as:watermark 559 o /sn:subscriptions/sn:subscription/yp:update-trigger/as:adaptive- 560 subscriptions/as:adaptive-period/as:period 562 o /sn:subscriptions/sn:subscription/yp:update-trigger/as:adaptive- 563 subscriptions/as:adaptive-period/as:anchor-time 565 6. Contributors 567 Michale Wang, Liang Geng for his major contributions to the initial 568 modeling and use cases. 570 Michale Wang 571 Email: wangzitao@huawei.com 573 Liang Geng 574 China Mobile 575 32 Xuanwumen West St, Xicheng District 576 Beijing 10053 578 Email: gengliang@chinamobile.com 580 7. Acknowledges 582 We would like to thanks Rob Wilton, Thomas Graf, Andy Bierman for 583 valuable review on this document, special thanks to Thmas to organize 584 the discussion on several relevant drafts and reach the common 585 understanding on the concept and ideas. 587 8. References 589 8.1. Normative References 591 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 592 Requirement Levels", BCP 14, RFC 2119, 593 DOI 10.17487/RFC2119, March 1997, 594 . 596 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 597 and A. Bierman, Ed., "Network Configuration Protocol 598 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 599 . 601 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 602 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 603 . 605 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 606 RFC 7950, DOI 10.17487/RFC7950, August 2016, 607 . 609 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 610 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 611 . 613 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 614 Writing an IANA Considerations Section in RFCs", BCP 26, 615 RFC 8126, DOI 10.17487/RFC8126, June 2017, 616 . 618 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 619 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 620 May 2017, . 622 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 623 Access Control Model", STD 91, RFC 8341, 624 DOI 10.17487/RFC8341, March 2018, 625 . 627 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 628 and R. Wilton, "Network Management Datastore Architecture 629 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 630 . 632 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 633 Documents Containing YANG Data Models", BCP 216, RFC 8407, 634 DOI 10.17487/RFC8407, October 2018, 635 . 637 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 638 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 639 . 641 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 642 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 643 September 2019, . 645 8.2. Informative References 647 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 648 DOI 10.17487/RFC3688, January 2004, 649 . 651 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 652 the Network Configuration Protocol (NETCONF)", RFC 6020, 653 DOI 10.17487/RFC6020, October 2010, 654 . 656 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 657 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 658 . 660 Appendix A. Example YANG Module 662 The example YANG module used in this document represents a simple 663 wifi mac interface. 665 YANG tree diagram for the "example-wifi-mac" module: 667 module: example-wifi-mac 668 +--rw clients 669 +--ro client* [mac] 670 +--ro mac yang:mac-address 671 +--ro rssi? int8 672 +--ro snr? uint8 673 +--ro ss? uint8 674 +--ro phy-rate? uint16 675 +--ro channel-support* uint8 676 +--ro neighbors 677 | +--ro neighbor-bssid? yang:mac-address 678 | +--ro neighbor-channel? uint8 679 | +--ro neighbor-rssi? int8 680 | +--ro neighbor-antenna? uint8 681 | +--ro channel-load-report? uint8 682 +--ro ssid 683 +--ro name? string 684 +--ro enabled? boolean 685 +--ro broadcast-filter? boolean 686 +--ro multicast-filter? boolean 687 +--ro ipv6-ndp-filter? boolean 688 +--ro ipv6-ndp-filter-timer? uint16 689 +--ro station-isolation? boolean 691 A.1. "example-wifi-mac" YANG Module 693 module example-wifi-mac { 694 yang-version 1; 695 namespace "http://example.com/yang/wifi-mac"; 696 prefix wifi; 698 import ietf-yang-types { 699 prefix yang; 700 } 702 container clients { 703 description 704 "Top-level container for clients operational state data."; 705 list client { 706 key "mac"; 707 config false; 708 description 709 "List of clients per BSS."; 710 leaf mac { 711 type yang:mac-address; 712 description 713 "MAC address of the client."; 714 } 715 leaf rssi { 716 type int8; 717 description 718 "The RSSI of this client in dBm. Expressed as negative 719 number"; 720 } 721 leaf snr { 722 type uint8; 723 description 724 "The SNR of AP to Client, in dB."; 725 } 726 leaf ss { 727 type uint8; 728 description 729 "Number of Spatial Streams supported by the client."; 730 } 731 leaf phy-rate { 732 type uint16; 733 description 734 "Last used PHY rate of connected client."; 735 } 736 leaf-list channel-support { 737 type uint8; 738 description 739 "List of supported channels."; 740 } 741 container neighbors { 742 description 743 "Container for Client beacon reports. Requires 802.11k 744 enabled. See Sec. 5.2.7.1 of 802.11k-2008 Standard."; 745 leaf neighbor-bssid { 746 type yang:mac-address; 747 description 748 "The BSSID of this neighbor."; 749 } 750 leaf neighbor-channel { 751 type uint8; 752 description 753 "The channel of this neighbor."; 754 } 755 leaf neighbor-rssi { 756 type int8; 757 description 758 "The RSSI of this neighbor in dBm, expressed as a negative 759 number."; 760 } 761 leaf neighbor-antenna { 762 type uint8; 763 description 764 "Antenna details for this neighbor."; 765 } 766 leaf channel-load-report { 767 type uint8; 768 description 769 "Channel load, as reported by Client to AP 770 normalized to 255. See Sec. 10.11.9.3 of 802.11ac-2013 771 Spec."; 772 } 773 } 774 container ssid { 775 description 776 "Top level container for ssids, including configuration 777 and state data."; 778 leaf name { 779 type string; 780 description 781 "The name of the SSID."; 782 } 783 leaf enabled { 784 type boolean; 785 default "true"; 786 description 787 "The desired operational state (up/down) of this SSID."; 788 } 789 leaf broadcast-filter { 790 type boolean; 791 description 792 "Convert all downstream broadcast ARP to unicast 793 only if Station is associated to the AP. Drop packet 794 if Station is not associated to the AP. All other 795 broadcast, except DHCP, is dropped by the AP. 797 DHCP Offers/ACKs are converted to Unicast, over-the-air."; 798 } 799 leaf multicast-filter { 800 type boolean; 801 description 802 "Drop all downstream Multicast packets."; 803 } 804 leaf ipv6-ndp-filter { 805 type boolean; 806 description 807 "Neighbor Advertisements will be cached at the AP (or WLC) 808 and unicast in response to Neighbor Solicitations. 810 Router Advertisements, in response to a Router Solicitation 811 are converted to Unicast for over-the-air transmission."; 812 } 813 leaf ipv6-ndp-filter-timer { 814 type uint16; 815 units "seconds"; 816 description 817 "Time, in seconds, the ndp-filter will cache 818 Neighbor Advertisements (NA)."; 819 } 820 leaf station-isolation { 821 type boolean; 822 description 823 "Block Station peer to peer communication."; 824 } 825 } 826 } 827 } 828 } 830 Appendix B. Adaptive Subscription and Notification Example 832 The examples within this document use the normative YANG module 833 "ietf-adaptive-subscription" as defined in Section 3 and the non- 834 normative example YANG module "example-wifi-mac" as defined in 835 Appendix A.1. 837 This section shows some typical adaptive subscription and 838 notification message exchanges. 840 B.1. "edit-config" Example 842 The client configures adaptive subscription policy parameters on the 843 server. The adaptive subscription configuration parameters require 844 the server to scan all clients every 5 seconds if the rssi value of 845 client is greater than -65dB; If the rssi value of client is less 846 than -65dB, switch to 60 seconds period value, and then scan all 847 clients every 60 seconds. 849 851 852 853 854 855 857 860 862 ds:running 863 864 866 /ex:example-wifi-mac 867 868 870 871 872 /as:clients/as:client[rssi < -65] 873 874 -65 875 60 876 877 878 879 /as:clients/as:client[rssi > -65] 880 881 -65 882 5 883 884 885 886 887 888 890 B.2. Create Adaptive Subscription Example 892 The subscriber sends an "establish-subscription" RPC with the 893 parameters listed in to request the creation of a adaptive 894 subscription. The adaptive subscription configuration parameters 895 require the server to scan all clients every 5 seconds if the rssi 896 value of client is greater than -65dB; If the rssi value of client is 897 less than -65dB, switch to 60 seconds period value, and then scan all 898 clients every 60 seconds. (Section 2) 900 902 905 907 ds:running 908 909 911 /ex:example-wifi-mac 912 913 915 916 as:clients/as:client[rssi > -65] 917 918 -65 919 5 920 921 922 as:clients/as:client[rssi < -65] 923 924 -65 925 60 926 927 928 929 931 In another example, the adaptive subscription configuration 932 parameters could also require the server to scan all clients every 5 933 seconds if the difference between maximum value of client rssi and 934 minimum value of client rssi is greater than 0.20dB; If the 935 difference between maximum value of client rssi and minimum value of 936 client rssi is less than 20dB, switch to 60 seconds period value and 937 then scan all clients every 60 seconds. 939 941 944 946 ds:running 947 948 950 /ex:example-wifi-mac 951 952 954 as:clients/as:client 955 ssid 956 957 958 as:clients/as:client[max(rssi)-min(rssi) > 20] 959 960 20 961 5 962 963 964 965 as:clients/as:client[max(rssi)-min(rssi) < 20] 966 967 20 968 60 969 970 971 972 974 B.3. "adaptive-update" notification example 976 Upon the server switches to from the update interval 5 seconds to the 977 new update interval 60 seconds, Before sending event records to 978 receivers, the "adaptive-update" notification should be generated and 979 sent to the receivers to inform the receivers that the update 980 interval value is switched to the new value. 982 985 2016-11-21T13:51:00Z 986 988 0 989 60 990 992 ds:running 993 994 996 /ex:example-wifi-mac 997 998 999 1001 B.4. Changes between Revisions 1003 v02 - v03 1005 o Clarify the difference between low priority telemetry data 1006 dropping and collection rate switching in the introduction 1007 section; 1009 o Update the abstract and introduction section to focus on 1010 collection rate switching in the server without interaction with 1011 the remote client; 1013 o Format usage example and change ssid into rssi in the appendix; 1015 o Use boilerplate and reuse the terms in the terminology section. 1017 Authors' Addresses 1019 Qin Wu 1020 Huawei 1021 101 Software Avenue, Yuhua District 1022 Nanjing, Jiangsu 210012 1023 China 1025 Email: bill.wu@huawei.com 1026 Wei Song 1027 Huawei 1028 101 Software Avenue, Yuhua District 1029 Nanjing, Jiangsu 210012 1030 China 1032 Email: songwei80@huawei.com 1034 Peng Liu 1035 China Mobile 1036 32 Xuanwumen West St, Xicheng District 1037 Beijing 10053 1039 Email: liupengyjy@chinamobile.com 1041 Qiufang Ma 1042 Huawei 1043 101 Software Avenue, Yuhua District 1044 Nanjing, Jiangsu 210012 1045 China 1047 Email: maqiufang1@huawei.com