idnits 2.17.1 draft-ietf-core-comi-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The server MUST not return the child resource if d= 't' -- The document date (November 12, 2018) is 1992 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) -- Looks like a reference, but probably isn't: '0' on line 334 -- Looks like a reference, but probably isn't: '26' on line 335 -- Looks like a reference, but probably isn't: '57' on line 336 == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-04 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-07 == Outdated reference: A later version (-05) exists of draft-veillette-core-yang-library-03 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE M. Veillette, Ed. 3 Internet-Draft Trilliant Networks Inc. 4 Intended status: Standards Track P. van der Stok, Ed. 5 Expires: May 16, 2019 consultant 6 A. Pelov 7 Acklio 8 A. Bierman 9 YumaWorks 10 November 12, 2018 12 CoAP Management Interface 13 draft-ietf-core-comi-04 15 Abstract 17 This document describes a network management interface for 18 constrained devices and networks, called CoAP Management Interface 19 (CoMI). The Constrained Application Protocol (CoAP) is used to 20 access datastore and data node resources specified in YANG, or SMIv2 21 converted to YANG. CoMI uses the YANG to CBOR mapping and converts 22 YANG identifier strings to numeric identifiers for payload size 23 reduction. CoMI extends the set of YANG based protocols, NETCONF and 24 RESTCONF, with the capability to manage constrained devices and 25 networks. 27 Note 29 Discussion and suggestions for improvement are requested, and should 30 be sent to yot@ietf.org. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on May 16, 2019. 49 Copyright Notice 51 Copyright (c) 2018 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (https://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5 69 2.1. Major differences between RESTCONF and CoMI . . . . . . . 6 70 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 71 2.3. Instance identifier . . . . . . . . . . . . . . . . . . . 8 72 2.4. Content-Formats . . . . . . . . . . . . . . . . . . . . . 8 73 2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10 74 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11 75 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11 76 4.1. Using the 'k' Uri-Query option . . . . . . . . . . . . . 13 77 4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 14 78 4.2.1. Using the 'c' Uri-Query option . . . . . . . . . . . 15 79 4.2.2. Using the 'd' Uri-Query option . . . . . . . . . . . 15 80 4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16 81 4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 19 82 4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 20 83 4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 20 84 4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 20 85 4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 21 86 4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 22 87 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 23 88 4.4. Full datastore access . . . . . . . . . . . . . . . . . . 23 89 4.4.1. Full datastore examples . . . . . . . . . . . . . . . 24 90 4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 25 91 4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 26 92 4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27 93 4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 27 94 5. Access to MIB Data . . . . . . . . . . . . . . . . . . . . . 28 95 6. Use of Block . . . . . . . . . . . . . . . . . . . . . . . . 28 96 7. Application Discovery . . . . . . . . . . . . . . . . . . . . 29 97 7.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 29 98 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 29 99 7.2.1. Datastore Resource Discovery . . . . . . . . . . . . 30 100 7.2.2. Data node Resource Discovery . . . . . . . . . . . . 30 101 7.2.3. Event stream Resource Discovery . . . . . . . . . . . 31 102 8. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 31 103 9. Security Considerations . . . . . . . . . . . . . . . . . . . 34 104 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 105 10.1. Resource Type (rt=) Link Target Attribute Values 106 Registry . . . . . . . . . . . . . . . . . . . . . . . . 35 107 10.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 35 108 10.3. Media Types Registry . . . . . . . . . . . . . . . . . . 36 109 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 110 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 111 12.1. Normative References . . . . . . . . . . . . . . . . . . 38 112 12.2. Informative References . . . . . . . . . . . . . . . . . 39 113 Appendix A. ietf-comi YANG module . . . . . . . . . . . . . . . 40 114 Appendix B. ietf-comi .sid file . . . . . . . . . . . . . . . . 46 115 Appendix C. YANG example specifications . . . . . . . . . . . . 49 116 C.1. ietf-system . . . . . . . . . . . . . . . . . . . . . . . 49 117 C.2. server list . . . . . . . . . . . . . . . . . . . . . . . 51 118 C.3. interfaces . . . . . . . . . . . . . . . . . . . . . . . 52 119 C.4. Example-port . . . . . . . . . . . . . . . . . . . . . . 52 120 C.5. IP-MIB . . . . . . . . . . . . . . . . . . . . . . . . . 53 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 123 1. Introduction 125 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 126 Machine to Machine (M2M) applications such as smart energy, smart 127 city and building control. Constrained devices need to be managed in 128 an automatic fashion to handle the large quantities of devices that 129 are expected in future installations. Messages between devices need 130 to be as small and infrequent as possible. The implementation 131 complexity and runtime resources need to be as small as possible. 133 This draft describes the CoAP Management Interface which uses CoAP 134 methods to access structured data defined in YANG [RFC7950]. This 135 draft is complementary to [RFC8040] which describes a REST-like 136 interface called RESTCONF, which uses HTTP methods to access 137 structured data defined in YANG. 139 The use of standardized data models specified in a standardized 140 language, such as YANG, promotes interoperability between devices and 141 applications from different manufacturers. 143 CoMI and RESTCONF are intended to work in a stateless client-server 144 fashion. They use a single round-trip to complete a single editing 145 transaction, where NETCONF needs multiple round trips. 147 To promote small messges, CoMI uses a YANG to CBOR mapping 148 [I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid] 149 to minimize CBOR payloads and URI length. 151 1.1. Terminology 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 155 document are to be interpreted as described in [RFC2119]. 157 The following terms are defined in the YANG data modelling language 158 [RFC7950]: action, anydata, anyxml, client, container, data model, 159 data node, identity, instance identifier, leaf, leaf-list, list, 160 module, RPC, schema node, server, submodule. 162 The following terms are defined in [RFC6241]: configuration data, 163 datastore, state data 165 The following term is defined in [I-D.ietf-core-yang-cbor]: YANG 166 schema item identifier (SID). 168 The following terms are defined in the CoAP protocol [RFC7252]: 169 Confirmable Message, Content-Format, Endpoint. 171 The following terms are defined in this document: 173 data node resource: a CoAP resource that models a YANG data node. 175 datastore resource: a CoAP resource that models a YANG datastore. 177 event stream resource: a CoAP resource used by clients to observe 178 YANG notifications. 180 notification instance: An instance of a schema node of type 181 notification, specified in a YANG module implemented by the 182 server. The instance is generated in the server at the occurrence 183 of the corresponding event and reported by an event stream. 185 list instance identifier: Handle used to identify a YANG data node 186 that is an instance of a YANG "list" specified with the values of 187 the key leaves of the list. 189 single instance identifier: Handle used to identify a specific data 190 node which can be instantiated only once. This includes data 191 nodes defined at the root of a YANG module and data nodes defined 192 within a container. This excludes data nodes defined within a 193 list or any children of these data nodes. 195 instance-identifier: List instance identifier or single instance 196 identifier. 198 instance-value: The value assigned to a schema node instance. 199 Schema node values are serialized into the payload according to 200 the rules defined in section 4 of [I-D.ietf-core-yang-cbor]. 202 2. CoMI Architecture 204 This section describes the CoMI architecture to use CoAP for reading 205 and modifying the content of datastore(s) used for the management of 206 the instrumented node. 208 +----------------------------------------------------------------+ 209 | SMIv2 specification (2) | 210 +----------------------------------------------------------------+ 211 | 212 V 213 +----------------------------------------------------------------+ 214 | YANG specification (1) | 215 +----------------------------------------------------------------+ 216 | | 217 Client V Server V 218 +----------------+ +-----------------------+ 219 | Request |--> CoAP request(3) -->| Indication | 220 | Confirm |<-- CoAP response(3)<--| Response (4) | 221 | | | | 222 | |<==== Security (7) ===>|+---------------------+| 223 +----------------+ || Datastore(s) (5) || 224 |+---------------------+| 225 |+---------------------+| 226 || Event stream(s) (6) || 227 |+---------------------+| 228 +-----------------------+ 230 Figure 1: Abstract CoMI architecture 232 Figure 1 is a high-level representation of the main elements of the 233 CoMI management architecture. The different numbered components of 234 Figure 1 are discussed according to component number. 236 (1) YANG specification: contains a set of named and versioned 237 modules. 239 (2) SMIv2 specification: A named module specifies a set of variables 240 and "conceptual tables". There is an algorithm to translate SMIv2 241 specifications to YANG specifications. 243 (3) CoAP request/response messages: The CoMI client sends request 244 messages to and receives response messages from the CoMI server. 246 (4) Request, Indication, Response, Confirm: Processes performed by 247 the CoMI clients and servers. 249 (5) Datastore: A resource used to access configuration data, state 250 data, RPCs and actions. A CoMI server may support a single 251 unified datastore or multiple datastores as those defined by 252 Network Management Datastore Architecture (NMDA) [RFC8342]. 254 (6) Event stream: A resource used to get real time notifications. A 255 CoMI server may support multiple Event streams serving different 256 purposes such as normal monitoring, diagnostic, syslog, security 257 monitoring. 259 (7) Security: The server MUST prevent unauthorized users from 260 reading or writing any CoMI resources. CoMI relies on security 261 protocols such as DTLS [RFC6347] to secure CoAP communication. 263 2.1. Major differences between RESTCONF and CoMI 265 CoMI is a RESTful protocol for small devices where saving bytes to 266 transport counts. Contrary to RESTCONF, many design decisions are 267 motivated by the saving of bytes. Consequently, CoMI is not a 268 RESTCONF over CoAP protocol, but differs more significantly from 269 RESTCONF. Some major differences are cited below: 271 o CoMI uses CoAP/UDP as transport protocol and CBOR as payload 272 format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as 273 transport protocol and JSON or XML as payload formats. 275 o CoMI encodes YANG identifier strings as numbers, where RESTCONF 276 does not. 278 o CoMI uses the methods FETCH and iPATCH to access multiple data 279 nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP 280 method GET with the "fields" Query parameter. 282 o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not 283 used by CoAP. 285 o CoMI does not support "insert" query parameter (first, last, 286 before, after) and the "point" query parameter which are supported 287 by RESTCONF. 289 o CoMI does not support the "start-time" and "stop-time" query 290 parameters to retrieve past notifications. 292 o CoMI does not support the "filter" query parameters to observe a 293 specific set of notifications. 295 o CoMI also differ in the handling of default values, only 'report- 296 all' and 'trip' options are supported. 298 2.2. Compression of YANG identifiers 300 In the YANG specification, items are identified with a name string. 301 In order to significantly reduce the size of identifiers used in 302 CoMI, numeric identifiers are used instead of these strings. YANG 303 Schema Item iDentifier (SID) is defined in [I-D.ietf-core-yang-cbor] 304 section 2.1. 306 When used in a URI, SIDs are encoded in based64 using the URL and 307 Filename safe alphabet as defined by [RFC4648] section 5. The last 6 308 bits encoded is always aligned with the least significant 6 bits of 309 the SID represented using an unsigned integer. 'A' characters (value 310 0) at the start of the resulting string are removed. 312 SID in basae64 = URLsafeChar[SID >> 60 & 0x3F] | 313 URLsafeChar[SID >> 54 & 0x3F] | 314 URLsafeChar[SID >> 48 & 0x3F] | 315 URLsafeChar[SID >> 42 & 0x3F] | 316 URLsafeChar[SID >> 36 & 0x3F] | 317 URLsafeChar[SID >> 30 & 0x3F] | 318 URLsafeChar[SID >> 24 & 0x3F] | 319 URLsafeChar[SID >> 18 & 0x3F] | 320 URLsafeChar[SID >> 12 & 0x3F] | 321 URLsafeChar[SID >> 6 & 0x3F] | 322 URLsafeChar[SID & 0x3F] 324 For example, SID 1721 is encoded as follow. 326 URLsafeChar[1721 >> 60 & 0x3F] = URLsafeChar[0] = 'A' 327 URLsafeChar[1721 >> 54 & 0x3F] = URLsafeChar[0] = 'A' 328 URLsafeChar[1721 >> 48 & 0x3F] = URLsafeChar[0] = 'A' 329 URLsafeChar[1721 >> 42 & 0x3F] = URLsafeChar[0] = 'A' 330 URLsafeChar[1721 >> 36 & 0x3F] = URLsafeChar[0] = 'A' 331 URLsafeChar[1721 >> 30 & 0x3F] = URLsafeChar[0] = 'A' 332 URLsafeChar[1721 >> 24 & 0x3F] = URLsafeChar[0] = 'A' 333 URLsafeChar[1721 >> 18 & 0x3F] = URLsafeChar[0] = 'A' 334 URLsafeChar[1721 >> 12 & 0x3F] = URLsafeChar[0] = 'A' 335 URLsafeChar[1721 >> 6 & 0x3F] = URLsafeChar[26] = 'a' 336 URLsafeChar[1721 & 0x3F] = URLsafeChar[57] = '5' 338 The resulting base64 representation of SID 1721 is "a5" 340 2.3. Instance identifier 342 Instance identifiers are used to uniquely identify data node 343 instances within a datastore. This YANG built-in type is defined in 344 [RFC7950] section 9.13. An instance identifier is composed of the 345 data node identifier (i.e. a SID) and for data nodes within list(s) 346 the keys used to index within these list(s). 348 When part of a payload, instance identifiers are encoded in CBOR 349 based on the rules defined in [I-D.ietf-core-yang-cbor] section 350 6.13.1. When part of a URI, the SID is appended to the URI of the 351 targeted datastore, the keys are specified using the 'k' URI-Query as 352 defined in Section 4.1. 354 2.4. Content-Formats 356 ComI uses Content-Formats based on the YANG to CBOR mapping specified 357 in [I-D.ietf-core-yang-cbor]. 359 The following Content-formats are defined: 361 application/yang-data+cbor: This Content-Format represents a CBOR 362 YANG document containing one or multiple data node values. Each 363 data node is identified by its associated SID. 365 FORMAT: CBOR map of SID, instance-value 367 The message payload of Content-Format 'application/yang-data+cbor' 368 is encoded using a CBOR map. Each entry of this CBOR map is 369 composed of a key and a value. CBOR map keys are set to the SID 370 assigned to the data nodes, CBOR map values are set to the 371 instance value as defined in [I-D.ietf-core-yang-cbor] section 4. 373 application/yang-identifiers+cbor: This Content-Format represents a 374 CBOR YANG document containing a list of instance identifier used 375 to target specific data node instances within a datastore. 377 FORMAT: CBOR array of instance-identifier 379 The message payload of Content-Format 'application/yang- 380 identifiers+cbor' is encoded using a CBOR array. Each entry of 381 this CBOR array contain an instance identifier encoded as defined 382 in [I-D.ietf-core-yang-cbor] section 6.13.1. 384 application/yang-instances+cbor: This Content-Format represents a 385 CBOR YANG document containing a list of data node instances. Each 386 data node instance is identified by its associated instance 387 identifier. 389 FORMAT: CBOR array of CBOR map of instance-identifier, instance- 390 value 392 The message payload of Content-Format 'application/yang- 393 instances+cbor' is encoded using a CBOR array. Each entry within 394 this CBOR array contains a CBOR map carrying a single instance 395 identifier and associated value. Instance identifiers are encoded 396 using the rules defined in [I-D.ietf-core-yang-cbor] section 397 6.13.1, values are encoded using the rules defined in 398 [I-D.ietf-core-yang-cbor] section 4. 400 When present in an iPATCH request payload, this Content-Format 401 carry a list of data node instances to be replaced, created, or 402 deleted. For each data node instance D, for which the instance 403 identifier is the same as a data node instance I, in the targeted 404 datastore resource: the value of D replaces the value of I. When 405 the value of D is null, the data node instance I is removed. When 406 the targeted datastore resource does not contain a data node 407 instance with the same instance identifier as D, a new instance is 408 created with the same instance identifier and value as D. 410 The different Content-formats usage are summarized in the table 411 below: 413 +---------------+--------------+------------------------------------+ 414 | Method | Resource | Content-Format | 415 +---------------+--------------+------------------------------------+ 416 | GET response | data node | /application/yang-data+cbor | 417 | | | | 418 | PUT request | data node | /application/yang-data+cbor | 419 | | | | 420 | POST request | data node | /application/yang-data+cbor | 421 | | | | 422 | DELETE | data node | n/a | 423 | | | | 424 | GET response | datastore | /application/yang-data+cbor | 425 | | | | 426 | PUT request | datastore | /application/yang-data+cbor | 427 | | | | 428 | POST request | datastore | /application/yang-data+cbor | 429 | | | | 430 | FETCH request | datastore | /application/yang-identifiers+cbor | 431 | | | | 432 | FETCH | datastore | /application/yang-instances+cbor | 433 | response | | | 434 | | | | 435 | iPATCH | datastore | /application/yang-instances+cbor | 436 | request | | | 437 | | | | 438 | GET response | event stream | /application/yang-instances+cbor | 439 | | | | 440 | POST request | rpc, action | /application/yang-data+cbor | 441 | | | | 442 | POST response | rpc, action | /application/yang-data+cbor | 443 +---------------+--------------+------------------------------------+ 445 2.5. Unified datastore 447 CoMI supports a simple datastore model consisting of on a single 448 unified datastore. This datasore provides access to both 449 configuration and operational data. Configuration updates performed 450 on this datastore are reflected immediately or with a minimal delay 451 as operational data. 453 Alternatively, CoMI servers MAY implement a more complex datastore 454 model such as the Network Management Datastore Architecture (NMDA) as 455 defined by [RFC8342]. Each datastore supported is implemented as a 456 datastore resource. 458 Characteristics of the unified datastore are summarized in the table 459 below: 461 +-------------+-----------------------------------------------------+ 462 | Name | Value | 463 +-------------+-----------------------------------------------------+ 464 | Name | unified | 465 | | | 466 | YANG | all modules | 467 | modules | | 468 | | | 469 | YANG nodes | all data nodes ("config true" and "config false") | 470 | | | 471 | Access | read-write | 472 | | | 473 | How applied | changes applied in place immediately or with a | 474 | | minimal delay | 475 | | | 476 | Protocols | CoMI | 477 | | | 478 | Defined in | "ietf-comi" | 479 +-------------+-----------------------------------------------------+ 481 3. Example syntax 483 This section presents the notation used for the examples. The YANG 484 modules that are used throughout this document are shown in 485 Appendix C. The example modules are copied from existing modules and 486 annotated with SIDs. 488 CBOR is used to encode CoMI request and response payloads. The CBOR 489 syntax of the YANG payloads is specified in [RFC7049]. The payload 490 examples are notated in Diagnostic notation (defined in section 6 of 491 [RFC7049]) that can be automatically converted to CBOR. 493 SIDs in URIs are represented as a base64 number, SIDs in the payload 494 are represented as decimal numbers. 496 4. CoAP Interface 498 This note specifies a Management Interface. CoAP endpoints that 499 implement the CoMI management protocol, support at least one 500 discoverable management resource of resource type (rt): core.c.ds, 501 with example path: /c, where c is short-hand for CoMI. The path /c 502 is recommended, but not compulsory (see Section 7). 504 The mapping of YANG data node instances to CoMI resources is as 505 follows. Every data node of the YANG modules loaded in the CoMI 506 server represents a sub-resource of the datastore resource (e.g. /c/ 507 sid). When multiple instances of a list exist, instance selection is 508 possible as described in Section 4.1, Section 4.2.3.1, and 509 Section 4.2.4. 511 CoMI also supports event stream resourced used to observe 512 notification instances. Event stream resources can be discovered 513 using resource type (rt): core.c.ev. 515 The description of the CoMI management interface is shown in the 516 table below: 518 +-------------+------------------+-----------+ 519 | Function | Recommended path | rt | 520 +-------------+------------------+-----------+ 521 | Datastore | /c | core.c.ds | 522 | | | | 523 | Data node | /c/SID | core.c.dn | 524 | | | | 525 | Event steam | /s | core.c.ev | 526 +-------------+------------------+-----------+ 528 The path values are example values. On discovery, the server makes 529 the actual path values known for these resources. 531 The methods used by CoMI are: 533 +-----------+-------------------------------------------------------+ 534 | Operation | Description | 535 +-----------+-------------------------------------------------------+ 536 | GET | Retrieve the datastore resource or a data node | 537 | | resource | 538 | | | 539 | FETCH | Retrieve specific data nodes within a datastore | 540 | | resource | 541 | | | 542 | POST | Create a datastore resource or a data node resource, | 543 | | invoke an RPC or action | 544 | | | 545 | PUT | Create or replace a datastore resource or a data node | 546 | | resource | 547 | | | 548 | iPATCH | Idem-potently create, replace, and delete data node | 549 | | resource(s) within a datastore resource | 550 | | | 551 | DELETE | Delete a datastore resource or a data node resource | 552 +-----------+-------------------------------------------------------+ 554 There is one Uri-Query option for the GET, PUT, POST, and DELETE 555 methods. 557 +------------------+----------------------------------------+ 558 | Uri-Query option | Description | 559 +------------------+----------------------------------------+ 560 | k | Select an instance within YANG list(s) | 561 +------------------+----------------------------------------+ 563 This parameter is not used for FETCH and iPATCH, because their 564 request payloads support list instance selection. 566 4.1. Using the 'k' Uri-Query option 568 The "k" (key) parameter specifies a specific instance of a data node. 569 The SID in the URI is followed by the (?k=key1, key2,..). Where SID 570 identifies a data node, and key1, key2 are the values of the key 571 leaves that specify an instance. Lists can have multiple keys, and 572 lists can be part of lists. The order of key value generation is 573 given recursively by: 575 o For a given list, if a parent data node is a list, generate the 576 keys for the parent list first. 578 o For a given list, generate key values in the order specified in 579 the YANG module. 581 Key values are encoded using the rules defined in the following 582 table. 584 +-----------------------------+--------------------------------+ 585 | YANG datatype | Uri-Query text content | 586 +-----------------------------+--------------------------------+ 587 | uint8,uint16,unit32, uint64 | int2str(key) | 588 | | | 589 | int8, int16,int32, int64 | urlSafeBase64(CBORencode(key)) | 590 | | | 591 | decimal64 | urlSafeBase64(CBOR key) | 592 | | | 593 | string | key | 594 | | | 595 | boolean | "0" or "1" | 596 | | | 597 | enumeration | int2str(key) | 598 | | | 599 | bits | urlSafeBase64(CBORencode(key)) | 600 | | | 601 | binary | urlSafeBase64(key) | 602 | | | 603 | identityref | int2str(key) | 604 | | | 605 | union | urlSafeBase64(CBORencode(key)) | 606 | | | 607 | instance-identifier | urlSafeBase64(CBORencode(key)) | 608 +-----------------------------+--------------------------------+ 610 In this table: 612 o The method int2str() is used to convert an integer value to a 613 string. For example, int2str(0x0123) return the string "291". 615 o The method urlSafeBase64() is used to convert a binary string to 616 base64 using the URL and Filename safe alphabet as defined by 617 [RFC4648] section 5. For example, urlSafeBase64(\xF9\x56\xA1\x3C) 618 return the string "-VahPA". 620 o The method CBORencode() is used to convert a YANG value to CBOR as 621 specified in [I-D.ietf-core-yang-cbor] section 6. 623 The resulting key string is encoded in a Uri-Query as specified in 624 [RFC7252] section 6.5. 626 4.2. Data Retrieval 628 One or more data nodes can be retrieved by the client. The operation 629 is mapped to the GET method defined in section 5.8.1 of [RFC7252] and 630 to the FETCH method defined in section 2 of [RFC8132]. 632 It is possible that the size of the payload is too large to fit in a 633 single message. In the case that management data is bigger than the 634 maximum supported payload size, the Block mechanism from [RFC7959] 635 may be used, as explained in more detail in Section 6. 637 There are two additional Uri-Query options for the GET and FETCH 638 methods. 640 +-------------+-----------------------------------------------------+ 641 | Uri-Query | Description | 642 | option | | 643 +-------------+-----------------------------------------------------+ 644 | c | Control selection of configuration and non- | 645 | | configuration data nodes (GET and FETCH) | 646 | | | 647 | d | Control retrieval of default values. | 648 +-------------+-----------------------------------------------------+ 650 4.2.1. Using the 'c' Uri-Query option 652 The 'c' (content) parameter controls how descendant nodes of the 653 requested data nodes will be processed in the reply. 655 The allowed values are: 657 +-------+-----------------------------------------------------+ 658 | Value | Description | 659 +-------+-----------------------------------------------------+ 660 | c | Return only configuration descendant data nodes | 661 | | | 662 | n | Return only non-configuration descendant data nodes | 663 | | | 664 | a | Return all descendant data nodes | 665 +-------+-----------------------------------------------------+ 667 This parameter is only allowed for GET and FETCH methods on datastore 668 and data node resources. A 4.02 (Bad Option) error is returned if 669 used for other methods or resource types. 671 If this Uri-Query option is not present, the default value is "a". 673 4.2.2. Using the 'd' Uri-Query option 675 The "d" (with-defaults) parameter controls how the default values of 676 the descendant nodes of the requested data nodes will be processed. 678 The allowed values are: 680 +-------+-----------------------------------------------------------+ 681 | Value | Description | 682 +-------+-----------------------------------------------------------+ 683 | a | All data nodes are reported. Defined as 'report-all' in | 684 | | section 3.1 of [RFC6243]. | 685 | | | 686 | t | Data nodes set to the YANG default are not reported. | 687 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 688 +-------+-----------------------------------------------------------+ 690 If the target of a GET or FETCH method is a data node that represents 691 a leaf that has a default value, and the leaf has not been given a 692 value by any client yet, the server MUST return the default value of 693 the leaf. 695 If the target of a GET method is a data node that represents a 696 container or list that has child resources with default values, and 697 these have not been given value yet, 699 The server MUST not return the child resource if d= 't' 701 The server MUST return the child resource if d= 'a'. 703 If this Uri-Query option is not present, the default value is 't'. 705 4.2.3. GET 707 A request to read the values of a data node instance is sent with a 708 CoAP GET message. An instance identifier is specified in the URI 709 path prefixed with the example path /c. 711 FORMAT: 712 GET /c/instance-identifier 714 2.05 Content (Content-Format: application/yang-data+cbor) 715 CBOR map of SID, instance-value 717 The returned payload contains the CBOR encoding of the specified data 718 node instance value. 720 4.2.3.1. GET Examples 722 Using for example the current-datetime leaf from Appendix C.1, a 723 request is sent to retrieve the value of 'system-state/clock/current- 724 datetime' specified in container system-state. The SID of 'system- 725 state/clock/current-datetime' is 1723, encoded in base64 according to 726 Section 2.2, yields a7. The response to the request returns the CBOR 727 map with the key set to the SID of the requested data node (i.e. 729 1723) and the value encoded using a 'text string' as defined in 730 [I-D.ietf-core-yang-cbor] section 6.4. 732 REQ: GET example.com/c/a7 734 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 735 { 736 1723 : "2014-10-26T12:16:31Z" 737 } 739 The next example represents the retrieval of a YANG container. In 740 this case, the CoMI client performs a GET request on the clock 741 container (SID = 1721; base64: a5). The container returned is 742 encoded using a CBOR map as specified by [I-D.ietf-core-yang-cbor] 743 section 4.2. 745 REQ: GET example.com/c/a5 747 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 748 { 749 1721 : { 750 +2 : "2014-10-26T12:16:51Z", / current-datetime SID 1723 / 751 +1 : "2014-10-21T03:00:00Z" / boot-datetime SID 1722 / 752 } 753 } 755 This example shows the retrieval of the /interfaces/interface YANG 756 list accessed using SID 1533 (base64: X9). The return payload is 757 encoded using a CBOR array as specified by [I-D.ietf-core-yang-cbor] 758 section 4.4.1 containing 2 instances. 760 REQ: GET example.com/c/X9 762 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 763 { 764 1533 : [ 765 { 766 +4 : "eth0", / name (SID 1537) / 767 +1 : "Ethernet adaptor", / description (SID 1534) / 768 +5 : 1880, / type, (SID 1538) identity / 769 / ethernetCsmacd (SID 1880) / 770 +2 : true / enabled ( SID 1535) / 771 }, 772 { 773 +4 : "eth1", / name (SID 1537) / 774 +1 : "Ethernet adaptor", / description (SID 1534) / 775 +5 : 1880, / type, (SID 1538) identity / 776 / ethernetCsmacd (SID 1880) / 777 +2 : false / enabled ( SID 1535) / 778 } 779 ] 780 } 782 To retrieve a specific instance within the /interfaces/interface YANG 783 list, the CoMI client adds the key of the targeted instance in its 784 CoAP request using the 'k' URI-Query. The return payload containing 785 the instance requested is encoded using a CBOR array as specified by 786 [I-D.ietf-core-yang-cbor] section 4.4.1. 788 REQ: GET example.com/c/X9?k="eth0" 790 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 791 { 792 1533 : [ 793 { 794 +4 : "eth0", / name (SID 1537) / 795 +1 : "Ethernet adaptor", / description (SID 1534) / 796 +5 : 1880, / type, (SID 1538) identity / 797 / ethernetCsmacd (SID 1880) / 798 +2 : true / enabled ( SID 1535) / 799 } 800 ] 801 } 803 It is equally possible to select a leaf of a specific instance of a 804 list. The example below requests the description leaf (SID=1534, 805 base64: X-) within the interface list corresponding to the interface 806 name "eth0". The returned value is encoded in CBOR based on the 807 rules specified by [I-D.ietf-core-yang-cbor] section 5.4. 809 REQ: GET example.com/c/X-?k="eth0" 811 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 812 { 813 1534 : "Ethernet adaptor" 814 } 816 4.2.4. FETCH 818 The FETCH is used to retrieve multiple data node instance values. 819 The FETCH request payload contains the list of instance identifier of 820 the data node instances requested. 822 The return response payload contains a list of data node instance 823 values in the same order as requested. A CBOR null is returned for 824 each data node requested by the client, not supported by the server 825 or not currently instantiated. 827 For compactness, indexes of the list instance identifiers returned by 828 the FETCH response SHOULD be elided, only the SID is provided. In 829 this case, the format of each entry within the CBOR array of the 830 FETCH response is identical to the format as a GET response. 832 FORMAT: 833 FETCH /c (Content-Format: application/yang-identifiers+cbor) 834 CBOR array of instance-identifier 836 2.05 Content (Content-Format: application/yang-instances+cbor) 837 CBOR array of CBOR map of instance-identifier, instance-value 839 4.2.4.1. FETCH examples 841 This example uses the current-datetime leaf and the interface list 842 from Appendix C.1. In this example the value of current-datetime 843 (SID 1723) and the interface list (SID 1533) instance identified with 844 name="eth0" are queried. 846 REQ: FETCH /c (Content-Format: application/yang-identifiers+cbor) 847 [ 848 1723, / current-datetime (SID 1723) / 849 [1533, "eth0"] / interface (SID 1533) with name = "eth0" / 850 ] 852 RES: 2.05 Content (Content-Format: application/yang-instances+cbor) 853 [ 854 { 855 1723 : "2014-10-26T12:16:31Z" / current-datetime (SID 1723) / 856 }, 857 { 858 1533 : { 859 +4 : "eth0", / name (SID 1537) / 860 +1 : "Ethernet adaptor", / description (SID 1534) / 861 +5 : 1880, / type (SID 1538), identity / 862 / ethernetCsmacd (SID 1880) / 863 +2 : true / enabled (SID 1535) / 864 } 865 } 866 ] 868 4.3. Data Editing 870 CoMI allows datastore contents to be created, modified and deleted 871 using CoAP methods. 873 4.3.1. Data Ordering 875 A CoMI server SHOULD preserve the relative order of all user-ordered 876 list and leaf-list entries that are received in a single edit 877 request. These YANG data node types are encoded as CBOR arrays so 878 messages will preserve their order. 880 4.3.2. POST 882 The CoAP POST operation is used in CoMI for creation of data node 883 resources and the invocation of "ACTION" and "RPC" resources. Refer 884 to Section 4.6 for details on "ACTION" and "RPC" resources. 886 A request to create a data node resource is sent with a CoAP POST 887 message. The URI specifies the data node to be instantiated at the 888 exception of list instances. In this case, for compactness, the URI 889 specifies the list for which an instance is created. 891 FORMAT: 892 POST /c/ 893 (Content-Format :application/yang-data+cbor) 894 CBOR map of SID, instance-value 896 2.01 Created 898 If the data node resource already exists, then the POST request MUST 899 fail and a "4.09 Conflict" response code MUST be returned 901 4.3.2.1. Post example 903 The example uses the interface list from Appendix C.1. Example is 904 creating a new list instance within the interface list (SID = 1533): 906 REQ: POST /c/X9 (Content-Format: application/yang-data+cbor) 907 { 908 1533 : [ 909 { 910 +4 : "eth5", / name (SID 1537) / 911 +1 : "Ethernet adaptor", / description (SID 1534) / 912 +5 : 1880, / type (SID 1538), identity / 913 / ethernetCsmacd (SID 1880) / 914 +2 : true / enabled (SID 1535) / 915 } 916 ] 917 } 919 RES: 2.01 Created 921 4.3.3. PUT 923 A data node resource instance is created or replaced with the PUT 924 method. A request to set the value of a data node instance is sent 925 with a CoAP PUT message. 927 FORMAT: 928 PUT /c/ 929 (Content-Format :application/yang-data+cbor) 930 CBOR map of SID, instance-value 932 2.01 Created 934 4.3.3.1. PUT example 936 The example uses the interface list from Appendix C.1. Example is 937 renewing an instance of the list interface (SID = 1533) with key 938 name="eth0": 940 REQ: PUT /c/X9?k="eth0" (Content-Format: application/yang-data+cbor) 941 { 942 1533 : [ 943 { 944 +4 : "eth0", / name (SID 1537) / 945 +1 : "Ethernet adaptor", / description (SID 1534) / 946 +5 : 1880, / type (SID 1538), identity / 947 / ethernetCsmacd (SID 1880) / 948 +2 : true / enabled (SID 1535) / 949 } 950 ] 951 } 953 RES: 2.04 Changed 955 4.3.4. iPATCH 957 One or multiple data node instances are replaced with the idempotent 958 iPATCH method [RFC8132]. A request is sent with a CoAP iPATCH 959 message. 961 There are no Uri-Query options for the iPATCH method. 963 The processing of the iPATCH command is specified by Content-Format 964 'application/yang-instances+cbor'. In summary, if the CBOR patch 965 payload contains a data node instance that is not present in the 966 target, this instance is added. If the target contains the specified 967 instance, the content of this instance is replaced with the value of 968 the payload. A null value indicates the removal of an existing data 969 node instance. 971 FORMAT: 972 iPATCH /c (Content-Format: application/yang-instances+cbor) 973 CBOR array of CBOR map of instance-identifier, instance-value 975 2.04 Changed 977 4.3.4.1. iPATCH example 979 In this example, a CoMI client requests the following operations: 981 o Set "/system/ntp/enabled" (SID 1755) to true. 983 o Remove the server "tac.nrc.ca" from the"/system/ntp/server" (SID 984 1756) list. 986 o Add/set the server "NTP Pool server 2" to the list "/system/ntp/ 987 server" (SID 1756). 989 REQ: iPATCH /c (Content-Format: application/yang-instances+cbor) 990 [ 991 { 992 1755 : true / enabled (SID 1755) / 993 }, 994 { 995 [1756, "tac.nrc.ca"] : null / server (SID 1756) / 996 }, 997 { 998 1756 : { / server (SID 1756) / 999 +3 : "tic.nrc.ca", / name (SID 1759) / 1000 +4 : true, / prefer (SID 1760) / 1001 +5 : { / udp (SID 1761) / 1002 +1 : "132.246.11.231" / address (SID 1762) / 1003 } 1004 } 1005 } 1006 ] 1008 RES: 2.04 Changed 1010 4.3.5. DELETE 1012 A data node resource is deleted with the DELETE method. 1014 FORMAT: 1015 Delete /c/ 1017 2.02 Deleted 1019 4.3.5.1. DELETE example 1021 This example uses the interface list from Appendix C.3. This example 1022 is deleting an instance of the interface list (SID = 1533): 1024 REQ: DELETE /c/X9?k="eth0" 1026 RES: 2.02 Deleted 1028 4.4. Full datastore access 1030 The methods GET, PUT, POST, and DELETE can be used to request, 1031 replace, create, and delete a whole datastore respectively. 1033 FORMAT: 1034 GET /c 1036 2.05 Content (Content-Format: application/yang-data+cbor) 1037 CBOR map of SID, instance-value 1039 FORMAT: 1040 PUT /c (Content-Format: application/yang-data+cbor) 1041 CBOR map of SID, instance-value 1043 2.04 Changed 1045 FORMAT: 1046 POST /c (Content-Format: application/yang-data+cbor) 1047 CBOR map of SID, instance-value 1049 2.01 Created 1051 FORMAT: 1052 DELETE /c 1054 2.02 Deleted 1056 The content of the CBOR map represents the complete datastore of the 1057 server at the GET indication of after a successful processing of a 1058 PUT or POST request. 1060 4.4.1. Full datastore examples 1062 The example uses the interface list and the clock container from 1063 Appendix C.3. Assume that the datastore contains two modules ietf- 1064 system (SID 1700) and ietf-interfaces (SID 1500); they contain the 1065 'interface' list (SID 1533) with one instance and the 'clock' 1066 container (SID 1721). After invocation of GET, a CBOR map with data 1067 nodes from these two modules is returned: 1069 REQ: GET /c 1071 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 1072 { 1073 1721 : { / Clock (SID 1721) / 1074 +2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) / 1075 +1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) / 1076 }, 1077 1533 : [ 1078 { / interface (SID 1533) / 1079 +4 : "eth0", / name (SID 1537) / 1080 +1 : "Ethernet adaptor", / description (SID 1534) / 1081 +5 : 1880, / type (SID 1538), identity: / 1082 / ethernetCsmacd (SID 1880) / 1083 +2 : true / enabled (SID 1535) / 1084 } 1085 ] 1086 } 1088 4.5. Event stream 1090 Event notification is an essential function for the management of 1091 servers. CoMI allows notifications specified in YANG [RFC5277] to be 1092 reported to a list of clients. The recommended path of the default 1093 event stream is /s. The server MAY support additional event stream 1094 resources to address different notification needs. 1096 Reception of notification instances is enabled with the CoAP Observe 1097 [RFC7641] function. Clients subscribe to the notifications by 1098 sending a GET request with an "Observe" option, specifying the /s 1099 resource when the default stream is selected. 1101 Each response payload carries one or multiple notifications. The 1102 number of notification reported and the conditions used to remove 1103 notifications from the reported list is left to implementers. When 1104 multiple notifications are reported, they MUST be ordered starting 1105 from the newest notification at index zero. 1107 The format of notification contents is defined in 1108 [I-D.ietf-core-yang-cbor] section 4.2.1. For notification without 1109 any content, a null value is returned. 1111 An example implementation is: 1113 Every time an event is generated, the generated notification 1114 instance is appended to the chosen stream(s). After an 1115 aggregation period, which may be adjusted using an exclusion delay 1116 and limited by the maximum number of notifications supported, the 1117 content of the instance is sent to all clients observing the 1118 modified stream. 1120 FORMAT: 1121 GET / Observe(0) 1123 2.05 Content (Content-Format :application/yang-instances+cbor) 1124 CBOR array of CBOR map of instance-identifier, instance-value 1126 The array of data node instances may contain identical entries which 1127 have been generated at different times. 1129 4.5.1. Notify Examples 1131 Suppose the server generates the event specified in Appendix C.4. By 1132 executing a GET on the /s resource the client receives the following 1133 response: 1135 REQ: GET /s Observe(0) Token(0x93) 1137 RES: 2.05 Content (Content-Format :application/yang-tree+cbor) 1138 Observe(12) Token(0x93) 1139 [ 1140 { 1141 60010 : { / example-port-fault (SID 60010) / 1142 +1 : "0/4/21", / port-name (SID 60011) / 1143 +2 : "Open pin 2" / port-fault (SID 60012) / 1144 } 1145 }, 1146 { 1147 60010 : { / example-port-fault (SID 60010) / 1148 +1 : "1/4/21", / port-name (SID 60011) / 1149 +2 : "Open pin 5" / port-fault (SID 60012) / 1150 } 1151 } 1152 ] 1154 In the example, the request returns a success response with the 1155 contents of the last two generated events. Consecutively the server 1156 will regularly notify the client when a new event is generated. 1158 To check that the client is still alive, the server MUST send 1159 Confirmable Message periodically. When the client does not confirm 1160 the notification from the server, the server will remove the client 1161 from the list of observers [RFC7641]. 1163 4.6. RPC statements 1165 The YANG "action" and "RPC" statements specify the execution of a 1166 Remote procedure Call (RPC) in the server. It is invoked using a 1167 POST method to an "Action" or "RPC" resource instance. 1169 The request payload contains the values assigned to the input 1170 container when specified. The response payload contains the values 1171 of the output container when specified. Both the input and output 1172 containers are encoded in CBOR using the rules defined in 1173 [I-D.ietf-core-yang-cbor] section 4.2.1. 1175 The returned success response code is 2.05 Content. 1177 FORMAT: 1178 POST /c/ 1179 (Content-Format :application/yang-data+cbor) 1180 CBOR map of SID, instance-value 1182 2.05 Content (Content-Format :application/yang-data+cbor) 1183 CBOR map of SID, instance-value 1185 4.6.1. RPC Example 1187 The example is based on the YANG action specification of 1188 Appendix C.2. A server list is specified and the action "reset" (SID 1189 60002, base64: Opq), that is part of a "server instance" with key 1190 value "myserver", is invoked. 1192 REQ: POST /c/Opq?k="myserver" 1193 (Content-Format :application/yang-data+cbor) 1194 { 1195 60002 : { 1196 +1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / 1197 } 1198 } 1200 RES: 2.05 Content (Content-Format :application/yang-data+cbor) 1201 { 1202 60002 : { 1203 +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ 1204 } 1205 } 1207 5. Access to MIB Data 1209 Appendix C.5 shows a YANG module mapped from the SMI specification 1210 "IP-MIB" [RFC4293]. The following example shows the 1211 "ipNetToPhysicalEntry" list with 2 instances. 1213 REQ: GET example.com/c/Oz1 1215 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 1216 { 1217 60021 : [ / ipNetToPhysicalEntry / 1218 { 1219 +1 : 1, / ipNetToPhysicalIfIndex (SID 60022) / 1220 +2 : 1, / ipNetToPhysicalNetAddressType (SID 60023) / 1221 +3 : h'0A000033', / ipNetToPhysicalNetAddress (SID 60024) / 1222 +4 : h'00000A01172D',/ ipNetToPhysicalPhysAddress (SID 60025) / 1223 +5 : 2333943, / ipNetToPhysicalLastUpdated (SID 60026) / 1224 +6 : 4, / ipNetToPhysicalType (SID 60027) / 1225 +7 : 1, / ipNetToPhysicalState (SID 60028) / 1226 +8 : 1 / ipNetToPhysicalRowStatus (SID 60029) / 1227 }, 1228 { 1229 +1 : 1, / ipNetToPhysicalIfIndex (SID 60022) / 1230 +2 : 1, / ipNetToPhysicalNetAddressType (SID 60023) / 1231 +3 : h'09020304', / ipNetToPhysicalNetAddress (SID 60024) / 1232 +4 : h'00000A36200A',/ ipNetToPhysicalPhysAddress (SID 60025) / 1233 +5 : 2329836, / ipNetToPhysicalLastUpdated (SID 60026) / 1234 +6 : 3, / ipNetToPhysicalType (SID 60027) / 1235 +7 : 6, / ipNetToPhysicalState (SID 60028) / 1236 +8 : 1 / ipNetToPhysicalRowStatus (SID 60029) / 1237 } 1238 ] 1239 } 1241 6. Use of Block 1243 The CoAP protocol provides reliability by acknowledging the UDP 1244 datagrams. However, when large pieces of data need to be 1245 transported, datagrams get fragmented, thus creating constraints on 1246 the resources in the client, server and intermediate routers. The 1247 block option [RFC7959] allows the transport of the total payload in 1248 individual blocks of which the size can be adapted to the underlying 1249 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1250 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1251 acknowledged to guarantee reliability. 1253 Notice that the Block mechanism splits the data at fixed positions, 1254 such that individual data fields may become fragmented. Therefore, 1255 assembly of multiple blocks may be required to process the complete 1256 data field. 1258 Beware of race conditions. Blocks are filled one at a time and care 1259 should be taken that the whole data representation is sent in 1260 multiple blocks sequentially without interruption. On the server, 1261 values are changed, lists are re-ordered, extended or reduced. When 1262 these actions happen during the serialization of the contents of the 1263 resource, the transported results do not correspond with a state 1264 having occurred in the server; or worse the returned values are 1265 inconsistent. For example: array length does not correspond with the 1266 actual number of items. It may be advisable to use Indefinite-length 1267 CBOR arrays and maps, which are foreseen for data streaming purposes. 1269 7. Application Discovery 1271 Two application discovery mechanisms are supported by CoMI, the YANG 1272 library data model as defined by [I-D.veillette-core-yang-library] 1273 and the CORE resource discovery [RFC6690]. Implementers may choose 1274 to implement one or the other or both. 1276 7.1. YANG library 1278 The YANG library data model [I-D.veillette-core-yang-library] 1279 provides a high level description of the resources available. The 1280 YANG library contains the list of modules, features and deviations 1281 supported by the CoMI server. From this information, CoMI clients 1282 can infer the list of data nodes supported and the interaction model 1283 to be used to access them. This module also contains the list of 1284 datastores implemented. 1286 The location of the YANG library can be found by sending a GET 1287 request to "/.well-known/core" including a resource type (RT) 1288 parameter with the value "core.c.yl". Upon success, the return 1289 payload will contain the root resource of the YANG library module. 1291 REQ: GET /.well-known/core?rt=core.c.yl 1293 RES: 2.05 Content (Content-Format: application/link-format) 1294 ;rt="core.c.yl" 1296 7.2. Resource Discovery 1298 Even if the YANG library provides all the information needed for 1299 application discovery, the implementation of Resource discovery as 1300 defined by [RFC6690] can be desirable for a seamless integration with 1301 other CoAP interfaces and services. 1303 7.2.1. Datastore Resource Discovery 1305 The presence and location of (path to) each datastore implemented by 1306 the CoMI server can be discovered by sending a GET request to 1307 "/.well-known/core" including a resource type (RT) parameter with the 1308 value "core.c.ds". 1310 Upon success, the return payload contains the list of datastore 1311 resources. 1313 Each datastore returned is further qualified using the "ds" Link- 1314 Format attribute. This attribute is set to the SID assigned to the 1315 datastore identity. When a unified datastore is implemented, the ds 1316 attribute is set to 1029. For other examples of datastores, see the 1317 Network Management Datastore Architecture (NMDA) [RFC7950]. 1319 link-extension = ( "ds" "=" sid ) ) 1320 ; SID assigned to the datastore identity 1321 sid = 1*DIGIT 1323 For example: 1325 REQ: GET /.well-known/core?rt=core.c.ds 1327 RES: 2.05 Content (Content-Format: application/link-format) 1328 ; rt="core.c.ds";ds= 1029 1330 7.2.2. Data node Resource Discovery 1332 The presence and location of (path to) each data node implemented by 1333 the CoMI server are discovered by sending a GET request to "/.well- 1334 known/core" including a resource type (RT) parameter with the value 1335 "core.c.dn". 1337 Upon success, the return payload contains the SID assigned to each 1338 data node and their location. 1340 The example below shows the discovery of the presence and location of 1341 data nodes. Data nodes '/ietf-system:system-state/clock/boot- 1342 datetime' (SID 1722) and '/ietf-system:system-state/clock/current- 1343 datetime' (SID 1723) are returned. 1345 REQ: GET /.well-known/core?rt=core.c.dn 1347 RES: 2.05 Content (Content-Format: application/link-format) 1348 ;rt="core.c.dn", 1349 ;rt="core.c.dn" 1350 The list of data nodes may become prohibitively long. 1351 Implementations MAY return a subset of this list or can rely solely 1352 on the YANG library. 1354 7.2.3. Event stream Resource Discovery 1356 The presence and location of (path to) each event stream implemented 1357 by the CoMI server are discovered by sending a GET request to 1358 "/.well-known/core" including a resource type (RT) parameter with the 1359 value "core.c.es". 1361 Upon success, the return payload contains the list of event stream 1362 resources. 1364 For example: 1366 REQ: GET /.well-known/core?rt=core.c.es 1368 RES: 2.05 Content (Content-Format: application/link-format) 1369 ;rt="core.c.es" 1371 8. Error Handling 1373 In case a request is received which cannot be processed properly, the 1374 CoMI server MUST return an error message. This error message MUST 1375 contain a CoAP 4.xx or 5.xx response code. 1377 Errors returned by a CoMI server can be broken into two categories, 1378 those associated to the CoAP protocol itself and those generated 1379 during the validation of the YANG data model constrains as described 1380 in [RFC7950] section 8. 1382 The following list of common CoAP errors should be implemented by 1383 CoMI servers. This list is not exhaustive, other errors defined by 1384 CoAP and associated RFCs may be applicable. 1386 o Error 4.01 (Unauthorized) is returned by the CoMI server when the 1387 CoMI client is not authorized to perform the requested action on 1388 the targeted resource (i.e. data node, datastore, rpc, action or 1389 event stream). 1391 o Error 4.02 (Bad Option) is returned by the CoMI server when one or 1392 more CoAP options are unknown or malformed. 1394 o Error 4.04 (Not Found) is returned by the CoMI server when the 1395 CoMI client is requesting a non-instantiated resource (i.e. data 1396 node, datastore, rpc, action or event stream). 1398 o Error 4.05 (Method Not Allowed) is returned by the CoMI server 1399 when the CoMI client is requesting a method not supported on the 1400 targeted resource. (e.g. GET on an rpc, PUT or POST on a data 1401 node with "config" set to false). 1403 o Error 4.08 (Request Entity Incomplete) is returned by the CoMI 1404 server if one or multiple blocks of a block transfer request is 1405 missing, see [RFC7959] for more details. 1407 o Error 4.13 (Request Entity Too Large) may be returned by the CoMI 1408 server during a block transfer request, see [RFC7959] for more 1409 details. 1411 o Error 4.15 (Unsupported Content-Format) is returned by the CoMI 1412 server when the Content-Format used in the request don't match 1413 those specified in section Section 2.4. 1415 CoMI server MUST also enforce the different constraints associated to 1416 the YANG data models implemented. These constraints are described in 1417 [RFC7950] section 8. These errors are reported using the CoAP error 1418 code 4.00 (Bad Request) and may have the following error container as 1419 payload. The YANG definition and associated .sid file are available 1420 in Appendix A and Appendix B. The error container is encoded using 1421 the encoding rules of a YANG data template as defined in 1422 [I-D.ietf-core-yang-cbor] section 5. 1424 +--rw error! 1425 +--rw error-tag identityref 1426 +--rw error-app-tag? identityref 1427 +--rw error-data-node? instance-identifier 1428 +--rw error-message? string 1430 The following 'error-tag' and 'error-app-tag' are defined by the 1431 ietf-comi YANG module, these tags are implemented as YANG identity 1432 and can be extended as needed. 1434 o error-tag 'operation-failed' is returned by the CoMI server when 1435 the operation request cannot be processed successfully. 1437 * error-app-tag 'malformed-message' is returned by the CoMI 1438 server when the payload received from the CoMI client don't 1439 contain a well-formed CBOR content as defined in [RFC7049] 1440 section 3.3 or don't comply with the CBOR structure defined 1441 within this document. 1443 * error-app-tag 'data-not-unique' is returned by the CoMI server 1444 when the validation of the 'unique' constraint of a list or 1445 leaf-list fails. 1447 * error-app-tag 'too-many-elements' is returned by the CoMI 1448 server when the validation of the 'max-elements' constraint of 1449 a list or leaf-list fails. 1451 * error-app-tag 'too-few-elements' is returned by the CoMI server 1452 when the validation of the 'min-elements' constraint of a list 1453 or leaf-list fails. 1455 * error-app-tag 'must-violation' is returned by the CoMI server 1456 when the restrictions imposed by a 'must' statement are 1457 violated. 1459 * error-app-tag 'duplicate' is returned by the CoMI server when a 1460 client tries to create a duplicate list or leaf-list entry. 1462 o error-tag 'invalid-value' is returned by the CoMI server when the 1463 CoMI client tries to update or create a leaf with a value encoded 1464 using an invalid CBOR datatype or if the 'range', 'length', 1465 'pattern' or 'require-instance' constrain is not fulfilled. 1467 * error-app-tag 'invalid-datatype' is returned by the CoMI server 1468 when CBOR encoding don't follow the rules set by or when the 1469 value is incompatible with the YANG Built-In type. (e.g. a 1470 value greater than 127 for an int8, undefined enumeration) 1472 * error-app-tag 'not-in-range' is returned by the CoMI server 1473 when the validation of the 'range' property fails. 1475 * error-app-tag 'invalid-length' is returned by the CoMI server 1476 when the validation of the 'length' property fails. 1478 * error-app-tag 'pattern-test-failed' is returned by the CoMI 1479 server when the validation of the 'pattern' property fails. 1481 o error-tag 'missing-element' is returned by the CoMI server when 1482 the operation requested by a CoMI client fail to comply with the 1483 'mandatory' constraint defined. The 'mandatory' constraint is 1484 enforced for leafs and choices, unless the node or any of its 1485 ancestors have a 'when' condition or 'if-feature' expression that 1486 evaluates to 'false'. 1488 * error-app-tag 'missing-key' is returned by the CoMI server to 1489 further qualify an missing-element error. This error is 1490 returned when the CoMI client tries to create or list instance, 1491 without all the 'key' specified or when the CoMI client tries 1492 to delete a leaf listed as a 'key'. 1494 * error-app-tag 'missing-input-parameter' is returned by the CoMI 1495 server when the input parameters of an RPC or action are 1496 incomplete. 1498 o error-tag 'unknown-element' is returned by the CoMI server when 1499 the CoMI client tries to access a data node of a YANG module not 1500 supported, of a data node associated to an 'if-feature' expression 1501 evaluated to 'false' or to a 'when' condition evaluated to 1502 'false'. 1504 o error-tag 'bad-element' is returned by the CoMI server when the 1505 CoMI client tries to create data nodes for more than one case in a 1506 choice. 1508 o error-tag 'data-missing' is returned by the CoMI server when a 1509 data node required to accept the request is not present. 1511 * error-app-tag 'instance-required' is returned by the CoMI 1512 server when a leaf of type 'instance-identifier' or 'leafref' 1513 marked with require-instance set to 'true' refers to an 1514 instance that does not exist. 1516 * error-app-tag 'missing-choice' is returned by the CoMI server 1517 when no nodes exist in a mandatory choice. 1519 o error-tag 'error' is returned by the CoMI server when an 1520 unspecified error has occurred. 1522 For example, the CoMI server might return the following error. 1524 RES: 4.00 Bad Request (Content-Format :application/yang-data+cbor) 1525 { 1526 1024 : { 1527 +4 : 1011, / error-tag (SID 1028) / 1528 / = invalid-value (SID 1011) / 1529 +1 : 1018, / error-app-tag (SID 1025) / 1530 / = not-in-range (SID 1018) / 1531 +2 : 1740, / error-data-node (SID 1026) / 1532 / = timezone-utc-offset (SID 1740) / 1533 +3 : "maximum value exceeded" / error-message (SID 1027) / 1534 } 1535 } 1537 9. Security Considerations 1539 For secure network management, it is important to restrict access to 1540 configuration variables only to authorized parties. CoMI re-uses the 1541 security mechanisms already available to CoAP, this includes DTLS 1543 [RFC6347] for protected access to resources, as well suitable 1544 authentication and authorization mechanisms. 1546 Among the security decisions that need to be made are selecting 1547 security modes and encryption mechanisms (see [RFC7252]). This 1548 requires a trade-off, as the NoKey mode gives no protection at all, 1549 but is easy to implement, whereas the X.509 mode is quite secure, but 1550 may be too complex for constrained devices. 1552 In addition, mechanisms for authentication and authorization may need 1553 to be selected. 1555 CoMI avoids defining new security mechanisms as much as possible. 1556 However, some adaptations may still be required, to cater for CoMI's 1557 specific requirements. 1559 10. IANA Considerations 1561 10.1. Resource Type (rt=) Link Target Attribute Values Registry 1563 This document adds the following resource type to the "Resource Type 1564 (rt=) Link Target Attribute Values", within the "Constrained RESTful 1565 Environments (CoRE) Parameters" registry. 1567 +-----------+---------------------+-----------+ 1568 | Value | Description | Reference | 1569 +-----------+---------------------+-----------+ 1570 | core.c.ds | YANG datastore | RFC XXXX | 1571 | | | | 1572 | core.c.dn | YANG data node | RFC XXXX | 1573 | | | | 1574 | core.c.yl | YANG module library | RFC XXXX | 1575 | | | | 1576 | core.c.es | YANG event stream | RFC XXXX | 1577 +-----------+---------------------+-----------+ 1579 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1580 note. 1582 10.2. CoAP Content-Formats Registry 1584 This document adds the following Content-Format to the "CoAP Content- 1585 Formats", within the "Constrained RESTful Environments (CoRE) 1586 Parameters" registry. 1588 +-----------------------------------+-------------+-----------+ 1589 | Media Type | Encoding ID | Reference | 1590 +-----------------------------------+-------------+-----------+ 1591 | application/yang-data+cbor | XXX | RFC XXXX | 1592 | | | | 1593 | application/yang-identifiers+cbor | XXX | RFC XXXX | 1594 | | | | 1595 | application/yang-instances+cbor | XXX | RFC XXXX | 1596 +-----------------------------------+-------------+-----------+ 1598 // RFC Ed.: replace XXX with assigned IDs and remove this note. // 1599 RFC Ed.: replace RFC XXXX with this RFC number and remove this note. 1601 10.3. Media Types Registry 1603 This document adds the following media types to the "Media Types" 1604 registry. 1606 +-----------------------+----------------------------+-----------+ 1607 | Name | Template | Reference | 1608 +-----------------------+----------------------------+-----------+ 1609 | yang-data+cbor | application/yang-data+cbor | RFC XXXX | 1610 | | | | 1611 | yang-identifiers+cbor | application/ | RFC XXXX | 1612 | | | | 1613 | | yang-identifiers+cbor | | 1614 | | | | 1615 | yang-instances+cbor | application/ | RFC XXXX | 1616 | | | | 1617 | | yang-instances+cbor | | 1618 +-----------------------+----------------------------+-----------+ 1620 Each of these media types share the following information: 1622 o Subtype name: 1624 o Required parameters: N/A 1626 o Optional parameters: N/A 1628 o Encoding considerations: binary 1630 o Security considerations: See the Security Considerations section 1631 of RFC XXXX 1633 o Interoperability considerations: N/A 1635 o Published specification: RFC XXXX 1636 o Applications that use this media type: CoMI 1638 o Fragment identifier considerations: N/A 1640 o Additional information: 1642 * Deprecated alias names for this type: N/A 1644 * Magic number(s): N/A 1646 * File extension(s): N/A 1648 * Macintosh file type code(s): N/A 1650 o Person & email address to contact for further information: 1651 iesg&ietf.org 1653 o Intended usage: COMMON 1655 o Restrictions on usage: N/A 1657 o Author: Michel Veillette, ietf&augustcellars.com 1659 o Change Controller: IESG 1661 o Provisional registration? No 1663 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1664 note. 1666 11. Acknowledgements 1668 We are very grateful to Bert Greevenbosch who was one of the original 1669 authors of the CoMI specification and specified CBOR encoding and use 1670 of hashes. 1672 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1673 transported under SNMP. Carsten Bormann has given feedback on the 1674 use of CBOR. 1676 The draft has benefited from comments (alphabetical order) by Rodney 1677 Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy 1678 Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes 1679 Tschofenig, Michael Verschoor, and Thomas Watteyne. 1681 12. References 1683 12.1. Normative References 1685 [I-D.ietf-core-sid] 1686 Veillette, M. and A. Pelov, "YANG Schema Item iDentifier 1687 (SID)", draft-ietf-core-sid-04 (work in progress), June 1688 2018. 1690 [I-D.ietf-core-yang-cbor] 1691 Veillette, M., Pelov, A., Turner, R., and A. Minaburo, 1692 "CBOR Encoding of Data Modeled with YANG", draft-ietf- 1693 core-yang-cbor-07 (work in progress), September 2018. 1695 [I-D.veillette-core-yang-library] 1696 Veillette, M., "Constrained YANG Module Library", draft- 1697 veillette-core-yang-library-03 (work in progress), 1698 September 2018. 1700 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1701 Requirement Levels", BCP 14, RFC 2119, 1702 DOI 10.17487/RFC2119, March 1997, 1703 . 1705 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1706 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1707 . 1709 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1710 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1711 . 1713 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1714 and A. Bierman, Ed., "Network Configuration Protocol 1715 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1716 . 1718 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1719 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1720 . 1722 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1723 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1724 October 2013, . 1726 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1727 Application Protocol (CoAP)", RFC 7252, 1728 DOI 10.17487/RFC7252, June 2014, 1729 . 1731 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1732 Application Protocol (CoAP)", RFC 7641, 1733 DOI 10.17487/RFC7641, September 2015, 1734 . 1736 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1737 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1738 . 1740 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1741 the Constrained Application Protocol (CoAP)", RFC 7959, 1742 DOI 10.17487/RFC7959, August 2016, 1743 . 1745 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1746 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1747 . 1749 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1750 FETCH Methods for the Constrained Application Protocol 1751 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1752 . 1754 12.2. Informative References 1756 [RFC4293] Routhier, S., Ed., "Management Information Base for the 1757 Internet Protocol (IP)", RFC 4293, DOI 10.17487/RFC4293, 1758 April 2006, . 1760 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1761 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1762 January 2012, . 1764 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1765 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1766 . 1768 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1769 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1770 . 1772 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1773 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1774 2014, . 1776 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1777 and R. Wilton, "Network Management Datastore Architecture 1778 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1779 . 1781 Appendix A. ietf-comi YANG module 1783 file "ietf-comi@2018-09-26.yang" 1784 module ietf-comi { 1785 yang-version 1.1; 1787 namespace "urn:ietf:params:xml:ns:yang:ietf-comi"; 1788 prefix comi; 1790 import ietf-datastores { 1791 prefix ds; 1792 } 1794 import ietf-restconf { 1795 prefix rc; 1796 description 1797 "This import statement is only present to access 1798 the yang-data extension defined in RFC 8040."; 1799 reference "RFC 8040: RESTCONF Protocol"; 1800 } 1802 organization 1803 "IETF Core Working Group"; 1805 contact 1806 "Michel Veillette 1807 1809 Alexander Pelov 1810 1812 Peter van der Stok 1813 1815 Andy Bierman 1816 "; 1818 description 1819 "This module contains the different definitions required 1820 by the CoMI protocol."; 1822 revision 2018-09-26 { 1823 description 1824 "Use of YANG data template for the error payload. 1825 Definition of the unified datastore."; 1826 reference 1827 "[I-D.ietf-core-comi] CoAP Management Interface"; 1828 } 1829 revision 2017-07-01 { 1830 description 1831 "Initial revision."; 1832 reference 1833 "[I-D.ietf-core-comi] CoAP Management Interface"; 1834 } 1836 typedef sid { 1837 type uint64; 1838 description 1839 "YANG Schema Item iDentifier"; 1840 reference 1841 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 1842 } 1844 identity unified { 1845 base ds:datastore; 1846 description 1847 "The unified configuration and operational state datastore."; 1848 } 1850 identity error-tag { 1851 description 1852 "Base identity for error-tag."; 1853 } 1855 identity operation-failed { 1856 base error-tag; 1857 description 1858 "Returned by the CoMI server when the operation request 1859 can't be processed successfully."; 1860 } 1862 identity invalid-value { 1863 base error-tag; 1864 description 1865 "Returned by the CoMI server when the CoMI client tries to 1866 update or create a leaf with a value encoded using an 1867 invalid CBOR datatype or if the 'range', 'length', 1868 'pattern' or 'require-instance' constrain is not 1869 fulfilled."; 1870 } 1872 identity missing-element { 1873 base error-tag; 1874 description 1875 "Returned by the CoMI server when the operation requested 1876 by a CoMI client fails to comply with the 'mandatory' 1877 constraint defined. The 'mandatory' constraint is 1878 enforced for leafs and choices, unless the node or any of 1879 its ancestors have a 'when' condition or 'if-feature' 1880 expression that evaluates to 'false'."; 1881 } 1883 identity unknown-element { 1884 base error-tag; 1885 description 1886 "Returned by the CoMI server when the CoMI client tries to 1887 access a data node of a YANG module not supported, of a 1888 data node associated with an 'if-feature' expression 1889 evaluated to 'false' or to a 'when' condition evaluated 1890 to 'false'."; 1891 } 1893 identity bad-element { 1894 base error-tag; 1895 description 1896 "Returned by the CoMI server when the CoMI client tries to 1897 create data nodes for more than one case in a choice."; 1898 } 1900 identity data-missing { 1901 base error-tag; 1902 description 1903 "Returned by the CoMI server when a data node required to 1904 accept the request is not present."; 1905 } 1907 identity error { 1908 base error-tag; 1909 description 1910 "Returned by the CoMI server when an unspecified error has 1911 occurred."; 1912 } 1914 identity error-app-tag { 1915 description 1916 "Base identity for error-app-tag."; 1917 } 1919 identity malformed-message { 1920 base error-app-tag; 1921 description 1922 "Returned by the CoMI server when the payload received 1923 from the CoMI client don't contain a well-formed CBOR 1924 content as defined in [RFC7049] section 3.3 or don't 1925 comply with the CBOR structure defined within this 1926 document."; 1927 } 1929 identity data-not-unique { 1930 base error-app-tag; 1931 description 1932 "Returned by the CoMI server when the validation of the 1933 'unique' constraint of a list or leaf-list fails."; 1934 } 1936 identity too-many-elements { 1937 base error-app-tag; 1938 description 1939 "Returned by the CoMI server when the validation of the 1940 'max-elements' constraint of a list or leaf-list fails."; 1941 } 1943 identity too-few-elements { 1944 base error-app-tag; 1945 description 1946 "Returned by the CoMI server when the validation of the 1947 'min-elements' constraint of a list or leaf-list fails."; 1948 } 1950 identity must-violation { 1951 base error-app-tag; 1952 description 1953 "Returned by the CoMI server when the restrictions 1954 imposed by a 'must' statement are violated."; 1955 } 1957 identity duplicate { 1958 base error-app-tag; 1959 description 1960 "Returned by the CoMI server when a client tries to create 1961 a duplicate list or leaf-list entry."; 1962 } 1963 identity invalid-datatype { 1964 base error-app-tag; 1965 description 1966 "Returned by the CoMI server when CBOR encoding is 1967 incorect or when the value encoded is incompatible with 1968 the YANG Built-In type. (e.g. value greater than 127 1969 for an int8, undefined enumeration)."; 1970 } 1972 identity not-in-range { 1973 base error-app-tag; 1974 description 1975 "Returned by the CoMI server when the validation of the 1976 'range' property fails."; 1977 } 1979 identity invalid-length { 1980 base error-app-tag; 1981 description 1982 "Returned by the CoMI server when the validation of the 1983 'length' property fails."; 1984 } 1986 identity pattern-test-failed { 1987 base error-app-tag; 1988 description 1989 "Returned by the CoMI server when the validation of the 1990 'pattern' property fails."; 1991 } 1993 identity missing-key { 1994 base error-app-tag; 1995 description 1996 "Returned by the CoMI server to further qualify a 1997 missing-element error. This error is returned when the 1998 CoMI client tries to create or list instance, without all 1999 the 'key' specified or when the CoMI client tries to 2000 delete a leaf listed as a 'key'."; 2001 } 2003 identity missing-input-parameter { 2004 base error-app-tag; 2005 description 2006 "Returned by the CoMI server when the input parameters 2007 of a RPC or action are incomplete."; 2008 } 2010 identity instance-required { 2011 base error-app-tag; 2012 description 2013 "Returned by the CoMI server when a leaf of type 2014 'instance-identifier' or 'leafref' marked with 2015 require-instance set to 'true' refers to an instance 2016 that does not exist."; 2017 } 2019 identity missing-choice { 2020 base error-app-tag; 2021 description 2022 "Returned by the CoMI server when no nodes exist in a 2023 mandatory choice."; 2024 } 2026 rc:yang-data comi-error { 2027 container error { 2028 description 2029 "Optional payload of a 4.00 Bad Request CoAP error."; 2031 leaf error-tag { 2032 type identityref { 2033 base error-tag; 2034 } 2035 mandatory true; 2036 description 2037 "The enumerated error-tag."; 2038 } 2040 leaf error-app-tag { 2041 type identityref { 2042 base error-app-tag; 2043 } 2044 description 2045 "The application-specific error-tag."; 2046 } 2048 leaf error-data-node { 2049 type instance-identifier; 2050 description 2051 "When the error reported is caused by a specific data node, 2052 this leaf identifies the data node in error."; 2053 } 2055 leaf error-message { 2056 type string; 2057 description 2058 "A message describing the error."; 2060 } 2061 } 2062 } 2063 } 2064 2066 Appendix B. ietf-comi .sid file 2068 { 2069 "assignment-ranges": [ 2070 { 2071 "entry-point": 1000, 2072 "size": 100 2073 } 2074 ], 2075 "module-name": "ietf-comi", 2076 "module-revision": "2018-09-26", 2077 "items": [ 2078 { 2079 "namespace": "module", 2080 "identifier": "ietf-comi", 2081 "sid": 1000 2082 }, 2083 { 2084 "namespace": "identity", 2085 "identifier": "bad-element", 2086 "sid": 1001 2087 }, 2088 { 2089 "namespace": "identity", 2090 "identifier": "data-missing", 2091 "sid": 1002 2092 }, 2093 { 2094 "namespace": "identity", 2095 "identifier": "data-not-unique", 2096 "sid": 1003 2097 }, 2098 { 2099 "namespace": "identity", 2100 "identifier": "duplicate", 2101 "sid": 1004 2102 }, 2103 { 2104 "namespace": "identity", 2105 "identifier": "error", 2106 "sid": 1005 2107 }, 2108 { 2109 "namespace": "identity", 2110 "identifier": "error-app-tag", 2111 "sid": 1006 2112 }, 2113 { 2114 "namespace": "identity", 2115 "identifier": "error-tag", 2116 "sid": 1007 2117 }, 2118 { 2119 "namespace": "identity", 2120 "identifier": "instance-required", 2121 "sid": 1008 2122 }, 2123 { 2124 "namespace": "identity", 2125 "identifier": "invalid-datatype", 2126 "sid": 1009 2127 }, 2128 { 2129 "namespace": "identity", 2130 "identifier": "invalid-length", 2131 "sid": 1010 2132 }, 2133 { 2134 "namespace": "identity", 2135 "identifier": "invalid-value", 2136 "sid": 1011 2137 }, 2138 { 2139 "namespace": "identity", 2140 "identifier": "malformed-message", 2141 "sid": 1012 2142 }, 2143 { 2144 "namespace": "identity", 2145 "identifier": "missing-choice", 2146 "sid": 1013 2147 }, 2148 { 2149 "namespace": "identity", 2150 "identifier": "missing-element", 2151 "sid": 1014 2152 }, 2153 { 2154 "namespace": "identity", 2155 "identifier": "missing-input-parameter", 2156 "sid": 1015 2157 }, 2158 { 2159 "namespace": "identity", 2160 "identifier": "missing-key", 2161 "sid": 1016 2162 }, 2163 { 2164 "namespace": "identity", 2165 "identifier": "must-violation", 2166 "sid": 1017 2167 }, 2168 { 2169 "namespace": "identity", 2170 "identifier": "not-in-range", 2171 "sid": 1018 2172 }, 2173 { 2174 "namespace": "identity", 2175 "identifier": "operation-failed", 2176 "sid": 1019 2177 }, 2178 { 2179 "namespace": "identity", 2180 "identifier": "pattern-test-failed", 2181 "sid": 1020 2182 }, 2183 { 2184 "namespace": "identity", 2185 "identifier": "too-few-elements", 2186 "sid": 1021 2187 }, 2188 { 2189 "namespace": "identity", 2190 "identifier": "too-many-elements", 2191 "sid": 1022 2192 }, 2193 { 2194 "namespace": "identity", 2195 "identifier": "unified", 2196 "sid": 1029 2197 }, 2198 { 2199 "namespace": "identity", 2200 "identifier": "unknown-element", 2201 "sid": 1023 2202 }, 2203 { 2204 "namespace": "data", 2205 "identifier": "/ietf-comi:error", 2206 "sid": 1024 2207 }, 2208 { 2209 "namespace": "data", 2210 "identifier": "/ietf-comi:error/error-app-tag", 2211 "sid": 1025 2212 }, 2213 { 2214 "namespace": "data", 2215 "identifier": "/ietf-comi:error/error-data-node", 2216 "sid": 1026 2217 }, 2218 { 2219 "namespace": "data", 2220 "identifier": "/ietf-comi:error/error-message", 2221 "sid": 1027 2222 }, 2223 { 2224 "namespace": "data", 2225 "identifier": "/ietf-comi:error/error-tag", 2226 "sid": 1028 2227 } 2228 ] 2229 } 2231 Appendix C. YANG example specifications 2233 This appendix shows five YANG example specifications taken over from 2234 as many existing YANG modules. Each YANG item identifier is 2235 accompanied by its SID shown after the "//" comment sign. 2237 C.1. ietf-system 2239 Excerpt of the YANG module ietf-system [RFC7317]. 2241 module ietf-system { // SID 1700 2242 container system { // SID 1717 2243 container clock { // SID 1738 2244 choice timezone { 2245 case timezone-name { 2246 leaf timezone-name { // SID 1739 2247 type timezone-name; 2248 } 2249 } 2250 case timezone-utc-offset { 2251 leaf timezone-utc-offset { // SID 1740 2252 type int16 { 2253 } 2254 } 2255 } 2256 } 2257 } 2258 container ntp { // SID 1754 2259 leaf enabled { // SID 1755 2260 type boolean; 2261 default true; 2262 } 2263 list server { // SID 1756 2264 key name; 2265 leaf name { // SID 1759 2266 type string; 2267 } 2268 choice transport { 2269 case udp { 2270 container udp { // SID 1761 2271 leaf address { // SID 1762 2272 type inet:host; 2273 } 2274 leaf port { // SID 1763 2275 type inet:port-number; 2276 } 2277 } 2278 } 2279 } 2280 leaf association-type { // SID 1757 2281 type enumeration { 2282 enum server { 2283 } 2284 enum peer { 2285 } 2286 enum pool { 2287 } 2288 } 2289 } 2290 leaf iburst { // SID 1758 2291 type boolean; 2292 } 2293 leaf prefer { // SID 1760 2294 type boolean; 2295 default false; 2296 } 2297 } 2298 } 2299 container system-state { // SID 1720 2300 container clock { // SID 1721 2301 leaf current-datetime { // SID 1723 2302 type yang:date-and-time; 2303 } 2304 leaf boot-datetime { // SID 1722 2305 type yang:date-and-time; 2306 } 2307 } 2308 } 2309 } 2311 C.2. server list 2313 Taken over from [RFC7950] section 7.15.3. 2315 module example-server-farm { 2316 yang-version 1.1; 2317 namespace "urn:example:server-farm"; 2318 prefix "sfarm"; 2320 import ietf-yang-types { 2321 prefix "yang"; 2322 } 2324 list server { // SID 60000 2325 key name; 2326 leaf name { // SID 60001 2327 type string; 2328 } 2329 action reset { // SID 60002 2330 input { 2331 leaf reset-at { // SID 60003 2332 type yang:date-and-time; 2333 mandatory true; 2334 } 2335 } 2336 output { 2337 leaf reset-finished-at { // SID 60004 2338 type yang:date-and-time; 2339 mandatory true; 2340 } 2341 } 2342 } 2343 } 2344 } 2346 C.3. interfaces 2348 Excerpt of the YANG module ietf-interfaces [RFC7223]. 2350 module ietf-interfaces { // SID 1500 2351 container interfaces { // SID 1505 2352 list interface { // SID 1533 2353 key "name"; 2354 leaf name { // SID 1537 2355 type string; 2356 } 2357 leaf description { // SID 1534 2358 type string; 2359 } 2360 leaf type { // SID 1538 2361 type identityref { 2362 base interface-type; 2363 } 2364 mandatory true; 2365 } 2367 leaf enabled { // SID 1535 2368 type boolean; 2369 default "true"; 2370 } 2372 leaf link-up-down-trap-enable { // SID 1536 2373 if-feature if-mib; 2374 type enumeration { 2375 enum enabled { 2376 value 1; 2377 } 2378 enum disabled { 2379 value 2; 2380 } 2381 } 2382 } 2383 } 2384 } 2385 } 2387 C.4. Example-port 2389 Notification example defined within this document. 2391 module example-port { 2392 ... 2393 notification example-port-fault { // SID 60010 2394 description 2395 "Event generated if a hardware fault on a 2396 line card port is detected"; 2397 leaf port-name { // SID 60011 2398 type string; 2399 description "Port name"; 2400 } 2401 leaf port-fault { // SID 60012 2402 type string; 2403 description "Error condition detected"; 2404 } 2405 } 2406 } 2408 C.5. IP-MIB 2410 The YANG translation of the SMI specifying the IP-MIB [RFC4293], 2411 extended with example SID numbers, yields: 2413 module IP-MIB { 2414 import IF-MIB { 2415 prefix if-mib; 2416 } 2417 import INET-ADDRESS-MIB { 2418 prefix inet-address; 2419 } 2420 import SNMPv2-TC { 2421 prefix smiv2; 2422 } 2423 import ietf-inet-types { 2424 prefix inet; 2425 } 2426 import yang-smi { 2427 prefix smi; 2428 } 2429 import ietf-yang-types { 2430 prefix yang; 2431 } 2433 container ip { // SID 60020 2434 list ipNetToPhysicalEntry { // SID 60021 2435 key "ipNetToPhysicalIfIndex 2436 ipNetToPhysicalNetAddressType 2437 ipNetToPhysicalNetAddress"; 2438 leaf ipNetToPhysicalIfIndex { // SID 60022 2439 type if-mib:InterfaceIndex; 2440 } 2441 leaf ipNetToPhysicalNetAddressType { // SID 60023 2442 type inet-address:InetAddressType; 2443 } 2444 leaf ipNetToPhysicalNetAddress { // SID 60024 2445 type inet-address:InetAddress; 2446 } 2447 leaf ipNetToPhysicalPhysAddress { // SID 60025 2448 type yang:phys-address { 2449 length "0..65535"; 2450 } 2451 } 2452 leaf ipNetToPhysicalLastUpdated { // SID 60026 2453 type yang:timestamp; 2454 } 2455 leaf ipNetToPhysicalType { // SID 60027 2456 type enumeration { 2457 enum "other" { 2458 value 1; 2459 } 2460 enum "invalid" { 2461 value 2; 2462 } 2463 enum "dynamic" { 2464 value 3; 2465 } 2466 enum "static" { 2467 value 4; 2468 } 2469 enum "local" { 2470 value 5; 2471 } 2472 } 2473 } 2474 leaf ipNetToPhysicalState { // SID 60028 2475 type enumeration { 2476 enum "reachable" { 2477 value 1; 2478 } 2479 enum "stale" { 2480 value 2; 2481 } 2482 enum "delay" { 2483 value 3; 2484 } 2485 enum "probe" { 2486 value 4; 2488 } 2489 enum "invalid" { 2490 value 5; 2491 } 2492 enum "unknown" { 2493 value 6; 2494 } 2495 enum "incomplete" { 2496 value 7; 2497 } 2498 } 2499 } 2500 leaf ipNetToPhysicalRowStatus { // SID 60029 2501 type smiv2:RowStatus; 2502 } // list ipNetToPhysicalEntry 2503 } // container ip 2504 } // module IP-MIB 2506 Authors' Addresses 2508 Michel Veillette (editor) 2509 Trilliant Networks Inc. 2510 610 Rue du Luxembourg 2511 Granby, Quebec J2J 2V2 2512 Canada 2514 Email: michel.veillette@trilliant.com 2516 Peter van der Stok (editor) 2517 consultant 2519 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2520 Email: consultancy@vanderstok.org 2521 URI: www.vanderstok.org 2523 Alexander Pelov 2524 Acklio 2525 2bis rue de la Chataigneraie 2526 Cesson-Sevigne, Bretagne 35510 2527 France 2529 Email: a@ackl.io 2530 Andy Bierman 2531 YumaWorks 2532 685 Cochran St. 2533 Suite #160 2534 Simi Valley, CA 93065 2535 USA 2537 Email: andy@yumaworks.com