idnits 2.17.1 draft-ietf-core-comi-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 7 characters in excess of 72. ** 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 -- The document date (July 22, 2019) is 1732 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 345 -- Looks like a reference, but probably isn't: '26' on line 346 -- Looks like a reference, but probably isn't: '57' on line 347 == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-07 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-10 ** 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: 3 errors (**), 0 flaws (~~), 3 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: January 23, 2020 consultant 6 A. Pelov 7 Acklio 8 A. Bierman 9 YumaWorks 10 I. Petrov, Ed. 11 Acklio 12 July 22, 2019 14 CoAP Management Interface 15 draft-ietf-core-comi-07 17 Abstract 19 This document describes a network management interface for 20 constrained devices and networks, called CoAP Management Interface 21 (CoMI). The Constrained Application Protocol (CoAP) is used to 22 access datastore and data node resources specified in YANG, or SMIv2 23 converted to YANG. CoMI uses the YANG to CBOR mapping and converts 24 YANG identifier strings to numeric identifiers for payload size 25 reduction. The complete solution composed of CoMI, 26 [I-D.ietf-core-yang-cbor] and [I-D.ietf-core-sid] is called CORECONF. 27 CORECONF extends the set of YANG based protocols, NETCONF and 28 RESTCONF, with the capability to manage constrained devices and 29 networks. 31 Note 33 Discussion and suggestions for improvement are requested, and should 34 be sent to yot@ietf.org. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on January 23, 2020. 53 Copyright Notice 55 Copyright (c) 2019 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 72 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5 73 2.1. Major differences between RESTCONF and CoMI . . . . . . . 6 74 2.1.1. Differences due to CoAP and its efficient usage . . . 6 75 2.1.2. Differences due to the use of CBOR . . . . . . . . . 7 76 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 77 2.3. Instance identifier . . . . . . . . . . . . . . . . . . . 8 78 2.4. Content-Formats . . . . . . . . . . . . . . . . . . . . . 8 79 2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10 80 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11 81 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11 82 4.1. Using the 'k' Uri-Query option . . . . . . . . . . . . . 13 83 4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 14 84 4.2.1. Using the 'c' Uri-Query option . . . . . . . . . . . 14 85 4.2.2. Using the 'd' Uri-Query option . . . . . . . . . . . 15 86 4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16 87 4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 18 88 4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 19 89 4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 19 90 4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 20 91 4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 20 92 4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 21 93 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 22 94 4.4. Full datastore access . . . . . . . . . . . . . . . . . . 23 95 4.4.1. Full datastore examples . . . . . . . . . . . . . . . 23 97 4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 24 98 4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 25 99 4.5.2. The 'f' Uri-Query option . . . . . . . . . . . . . . 26 100 4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27 101 4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 27 102 5. Use of Block-wise Transfers . . . . . . . . . . . . . . . . . 29 103 6. Application Discovery . . . . . . . . . . . . . . . . . . . . 29 104 6.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 29 105 6.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 30 106 6.2.1. Datastore Resource Discovery . . . . . . . . . . . . 30 107 6.2.2. Data node Resource Discovery . . . . . . . . . . . . 31 108 6.2.3. Event stream Resource Discovery . . . . . . . . . . . 31 109 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 31 110 8. Security Considerations . . . . . . . . . . . . . . . . . . . 35 111 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 112 9.1. Resource Type (rt=) Link Target Attribute Values Registry 35 113 9.2. CoAP Content-Formats Registry . . . . . . . . . . . . . . 36 114 9.3. Media Types Registry . . . . . . . . . . . . . . . . . . 36 115 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 38 116 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 117 11.1. Normative References . . . . . . . . . . . . . . . . . . 38 118 11.2. Informative References . . . . . . . . . . . . . . . . . 40 119 Appendix A. ietf-comi YANG module . . . . . . . . . . . . . . . 40 120 Appendix B. ietf-comi .sid file . . . . . . . . . . . . . . . . 46 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49 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, CORECONF 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", "NOT RECOMMENDED", "MAY", and 155 "OPTIONAL" in this document are to be interpreted as described in BCP 156 14 [RFC2119] [RFC8174] when, and only when, they appear in all 157 capitals, as shown here. 159 The following terms are defined in the YANG data modelling language 160 [RFC7950]: action, anydata, anyxml, client, container, data model, 161 data node, identity, instance identifier, leaf, leaf-list, list, 162 module, RPC, schema node, server, submodule. 164 The following terms are defined in [RFC6241]: configuration data, 165 datastore, state data 167 The following term is defined in [I-D.ietf-core-sid]: YANG schema 168 item identifier (SID). 170 The following terms are defined in the CoAP protocol [RFC7252]: 171 Confirmable Message, Content-Format, Endpoint. 173 The following terms are defined in this document: 175 data node resource: a CoAP resource that models a YANG data node. 177 datastore resource: a CoAP resource that models a YANG datastore. 179 event stream resource: a CoAP resource used by clients to observe 180 YANG notifications. 182 notification instance: An instance of a schema node of type 183 notification, specified in a YANG module implemented by the 184 server. The instance is generated in the server at the occurrence 185 of the corresponding event and reported by an event stream. 187 list instance identifier: Handle used to identify a YANG data node 188 that is an instance of a YANG "list" specified with the values of 189 the key leaves of the list. 191 single instance identifier: Handle used to identify a specific data 192 node which can be instantiated only once. This includes data 193 nodes defined at the root of a YANG module and data nodes defined 194 within a container. This excludes data nodes defined within a 195 list or any children of these data nodes. 197 instance-identifier: List instance identifier or single instance 198 identifier. 200 instance-value: The value assigned to a schema node instance. 201 Schema node values are serialized into the payload according to 202 the rules defined in section 4 of [I-D.ietf-core-yang-cbor]. 204 2. CoMI Architecture 206 This section describes the CoMI architecture to use CoAP for reading 207 and modifying the content of datastore(s) used for the management of 208 the instrumented node. 210 +----------------------------------------------------------------+ 211 | SMIv2 specification (optional) (2) | 212 +----------------------------------------------------------------+ 213 | 214 V 215 +----------------------------------------------------------------+ 216 | YANG specification (1) | 217 +----------------------------------------------------------------+ 218 | | 219 Client V Server V 220 +----------------+ +-----------------------+ 221 | Request |--> CoAP request(3) -->| Indication | 222 | Confirm |<-- CoAP response(3)<--| Response (4) | 223 | | | | 224 | |<==== Security (7) ===>|+---------------------+| 225 +----------------+ || Datastore(s) (5) || 226 |+---------------------+| 227 |+---------------------+| 228 || Event stream(s) (6) || 229 |+---------------------+| 230 +-----------------------+ 232 Figure 1: Abstract CoMI architecture 234 Figure 1 is a high-level representation of the main elements of the 235 CoMI management architecture. The different numbered components of 236 Figure 1 are discussed according to component number. 238 (1) YANG specification: contains a set of named and versioned 239 modules. 241 (2) SMIv2 specification: Optional part that consists of a named 242 module which, specifies a set of variables and "conceptual 243 tables". There is an algorithm to translate SMIv2 specifications 244 to YANG specifications. 246 (3) CoAP request/response messages: The CoMI client sends request 247 messages to and receives response messages from the CoMI server. 249 (4) Request, Indication, Response, Confirm: Processes performed by 250 the CoMI clients and servers. 252 (5) Datastore: A resource used to access configuration data, state 253 data, RPCs and actions. A CoMI server may support a single 254 unified datastore or multiple datastores as those defined by 255 Network Management Datastore Architecture (NMDA) [RFC8342]. 257 (6) Event stream: A resource used to get real time notifications. A 258 CoMI server may support multiple Event streams serving different 259 purposes such as normal monitoring, diagnostic, syslog, security 260 monitoring. 262 (7) Security: The server MUST prevent unauthorized users from 263 reading or writing any CoMI resources. CoMI relies on security 264 protocols such as DTLS [RFC6347] to secure CoAP communications. 266 2.1. Major differences between RESTCONF and CoMI 268 CoMI is a RESTful protocol for small devices where saving bytes to 269 transport counts. Contrary to RESTCONF, many design decisions are 270 motivated by the saving of bytes. Consequently, CoMI is not a 271 RESTCONF over CoAP protocol, but differs more significantly from 272 RESTCONF. 274 2.1.1. Differences due to CoAP and its efficient usage 276 o CoMI uses CoAP/UDP as transport protocol and CBOR as payload 277 format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as 278 transport protocol and JSON or XML as payload formats. 280 o CoMI uses the methods FETCH and iPATCH to access multiple data 281 nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP 282 method GET with the "fields" Query parameter. 284 o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not 285 supported by CoAP. 287 o CoMI does not support "insert" query parameter (first, last, 288 before, after) and the "point" query parameter which are supported 289 by RESTCONF. 291 o CoMI does not support the "start-time" and "stop-time" query 292 parameters to retrieve past notifications. 294 o CoMI does not support the "filter" query parameters to observe a 295 specific set of notifications. 297 2.1.2. Differences due to the use of CBOR 299 o CoMI encodes YANG identifier strings as numbers, where RESTCONF 300 does not. 302 o CoMI also differ in the handling of default values, only 'report- 303 all' and 'trip' options are supported. 305 2.2. Compression of YANG identifiers 307 In the YANG specification, items are identified with a name string. 308 In order to significantly reduce the size of identifiers used in 309 CoMI, numeric identifiers are used instead of these strings. YANG 310 Schema Item iDentifier (SID) is defined in [I-D.ietf-core-yang-cbor] 311 section 2.1. 313 When used in a URI, SIDs are encoded using base64 encoding of the SID 314 bytes. The base64 encoding is using the URL and Filename safe 315 alphabet as defined by [RFC4648] section 5, without padding. The 316 last 6 bits encoded is always aligned with the least significant 6 317 bits of the SID represented using an unsigned integer. 'A' 318 characters (value 0) at the start of the resulting string are 319 removed. See Figure 2 for complete illustration. 321 SID in base64 = URLsafeChar[SID >> 60 & 0x3F] | 322 URLsafeChar[SID >> 54 & 0x3F] | 323 URLsafeChar[SID >> 48 & 0x3F] | 324 URLsafeChar[SID >> 42 & 0x3F] | 325 URLsafeChar[SID >> 36 & 0x3F] | 326 URLsafeChar[SID >> 30 & 0x3F] | 327 URLsafeChar[SID >> 24 & 0x3F] | 328 URLsafeChar[SID >> 18 & 0x3F] | 329 URLsafeChar[SID >> 12 & 0x3F] | 330 URLsafeChar[SID >> 6 & 0x3F] | 331 URLsafeChar[SID & 0x3F] 333 Figure 2 335 For example, SID 1721 is encoded as follow. 337 URLsafeChar[1721 >> 60 & 0x3F] = URLsafeChar[0] = 'A' 338 URLsafeChar[1721 >> 54 & 0x3F] = URLsafeChar[0] = 'A' 339 URLsafeChar[1721 >> 48 & 0x3F] = URLsafeChar[0] = 'A' 340 URLsafeChar[1721 >> 42 & 0x3F] = URLsafeChar[0] = 'A' 341 URLsafeChar[1721 >> 36 & 0x3F] = URLsafeChar[0] = 'A' 342 URLsafeChar[1721 >> 30 & 0x3F] = URLsafeChar[0] = 'A' 343 URLsafeChar[1721 >> 24 & 0x3F] = URLsafeChar[0] = 'A' 344 URLsafeChar[1721 >> 18 & 0x3F] = URLsafeChar[0] = 'A' 345 URLsafeChar[1721 >> 12 & 0x3F] = URLsafeChar[0] = 'A' 346 URLsafeChar[1721 >> 6 & 0x3F] = URLsafeChar[26] = 'a' 347 URLsafeChar[1721 & 0x3F] = URLsafeChar[57] = '5' 349 The resulting base64 representation of SID 1721 is "a5" 351 2.3. Instance identifier 353 Instance identifiers are used to uniquely identify data node 354 instances within a datastore. This YANG built-in type is defined in 355 [RFC7950] section 9.13. An instance identifier is composed of the 356 data node identifier (i.e. a SID) and for data nodes within list(s) 357 the keys used to index within these list(s). 359 When part of a payload, instance identifiers are encoded in CBOR 360 based on the rules defined in [I-D.ietf-core-yang-cbor] section 361 6.13.1. When part of a URI, the SID is appended to the URI of the 362 targeted datastore, the keys are specified using the 'k' URI-Query as 363 defined in Section 4.1. 365 2.4. Content-Formats 367 CoMI uses Content-Formats based on the YANG to CBOR mapping specified 368 in [I-D.ietf-core-yang-cbor]. 370 The following Content-formats are defined: 372 application/yang-data+cbor: This Content-Format represents a CBOR 373 YANG document containing one or multiple data node values. Each 374 data node is identified by its associated SID. 376 FORMAT: CBOR map of SID, instance-value 378 The message payload of Content-Format 'application/yang-data+cbor' 379 is encoded using a CBOR map. Each entry of this CBOR map is 380 composed of a key and a value. CBOR map keys are set to the SID 381 or SID deltas associated with the data nodes as defined in 382 [I-D.ietf-core-yang-cbor] section 4, CBOR map values are set to 383 the instance value as defined in [I-D.ietf-core-yang-cbor] section 384 4. 386 application/yang-identifiers+cbor: This Content-Format represents a 387 CBOR YANG document containing a list of instance identifier used 388 to target specific data node instances within a datastore. 390 FORMAT: CBOR array of instance-identifier 392 The message payload of Content-Format 'application/yang- 393 identifiers+cbor' is encoded using a CBOR array. Each entry of 394 this CBOR array contain an instance identifier encoded as defined 395 in [I-D.ietf-core-yang-cbor] section 6.13.1. 397 application/yang-instances+cbor: This Content-Format represents a 398 CBOR YANG document containing a list of data node instances. Each 399 data node instance is identified by its associated instance 400 identifier. 402 FORMAT: CBOR array of CBOR map of instance-identifier, instance- 403 value 405 The message payload of Content-Format 'application/yang- 406 instances+cbor' is encoded using a CBOR array. Each entry within 407 this CBOR array contains a CBOR map carrying an instance 408 identifier and associated instance value. Instance identifiers 409 are encoded using the rules defined in [I-D.ietf-core-yang-cbor] 410 section 6.13.1, values are encoded using the rules defined in 411 [I-D.ietf-core-yang-cbor] section 4. 413 When present in an iPATCH request payload, this Content-Format 414 carry a list of data node instances to be replaced, created, or 415 deleted. For each data node instance D, for which the instance 416 identifier is the same as a data node instance I, in the targeted 417 datastore resource: the value of D replaces the value of I. When 418 the value of D is null, the data node instance I is removed. When 419 the targeted datastore resource does not contain a data node 420 instance with the same instance identifier as D, a new instance is 421 created with the same instance identifier and value as D. 423 The different Content-format usages are summarized in the table 424 below: 426 +---------------+--------------+------------------------------------+ 427 | Method | Resource | Content-Format | 428 +---------------+--------------+------------------------------------+ 429 | GET response | data node | /application/yang-data+cbor | 430 | | | | 431 | PUT request | data node | /application/yang-data+cbor | 432 | | | | 433 | POST request | data node | /application/yang-data+cbor | 434 | | | | 435 | DELETE | data node | n/a | 436 | | | | 437 | GET response | datastore | /application/yang-data+cbor | 438 | | | | 439 | PUT request | datastore | /application/yang-data+cbor | 440 | | | | 441 | POST request | datastore | /application/yang-data+cbor | 442 | | | | 443 | FETCH request | datastore | /application/yang-identifiers+cbor | 444 | | | | 445 | FETCH | datastore | /application/yang-instances+cbor | 446 | response | | | 447 | | | | 448 | iPATCH | datastore | /application/yang-instances+cbor | 449 | request | | | 450 | | | | 451 | GET response | event stream | /application/yang-instances+cbor | 452 | | | | 453 | POST request | rpc, action | /application/yang-data+cbor | 454 | | | | 455 | POST response | rpc, action | /application/yang-data+cbor | 456 +---------------+--------------+------------------------------------+ 458 2.5. Unified datastore 460 CoMI supports a simple datastore model consisting of a single unified 461 datastore. This datastore provides access to both configuration and 462 operational data. Configuration updates performed on this datastore 463 are reflected immediately or with a minimal delay as operational 464 data. 466 Alternatively, CoMI servers MAY implement a more complex datastore 467 model such as the Network Management Datastore Architecture (NMDA) as 468 defined by [RFC8342]. Each datastore supported is implemented as a 469 datastore resource. 471 Characteristics of the unified datastore are summarized in the table 472 below: 474 +-------------+-----------------------------------------------------+ 475 | Name | Value | 476 +-------------+-----------------------------------------------------+ 477 | Name | unified | 478 | | | 479 | YANG | all modules | 480 | modules | | 481 | | | 482 | YANG nodes | all data nodes ("config true" and "config false") | 483 | | | 484 | Access | read-write | 485 | | | 486 | How applied | changes applied in place immediately or with a | 487 | | minimal delay | 488 | | | 489 | Protocols | CORECONF | 490 | | | 491 | Defined in | "ietf-comi" | 492 +-------------+-----------------------------------------------------+ 494 3. Example syntax 496 CBOR is used to encode CoMI request and response payloads. The CBOR 497 syntax of the YANG payloads is specified in [RFC7049]. The payload 498 examples are notated in Diagnostic notation (defined in section 6 of 499 [RFC7049]) that can be automatically converted to CBOR. 501 SIDs in URIs are represented as a base64 number, SIDs in the payload 502 are represented as decimal numbers. 504 4. CoAP Interface 506 This note specifies a Management Interface. CoAP endpoints that 507 implement the CoMI management protocol, support at least one 508 discoverable management resource of resource type (rt): core.c.ds, 509 with example path: /c, where c is short-hand for CoMI. The path /c 510 is recommended, but not compulsory (see Section 6). 512 The mapping of YANG data node instances to CoMI resources is as 513 follows. Every data node of the YANG modules loaded in the CoMI 514 server represents a sub-resource of the datastore resource (e.g. /c/ 515 sid). When multiple instances of a list exist, instance selection is 516 possible as described in Section 4.1, Section 4.2.3.1, and 517 Section 4.2.4. 519 CoMI also supports event stream resources used to observe 520 notification instances. Event stream resources can be discovered 521 using resource type (rt): core.c.ev. 523 The description of the CoMI management interface is shown in the 524 table below: 526 +-------------+------------------+-----------+ 527 | Function | Recommended path | rt | 528 +-------------+------------------+-----------+ 529 | Datastore | /c | core.c.ds | 530 | | | | 531 | Data node | /c/SID | core.c.dn | 532 | | | | 533 | Event steam | /s | core.c.ev | 534 +-------------+------------------+-----------+ 536 The path values in the table are the recommended ones. On discovery, 537 the server makes the actual path values known for these resources. 539 The methods used by CoMI are: 541 +-----------+-------------------------------------------------------+ 542 | Operation | Description | 543 +-----------+-------------------------------------------------------+ 544 | GET | Retrieve the datastore resource or a data node | 545 | | resource | 546 | | | 547 | FETCH | Retrieve specific data nodes within a datastore | 548 | | resource | 549 | | | 550 | POST | Create a datastore resource or a data node resource, | 551 | | invoke an RPC or action | 552 | | | 553 | PUT | Create or replace a datastore resource or a data node | 554 | | resource | 555 | | | 556 | iPATCH | Idem-potently create, replace, and delete data node | 557 | | resource(s) within a datastore resource | 558 | | | 559 | DELETE | Delete a datastore resource or a data node resource | 560 +-----------+-------------------------------------------------------+ 562 There is one Uri-Query option for the GET, PUT, POST, and DELETE 563 methods. 565 +------------------+----------------------------------------+ 566 | Uri-Query option | Description | 567 +------------------+----------------------------------------+ 568 | k | Select an instance within YANG list(s) | 569 +------------------+----------------------------------------+ 570 This parameter is not used for FETCH and iPATCH, because their 571 request payloads support list instance selection. 573 4.1. Using the 'k' Uri-Query option 575 The "k" (key) parameter specifies a specific instance of a data node. 576 The SID in the URI is followed by the (?k=key1,key2,...). Where SID 577 identifies a data node, and key1, key2 are the values of the key 578 leaves that specify an instance. Lists can have multiple keys, and 579 lists can be part of lists. The order of key value generation is 580 given recursively by: 582 o For a given list, if a parent data node is a list, generate the 583 keys for the parent list first. 585 o For a given list, generate key values in the order specified in 586 the YANG module. 588 Key values are encoded using the rules defined in the following 589 table. 591 +-----------------------------+--------------------------------+ 592 | YANG datatype | Uri-Query text content | 593 +-----------------------------+--------------------------------+ 594 | uint8,uint16,unit32, uint64 | int2str(key) | 595 | | | 596 | int8, int16,int32, int64 | urlSafeBase64(CBORencode(key)) | 597 | | | 598 | decimal64 | urlSafeBase64(CBOR key) | 599 | | | 600 | string | key | 601 | | | 602 | boolean | "0" or "1" | 603 | | | 604 | enumeration | int2str(key) | 605 | | | 606 | bits | urlSafeBase64(CBORencode(key)) | 607 | | | 608 | binary | urlSafeBase64(key) | 609 | | | 610 | identityref | int2str(key) | 611 | | | 612 | union | urlSafeBase64(CBORencode(key)) | 613 | | | 614 | instance-identifier | urlSafeBase64(CBORencode(key)) | 615 +-----------------------------+--------------------------------+ 617 In this table: 619 o The method int2str() is used to convert an integer value to a 620 decimal string. For example, int2str(0x0123) return the string 621 "291". 623 o The method urlSafeBase64() is used to convert a binary string to 624 base64 using the URL and Filename safe alphabet as defined by 625 [RFC4648] section 5, without padding. For example, 626 urlSafeBase64(\xF9\x56\xA1\x3C) return the string "-VahPA". 628 o The method CBORencode() is used to convert a YANG value to CBOR as 629 specified in [I-D.ietf-core-yang-cbor] section 6. 631 The resulting key string is encoded in a Uri-Query as specified in 632 [RFC7252] section 6.5. 634 4.2. Data Retrieval 636 One or more data nodes can be retrieved by the client. The operation 637 is mapped to the GET method defined in section 5.8.1 of [RFC7252] and 638 to the FETCH method defined in section 2 of [RFC8132]. 640 There are two additional Uri-Query options for the GET and FETCH 641 methods. 643 +-------------+-----------------------------------------------------+ 644 | Uri-Query | Description | 645 | option | | 646 +-------------+-----------------------------------------------------+ 647 | c | Control selection of configuration and non- | 648 | | configuration data nodes (GET and FETCH) | 649 | | | 650 | d | Control retrieval of default values. | 651 +-------------+-----------------------------------------------------+ 653 4.2.1. Using the 'c' Uri-Query option 655 The 'c' (content) option controls how descendant nodes of the 656 requested data nodes will be processed in the reply. 658 The allowed values are: 660 +-------+-----------------------------------------------------+ 661 | Value | Description | 662 +-------+-----------------------------------------------------+ 663 | c | Return only configuration descendant data nodes | 664 | | | 665 | n | Return only non-configuration descendant data nodes | 666 | | | 667 | a | Return all descendant data nodes | 668 +-------+-----------------------------------------------------+ 670 This option is only allowed for GET and FETCH methods on datastore 671 and data node resources. A 4.02 (Bad Option) error is returned if 672 used for other methods or resource types. 674 If this Uri-Query option is not present, the default value is "a". 676 4.2.2. Using the 'd' Uri-Query option 678 The "d" (with-defaults) option controls how the default values of the 679 descendant nodes of the requested data nodes will be processed. 681 The allowed values are: 683 +-------+-----------------------------------------------------------+ 684 | Value | Description | 685 +-------+-----------------------------------------------------------+ 686 | a | All data nodes are reported. Defined as 'report-all' in | 687 | | section 3.1 of [RFC6243]. | 688 | | | 689 | t | Data nodes set to the YANG default are not reported. | 690 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 691 +-------+-----------------------------------------------------------+ 693 If the target of a GET or FETCH method is a data node that represents 694 a leaf that has a default value, and the leaf has not been given a 695 value by any client yet, the server MUST return the default value of 696 the leaf. 698 If the target of a GET method is a data node that represents a 699 container or list that has child resources with default values, and 700 these have not been given value yet, 702 The server MUST NOT return the child resource if d= 't' 704 The server MUST return the child resource if d= 'a'. 706 If this Uri-Query option is not present, the default value is 't'. 708 4.2.3. GET 710 A request to read the values of a data node instance is sent with a 711 CoAP GET message. A base64-encoded instance-identifier in SID-form 712 is specified in the URI path prefixed with the example path /c. 714 FORMAT: 715 GET /c/instance-identifier 717 2.05 Content (Content-Format: application/yang-data+cbor) 718 CBOR map of SID, instance-value 720 The returned payload contains the CBOR encoding of the specified data 721 node instance value. 723 4.2.3.1. GET Examples 725 Using for example the current-datetime leaf from module ietf-system 726 [RFC7317], a request is sent to retrieve the value of 'system- 727 state/clock/current-datetime' specified in container system-state. 728 The SID of 'system-state/clock/current-datetime' is 1723, encoded in 729 base64 according to Section 2.2, yields a7. The response to the 730 request returns the CBOR map with the key set to the SID of the 731 requested data node (i.e. 1723) and the value encoded using a 'text 732 string' as defined in [I-D.ietf-core-yang-cbor] section 6.4. 734 REQ: GET example.com/c/a7 736 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 737 { 738 1723 : "2014-10-26T12:16:31Z" 739 } 741 The next example represents the retrieval of a YANG container. In 742 this case, the CoMI client performs a GET request on the clock 743 container (SID = 1721; base64: a5). The container returned is 744 encoded using a CBOR map as specified by [I-D.ietf-core-yang-cbor] 745 section 4.2. 747 REQ: GET example.com/c/a5 749 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 750 { 751 1721 : { 752 +2 : "2014-10-26T12:16:51Z", / current-datetime SID 1723 / 753 +1 : "2014-10-21T03:00:00Z" / boot-datetime SID 1722 / 754 } 755 } 757 Figure 3 759 This example shows the retrieval of the /interfaces/interface YANG 760 list accessed using SID 1533 (base64: X9). The return payload is 761 encoded using a CBOR array as specified by [I-D.ietf-core-yang-cbor] 762 section 4.4.1 containing 2 instances. 764 REQ: GET example.com/c/X9 766 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 767 { 768 1533 : [ 769 { 770 +4 : "eth0", / name (SID 1537) / 771 +1 : "Ethernet adaptor", / description (SID 1534) / 772 +5 : 1880, / type, (SID 1538) identity / 773 / ethernetCsmacd (SID 1880) / 774 +2 : true / enabled ( SID 1535) / 775 }, 776 { 777 +4 : "eth1", / name (SID 1537) / 778 +1 : "Ethernet adaptor", / description (SID 1534) / 779 +5 : 1880, / type, (SID 1538) identity / 780 / ethernetCsmacd (SID 1880) / 781 +2 : false / enabled ( SID 1535) / 782 } 783 ] 784 } 786 To retrieve a specific instance within the /interfaces/interface YANG 787 list, the CoMI client adds the key of the targeted instance in its 788 CoAP request using the 'k' URI-Query. The return payload containing 789 the instance requested is encoded using a CBOR array as specified by 790 [I-D.ietf-core-yang-cbor] section 4.4.1. 792 REQ: GET example.com/c/X9?k="eth0" 794 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 795 { 796 1533 : [ 797 { 798 +4 : "eth0", / name (SID 1537) / 799 +1 : "Ethernet adaptor", / description (SID 1534) / 800 +5 : 1880, / type, (SID 1538) identity / 801 / ethernetCsmacd (SID 1880) / 802 +2 : true / enabled ( SID 1535) / 803 } 804 ] 805 } 807 It is equally possible to select a leaf of a specific instance of a 808 list. The example below requests the description leaf (SID=1534, 809 base64: X-) within the interface list corresponding to the interface 810 name "eth0". The returned value is encoded in CBOR based on the 811 rules specified by [I-D.ietf-core-yang-cbor] section 6.4. 813 REQ: GET example.com/c/X-?k="eth0" 815 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 816 { 817 1534 : "Ethernet adaptor" 818 } 820 4.2.4. FETCH 822 The FETCH is used to retrieve multiple data node instance values. 823 The FETCH request payload contains the list of instance identifier of 824 the data node instances requested. 826 The return response payload contains a list of data node instance 827 values in the same order as requested. A CBOR null is returned for 828 each data node requested by the client, not supported by the server 829 or not currently instantiated. 831 For compactness, indexes of the list instance identifiers returned by 832 the FETCH response SHOULD be elided, only the SID is provided. In 833 this case, the format of each entry within the CBOR array of the 834 FETCH response is identical to the format as a GET response. 836 FORMAT: 837 FETCH /c (Content-Format: application/yang-identifiers+cbor) 838 CBOR array of instance-identifier 840 2.05 Content (Content-Format: application/yang-instances+cbor) 841 CBOR array of CBOR map of instance-identifier, instance-value 843 4.2.4.1. FETCH examples 845 This example uses the current-datetime leaf from module ietf-system 846 [RFC7317] and the interface list from module ietf-interfaces 847 [RFC7223]. In this example the value of current-datetime (SID 1723) 848 and the interface list (SID 1533) instance identified with 849 name="eth0" are queried. 851 REQ: FETCH /c (Content-Format: application/yang-identifiers+cbor) 852 [ 853 1723, / current-datetime (SID 1723) / 854 [1533, "eth0"] / interface (SID 1533) with name = "eth0" / 855 ] 857 RES: 2.05 Content (Content-Format: application/yang-instances+cbor) 858 [ 859 { 860 1723 : "2014-10-26T12:16:31Z" / current-datetime (SID 1723) / 861 }, 862 { 863 1533 : { 864 +4 : "eth0", / name (SID 1537) / 865 +1 : "Ethernet adaptor", / description (SID 1534) / 866 +5 : 1880, / type (SID 1538), identity / 867 / ethernetCsmacd (SID 1880) / 868 +2 : true / enabled (SID 1535) / 869 } 870 } 871 ] 873 4.3. Data Editing 875 CoMI allows datastore contents to be created, modified and deleted 876 using CoAP methods. 878 4.3.1. Data Ordering 880 A CoMI server SHOULD preserve the relative order of all user-ordered 881 list and leaf-list entries that are received in a single edit 882 request. These YANG data node types are encoded as CBOR arrays so 883 messages will preserve their order. 885 4.3.2. POST 887 The CoAP POST operation is used in CoMI for creation of data node 888 resources and the invocation of "ACTION" and "RPC" resources. Refer 889 to Section 4.6 for details on "ACTION" and "RPC" resources. 891 A request to create a data node resource is sent with a CoAP POST 892 message. The URI specifies the data node to be instantiated at the 893 exception of list instances. In this case, for compactness, the URI 894 specifies the list for which an instance is created. 896 FORMAT: 897 POST /c/ 898 (Content-Format: application/yang-data+cbor) 899 CBOR map of SID, instance-value 901 2.01 Created 903 If the data node resource already exists, then the POST request MUST 904 fail and a "4.09 Conflict" response code MUST be returned 906 4.3.2.1. Post example 908 The example uses the interface list from module ietf-interfaces 909 [RFC7223]. This example creates a new list instance within the 910 interface list (SID = 1533): 912 REQ: POST /c/X9 (Content-Format: application/yang-data+cbor) 913 { 914 1533 : [ 915 { 916 +4 : "eth5", / name (SID 1537) / 917 +1 : "Ethernet adaptor", / description (SID 1534) / 918 +5 : 1880, / type (SID 1538), identity / 919 / ethernetCsmacd (SID 1880) / 920 +2 : true / enabled (SID 1535) / 921 } 922 ] 923 } 925 RES: 2.01 Created 927 4.3.3. PUT 929 A data node resource instance is created or replaced with the PUT 930 method. A request to set the value of a data node instance is sent 931 with a CoAP PUT message. 933 FORMAT: 934 PUT /c/ 935 (Content-Format: application/yang-data+cbor) 936 CBOR map of SID, instance-value 938 2.01 Created 940 4.3.3.1. PUT example 942 The example uses the interface list from module ietf-interfaces 943 [RFC7223]. Example updates the instance of the list interface (SID = 944 1533) with key name="eth0": 946 REQ: PUT /c/X9?k="eth0" (Content-Format: application/yang-data+cbor) 947 { 948 1533 : [ 949 { 950 +4 : "eth0", / name (SID 1537) / 951 +1 : "Ethernet adaptor", / description (SID 1534) / 952 +5 : 1880, / type (SID 1538), identity / 953 / ethernetCsmacd (SID 1880) / 954 +2 : true / enabled (SID 1535) / 955 } 956 ] 957 } 959 RES: 2.04 Changed 961 4.3.4. iPATCH 963 One or multiple data node instances are replaced with the idempotent 964 CoAP iPATCH method [RFC8132]. 966 There are no Uri-Query options for the iPATCH method. 968 The processing of the iPATCH command is specified by Content-Format 969 'application/yang-instances+cbor'. In summary, if the CBOR patch 970 payload contains a data node instance that is not present in the 971 target, this instance is added. If the target contains the specified 972 instance, the content of this instance is replaced with the value of 973 the payload. A null value indicates the removal of an existing data 974 node instance. 976 FORMAT: 977 iPATCH /c (Content-Format: application/yang-instances+cbor) 978 CBOR array of CBOR map of instance-identifier, instance-value 980 2.04 Changed 982 4.3.4.1. iPATCH example 984 In this example, a CoMI client requests the following operations: 986 o Set "/system/ntp/enabled" (SID 1755) to true. 988 o Remove the server "tac.nrc.ca" from the "/system/ntp/server" (SID 989 1756) list. 991 o Add/set the server "NTP Pool server 2" to the list "/system/ntp/ 992 server" (SID 1756). 994 REQ: iPATCH /c (Content-Format: application/yang-instances+cbor) 995 [ 996 { 997 1755 : true / enabled (SID 1755) / 998 }, 999 { 1000 [1756, "tac.nrc.ca"] : null / server (SID 1756) / 1001 }, 1002 { 1003 1756 : { / server (SID 1756) / 1004 +3 : "tic.nrc.ca", / name (SID 1759) / 1005 +4 : true, / prefer (SID 1760) / 1006 +5 : { / udp (SID 1761) / 1007 +1 : "132.246.11.231" / address (SID 1762) / 1008 } 1009 } 1010 } 1011 ] 1013 RES: 2.04 Changed 1015 4.3.5. DELETE 1017 A data node resource is deleted with the DELETE method. 1019 FORMAT: 1020 Delete /c/ 1022 2.02 Deleted 1024 4.3.5.1. DELETE example 1026 This example uses the interface list from module ietf-interfaces 1027 [RFC7223]. This example deletes an instance of the interface list 1028 (SID = 1533): 1030 REQ: DELETE /c/X9?k="eth0" 1032 RES: 2.02 Deleted 1034 4.4. Full datastore access 1036 The methods GET, PUT, POST, and DELETE can be used to request, 1037 replace, create, and delete a whole datastore respectively. 1039 FORMAT: 1040 GET /c 1042 2.05 Content (Content-Format: application/yang-data+cbor) 1043 CBOR map of SID, instance-value 1045 FORMAT: 1046 PUT /c (Content-Format: application/yang-data+cbor) 1047 CBOR map of SID, instance-value 1049 2.04 Changed 1051 FORMAT: 1052 POST /c (Content-Format: application/yang-data+cbor) 1053 CBOR map of SID, instance-value 1055 2.01 Created 1057 FORMAT: 1058 DELETE /c 1060 2.02 Deleted 1062 The content of the CBOR map represents the complete datastore of the 1063 server at the GET indication of after a successful processing of a 1064 PUT or POST request. 1066 4.4.1. Full datastore examples 1068 The example uses the interface list from module ietf-interfaces 1069 [RFC7223] and the clock container from module ietf-system [RFC7317]. 1070 We assume that the datastore contains two modules ietf-system (SID 1071 1700) and ietf-interfaces (SID 1500); they contain the 'interface' 1072 list (SID 1533) with one instance and the 'clock' container (SID 1073 1721). After invocation of GET, a CBOR map with data nodes from 1074 these two modules is returned: 1076 REQ: GET /c 1078 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 1079 { 1080 1721 : { / Clock (SID 1721) / 1081 +2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) / 1082 +1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) / 1083 }, 1084 1533 : [ 1085 { / interface (SID 1533) / 1086 +4 : "eth0", / name (SID 1537) / 1087 +1 : "Ethernet adaptor", / description (SID 1534) / 1088 +5 : 1880, / type (SID 1538), identity: / 1089 / ethernetCsmacd (SID 1880) / 1090 +2 : true / enabled (SID 1535) / 1091 } 1092 ] 1093 } 1095 4.5. Event stream 1097 Event notification is an essential function for the management of 1098 servers. CoMI allows notifications specified in YANG [RFC5277] to be 1099 reported to a list of clients. The recommended path of the default 1100 event stream is /s. The server MAY support additional event stream 1101 resources to address different notification needs. 1103 Reception of notification instances is enabled with the CoAP Observe 1104 [RFC7641] function. Clients subscribe to the notifications by 1105 sending a GET request with an "Observe" option, specifying the /s 1106 resource when the default stream is selected. 1108 Each response payload carries one or multiple notifications. The 1109 number of notifications reported, and the conditions used to remove 1110 notifications from the reported list is left to implementers. When 1111 multiple notifications are reported, they MUST be ordered starting 1112 from the newest notification at index zero. 1114 The format of notification without any content is a null value. The 1115 format of single notification is defined in [I-D.ietf-core-yang-cbor] 1116 section 4.2.1. For multiple notifications the format is an array 1117 where each element is a single notification as described in 1118 [I-D.ietf-core-yang-cbor] section 4.2.1. 1120 FORMAT: 1121 GET / Observe(0) 1123 2.05 Content (Content-Format: application/yang-instances+cbor) 1124 A CBOR map or a 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 An example implementation is: 1131 Every time an event is generated, the generated notification 1132 instance is appended to the chosen stream(s). After an 1133 aggregation period, which may be adjusted using an exclusion delay 1134 and limited by the maximum number of notifications supported, the 1135 content of the instance is sent to all clients observing the 1136 modified stream. 1138 4.5.1. Notify Examples 1140 Let suppose the server generates the example-port-fault event as 1141 defined below. 1143 module example-port { 1144 ... 1145 notification example-port-fault { // SID 60010 1146 description 1147 "Event generated if a hardware fault is detected"; 1148 leaf port-name { // SID 60011 1149 type string; 1150 } 1151 leaf port-fault { // SID 60012 1152 type string; 1153 } 1154 } 1155 } 1157 By executing a GET on the /s resource the client receives the 1158 following response: 1160 REQ: GET /s Observe(0) 1162 RES: 2.05 Content (Content-Format: application/yang-tree+cbor) 1163 Observe(12) 1164 [ 1165 { 1166 60010 : { / example-port-fault (SID 60010) / 1167 +1 : "0/4/21", / port-name (SID 60011) / 1168 +2 : "Open pin 2" / port-fault (SID 60012) / 1169 } 1170 }, 1171 { 1172 60010 : { / example-port-fault (SID 60010) / 1173 +1 : "1/4/21", / port-name (SID 60011) / 1174 +2 : "Open pin 5" / port-fault (SID 60012) / 1175 } 1176 } 1177 ] 1179 In the example, the request returns a success response with the 1180 contents of the last two generated events. Consecutively the server 1181 will regularly notify the client when a new event is generated. 1183 To check that the client is still alive, the server MUST send 1184 Confirmable Message periodically. When the client does not confirm 1185 the notification from the server, the server will remove the client 1186 from the list of observers [RFC7641]. 1188 4.5.2. The 'f' Uri-Query option 1190 The 'f' (filter) option is used to indicate which subset of all 1191 possible notifications is of interest. If not present, all events 1192 notifications supported by the event stream are reported. 1194 When not supported by a CoMI server, this option shall be ignored, 1195 all events notifications are reported independently of the presence 1196 and content of the 'f' (filter) option. 1198 When present, this option contains a comma separated list of 1199 notification SIDs. For example, the following request returns 1200 notifications 60010 and 60020. 1202 REQ: GET /s?f=60010,60020 Observe(0) 1204 4.6. RPC statements 1206 The YANG "action" and "RPC" statements specify the execution of a 1207 Remote procedure Call (RPC) in the server. It is invoked using a 1208 POST method to an "Action" or "RPC" resource instance. 1210 The request payload contains the values assigned to the input 1211 container when specified. The response payload contains the values 1212 of the output container when specified. Both the input and output 1213 containers are encoded in CBOR using the rules defined in 1214 [I-D.ietf-core-yang-cbor] section 4.2.1. 1216 The returned success response code is 2.05 Content. 1218 FORMAT: 1219 POST /c/ 1220 (Content-Format: application/yang-data+cbor) 1221 CBOR map of SID, instance-value 1223 2.05 Content (Content-Format: application/yang-data+cbor) 1224 CBOR map of SID, instance-value 1226 4.6.1. RPC Example 1228 The example is based on the YANG action "reset" as defined in 1229 [RFC7950] section 7.15.3 and annotated below with SIDs. 1231 module example-server-farm { 1232 yang-version 1.1; 1233 namespace "urn:example:server-farm"; 1234 prefix "sfarm"; 1236 import ietf-yang-types { 1237 prefix "yang"; 1238 } 1240 list server { // SID 60000 1241 key name; 1242 leaf name { // SID 60001 1243 type string; 1244 } 1245 action reset { // SID 60002 1246 input { 1247 leaf reset-at { // SID 60003 1248 type yang:date-and-time; 1249 mandatory true; 1250 } 1251 } 1252 output { 1253 leaf reset-finished-at { // SID 60004 1254 type yang:date-and-time; 1255 mandatory true; 1256 } 1257 } 1258 } 1259 } 1260 } 1262 This example invokes the 'reset' action (SID 60002, base64: Opq), of 1263 the server instance with name equal to "myserver". 1265 REQ: POST /c/Opq?k="myserver" 1266 (Content-Format: application/yang-data+cbor) 1267 { 1268 60002 : { 1269 +1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / 1270 } 1271 } 1273 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 1274 { 1275 60002 : { 1276 +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ 1277 } 1278 } 1280 5. Use of Block-wise Transfers 1282 The CoAP protocol provides reliability by acknowledging the UDP 1283 datagrams. However, when large pieces of data need to be 1284 transported, datagrams get fragmented, thus creating constraints on 1285 the resources in the client, server and intermediate routers. The 1286 block option [RFC7959] allows the transport of the total payload in 1287 individual blocks of which the size can be adapted to the underlying 1288 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1289 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1290 acknowledged to guarantee reliability. 1292 Notice that the Block mechanism splits the data at fixed positions, 1293 such that individual data fields may become fragmented. Therefore, 1294 assembly of multiple blocks may be required to process the complete 1295 data field. 1297 Beware of race conditions. Blocks are filled one at a time and care 1298 should be taken that the whole data representation is sent in 1299 multiple blocks sequentially without interruption. On the server, 1300 values are changed, lists are re-ordered, extended or reduced. When 1301 these actions happen during the serialization of the contents of the 1302 resource, the transported results do not correspond with a state 1303 having occurred in the server; or worse the returned values are 1304 inconsistent. For example: array length does not correspond with the 1305 actual number of items. It may be advisable to use Indefinite-length 1306 CBOR arrays and maps, which are foreseen for data streaming purposes. 1308 6. Application Discovery 1310 Two application discovery mechanisms are supported by CoMI, the YANG 1311 library data model as defined by [I-D.veillette-core-yang-library] 1312 and the CORE resource discovery [RFC6690]. Implementers may choose 1313 to implement one or the other or both. 1315 6.1. YANG library 1317 The YANG library data model [I-D.veillette-core-yang-library] 1318 provides a high level description of the resources available. The 1319 YANG library contains the list of modules, features and deviations 1320 supported by the CoMI server. From this information, CoMI clients 1321 can infer the list of data nodes supported and the interaction model 1322 to be used to access them. This module also contains the list of 1323 datastores implemented. 1325 As described in [RFC6690], the location of the YANG library can be 1326 found by sending a GET request to "/.well-known/core" including a 1327 resource type (RT) parameter with the value "core.c.yl". Upon 1328 success, the return payload will contain the root resource of the 1329 YANG library module. 1331 The following example assumes that the SID of the YANG library is 1332 2351 (kv encoded as specified in Section 2.2). 1334 REQ: GET /.well-known/core?rt=core.c.yl 1336 RES: 2.05 Content (Content-Format: application/link-format) 1337 ;rt="core.c.yl" 1339 6.2. Resource Discovery 1341 As some CoAP interfaces and services might not support the YANG 1342 library interface and still be interested to discover resources that 1343 are available, implementations MAY choose to support discovery of all 1344 available resources using "/.well-known/core" as defined by 1345 [RFC6690]. 1347 6.2.1. Datastore Resource Discovery 1349 The presence and location of (path to) each datastore implemented by 1350 the CoMI server can be discovered by sending a GET request to 1351 "/.well-known/core" including a resource type (RT) parameter with the 1352 value "core.c.ds". 1354 Upon success, the return payload contains the list of datastore 1355 resources. 1357 Each datastore returned is further qualified using the "ds" Link- 1358 Format attribute. This attribute is set to the SID assigned to the 1359 datastore identity. When a unified datastore is implemented, the ds 1360 attribute is set to 1029 as specified in Appendix B. For other 1361 examples of datastores, see the Network Management Datastore 1362 Architecture (NMDA) [RFC7950]. 1364 link-extension = ( "ds" "=" sid ) ) 1365 ; SID assigned to the datastore identity 1366 sid = 1*DIGIT 1368 For example: 1370 REQ: GET /.well-known/core?rt=core.c.ds 1372 RES: 2.05 Content (Content-Format: application/link-format) 1373 ; rt="core.c.ds";ds= 1029 1375 6.2.2. Data node Resource Discovery 1377 If implemented, the presence and location of (path to) each data node 1378 implemented by the CoMI server are discovered by sending a GET 1379 request to "/.well-known/core" including a resource type (RT) 1380 parameter with the value "core.c.dn". 1382 Upon success, the return payload contains the SID assigned to each 1383 data node and their location. 1385 The example below shows the discovery of the presence and location of 1386 data nodes. Data nodes '/ietf-system:system-state/clock/boot- 1387 datetime' (SID 1722) and '/ietf-system:system-state/clock/current- 1388 datetime' (SID 1723) are returned. 1390 REQ: GET /.well-known/core?rt=core.c.dn 1392 RES: 2.05 Content (Content-Format: application/link-format) 1393 ;rt="core.c.dn", 1394 ;rt="core.c.dn" 1396 Without additional filtering, the list of data nodes may become 1397 prohibitively long. If this is the case implementations SHOULD 1398 support a way to obtain all links using multiple GET requests (for 1399 example through some form of pagination). 1401 6.2.3. Event stream Resource Discovery 1403 The presence and location of (path to) each event stream implemented 1404 by the CoMI server are discovered by sending a GET request to 1405 "/.well-known/core" including a resource type (RT) parameter with the 1406 value "core.c.es". 1408 Upon success, the return payload contains the list of event stream 1409 resources. 1411 For example: 1413 REQ: GET /.well-known/core?rt=core.c.es 1415 RES: 2.05 Content (Content-Format: application/link-format) 1416 ;rt="core.c.es" 1418 7. Error Handling 1420 In case a request is received which cannot be processed properly, the 1421 CoMI server MUST return an error response. This error response MUST 1422 contain a CoAP 4.xx or 5.xx response code. 1424 Errors returned by a CoMI server can be broken into two categories, 1425 those associated to the CoAP protocol itself and those generated 1426 during the validation of the YANG data model constrains as described 1427 in [RFC7950] section 8. 1429 The following list of common CoAP errors should be implemented by 1430 CoMI servers. This list is not exhaustive, other errors defined by 1431 CoAP and associated RFCs may be applicable. 1433 o Error 4.01 (Unauthorized) is returned by the CoMI server when the 1434 CoMI client is not authorized to perform the requested action on 1435 the targeted resource (i.e. data node, datastore, rpc, action or 1436 event stream). 1438 o Error 4.02 (Bad Option) is returned by the CoMI server when one or 1439 more CoAP options are unknown or malformed. 1441 o Error 4.04 (Not Found) is returned by the CoMI server when the 1442 CoMI client is requesting a non-instantiated resource (i.e. data 1443 node, datastore, rpc, action or event stream). 1445 o Error 4.05 (Method Not Allowed) is returned by the CoMI server 1446 when the CoMI client is requesting a method not supported on the 1447 targeted resource. (e.g. GET on an rpc, PUT or POST on a data 1448 node with "config" set to false). 1450 o Error 4.08 (Request Entity Incomplete) is returned by the CoMI 1451 server if one or multiple blocks of a block transfer request is 1452 missing, see [RFC7959] for more details. 1454 o Error 4.13 (Request Entity Too Large) may be returned by the CoMI 1455 server during a block transfer request, see [RFC7959] for more 1456 details. 1458 o Error 4.15 (Unsupported Content-Format) is returned by the CoMI 1459 server when the Content-Format used in the request does not match 1460 those specified in section Section 2.4. 1462 The CoMI server MUST also enforce the different constraints 1463 associated to the YANG data models implemented. These constraints 1464 are described in [RFC7950] section 8. These errors are reported 1465 using the CoAP error code 4.00 (Bad Request) and may have the 1466 following error container as payload. The YANG definition and 1467 associated .sid file are available in Appendix A and Appendix B. The 1468 error container is encoded using the encoding rules of a YANG data 1469 template as defined in [I-D.ietf-core-yang-cbor] section 5. 1471 +--rw error! 1472 +--rw error-tag identityref 1473 +--rw error-app-tag? identityref 1474 +--rw error-data-node? instance-identifier 1475 +--rw error-message? string 1477 The following 'error-tag' and 'error-app-tag' are defined by the 1478 ietf-comi YANG module, these tags are implemented as YANG identity 1479 and can be extended as needed. 1481 o error-tag 'operation-failed' is returned by the CoMI server when 1482 the operation request cannot be processed successfully. 1484 * error-app-tag 'malformed-message' is returned by the CoMI 1485 server when the payload received from the CoMI client does not 1486 contain a well-formed CBOR content as defined in [RFC7049] 1487 section 3.3 or does not comply with the CBOR structure defined 1488 within this document. 1490 * error-app-tag 'data-not-unique' is returned by the CoMI server 1491 when the validation of the 'unique' constraint of a list or 1492 leaf-list fails. 1494 * error-app-tag 'too-many-elements' is returned by the CoMI 1495 server when the validation of the 'max-elements' constraint of 1496 a list or leaf-list fails. 1498 * error-app-tag 'too-few-elements' is returned by the CoMI server 1499 when the validation of the 'min-elements' constraint of a list 1500 or leaf-list fails. 1502 * error-app-tag 'must-violation' is returned by the CoMI server 1503 when the restrictions imposed by a 'must' statement are 1504 violated. 1506 * error-app-tag 'duplicate' is returned by the CoMI server when a 1507 client tries to create a duplicate list or leaf-list entry. 1509 o error-tag 'invalid-value' is returned by the CoMI server when the 1510 CoMI client tries to update or create a leaf with a value encoded 1511 using an invalid CBOR datatype or if the 'range', 'length', 1512 'pattern' or 'require-instance' constrain is not fulfilled. 1514 * error-app-tag 'invalid-datatype' is returned by the CoMI server 1515 when CBOR encoding does not follow the rules set by the YANG 1516 Build-In type or when the value is incompatible with it (e.g. a 1517 value greater than 127 for an int8, undefined enumeration). 1519 * error-app-tag 'not-in-range' is returned by the CoMI server 1520 when the validation of the 'range' property fails. 1522 * error-app-tag 'invalid-length' is returned by the CoMI server 1523 when the validation of the 'length' property fails. 1525 * error-app-tag 'pattern-test-failed' is returned by the CoMI 1526 server when the validation of the 'pattern' property fails. 1528 o error-tag 'missing-element' is returned by the CoMI server when 1529 the operation requested by a CoMI client fails to comply with the 1530 'mandatory' constraint defined. The 'mandatory' constraint is 1531 enforced for leafs and choices, unless the node or any of its 1532 ancestors have a 'when' condition or 'if-feature' expression that 1533 evaluates to 'false'. 1535 * error-app-tag 'missing-key' is returned by the CoMI server to 1536 further qualify a missing-element error. This error is 1537 returned when the CoMI client tries to create or list instance, 1538 without all the 'key' specified or when the CoMI client tries 1539 to delete a leaf listed as a 'key'. 1541 * error-app-tag 'missing-input-parameter' is returned by the CoMI 1542 server when the input parameters of an RPC or action are 1543 incomplete. 1545 o error-tag 'unknown-element' is returned by the CoMI server when 1546 the CoMI client tries to access a data node of a YANG module not 1547 supported, of a data node associated to an 'if-feature' expression 1548 evaluated to 'false' or to a 'when' condition evaluated to 1549 'false'. 1551 o error-tag 'bad-element' is returned by the CoMI server when the 1552 CoMI client tries to create data nodes for more than one case in a 1553 choice. 1555 o error-tag 'data-missing' is returned by the CoMI server when a 1556 data node required to accept the request is not present. 1558 * error-app-tag 'instance-required' is returned by the CoMI 1559 server when a leaf of type 'instance-identifier' or 'leafref' 1560 marked with require-instance set to 'true' refers to an 1561 instance that does not exist. 1563 * error-app-tag 'missing-choice' is returned by the CoMI server 1564 when no nodes exist in a mandatory choice. 1566 o error-tag 'error' is returned by the CoMI server when an 1567 unspecified error has occurred. 1569 For example, the CoMI server might return the following error. 1571 RES: 4.00 Bad Request (Content-Format: application/yang-data+cbor) 1572 { 1573 1024 : { 1574 +4 : 1011, / error-tag (SID 1028) / 1575 / = invalid-value (SID 1011) / 1576 +1 : 1018, / error-app-tag (SID 1025) / 1577 / = not-in-range (SID 1018) / 1578 +2 : 1740, / error-data-node (SID 1026) / 1579 / = timezone-utc-offset (SID 1740) / 1580 +3 : "maximum value exceeded" / error-message (SID 1027) / 1581 } 1582 } 1584 8. Security Considerations 1586 For secure network management, it is important to restrict access to 1587 configuration variables only to authorized parties. CoMI re-uses the 1588 security mechanisms already available to CoAP, this includes DTLS 1589 [RFC6347] for protected access to resources, as well suitable 1590 authentication and authorization mechanisms. 1592 Among the security decisions that need to be made are selecting 1593 security modes and encryption mechanisms (see [RFC7252]). 1595 In addition, mechanisms for authentication and authorization may need 1596 to be selected if not provided with the security mode. 1598 9. IANA Considerations 1600 9.1. Resource Type (rt=) Link Target Attribute Values Registry 1602 This document adds the following resource type to the "Resource Type 1603 (rt=) Link Target Attribute Values", within the "Constrained RESTful 1604 Environments (CoRE) Parameters" registry. 1606 +-----------+---------------------+-----------+ 1607 | Value | Description | Reference | 1608 +-----------+---------------------+-----------+ 1609 | core.c.ds | YANG datastore | RFC XXXX | 1610 | | | | 1611 | core.c.dn | YANG data node | RFC XXXX | 1612 | | | | 1613 | core.c.yl | YANG module library | RFC XXXX | 1614 | | | | 1615 | core.c.es | YANG event stream | RFC XXXX | 1616 +-----------+---------------------+-----------+ 1618 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1619 note. 1621 9.2. CoAP Content-Formats Registry 1623 This document adds the following Content-Format to the "CoAP Content- 1624 Formats", within the "Constrained RESTful Environments (CoRE) 1625 Parameters" registry. 1627 +-----------------------------------+------------+------+-----------+ 1628 | Media Type | Content | ID | Reference | 1629 | | Coding | | | 1630 +-----------------------------------+------------+------+-----------+ 1631 | application/yang-data+cbor | | TBD1 | RFC XXXX | 1632 | | | | | 1633 | application/yang-identifiers+cbor | | TBD2 | RFC XXXX | 1634 | | | | | 1635 | application/yang-instances+cbor | | TBD3 | RFC XXXX | 1636 +-----------------------------------+------------+------+-----------+ 1638 // RFC Ed.: replace TBD1, TBD2 and TBD3 with assigned IDs and remove 1639 this note. // RFC Ed.: replace RFC XXXX with this RFC number and 1640 remove this note. 1642 9.3. Media Types Registry 1644 This document adds the following media types to the "Media Types" 1645 registry. 1647 +-----------------------+----------------------------+-----------+ 1648 | Name | Template | Reference | 1649 +-----------------------+----------------------------+-----------+ 1650 | yang-data+cbor | application/yang-data+cbor | RFC XXXX | 1651 | | | | 1652 | yang-identifiers+cbor | application/ | RFC XXXX | 1653 | | | | 1654 | | yang-identifiers+cbor | | 1655 | | | | 1656 | yang-instances+cbor | application/ | RFC XXXX | 1657 | | | | 1658 | | yang-instances+cbor | | 1659 +-----------------------+----------------------------+-----------+ 1661 Each of these media types share the following information: 1663 o Subtype name: 1665 o Required parameters: N/A 1667 o Optional parameters: N/A 1669 o Encoding considerations: binary 1671 o Security considerations: See the Security Considerations section 1672 of RFC XXXX 1674 o Interoperability considerations: N/A 1676 o Published specification: RFC XXXX 1678 o Applications that use this media type: CoMI 1680 o Fragment identifier considerations: N/A 1682 o Additional information: 1684 * Deprecated alias names for this type: N/A 1686 * Magic number(s): N/A 1688 * File extension(s): N/A 1690 * Macintosh file type code(s): N/A 1692 o Person & email address to contact for further information: 1693 iesg&ietf.org 1695 o Intended usage: COMMON 1697 o Restrictions on usage: N/A 1699 o Author: Michel Veillette, ietf&augustcellars.com 1701 o Change Controller: IESG 1703 o Provisional registration? No 1705 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1706 note. 1708 10. Acknowledgements 1710 We are very grateful to Bert Greevenbosch who was one of the original 1711 authors of the CoMI specification. 1713 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1714 transported under SNMP. Carsten Bormann has given feedback on the 1715 use of CBOR. 1717 The draft has benefited from comments (alphabetical order) by Rodney 1718 Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy 1719 Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes 1720 Tschofenig, Michael Verschoor, and Thomas Watteyne. 1722 11. References 1724 11.1. Normative References 1726 [I-D.ietf-core-sid] 1727 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 1728 iDentifier (SID)", draft-ietf-core-sid-07 (work in 1729 progress), July 2019. 1731 [I-D.ietf-core-yang-cbor] 1732 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 1733 Data Modeled with YANG", draft-ietf-core-yang-cbor-10 1734 (work in progress), April 2019. 1736 [I-D.veillette-core-yang-library] 1737 Veillette, M. and I. Petrov, "Constrained YANG Module 1738 Library", draft-veillette-core-yang-library-05 (work in 1739 progress), July 2019. 1741 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1742 Requirement Levels", BCP 14, RFC 2119, 1743 DOI 10.17487/RFC2119, March 1997, 1744 . 1746 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1747 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1748 . 1750 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1751 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1752 . 1754 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1755 and A. Bierman, Ed., "Network Configuration Protocol 1756 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1757 . 1759 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1760 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1761 . 1763 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1764 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1765 October 2013, . 1767 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1768 Application Protocol (CoAP)", RFC 7252, 1769 DOI 10.17487/RFC7252, June 2014, 1770 . 1772 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1773 Application Protocol (CoAP)", RFC 7641, 1774 DOI 10.17487/RFC7641, September 2015, 1775 . 1777 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1778 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1779 . 1781 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1782 the Constrained Application Protocol (CoAP)", RFC 7959, 1783 DOI 10.17487/RFC7959, August 2016, 1784 . 1786 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1787 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1788 . 1790 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1791 FETCH Methods for the Constrained Application Protocol 1792 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1793 . 1795 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1796 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1797 May 2017, . 1799 11.2. Informative References 1801 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1802 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1803 January 2012, . 1805 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1806 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1807 . 1809 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1810 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1811 . 1813 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1814 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1815 2014, . 1817 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1818 and R. Wilton, "Network Management Datastore Architecture 1819 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1820 . 1822 Appendix A. ietf-comi YANG module 1824 file "ietf-comi@2019-03-28.yang" 1825 module ietf-comi { 1826 yang-version 1.1; 1828 namespace "urn:ietf:params:xml:ns:yang:ietf-comi"; 1829 prefix comi; 1831 import ietf-datastores { 1832 prefix ds; 1833 } 1835 import ietf-restconf { 1836 prefix rc; 1837 description 1838 "This import statement is required to access 1839 the yang-data extension defined in RFC 8040."; 1840 reference "RFC 8040: RESTCONF Protocol"; 1841 } 1843 organization 1844 "IETF Core Working Group"; 1846 contact 1847 "Michel Veillette 1848 1850 Alexander Pelov 1851 1853 Peter van der Stok 1854 1856 Andy Bierman 1857 "; 1859 description 1860 "This module contains the different definitions required 1861 by the CoMI protocol."; 1863 revision 2019-03-28 { 1864 description 1865 "Initial revision."; 1866 reference 1867 "[I-D.ietf-core-comi] CoAP Management Interface"; 1868 } 1870 identity unified { 1871 base ds:datastore; 1872 description 1873 "Identifier of the unified configuration and operational 1874 state datastore."; 1875 } 1877 identity error-tag { 1878 description 1879 "Base identity for error-tag."; 1880 } 1882 identity operation-failed { 1883 base error-tag; 1884 description 1885 "Returned by the CoMI server when the operation request 1886 can't be processed successfully."; 1887 } 1889 identity invalid-value { 1890 base error-tag; 1891 description 1892 "Returned by the CoMI server when the CoMI client tries to 1893 update or create a leaf with a value encoded using an 1894 invalid CBOR datatype or if the 'range', 'length', 1895 'pattern' or 'require-instance' constrain is not 1896 fulfilled."; 1897 } 1899 identity missing-element { 1900 base error-tag; 1901 description 1902 "Returned by the CoMI server when the operation requested 1903 by a CoMI client fails to comply with the 'mandatory' 1904 constraint defined. The 'mandatory' constraint is 1905 enforced for leafs and choices, unless the node or any of 1906 its ancestors have a 'when' condition or 'if-feature' 1907 expression that evaluates to 'false'."; 1908 } 1910 identity unknown-element { 1911 base error-tag; 1912 description 1913 "Returned by the CoMI server when the CoMI client tries to 1914 access a data node of a YANG module not supported, of a 1915 data node associated with an 'if-feature' expression 1916 evaluated to 'false' or to a 'when' condition evaluated 1917 to 'false'."; 1918 } 1920 identity bad-element { 1921 base error-tag; 1922 description 1923 "Returned by the CoMI server when the CoMI client tries to 1924 create data nodes for more than one case in a choice."; 1925 } 1927 identity data-missing { 1928 base error-tag; 1929 description 1930 "Returned by the CoMI server when a data node required to 1931 accept the request is not present."; 1932 } 1933 identity error { 1934 base error-tag; 1935 description 1936 "Returned by the CoMI server when an unspecified error has 1937 occurred."; 1938 } 1940 identity error-app-tag { 1941 description 1942 "Base identity for error-app-tag."; 1943 } 1945 identity malformed-message { 1946 base error-app-tag; 1947 description 1948 "Returned by the CoMI server when the payload received 1949 from the CoMI client don't contain a well-formed CBOR 1950 content as defined in [RFC7049] section 3.3 or don't 1951 comply with the CBOR structure defined within this 1952 document."; 1953 } 1955 identity data-not-unique { 1956 base error-app-tag; 1957 description 1958 "Returned by the CoMI server when the validation of the 1959 'unique' constraint of a list or leaf-list fails."; 1960 } 1962 identity too-many-elements { 1963 base error-app-tag; 1964 description 1965 "Returned by the CoMI server when the validation of the 1966 'max-elements' constraint of a list or leaf-list fails."; 1967 } 1969 identity too-few-elements { 1970 base error-app-tag; 1971 description 1972 "Returned by the CoMI server when the validation of the 1973 'min-elements' constraint of a list or leaf-list fails."; 1974 } 1976 identity must-violation { 1977 base error-app-tag; 1978 description 1979 "Returned by the CoMI server when the restrictions 1980 imposed by a 'must' statement are violated."; 1982 } 1984 identity duplicate { 1985 base error-app-tag; 1986 description 1987 "Returned by the CoMI server when a client tries to create 1988 a duplicate list or leaf-list entry."; 1989 } 1991 identity invalid-datatype { 1992 base error-app-tag; 1993 description 1994 "Returned by the CoMI server when CBOR encoding is 1995 incorect or when the value encoded is incompatible with 1996 the YANG Built-In type. (e.g. value greater than 127 1997 for an int8, undefined enumeration)."; 1998 } 2000 identity not-in-range { 2001 base error-app-tag; 2002 description 2003 "Returned by the CoMI server when the validation of the 2004 'range' property fails."; 2005 } 2007 identity invalid-length { 2008 base error-app-tag; 2009 description 2010 "Returned by the CoMI server when the validation of the 2011 'length' property fails."; 2012 } 2014 identity pattern-test-failed { 2015 base error-app-tag; 2016 description 2017 "Returned by the CoMI server when the validation of the 2018 'pattern' property fails."; 2019 } 2021 identity missing-key { 2022 base error-app-tag; 2023 description 2024 "Returned by the CoMI server to further qualify a 2025 missing-element error. This error is returned when the 2026 CoMI client tries to create or list instance, without all 2027 the 'key' specified or when the CoMI client tries to 2028 delete a leaf listed as a 'key'."; 2029 } 2030 identity missing-input-parameter { 2031 base error-app-tag; 2032 description 2033 "Returned by the CoMI server when the input parameters 2034 of a RPC or action are incomplete."; 2035 } 2037 identity instance-required { 2038 base error-app-tag; 2039 description 2040 "Returned by the CoMI server when a leaf of type 2041 'instance-identifier' or 'leafref' marked with 2042 require-instance set to 'true' refers to an instance 2043 that does not exist."; 2044 } 2046 identity missing-choice { 2047 base error-app-tag; 2048 description 2049 "Returned by the CoMI server when no nodes exist in a 2050 mandatory choice."; 2051 } 2053 rc:yang-data comi-error { 2054 container error { 2055 description 2056 "Optional payload of a 4.00 Bad Request CoAP error."; 2058 leaf error-tag { 2059 type identityref { 2060 base error-tag; 2061 } 2062 mandatory true; 2063 description 2064 "The enumerated error-tag."; 2065 } 2067 leaf error-app-tag { 2068 type identityref { 2069 base error-app-tag; 2070 } 2071 description 2072 "The application-specific error-tag."; 2073 } 2075 leaf error-data-node { 2076 type instance-identifier; 2077 description 2078 "When the error reported is caused by a specific data node, 2079 this leaf identifies the data node in error."; 2080 } 2082 leaf error-message { 2083 type string; 2084 description 2085 "A message describing the error."; 2086 } 2087 } 2088 } 2089 } 2090 2092 Appendix B. ietf-comi .sid file 2094 { 2095 "assignment-ranges": [ 2096 { 2097 "entry-point": 1000, 2098 "size": 100 2099 } 2100 ], 2101 "module-name": "ietf-comi", 2102 "module-revision": "2019-03-28", 2103 "items": [ 2104 { 2105 "namespace": "module", 2106 "identifier": "ietf-comi", 2107 "sid": 1000 2108 }, 2109 { 2110 "namespace": "identity", 2111 "identifier": "bad-element", 2112 "sid": 1001 2113 }, 2114 { 2115 "namespace": "identity", 2116 "identifier": "data-missing", 2117 "sid": 1002 2118 }, 2119 { 2120 "namespace": "identity", 2121 "identifier": "data-not-unique", 2122 "sid": 1003 2123 }, 2124 { 2125 "namespace": "identity", 2126 "identifier": "duplicate", 2127 "sid": 1004 2128 }, 2129 { 2130 "namespace": "identity", 2131 "identifier": "error", 2132 "sid": 1005 2133 }, 2134 { 2135 "namespace": "identity", 2136 "identifier": "error-app-tag", 2137 "sid": 1006 2138 }, 2139 { 2140 "namespace": "identity", 2141 "identifier": "error-tag", 2142 "sid": 1007 2143 }, 2144 { 2145 "namespace": "identity", 2146 "identifier": "instance-required", 2147 "sid": 1008 2148 }, 2149 { 2150 "namespace": "identity", 2151 "identifier": "invalid-datatype", 2152 "sid": 1009 2153 }, 2154 { 2155 "namespace": "identity", 2156 "identifier": "invalid-length", 2157 "sid": 1010 2158 }, 2159 { 2160 "namespace": "identity", 2161 "identifier": "invalid-value", 2162 "sid": 1011 2163 }, 2164 { 2165 "namespace": "identity", 2166 "identifier": "malformed-message", 2167 "sid": 1012 2168 }, 2169 { 2170 "namespace": "identity", 2171 "identifier": "missing-choice", 2172 "sid": 1013 2173 }, 2174 { 2175 "namespace": "identity", 2176 "identifier": "missing-element", 2177 "sid": 1014 2178 }, 2179 { 2180 "namespace": "identity", 2181 "identifier": "missing-input-parameter", 2182 "sid": 1015 2183 }, 2184 { 2185 "namespace": "identity", 2186 "identifier": "missing-key", 2187 "sid": 1016 2188 }, 2189 { 2190 "namespace": "identity", 2191 "identifier": "must-violation", 2192 "sid": 1017 2193 }, 2194 { 2195 "namespace": "identity", 2196 "identifier": "not-in-range", 2197 "sid": 1018 2198 }, 2199 { 2200 "namespace": "identity", 2201 "identifier": "operation-failed", 2202 "sid": 1019 2203 }, 2204 { 2205 "namespace": "identity", 2206 "identifier": "pattern-test-failed", 2207 "sid": 1020 2208 }, 2209 { 2210 "namespace": "identity", 2211 "identifier": "too-few-elements", 2212 "sid": 1021 2213 }, 2214 { 2215 "namespace": "identity", 2216 "identifier": "too-many-elements", 2217 "sid": 1022 2218 }, 2219 { 2220 "namespace": "identity", 2221 "identifier": "unified", 2222 "sid": 1029 2223 }, 2224 { 2225 "namespace": "identity", 2226 "identifier": "unknown-element", 2227 "sid": 1023 2228 }, 2229 { 2230 "namespace": "data", 2231 "identifier": "/ietf-comi:error", 2232 "sid": 1024 2233 }, 2234 { 2235 "namespace": "data", 2236 "identifier": "/ietf-comi:error/error-app-tag", 2237 "sid": 1025 2238 }, 2239 { 2240 "namespace": "data", 2241 "identifier": "/ietf-comi:error/error-data-node", 2242 "sid": 1026 2243 }, 2244 { 2245 "namespace": "data", 2246 "identifier": "/ietf-comi:error/error-message", 2247 "sid": 1027 2248 }, 2249 { 2250 "namespace": "data", 2251 "identifier": "/ietf-comi:error/error-tag", 2252 "sid": 1028 2253 } 2254 ] 2255 } 2257 Authors' Addresses 2259 Michel Veillette (editor) 2260 Trilliant Networks Inc. 2261 610 Rue du Luxembourg 2262 Granby, Quebec J2J 2V2 2263 Canada 2265 Email: michel.veillette@trilliant.com 2266 Peter van der Stok (editor) 2267 consultant 2269 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2270 Email: consultancy@vanderstok.org 2271 URI: www.vanderstok.org 2273 Alexander Pelov 2274 Acklio 2275 2bis rue de la Chataigneraie 2276 Cesson-Sevigne, Bretagne 35510 2277 France 2279 Email: a@ackl.io 2281 Andy Bierman 2282 YumaWorks 2283 685 Cochran St. 2284 Suite #160 2285 Simi Valley, CA 93065 2286 USA 2288 Email: andy@yumaworks.com 2290 Ivaylo Petrov (editor) 2291 Acklio 2292 1137A avenue des Champs Blancs 2293 Cesson-Sevigne, Bretagne 35510 2294 France 2296 Email: ivaylo@ackl.io