idnits 2.17.1 draft-ietf-core-sid-08.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 11 instances of too long lines in the document, the longest one being 9 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 08, 2020) is 1560 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: 'DONE' is mentioned on line 1298, but not defined == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-08 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force M. Veillette, Ed. 3 Internet-Draft Trilliant Networks Inc. 4 Intended status: Standards Track A. Pelov, Ed. 5 Expires: July 11, 2020 I. Petrov, Ed. 6 Acklio 7 January 08, 2020 9 YANG Schema Item iDentifier (SID) 10 draft-ietf-core-sid-08 12 Abstract 14 YANG Schema Item iDentifiers (SID) are globally unique 63-bit 15 unsigned integers used to identify YANG items. This document defines 16 the semantics, the registration, and assignment processes of SIDs. 17 To enable the implementation of these processes, this document also 18 defines a file format used to persist and publish assigned SIDs. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on July 11, 2020. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 56 3. ".sid" file lifecycle . . . . . . . . . . . . . . . . . . . . 4 57 4. ".sid" file format . . . . . . . . . . . . . . . . . . . . . 5 58 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 59 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 60 6.1. Register SID File Format Module . . . . . . . . . . . . . 9 61 6.2. Create new IANA Registry: "SID Mega-Range" registry . . . 9 62 6.2.1. Structure . . . . . . . . . . . . . . . . . . . . . . 9 63 6.2.2. Allocation policy . . . . . . . . . . . . . . . . . . 10 64 6.2.2.1. First allocation . . . . . . . . . . . . . . . . 10 65 6.2.2.2. Consecutive allocations . . . . . . . . . . . . . 11 66 6.2.3. Initial contents of the Registry . . . . . . . . . . 11 67 6.3. Create a new IANA Registry: IETF SID Range Registry 68 (managed by IANA) . . . . . . . . . . . . . . . . . . . . 11 69 6.3.1. Structure . . . . . . . . . . . . . . . . . . . . . . 11 70 6.3.2. Allocation policy . . . . . . . . . . . . . . . . . . 11 71 6.3.3. Initial contents of the registry . . . . . . . . . . 12 72 6.4. Create new IANA Registry: "IETF SID Registry" . . . . . . 13 73 6.4.1. Structure . . . . . . . . . . . . . . . . . . . . . . 13 74 6.4.2. Allocation policy . . . . . . . . . . . . . . . . . . 14 75 6.4.3. Initial contents of the registry . . . . . . . . . . 14 76 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 77 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 78 8.1. Normative References . . . . . . . . . . . . . . . . . . 14 79 8.2. Informative References . . . . . . . . . . . . . . . . . 15 80 Appendix A. ".sid" file example . . . . . . . . . . . . . . . . 16 81 Appendix B. SID auto generation . . . . . . . . . . . . . . . . 25 82 Appendix C. ".sid" file lifecycle . . . . . . . . . . . . . . . 25 83 C.1. SID File Creation . . . . . . . . . . . . . . . . . . . . 26 84 C.2. SID File Update . . . . . . . . . . . . . . . . . . . . . 27 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 87 1. Introduction 89 Some of the items defined in YANG [RFC7950] require the use of a 90 unique identifier. In both NETCONF [RFC6241] and RESTCONF [RFC8040], 91 these identifiers are implemented using names. To allow the 92 implementation of data models defined in YANG in constrained devices 93 and constrained networks, a more compact method to identify YANG 94 items is required. This compact identifier, called SID, is encoded 95 using a 63-bit unsigned integer. The reason not to use 64-bit 96 unsigned integers is that otherwise protocols doing arithmetical 97 operations with the SIDs could be very difficult to implement. 99 The following items are identified using SIDs: 101 o identities 103 o data nodes (Note: including those parts of a YANG template as 104 defined by the 'yang-data' extension.) 106 o RPCs and associated input(s) and output(s) 108 o actions and associated input(s) and output(s) 110 o notifications and associated information 112 o YANG modules, submodules and features 114 SIDs are globally unique integers, a registration system is used in 115 order to guarantee their uniqueness. SIDs are registered in blocks 116 called "SID ranges". 118 Assignment of SIDs to YANG items can be automated. For more details 119 how this could be achieved, please consult Appendix B. 121 SIDs are assigned permanently, items introduced by a new revision of 122 a YANG module are added to the list of SIDs already assigned. 124 Section 3 provides more details about the registration process of 125 YANG modules and associated SIDs. To enable the implementation of 126 this registry, Section 4 defines a standard file format used to store 127 and publish SIDs. 129 2. Terminology and Notation 131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 133 "OPTIONAL" in this document are to be interpreted as described in BCP 134 14 [RFC2119] [RFC8174] when, and only when, they appear in all 135 capitals, as shown here. 137 The following terms are defined in [RFC7950]: 139 o action 141 o feature 143 o module 144 o notification 146 o RPC 148 o schema node 150 o schema tree 152 o submodule 154 The following term is defined in [RFC8040]: 156 o yang-data extension 158 This specification also makes use of the following terminology: 160 o item: A schema node, an identity, a module, a submodule or a 161 feature defined using the YANG modeling language. 163 o path: A path is a string that identifies a schema node within the 164 schema tree. A path consists of the list of schema node 165 identifier(s) separated by slashes ("/"). Schema node 166 identifier(s) are always listed from the top-level schema node up 167 to the targeted schema node. (e.g. "/ietf-system:system- 168 state/clock/current-datetime") 170 o YANG Schema Item iDentifier (SID): Unsigned integer used to 171 identify different YANG items. 173 3. ".sid" file lifecycle 175 YANG is a language designed to model data accessed using one of the 176 compatible protocols (e.g. NETCONF [RFC6241], RESCONF [RFC8040] and 177 CoRECONF [I-D.ietf-core-comi]). A YANG module defines hierarchies of 178 data, including configuration, state data, RPCs, actions and 179 notifications. 181 Many YANG modules are not created in the context of constrained 182 applications. YANG modules can be implemented using NETCONF 183 [RFC6241] or RESTCONF [RFC8040] without the need to assign SIDs. 185 As needed, authors of YANG modules can assign SIDs to their YANG 186 modules. In order to do that, they should first obtain a SID range 187 from a registry and use that range to assign or generate SIDs to 188 items of their YANG module. For example how this could be achieved, 189 please refer to Appendix C. 191 Registration of the .sid file associated to a YANG module is optional 192 but recommended to promote interoperability between devices and to 193 avoid duplicate allocation of SIDs to a single YANG module. 194 Different registries might have different requirements for the 195 registration and publication of the ".sid" files. For diagram of one 196 of the possibilities, please refer to the activity diagram on 197 Figure 1 in Appendix C. 199 Each time a YANG module or one of its imported module(s) or included 200 sub-module(s) is updated, the ".sid" file MAY need to be updated. 201 This update SHOULD be performed using an automated tool. 203 If a new revision requires more SIDs than initially allocated, a new 204 SID range MUST be added to the 'assignment-ranges' as defined in 205 Section 4. These extra SIDs are used for subsequent assignments. 207 For an example of this update process, see activity diagram Figure 2 208 in Appendix C. 210 4. ".sid" file format 212 ".sid" files are used to persist and publish SIDs assigned to the 213 different YANG items of a specific YANG module. The following YANG 214 module defined the structure of this file, encoding is performed 215 using the rules defined in [RFC7951]. 217 file "ietf-sid-file@2017-11-26.yang" 218 module ietf-sid-file { 219 namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file"; 220 prefix sid; 222 import ietf-yang-types { 223 prefix yang; 224 } 226 organization 227 "IETF Core Working Group"; 229 contact 230 "Michel Veillette 231 233 Andy Bierman 234 236 Alexander Pelov 237 "; 239 description 240 "This module defines the structure of the .sid files. 242 Each .sid file contains the mapping between the different 243 string identifiers defined by a YANG module and a 244 corresponding numeric value called SID."; 246 revision 2017-11-26 { 247 description 248 "Initial revision."; 249 reference 250 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 251 } 253 typedef revision-identifier { 254 type string { 255 pattern '\d{4}-\d{2}-\d{2}'; 256 } 257 description 258 "Represents a date in YYYY-MM-DD format."; 259 } 261 typedef sid { 262 type uint64; 263 description 264 "YANG Schema Item iDentifier"; 265 reference 266 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 267 } 269 typedef schema-node-path { 270 type string { 271 pattern 272 '/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' + 273 '(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*'; 274 } 275 description 276 "Identifies a schema-node path string for use in the 277 SID registry. This string format follows the rules 278 for an instance-identifier, as defined in RFC 7959, 279 except that no predicates are allowed. 281 This format is intended to support the YANG 1.1 ABNF 282 for a schema node identifier, except module names 283 are used instead of prefixes, as specified in RFC 7951."; 284 reference 285 "RFC 7950, The YANG 1.1 Data Modeling Language; 286 Section 6.5: Schema Node Identifier; 287 RFC 7951, JSON Encoding of YANG Data; 288 Section 6.11: The instance-identifier type"; 289 } 291 leaf module-name { 292 type yang:yang-identifier; 293 description 294 "Name of the YANG module associated with this .sid file."; 295 } 297 leaf module-revision { 298 type revision-identifier; 299 description 300 "Revision of the YANG module associated with this .sid file. 301 This leaf is not present if no revision statement is 302 defined in the YANG module."; 303 } 305 list assigment-ranges { 306 key "entry-point"; 307 description 308 "SID range(s) allocated to the YANG module identified by 309 'module-name' and 'module-revision'."; 311 leaf entry-point { 312 type sid; 313 mandatory true; 314 description 315 "Lowest SID available for assignment."; 316 } 318 leaf size { 319 type uint64; 320 mandatory true; 321 description 322 "Number of SIDs available for assignment."; 323 } 324 } 326 list items { 327 key "namespace identifier"; 328 description 329 "Each entry within this list defined the mapping between 330 a YANG item string identifier and a SID. This list MUST 331 include a mapping entry for each YANG item defined by 332 the YANG module identified by 'module-name' and 333 'module-revision'."; 335 leaf namespace { 336 type enumeration { 337 enum module { 338 value 0; 339 description 340 "All module and submodule names share the same 341 global module identifier namespace."; 342 } 343 enum identity { 344 value 1; 345 description 346 "All identity names defined in a module and its 347 submodules share the same identity identifier 348 namespace."; 349 } 350 enum feature { 351 value 2; 352 description 353 "All feature names defined in a module and its 354 submodules share the same feature identifier 355 namespace."; 356 } 357 enum data { 358 value 3; 359 description 360 "The namespace for all data nodes, as defined in YANG."; 361 } 362 } 363 description 364 "Namespace of the YANG item for this mapping entry."; 365 } 367 leaf identifier { 368 type union { 369 type yang:yang-identifier; 370 type schema-node-path; 371 } 372 description 373 "String identifier of the YANG item for this mapping entry. 375 If the corresponding 'namespace' field is 'module', 376 'feature', or 'identity', then this field MUST 377 contain a valid YANG identifier string. 379 If the corresponding 'namespace' field is 'data', 380 then this field MUST contain a valid schema node 381 path."; 382 } 384 leaf sid { 385 type sid; 386 mandatory true; 387 description 388 "SID assigned to the YANG item for this mapping entry."; 389 } 390 } 391 } 392 394 5. Security Considerations 396 This document defines a new type of identifier used to encode data 397 models defined in YANG [RFC7950]. As such, this identifier does not 398 contribute to any new security issues in addition of those identified 399 for the specific protocols or contexts for which it is used. 401 6. IANA Considerations 403 6.1. Register SID File Format Module 405 This document registers one YANG module in the "YANG Module Names" 406 registry [RFC6020]: 408 o name: ietf-sid-file 410 o namespace: urn:ietf:params:xml:ns:yang:ietf-sid-file 412 o prefix: sid 414 o reference: [[THISRFC]] 416 6.2. Create new IANA Registry: "SID Mega-Range" registry 418 The name of this registry is "SID Mega-Range". This registry is used 419 to record the delegation of the management of a block of SIDs to 420 third parties (such as SDOs or registrars). 422 6.2.1. Structure 424 Each entry in this registry must include: 426 o The entry point (first SID) of the registered SID block. 428 o The size of the registered SID block. The size MUST be one 429 million (1 000 000) SIDs. 431 o The contact information of the requesting organization including: 433 * The policy of SID range allocations: Public, Private or Both. 435 * Organization name 437 * URL 439 The information associated to the Organization name should not be 440 publicly visible in the registry, but should be available. This 441 information includes contact email and phone number and change 442 controller email and phone number. 444 6.2.2. Allocation policy 446 The IANA policy for future additions to this registry is "Expert 447 Review" [RFC8126]. 449 An organization requesting to manage a SID Range (and thus have an 450 entry in the SID Mega-Range Registry), must ensure the following 451 capacities: 453 o The capacity to manage and operate a SID Range Registry. A SID 454 Range Registry MUST provide the following information for all SID 455 Ranges allocated by the Registry: 457 * Entry Point of allocated SID Range 459 * Size of allocated SID Range 461 * Type: Public or Private 463 + Public Ranges MUST include at least a reference to the YANG 464 module and ".sid" files for that SID Range. 466 + Private Ranges MUST be marked as "Private" 468 o A Policy of allocation, which clearly identifies if the SID Range 469 allocations would be Private, Public or Both. 471 o Technical capacity to ensure the sustained operation of the 472 registry for a period of at least 5 years. If Private 473 Registrations are allowed, the period must be of at least 10 474 years. 476 6.2.2.1. First allocation 478 For a first allocation to be provided, the requesting organization 479 must demonstrate a functional registry infrastructure. 481 6.2.2.2. Consecutive allocations 483 On subsequent allocation request(s), the organization must 484 demonstrate the exhaustion of the prior range. These conditions need 485 to be asserted by the assigned expert(s). 487 If that extra-allocation is done within 3 years from the last 488 allocation, the experts need to discuss this request on the CORE 489 working group mailing list and consensus needs to be obtained before 490 allocating a new Mega-Range. 492 6.2.3. Initial contents of the Registry 494 The initial entry in this registry is allocated to IANA: 496 +-------------+---------+------------+-------------------+----------+ 497 | Entry Point | Size | Allocation | Organization name | URL | 498 +-------------+---------+------------+-------------------+----------+ 499 | 0 | 1000000 | Public | IANA | iana.org | 500 +-------------+---------+------------+-------------------+----------+ 502 6.3. Create a new IANA Registry: IETF SID Range Registry (managed by 503 IANA) 505 6.3.1. Structure 507 Each entry in this registry must include: 509 o The SID range entry point. 511 o The SID range size. 513 o The YANG module name. 515 o Document reference. 517 6.3.2. Allocation policy 519 The first million SIDs assigned to IANA is sub-divided as follows: 521 o The range of 0 to 999 (size 1000) is "Reserved" as defined in 522 [RFC8126]. 524 o The range of 1000 to 59,999 (size 59,000) is reserved for YANG 525 modules defined in RFCs. The IANA policy for additions to this 526 registry is "Expert Review" [RFC8126]. 528 * The Expert MUST verify that the YANG module for which this 529 allocation is made has an RFC (existing RFC) OR is on track to 530 become RFC (early allocation with a request from the WG chairs 531 as defined by [RFC7120]). 533 o The SID range allocated for a YANG module can follow in one of the 534 four categories: 536 * SMALL (50 SIDs) 538 * MEDIUM (100 SIDs) 540 * LARGE (250 SIDs) 542 * CUSTOM (requested by the YANG module author, with a maximum of 543 1000 SIDs). In all cases, the size of a SID range assigned to 544 a YANG module should be at least 33% above the current number 545 of YANG items. This headroom allows assignment within the same 546 range of new YANG items introduced by subsequent revisions. A 547 larger SID range size may be requested by the authors if this 548 recommendation is considered insufficient. It is important to 549 note that an additional SID range can be allocated to an 550 existing YANG module if the initial range is exhausted. 552 o The range of 60,000 to 99,999 (size 40,000)is reserved for 553 experimental YANG modules. This range MUST NOT be used in 554 operational deployments since these SIDs are not globally unique 555 which limit their interoperability. The IANA policy for this 556 range is "Experimental use" [RFC8126]. 558 o The range of 100,000 to 999,999 (size 900,000) is "Reserved" as 559 defined in [RFC8126]. 561 +-------------+---------+------------------+ 562 | Entry Point | Size | IANA policy | 563 +-------------+---------+------------------+ 564 | 0 | 1,000 | Reserved | 565 | 1,000 | 59,000 | Expert Review | 566 | 60,000 | 40,000 | Experimental use | 567 | 100,000 | 900,000 | Reserved | 568 +-------------+---------+------------------+ 570 6.3.3. Initial contents of the registry 572 Initial entries in this registry are as follows: 574 +-------------+------+------------------+----------------------+ 575 | Entry Point | Size | Module name | Document reference | 576 +-------------+------+------------------+----------------------+ 577 | 1000 | 100 | ietf-comi | [I-D.ietf-core-comi] | 578 | 1100 | 50 | ietf-yang-types | [RFC6991] | 579 | 1150 | 50 | ietf-inet-types | [RFC6991] | 580 | 1200 | 50 | iana-crypt-hash | [RFC7317] | 581 | 1250 | 50 | ietf-netconf-acm | [RFC8341] | 582 | 1300 | 50 | ietf-sid-file | RFCXXXX | 583 | 1500 | 100 | ietf-interfaces | [RFC8343] | 584 | 1600 | 100 | ietf-ip | [RFC8344] | 585 | 1700 | 100 | ietf-system | [RFC7317] | 586 | 1800 | 400 | iana-if-type | [RFC7224] | 587 +-------------+------+------------------+----------------------+ 589 // RFC Ed.: replace XXXX with RFC number assigned to this draft. 591 For allocation, RFC publication of the YANG module is required as per 592 [RFC8126]. The YANG module must be registered in the "YANG module 593 Name" registry according to the rules specified in section 14 of 594 [RFC6020]. 596 6.4. Create new IANA Registry: "IETF SID Registry" 598 The name of this registry is "IETF SID Registry". This registry is 599 used to record the allocation of SIDs for individual YANG module 600 items. 602 6.4.1. Structure 604 Each entry in this registry must include: 606 o The YANG module name. This module name must be present in the 607 "Name" column of the "YANG Module Names" registry. 609 o A link to the associated ".yang" file. This file link must be 610 present in the "File" column of the "YANG Module Names" registry. 612 o The link to the ".sid" file which defines the allocation. 614 o The number of actually allocated SIDs in the ".sid" file. 616 The ".sid" file is stored by IANA. 618 6.4.2. Allocation policy 620 The allocation policy is Expert review. The Expert MUST ensure that 621 the following conditions are met: 623 o The ".sid" file has a valid structure: 625 * The ".sid" file MUST be a valid JSON file following the 626 structure of the module defined in RFCXXXX (RFC Ed: replace XXX 627 with RFC number assigned to this draft). 629 o The ".sid" file allocates individual SIDs ONLY in the SID Ranges 630 for this YANG module (as allocated in the IETF SID Range 631 Registry): 633 * All SIDs in this ".sid" file MUST be within the ranges 634 allocated to this YANG module in the "IETF SID Range Registry". 636 o If another ".sid" file has already allocated SIDs for this YANG 637 module (e.g. for older or newer versions of the YANG module), the 638 YANG items are assigned the same SIDs as in the the other ".sid" 639 file. 641 o SIDs never change. 643 6.4.3. Initial contents of the registry 645 None. 647 7. Acknowledgments 649 The authors would like to thank Andy Bierman, Carsten Bormann, 650 Abhinav Somaraju, Laurent Toutain, Randy Turner and Peter van der 651 Stok for their help during the development of this document and their 652 useful comments during the review process. 654 8. References 656 8.1. Normative References 658 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 659 Requirement Levels", BCP 14, RFC 2119, 660 DOI 10.17487/RFC2119, March 1997, 661 . 663 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 664 Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 665 2014, . 667 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 668 RFC 7950, DOI 10.17487/RFC7950, August 2016, 669 . 671 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 672 RFC 7951, DOI 10.17487/RFC7951, August 2016, 673 . 675 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 676 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 677 May 2017, . 679 8.2. Informative References 681 [I-D.ietf-core-comi] 682 Veillette, M., Stok, P., Pelov, A., Bierman, A., and I. 683 Petrov, "CoAP Management Interface", draft-ietf-core- 684 comi-08 (work in progress), September 2019. 686 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 687 the Network Configuration Protocol (NETCONF)", RFC 6020, 688 DOI 10.17487/RFC6020, October 2010, 689 . 691 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 692 and A. Bierman, Ed., "Network Configuration Protocol 693 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 694 . 696 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 697 RFC 6991, DOI 10.17487/RFC6991, July 2013, 698 . 700 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", 701 RFC 7224, DOI 10.17487/RFC7224, May 2014, 702 . 704 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 705 System Management", RFC 7317, DOI 10.17487/RFC7317, August 706 2014, . 708 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 709 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 710 . 712 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 713 Writing an IANA Considerations Section in RFCs", BCP 26, 714 RFC 8126, DOI 10.17487/RFC8126, June 2017, 715 . 717 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 718 Access Control Model", STD 91, RFC 8341, 719 DOI 10.17487/RFC8341, March 2018, 720 . 722 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 723 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 724 . 726 [RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", 727 RFC 8344, DOI 10.17487/RFC8344, March 2018, 728 . 730 Appendix A. ".sid" file example 732 The following .sid file (ietf-system@2014-08-06.sid) have been 733 generated using the following yang modules: 735 o ietf-system@2014-08-06.yang 737 o ietf-yang-types@2013-07-15.yang 739 o ietf-inet-types@2013-07-15.yang 741 o ietf-netconf-acm@2012-02-22.yang 743 o iana-crypt-hash@2014-04-04.yang 745 { 746 "assignment-ranges": [ 747 { 748 "entry-point": 1700, 749 "size": 100 750 } 751 ], 752 "module-name": "ietf-system", 753 "module-revision": "2014-08-06", 754 "items": [ 755 { 756 "namespace": "module", 757 "identifier": "ietf-system", 758 "sid": 1700 759 }, 760 { 761 "namespace": "identity", 762 "identifier": "authentication-method", 763 "sid": 1701 764 }, 765 { 766 "namespace": "identity", 767 "identifier": "local-users", 768 "sid": 1702 769 }, 770 { 771 "namespace": "identity", 772 "identifier": "radius", 773 "sid": 1703 774 }, 775 { 776 "namespace": "identity", 777 "identifier": "radius-authentication-type", 778 "sid": 1704 779 }, 780 { 781 "namespace": "identity", 782 "identifier": "radius-chap", 783 "sid": 1705 784 }, 785 { 786 "namespace": "identity", 787 "identifier": "radius-pap", 788 "sid": 1706 789 }, 790 { 791 "namespace": "feature", 792 "identifier": "authentication", 793 "sid": 1707 794 }, 795 { 796 "namespace": "feature", 797 "identifier": "dns-udp-tcp-port", 798 "sid": 1708 799 }, 800 { 801 "namespace": "feature", 802 "identifier": "local-users", 803 "sid": 1709 804 }, 805 { 806 "namespace": "feature", 807 "identifier": "ntp", 808 "sid": 1710 809 }, 810 { 811 "namespace": "feature", 812 "identifier": "ntp-udp-port", 813 "sid": 1711 814 }, 815 { 816 "namespace": "feature", 817 "identifier": "radius", 818 "sid": 1712 819 }, 820 { 821 "namespace": "feature", 822 "identifier": "radius-authentication", 823 "sid": 1713 824 }, 825 { 826 "namespace": "feature", 827 "identifier": "timezone-name", 828 "sid": 1714 829 }, 830 { 831 "namespace": "data", 832 "identifier": "/ietf-system:set-current-datetime", 833 "sid": 1715 834 }, 835 { 836 "namespace": "data", 837 "identifier": "/ietf-system:set-current-datetime/ 838 current-datetime", 839 "sid": 1716 840 }, 841 { 842 "namespace": "data", 843 "identifier": "/ietf-system:system", 844 "sid": 1717 845 }, 846 { 847 "namespace": "data", 848 "identifier": "/ietf-system:system-restart", 849 "sid": 1718 850 }, 851 { 852 "namespace": "data", 853 "identifier": "/ietf-system:system-shutdown", 854 "sid": 1719 855 }, 856 { 857 "namespace": "data", 858 "identifier": "/ietf-system:system-state", 859 "sid": 1720 860 }, 861 { 862 "namespace": "data", 863 "identifier": "/ietf-system:system-state/clock", 864 "sid": 1721 865 }, 866 { 867 "namespace": "data", 868 "identifier": "/ietf-system:system-state/clock/boot-datetime", 869 "sid": 1722 870 }, 871 { 872 "namespace": "data", 873 "identifier": "/ietf-system:system-state/clock/ 874 current-datetime", 875 "sid": 1723 876 }, 877 { 878 "namespace": "data", 879 "identifier": "/ietf-system:system-state/platform", 880 "sid": 1724 881 }, 882 { 883 "namespace": "data", 884 "identifier": "/ietf-system:system-state/platform/machine", 885 "sid": 1725 886 }, 887 { 888 "namespace": "data", 889 "identifier": "/ietf-system:system-state/platform/os-name", 890 "sid": 1726 891 }, 892 { 893 "namespace": "data", 894 "identifier": "/ietf-system:system-state/platform/os-release", 895 "sid": 1727 896 }, 897 { 898 "namespace": "data", 899 "identifier": "/ietf-system:system-state/platform/os-version", 900 "sid": 1728 901 }, 902 { 903 "namespace": "data", 904 "identifier": "/ietf-system:system/authentication", 905 "sid": 1729 906 }, 907 { 908 "namespace": "data", 909 "identifier": "/ietf-system:system/authentication/user", 910 "sid": 1730 911 }, 912 { 913 "namespace": "data", 914 "identifier": "/ietf-system:system/authentication/ 915 user-authentication-order", 916 "sid": 1731 917 }, 918 { 919 "namespace": "data", 920 "identifier": "/ietf-system:system/authentication/user/ 921 authorized-key", 922 "sid": 1732 923 }, 924 { 925 "namespace": "data", 926 "identifier": "/ietf-system:system/authentication/user/ 927 authorized-key/algorithm", 928 "sid": 1733 929 }, 930 { 931 "namespace": "data", 932 "identifier": "/ietf-system:system/authentication/user/ 933 authorized-key/key-data", 934 "sid": 1734 935 }, 936 { 937 "namespace": "data", 938 "identifier": "/ietf-system:system/authentication/user/ 939 authorized-key/name", 940 "sid": 1735 941 }, 942 { 943 "namespace": "data", 944 "identifier": "/ietf-system:system/authentication/user/ 945 name", 946 "sid": 1736 947 }, 948 { 949 "namespace": "data", 950 "identifier": "/ietf-system:system/authentication/user/ 951 password", 953 "sid": 1737 954 }, 955 { 956 "namespace": "data", 957 "identifier": "/ietf-system:system/clock", 958 "sid": 1738 959 }, 960 { 961 "namespace": "data", 962 "identifier": "/ietf-system:system/clock/timezone-name", 963 "sid": 1739 964 }, 965 { 966 "namespace": "data", 967 "identifier": "/ietf-system:system/clock/timezone-utc-offset", 968 "sid": 1740 969 }, 970 { 971 "namespace": "data", 972 "identifier": "/ietf-system:system/contact", 973 "sid": 1741 974 }, 975 { 976 "namespace": "data", 977 "identifier": "/ietf-system:system/dns-resolver", 978 "sid": 1742 979 }, 980 { 981 "namespace": "data", 982 "identifier": "/ietf-system:system/dns-resolver/options", 983 "sid": 1743 984 }, 985 { 986 "namespace": "data", 987 "identifier": "/ietf-system:system/dns-resolver/options/ 988 attempts", 989 "sid": 1744 990 }, 991 { 992 "namespace": "data", 993 "identifier": "/ietf-system:system/dns-resolver/options/ 994 timeout", 995 "sid": 1745 996 }, 997 { 998 "namespace": "data", 999 "identifier": "/ietf-system:system/dns-resolver/search", 1000 "sid": 1746 1002 }, 1003 { 1004 "namespace": "data", 1005 "identifier": "/ietf-system:system/dns-resolver/server", 1006 "sid": 1747 1007 }, 1008 { 1009 "namespace": "data", 1010 "identifier": "/ietf-system:system/dns-resolver/server/name", 1011 "sid": 1748 1012 }, 1013 { 1014 "namespace": "data", 1015 "identifier": "/ietf-system:system/dns-resolver/server/ 1016 udp-and-tcp", 1017 "sid": 1749 1018 }, 1019 { 1020 "namespace": "data", 1021 "identifier": "/ietf-system:system/dns-resolver/server/ 1022 udp-and-tcp/address", 1023 "sid": 1750 1024 }, 1025 { 1026 "namespace": "data", 1027 "identifier": "/ietf-system:system/dns-resolver/server/ 1028 udp-and-tcp/port", 1029 "sid": 1751 1030 }, 1031 { 1032 "namespace": "data", 1033 "identifier": "/ietf-system:system/hostname", 1034 "sid": 1752 1035 }, 1036 { 1037 "namespace": "data", 1038 "identifier": "/ietf-system:system/location", 1039 "sid": 1753 1040 }, 1041 { 1042 "namespace": "data", 1043 "identifier": "/ietf-system:system/ntp", 1044 "sid": 1754 1045 }, 1046 { 1047 "namespace": "data", 1048 "identifier": "/ietf-system:system/ntp/enabled", 1049 "sid": 1755 1051 }, 1052 { 1053 "namespace": "data", 1054 "identifier": "/ietf-system:system/ntp/server", 1055 "sid": 1756 1056 }, 1057 { 1058 "namespace": "data", 1059 "identifier": "/ietf-system:system/ntp/server/ 1060 association-type", 1061 "sid": 1757 1062 }, 1063 { 1064 "namespace": "data", 1065 "identifier": "/ietf-system:system/ntp/server/iburst", 1066 "sid": 1758 1067 }, 1068 { 1069 "namespace": "data", 1070 "identifier": "/ietf-system:system/ntp/server/name", 1071 "sid": 1759 1072 }, 1073 { 1074 "namespace": "data", 1075 "identifier": "/ietf-system:system/ntp/server/prefer", 1076 "sid": 1760 1077 }, 1078 { 1079 "namespace": "data", 1080 "identifier": "/ietf-system:system/ntp/server/udp", 1081 "sid": 1761 1082 }, 1083 { 1084 "namespace": "data", 1085 "identifier": "/ietf-system:system/ntp/server/udp/address", 1086 "sid": 1762 1087 }, 1088 { 1089 "namespace": "data", 1090 "identifier": "/ietf-system:system/ntp/server/udp/port", 1091 "sid": 1763 1092 }, 1093 { 1094 "namespace": "data", 1095 "identifier": "/ietf-system:system/radius", 1096 "sid": 1764 1097 }, 1098 { 1099 "namespace": "data", 1100 "identifier": "/ietf-system:system/radius/options", 1101 "sid": 1765 1102 }, 1103 { 1104 "namespace": "data", 1105 "identifier": "/ietf-system:system/radius/options/attempts", 1106 "sid": 1766 1107 }, 1108 { 1109 "namespace": "data", 1110 "identifier": "/ietf-system:system/radius/options/timeout", 1111 "sid": 1767 1112 }, 1113 { 1114 "namespace": "data", 1115 "identifier": "/ietf-system:system/radius/server", 1116 "sid": 1768 1117 }, 1118 { 1119 "namespace": "data", 1120 "identifier": "/ietf-system:system/radius/server/ 1121 authentication-type", 1122 "sid": 1769 1123 }, 1124 { 1125 "namespace": "data", 1126 "identifier": "/ietf-system:system/radius/server/name", 1127 "sid": 1770 1128 }, 1129 { 1130 "namespace": "data", 1131 "identifier": "/ietf-system:system/radius/server/udp", 1132 "sid": 1771 1133 }, 1134 { 1135 "namespace": "data", 1136 "identifier": "/ietf-system:system/radius/server/udp/ 1137 address", 1138 "sid": 1772 1139 }, 1140 { 1141 "namespace": "data", 1142 "identifier": "/ietf-system:system/radius/server/udp/ 1143 authentication-port", 1144 "sid": 1773 1145 }, 1146 { 1147 "namespace": "data", 1148 "identifier": "/ietf-system:system/radius/server/udp/ 1149 shared-secret", 1150 "sid": 1774 1151 } 1152 ] 1153 } 1155 Appendix B. SID auto generation 1157 Assignment of SIDs to YANG items can be automated, the recommended 1158 process to assign SIDs is as follows: 1160 1. A tool extracts the different items defined for a specific YANG 1161 module. 1163 2. The list of items is sorted in alphabetical order, 'namespace' in 1164 descending order, 'identifier' in ascending order. The 1165 'namespace' and 'identifier' formats are described in the YANG 1166 module 'ietf-sid-file' defined in Section 4. 1168 3. SIDs are assigned sequentially from the entry point up to the 1169 size of the registered SID range. This approach is recommended 1170 to minimize the serialization overhead, especially when delta 1171 between a reference SID and the current SID is used by protocols 1172 aiming to reduce message size. 1174 4. If the number of items exceeds the SID range(s) allocated to a 1175 YANG module, an extra range is added for subsequent assignments. 1177 Changes of SID files can also be automated using the same method 1178 described above, only unassigned YANG items are processed at step #3. 1179 Already existing items in the SID file should not be given new SIDs. 1181 Appendix C. ".sid" file lifecycle 1183 Before assigning SIDs to their YANG modules, YANG module authors must 1184 acquire a SID range from a "SID Range Registry". If the YANG module 1185 is part of an IETF draft or RFC, the SID range need to be acquired 1186 from the "IETF SID Range Registry" as defined in Section 6.3. For 1187 the other YANG modules, the authors can acquire a SID range from any 1188 "SID Range Registry" of their choice. 1190 Once the SID range is acquired, the owner can use it to generate 1191 ".sid" file/s for his YANG module/s. It is recommended to leave some 1192 unallocated SIDs following the allocated range in each ".sid" file in 1193 order to allow better evolution of the YANG module in the future. 1194 Generation of ".sid" files should be performed using an automated 1195 tool. Note that ".sid" files can only be generated for YANG modules 1196 and not for submodules. 1198 C.1. SID File Creation 1200 The following activity diagram summarizes the creation of a YANG 1201 module and its associated .sid file. 1203 +---------------+ 1204 O | Creation of a | 1205 -|- ->| YANG module | 1206 / \ +---------------+ 1207 | 1208 V 1209 /-------------\ 1210 / Standardized \ yes 1211 \ YANG module ? /-------------+ 1212 \-------------/ | 1213 | no | 1214 V V 1215 /-------------\ +---------------+ 1216 / Constrained \ yes | SID range | 1217 +-->\ application ? /---->| registration |<----------+ 1218 | \-------------/ +---------------+ | 1219 | | no | | 1220 | V V | 1221 | +---------------+ +---------------+ | 1222 +---| YANG module | | SID sub-range | | 1223 | update | | assignment |<----------+ 1224 +---------------+ +---------------+ | 1225 | | 1226 V | 1227 +---------------+ +-------------+ 1228 | .sid file | | Rework YANG | 1229 | generation | | model | 1230 +---------------+ +-------------+ 1231 | ^ 1232 V | 1233 /----------\ yes | 1234 / Work in \ -----------+ 1235 \ progress / 1236 \----------/ 1237 | no 1238 V 1239 /-------------\ /-------------\ 1240 / RFC \ no / Open \ no 1241 \ publication? /---->\ specification?/---+ 1242 \-------------/ \-------------/ | 1243 | yes | yes | 1244 | +---------------+ | 1245 V V V 1246 +---------------+ +---------------+ 1247 | IANA | | Third party | 1248 | registration | | registration | 1249 +-------+-------+ +-------+-------+ 1250 | | 1251 +---------------------------------+ 1252 V 1253 [DONE] 1255 Figure 1: SID Lifecycle 1257 C.2. SID File Update 1259 The following Activity diagram summarizes the update of a YANG module 1260 and its associated .sid file. 1262 +---------------+ 1263 O | Update of the | 1264 -|- ->| YANG module | 1265 / \ | or include(s) | 1266 | or import(s) | 1267 +---------------+ 1268 | 1269 V 1270 /-------------\ 1271 / New items \ yes 1272 \ created ? /------+ 1273 \-------------/ | 1274 | no V 1275 | /-------------\ +----------------+ 1276 | / SID range \ yes | Extra sub-range| 1277 | \ exhausted ? /---->| assignment | 1278 | \-------------/ +----------------+ 1279 | | no | 1280 | +---------------------+ 1281 | | 1282 | V 1283 | +---------------+ 1284 | | .sid file | 1285 | | update based | 1286 | | on previous | 1287 | | .sid file | 1288 | +---------------+ 1289 | | 1290 | V 1291 | /-------------\ +---------------+ 1292 | / Publicly \ yes | YANG module | 1293 | \ available ? /---->| registration | 1294 | \-------------/ +---------------+ 1295 | | no | 1296 +--------------+---------------------+ 1297 | 1298 [DONE] 1300 Figure 2: YANG and SID file update 1302 Authors' Addresses 1303 Michel Veillette (editor) 1304 Trilliant Networks Inc. 1305 610 Rue du Luxembourg 1306 Granby, Quebec J2J 2V2 1307 Canada 1309 Phone: +14503750556 1310 Email: michel.veillette@trilliant.com 1312 Alexander Pelov (editor) 1313 Acklio 1314 1137A avenue des Champs Blancs 1315 Cesson-Sevigne, Bretagne 35510 1316 France 1318 Email: a@ackl.io 1320 Ivaylo Petrov (editor) 1321 Acklio 1322 1137A avenue des Champs Blancs 1323 Cesson-Sevigne, Bretagne 35510 1324 France 1326 Email: ivaylo@ackl.io