idnits 2.17.1 draft-tao-netmod-yang-node-tags-00.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 18 instances of too long lines in the document, the longest one being 9 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 -- The document date (November 2, 2019) is 1638 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 107, but not defined Summary: 2 errors (**), 0 flaws (~~), 2 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: May 5, 2020 November 2, 2019 7 YANG Data Node Self Explanation Tags 8 draft-tao-netmod-yang-node-tags-00 10 Abstract 12 This document defines a method to tag data node associated with 13 telemetry data in YANG Modules. This YANG data node tagging method 14 can be used to filter queries of operational state on a server during 15 a "pub/sub" service for YANG datastore updates when the state of all 16 subscriptions of a particular Subscriber to be fetched is huge, so 17 that the amount of data to be streamed out to the destination can be 18 greatly reduced. 20 An extension statement to be used to indicate YANG data node tags 21 that SHOULD be added by the module implementation automatically(i.e., 22 outside of configuration). 24 A YANG module [RFC7950] is defined, which augment Module tag model 25 and provides a list of data node entries to allow for adding or 26 removing of data node tags as well as viewing the set of tags 27 associated with a YANG module. 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 May 5, 2020. 46 Copyright Notice 48 Copyright (c) 2019 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Use cases for Data Node tags . . . . . . . . . . . . . . 3 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 66 2. Data Node Tag Values . . . . . . . . . . . . . . . . . . . . 4 67 2.1. IETF Tags Prefix . . . . . . . . . . . . . . . . . . . . 4 68 2.2. Vendor Tags Prefix . . . . . . . . . . . . . . . . . . . 4 69 2.3. User Tags Prefix . . . . . . . . . . . . . . . . . . . . 5 70 2.4. Reserved Tags Prefix . . . . . . . . . . . . . . . . . . 5 71 3. Data Node Tag Management . . . . . . . . . . . . . . . . . . 5 72 3.1. Module Design Tagging . . . . . . . . . . . . . . . . . . 5 73 3.2. Implementation Tagging . . . . . . . . . . . . . . . . . 5 74 3.3. User Tagging . . . . . . . . . . . . . . . . . . . . . . 5 75 4. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 6 76 4.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 6 77 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6 78 6. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 9 79 6.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 9 80 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 81 7.1. YANG Data Node Tag Prefixes Registry . . . . . . . . . . 9 82 7.2. IETF YANG Data Node Tags Registry . . . . . . . . . . . . 10 83 7.3. Updates to the IETF XML Registry . . . . . . . . . . . . 11 84 7.4. Updates to the YANG Module Names Registry . . . . . . . . 11 85 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 86 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 87 9.1. Normative References . . . . . . . . . . . . . . . . . . 12 88 9.2. Informative References . . . . . . . . . . . . . . . . . 13 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 91 1. Introduction 93 As described [I.D-ietf-netmod-module-tags], the use of tags for 94 classification and organization is fairly ubiquitous not only within 95 IETF protocols, but in the internet itself(e.g., "#hashtags"). A 96 module tag defined in [I.D-ietf-netmod-module-tags] is a string 97 associated only with a module name at module level. 99 This document define data node tag and associate them with data node 100 within YANG modules. The data node tags can be learnt dynamically by 101 the client from the live server and used to filter queries of 102 configuration or operational state on a server based on these data 103 node tags,.e.g.,return specific object type operational state related 104 to system-management. NETCONF clients can discover data models with 105 data nod tags supported by a NETCONF server via 106 operation. The data node tag capability can also be advertised via 107 Capability Notification Model [I-D.netconf-notification-capabilities] 108 by the NETCONF server or some place where offline document are kept. 109 These tags may be registered as well as assigned during the module 110 definition; assigned by implementations; or dynamically defined and 111 set by users. 113 This document defines a YANG module [RFC7950] which augments Module 114 tag model and provides a list of data node entries to allow for 115 adding or removing of tags as well as viewing the set of tags 116 associated with a data node within YANG modules. 118 This document defines an extension statement to be used to indicate 119 tags that SHOULD be added by the module implementation automatically 120 (i.e., outside of configuration). 122 The YANG data model in this document conforms to the Network 123 Management Datastore Architecture defined in [RFC8342]. 125 1.1. Use cases for Data Node tags 127 The following is a list of already implemented and potential use 128 cases. 130 One example use of data node tags would be to help filter different 131 discrete categories of YANG data node within YANG modules supported 132 by a device. For example, if data nodes within YANG modules are 133 suitably tagged and learnt by the client from a live server, then an 134 XPath query can be used by the client to list all of the performance 135 related data nodes supported by a device. 137 Data node tags can also be used to help coordination when clients are 138 interacting with large amount of devices with the same categories of 139 YANG data node across different YANG modules. For example, one 140 management client could mark some specific data node across modules 141 implemented in various different devices with the same performance- 142 metric tag, so all the devices can provide consistent representation 143 and reporting for the same category of YANG data nodes. 145 Future management protocol extensions could allow for filtering 146 queries of configuration or operational state on a server based on 147 tags. For example, return all operational state related to system- 148 management. 150 1.2. Terminology 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 154 "OPTIONAL" in this document are to be interpreted as described in BCP 155 14 [RFC2119] [RFC8174] when, and only when, they appear in all 156 capitals, as shown here. 158 2. Data Node Tag Values 160 All data node tags SHOULD begin with a prefix indicating who owns 161 their definition. An IANA registry (Section 7.1) is used to support 162 registering data node tag prefixes. Currently 3 prefixes are 163 defined. 165 No further structure is imposed by this document on the value 166 following the registered prefix, and the value can contain any YANG 167 type 'string' characters except carriage-returns, newlines and tabs. 168 Therefore, designers, implementers, and users are free to add or not 169 add any structure they may require to their own tag values. 171 2.1. IETF Tags Prefix 173 An IETF tag is a data node tag that has the prefix "ietf:dn:". All 174 IETF data node tags are registered with IANA in a registry defined 175 later in this document (Section 7.2). 177 2.2. Vendor Tags Prefix 179 A vendor tag is a tag that has the prefix "vendor:dn:". These tags 180 are defined by the vendor that implements the module, and are not 181 registered; however, it is RECOMMENDED that the vendor include extra 182 identification in the tag to avoid collisions such as using the 183 enterpise or organization name following the "vendor:dn:" prefix 184 (e.g., vendor:dn:vendor-defined-classifier). 186 2.3. User Tags Prefix 188 A user tag is any tag that has the prefix "user:dn:". These tags are 189 defined by the user/administrator and are not meant to be registered. 190 Users are not required to use the "user:dn:" prefix; however, doing 191 so is RECOMMENDED as it helps avoid prefix collisions. 193 2.4. Reserved Tags Prefix 195 Any tag not starting with the prefix "ietf:dn:", "vendor:dn:" or 196 "user:dn:" is reserved for future use. These tag values are not 197 invalid, but simply reserved in the context of specifications (e.g., 198 RFCs). 200 3. Data Node Tag Management 202 Tags can become associated with a data node within YANG module in a 203 number of ways. Tags may be defined and associated at module design 204 time, at implementation time without the need of live server, or via 205 user administrative control . As the main consumer of data node tags 206 are users, users may also remove any tag from a live server, no 207 matter how the tag became associated with a data node within a YANG 208 module. 210 3.1. Module Design Tagging 212 A data node definition MAY indicate a set of data node tags to be 213 added by the module implementer. These design time tags are 214 indicated using the node-tag extension statement. 216 If the data node is defined in an IETF standards track document, the 217 data node tags MUST be IETF Tags (2.1). Thus, new data node can 218 drive the addition of new IETF tags to the IANA registry defined in 219 Section 7.2, and the IANA registry can serve as a check against 220 duplication. 222 3.2. Implementation Tagging 224 An implementation MAY include additional tags associated with data 225 node within a YANG module. These tags SHOULD be IETF Tags (i.e., 226 registered) or vendor specific tags. 228 3.3. User Tagging 230 Data node tags of any kind, with or without a prefix, can be assigned 231 and removed by the user from a live server using normal configuration 232 mechanisms. In order to remove a data node tag from the operational 233 datastore the user adds a matching "masked-tag" entry for a given 234 data node within the ietf-data-node-tags Module. 236 4. Tags Module Structure 238 4.1. Tags Module Tree 240 The tree associated with the "ietf-data-node-tags" module follows. 241 The meaning of the symbols can be found in [RFC8340]. 243 module: ietf-data-node-tags 244 augment /tags:module-tags/tags:module: 245 +--rw data-node-tags 246 +--rw data-node* [node-name] 247 +--rw node-name nacm:node-instance-identifier 248 +--rw tag* tags:tag 249 +--rw masked-tag* tags:tag 250 +--rw group-id string 252 5. YANG Module 254 file "ietf-data-node-tags@2019-05-03.yang" 255 module ietf-data-node-tags { 256 yang-version 1.1; 257 namespace "urn:ietf:params:xml:ns:yang:ietf-data-node-tags"; 258 prefix ntags; 260 import ietf-yang-types { prefix yang; } 261 import ietf-netconf-acm { prefix nacm; } 262 import ietf-module-tags { prefix tags; } 263 organization 264 "IETF NetMod Working Group (NetMod)"; 265 contact 266 "WG Web: 267 WG List: 269 Author: Ran Tao 270 271 Author: Qin Wu 272 "; 274 // RFC Ed.: replace XXXX with actual RFC number and 275 // remove this note. 277 description 278 "This module describes a mechanism associating tags with YANG data 279 node within YANG modules. Tags may be IANA assigned or privately defined. 280 Copyright (c) 2018 IETF Trust and the persons identified as 281 authors of the code. All rights reserved. 283 Redistribution and use in source and binary forms, with or 284 without modification, is permitted pursuant to, and subject to 285 the license terms contained in, the Simplified BSD License set 286 forth in Section 4.c of the IETF Trust's Legal Provisions 287 Relating to IETF Documents 288 (https://trustee.ietf.org/license-info). 290 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 291 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 292 'MAY', and 'OPTIONAL' in this document are to be interpreted as 293 described in BCP 14 [RFC2119] [RFC8174] when, and only when, 294 they appear in all capitals, as shown here. 296 This version of this YANG module is part of RFC XXXX 297 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 298 full legal notices."; 300 // RFC Ed.: update the date below with the date of RFC publication 301 // and RFC number and remove this note. 303 revision 2019-05-03 { 304 description 305 "Initial revision."; 306 reference "RFC XXXX: YANG Data Node Tags"; 307 } 308 typedef node-tag { 309 type string { 310 length "1..max"; 311 pattern '[\S ]+'; 312 } 313 description 314 "A tag is a type 'string' value that does not include carriage 315 return, newline or tab characters. It SHOULD begin with a 316 registered prefix; however, tags without a registered prefix 317 SHOULD NOT be treated as invalid."; 318 } 319 extension node-tag { 320 argument node-tag; 321 description 322 "The argument 'tag' is of type 'tag'. This extension statement 323 is used by module authors to indicate the data node tags that SHOULD be 324 added automatically by the system. As such the origin of the 325 value for the pre-defined tags should be set to 'system' 326 [RFC8342]."; 327 } 329 augment "/tags:module-tags/tags:module" { 330 description 331 "Augment the Tags module with data node tag attributes"; 332 container data-node-tags { 333 description 334 "Contains the list of data nodes and their associated tags"; 335 list data-node { 336 key "node-name"; 337 description 338 "A list of modules and their associated tags"; 339 leaf node-name { 340 type nacm:node-instance-identifier; 341 mandatory true; 342 description 343 "The YANG module name."; 344 } 345 leaf-list node-tag { 346 type node-tag; 347 description 348 "Tags associated with the data node within YANG module. See 349 the IANA 'YANG Data Node Tag Prefixes' registry for reserved 350 prefixes and the IANA'IETF YANG Data Node Tags' registry for 351 IETF tags. 353 The 'operational' state [RFC8342] view of this list is 354 constructed using the following steps: 356 1) System tags (i.e., tags of 'system' origin) are added. 357 2) User configured tags (i.e., tags of 'intended' origin) 358 are added. 359 3) Any tag that is equal to a masked-tag is removed."; 360 } 361 leaf-list node-masked-tag { 362 type node-tag; 363 description 364 "The list of tags that should not be associated with this 365 data node. The user can remove (mask) tags from the 366 operational state datastore [RFC8342] by adding them to 367 this list. It is not an error to add tags to this list 368 that are not associated with the data node within the module, 369 but they have no operational effect."; 370 } 371 leaf group-id { 372 type string; 373 description 374 "This group ID is used to identify a set of data nodes 375 of the same group which have a common characteristic."; 376 } 377 } 378 } 379 } 380 } 381 383 6. Guidelines to Model Writers 385 This section updates [RFC8407]. 387 6.1. Define Standard Tags 389 A module MAY indicate, using node-tag extension statements, a set of 390 tags that are to be automatically associated with it (i.e., not added 391 through configuration). 393 module example-module { 394 //... 395 import module-tags { prefix tags; } 396 container top { 397 ntags:node-tag "ietf:dn:object-type"; 398 list X { 399 ntags:node-tag "ietf:dn:property"; 400 } 401 container Y { 402 ntags:node-tag "ietf:dn:performance-metric"; 403 } 404 } 405 // ... 406 } 408 The module writer can use existing standard tags, or use new tags 409 defined in the model definition, as appropriate. For IETF 410 standardized modules new data node tags MUST be assigned in the IANA 411 registry defined below, see Section 7.2. 413 7. IANA Considerations 415 7.1. YANG Data Node Tag Prefixes Registry 417 IANA is asked to create a new registry "YANG Data Node Tag Prefixes" 418 grouped under a new "Protocol" category named "YANG Data Node Tag 419 Prefixes". 421 This registry allocates tag prefixes. All YANG data node tags SHOULD 422 begin with one of the prefixes in this registry. 424 Prefix entries in this registry should be short strings consisting of 425 lowercase ASCII alpha-numeric characters and a final ":" character. 427 The allocation policy for this registry is Specification Required 428 [RFC8126]. The Reference and Assignee values should be sufficient to 429 identify and contact the organization that has been allocated the 430 prefix. 432 The initial values for this registry are as follows. 434 +----------+----------------------------------+-----------+----------+ 435 | Prefix | Description | Reference | Assignee | 436 +----------+----------------------------------+-----------+----------+ 437 | ietf:dn: | IETF Tags allocated in the IANA | [This | IETF | 438 | | IETF YANG Data Node Tags registry| document] | | 439 | | | | | 440 |vendor:dn:| Non-registered tags allocated by | [This | IETF | 441 | | the module implementer. | document] | | 442 | | | | | 443 | user:dn: | Non-registered tags allocated by | [This | IETF | 444 | | and for the user. | document] | | 445 +----------+----------------------------------+-----------+----------+ 447 Other standards organizations (SDOs) wishing to allocate their own 448 set of tags should allocate a prefix from this registry. 450 7.2. IETF YANG Data Node Tags Registry 452 IANA is asked to create a new registry "IETF YANG Module Tags" 453 grouped under a new "Protocol" category "IETF YANG Module Tags". 454 This registry should be included below "YANG Module Tag Prefixes" 455 when listed on the same page. 457 This registry allocates tags that have the registered prefix "ietf:". 458 New values should be well considered and not achievable through a 459 combination of already existing IETF tags. 461 The allocation policy for this registry is IETF Review [RFC8126]. 463 The initial values for this registry are as follows. 465 +----------------------------+--------------------------+-----------+ 466 | Tag | Description | Reference | 467 +----------------------------+--------------------------+-----------+ 468 | | | | 469 | ietf:dn:object-type | Relates to object type | [This | 470 | | (e.g., interfaces). | document] | 471 | | | | 472 | ietf:dn:performance-metric | Relates to performance | [This | 473 | | metric | document] | 474 | | (e.g., ifstatistics). | | 475 | | | | 476 | ietf:dn:property | Represents a object | [This | 477 | | property | document] | 478 | | (e.g.,ifindex). | | 479 | | | | 480 |ietf:dn:statistics-operation| Relates to statistics | [This | 481 | | operation(e.g.,average, | document] | 482 | | min, max, sum,etc) | | 483 +----------------------------+--------------------------+-----------+ 485 7.3. Updates to the IETF XML Registry 487 This document registers a URI in the "IETF XML Registry" [RFC3688]. 488 Following the format in [RFC3688], the following registration has 489 been made: 491 URI: 492 urn:ietf:params:xml:ns:yang:ietf-data-node-tags 494 Registrant Contact: 495 The IESG. 497 XML: 498 N/A; the requested URI is an XML namespace. 500 7.4. Updates to the YANG Module Names Registry 502 This document registers one YANG module in the "YANG Module Names" 503 registry [RFC6020]. Following the format in [RFC6020], the following 504 registration has been made: 506 name: 507 ietf-data-node-tags 509 namespace: 510 urn:ietf:params:xml:ns:yang:ietf-data-node-tags 512 prefix: 513 tags 515 reference: 516 RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove 517 this note.) 519 8. Security Considerations 521 The YANG module defined in this memo is designed to be accessed via 522 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 523 secure transport layer and the mandatory-to-implement secure 524 transport is SSH [RFC6242]. 526 This document adds the ability to associate data node tag meta-data 527 with YANG modules. This document does not define any actions based 528 on these associations, and none are yet defined, and therefore it 529 does not by itself introduce any new security considerations. 531 Users of the data node tag-meta data may define various actions to be 532 taken based on the data node tag meta-data. These actions and their 533 definitions are outside the scope of this document. Users will need 534 to consider the security implications of any actions they choose to 535 define. 537 9. References 539 9.1. Normative References 541 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 542 Requirement Levels", BCP 14, RFC 2119, 543 DOI 10.17487/RFC2119, March 1997, 544 . 546 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 547 RFC 7950, DOI 10.17487/RFC7950, August 2016, 548 . 550 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 551 Writing an IANA Considerations Section in RFCs", BCP 26, 552 RFC 8126, DOI 10.17487/RFC8126, June 2017, 553 . 555 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 556 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 557 May 2017, . 559 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 560 and R. Wilton, "Network Management Datastore Architecture 561 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 562 . 564 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 565 Documents Containing YANG Data Models", BCP 216, RFC 8407, 566 DOI 10.17487/RFC8407, October 2018, 567 . 569 9.2. Informative References 571 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 572 DOI 10.17487/RFC3688, January 2004, 573 . 575 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 576 the Network Configuration Protocol (NETCONF)", RFC 6020, 577 DOI 10.17487/RFC6020, October 2010, 578 . 580 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 581 and A. Bierman, Ed., "Network Configuration Protocol 582 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 583 . 585 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 586 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 587 . 589 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 590 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 591 . 593 Authors' Addresses 595 Ran Tao 596 Huawei 598 Email: taoran20@huawei.com 599 Qin Wu 600 Huawei 601 101 Software Avenue, Yuhua District 602 Nanjing, Jiangsu 210012 603 China 605 Email: bill.wu@huawei.com