idnits 2.17.1 draft-wang-netconf-adaptive-subscription-06.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. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 10, 2021) is 1020 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 133, but not defined == Missing Reference: 'RFC3198' is mentioned on line 133, but not defined == Missing Reference: 'RFC8639' is mentioned on line 252, but not defined == Unused Reference: 'RFC8126' is defined on line 581, but no explicit reference was found in the text == Unused Reference: 'RFC8407' is defined on line 600, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 6 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: January 11, 2022 P. Liu 6 China Mobile 7 Q. Ma 8 Huawei 9 W. Wang 10 China Telecom 11 July 10, 2021 13 Adaptive Subscription to YANG Notification 14 draft-wang-netconf-adaptive-subscription-06 16 Abstract 18 This document defines a YANG data model and associated mechanism 19 enabling subscriber's adaptive subscriptions to a publisher's event 20 streams with various different period intervals to report updates. 21 Applying these elements allows servers automatically adjust the 22 volume of telemetry traffic and rate of traffic sent from publisher 23 to the receivers. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on January 11, 2022. 42 Copyright Notice 44 Copyright (c) 2021 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Model Overview . . . . . . . . . . . . . . . . . . . . . . . 4 62 2.1. Subscription Configuration . . . . . . . . . . . . . . . 5 63 2.2. YANG RPC . . . . . . . . . . . . . . . . . . . . . . . . 6 64 2.2.1. "establish-subscription" RPC . . . . . . . . . . . . 6 65 2.3. Notifications for Adaptive Subscribed Content . . . . . . 6 66 3. Adaptive Subscription YANG Module . . . . . . . . . . . . . . 7 67 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 68 4.1. Updates to the IETF XML Registry . . . . . . . . . . . . 11 69 4.2. Updates to the YANG Module Names Registry . . . . . . . . 11 70 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 71 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 12 72 7. Acknowledges . . . . . . . . . . . . . . . . . . . . . . . . 12 73 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 74 8.1. Normative References . . . . . . . . . . . . . . . . . . 13 75 8.2. Informative References . . . . . . . . . . . . . . . . . 14 76 Appendix A. Example YANG Module . . . . . . . . . . . . . . . . 14 77 A.1. "example-wifi-mac" YANG Module . . . . . . . . . . . . . 15 78 Appendix B. Adaptive Subscription and Notification Example . . . 19 79 B.1. "edit-config" Example . . . . . . . . . . . . . . . . . . 19 80 B.2. Create Adaptive Subscription Example . . . . . . . . . . 21 81 B.3. "adaptive-update" notification example . . . . . . . . . 22 82 B.4. Changes between Revisions . . . . . . . . . . . . . . . . 23 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 85 1. Introduction 87 YANG-Push subscriptions [RFC8641] allow client applications to 88 subscribe to continuous datastore updates without needing to poll. 89 It defines a mechanism (i.e.,update trigger) to determine when an 90 update record needs to be generated. Two type of subscriptions are 91 introduced in [RFC8641], distinguished by how updates are triggered: 92 periodic and on-change. 94 o Periodic subscription allows subscribed data to be streamed to the 95 destination at a configured fixed periodic interval 97 o On-change subscription allows update to be triggered whenever a 98 change in the subscribed information is detected. The periodic 99 interval is set to zero value in the on-change subscription case. 101 However in some large scale deployments (e.g., wireless network 102 performance monitoring) where an increased data collection rate is 103 being used, it becomes more likely that a burst of streamed data may 104 temporarily overwhelm a receiver and consume expensive network 105 resource (e.g., radio resource). If the rate at which we can collect 106 a stream of data is set too low or getting low priority telemetry 107 data dropped, these telemetry data are not sufficient to detect and 108 diagnose problems and verify correct network behavior. There is a 109 need for a service to configure both clients and servers with 110 multiple different period intervals and corresponding subscription 111 policy which allows servers/publishers automatically switch to 112 different period intervals according to resource usage change without 113 the interaction with the remote client, e.g., when the wireless 114 signal strength falls below a configured low watermark, the 115 subscribed data can be streamed at a higher rate while when the 116 wireless signal strength crosses a configured high watermark, the 117 subscribed data can be streamed at lower rate. 119 This document defines a YANG data model and associated mechanism 120 enabling subscriber's adaptive subscriptions to a publisher's event 121 streams. Applying these elements allows servers to automatically 122 adjust the volume of telemetry traffic and rate of traffic sent from 123 publisher to the receivers. 125 1.1. Terminology 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 129 "OPTIONAL" in this document are to be interpreted as described in BCP 130 14 [RFC2119] [RFC8174] when, and only when, they appear in all 131 capitals, as shown here. 133 The following terms are defined in [RFC5277] [RFC7950] [RFC3198] 134 [RFC8342] [RFC8639] and are not redefined here: 136 o Event 138 o Client 140 o Configuration 142 o Configured subscription 144 o Configuration datastore 145 o Notification message 147 o Publisher 149 o Receiver 151 o Subscriber 153 o Subscription 155 o On-change subscription 157 o Periodic subscription 159 2. Model Overview 161 This document defines a YANG module "ietf-adaptive-subscription", 162 which augments the "update-trigger" choice defined in the "ietf-yang- 163 push" module [RFC8641] with subscription configuration parameters 164 that are specific to adaptive subscription. 166 In addition to Subscription state notifications defined in [RFC8639] 167 and Notifications for Subscribed Content defined in [RFC8641], "ietf- 168 adaptive-subscription" YANG module also defines "adaptive-period- 169 update" notification to report update interval change. 171 The following tree diagrams [RFC8340] provide an overview of the data 172 model for "ietf-adaptive-subscription.yang" module. 174 module: ietf-adaptive-subscription 175 augment /sn:subscriptions/sn:subscription/yp:update-trigger: 176 +--rw (adaptive-subscription)? 177 +--:(adaptive-subscriptions) 178 +--rw adaptive-subscriptions 179 +--rw adaptive-period* [name] 180 +--rw name string 181 +--rw xpath-external-eval string 182 +--rw watermark? uint32 183 +--rw period centiseconds 184 +--rw anchor-time? yang:date-and-time 185 augment /sn:establish-subscription/sn:input/yp:update-trigger: 186 +-- (adaptive-subscription)? 187 +--:(adaptive-subscriptions) 188 +--rw adaptive-subscriptions 189 +--rw adaptive-period* [name] 190 +--rw name string 191 +--rw xpath-external-eval string 192 +--rw watermark? uint32 193 +--rw period centiseconds 194 +--rw anchor-time? yang:date-and-time 195 notifications: 196 +---n adaptive-period-update 197 +--ro id? sn:subscription-id 198 +--ro period centiseconds 199 +--ro anchor-time? yang:date-and-time 200 +--ro (selection-filter)? 201 +--:(by-reference) 202 | +--ro selection-filter-ref selection-filter-ref 203 +--:(within-subscription) 204 +--ro (filter-spec)? 205 +--:(datastore-subtree-filter) 206 | +--ro datastore-subtree-filter? {sn:subtree}? 207 +--:(datastore-xpath-filter) 208 +--ro datastore-xpath-filter? yang:xpath1.0 {sn:xpath}? 210 2.1. Subscription Configuration 212 For adaptive subscriptions, triggered updates will occur at the 213 boundaries of specified time intervals when a trigger condition is 214 satisfied. These boundaries can be calculated from the adaptive 215 periodic parameters: 217 o a "period" that defines the new duration between push updates, the 218 period can be changed based on trigger condition. 220 o an "anchor-time" update intervals fall on the points in time that 221 are a multiple of a "period" from an "anchor-time". If an 222 "anchor-time" is not provided, then the "anchor-time" MUST be set 223 with the creation time of the initial update record. 225 o a "watermark" that defines the threshold value of the targeted 226 data object, e.g., it can be lower boundary or upper boundary of 227 targeted data object. 229 o a "xpath-external-eval" represents an Evaluation criteria that may 230 be applied against event records in an event stream, which is used 231 to trigger update interval switch in the server. It contains 232 comparisons of datastore node with its value to the specific 233 threshold (i.e., watermark) and associated logical operation in 234 the XPath format. Different from stream-xpath-filter defined in 235 [RFC8639], it doesn't influence the event records output 236 generation from a publisher. 238 2.2. YANG RPC 240 2.2.1. "establish-subscription" RPC 242 The augmentation of YANG module ietf-yang-push made to RPCs specified 243 in YANG module ietf-subscribed-notifications [RFC8639] is introduced. 244 This augmentation concerns the "establish- subscription" RPC, which 245 is augmented with parameters that are needed to specify adaptive 246 subscriptions. These parameters are same as one defined in 247 Section 2.1. 249 2.3. Notifications for Adaptive Subscribed Content 251 The adaptive update notification is similar to Subscription state 252 change notifications defined in [RFC8639]. It is inserted into the 253 sequence of notification messages sent to a particular receiver. The 254 adaptive update notification cannot be dropped or filtered out, it 255 cannot be stored in replay buffers, and it is delivered only to 256 impacted receivers of a subscription. The identification of adaptive 257 update notification is easy to separate from other notification 258 messages through the use of the YANG extension "subscription-state- 259 notif". This extension tags a notification as a subscription state 260 change notification. 262 The objects in the 'adpative-update' notification include: 264 o a "period" that defines the duration between push updates, the 265 period can be changed based on trigger condition. 267 o an "anchor-time"; update intervals fall on the points in time that 268 are a multiple of a "period" from an "anchor-time". If an 269 "anchor-time" is not provided, then the "anchor-time" MUST be set 270 with the creation time of the initial update record. 272 o A selection filter identifying YANG nodes of interest in a 273 datastore. Filter contents are specified via a reference to an 274 existing filter or via an in-line definition for only that 275 subscription. Referenced filters allow an implementation to avoid 276 evaluating filter acceptability during a dynamic subscription 277 request. The "case" statement differentiates the options. Note 278 that filter contents are not affected by "xpath-external-eval" 279 parameter and "watermark" parameter defined by update trigger. 281 3. Adaptive Subscription YANG Module 283 file "ietf-adaptive-subscription@2020-02-14.yang" 284 module ietf-adaptive-subscription { 285 yang-version 1.1; 286 namespace "urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription"; 287 prefix as; 288 import ietf-subscribed-notifications { 289 prefix sn; 290 } 291 import ietf-yang-push { 292 prefix yp; 293 } 294 import ietf-yang-types { 295 prefix yang; 296 } 298 organization 299 "IETF NETCONF (Network Configuration) Working Group"; 300 contact 301 ""; 302 description 303 "NETCONF Protocol Data Types and Protocol Operations. 304 Copyright (c) 2020 IETF Trust and the persons identified as 305 the document authors. All rights reserved. 307 Redistribution and use in source and binary forms, with or 308 without modification, is permitted pursuant to, and subject 309 to the license terms contained in, the Simplified BSD License 310 set forth in Section 4.c of the IETF Trust's Legal Provisions 311 Relating to IETF Documents 312 (http://trustee.ietf.org/license-info). 314 This version of this YANG module is part of RFC xxxx; see 315 the RFC itself for full legal notices."; 317 revision 2019-12-15 { 318 description 319 "Initial revision"; 320 reference 321 "RFCxxx Adaptive subscription to YANG notification."; 322 } 324 typedef centiseconds { 325 type uint32; 326 description 327 "A period of time, measured in units of 0.01 seconds."; 328 } 330 typedef seconds { 331 type uint32; 332 description 333 "A period of time, measured in units of 1 seconds."; 334 } 336 grouping adaptive-subscription-modifiable { 337 description 338 "This grouping describes the datastore-specific adaptive subscription 339 conditions that can be changed during the lifetime of the 340 subscription."; 341 choice adaptive-subscription { 342 description 343 "Defines necessary conditions for sending an event record to 344 the subscriber."; 345 container adaptive-subscriptions { 346 list adaptive-period { 347 key "name"; 348 description 349 "Defines necessary conditions to switch update interval for 350 sending an event record to the subscriber. The event record output 351 generation will not be influeced these conditions."; 352 leaf name { 353 type string { 354 length "1..64"; 355 } 356 description 357 "The name of the condition to be matched. A device MAY further 358 restrict the length of this name; space and special 359 characters are not allowed."; 360 } 361 leaf xpath-external-eval { 362 type string; 363 description 364 "A XPath string, representing a logical expression, 365 which can contain comparisons of datastore values 366 and logical operations in the XPath format."; 367 } 368 leaf watermark { 369 type uint32; 370 description 371 "The watermark for targeted data object. The high 372 watermark, lowe watermark can be specified for the 373 targeted data object."; 374 } 375 leaf period { 376 type centiseconds; 377 mandatory true; 378 description 379 "Duration of time that should occur between periodic 380 push updates, in units of 0.01 seconds."; 381 } 382 leaf anchor-time { 383 type yang:date-and-time; 384 description 385 "Designates a timestamp before or after which a series 386 of periodic push updates are determined. The next 387 update will take place at a point in time that is a 388 multiple of a period from the 'anchor-time'. 389 For example, for an 'anchor-time' that is set for the 390 top of a particular minute and a period interval of a 391 minute, updates will be sent at the top of every 392 minute that this subscription is active."; 393 } 394 } 395 description 396 "Container for adaptive subscription."; 397 } 398 } 399 } 401 augment "/sn:subscriptions/sn:subscription/yp:update-trigger" { 402 description 403 "This augmentation adds additional subscription parameters 404 that apply specifically to adaptive subscription."; 405 uses adaptive-subscription-modifiable; 406 } 407 augment "/sn:establish-subscription/sn:input/yp:update-trigger" { 408 description 409 "This augmentation adds additional subscription parameters 410 that apply specifically to datastore updates to RPC input."; 411 uses adaptive-subscription-modifiable; 412 } 413 notification adaptive-period-update { 414 sn:subscription-state-notification; 415 description 416 "This notification contains a push update that in turn contains 417 data subscribed to via a subscription. In the case of a 418 periodic subscription, this notification is sent for periodic 419 updates. It can also be used for synchronization updates of 420 an on-change subscription. This notification shall only be 421 sent to receivers of a subscription. It does not constitute 422 a general-purpose notification that would be subscribable as 423 part of the NETCONF event stream by any receiver."; 424 leaf id { 425 type sn:subscription-id; 426 description 427 "This references the subscription that drove the 428 notification to be sent."; 429 } 430 leaf period { 431 type centiseconds; 432 mandatory true; 433 description 434 "New duration of time that should occur between periodic 435 push updates, in units of 0.01 seconds."; 436 } 437 leaf anchor-time { 438 type yang:date-and-time; 439 description 440 "Designates a timestamp before or after which a series 441 of periodic push updates are determined. The next 442 update will take place at a point in time that is a 443 multiple of a period from the 'anchor-time'. 444 For example, for an 'anchor-time' that is set for the 445 top of a particular minute and a period interval of a 446 minute, updates will be sent at the top of every 447 minute that this subscription is active."; 448 } 449 uses yp:datastore-criteria { 450 refine "selection-filter/within-subscription" { 451 description 452 "Specifies the selection filter and where it originated 453 from. If the 'selection-filter-ref' is populated, the 454 filter in the subscription came from the 'filters' 455 container. Otherwise, it is populated in-line as part 456 of the subscription itself."; 457 } 458 } 459 } 460 } 461 463 4. IANA Considerations 465 4.1. Updates to the IETF XML Registry 467 This document registers two URIs in the IETF XML registry [RFC3688]. 468 Following the format in [RFC3688], the following registrations are 469 requested to be made: 471 --------------------------------------------------------------------- 472 URI: urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription 473 Registrant Contact: The IESG. 474 XML: N/A, the requested URI is an XML namespace. 475 --------------------------------------------------------------------- 477 4.2. Updates to the YANG Module Names Registry 479 This document registers two YANG modules in the YANG Module Names 480 registry [RFC7950]. . Following the format in [RFC6020], the 481 following registration has been made: 483 --------------------------------------------------------------------- 484 Name: ietf-adaptive-subscription 485 Namespace: urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription 486 Prefix: as 487 Reference: RFC xxxx 488 --------------------------------------------------------------------- 490 5. Security Considerations 492 The YANG module specified in this document defines a schema for data 493 that is designed to be accessed via network management protocols such 494 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 495 is the secure transport layer, and the mandatory-to-implement secure 496 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 497 is HTTPS, and the mandatory-to-implement secure transport is TLS 498 [RFC8446]. 500 The NETCONF Configuration Access Control Model (NACM) [RFC8341] 501 provides the means to restrict access for particular NETCONF or 502 RESTCONF users to a preconfigured subset of all available NETCONF or 503 RESTCONF protocol operations and content. 505 There are a number of data nodes defined in this YANG module that are 506 writable/creatable/deletable (i.e., config true, which is the 507 default). These data nodes may be considered sensitive in some 508 network environments. Write operations (e.g., edit-config) to these 509 data nodes without proper protection can have a negative effect on 510 network operations. These are the subtrees and data nodes and their 511 sensitivity/vulnerability: 513 o /sn:subscriptions/sn:subscription/yp:update-trigger/as:adaptive- 514 subscriptions/as:adaptive-period/as:watermark 516 o /sn:subscriptions/sn:subscription/yp:update-trigger/as:adaptive- 517 subscriptions/as:adaptive-period/as:period 519 o /sn:subscriptions/sn:subscription/yp:update-trigger/as:adaptive- 520 subscriptions/as:adaptive-period/as:anchor-time 522 o /sn:establish-subscription/sn:input/yp:update-trigger/as:adaptive- 523 subscriptions/as:adaptive-period/as:watermark 525 o /sn:establish-subscription/sn:input/yp:update-trigger/as:adaptive- 526 subscriptions/as:adaptive-period/as:period 528 o /sn:establish-subscription/sn:input/yp:update-trigger/as:adaptive- 529 subscriptions/as:adaptive-period/as:anchor-time 531 6. Contributors 533 Michale Wang, Liang Geng for his major contributions to the initial 534 modeling and use cases. 536 Michale Wang 537 Email: wangzitao@huawei.com 539 Liang Geng 540 China Mobile 541 32 Xuanwumen West St, Xicheng District 542 Beijing 10053 544 Email: gengliang@chinamobile.com 546 7. Acknowledges 548 We would like to thanks Rob Wilton, Thomas Graf, Andy Bierman, 549 Michael Richardson, Henk Birkholz for valuable review on this 550 document, special thanks to Thmas and Michael to organize the 551 discussion on several relevant drafts and reach the common 552 understanding on the concept and ideas. Thanks Michael for providing 553 CHIP/Matter WIFI statistics reference. 555 8. References 557 8.1. Normative References 559 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 560 Requirement Levels", BCP 14, RFC 2119, 561 DOI 10.17487/RFC2119, March 1997, 562 . 564 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 565 and A. Bierman, Ed., "Network Configuration Protocol 566 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 567 . 569 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 570 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 571 . 573 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 574 RFC 7950, DOI 10.17487/RFC7950, August 2016, 575 . 577 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 578 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 579 . 581 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 582 Writing an IANA Considerations Section in RFCs", BCP 26, 583 RFC 8126, DOI 10.17487/RFC8126, June 2017, 584 . 586 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 587 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 588 May 2017, . 590 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 591 Access Control Model", STD 91, RFC 8341, 592 DOI 10.17487/RFC8341, March 2018, 593 . 595 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 596 and R. Wilton, "Network Management Datastore Architecture 597 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 598 . 600 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 601 Documents Containing YANG Data Models", BCP 216, RFC 8407, 602 DOI 10.17487/RFC8407, October 2018, 603 . 605 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 606 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 607 . 609 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 610 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 611 September 2019, . 613 8.2. Informative References 615 [CHIP] Matter, "Connected Home over IP Specification", April 616 2021. 618 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 619 DOI 10.17487/RFC3688, January 2004, 620 . 622 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 623 the Network Configuration Protocol (NETCONF)", RFC 6020, 624 DOI 10.17487/RFC6020, October 2010, 625 . 627 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 628 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 629 . 631 Appendix A. Example YANG Module 633 The example YANG module used in this document represents a Wi-Fi 634 Network Diagnostics data specified in [CHIP] which can be used by a 635 Node to assist a user or Administrative Node in diagnosing potential 636 problems. 638 YANG tree diagram for the "example-wifi-mac" module: 640 module: example-wifi-network-diagnostic 641 +--rw server 642 | +--rw bssid? yang:mac-address 643 | +--rw security-type? enumeration 644 | +--rw wifi-version? enumeration 645 | +--rw channel-num? int8 646 | +--rw rssi? int8 647 | +--rw beacon-lost-count? int8 648 | +--rw beacon-rx-count? int8 649 | +--rw packet-multicast-rx-count? int8 650 | +--rw packet-multicast-tx-count? int8 651 | +--rw packet-unicast-rx-count? int8 652 | +--rw packet-unicast-tx-count? int8 653 | +--rw current-max-rate? int8 654 | +--rw overrun-count? int8 655 +--rw events 656 +--rw event* [name] 657 +--rw name string 658 +--rw disconnection? enumeration 659 +--rw association-failure? enumeration 660 +--rw Connection-status? enumeration 662 A.1. "example-wifi-mac" YANG Module 664 module example-wifi-network-diagnostic { 665 yang-version 1; 666 namespace "http://example.com/yang/wifi-network-diagnostic"; 667 prefix wnd; 669 import ietf-yang-types { 670 prefix yang; 671 } 673 container server { 674 description 675 "Configuration of the WiFi Server logical entity."; 676 leaf bssid { 677 type yang:mac-address; 678 description 679 "The MAC address of a wireless access point."; 680 } 681 leaf security-type { 682 type enumeration { 683 enum unspecified { 684 value 0; 685 } 686 enum none { 687 value 1; 689 } 690 enum wep { 691 value 2; 692 } 693 enum wpa { 694 value 3; 695 } 696 enum wpa2 { 697 value 4; 698 } 699 enum wpa3 { 700 value 5; 701 } 702 } 703 description 704 "The type of Wi-Fi security used. A value of 0 705 indicate that the interface is not currently 706 configured or operational."; 707 } 708 leaf wifi-version { 709 type enumeration { 710 enum 80211a { 711 value 0; 712 } 713 enum 80211b { 714 value 1; 715 } 716 enum 80211g { 717 value 2; 718 } 719 enum 80211n { 720 value 3; 721 } 722 enum 80211ac { 723 value 4; 724 } 725 enum 80211ax { 726 value 5; 727 } 728 } 729 description 730 "The highest 802.11 standard version usable 731 by the Node."; 732 } 733 leaf channel-num { 734 type int8; 735 description 736 "The channel that Wi-Fi communication is currently 737 operating on. A value of 0indicates that the interface 738 is not currently configured or operational."; 739 } 740 leaf rssi { 741 type int8; 742 description 743 "The RSSI of the Node's Wi-Fi radio in dBm."; 744 } 745 leaf beacon-lost-count { 746 type int8; 747 description 748 "The count of the number of missed beacons the 749 Node has detected."; 750 } 751 leaf beacon-rx-count { 752 type int8; 753 description 754 "The count of the number of received beacons. The 755 total number of expected beacons that could have been 756 received during the interval since association SHOULD 757 match the sum of BeaconRxCount and BeaconLostCount. "; 758 } 759 leaf packet-multicast-rx-count { 760 type int8; 761 description 762 "The number of multicast packets received by 763 the Node."; 764 } 765 leaf packet-multicast-tx-count { 766 type int8; 767 description 768 "The number of multicast packets transmitted by 769 the Node."; 770 } 771 leaf packet-unicast-rx-count { 772 type int8; 773 description 774 "The number of multicast packets received by 775 the Node."; 776 } 777 leaf packet-unicast-tx-count { 778 type int8; 779 description 780 "The number of multicast packets transmitted by 781 the Node."; 782 } 783 leaf current-max-rate { 784 type int8; 785 description 786 "The current maximum PHY rate of transfer of 787 data in bytes-per-second."; 788 } 789 leaf overrun-count { 790 type int8; 791 description 792 "The number of packets dropped either at ingress or 793 egress, due to lack of buffer memory to retain all 794 packets on the ethernet network interface. The 795 OverrunCount attribute SHALL be reset to 0 upon a 796 reboot of the Node.."; 797 } 798 } 799 container events { 800 description 801 "Configuration of WIFI Network Diagnostic events."; 802 list event { 803 key "name"; 804 description 805 "The list of event sources configured on the 806 server."; 807 leaf name { 808 type string; 809 description 810 "The unique name of an event source."; 811 } 812 leaf disconnection { 813 type enumeration { 814 enum de-authenticated { 815 value 1; 816 } 817 enum dis-association { 818 value 2; 819 } 820 } 821 description 822 "A Node's Wi-Fi connection has been disconnected as a 823 result of de-authenticated or dis-association and 824 indicates the reason."; 825 } 826 leaf association-failure { 827 type enumeration { 828 enum unknown { 829 value 0; 830 } 831 enum association-failed { 832 value 1; 834 } 835 enum authentication-failed { 836 value 2; 837 } 838 enum ssid-not-found { 839 value 3; 840 } 841 } 842 description 843 "A Node has attempted to connect, or reconnect, to 844 a Wi-Fi access point, but is unable to successfully 845 associate or authenticate, after exhausting all 846 internal retries of its supplicant."; 847 } 848 leaf Connection-status { 849 type enumeration { 850 enum connected { 851 value 1; 852 } 853 enum notconnected { 854 value 2; 855 } 856 } 857 description 858 "A Node's connection status to a Wi-Fi network has 859 changed. Connected, in this context, SHALL mean that 860 a Node acting as a Wi-Fi station is successfully 861 associated to a Wi-Fi Access Point.."; 862 } 863 } 864 } 865 } 867 Appendix B. Adaptive Subscription and Notification Example 869 The examples within this document use the normative YANG module 870 "ietf-adaptive-subscription" as defined in Section 3 and the non- 871 normative example YANG module "example-wifi-network-diagnostic" as 872 defined in Appendix A.1. 874 This section shows some typical adaptive subscription and 875 notification message exchanges. 877 B.1. "edit-config" Example 879 The client configures adaptive subscription policy parameters on the 880 server. The adaptive subscription configuration parameters require 881 the server to support two update intervals (i.e., 5 seconds, 60 882 seconds) and scan all clients every 60 seconds in the sampling window 883 if the rssi value of client is greater than or equal to -65dB in the 884 sampling window; If the rssi value of client is less than -65dB, 885 switch to 5 seconds period value, and then scan all clients every 60 886 seconds. 888 890 891 892 893 894 896 899 901 ds:running 902 903 905 /wnd:example-wifi-network-diagnostic 906 907 909 910 911 /wnd:server[rssi < -65] 912 913 -65 914 5 915 916 917 918 /wnd:server[rssi ≥ -65] 919 920 -65 921 60 922 923 924 925 926 927 929 B.2. Create Adaptive Subscription Example 931 The subscriber sends an "establish-subscription" RPC with the 932 parameters listed in to request the creation of a adaptive 933 subscription. The adaptive subscription configuration parameters 934 require the server to scan all clients every 5 seconds if the rssi 935 value of client is less than -65dB; If the rssi value of client is 936 great than or equal to -65dB, switch to 60 seconds period value, and 937 then report all clients every 60 seconds or scan every 5 seconds, 938 collect 12 measurement values but report the last measurement value 939 or average value of 12 measurement values. (Section 2) 941 943 946 948 ds:running 949 950 952 /wnd:example-wifi-network-diagnostic 953 954 956 957 wnd:server[rssi < -65] 958 959 -65 960 5 961 962 963 wnd:server[rssi ≥ -65] 964 965 -65 966 60 967 968 969 970 972 In another example, the adaptive subscription configuration 973 parameters could also require the server to scan all clients every 5 974 seconds and report if the difference between maximum value of client 975 rssi and minimum value of client rssi is greater than 0.20 dB in the 976 sampling window; If the difference between maximum value of client 977 rssi and minimum value of client rssi is less than 0.20 dB, switch to 978 60 seconds period value and then scan all clients every 60 seconds 979 and report the last measurement value. If the difference between 980 maximum value of client rssi and minimum value of client rssi is 981 greater than or equal to 0.20 dB in two consecutive sampling windows, 982 then in the second sampling window, only report the measurement value 983 not reported by the previous sampling window. 985 987 990 992 ds:running 993 994 996 /wnd:example-wifi-network-dianostic 997 998 1000 1001 1002 wnd:server[max(rssi)-min(rssi) ≥ 20] 1003 1004 20 1005 5 1006 1007 1008 1009 wnd:server[max(rssi)-min(rssi) < 20] 1010 1011 20 1012 60 1013 1014 1015 1016 1018 B.3. "adaptive-update" notification example 1020 Upon the server switches to from the update interval 5 seconds to the 1021 new update interval 60 seconds, Before sending event records to 1022 receivers, the "adaptive-update" notification should be generated and 1023 sent to the receivers to inform the receivers that the update 1024 interval value is switched to the new value. 1026 1029 2016-11-21T13:51:00Z 1030 1032 0 1033 60 1034 1036 ds:running 1037 1038 1040 /ex:example-wifi-network-diagnostic 1041 1042 1043 1045 B.4. Changes between Revisions 1047 v05 -v06 1049 o Replace example-wifi-mac module with example-wifi-network- 1050 diagnostic using WIFI statistics specified in CHIP specification. 1052 o Update adaptive subscription Example to align with WIFI example 1053 module change. 1055 o Add one more reference to CHIP Specification. 1057 v04 -v05 1059 o Remove "modify-subscption" RPC usage. 1061 o Module update to fix the nits. 1063 o Update adaptive subscription Example. 1065 o Other Editorial changes. 1067 v03 - v04 1069 o Add missing subtrees and data nodes in the security section; 1071 o Change "adaptive-update" notification into "adaptive-period- 1072 update" notification; 1074 o Other Editorial changes. 1076 v02 - v03 1078 o Clarify the difference between low priority telemetry data 1079 dropping and collection rate switching in the introduction 1080 section; 1082 o Update the abstract and introduction section to focus on 1083 collection rate switching in the server without interaction with 1084 the remote client; 1086 o Format usage example and change ssid into rssi in the appendix; 1088 o Use boilerplate and reuse the terms in the terminology section. 1090 Authors' Addresses 1092 Qin Wu 1093 Huawei 1094 101 Software Avenue, Yuhua District 1095 Nanjing, Jiangsu 210012 1096 China 1098 Email: bill.wu@huawei.com 1100 Wei Song 1101 Huawei 1102 101 Software Avenue, Yuhua District 1103 Nanjing, Jiangsu 210012 1104 China 1106 Email: songwei80@huawei.com 1108 Peng Liu 1109 China Mobile 1110 32 Xuanwumen West St, Xicheng District 1111 Beijing 10053 1113 Email: liupengyjy@chinamobile.com 1114 Qiufang Ma 1115 Huawei 1116 101 Software Avenue, Yuhua District 1117 Nanjing, Jiangsu 210012 1118 China 1120 Email: maqiufang1@huawei.com 1122 Wei Wang 1123 China Telecom 1124 32 Xuanwumen West St, Xicheng District 1125 Beijing 102209 1127 Email: wangw36@chinatelecom.cn