idnits 2.17.1 draft-ietf-netconf-notification-capabilities-16.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 16, 2021) is 1105 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-12 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF B. Lengyel 3 Internet-Draft Ericsson 4 Intended status: Standards Track A. Clemm 5 Expires: October 18, 2021 Futurewei 6 B. Claise 7 Huawei 8 April 16, 2021 10 YANG Modules describing Capabilities for Systems and Datastore Update 11 Notifications 12 draft-ietf-netconf-notification-capabilities-16 14 Abstract 16 This document defines two YANG modules,"ietf-system-capabilities" and 17 "ietf-notification-capabilities". 19 The module "ietf-system-capabilities" provides a placeholder 20 structure that can be used to discover YANG related system 21 capabilities for servers. The module can be used to report 22 capability information from the server at run-time or implementation- 23 time, per the YANG Instance Data File Format. 25 The module "ietf-notification-capabilities" augments "ietf-system- 26 capabilities" to specify capabilities related to Subscription to YANG 27 Notifications for Datastore Updates. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on October 18, 2021. 46 Copyright Notice 48 Copyright (c) 2021 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 64 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 65 2. Providing System Capability Information . . . . . . . . . . . 4 66 3. Providing YANG-Push Notification Capabilities Information . . 5 67 4. System Capabilities Model . . . . . . . . . . . . . . . . . . 6 68 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7 69 4.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 7 70 5. Notification Capabilities Model . . . . . . . . . . . . . . . 11 71 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 11 72 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 11 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 17 74 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 75 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 18 76 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 18 77 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 78 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 79 9.1. Normative References . . . . . . . . . . . . . . . . . . 19 80 9.2. Informative References . . . . . . . . . . . . . . . . . 20 81 Appendix A. Instance data example #1 . . . . . . . . . . . . . . 20 82 Appendix B. Instance data example #2 . . . . . . . . . . . . . . 22 83 Appendix C. Changes between revisions . . . . . . . . . . . . . 24 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 86 1. Introduction 88 Servers and/or a publishers often have capabilities, values 89 describing operational behavior, that need to be conveyed to clients, 90 which is enabled by the YANG modules described in this document. 92 There is a need to publish this capability information as it is part 93 of the contract between the server and client. Examples include 94 maximum size of data that can be stored or transferred, information 95 about counters (whether a node supports "on-change" telemetry), etc. 96 Such capabilities are often dependent on a vendor's implementation or 97 the available resources at deployment. Many such capabilities are 98 specific to either the complete system, individual YANG datastores 99 [RFC8342] or specific parts of the YANG schema, or even individual 100 data nodes. It is a goal of this document to provide a common way of 101 representing such capabilities in a format that is: 103 o vendor independent 105 o machine readable 107 o available in identical format both at implementation-time and run- 108 time 110 Implementation-time information is needed by Network Management 111 System (NMS) implementers. A NMS implementation that wants to 112 support notifications, needs the information about a system's 113 capability to send "on-change" notifications. If the information is 114 not documented in a way available to the NMS designer, but only as 115 instance data from the network node once it is deployed, the NMS 116 implementation will be delayed, because it has to wait for the 117 network node to be ready. In addition, the assumption that all NMS 118 implementers will have a correctly configured network node available 119 to retrieve data from is an expensive proposition and may not always 120 hold. (An NMS may need to be able to handle many dozens of network 121 node types.) Often a fully functional NMS is a requirement for 122 introducing a new network node type into a network, so delaying NMS 123 readiness effectively also delays the time at which a new network 124 node type can be introduced into the network. 126 Implementation-time information is needed by system integrators. 127 When introducing a network node type into their network, operators 128 often need to integrate the node type into their own management 129 system. The NMS may have management functions that depend on "on- 130 change" notifications. The network operator needs to plan his 131 management practices and NMS implementation before he even decides to 132 buy the specific network node type. Moreover the decision to buy the 133 node type sometimes depends on these management possibilities. 135 Run-time information is needed: 137 o for any "purely model driven" application, e.g., a NETCONF- 138 browser. Such applications depend on reading models and 139 capabilities at run-time to support all the publisher's available 140 functionality. 142 o in case the capability might change during run-time e.g., due to 143 licensing, HW constraints etc. 145 o to check that capability information provided earlier, at 146 implementation-time is what the publisher has implemented. 148 1.1. Terminology 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 152 "OPTIONAL" in this document are to be interpreted as described in BCP 153 14 [RFC2119] [RFC8174] when, and only when, they appear in all 154 capitals, as shown here. 156 The terms "YANG-Push", "on-change subscription" and "periodic 157 subscription" are used as defined in [RFC8641]. 159 The terms "subscriber", "publisher" and "receiver" are used as 160 defined in [RFC8639]. 162 The term "server" is used as defined in [RFC8342]. 164 The terms "YANG instance data file format", "instance data", and 165 "instance data set" are used as defined in 166 [I-D.ietf-netmod-yang-instance-file-format]. 168 In addition, this document defines the following terms: 170 "Implementation-time information": Information about the server's 171 behavior that is made available during the implementation of the 172 server, available from a source other then a running server. 174 "Run-time information": Information about the server's behavior that 175 is available from the running server via management protocols such as 176 NETCONF [RFC6241] or RESTCONF [RFC8040]. 178 2. Providing System Capability Information 180 Capability information is represented by instance-data based on one 181 or more "capability defining YANG modules". This allows a user to 182 discover capabilities both at implementation-time and run-time. 184 o For the implementation-time use-case: Capabilities SHOULD be 185 provided by the implementer as YANG instance data files complying 186 to [I-D.ietf-netmod-yang-instance-file-format]. The file MUST be 187 available already at implementation-time retrievable in a way that 188 does not depend on a live network node. E.g., download from 189 product website. 191 o For the run-time use-case: Capabilities SHOULD be available via 192 NETCONF [RFC6241] or RESTCONF [RFC8040] from the live server 193 (implementing the publisher) during run-time. Implementations 194 that support changing these capabilities at run-time SHOULD 195 support "on-change" notifications about the system-capabilities 196 container. 198 The module "ietf-system-capabilities" provides a placeholder 199 structure to be used to specify any YANG related system capability. 201 The module "ietf-notification-capabilities" is defined to allow a 202 publisher to specify capabilities related to "Subscription to YANG 203 Notifications for Datastore Updates" [RFC8641], also known as YANG- 204 Push, augmenting "ietf-system-capabilities". 206 The YANG data models in this document conform to the Network 207 Management Datastore Architecture (NMDA) defined in [RFC8342]. 209 3. Providing YANG-Push Notification Capabilities Information 211 A specific case is the need to specify capabilities is the YANG-Push 212 functionality. As defined in [RFC8641] a publisher may allow 213 subscribers to subscribe to updates from a datastore and subsequently 214 push such update notifications to the receiver. Notifications may be 215 sent periodically or "on-change" (more or less immediately after each 216 change). 218 A publisher supporting YANG-Push has a number of capabilities defined 219 in [RFC8641] that are often determined during the implementation of 220 the publisher. These include: 222 o Supported (reporting) periods for "periodic" subscriptions 224 o Maximum number of objects that can be sent in an update 226 o The set of datastores or data nodes for which "periodic" 227 notification is supported 229 Additional capabilities if the optional "on-change" feature is 230 supported include: 232 o Supported dampening periods for "on-change" subscriptions 234 o The set of datastores or data nodes for which "on-change" 235 notification is supported 237 Publishers might have some capabilities (or limitations) to document. 238 For example, how many update notifications and how many datastore 239 node updates they can send out in a certain time-period. Other 240 publishers might not support "periodic" subscriptions to all 241 datastores. In some cases, a publisher supporting "on-change" 242 notifications will not be able to push updates for some object types 243 "on-change". Reasons for this might be that the value of the 244 datastore node changes frequently (e.g., in-octets counter), that 245 small object changes are frequent and irrelevant to the receiver 246 (e.g., a temperature gauge changing 0.1 degrees within a 247 predetermined and acceptable range), or that the implementation is 248 not capable of on-change notification for a particular object. In 249 all those cases, it will be important for subscriber applications to 250 have a way to identify which objects "on-change" notifications are 251 supported and for which ones not. 253 Faced with the reality that support for "on-change" notification does 254 not mean that such notifications will be sent for any specific data 255 node, subscriber/management applications can not rely on the "on- 256 change" functionality unless the subscriber has some means to 257 identify which objects "on-change" notifications are supported. YANG 258 models are meant to be used as an interface contract. Without 259 identification of the data nodes actually supporting "on-change", 260 this contract would be incomplete. 262 Clients of a server (and subscribers to a publisher, as subscribers 263 are also clients) need a method to gather capability information. 265 4. System Capabilities Model 267 The module "ietf-system-capabilities" is defined to provide a 268 structure that can be used to discover (as read-only operational 269 state) any YANG related system capability. 271 This module itself does not contain any capabilities; it provides 272 augmentation points for capabilities to be defined in subsequent YANG 273 modules. It SHOULD be used by other modules to augment-in specific 274 capability information. Every set of such capabilities SHOULD be 275 wrapped in a container under the augment statement to cleanly 276 separate different groups of capabilities. These "wrapper 277 containers" SHALL be augmented in at /sysc:system-capabilities and 278 /sysc:system-capabilities/sysc:datastore-capabilities/sysc:per-node- 279 capabilities. 281 Capability values can be specified on system level, datastore level 282 (by selecting all nodes in the datastore) or for specific data nodes 283 of a specific datastore (and their contained sub-trees). Capability 284 values specified for a specific datastore or node-set override values 285 specified on the system level. 287 Note: The solution is usable for both NMDA and non-NMDA systems. For 288 non-NMDA servers "config false" data is considered as if it was part 289 of the running datastore. 291 4.1. Tree Diagram 293 The following tree diagram [RFC8340] provides an overview of the data 294 model. 296 module: ietf-system-capabilities 297 +--ro system-capabilities 298 +--ro datastore-capabilities* [datastore] 299 +--ro datastore -> /yanglib:yang-library/datastore/name 300 +--ro per-node-capabilities* [] 301 +--ro (node-selection)? 302 +--:(node-selector) 303 +--ro node-selector? nacm:node-instance-identifier 305 4.2. YANG Module 307 This YANG module imports typedefs from [RFC8341] and a reference path 308 from [RFC8525]. 310 file "ietf-system-capabilities@2021-04-02.yang" 312 module ietf-system-capabilities { 313 yang-version 1.1; 314 namespace "urn:ietf:params:xml:ns:yang:ietf-system-capabilities"; 315 prefix sysc; 317 import ietf-netconf-acm { 318 prefix nacm; 319 reference 320 "RFC 8341: Network Configuration Access Control Model"; 321 } 322 import ietf-yang-library { 323 prefix yanglib; 324 description 325 "This module requires ietf-yang-library to be implemented. 326 Revision 2019-01-04 or a revision derived from it 327 is REQUIRED."; 328 reference 329 "RFC8525: YANG Library"; 330 } 332 organization 333 "IETF NETCONF (Network Configuration) Working Group"; 334 contact 335 "WG Web: 336 WG List: 338 Editor: Balazs Lengyel 339 "; 340 description 341 "This module specifies a structure to specify system 342 capabilities for a server or a publisher. System capabilities 343 may include capabilities of a NETCONF or RESTCONF server or a 344 notification publisher. 346 This module does not contain any specific capabilities, it only 347 provides a structure where containers containing the actual 348 capabilities are augmented in. 350 Capability values can be specified on system level, 351 datastore level (by selecting all nodes in the datastore) or 352 for specific data nodes of a specific datastore (and their 353 contained sub-trees). 354 Capability values specified for a specific datastore or 355 node-set override values specified on the system/publisher level. 357 To find a capability value for a specific data node in a 358 specific datastore the user SHALL: 360 1) search for a datastore-capabilities list entry for 361 the specific datastore. 363 2) If the datastore entry is found within that entry, process all 364 per-node-capabilities entries in the order they appear in the list. 365 The first entry that specifies the specific capability and has a 366 node-selector selecting the specific data node defines the 367 capability value. 369 3) If the capability value is not found above and the specific 370 capability is specified under the system-capabilities container 371 (outside the datastore-capabilities list), this value shall be 372 used. 374 4) If no values are found in the previous steps, the 375 system/publisher is not capable of providing a value. Possible 376 reasons are: it is unknown, the capability is changing for some 377 reason, there is no specified limit, etc. In this case the 378 system's behavior is unspecified. 380 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 381 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 382 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 383 are to be interpreted as described in BCP 14 (RFC 2119) 384 (RFC 8174) when, and only when, they appear in all 385 capitals, as shown here. 387 Copyright (c) 2021 IETF Trust and the persons identified as 388 authors of the code. All rights reserved. 390 Redistribution and use in source and binary forms, with or 391 without modification, is permitted pursuant to, and subject to 392 the license terms contained in, the Simplified BSD License set 393 forth in Section 4.c of the IETF Trust's Legal Provisions 394 Relating to IETF Documents 395 (https://trustee.ietf.org/license-info). 397 This version of this YANG module is part of RFC XXXX 398 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 399 for full legal notices."; 401 // RFC Ed.: replace XXXX with actual RFC number and remove this 402 // note. 404 revision 2021-04-02 { 405 description 406 "Initial version 407 NOTE TO RFC EDITOR: 408 (1)Please replace the above revision date to 409 the date of RFC publication when published. 410 (2) Please replace the date in the file name 411 (ietf-system-capabilities@2021-04-02.yang) 412 to the date of RFC publication. 413 (3) Please replace the following reference 414 with RFC number when published 415 (i.e. RFC xxxx)."; 416 reference 417 "RFC XXXX: YANG Modules describing Capabilities for Systems 418 and Datastore Update Notifications"; 419 } 421 container system-capabilities { 422 config false; 423 description 424 "System capabilities. 425 Capability values specified here at the system level 426 are valid for all datastores and are used when the 427 capability is not specified on the datastore level 428 or for specific data nodes."; 429 // augmentation point for system level capabilities 430 list datastore-capabilities { 431 key "datastore"; 432 description 433 "Capabilities values per datastore. 435 For non-NMDA servers/publishers 'config false' data is 436 considered as if it was part of the running datastore."; 437 leaf datastore { 438 type leafref { 439 path 440 "/yanglib:yang-library/yanglib:datastore/yanglib:name"; 441 } 442 description 443 "The datastore for which capabilities are defined. 444 Only one specific datastore can be specified 445 e.g., ds:conventional is not allowed."; 446 } 447 list per-node-capabilities { 448 description 449 "Each list entry specifies capabilities for the selected 450 data nodes. The same capabilities apply for the data nodes 451 in the subtree below the selected nodes. 453 The system SHALL order the entries according to their 454 precedence. The order of the entries MUST NOT change unless 455 the underlying capabilities also change."; 456 choice node-selection { 457 description 458 "A method to select all or some nodes within a datastore."; 459 leaf node-selector { 460 type nacm:node-instance-identifier; 461 description 462 "Selects the data nodes for which capabilities are 463 specified. The special value '/' denotes all data nodes 464 in the datastore, consistent with the path leaf node on 465 page 41 [RFC8341]."; 466 reference 467 "RFC 8341: Network Configuration Access Control Model"; 468 } 469 } 470 // augmentation point for datastore or data node level 471 // capabilities 472 } 473 } 474 } 475 } 477 479 5. Notification Capabilities Model 481 The YANG module "ietf-notification-capabilities" provides YANG-Push 482 related capability information. 484 5.1. Tree Diagram 486 The following tree diagram [RFC8340] provides an overview of the data 487 model. 489 module: ietf-notification-capabilities 490 augment /sysc:system-capabilities: 491 +--ro subscription-capabilities 492 +--ro max-nodes-per-update? uint32 493 +--ro periodic-notifications-supported? notification-support 494 +--ro (update-period)? 495 | +--:(minimum-update-period) 496 | | +--ro minimum-update-period? uint32 497 | +--:(supported-update-period) 498 | +--ro supported-update-period* uint32 499 +--ro on-change-supported? notification-support 500 | {yp:on-change}? 501 +--ro minimum-dampening-period? uint32 502 | {yp:on-change}? 503 +--ro supported-excluded-change-type* union 504 {yp:on-change}? 505 augment /sysc:system-capabilities/sysc:datastore-capabilities 506 /sysc:per-node-capabilities: 507 +--ro subscription-capabilities 508 +--ro max-nodes-per-update? uint32 509 +--ro periodic-notifications-supported? notification-support 510 +--ro (update-period)? 511 | +--:(minimum-update-period) 512 | | +--ro minimum-update-period? uint32 513 | +--:(supported-update-period) 514 | +--ro supported-update-period* uint32 515 +--ro on-change-supported? notification-support 516 | {yp:on-change}? 517 +--ro minimum-dampening-period? uint32 518 | {yp:on-change}? 519 +--ro supported-excluded-change-type* union 520 {yp:on-change}? 522 5.2. YANG Module 524 This YANG module imports a feature and typedefs from [RFC8641] and 525 also imports the "ietf-system-capabilities" specified in this 526 document. 528 file "ietf-notification-capabilities@2021-04-02.yang" 530 module ietf-notification-capabilities { 531 yang-version 1.1; 532 namespace 533 "urn:ietf:params:xml:ns:yang:ietf-notification-capabilities"; 534 prefix notc; 536 import ietf-yang-push { 537 prefix yp; 538 description 539 "This module requires ietf-yang-push to be implemented."; 540 reference 541 "RFC 8641: Subscription to YANG Notifications for Datastore 542 Updates"; 543 } 544 import ietf-system-capabilities { 545 prefix sysc; 546 description 547 "This module requires ietf-system-capabilities to be 548 implemented."; 549 reference 550 "RFC XXXX: YANG Modules describing Capabilities for Systems 551 and Datastore Update Notifications"; 552 } 554 // RFC Ed.: replace the above XXXX with actual RFC number 555 // and remove this note. 557 organization 558 "IETF NETCONF (Network Configuration) Working Group"; 559 contact 560 "WG Web: 561 WG List: 563 Editor: Balazs Lengyel 564 "; 565 description 566 "This module specifies YANG-Push [RFC 8641] related publisher 567 capabilities. 569 The module contains: 571 - specification of which data nodes support 'on-change' or 572 'periodic' notifications. 574 - capabilities related to the throughput of notification data 575 the publisher can support. (Note that for a specific 576 subscription the publisher MAY still allow only longer periods 577 or smaller updates depending on e.g., actual load conditions.) 579 Capability values can be specified on system/publisher level, 580 datastore level or for specific data nodes of a specific 581 datastore (and their contained sub-trees), as defined in the 582 ietf-system-capabilities module. 584 If different data nodes covered by a single subscription 585 have different values for a specific capability, then using 586 values that are only acceptable for some of these data nodes, 587 but not for others, may result in the rejection of the 588 subscription. 590 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 591 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 592 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 593 are to be interpreted as described in BCP 14 (RFC 2119) 594 (RFC 8174) when, and only when, they appear in all 595 capitals, as shown here. 597 Copyright (c) 2021 IETF Trust and the persons identified as 598 authors of the code. All rights reserved. 600 Redistribution and use in source and binary forms, with or 601 without modification, is permitted pursuant to, and subject to 602 the license terms contained in, the Simplified BSD License set 603 forth in Section 4.c of the IETF Trust's Legal Provisions 604 Relating to IETF Documents 605 (https://trustee.ietf.org/license-info). 607 This version of this YANG module is part of RFC XXXX 608 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 609 for full legal notices."; 611 // RFC Ed.: replace XXXX with actual RFC number and remove this 612 // note. 614 revision 2021-04-02 { 615 description 616 "Initial version"; 617 reference 618 "RFC XXXX: YANG Modules describing Capabilities for Systems 619 and Datastore Update Notifications"; 620 } 622 // RFC Ed.: replace XXXX with actual RFC number and remove this 623 // note. 625 grouping subscription-capabilities { 626 description 627 "Capabilities related to YANG-Push subscriptions 628 and notifications"; 629 container subscription-capabilities { 630 description 631 "Capabilities related to YANG-Push subscriptions 632 and notifications"; 633 typedef notification-support { 634 type bits { 635 bit config-changes { 636 description 637 "The publisher is capable of sending 638 notifications for 'config false' nodes for the 639 relevant scope and subscription type."; 640 } 641 bit state-changes { 642 description 643 "The publisher is capable of sending 644 notifications for 'config false' nodes for the relevant 645 scope and subscription type."; 646 } 647 } 648 description 649 "Type for defining whether 'on-change' or 650 'periodic' notifications are supported 'config false' 651 data nodes, 'config true' date nodes, no data nodes, 652 or all data nodes. 654 If the bit config-changes or state-changes is set 655 for a datastore, or a set of nodes that does not contain 656 nodes with the indicated config value, this has no 657 effect, as if no support was declared. E.g. indicating 658 support for state-changes for a candidate datastore has 659 no effect."; 660 } 662 leaf max-nodes-per-update { 663 type uint32 { 664 range "1..max"; 665 } 666 description 667 "Maximum number of data nodes that can be sent 668 in an update. The publisher MAY support more data nodes, 669 but SHOULD support at least this number. 671 May be used to avoid the 'update-too-big' error 672 during subscription."; 674 reference 675 "RFC 8641: Subscription to YANG Notifications for Datastore 676 Updates, the 'update-too-big' error/identity"; 677 } 678 leaf periodic-notifications-supported { 679 type notification-support; 680 description 681 "Specifies whether the publisher is capable of 682 sending 'periodic' notifications for the selected 683 data nodes including any subtrees that may exist 684 below them."; 685 reference 686 "RFC 8641: Subscription to YANG Notifications for Datastore 687 Updates, 'periodic' subscription concept"; 688 } 689 choice update-period { 690 description 691 "Supported update period value or values for 692 'periodic' subscriptions."; 693 leaf minimum-update-period { 694 type uint32; 695 units "centiseconds"; 696 description 697 "Indicates the minimal update period that is 698 supported for a 'periodic' subscription. 700 A subscription request to the selected data 701 nodes with a smaller period than what this leaf 702 specifies will result in a 'period-unsupported' error."; 703 reference 704 "RFC 8641: Subscription to YANG Notifications for Datastore 705 Updates, the period leaf in the ietf-yang-push YANG 706 module"; 707 } 708 leaf-list supported-update-period { 709 type uint32; 710 units "centiseconds"; 711 description 712 "Supported update period values for a 'periodic' 713 subscription. 715 A subscription request to the selected data nodes with a 716 period not included in the leaf-list will result in a 717 'period-unsupported' error."; 718 reference 719 "RFC 8641: Subscription to YANG Notifications for Datastore 720 Updates, the period leaf in the ietf-yang-push YANG 721 module"; 723 } 724 } 725 leaf on-change-supported { 726 if-feature "yp:on-change"; 727 type notification-support; 728 description 729 "Specifies whether the publisher is capable of 730 sending 'on-change' notifications for the selected 731 data nodes and the subtree below them."; 732 reference 733 "RFC 8641: Subscription to YANG Notifications for Datastore 734 Updates, on-change concept"; 735 } 736 leaf minimum-dampening-period { 737 if-feature "yp:on-change"; 738 type uint32; 739 units "centiseconds"; 740 description 741 "The minimum dampening-period supported for 'on-change' 742 subscriptions for the selected data nodes. 744 If this value is present and greater than zero, 745 that implies dampening is mandatory."; 746 reference 747 "RFC 8641: Subscription to YANG Notifications for 748 Datastore Updates, the dampening-period leaf in the 749 ietf-yang-push YANG module"; 750 } 751 leaf-list supported-excluded-change-type { 752 if-feature "yp:on-change"; 753 type union { 754 type enumeration { 755 enum none { 756 value -2; 757 description 758 "None of the change types can be excluded."; 759 } 760 enum all { 761 value -1; 762 description 763 "Any combination of change types can be excluded."; 764 } 765 } 766 type yp:change-type; 767 } 768 description 769 "The change types that can be excluded in 770 YANG-Push subscriptions."; 772 reference 773 "RFC 8641: Subscription to YANG Notifications for Datastore 774 Updates, the change-type typedef in the ietf-yang-push 775 YANG module"; 776 } 777 } 778 } 780 augment "/sysc:system-capabilities" { 781 description 782 "Add system level capabilities"; 783 uses subscription-capabilities { 784 refine 785 "subscription-capabilities/supported-excluded-change-type" { 786 default "none"; 787 } 788 } 789 } 791 augment "/sysc:system-capabilities/sysc:datastore-capabilities" 792 + "/sysc:per-node-capabilities" { 793 description 794 "Add datastore and node level capabilities"; 795 uses subscription-capabilities { 796 refine 797 "subscription-capabilities/supported-excluded-change-type" { 798 default "none"; 799 } 800 } 801 } 802 } 804 806 6. Security Considerations 808 The YANG modules specified in this document define a schema for data 809 that is designed to be accessed via network management protocols such 810 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 811 is the secure transport layer, and the mandatory-to-implement secure 812 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 813 is HTTPS, and the mandatory-to-implement secure transport is TLS 814 [RFC8446]. 816 The Network Configuration Access Control Model (NACM) [RFC8341] 817 provides the means to restrict access for particular NETCONF or 818 RESTCONF users to a preconfigured subset of all available NETCONF or 819 RESTCONF protocol operations and content. 821 All protocol-accessible data nodes are read-only and cannot be 822 modified. The data in these modules is not security sensitive. 823 Access control may be configured, to avoid exposing the read-only 824 data. 826 When that data is in file format, data should be protected against 827 modification or unauthorized access using normal file handling 828 mechanisms. 830 7. IANA Considerations 832 7.1. The IETF XML Registry 834 This document registers two URIs in the IETF XML registry [RFC3688]. 835 Following the format in [RFC3688], the following registrations are 836 requested: 838 URI: urn:ietf:params:xml:ns:yang:ietf-system-capabilities 839 Registrant Contact: The NETCONF WG of the IETF. 840 XML: N/A, the requested URI is an XML namespace. 842 URI: urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 843 Registrant Contact: The NETCONF WG of the IETF. 844 XML: N/A, the requested URI is an XML namespace. 846 7.2. The YANG Module Names Registry 848 This document registers two YANG modules in the YANG Module Names 849 registry. Following the format in [RFC7950], the the following 850 registrations are requested: 852 name: ietf-system-capabilities 853 namespace: urn:ietf:params:xml:ns:yang:ietf-system-capabilities 854 prefix: sysc 855 reference: RFC XXXX 857 name: ietf-notification-capabilities 858 namespace: 859 urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 860 prefix: notc 861 reference: RFC XXXX 863 8. Acknowledgments 865 For their valuable comments, discussions, and feedback, we wish to 866 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Kent 867 Watsen, Eric Voit, Joe Clarke, Martin Bjorklund, Ladislav Lhotka, Qin 868 Wu, Mahesh Jethanandani, Ran Tao, Reshad Rahman and other members of 869 the Netmod WG. 871 9. References 873 9.1. Normative References 875 [I-D.ietf-netmod-yang-instance-file-format] 876 Lengyel, B. and B. Claise, "YANG Instance Data File 877 Format", draft-ietf-netmod-yang-instance-file-format-12 878 (work in progress), April 2020. 880 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 881 Requirement Levels", BCP 14, RFC 2119, 882 DOI 10.17487/RFC2119, March 1997, 883 . 885 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 886 RFC 7950, DOI 10.17487/RFC7950, August 2016, 887 . 889 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 890 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 891 May 2017, . 893 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 894 Access Control Model", STD 91, RFC 8341, 895 DOI 10.17487/RFC8341, March 2018, 896 . 898 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 899 and R. Wilton, "Network Management Datastore Architecture 900 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 901 . 903 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 904 and R. Wilton, "YANG Library", RFC 8525, 905 DOI 10.17487/RFC8525, March 2019, 906 . 908 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 909 E., and A. Tripathy, "Subscription to YANG Notifications", 910 RFC 8639, DOI 10.17487/RFC8639, September 2019, 911 . 913 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 914 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 915 September 2019, . 917 9.2. Informative References 919 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 920 DOI 10.17487/RFC3688, January 2004, 921 . 923 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 924 and A. Bierman, Ed., "Network Configuration Protocol 925 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 926 . 928 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 929 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 930 . 932 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 933 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 934 . 936 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 937 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 938 . 940 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 941 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 942 . 944 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 945 "Handling Long Lines in Content of Internet-Drafts and 946 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 947 . 949 Appendix A. Instance data example #1 951 The following instance data example describes the notification 952 capabilities of a hypothetical "acme-router". The router implements 953 the running, and operational datastores. Every change can be 954 reported "on-change" from the running datastore, but only "config 955 false" nodes and some "config false" data from the operational 956 datastore. Interface statistics are not reported "on-change" only 957 two important counters. Datastore subscription capabilities are not 958 reported "on-change" as they never change on the acme-router during 959 run-time. 961 ========== NOTE: '\' line wrapping per BCP YYY (RFC YYYY) =========== 963 964 966 acme-router-notification-capabilities 967 968 ietf-system-capabilities@2021-04-02 969 ietf-notification-capabilities@2021-04-02 970 971 Defines the notification capabilities of an acme-router. 972 The router only has running, and operational datastores. 973 Every change can be reported on-change from the running 974 datastore, but only "config false" nodes and some "config 975 false" data from the operational datastore. Statistics are 976 not reported on-change only two important counters, for these 977 a smaller dampening period is possible. 978 979 980 985 986 500 987 2000 988 100 989 \ 990 config-changes state-changes\ 991 992 \ 993 config-changes state-changes\ 994 995 \ 996 all\ 997 998 999 1000 ds:operational 1001 1002 \ 1003 /if:interfaces/if:interface[if:name='lo']\ 1004 1005 1006 1007 1008 1009 1010 1011 \ 1012 /if:interfaces/if:interface/if:statistics/if:in-octets\ 1014 1015 1016 10 1017 1018 \ 1019 state-changes\ 1020 1021 1022 1023 1024 \ 1025 /if:interfaces/if:interface/if:statistics/if:out-octets\ 1026 1027 1028 10 1029 1030 \ 1031 state-changes\ 1032 1033 1034 1035 1036 \ 1037 /if:interfaces/if:interface/if:statistics\ 1038 1039 1040 1041 1042 1043 1044 1045 1046 1048 Figure 1: Notification Capabilities with data node specific settings 1050 Appendix B. Instance data example #2 1052 The following examples use artwork folding [RFC8792] for better 1053 formatting. 1055 The following instance data example describes the notification 1056 capabilities of a hypothetical "acme-switch". The switch implements 1057 the running, candidate and operational datastores. Every change can 1058 be reported "on-change" from the running datastore, nothing from the 1059 candidate datastore and all "config false" data from the operational 1060 datastore. "periodic" subscriptions are supported for running and 1061 operational, but not for candidate datastores. 1063 ========== NOTE: '\' line wrapping per BCP YYY (RFC YYYY) =========== 1065 1066 1068 acme-switch-notification-capabilities 1069 1070 ietf-system-capabilities@2021-04-02 1071 ietf-notification-capabilities@2021-04-02 1072 1073 Notification capabilities of acme-switch. 1074 Acme-switch implements the running, candidate and operational 1075 datastores. Every change can be reported on-change from the 1076 running datastore, nothing from the candidate datastore and 1077 all "config false" data from the operational datastore. Periodic 1078 subscriptions are supported for running and operational, but not 1079 for candidate datastore. 1080 1081 1082 1087 1088 500 1089 2000 1090 100 1091 \ 1092 config-changes state-changes\ 1093 1094 1095 1096 ds:operational 1097 1098 / 1099 1100 \ 1101 state-changes\ 1102 1103 1104 1105 1106 1107 ds:candidate 1108 1109 / 1110 1111 1112 1113 1114 1115 1116 1117 ds:running 1118 1119 / 1120 1121 \ 1122 config-changes\ 1123 1124 1125 1126 1127 1128 1129 1131 Figure 2: Notification Capabilities with datastore level settings 1133 Appendix C. Changes between revisions 1135 Note to RFC Editor (To be removed by RFC Editor) 1137 v15 - v16 1139 o Two editorial comments from document shepherd 1141 v14 - v15 1143 o Address the last comments from document shepherd 1145 v13 - v14 1147 o Updated according to sheperds review 1149 o Added to import, which imported modules need to be implemented. 1151 o Added notes to the RFC editor 1153 o Re-arrange the sections, for a better reading flow 1155 o Many editorial changes 1157 o Replace YANG module prefix 1158 v12 - v13 1160 o Rearranged order of notification capability leafs into 3 groups: 1161 generic, specific to periodic subscriptions, specific to on- 1162 change. 1164 o Introduced artwork folding in the examples 1166 o Updated to follow draft-ietf-netmod-yang-instance-file-format-10 1168 o Various editing changes 1170 v11 - v12 1172 o Updated max-nodes-per-update description 1174 o Reformatted YANG models with pyang -f yang --keep-comments --yang- 1175 line-length 69 1177 v10 - v11 1179 o Updated examples 1181 o Updated typedef notification-support 1183 v09 - v10 1185 o Removed description text from imports about the need for 1186 implementing the imported module. 1188 o Changed notification-support to bits with shorter names 1190 o Assigned enum values to supported-excluded-change-type 1192 o Made node-selector a choice to allow for future alternative 1193 selection methods. 1195 o Changed precedence of per-node-capabilities entries. Precedence 1196 is now according to the position of entries in the list. 1198 v08 - v09 1200 o Split the YANG module into two: ietf-system-capabilities and ietf- 1201 notification-capabilities. Restructured/updated the draft 1202 accordingly. 1204 v07 - v08 1205 o Prepared the YANG model to include other non-YANG-Push related 1206 capabilities. 1208 o Renamed the top level container to system-capabilities 1210 o Added a container subscription-capabilities to the grouping 1211 subscription-capabilities to contain all subscription related 1212 capabilities 1214 o Updated examples according to draft-ietf-netmod-yang-instance- 1215 file-format-06. 1217 v06 - v07 1219 o Updated examples according to draft-ietf-netmod-yang-instance- 1220 file-format-05. 1222 v05 - v06 1224 o Providing the capability data is only a "SHOULD" recommendation. 1225 Some reviewers wanted MUST some wanted much less. 1227 o The YANG module import statements now indicate the imported 1228 modules that must be implemented not just available as import as 1229 requested by the YangDoctors review. 1231 v04 - v05 1233 o Added new capabilities periodic-notifications-supported and 1234 supported-excluded-change-type. 1236 o Restructured YANG module to make the node-selector's usage similar 1237 to how NACM uses it: "/" means the whole datastore. 1239 o Small corrections, spelling, rewording 1241 o Replaced the term server with the term publisher except in cases 1242 where we speak about datastores and functionality based on get, 1243 getconfig operations. In this latter case it is really the server 1244 functionality that is discussed 1246 v03 - v04 1248 o Clarified recommended support for on-change notifications about 1249 the datastore-subscription-capabilities. 1251 v02 - v03 1252 o Allow throughput related capabilities to be defined on top, 1253 datastore or data node level. Described that specific capability 1254 values always override generic ones. 1256 o Indicate that non-NMDA servers can also use this model. 1258 o Updated according to draft-ietf-netmod-yang-instance-file- 1259 format-04 1261 v01 - v02 1263 o Added instance data examples 1265 o On-change capability can be defined per datastore 1267 o Added "if-feature yp:on-change" where relevant 1269 o Unified units used 1271 v00 - v01 1273 o Add more capabilities: minimum period, supported period max-number 1274 of objects, min dampening period, dampening supported 1276 Authors' Addresses 1278 Balazs Lengyel 1279 Ericsson 1280 Magyar Tudosok korutja 11 1281 1117 Budapest 1282 Hungary 1284 Email: balazs.lengyel@ericsson.com 1286 Alexander Clemm 1287 Futurewei 1288 2330 Central Expressway 1289 Santa Clara, CA 95050 1290 USA 1292 Email: ludwig@clemm.org 1294 Benoit Claise 1295 Huawei 1297 Email: benoit.claise@huawei.com