idnits 2.17.1 draft-ietf-core-comi-06.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 -- The document date (July 09, 2019) is 1754 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 342 -- Looks like a reference, but probably isn't: '26' on line 343 -- Looks like a reference, but probably isn't: '57' on line 344 == 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 == 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 (~~), 4 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 10, 2020 consultant 6 A. Pelov 7 Acklio 8 A. Bierman 9 YumaWorks 10 I. Petrov, Ed. 11 Acklio 12 July 09, 2019 14 CoAP Management Interface 15 draft-ietf-core-comi-06 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 10, 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 . . . . . . . . . . . . . . . . . . . . . . . . 19 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 . . . . . . . . . . . . 30 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 in base64 using the URL and 314 Filename safe alphabet as defined by [RFC4648] section 5, without 315 padding. The last 6 bits encoded is always aligned with the least 316 significant 6 bits of the SID represented using an unsigned integer. 317 'A' characters (value 0) at the start of the resulting string are 318 removed. 320 SID in base64 = URLsafeChar[SID >> 60 & 0x3F] | 321 URLsafeChar[SID >> 54 & 0x3F] | 322 URLsafeChar[SID >> 48 & 0x3F] | 323 URLsafeChar[SID >> 42 & 0x3F] | 324 URLsafeChar[SID >> 36 & 0x3F] | 325 URLsafeChar[SID >> 30 & 0x3F] | 326 URLsafeChar[SID >> 24 & 0x3F] | 327 URLsafeChar[SID >> 18 & 0x3F] | 328 URLsafeChar[SID >> 12 & 0x3F] | 329 URLsafeChar[SID >> 6 & 0x3F] | 330 URLsafeChar[SID & 0x3F] 332 For example, SID 1721 is encoded as follow. 334 URLsafeChar[1721 >> 60 & 0x3F] = URLsafeChar[0] = 'A' 335 URLsafeChar[1721 >> 54 & 0x3F] = URLsafeChar[0] = 'A' 336 URLsafeChar[1721 >> 48 & 0x3F] = URLsafeChar[0] = 'A' 337 URLsafeChar[1721 >> 42 & 0x3F] = URLsafeChar[0] = 'A' 338 URLsafeChar[1721 >> 36 & 0x3F] = URLsafeChar[0] = 'A' 339 URLsafeChar[1721 >> 30 & 0x3F] = URLsafeChar[0] = 'A' 340 URLsafeChar[1721 >> 24 & 0x3F] = URLsafeChar[0] = 'A' 341 URLsafeChar[1721 >> 18 & 0x3F] = URLsafeChar[0] = 'A' 342 URLsafeChar[1721 >> 12 & 0x3F] = URLsafeChar[0] = 'A' 343 URLsafeChar[1721 >> 6 & 0x3F] = URLsafeChar[26] = 'a' 344 URLsafeChar[1721 & 0x3F] = URLsafeChar[57] = '5' 346 The resulting base64 representation of SID 1721 is "a5" 348 2.3. Instance identifier 350 Instance identifiers are used to uniquely identify data node 351 instances within a datastore. This YANG built-in type is defined in 352 [RFC7950] section 9.13. An instance identifier is composed of the 353 data node identifier (i.e. a SID) and for data nodes within list(s) 354 the keys used to index within these list(s). 356 When part of a payload, instance identifiers are encoded in CBOR 357 based on the rules defined in [I-D.ietf-core-yang-cbor] section 358 6.13.1. When part of a URI, the SID is appended to the URI of the 359 targeted datastore, the keys are specified using the 'k' URI-Query as 360 defined in Section 4.1. 362 2.4. Content-Formats 364 CoMI uses Content-Formats based on the YANG to CBOR mapping specified 365 in [I-D.ietf-core-yang-cbor]. 367 The following Content-formats are defined: 369 application/yang-data+cbor: This Content-Format represents a CBOR 370 YANG document containing one or multiple data node values. Each 371 data node is identified by its associated SID. 373 FORMAT: CBOR map of SID, instance-value 375 The message payload of Content-Format 'application/yang-data+cbor' 376 is encoded using a CBOR map. Each entry of this CBOR map is 377 composed of a key and a value. CBOR map keys are set to the SID 378 or SID deltas associated with the data nodes as defined in 379 [I-D.ietf-core-yang-cbor] section 4, CBOR map values are set to 380 the instance value as defined in [I-D.ietf-core-yang-cbor] section 381 4. 383 application/yang-identifiers+cbor: This Content-Format represents a 384 CBOR YANG document containing a list of instance identifier used 385 to target specific data node instances within a datastore. 387 FORMAT: CBOR array of instance-identifier 389 The message payload of Content-Format 'application/yang- 390 identifiers+cbor' is encoded using a CBOR array. Each entry of 391 this CBOR array contain an instance identifier encoded as defined 392 in [I-D.ietf-core-yang-cbor] section 6.13.1. 394 application/yang-instances+cbor: This Content-Format represents a 395 CBOR YANG document containing a list of data node instances. Each 396 data node instance is identified by its associated instance 397 identifier. 399 FORMAT: CBOR array of CBOR map of instance-identifier, instance- 400 value 402 The message payload of Content-Format 'application/yang- 403 instances+cbor' is encoded using a CBOR array. Each entry within 404 this CBOR array contains a CBOR map carrying an instance 405 identifier and associated instance value. Instance identifiers 406 are encoded using the rules defined in [I-D.ietf-core-yang-cbor] 407 section 6.13.1, values are encoded using the rules defined in 408 [I-D.ietf-core-yang-cbor] section 4. 410 When present in an iPATCH request payload, this Content-Format 411 carry a list of data node instances to be replaced, created, or 412 deleted. For each data node instance D, for which the instance 413 identifier is the same as a data node instance I, in the targeted 414 datastore resource: the value of D replaces the value of I. When 415 the value of D is null, the data node instance I is removed. When 416 the targeted datastore resource does not contain a data node 417 instance with the same instance identifier as D, a new instance is 418 created with the same instance identifier and value as D. 420 The different Content-format usages are summarized in the table 421 below: 423 +---------------+--------------+------------------------------------+ 424 | Method | Resource | Content-Format | 425 +---------------+--------------+------------------------------------+ 426 | GET response | data node | /application/yang-data+cbor | 427 | | | | 428 | PUT request | data node | /application/yang-data+cbor | 429 | | | | 430 | POST request | data node | /application/yang-data+cbor | 431 | | | | 432 | DELETE | data node | n/a | 433 | | | | 434 | GET response | datastore | /application/yang-data+cbor | 435 | | | | 436 | PUT request | datastore | /application/yang-data+cbor | 437 | | | | 438 | POST request | datastore | /application/yang-data+cbor | 439 | | | | 440 | FETCH request | datastore | /application/yang-identifiers+cbor | 441 | | | | 442 | FETCH | datastore | /application/yang-instances+cbor | 443 | response | | | 444 | | | | 445 | iPATCH | datastore | /application/yang-instances+cbor | 446 | request | | | 447 | | | | 448 | GET response | event stream | /application/yang-instances+cbor | 449 | | | | 450 | POST request | rpc, action | /application/yang-data+cbor | 451 | | | | 452 | POST response | rpc, action | /application/yang-data+cbor | 453 +---------------+--------------+------------------------------------+ 455 2.5. Unified datastore 457 CoMI supports a simple datastore model consisting of a single unified 458 datastore. This datastore provides access to both configuration and 459 operational data. Configuration updates performed on this datastore 460 are reflected immediately or with a minimal delay as operational 461 data. 463 Alternatively, CoMI servers MAY implement a more complex datastore 464 model such as the Network Management Datastore Architecture (NMDA) as 465 defined by [RFC8342]. Each datastore supported is implemented as a 466 datastore resource. 468 Characteristics of the unified datastore are summarized in the table 469 below: 471 +-------------+-----------------------------------------------------+ 472 | Name | Value | 473 +-------------+-----------------------------------------------------+ 474 | Name | unified | 475 | | | 476 | YANG | all modules | 477 | modules | | 478 | | | 479 | YANG nodes | all data nodes ("config true" and "config false") | 480 | | | 481 | Access | read-write | 482 | | | 483 | How applied | changes applied in place immediately or with a | 484 | | minimal delay | 485 | | | 486 | Protocols | CORECONF | 487 | | | 488 | Defined in | "ietf-comi" | 489 +-------------+-----------------------------------------------------+ 491 3. Example syntax 493 CBOR is used to encode CoMI request and response payloads. The CBOR 494 syntax of the YANG payloads is specified in [RFC7049]. The payload 495 examples are notated in Diagnostic notation (defined in section 6 of 496 [RFC7049]) that can be automatically converted to CBOR. 498 SIDs in URIs are represented as a base64 number, SIDs in the payload 499 are represented as decimal numbers. 501 4. CoAP Interface 503 This note specifies a Management Interface. CoAP endpoints that 504 implement the CoMI management protocol, support at least one 505 discoverable management resource of resource type (rt): core.c.ds, 506 with example path: /c, where c is short-hand for CoMI. The path /c 507 is recommended, but not compulsory (see Section 6). 509 The mapping of YANG data node instances to CoMI resources is as 510 follows. Every data node of the YANG modules loaded in the CoMI 511 server represents a sub-resource of the datastore resource (e.g. /c/ 512 sid). When multiple instances of a list exist, instance selection is 513 possible as described in Section 4.1, Section 4.2.3.1, and 514 Section 4.2.4. 516 CoMI also supports event stream resources used to observe 517 notification instances. Event stream resources can be discovered 518 using resource type (rt): core.c.ev. 520 The description of the CoMI management interface is shown in the 521 table below: 523 +-------------+------------------+-----------+ 524 | Function | Recommended path | rt | 525 +-------------+------------------+-----------+ 526 | Datastore | /c | core.c.ds | 527 | | | | 528 | Data node | /c/SID | core.c.dn | 529 | | | | 530 | Event steam | /s | core.c.ev | 531 +-------------+------------------+-----------+ 533 The path values in the table are the recommended ones. On discovery, 534 the server makes the actual path values known for these resources. 536 The methods used by CoMI are: 538 +-----------+-------------------------------------------------------+ 539 | Operation | Description | 540 +-----------+-------------------------------------------------------+ 541 | GET | Retrieve the datastore resource or a data node | 542 | | resource | 543 | | | 544 | FETCH | Retrieve specific data nodes within a datastore | 545 | | resource | 546 | | | 547 | POST | Create a datastore resource or a data node resource, | 548 | | invoke an RPC or action | 549 | | | 550 | PUT | Create or replace a datastore resource or a data node | 551 | | resource | 552 | | | 553 | iPATCH | Idem-potently create, replace, and delete data node | 554 | | resource(s) within a datastore resource | 555 | | | 556 | DELETE | Delete a datastore resource or a data node resource | 557 +-----------+-------------------------------------------------------+ 559 There is one Uri-Query option for the GET, PUT, POST, and DELETE 560 methods. 562 +------------------+----------------------------------------+ 563 | Uri-Query option | Description | 564 +------------------+----------------------------------------+ 565 | k | Select an instance within YANG list(s) | 566 +------------------+----------------------------------------+ 567 This parameter is not used for FETCH and iPATCH, because their 568 request payloads support list instance selection. 570 4.1. Using the 'k' Uri-Query option 572 The "k" (key) parameter specifies a specific instance of a data node. 573 The SID in the URI is followed by the (?k=key1,key2,...). Where SID 574 identifies a data node, and key1, key2 are the values of the key 575 leaves that specify an instance. Lists can have multiple keys, and 576 lists can be part of lists. The order of key value generation is 577 given recursively by: 579 o For a given list, if a parent data node is a list, generate the 580 keys for the parent list first. 582 o For a given list, generate key values in the order specified in 583 the YANG module. 585 Key values are encoded using the rules defined in the following 586 table. 588 +-----------------------------+--------------------------------+ 589 | YANG datatype | Uri-Query text content | 590 +-----------------------------+--------------------------------+ 591 | uint8,uint16,unit32, uint64 | int2str(key) | 592 | | | 593 | int8, int16,int32, int64 | urlSafeBase64(CBORencode(key)) | 594 | | | 595 | decimal64 | urlSafeBase64(CBOR key) | 596 | | | 597 | string | key | 598 | | | 599 | boolean | "0" or "1" | 600 | | | 601 | enumeration | int2str(key) | 602 | | | 603 | bits | urlSafeBase64(CBORencode(key)) | 604 | | | 605 | binary | urlSafeBase64(key) | 606 | | | 607 | identityref | int2str(key) | 608 | | | 609 | union | urlSafeBase64(CBORencode(key)) | 610 | | | 611 | instance-identifier | urlSafeBase64(CBORencode(key)) | 612 +-----------------------------+--------------------------------+ 614 In this table: 616 o The method int2str() is used to convert an integer value to a 617 decimal string. For example, int2str(0x0123) return the string 618 "291". 620 o The method urlSafeBase64() is used to convert a binary string to 621 base64 using the URL and Filename safe alphabet as defined by 622 [RFC4648] section 5, without padding. For example, 623 urlSafeBase64(\xF9\x56\xA1\x3C) return the string "-VahPA". 625 o The method CBORencode() is used to convert a YANG value to CBOR as 626 specified in [I-D.ietf-core-yang-cbor] section 6. 628 The resulting key string is encoded in a Uri-Query as specified in 629 [RFC7252] section 6.5. 631 4.2. Data Retrieval 633 One or more data nodes can be retrieved by the client. The operation 634 is mapped to the GET method defined in section 5.8.1 of [RFC7252] and 635 to the FETCH method defined in section 2 of [RFC8132]. 637 There are two additional Uri-Query options for the GET and FETCH 638 methods. 640 +-------------+-----------------------------------------------------+ 641 | Uri-Query | Description | 642 | option | | 643 +-------------+-----------------------------------------------------+ 644 | c | Control selection of configuration and non- | 645 | | configuration data nodes (GET and FETCH) | 646 | | | 647 | d | Control retrieval of default values. | 648 +-------------+-----------------------------------------------------+ 650 4.2.1. Using the 'c' Uri-Query option 652 The 'c' (content) option controls how descendant nodes of the 653 requested data nodes will be processed in the reply. 655 The allowed values are: 657 +-------+-----------------------------------------------------+ 658 | Value | Description | 659 +-------+-----------------------------------------------------+ 660 | c | Return only configuration descendant data nodes | 661 | | | 662 | n | Return only non-configuration descendant data nodes | 663 | | | 664 | a | Return all descendant data nodes | 665 +-------+-----------------------------------------------------+ 667 This option is only allowed for GET and FETCH methods on datastore 668 and data node resources. A 4.02 (Bad Option) error is returned if 669 used for other methods or resource types. 671 If this Uri-Query option is not present, the default value is "a". 673 4.2.2. Using the 'd' Uri-Query option 675 The "d" (with-defaults) option controls how the default values of the 676 descendant nodes of the requested data nodes will be processed. 678 The allowed values are: 680 +-------+-----------------------------------------------------------+ 681 | Value | Description | 682 +-------+-----------------------------------------------------------+ 683 | a | All data nodes are reported. Defined as 'report-all' in | 684 | | section 3.1 of [RFC6243]. | 685 | | | 686 | t | Data nodes set to the YANG default are not reported. | 687 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 688 +-------+-----------------------------------------------------------+ 690 If the target of a GET or FETCH method is a data node that represents 691 a leaf that has a default value, and the leaf has not been given a 692 value by any client yet, the server MUST return the default value of 693 the leaf. 695 If the target of a GET method is a data node that represents a 696 container or list that has child resources with default values, and 697 these have not been given value yet, 699 The server MUST NOT return the child resource if d= 't' 701 The server MUST return the child resource if d= 'a'. 703 If this Uri-Query option is not present, the default value is 't'. 705 4.2.3. GET 707 A request to read the values of a data node instance is sent with a 708 CoAP GET message. A base64-encoded instance-identifier in SID-form 709 is specified in the URI path prefixed with the example path /c. 711 FORMAT: 712 GET /c/instance-identifier 714 2.05 Content (Content-Format: application/yang-data+cbor) 715 CBOR map of SID, instance-value 717 The returned payload contains the CBOR encoding of the specified data 718 node instance value. 720 4.2.3.1. GET Examples 722 Using for example the current-datetime leaf from module ietf-system 723 [RFC7317], a request is sent to retrieve the value of 'system- 724 state/clock/current-datetime' specified in container system-state. 725 The SID of 'system-state/clock/current-datetime' is 1723, encoded in 726 base64 according to Section 2.2, yields a7. The response to the 727 request returns the CBOR map with the key set to the SID of the 728 requested data node (i.e. 1723) and the value encoded using a 'text 729 string' as defined in [I-D.ietf-core-yang-cbor] section 6.4. 731 REQ: GET example.com/c/a7 733 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 734 { 735 1723 : "2014-10-26T12:16:31Z" 736 } 738 The next example represents the retrieval of a YANG container. In 739 this case, the CoMI client performs a GET request on the clock 740 container (SID = 1721; base64: a5). The container returned is 741 encoded using a CBOR map as specified by [I-D.ietf-core-yang-cbor] 742 section 4.2. 744 REQ: GET example.com/c/a5 746 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 747 { 748 1721 : { 749 +2 : "2014-10-26T12:16:51Z", / current-datetime SID 1723 / 750 +1 : "2014-10-21T03:00:00Z" / boot-datetime SID 1722 / 751 } 752 } 753 This example shows the retrieval of the /interfaces/interface YANG 754 list accessed using SID 1533 (base64: X9). The return payload is 755 encoded using a CBOR array as specified by [I-D.ietf-core-yang-cbor] 756 section 4.4.1 containing 2 instances. 758 REQ: GET example.com/c/X9 760 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 761 { 762 1533 : [ 763 { 764 +4 : "eth0", / name (SID 1537) / 765 +1 : "Ethernet adaptor", / description (SID 1534) / 766 +5 : 1880, / type, (SID 1538) identity / 767 / ethernetCsmacd (SID 1880) / 768 +2 : true / enabled ( SID 1535) / 769 }, 770 { 771 +4 : "eth1", / name (SID 1537) / 772 +1 : "Ethernet adaptor", / description (SID 1534) / 773 +5 : 1880, / type, (SID 1538) identity / 774 / ethernetCsmacd (SID 1880) / 775 +2 : false / enabled ( SID 1535) / 776 } 777 ] 778 } 780 To retrieve a specific instance within the /interfaces/interface YANG 781 list, the CoMI client adds the key of the targeted instance in its 782 CoAP request using the 'k' URI-Query. The return payload containing 783 the instance requested is encoded using a CBOR array as specified by 784 [I-D.ietf-core-yang-cbor] section 4.4.1. 786 REQ: GET example.com/c/X9?k="eth0" 788 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 789 { 790 1533 : [ 791 { 792 +4 : "eth0", / name (SID 1537) / 793 +1 : "Ethernet adaptor", / description (SID 1534) / 794 +5 : 1880, / type, (SID 1538) identity / 795 / ethernetCsmacd (SID 1880) / 796 +2 : true / enabled ( SID 1535) / 797 } 798 ] 799 } 800 It is equally possible to select a leaf of a specific instance of a 801 list. The example below requests the description leaf (SID=1534, 802 base64: X-) within the interface list corresponding to the interface 803 name "eth0". The returned value is encoded in CBOR based on the 804 rules specified by [I-D.ietf-core-yang-cbor] section 6.4. 806 REQ: GET example.com/c/X-?k="eth0" 808 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 809 { 810 1534 : "Ethernet adaptor" 811 } 813 4.2.4. FETCH 815 The FETCH is used to retrieve multiple data node instance values. 816 The FETCH request payload contains the list of instance identifier of 817 the data node instances requested. 819 The return response payload contains a list of data node instance 820 values in the same order as requested. A CBOR null is returned for 821 each data node requested by the client, not supported by the server 822 or not currently instantiated. 824 For compactness, indexes of the list instance identifiers returned by 825 the FETCH response SHOULD be elided, only the SID is provided. In 826 this case, the format of each entry within the CBOR array of the 827 FETCH response is identical to the format as a GET response. 829 FORMAT: 830 FETCH /c (Content-Format: application/yang-identifiers+cbor) 831 CBOR array of instance-identifier 833 2.05 Content (Content-Format: application/yang-instances+cbor) 834 CBOR array of CBOR map of instance-identifier, instance-value 836 4.2.4.1. FETCH examples 838 This example uses the current-datetime leaf from module ietf-system 839 [RFC7317] and the interface list from module ietf-interfaces 840 [RFC7223]. In this example the value of current-datetime (SID 1723) 841 and the interface list (SID 1533) instance identified with 842 name="eth0" are queried. 844 REQ: FETCH /c (Content-Format: application/yang-identifiers+cbor) 845 [ 846 1723, / current-datetime (SID 1723) / 847 [1533, "eth0"] / interface (SID 1533) with name = "eth0" / 848 ] 850 RES: 2.05 Content (Content-Format: application/yang-instances+cbor) 851 [ 852 { 853 1723 : "2014-10-26T12:16:31Z" / current-datetime (SID 1723) / 854 }, 855 { 856 1533 : { 857 +4 : "eth0", / name (SID 1537) / 858 +1 : "Ethernet adaptor", / description (SID 1534) / 859 +5 : 1880, / type (SID 1538), identity / 860 / ethernetCsmacd (SID 1880) / 861 +2 : true / enabled (SID 1535) / 862 } 863 } 864 ] 866 4.3. Data Editing 868 CoMI allows datastore contents to be created, modified and deleted 869 using CoAP methods. 871 4.3.1. Data Ordering 873 A CoMI server SHOULD preserve the relative order of all user-ordered 874 list and leaf-list entries that are received in a single edit 875 request. These YANG data node types are encoded as CBOR arrays so 876 messages will preserve their order. 878 4.3.2. POST 880 The CoAP POST operation is used in CoMI for creation of data node 881 resources and the invocation of "ACTION" and "RPC" resources. Refer 882 to Section 4.6 for details on "ACTION" and "RPC" resources. 884 A request to create a data node resource is sent with a CoAP POST 885 message. The URI specifies the data node to be instantiated at the 886 exception of list instances. In this case, for compactness, the URI 887 specifies the list for which an instance is created. 889 FORMAT: 890 POST /c/ 891 (Content-Format: application/yang-data+cbor) 892 CBOR map of SID, instance-value 894 2.01 Created 896 If the data node resource already exists, then the POST request MUST 897 fail and a "4.09 Conflict" response code MUST be returned 899 4.3.2.1. Post example 901 The example uses the interface list from module ietf-interfaces 902 [RFC7223]. This example creates a new list instance within the 903 interface list (SID = 1533): 905 REQ: POST /c/X9 (Content-Format: application/yang-data+cbor) 906 { 907 1533 : [ 908 { 909 +4 : "eth5", / name (SID 1537) / 910 +1 : "Ethernet adaptor", / description (SID 1534) / 911 +5 : 1880, / type (SID 1538), identity / 912 / ethernetCsmacd (SID 1880) / 913 +2 : true / enabled (SID 1535) / 914 } 915 ] 916 } 918 RES: 2.01 Created 920 4.3.3. PUT 922 A data node resource instance is created or replaced with the PUT 923 method. A request to set the value of a data node instance is sent 924 with a CoAP PUT message. 926 FORMAT: 927 PUT /c/ 928 (Content-Format: application/yang-data+cbor) 929 CBOR map of SID, instance-value 931 2.01 Created 933 4.3.3.1. PUT example 935 The example uses the interface list from module ietf-interfaces 936 [RFC7223]. Example updates the instance of the list interface (SID = 937 1533) with key name="eth0": 939 REQ: PUT /c/X9?k="eth0" (Content-Format: application/yang-data+cbor) 940 { 941 1533 : [ 942 { 943 +4 : "eth0", / name (SID 1537) / 944 +1 : "Ethernet adaptor", / description (SID 1534) / 945 +5 : 1880, / type (SID 1538), identity / 946 / ethernetCsmacd (SID 1880) / 947 +2 : true / enabled (SID 1535) / 948 } 949 ] 950 } 952 RES: 2.04 Changed 954 4.3.4. iPATCH 956 One or multiple data node instances are replaced with the idempotent 957 CoAP iPATCH method [RFC8132]. 959 There are no Uri-Query options for the iPATCH method. 961 The processing of the iPATCH command is specified by Content-Format 962 'application/yang-instances+cbor'. In summary, if the CBOR patch 963 payload contains a data node instance that is not present in the 964 target, this instance is added. If the target contains the specified 965 instance, the content of this instance is replaced with the value of 966 the payload. A null value indicates the removal of an existing data 967 node instance. 969 FORMAT: 970 iPATCH /c (Content-Format: application/yang-instances+cbor) 971 CBOR array of CBOR map of instance-identifier, instance-value 973 2.04 Changed 975 4.3.4.1. iPATCH example 977 In this example, a CoMI client requests the following operations: 979 o Set "/system/ntp/enabled" (SID 1755) to true. 981 o Remove the server "tac.nrc.ca" from the "/system/ntp/server" (SID 982 1756) list. 984 o Add/set the server "NTP Pool server 2" to the list "/system/ntp/ 985 server" (SID 1756). 987 REQ: iPATCH /c (Content-Format: application/yang-instances+cbor) 988 [ 989 { 990 1755 : true / enabled (SID 1755) / 991 }, 992 { 993 [1756, "tac.nrc.ca"] : null / server (SID 1756) / 994 }, 995 { 996 1756 : { / server (SID 1756) / 997 +3 : "tic.nrc.ca", / name (SID 1759) / 998 +4 : true, / prefer (SID 1760) / 999 +5 : { / udp (SID 1761) / 1000 +1 : "132.246.11.231" / address (SID 1762) / 1001 } 1002 } 1003 } 1004 ] 1006 RES: 2.04 Changed 1008 4.3.5. DELETE 1010 A data node resource is deleted with the DELETE method. 1012 FORMAT: 1013 Delete /c/ 1015 2.02 Deleted 1017 4.3.5.1. DELETE example 1019 This example uses the interface list from module ietf-interfaces 1020 [RFC7223]. This example deletes an instance of the interface list 1021 (SID = 1533): 1023 REQ: DELETE /c/X9?k="eth0" 1025 RES: 2.02 Deleted 1027 4.4. Full datastore access 1029 The methods GET, PUT, POST, and DELETE can be used to request, 1030 replace, create, and delete a whole datastore respectively. 1032 FORMAT: 1033 GET /c 1035 2.05 Content (Content-Format: application/yang-data+cbor) 1036 CBOR map of SID, instance-value 1038 FORMAT: 1039 PUT /c (Content-Format: application/yang-data+cbor) 1040 CBOR map of SID, instance-value 1042 2.04 Changed 1044 FORMAT: 1045 POST /c (Content-Format: application/yang-data+cbor) 1046 CBOR map of SID, instance-value 1048 2.01 Created 1050 FORMAT: 1051 DELETE /c 1053 2.02 Deleted 1055 The content of the CBOR map represents the complete datastore of the 1056 server at the GET indication of after a successful processing of a 1057 PUT or POST request. 1059 4.4.1. Full datastore examples 1061 The example uses the interface list from module ietf-interfaces 1062 [RFC7223] and the clock container from module ietf-system [RFC7317]. 1063 We assume that the datastore contains two modules ietf-system (SID 1064 1700) and ietf-interfaces (SID 1500); they contain the 'interface' 1065 list (SID 1533) with one instance and the 'clock' container (SID 1066 1721). After invocation of GET, a CBOR map with data nodes from 1067 these two modules is returned: 1069 REQ: GET /c 1071 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 1072 { 1073 1721 : { / Clock (SID 1721) / 1074 +2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) / 1075 +1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) / 1076 }, 1077 1533 : [ 1078 { / interface (SID 1533) / 1079 +4 : "eth0", / name (SID 1537) / 1080 +1 : "Ethernet adaptor", / description (SID 1534) / 1081 +5 : 1880, / type (SID 1538), identity: / 1082 / ethernetCsmacd (SID 1880) / 1083 +2 : true / enabled (SID 1535) / 1084 } 1085 ] 1086 } 1088 4.5. Event stream 1090 Event notification is an essential function for the management of 1091 servers. CoMI allows notifications specified in YANG [RFC5277] to be 1092 reported to a list of clients. The recommended path of the default 1093 event stream is /s. The server MAY support additional event stream 1094 resources to address different notification needs. 1096 Reception of notification instances is enabled with the CoAP Observe 1097 [RFC7641] function. Clients subscribe to the notifications by 1098 sending a GET request with an "Observe" option, specifying the /s 1099 resource when the default stream is selected. 1101 Each response payload carries one or multiple notifications. The 1102 number of notifications reported, and the conditions used to remove 1103 notifications from the reported list is left to implementers. When 1104 multiple notifications are reported, they MUST be ordered starting 1105 from the newest notification at index zero. 1107 The format of notification contents is defined in 1108 [I-D.ietf-core-yang-cbor] section 4.2.1. For notification without 1109 any content, a null value is returned. 1111 An example implementation is: 1113 Every time an event is generated, the generated notification 1114 instance is appended to the chosen stream(s). After an 1115 aggregation period, which may be adjusted using an exclusion delay 1116 and limited by the maximum number of notifications supported, the 1117 content of the instance is sent to all clients observing the 1118 modified stream. 1120 FORMAT: 1121 GET / Observe(0) 1123 2.05 Content (Content-Format: application/yang-instances+cbor) 1124 CBOR array of CBOR map of instance-identifier, instance-value 1126 The array of data node instances may contain identical entries which 1127 have been generated at different times. 1129 4.5.1. Notify Examples 1131 Let suppose the server generates the example-port-fault event as 1132 defined below. 1134 module example-port { 1135 ... 1136 notification example-port-fault { // SID 60010 1137 description 1138 "Event generated if a hardware fault is detected"; 1139 leaf port-name { // SID 60011 1140 type string; 1141 } 1142 leaf port-fault { // SID 60012 1143 type string; 1144 } 1145 } 1146 } 1148 By executing a GET on the /s resource the client receives the 1149 following response: 1151 REQ: GET /s Observe(0) 1153 RES: 2.05 Content (Content-Format: application/yang-tree+cbor) 1154 Observe(12) 1155 [ 1156 { 1157 60010 : { / example-port-fault (SID 60010) / 1158 +1 : "0/4/21", / port-name (SID 60011) / 1159 +2 : "Open pin 2" / port-fault (SID 60012) / 1160 } 1161 }, 1162 { 1163 60010 : { / example-port-fault (SID 60010) / 1164 +1 : "1/4/21", / port-name (SID 60011) / 1165 +2 : "Open pin 5" / port-fault (SID 60012) / 1166 } 1167 } 1168 ] 1170 In the example, the request returns a success response with the 1171 contents of the last two generated events. Consecutively the server 1172 will regularly notify the client when a new event is generated. 1174 To check that the client is still alive, the server MUST send 1175 Confirmable Message periodically. When the client does not confirm 1176 the notification from the server, the server will remove the client 1177 from the list of observers [RFC7641]. 1179 4.5.2. The 'f' Uri-Query option 1181 The 'f' (filter) option is used to indicate which subset of all 1182 possible notifications is of interest. If not present, all events 1183 notifications supported by the event stream are reported. 1185 When not supported by a CoMI server, this option shall be ignored, 1186 all events notifications are reported independently of the presence 1187 and content of the 'f' (filter) option. 1189 When present, this option contains a comma separated list of 1190 notification SIDs. For example, the following request returns 1191 notifications 60010 and 60020. 1193 REQ: GET /s?f=60010,60020 Observe(0) 1195 4.6. RPC statements 1197 The YANG "action" and "RPC" statements specify the execution of a 1198 Remote procedure Call (RPC) in the server. It is invoked using a 1199 POST method to an "Action" or "RPC" resource instance. 1201 The request payload contains the values assigned to the input 1202 container when specified. The response payload contains the values 1203 of the output container when specified. Both the input and output 1204 containers are encoded in CBOR using the rules defined in 1205 [I-D.ietf-core-yang-cbor] section 4.2.1. 1207 The returned success response code is 2.05 Content. 1209 FORMAT: 1210 POST /c/ 1211 (Content-Format: application/yang-data+cbor) 1212 CBOR map of SID, instance-value 1214 2.05 Content (Content-Format: application/yang-data+cbor) 1215 CBOR map of SID, instance-value 1217 4.6.1. RPC Example 1219 The example is based on the YANG action "reset" as defined in 1220 [RFC7950] section 7.15.3 and annotated below with SIDs. 1222 module example-server-farm { 1223 yang-version 1.1; 1224 namespace "urn:example:server-farm"; 1225 prefix "sfarm"; 1227 import ietf-yang-types { 1228 prefix "yang"; 1229 } 1231 list server { // SID 60000 1232 key name; 1233 leaf name { // SID 60001 1234 type string; 1235 } 1236 action reset { // SID 60002 1237 input { 1238 leaf reset-at { // SID 60003 1239 type yang:date-and-time; 1240 mandatory true; 1241 } 1242 } 1243 output { 1244 leaf reset-finished-at { // SID 60004 1245 type yang:date-and-time; 1246 mandatory true; 1247 } 1248 } 1249 } 1250 } 1251 } 1253 This example invokes the 'reset' action (SID 60002, base64: Opq), of 1254 the server instance with name equal to "myserver". 1256 REQ: POST /c/Opq?k="myserver" 1257 (Content-Format: application/yang-data+cbor) 1258 { 1259 60002 : { 1260 +1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / 1261 } 1262 } 1264 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 1265 { 1266 60002 : { 1267 +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ 1268 } 1269 } 1271 5. Use of Block-wise Transfers 1273 The CoAP protocol provides reliability by acknowledging the UDP 1274 datagrams. However, when large pieces of data need to be 1275 transported, datagrams get fragmented, thus creating constraints on 1276 the resources in the client, server and intermediate routers. The 1277 block option [RFC7959] allows the transport of the total payload in 1278 individual blocks of which the size can be adapted to the underlying 1279 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1280 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1281 acknowledged to guarantee reliability. 1283 Notice that the Block mechanism splits the data at fixed positions, 1284 such that individual data fields may become fragmented. Therefore, 1285 assembly of multiple blocks may be required to process the complete 1286 data field. 1288 Beware of race conditions. Blocks are filled one at a time and care 1289 should be taken that the whole data representation is sent in 1290 multiple blocks sequentially without interruption. On the server, 1291 values are changed, lists are re-ordered, extended or reduced. When 1292 these actions happen during the serialization of the contents of the 1293 resource, the transported results do not correspond with a state 1294 having occurred in the server; or worse the returned values are 1295 inconsistent. For example: array length does not correspond with the 1296 actual number of items. It may be advisable to use Indefinite-length 1297 CBOR arrays and maps, which are foreseen for data streaming purposes. 1299 6. Application Discovery 1301 Two application discovery mechanisms are supported by CoMI, the YANG 1302 library data model as defined by [I-D.veillette-core-yang-library] 1303 and the CORE resource discovery [RFC6690]. Implementers may choose 1304 to implement one or the other or both. 1306 6.1. YANG library 1308 The YANG library data model [I-D.veillette-core-yang-library] 1309 provides a high level description of the resources available. The 1310 YANG library contains the list of modules, features and deviations 1311 supported by the CoMI server. From this information, CoMI clients 1312 can infer the list of data nodes supported and the interaction model 1313 to be used to access them. This module also contains the list of 1314 datastores implemented. 1316 The location of the YANG library can be found by sending a GET 1317 request to "/.well-known/core" including a resource type (RT) 1318 parameter with the value "core.c.yl". Upon success, the return 1319 payload will contain the root resource of the YANG library module. 1321 REQ: GET /.well-known/core?rt=core.c.yl 1323 RES: 2.05 Content (Content-Format: application/link-format) 1324 ;rt="core.c.yl" 1326 6.2. Resource Discovery 1328 Even if the YANG library provides all the information needed for 1329 application discovery once it is itself discovered, other types of 1330 resources could be discovered using the implementation of Resource 1331 discovery as defined by [RFC6690]. This can be desirable for a 1332 seamless integration with other CoAP interfaces and services. 1334 6.2.1. Datastore Resource Discovery 1336 The presence and location of (path to) each datastore implemented by 1337 the CoMI server can be discovered by sending a GET request to 1338 "/.well-known/core" including a resource type (RT) parameter with the 1339 value "core.c.ds". 1341 Upon success, the return payload contains the list of datastore 1342 resources. 1344 Each datastore returned is further qualified using the "ds" Link- 1345 Format attribute. This attribute is set to the SID assigned to the 1346 datastore identity. When a unified datastore is implemented, the ds 1347 attribute is set to 1029. For other examples of datastores, see the 1348 Network Management Datastore Architecture (NMDA) [RFC7950]. 1350 link-extension = ( "ds" "=" sid ) ) 1351 ; SID assigned to the datastore identity 1352 sid = 1*DIGIT 1354 For example: 1356 REQ: GET /.well-known/core?rt=core.c.ds 1358 RES: 2.05 Content (Content-Format: application/link-format) 1359 ; rt="core.c.ds";ds= 1029 1361 6.2.2. Data node Resource Discovery 1363 The presence and location of (path to) each data node implemented by 1364 the CoMI server are discovered by sending a GET request to "/.well- 1365 known/core" including a resource type (RT) parameter with the value 1366 "core.c.dn". 1368 Upon success, the return payload contains the SID assigned to each 1369 data node and their location. 1371 The example below shows the discovery of the presence and location of 1372 data nodes. Data nodes '/ietf-system:system-state/clock/boot- 1373 datetime' (SID 1722) and '/ietf-system:system-state/clock/current- 1374 datetime' (SID 1723) are returned. 1376 REQ: GET /.well-known/core?rt=core.c.dn 1378 RES: 2.05 Content (Content-Format: application/link-format) 1379 ;rt="core.c.dn", 1380 ;rt="core.c.dn" 1382 Without additional filtering, the list of data nodes may become 1383 prohibitively long. Implementations MAY return a subset of this list 1384 or can rely solely on the YANG library. 1386 6.2.3. Event stream Resource Discovery 1388 The presence and location of (path to) each event stream implemented 1389 by the CoMI server are discovered by sending a GET request to 1390 "/.well-known/core" including a resource type (RT) parameter with the 1391 value "core.c.es". 1393 Upon success, the return payload contains the list of event stream 1394 resources. 1396 For example: 1398 REQ: GET /.well-known/core?rt=core.c.es 1400 RES: 2.05 Content (Content-Format: application/link-format) 1401 ;rt="core.c.es" 1403 7. Error Handling 1405 In case a request is received which cannot be processed properly, the 1406 CoMI server MUST return an error response. This error response MUST 1407 contain a CoAP 4.xx or 5.xx response code. 1409 Errors returned by a CoMI server can be broken into two categories, 1410 those associated to the CoAP protocol itself and those generated 1411 during the validation of the YANG data model constrains as described 1412 in [RFC7950] section 8. 1414 The following list of common CoAP errors should be implemented by 1415 CoMI servers. This list is not exhaustive, other errors defined by 1416 CoAP and associated RFCs may be applicable. 1418 o Error 4.01 (Unauthorized) is returned by the CoMI server when the 1419 CoMI client is not authorized to perform the requested action on 1420 the targeted resource (i.e. data node, datastore, rpc, action or 1421 event stream). 1423 o Error 4.02 (Bad Option) is returned by the CoMI server when one or 1424 more CoAP options are unknown or malformed. 1426 o Error 4.04 (Not Found) is returned by the CoMI server when the 1427 CoMI client is requesting a non-instantiated resource (i.e. data 1428 node, datastore, rpc, action or event stream). 1430 o Error 4.05 (Method Not Allowed) is returned by the CoMI server 1431 when the CoMI client is requesting a method not supported on the 1432 targeted resource. (e.g. GET on an rpc, PUT or POST on a data 1433 node with "config" set to false). 1435 o Error 4.08 (Request Entity Incomplete) is returned by the CoMI 1436 server if one or multiple blocks of a block transfer request is 1437 missing, see [RFC7959] for more details. 1439 o Error 4.13 (Request Entity Too Large) may be returned by the CoMI 1440 server during a block transfer request, see [RFC7959] for more 1441 details. 1443 o Error 4.15 (Unsupported Content-Format) is returned by the CoMI 1444 server when the Content-Format used in the request does not match 1445 those specified in section Section 2.4. 1447 CoMI server MUST also enforce the different constraints associated to 1448 the YANG data models implemented. These constraints are described in 1449 [RFC7950] section 8. These errors are reported using the CoAP error 1450 code 4.00 (Bad Request) and may have the following error container as 1451 payload. The YANG definition and associated .sid file are available 1452 in Appendix A and Appendix B. The error container is encoded using 1453 the encoding rules of a YANG data template as defined in 1454 [I-D.ietf-core-yang-cbor] section 5. 1456 +--rw error! 1457 +--rw error-tag identityref 1458 +--rw error-app-tag? identityref 1459 +--rw error-data-node? instance-identifier 1460 +--rw error-message? string 1462 The following 'error-tag' and 'error-app-tag' are defined by the 1463 ietf-comi YANG module, these tags are implemented as YANG identity 1464 and can be extended as needed. 1466 o error-tag 'operation-failed' is returned by the CoMI server when 1467 the operation request cannot be processed successfully. 1469 * error-app-tag 'malformed-message' is returned by the CoMI 1470 server when the payload received from the CoMI client does not 1471 contain a well-formed CBOR content as defined in [RFC7049] 1472 section 3.3 or does not comply with the CBOR structure defined 1473 within this document. 1475 * error-app-tag 'data-not-unique' is returned by the CoMI server 1476 when the validation of the 'unique' constraint of a list or 1477 leaf-list fails. 1479 * error-app-tag 'too-many-elements' is returned by the CoMI 1480 server when the validation of the 'max-elements' constraint of 1481 a list or leaf-list fails. 1483 * error-app-tag 'too-few-elements' is returned by the CoMI server 1484 when the validation of the 'min-elements' constraint of a list 1485 or leaf-list fails. 1487 * error-app-tag 'must-violation' is returned by the CoMI server 1488 when the restrictions imposed by a 'must' statement are 1489 violated. 1491 * error-app-tag 'duplicate' is returned by the CoMI server when a 1492 client tries to create a duplicate list or leaf-list entry. 1494 o error-tag 'invalid-value' is returned by the CoMI server when the 1495 CoMI client tries to update or create a leaf with a value encoded 1496 using an invalid CBOR datatype or if the 'range', 'length', 1497 'pattern' or 'require-instance' constrain is not fulfilled. 1499 * error-app-tag 'invalid-datatype' is returned by the CoMI server 1500 when CBOR encoding does not follow the rules set by or when the 1501 value is incompatible with the YANG Built-In type (e.g. a value 1502 greater than 127 for an int8, undefined enumeration) 1504 * error-app-tag 'not-in-range' is returned by the CoMI server 1505 when the validation of the 'range' property fails. 1507 * error-app-tag 'invalid-length' is returned by the CoMI server 1508 when the validation of the 'length' property fails. 1510 * error-app-tag 'pattern-test-failed' is returned by the CoMI 1511 server when the validation of the 'pattern' property fails. 1513 o error-tag 'missing-element' is returned by the CoMI server when 1514 the operation requested by a CoMI client fails to comply with the 1515 'mandatory' constraint defined. The 'mandatory' constraint is 1516 enforced for leafs and choices, unless the node or any of its 1517 ancestors have a 'when' condition or 'if-feature' expression that 1518 evaluates to 'false'. 1520 * error-app-tag 'missing-key' is returned by the CoMI server to 1521 further qualify a missing-element error. This error is 1522 returned when the CoMI client tries to create or list instance, 1523 without all the 'key' specified or when the CoMI client tries 1524 to delete a leaf listed as a 'key'. 1526 * error-app-tag 'missing-input-parameter' is returned by the CoMI 1527 server when the input parameters of an RPC or action are 1528 incomplete. 1530 o error-tag 'unknown-element' is returned by the CoMI server when 1531 the CoMI client tries to access a data node of a YANG module not 1532 supported, of a data node associated to an 'if-feature' expression 1533 evaluated to 'false' or to a 'when' condition evaluated to 1534 'false'. 1536 o error-tag 'bad-element' is returned by the CoMI server when the 1537 CoMI client tries to create data nodes for more than one case in a 1538 choice. 1540 o error-tag 'data-missing' is returned by the CoMI server when a 1541 data node required to accept the request is not present. 1543 * error-app-tag 'instance-required' is returned by the CoMI 1544 server when a leaf of type 'instance-identifier' or 'leafref' 1545 marked with require-instance set to 'true' refers to an 1546 instance that does not exist. 1548 * error-app-tag 'missing-choice' is returned by the CoMI server 1549 when no nodes exist in a mandatory choice. 1551 o error-tag 'error' is returned by the CoMI server when an 1552 unspecified error has occurred. 1554 For example, the CoMI server might return the following error. 1556 RES: 4.00 Bad Request (Content-Format: application/yang-data+cbor) 1557 { 1558 1024 : { 1559 +4 : 1011, / error-tag (SID 1028) / 1560 / = invalid-value (SID 1011) / 1561 +1 : 1018, / error-app-tag (SID 1025) / 1562 / = not-in-range (SID 1018) / 1563 +2 : 1740, / error-data-node (SID 1026) / 1564 / = timezone-utc-offset (SID 1740) / 1565 +3 : "maximum value exceeded" / error-message (SID 1027) / 1566 } 1567 } 1569 8. Security Considerations 1571 For secure network management, it is important to restrict access to 1572 configuration variables only to authorized parties. CoMI re-uses the 1573 security mechanisms already available to CoAP, this includes DTLS 1574 [RFC6347] for protected access to resources, as well suitable 1575 authentication and authorization mechanisms. 1577 Among the security decisions that need to be made are selecting 1578 security modes and encryption mechanisms (see [RFC7252]). This 1579 requires a trade-off, as the NoKey mode gives no protection at all, 1580 but is easy to implement, whereas the Certificate mode is quite 1581 secure, but may be too complex for constrained devices. 1583 In addition, mechanisms for authentication and authorization may need 1584 to be selected in case NoKey is used. 1586 9. IANA Considerations 1588 9.1. Resource Type (rt=) Link Target Attribute Values Registry 1590 This document adds the following resource type to the "Resource Type 1591 (rt=) Link Target Attribute Values", within the "Constrained RESTful 1592 Environments (CoRE) Parameters" registry. 1594 +-----------+---------------------+-----------+ 1595 | Value | Description | Reference | 1596 +-----------+---------------------+-----------+ 1597 | core.c.ds | YANG datastore | RFC XXXX | 1598 | | | | 1599 | core.c.dn | YANG data node | RFC XXXX | 1600 | | | | 1601 | core.c.yl | YANG module library | RFC XXXX | 1602 | | | | 1603 | core.c.es | YANG event stream | RFC XXXX | 1604 +-----------+---------------------+-----------+ 1606 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1607 note. 1609 9.2. CoAP Content-Formats Registry 1611 This document adds the following Content-Format to the "CoAP Content- 1612 Formats", within the "Constrained RESTful Environments (CoRE) 1613 Parameters" registry. 1615 +-----------------------------------+------------+------+-----------+ 1616 | Media Type | Content | ID | Reference | 1617 | | Coding | | | 1618 +-----------------------------------+------------+------+-----------+ 1619 | application/yang-data+cbor | | TBD1 | RFC XXXX | 1620 | | | | | 1621 | application/yang-identifiers+cbor | | TBD2 | RFC XXXX | 1622 | | | | | 1623 | application/yang-instances+cbor | | TBD3 | RFC XXXX | 1624 +-----------------------------------+------------+------+-----------+ 1626 // RFC Ed.: replace TBD1, TBD2 and TBD3 with assigned IDs and remove 1627 this note. // RFC Ed.: replace RFC XXXX with this RFC number and 1628 remove this note. 1630 9.3. Media Types Registry 1632 This document adds the following media types to the "Media Types" 1633 registry. 1635 +-----------------------+----------------------------+-----------+ 1636 | Name | Template | Reference | 1637 +-----------------------+----------------------------+-----------+ 1638 | yang-data+cbor | application/yang-data+cbor | RFC XXXX | 1639 | | | | 1640 | yang-identifiers+cbor | application/ | RFC XXXX | 1641 | | | | 1642 | | yang-identifiers+cbor | | 1643 | | | | 1644 | yang-instances+cbor | application/ | RFC XXXX | 1645 | | | | 1646 | | yang-instances+cbor | | 1647 +-----------------------+----------------------------+-----------+ 1649 Each of these media types share the following information: 1651 o Subtype name: 1653 o Required parameters: N/A 1655 o Optional parameters: N/A 1657 o Encoding considerations: binary 1659 o Security considerations: See the Security Considerations section 1660 of RFC XXXX 1662 o Interoperability considerations: N/A 1664 o Published specification: RFC XXXX 1666 o Applications that use this media type: CoMI 1668 o Fragment identifier considerations: N/A 1670 o Additional information: 1672 * Deprecated alias names for this type: N/A 1674 * Magic number(s): N/A 1676 * File extension(s): N/A 1678 * Macintosh file type code(s): N/A 1680 o Person & email address to contact for further information: 1681 iesg&ietf.org 1683 o Intended usage: COMMON 1685 o Restrictions on usage: N/A 1687 o Author: Michel Veillette, ietf&augustcellars.com 1689 o Change Controller: IESG 1691 o Provisional registration? No 1693 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1694 note. 1696 10. Acknowledgements 1698 We are very grateful to Bert Greevenbosch who was one of the original 1699 authors of the CoMI specification. 1701 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1702 transported under SNMP. Carsten Bormann has given feedback on the 1703 use of CBOR. 1705 The draft has benefited from comments (alphabetical order) by Rodney 1706 Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy 1707 Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes 1708 Tschofenig, Michael Verschoor, and Thomas Watteyne. 1710 11. References 1712 11.1. Normative References 1714 [I-D.ietf-core-sid] 1715 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 1716 iDentifier (SID)", draft-ietf-core-sid-07 (work in 1717 progress), July 2019. 1719 [I-D.ietf-core-yang-cbor] 1720 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 1721 Data Modeled with YANG", draft-ietf-core-yang-cbor-10 1722 (work in progress), April 2019. 1724 [I-D.veillette-core-yang-library] 1725 Veillette, M. and I. Petrov, "Constrained YANG Module 1726 Library", draft-veillette-core-yang-library-04 (work in 1727 progress), March 2019. 1729 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1730 Requirement Levels", BCP 14, RFC 2119, 1731 DOI 10.17487/RFC2119, March 1997, 1732 . 1734 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1735 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1736 . 1738 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1739 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1740 . 1742 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1743 and A. Bierman, Ed., "Network Configuration Protocol 1744 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1745 . 1747 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1748 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1749 . 1751 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1752 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1753 October 2013, . 1755 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1756 Application Protocol (CoAP)", RFC 7252, 1757 DOI 10.17487/RFC7252, June 2014, 1758 . 1760 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1761 Application Protocol (CoAP)", RFC 7641, 1762 DOI 10.17487/RFC7641, September 2015, 1763 . 1765 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1766 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1767 . 1769 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1770 the Constrained Application Protocol (CoAP)", RFC 7959, 1771 DOI 10.17487/RFC7959, August 2016, 1772 . 1774 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1775 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1776 . 1778 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1779 FETCH Methods for the Constrained Application Protocol 1780 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1781 . 1783 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1784 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1785 May 2017, . 1787 11.2. Informative References 1789 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1790 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1791 January 2012, . 1793 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1794 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1795 . 1797 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1798 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1799 . 1801 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1802 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1803 2014, . 1805 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1806 and R. Wilton, "Network Management Datastore Architecture 1807 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1808 . 1810 Appendix A. ietf-comi YANG module 1812 file "ietf-comi@2019-03-28.yang" 1813 module ietf-comi { 1814 yang-version 1.1; 1816 namespace "urn:ietf:params:xml:ns:yang:ietf-comi"; 1817 prefix comi; 1819 import ietf-datastores { 1820 prefix ds; 1821 } 1823 import ietf-restconf { 1824 prefix rc; 1825 description 1826 "This import statement is required to access 1827 the yang-data extension defined in RFC 8040."; 1828 reference "RFC 8040: RESTCONF Protocol"; 1829 } 1831 organization 1832 "IETF Core Working Group"; 1834 contact 1835 "Michel Veillette 1836 1838 Alexander Pelov 1839 1841 Peter van der Stok 1842 1844 Andy Bierman 1845 "; 1847 description 1848 "This module contains the different definitions required 1849 by the CoMI protocol."; 1851 revision 2019-03-28 { 1852 description 1853 "Initial revision."; 1854 reference 1855 "[I-D.ietf-core-comi] CoAP Management Interface"; 1856 } 1858 identity unified { 1859 base ds:datastore; 1860 description 1861 "Identifier of the unified configuration and operational 1862 state datastore."; 1863 } 1865 identity error-tag { 1866 description 1867 "Base identity for error-tag."; 1868 } 1870 identity operation-failed { 1871 base error-tag; 1872 description 1873 "Returned by the CoMI server when the operation request 1874 can't be processed successfully."; 1875 } 1877 identity invalid-value { 1878 base error-tag; 1879 description 1880 "Returned by the CoMI server when the CoMI client tries to 1881 update or create a leaf with a value encoded using an 1882 invalid CBOR datatype or if the 'range', 'length', 1883 'pattern' or 'require-instance' constrain is not 1884 fulfilled."; 1885 } 1887 identity missing-element { 1888 base error-tag; 1889 description 1890 "Returned by the CoMI server when the operation requested 1891 by a CoMI client fails to comply with the 'mandatory' 1892 constraint defined. The 'mandatory' constraint is 1893 enforced for leafs and choices, unless the node or any of 1894 its ancestors have a 'when' condition or 'if-feature' 1895 expression that evaluates to 'false'."; 1896 } 1898 identity unknown-element { 1899 base error-tag; 1900 description 1901 "Returned by the CoMI server when the CoMI client tries to 1902 access a data node of a YANG module not supported, of a 1903 data node associated with an 'if-feature' expression 1904 evaluated to 'false' or to a 'when' condition evaluated 1905 to 'false'."; 1906 } 1908 identity bad-element { 1909 base error-tag; 1910 description 1911 "Returned by the CoMI server when the CoMI client tries to 1912 create data nodes for more than one case in a choice."; 1913 } 1915 identity data-missing { 1916 base error-tag; 1917 description 1918 "Returned by the CoMI server when a data node required to 1919 accept the request is not present."; 1920 } 1921 identity error { 1922 base error-tag; 1923 description 1924 "Returned by the CoMI server when an unspecified error has 1925 occurred."; 1926 } 1928 identity error-app-tag { 1929 description 1930 "Base identity for error-app-tag."; 1931 } 1933 identity malformed-message { 1934 base error-app-tag; 1935 description 1936 "Returned by the CoMI server when the payload received 1937 from the CoMI client don't contain a well-formed CBOR 1938 content as defined in [RFC7049] section 3.3 or don't 1939 comply with the CBOR structure defined within this 1940 document."; 1941 } 1943 identity data-not-unique { 1944 base error-app-tag; 1945 description 1946 "Returned by the CoMI server when the validation of the 1947 'unique' constraint of a list or leaf-list fails."; 1948 } 1950 identity too-many-elements { 1951 base error-app-tag; 1952 description 1953 "Returned by the CoMI server when the validation of the 1954 'max-elements' constraint of a list or leaf-list fails."; 1955 } 1957 identity too-few-elements { 1958 base error-app-tag; 1959 description 1960 "Returned by the CoMI server when the validation of the 1961 'min-elements' constraint of a list or leaf-list fails."; 1962 } 1964 identity must-violation { 1965 base error-app-tag; 1966 description 1967 "Returned by the CoMI server when the restrictions 1968 imposed by a 'must' statement are violated."; 1970 } 1972 identity duplicate { 1973 base error-app-tag; 1974 description 1975 "Returned by the CoMI server when a client tries to create 1976 a duplicate list or leaf-list entry."; 1977 } 1979 identity invalid-datatype { 1980 base error-app-tag; 1981 description 1982 "Returned by the CoMI server when CBOR encoding is 1983 incorect or when the value encoded is incompatible with 1984 the YANG Built-In type. (e.g. value greater than 127 1985 for an int8, undefined enumeration)."; 1986 } 1988 identity not-in-range { 1989 base error-app-tag; 1990 description 1991 "Returned by the CoMI server when the validation of the 1992 'range' property fails."; 1993 } 1995 identity invalid-length { 1996 base error-app-tag; 1997 description 1998 "Returned by the CoMI server when the validation of the 1999 'length' property fails."; 2000 } 2002 identity pattern-test-failed { 2003 base error-app-tag; 2004 description 2005 "Returned by the CoMI server when the validation of the 2006 'pattern' property fails."; 2007 } 2009 identity missing-key { 2010 base error-app-tag; 2011 description 2012 "Returned by the CoMI server to further qualify a 2013 missing-element error. This error is returned when the 2014 CoMI client tries to create or list instance, without all 2015 the 'key' specified or when the CoMI client tries to 2016 delete a leaf listed as a 'key'."; 2017 } 2018 identity missing-input-parameter { 2019 base error-app-tag; 2020 description 2021 "Returned by the CoMI server when the input parameters 2022 of a RPC or action are incomplete."; 2023 } 2025 identity instance-required { 2026 base error-app-tag; 2027 description 2028 "Returned by the CoMI server when a leaf of type 2029 'instance-identifier' or 'leafref' marked with 2030 require-instance set to 'true' refers to an instance 2031 that does not exist."; 2032 } 2034 identity missing-choice { 2035 base error-app-tag; 2036 description 2037 "Returned by the CoMI server when no nodes exist in a 2038 mandatory choice."; 2039 } 2041 rc:yang-data comi-error { 2042 container error { 2043 description 2044 "Optional payload of a 4.00 Bad Request CoAP error."; 2046 leaf error-tag { 2047 type identityref { 2048 base error-tag; 2049 } 2050 mandatory true; 2051 description 2052 "The enumerated error-tag."; 2053 } 2055 leaf error-app-tag { 2056 type identityref { 2057 base error-app-tag; 2058 } 2059 description 2060 "The application-specific error-tag."; 2061 } 2063 leaf error-data-node { 2064 type instance-identifier; 2065 description 2066 "When the error reported is caused by a specific data node, 2067 this leaf identifies the data node in error."; 2068 } 2070 leaf error-message { 2071 type string; 2072 description 2073 "A message describing the error."; 2074 } 2075 } 2076 } 2077 } 2078 2080 Appendix B. ietf-comi .sid file 2082 { 2083 "assignment-ranges": [ 2084 { 2085 "entry-point": 1000, 2086 "size": 100 2087 } 2088 ], 2089 "module-name": "ietf-comi", 2090 "module-revision": "2019-03-28", 2091 "items": [ 2092 { 2093 "namespace": "module", 2094 "identifier": "ietf-comi", 2095 "sid": 1000 2096 }, 2097 { 2098 "namespace": "identity", 2099 "identifier": "bad-element", 2100 "sid": 1001 2101 }, 2102 { 2103 "namespace": "identity", 2104 "identifier": "data-missing", 2105 "sid": 1002 2106 }, 2107 { 2108 "namespace": "identity", 2109 "identifier": "data-not-unique", 2110 "sid": 1003 2111 }, 2112 { 2113 "namespace": "identity", 2114 "identifier": "duplicate", 2115 "sid": 1004 2116 }, 2117 { 2118 "namespace": "identity", 2119 "identifier": "error", 2120 "sid": 1005 2121 }, 2122 { 2123 "namespace": "identity", 2124 "identifier": "error-app-tag", 2125 "sid": 1006 2126 }, 2127 { 2128 "namespace": "identity", 2129 "identifier": "error-tag", 2130 "sid": 1007 2131 }, 2132 { 2133 "namespace": "identity", 2134 "identifier": "instance-required", 2135 "sid": 1008 2136 }, 2137 { 2138 "namespace": "identity", 2139 "identifier": "invalid-datatype", 2140 "sid": 1009 2141 }, 2142 { 2143 "namespace": "identity", 2144 "identifier": "invalid-length", 2145 "sid": 1010 2146 }, 2147 { 2148 "namespace": "identity", 2149 "identifier": "invalid-value", 2150 "sid": 1011 2151 }, 2152 { 2153 "namespace": "identity", 2154 "identifier": "malformed-message", 2155 "sid": 1012 2156 }, 2157 { 2158 "namespace": "identity", 2159 "identifier": "missing-choice", 2160 "sid": 1013 2161 }, 2162 { 2163 "namespace": "identity", 2164 "identifier": "missing-element", 2165 "sid": 1014 2166 }, 2167 { 2168 "namespace": "identity", 2169 "identifier": "missing-input-parameter", 2170 "sid": 1015 2171 }, 2172 { 2173 "namespace": "identity", 2174 "identifier": "missing-key", 2175 "sid": 1016 2176 }, 2177 { 2178 "namespace": "identity", 2179 "identifier": "must-violation", 2180 "sid": 1017 2181 }, 2182 { 2183 "namespace": "identity", 2184 "identifier": "not-in-range", 2185 "sid": 1018 2186 }, 2187 { 2188 "namespace": "identity", 2189 "identifier": "operation-failed", 2190 "sid": 1019 2191 }, 2192 { 2193 "namespace": "identity", 2194 "identifier": "pattern-test-failed", 2195 "sid": 1020 2196 }, 2197 { 2198 "namespace": "identity", 2199 "identifier": "too-few-elements", 2200 "sid": 1021 2201 }, 2202 { 2203 "namespace": "identity", 2204 "identifier": "too-many-elements", 2205 "sid": 1022 2206 }, 2207 { 2208 "namespace": "identity", 2209 "identifier": "unified", 2210 "sid": 1029 2211 }, 2212 { 2213 "namespace": "identity", 2214 "identifier": "unknown-element", 2215 "sid": 1023 2216 }, 2217 { 2218 "namespace": "data", 2219 "identifier": "/ietf-comi:error", 2220 "sid": 1024 2221 }, 2222 { 2223 "namespace": "data", 2224 "identifier": "/ietf-comi:error/error-app-tag", 2225 "sid": 1025 2226 }, 2227 { 2228 "namespace": "data", 2229 "identifier": "/ietf-comi:error/error-data-node", 2230 "sid": 1026 2231 }, 2232 { 2233 "namespace": "data", 2234 "identifier": "/ietf-comi:error/error-message", 2235 "sid": 1027 2236 }, 2237 { 2238 "namespace": "data", 2239 "identifier": "/ietf-comi:error/error-tag", 2240 "sid": 1028 2241 } 2242 ] 2243 } 2245 Authors' Addresses 2247 Michel Veillette (editor) 2248 Trilliant Networks Inc. 2249 610 Rue du Luxembourg 2250 Granby, Quebec J2J 2V2 2251 Canada 2253 Email: michel.veillette@trilliant.com 2254 Peter van der Stok (editor) 2255 consultant 2257 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2258 Email: consultancy@vanderstok.org 2259 URI: www.vanderstok.org 2261 Alexander Pelov 2262 Acklio 2263 2bis rue de la Chataigneraie 2264 Cesson-Sevigne, Bretagne 35510 2265 France 2267 Email: a@ackl.io 2269 Andy Bierman 2270 YumaWorks 2271 685 Cochran St. 2272 Suite #160 2273 Simi Valley, CA 93065 2274 USA 2276 Email: andy@yumaworks.com 2278 Ivaylo Petrov (editor) 2279 Acklio 2280 1137A avenue des Champs Blancs 2281 Cesson-Sevigne, Bretagne 35510 2282 France 2284 Email: ivaylo@ackl.io