idnits 2.17.1 draft-tao-netmod-yang-node-tags-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 32 instances of too long lines in the document, the longest one being 11 characters in excess of 72. ** The abstract seems to contain references ([RFC7950]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 211 has weird spacing: '...latency tunne...' == Line 213 has weird spacing: '...et-loss tunne...' == Line 215 has weird spacing: '...latency tunne...' == Line 217 has weird spacing: '...latency tunne...' == Line 219 has weird spacing: '...-packet tun...' == (8 more instances...) -- The document date (March 6, 2020) is 1510 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'I-D.netconf-notification-capabilities' is mentioned on line 139, but not defined Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group R. Tao 3 Internet-Draft Q. Wu 4 Intended status: Standards Track Huawei 5 Expires: September 7, 2020 B. Claise 6 Cisco 7 L. Geng 8 Z. Du 9 China Mobile 10 March 6, 2020 12 YANG Data Node Self Explanation Tags 13 draft-tao-netmod-yang-node-tags-01 15 Abstract 17 This document defines a method to tag data node associated with 18 telemetry data in YANG Modules. This YANG data node tagging method 19 can be used to provide input, instruction, indication to selection 20 filter and filter queries of operational state on a server during a 21 "pub/sub" service for YANG datastore updates and provide multiple 22 dimensional network visibility analysis when the state of all 23 subscriptions of a particular Subscriber to be fetched is huge, so 24 that the amount of data to be streamed out to the destination can be 25 greatly reduced and only targeted to the characteristics data. 27 An extension statement to be used to indicate YANG data node self 28 explanation tags that SHOULD be added by the module implementation 29 automatically (i.e., outside of configuration). 31 A YANG module [RFC7950] is defined, which augments Module tag model 32 and provides a list of data node entries to allow for adding or 33 removing of data node self explanation tags as well as viewing the 34 set of self explanation tags associated with a YANG module. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on September 7, 2020. 53 Copyright Notice 55 Copyright (c) 2020 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 1.1. Data Node tags Use Cases . . . . . . . . . . . . . . . . 4 72 1.1.1. Multiple Dimensional Performance Measurement 73 Information Tagging . . . . . . . . . . . . . . . . . 4 74 1.1.2. Correlated Information Tagging . . . . . . . . . . . 7 75 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 76 2. Data Node Tag Values . . . . . . . . . . . . . . . . . . . . 8 77 2.1. IETF Tags Prefix . . . . . . . . . . . . . . . . . . . . 8 78 2.2. Vendor Tags Prefix . . . . . . . . . . . . . . . . . . . 8 79 2.3. User Tags Prefix . . . . . . . . . . . . . . . . . . . . 8 80 2.4. Reserved Tags Prefix . . . . . . . . . . . . . . . . . . 8 81 3. Data Node Tag Management . . . . . . . . . . . . . . . . . . 9 82 3.1. Module Design Tagging . . . . . . . . . . . . . . . . . . 9 83 3.2. Implementation Tagging . . . . . . . . . . . . . . . . . 9 84 3.3. User Tagging . . . . . . . . . . . . . . . . . . . . . . 9 85 4. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 9 86 4.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 9 87 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 10 88 6. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 18 89 6.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 19 90 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 91 7.1. YANG Data Node Tag Prefixes Registry . . . . . . . . . . 19 92 7.2. IETF YANG Data Node Tags Registry . . . . . . . . . . . . 20 93 7.3. Updates to the IETF XML Registry . . . . . . . . . . . . 25 94 7.4. Updates to the YANG Module Names Registry . . . . . . . . 25 95 8. Security Considerations . . . . . . . . . . . . . . . . . . . 25 96 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 97 9.1. Normative References . . . . . . . . . . . . . . . . . . 26 98 9.2. Informative References . . . . . . . . . . . . . . . . . 26 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 101 1. Introduction 103 As described [I.D-ietf-netmod-module-tags], the use of tags for 104 classification and organization is fairly ubiquitous not only within 105 IETF protocols, but in the internet itself (e.g., "#hashtags"). A 106 module tag defined in [I.D-ietf-netmod-module-tags] is a string 107 associated only with a module name at module level. 109 At the time of writing this document (2020), there are many data 110 models that have been specified or are being specified by the IETF. 111 They cover many of the networking protocols and techniques. However 112 data objects defined by these technology specific data models might 113 represent a portion of fault, configuration, accounting, performance, 114 security the management categories information (e.g., performance 115 metric associated with data object type) in many different way, lack 116 the same classification criteria and granularity,e.g., sensor data in 117 hardware model is defined with fine granularity with value scale and 118 value precision while interface model only provides statistics data 119 for specific interface type. 121 This document defines data node self explanation tags and associates 122 them with data nodes within YANG module, which 124 o Provide dictionary meaning for each data node; 126 o Indicate relationship between data nodes within the same YANG 127 module or of different YANG modules; 129 o Identify specific service or feature, network element; 131 The data node self explanation tags can be used by the client to 132 provide input, instruction, indication to selection filter and filter 133 queries of configuration or operational state on a server based on 134 these data node tags,.e.g.,return specific object type operational 135 state related to system-management. NETCONF clients can discover 136 data models with data node self explanation tags supported by a 137 NETCONF server via operation. The data node self 138 explanation tag capability can also be advertised via capability 139 notification Model [I-D.netconf-notification-capabilities] by the 140 NETCONF server or some place where offline document are kept. These 141 self explanation tags may be registered as well as assigned during 142 the module definition; assigned by implementations; or dynamically 143 defined and set by users. 145 This document defines a YANG module [RFC7950] which augments module 146 tag model and provides a list of data node entries to allow for 147 adding or removing of self explanation tags as well as viewing the 148 set of self explanation tags associated with a data node within YANG 149 modules. 151 This document defines an extension statement to be used to indicate 152 self explanation tags that SHOULD be added by the module 153 implementation automatically (i.e., outside of configuration). 155 The YANG data model in this document conforms to the Network 156 Management Datastore Architecture defined in [RFC8342]. 158 1.1. Data Node tags Use Cases 160 The following is a list of already implemented and potential use 161 cases. 163 1.1.1. Multiple Dimensional Performance Measurement Information Tagging 165 Data node tags can be used to express multiple dimensional 166 performance metric and properties associated with YANG data nodes or 167 data objects modelled with YANG (See Figure 1). 169 ----- ----- 170 // \\ // \\ 171 | Property+------+ +-------+ Property| 172 \\ A // | | \\ B // 173 -----+ +--V----------------V---+ ----- 174 | YANG Data Node | 175 | /Data Object | 176 /---\ +--^----------------^---+ /---\ 177 / \ | | / \ 178 |Metric +-------+ +--------|Metric | 179 \ A / +-------------+ \ B / 180 \-+-/ | | \-+-/ 181 | | Metric Group| | 182 -------------| |--------------- 183 +-------------+ 185 Figure 1 187 The use of data node tags would be to help filter different discrete 188 categories of YANG data nodes across YANG modules supported by a 189 device. If data nodes across YANG modules are suitably tagged and 190 learnt by the client from a live server, then an XPath query can be 191 used by the client to list all related data nodes supported by a 192 device with the same characteristics. Data node tags can also be 193 used to help coordination when clients are interacting with various 194 different devices with the same categories of YANG data node across 195 different YANG modules. For example, one management client could 196 mark some specific data node across modules implemented in various 197 different devices with the same metric group tag, so consistent 198 representation and reporting can be provided for YANG data nodes 199 belonging to the same metric group (see Figure 2). 201 +-----------+---------------+-----------+-----------------------+ 202 | Object | Property | Metric | Metric Module | 203 | Name | Name | Group | Name | 204 | | | | | 205 |tunnel-svc | name | - | - tunnel | 206 | | | | | 207 |tunnel-svc | create-time | - | - tunnel | 208 | | | | | 209 |tunnel-svc | modified-time | - | - | 210 | | | | | 211 |tunnel-svc | - |lsp-ping-pm| avg-latency tunnel-pm| 212 | | | | | 213 |tunnel-svc | - |lsp-ping-pm| packet-loss tunnel-pm| 214 | | | | | 215 |tunnel-svc | - |lsp-ping-pm| min-latency tunnel-pm| 216 | | | | | 217 |tunnel-svc | - |lsp-ping-pm| max-latency tunnel-pm| 218 | | | |transmitted | 219 |tunnel-svc | - |lsp-ping-pm| -packet tunnel-pm| 220 +-----------+---------------+-----------+-----------------------+ 222 +---------------------------------------------------------+ 223 | Metric Metric Metric Metric Metric | 224 | Group Name Precision Scale Unit | 225 | | 226 | lsp-ping-pm avg- 1 1 ms | 227 | latency | 228 | | 229 | lsp-ping-pm packet- 1 1 percentile | 230 | loss | 231 | | 232 | | 233 | lsp-ping-pm min- 1 1 ms | 234 | latency | 235 | | 236 | | 237 | lsp-ping-pm max- 1 1 ms | 238 | latency | 239 | | 240 | | 241 | lsp-ping-pm transmitted 1 1 | 242 +---------------------------------------------------------+ 244 Figure 2 246 1.1.2. Correlated Information Tagging 248 Another example is the management client could mark some data node 249 across different level of YANG modules implemented in the device, the 250 management system with the same service tag (e.g., L3VPN Service), so 251 root cause can be identified efficiently during service-level 252 agreements and performance monitoring or network failure 253 troubleshooting. 255 +--------------+ 256 | Parent object| 257 +-------^------+ 258 | 259 ----- +-----+-----+ ----- 260 // \\ |Service Tag| // \\ 261 | Property+------+ ++--------+-+ +-------+ Property| 262 \\ A // | | | | \\ B // 263 -----+ +--V---V-+ +-V---V--+ ----- 264 | Child | | Child | 265 |ObjectA | |ObjectB | 266 /---\ +--^-----+ +-----^--+ /---\ 267 / \ | | / \ 268 |Metric +-------+ +--------|Metric | 269 \ A / \ B / 270 \---/ \---/ 272 +-----------------------------------------------------------+ 273 | Service Metric Metric Module Level | 274 | Tag Group Name | 275 | | 276 | L3VPN L3VPN maximum L3VPN Service | 277 | -routes | 278 | | 279 | L3VPN OSPF-Process total-active OSPF Device | 280 | routes | 281 | | 282 | total-active | 283 | L3VPN RIP-Process routes RIP Device | 284 | | 285 | total-active | 286 | L3VPN BGP-Process routes BGP Device | 287 | | 288 +-----------------------------------------------------------+ 290 1.2. Terminology 292 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 293 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 294 "OPTIONAL" in this document are to be interpreted as described in BCP 295 14 [RFC2119] [RFC8174] when, and only when, they appear in all 296 capitals, as shown here. 298 2. Data Node Tag Values 300 All data node tags SHOULD begin with a prefix indicating who owns 301 their definition. An IANA registry (Section 7.1) is used to support 302 registering data node tag prefixes. Currently 3 prefixes are 303 defined. 305 No further structure is imposed by this document on the value 306 following the registered prefix, and the value can contain any YANG 307 type 'string' characters except carriage-returns, newlines and tabs. 308 Therefore, designers, implementers, and users are free to add or not 309 add any structure they may require to their own tag values. 311 2.1. IETF Tags Prefix 313 An IETF tag is a data node tag that has the prefix "ietf:". All IETF 314 data node tags are registered with IANA in a registry defined later 315 in this document (Section 7.2). 317 2.2. Vendor Tags Prefix 319 A vendor tag is a tag that has the prefix "vendor:". These tags are 320 defined by the vendor that implements the module, and are not 321 registered; however, it is RECOMMENDED that the vendor include extra 322 identification in the tag to avoid collisions such as using the 323 enterpise or organization name following the "vendor:" prefix (e.g., 324 vendor:vendor-defined-classifier). 326 2.3. User Tags Prefix 328 A user tag is any tag that has the prefix "user:". These tags are 329 defined by the user/administrator and are not meant to be registered. 330 Users are not required to use the "user:" prefix; however, doing so 331 is RECOMMENDED as it helps avoid prefix collisions. 333 2.4. Reserved Tags Prefix 335 Any tag not starting with the prefix "ietf:", "vendor:" or "user:" is 336 reserved for future use. These tag values are not invalid, but 337 simply reserved in the context of specifications (e.g., RFCs). 339 3. Data Node Tag Management 341 Tags can become associated with a data node within YANG module in a 342 number of ways. Tags may be defined and associated at module design 343 time, at implementation time without the need of live server, or via 344 user administrative control . As the main consumer of data node tags 345 are users, users may also remove any tag from a live server, no 346 matter how the tag became associated with a data node within a YANG 347 module. 349 3.1. Module Design Tagging 351 A data node definition MAY indicate a set of data node tags to be 352 added by the module implementer. These design time tags are 353 indicated using the node-tag extension statement. 355 If the data node is defined in an IETF standards track document, the 356 data node tags MUST be IETF Tags (2.1). Thus, new data node can 357 drive the addition of new IETF tags to the IANA registry defined in 358 Section 7.2, and the IANA registry can serve as a check against 359 duplication. 361 3.2. Implementation Tagging 363 An implementation MAY include additional tags associated with data 364 node within a YANG module. These tags SHOULD be IETF Tags (i.e., 365 registered) or vendor specific tags. 367 3.3. User Tagging 369 Data node tags of any kind, with or without a prefix, can be assigned 370 and removed by the user from a live server using normal configuration 371 mechanisms. In order to remove a data node tag from the operational 372 datastore, the user adds a matching "masked-tag" entry for a given 373 data node within the ietf-data-node-tags Module. 375 4. Tags Module Structure 377 4.1. Tags Module Tree 379 The tree associated with the "ietf-data-node-tags" module follows. 380 The meaning of the symbols can be found in [RFC8340]. 382 module: ietf-data-node-tags 383 augment /tags:module-tags/tags:module: 384 +--rw self-explanation-node-tags 385 +--rw self-explanation-node* [node-name] 386 +--rw node-name nacm:node-instance-identifier 387 +--rw metric-precision tags:tag 388 +--rw metric-scale tags:tag 389 +--rw operation-type tags:tag 390 +--rw parent-grouping tags:tag 391 +--rw data-source-type tags:tag 392 +--rw opm-tag tags:tag 393 +--rw service-tag* tags:tag 394 +--rw task-tag* tags:tag 395 +--rw correlate-group-id string 397 5. YANG Module 399 file "ietf-self-explanation-node-tags@2019-05-03.yang" 400 module ietf-data-node-tags { 401 yang-version 1.1; 402 namespace "urn:ietf:params:xml:ns:yang:ietf-self-explanation-node-tags"; 403 prefix ntags; 404 import ietf-netconf-acm { prefix nacm; } 405 import ietf-module-tags { prefix tags; } 406 organization 407 "IETF NetMod Working Group (NetMod)"; 408 contact 409 "WG Web: 410 WG List: 411 Author: Ran Tao 412 413 Author: Qin Wu 414 "; 416 // RFC Ed.: replace XXXX with actual RFC number and 417 // remove this note. 419 description 420 "This module describes a mechanism associating self-explanation 421 tags with YANG data node within YANG modules. Tags may be IANA 422 assigned or privately defined. 424 Copyright (c) 2018 IETF Trust and the persons identified as 425 authors of the code. All rights reserved. 427 Redistribution and use in source and binary forms, with or 428 without modification, is permitted pursuant to, and subject to 429 the license terms contained in, the Simplified BSD License set 430 forth in Section 4.c of the IETF Trust's Legal Provisions 431 Relating to IETF Documents 432 (https://trustee.ietf.org/license-info). 434 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 435 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 436 'MAY', and 'OPTIONAL' in this document are to be interpreted as 437 described in BCP 14 [RFC2119] [RFC8174] when, and only when, 438 they appear in all capitals, as shown here. 440 This version of this YANG module is part of RFC XXXX 441 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 442 full legal notices."; 444 // RFC Ed.: update the date below with the date of RFC publication 445 // and RFC number and remove this note. 447 revision 2019-05-03 { 448 description 449 "Initial revision."; 450 reference "RFC XXXX: YANG Data Node Tags"; 451 } 452 typedef tag { 453 type string { 454 length "1..max"; 455 pattern '[a-zA-Z_][a-zA-Z0-9\-_]*:[\S ]+'; 456 } 457 description 458 "A tag value is composed of a standard prefix followed by any type 459 'string' value that does not include carriage return, newline or 460 tab characters."; 461 } 462 typedef measurement-precision { 463 type int8 { 464 range "-8 .. 9"; 465 } 466 description 467 "A node using this data type represents a sensor value 468 precision range. 470 A node of this type SHOULD be defined together with nodes of 471 type measurement-units and type measurement-scale. Together, 472 associated nodes of these three types are used to identify the 473 semantics of a node of type sensor-value. 475 If a node of this type contains a value in the range 1 to 9, 476 it represents the number of decimal places in the fractional 477 part of an associated sensor-value fixed-point number. 479 If a node of this type contains a value in the range -8 to -1, 480 it represents the number of accurate digits in the associated 481 sensor-value fixed-point number. 483 The value zero indicates the associated sensor-value node is 484 not a fixed-point number. 486 Server implementers must choose a value for the associated 487 sensor-value-precision node so that the precision and accuracy 488 of the associated sensor-value node is correctly indicated. 490 For example, a component representing a temperature sensor 491 that can measure 0 to 100 degrees C in 0.1 degree 492 increments, +/- 0.05 degrees, would have a 493 sensor-value-precision value of '1', a sensor-value-scale 494 value of 'units', and a sensor-value ranging from '0' to 495 '1000'. The sensor-value would be interpreted as 496 'degrees C * 10'."; 497 reference 498 "RFC 3433: Entity Sensor Management Information Base - 499 EntitySensorPrecision"; 500 } 502 typedef measurement-scale { 503 type enumeration { 504 enum yocto { 505 value 1; 506 description 507 "Measurement scaling factor of 10^-24."; 508 } 509 enum zepto { 510 value 2; 511 description 512 "Measurement scaling factor of 10^-21."; 513 } 514 enum atto { 515 value 3; 516 description 517 "Measurement scaling factor of 10^-18."; 518 } 519 enum femto { 520 value 4; 521 description 522 "Measurement scaling factor of 10^-15."; 523 } 524 enum pico { 525 value 5; 526 description 527 "Measurement scaling factor of 10^-12."; 528 } 529 enum nano { 530 value 6; 531 description 532 "Measurement scaling factor of 10^-9."; 533 } 534 enum micro { 535 value 7; 536 description 537 "Measurement scaling factor of 10^-6."; 538 } 539 enum milli { 540 value 8; 541 description 542 "Measurement scaling factor of 10^-3."; 543 } 544 enum units { 545 value 9; 546 description 547 "Measurement scaling factor of 10^0."; 548 } 549 enum kilo { 550 value 10; 551 description 552 "Measurement scaling factor of 10^3."; 553 } 554 enum mega { 555 value 11; 556 description 557 "Measurement scaling factor of 10^6."; 558 } 559 enum giga { 560 value 12; 561 description 562 "Measurement scaling factor of 10^9."; 563 } 564 enum tera { 565 value 13; 566 description 567 "Measurement scaling factor of 10^12."; 568 } 569 enum peta { 570 value 14; 571 description 572 "Measurement scaling factor of 10^15."; 573 } 574 enum exa { 575 value 15; 576 description 577 "Measurement scaling factor of 10^18."; 578 } 579 enum zetta { 580 value 16; 581 description 582 "Measurement scaling factor of 10^21."; 583 } 584 enum yotta { 585 value 17; 586 description 587 "Measurement scaling factor of 10^24."; 588 } 589 } 590 description 591 "A node using this data type represents a data scaling factor, 592 represented with an International System of Units (SI) prefix. 593 The actual data units are determined by examining a node of 594 this type together with the associated sensor-value-type. 596 A node of this type SHOULD be defined together with nodes of 597 type sensor-value-type and type sensor-value-precision. 598 Together, associated nodes of these three types are used to 599 identify the semantics of a node of type sensor-value."; 600 reference 601 "RFC 3433: Entity Sensor Management Information Base - 602 EntitySensorDataScale"; 603 } 605 identity measurement-unit { 606 description 607 "Base identity for measurement unit."; 608 } 610 identity ac-volts { 611 base measurement-unit; 612 description 613 "Identity for a measure of electric potential (alternating current)."; 614 } 615 identity dc-volts { 616 base measurement-unit; 617 description 618 "Identity for a measure of electric potential (direct current)."; 619 } 620 identity amperes { 621 base measurement-unit; 622 description 623 "Identity for a measure of electric current."; 624 } 625 identity power { 626 base measurement-unit; 627 description 628 "Identity for a measure of power."; 629 } 630 identity hertz { 631 base measurement-unit; 632 description 633 "Identity for a measure of frequency."; 634 } 635 identity celsius { 636 base measurement-unit; 637 description 638 "Identity for a measure of temperature."; 639 } 640 identity rpm { 641 base measurement-unit; 642 description 643 "Identity for a measure of shaft revolutions per minute."; 644 } 645 extension metric-scale{ 646 argument tag; 647 description 648 "The argument 'tag' is of type 'tag'.The metric-scale can be 649 used to provide an additional metric scale (e.g., Measurement 650 scaling factor of 10^0, 10^-3,10^3) information associated with 651 the performance metric data node tag."; 652 } 653 extension metric-precision { 654 argument tag; 655 description 656 "The argument 'tag' is of type 'tag'.The metric-precision can be 657 used to provide an additional metric precision (e.g., the range -8 to -1, 658 0, the range 1 to 9) information associated with the performance metric 659 data node tag."; 660 } 662 extension statistics-operation { 663 argument tag; 664 description 665 "The argument 'tag' is of type 'tag'.The statistics-operation can be 666 used to provide an additional statistics operation type(e.g., sum, 667 min, max,last) information associated with the performance metric 668 data node tag."; 669 } 670 extension data-source-type{ 671 argument tag; 672 description 673 "The argument 'tag' is of type 'tag'.The data-source-type can be 674 used to provide an additional data source type (e.g., connectivity, 675 resource, hardware,qos,policy) information associated with 676 the performance metric data node tag."; 677 } 678 extension membership-tag { 679 argument tag; 680 description 681 "The argument 'tag' is of type 'tag'.The membership-tag can be 682 used to provide an additional multiple source aggregation 683 information associated with the performance metric data node 684 or interface related data node."; 685 } 686 extension service-tag { 687 argument tag; 688 description 689 "The argument 'tag' is of type 'tag'.The service-tag can be 690 used to provide a service classification information (e.g., tunnel, 691 l3vpn,l2vpn) information associated with YANG data node."; 692 } 694 extension task-tag { 695 argument tag; 696 description 697 "The argument 'tag' is of type 'tag'.The task-tag can be 698 used to provide a task classification information (e.g., fault management, 699 performance measurement) information associated with YANG data node."; 700 } 702 extension opm-tag { 703 argument tag; 704 description 705 "The argument 'tag' is of type 'tag'. This extension statement 706 is used by module authors to indicate the opm tags that SHOULD be 707 added automatically by the system. As such the origin of the 708 value for the pre-defined tags should be set to 'system' 709 [RFC8342]."; 710 } 712 augment "/tags:module-tags/tags:module" { 713 description 714 "Augment the Tags module with data node tag attributes"; 715 container self-explanation-node-tags { 716 description 717 "Contains the list of data nodes and their associated tags"; 718 list self-explanation-node { 719 key "node-name"; 720 description 721 "A list of self-explanation nodes and their associated tags"; 722 leaf node-name { 723 type nacm:node-instance-identifier; 724 mandatory true; 725 description 726 "The YANG data node name."; 727 } 728 leaf metric-precision { 729 type tags:tag; 730 description 731 "The numeric expression precision of performance 732 metric related data node."; 733 } 734 leaf metric-unit { 735 type tags:tag; 736 description 737 "The measurement unit of performance 738 metric related data node."; 739 } 740 leaf metric-scale { 741 type tags:tag; 742 description 743 "The measurement scale of performance 744 metric related data node."; 745 } 746 leaf operation-type{ 747 type tags:tag; 748 description 749 "Statistics operation of performance metric related 750 data node."; 751 } 752 leaf data-source-type { 753 type tags:tag; 754 description 755 "The data source type with the data node within YANG module."; 756 } 757 leaf parent-grouping { 758 type tags:tag; 759 description 760 "The parent-grouping tag can be used to identify multiple source 761 (e.g., line card,member link in an aggregated Ethernet 762 interface) related to performance metric related data node 763 or interface related to data node."; 764 } 765 leaf opm-tag { 766 type tags:tag; 767 description 768 "Tags associated with the data node within YANG module. See 769 the IANA 'YANG Data Node Tag Prefixes' registry for reserved 770 prefixes and the IANA'IETF YANG Data Node Tags' registry for 771 IETF tags. 773 The 'operational' state [RFC8342] view of this list is 774 constructed using the following steps: 776 1) System tags (i.e., tags of 'system' origin) are added. 777 2) User configured tags (i.e., tags of 'intended' origin) 778 are added. 779 3) Any tag that is equal to a masked-tag is removed."; 780 } 781 leaf service-tag { 782 type tags:tag; 783 description 784 "The node-service-tag can be used to provide a service 785 classification information (e.g., tunnel, l3vpn,l2vpn) 786 information associated with YANG data node."; 787 } 788 leaf task-tag { 789 type tags:tag; 790 description 791 "The node-task-tag can be used to provide a task 792 classification information (e.g., fault management, 793 performance measurement) information associated with 794 YANG data node."; 795 } 796 leaf correlate-group-id { 797 type string; 798 description 799 "This group ID is used to to correlate 800 data nodes within the same YANG module or of different YANG modules."; 801 } 802 } 803 } 804 } 805 } 806 808 6. Guidelines to Model Writers 810 This section updates [RFC8407]. 812 6.1. Define Standard Tags 814 A module MAY indicate, using node-tag extension statements, a set of 815 tags that are to be automatically associated with it (i.e., not added 816 through configuration). 818 module example-module { 819 //... 820 import ietf-data-node-tags { prefix ntags; } 821 container top { 822 ntags:opm-tag "ietf:object-type"; 823 list X { 824 ntags:opm-tag "ietf:property"; 825 } 826 container Y { 827 ntags:opm-tag "ietf:metric"; 828 ntags:statistics-operation "ietf:avg"; 829 ntags:metric-scale "ietf:milli"; 830 } 831 } 832 // ... 833 } 835 The module writer can use existing standard tags, or use new tags 836 defined in the model definition, as appropriate. For IETF 837 standardized modules new data node tags MUST be assigned in the IANA 838 registry defined below, see Section Section 7.2. 840 7. IANA Considerations 842 7.1. YANG Data Node Tag Prefixes Registry 844 IANA is asked to create a new registry "YANG Data Node Tag Prefixes" 845 grouped under a new "Protocol" category named "YANG Data Node Tag 846 Prefixes". 848 This registry allocates tag prefixes. All YANG data node tags SHOULD 849 begin with one of the prefixes in this registry. 851 Prefix entries in this registry should be short strings consisting of 852 lowercase ASCII alpha-numeric characters and a final ":" character. 854 The allocation policy for this registry is Specification Required 855 [RFC8126]. The Reference and Assignee values should be sufficient to 856 identify and contact the organization that has been allocated the 857 prefix. 859 The initial values for this registry are as follows. 861 +----------+----------------------------------+-----------+----------+ 862 | Prefix | Description | Reference | Assignee | 863 +----------+----------------------------------+-----------+----------+ 864 | ietf: | IETF Tags allocated in the IANA | [This | IETF | 865 | | IETF YANG Data Node Tags registry| document] | | 866 | | | | | 867 |vendor: | Non-registered tags allocated by | [This | IETF | 868 | | the module implementer. | document] | | 869 | | | | | 870 | user: | Non-registered tags allocated by | [This | IETF | 871 | | and for the user. | document] | | 872 +----------+----------------------------------+-----------+----------+ 874 Other standards organizations (SDOs) wishing to allocate their own 875 set of tags should allocate a prefix from this registry. 877 7.2. IETF YANG Data Node Tags Registry 879 IANA is asked to create four new registries "IETF YANG Data Node 880 Tags","IETF Metric Precision Tags","IETF Statistics Operation 881 Tags","Node Service Tag" grouped under a new "Protocol" category 882 "IETF YANG Data Node Tags". These four registries should be included 883 below "YANG Data Node Tag Prefixes" when listed on the same page. 885 Four registries allocate tags that have the registered prefix 886 "ietf:". New values should be well considered and not achievable 887 through a combination of already existing IETF tags. 889 The allocation policy for these four registries is IETF Review 890 [RFC8126]. 892 The initial values for these eight registries are as follows. 894 +----------------------------+--------------------------+-----------+ 895 | Data Node Tag | Description | Reference | 896 +----------------------------+--------------------------+-----------+ 897 | | | | 898 | ietf:object-type | Relates to object type | [This | 899 | | (e.g., interfaces). | document] | 900 | | | | 901 | ietf:metric | Relates to performance | [This | 902 | | metric info | document] | 903 | | (e.g., ifstatistics). | | 904 | | | | 905 | ietf:metric-group | Represent metric group | [This | 906 | | (e.g., flow statistics). | document] | 907 | | | | 908 | ietf:property | Represents a object | [This | 909 | | property | document] | 910 | | (e.g.,ifindex). | | 911 +----------------------------+--------------------------+-----------+ 912 +----------------------------+--------------------------+-----------+ 913 | Metric Precision | Description | Reference | 914 +----------------------------+--------------------------+-----------+ 915 |ietf:minus-eight |Relates to metric precision [This | 916 | | of performance metric | document] | 917 | | | | 918 |ietf:minus-seven |Relates to metric precision [This | 919 | | of performance metric | document] | 920 | | | | 921 |ietf:minus-sixe |Relates to metric precision [This | 922 | | of performance metric | document] | 923 | | | | 924 |ietf:minus-five |Relates to metric precision [This | 925 | | of performance metric | document] | 926 | | | | 927 |ietf:minus-four |Relates to metric precision [This | 928 | | of performance metric | document] | 929 | | | | 930 |ietf:minus-three |Relates to metric precision [This | 931 | | of performance metric | document] | 932 | | | | 933 |ietf:minus-two |Relates to metric precision [This | 934 | | of performance metric | document] | 935 | | | | 936 |ietf:minus-one |Relates to metric precision [This | 937 | | of performance metric | document] | 938 | | | | 939 |ietf:zero |Relates to metric precision [This | 940 | | of performance metric | document] | 941 | | | | 942 |ietf:one |Relates to metric precision [This | 943 | | of performance metric | document] | 944 | | | | 945 |ietf:two |Relates to metric precision [This | 946 | | of performance metric | document] | 947 | | | | 948 |ietf:three |Relates to metric precision [This | 949 | | of performance metric | document] | 950 | | | | 951 |ietf:four | Relates to metric precision [This | 952 | | of performance metric | document] | 953 | | | | 954 |ietf:five | Relates to metric precision [This | 955 | | of performance metric | document] | 956 | | | | 957 |ietf:six | Relates to metric precision [This | 958 | | of performance metric | document] | 959 | | | | 960 |ietf:seven | Relates to metric precision [This | 961 | | of performance metric | document] | 962 | | | | 963 |ietf:eight | Relates to metric precision [This | 964 | | of performance metric | document] | 965 | | | | 966 |ietf:nine | Relates to metric precision [This | 967 | | of performance metric | document] | 968 +----------------------------+--------------------------+-----------+ 969 +----------------------------+--------------------------+-----------+ 970 | Metric scale | Description | Reference | 971 +----------------------------+--------------------------+-----------+ 972 |ietf:yocto | Relates to metric scale | [This | 973 | | of performance metric | document] | 974 | | | | 975 |ietf:zepto | Relates to metric scale | [This | 976 | | of performance metric | document] | 977 | | | | 978 |ietf:atto | Relates to metric scale | [This | 979 | | of performance metric | document] | 980 | | | | 981 |ietf: femto | Relates to metric scale | [This | 982 | | of performance metric | document] | 983 | | | | 984 |ietf: pico | Relates to metric scale | [This | 985 | | of performance metric | document] | 986 | | | | 987 |ietf: nano | Relates to metric scale | [This | 988 | | of performance metric | document] | 989 | | | | 990 |ietf: micro | Relates to metric scale | [This | 991 | | of performance metric | document] | 992 | | | | 993 |ietf: milli | Relates to metric scale | [This | 994 | | of performance metric | document] | 995 | | | | 996 |ietf: units | Relates to metric scale | [This | 997 | | of performance metric | document] | 998 | | | | 999 |ietf: kilo | Relates to metric scale | [This | 1000 | | of performance metric | document] | 1001 | | | | 1002 |ietf: mega | Relates to metric scale | [This | 1003 | | of performance metric | document] | 1004 | | | | 1005 |ietf: giga | Relates to metric scale | [This | 1006 | | of performance metric | document] | 1007 | | | | 1008 |ietf: tera | Relates to metric scale | [This | 1009 | | of performance metric | document] | 1010 | | | | 1011 |ietf: peta | Relates to metric scale | [This | 1012 | | of performance metric | document] | 1013 | | | | 1014 |ietf: exa | Relates to metric scale | [This | 1015 | | of performance metric | document] | 1016 | | | | 1017 |ietf: zetta | Relates to metric scale | [This | 1018 | | of performance metric | document] | 1019 | | | | 1020 |ietf: yotta | Relates to metric scale | [This | 1021 | | of performance metric | document] | 1022 +----------------------------+--------------------------+-----------+ 1023 +----------------------------+--------------------------+-----------+ 1024 | Statistics Operation Tag | Description | Reference | 1025 +----------------------------+--------------------------+-----------+ 1026 |ietf:avg | Relates to statistics | [This | 1027 | | operation(e.g.,average, | document] | 1028 | | min, max, sum,etc) | | 1029 |ietf:min | Relates to statistics | [This | 1030 | | operation(e.g.,average, | document] | 1031 | | min, max, sum,etc) | | 1032 |ietf:max | Relates to statistics | [This | 1033 | | operation(e.g.,average, | document] | 1034 | | min, max, sum,etc) | | 1035 |ietf:threshold | Relates to statistics | [This | 1036 | | operation(e.g.,average, | document] | 1037 | | min, max, threshold,etc) | | 1038 +----------------------------+--------------------------+-----------+ 1040 +----------------------------+--------------------------+-----------+ 1041 | Parent Grouping | Description | Reference | 1042 +----------------------------+--------------------------+-----------+ 1043 |ietf:lag |Relates to multiple source| [This | 1044 | |aggregation(e.g.,LAG) | document] | 1045 | | | | 1046 |ietf:lag |Relates to multiple source| [This | 1047 | |aggregation(e.g.,linecard)| document] | 1048 +----------------------------+--------------------------+-----------+ 1049 +----------------------------+--------------------------+-----------+ 1050 | Data source Type | Description | Reference | 1051 +----------------------------+--------------------------+-----------+ 1052 | | | | 1053 | ietf:service-flow | Relates to data source | [This | 1054 | | type(e.g., microburst). | document] | 1055 | | | | 1056 | ietf:topo | Relates to data source | [This | 1057 | | type(e.g., topology). | document] | 1058 | | | | 1059 | ietf:resource | Relates to data source | [This | 1060 | | type info | document] | 1061 | | (e.g., interface,queue). | | 1062 | | | | 1063 | ietf:policy | Relates to data source | [This | 1064 | | type info | document] | 1065 | |(e.g., acl, routing policy| | 1066 | | | | 1067 | ietf:hardware | Relates to data source | [This | 1068 | | type | document] | 1069 | | (e.g.,optical module). | | 1070 +----------------------------+--------------------------+-----------+ 1071 +----------------------------+--------------------------+-----------+ 1072 | Service Tag | Description | Reference | 1073 +----------------------------+--------------------------+-----------+ 1074 |ietf:l3vpn | Relates to service | [This | 1075 | | offering(e.g.,l3vpn | document] | 1076 | | l2vpn,tunnel,etc) | | 1077 |ietf:l2vpn | Relates to service | [This | 1078 | | offering(e.g.,l3vpn | document] | 1079 | | l2vpn,tunnel,etc) | | 1080 |ietf:te-tunnel | Relates to service | [This | 1081 | | offering(e.g.,l3vpn | document] | 1082 | | l2vpn,tunnel,etc) | | 1083 +----------------------------+--------------------------+-----------+ 1084 +----------------------------+--------------------------+-----------+ 1085 | Task Tag | Description | Reference | 1086 +----------------------------+--------------------------+-----------+ 1087 |ietf:vpn-diag | Relates to vpn serivce | [This | 1088 | | diagonostic function | document] | 1089 | | | | 1090 |ietf:vpn-fullfilment | Relates to vpn service | [This | 1091 | | fullfillment function | document] | 1092 | | | | 1093 |ietf:vpn-assurance | Relates to vpn service | [This | 1094 | | assurance function | document] | 1095 +----------------------------+--------------------------+-----------+ 1097 7.3. Updates to the IETF XML Registry 1099 This document registers a URI in the "IETF XML Registry" [RFC3688]. 1100 Following the format in [RFC3688], the following registration has 1101 been made: 1103 URI: 1104 urn:ietf:params:xml:ns:yang:ietf-data-node-tags 1105 Registrant Contact: 1106 The IESG. 1107 XML: 1108 N/A; the requested URI is an XML namespace. 1110 7.4. Updates to the YANG Module Names Registry 1112 This document registers one YANG module in the "YANG Module Names" 1113 registry [RFC6020]. Following the format in [RFC6020], the following 1114 registration has been made: 1116 name: 1117 ietf-data-node-tags 1118 namespace: 1119 urn:ietf:params:xml:ns:yang:ietf-data-node-tags 1120 prefix: 1121 tags 1122 reference: 1123 RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove 1124 this note.) 1126 8. Security Considerations 1128 The YANG module defined in this memo is designed to be accessed via 1129 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1130 secure transport layer and the mandatory-to-implement secure 1131 transport is SSH [RFC6242]. 1133 This document adds the ability to associate data node tag meta-data 1134 with YANG modules. This document does not define any actions based 1135 on these associations, and none are yet defined, and therefore it 1136 does not by itself introduce any new security considerations. 1138 Users of the data node tag-meta data may define various actions to be 1139 taken based on the data node tag meta-data. These actions and their 1140 definitions are outside the scope of this document. Users will need 1141 to consider the security implications of any actions they choose to 1142 define. 1144 9. References 1146 9.1. Normative References 1148 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1149 Requirement Levels", BCP 14, RFC 2119, 1150 DOI 10.17487/RFC2119, March 1997, 1151 . 1153 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1154 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1155 . 1157 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1158 Writing an IANA Considerations Section in RFCs", BCP 26, 1159 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1160 . 1162 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1163 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1164 May 2017, . 1166 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1167 and R. Wilton, "Network Management Datastore Architecture 1168 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1169 . 1171 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1172 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1173 DOI 10.17487/RFC8407, October 2018, 1174 . 1176 9.2. Informative References 1178 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1179 DOI 10.17487/RFC3688, January 2004, 1180 . 1182 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1183 the Network Configuration Protocol (NETCONF)", RFC 6020, 1184 DOI 10.17487/RFC6020, October 2010, 1185 . 1187 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1188 and A. Bierman, Ed., "Network Configuration Protocol 1189 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1190 . 1192 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1193 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1194 . 1196 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1197 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1198 . 1200 Authors' Addresses 1202 Ran Tao 1203 Huawei 1205 Email: taoran20@huawei.com 1207 Qin Wu 1208 Huawei 1209 101 Software Avenue, Yuhua District 1210 Nanjing, Jiangsu 210012 1211 China 1213 Email: bill.wu@huawei.com 1215 Benoit Claise 1216 Cisco 1217 De Kleetlaan 6a b1 1218 Diegem 1831 1219 Belgium 1221 Email: bclaise@cisco.com 1223 Liang Geng 1224 China Mobile 1225 32 Xuanwumen West St, Xicheng District 1226 Beijing 10053 1228 Email: gengliang@chinamobile.com 1230 Zongpeng Du 1231 China Mobile 1232 32 Xuanwumen West St, Xicheng District 1233 Beijing 10053 1235 Email: duzongpeng@chinamobile.com