idnits 2.17.00 (12 Aug 2021) /tmp/idnits19495/draft-ietf-core-comi-05.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.ietf-core-sid], [I-D.ietf-core-yang-cbor]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. 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 (May 15, 2019) is 1101 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 329 -- Looks like a reference, but probably isn't: '26' on line 330 -- Looks like a reference, but probably isn't: '57' on line 331 == Outdated reference: A later version (-18) exists of draft-ietf-core-sid-06 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-10 == Outdated reference: A later version (-05) exists of draft-veillette-core-yang-library-04 ** 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: 2 errors (**), 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: November 16, 2019 consultant 6 A. Pelov 7 Acklio 8 A. Bierman 9 YumaWorks 10 May 15, 2019 12 CoAP Management Interface 13 draft-ietf-core-comi-05 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. The complete solution composed of CoMI, 24 [I-D.ietf-core-yang-cbor] and [I-D.ietf-core-sid] is called CORECONF. 25 CORECONF extends the set of YANG based protocols, NETCONF and 26 RESTCONF, with the capability to manage constrained devices and 27 networks. 29 Note 31 Discussion and suggestions for improvement are requested, and should 32 be sent to yot@ietf.org. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on November 16, 2019. 50 Copyright Notice 52 Copyright (c) 2019 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5 70 2.1. Major differences between RESTCONF and CoMI . . . . . . . 6 71 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 72 2.3. Instance identifier . . . . . . . . . . . . . . . . . . . 8 73 2.4. Content-Formats . . . . . . . . . . . . . . . . . . . . . 8 74 2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10 75 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11 76 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11 77 4.1. Using the 'k' Uri-Query option . . . . . . . . . . . . . 13 78 4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 14 79 4.2.1. Using the 'c' Uri-Query option . . . . . . . . . . . 14 80 4.2.2. Using the 'd' Uri-Query option . . . . . . . . . . . 15 81 4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16 82 4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 18 83 4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 19 84 4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 19 85 4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 19 86 4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 20 87 4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 21 88 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 22 89 4.4. Full datastore access . . . . . . . . . . . . . . . . . . 23 90 4.4.1. Full datastore examples . . . . . . . . . . . . . . . 23 91 4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 24 92 4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 25 93 4.5.2. The 'f' Uri-Query option . . . . . . . . . . . . . . 26 94 4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27 95 4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 27 97 5. Use of Block . . . . . . . . . . . . . . . . . . . . . . . . 29 98 6. Application Discovery . . . . . . . . . . . . . . . . . . . . 29 99 6.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 29 100 6.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 30 101 6.2.1. Datastore Resource Discovery . . . . . . . . . . . . 30 102 6.2.2. Data node Resource Discovery . . . . . . . . . . . . 30 103 6.2.3. Event stream Resource Discovery . . . . . . . . . . . 31 104 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 31 105 8. Security Considerations . . . . . . . . . . . . . . . . . . . 35 106 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 107 9.1. Resource Type (rt=) Link Target Attribute Values Registry 35 108 9.2. CoAP Content-Formats Registry . . . . . . . . . . . . . . 36 109 9.3. Media Types Registry . . . . . . . . . . . . . . . . . . 36 110 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 38 111 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 112 11.1. Normative References . . . . . . . . . . . . . . . . . . 38 113 11.2. Informative References . . . . . . . . . . . . . . . . . 40 114 Appendix A. ietf-comi YANG module . . . . . . . . . . . . . . . 40 115 Appendix B. ietf-comi .sid file . . . . . . . . . . . . . . . . 46 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49 118 1. Introduction 120 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 121 Machine to Machine (M2M) applications such as smart energy, smart 122 city and building control. Constrained devices need to be managed in 123 an automatic fashion to handle the large quantities of devices that 124 are expected in future installations. Messages between devices need 125 to be as small and infrequent as possible. The implementation 126 complexity and runtime resources need to be as small as possible. 128 This draft describes the CoAP Management Interface which uses CoAP 129 methods to access structured data defined in YANG [RFC7950]. This 130 draft is complementary to [RFC8040] which describes a REST-like 131 interface called RESTCONF, which uses HTTP methods to access 132 structured data defined in YANG. 134 The use of standardized data models specified in a standardized 135 language, such as YANG, promotes interoperability between devices and 136 applications from different manufacturers. 138 CoMI and RESTCONF are intended to work in a stateless client-server 139 fashion. They use a single round-trip to complete a single editing 140 transaction, where NETCONF needs multiple round trips. 142 To promote small messges, CoMI uses a YANG to CBOR mapping 143 [I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid] 144 to minimize CBOR payloads and URI length. 146 1.1. Terminology 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 150 document are to be interpreted as described in [RFC2119]. 152 The following terms are defined in the YANG data modelling language 153 [RFC7950]: action, anydata, anyxml, client, container, data model, 154 data node, identity, instance identifier, leaf, leaf-list, list, 155 module, RPC, schema node, server, submodule. 157 The following terms are defined in [RFC6241]: configuration data, 158 datastore, state data 160 The following term is defined in [I-D.ietf-core-sid]: YANG schema 161 item identifier (SID). 163 The following terms are defined in the CoAP protocol [RFC7252]: 164 Confirmable Message, Content-Format, Endpoint. 166 The following terms are defined in this document: 168 data node resource: a CoAP resource that models a YANG data node. 170 datastore resource: a CoAP resource that models a YANG datastore. 172 event stream resource: a CoAP resource used by clients to observe 173 YANG notifications. 175 notification instance: An instance of a schema node of type 176 notification, specified in a YANG module implemented by the 177 server. The instance is generated in the server at the occurrence 178 of the corresponding event and reported by an event stream. 180 list instance identifier: Handle used to identify a YANG data node 181 that is an instance of a YANG "list" specified with the values of 182 the key leaves of the list. 184 single instance identifier: Handle used to identify a specific data 185 node which can be instantiated only once. This includes data 186 nodes defined at the root of a YANG module and data nodes defined 187 within a container. This excludes data nodes defined within a 188 list or any children of these data nodes. 190 instance-identifier: List instance identifier or single instance 191 identifier. 193 instance-value: The value assigned to a schema node instance. 194 Schema node values are serialized into the payload according to 195 the rules defined in section 4 of [I-D.ietf-core-yang-cbor]. 197 2. CoMI Architecture 199 This section describes the CoMI architecture to use CoAP for reading 200 and modifying the content of datastore(s) used for the management of 201 the instrumented node. 203 +----------------------------------------------------------------+ 204 | SMIv2 specification (2) | 205 +----------------------------------------------------------------+ 206 | 207 V 208 +----------------------------------------------------------------+ 209 | YANG specification (1) | 210 +----------------------------------------------------------------+ 211 | | 212 Client V Server V 213 +----------------+ +-----------------------+ 214 | Request |--> CoAP request(3) -->| Indication | 215 | Confirm |<-- CoAP response(3)<--| Response (4) | 216 | | | | 217 | |<==== Security (7) ===>|+---------------------+| 218 +----------------+ || Datastore(s) (5) || 219 |+---------------------+| 220 |+---------------------+| 221 || Event stream(s) (6) || 222 |+---------------------+| 223 +-----------------------+ 225 Figure 1: Abstract CoMI architecture 227 Figure 1 is a high-level representation of the main elements of the 228 CoMI management architecture. The different numbered components of 229 Figure 1 are discussed according to component number. 231 (1) YANG specification: contains a set of named and versioned 232 modules. 234 (2) SMIv2 specification: A named module specifies a set of variables 235 and "conceptual tables". There is an algorithm to translate SMIv2 236 specifications to YANG specifications. 238 (3) CoAP request/response messages: The CoMI client sends request 239 messages to and receives response messages from the CoMI server. 241 (4) Request, Indication, Response, Confirm: Processes performed by 242 the CoMI clients and servers. 244 (5) Datastore: A resource used to access configuration data, state 245 data, RPCs and actions. A CoMI server may support a single 246 unified datastore or multiple datastores as those defined by 247 Network Management Datastore Architecture (NMDA) [RFC8342]. 249 (6) Event stream: A resource used to get real time notifications. A 250 CoMI server may support multiple Event streams serving different 251 purposes such as normal monitoring, diagnostic, syslog, security 252 monitoring. 254 (7) Security: The server MUST prevent unauthorized users from 255 reading or writing any CoMI resources. CoMI relies on security 256 protocols such as DTLS [RFC6347] to secure CoAP communications. 258 2.1. Major differences between RESTCONF and CoMI 260 CoMI is a RESTful protocol for small devices where saving bytes to 261 transport counts. Contrary to RESTCONF, many design decisions are 262 motivated by the saving of bytes. Consequently, CoMI is not a 263 RESTCONF over CoAP protocol, but differs more significantly from 264 RESTCONF. Some major differences are cited below: 266 o CoMI uses CoAP/UDP as transport protocol and CBOR as payload 267 format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as 268 transport protocol and JSON or XML as payload formats. 270 o CoMI encodes YANG identifier strings as numbers, where RESTCONF 271 does not. 273 o CoMI uses the methods FETCH and iPATCH to access multiple data 274 nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP 275 method GET with the "fields" Query parameter. 277 o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not 278 supported by CoAP. 280 o CoMI does not support "insert" query parameter (first, last, 281 before, after) and the "point" query parameter which are supported 282 by RESTCONF. 284 o CoMI does not support the "start-time" and "stop-time" query 285 parameters to retrieve past notifications. 287 o CoMI does not support the "filter" query parameters to observe a 288 specific set of notifications. 290 o CoMI also differ in the handling of default values, only 'report- 291 all' and 'trip' options are supported. 293 2.2. Compression of YANG identifiers 295 In the YANG specification, items are identified with a name string. 296 In order to significantly reduce the size of identifiers used in 297 CoMI, numeric identifiers are used instead of these strings. YANG 298 Schema Item iDentifier (SID) is defined in [I-D.ietf-core-yang-cbor] 299 section 2.1. 301 When used in a URI, SIDs are encoded in based64 using the URL and 302 Filename safe alphabet as defined by [RFC4648] section 5. The last 6 303 bits encoded is always aligned with the least significant 6 bits of 304 the SID represented using an unsigned integer. 'A' characters (value 305 0) at the start of the resulting string are removed. 307 SID in basae64 = URLsafeChar[SID >> 60 & 0x3F] | 308 URLsafeChar[SID >> 54 & 0x3F] | 309 URLsafeChar[SID >> 48 & 0x3F] | 310 URLsafeChar[SID >> 42 & 0x3F] | 311 URLsafeChar[SID >> 36 & 0x3F] | 312 URLsafeChar[SID >> 30 & 0x3F] | 313 URLsafeChar[SID >> 24 & 0x3F] | 314 URLsafeChar[SID >> 18 & 0x3F] | 315 URLsafeChar[SID >> 12 & 0x3F] | 316 URLsafeChar[SID >> 6 & 0x3F] | 317 URLsafeChar[SID & 0x3F] 319 For example, SID 1721 is encoded as follow. 321 URLsafeChar[1721 >> 60 & 0x3F] = URLsafeChar[0] = 'A' 322 URLsafeChar[1721 >> 54 & 0x3F] = URLsafeChar[0] = 'A' 323 URLsafeChar[1721 >> 48 & 0x3F] = URLsafeChar[0] = 'A' 324 URLsafeChar[1721 >> 42 & 0x3F] = URLsafeChar[0] = 'A' 325 URLsafeChar[1721 >> 36 & 0x3F] = URLsafeChar[0] = 'A' 326 URLsafeChar[1721 >> 30 & 0x3F] = URLsafeChar[0] = 'A' 327 URLsafeChar[1721 >> 24 & 0x3F] = URLsafeChar[0] = 'A' 328 URLsafeChar[1721 >> 18 & 0x3F] = URLsafeChar[0] = 'A' 329 URLsafeChar[1721 >> 12 & 0x3F] = URLsafeChar[0] = 'A' 330 URLsafeChar[1721 >> 6 & 0x3F] = URLsafeChar[26] = 'a' 331 URLsafeChar[1721 & 0x3F] = URLsafeChar[57] = '5' 333 The resulting base64 representation of SID 1721 is "a5" 335 2.3. Instance identifier 337 Instance identifiers are used to uniquely identify data node 338 instances within a datastore. This YANG built-in type is defined in 339 [RFC7950] section 9.13. An instance identifier is composed of the 340 data node identifier (i.e. a SID) and for data nodes within list(s) 341 the keys used to index within these list(s). 343 When part of a payload, instance identifiers are encoded in CBOR 344 based on the rules defined in [I-D.ietf-core-yang-cbor] section 345 6.13.1. When part of a URI, the SID is appended to the URI of the 346 targeted datastore, the keys are specified using the 'k' URI-Query as 347 defined in Section 4.1. 349 2.4. Content-Formats 351 ComI uses Content-Formats based on the YANG to CBOR mapping specified 352 in [I-D.ietf-core-yang-cbor]. 354 The following Content-formats are defined: 356 application/yang-data+cbor: This Content-Format represents a CBOR 357 YANG document containing one or multiple data node values. Each 358 data node is identified by its associated SID. 360 FORMAT: CBOR map of SID, instance-value 362 The message payload of Content-Format 'application/yang-data+cbor' 363 is encoded using a CBOR map. Each entry of this CBOR map is 364 composed of a key and a value. CBOR map keys are set to the SID 365 assigned to the data nodes, CBOR map values are set to the 366 instance value as defined in [I-D.ietf-core-yang-cbor] section 4. 368 application/yang-identifiers+cbor: This Content-Format represents a 369 CBOR YANG document containing a list of instance identifier used 370 to target specific data node instances within a datastore. 372 FORMAT: CBOR array of instance-identifier 374 The message payload of Content-Format 'application/yang- 375 identifiers+cbor' is encoded using a CBOR array. Each entry of 376 this CBOR array contain an instance identifier encoded as defined 377 in [I-D.ietf-core-yang-cbor] section 6.13.1. 379 application/yang-instances+cbor: This Content-Format represents a 380 CBOR YANG document containing a list of data node instances. Each 381 data node instance is identified by its associated instance 382 identifier. 384 FORMAT: CBOR array of CBOR map of instance-identifier, instance- 385 value 387 The message payload of Content-Format 'application/yang- 388 instances+cbor' is encoded using a CBOR array. Each entry within 389 this CBOR array contains a CBOR map carrying an instance 390 identifier and associated instance value. Instance identifiers 391 are encoded using the rules defined in [I-D.ietf-core-yang-cbor] 392 section 6.13.1, values are encoded using the rules defined in 393 [I-D.ietf-core-yang-cbor] section 4. 395 When present in an iPATCH request payload, this Content-Format 396 carry a list of data node instances to be replaced, created, or 397 deleted. For each data node instance D, for which the instance 398 identifier is the same as a data node instance I, in the targeted 399 datastore resource: the value of D replaces the value of I. When 400 the value of D is null, the data node instance I is removed. When 401 the targeted datastore resource does not contain a data node 402 instance with the same instance identifier as D, a new instance is 403 created with the same instance identifier and value as D. 405 The different Content-format usages are summarized in the table 406 below: 408 +---------------+--------------+------------------------------------+ 409 | Method | Resource | Content-Format | 410 +---------------+--------------+------------------------------------+ 411 | GET response | data node | /application/yang-data+cbor | 412 | | | | 413 | PUT request | data node | /application/yang-data+cbor | 414 | | | | 415 | POST request | data node | /application/yang-data+cbor | 416 | | | | 417 | DELETE | data node | n/a | 418 | | | | 419 | GET response | datastore | /application/yang-data+cbor | 420 | | | | 421 | PUT request | datastore | /application/yang-data+cbor | 422 | | | | 423 | POST request | datastore | /application/yang-data+cbor | 424 | | | | 425 | FETCH request | datastore | /application/yang-identifiers+cbor | 426 | | | | 427 | FETCH | datastore | /application/yang-instances+cbor | 428 | response | | | 429 | | | | 430 | iPATCH | datastore | /application/yang-instances+cbor | 431 | request | | | 432 | | | | 433 | GET response | event stream | /application/yang-instances+cbor | 434 | | | | 435 | POST request | rpc, action | /application/yang-data+cbor | 436 | | | | 437 | POST response | rpc, action | /application/yang-data+cbor | 438 +---------------+--------------+------------------------------------+ 440 2.5. Unified datastore 442 CoMI supports a simple datastore model consisting of a single unified 443 datastore. This datasore provides access to both configuration and 444 operational data. Configuration updates performed on this datastore 445 are reflected immediately or with a minimal delay as operational 446 data. 448 Alternatively, CoMI servers MAY implement a more complex datastore 449 model such as the Network Management Datastore Architecture (NMDA) as 450 defined by [RFC8342]. Each datastore supported is implemented as a 451 datastore resource. 453 Characteristics of the unified datastore are summarized in the table 454 below: 456 +-------------+-----------------------------------------------------+ 457 | Name | Value | 458 +-------------+-----------------------------------------------------+ 459 | Name | unified | 460 | | | 461 | YANG | all modules | 462 | modules | | 463 | | | 464 | YANG nodes | all data nodes ("config true" and "config false") | 465 | | | 466 | Access | read-write | 467 | | | 468 | How applied | changes applied in place immediately or with a | 469 | | minimal delay | 470 | | | 471 | Protocols | CORECONF | 472 | | | 473 | Defined in | "ietf-comi" | 474 +-------------+-----------------------------------------------------+ 476 3. Example syntax 478 CBOR is used to encode CoMI request and response payloads. The CBOR 479 syntax of the YANG payloads is specified in [RFC7049]. The payload 480 examples are notated in Diagnostic notation (defined in section 6 of 481 [RFC7049]) that can be automatically converted to CBOR. 483 SIDs in URIs are represented as a base64 number, SIDs in the payload 484 are represented as decimal numbers. 486 4. CoAP Interface 488 This note specifies a Management Interface. CoAP endpoints that 489 implement the CoMI management protocol, support at least one 490 discoverable management resource of resource type (rt): core.c.ds, 491 with example path: /c, where c is short-hand for CoMI. The path /c 492 is recommended, but not compulsory (see Section 6). 494 The mapping of YANG data node instances to CoMI resources is as 495 follows. Every data node of the YANG modules loaded in the CoMI 496 server represents a sub-resource of the datastore resource (e.g. /c/ 497 sid). When multiple instances of a list exist, instance selection is 498 possible as described in Section 4.1, Section 4.2.3.1, and 499 Section 4.2.4. 501 CoMI also supports event stream resourced used to observe 502 notification instances. Event stream resources can be discovered 503 using resource type (rt): core.c.ev. 505 The description of the CoMI management interface is shown in the 506 table below: 508 +-------------+------------------+-----------+ 509 | Function | Recommended path | rt | 510 +-------------+------------------+-----------+ 511 | Datastore | /c | core.c.ds | 512 | | | | 513 | Data node | /c/SID | core.c.dn | 514 | | | | 515 | Event steam | /s | core.c.ev | 516 +-------------+------------------+-----------+ 518 The path values are example values. On discovery, the server makes 519 the actual path values known for these resources. 521 The methods used by CoMI are: 523 +-----------+-------------------------------------------------------+ 524 | Operation | Description | 525 +-----------+-------------------------------------------------------+ 526 | GET | Retrieve the datastore resource or a data node | 527 | | resource | 528 | | | 529 | FETCH | Retrieve specific data nodes within a datastore | 530 | | resource | 531 | | | 532 | POST | Create a datastore resource or a data node resource, | 533 | | invoke an RPC or action | 534 | | | 535 | PUT | Create or replace a datastore resource or a data node | 536 | | resource | 537 | | | 538 | iPATCH | Idem-potently create, replace, and delete data node | 539 | | resource(s) within a datastore resource | 540 | | | 541 | DELETE | Delete a datastore resource or a data node resource | 542 +-----------+-------------------------------------------------------+ 544 There is one Uri-Query option for the GET, PUT, POST, and DELETE 545 methods. 547 +------------------+----------------------------------------+ 548 | Uri-Query option | Description | 549 +------------------+----------------------------------------+ 550 | k | Select an instance within YANG list(s) | 551 +------------------+----------------------------------------+ 552 This parameter is not used for FETCH and iPATCH, because their 553 request payloads support list instance selection. 555 4.1. Using the 'k' Uri-Query option 557 The "k" (key) parameter specifies a specific instance of a data node. 558 The SID in the URI is followed by the (?k=key1,key2,...). Where SID 559 identifies a data node, and key1, key2 are the values of the key 560 leaves that specify an instance. Lists can have multiple keys, and 561 lists can be part of lists. The order of key value generation is 562 given recursively by: 564 o For a given list, if a parent data node is a list, generate the 565 keys for the parent list first. 567 o For a given list, generate key values in the order specified in 568 the YANG module. 570 Key values are encoded using the rules defined in the following 571 table. 573 +-----------------------------+--------------------------------+ 574 | YANG datatype | Uri-Query text content | 575 +-----------------------------+--------------------------------+ 576 | uint8,uint16,unit32, uint64 | int2str(key) | 577 | | | 578 | int8, int16,int32, int64 | urlSafeBase64(CBORencode(key)) | 579 | | | 580 | decimal64 | urlSafeBase64(CBOR key) | 581 | | | 582 | string | key | 583 | | | 584 | boolean | "0" or "1" | 585 | | | 586 | enumeration | int2str(key) | 587 | | | 588 | bits | urlSafeBase64(CBORencode(key)) | 589 | | | 590 | binary | urlSafeBase64(key) | 591 | | | 592 | identityref | int2str(key) | 593 | | | 594 | union | urlSafeBase64(CBORencode(key)) | 595 | | | 596 | instance-identifier | urlSafeBase64(CBORencode(key)) | 597 +-----------------------------+--------------------------------+ 599 In this table: 601 o The method int2str() is used to convert an integer value to a 602 string. For example, int2str(0x0123) return the string "291". 604 o The method urlSafeBase64() is used to convert a binary string to 605 base64 using the URL and Filename safe alphabet as defined by 606 [RFC4648] section 5. For example, urlSafeBase64(\xF9\x56\xA1\x3C) 607 return the string "-VahPA". 609 o The method CBORencode() is used to convert a YANG value to CBOR as 610 specified in [I-D.ietf-core-yang-cbor] section 6. 612 The resulting key string is encoded in a Uri-Query as specified in 613 [RFC7252] section 6.5. 615 4.2. Data Retrieval 617 One or more data nodes can be retrieved by the client. The operation 618 is mapped to the GET method defined in section 5.8.1 of [RFC7252] and 619 to the FETCH method defined in section 2 of [RFC8132]. 621 There are two additional Uri-Query options for the GET and FETCH 622 methods. 624 +-------------+-----------------------------------------------------+ 625 | Uri-Query | Description | 626 | option | | 627 +-------------+-----------------------------------------------------+ 628 | c | Control selection of configuration and non- | 629 | | configuration data nodes (GET and FETCH) | 630 | | | 631 | d | Control retrieval of default values. | 632 +-------------+-----------------------------------------------------+ 634 4.2.1. Using the 'c' Uri-Query option 636 The 'c' (content) option controls how descendant nodes of the 637 requested data nodes will be processed in the reply. 639 The allowed values are: 641 +-------+-----------------------------------------------------+ 642 | Value | Description | 643 +-------+-----------------------------------------------------+ 644 | c | Return only configuration descendant data nodes | 645 | | | 646 | n | Return only non-configuration descendant data nodes | 647 | | | 648 | a | Return all descendant data nodes | 649 +-------+-----------------------------------------------------+ 651 This option is only allowed for GET and FETCH methods on datastore 652 and data node resources. A 4.02 (Bad Option) error is returned if 653 used for other methods or resource types. 655 If this Uri-Query option is not present, the default value is "a". 657 4.2.2. Using the 'd' Uri-Query option 659 The "d" (with-defaults) option controls how the default values of the 660 descendant nodes of the requested data nodes will be processed. 662 The allowed values are: 664 +-------+-----------------------------------------------------------+ 665 | Value | Description | 666 +-------+-----------------------------------------------------------+ 667 | a | All data nodes are reported. Defined as 'report-all' in | 668 | | section 3.1 of [RFC6243]. | 669 | | | 670 | t | Data nodes set to the YANG default are not reported. | 671 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 672 +-------+-----------------------------------------------------------+ 674 If the target of a GET or FETCH method is a data node that represents 675 a leaf that has a default value, and the leaf has not been given a 676 value by any client yet, the server MUST return the default value of 677 the leaf. 679 If the target of a GET method is a data node that represents a 680 container or list that has child resources with default values, and 681 these have not been given value yet, 683 The server MUST not return the child resource if d= 't' 685 The server MUST return the child resource if d= 'a'. 687 If this Uri-Query option is not present, the default value is 't'. 689 4.2.3. GET 691 A request to read the values of a data node instance is sent with a 692 CoAP GET message. An instance identifier is specified in the URI 693 path prefixed with the example path /c. 695 FORMAT: 696 GET /c/instance-identifier 698 2.05 Content (Content-Format: application/yang-data+cbor) 699 CBOR map of SID, instance-value 701 The returned payload contains the CBOR encoding of the specified data 702 node instance value. 704 4.2.3.1. GET Examples 706 Using for example the current-datetime leaf from module ietf-system 707 [RFC7317], a request is sent to retrieve the value of 'system- 708 state/clock/current-datetime' specified in container system-state. 709 The SID of 'system-state/clock/current-datetime' is 1723, encoded in 710 base64 according to Section 2.2, yields a7. The response to the 711 request returns the CBOR map with the key set to the SID of the 712 requested data node (i.e. 1723) and the value encoded using a 'text 713 string' as defined in [I-D.ietf-core-yang-cbor] section 6.4. 715 REQ: GET example.com/c/a7 717 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 718 { 719 1723 : "2014-10-26T12:16:31Z" 720 } 722 The next example represents the retrieval of a YANG container. In 723 this case, the CoMI client performs a GET request on the clock 724 container (SID = 1721; base64: a5). The container returned is 725 encoded using a CBOR map as specified by [I-D.ietf-core-yang-cbor] 726 section 4.2. 728 REQ: GET example.com/c/a5 730 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 731 { 732 1721 : { 733 +2 : "2014-10-26T12:16:51Z", / current-datetime SID 1723 / 734 +1 : "2014-10-21T03:00:00Z" / boot-datetime SID 1722 / 735 } 736 } 737 This example shows the retrieval of the /interfaces/interface YANG 738 list accessed using SID 1533 (base64: X9). The return payload is 739 encoded using a CBOR array as specified by [I-D.ietf-core-yang-cbor] 740 section 4.4.1 containing 2 instances. 742 REQ: GET example.com/c/X9 744 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 745 { 746 1533 : [ 747 { 748 +4 : "eth0", / name (SID 1537) / 749 +1 : "Ethernet adaptor", / description (SID 1534) / 750 +5 : 1880, / type, (SID 1538) identity / 751 / ethernetCsmacd (SID 1880) / 752 +2 : true / enabled ( SID 1535) / 753 }, 754 { 755 +4 : "eth1", / name (SID 1537) / 756 +1 : "Ethernet adaptor", / description (SID 1534) / 757 +5 : 1880, / type, (SID 1538) identity / 758 / ethernetCsmacd (SID 1880) / 759 +2 : false / enabled ( SID 1535) / 760 } 761 ] 762 } 764 To retrieve a specific instance within the /interfaces/interface YANG 765 list, the CoMI client adds the key of the targeted instance in its 766 CoAP request using the 'k' URI-Query. The return payload containing 767 the instance requested is encoded using a CBOR array as specified by 768 [I-D.ietf-core-yang-cbor] section 4.4.1. 770 REQ: GET example.com/c/X9?k="eth0" 772 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 773 { 774 1533 : [ 775 { 776 +4 : "eth0", / name (SID 1537) / 777 +1 : "Ethernet adaptor", / description (SID 1534) / 778 +5 : 1880, / type, (SID 1538) identity / 779 / ethernetCsmacd (SID 1880) / 780 +2 : true / enabled ( SID 1535) / 781 } 782 ] 783 } 784 It is equally possible to select a leaf of a specific instance of a 785 list. The example below requests the description leaf (SID=1534, 786 base64: X-) within the interface list corresponding to the interface 787 name "eth0". The returned value is encoded in CBOR based on the 788 rules specified by [I-D.ietf-core-yang-cbor] section 6.4. 790 REQ: GET example.com/c/X-?k="eth0" 792 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 793 { 794 1534 : "Ethernet adaptor" 795 } 797 4.2.4. FETCH 799 The FETCH is used to retrieve multiple data node instance values. 800 The FETCH request payload contains the list of instance identifier of 801 the data node instances requested. 803 The return response payload contains a list of data node instance 804 values in the same order as requested. A CBOR null is returned for 805 each data node requested by the client, not supported by the server 806 or not currently instantiated. 808 For compactness, indexes of the list instance identifiers returned by 809 the FETCH response SHOULD be elided, only the SID is provided. In 810 this case, the format of each entry within the CBOR array of the 811 FETCH response is identical to the format as a GET response. 813 FORMAT: 814 FETCH /c (Content-Format: application/yang-identifiers+cbor) 815 CBOR array of instance-identifier 817 2.05 Content (Content-Format: application/yang-instances+cbor) 818 CBOR array of CBOR map of instance-identifier, instance-value 820 4.2.4.1. FETCH examples 822 This example uses the current-datetime leaf from module ietf-system 823 [RFC7317] and the interface list from module ietf-interfaces 824 [RFC7223]. In this example the value of current-datetime (SID 1723) 825 and the interface list (SID 1533) instance identified with 826 name="eth0" are queried. 828 REQ: FETCH /c (Content-Format: application/yang-identifiers+cbor) 829 [ 830 1723, / current-datetime (SID 1723) / 831 [1533, "eth0"] / interface (SID 1533) with name = "eth0" / 832 ] 834 RES: 2.05 Content (Content-Format: application/yang-instances+cbor) 835 [ 836 { 837 1723 : "2014-10-26T12:16:31Z" / current-datetime (SID 1723) / 838 }, 839 { 840 1533 : { 841 +4 : "eth0", / name (SID 1537) / 842 +1 : "Ethernet adaptor", / description (SID 1534) / 843 +5 : 1880, / type (SID 1538), identity / 844 / ethernetCsmacd (SID 1880) / 845 +2 : true / enabled (SID 1535) / 846 } 847 } 848 ] 850 4.3. Data Editing 852 CoMI allows datastore contents to be created, modified and deleted 853 using CoAP methods. 855 4.3.1. Data Ordering 857 A CoMI server SHOULD preserve the relative order of all user-ordered 858 list and leaf-list entries that are received in a single edit 859 request. These YANG data node types are encoded as CBOR arrays so 860 messages will preserve their order. 862 4.3.2. POST 864 The CoAP POST operation is used in CoMI for creation of data node 865 resources and the invocation of "ACTION" and "RPC" resources. Refer 866 to Section 4.6 for details on "ACTION" and "RPC" resources. 868 A request to create a data node resource is sent with a CoAP POST 869 message. The URI specifies the data node to be instantiated at the 870 exception of list instances. In this case, for compactness, the URI 871 specifies the list for which an instance is created. 873 FORMAT: 874 POST /c/ 875 (Content-Format :application/yang-data+cbor) 876 CBOR map of SID, instance-value 878 2.01 Created 880 If the data node resource already exists, then the POST request MUST 881 fail and a "4.09 Conflict" response code MUST be returned 883 4.3.2.1. Post example 885 The example uses the interface list from module ietf-interfaces 886 [RFC7223]. This example creates a new list instance within the 887 interface list (SID = 1533): 889 REQ: POST /c/X9 (Content-Format: application/yang-data+cbor) 890 { 891 1533 : [ 892 { 893 +4 : "eth5", / name (SID 1537) / 894 +1 : "Ethernet adaptor", / description (SID 1534) / 895 +5 : 1880, / type (SID 1538), identity / 896 / ethernetCsmacd (SID 1880) / 897 +2 : true / enabled (SID 1535) / 898 } 899 ] 900 } 902 RES: 2.01 Created 904 4.3.3. PUT 906 A data node resource instance is created or replaced with the PUT 907 method. A request to set the value of a data node instance is sent 908 with a CoAP PUT message. 910 FORMAT: 911 PUT /c/ 912 (Content-Format :application/yang-data+cbor) 913 CBOR map of SID, instance-value 915 2.01 Created 917 4.3.3.1. PUT example 919 The example uses the interface list from module ietf-interfaces 920 [RFC7223]. Example updates the instance of the list interface (SID = 921 1533) with key name="eth0": 923 REQ: PUT /c/X9?k="eth0" (Content-Format: application/yang-data+cbor) 924 { 925 1533 : [ 926 { 927 +4 : "eth0", / name (SID 1537) / 928 +1 : "Ethernet adaptor", / description (SID 1534) / 929 +5 : 1880, / type (SID 1538), identity / 930 / ethernetCsmacd (SID 1880) / 931 +2 : true / enabled (SID 1535) / 932 } 933 ] 934 } 936 RES: 2.04 Changed 938 4.3.4. iPATCH 940 One or multiple data node instances are replaced with the idempotent 941 CoAP iPATCH method [RFC8132]. 943 There are no Uri-Query options for the iPATCH method. 945 The processing of the iPATCH command is specified by Content-Format 946 'application/yang-instances+cbor'. In summary, if the CBOR patch 947 payload contains a data node instance that is not present in the 948 target, this instance is added. If the target contains the specified 949 instance, the content of this instance is replaced with the value of 950 the payload. A null value indicates the removal of an existing data 951 node instance. 953 FORMAT: 954 iPATCH /c (Content-Format: application/yang-instances+cbor) 955 CBOR array of CBOR map of instance-identifier, instance-value 957 2.04 Changed 959 4.3.4.1. iPATCH example 961 In this example, a CoMI client requests the following operations: 963 o Set "/system/ntp/enabled" (SID 1755) to true. 965 o Remove the server "tac.nrc.ca" from the"/system/ntp/server" (SID 966 1756) list. 968 o Add/set the server "NTP Pool server 2" to the list "/system/ntp/ 969 server" (SID 1756). 971 REQ: iPATCH /c (Content-Format: application/yang-instances+cbor) 972 [ 973 { 974 1755 : true / enabled (SID 1755) / 975 }, 976 { 977 [1756, "tac.nrc.ca"] : null / server (SID 1756) / 978 }, 979 { 980 1756 : { / server (SID 1756) / 981 +3 : "tic.nrc.ca", / name (SID 1759) / 982 +4 : true, / prefer (SID 1760) / 983 +5 : { / udp (SID 1761) / 984 +1 : "132.246.11.231" / address (SID 1762) / 985 } 986 } 987 } 988 ] 990 RES: 2.04 Changed 992 4.3.5. DELETE 994 A data node resource is deleted with the DELETE method. 996 FORMAT: 997 Delete /c/ 999 2.02 Deleted 1001 4.3.5.1. DELETE example 1003 This example uses the interface list from module ietf-interfaces 1004 [RFC7223]. This example deletes an instance of the interface list 1005 (SID = 1533): 1007 REQ: DELETE /c/X9?k="eth0" 1009 RES: 2.02 Deleted 1011 4.4. Full datastore access 1013 The methods GET, PUT, POST, and DELETE can be used to request, 1014 replace, create, and delete a whole datastore respectively. 1016 FORMAT: 1017 GET /c 1019 2.05 Content (Content-Format: application/yang-data+cbor) 1020 CBOR map of SID, instance-value 1022 FORMAT: 1023 PUT /c (Content-Format: application/yang-data+cbor) 1024 CBOR map of SID, instance-value 1026 2.04 Changed 1028 FORMAT: 1029 POST /c (Content-Format: application/yang-data+cbor) 1030 CBOR map of SID, instance-value 1032 2.01 Created 1034 FORMAT: 1035 DELETE /c 1037 2.02 Deleted 1039 The content of the CBOR map represents the complete datastore of the 1040 server at the GET indication of after a successful processing of a 1041 PUT or POST request. 1043 4.4.1. Full datastore examples 1045 The example uses the interface list from module ietf-interfaces 1046 [RFC7223] and the clock container from module ietf-system [RFC7317]. 1047 We assume that the datastore contains two modules ietf-system (SID 1048 1700) and ietf-interfaces (SID 1500); they contain the 'interface' 1049 list (SID 1533) with one instance and the 'clock' container (SID 1050 1721). After invocation of GET, a CBOR map with data nodes from 1051 these two modules is returned: 1053 REQ: GET /c 1055 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 1056 { 1057 1721 : { / Clock (SID 1721) / 1058 +2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) / 1059 +1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) / 1060 }, 1061 1533 : [ 1062 { / interface (SID 1533) / 1063 +4 : "eth0", / name (SID 1537) / 1064 +1 : "Ethernet adaptor", / description (SID 1534) / 1065 +5 : 1880, / type (SID 1538), identity: / 1066 / ethernetCsmacd (SID 1880) / 1067 +2 : true / enabled (SID 1535) / 1068 } 1069 ] 1070 } 1072 4.5. Event stream 1074 Event notification is an essential function for the management of 1075 servers. CoMI allows notifications specified in YANG [RFC5277] to be 1076 reported to a list of clients. The recommended path of the default 1077 event stream is /s. The server MAY support additional event stream 1078 resources to address different notification needs. 1080 Reception of notification instances is enabled with the CoAP Observe 1081 [RFC7641] function. Clients subscribe to the notifications by 1082 sending a GET request with an "Observe" option, specifying the /s 1083 resource when the default stream is selected. 1085 Each response payload carries one or multiple notifications. The 1086 number of notifications reported, and the conditions used to remove 1087 notifications from the reported list is left to implementers. When 1088 multiple notifications are reported, they MUST be ordered starting 1089 from the newest notification at index zero. 1091 The format of notification contents is defined in 1092 [I-D.ietf-core-yang-cbor] section 4.2.1. For notification without 1093 any content, a null value is returned. 1095 An example implementation is: 1097 Every time an event is generated, the generated notification 1098 instance is appended to the chosen stream(s). After an 1099 aggregation period, which may be adjusted using an exclusion delay 1100 and limited by the maximum number of notifications supported, the 1101 content of the instance is sent to all clients observing the 1102 modified stream. 1104 FORMAT: 1105 GET / Observe(0) 1107 2.05 Content (Content-Format :application/yang-instances+cbor) 1108 CBOR array of CBOR map of instance-identifier, instance-value 1110 The array of data node instances may contain identical entries which 1111 have been generated at different times. 1113 4.5.1. Notify Examples 1115 Let suppose the server generates the example-port-fault event as 1116 defined below. 1118 module example-port { 1119 ... 1120 notification example-port-fault { // SID 60010 1121 description 1122 "Event generated if a hardware fault is detected"; 1123 leaf port-name { // SID 60011 1124 type string; 1125 } 1126 leaf port-fault { // SID 60012 1127 type string; 1128 } 1129 } 1130 } 1132 By executing a GET on the /s resource the client receives the 1133 following 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.5.2. The 'f' Uri-Query option 1165 The 'f' (filter) option is used to indicate which subset of all 1166 possible notifications is of interest. If not present, all events 1167 notifications supported by the event stream are reported. 1169 When not supported by a CoMI server, this option shall be ignored, 1170 all events notifications are reported independently of the presence 1171 and content of the 'f' (filter) option. 1173 When present, this option contains a comma separated list of 1174 notification SIDs. For example, the following request returns 1175 notifications 60010 and 60020. 1177 REQ: GET /s?f=60010,60020 Observe(0) Token(0x241) 1179 4.6. RPC statements 1181 The YANG "action" and "RPC" statements specify the execution of a 1182 Remote procedure Call (RPC) in the server. It is invoked using a 1183 POST method to an "Action" or "RPC" resource instance. 1185 The request payload contains the values assigned to the input 1186 container when specified. The response payload contains the values 1187 of the output container when specified. Both the input and output 1188 containers are encoded in CBOR using the rules defined in 1189 [I-D.ietf-core-yang-cbor] section 4.2.1. 1191 The returned success response code is 2.05 Content. 1193 FORMAT: 1194 POST /c/ 1195 (Content-Format :application/yang-data+cbor) 1196 CBOR map of SID, instance-value 1198 2.05 Content (Content-Format :application/yang-data+cbor) 1199 CBOR map of SID, instance-value 1201 4.6.1. RPC Example 1203 The example is based on the YANG action reset as defined in [RFC7950] 1204 section 7.15.3 and annotated below with SIDs. 1206 module example-server-farm { 1207 yang-version 1.1; 1208 namespace "urn:example:server-farm"; 1209 prefix "sfarm"; 1211 import ietf-yang-types { 1212 prefix "yang"; 1213 } 1215 list server { // SID 60000 1216 key name; 1217 leaf name { // SID 60001 1218 type string; 1219 } 1220 action reset { // SID 60002 1221 input { 1222 leaf reset-at { // SID 60003 1223 type yang:date-and-time; 1224 mandatory true; 1225 } 1226 } 1227 output { 1228 leaf reset-finished-at { // SID 60004 1229 type yang:date-and-time; 1230 mandatory true; 1231 } 1232 } 1233 } 1234 } 1235 } 1237 This example invokes the 'reset' action (SID 60002, base64: Opq), of 1238 the server instance with name equal to "myserver". 1240 REQ: POST /c/Opq?k="myserver" 1241 (Content-Format :application/yang-data+cbor) 1242 { 1243 60002 : { 1244 +1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / 1245 } 1246 } 1248 RES: 2.05 Content (Content-Format :application/yang-data+cbor) 1249 { 1250 60002 : { 1251 +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ 1252 } 1253 } 1255 5. Use of Block 1257 The CoAP protocol provides reliability by acknowledging the UDP 1258 datagrams. However, when large pieces of data need to be 1259 transported, datagrams get fragmented, thus creating constraints on 1260 the resources in the client, server and intermediate routers. The 1261 block option [RFC7959] allows the transport of the total payload in 1262 individual blocks of which the size can be adapted to the underlying 1263 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1264 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1265 acknowledged to guarantee reliability. 1267 Notice that the Block mechanism splits the data at fixed positions, 1268 such that individual data fields may become fragmented. Therefore, 1269 assembly of multiple blocks may be required to process the complete 1270 data field. 1272 Beware of race conditions. Blocks are filled one at a time and care 1273 should be taken that the whole data representation is sent in 1274 multiple blocks sequentially without interruption. On the server, 1275 values are changed, lists are re-ordered, extended or reduced. When 1276 these actions happen during the serialization of the contents of the 1277 resource, the transported results do not correspond with a state 1278 having occurred in the server; or worse the returned values are 1279 inconsistent. For example: array length does not correspond with the 1280 actual number of items. It may be advisable to use Indefinite-length 1281 CBOR arrays and maps, which are foreseen for data streaming purposes. 1283 6. Application Discovery 1285 Two application discovery mechanisms are supported by CoMI, the YANG 1286 library data model as defined by [I-D.veillette-core-yang-library] 1287 and the CORE resource discovery [RFC6690]. Implementers may choose 1288 to implement one or the other or both. 1290 6.1. YANG library 1292 The YANG library data model [I-D.veillette-core-yang-library] 1293 provides a high level description of the resources available. The 1294 YANG library contains the list of modules, features and deviations 1295 supported by the CoMI server. From this information, CoMI clients 1296 can infer the list of data nodes supported and the interaction model 1297 to be used to access them. This module also contains the list of 1298 datastores implemented. 1300 The location of the YANG library can be found by sending a GET 1301 request to "/.well-known/core" including a resource type (RT) 1302 parameter with the value "core.c.yl". Upon success, the return 1303 payload will contain the root resource of the YANG library module. 1305 REQ: GET /.well-known/core?rt=core.c.yl 1307 RES: 2.05 Content (Content-Format: application/link-format) 1308 ;rt="core.c.yl" 1310 6.2. Resource Discovery 1312 Even if the YANG library provides all the information needed for 1313 application discovery, the implementation of Resource discovery as 1314 defined by [RFC6690] can be desirable for a seamless integration with 1315 other CoAP interfaces and services. 1317 6.2.1. Datastore Resource Discovery 1319 The presence and location of (path to) each datastore implemented by 1320 the CoMI server can be discovered by sending a GET request to 1321 "/.well-known/core" including a resource type (RT) parameter with the 1322 value "core.c.ds". 1324 Upon success, the return payload contains the list of datastore 1325 resources. 1327 Each datastore returned is further qualified using the "ds" Link- 1328 Format attribute. This attribute is set to the SID assigned to the 1329 datastore identity. When a unified datastore is implemented, the ds 1330 attribute is set to 1029. For other examples of datastores, see the 1331 Network Management Datastore Architecture (NMDA) [RFC7950]. 1333 link-extension = ( "ds" "=" sid ) ) 1334 ; SID assigned to the datastore identity 1335 sid = 1*DIGIT 1337 For example: 1339 REQ: GET /.well-known/core?rt=core.c.ds 1341 RES: 2.05 Content (Content-Format: application/link-format) 1342 ; rt="core.c.ds";ds= 1029 1344 6.2.2. Data node Resource Discovery 1346 The presence and location of (path to) each data node implemented by 1347 the CoMI server are discovered by sending a GET request to "/.well- 1348 known/core" including a resource type (RT) parameter with the value 1349 "core.c.dn". 1351 Upon success, the return payload contains the SID assigned to each 1352 data node and their location. 1354 The example below shows the discovery of the presence and location of 1355 data nodes. Data nodes '/ietf-system:system-state/clock/boot- 1356 datetime' (SID 1722) and '/ietf-system:system-state/clock/current- 1357 datetime' (SID 1723) are returned. 1359 REQ: GET /.well-known/core?rt=core.c.dn 1361 RES: 2.05 Content (Content-Format: application/link-format) 1362 ;rt="core.c.dn", 1363 ;rt="core.c.dn" 1365 The list of data nodes may become prohibitively long. 1366 Implementations MAY return a subset of this list or can rely solely 1367 on the YANG library. 1369 6.2.3. Event stream Resource Discovery 1371 The presence and location of (path to) each event stream implemented 1372 by the CoMI server are discovered by sending a GET request to 1373 "/.well-known/core" including a resource type (RT) parameter with the 1374 value "core.c.es". 1376 Upon success, the return payload contains the list of event stream 1377 resources. 1379 For example: 1381 REQ: GET /.well-known/core?rt=core.c.es 1383 RES: 2.05 Content (Content-Format: application/link-format) 1384 ;rt="core.c.es" 1386 7. Error Handling 1388 In case a request is received which cannot be processed properly, the 1389 CoMI server MUST return an error message. This error message MUST 1390 contain a CoAP 4.xx or 5.xx response code. 1392 Errors returned by a CoMI server can be broken into two categories, 1393 those associated to the CoAP protocol itself and those generated 1394 during the validation of the YANG data model constrains as described 1395 in [RFC7950] section 8. 1397 The following list of common CoAP errors should be implemented by 1398 CoMI servers. This list is not exhaustive, other errors defined by 1399 CoAP and associated RFCs may be applicable. 1401 o Error 4.01 (Unauthorized) is returned by the CoMI server when the 1402 CoMI client is not authorized to perform the requested action on 1403 the targeted resource (i.e. data node, datastore, rpc, action or 1404 event stream). 1406 o Error 4.02 (Bad Option) is returned by the CoMI server when one or 1407 more CoAP options are unknown or malformed. 1409 o Error 4.04 (Not Found) is returned by the CoMI server when the 1410 CoMI client is requesting a non-instantiated resource (i.e. data 1411 node, datastore, rpc, action or event stream). 1413 o Error 4.05 (Method Not Allowed) is returned by the CoMI server 1414 when the CoMI client is requesting a method not supported on the 1415 targeted resource. (e.g. GET on an rpc, PUT or POST on a data 1416 node with "config" set to false). 1418 o Error 4.08 (Request Entity Incomplete) is returned by the CoMI 1419 server if one or multiple blocks of a block transfer request is 1420 missing, see [RFC7959] for more details. 1422 o Error 4.13 (Request Entity Too Large) may be returned by the CoMI 1423 server during a block transfer request, see [RFC7959] for more 1424 details. 1426 o Error 4.15 (Unsupported Content-Format) is returned by the CoMI 1427 server when the Content-Format used in the request don't match 1428 those specified in section Section 2.4. 1430 CoMI server MUST also enforce the different constraints associated to 1431 the YANG data models implemented. These constraints are described in 1432 [RFC7950] section 8. These errors are reported using the CoAP error 1433 code 4.00 (Bad Request) and may have the following error container as 1434 payload. The YANG definition and associated .sid file are available 1435 in Appendix A and Appendix B. The error container is encoded using 1436 the encoding rules of a YANG data template as defined in 1437 [I-D.ietf-core-yang-cbor] section 5. 1439 +--rw error! 1440 +--rw error-tag identityref 1441 +--rw error-app-tag? identityref 1442 +--rw error-data-node? instance-identifier 1443 +--rw error-message? string 1445 The following 'error-tag' and 'error-app-tag' are defined by the 1446 ietf-comi YANG module, these tags are implemented as YANG identity 1447 and can be extended as needed. 1449 o error-tag 'operation-failed' is returned by the CoMI server when 1450 the operation request cannot be processed successfully. 1452 * error-app-tag 'malformed-message' is returned by the CoMI 1453 server when the payload received from the CoMI client don't 1454 contain a well-formed CBOR content as defined in [RFC7049] 1455 section 3.3 or don't comply with the CBOR structure defined 1456 within this document. 1458 * error-app-tag 'data-not-unique' is returned by the CoMI server 1459 when the validation of the 'unique' constraint of a list or 1460 leaf-list fails. 1462 * error-app-tag 'too-many-elements' is returned by the CoMI 1463 server when the validation of the 'max-elements' constraint of 1464 a list or leaf-list fails. 1466 * error-app-tag 'too-few-elements' is returned by the CoMI server 1467 when the validation of the 'min-elements' constraint of a list 1468 or leaf-list fails. 1470 * error-app-tag 'must-violation' is returned by the CoMI server 1471 when the restrictions imposed by a 'must' statement are 1472 violated. 1474 * error-app-tag 'duplicate' is returned by the CoMI server when a 1475 client tries to create a duplicate list or leaf-list entry. 1477 o error-tag 'invalid-value' is returned by the CoMI server when the 1478 CoMI client tries to update or create a leaf with a value encoded 1479 using an invalid CBOR datatype or if the 'range', 'length', 1480 'pattern' or 'require-instance' constrain is not fulfilled. 1482 * error-app-tag 'invalid-datatype' is returned by the CoMI server 1483 when CBOR encoding don't follow the rules set by or when the 1484 value is incompatible with the YANG Built-In type. (e.g. a 1485 value greater than 127 for an int8, undefined enumeration) 1487 * error-app-tag 'not-in-range' is returned by the CoMI server 1488 when the validation of the 'range' property fails. 1490 * error-app-tag 'invalid-length' is returned by the CoMI server 1491 when the validation of the 'length' property fails. 1493 * error-app-tag 'pattern-test-failed' is returned by the CoMI 1494 server when the validation of the 'pattern' property fails. 1496 o error-tag 'missing-element' is returned by the CoMI server when 1497 the operation requested by a CoMI client fail to comply with the 1498 'mandatory' constraint defined. The 'mandatory' constraint is 1499 enforced for leafs and choices, unless the node or any of its 1500 ancestors have a 'when' condition or 'if-feature' expression that 1501 evaluates to 'false'. 1503 * error-app-tag 'missing-key' is returned by the CoMI server to 1504 further qualify a missing-element error. This error is 1505 returned when the CoMI client tries to create or list instance, 1506 without all the 'key' specified or when the CoMI client tries 1507 to delete a leaf listed as a 'key'. 1509 * error-app-tag 'missing-input-parameter' is returned by the CoMI 1510 server when the input parameters of an RPC or action are 1511 incomplete. 1513 o error-tag 'unknown-element' is returned by the CoMI server when 1514 the CoMI client tries to access a data node of a YANG module not 1515 supported, of a data node associated to an 'if-feature' expression 1516 evaluated to 'false' or to a 'when' condition evaluated to 1517 'false'. 1519 o error-tag 'bad-element' is returned by the CoMI server when the 1520 CoMI client tries to create data nodes for more than one case in a 1521 choice. 1523 o error-tag 'data-missing' is returned by the CoMI server when a 1524 data node required to accept the request is not present. 1526 * error-app-tag 'instance-required' is returned by the CoMI 1527 server when a leaf of type 'instance-identifier' or 'leafref' 1528 marked with require-instance set to 'true' refers to an 1529 instance that does not exist. 1531 * error-app-tag 'missing-choice' is returned by the CoMI server 1532 when no nodes exist in a mandatory choice. 1534 o error-tag 'error' is returned by the CoMI server when an 1535 unspecified error has occurred. 1537 For example, the CoMI server might return the following error. 1539 RES: 4.00 Bad Request (Content-Format :application/yang-data+cbor) 1540 { 1541 1024 : { 1542 +4 : 1011, / error-tag (SID 1028) / 1543 / = invalid-value (SID 1011) / 1544 +1 : 1018, / error-app-tag (SID 1025) / 1545 / = not-in-range (SID 1018) / 1546 +2 : 1740, / error-data-node (SID 1026) / 1547 / = timezone-utc-offset (SID 1740) / 1548 +3 : "maximum value exceeded" / error-message (SID 1027) / 1549 } 1550 } 1552 8. Security Considerations 1554 For secure network management, it is important to restrict access to 1555 configuration variables only to authorized parties. CoMI re-uses the 1556 security mechanisms already available to CoAP, this includes DTLS 1557 [RFC6347] for protected access to resources, as well suitable 1558 authentication and authorization mechanisms. 1560 Among the security decisions that need to be made are selecting 1561 security modes and encryption mechanisms (see [RFC7252]). This 1562 requires a trade-off, as the NoKey mode gives no protection at all, 1563 but is easy to implement, whereas the X.509 mode is quite secure, but 1564 may be too complex for constrained devices. 1566 In addition, mechanisms for authentication and authorization may need 1567 to be selected. 1569 CoMI avoids defining new security mechanisms as much as possible. 1570 However, some adaptations may still be required, to cater for CoMI's 1571 specific requirements. 1573 9. IANA Considerations 1575 9.1. Resource Type (rt=) Link Target Attribute Values Registry 1577 This document adds the following resource type to the "Resource Type 1578 (rt=) Link Target Attribute Values", within the "Constrained RESTful 1579 Environments (CoRE) Parameters" registry. 1581 +-----------+---------------------+-----------+ 1582 | Value | Description | Reference | 1583 +-----------+---------------------+-----------+ 1584 | core.c.ds | YANG datastore | RFC XXXX | 1585 | | | | 1586 | core.c.dn | YANG data node | RFC XXXX | 1587 | | | | 1588 | core.c.yl | YANG module library | RFC XXXX | 1589 | | | | 1590 | core.c.es | YANG event stream | RFC XXXX | 1591 +-----------+---------------------+-----------+ 1593 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1594 note. 1596 9.2. CoAP Content-Formats Registry 1598 This document adds the following Content-Format to the "CoAP Content- 1599 Formats", within the "Constrained RESTful Environments (CoRE) 1600 Parameters" registry. 1602 +-----------------------------------+-------------+-----------+ 1603 | Media Type | Encoding ID | Reference | 1604 +-----------------------------------+-------------+-----------+ 1605 | application/yang-data+cbor | XXX | RFC XXXX | 1606 | | | | 1607 | application/yang-identifiers+cbor | XXX | RFC XXXX | 1608 | | | | 1609 | application/yang-instances+cbor | XXX | RFC XXXX | 1610 +-----------------------------------+-------------+-----------+ 1612 // RFC Ed.: replace XXX with assigned IDs and remove this note. // 1613 RFC Ed.: replace RFC XXXX with this RFC number and remove this note. 1615 9.3. Media Types Registry 1617 This document adds the following media types to the "Media Types" 1618 registry. 1620 +-----------------------+----------------------------+-----------+ 1621 | Name | Template | Reference | 1622 +-----------------------+----------------------------+-----------+ 1623 | yang-data+cbor | application/yang-data+cbor | RFC XXXX | 1624 | | | | 1625 | yang-identifiers+cbor | application/ | RFC XXXX | 1626 | | | | 1627 | | yang-identifiers+cbor | | 1628 | | | | 1629 | yang-instances+cbor | application/ | RFC XXXX | 1630 | | | | 1631 | | yang-instances+cbor | | 1632 +-----------------------+----------------------------+-----------+ 1634 Each of these media types share the following information: 1636 o Subtype name: 1638 o Required parameters: N/A 1640 o Optional parameters: N/A 1642 o Encoding considerations: binary 1644 o Security considerations: See the Security Considerations section 1645 of RFC XXXX 1647 o Interoperability considerations: N/A 1649 o Published specification: RFC XXXX 1651 o Applications that use this media type: CoMI 1653 o Fragment identifier considerations: N/A 1655 o Additional information: 1657 * Deprecated alias names for this type: N/A 1659 * Magic number(s): N/A 1661 * File extension(s): N/A 1663 * Macintosh file type code(s): N/A 1665 o Person & email address to contact for further information: 1666 iesg&ietf.org 1668 o Intended usage: COMMON 1670 o Restrictions on usage: N/A 1672 o Author: Michel Veillette, ietf&augustcellars.com 1674 o Change Controller: IESG 1676 o Provisional registration? No 1678 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1679 note. 1681 10. Acknowledgements 1683 We are very grateful to Bert Greevenbosch who was one of the original 1684 authors of the CoMI specification. 1686 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1687 transported under SNMP. Carsten Bormann has given feedback on the 1688 use of CBOR. 1690 The draft has benefited from comments (alphabetical order) by Rodney 1691 Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy 1692 Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes 1693 Tschofenig, Michael Verschoor, and Thomas Watteyne. 1695 11. References 1697 11.1. Normative References 1699 [I-D.ietf-core-sid] 1700 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 1701 iDentifier (SID)", draft-ietf-core-sid-06 (work in 1702 progress), March 2019. 1704 [I-D.ietf-core-yang-cbor] 1705 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 1706 Data Modeled with YANG", draft-ietf-core-yang-cbor-10 1707 (work in progress), April 2019. 1709 [I-D.veillette-core-yang-library] 1710 Veillette, M. and I. Petrov, "Constrained YANG Module 1711 Library", draft-veillette-core-yang-library-04 (work in 1712 progress), March 2019. 1714 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1715 Requirement Levels", BCP 14, RFC 2119, 1716 DOI 10.17487/RFC2119, March 1997, 1717 . 1719 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1720 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1721 . 1723 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1724 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1725 . 1727 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1728 and A. Bierman, Ed., "Network Configuration Protocol 1729 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1730 . 1732 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1733 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1734 . 1736 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1737 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1738 October 2013, . 1740 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1741 Application Protocol (CoAP)", RFC 7252, 1742 DOI 10.17487/RFC7252, June 2014, 1743 . 1745 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1746 Application Protocol (CoAP)", RFC 7641, 1747 DOI 10.17487/RFC7641, September 2015, 1748 . 1750 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1751 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1752 . 1754 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1755 the Constrained Application Protocol (CoAP)", RFC 7959, 1756 DOI 10.17487/RFC7959, August 2016, 1757 . 1759 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1760 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1761 . 1763 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1764 FETCH Methods for the Constrained Application Protocol 1765 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1766 . 1768 11.2. Informative References 1770 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1771 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1772 January 2012, . 1774 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1775 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1776 . 1778 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1779 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1780 . 1782 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1783 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1784 2014, . 1786 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1787 and R. Wilton, "Network Management Datastore Architecture 1788 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1789 . 1791 Appendix A. ietf-comi YANG module 1793 file "ietf-comi@2019-03-28.yang" 1794 module ietf-comi { 1795 yang-version 1.1; 1797 namespace "urn:ietf:params:xml:ns:yang:ietf-comi"; 1798 prefix comi; 1800 import ietf-datastores { 1801 prefix ds; 1802 } 1804 import ietf-restconf { 1805 prefix rc; 1806 description 1807 "This import statement is required to access 1808 the yang-data extension defined in RFC 8040."; 1809 reference "RFC 8040: RESTCONF Protocol"; 1810 } 1811 organization 1812 "IETF Core Working Group"; 1814 contact 1815 "Michel Veillette 1816 1818 Alexander Pelov 1819 1821 Peter van der Stok 1822 1824 Andy Bierman 1825 "; 1827 description 1828 "This module contains the different definitions required 1829 by the CoMI protocol."; 1831 revision 2019-03-28 { 1832 description 1833 "Initial revision."; 1834 reference 1835 "[I-D.ietf-core-comi] CoAP Management Interface"; 1836 } 1838 identity unified { 1839 base ds:datastore; 1840 description 1841 "Identifier of the unified configuration and operational 1842 state datastore."; 1843 } 1845 identity error-tag { 1846 description 1847 "Base identity for error-tag."; 1848 } 1850 identity operation-failed { 1851 base error-tag; 1852 description 1853 "Returned by the CoMI server when the operation request 1854 can't be processed successfully."; 1855 } 1857 identity invalid-value { 1858 base error-tag; 1859 description 1860 "Returned by the CoMI server when the CoMI client tries to 1861 update or create a leaf with a value encoded using an 1862 invalid CBOR datatype or if the 'range', 'length', 1863 'pattern' or 'require-instance' constrain is not 1864 fulfilled."; 1865 } 1867 identity missing-element { 1868 base error-tag; 1869 description 1870 "Returned by the CoMI server when the operation requested 1871 by a CoMI client fails to comply with the 'mandatory' 1872 constraint defined. The 'mandatory' constraint is 1873 enforced for leafs and choices, unless the node or any of 1874 its ancestors have a 'when' condition or 'if-feature' 1875 expression that evaluates to 'false'."; 1876 } 1878 identity unknown-element { 1879 base error-tag; 1880 description 1881 "Returned by the CoMI server when the CoMI client tries to 1882 access a data node of a YANG module not supported, of a 1883 data node associated with an 'if-feature' expression 1884 evaluated to 'false' or to a 'when' condition evaluated 1885 to 'false'."; 1886 } 1888 identity bad-element { 1889 base error-tag; 1890 description 1891 "Returned by the CoMI server when the CoMI client tries to 1892 create data nodes for more than one case in a choice."; 1893 } 1895 identity data-missing { 1896 base error-tag; 1897 description 1898 "Returned by the CoMI server when a data node required to 1899 accept the request is not present."; 1900 } 1902 identity error { 1903 base error-tag; 1904 description 1905 "Returned by the CoMI server when an unspecified error has 1906 occurred."; 1908 } 1910 identity error-app-tag { 1911 description 1912 "Base identity for error-app-tag."; 1913 } 1915 identity malformed-message { 1916 base error-app-tag; 1917 description 1918 "Returned by the CoMI server when the payload received 1919 from the CoMI client don't contain a well-formed CBOR 1920 content as defined in [RFC7049] section 3.3 or don't 1921 comply with the CBOR structure defined within this 1922 document."; 1923 } 1925 identity data-not-unique { 1926 base error-app-tag; 1927 description 1928 "Returned by the CoMI server when the validation of the 1929 'unique' constraint of a list or leaf-list fails."; 1930 } 1932 identity too-many-elements { 1933 base error-app-tag; 1934 description 1935 "Returned by the CoMI server when the validation of the 1936 'max-elements' constraint of a list or leaf-list fails."; 1937 } 1939 identity too-few-elements { 1940 base error-app-tag; 1941 description 1942 "Returned by the CoMI server when the validation of the 1943 'min-elements' constraint of a list or leaf-list fails."; 1944 } 1946 identity must-violation { 1947 base error-app-tag; 1948 description 1949 "Returned by the CoMI server when the restrictions 1950 imposed by a 'must' statement are violated."; 1951 } 1953 identity duplicate { 1954 base error-app-tag; 1955 description 1956 "Returned by the CoMI server when a client tries to create 1957 a duplicate list or leaf-list entry."; 1958 } 1960 identity invalid-datatype { 1961 base error-app-tag; 1962 description 1963 "Returned by the CoMI server when CBOR encoding is 1964 incorect or when the value encoded is incompatible with 1965 the YANG Built-In type. (e.g. value greater than 127 1966 for an int8, undefined enumeration)."; 1967 } 1969 identity not-in-range { 1970 base error-app-tag; 1971 description 1972 "Returned by the CoMI server when the validation of the 1973 'range' property fails."; 1974 } 1976 identity invalid-length { 1977 base error-app-tag; 1978 description 1979 "Returned by the CoMI server when the validation of the 1980 'length' property fails."; 1981 } 1983 identity pattern-test-failed { 1984 base error-app-tag; 1985 description 1986 "Returned by the CoMI server when the validation of the 1987 'pattern' property fails."; 1988 } 1990 identity missing-key { 1991 base error-app-tag; 1992 description 1993 "Returned by the CoMI server to further qualify a 1994 missing-element error. This error is returned when the 1995 CoMI client tries to create or list instance, without all 1996 the 'key' specified or when the CoMI client tries to 1997 delete a leaf listed as a 'key'."; 1998 } 2000 identity missing-input-parameter { 2001 base error-app-tag; 2002 description 2003 "Returned by the CoMI server when the input parameters 2004 of a RPC or action are incomplete."; 2005 } 2007 identity instance-required { 2008 base error-app-tag; 2009 description 2010 "Returned by the CoMI server when a leaf of type 2011 'instance-identifier' or 'leafref' marked with 2012 require-instance set to 'true' refers to an instance 2013 that does not exist."; 2014 } 2016 identity missing-choice { 2017 base error-app-tag; 2018 description 2019 "Returned by the CoMI server when no nodes exist in a 2020 mandatory choice."; 2021 } 2023 rc:yang-data comi-error { 2024 container error { 2025 description 2026 "Optional payload of a 4.00 Bad Request CoAP error."; 2028 leaf error-tag { 2029 type identityref { 2030 base error-tag; 2031 } 2032 mandatory true; 2033 description 2034 "The enumerated error-tag."; 2035 } 2037 leaf error-app-tag { 2038 type identityref { 2039 base error-app-tag; 2040 } 2041 description 2042 "The application-specific error-tag."; 2043 } 2045 leaf error-data-node { 2046 type instance-identifier; 2047 description 2048 "When the error reported is caused by a specific data node, 2049 this leaf identifies the data node in error."; 2050 } 2051 leaf error-message { 2052 type string; 2053 description 2054 "A message describing the error."; 2055 } 2056 } 2057 } 2058 } 2059 2061 Appendix B. ietf-comi .sid file 2063 { 2064 "assignment-ranges": [ 2065 { 2066 "entry-point": 1000, 2067 "size": 100 2068 } 2069 ], 2070 "module-name": "ietf-comi", 2071 "module-revision": "2019-03-28", 2072 "items": [ 2073 { 2074 "namespace": "module", 2075 "identifier": "ietf-comi", 2076 "sid": 1000 2077 }, 2078 { 2079 "namespace": "identity", 2080 "identifier": "bad-element", 2081 "sid": 1001 2082 }, 2083 { 2084 "namespace": "identity", 2085 "identifier": "data-missing", 2086 "sid": 1002 2087 }, 2088 { 2089 "namespace": "identity", 2090 "identifier": "data-not-unique", 2091 "sid": 1003 2092 }, 2093 { 2094 "namespace": "identity", 2095 "identifier": "duplicate", 2096 "sid": 1004 2097 }, 2098 { 2099 "namespace": "identity", 2100 "identifier": "error", 2101 "sid": 1005 2102 }, 2103 { 2104 "namespace": "identity", 2105 "identifier": "error-app-tag", 2106 "sid": 1006 2107 }, 2108 { 2109 "namespace": "identity", 2110 "identifier": "error-tag", 2111 "sid": 1007 2112 }, 2113 { 2114 "namespace": "identity", 2115 "identifier": "instance-required", 2116 "sid": 1008 2117 }, 2118 { 2119 "namespace": "identity", 2120 "identifier": "invalid-datatype", 2121 "sid": 1009 2122 }, 2123 { 2124 "namespace": "identity", 2125 "identifier": "invalid-length", 2126 "sid": 1010 2127 }, 2128 { 2129 "namespace": "identity", 2130 "identifier": "invalid-value", 2131 "sid": 1011 2132 }, 2133 { 2134 "namespace": "identity", 2135 "identifier": "malformed-message", 2136 "sid": 1012 2137 }, 2138 { 2139 "namespace": "identity", 2140 "identifier": "missing-choice", 2141 "sid": 1013 2142 }, 2143 { 2144 "namespace": "identity", 2145 "identifier": "missing-element", 2146 "sid": 1014 2148 }, 2149 { 2150 "namespace": "identity", 2151 "identifier": "missing-input-parameter", 2152 "sid": 1015 2153 }, 2154 { 2155 "namespace": "identity", 2156 "identifier": "missing-key", 2157 "sid": 1016 2158 }, 2159 { 2160 "namespace": "identity", 2161 "identifier": "must-violation", 2162 "sid": 1017 2163 }, 2164 { 2165 "namespace": "identity", 2166 "identifier": "not-in-range", 2167 "sid": 1018 2168 }, 2169 { 2170 "namespace": "identity", 2171 "identifier": "operation-failed", 2172 "sid": 1019 2173 }, 2174 { 2175 "namespace": "identity", 2176 "identifier": "pattern-test-failed", 2177 "sid": 1020 2178 }, 2179 { 2180 "namespace": "identity", 2181 "identifier": "too-few-elements", 2182 "sid": 1021 2183 }, 2184 { 2185 "namespace": "identity", 2186 "identifier": "too-many-elements", 2187 "sid": 1022 2188 }, 2189 { 2190 "namespace": "identity", 2191 "identifier": "unified", 2192 "sid": 1029 2193 }, 2194 { 2195 "namespace": "identity", 2196 "identifier": "unknown-element", 2197 "sid": 1023 2198 }, 2199 { 2200 "namespace": "data", 2201 "identifier": "/ietf-comi:error", 2202 "sid": 1024 2203 }, 2204 { 2205 "namespace": "data", 2206 "identifier": "/ietf-comi:error/error-app-tag", 2207 "sid": 1025 2208 }, 2209 { 2210 "namespace": "data", 2211 "identifier": "/ietf-comi:error/error-data-node", 2212 "sid": 1026 2213 }, 2214 { 2215 "namespace": "data", 2216 "identifier": "/ietf-comi:error/error-message", 2217 "sid": 1027 2218 }, 2219 { 2220 "namespace": "data", 2221 "identifier": "/ietf-comi:error/error-tag", 2222 "sid": 1028 2223 } 2224 ] 2225 } 2227 Authors' Addresses 2229 Michel Veillette (editor) 2230 Trilliant Networks Inc. 2231 610 Rue du Luxembourg 2232 Granby, Quebec J2J 2V2 2233 Canada 2235 Email: michel.veillette@trilliant.com 2237 Peter van der Stok (editor) 2238 consultant 2240 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2241 Email: consultancy@vanderstok.org 2242 URI: www.vanderstok.org 2243 Alexander Pelov 2244 Acklio 2245 2bis rue de la Chataigneraie 2246 Cesson-Sevigne, Bretagne 35510 2247 France 2249 Email: a@ackl.io 2251 Andy Bierman 2252 YumaWorks 2253 685 Cochran St. 2254 Suite #160 2255 Simi Valley, CA 93065 2256 USA 2258 Email: andy@yumaworks.com