idnits 2.17.1 draft-ietf-netmod-rfc6991-bis-02.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 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 4, 2019) is 1633 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 2460 (Obsoleted by RFC 8200) -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Schoenwaelder, Ed. 3 Internet-Draft Jacobs University 4 Obsoletes: 6991 (if approved) November 4, 2019 5 Intended status: Standards Track 6 Expires: May 7, 2020 8 Common YANG Data Types 9 draft-ietf-netmod-rfc6991-bis-02 11 Abstract 13 This document introduces a collection of common data types to be used 14 with the YANG data modeling language. This document obsoletes RFC 15 6991. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on May 7, 2020. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 This document may contain material from IETF Documents or IETF 50 Contributions published or made publicly available before November 51 10, 2008. The person(s) controlling the copyright in some of this 52 material may not have granted the IETF Trust the right to allow 53 modifications of such material outside the IETF Standards Process. 54 Without obtaining an adequate license from the person(s) controlling 55 the copyright in such materials, this document may not be modified 56 outside the IETF Standards Process, and derivative works of it may 57 not be created outside the IETF Standards Process, except to format 58 it for publication as an RFC or to translate it into languages other 59 than English. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 3. Core YANG Derived Types . . . . . . . . . . . . . . . . . . . 7 66 4. Internet-Specific Derived Types . . . . . . . . . . . . . . . 24 67 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . 38 69 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 39 70 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40 71 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 72 9.1. Normative References . . . . . . . . . . . . . . . . . . . 41 73 9.2. Informative References . . . . . . . . . . . . . . . . . . 42 74 Appendix A. Changes from RFC 6991 . . . . . . . . . . . . . . . . 46 75 Appendix B. Changes from RFC 6021 . . . . . . . . . . . . . . . . 47 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 48 78 1. Introduction 80 YANG [RFC7950] is a data modeling language used to model 81 configuration and state data manipulated by the Network Configuration 82 Protocol (NETCONF) [RFC6241]. The YANG language supports a small set 83 of built-in data types and provides mechanisms to derive other types 84 from the built-in types. 86 This document introduces a collection of common data types derived 87 from the built-in YANG data types. The derived types are designed to 88 be applicable for modeling all areas of management information. The 89 definitions are organized in several YANG modules. The 90 "ietf-yang-types" module contains generally useful data types. The 91 "ietf-inet-types" module contains definitions that are relevant for 92 the Internet protocol suite. 94 This document adds new type definitions to the YANG modules and 95 obsoletes [RFC6991]. For further details, see the revision 96 statements of the YANG modules in Section 3 and Section 4 and the 97 summary in Appendix A. 99 This document uses the YANG terminology defined in Section 3 of 100 [RFC7950]. 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in BCP 105 14 [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 2. Overview 110 This section provides a short overview of the types defined in 111 subsequent sections and their equivalent Structure of Management 112 Information Version 2 (SMIv2) [RFC2578][RFC2579] data types. A YANG 113 data type is equivalent to an SMIv2 data type if the data types have 114 the same set of values and the semantics of the values are 115 equivalent. 117 Table 1 lists the types defined in the ietf-yang-types YANG module 118 and the corresponding SMIv2 types (- indicates there is no 119 corresponding SMIv2 type). 121 +--------------------------+--------------------------------+ 122 | YANG type | Equivalent SMIv2 type (module) | 123 +--------------------------+--------------------------------+ 124 | counter32 | Counter32 (SNMPv2-SMI) | 125 | zero-based-counter32 | ZeroBasedCounter32 (RMON2-MIB) | 126 | counter64 | Counter64 (SNMPv2-SMI) | 127 | zero-based-counter64 | ZeroBasedCounter64 (HCNUM-TC) | 128 | gauge32 | Gauge32 (SNMPv2-SMI) | 129 | gauge64 | CounterBasedGauge64 (HCNUM-TC) | 130 | object-identifier | - | 131 | object-identifier-128 | OBJECT IDENTIFIER | 132 | date-and-time | - | 133 | date | - | 134 | time | - | 135 | hours32 | - | 136 | minutes32 | - | 137 | seconds32 | - | 138 | centiseconds32 | TimeInterval (SNMPv2-TC) | 139 | milliseconds32 | - | 140 | microseconds32 | - | 141 | microseconds64 | - | 142 | nanoseconds32 | - | 143 | nanoseconds64 | - | 144 | timeticks | TimeTicks (SNMPv2-SMI) | 145 | timestamp | TimeStamp (SNMPv2-TC) | 146 | phys-address | PhysAddress (SNMPv2-TC) | 147 | mac-address | MacAddress (SNMPv2-TC) | 148 | xpath1.0 | - | 149 | hex-string | - | 150 | uuid | - | 151 | dotted-quad | - | 152 | yang-identifier | - | 153 | revision-identifier | - | 154 | node-instance-identifier | - | 155 +--------------------------+--------------------------------+ 157 Table 1: ietf-yang-types 159 Table 2 lists the types defined in the ietf-inet-types YANG module 160 and the corresponding SMIv2 types (if any). 162 +----------------------+--------------------------------------------+ 163 | YANG type | Equivalent SMIv2 type (module) | 164 +----------------------+--------------------------------------------+ 165 | ip-version | InetVersion (INET-ADDRESS-MIB) | 166 | dscp | Dscp (DIFFSERV-DSCP-TC) | 167 | ipv6-flow-label | IPv6FlowLabel (IPV6-FLOW-LABEL-MIB) | 168 | port-number | InetPortNumber (INET-ADDRESS-MIB) | 169 | as-number | InetAutonomousSystemNumber | 170 | | (INET-ADDRESS-MIB) | 171 | ip-address | - | 172 | ipv4-address | - | 173 | ipv6-address | - | 174 | ip-address-no-zone | - | 175 | ipv4-address-no-zone | - | 176 | ipv6-address-no-zone | - | 177 | ip-prefix | - | 178 | ipv4-prefix | - | 179 | ipv6-prefix | - | 180 | domain-name | - | 181 | host | - | 182 | uri | Uri (URI-TC-MIB) | 183 | email-address | - | 184 +----------------------+--------------------------------------------+ 186 Table 2: ietf-inet-types 188 3. Core YANG Derived Types 190 The ietf-yang-types YANG module references [IEEE802], [ISO9834-1], 191 [RFC2578], [RFC2579], [RFC2856], [RFC3339], [RFC4122], [RFC4502], 192 [RFC5322], [RFC7950], [XPATH], and [XSD-TYPES]. 194 file "ietf-yang-types@2019-11-04.yang" 196 module ietf-yang-types { 198 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-types"; 199 prefix "yang"; 201 organization 202 "IETF Network Modeling (NETMOD) Working Group"; 204 contact 205 "WG Web: 206 WG List: 208 Editor: Juergen Schoenwaelder 209 "; 211 description 212 "This module contains a collection of generally useful derived 213 YANG data types. 215 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 216 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 217 'MAY', and 'OPTIONAL' in this document are to be interpreted as 218 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 219 they appear in all capitals, as shown here. 221 Copyright (c) 2019 IETF Trust and the persons identified as 222 authors of the code. All rights reserved. 224 Redistribution and use in source and binary forms, with or 225 without modification, is permitted pursuant to, and subject 226 to the license terms contained in, the Simplified BSD License 227 set forth in Section 4.c of the IETF Trust's Legal Provisions 228 Relating to IETF Documents 229 (http://trustee.ietf.org/license-info). 231 This version of this YANG module is part of RFC XXXX; 232 see the RFC itself for full legal notices."; 234 revision 2019-11-04 { 235 description 236 "This revision adds the following new data types: 237 - date, time 238 - hours32, minutes32, seconds32, centiseconds32, milliseconds32, 239 - microseconds32, microseconds64, nanoseconds32, nanoseconds64 240 - revision-identifier, node-instance-identifier"; 241 reference 242 "RFC XXXX: Common YANG Data Types"; 243 } 245 revision 2013-07-15 { 246 description 247 "This revision adds the following new data types: 248 - yang-identifier 249 - hex-string 250 - uuid 251 - dotted-quad"; 252 reference 253 "RFC 6991: Common YANG Data Types"; 254 } 256 revision 2010-09-24 { 257 description 258 "Initial revision."; 259 reference 260 "RFC 6021: Common YANG Data Types"; 261 } 263 /*** collection of counter and gauge types ***/ 265 typedef counter32 { 266 type uint32; 267 description 268 "The counter32 type represents a non-negative integer 269 that monotonically increases until it reaches a 270 maximum value of 2^32-1 (4294967295 decimal), when it 271 wraps around and starts increasing again from zero. 273 Counters have no defined 'initial' value, and thus, a 274 single value of a counter has (in general) no information 275 content. Discontinuities in the monotonically increasing 276 value normally occur at re-initialization of the 277 management system, and at other times as specified in the 278 description of a schema node using this type. If such 279 other times can occur, for example, the instantiation of 280 a schema node of type counter32 at times other than 281 re-initialization, then a corresponding schema node 282 should be defined, with an appropriate type, to indicate 283 the last discontinuity. 285 The counter32 type should not be used for configuration 286 schema nodes. A default statement SHOULD NOT be used in 287 combination with the type counter32. 289 In the value set and its semantics, this type is equivalent 290 to the Counter32 type of the SMIv2."; 291 reference 292 "RFC 2578: Structure of Management Information Version 2 293 (SMIv2)"; 294 } 296 typedef zero-based-counter32 { 297 type yang:counter32; 298 default "0"; 299 description 300 "The zero-based-counter32 type represents a counter32 301 that has the defined 'initial' value zero. 303 A schema node instance of this type will be set to zero (0) 304 on creation and will thereafter increase monotonically until 305 it reaches a maximum value of 2^32-1 (4294967295 decimal), 306 when it wraps around and starts increasing again from zero. 308 Provided that an application discovers a new schema node 309 instance of this type within the minimum time to wrap, it 310 can use the 'initial' value as a delta. It is important for 311 a management station to be aware of this minimum time and the 312 actual time between polls, and to discard data if the actual 313 time is too long or there is no defined minimum time. 315 In the value set and its semantics, this type is equivalent 316 to the ZeroBasedCounter32 textual convention of the SMIv2."; 317 reference 318 "RFC 4502: Remote Network Monitoring Management Information 319 Base Version 2"; 320 } 322 typedef counter64 { 323 type uint64; 324 description 325 "The counter64 type represents a non-negative integer 326 that monotonically increases until it reaches a 327 maximum value of 2^64-1 (18446744073709551615 decimal), 328 when it wraps around and starts increasing again from zero. 330 Counters have no defined 'initial' value, and thus, a 331 single value of a counter has (in general) no information 332 content. Discontinuities in the monotonically increasing 333 value normally occur at re-initialization of the 334 management system, and at other times as specified in the 335 description of a schema node using this type. If such 336 other times can occur, for example, the instantiation of 337 a schema node of type counter64 at times other than 338 re-initialization, then a corresponding schema node 339 should be defined, with an appropriate type, to indicate 340 the last discontinuity. 342 The counter64 type should not be used for configuration 343 schema nodes. A default statement SHOULD NOT be used in 344 combination with the type counter64. 346 In the value set and its semantics, this type is equivalent 347 to the Counter64 type of the SMIv2."; 348 reference 349 "RFC 2578: Structure of Management Information Version 2 350 (SMIv2)"; 351 } 353 typedef zero-based-counter64 { 354 type yang:counter64; 355 default "0"; 356 description 357 "The zero-based-counter64 type represents a counter64 that 358 has the defined 'initial' value zero. 360 A schema node instance of this type will be set to zero (0) 361 on creation and will thereafter increase monotonically until 362 it reaches a maximum value of 2^64-1 (18446744073709551615 363 decimal), when it wraps around and starts increasing again 364 from zero. 366 Provided that an application discovers a new schema node 367 instance of this type within the minimum time to wrap, it 368 can use the 'initial' value as a delta. It is important for 369 a management station to be aware of this minimum time and the 370 actual time between polls, and to discard data if the actual 371 time is too long or there is no defined minimum time. 373 In the value set and its semantics, this type is equivalent 374 to the ZeroBasedCounter64 textual convention of the SMIv2."; 375 reference 376 "RFC 2856: Textual Conventions for Additional High Capacity 377 Data Types"; 378 } 380 typedef gauge32 { 381 type uint32; 382 description 383 "The gauge32 type represents a non-negative integer, which 384 may increase or decrease, but shall never exceed a maximum 385 value, nor fall below a minimum value. The maximum value 386 cannot be greater than 2^32-1 (4294967295 decimal), and 387 the minimum value cannot be smaller than 0. The value of 388 a gauge32 has its maximum value whenever the information 389 being modeled is greater than or equal to its maximum 390 value, and has its minimum value whenever the information 391 being modeled is smaller than or equal to its minimum value. 392 If the information being modeled subsequently decreases 393 below (increases above) the maximum (minimum) value, the 394 gauge32 also decreases (increases). 396 In the value set and its semantics, this type is equivalent 397 to the Gauge32 type of the SMIv2."; 398 reference 399 "RFC 2578: Structure of Management Information Version 2 400 (SMIv2)"; 401 } 403 typedef gauge64 { 404 type uint64; 405 description 406 "The gauge64 type represents a non-negative integer, which 407 may increase or decrease, but shall never exceed a maximum 408 value, nor fall below a minimum value. The maximum value 409 cannot be greater than 2^64-1 (18446744073709551615), and 410 the minimum value cannot be smaller than 0. The value of 411 a gauge64 has its maximum value whenever the information 412 being modeled is greater than or equal to its maximum 413 value, and has its minimum value whenever the information 414 being modeled is smaller than or equal to its minimum value. 415 If the information being modeled subsequently decreases 416 below (increases above) the maximum (minimum) value, the 417 gauge64 also decreases (increases). 419 In the value set and its semantics, this type is equivalent 420 to the CounterBasedGauge64 SMIv2 textual convention defined 421 in RFC 2856"; 422 reference 423 "RFC 2856: Textual Conventions for Additional High Capacity 424 Data Types"; 425 } 427 /*** collection of identifier-related types ***/ 428 typedef object-identifier { 429 type string { 430 pattern '(([0-1](\.[1-3]?[0-9]))|(2\.(0|([1-9]\d*))))' 431 + '(\.(0|([1-9]\d*)))*'; 432 } 433 description 434 "The object-identifier type represents administratively 435 assigned names in a registration-hierarchical-name tree. 437 Values of this type are denoted as a sequence of numerical 438 non-negative sub-identifier values. Each sub-identifier 439 value MUST NOT exceed 2^32-1 (4294967295). Sub-identifiers 440 are separated by single dots and without any intermediate 441 whitespace. 443 The ASN.1 standard restricts the value space of the first 444 sub-identifier to 0, 1, or 2. Furthermore, the value space 445 of the second sub-identifier is restricted to the range 446 0 to 39 if the first sub-identifier is 0 or 1. Finally, 447 the ASN.1 standard requires that an object identifier 448 has always at least two sub-identifiers. The pattern 449 captures these restrictions. 451 Although the number of sub-identifiers is not limited, 452 module designers should realize that there may be 453 implementations that stick with the SMIv2 limit of 128 454 sub-identifiers. 456 This type is a superset of the SMIv2 OBJECT IDENTIFIER type 457 since it is not restricted to 128 sub-identifiers. Hence, 458 this type SHOULD NOT be used to represent the SMIv2 OBJECT 459 IDENTIFIER type; the object-identifier-128 type SHOULD be 460 used instead."; 461 reference 462 "ISO9834-1: Information technology -- Open Systems 463 Interconnection -- Procedures for the operation of OSI 464 Registration Authorities: General procedures and top 465 arcs of the ASN.1 Object Identifier tree"; 466 } 468 typedef object-identifier-128 { 469 type object-identifier { 470 pattern '\d*(\.\d*){1,127}'; 471 } 472 description 473 "This type represents object-identifiers restricted to 128 474 sub-identifiers. 476 In the value set and its semantics, this type is equivalent 477 to the OBJECT IDENTIFIER type of the SMIv2."; 478 reference 479 "RFC 2578: Structure of Management Information Version 2 480 (SMIv2)"; 481 } 483 /*** collection of types related to date and time ***/ 485 typedef date-and-time { 486 type string { 487 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?' 488 + '(Z|[\+\-]\d{2}:\d{2})'; 489 } 490 description 491 "The date-and-time type is a profile of the ISO 8601 492 standard for representation of dates and times using the 493 Gregorian calendar. The profile is defined by the 494 date-time production in Section 5.6 of RFC 3339. 496 The date-and-time type is compatible with the dateTime XML 497 schema type with the following notable exceptions: 499 (a) The date-and-time type does not allow negative years. 501 (b) The date-and-time time-offset -00:00 indicates an unknown 502 time zone (see RFC 3339) while -00:00 and +00:00 and Z 503 all represent the same time zone in dateTime. 505 (c) The canonical format (see below) of date-and-time values 506 differs from the canonical format used by the dateTime XML 507 schema type, which requires all times to be in UTC using 508 the time-offset 'Z'. 510 This type is not equivalent to the DateAndTime textual 511 convention of the SMIv2 since RFC 3339 uses a different 512 separator between full-date and full-time and provides 513 higher resolution of time-secfrac. 515 The canonical format for date-and-time values with a known time 516 zone uses a numeric time zone offset that is calculated using 517 the device's configured known offset to UTC time. A change of 518 the device's offset to UTC time will cause date-and-time values 519 to change accordingly. Such changes might happen periodically 520 in case a server follows automatically daylight saving time 521 (DST) time zone offset changes. The canonical format for 522 date-and-time values with an unknown time zone (usually 523 referring to the notion of local time) uses the time-offset 524 -00:00."; 525 reference 526 "RFC 3339: Date and Time on the Internet: Timestamps 527 RFC 2579: Textual Conventions for SMIv2 528 XSD-TYPES: XML Schema Part 2: Datatypes Second Edition"; 529 } 531 typedef date { 532 type string { 533 pattern '\d{4}-\d{2}-\d{2}' 534 + '(Z|[\+\-]\d{2}:\d{2})'; 535 } 536 description 537 "The date type represents a time-interval of the length 538 of a day, i.e., 24 hours. 540 The date type is compatible with the date XML schema 541 type with the following notable exceptions: 543 (a) The date type does not allow negative years. 545 (b) The date time-offset -00:00 indicates an unknown 546 time zone (see RFC 3339) while -00:00 and +00:00 and Z 547 all represent the same time zone in date. 549 (c) The canonical format (see below) of data values 550 differs from the canonical format used by the date XML 551 schema type, which requires all times to be in UTC using 552 the time-offset 'Z'. 554 The canonical format for date values with a known time 555 zone uses a numeric time zone offset that is calculated using 556 the device's configured known offset to UTC time. A change of 557 the device's offset to UTC time will cause date values 558 to change accordingly. Such changes might happen periodically 559 in case a server follows automatically daylight saving time 560 (DST) time zone offset changes. The canonical format for 561 date values with an unknown time zone (usually referring 562 to the notion of local time) uses the time-offset -00:00."; 563 reference 564 "RFC 3339: Date and Time on the Internet: Timestamps 565 XSD-TYPES: XML Schema Part 2: Datatypes Second Edition"; 566 } 568 /* 569 * DISCUSS: 570 * - XML schema seems to use a different canonical format, we 571 * need to take a closer look how to define the canonical format 572 * given that a data really identifies a 24 hour interval and 573 * what XSD means with 'interval midpoint'. 574 */ 576 typedef time { 577 type string { 578 pattern '\d{2}:\d{2}:\d{2}(\.\d+)?' 579 + '(Z|[\+\-]\d{2}:\d{2})'; 580 } 581 description 582 "The time type represents an instance of time of zero-duration 583 that recurs every day. 585 The time type is compatible with the time XML schema 586 type with the following notable exceptions: 588 (a) The time time-offset -00:00 indicates an unknown 589 time zone (see RFC 3339) while -00:00 and +00:00 and Z 590 all represent the same time zone in time. 592 (c) The canonical format (see below) of time values 593 differs from the canonical format used by the time XML 594 schema type, which requires all times to be in UTC using 595 the time-offset 'Z'. 597 The canonical format for time values with a known time 598 zone uses a numeric time zone offset that is calculated using 599 the device's configured known offset to UTC time. A change of 600 the device's offset to UTC time will cause time values 601 to change accordingly. Such changes might happen periodically 602 in case a server follows automatically daylight saving time 603 (DST) time zone offset changes. The canonical format for 604 time values with an unknown time zone (usually referring 605 to the notion of local time) uses the time-offset -00:00."; 606 reference 607 "RFC 3339: Date and Time on the Internet: Timestamps 608 XSD-TYPES: XML Schema Part 2: Datatypes Second Edition"; 609 } 611 typedef hours32 { 612 type int32; 613 units "hours"; 614 description 615 "A period of time, measured in units of hours. 617 The maximum time period that can be expressed is in the 618 range [89478485 days 08:00:00 to 89478485 days 07:00:00]. 620 This type should be range restricted in situations 621 where only non-negative time periods are desirable, 622 (i.e., range '0..max')."; 623 } 625 typedef minutes32 { 626 type int32; 627 units "minutes"; 628 description 629 "A period of time, measured in units of minutes. 631 The maximum time period that can be expressed is in the 632 range [-1491308 days 2:08:00 to 1491308 days 2:07:00]. 634 This type should be range restricted in situations 635 where only non-negative time periods are desirable, 636 (i.e., range '0..max')."; 637 } 639 typedef seconds32 { 640 type int32; 641 units "seconds"; 642 description 643 "A period of time, measured in units of seconds. 645 The maximum time period that can be expressed is in the 646 range [-24855 days 03:14:08 to 24855 days 03:14:07]. 648 This type should be range restricted in situations 649 where only non-negative time periods are desirable, 650 (i.e., range '0..max')."; 651 } 653 typedef centiseconds32 { 654 type int32; 655 units "centiseconds"; 656 description 657 "A period of time, measured in units of 10^-2 seconds. 659 The maximum time period that can be expressed is in the 660 range [-248 days 13:13:56 to 248 days 13:13:56]. 662 This type should be range restricted in situations 663 where only non-negative time periods are desirable, 664 (i.e., range '0..max')."; 665 } 667 typedef milliseconds32 { 668 type int32; 669 units "milliseconds"; 670 description 671 "A period of time, measured in units of 10^-3 seconds. 673 The maximum time period that can be expressed is in the 674 range [-24 days 20:31:23 to 24 days 20:31:23]. 676 This type should be range restricted in situations 677 where only non-negative time periods are desirable, 678 (i.e., range '0..max')."; 679 } 681 typedef microseconds32 { 682 type int32; 683 units "microseconds"; 684 description 685 "A period of time, measured in units of 10^-6 seconds. 687 The maximum time period that can be expressed is in the 688 range [-00:35:47 to 00:35:47]. 690 This type should be range restricted in situations 691 where only non-negative time periods are desirable, 692 (i.e., range '0..max')."; 693 } 695 typedef microseconds64 { 696 type int64; 697 units "microseconds"; 698 description 699 "A period of time, measured in units of 10^-6 seconds. 701 The maximum time period that can be expressed is in the 702 range [-106751991 days 04:00:54 to 106751991 days 04:00:54]. 704 This type should be range restricted in situations 705 where only non-negative time periods are desirable, 706 (i.e., range '0..max')."; 707 } 709 typedef nanoseconds32 { 710 type int32; 711 units "nanoseconds"; 712 description 713 "A period of time, measured in units of 10^-9 seconds. 715 The maximum time period that can be expressed is in the 716 range [-00:00:02 to 00:00:02]. 718 This type should be range restricted in situations 719 where only non-negative time periods are desirable, 720 (i.e., range '0..max')."; 721 } 723 typedef nanoseconds64 { 724 type int64; 725 units "nanoseconds"; 726 description 727 "A period of time, measured in units of 10^-9 seconds. 729 The maximum time period that can be expressed is in the 730 range [-106753 days 23:12:44 to 106752 days 0:47:16]. 732 This type should be range restricted in situations 733 where only non-negative time periods are desirable, 734 (i.e., range '0..max')."; 735 } 737 typedef timeticks { 738 type uint32; 739 description 740 "The timeticks type represents a non-negative integer that 741 represents the time, modulo 2^32 (4294967296 decimal), in 742 hundredths of a second between two epochs. When a schema 743 node is defined that uses this type, the description of 744 the schema node identifies both of the reference epochs. 746 In the value set and its semantics, this type is equivalent 747 to the TimeTicks type of the SMIv2."; 748 reference 749 "RFC 2578: Structure of Management Information Version 2 750 (SMIv2)"; 751 } 753 typedef timestamp { 754 type yang:timeticks; 755 description 756 "The timestamp type represents the value of an associated 757 timeticks schema node instance at which a specific occurrence 758 happened. The specific occurrence must be defined in the 759 description of any schema node defined using this type. When 760 the specific occurrence occurred prior to the last time the 761 associated timeticks schema node instance was zero, then the 762 timestamp value is zero. 764 Note that this requires all timestamp values to be reset to 765 zero when the value of the associated timeticks schema node 766 instance reaches 497+ days and wraps around to zero. 768 The associated timeticks schema node must be specified 769 in the description of any schema node using this type. 771 In the value set and its semantics, this type is equivalent 772 to the TimeStamp textual convention of the SMIv2."; 773 reference 774 "RFC 2579: Textual Conventions for SMIv2"; 775 } 777 /*** collection of generic address types ***/ 779 typedef phys-address { 780 type string { 781 pattern '([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)?'; 782 } 783 description 784 "Represents media- or physical-level addresses represented 785 as a sequence octets, each octet represented by two hexadecimal 786 numbers. Octets are separated by colons. The canonical 787 representation uses lowercase characters. 789 In the value set and its semantics, this type is equivalent 790 to the PhysAddress textual convention of the SMIv2."; 791 reference 792 "RFC 2579: Textual Conventions for SMIv2"; 793 } 795 typedef mac-address { 796 type string { 797 pattern '[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}'; 798 } 799 description 800 "The mac-address type represents an IEEE 802 MAC address. 801 The canonical representation uses lowercase characters. 803 In the value set and its semantics, this type is equivalent 804 to the MacAddress textual convention of the SMIv2."; 805 reference 806 "IEEE 802: IEEE Standard for Local and Metropolitan Area 807 Networks: Overview and Architecture 808 RFC 2579: Textual Conventions for SMIv2"; 809 } 811 /*** collection of XML-specific types ***/ 812 typedef xpath1.0 { 813 type string; 814 description 815 "This type represents an XPATH 1.0 expression. 817 When a schema node is defined that uses this type, the 818 description of the schema node MUST specify the XPath 819 context in which the XPath expression is evaluated."; 820 reference 821 "XPATH: XML Path Language (XPath) Version 1.0"; 822 } 824 /* 825 * DISCUSS: 826 * - How do we deal with xpath expressions in other encodings 827 * such as JSON. Do we assume an xpath context populated with 828 * module names such that module names can be used to qualify 829 * path expressions. This may need discussion and/or a new 830 * definition. 831 * - This interacts with the definition of node-instance-identifier. 832 */ 834 /*** collection of string types ***/ 836 typedef hex-string { 837 type string { 838 pattern '([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)?'; 839 } 840 description 841 "A hexadecimal string with octets represented as hex digits 842 separated by colons. The canonical representation uses 843 lowercase characters."; 844 } 846 typedef uuid { 847 type string { 848 pattern '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-' 849 + '[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'; 850 } 851 description 852 "A Universally Unique IDentifier in the string representation 853 defined in RFC 4122. The canonical representation uses 854 lowercase characters. 856 The following is an example of a UUID in string representation: 857 f81d4fae-7dec-11d0-a765-00a0c91e6bf6 858 "; 859 reference 860 "RFC 4122: A Universally Unique IDentifier (UUID) URN 861 Namespace"; 862 } 864 typedef dotted-quad { 865 type string { 866 pattern 867 '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}' 868 + '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'; 869 } 870 description 871 "An unsigned 32-bit number expressed in the dotted-quad 872 notation, i.e., four octets written as decimal numbers 873 and separated with the '.' (full stop) character."; 874 } 876 /*** collection of YANG specific types ***/ 878 typedef yang-identifier { 879 type string { 880 length "1..max"; 881 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 882 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 883 } 884 description 885 "A YANG identifier string as defined by the 'identifier' 886 rule in Section 12 of RFC 6020. An identifier must 887 start with an alphabetic character or an underscore 888 followed by an arbitrary sequence of alphabetic or 889 numeric characters, underscores, hyphens, or dots. 891 A YANG identifier MUST NOT start with any possible 892 combination of the lowercase or uppercase character 893 sequence 'xml'."; 894 reference 895 "RFC 6020: YANG - A Data Modeling Language for the Network 896 Configuration Protocol (NETCONF)"; 897 } 899 typedef revision-identifier { 900 type date { 901 pattern '\d{4}-\d{2}-\d{2}'; 902 } 903 description 904 "Represents a specific revision of a YANG module by means of 905 a date value without a time zone."; 906 } 907 typedef node-instance-identifier { 908 type xpath1.0; 909 description 910 "Path expression used to represent a data node, action, 911 or notification instance-identifier string. 913 A node-instance-identifier value is an unrestricted 914 YANG instance-identifier expression or the special 915 value '/', which refers to the entire accessible tree. 917 All the rules for instance-identifier apply, except that 918 predicates for keys are optional. If a key predicate is 919 missing, then the node-instance-identifier represents all 920 possible server instances for that key. 922 This XML Path Language (XPath) expression is evaluated in the 923 following context: 925 o The set of namespace declarations are those in scope on 926 the leaf element where this type is used. 928 o The set of variable bindings contains one variable, 929 'USER', which contains the name of the user of the 930 current session. 932 o The function library is the core function library, but 933 note that due to the syntax restrictions of an 934 instance-identifier, no functions are allowed. 936 o The context node is the root node in the data tree. 938 The accessible tree includes actions and notifications tied 939 to data nodes."; 940 } 942 /* 943 * DISCUSS: 944 * - This is taken from RFC 8341 and the idea is that this definition 945 * is useful without requiring a dependency on NACM 946 * - What does the second bullet actually do? Do we keep this? 947 * - This interacts with the definition of xpath1.0. 948 */ 950 /* DISCUSS: 951 * - It was suggested to add types for longitude, latitude, 952 * postal code, country-code. Do we go there or do we leave 953 * these for other modules to define? It seems such definitions 954 * should go into draft-ietf-netmod-geo-location. 956 */ 958 /* DISCUSS: 959 * - It was suggested to add percentage types but they tend to differ 960 * widely. However, percentages are also widely used. 961 */ 962 } 964 966 4. Internet-Specific Derived Types 968 The ietf-inet-types YANG module references [RFC0768], [RFC0791], 969 [RFC0793], [RFC0952], [RFC1034], [RFC1123], [RFC1930], [RFC2317], 970 [RFC2460], [RFC2474], [RFC2780], [RFC2782], [RFC3289], [RFC3305], 971 [RFC3595], [RFC3986], [RFC4001], [RFC4007], [RFC4271], [RFC4291], 972 [RFC4340], [RFC4592] [RFC4960], [RFC5017], [RFC5890], [RFC5952], and 973 [RFC6793]. 975 file "ietf-inet-types@2019-11-04.yang" 977 module ietf-inet-types { 979 namespace "urn:ietf:params:xml:ns:yang:ietf-inet-types"; 980 prefix "inet"; 982 organization 983 "IETF Network Modeling (NETMOD) Working Group"; 985 contact 986 "WG Web: 987 WG List: 989 Editor: Juergen Schoenwaelder 990 "; 992 description 993 "This module contains a collection of generally useful derived 994 YANG data types for Internet addresses and related things. 996 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 997 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 998 'MAY', and 'OPTIONAL' in this document are to be interpreted as 999 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1000 they appear in all capitals, as shown here. 1002 Copyright (c) 2019 IETF Trust and the persons identified as 1003 authors of the code. All rights reserved. 1005 Redistribution and use in source and binary forms, with or 1006 without modification, is permitted pursuant to, and subject 1007 to the license terms contained in, the Simplified BSD License 1008 set forth in Section 4.c of the IETF Trust's Legal Provisions 1009 Relating to IETF Documents 1010 (http://trustee.ietf.org/license-info). 1012 This version of this YANG module is part of RFC XXXX; 1013 see the RFC itself for full legal notices."; 1015 revision 2019-11-04 { 1016 description 1017 "This revision adds the following new data types: 1018 - ip-address-and-prefix 1019 - ipv4-address-and-prefix 1020 - ipv6-address-and-prefix 1021 - email-address"; 1022 reference 1023 "RFC XXXX: Common YANG Data Types"; 1024 } 1026 revision 2013-07-15 { 1027 description 1028 "This revision adds the following new data types: 1029 - ip-address-no-zone 1030 - ipv4-address-no-zone 1031 - ipv6-address-no-zone"; 1032 reference 1033 "RFC 6991: Common YANG Data Types"; 1034 } 1036 revision 2010-09-24 { 1037 description 1038 "Initial revision."; 1039 reference 1040 "RFC 6021: Common YANG Data Types"; 1041 } 1043 /*** collection of types related to protocol fields ***/ 1045 typedef ip-version { 1046 type enumeration { 1047 enum unknown { 1048 value "0"; 1049 description 1050 "An unknown or unspecified version of the Internet 1051 protocol."; 1052 } 1053 enum ipv4 { 1054 value "1"; 1055 description 1056 "The IPv4 protocol as defined in RFC 791."; 1057 } 1058 enum ipv6 { 1059 value "2"; 1060 description 1061 "The IPv6 protocol as defined in RFC 2460."; 1062 } 1064 } 1065 description 1066 "This value represents the version of the IP protocol. 1068 In the value set and its semantics, this type is equivalent 1069 to the InetVersion textual convention of the SMIv2."; 1070 reference 1071 "RFC 791: Internet Protocol 1072 RFC 2460: Internet Protocol, Version 6 (IPv6) Specification 1073 RFC 4001: Textual Conventions for Internet Network Addresses"; 1074 } 1076 typedef dscp { 1077 type uint8 { 1078 range "0..63"; 1079 } 1080 description 1081 "The dscp type represents a Differentiated Services Code Point 1082 that may be used for marking packets in a traffic stream. 1084 In the value set and its semantics, this type is equivalent 1085 to the Dscp textual convention of the SMIv2."; 1086 reference 1087 "RFC 3289: Management Information Base for the Differentiated 1088 Services Architecture 1089 RFC 2474: Definition of the Differentiated Services Field 1090 (DS Field) in the IPv4 and IPv6 Headers 1091 RFC 2780: IANA Allocation Guidelines For Values In 1092 the Internet Protocol and Related Headers"; 1093 } 1095 typedef ipv6-flow-label { 1096 type uint32 { 1097 range "0..1048575"; 1098 } 1099 description 1100 "The ipv6-flow-label type represents the flow identifier or 1101 Flow Label in an IPv6 packet header that may be used to 1102 discriminate traffic flows. 1104 In the value set and its semantics, this type is equivalent 1105 to the IPv6FlowLabel textual convention of the SMIv2."; 1106 reference 1107 "RFC 3595: Textual Conventions for IPv6 Flow Label 1108 RFC 2460: Internet Protocol, Version 6 (IPv6) Specification"; 1109 } 1111 typedef port-number { 1112 type uint16 { 1113 range "0..65535"; 1114 } 1115 description 1116 "The port-number type represents a 16-bit port number of an 1117 Internet transport-layer protocol such as UDP, TCP, DCCP, or 1118 SCTP. Port numbers are assigned by IANA. A current list of 1119 all assignments is available from . 1121 Note that the port number value zero is reserved by IANA. In 1122 situations where the value zero does not make sense, it can 1123 be excluded by subtyping the port-number type. 1125 In the value set and its semantics, this type is equivalent 1126 to the InetPortNumber textual convention of the SMIv2."; 1127 reference 1128 "RFC 768: User Datagram Protocol 1129 RFC 793: Transmission Control Protocol 1130 RFC 4960: Stream Control Transmission Protocol 1131 RFC 4340: Datagram Congestion Control Protocol (DCCP) 1132 RFC 4001: Textual Conventions for Internet Network Addresses"; 1133 } 1135 /*** collection of types related to autonomous systems ***/ 1137 typedef as-number { 1138 type uint32; 1139 description 1140 "The as-number type represents autonomous system numbers 1141 which identify an Autonomous System (AS). An AS is a set 1142 of routers under a single technical administration, using 1143 an interior gateway protocol and common metrics to route 1144 packets within the AS, and using an exterior gateway 1145 protocol to route packets to other ASes. IANA maintains 1146 the AS number space and has delegated large parts to the 1147 regional registries. 1149 Autonomous system numbers were originally limited to 16 1150 bits. BGP extensions have enlarged the autonomous system 1151 number space to 32 bits. This type therefore uses an uint32 1152 base type without a range restriction in order to support 1153 a larger autonomous system number space. 1155 In the value set and its semantics, this type is equivalent 1156 to the InetAutonomousSystemNumber textual convention of 1157 the SMIv2."; 1158 reference 1159 "RFC 1930: Guidelines for creation, selection, and registration 1160 of an Autonomous System (AS) 1161 RFC 4271: A Border Gateway Protocol 4 (BGP-4) 1162 RFC 4001: Textual Conventions for Internet Network Addresses 1163 RFC 6793: BGP Support for Four-Octet Autonomous System (AS) 1164 Number Space"; 1165 } 1167 /*** collection of types related to IP addresses and hostnames ***/ 1169 typedef ip-address { 1170 type union { 1171 type inet:ipv4-address; 1172 type inet:ipv6-address; 1173 } 1174 description 1175 "The ip-address type represents an IP address and is IP 1176 version neutral. The format of the textual representation 1177 implies the IP version. This type supports scoped addresses 1178 by allowing zone identifiers in the address format."; 1179 reference 1180 "RFC 4007: IPv6 Scoped Address Architecture"; 1181 } 1183 typedef ipv4-address { 1184 type string { 1185 pattern 1186 '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}' 1187 + '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])' 1188 + '(%[\p{N}\p{L}]+)?'; 1189 } 1190 description 1191 "The ipv4-address type represents an IPv4 address in 1192 dotted-quad notation. The IPv4 address may include a zone 1193 index, separated by a % sign. 1195 The zone index is used to disambiguate identical address 1196 values. For link-local addresses, the zone index will 1197 typically be the interface index number or the name of an 1198 interface. If the zone index is not present, the default 1199 zone of the device will be used. 1201 The canonical format for the zone index is the numerical 1202 format"; 1203 } 1205 typedef ipv6-address { 1206 type string { 1207 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}' 1208 + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|' 1209 + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}' 1210 + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))' 1211 + '(%[\p{N}\p{L}]+)?'; 1212 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|' 1213 + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)' 1214 + '(%.+)?'; 1215 } 1216 description 1217 "The ipv6-address type represents an IPv6 address in full, 1218 mixed, shortened, and shortened-mixed notation. The IPv6 1219 address may include a zone index, separated by a % sign. 1221 The zone index is used to disambiguate identical address 1222 values. For link-local addresses, the zone index will 1223 typically be the interface index number or the name of an 1224 interface. If the zone index is not present, the default 1225 zone of the device will be used. 1227 The canonical format of IPv6 addresses uses the textual 1228 representation defined in Section 4 of RFC 5952. The 1229 canonical format for the zone index is the numerical 1230 format as described in Section 11.2 of RFC 4007."; 1231 reference 1232 "RFC 4291: IP Version 6 Addressing Architecture 1233 RFC 4007: IPv6 Scoped Address Architecture 1234 RFC 5952: A Recommendation for IPv6 Address Text 1235 Representation"; 1236 } 1238 typedef ip-address-no-zone { 1239 type union { 1240 type inet:ipv4-address-no-zone; 1241 type inet:ipv6-address-no-zone; 1242 } 1243 description 1244 "The ip-address-no-zone type represents an IP address and is 1245 IP version neutral. The format of the textual representation 1246 implies the IP version. This type does not support scoped 1247 addresses since it does not allow zone identifiers in the 1248 address format."; 1249 reference 1250 "RFC 4007: IPv6 Scoped Address Architecture"; 1251 } 1253 typedef ipv4-address-no-zone { 1254 type inet:ipv4-address { 1255 pattern '[0-9\.]*'; 1257 } 1258 description 1259 "An IPv4 address without a zone index. This type, derived from 1260 ipv4-address, may be used in situations where the zone is known 1261 from the context and hence no zone index is needed."; 1262 } 1264 typedef ipv6-address-no-zone { 1265 type inet:ipv6-address { 1266 pattern '[0-9a-fA-F:\.]*'; 1267 } 1268 description 1269 "An IPv6 address without a zone index. This type, derived from 1270 ipv6-address, may be used in situations where the zone is known 1271 from the context and hence no zone index is needed."; 1272 reference 1273 "RFC 4291: IP Version 6 Addressing Architecture 1274 RFC 4007: IPv6 Scoped Address Architecture 1275 RFC 5952: A Recommendation for IPv6 Address Text 1276 Representation"; 1277 } 1279 typedef ip-prefix { 1280 type union { 1281 type inet:ipv4-prefix; 1282 type inet:ipv6-prefix; 1283 } 1284 description 1285 "The ip-prefix type represents an IP prefix and is IP 1286 version neutral. The format of the textual representations 1287 implies the IP version."; 1288 } 1290 typedef ipv4-prefix { 1291 type string { 1292 pattern 1293 '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}' 1294 + '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])' 1295 + '/(([0-9])|([1-2][0-9])|(3[0-2]))'; 1296 } 1297 description 1298 "The ipv4-prefix type represents an IPv4 prefix. 1299 The prefix length is given by the number following the 1300 slash character and must be less than or equal to 32. 1302 A prefix length value of n corresponds to an IP address 1303 mask that has n contiguous 1-bits from the most 1304 significant bit (MSB) and all other bits set to 0. 1306 The canonical format of an IPv4 prefix has all bits of 1307 the IPv4 address set to zero that are not part of the 1308 IPv4 prefix. 1310 The definition of ipv4-prefix does not require that bits, 1311 which are not part of the prefix, are set to zero. However, 1312 implementations have to return values in canonical format, 1313 which requires non-prefix bits to be set to zero. This means 1314 that 192.0.2.1/24 must be accepted as a valid value but it 1315 will be converted into the canonical format 192.0.2.0/24."; 1316 } 1318 typedef ipv6-prefix { 1319 type string { 1320 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}' 1321 + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|' 1322 + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}' 1323 + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))' 1324 + '(/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))'; 1325 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|' 1326 + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)' 1327 + '(/.+)'; 1328 } 1329 description 1330 "The ipv6-prefix type represents an IPv6 prefix. 1331 The prefix length is given by the number following the 1332 slash character and must be less than or equal to 128. 1334 A prefix length value of n corresponds to an IP address 1335 mask that has n contiguous 1-bits from the most 1336 significant bit (MSB) and all other bits set to 0. 1338 The canonical format of an IPv6 prefix has all bits of 1339 the IPv6 address set to zero that are not part of the 1340 IPv6 prefix. Furthermore, the IPv6 address is represented 1341 as defined in Section 4 of RFC 5952. 1343 The definition of ipv6-prefix does not require that bits, 1344 which are not part of the prefix, are set to zero. However, 1345 implementations have to return values in canonical format, 1346 which requires non-prefix bits to be set to zero. This means 1347 that 2001:db8::1/64 must be accepted as a valid value but it 1348 will be converted into the canonical format 2001:db8::/64."; 1349 reference 1350 "RFC 5952: A Recommendation for IPv6 Address Text 1351 Representation"; 1352 } 1353 typedef ip-address-and-prefix { 1354 type union { 1355 type inet:ipv4-address-and-prefix; 1356 type inet:ipv6-address-and-prefix; 1357 } 1358 description 1359 "The ip-address-and-prefix type represents an IP address and 1360 prefix and is IP version neutral. The format of the textual 1361 representations implies the IP version."; 1362 } 1364 typedef ipv4-address-and-prefix { 1365 type string { 1366 pattern 1367 '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}' 1368 + '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])' 1369 + '/(([0-9])|([1-2][0-9])|(3[0-2]))'; 1370 } 1371 description 1372 "The ipv4-address-and-prefix type represents an IPv4 1373 address and an associated ipv4 prefix. 1374 The prefix length is given by the number following the 1375 slash character and must be less than or equal to 32. 1377 A prefix length value of n corresponds to an IP address 1378 mask that has n contiguous 1-bits from the most 1379 significant bit (MSB) and all other bits set to 0."; 1380 } 1382 typedef ipv6-address-and-prefix { 1383 type string { 1384 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}' 1385 + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|' 1386 + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}' 1387 + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))' 1388 + '(/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))'; 1389 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|' 1390 + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)' 1391 + '(/.+)'; 1392 } 1393 description 1394 "The ipv6-address-and-prefix type represents an IPv6 1395 address and an associated ipv4 prefix. 1396 The prefix length is given by the number following the 1397 slash character and must be less than or equal to 128. 1399 A prefix length value of n corresponds to an IP address 1400 mask that has n contiguous 1-bits from the most 1401 significant bit (MSB) and all other bits set to 0. 1403 The canonical format requires that the IPv6 address is 1404 represented as defined in Section 4 of RFC 5952."; 1405 reference 1406 "RFC 5952: A Recommendation for IPv6 Address Text 1407 Representation"; 1408 } 1410 /*** collection of domain name and URI types ***/ 1412 typedef domain-name { 1413 type string { 1414 length "1..253"; 1415 pattern 1416 '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.)*' 1417 + '([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.?)' 1418 + '|\.'; 1419 } 1420 description 1421 "The domain-name type represents a DNS domain name. The 1422 name SHOULD be fully qualified whenever possible. This 1423 type does not support wildcards (see RFC 4592) or 1424 classless in-addr.arpa delegations (see RFC 2317). 1426 Internet domain names are only loosely specified. Section 1427 3.5 of RFC 1034 recommends a syntax (modified in Section 1428 2.1 of RFC 1123). The pattern above is intended to allow 1429 for current practice in domain name use, and some possible 1430 future expansion. Note that Internet host names have a 1431 stricter syntax (described in RFC 952) than the DNS 1432 recommendations in RFCs 1034 and 1123, and that systems 1433 that want to store host names in schema node instances 1434 using the domain-name type are recommended to adhere to 1435 this stricter standard to ensure interoperability. 1437 The encoding of DNS names in the DNS protocol is limited 1438 to 255 characters. Since the encoding consists of labels 1439 prefixed by a length bytes and there is a trailing NULL 1440 byte, only 253 characters can appear in the textual dotted 1441 notation. 1443 The description clause of schema nodes using the domain-name 1444 type MUST describe when and how these names are resolved to 1445 IP addresses. Note that the resolution of a domain-name value 1446 may require to query multiple DNS records (e.g., A for IPv4 1447 and AAAA for IPv6). The order of the resolution process and 1448 which DNS record takes precedence can either be defined 1449 explicitly or may depend on the configuration of the 1450 resolver. 1452 Domain-name values use the US-ASCII encoding. Their canonical 1453 format uses lowercase US-ASCII characters. Internationalized 1454 domain names MUST be A-labels as per RFC 5890."; 1455 reference 1456 "RFC 952: DoD Internet Host Table Specification 1457 RFC 1034: Domain Names - Concepts and Facilities 1458 RFC 1123: Requirements for Internet Hosts -- Application 1459 and Support 1460 RFC 2317: Classless IN-ADDR.ARPA delegation 1461 RFC 2782: A DNS RR for specifying the location of services 1462 (DNS SRV) 1463 RFC 4592: The Role of Wildcards in the Domain Name System 1464 RFC 5890: Internationalized Domain Names in Applications 1465 (IDNA): Definitions and Document Framework"; 1466 } 1468 typedef host { 1469 type union { 1470 type inet:ip-address; 1471 type inet:domain-name; 1472 } 1473 description 1474 "The host type represents either an IP address or a DNS 1475 domain name."; 1476 } 1478 /* 1479 * DISCUSS: 1480 * - Lada suggested to replace the inet:domain-name usage in 1481 * the union with a new host-name definition that follows 1482 * the NR-LDH definition in RFC 5890. 1483 */ 1485 typedef uri { 1486 type string; 1487 description 1488 "The uri type represents a Uniform Resource Identifier 1489 (URI) as defined by STD 66. 1491 Objects using the uri type MUST be in US-ASCII encoding, 1492 and MUST be normalized as described by RFC 3986 Sections 1493 6.2.1, 6.2.2.1, and 6.2.2.2. All unnecessary 1494 percent-encoding is removed, and all case-insensitive 1495 characters are set to lowercase except for hexadecimal 1496 digits, which are normalized to uppercase as described in 1497 Section 6.2.2.1. 1499 The purpose of this normalization is to help provide 1500 unique URIs. Note that this normalization is not 1501 sufficient to provide uniqueness. Two URIs that are 1502 textually distinct after this normalization may still be 1503 equivalent. 1505 Objects using the uri type may restrict the schemes that 1506 they permit. For example, 'data:' and 'urn:' schemes 1507 might not be appropriate. 1509 A zero-length URI is not a valid URI. This can be used to 1510 express 'URI absent' where required. 1512 In the value set and its semantics, this type is equivalent 1513 to the Uri SMIv2 textual convention defined in RFC 5017."; 1514 reference 1515 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax 1516 RFC 3305: Report from the Joint W3C/IETF URI Planning Interest 1517 Group: Uniform Resource Identifiers (URIs), URLs, 1518 and Uniform Resource Names (URNs): Clarifications 1519 and Recommendations 1520 RFC 5017: MIB Textual Conventions for Uniform Resource 1521 Identifiers (URIs)"; 1522 } 1524 typedef email-address { 1525 type string { 1526 // dot-atom-text "@" ... 1527 pattern '[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+' 1528 + '(\.[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+)*' 1529 + '@' 1530 + '[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+' 1531 + '(\.[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+)*'; 1532 } 1533 description 1534 "The email-address type represents an email address as 1535 defined as addr-spec in RFC 5322 section 3.4.1."; 1536 reference 1537 "RFC 5322: Internet Message Format"; 1538 } 1540 /* 1541 * DISCUSS: 1542 * - It was suggested to add email types following RFC 5322 1543 * email-address (addr-spec, per Section 3.4.1) 1544 * named-email-address (name-addr, per Section 3.4) 1545 * - This sounds useful but the devil is in the details, 1546 * in particular name-addr is a quite complex construct; 1547 * perhaps addr-spec is sufficient, this is also the 1548 * format allowed in mailto: URIs (mailto: seems to use 1549 * only a subset of addr-spec which may be good enough 1550 * here as well). 1551 * - Need to define a pattern that has a meaningful trade-off 1552 * between precision and complexity (there are very tight 1553 * pattern that are very long and complex). The current 1554 * pattern does not take care of quoted-string, obs-local-part, 1555 * domain-literal, obs-domain. 1556 */ 1558 /* 1559 * DISCUSS: 1560 * - There was a request to add types for URI fields (scheme, 1561 * authority, path, query, fragment) but it is not clear how 1562 * commonly useful these types are, the WG was pretty silent 1563 * about this proposal. On the technical side, it is unclear 1564 * whether data is represented with percent escapes resolved 1565 * or not. (Mahesh's proposal does not spell this out, the 1566 * pattern does not allow the % character, which may be wrong.) 1567 */ 1568 } 1570 1572 5. IANA Considerations 1574 This document registers two URIs in the IETF XML registry [RFC3688]. 1575 Following the format in RFC 3688, the following registrations have 1576 been made. 1578 URI: urn:ietf:params:xml:ns:yang:ietf-yang-types 1579 Registrant Contact: The NETMOD WG of the IETF. 1580 XML: N/A, the requested URI is an XML namespace. 1582 URI: urn:ietf:params:xml:ns:yang:ietf-inet-types 1583 Registrant Contact: The NETMOD WG of the IETF. 1584 XML: N/A, the requested URI is an XML namespace. 1586 This document registers two YANG modules in the YANG Module Names 1587 registry [RFC6020]. 1589 name: ietf-yang-types 1590 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-types 1591 prefix: yang 1592 reference: RFC XXXX 1594 name: ietf-inet-types 1595 namespace: urn:ietf:params:xml:ns:yang:ietf-inet-types 1596 prefix: inet 1597 reference: RFC XXXX 1599 6. Security Considerations 1601 This document defines common data types using the YANG data modeling 1602 language. The definitions themselves have no security impact on the 1603 Internet, but the usage of these definitions in concrete YANG modules 1604 might have. The security considerations spelled out in the YANG 1605 specification [RFC7950] apply for this document as well. 1607 7. Contributors 1609 The following people contributed significantly to the initial version 1610 of this document: 1612 - Andy Bierman (Brocade) 1613 - Martin Bjorklund (Tail-f Systems) 1614 - Balazs Lengyel (Ericsson) 1615 - David Partain (Ericsson) 1616 - Phil Shafer (Juniper Networks) 1618 8. Acknowledgments 1620 The editor wishes to thank the following individuals for providing 1621 helpful comments on various versions of this document: Andy Bierman, 1622 Martin Bjorklund, Benoit Claise, Joel M. Halpern, Ladislav Lhotka, 1623 Lars-Johan Liman, and Dan Romascanu. 1625 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 1626 Excellence project (ICT-318488) supported by the European Commission 1627 under its Seventh Framework Programme. 1629 9. References 1631 9.1. Normative References 1633 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1634 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1635 RFC2119, March 1997, 1636 . 1638 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1639 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1640 . 1642 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1643 DOI 10.17487/RFC3688, January 2004, 1644 . 1646 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1647 Resource Identifier (URI): Generic Syntax", STD 66, 1648 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1649 . 1651 [RFC4007] Deering, S., Haberman, B., Jinmei, T., Nordmark, E., and 1652 B. Zill, "IPv6 Scoped Address Architecture", RFC 4007, 1653 DOI 10.17487/RFC4007, March 2005, 1654 . 1656 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1657 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1658 DOI 10.17487/RFC4122, July 2005, 1659 . 1661 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1662 Architecture", RFC 4291, DOI 10.17487/RFC4291, 1663 February 2006, . 1665 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1666 the Network Configuration Protocol (NETCONF)", RFC 6020, 1667 DOI 10.17487/RFC6020, October 2010, 1668 . 1670 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1671 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1672 . 1674 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1675 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1676 . 1678 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1679 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1680 May 2017, . 1682 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 1683 Version 1.0", World Wide Web Consortium 1684 Recommendation REC-xpath-19991116, November 1999, 1685 . 1687 9.2. Informative References 1689 [IEEE802] IEEE, "IEEE Standard for Local and Metropolitan Area 1690 Networks: Overview and Architecture", IEEE Std. 802-2001. 1692 [ISO9834-1] 1693 ISO/IEC, "Information technology -- Open Systems 1694 Interconnection -- Procedures for the operation of OSI 1695 Registration Authorities: General procedures and top arcs 1696 of the ASN.1 Object Identifier tree", ISO/IEC 9834-1:2008, 1697 2008. 1699 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 1700 DOI 10.17487/RFC0768, August 1980, 1701 . 1703 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 1704 DOI 10.17487/RFC0791, September 1981, 1705 . 1707 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1708 RFC 793, DOI 10.17487/RFC0793, September 1981, 1709 . 1711 [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet 1712 host table specification", RFC 952, DOI 10.17487/RFC0952, 1713 October 1985, . 1715 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 1716 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 1717 . 1719 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 1720 Application and Support", STD 3, RFC 1123, DOI 10.17487/ 1721 RFC1123, October 1989, 1722 . 1724 [RFC1930] Hawkinson, J. and T. Bates, "Guidelines for creation, 1725 selection, and registration of an Autonomous System (AS)", 1726 BCP 6, RFC 1930, DOI 10.17487/RFC1930, March 1996, 1727 . 1729 [RFC2317] Eidnes, H., de Groot, G., and P. Vixie, "Classless IN- 1730 ADDR.ARPA delegation", BCP 20, RFC 2317, DOI 10.17487/ 1731 RFC2317, March 1998, 1732 . 1734 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 1735 (IPv6) Specification", RFC 2460, DOI 10.17487/RFC2460, 1736 December 1998, . 1738 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 1739 "Definition of the Differentiated Services Field (DS 1740 Field) in the IPv4 and IPv6 Headers", RFC 2474, 1741 DOI 10.17487/RFC2474, December 1998, 1742 . 1744 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1745 Schoenwaelder, Ed., "Structure of Management Information 1746 Version 2 (SMIv2)", STD 58, RFC 2578, DOI 10.17487/ 1747 RFC2578, April 1999, 1748 . 1750 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1751 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 1752 STD 58, RFC 2579, DOI 10.17487/RFC2579, April 1999, 1753 . 1755 [RFC2780] Bradner, S. and V. Paxson, "IANA Allocation Guidelines For 1756 Values In the Internet Protocol and Related Headers", 1757 BCP 37, RFC 2780, DOI 10.17487/RFC2780, March 2000, 1758 . 1760 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 1761 specifying the location of services (DNS SRV)", RFC 2782, 1762 DOI 10.17487/RFC2782, February 2000, 1763 . 1765 [RFC2856] Bierman, A., McCloghrie, K., and R. Presuhn, "Textual 1766 Conventions for Additional High Capacity Data Types", 1767 RFC 2856, DOI 10.17487/RFC2856, June 2000, 1768 . 1770 [RFC3289] Baker, F., Chan, K., and A. Smith, "Management Information 1771 Base for the Differentiated Services Architecture", 1772 RFC 3289, DOI 10.17487/RFC3289, May 2002, 1773 . 1775 [RFC3305] Mealling, M., Ed. and R. Denenberg, Ed., "Report from the 1776 Joint W3C/IETF URI Planning Interest Group: Uniform 1777 Resource Identifiers (URIs), URLs, and Uniform Resource 1778 Names (URNs): Clarifications and Recommendations", 1779 RFC 3305, DOI 10.17487/RFC3305, August 2002, 1780 . 1782 [RFC3595] Wijnen, B., "Textual Conventions for IPv6 Flow Label", 1783 RFC 3595, DOI 10.17487/RFC3595, September 2003, 1784 . 1786 [RFC4001] Daniele, M., Haberman, B., Routhier, S., and J. 1787 Schoenwaelder, "Textual Conventions for Internet Network 1788 Addresses", RFC 4001, DOI 10.17487/RFC4001, February 2005, 1789 . 1791 [RFC4271] Rekhter, Y., Ed., Li, T., Ed., and S. Hares, Ed., "A 1792 Border Gateway Protocol 4 (BGP-4)", RFC 4271, 1793 DOI 10.17487/RFC4271, January 2006, 1794 . 1796 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 1797 Congestion Control Protocol (DCCP)", RFC 4340, 1798 DOI 10.17487/RFC4340, March 2006, 1799 . 1801 [RFC4502] Waldbusser, S., "Remote Network Monitoring Management 1802 Information Base Version 2", RFC 4502, DOI 10.17487/ 1803 RFC4502, May 2006, 1804 . 1806 [RFC4592] Lewis, E., "The Role of Wildcards in the Domain Name 1807 System", RFC 4592, DOI 10.17487/RFC4592, July 2006, 1808 . 1810 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1811 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1812 . 1814 [RFC5017] McWalter, D., Ed., "MIB Textual Conventions for Uniform 1815 Resource Identifiers (URIs)", RFC 5017, DOI 10.17487/ 1816 RFC5017, September 2007, 1817 . 1819 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1820 DOI 10.17487/RFC5322, October 2008, 1821 . 1823 [RFC5890] Klensin, J., "Internationalized Domain Names for 1824 Applications (IDNA): Definitions and Document Framework", 1825 RFC 5890, DOI 10.17487/RFC5890, August 2010, 1826 . 1828 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1829 Address Text Representation", RFC 5952, DOI 10.17487/ 1830 RFC5952, August 2010, 1831 . 1833 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1834 and A. Bierman, Ed., "Network Configuration Protocol 1835 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1836 . 1838 [RFC6793] Vohra, Q. and E. Chen, "BGP Support for Four-Octet 1839 Autonomous System (AS) Number Space", RFC 6793, 1840 DOI 10.17487/RFC6793, December 2012, 1841 . 1843 [XSD-TYPES] 1844 Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 1845 Second Edition", World Wide Web Consortium 1846 Recommendation REC-xmlschema-2-20041028, October 2004, 1847 . 1849 Appendix A. Changes from RFC 6991 1851 This version adds new type definitions to the YANG modules. The 1852 following new data types have been added to the ietf-yang-types 1853 module: 1855 o date, time 1857 o hours32, minutes32, seconds32, centiseconds32, milliseconds32, 1859 o microseconds32, microseconds64, nanoseconds32, nanoseconds64 1861 o revision-identifier, node-instance-identifier 1863 The following new data types have been added to the ietf-inet-types 1864 module: 1866 o ip-address-and-prefix, ipv4-address-and-prefix, ipv6-address-and- 1867 prefix 1869 o email-address 1871 Appendix B. Changes from RFC 6021 1873 This version adds new type definitions to the YANG modules. The 1874 following new data types have been added to the ietf-yang-types 1875 module: 1877 o yang-identifier 1879 o hex-string 1881 o uuid 1883 o dotted-quad 1885 The following new data types have been added to the ietf-inet-types 1886 module: 1888 o ip-address-no-zone 1890 o ipv4-address-no-zone 1892 o ipv6-address-no-zone 1894 Author's Address 1896 Juergen Schoenwaelder (editor) 1897 Jacobs University 1899 Email: j.schoenwaelder@jacobs-university.de