idnits 2.17.1 draft-claise-netconf-metadata-for-collection-01.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 126 instances of too long lines in the document, the longest one being 68 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 28, 2020) is 1214 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) == Unused Reference: 'I-D.ietf-netmod-rfc6991-bis' is defined on line 955, but no explicit reference was found in the text == Unused Reference: 'RFC8641' is defined on line 978, but no explicit reference was found in the text == Outdated reference: A later version (-21) exists of draft-ietf-netconf-notification-capabilities-13 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-rfc6991-bis-04 == Outdated reference: A later version (-05) exists of draft-claise-opsawg-service-assurance-architecture-03 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF B. Claise 3 Internet-Draft M. Nayyar 4 Intended status: Standards Track A. Reddy Sesani 5 Expires: July 1, 2021 Cisco Systems, Inc. 6 December 28, 2020 8 Per-Node Capabilities for Optimum Operational Data Collection 9 draft-claise-netconf-metadata-for-collection-01 11 Abstract 13 This document proposes a YANG module that provides per-node 14 capabilities for optimum operational data collection. This YANG 15 module augments the YANG Modules for describing System Capabilities 16 and YANG-Push Notification capabilities. 18 This module defines augmented nodes to publish the metadata 19 information specific to YANG node-identifier as per ietf-system- 20 capabilities datatree. 22 Complementary RPCs, based on the same node capabilities, simplify the 23 data collection operations. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on July 1, 2021. 42 Copyright Notice 44 Copyright (c) 2020 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 4. Base ietf-system-node-metadata YANG module . . . . . . . . . 7 63 4.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 7 64 4.2. Full Tree View . . . . . . . . . . . . . . . . . . . . . 7 65 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8 66 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 14 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 69 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 20 70 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 21 71 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 72 9.1. Normative References . . . . . . . . . . . . . . . . . . 21 73 9.2. Informative References . . . . . . . . . . . . . . . . . 22 74 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 23 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 77 1. Terminology 79 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 80 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 81 "OPTIONAL" in this document are to be interpreted as described in BCP 82 14 [RFC2119] [RFC8174] when, and only when, they appear in all 83 capitals, as shown here. 85 The term Client and Server are specified in [RFC8342]. 87 The term Implementation-time and Run-time are specified in 88 [I-D.ietf-netconf-notification-capabilities]. 90 2. Introduction 92 This document specifies a way to learn from the devices how granular 93 its telemetry and data can be to provide the best post-processing 94 analytics. In the end, the service assurance architecture 95 [I-D.claise-opsawg-service-assurance-architecture], it's not 96 sufficient to simply stream (or poll) telemetry data, it is equally 97 important to be able to act on the data. As such, a series of extra 98 information about the node capabilities is essential. 100 The module ietf-system-capabilities 101 [I-D.ietf-netconf-notification-capabilities] provides a structure 102 that can be used to specify YANG related system capabilities for 103 servers. The module can be used in conjunction with YANG Instance 104 Data to make this information available at implementation-time. The 105 module can also be used to report capability information from the 106 server at run-time. 108 The module ietf-notification-capabilities 109 [I-D.ietf-netconf-notification-capabilities] augments ietf-system- 110 capabilities to specify capabilities related to "Subscription to YANG 111 Datastores" (YANG-Push) [RFC8639]. It provides a starting point by 112 specifying some per-node telemetry-related capabilities. Of 113 particular interest are the following node capabilities: 115 o minimum-dampening-period 117 o on-change-supported 119 o periodic-notifications-supported 121 o supported-excluded-change-type 123 Taking the example of on-change-supported and periodic-notifications- 124 supported, it's key to understand whether a publisher is capable of 125 sending on-change notifications versus sending periodic notifications 126 for the selected data store or data nodes. Indeed, not only would 127 the telemetry configuration change depending on the capabilities (on- 128 change versus periodic), but more importantly the client's handling 129 of the telemetry information would change. Upon receipt of an on- 130 change telemetry message, an immediate action could be taken to 131 correct or mitigate the issue, while in case of periodic 132 notification, a comparison with the previous value must first be 133 performed in order to understand if and how the network state has 134 changed. 136 Exactly like a client that connects to a server is able to discover 137 the capabilities in terms of supported YANG modules, features, 138 deviations, and protocol capabilities; the same client must also be 139 able to discover the required per-node capabilities (also known as 140 metadata) to correctly act on the telemetry information. It forms 141 part of the API contract for managing and monitoring the device. 142 Extending the per-node capabilities specified in 143 [I-D.ietf-netconf-notification-capabilities], additional per-node 144 capabilities are required. 146 The YANG module in this document augments the ietf-system- 147 capabilities YANG module in "YANG Modules for describing System 148 Capabilities and Yang-Push Notification Capabilities" 149 [I-D.ietf-netconf-notification-capabilities]. 151 The YANG data model in this document conform to the Network 152 Management Datastore Architecture (NMDA) defined in [RFC8342]. 154 3. Concepts 156 Doing networking data collection for the sake of doing collection is 157 not useful. At the time of network automation, displaying nice 158 graphs from collected data is not useful: the collected data must be 159 acted upon immediately. Some use cases are: network availability, 160 closed loop automation (reconfiguring network based on observed 161 network state changes), service assurance 162 [I-D.claise-opsawg-service-assurance-architecture], etc. 164 Along with the capabilities specified in ietf-netconf-notification- 165 capabilities [I-D.ietf-netconf-notification-capabilities] YANG model, 166 there is some additional information that can be made available per 167 node-selector to help with this optimum collection of operational 168 data. For example, these additional metadata can help reduce the 169 load on the devices being managed along with the performance 170 improvements because of the way data is subscribed to. Some other 171 metadata can help with the collection automation itself (mapping of 172 config and oper data node, mapping of MIB oid to YANG leaf). 174 Some metadata are static and can augment the node-capabilities in 175 [I-D.ietf-netconf-notification-capabilities], for both implementation 176 time and run time environments. Other metadata are dynamic and have 177 to be derived during the run-time. They can change based on the role 178 of the device and the scale of the data being observed. 180 Per-node static metadata includes: 182 o minimum-observable-period: This is the minimum observable period 183 in nanoseconds for the node-selector. Streaming or polling more 184 frequently then this interval may not fetch useful information as 185 the node could be updated only at this frequency internally. If a 186 close loop automation system would stream or poll more frequently, 187 it could actually draw the wrong conclusions. Let's take the 188 example of interface counters than are updated more frequently 189 than 30 seconds in a distributed system. Streaming interface 190 counters every 30 seconds would see an natural increase in the 191 interface counters. However, streaming those interface counters 192 every 10 seconds could lead to the wrong conclusion that no 193 packets are received/sent on that specific interface ... 195 triggering an automatic interface troubleshooting action. Hence 196 determining the minimum-observable-period for every monitored leaf 197 is essential for closed loop automation and assurance systems. 199 o suggested-observable-period: The suggested observable period for 200 this node-selector. This value represents factory default 201 suggested information, only available at implementation time. Let 202 us assume that an assurance system would like to monitor all FIB 203 entries in the router. The router would advertise that the 204 suggested observable period is, let's say, 30 seconds. Those 5 205 seconds are the factory defaults, provided at the implementation 206 time. Once the router is in production, the observable period 207 would obviously change depending on the environment (as an 208 example, a FIB containing all BGP entries is huge): this dynamic 209 suggest observable period is called the computed-observable-period 210 and is available part of the get-measurement-metadata RPC. 212 o optimized-measurement-point: In some server design, operational 213 data are usually modeled/structured in a way that the relevant 214 data are grouped together and reside together. In most cases, it 215 is more performant to fetch this data together than as individual 216 leaves: data are structured together internally, grouped together, 217 and therefore fetched together. This feature specifies optimum 218 observable points in the model at which data can be collected and 219 streamed in an efficient way. Depending on the implementation, 220 optimum points can be leaves or a container nodes in the YANG 221 tree. This is a selection node, that means its presence for a 222 node-selector indicates it is the optimized measurement point. 224 o corresponding-mib-oid: The object identifier (OID) assigned to a 225 SMIv2 definition, corresponding to the node-selector. The object 226 identifier value is written in decimal dotted notation. Existing 227 SNMP MIBs based automations can use this information to migrate to 228 more analytics-ready YANG Modeled data. Working from a single 229 data model system (YANG-based in this case) for data collection 230 simplifies the management, as opposed to use different data 231 models. Therefore, knowing the mapping MIB OID/YANG leaf is 232 important, as transition mechanism towards YANG (for example: 233 moving away from SNMP polling to model-driven telemetry) but also 234 as a way to understand whether the same operational data is 235 metered in both the MIB and YANG worlds, adding to the load on 236 devices. Some IETF RFCs, such as the YANG Interface Management 237 [RFC8343], specify the mapping in the document. However, 238 providing this mapping directly from the server helps automation 239 from a client point of view. 241 o related-node: Data nodes that are related for closed-loop scenario 242 for data node specified in node-capabilities. In case node- 243 capabilities is an operational node then the associated node- 244 instance-identifier represents config paths directly related to 245 this operational node capabilities. In case node-capabilities is 246 an config node then the associated node-instance-identifier 247 represents operational leaf directly related to this configuration 248 node capabilities. This node is specifically interesting for non 249 NMDA [RFC8342], non openconfig YANG modules. For example, in the 250 initial YANG data model for interface management [RFC7223], which 251 is not NMDA-compliant, advertising the mapping between the admin- 252 status and the oper-status leaves would clearly simplify the 253 closed loop automation. Note that NMDA and the openconfig -state 254 container solved that issue but not all servers are NMDA compliant 255 and openconfig models don't cover all server functions. 257 A generic RPC, get-system-node-capabilities, provides the 258 capabilities for the nodes in the subtree of the input. If the input 259 node passed is a leaf/leaf-list, then all the metadata for that input 260 node are returned. If the input node is not leaf/leaf-list then the 261 RPC returns the metadata of all of its subtree nodes. 263 There is some run-time information that is very helpful for the 264 applications to know, to be able to start listening to the device 265 without adding too much additional resource strain on the device. 266 The get-measurement-metadata RPC can be used to fetch this data. 268 Per-node dynamic metadata includes, part of the get-measurement- 269 metadata RPC: 271 o optimized-measurement-point: The node-selector is searched up the 272 data tree chain to find the parent node that is the optimized 273 measurement point (if the optimized-measurement-point-feature is 274 supported). If the node-selector itself is the optimized point 275 then same data node is returned in the output. If the node- 276 selector has no optimized measurement point then this optimized- 277 measurement-point leaf is not returned. 279 o computed-observable-period: the computed observable period for 280 this node-selector (and optimized-measurement-point). The system 281 internally dynamically computes the suggested observable period 282 (relevant for polling or streaming cadence) which can be greater- 283 or-equal to the minimal-observable-period. Since this value is 284 dynamic, this metadata is only available in a run time 285 environment. 287 o active-measurements - subscribed-measurement-period: List of 288 existing subscriptions for this node-selector. If there are no 289 active subscriptions then system calculate the measurement-period 290 and this list is not-returned, else, each instance in this list 291 will be pair of active measurement with intended and actual period 292 used by the system. 294 4. Base ietf-system-node-metadata YANG module 296 4.1. Tree View 298 The following tree diagram [RFC8340] provides an overview of the 299 ietf-system-node-metadata data model. 301 module: ietf-system-node-metadata 302 augment /sysc:system-capabilities/sysc:datastore-capabilities/sysc:per-node-capabilities/sysc:node-selection/sysc:node-selector: 303 +--ro minimum-observable-period? uint64 304 +--ro suggested-observable-period? uint64 305 +--ro optimized-measurement-point? empty {optimized-measurement-point-feature}? 306 +--ro corresponding-mib-oid? yang:object-identifier-128 307 +--ro related-node? yang:node-instance-identifier 309 rpcs: 310 +---x get-measurement-metadata 311 | +---w input 312 | | +---w node-selector? yang:node-instance-identifier 313 | +--ro output 314 | +--ro optimized-measurement-point? yang:node-instance-identifier {optimized-measurement-point-feature}? 315 | +--ro computed-observable-period? uint64 316 | +--ro active-measurements* [] 317 | +--ro subscribed-measurement-period? uint64 318 +---x get-system-node-capabilities 319 +---w input 320 | +---w node-selector? yang:node-instance-identifier 321 +--ro output 322 +--ro node-selector-capability* [] 323 +--ro node? yang:node-instance-identifier 324 +--ro minimum-observable-period? uint64 325 +--ro suggested-observable-period? uint64 326 +--ro optimized-measurement-point? empty {optimized-measurement-point-feature}? 327 +--ro corresponding-mib-oid? yang:object-identifier-128 328 +--ro related-node? yang:node-instance-identifier 330 4.2. Full Tree View 332 The following tree diagram [RFC8340] provides an overview of the 333 ietf-system-capabilities and ietf-system-node-metadata data models. 335 module: ietf-system-node-metadata 337 rpcs: 338 +---x get-measurement-metadata 339 | +---w input 340 | | +---w node-selector? yang:node-instance-identifier 341 | +--ro output 342 | +--ro optimized-measurement-point? yang:node-instance-identifier {optimized-measurement-point-feature}? 343 | +--ro computed-observable-period? uint64 344 | +--ro active-measurements* [] 345 | +--ro subscribed-measurement-period? uint64 346 +---x get-system-node-capabilities 347 +---w input 348 | +---w node-selector? yang:node-instance-identifier 349 +--ro output 350 +--ro node-selector-capability* [] 351 +--ro node? yang:node-instance-identifier 352 +--ro minimum-observable-period? uint64 353 +--ro suggested-observable-period? uint64 354 +--ro optimized-measurement-point? empty {optimized-measurement-point-feature}? 355 +--ro corresponding-mib-oid? yang:object-identifier-128 356 +--ro related-node? yang:node-instance-identifier 357 module: ietf-system-capabilities 358 +--ro system-capabilities 359 +--ro datastore-capabilities* [datastore] 360 +--ro datastore -> /yanglib:yang-library/datastore/name 361 +--ro per-node-capabilities* [] 362 +--ro (node-selection)? 363 +--:(node-selector) 364 +--ro node-selector? nacm:node-instance-identifier 365 +--ro sys-metadata:minimum-observable-period? uint64 366 +--ro sys-metadata:suggested-observable-period? uint64 367 +--ro sys-metadata:optimized-measurement-point? empty {optimized-measurement-point-feature}? 368 +--ro sys-metadata:corresponding-mib-oid? yang:object-identifier-128 369 +--ro sys-metadata:related-node? yang:node-instance-identifier 371 4.3. YANG Module 373 file "ietf-system-node-metadata@2020-03-20.yang" 375 module ietf-system-node-metadata { 376 yang-version 1.1; 377 namespace "urn:ietf:params:xml:ns:yang:ietf-system-node-metadata"; 378 prefix sys-metadata; 380 import ietf-system-capabilities { 381 prefix sysc; 382 reference 383 "RFC XXXX: YANG Modules for describing System Capabilities and 384 Yang-Push Notification Capabilities"; 385 } 386 import ietf-yang-types { 387 prefix yang; 388 reference 389 "RFC XXXX: Currently draft-ietf-netmod-rfc6991-bis-04, Common 390 YANG Data types"; 391 } 393 organization 394 "IETF NETCONF (Network Configuration) Working Group"; 395 contact 396 "WG Web: 397 WG List: 399 Editor: Benoit Claise 400 402 Editor: Munish Nayyar 403 405 Editor: Adithya Reddy Sesani 406 407 "; 408 description 409 "This document proposes a YANG module that provides per-node 410 capabilities for optimum operational data collection. 412 This YANG module augments the YANG Modules for describing 413 System Capabilities and Yang-Push Notification capabilities 414 [RFC XXXX]. 416 This module defines augmented nodes to publish the 417 metadata information specific to YANG node-identifier as per 418 ietf-system-capabilities datatree. 420 Complementary RPCs, based on the same node capabilities, 421 simplify the data collection operations. 423 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 424 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 425 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 426 are to be interpreted as described in BCP 14 (RFC 2119) 427 (RFC 8174) when, and only when, they appear in all 428 capitals, as shown here. 430 Copyright (c) 2020 IETF Trust and the persons identified as 431 authors of the code. All rights reserved. 433 Redistribution and use in source and binary forms, with or 434 without modification, is permitted pursuant to, and subject 435 to the license terms contained in, the Simplified BSD License 436 set forth in Section 4.c of the IETF Trust's Legal Provisions 437 Relating to IETF Documents 438 (http://trustee.ietf.org/license-info). 440 This version of this YANG module is part of RFC XXXX 441 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 442 for full legal notices."; 444 revision 2020-03-23 { 445 description 446 "Initial version"; 447 reference 448 "RFC XXX: Per-Node Capabilities For Closed Loop Automation."; 449 } 451 feature optimized-measurement-point-feature { 452 description 453 "Support for optimized measurement point within data tree."; 454 } 456 grouping system-node-metadata-info { 457 description 458 "group of metadata properties associated to the 459 node-instance."; 460 leaf minimum-observable-period { 461 type uint64; 462 units "nanoseconds"; 463 description 464 "The minimum observable period for this node-selector. Don't 465 poll or stream more frequently that minimum observable 466 period in nanoseconds as the corresponding counter is not 467 updated more frequently."; 468 } 469 leaf suggested-observable-period { 470 type uint64; 471 units "nanoseconds"; 472 description 473 "The suggested observable period for this node-selector. 474 This value represents factory default suggested 475 information, only available at implementation time."; 476 } 477 leaf optimized-measurement-point { 478 if-feature "optimized-measurement-point-feature"; 479 type empty; 480 description 481 "This node-selector is an optimized measurement point."; 482 } 483 leaf corresponding-mib-oid { 484 type yang:object-identifier-128; 485 description 486 "The object identifier (OID) assigned to a SMIv2 definition, 487 corresponding to this node-selector."; 488 } 489 leaf related-node { 490 type yang:node-instance-identifier; 491 description 492 "In case the node instance is an operational node then the 493 associated node-instance-identifier represents the config 494 leaf directly related to this operational node. In case the 495 node instance is an config node then the associated 496 node-instance-identifier represents the operational leaf 497 directly related to this configuration node. A typical 498 example is the relationship between the admin-status and 499 oper-status, which is impossible to detect automatically in 500 a non-NMDA environment or for non-openconfig YANG moduels. 501 The related-node SHOULD NOT reported for NMDA architectures 502 and openconfig YANG modules."; 503 } 504 } 506 augment 507 "/sysc:system-capabilities/sysc:datastore-capabilities/" 508 + "sysc:per-node-capabilities/" 509 + "sysc:node-selection/sysc:node-selector" { 510 description 511 "Metadata information tied to the per-node-capabilities"; 512 uses system-node-metadata-info; 513 } 515 rpc get-measurement-metadata { 516 description 517 "RPC that returns the optimized measurement per-node 518 capabilities and some measurement parameters. This RPC 519 is added to allow clients to learn dynamically changing 520 metadata for a specific leaf on a server. 522 If the server supports the optimized-measurement-point 523 feature, then the output data refers to 524 optimized-measurement-point. The server will internally 525 find the optimized-measurement-point. If it can not find it, 526 then no output is returned (for the 527 optimized-measurement-point, computed-observable-period, 528 and active-measurements). 530 If the server doesn't support the optimized-measurement-point 531 feature, then the output data refers to input node selector."; 532 input { 533 leaf node-selector { 534 type yang:node-instance-identifier; 535 description 536 "node instance for which metadata is requested"; 537 } 538 } 539 output { 540 leaf optimized-measurement-point { 541 if-feature "optimized-measurement-point-feature"; 542 type yang:node-instance-identifier; 543 description 544 "The node-selector is searched up the data tree chain to 545 find the parent node that is the optimized measurement 546 point (if the optimized-measurement-point-feature is 547 supported). 549 If the node-selector itself is the optimized point then 550 same data node is returned in the output. 552 If the node-selector has no optimized measurement point 553 then this optimized-measurement-point leaf is not 554 returned."; 555 } 556 leaf computed-observable-period { 557 type uint64; 558 units "nanoseconds"; 559 description 560 "the computed observable period for this node-selector (and 561 optimized-measurement-point). The system internally 562 dynamically computes the suggested observable period 563 (relevant for polling or streaming cadence) which can be 564 greater-or-equal to the minimal-observable-period. 565 Since this value is dynamic, this metadata is only 566 available in a run time environment."; 567 } 568 list active-measurements { 569 description 570 "list of existing subscriptions for this node-selector. If 571 there are no active subscriptions then system calculate 572 the measurement-period and this list is not-returned, 573 else, each instance in this list will be pair of active 574 measurement with intended and actual period used by the 575 system"; 576 leaf subscribed-measurement-period { 577 type uint64; 578 units "nanoseconds"; 579 description 580 "Currently subscribed measurement period for this 581 node-selector (and optimized-measurement-point)"; 582 } 583 } 584 } 585 } 587 rpc get-system-node-capabilities { 588 description 589 "RPC to get the capabilities for the nodes in the subtree of 590 the input. 591 If the input node passed is a leaf/leaf-list, then 592 the same node metadata is returned in the output. 593 If the input node is not leaf/leaf-list then metadata of its 594 subtree nodes is returned."; 595 input { 596 leaf node-selector { 597 type yang:node-instance-identifier; 598 description 599 "node instance whose subtree which metadata is requested."; 600 } 601 } 602 output { 603 list node-selector-capability { 604 description 605 "metadata of nodes in the subtree of node-selector."; 606 leaf node { 607 type yang:node-instance-identifier; 608 description 609 "instance path of the node inside subtree of 610 node-selector."; 611 } 612 uses system-node-metadata-info; 613 } 614 } 615 } 616 } 618 620 5. Examples 622 The YANG module specified in this document defines a schema for data 623 that is designed to be accessed via network management protocols such 624 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 625 is the secure transport layer, and the mandatory-to-implement secure 626 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 627 is HTTPS, and the mandatory-to-implement secure transport is TLS 628 [RFC8446]. 630 XML data tree for the ietf-interface YANG module [RFC8343]: 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 669 Example1: Demonstrating the querying metadata for all system schema 670 nodes for the ietf-interfaces [RFC8343]. 672 673 674 675 676 677 678 679 680 682 683 684 685 686 687 ds:operational 688 689 /if:interfaces/if:interface 690 691 692 1000 693 1000 694 695 696 /if:interfaces/if:interface/if:admin-status 697 1.3.6.1.2.1.2.2.1.7 698 1000 699 1000 700 701 702 /if:interfaces/if:interface/if:oper-status 703 1.3.6.1.2.1.2.2.1.8 704 1000 705 1000 706 707 708 /if:interfaces/if:interface/if:if-index 709 1.3.6.1.2.1.2.1 710 1000 711 1000 712 713 714 /if:interfaces/if:interface/if:phys-address 715 1.3.6.1.2.1.2.2.1.6 716 1000 717 1000 718 719 720 /if:interfaces/if:interface/if:lower-layer-if 721 1.3.6.1.2.1.31.1.2.1.2 722 1000 723 1000 724 725 726 /if:interfaces/if:interface/if:higher-layer-if 727 1.3.6.1.2.1.31.1.2.1.1 728 1000 729 1000 730 731 732 /if:interfaces/if:interface/if:speed 733 1.3.6.1.2.1.2.2.1.5 734 1000 735 1000 736 737 738 /if:interfaces/if:interface/if:statistics 739 740 1.3.6.1.2.1.31.1.1 741 1000 742 1000 743 744 745 /if:interfaces/if:interface/if:statistics/if:discontinuity-time 746 747 1.3.6.1.2.1.31.1.1.1.19 748 1000 749 1000 750 751 752 /if:interfaces/if:interface/if:statistics/if:in-octets 753 1.3.6.1.2.1.2.2.1.10 754 1000 755 1000 756 757 758 /if:interfaces/if:interface/if:statistics/if:in-unicast-pkts 759 1.3.6.1.2.1.2.2.1.11 760 1000 761 1000 762 763 764 /if:interfaces/if:interface/if:statistics/if:in-multicast-pkts 765 1.3.6.1.2.1.31.1.1.1.2 766 1000 767 1000 768 769 770 /if:interfaces/if:interface/if:statistics/if:in-broadcast-pkts 771 1.3.6.1.2.1.31.1.1.1.3 772 1000 773 1000 774 775 776 /if:interfaces/if:interface/if:statistics/if:in-discards 777 1.3.6.1.2.1.2.2.1.13 778 1000 779 1000 780 781 782 /if:interfaces/if:interface/if:statistics/if:in-errors 783 1.3.6.1.2.1.2.2.1.14 784 1000 785 1000 786 787 788 /if:interfaces/if:interface/if:statistics/if:in-unknown-protos 789 1.3.6.1.2.1.2.2.1.15 790 1000 791 1000 792 793 794 /if:interfaces/if:interface/if:statistics/if:out-octets 795 1.3.6.1.2.1.2.2.1.16 796 1000 797 1000 798 799 800 /if:interfaces/if:interface/if:statistics/if:out-unicast-pkts 801 1.3.6.1.2.1.2.2.1.17 802 1000 803 1000 804 805 806 /if:interfaces/if:interface/if:statistics/if:out-multicast-pkts 807 1.3.6.1.2.1.31.1.1.1.4 808 1000 809 1000 810 811 812 /if:interfaces/if:interface/if:statistics/if:out-broadcast-pkts 813 1.3.6.1.2.1.31.1.1.1.5 814 1000 815 1000 816 817 818 /if:interfaces/if:interface/if:statistics/if:out-discards 819 1.3.6.1.2.1.2.2.1.19 820 1000 821 1000 822 823 824 /if:interfaces/if:interface/if:statistics/if:out-errors 825 1.3.6.1.2.1.2.2.1.20 826 1000 827 1000 828 829 830 831 832 834 Example2: Demonstrating the querying metadata of all optimized- 835 measurement-point(s). Use containment and selection nodes filtering 836 criteria to express which all metadata you want. In this example: 837 get query filter only to "select" the node-instance-identifier, 838 optimized-measurement-point nodes, for the ietf-interfaces [RFC8343]. 839 There are two optimized-measurement-points: interface and statistics. 841 842 843 844 845 846 847 ds:operational 848 849 850 851 852 853 854 856 858 859 860 861 862 ds:operational 863 864 /if:interfaces/if:interface 865 866 867 868 /if:interfaces/if:interface/if:statistics 869 870 871 872 873 874 876 Example3: Demonstrating the usage of RPC to query the device for 877 computed-measurement-period and the subscribed-measurement-period(s) 878 for the in-errors YANG leaf. 880 882 883 884 /if:interfaces/if:interface/if:statistics/if:in-errors 885 886 888 889 890 /if:interfaces/if:interface/if:statistics 891 3000 892 893 1000 894 895 896 1000 897 898 899 1000 900 901 903 6. Security Considerations 905 The YANG module specified in this document defines a schema for data 906 that is designed to be accessed via network management protocols such 907 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 908 is the secure transport layer, and the mandatory-to-implement secure 909 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 910 is HTTPS, and the mandatory-to-implement secure transport is TLS 911 [RFC8446]. 913 The Network Configuration Access Control Model (NACM) [RFC8341] 914 provides the means to restrict access for particular NETCONF or 915 RESTCONF users to a preconfigured subset of all available NETCONF or 916 RESTCONF protocol operations and content. 918 7. IANA Considerations 920 7.1. The IETF XML Registry 922 This document registers two URIs in the IETF XML registry [RFC3688]. 923 Following the format in [RFC3688], the following registrations are 924 requested: 926 URI: urn:ietf:params:xml:ns:yang:ietf-system-node-metadata 927 Registrant Contact: The NETCONF WG of the IETF. 928 XML: N/A, the requested URI is an XML namespace. 930 8. Open Issues 932 "related-node" should be split into two: "related-config-node" and 933 "related-state-node"? 935 Explain how to use the RPC from the client side, along with the 936 different options. 938 Expand on the active measurement use case 940 nanosecond: an overkill? 942 security considerations: see https://trac.ietf.org/trac/ops/wiki/ 943 yang-security-guidelines 945 9. References 947 9.1. Normative References 949 [I-D.ietf-netconf-notification-capabilities] 950 Lengyel, B., Clemm, A., and B. Claise, "YANG Modules for 951 describing System Capabilities and Yang-Push Notification 952 Capabilities", draft-ietf-netconf-notification- 953 capabilities-13 (work in progress), March 2020. 955 [I-D.ietf-netmod-rfc6991-bis] 956 Schoenwaelder, J., "Common YANG Data Types", draft-ietf- 957 netmod-rfc6991-bis-04 (work in progress), July 2020. 959 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 960 Requirement Levels", BCP 14, RFC 2119, 961 DOI 10.17487/RFC2119, March 1997, 962 . 964 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 965 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 966 May 2017, . 968 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 969 Access Control Model", STD 91, RFC 8341, 970 DOI 10.17487/RFC8341, March 2018, 971 . 973 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 974 E., and A. Tripathy, "Subscription to YANG Notifications", 975 RFC 8639, DOI 10.17487/RFC8639, September 2019, 976 . 978 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 979 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 980 September 2019, . 982 9.2. Informative References 984 [I-D.claise-opsawg-service-assurance-architecture] 985 Claise, B., Quilbeuf, J., Fathi, Y., Lopez, D., and D. 986 Voyer, "Service Assurance for Intent-based Networking 987 Architecture", draft-claise-opsawg-service-assurance- 988 architecture-03 (work in progress), July 2020. 990 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 991 DOI 10.17487/RFC3688, January 2004, 992 . 994 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 995 and A. Bierman, Ed., "Network Configuration Protocol 996 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 997 . 999 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1000 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1001 . 1003 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1004 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1005 . 1007 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1008 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1009 . 1011 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1012 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1013 . 1015 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1016 and R. Wilton, "Network Management Datastore Architecture 1017 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1018 . 1020 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1021 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1022 . 1024 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1025 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1026 . 1028 Acknowledgements 1030 The authors would like to thank ... for their reviews and feedback. 1032 Authors' Addresses 1034 Benoit Claise 1035 Cisco Systems, Inc. 1036 De Kleetlaan 6a b1 1037 1831 Diegem 1038 Belgium 1040 Email: bclaise@cisco.com 1042 Munish Nayyar 1043 Cisco Systems, Inc. 1044 Milpitas 1045 California 1046 United States 1048 Email: mnayyar@cisco.com 1050 Adithya Reddy Sesani 1051 Cisco Systems, Inc. 1052 Milpitas 1053 California 1054 United States 1056 Email: adithyas@cisco.com