idnits 2.17.1 draft-ietf-core-sid-07.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 (July 08, 2019) is 1753 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 == Unused Reference: 'RFC7049' is defined on line 659, but no explicit reference was found in the text == Unused Reference: 'RFC7120' is defined on line 663, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-05 Summary: 2 errors (**), 0 flaws (~~), 5 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: January 9, 2020 I. Petrov, Ed. 6 Acklio 7 July 08, 2019 9 YANG Schema Item iDentifier (SID) 10 draft-ietf-core-sid-07 12 Abstract 14 YANG Schema Item iDentifiers (SID) are globally unique 64-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 January 9, 2020. 37 Copyright Notice 39 Copyright (c) 2019 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 64-bit unsigned integer. The following items are identified 96 using SIDs: 98 o identities 100 o data nodes (Note: including those parts of a YANG template as 101 defined by the 'yang-data' extension.) 103 o RPCs and associated input(s) and output(s) 105 o actions and associated input(s) and output(s) 107 o notifications and associated information 109 o YANG modules, submodules and features 111 SIDs are globally unique integers, a registration system is used in 112 order to guarantee their uniqueness. SIDs are registered in blocks 113 called "SID ranges". 115 Assignment of SIDs to YANG items can be automated. For more details 116 how this could be achieved, please consult Appendix B. 118 SIDs are assigned permanently, items introduced by a new revision of 119 a YANG module are added to the list of SIDs already assigned. 121 Section 3 provides more details about the registration process of 122 YANG modules and associated SIDs. To enable the implementation of 123 this registry, Section 4 defines a standard file format used to store 124 and publish SIDs. 126 2. Terminology and Notation 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 130 "OPTIONAL" in this document are to be interpreted as described in BCP 131 14 [RFC2119] [RFC8174] when, and only when, they appear in all 132 capitals, as shown here. 134 The following terms are defined in [RFC7950]: 136 o action 138 o feature 140 o module 142 o notification 144 o RPC 145 o schema node 147 o schema tree 149 o submodule 151 The following term is defined in [RFC8040]: 153 o yang-data extension 155 This specification also makes use of the following terminology: 157 o item: A schema node, an identity, a module, a submodule or a 158 feature defined using the YANG modeling language. 160 o path: A path is a string that identifies a schema node within the 161 schema tree. A path consists of the list of schema node 162 identifier(s) separated by slashes ("/"). Schema node 163 identifier(s) are always listed from the top-level schema node up 164 to the targeted schema node. (e.g. "/ietf-system:system- 165 state/clock/current-datetime") 167 o YANG Schema Item iDentifier (SID): Unsigned integer used to 168 identify different YANG items. 170 3. ".sid" file lifecycle 172 YANG is a language designed to model data accessed using one of the 173 compatible protocols (e.g. NETCONF [RFC6241], RESCONF [RFC8040] and 174 CoRECONF [I-D.ietf-core-comi]). A YANG module defines hierarchies of 175 data, including configuration, state data, RPCs, actions and 176 notifications. 178 Many YANG modules are not created in the context of constrained 179 applications. YANG modules can be implemented using NETCONF 180 [RFC6241] or RESTCONF [RFC8040] without the need to assign SIDs. 182 As needed, authors of YANG modules can assign SIDs to their YANG 183 modules. In order to do that, they should first obtain a SID range 184 from a registry and use that range to assign or generate SIDs to 185 items of their YANG module. For example how this could be achieved, 186 please refer to Appendix C. 188 Registration of the .sid file associated to a YANG module is optional 189 but recommended to promote interoperability between devices and to 190 avoid duplicate allocation of SIDs to a single YANG module. 191 Different registries might have different requirements for the 192 registration and publication of the ".sid" files. For diagram of one 193 of the possibilities, please refer to the activity diagram on 194 Figure 1 in Appendix C. 196 Each time a YANG module or one of its imported module(s) or included 197 sub-module(s) is updated, the ".sid" file MAY need to be updated. 198 This update SHOULD also be performed using an automated tool. 200 If a new revision requires more SIDs than initially allocated, a new 201 SID range MUST be added to the 'assignment-ranges' as defined in 202 Section 4. These extra SIDs are used for subsequent assignments. 204 For an example of this update process, see activity diagram Figure 2 205 in Appendix C. 207 4. ".sid" file format 209 ".sid" files are used to persist and publish SIDs assigned to the 210 different YANG items of a specific YANG module. The following YANG 211 module defined the structure of this file, encoding is performed 212 using the rules defined in [RFC7951]. 214 file "ietf-sid-file@2017-11-26.yang" 215 module ietf-sid-file { 216 namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file"; 217 prefix sid; 219 import ietf-yang-types { 220 prefix yang; 221 } 223 organization 224 "IETF Core Working Group"; 226 contact 227 "Michel Veillette 228 230 Andy Bierman 231 233 Alexander Pelov 234 "; 236 description 237 "This module defines the structure of the .sid files. 239 Each .sid file contains the mapping between the different 240 string identifiers defined by a YANG module and a 241 corresponding numeric value called SID."; 243 revision 2017-11-26 { 244 description 245 "Initial revision."; 246 reference 247 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 248 } 250 typedef revision-identifier { 251 type string { 252 pattern '\d{4}-\d{2}-\d{2}'; 253 } 254 description 255 "Represents a date in YYYY-MM-DD format."; 256 } 258 typedef sid { 259 type uint64; 260 description 261 "YANG Schema Item iDentifier"; 262 reference 263 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 264 } 266 typedef schema-node-path { 267 type string { 268 pattern 269 '/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' + 270 '(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*'; 271 } 272 description 273 "Identifies a schema-node path string for use in the 274 SID registry. This string format follows the rules 275 for an instance-identifier, as defined in RFC 7959, 276 except that no predicates are allowed. 278 This format is intended to support the YANG 1.1 ABNF 279 for a schema node identifier, except module names 280 are used instead of prefixes, as specified in RFC 7951."; 281 reference 282 "RFC 7950, The YANG 1.1 Data Modeling Language; 283 Section 6.5: Schema Node Identifier; 284 RFC 7951, JSON Encoding of YANG Data; 285 Section 6.11: The instance-identifier type"; 286 } 288 leaf module-name { 289 type yang:yang-identifier; 290 description 291 "Name of the YANG module associated with this .sid file."; 292 } 294 leaf module-revision { 295 type revision-identifier; 296 description 297 "Revision of the YANG module associated with this .sid file. 298 This leaf is not present if no revision statement is 299 defined in the YANG module."; 300 } 302 list assigment-ranges { 303 key "entry-point"; 304 description 305 "SID range(s) allocated to the YANG module identified by 306 'module-name' and 'module-revision'."; 308 leaf entry-point { 309 type sid; 310 mandatory true; 311 description 312 "Lowest SID available for assignment."; 313 } 315 leaf size { 316 type uint64; 317 mandatory true; 318 description 319 "Number of SIDs available for assignment."; 320 } 321 } 323 list items { 324 key "namespace identifier"; 325 description 326 "Each entry within this list defined the mapping between 327 a YANG item string identifier and a SID. This list MUST 328 include a mapping entry for each YANG item defined by 329 the YANG module identified by 'module-name' and 330 'module-revision'."; 332 leaf namespace { 333 type enumeration { 334 enum module { 335 value 0; 336 description 337 "All module and submodule names share the same 338 global module identifier namespace."; 339 } 340 enum identity { 341 value 1; 342 description 343 "All identity names defined in a module and its 344 submodules share the same identity identifier 345 namespace."; 346 } 347 enum feature { 348 value 2; 349 description 350 "All feature names defined in a module and its 351 submodules share the same feature identifier 352 namespace."; 353 } 354 enum data { 355 value 3; 356 description 357 "The namespace for all data nodes, as defined in YANG."; 358 } 359 } 360 description 361 "Namespace of the YANG item for this mapping entry."; 362 } 364 leaf identifier { 365 type union { 366 type yang:yang-identifier; 367 type schema-node-path; 368 } 369 description 370 "String identifier of the YANG item for this mapping entry. 372 If the corresponding 'namespace' field is 'module', 373 'feature', or 'identity', then this field MUST 374 contain a valid YANG identifier string. 376 If the corresponding 'namespace' field is 'data', 377 then this field MUST contain a valid schema node 378 path."; 379 } 381 leaf sid { 382 type sid; 383 mandatory true; 384 description 385 "SID assigned to the YANG item for this mapping entry."; 386 } 387 } 388 } 389 391 5. Security Considerations 393 This document defines a new type of identifier used to encode data 394 models defined in YANG [RFC7950]. As such, this identifier does not 395 contribute to any new security issues in addition of those identified 396 for the specific protocols or contexts for which it is used. 398 6. IANA Considerations 400 6.1. Register SID File Format Module 402 This document registers one YANG module in the "YANG Module Names" 403 registry [RFC6020]: 405 o name: ietf-sid-file 407 o namespace: urn:ietf:params:xml:ns:yang:ietf-sid-file 409 o prefix: sid 411 o reference: [[THISRFC]] 413 6.2. Create new IANA Registry: "SID Mega-Range" registry 415 The name of this registry is "SID Mega-Range". This registry is used 416 to record the delegation of the management of a block of SIDs to 417 third parties (such as SDOs or registrars). 419 6.2.1. Structure 421 Each entry in this registry must include: 423 o The entry point (first SID) of the registered SID block. 425 o The size of the registered SID block. The size MUST be one 426 million (1 000 000) SIDs. 428 o The contact information of the requesting organization including: 430 * The policy of SID range allocations: Public, Private or Both. 432 * Organization name 433 * URL 435 The information associated to the Organization name should not be 436 publicly visible in the registry, but should be available. This 437 information includes contact email and phone number and change 438 controller email and phone number. 440 6.2.2. Allocation policy 442 The IANA policy for future additions to this registry is "Expert 443 Review" [RFC8126]. 445 An organization requesting to manage a SID Range (and thus have an 446 entry in the SID Mega-Range Registry), must ensure the following 447 capacities: 449 o The capacity to manage and operate a SID Range Registry. A SID 450 Range Registry MUST provide the following information for all SID 451 Ranges allocated by the Registry: 453 * Entry Point of allocated SID Range 455 * Size of allocated SID Range 457 * Type: Public or Private 459 + Public Ranges MUST include at least a reference to the YANG 460 module and ".sid" files for that SID Range. 462 + Private Ranges MUST be marked as "Private" 464 o A Policy of allocation, which clearly identifies if the SID Range 465 allocations would be Private, Public or Both. 467 o Technical capacity to ensure the sustained operation of the 468 registry for a period of at least 5 years. If Private 469 Registrations are allowed, the period must be of at least 10 470 years. 472 6.2.2.1. First allocation 474 For a first allocation to be provided, the requesting organization 475 must demonstrate a functional registry infrastructure. 477 6.2.2.2. Consecutive allocations 479 On subsequent allocation request(s), the organization must 480 demonstrate the exhaustion of the prior range. These conditions need 481 to be asserted by the assigned expert(s). 483 If that extra-allocation is done within 3 years from the last 484 allocation, the experts need to discuss this request on the CORE 485 working group mailing list and consensus needs to be obtained before 486 allocating a new Mega-Range. 488 6.2.3. Initial contents of the Registry 490 The initial entry in this registry is allocated to IANA: 492 +-------------+---------+------------+-------------------+----------+ 493 | Entry Point | Size | Allocation | Organization name | URL | 494 +-------------+---------+------------+-------------------+----------+ 495 | 0 | 1000000 | Public | IANA | iana.org | 496 +-------------+---------+------------+-------------------+----------+ 498 6.3. Create a new IANA Registry: IETF SID Range Registry (managed by 499 IANA) 501 6.3.1. Structure 503 Each entry in this registry must include: 505 o The SID range entry point. 507 o The SID range size. 509 o The YANG module name. 511 o Document reference. 513 6.3.2. Allocation policy 515 The first million SIDs assigned to IANA is sub-divided as follows: 517 o The range of 0 to 999 (size 1000) is "Reserved" as defined in 518 [RFC8126]. 520 o The range of 1000 to 59,999 (size 59,000) is reserved for YANG 521 modules defined in RFCs. The IANA policy for additions to this 522 registry is "Expert Review" [RFC8126]. 524 * The Expert MUST verify that the YANG module for which this 525 allocation is made has an RFC (existing RFC) OR is on track to 526 become RFC (early allocation with a request from the WG 527 chairs). 529 o The SID range allocated for a YANG module can follow in one of the 530 four categories: 532 * SMALL (50 SIDs) 534 * MEDIUM (100 SIDs) 536 * LARGE (250 SIDs) 538 * CUSTOM (requested by the YANG module author, with a maximum of 539 1000 SIDs). In all cases, the size of a SID range assigned to 540 a YANG module should be at least 33% above the current number 541 of YANG items. This headroom allows assignment within the same 542 range of new YANG items introduced by subsequent revisions. A 543 larger SID range size may be requested by the authors if this 544 recommendation is considered insufficient. It is important to 545 note that an additional SID range can be allocated to an 546 existing YANG module if the initial range is exhausted. 548 o The range of 60,000 to 99,999 (size 40,000)is reserved for 549 experimental YANG modules. This range MUST NOT be used in 550 operational deployments since these SIDs are not globally unique 551 which limit their interoperability. The IANA policy for this 552 range is "Experimental use" [RFC8126]. 554 o The range of 100,000 to 999,999 (size 900,000) is "Reserved" as 555 defined in [RFC8126]. 557 +-------------+---------+------------------+ 558 | Entry Point | Size | IANA policy | 559 +-------------+---------+------------------+ 560 | 0 | 1,000 | Reserved | 561 | 1,000 | 59,000 | Expert Review | 562 | 60,000 | 40,000 | Experimental use | 563 | 100,000 | 900,000 | Reserved | 564 +-------------+---------+------------------+ 566 6.3.3. Initial contents of the registry 568 Initial entries in this registry are as follows: 570 +-------------+------+------------------+----------------------+ 571 | Entry Point | Size | Module name | Document reference | 572 +-------------+------+------------------+----------------------+ 573 | 1000 | 100 | ietf-comi | [I-D.ietf-core-comi] | 574 | 1100 | 50 | ietf-yang-types | [RFC6991] | 575 | 1150 | 50 | ietf-inet-types | [RFC6991] | 576 | 1200 | 50 | iana-crypt-hash | [RFC7317] | 577 | 1250 | 50 | ietf-netconf-acm | [RFC8341] | 578 | 1300 | 50 | ietf-sid-file | RFCXXXX | 579 | 1500 | 100 | ietf-interfaces | [RFC8343] | 580 | 1600 | 100 | ietf-ip | [RFC8344] | 581 | 1700 | 100 | ietf-system | [RFC7317] | 582 | 1800 | 400 | iana-if-type | [RFC7224] | 583 +-------------+------+------------------+----------------------+ 585 // RFC Ed.: replace XXXX with RFC number assigned to this draft. 587 For allocation, RFC publication of the YANG module is required as per 588 [RFC8126]. The YANG module must be registered in the "YANG module 589 Name" registry according to the rules specified in section 14 of 590 [RFC6020]. 592 6.4. Create new IANA Registry: "IETF SID Registry" 594 The name of this registry is "IETF SID Registry". This registry is 595 used to record the allocation of SIDs for individual YANG module 596 items. 598 6.4.1. Structure 600 Each entry in this registry must include: 602 o The YANG module name. This module name must be present in the 603 "Name" column of the "YANG Module Names" registry. 605 o A link to the associated ".yang" file. This file link must be 606 present in the "File" column of the "YANG Module Names" registry. 608 o The link to the ".sid" file which defines the allocation. 610 o The number of actually allocated SIDs in the ".sid" file. 612 The ".sid" file is stored by IANA. 614 6.4.2. Allocation policy 616 The allocation policy is Expert review. The Expert MUST ensure that 617 the following conditions are met: 619 o The ".sid" file has a valid structure: 621 * The ".sid" file MUST be a valid JSON file following the 622 structure of the module defined in RFCXXXX (RFC Ed: replace XXX 623 with RFC number assigned to this draft). 625 o The ".sid" file allocates individual SIDs ONLY in the SID Ranges 626 for this YANG module (as allocated in the IETF SID Range 627 Registry): 629 * All SIDs in this ".sid" file MUST be within the ranges 630 allocated to this YANG module in the "IETF SID Range Registry". 632 o If another ".sid" file has already allocated SIDs for this YANG 633 module (e.g. for older or newer versions of the YANG module), the 634 YANG items are assigned the same SIDs as in the the other ".sid" 635 file. 637 o SIDs never change. 639 6.4.3. Initial contents of the registry 641 None. 643 7. Acknowledgments 645 The authors would like to thank Andy Bierman, Carsten Bormann, 646 Abhinav Somaraju, Laurent Toutain, Randy Turner and Peter van der 647 Stok for their help during the development of this document and their 648 useful comments during the review process. 650 8. References 652 8.1. Normative References 654 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 655 Requirement Levels", BCP 14, RFC 2119, 656 DOI 10.17487/RFC2119, March 1997, 657 . 659 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 660 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 661 October 2013, . 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., and A. Bierman, "CoAP 683 Management Interface", draft-ietf-core-comi-05 (work in 684 progress), May 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