idnits 2.17.1 draft-wang-netconf-bulk-subscribed-notifications-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 12 instances of too long lines in the document, the longest one being 24 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 208 has weird spacing: '...roup-id str...' == Line 215 has weird spacing: '...gorithm strin...' == Line 222 has weird spacing: '...gorithm stri...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (October 29, 2020) is 1273 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: 'I-D.ietf-netconf-notification-messages' is mentioned on line 114, but not defined == Unused Reference: 'RFC8126' is defined on line 551, but no explicit reference was found in the text == Unused Reference: 'RFC8407' is defined on line 570, 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 Huawei 4 Intended status: Standards Track P. Liu 5 Expires: May 2, 2021 Y. Fu 6 China Mobile 7 October 29, 2020 9 Bulk Subscription to YANG Event Notification 10 draft-wang-netconf-bulk-subscribed-notifications-03 12 Abstract 14 This document defines a YANG data model and associated mechanism that 15 allows subscriber applications to bulk subscribe to publishers' event 16 streams based on bundle group information such as bundle size and 17 bundle latency. This allows the publishers to report multiple 18 notifications in a single bundling message. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on May 2, 2021. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Model Overview . . . . . . . . . . . . . . . . . . . . . . . 4 57 3. Bulk Subscription YANG Module . . . . . . . . . . . . . . . . 5 58 4. Bulk Notification YANG Module . . . . . . . . . . . . . . . . 9 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 60 5.1. Updates to the IETF XML Registry . . . . . . . . . . . . 10 61 5.2. Updates to the YANG Module Names Registry . . . . . . . . 10 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 63 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 64 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 65 8.1. Normative References . . . . . . . . . . . . . . . . . . 12 66 8.2. Informative References . . . . . . . . . . . . . . . . . 13 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 69 1. Introduction 71 Subscription to YANG Notifications for Datastore Updates [RFC8641] 72 uses a "target" object in subscription protocol operation for 73 identifying the targeted source of information against which the 74 subscription is applied and supports multiple subscriptions on a 75 single transport session. Notification Message Headers and Bundles 76 [I-D.ietf-netconf-notification-messages] allows multiple 77 notifications bundled into one transportable message. However the 78 subscription protocol operation doesn't provide specific criteria to 79 classify subscriptions and therefore lacks the capability to 80 explicitly indicate which specific subscription associated with the 81 notification should be bundled together, e.g., subscription A and B 82 are bundled based on their relationship with a set of YANG data 83 models while subscription C and D are bundled based on "transport" 84 and "encoding" parameters,both bundled groups are transported in the 85 same transport session. A bundle size, bundle latency associated 86 with a set of subscriptions or YANG data models enables the ability 87 to perform encapsulation operation on a set of subscriptions with 88 common characteristics via a single transaction. The bundle size and 89 bundle latency provides a more optimal mechanism for notification 90 encapsulation which would otherwise require multiple atomic 91 transactions on a per subscription (i.e., one message per 92 notification) basis. Following are some of the use-cases where such 93 identifier can be used. 95 o For a dynamic subscription, the subscriber may have already had 96 priori knowledge about correlation relation between 97 subscriptions(e.g., aggregated subscribed data from multiple 98 sources). With this priori knowledge,it might send a bundle 99 subscription RPC request to indicate what specific notifications 100 associated with the subscription must be bundled together. 102 o For a configured subscription, self-explanation data Node tag 103 capability advertisment describing correlation between data nodes 104 in different YANG data model from different publisher can be used 105 to further establish correlation relation between subscriptions. 106 The correlation relation between subscriptions can be configured 107 back onto publisher, which help determine which notifications can 108 be bundles and which notifications are not. 110 o With the above bundle subscription indication from subscriber to 111 the publisher, multiple notifications corresponding to the request 112 protocol operation for those notifications are bundled into one 113 transportable message using Notification Message Headers and 114 Bundles defined in [I-D.ietf-netconf-notification-messages]. 116 This document defines a YANG data model and associated mechanism that 117 classify subscription based on various different filtering criteria 118 and allow subscriber applications to bulk subscribe/unsubscribe to 119 publisher's targeted object source based on bundle size and bundle 120 latency. This also allows the publishers to report multiple 121 notification in a single bundling message defined in [I-D.ietf- 122 netconf-notification-messages]. 124 1.1. Terminology 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 128 "OPTIONAL" in this document are to be interpreted as described in BCP 129 14 [RFC2119] [RFC8174] when, and only when, they appear in all 130 capitals, as shown here. 132 This document uses the following terms: 134 Event: An event is something that happens that may be of interest - 135 a configuration change, a fault, a change in status, crossing a 136 threshold, or an external input to the system, for example. 137 Often, this results in an asynchronous message, sometimes referred 138 to as a notification or event notification, being sent to 139 interested parties to notify them that this event has occurred 140 [RFC5277]. 142 Client: Defined in [RFC8342]. 144 Configuration: Defined in [RFC8342]. 146 Configured subscription: Defined in [RFC8639] 148 Configuration datastore: Defined in [RFC8342]. 150 Event record: A set of information detailing an event [RFC8639]. 152 Event stream: A continuous, chronologically ordered set of events 153 aggregated under some context [RFC8639]. 155 Notification message: Information intended for a receiver 156 indicating that one or more events have occurred [RFC8639]. 158 Publisher: An entity responsible for streaming notification messages 159 per the terms of a subscription [RFC8639]. 161 Receiver: A target to which a publisher pushes subscribed event 162 records. For dynamic subscriptions, the receiver and subscriber 163 are the same entity [RFC8639]. 165 Subscriber: A client able to request and negotiate a contract for 166 the generation and push of event records from a publisher. For 167 dynamic subscriptions, the receiver and subscriber are the same 168 entity [RFC8639]. 170 Subscription: A contract with a publisher, stipulating the 171 information that one or more receivers wish to have pushed from 172 the publisher without the need for further solicitation [RFC8639]. 174 2. Model Overview 176 The YANG data model for the Bulk Subscriptions to YANG Event 177 Notification has been split into two modules: 179 o The ietf-bulk-subscription.yang module defines a list for 180 classifying different subscriptions corresponding to target object 181 into groups. Each group is associated with a bundle size, bundle 182 latency and a set of subscriptions. A set of subscription is 183 identified by a "group-id" string. This string is used both as an 184 index within the bulk subscription module. It associate a 185 specific bundle group with a group of subscriptions and a set of 186 YANG data models, as shown in the subscription augmentation. In 187 addition,ietf-subscribed-notifications.yang module defined in 188 [RFC8639] is augmented with "max-bundle-size","max-bundle-latency" 189 and "compression-algorithm" to enhance QoS feature and provide 190 additional subscription bundle classification criteria. 192 o The ietf-bulk-notification.yang module augment the YANG structure 193 of ietf-notification-messages.yang [draft-ietf-netconf- 194 notification-messages], a "group-id" is added to the "message- 195 header" of the ietf-notification-messages.yang to indicate the 196 group to which a set of notifications belongs. In addition, 197 "compression-algorithm" parameter is augmented to "message-header" 198 to inform the corresponding recievers of compression algorithm to 199 be used by the publisher. 201 The following tree diagrams [RFC8340] provide an overview of the data 202 model for "ietf-bulk-subscription.yang" module and the "ietf-bulk- 203 notification.yang" module. 205 module: ietf-bulk-subscription 206 +--rw bundle-groups 207 +--rw bundle-group* [group-id] 208 +--rw group-id string 209 +--rw subscription-id* leafref 210 +--rw yang-module* yang:yang-identifier 212 augment /sn:subscriptions/sn:subscription: 213 +--rw max-bundle-size uint32 214 +--rw max-bundle-latency uint32 215 +--rw compression-algorithm string 217 +---x bundle-subscription 218 +---input 219 +---w group-id? -> /bundle-groups/bundle-group/group-id 220 +--rw max-bundle-size uint32 221 +---w max-bundle-latency uint32 222 +---w compression-algorithm string 223 +---w subscription-id* subscription-id 224 +---w masked-subscription-id* subscription-id 226 module: ietf-bulk-notification 227 augment-structure /nm:message/nm:message-header: 228 +--rw group-id? string 229 +--rw compression-algorithm string 231 3. Bulk Subscription YANG Module 233 file "ietf-bulk-subscription@2019-09-23.yang" 234 module ietf-bulk-subscription { 235 yang-version 1.1; 236 namespace "urn:ietf:params:xml:ns:yang:ietf-bulk-subscription"; 237 prefix bs; 239 import ietf-subscribed-notifications { 240 prefix sn; 241 } 242 import ietf-yang-types { 243 prefix yang; 244 } 246 organization 247 "IETF NETCONF (Network Configuration) Working Group"; 248 contact 249 ""; 250 description 251 "NETCONF Protocol Data Types and Protocol Operations. 253 Copyright (c) 2011 IETF Trust and the persons identified as 254 the document authors. All rights reserved. 256 Redistribution and use in source and binary forms, with or 257 without modification, is permitted pursuant to, and subject 258 to the license terms contained in, the Simplified BSD License 259 set forth in Section 4.c of the IETF Trust's Legal Provisions 260 Relating to IETF Documents 261 (http://trustee.ietf.org/license-info). 263 This version of this YANG module is part of RFC 6241; see 264 the RFC itself for full legal notices."; 266 revision 2019-09-23 { 267 description 268 "Initial revision"; 269 reference "RFC XXXX: Bulk Subscription to YANG Event Notification"; 270 } 271 identity encode-cbor { 272 base sn:encoding; 273 description 274 "Encode data using cbor."; 275 } 276 identity encode-gpb { 277 base sn:encoding; 278 description 279 "Encode data using gpb."; 280 } 281 container bundle-groups { 282 list bundle-group { 283 key "group-id"; 284 leaf group-id { 285 type string; 286 description 287 "This group ID is used as an index within the bulk subscription module 288 , which indicates subscription classification criteria."; 289 } 290 leaf-list subscription-id { 291 type leafref { 292 path "/sn:subscriptions/sn:subscription/sn:id"; 293 } 294 description 295 "subscription-id"; 296 } 297 leaf-list yang-module { 298 type yang:yang-identifier; 299 description 300 "Name of the YANG module list supported by the publisher."; 301 } 302 description 303 "List for group that classify different subscriptions into groups."; 304 } 305 leaf compression-algorithm { 306 type string; 307 description 308 "The technology with which an originator compress bytestream 309 contents."; 310 } 311 description 312 "Container for subscription group."; 313 } 314 augment "/sn:subscriptions/sn:subscription" { 315 leaf max-bundle-size { 316 type uint32; 317 default 400; 318 description 319 "The maximum number of data objects to be included by the publisher in a 320 single message to recievers."; 321 } 322 leaf max-bundle-latency { 323 type uint32; 324 units centiseconds; 325 default 400; 326 description 327 "The maximum latency before a specific YANG Notifications generated 328 must egress a publisher."; 329 } 330 leaf compression-algorithm { 331 type string; 332 description 333 "The technology with which an originator compress bytestream 334 contents."; 335 } 337 description 338 "Augment the subscribed-notifications module with transport specific information."; 339 } 341 rpc bundle-subscription { 342 description 343 "Bundle subscription. This paremeter indicates what subscription must be bundled together."; 344 input { 345 leaf group-id { 346 type string; 347 description 348 "This group ID is used as an index within the bulk subscription module"; 349 } 350 leaf-list subscription-id { 351 type uint32; 352 description 353 "Subscription-id paremeter indicates what subscription must be bundled together."; 354 } 355 leaf-list mask-subscription-id { 356 type uint32; 357 description 358 "Mask subscription-id paremeter indicates what subscription must 359 not be bundled together."; 360 } 361 leaf max-bundle-size { 362 type uint32; 363 default 400; 364 description 365 "The maximum number of data objects to be included by the publisher in a single 366 message to recievers."; 367 } 368 leaf max-bundle-latency { 369 type uint32; 370 units centiseconds; 371 default 400; 372 description 373 "The maximum latency before a specific YANG Notifications generated 374 must egress a publisher."; 375 } 376 leaf compression-algorithm { 377 type string; 378 description 379 "The technology with which an originator compress bytestream 380 contents."; 381 } 382 } 383 } 384 } 385 386 4. Bulk Notification YANG Module 388 file "ietf-bulk-notification@2019-09-23.yang" 389 module ietf-bulk-notification { 390 yang-version 1.1; 391 namespace "urn:ietf:params:xml:ns:yang:ietf-bulk-notification"; 392 prefix bn; 394 import ietf-yang-structure-ext { 395 prefix sx; 396 } 397 import ietf-notification-messages { 398 prefix nm; 399 } 401 organization 402 "IETF NETCONF (Network Configuration) Working Group"; 403 contact 404 ""; 405 description 406 "NETCONF Protocol Data Types and Protocol Operations. 408 Copyright (c) 2011 IETF Trust and the persons identified as 409 the document authors. All rights reserved. 411 Redistribution and use in source and binary forms, with or 412 without modification, is permitted pursuant to, and subject 413 to the license terms contained in, the Simplified BSD License 414 set forth in Section 4.c of the IETF Trust's Legal Provisions 415 Relating to IETF Documents 416 (http://trustee.ietf.org/license-info). 418 This version of this YANG module is part of RFC 6241; see 419 the RFC itself for full legal notices."; 421 revision 2019-09-23 { 422 description 423 "Initial revision"; 424 reference 425 "RFC XXXX: Bulk Subscription to YANG Event Notification"; 426 } 428 sx:augment-structure "/nm:message/nm:message-header" { 429 leaf group-id { 430 type string; 431 description 432 "To identify the group to which a set of notifications belongs."; 433 } 434 leaf compression-algorithm { 435 type string; 436 description 437 "The technology with which an originator compress bytestream 438 contents."; 439 } 440 description 441 "Group related informations are added to the 'message-header' of 442 the ietf-notification-messages to identify the group to which a 443 set of notifications belongs and compression algorithms used by 444 the publisher."; 445 } 446 } 447 449 5. IANA Considerations 451 5.1. Updates to the IETF XML Registry 453 This document registers two URIs in the IETF XML registry [RFC3688]. 454 Following the format in [RFC3688], the following registrations are 455 requested to be made: 457 --------------------------------------------------------------------- 458 URI: urn:ietf:params:xml:ns:yang:ietf-bulk-subscription 459 Registrant Contact: The IESG. 460 XML: N/A, the requested URI is an XML namespace. 462 URI: urn:ietf:params:xml:ns:yang:ietf-bulk-notification 463 Registrant Contact: The IESG. 464 XML: N/A, the requested URI is an XML namespace. 465 --------------------------------------------------------------------- 467 5.2. Updates to the YANG Module Names Registry 469 This document registers two YANG modules in the YANG Module Names 470 registry [RFC7950]. . Following the format in [RFC6020], the 471 following registration has been made: 473 --------------------------------------------------------------------- 474 Name: ietf-bulk-subscription 475 Namespace: urn:ietf:params:xml:ns:yang:ietf-bulk-subscription 476 Prefix: trig 477 Reference: RFC xxxx 479 Name: ietf-bulk-notification 480 Namespace: urn:ietf:params:xml:ns:yang:ietf-bulk-notification 481 Prefix: evt 482 Reference: RFC xxxx 483 --------------------------------------------------------------------- 485 6. Security Considerations 487 The YANG module specified in this document defines a schema for data 488 that is designed to be accessed via network management protocols such 489 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 490 is the secure transport layer, and the mandatory-to-implement secure 491 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 492 is HTTPS, and the mandatory-to-implement secure transport is TLS 493 [RFC8446]. 495 The NETCONF Configuration Access Control Model (NACM) [RFC8341] 496 provides the means to restrict access for particular NETCONF or 497 RESTCONF users to a preconfigured subset of all available NETCONF or 498 RESTCONF protocol operations and content. 500 There are a number of data nodes defined in this YANG module that are 501 writable/creatable/deletable (i.e., config true, which is the 502 default). These data nodes may be considered sensitive in some 503 network environments. Write operations (e.g., edit-config) to these 504 data nodes without proper protection can have a negative effect on 505 network operations. These are the subtrees and data nodes and their 506 sensitivity/vulnerability: 508 o /bundle-groups/bundle-group/group-id 510 o /sn:subscriptions/sn:subscription/bs:max-bundle-latency 512 o /sn:subscriptions/sn:subscription/bs:max-bundle-size 514 o /bundle-subscription/input/group-id 516 7. Acknowledgements 518 Thanks to Eric Voit, Hui Cai,Zitao Wang for reviewing this draft and 519 providing important input to this document. 521 8. References 523 8.1. Normative References 525 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 526 Requirement Levels", BCP 14, RFC 2119, 527 DOI 10.17487/RFC2119, March 1997, 528 . 530 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 531 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 532 . 534 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 535 and A. Bierman, Ed., "Network Configuration Protocol 536 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 537 . 539 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 540 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 541 . 543 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 544 RFC 7950, DOI 10.17487/RFC7950, August 2016, 545 . 547 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 548 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 549 . 551 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 552 Writing an IANA Considerations Section in RFCs", BCP 26, 553 RFC 8126, DOI 10.17487/RFC8126, June 2017, 554 . 556 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 557 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 558 May 2017, . 560 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 561 Access Control Model", STD 91, RFC 8341, 562 DOI 10.17487/RFC8341, March 2018, 563 . 565 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 566 and R. Wilton, "Network Management Datastore Architecture 567 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 568 . 570 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 571 Documents Containing YANG Data Models", BCP 216, RFC 8407, 572 DOI 10.17487/RFC8407, October 2018, 573 . 575 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 576 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 577 . 579 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 580 E., and A. Tripathy, "Subscription to YANG Notifications", 581 RFC 8639, DOI 10.17487/RFC8639, September 2019, 582 . 584 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 585 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 586 September 2019, . 588 8.2. Informative References 590 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 591 DOI 10.17487/RFC3688, January 2004, 592 . 594 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 595 the Network Configuration Protocol (NETCONF)", RFC 6020, 596 DOI 10.17487/RFC6020, October 2010, 597 . 599 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 600 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 601 . 603 Authors' Addresses 605 Qin Wu 606 Huawei 607 101 Software Avenue, Yuhua District 608 Nanjing, Jiangsu 210012 609 China 611 Email: bill.wu@huawei.com 612 Peng Liu 613 China Mobile 614 32 Xuanwumen West St, Xicheng District 615 Beijing 10053 617 Email: liupengyjy@chinamobile.com 619 Yuexia Fu 620 China Mobile 621 32 Xuanwumen West St, Xicheng District 622 Beijing 10053 624 Email: yuexiafu@chinamobile.com