idnits 2.17.1 draft-ietf-netconf-notification-capabilities-13.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 (March 23, 2020) is 1496 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-08 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: September 24, 2020 Futurewei 6 B. Claise 7 Cisco Systems, Inc. 8 March 23, 2020 10 YANG Modules for describing System Capabilities and Yang-Push 11 Notification Capabilities 12 draft-ietf-netconf-notification-capabilities-13 14 Abstract 16 This document defines two YANG modules: 18 The module ietf-system-capabilities provides a structure that can be 19 used to specify YANG related system capabilities for servers. The 20 module can be used in conjunction with YANG Instance Data to make 21 this information available at implementation-time. The module can 22 also be used to report capability information from the server at run- 23 time. 25 The module ietf-notification-capabilities augments ietf-system- 26 capabilities to specify capabilities related to "Subscription to YANG 27 Datastores" (YANG-Push). 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 September 24, 2020. 46 Copyright Notice 48 Copyright (c) 2020 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. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 64 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2.1. YANG-Push Notification Capabilities . . . . . . . . . . . 4 66 3. Providing System Capability Information . . . . . . . . . . . 6 67 4. System Capabilities Model . . . . . . . . . . . . . . . . . . 6 68 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7 69 4.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 7 70 5. Notification Capabilities Model . . . . . . . . . . . . . . . 10 71 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 10 72 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 11 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 74 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 75 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 17 76 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 17 77 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 78 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 79 9.1. Normative References . . . . . . . . . . . . . . . . . . 18 80 9.2. Informative References . . . . . . . . . . . . . . . . . 19 81 Appendix A. Instance data examples . . . . . . . . . . . . . . . 19 82 Appendix B. Changes between revisions . . . . . . . . . . . . . 23 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 85 1. Terminology 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 89 "OPTIONAL" in this document are to be interpreted as described in BCP 90 14 [RFC2119] [RFC8174] when, and only when, they appear in all 91 capitals, as shown here. 93 The terms YANG-Push, On-change subscription and Periodic subscription 94 are used as defined in [RFC8641]. 96 The terms Subscriber, Publisher and Receiver are used as defined in 97 [RFC8639]. 99 The term Server is used as defined in [RFC8342]. 101 The terms Instance Data and Instance Data Set are used as defined in 102 [I-D.ietf-netmod-yang-instance-file-format]. 104 In addition, this document defines the following terms: 106 Implementation-time information: Information about the server's 107 behavior that is made available during the implementation of the 108 server, available from a source other then a running server. 110 Run-time information: Information about the server's behavior that is 111 available from the running server via management protocols such as 112 NETCONF [RFC6241] or RESTCONF [RFC8040]. 114 On-change notification capability: The capability of the publisher to 115 send on-change notifications for a specific datastore or a specific 116 data node. 118 2. Introduction 120 Systems implementing a server and/or a publisher often have 121 capabilities that are not defined by the YANG model itself. There is 122 a need to publish this capability information as it is part of the 123 contract between the server and client. Examples include maximum 124 size of data that can be stored or transferred, information about 125 counters (whether a node supports on-change telemetry), etc. Such 126 capabilities are often dependent on a vendor's implementation or the 127 available resources at deployment. Many such capabilities are 128 specific to either the complete system, individual YANG datastores or 129 specific parts of the YANG schema, or even individual data nodes. It 130 is a goal of this document to provide a common way of representing 131 such capabilities in a format that is: 133 o vendor independent 135 o machine readable 137 o available in identical format both at implementation-time and run- 138 time 140 2.1. YANG-Push Notification Capabilities 142 A specific case where we need to specify capabilities is the YANG- 143 Push functionality. As defined in [RFC8641] a publisher may allow 144 subscribers to subscribe to updates from a datastore and subsequently 145 push such update notifications to the receiver. Notifications may be 146 sent periodically or on-change (more or less immediately after each 147 change). 149 A publisher supporting YANG-Push has a number of capabilities defined 150 in [RFC8641] that are often determined during the implementation of 151 the publisher. These include: 153 o Supported (reporting) periods for periodic subscriptions 155 o Maximum number of objects that can be sent in an update 157 o The set of datastores or data nodes for which periodic 158 notification is supported 160 Additional capabilities if the optional on-change feature is 161 supported include: 163 o Supported dampening periods for on-change subscriptions 165 o The set of datastores or data nodes for which on-change 166 notification is supported 168 Publishers have limitations in how many update notifications and how 169 many datastore node updates they can send out in a certain time- 170 period. 172 Publishers might not support periodic subscriptions to all 173 datastores. 175 In some cases, a publisher supporting on-change notifications will 176 not be able to push updates for some object types on-change. Reasons 177 for this might be that the value of the datastore node changes 178 frequently (e.g., in-octets counter), that small object changes are 179 frequent and irrelevant to the receiver (e.g., a temperature gauge 180 changing 0.1 degrees within a predetermined and acceptable range), or 181 that the implementation is not capable of on-change notification for 182 a particular object. In those cases, it will be important for 183 subscriber applications to have a way to identify which objects on- 184 change notifications are supported and for which ones not. 186 Faced with the reality that support for on-change notification does 187 not mean that such notifications will be sent for any specific data 188 node, subscriber/management applications can not rely on the on- 189 change functionality unless the subscriber has some means to identify 190 which objects on-change notifications are supported. YANG models are 191 meant to be used as an interface contract. Without identification of 192 the data nodes actually supporting on-change, this contract would be 193 incomplete. 195 Clients of a server, subscribers to a publisher need a method to 196 gather capability information. 198 Implementation-time information is needed by Network Management 199 System (NMS) implementers. A NMS implementation that wants to 200 support notifications, needs the information about on-change 201 notification capability. If the information is not documented in a 202 way available to the NMS designer, but only as instance data from the 203 network node once it is deployed, the NMS implementation will be 204 delayed, because it has to wait for the network node to be ready. In 205 addition, the assumption that all NMS implementers will have a 206 correctly configured network node available to retrieve data from is 207 an expensive proposition and may not always hold. (An NMS may need 208 to be able to handle many dozens of network node types.) Often a 209 fully functional NMS is a requirement for introducing a new network 210 node type into a network, so delaying NMS readiness effectively also 211 delays the time at which a new network node type can be introduced 212 into the network. 214 Implementation-time information is needed by system integrators. 215 When introducing a network node type into their network, operators 216 often need to integrate the node type into their own management 217 system. The NMS may have management functions that depend on on- 218 change notifications. The network operator needs to plan his 219 management practices and NMS implementation before he even decides to 220 buy the specific network node type. Moreover the decision to buy the 221 node type sometimes depends on these management possibilities. 223 Run-time information is needed: 225 o for any "purely model driven" application, e.g., a NETCONF- 226 browser. Such applications depend on reading models and 227 capabilities at run-time to support all the publisher's available 228 functionality. 230 o in case the capability might change during run-time e.g., due to 231 licensing, HW constraints etc. 233 o to check that capability information provided earlier, at 234 implementation-time is what the publisher has implemented. 236 3. Providing System Capability Information 238 Capability information is represented by instance-data based on one 239 or more "capability defining YANG modules". This allows a user to 240 discover capabilities both at implementation-time and run-time. 242 o For the implementation-time use-case: Capabilities SHOULD be 243 provided by the implementer as YANG instance data files complying 244 to [I-D.ietf-netmod-yang-instance-file-format]. The file MUST be 245 available already at implementation-time retrievable in a way that 246 does not depend on a live network node. E.g., download from 247 product website. 249 o For the run-time use-case: Capabilities SHOULD be available via 250 NETCONF [RFC6241] or RESTCONF [RFC8040] from the live server 251 (implementing the publisher) during run-time. Implementations 252 which support changing these capabilities at run-time SHOULD 253 support on-change notifications about the system-capabilities 254 container. 256 The module ietf-system-capabilities is defined to provide a structure 257 that can be used to specify any YANG related system capability. 259 The module ietf-notification-capabilities is defined to allow a 260 publisher to specify capabilities related to "Subscription to YANG 261 Datastores" (YANG-Push) augmenting ietf-system-capabilities. 263 The YANG data models in this document conform to the Network 264 Management Datastore Architecture (NMDA) defined in [RFC8342]. 266 4. System Capabilities Model 268 The module ietf-system-capabilities is defined to provide a structure 269 that can be used to specify any YANG related system capability. 271 Capability values can be specified on system/publisher level, 272 datastore level (by selecting all nodes in the datastore) or for 273 specific data nodes of a specific datastore (and their contained sub- 274 trees). Capability values specified for a specific datastore or 275 node-set override values specified on the system/publisher level. 277 This module itself does not contain any capabilities. It SHOULD be 278 used by other modules to augment-in specific capability information. 279 Every set of such capabilities SHOULD be wrapped in a container under 280 the augment statement to cleanly separate different groups of 281 capabilities. These "wrapper containers" SHALL be augmented in at 282 /sysc:system-capabilities and /sysc:system-capabilities/ 283 sysc:datastore-capabilities/sysc:per-node-capabilities. 285 Note: The solution is usable for both NMDA and non-NMDA systems. For 286 non-NMDA servers/publishers config=false data is considered as if it 287 was part of the running datastore. 289 4.1. Tree Diagram 291 The following tree diagram [RFC8340] provides an overview of the data 292 model. 294 module: ietf-system-capabilities 295 +--ro system-capabilities 296 +--ro datastore-capabilities* [datastore] 297 +--ro datastore -> /yanglib:yang-library/datastore/name 298 +--ro per-node-capabilities* [] 299 +--ro (node-selection)? 300 +--:(node-selector) 301 +--ro node-selector? nacm:node-instance-identifier 303 4.2. YANG Module 305 This YANG module imports typedefs from [RFC8341] and a reference path 306 from [RFC8525]. 308 file "ietf-system-capabilities@2020-03-23.yang" 310 module ietf-system-capabilities { 311 yang-version 1.1; 312 namespace "urn:ietf:params:xml:ns:yang:ietf-system-capabilities"; 313 prefix sysc; 315 import ietf-netconf-acm { 316 prefix nacm; 317 reference 318 "RFC 8341: Network Configuration Access Control Model"; 319 } 320 import ietf-yang-library { 321 prefix yanglib; 322 description 323 "Revision 2019-01-04 or a 324 revision derived from it is REQUIRED."; 325 reference 326 "RFC RFC8525: YANG Library"; 327 } 329 organization 330 "IETF NETCONF (Network Configuration) Working Group"; 331 contact 332 "WG Web: 333 WG List: 335 Editor: Balazs Lengyel 336 "; 337 description 338 "This module specifies a module intended to contain system 339 capabilities. System capabilities may include capabilities of a 340 NETCONF or RESTCONF server or a notification publisher. 342 This module does not contain any specific capabilities it only 343 provides a structure where containers containing the actual 344 capabilities should be augmented in. 346 Capability values can be specified on system level, 347 datastore level (by selecting all nodes in the datastore) or 348 for specific data nodes of a specific datastore (and their 349 contained sub-trees). 350 Capability values specified for a specific datastore or 351 node-set override values specified on the system/publisher level. 353 To find a capability value for a specific data node in a 354 specific datastore the user SHALL 355 1) search for a datastore-capabilities list entry for 356 the specific datastore. 357 2) If the datastore entry is found within that entry process all 358 per-node-capabilities entries in the order they appear in the list. 359 The first entry that specifies the specific capability and has a 360 node-selector selecting the specific data node defines the 361 capability value. 362 3) If the capability value is not found above and the specific 363 capability is specified under the system-capabilities container 364 (outside the datastore-capabilities list) this value shall be used. 365 4) If no values are found in the previous steps the 366 system/publisher is not capable of providing a value because 367 it is unknown, the capability is changing for some reason, 368 there is no specified limit etc. In this case the 369 system's behavior is unspecified. 371 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 372 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 373 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 374 are to be interpreted as described in BCP 14 (RFC 2119) 375 (RFC 8174) when, and only when, they appear in all 376 capitals, as shown here. 378 Copyright (c) 2020 IETF Trust and the persons identified as 379 authors of the code. All rights reserved. 381 Redistribution and use in source and binary forms, with or 382 without modification, is permitted pursuant to, and subject to 383 the license terms contained in, the Simplified BSD License set 384 forth in Section 4.c of the IETF Trust's Legal Provisions 385 Relating to IETF Documents 386 (https://trustee.ietf.org/license-info). 388 This version of this YANG module is part of RFC XXXX 389 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 390 for full legal notices."; 392 revision 2020-03-23 { 393 description 394 "Initial version"; 395 reference 396 "RFC XXX: YANG-Push Notification Capabilities"; 397 } 399 container system-capabilities { 400 config false; 401 description 402 "System capabilities. 403 Capability values specified here at the system level 404 are valid for all datastores and 405 are used when the capability is not specified on the 406 datastore level or for specific data nodes."; 407 // augmentation point for system level capabilities 408 list datastore-capabilities { 409 key "datastore"; 410 description 411 "Capabilities values per datastore. 412 For non-NMDA servers/publishers config=false data is 413 considered as if it was part of the running datastore."; 414 leaf datastore { 415 type leafref { 416 path 417 "/yanglib:yang-library/yanglib:datastore/yanglib:name"; 418 } 419 description 420 "The datastore for which capabilities are defined. 421 Only individual datastores can be specified 422 e.g., ds:conventional is not allowed."; 423 } 424 list per-node-capabilities { 425 description 426 "Each list entry specifies capabilities for the selected 427 data nodes. The same capabilities apply for the data nodes 428 in the subtree below the selected nodes. 430 The system SHALL order the entries according to their 431 precedence. The order of the entries MUST NOT change unless 432 the underlying capabilities also change."; 433 choice node-selection { 434 description 435 "A method to select all or some nodes within a datastore."; 436 leaf node-selector { 437 type nacm:node-instance-identifier; 438 description 439 "Selects the data nodes for which capabilities are 440 specified. The special value '/' denotes all data nodes 441 in the datastore."; 442 } 443 } 444 // augmentation point for datastore or data node level 445 // capabilities 446 } 447 } 448 } 449 } 451 453 5. Notification Capabilities Model 455 The YANG module ietf-notification-capabilities is defined to provide 456 YANG-Push related capability information. 458 5.1. Tree Diagram 460 The following tree diagram [RFC8340] provides an overview of the data 461 model. 463 module: ietf-notification-capabilities 464 augment /sysc:system-capabilities: 465 +--ro subscription-capabilities 466 +--ro max-nodes-per-update? uint32 467 +--ro periodic-notifications-supported? notification-support 468 +--ro (update-period)? 469 | +--:(minimum-update-period) 470 | | +--ro minimum-update-period? uint32 471 | +--:(supported-update-period) 472 | +--ro supported-update-period* uint32 473 +--ro on-change-supported? notification-support 474 | {yp:on-change}? 475 +--ro minimum-dampening-period? uint32 476 | {yp:on-change}? 477 +--ro supported-excluded-change-type* union 478 {yp:on-change}? 479 augment /sysc:system-capabilities/sysc:datastore-capabilities 480 /sysc:per-node-capabilities: 481 +--ro subscription-capabilities 482 +--ro max-nodes-per-update? uint32 483 +--ro periodic-notifications-supported? notification-support 484 +--ro (update-period)? 485 | +--:(minimum-update-period) 486 | | +--ro minimum-update-period? uint32 487 | +--:(supported-update-period) 488 | +--ro supported-update-period* uint32 489 +--ro on-change-supported? notification-support 490 | {yp:on-change}? 491 +--ro minimum-dampening-period? uint32 492 | {yp:on-change}? 493 +--ro supported-excluded-change-type* union 494 {yp:on-change}? 496 5.2. YANG Module 498 This YANG module imports a feature and typedefs from [RFC8641]. 500 file "ietf-notification-capabilities@2020-03-23.yang" 502 module ietf-notification-capabilities { 503 yang-version 1.1; 504 namespace 505 "urn:ietf:params:xml:ns:yang:ietf-notification-capabilities"; 506 prefix inc; 508 import ietf-yang-push { 509 prefix yp; 510 reference 511 "RFC 8641: Subscription to YANG Notifications for Datastore 512 Updates"; 513 } 514 import ietf-system-capabilities { 515 prefix sysc; 516 reference 517 "RFC XXXX: YANG Modules for describing System Capabilities 518 and Yang-Push Notification Capabilities"; 519 } 521 organization 522 "IETF NETCONF (Network Configuration) Working Group"; 523 contact 524 "WG Web: 525 WG List: 527 Editor: Balazs Lengyel 528 "; 529 description 530 "This module specifies YANG-Push [RFC 8641] related publisher 531 capabilities. 533 The module contains 534 - specification of which data nodes support on-change or 535 periodic notifications. 536 - capabilities related to the throughput of notification data 537 the publisher can support. (Note that for a specific 538 subscription the publisher MAY still allow only longer periods 539 or smaller updates depending on e.g., actual load conditions.) 541 Capability values can be specified on system/publisher level, 542 datastore level or for specific data nodes of a specific 543 datastore (and their contained sub-trees), as defined in the 544 ietf-system-capabilities module. 546 If, different data nodes covered by a single subscription 547 have different values for a specific capability, then using 548 values that are only acceptable for some of these data nodes, 549 but not for others, may result in the rejection of the 550 subscription. 552 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 553 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 554 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 555 are to be interpreted as described in BCP 14 (RFC 2119) 556 (RFC 8174) when, and only when, they appear in all 557 capitals, as shown here. 559 Copyright (c) 2020 IETF Trust and the persons identified as 560 authors of the code. All rights reserved. 562 Redistribution and use in source and binary forms, with or 563 without modification, is permitted pursuant to, and subject 564 to the license terms contained in, the Simplified BSD License 565 set forth in Section 4.c of the IETF Trust's Legal Provisions 566 Relating to IETF Documents 567 (http://trustee.ietf.org/license-info). 569 This version of this YANG module is part of RFC XXXX 570 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 571 for full legal notices."; 573 revision 2020-03-23 { 574 description 575 "Initial version"; 576 reference 577 "RFC XXX: YANG-Push Notification Capabilities"; 578 } 580 grouping subscription-capabilities { 581 description 582 "Capabilities related to YANG-Push subscriptions 583 and notifications"; 584 container subscription-capabilities { 585 description 586 "Capabilities related to YANG-Push subscriptions 587 and notifications"; 588 typedef notification-support { 589 type bits { 590 bit config-changes { 591 description 592 "The publisher is capable of sending 593 notifications for config=true nodes for the relevant 594 scope and subscription type."; 595 } 596 bit state-changes { 597 description 598 "The publisher is capable of sending 599 notifications for config=false nodes for the relevant 600 scope and subscription type."; 601 } 602 } 603 description 604 "Type for defining whether on-change or 605 periodic notifications are supported for none, only 606 config=true, only config=false or all data nodes. 608 If the bit config-changes or state-changes is set 609 for a datastore or a set of nodes that does not contain 610 nodes with the indicated config value, 611 this has no effect, as if no support was declared. 612 E.g. indicating support for state-changes for 613 a candidate datastore has no effect."; 614 } 616 leaf max-nodes-per-update { 617 type uint32 { 618 range "1..max"; 619 } 620 description 621 "Maximum number of data nodes that can be sent 622 in an update. The publisher MAY support more data nodes, 623 but SHOULD support at least this number. 624 May be used to avoid the update-too-big error 625 during subscription."; 626 reference "The update-too-big error/identity in RFC 8641"; 627 } 628 leaf periodic-notifications-supported { 629 type notification-support; 630 description 631 "Specifies whether the publisher is capable of 632 sending periodic notifications for the selected 633 data nodes and the subtree below them."; 634 reference 635 "Periodic subscription concept in RFC 8641"; 636 } 637 choice update-period { 638 description 639 "Supported update period value or values for 640 periodic subscriptions."; 641 leaf minimum-update-period { 642 type uint32; 643 units "centiseconds"; 644 description 645 "Indicates the minimal update period that is 646 supported for a periodic subscription. 647 A subscription request to the selected data 648 nodes with a smaller period than what this leaf 649 specifies will result in a 'period-unsupported' error."; 650 reference 651 "The period leaf in RFC 8641 ietf-yang-push YANG module"; 652 } 653 leaf-list supported-update-period { 654 type uint32; 655 units "centiseconds"; 656 description 657 "Supported update period values for a 658 periodic subscription. 659 A subscription request to the selected data nodes with a 660 period not included in the leaf-list will result in a 661 'period-unsupported' error."; 662 reference 663 "The period leaf in RFC 8641 ietf-yang-push YANG module"; 664 } 665 } 666 leaf on-change-supported { 667 if-feature "yp:on-change"; 668 type notification-support; 669 description 670 "Specifies whether the publisher is capable of 671 sending on-change notifications for the selected 672 data nodes and the subtree below them."; 673 reference 674 "On-change concept in RFC 8641"; 675 } 676 leaf minimum-dampening-period { 677 if-feature "yp:on-change"; 678 type uint32; 679 units "centiseconds"; 680 description 681 "The minimum dampening-period supported for on-change 682 subscriptions for the selected data nodes. 683 If this value is present and greater than zero, 684 that implies dampening is mandatory."; 685 reference 686 "The dampening-period leaf in RFC 8641 ietf-yang-push 687 YANG module"; 688 } 689 leaf-list supported-excluded-change-type { 690 if-feature "yp:on-change"; 691 type union { 692 type enumeration { 693 enum none { 694 value -2; 695 description 696 "None of the change types can be excluded."; 697 } 698 enum all { 699 value -1; 700 description 701 "Any combination of change types can be excluded."; 702 } 703 } 704 type yp:change-type; 705 } 706 description 707 "The change types that can be excluded in 708 YANG-Push subscriptions."; 709 reference 710 "The change-type typedef in RFC 8641 ietf-yang-push 711 YANG module"; 712 } 713 } 714 } 716 augment "/sysc:system-capabilities" { 717 description 718 "Add system level capabilities"; 719 uses subscription-capabilities { 720 refine 721 "subscription-capabilities/supported-excluded-change-type" { 722 default "none"; 723 } 724 } 725 } 727 augment "/sysc:system-capabilities/sysc:datastore-capabilities" 728 + "/sysc:per-node-capabilities" { 729 description 730 "Add datastore and node level capabilities"; 731 uses subscription-capabilities { 732 refine 733 "subscription-capabilities/supported-excluded-change-type" { 734 default "none"; 735 } 736 } 737 } 738 } 740 742 6. Security Considerations 744 The YANG modules specified in this document define a schema for data 745 that is designed to be accessed via network management protocols such 746 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 747 is the secure transport layer, and the mandatory-to-implement secure 748 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 749 is HTTPS, and the mandatory-to-implement secure transport is TLS 750 [RFC8446]. 752 The Network Configuration Access Control Model (NACM) [RFC8341] 753 provides the means to restrict access for particular NETCONF or 754 RESTCONF users to a preconfigured subset of all available NETCONF or 755 RESTCONF protocol operations and content. 757 All protocol-accessible data nodes are read-only and cannot be 758 modified. The data in these modules is not security sensitive. 759 Access control may be configured, to avoid exposing the read-only 760 data. 762 When that data is in file format, data should be protected against 763 modification or unauthorized access using normal file handling 764 mechanisms. 766 7. IANA Considerations 768 7.1. The IETF XML Registry 770 This document registers two URIs in the IETF XML registry [RFC3688]. 771 Following the format in [RFC3688], the following registrations are 772 requested: 774 URI: urn:ietf:params:xml:ns:yang:ietf-system-capabilities 775 Registrant Contact: The NETCONF WG of the IETF. 776 XML: N/A, the requested URI is an XML namespace. 778 URI: urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 779 Registrant Contact: The NETCONF WG of the IETF. 780 XML: N/A, the requested URI is an XML namespace. 782 7.2. The YANG Module Names Registry 784 This document registers two YANG modules in the YANG Module Names 785 registry. Following the format in [RFC7950], the the following 786 registrations are requested: 788 name: ietf-system-capabilities 789 namespace: urn:ietf:params:xml:ns:yang:ietf-system-capabilities 790 prefix: sysc 791 reference: RFC XXXX 793 name: ietf-notification-capabilities 794 namespace: 795 urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 796 prefix: inc 797 reference: RFC XXXX 799 8. Acknowledgments 801 For their valuable comments, discussions, and feedback, we wish to 802 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Kent 803 Watsen, Eric Voit, Joe Clarke, Martin Bjorklund, Ladislav Lhotka, Qin 804 Wu, Mahesh Jethanandani, Ran Tao, Reshad Rahman and other members of 805 the Netmod WG. 807 9. References 809 9.1. Normative References 811 [I-D.ietf-netmod-yang-instance-file-format] 812 Lengyel, B. and B. Claise, "YANG Instance Data File 813 Format", draft-ietf-netmod-yang-instance-file-format-08 814 (work in progress), March 2020. 816 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 817 Requirement Levels", BCP 14, RFC 2119, 818 DOI 10.17487/RFC2119, March 1997, 819 . 821 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 822 RFC 7950, DOI 10.17487/RFC7950, August 2016, 823 . 825 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 826 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 827 May 2017, . 829 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 830 Access Control Model", STD 91, RFC 8341, 831 DOI 10.17487/RFC8341, March 2018, 832 . 834 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 835 and R. Wilton, "Network Management Datastore Architecture 836 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 837 . 839 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 840 and R. Wilton, "YANG Library", RFC 8525, 841 DOI 10.17487/RFC8525, March 2019, 842 . 844 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 845 E., and A. Tripathy, "Subscription to YANG Notifications", 846 RFC 8639, DOI 10.17487/RFC8639, September 2019, 847 . 849 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 850 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 851 September 2019, . 853 9.2. Informative References 855 [I-D.ietf-netmod-artwork-folding] 856 Watsen, K., Auerswald, E., Farrel, A., and Q. WU, 857 "Handling Long Lines in Inclusions in Internet-Drafts and 858 RFCs", draft-ietf-netmod-artwork-folding-12 (work in 859 progress), January 2020. 861 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 862 DOI 10.17487/RFC3688, January 2004, 863 . 865 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 866 and A. Bierman, Ed., "Network Configuration Protocol 867 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 868 . 870 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 871 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 872 . 874 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 875 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 876 . 878 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 879 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 880 . 882 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 883 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 884 . 886 Appendix A. Instance data examples 888 The following examples use artwork folding 889 [I-D.ietf-netmod-artwork-folding] for better formatting. 891 The following instance-data example describes the notification 892 capabilities of a hypothetical "acme-switch". The switch implements 893 the running, candidate and operational datastores. Every change can 894 be reported on-change from running, nothing from candidate and all 895 config=false data from operational. Periodic subscriptions are 896 supported for running and operational, but not for candidate. 898 file "acme-switch-notification-capabilities.xml" 899 ========== NOTE: '\' line wrapping per BCP YYY (RFC YYYY) =========== 901 902 904 acme-switch-notification-capabilities 905 906 ietf-system-capabilities@2020-03-23 907 ietf-notification-capabilities@2020-03-23 908 909 910 Notification capabilities of acme-switch. 911 Acme-switch implements the running, candidate and operational 912 datastores. Every change can be reported on-change from running, 913 nothing from candidate and all config=false data from operational. 914 Periodic subscriptions are supported for running and 915 operational, but not for candidate. 916 917 918 923 924 500 925 2000 926 100 927 \ 928 config-changes state-changes\ 929 930 931 932 ds:operational 933 934 / 935 936 \ 937 state-changes\ 938 940 941 942 943 944 ds:candidate 945 946 / 947 948 949 950 951 952 953 954 ds:running 955 956 / 957 958 \ 959 config-changes\ 960 961 962 963 964 965 966 967 969 Figure 1: Notification Capabilities with datastore level settings 971 The following instance-data example describes the notification 972 capabilities of a hypothetical "acme-router". The router implements 973 the running, and operational datastores. Every change can be 974 reported on-change from running, but only config=true nodes and some 975 config=false data from operational. Interface statistics are not 976 reported on-change only 2 important counters. Datastore subscription 977 capabilities are not reported on-change as they never change on the 978 acme-router during run-time. 980 file "acme-router-notification-capabilities.xml" 981 ========== NOTE: '\' line wrapping per BCP YYY (RFC YYYY) =========== 983 984 986 acme-router-notification-capabilities 987 988 ietf-system-capabilities@2020-03-23 989 ietf-notification-capabilities@2020-03-23 990 991 992 Defines the notification capabilities of an acme-router. 993 The router only has running, and operational datastores. 994 Every change can be reported on-change from running, but 995 only config=true nodes and some config=false data from operational. 996 Statistics are not reported on-change only 2 important counters, 997 for these a smaller dampening period is possible. 998 999 1000 1005 1006 500 1007 2000 1008 100 1009 \ 1010 config-changes state-changes\ 1011 1012 \ 1013 config-changes state-changes\ 1014 1015 \ 1016 all\ 1017 1018 1019 1020 ds:operational 1021 1022 \ 1023 /if:interfaces/if:interface[if:name='lo']\ 1024 1025 1026 1027 1028 1029 1030 1031 \ 1032 /if:interfaces/if:interface/if:statistics/if:in-octets\ 1033 1034 1035 10 1036 1037 \ 1038 state-changes\ 1039 1040 1041 1042 1043 \ 1044 /if:interfaces/if:interface/if:statistics/if:out-octets\ 1045 1046 1047 10 1048 1049 \ 1050 state-changes\ 1051 1052 1053 1054 1055 \ 1056 /if:interfaces/if:interface/if:statistics\ 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1068 Figure 2: Notification Capabilities with data node specific settings 1070 Appendix B. Changes between revisions 1072 Note to RFC Editor (To be removed by RFC Editor) 1074 v12 - v13 1076 o Rearranged order of notification capability leafs into 3 groups: 1077 generic, specific to periodic subscriptions, specific to on- 1078 change. 1080 o Introduced artwork folding in the examples 1082 o Updated to follow draft-ietf-netmod-yang-instance-file-format-10 1083 o Various editing changes 1085 v11 - v12 1087 o Updated max-nodes-per-update description 1089 o Reformatted YANG models with pyang -f yang --keep-comments --yang- 1090 line-length 69 1092 v10 - v11 1094 o Updated examples 1096 o Updated typedef notification-support 1098 v09 - v10 1100 o Removed description text from imports about the need for 1101 implementing the imported module. 1103 o Changed notification-support to bits with shorter names 1105 o Assigned enum values to supported-excluded-change-type 1107 o Made node-selector a choice to allow for future alternative 1108 selection methods. 1110 o Changed precedence of per-node-capabilities entries. Precedence 1111 is now according to the position of entries in the list. 1113 v08 - v09 1115 o Split the YANG module into two: ietf-system-capabilities and ietf- 1116 notification-capabilities. Restructured/updated the draft 1117 accordingly. 1119 v07 - v08 1121 o Prepared the YANG model to include other non-YANG-Push related 1122 capabilities. 1124 o Renamed the top level container to system-capabilities 1126 o Added a container subscription-capabilities to the grouping 1127 subscription-capabilities to contain all subscription related 1128 capabilities 1130 o Updated examples according to draft-ietf-netmod-yang-instance- 1131 file-format-06. 1133 v06 - v07 1135 o Updated examples according to draft-ietf-netmod-yang-instance- 1136 file-format-05. 1138 v05 - v06 1140 o Providing the capability data is only a "SHOULD" recommendation. 1141 Some reviewers wanted MUST some wanted much less. 1143 o The YANG module import statements now indicate the imported 1144 modules that must be implemented not just available as import as 1145 requested by the YangDoctors review. 1147 v04 - v05 1149 o Added new capabilities periodic-notifications-supported and 1150 supported-excluded-change-type. 1152 o Restructured YANG module to make the node-selector's usage similar 1153 to how NACM uses it: "/" means the whole datastore. 1155 o Small corrections, spelling, rewording 1157 o Replaced the term server with the term publisher except in cases 1158 where we speak about datastores and functionality based on get, 1159 getconfig operations. In this latter case it is really the server 1160 functionality that is discussed 1162 v03 - v04 1164 o Clarified recommended support for on-change notifications about 1165 the datastore-subscription-capabilities. 1167 v02 - v03 1169 o Allow throughput related capabilities to be defined on top, 1170 datastore or data node level. Described that specific capability 1171 values always override generic ones. 1173 o Indicate that non-NMDA servers can also use this model. 1175 o Updated according to draft-ietf-netmod-yang-instance-file- 1176 format-04 1178 v01 - v02 1180 o Added instance data examples 1182 o On-change capability can be defined per datastore 1184 o Added "if-feature yp:on-change" where relevant 1186 o Unified units used 1188 v00 - v01 1190 o Add more capabilities: minimum period, supported period max-number 1191 of objects, min dampening period, dampening supported 1193 Authors' Addresses 1195 Balazs Lengyel 1196 Ericsson 1197 Magyar Tudosok korutja 11 1198 1117 Budapest 1199 Hungary 1201 Email: balazs.lengyel@ericsson.com 1203 Alexander Clemm 1204 Futurewei 1205 2330 Central Expressway 1206 Santa Clara, CA 95050 1207 USA 1209 Email: ludwig@clemm.org 1211 Benoit Claise 1212 Cisco Systems, Inc. 1213 De Kleetlaan 6a b1 1214 1831 Diegem 1215 Belgium 1217 Email: bclaise@cisco.com