idnits 2.17.1 draft-ietf-netmod-module-tags-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 2, 2019) is 1882 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Hopps 3 Internet-Draft LabN Consulting, L.L.C. 4 Updates: 8407 (if approved) L. Berger 5 Intended status: Standards Track LabN Consulting, LLC. 6 Expires: September 3, 2019 D. Bogdanovic 7 Volta Networks 8 March 2, 2019 10 YANG Module Tags 11 draft-ietf-netmod-module-tags-06 13 Abstract 15 This document provides for the association of tags with YANG modules. 16 The expectation is for such tags to be used to help classify and 17 organize modules. A method for defining, reading and writing a 18 modules tags is provided. Tags may be standardized and assigned 19 during module definition; assigned by implementations; or dynamically 20 defined and set by users. This document also provides guidance to 21 future model writers, as such, this document updates RFC8407. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on September 3, 2019. 40 Copyright Notice 42 Copyright (c) 2019 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Some possible use cases of YANG module tags . . . . . . . 3 59 1.2. Conventions Used in This Document . . . . . . . . . . . . 4 60 2. Tag Values . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 2.1. IETF Standard Tags . . . . . . . . . . . . . . . . . . . 4 62 2.2. Vendor Tags . . . . . . . . . . . . . . . . . . . . . . . 4 63 2.3. User Tags . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.4. Reserved Tags . . . . . . . . . . . . . . . . . . . . . . 5 65 3. Tag Management . . . . . . . . . . . . . . . . . . . . . . . 5 66 3.1. Module Definition Tagging . . . . . . . . . . . . . . . . 5 67 3.2. Implementation Tagging . . . . . . . . . . . . . . . . . 5 68 3.3. User Tagging . . . . . . . . . . . . . . . . . . . . . . 5 69 4. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 5 70 4.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 5 71 4.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 6 72 5. Other Classifications . . . . . . . . . . . . . . . . . . . . 8 73 6. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 8 74 6.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 8 75 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 76 7.1. YANG Module Tag Prefixes Registry . . . . . . . . . . . . 9 77 7.2. YANG Module Tags Registry . . . . . . . . . . . . . . . . 10 78 7.3. Updates to the IETF XML Registry . . . . . . . . . . . . 11 79 7.4. Updates to the YANG Module Names Registry . . . . . . . . 11 80 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 81 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 82 9.1. Normative References . . . . . . . . . . . . . . . . . . 12 83 9.2. Informative References . . . . . . . . . . . . . . . . . 12 84 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 13 85 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 14 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 88 1. Introduction 90 The use of tags for classification and organization is fairly 91 ubiquitous not only within IETF protocols, but in the internet itself 92 (e.g., "#hashtags"). One benefit of using tags for organization over 93 a rigid structure is that it is more flexible and can more easily 94 adapt over time as technologies evolve. Tags can be usefully 95 standardized, but they can also serve as a non-standardized mechanism 96 available for users to define themselves. This document provides a 97 mechanism to define tags and associate them with YANG modules in a 98 flexible manner. In particular, tags may be standardized as well as 99 assigned during module definition; assigned by implementations; or 100 dynamically defined and set by users. 102 This document defines a YANG module [RFC7950] which provides a list 103 of module entries to allow for adding or removing of tags as well as 104 viewing the set of tags associated with a module. 106 This document defines an extension statement to be used to indicate 107 tags that SHOULD be added by the module implementation automatically 108 (i.e., outside of configuration). 110 This document also defines an IANA registry for tag prefixes as well 111 as a set of globally assigned tags. 113 Section 6 provides guidelines for authors of YANG data models. 115 This document updates [RFC8407]. 117 The YANG data model in this document conforms to the Network 118 Management Datastore Architecture defined in [RFC8342]. 120 1.1. Some possible use cases of YANG module tags 122 During this documents progression there were requests for example 123 uses of module tags. The following are a few example use cases for 124 tags. This list is certainly not exhaustive. 126 One example use of tags would be to help filter different discrete 127 categories of YANG modules supported by a device. E.g., if modules 128 are suitably tagged, then an XPath query can be used to list all of 129 the vendor modules supported by a device. 131 Tags can also be used to help coordination when multiple semi- 132 independent clients are interacting with the same devices. E.g., one 133 management client could mark that some modules should not be used 134 because they have not been verified to behave correctly, so that 135 other management clients avoid querying the data associated with 136 those modules. 138 Tag classification is useful for users searching module repositories 139 (e.g. YANG catalog). A query restricted to the 'ietf:routing' 140 module tag could be used to return only the IETF YANG modules 141 associated with routing. Without tags, a user would need to know the 142 name of all the IETF routing protocol YANG modules. 144 Future management protocol extensions could allow for filtering 145 queries of configuration or operational state on a server based on 146 tags. E.g., return all operational state related to system- 147 management. 149 1.2. Conventions Used in This Document 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 153 "OPTIONAL" in this document are to be interpreted as described in 154 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, 155 as shown here. 157 2. Tag Values 159 All tags SHOULD begin with a prefix indicating who owns their 160 definition. An IANA registry is used to support standardizing tag 161 prefixes Section 7.1. Currently 3 prefixes are defined with all 162 others reserved. No further structure is imposed by this document on 163 the value following the standard prefix, and the value can contain 164 any yang type 'string' characters except carriage-returns, newlines 165 and tabs. 167 Again, except for the conflict-avoiding prefix, this document is not 168 specifying any structure on (i.e., restricting) the tag values on 169 purpose. The intent is to avoid arbitrarily restricting the values 170 that designers, implementers and users can use. As a result of this 171 choice, designers, implementers, and users are free to add or not add 172 any structure they may require to their own tag values. 174 2.1. IETF Standard Tags 176 An IETF standard tag is a tag that has the prefix "ietf:". All IETF 177 standard tags are registered with IANA in a registry defined later in 178 this document Section 7.2. 180 2.2. Vendor Tags 182 A vendor tag is a tag that has the prefix "vendor:". These tags are 183 defined by the vendor that implements the module, and are not 184 standardized; however, it is RECOMMENDED that the vendor include 185 extra identification in the tag to avoid collisions such as using the 186 enterpise or organization name follwing the "vendor:" prefix (e.g., 187 vendor:example.com:vendor-defined-classifier). 189 2.3. User Tags 191 A user tag is any tag that has the prefix "user:". These tags are 192 defined by the user/administrator and will never be standardized. 194 2.4. Reserved Tags 196 Any tag not starting with the prefix "ietf:", "vendor:" or "user:" is 197 reserved for future standardization. 199 3. Tag Management 201 Tags can become associated with a module in a number of ways. Tags 202 may be defined and associated at module design time, at 203 implementation time, or via user administrative control. As the main 204 consumer of tags are users, users may also remove any tag, no matter 205 how the tag became associated with a module. 207 3.1. Module Definition Tagging 209 A module definition MAY indicate a set of tags to be added by the 210 module implementer. These design time tags are indicated using the 211 module-tag extension statement. 213 If the module definition is IETF standards track, the tags MUST also 214 be Section 2.1. Thus, new modules can drive the addition of new 215 standard tags to the IANA registry, and the IANA registry can serve 216 as a check against duplication. 218 3.2. Implementation Tagging 220 An implementation MAY include additional tags associated with a 221 module. These tags SHOULD be standard or vendor specific tags. 223 3.3. User Tagging 225 Tags of any kind can be assigned and removed by the user using normal 226 configuration mechanisms. 228 4. Tags Module Structure 230 4.1. Tags Module Tree 232 The tree associated with the "ietf-module-tags" module follows. The 233 meaning of the symbols can be found in [RFC8340]. 235 module: ietf-module-tags 236 +--rw module-tags 237 +--rw module* [name] 238 +--rw name yang:yang-identifier 239 +--rw tag* tag 240 +--rw masked-tag* tag 242 4.2. YANG Module 244 file "ietf-module-tags@2019-03-02.yang" 245 module ietf-module-tags { 246 yang-version 1.1; 247 namespace "urn:ietf:params:xml:ns:yang:ietf-module-tags"; 248 prefix tags; 250 import ietf-yang-types { 251 prefix yang; 252 } 254 organization 255 "IETF NetMod Working Group (NetMod)"; 256 contact 257 "NetMod Working Group - "; 259 // RFC Ed.: replace XXXX with actual RFC number and 260 // remove this note. 262 description 263 "This module describes a mechanism associating tags with YANG 264 modules. Tags may be IANA assigned or privately defined. 266 Copyright (c) 2018 IETF Trust and the persons identified as 267 authors of the code. All rights reserved. 269 Redistribution and use in source and binary forms, with or 270 without modification, is permitted pursuant to, and subject to 271 the license terms contained in, the Simplified BSD License set 272 forth in Section 4.c of the IETF Trust's Legal Provisions 273 Relating to IETF Documents 274 (https://trustee.ietf.org/license-info). 276 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 277 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 278 'MAY', and 'OPTIONAL' in this document are to be interpreted as 279 described in BCP 14 [RFC2119] [RFC8174] when, and only when, 280 they appear in all capitals, as shown here. 282 This version of this YANG module is part of RFC XXXX 283 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 284 full legal notices."; 286 // RFC Ed.: update the date below with the date of RFC publication 287 // and RFC number and remove this note. 289 revision 2019-03-02 { 290 description 291 "Initial revision."; 292 reference "RFC XXXX: YANG Module Tags"; 293 } 295 typedef tag { 296 type string { 297 length "1..max"; 298 pattern '[a-zA-Z_][a-zA-Z0-9\-_]*:[\S ]+'; 299 } 300 description 301 "A tag value is composed of a standard prefix followed by any 302 type 'string' value that does not include carriage return, 303 newline or tab characters."; 304 } 306 extension module-tag { 307 argument tag; 308 description 309 "The argument 'tag' is of type 'tag'. This extension statement 310 is used by module authors to indicate the tags that SHOULD be 311 added automatically by the system. As such the origin of the 312 value for the pre-defined tags should be set to 'system'."; 313 } 315 container module-tags { 316 description 317 "Contains the list of modules and their associated tags"; 318 list module { 319 key "name"; 320 description 321 "A list of modules and their associated tags"; 322 leaf name { 323 type yang:yang-identifier; 324 mandatory true; 325 description 326 "The YANG module name."; 327 } 328 leaf-list tag { 329 type tag; 330 description 331 "Tags associated with the module. See the IANA 'YANG Module 332 Tag Prefixes' registry for reserved prefixes and the IANA 333 'YANG Module Tags' registry for IETF standard tags. 335 The 'operational' state [RFC8342] view of this list is 336 constructed using the following steps: 338 1) System tags (i.e., tags of 'system' origin) are added. 339 2) User configured tags (i.e., tags of 'intended' origin) 340 are added. 341 3) Any tag that is equal to a masked-tag is removed."; 342 } 343 leaf-list masked-tag { 344 type tag; 345 description 346 "The list of tags that should not be associated with this 347 module. The user can remove (mask) tags from the 348 operational state datastore [RFC8342] by adding them to 349 this list. It is not an error to add tags to this list 350 that are not associated with the module, but they have no 351 operational effect."; 352 } 353 } 354 } 355 } 356 358 5. Other Classifications 360 It is worth noting that a different YANG module classification 361 document exists [RFC8199]. That document only classifies modules in 362 a logical manner and does not define tagging or any other mechanisms. 363 It divides YANG modules into two categories (service or element) and 364 then into one of three origins: standard, vendor or user. It does 365 provide a good way to discuss and identify modules in general. This 366 document defines standard tags to support [RFC8199] style 367 classification. 369 6. Guidelines to Model Writers 371 This section updates [RFC8407]. 373 6.1. Define Standard Tags 375 A module MAY indicate, using module-tag extension statements, a set 376 of tags that are to be automatically associated with it (i.e., not 377 added through configuration). 379 module example-module { 380 //... 381 import module-tags { prefix tags; } 383 tags:module-tag "ietf:some-new-tag"; 384 tags:module-tag "ietf:some-other-tag"; 385 // ... 386 } 388 The module writer can use existing standard tags, or use new tags 389 defined in the model definition, as appropriate. For standardized 390 modules new tags MUST be assigned in the IANA registry defined below, 391 see Section 7.2. 393 7. IANA Considerations 395 7.1. YANG Module Tag Prefixes Registry 397 IANA is asked to create a new registry "YANG Module Tag Prefixes" 398 grouped under a new "Protocol" category named "YANG Module Tags". 400 This registry allocates tag prefixes. All YANG module tags SHOULD 401 begin with one of the prefixes in this registry. 403 Prefix entries in this registry should be short strings consisting of 404 lowercase ASCII alpha-numeric characters and a final ":" character. 406 The allocation policy for this registry is Specification Required 407 [RFC8126]. 409 The initial values for this registry are as follows. 411 +---------+---------------------------------------------------------+ 412 | Prefix | Description | 413 +---------+---------------------------------------------------------+ 414 | ietf: | IETF Standard Tag allocated in the IANA YANG Module | 415 | | Tags registry. | 416 | | | 417 | vendor: | Non-standardized tags allocated by the module | 418 | | implementer. | 419 | | | 420 | user: | Non-standardized tags allocated by and for the user. | 421 +---------+---------------------------------------------------------+ 423 Other standards organizations (SDOs) wishing to standardize their own 424 set of tags should allocate a prefix from this registry. 426 7.2. YANG Module Tags Registry 428 IANA is asked to create a new registry "YANG Module Tags" grouped 429 under a new "Protocol" category "YANG Module Tags". This registry 430 should be included below "YANG Module Tag Prefixes" when listed on 431 the same page. 433 This registry allocates prefixes that have the standard prefix 434 "ietf:". New values should be well considered and not achievable 435 through a combination of already existing standard tags. 437 The allocation policy for this registry is IETF Review [RFC8126]. 439 The initial values for this registry are as follows. 441 +----------------------------+--------------------------+-----------+ 442 | Tag | Description | Reference | 443 +----------------------------+--------------------------+-----------+ 444 | ietf:network-element-class | [RFC8199] network | [RFC8199] | 445 | | element. | | 446 | | | | 447 | ietf:network-service-class | [RFC8199] network | [RFC8199] | 448 | | service. | | 449 | | | | 450 | ietf:sdo-defined-class | Module is defined by a | [RFC8199] | 451 | | standards organization. | | 452 | | | | 453 | ietf:vendor-defined-class | Module is defined by a | [RFC8199] | 454 | | vendor. | | 455 | | | | 456 | ietf:user-defined-class | Module is defined by the | [RFC8199] | 457 | | user. | | 458 | | | | 459 | ietf:hardware | Relates to hardware | [This | 460 | | (e.g., inventory). | document] | 461 | | | | 462 | ietf:software | Relates to software | [This | 463 | | (e.g., installed OS). | document] | 464 | | | | 465 | ietf:protocol | Represents a protocol | [This | 466 | | (often combined with | document] | 467 | | another tag to refine). | | 468 | | | | 469 | ietf:qos | Relates to quality of | [This | 470 | | service. | document] | 471 | | | | 472 | ietf:network-service-app | Relates to a network | [This | 473 | | service application | document] | 474 | | (e.g., an NTP server, | | 475 | | DNS server, DHCP server, | | 476 | | etc). | | 477 | | | | 478 | ietf:system-management | Relates to system | [This | 479 | | management (e.g., a | document] | 480 | | system management | | 481 | | protocol such as syslog, | | 482 | | TACAC+, SNMP, netconf, | | 483 | | ...). | | 484 | | | | 485 | ietf:oam | Relates to Operations, | [This | 486 | | Administration, and | document] | 487 | | Maintenance (e.g., BFD). | | 488 | | | | 489 | ietf:routing | Relates to routing. | [This | 490 | | | document] | 491 | | | | 492 | ietf:signaling | Relates to control plane | [This | 493 | | signaling. | document] | 494 | | | | 495 | ietf:link-management | Relates to link | [This | 496 | | management. | document] | 497 +----------------------------+--------------------------+-----------+ 499 7.3. Updates to the IETF XML Registry 501 This document registers a URI in the "IETF XML Registry" [RFC3688]. 502 Following the format in [RFC3688], the following registration has 503 been made: 505 URI: urn:ietf:params:xml:ns:yang:ietf-module-tags 507 Registrant Contact: The IESG. 509 XML: N/A; the requested URI is an XML namespace. 511 7.4. Updates to the YANG Module Names Registry 513 This document registers one YANG module in the "YANG Module Names" 514 registry [RFC6020]. Following the format in [RFC6020], the following 515 registration has been made: 517 name: ietf-module-tags 519 namespace: urn:ietf:params:xml:ns:yang:ietf-module-tags 521 prefix: tags 522 reference: RFC XXXX (RFC Ed.: replace XXX with actual RFC number and 523 remove this note.) 525 8. Security Considerations 527 The YANG module defined in this memo is designed to be accessed via 528 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 529 secure transport layer and the mandatory-to-implement secure 530 transport is SSH [RFC6242]. 532 This document adds the ability to associate tag meta-data with YANG 533 modules. This document does not define any actions based on these 534 associations, and none are yet defined, and therefore it does not by 535 itself introduce any new security considerations. 537 Users of the tag-meta data may define various actions to be taken 538 based on the tag meta-data. These actions and their definitions are 539 outside the scope of this document. Users will need to consider the 540 security implications of any actions they choose to define. 542 9. References 544 9.1. Normative References 546 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 547 Requirement Levels", BCP 14, RFC 2119, 548 DOI 10.17487/RFC2119, March 1997, 549 . 551 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 552 RFC 7950, DOI 10.17487/RFC7950, August 2016, 553 . 555 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 556 Writing an IANA Considerations Section in RFCs", BCP 26, 557 RFC 8126, DOI 10.17487/RFC8126, June 2017, 558 . 560 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 561 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 562 May 2017, . 564 9.2. Informative References 566 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 567 DOI 10.17487/RFC3688, January 2004, 568 . 570 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 571 the Network Configuration Protocol (NETCONF)", RFC 6020, 572 DOI 10.17487/RFC6020, October 2010, 573 . 575 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 576 and A. Bierman, Ed., "Network Configuration Protocol 577 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 578 . 580 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 581 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 582 . 584 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 585 Classification", RFC 8199, DOI 10.17487/RFC8199, July 586 2017, . 588 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 589 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 590 . 592 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 593 and R. Wilton, "Network Management Datastore Architecture 594 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 595 . 597 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 598 Documents Containing YANG Data Models", BCP 216, RFC 8407, 599 DOI 10.17487/RFC8407, October 2018, 600 . 602 Appendix A. Examples 604 The following is a fictional example result from a query of the 605 module tags list. For the sake of brevity only a few module results 606 are imagined. 608 609 610 611 ietf-bfd 612 ietf:network-element-class 613 ietf:oam 614 ietf:protocol 615 ietf:sdo-defined-class 616 617 618 ietf-isis 619 ietf:network-element-class 620 ietf:protocol 621 ietf:sdo-defined-class 622 ietf:routing 623 624 625 ietf-ssh-server 626 ietf:network-element-class 627 ietf:protocol 628 ietf:sdo-defined-class 629 ietf:system-management 630 631 632 634 Appendix B. Acknowledgements 636 Special thanks to Robert Wilton for his help improving the 637 introduction and providing the example use cases. 639 Authors' Addresses 641 Christian Hopps 642 LabN Consulting, L.L.C. 644 Email: chopps@chopps.org 646 Lou Berger 647 LabN Consulting, LLC. 649 Email: lberger@labn.net 650 Dean Bogdanovic 651 Volta Networks 653 Email: ivandean@gmail.com