idnits 2.17.1 draft-ietf-core-comi-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 7 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 17, 2021) is 1195 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-14 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-13 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-36 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 5 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: July 21, 2021 consultant 6 A. Pelov 7 Acklio 8 A. Bierman 9 YumaWorks 10 I. Petrov, Ed. 11 Acklio 12 January 17, 2021 14 CoAP Management Interface (CORECONF) 15 draft-ietf-core-comi-11 17 Abstract 19 This document describes a network management interface for 20 constrained devices and networks, called CoAP Management Interface 21 (CORECONF). The Constrained Application Protocol (CoAP) is used to 22 access datastore and data node resources specified in YANG, or SMIv2 23 converted to YANG. CORECONF uses the YANG to CBOR mapping and 24 converts YANG identifier strings to numeric identifiers for payload 25 size reduction. CORECONF extends the set of YANG based protocols, 26 NETCONF and RESTCONF, with the capability to manage constrained 27 devices and networks. 29 Note 31 Discussion and suggestions for improvement are requested, and should 32 be sent to yot@ietf.org. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on July 21, 2021. 50 Copyright Notice 52 Copyright (c) 2021 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. CORECONF Architecture . . . . . . . . . . . . . . . . . . . . 5 70 2.1. Major differences between RESTCONF and CORECONF . . . . . 6 71 2.1.1. Differences due to CoAP and its efficient usage . . . 6 72 2.1.2. Differences due to the use of CBOR . . . . . . . . . 7 73 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 74 2.3. Instance-identifier . . . . . . . . . . . . . . . . . . . 8 75 2.4. Media-Types . . . . . . . . . . . . . . . . . . . . . . . 8 76 2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10 77 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11 78 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11 79 4.1. Using the 'k' query parameter . . . . . . . . . . . . . . 13 80 4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 15 81 4.2.1. Using the 'c' query parameter . . . . . . . . . . . . 15 82 4.2.2. Using the 'd' query parameter . . . . . . . . . . . . 16 83 4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16 84 4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 19 85 4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 20 86 4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 20 87 4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 20 88 4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 21 89 4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 22 90 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 23 91 4.4. Full datastore access . . . . . . . . . . . . . . . . . . 24 92 4.4.1. Full datastore examples . . . . . . . . . . . . . . . 24 93 4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 25 94 4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 26 95 4.5.2. The 'f' query parameter . . . . . . . . . . . . . . . 27 97 4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27 98 4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 28 99 5. Use of Block-wise Transfers . . . . . . . . . . . . . . . . . 30 100 6. Application Discovery . . . . . . . . . . . . . . . . . . . . 30 101 6.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 30 102 6.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 31 103 6.2.1. Datastore Resource Discovery . . . . . . . . . . . . 31 104 6.2.2. Data node Resource Discovery . . . . . . . . . . . . 32 105 6.2.3. Event stream Resource Discovery . . . . . . . . . . . 32 106 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 33 107 8. Security Considerations . . . . . . . . . . . . . . . . . . . 36 108 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 109 9.1. Resource Type (rt=) Link Target Attribute Values Registry 37 110 9.2. CoAP Content-Formats Registry . . . . . . . . . . . . . . 37 111 9.3. Media Types Registry . . . . . . . . . . . . . . . . . . 38 112 9.4. YANG Namespace Registration . . . . . . . . . . . . . . . 39 113 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 39 114 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 115 11.1. Normative References . . . . . . . . . . . . . . . . . . 40 116 11.2. Informative References . . . . . . . . . . . . . . . . . 41 117 Appendix A. ietf-coreconf YANG module . . . . . . . . . . . . . 42 118 Appendix B. ietf-coreconf .sid file . . . . . . . . . . . . . . 48 119 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 121 1. Introduction 123 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 124 Machine to Machine (M2M) applications such as smart energy, smart 125 city, and building control. Constrained devices need to be managed 126 in an automatic fashion to handle the large quantities of devices 127 that are expected in future installations. Messages between devices 128 need to be as small and infrequent as possible. The implementation 129 complexity and runtime resources need to be as small as possible. 131 This draft describes the CoAP Management Interface which uses CoAP 132 methods to access structured data defined in YANG [RFC7950]. This 133 draft is complementary to [RFC8040] which describes a REST-like 134 interface called RESTCONF, which uses HTTP methods to access 135 structured data defined in YANG. 137 The use of standardized data models specified in a standardized 138 language, such as YANG, promotes interoperability between devices and 139 applications from different manufacturers. 141 CORECONF and RESTCONF are intended to work in a stateless client- 142 server fashion. They use a single round-trip to complete a single 143 editing transaction, where NETCONF needs multiple round trips. 145 To promote small messages, CORECONF uses a YANG to CBOR mapping 146 [I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid] 147 to minimize CBOR payloads and URI length. 149 1.1. Terminology 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 153 "OPTIONAL" in this document are to be interpreted as described in BCP 154 14 [RFC2119] [RFC8174] when, and only when, they appear in all 155 capitals, as shown here. 157 The following terms are defined in the YANG data modeling language 158 [RFC7950]: action, anydata, anyxml, client, container, data model, 159 data node, identity, instance identifier, leaf, leaf-list, list, 160 module, RPC, schema node, server, submodule. 162 The following terms are defined in [RFC6241]: configuration data, 163 datastore, state data 165 The following term is defined in [I-D.ietf-core-sid]: YANG schema 166 item identifier (YANG SID, often shorten to simply SID). 168 The following terms are defined in the CoAP protocol [RFC7252]: 169 Confirmable Message, Content-Format, Endpoint. 171 The following terms are defined in this document: 173 data node resource: a CoAP resource that models a YANG data node. 175 datastore resource: a CoAP resource that models a YANG datastore. 177 event stream resource: a CoAP resource used by clients to observe 178 YANG notifications. 180 notification instance: An instance of a schema node of type 181 notification, specified in a YANG module implemented by the 182 server. The instance is generated in the server at the occurrence 183 of the corresponding event and reported by an event stream 184 resource. 186 list instance identifier: Handle used to identify a YANG data node 187 that is an instance of a YANG "list" specified with the values of 188 the key leaves of the list. 190 single instance identifier: Handle used to identify a specific data 191 node which can be instantiated only once. This includes data 192 nodes defined at the root of a YANG module and data nodes defined 193 within a container. This excludes data nodes defined within a 194 list or any children of these data nodes. 196 instance-identifier: List instance identifier or single instance 197 identifier. 199 instance-value: The value assigned to a data node instance. 200 Instance-values are serialized into the payload according to the 201 rules defined in section 4 of [I-D.ietf-core-yang-cbor]. 203 2. CORECONF Architecture 205 This section describes the CORECONF architecture to use CoAP for 206 reading and modifying the content of datastore(s) used for the 207 management of the instrumented node. 209 +----------------------------------------------------------------+ 210 | SMIv2 specification (optional) (2) | 211 +----------------------------------------------------------------+ 212 | 213 V 214 +----------------------------------------------------------------+ 215 | YANG specification (1) | 216 +----------------------------------------------------------------+ 217 | | 218 Client V Server V 219 +----------------+ +-----------------------+ 220 | Request |--> CoAP request(3) -->| Indication | 221 | Confirm |<-- CoAP response(3)<--| Response (4) | 222 | | | | 223 | |<==== Security (7) ===>|+---------------------+| 224 +----------------+ || Datastore(s) (5) || 225 |+---------------------+| 226 |+---------------------+| 227 || Event stream(s) (6) || 228 |+---------------------+| 229 +-----------------------+ 231 Figure 1: Abstract CORECONF architecture 233 Figure 1 is a high-level representation of the main elements of the 234 CORECONF management architecture. The different numbered components 235 of Figure 1 are discussed according to the component number. 237 (1) YANG specification: contains a set of named and versioned 238 modules. 240 (2) SMIv2 specification: Optional part that consists of a named 241 module which, specifies a set of variables and "conceptual 242 tables". There is an algorithm to translate SMIv2 specifications 243 to YANG specifications. 245 (3) CoAP request/response messages: The CORECONF client sends 246 request messages to and receives response messages from the 247 CORECONF server. 249 (4) Request, Indication, Response, Confirm: Processes performed by 250 the CORECONF clients and servers. 252 (5) Datastore: A resource used to access configuration data, state 253 data, RPCs, and actions. A CORECONF 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 CORECONF server may support multiple Event streams serving 259 different purposes such as normal monitoring, diagnostic, syslog, 260 security monitoring. 262 (7) Security: The server MUST prevent unauthorized users from 263 reading or writing any CORECONF resources. CORECONF relies on 264 security protocols such as DTLS [RFC6347] or OSCORE [RFC8613] to 265 secure CoAP communications. 267 2.1. Major differences between RESTCONF and CORECONF 269 CORECONF is a RESTful protocol for small devices where saving bytes 270 to transport a message is very important. Contrary to RESTCONF, many 271 design decisions are motivated by the saving of bytes. Consequently, 272 CORECONF is not a RESTCONF over CoAP protocol, but differs more 273 significantly from RESTCONF. 275 2.1.1. Differences due to CoAP and its efficient usage 277 o CORECONF uses CoAP/UDP as transport protocol and CBOR as payload 278 format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as 279 transport protocol and JSON or XML as payload formats. 281 o CORECONF uses the methods FETCH and iPATCH to access multiple data 282 nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP 283 method GET with the "fields" Query parameter. 285 o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not 286 supported by CoAP. 288 o CORECONF does not support "insert" query parameter (first, last, 289 before, after) and the "point" query parameter which are supported 290 by RESTCONF. 292 o CORECONF does not support the "start-time" and "stop-time" query 293 parameters to retrieve past notifications. 295 2.1.2. Differences due to the use of CBOR 297 o CORECONF encodes YANG identifier strings as numbers, where 298 RESTCONF does not. 300 o CORECONF also differ in the handling of default values, only 301 'report-all' and 'trim' options are supported. 303 2.2. Compression of YANG identifiers 305 In the YANG specification, items are identified with a name string. 306 In order to significantly reduce the size of identifiers used in 307 CORECONF, numeric identifiers called YANG Schema Item iDentifier 308 (YANG SID or simply SID) are used instead. 310 When used in a URI, SIDs are encoded using base64 encoding of the SID 311 bytes. The base64 encoding is using the URL and Filename safe 312 alphabet as defined by [RFC4648] section 5, without padding. The 313 last 6 bits encoded is always aligned with the least significant 6 314 bits of the SID represented using an unsigned integer. 'A' 315 characters (value 0) at the start of the resulting string are 316 removed. See Figure 2 for complete illustration. 318 SID in base64 = URLsafeChar[SID >> 60 & 0x3F] | 319 URLsafeChar[SID >> 54 & 0x3F] | 320 URLsafeChar[SID >> 48 & 0x3F] | 321 URLsafeChar[SID >> 42 & 0x3F] | 322 URLsafeChar[SID >> 36 & 0x3F] | 323 URLsafeChar[SID >> 30 & 0x3F] | 324 URLsafeChar[SID >> 24 & 0x3F] | 325 URLsafeChar[SID >> 18 & 0x3F] | 326 URLsafeChar[SID >> 12 & 0x3F] | 327 URLsafeChar[SID >> 6 & 0x3F] | 328 URLsafeChar[SID & 0x3F] 330 Figure 2 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 the two-character 347 string "a5". 349 2.3. Instance-identifier 351 Instance-identifiers are used to uniquely identify data node 352 instances within a datastore. This YANG built-in type is defined in 353 [RFC7950] section 9.13. An instance-identifier is composed of the 354 data node identifier (i.e. a SID) and for data nodes within list(s) 355 the keys used to index within these list(s). 357 When part of a payload, instance-identifiers are encoded in CBOR 358 based on the rules defined in [I-D.ietf-core-yang-cbor] section 359 6.13.1. When part of a URI, the SID is appended to the URI of the 360 targeted datastore, the keys are specified using the 'k' query 361 parameter as defined in Section 4.1. 363 2.4. Media-Types 365 CORECONF uses Media-Types based on the YANG to CBOR mapping specified 366 in [I-D.ietf-core-yang-cbor]. 368 The following Media-Type is used as defined in [I-D.ietf-core-sid]. 370 o application/yang-data+cbor; id=sid 372 The following new Media-Types are defined in this document: 374 application/yang-identifiers+cbor: This Media-Type represents a CBOR 375 YANG document containing a list of instance-identifier used to 376 target specific data node instances within a datastore. 378 FORMAT: CBOR array of instance-identifier 380 The message payload of Media-Type 'application/yang- 381 identifiers+cbor' is encoded using a CBOR array. Each entry of 382 this CBOR array contain an instance-identifier encoded as defined 383 in [I-D.ietf-core-yang-cbor] section 6.13.1. 385 application/yang-instances+cbor: This Media-Type represents a CBOR 386 YANG document containing a list of data node instances. Each data 387 node instance is identified by its associated instance-identifier. 389 FORMAT: CBOR array of CBOR map of instance-identifier, instance- 390 value 392 The message payload of Media-Type 'application/yang- 393 instances+cbor' is encoded using a CBOR array. Each entry within 394 this CBOR array contains a CBOR map carrying an instance- 395 identifier and associated instance-value. Instance-identifiers 396 are encoded using the rules defined in [I-D.ietf-core-yang-cbor] 397 section 6.13.1, instance-values are encoded using the rules 398 defined in [I-D.ietf-core-yang-cbor] section 4. 400 When present in an iPATCH request payload, this Media-Type carry a 401 list of data node instances to be replaced, created, or deleted. 402 For each data node instance D, for which the instance-identifier 403 is the same as a data node instance I, in the targeted datastore 404 resource: the value of D replaces the value of I. When the value 405 of D is null, the data node instance I is removed. When the 406 targeted datastore resource does not contain a data node instance 407 with the same instance-identifier as D, a new instance is created 408 with the same instance-identifier and value as D. 410 The different Media-Type usages are summarized in the table below: 412 +---------------+--------------+------------------------------------+ 413 | Method | Resource | Media-Type | 414 +---------------+--------------+------------------------------------+ 415 | GET response | data node | application/yang-data+cbor; id=sid | 416 | | | | 417 | PUT request | data node | application/yang-data+cbor; id=sid | 418 | | | | 419 | POST request | data node | application/yang-data+cbor; id=sid | 420 | | | | 421 | DELETE | data node | n/a | 422 | | | | 423 | GET response | datastore | application/yang-data+cbor; id=sid | 424 | | | | 425 | PUT request | datastore | application/yang-data+cbor; id=sid | 426 | | | | 427 | POST request | datastore | application/yang-data+cbor; id=sid | 428 | | | | 429 | FETCH request | datastore | application/yang-identifiers+cbor | 430 | | | | 431 | FETCH | datastore | application/yang-instances+cbor | 432 | response | | | 433 | | | | 434 | iPATCH | datastore | application/yang-instances+cbor | 435 | request | | | 436 | | | | 437 | GET response | event stream | application/yang-instances+cbor | 438 | | | | 439 | POST request | rpc, action | application/yang-data+cbor; id=sid | 440 | | | | 441 | POST response | rpc, action | application/yang-data+cbor; id=sid | 442 +---------------+--------------+------------------------------------+ 444 2.5. Unified datastore 446 CORECONF supports a simple datastore model consisting of a single 447 unified datastore. This datastore provides access to both 448 configuration and operational data. Configuration updates performed 449 on this datastore are reflected immediately or with a minimal delay 450 as operational data. 452 Alternatively, CORECONF servers MAY implement a more complex 453 datastore model such as the Network Management Datastore Architecture 454 (NMDA) as defined by [RFC8342]. Each datastore supported is 455 implemented as a datastore resource. 457 Characteristics of the unified datastore are summarized in the table 458 below: 460 +-------------+-----------------------------------------------------+ 461 | Name | Value | 462 +-------------+-----------------------------------------------------+ 463 | Name | unified | 464 | | | 465 | YANG | all modules | 466 | modules | | 467 | | | 468 | YANG nodes | all data nodes ("config true" and "config false") | 469 | | | 470 | Access | read-write | 471 | | | 472 | How applied | changes applied in place immediately or with a | 473 | | minimal delay | 474 | | | 475 | Protocols | CORECONF | 476 | | | 477 | Defined in | "ietf-coreconf" | 478 +-------------+-----------------------------------------------------+ 480 3. Example syntax 482 CBOR is used to encode CORECONF request and response payloads. The 483 CBOR syntax of the YANG payloads is specified in [RFC7049]. The 484 payload examples are notated in Diagnostic notation (defined in 485 section 6 of [RFC7049]) that can be automatically converted to CBOR. 487 SIDs in URIs are represented as a base64 number, SIDs in the payload 488 are represented as decimal numbers. 490 4. CoAP Interface 492 This note specifies a Management Interface. CoAP endpoints that 493 implement the CORECONF management protocol, support at least one 494 discoverable management resource of resource type (rt): core.c.ds. 495 The path of the discoverable management resource is left to 496 implementers to select (see Section 6). 498 The mapping of YANG data node instances to CORECONF resources is as 499 follows. Every data node of the YANG modules loaded in the CORECONF 500 server represents a sub-resource of the datastore resource (e.g. /c/ 501 YANGSID). When multiple instances of a list exist, instance 502 selection is possible as described in Section 4.1, Section 4.2.3.1, 503 and Section 4.2.4. 505 CORECONF also supports event stream resources used to observe 506 notification instances. Event stream resources can be discovered 507 using resource type (rt): core.c.ev. 509 The description of the CORECONF management interface is shown in the 510 table below: 512 +------------------------------+--------------+-----------+ 513 | CoAP resource | Example path | rt | 514 +------------------------------+--------------+-----------+ 515 | Datastore resource | /c | core.c.ds | 516 | | | | 517 | Data node resource | /c/YANGSID | core.c.dn | 518 | | | | 519 | Default event steam resource | /s | core.c.ev | 520 +------------------------------+--------------+-----------+ 522 The path values in the table are example ones. On discovery, the 523 server makes the actual path values known for these resources. 525 The methods used by CORECONF are: 527 +-----------+-------------------------------------------------------+ 528 | Operation | Description | 529 +-----------+-------------------------------------------------------+ 530 | GET | Retrieve the datastore resource or a data node | 531 | | resource | 532 | | | 533 | FETCH | Retrieve specific data nodes within a datastore | 534 | | resource | 535 | | | 536 | POST | Create a datastore resource or a data node resource, | 537 | | invoke an RPC or action | 538 | | | 539 | PUT | Create or replace a datastore resource or a data node | 540 | | resource | 541 | | | 542 | iPATCH | Idem-potently create, replace, and delete data node | 543 | | resource(s) within a datastore resource | 544 | | | 545 | DELETE | Delete a datastore resource or a data node resource | 546 +-----------+-------------------------------------------------------+ 548 There is at most one instance of the 'k' query parameter for YANG 549 list element selection for the GET, PUT, POST, and DELETE methods. 550 Having multiple instances of that query parameter shall be treated as 551 an error. 553 +-----------------+----------------------------------------+ 554 | Query parameter | Description | 555 +-----------------+----------------------------------------+ 556 | k | Select an instance within YANG list(s) | 557 +-----------------+----------------------------------------+ 559 This parameter is not used for FETCH and iPATCH, because their 560 request payloads support list instance selection. 562 4.1. Using the 'k' query parameter 564 The 'k' (key) parameter specifies a specific instance of a data node. 565 The SID in the URI is followed by the (?k=key1,key2,...). Where SID 566 identifies a data node, and key1, key2 are the values of the key 567 leaves that specify an instance. Lists can have multiple keys, and 568 lists can be part of lists. The order of key value generation is 569 given recursively by: 571 o For a given list, if a parent data node is a list, generate the 572 keys for the parent list first. 574 o For a given list, generate key values in the order specified in 575 the YANG module. 577 Key values are encoded using the rules defined in the following 578 table. 580 +-----------------------------+--------------------------------+ 581 | YANG datatype | Uri-Query text content | 582 +-----------------------------+--------------------------------+ 583 | uint8,uint16,unit32, uint64 | int2str(key) | 584 | | | 585 | int8, int16,int32, int64 | urlSafeBase64(CBORencode(key)) | 586 | | | 587 | decimal64 | urlSafeBase64(CBOR key) | 588 | | | 589 | string | key | 590 | | | 591 | boolean | "0" or "1" | 592 | | | 593 | enumeration | int2str(key) | 594 | | | 595 | bits | urlSafeBase64(CBORencode(key)) | 596 | | | 597 | binary | urlSafeBase64(key) | 598 | | | 599 | identityref | int2str(key) | 600 | | | 601 | union | urlSafeBase64(CBORencode(key)) | 602 | | | 603 | instance-identifier | urlSafeBase64(CBORencode(key)) | 604 +-----------------------------+--------------------------------+ 606 In this table: 608 o The method int2str() is used to convert an integer value to a 609 decimal string. For example, int2str(0x0123) return the three- 610 character string "291". 612 o The boolean values false and true are represented as the single- 613 character strings "0" and "1" respectively. 615 o The method urlSafeBase64() is used to convert a binary string to 616 base64 using the URL and Filename safe alphabet as defined by 617 [RFC4648] section 5, without padding. For example, 618 urlSafeBase64(0xF956A13C) return the six-character string 619 "-VahPA". 621 o The method CBORencode() is used to convert a YANG value to CBOR as 622 specified in [I-D.ietf-core-yang-cbor] section 6. 624 The resulting key strings are joined using commas between every two 625 consecutive key values to produce the value of the 'k' parameter. 627 4.2. Data Retrieval 629 One or more data nodes can be retrieved by the client. The operation 630 is mapped to the GET method defined in section 5.8.1 of [RFC7252] and 631 to the FETCH method defined in section 2 of [RFC8132]. 633 There are two additional query parameters for the GET and FETCH 634 methods. 636 +-------------+-----------------------------------------------------+ 637 | query | Description | 638 | parameters | | 639 +-------------+-----------------------------------------------------+ 640 | c | Control selection of configuration and non- | 641 | | configuration data nodes (GET and FETCH) | 642 | | | 643 | d | Control retrieval of default values. | 644 +-------------+-----------------------------------------------------+ 646 4.2.1. Using the 'c' query parameter 648 The 'c' (content) option controls how descendant nodes of the 649 requested data nodes will be processed in the reply. 651 The allowed values are: 653 +-------+-----------------------------------------------------+ 654 | Value | Description | 655 +-------+-----------------------------------------------------+ 656 | c | Return only configuration descendant data nodes | 657 | | | 658 | n | Return only non-configuration descendant data nodes | 659 | | | 660 | a | Return all descendant data nodes | 661 +-------+-----------------------------------------------------+ 663 This option is only allowed for GET and FETCH methods on datastore 664 and data node resources. A 4.02 (Bad Option) error is returned if 665 used for other methods or resource types. 667 If this query parameter is not present, the default value is "a" (the 668 quotes are added for readability, but they are not part of the 669 payload). 671 4.2.2. Using the 'd' query parameter 673 The 'd' (with-defaults) option controls how the default values of the 674 descendant nodes of the requested data nodes will be processed. 676 The allowed values are: 678 +-------+-----------------------------------------------------------+ 679 | Value | Description | 680 +-------+-----------------------------------------------------------+ 681 | a | All data nodes are reported. Defined as 'report-all' in | 682 | | section 3.1 of [RFC6243]. | 683 | | | 684 | t | Data nodes set to the YANG default are not reported. | 685 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 686 +-------+-----------------------------------------------------------+ 688 If the target of a GET or FETCH method is a data node that represents 689 a leaf that has a default value, and the leaf has not been given a 690 value by any client yet, the server MUST return the default value of 691 the leaf. 693 If the target of a GET method is a data node that represents a 694 container or list that has child resources with default values, and 695 these have not been given value yet, 697 The server MUST NOT return the child resource if d=t 699 The server MUST return the child resource if d=a. 701 If this query parameter is not present, the default value is "t" (the 702 quotes are added for readability, but they are not part of the 703 payload). 705 4.2.3. GET 707 A request to read the value of a data node instance is sent with a 708 CoAP GET message. The URI is set to the data node resource 709 requested, the 'k' query parameter is added if any of the parents of 710 the requested data node is a list node. 712 FORMAT: 713 GET ['k' Uri-Query option] 715 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 716 CBOR map of SID, instance-value 718 The returned payload contains the CBOR encoding of the requested 719 instance-value. 721 4.2.3.1. GET Examples 723 Using, for example, the current-datetime leaf from module ietf-system 724 [RFC7317], a request is sent to retrieve the value of 'system- 725 state/clock/current-datetime'. The SID of 'system-state/clock/ 726 current-datetime' is 1723, encoded in base64 according to 727 Section 2.2, yields a7. The response to the request returns the CBOR 728 map with the key set to the SID of the requested data node (i.e. 729 1723) and the value encoded using a 'text string' as defined in 730 [I-D.ietf-core-yang-cbor] section 6.4. The datastore resource path 731 /c is an example location discovered with a request similar to 732 Figure 4. 734 REQ: GET 736 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 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 CORECONF 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 749 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 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 766 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 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 CORECONF client adds the key of the targeted instance in 788 its CoAP request using the 'k' query parameter. The return payload 789 containing the instance requested is encoded using a CBOR array as 790 specified by [I-D.ietf-core-yang-cbor] section 4.4.1 containing the 791 requested instance. 793 REQ: GET 795 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 796 { 797 1533 : [ 798 { 799 4 : "eth0", / name (SID 1537) / 800 1 : "Ethernet adaptor", / description (SID 1534) / 801 5 : 1880, / type, (SID 1538) identity / 802 / ethernetCsmacd (SID 1880) / 803 2 : true / enabled (SID 1535) / 804 } 805 ] 806 } 808 It is equally possible to select a leaf of a specific instance of a 809 list. The example below requests the description leaf (SID 1534, 810 base64: X-) within the interface list corresponding to the interface 811 name "eth0". The returned value is encoded in CBOR based on the 812 rules specified by [I-D.ietf-core-yang-cbor] section 6.4. 814 REQ: GET 816 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 817 { 818 1534 : "Ethernet adaptor" 819 } 821 4.2.4. FETCH 823 The FETCH is used to retrieve multiple instance-values. The FETCH 824 request payload contains the list of instance-identifier of the data 825 node instances requested. 827 The return response payload contains a list of data node instance- 828 values in the same order as requested. A CBOR null is returned for 829 each data node requested by the client, not supported by the server 830 or not currently instantiated. 832 For compactness, indexes of the list instance identifiers returned by 833 the FETCH response SHOULD be elided, only the SID is provided. This 834 approach may also help reducing implementations complexity since the 835 format of each entry within the CBOR array of the FETCH response is 836 identical to the format of the corresponding GET response. 838 FORMAT: 839 FETCH 840 (Content-Format: application/yang-identifiers+cbor) 841 CBOR array of instance-identifier 843 2.05 Content (Content-Format: application/yang-instances+cbor) 844 CBOR array of CBOR map of SID, instance-value 846 4.2.4.1. FETCH examples 848 This example uses the current-datetime leaf from module ietf-system 849 [RFC7317] and the interface list from module ietf-interfaces 850 [RFC8343]. In this example the value of current-datetime (SID 1723) 851 and the interface list (SID 1533) instance identified with 852 name="eth0" are queried. 854 REQ: FETCH 855 (Content-Format: application/yang-identifiers+cbor) 856 [ 857 1723, / current-datetime (SID 1723) / 858 [1533, "eth0"] / interface (SID 1533) with name = "eth0" / 859 ] 861 RES: 2.05 Content (Content-Format: application/yang-instances+cbor) 862 [ 863 { 864 1723 : "2014-10-26T12:16:31Z" / current-datetime (SID 1723) / 865 }, 866 { 867 1533 : { 868 4 : "eth0", / name (SID 1537) / 869 1 : "Ethernet adaptor", / description (SID 1534) / 870 5 : 1880, / type (SID 1538), identity / 871 / ethernetCsmacd (SID 1880) / 872 2 : true, / enabled (SID 1535) / 873 11 : 3 / oper-status (SID 1544), value is testing / 874 } 875 } 876 ] 878 4.3. Data Editing 880 CORECONF allows datastore contents to be created, modified and 881 deleted using CoAP methods. 883 4.3.1. Data Ordering 885 A CORECONF server MUST preserve the relative order of all user- 886 ordered list and leaf-list entries that are received in a single edit 887 request. These YANG data node types are encoded as CBOR arrays so 888 messages will preserve their order. 890 4.3.2. POST 892 The CoAP POST operation is used in CORECONF for the creation of data 893 node resources and the invocation of "ACTION" and "RPC" resources. 894 Refer to Section 4.6 for details on "ACTION" and "RPC" resources. 896 A request to create a data node instance is sent with a CoAP POST 897 message. The URI specifies the data node resource of the instance to 898 be created. In the case of a list instance, keys MUST be present in 899 the payload. 901 FORMAT: 902 POST 903 (Content-Format: application/yang-data+cbor; id=sid) 904 CBOR map of SID, instance-value 906 2.01 Created 908 If the data node instance already exists, then the POST request MUST 909 fail and a "4.09 Conflict" response code MUST be returned 911 4.3.2.1. Post example 913 The example uses the interface list from module ietf-interfaces 914 [RFC8343]. This example creates a new list instance within the 915 interface list (SID = 1533), while assuming the datastore resource is 916 hosted on the CoAP server with DNS name example.com and with path 917 /ds. The path /ds is an example location that is assumed to have 918 been discovered using request similar to Figure 4. 920 REQ: POST 921 (Content-Format: application/yang-data+cbor; id=sid) 922 { 923 1533 : [ 924 { 925 4 : "eth5", / name (SID 1537) / 926 1 : "Ethernet adaptor", / description (SID 1534) / 927 5 : 1880, / type (SID 1538), identity / 928 / ethernetCsmacd (SID 1880) / 929 2 : true / enabled (SID 1535) / 930 } 931 ] 932 } 934 RES: 2.01 Created 936 4.3.3. PUT 938 A data node resource instance is created or replaced with the PUT 939 method. A request to set the value of a data node instance is sent 940 with a CoAP PUT message. 942 FORMAT: 943 PUT ['k' Uri-Query option] 944 (Content-Format: application/yang-data+cbor; id=sid) 945 CBOR map of SID, instance-value 947 2.01 Created 949 4.3.3.1. PUT example 951 The example uses the interface list from module ietf-interfaces 952 [RFC8343]. This example updates the instance of the list interface 953 (SID = 1533) with key name="eth0". The example location /c is an 954 example location that is discovered using a request similar to 955 Figure 4. 957 REQ: PUT 958 (Content-Format: application/yang-data+cbor; id=sid) 959 { 960 1533 : [ 961 { 962 4 : "eth0", / name (SID 1537) / 963 1 : "Ethernet adaptor", / description (SID 1534) / 964 5 : 1880, / type (SID 1538), identity / 965 / ethernetCsmacd (SID 1880) / 966 2 : true / enabled (SID 1535) / 967 } 968 ] 969 } 971 RES: 2.04 Changed 973 4.3.4. iPATCH 975 One or multiple data node instances are replaced with the idempotent 976 CoAP iPATCH method [RFC8132]. 978 There are no query parameters for the iPATCH method. 980 The processing of the iPATCH command is specified by Media-Type 981 'application/yang-instances+cbor'. In summary, if the CBOR patch 982 payload contains a data node instance that is not present in the 983 target, this instance is added. If the target contains the specified 984 instance, the content of this instance is replaced with the value of 985 the payload. A null value indicates the removal of an existing data 986 node instance. 988 FORMAT: 989 iPATCH 990 (Content-Format: application/yang-instances+cbor) 991 CBOR array of CBOR map of instance-identifier, instance-value 993 2.04 Changed 995 4.3.4.1. iPATCH example 997 In this example, a CORECONF client requests the following operations: 999 o Set "/system/ntp/enabled" (SID 1755) to true. 1001 o Remove the server "tac.nrc.ca" from the "/system/ntp/server" (SID 1002 1756) list. 1004 o Add/set the server "NTP Pool server 2" to the list "/system/ntp/ 1005 server" (SID 1756). 1007 REQ: iPATCH 1008 (Content-Format: application/yang-instances+cbor) 1009 [ 1010 { 1011 1755 : true / enabled (SID 1755) / 1012 }, 1013 { 1014 [1756, "tac.nrc.ca"] : null / server (SID 1756) / 1015 }, 1016 { 1017 1756 : { / server (SID 1756) / 1018 3 : "tic.nrc.ca", / name (SID 1759) / 1019 4 : true, / prefer (SID 1760) / 1020 5 : { / udp (SID 1761) / 1021 1 : "132.246.11.231" / address (SID 1762) / 1022 } 1023 } 1024 } 1025 ] 1027 RES: 2.04 Changed 1029 4.3.5. DELETE 1031 A data node resource is deleted with the DELETE method. 1033 FORMAT: 1034 Delete ['k' Uri-Query option] 1036 2.02 Deleted 1038 4.3.5.1. DELETE example 1040 This example uses the interface list from module ietf-interfaces 1041 [RFC8343]. This example deletes an instance of the interface list 1042 (SID = 1533): 1044 REQ: DELETE 1046 RES: 2.02 Deleted 1048 4.4. Full datastore access 1050 The methods GET, PUT, POST, and DELETE can be used to request, 1051 replace, create, and delete a whole datastore respectively. 1053 FORMAT: 1054 GET 1056 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 1057 CBOR map of SID, instance-value 1059 FORMAT: 1060 PUT 1061 (Content-Format: application/yang-data+cbor; id=sid) 1062 CBOR map of SID, instance-value 1064 2.04 Changed 1066 FORMAT: 1067 POST 1068 (Content-Format: application/yang-data+cbor; id=sid) 1069 CBOR map of SID, instance-value 1071 2.01 Created 1073 FORMAT: 1074 DELETE 1076 2.02 Deleted 1078 The content of the CBOR map represents the complete datastore of the 1079 server at the GET indication of after a successful processing of a 1080 PUT or POST request. 1082 4.4.1. Full datastore examples 1084 The example uses the interface list from module ietf-interfaces 1085 [RFC8343] and the clock container from module ietf-system [RFC7317]. 1086 We assume that the datastore contains two modules ietf-system (SID 1087 1700) and ietf-interfaces (SID 1500); they contain the 'interface' 1088 list (SID 1533) with one instance and the 'clock' container (SID 1089 1721). After invocation of GET, a CBOR map with data nodes from 1090 these two modules is returned: 1092 REQ: GET 1094 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 1095 { 1096 1721 : { / Clock (SID 1721) / 1097 2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) / 1098 1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) / 1099 }, 1100 1533 : [ 1101 { / interface (SID 1533) / 1102 4 : "eth0", / name (SID 1537) / 1103 1 : "Ethernet adaptor", / description (SID 1534) / 1104 5 : 1880, / type (SID 1538), identity: / 1105 / ethernetCsmacd (SID 1880) / 1106 2 : true, / enabled (SID 1535) / 1107 11 : 3 / oper-status (SID 1544), value is testing / 1108 } 1109 ] 1110 } 1112 4.5. Event stream 1114 Event notification is an essential function for the management of 1115 servers. CORECONF allows notifications specified in YANG [RFC5277] 1116 to be reported to a list of clients. The path for the default event 1117 stream can be discovered as described in Section 4. The server MAY 1118 support additional event stream resources to address different 1119 notification needs. 1121 Reception of notification instances is enabled with the CoAP Observe 1122 [RFC7641] function. Clients subscribe to the notifications by 1123 sending a GET request with an "Observe" option to the stream 1124 resource. 1126 Each response payload carries one or multiple notifications. The 1127 number of notifications reported, and the conditions used to remove 1128 notifications from the reported list are left to implementers. When 1129 multiple notifications are reported, they MUST be ordered starting 1130 from the newest notification at index zero. Note that this could 1131 lead to notifications being sent multiple times, which increases the 1132 probability for the client to receive them, but it might potentially 1133 lead to messages that exceed the MTU of a single CoAP packet. If 1134 such cases could arise, implementers should make sure appropriate 1135 fragmentation is available - for example the one described in 1136 Section 5. 1138 The format of notification without any content is a null value. The 1139 format of single notification is defined in [I-D.ietf-core-yang-cbor] 1140 section 4.2.1. For multiple notifications the format is an array 1141 where each element is a single notification as described in 1142 [I-D.ietf-core-yang-cbor] section 4.2.1. 1144 FORMAT: 1145 GET Observe(0) 1147 2.05 Content (Content-Format: application/yang-instances+cbor) 1148 CBOR array of CBOR map of instance-identifier, instance-value 1150 The array of data node instances may contain identical entries which 1151 have been generated at different times. 1153 An example implementation is: 1155 Every time an event is generated, the generated notification 1156 instance is appended to the chosen stream(s). After an 1157 aggregation period, which may be limited by the maximum number of 1158 notifications supported, the content of the instance is sent to 1159 all clients observing the modified stream. 1161 4.5.1. Notify Examples 1163 Let suppose the server generates the example-port-fault event as 1164 defined below. 1166 module example-port { 1167 ... 1168 notification example-port-fault { // SID 60010 1169 description 1170 "Event generated if a hardware fault is detected"; 1171 leaf port-name { // SID 60011 1172 type string; 1173 } 1174 leaf port-fault { // SID 60012 1175 type string; 1176 } 1177 } 1178 } 1180 In this example the default event stream resource path /s is an 1181 example location discovered with a request similar to Figure 5. By 1182 executing a GET with Observe 0 on the default event stream resource 1183 the client receives the following response: 1185 REQ: GET Observe(0) 1187 RES: 2.05 Content (Content-Format: application/yang-tree+cbor) 1188 Observe(12) 1189 [ 1190 { 1191 60010 : { / example-port-fault (SID 60010) / 1192 1 : "0/4/21", / port-name (SID 60011) / 1193 2 : "Open pin 2" / port-fault (SID 60012) / 1194 } 1195 }, 1196 { 1197 60010 : { / example-port-fault (SID 60010) / 1198 1 : "1/4/21", / port-name (SID 60011) / 1199 2 : "Open pin 5" / port-fault (SID 60012) / 1200 } 1201 } 1202 ] 1204 In the example, the request returns a success response with the 1205 contents of the last two generated events. Consecutively the server 1206 will regularly notify the client when a new event is generated. 1208 4.5.2. The 'f' query parameter 1210 The 'f' (filter) option is used to indicate which subset of all 1211 possible notifications is of interest. If not present, all 1212 notifications supported by the event stream are reported. 1214 When not supported by a CORECONF server, this option shall be 1215 ignored, all events notifications are reported independently of the 1216 presence and content of the 'f' (filter) option. 1218 When present, this option contains a comma-separated list of 1219 notification SIDs. For example, the following request returns 1220 notifications 60010 and 60020. 1222 REQ: GET Observe(0) 1224 4.6. RPC statements 1226 The YANG "action" and "RPC" statements specify the execution of a 1227 Remote procedure Call (RPC) in the server. It is invoked using a 1228 POST method to an "Action" or "RPC" resource instance. 1230 The request payload contains the values assigned to the input 1231 container when specified. The response payload contains the values 1232 of the output container when specified. Both the input and output 1233 containers are encoded in CBOR using the rules defined in 1234 [I-D.ietf-core-yang-cbor] section 4.2.1. 1236 The returned success response code is 2.05 Content. 1238 FORMAT: 1239 POST ['k' Uri-Query option] 1240 (Content-Format: application/yang-data+cbor; id=sid) 1241 CBOR map of SID, instance-value 1243 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 1244 CBOR map of SID, instance-value 1246 4.6.1. RPC Example 1248 The example is based on the YANG action "reset" as defined in 1249 [RFC7950] section 7.15.3 and annotated below with SIDs. 1251 module example-server-farm { 1252 yang-version 1.1; 1253 namespace "urn:example:server-farm"; 1254 prefix "sfarm"; 1256 import ietf-yang-types { 1257 prefix "yang"; 1258 } 1260 list server { // SID 60000 1261 key name; 1262 leaf name { // SID 60001 1263 type string; 1264 } 1265 action reset { // SID 60002 1266 input { 1267 leaf reset-at { // SID 60003 1268 type yang:date-and-time; 1269 mandatory true; 1270 } 1271 } 1272 output { 1273 leaf reset-finished-at { // SID 60004 1274 type yang:date-and-time; 1275 mandatory true; 1276 } 1277 } 1278 } 1279 } 1280 } 1282 This example invokes the 'reset' action (SID 60002, base64: Opq), of 1283 the server instance with name equal to "myserver". 1285 REQ: POST 1286 (Content-Format: application/yang-data+cbor; id=sid) 1287 { 1288 60002 : { 1289 1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / 1290 } 1291 } 1293 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 1294 { 1295 60002 : { 1296 2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ 1297 } 1298 } 1300 5. Use of Block-wise Transfers 1302 The CoAP protocol provides reliability by acknowledging the UDP 1303 datagrams. However, when large pieces of data need to be 1304 transported, datagrams get fragmented, thus creating constraints on 1305 the resources in the client, server and intermediate routers. The 1306 block option [RFC7959] allows the transport of the total payload in 1307 individual blocks of which the size can be adapted to the underlying 1308 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1309 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1310 acknowledged to guarantee reliability. 1312 Notice that the Block mechanism splits the data at fixed positions, 1313 such that individual data fields may become fragmented. Therefore, 1314 assembly of multiple blocks may be required to process complete data 1315 fields. 1317 Beware of race conditions. In case blocks are filled one at a time, 1318 care should be taken that the whole and consistent data 1319 representation is sent in multiple blocks sequentially without 1320 interruption. On the server, values might change, lists might get 1321 re-ordered, extended or reduced. When these actions happen during 1322 the serialization of the contents of the resource, the transported 1323 results do not correspond with a state having occurred in the server; 1324 or worse the returned values are inconsistent. For example: array 1325 length does not correspond with the actual number of items. It may 1326 be advisable to use Indefinite-length CBOR arrays and maps, which are 1327 foreseen for data streaming purposes. 1329 6. Application Discovery 1331 Two application discovery mechanisms are supported by CORECONF, the 1332 YANG library data model as defined by [I-D.ietf-core-yang-library] 1333 and the CORE resource discovery [RFC6690]. Implementers may choose 1334 to implement one or the other or both. 1336 6.1. YANG library 1338 The YANG library data model [I-D.ietf-core-yang-library] provides a 1339 high-level description of the resources available. The YANG library 1340 contains the list of modules, features, and deviations supported by 1341 the CORECONF server. From this information, CORECONF clients can 1342 infer the list of data nodes supported and the interaction model to 1343 be used to access them. This module also contains the list of 1344 datastores implemented. 1346 As described in [RFC6690], the location of the YANG library can be 1347 found by sending a GET request to "/.well-known/core" including a 1348 resource type (RT) parameter with the value "core.c.yl". Upon 1349 success, the return payload will contain the root resource of the 1350 YANG library module. 1352 The following example assumes that the SID of the YANG library is 1353 2351 (kv encoded as specified in Section 2.2) and that the server 1354 uses /c as datastore resource path. 1356 REQ: GET 1358 RES: 2.05 Content (Content-Format: application/link-format) 1359 ;rt="core.c.yl" 1361 6.2. Resource Discovery 1363 As some CoAP interfaces and services might not support the YANG 1364 library interface and still be interested to discover resources that 1365 are available, implementations MAY choose to support discovery of all 1366 available resources using "/.well-known/core" as defined by 1367 [RFC6690]. 1369 6.2.1. Datastore Resource Discovery 1371 The presence and location of (path to) each datastore implemented by 1372 the CORECONF server can be discovered by sending a GET request to 1373 "/.well-known/core" including a resource type (RT) parameter with the 1374 value "core.c.ds". 1376 Upon success, the return payload contains the list of datastore 1377 resources. 1379 Each datastore returned is further qualified using the "ds" Link- 1380 Format attribute. This attribute is set to the SID assigned to the 1381 datastore identity. When a unified datastore is implemented, the ds 1382 attribute is set to 1029 as specified in Appendix B. For other 1383 examples of datastores, see the Network Management Datastore 1384 Architecture (NMDA) [RFC7950]. 1386 link-extension = ( "ds" "=" sid ) ) 1387 ; SID assigned to the datastore identity 1388 sid = 1*DIGIT 1390 The following example assumes that the server uses /c as datastore 1391 resource path. 1393 REQ: GET 1395 RES: 2.05 Content (Content-Format: application/link-format) 1396 ; rt="core.c.ds";ds=1029 1398 Figure 4 1400 6.2.2. Data node Resource Discovery 1402 If implemented, the presence and location of (path to) each data node 1403 implemented by the CORECONF server are discovered by sending a GET 1404 request to "/.well-known/core" including a resource type (RT) 1405 parameter with the value "core.c.dn". 1407 Upon success, the return payload contains the SID assigned to each 1408 data node and their location. 1410 The example below shows the discovery of the presence and location of 1411 data nodes. Data nodes '/ietf-system:system-state/clock/boot- 1412 datetime' (SID 1722) and '/ietf-system:system-state/clock/current- 1413 datetime' (SID 1723) are returned. The example assumes that the 1414 server uses /c as datastore resource path. 1416 REQ: GET 1418 RES: 2.05 Content (Content-Format: application/link-format) 1419 ;rt="core.c.dn", 1420 ;rt="core.c.dn" 1422 Without additional filtering, the list of data nodes may become 1423 prohibitively long. If this is the case implementations SHOULD 1424 support a way to obtain all links using multiple GET requests (for 1425 example through some form of pagination). 1427 6.2.3. Event stream Resource Discovery 1429 The presence and location of (path to) each event stream implemented 1430 by the CORECONF server are discovered by sending a GET request to 1431 "/.well-known/core" including a resource type (RT) parameter with the 1432 value "core.c.es". 1434 Upon success, the return payload contains the list of event stream 1435 resources. 1437 The following example assumes that the server uses /s as the default 1438 event stream resource. 1440 REQ: GET 1442 RES: 2.05 Content (Content-Format: application/link-format) 1443 ;rt="core.c.es" 1445 Figure 5 1447 7. Error Handling 1449 In case a request is received which cannot be processed properly, the 1450 CORECONF server MUST return an error response. This error response 1451 MUST contain a CoAP 4.xx or 5.xx response code. 1453 Errors returned by a CORECONF server can be broken into two 1454 categories, those associated with the CoAP protocol itself and those 1455 generated during the validation of the YANG data model constrains as 1456 described in [RFC7950] section 8. 1458 The following list of common CoAP errors should be implemented by 1459 CORECONF servers. This list is not exhaustive, other errors defined 1460 by CoAP and associated RFCs may be applicable. 1462 o Error 4.01 (Unauthorized) is returned by the CORECONF server when 1463 the CORECONF client is not authorized to perform the requested 1464 action on the targeted resource (i.e. data node, datastore, rpc, 1465 action or event stream). 1467 o Error 4.02 (Bad Option) is returned by the CORECONF server when 1468 one or more CoAP options are unknown or malformed. 1470 o Error 4.04 (Not Found) is returned by the CORECONF server when the 1471 CORECONF client is requesting a non-instantiated resource (i.e. 1472 data node, datastore, rpc, action or event stream). 1474 o Error 4.05 (Method Not Allowed) is returned by the CORECONF server 1475 when the CORECONF client is requesting a method not supported on 1476 the targeted resource. (e.g. GET on an rpc, PUT or POST on a data 1477 node with "config" set to false). 1479 o Error 4.08 (Request Entity Incomplete) is returned by the CORECONF 1480 server if one or multiple blocks of a block transfer request is 1481 missing, see [RFC7959] for more details. 1483 o Error 4.13 (Request Entity Too Large) may be returned by the 1484 CORECONF server during a block transfer request, see [RFC7959] for 1485 more details. 1487 o Error 4.15 (Unsupported Content-Format) is returned by the 1488 CORECONF server when the Content-Format used in the request does 1489 not match those specified in section Section 2.4. 1491 The CORECONF server MUST also enforce the different constraints 1492 associated with the YANG data models implemented. These constraints 1493 are described in [RFC7950] section 8. These errors are reported 1494 using the CoAP error code 4.00 (Bad Request) and may have the 1495 following error container as payload. The YANG definition and 1496 associated .sid file are available in Appendix A and Appendix B. The 1497 error container is encoded using the encoding rules of a YANG data 1498 template as defined in [I-D.ietf-core-yang-cbor] section 5. 1500 +--rw error! 1501 +--rw error-tag identityref 1502 +--rw error-app-tag? identityref 1503 +--rw error-data-node? instance-identifier 1504 +--rw error-message? string 1506 The following 'error-tag' and 'error-app-tag' are defined by the 1507 ietf-coreconf YANG module, these tags are implemented as YANG 1508 identity and can be extended as needed. 1510 o error-tag 'operation-failed' is returned by the CORECONF server 1511 when the operation request cannot be processed successfully. 1513 * error-app-tag 'malformed-message' is returned by the CORECONF 1514 server when the payload received from the CORECONF client does 1515 not contain a well-formed CBOR content as defined in [RFC7049] 1516 section 3.3 or does not comply with the CBOR structure defined 1517 within this document. 1519 * error-app-tag 'data-not-unique' is returned by the CORECONF 1520 server when the validation of the 'unique' constraint of a list 1521 or leaf-list fails. 1523 * error-app-tag 'too-many-elements' is returned by the CORECONF 1524 server when the validation of the 'max-elements' constraint of 1525 a list or leaf-list fails. 1527 * error-app-tag 'too-few-elements' is returned by the CORECONF 1528 server when the validation of the 'min-elements' constraint of 1529 a list or leaf-list fails. 1531 * error-app-tag 'must-violation' is returned by the CORECONF 1532 server when the restrictions imposed by a 'must' statement are 1533 violated. 1535 * error-app-tag 'duplicate' is returned by the CORECONF server 1536 when a client tries to create a duplicate list or leaf-list 1537 entry. 1539 o error-tag 'invalid-value' is returned by the CORECONF server when 1540 the CORECONF client tries to update or create a leaf with a value 1541 encoded using an invalid CBOR datatype or if the 'range', 1542 'length', 'pattern' or 'require-instance' constrain is not 1543 fulfilled. 1545 * error-app-tag 'invalid-datatype' is returned by the CORECONF 1546 server when CBOR encoding does not follow the rules set by the 1547 YANG Build-In type or when the value is incompatible with it 1548 (e.g. a value greater than 127 for an int8, undefined 1549 enumeration). 1551 * error-app-tag 'not-in-range' is returned by the CORECONF server 1552 when the validation of the 'range' property fails. 1554 * error-app-tag 'invalid-length' is returned by the CORECONF 1555 server when the validation of the 'length' property fails. 1557 * error-app-tag 'pattern-test-failed' is returned by the CORECONF 1558 server when the validation of the 'pattern' property fails. 1560 o error-tag 'missing-element' is returned by the CORECONF server 1561 when the operation requested by a CORECONF client fails to comply 1562 with the 'mandatory' constraint defined. The 'mandatory' 1563 constraint is enforced for leafs and choices, unless the node or 1564 any of its ancestors have a 'when' condition or 'if-feature' 1565 expression that evaluates to 'false'. 1567 * error-app-tag 'missing-key' is returned by the CORECONF server 1568 to further qualify a missing-element error. This error is 1569 returned when the CORECONF client tries to create or list 1570 instance, without all the 'key' specified or when the CORECONF 1571 client tries to delete a leaf listed as a 'key'. 1573 * error-app-tag 'missing-input-parameter' is returned by the 1574 CORECONF server when the input parameters of an RPC or action 1575 are incomplete. 1577 o error-tag 'unknown-element' is returned by the CORECONF server 1578 when the CORECONF client tries to access a data node of a YANG 1579 module not supported, of a data node associated with an 'if- 1580 feature' expression evaluated to 'false' or to a 'when' condition 1581 evaluated to 'false'. 1583 o error-tag 'bad-element' is returned by the CORECONF server when 1584 the CORECONF client tries to create data nodes for more than one 1585 case in a choice. 1587 o error-tag 'data-missing' is returned by the CORECONF server when a 1588 data node required to accept the request is not present. 1590 * error-app-tag 'instance-required' is returned by the CORECONF 1591 server when a leaf of type 'instance-identifier' or 'leafref' 1592 marked with require-instance set to 'true' refers to an 1593 instance that does not exist. 1595 * error-app-tag 'missing-choice' is returned by the CORECONF 1596 server when no nodes exist in a mandatory choice. 1598 o error-tag 'error' is returned by the CORECONF server when an 1599 unspecified error has occurred. 1601 For example, the CORECONF server might return the following error. 1603 RES: 4.00 Bad Request (Content-Format: application/yang-data+cbor; id=sid) 1604 { 1605 1024 : { 1606 4 : 1011, / error-tag (SID 1028) / 1607 / = invalid-value (SID 1011) / 1608 1 : 1018, / error-app-tag (SID 1025) / 1609 / = not-in-range (SID 1018) / 1610 2 : 1740, / error-data-node (SID 1026) / 1611 / = timezone-utc-offset (SID 1740) / 1612 3 : "maximum value exceeded" / error-message (SID 1027) / 1613 } 1614 } 1616 8. Security Considerations 1618 For secure network management, it is important to restrict access to 1619 configuration variables only to authorized parties. CORECONF re-uses 1620 the security mechanisms already available to CoAP, this includes DTLS 1621 [RFC6347] and OSCORE [RFC8613] for protected access to resources, as 1622 well as suitable authentication and authorization mechanisms, for 1623 example those defined in ACE OAuth [I-D.ietf-ace-oauth-authz]. 1625 All the security considerations of [RFC7252], [RFC7959], [RFC8132] 1626 and [RFC7641] apply to this document as well. The use of NoSec DTLS, 1627 when OSCORE is not used, is NOT RECOMMENDED. 1629 In addition, mechanisms for authentication and authorization may need 1630 to be selected if not provided with the CoAP security mode. 1632 As [I-D.ietf-core-yang-cbor] and [RFC4648] are used for payload and 1633 SID encoding, the security considerations of those documents also 1634 need to be well-understood. 1636 9. IANA Considerations 1638 9.1. Resource Type (rt=) Link Target Attribute Values Registry 1640 This document adds the following resource type to the "Resource Type 1641 (rt=) Link Target Attribute Values", within the "Constrained RESTful 1642 Environments (CoRE) Parameters" registry. 1644 +-----------+---------------------+-----------+ 1645 | Value | Description | Reference | 1646 +-----------+---------------------+-----------+ 1647 | core.c.ds | YANG datastore | RFC XXXX | 1648 | | | | 1649 | core.c.dn | YANG data node | RFC XXXX | 1650 | | | | 1651 | core.c.yl | YANG module library | RFC XXXX | 1652 | | | | 1653 | core.c.es | YANG event stream | RFC XXXX | 1654 +-----------+---------------------+-----------+ 1656 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1657 note. 1659 9.2. CoAP Content-Formats Registry 1661 This document adds the following Content-Format to the "CoAP Content- 1662 Formats", within the "Constrained RESTful Environments (CoRE) 1663 Parameters" registry. 1665 +-----------------------------------+------------+------+-----------+ 1666 | Media Type | Content | ID | Reference | 1667 | | Coding | | | 1668 +-----------------------------------+------------+------+-----------+ 1669 | application/yang-identifiers+cbor | | TBD2 | RFC XXXX | 1670 | | | | | 1671 | application/yang-instances+cbor | | TBD3 | RFC XXXX | 1672 +-----------------------------------+------------+------+-----------+ 1674 // RFC Ed.: replace TBD1, TBD2 and TBD3 with assigned IDs and remove 1675 this note. // RFC Ed.: replace RFC XXXX with this RFC number and 1676 remove this note. 1678 9.3. Media Types Registry 1680 This document adds the following media types to the "Media Types" 1681 registry. 1683 +-----------------------+-----------------------+-----------+ 1684 | Name | Template | Reference | 1685 +-----------------------+-----------------------+-----------+ 1686 | yang-identifiers+cbor | application/ | RFC XXXX | 1687 | | | | 1688 | | yang-identifiers+cbor | | 1689 | | | | 1690 | yang-instances+cbor | application/ | RFC XXXX | 1691 | | | | 1692 | | yang-instances+cbor | | 1693 +-----------------------+-----------------------+-----------+ 1695 Each of these media types share the following information: 1697 o Subtype name: 1699 o Required parameters: N/A 1701 o Optional parameters: N/A 1703 o Encoding considerations: binary 1705 o Security considerations: See the Security Considerations section 1706 of RFC XXXX 1708 o Interoperability considerations: N/A 1710 o Published specification: RFC XXXX 1712 o Applications that use this media type: CORECONF 1714 o Fragment identifier considerations: N/A 1716 o Additional information: 1718 * Deprecated alias names for this type: N/A 1720 * Magic number(s): N/A 1722 * File extension(s): N/A 1724 * Macintosh file type code(s): N/A 1725 o Person & email address to contact for further information: 1726 iesg&ietf.org 1728 o Intended usage: COMMON 1730 o Restrictions on usage: N/A 1732 o Author: Michel Veillette, ietf&augustcellars.com 1734 o Change Controller: IESG 1736 o Provisional registration? No 1738 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1739 note. 1741 9.4. YANG Namespace Registration 1743 This document registers the following XML namespace URN in the "IETF 1744 XML Registry", following the format defined in [RFC3688]: 1746 URI: please assign urn:ietf:params:xml:ns:yang:ietf-coreconf 1748 Registrant Contact: The IESG. 1750 XML: N/A, the requested URI is an XML namespace. 1752 Reference: RFC XXXX 1754 // RFC Ed.: please replace XXXX with RFC number and remove this note 1756 10. Acknowledgments 1758 We are very grateful to Bert Greevenbosch who was one of the original 1759 authors of the CORECONF specification. 1761 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1762 transported under SNMP. Carsten Bormann has given feedback on the 1763 use of CBOR. 1765 The draft has benefited from comments (alphabetical order) by Rodney 1766 Cummings, Dee Denteneer, Esko Dijk, Klaus Hartke, Michael van 1767 Hartskamp, Tanguy Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach 1768 Shelby, Hannes Tschofenig, Michael Verschoor, and Thomas Watteyne. 1770 11. References 1772 11.1. Normative References 1774 [I-D.ietf-core-sid] 1775 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 1776 iDentifier (YANG SID)", draft-ietf-core-sid-14 (work in 1777 progress), July 2020. 1779 [I-D.ietf-core-yang-cbor] 1780 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 1781 Data Modeled with YANG", draft-ietf-core-yang-cbor-13 1782 (work in progress), July 2020. 1784 [I-D.ietf-core-yang-library] 1785 Veillette, M. and I. Petrov, "Constrained YANG Module 1786 Library", draft-ietf-core-yang-library-03 (work in 1787 progress), January 2021. 1789 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1790 Requirement Levels", BCP 14, RFC 2119, 1791 DOI 10.17487/RFC2119, March 1997, 1792 . 1794 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1795 DOI 10.17487/RFC3688, January 2004, 1796 . 1798 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1799 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1800 . 1802 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1803 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1804 . 1806 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1807 and A. Bierman, Ed., "Network Configuration Protocol 1808 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1809 . 1811 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1812 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1813 . 1815 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1816 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1817 October 2013, . 1819 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1820 Application Protocol (CoAP)", RFC 7252, 1821 DOI 10.17487/RFC7252, June 2014, 1822 . 1824 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1825 Application Protocol (CoAP)", RFC 7641, 1826 DOI 10.17487/RFC7641, September 2015, 1827 . 1829 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1830 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1831 . 1833 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1834 the Constrained Application Protocol (CoAP)", RFC 7959, 1835 DOI 10.17487/RFC7959, August 2016, 1836 . 1838 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1839 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1840 . 1842 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1843 FETCH Methods for the Constrained Application Protocol 1844 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1845 . 1847 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1848 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1849 May 2017, . 1851 11.2. Informative References 1853 [I-D.ietf-ace-oauth-authz] 1854 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1855 H. Tschofenig, "Authentication and Authorization for 1856 Constrained Environments (ACE) using the OAuth 2.0 1857 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-36 1858 (work in progress), November 2020. 1860 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1861 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1862 January 2012, . 1864 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1865 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1866 . 1868 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1869 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1870 2014, . 1872 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1873 and R. Wilton, "Network Management Datastore Architecture 1874 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1875 . 1877 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1878 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1879 . 1881 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1882 "Object Security for Constrained RESTful Environments 1883 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1884 . 1886 Appendix A. ietf-coreconf YANG module 1888 file "ietf-coreconf@2019-03-28.yang" 1889 module ietf-coreconf { 1890 yang-version 1.1; 1892 namespace "urn:ietf:params:xml:ns:yang:ietf-coreconf"; 1893 prefix coreconf; 1895 import ietf-datastores { 1896 prefix ds; 1897 } 1899 import ietf-restconf { 1900 prefix rc; 1901 description 1902 "This import statement is required to access 1903 the yang-data extension defined in RFC 8040."; 1904 reference "RFC 8040: RESTCONF Protocol"; 1905 } 1907 organization 1908 "IETF Core Working Group"; 1910 contact 1911 "Michel Veillette 1912 1914 Alexander Pelov 1915 1916 Peter van der Stok 1917 1919 Andy Bierman 1920 "; 1922 description 1923 "This module contains the different definitions required 1924 by the CORECONF protocol. 1926 Copyright (c) 2019 IETF Trust and the persons identified as 1927 authors of the code. All rights reserved. 1929 Redistribution and use in source and binary forms, with or 1930 without modification, is permitted pursuant to, and subject to 1931 the license terms contained in, the Simplified BSD License set 1932 forth in Section 4.c of the IETF Trust's Legal Provisions 1933 Relating to IETF Documents 1934 (https://trustee.ietf.org/license-info). 1936 This version of this YANG module is part of RFC XXXX; 1937 see the RFC itself for full legal notices."; 1939 revision 2019-03-28 { 1940 description 1941 "Initial revision."; 1942 reference 1943 "[I-D.ietf-core-comi] CoAP Management Interface"; 1944 } 1946 identity unified { 1947 base ds:datastore; 1948 description 1949 "Identifier of the unified configuration and operational 1950 state datastore."; 1951 } 1953 identity error-tag { 1954 description 1955 "Base identity for error-tag."; 1956 } 1958 identity operation-failed { 1959 base error-tag; 1960 description 1961 "Returned by the CORECONF server when the operation request 1962 can't be processed successfully."; 1963 } 1964 identity invalid-value { 1965 base error-tag; 1966 description 1967 "Returned by the CORECONF server when the CORECONF client tries to 1968 update or create a leaf with a value encoded using an 1969 invalid CBOR datatype or if the 'range', 'length', 1970 'pattern' or 'require-instance' constrain is not 1971 fulfilled."; 1972 } 1974 identity missing-element { 1975 base error-tag; 1976 description 1977 "Returned by the CORECONF server when the operation requested 1978 by a CORECONF client fails to comply with the 'mandatory' 1979 constraint defined. The 'mandatory' constraint is 1980 enforced for leafs and choices, unless the node or any of 1981 its ancestors have a 'when' condition or 'if-feature' 1982 expression that evaluates to 'false'."; 1983 } 1985 identity unknown-element { 1986 base error-tag; 1987 description 1988 "Returned by the CORECONF server when the CORECONF client tries to 1989 access a data node of a YANG module not supported, of a 1990 data node associated with an 'if-feature' expression 1991 evaluated to 'false' or to a 'when' condition evaluated 1992 to 'false'."; 1993 } 1995 identity bad-element { 1996 base error-tag; 1997 description 1998 "Returned by the CORECONF server when the CORECONF client tries to 1999 create data nodes for more than one case in a choice."; 2000 } 2002 identity data-missing { 2003 base error-tag; 2004 description 2005 "Returned by the CORECONF server when a data node required to 2006 accept the request is not present."; 2007 } 2009 identity error { 2010 base error-tag; 2011 description 2012 "Returned by the CORECONF server when an unspecified error has 2013 occurred."; 2014 } 2016 identity error-app-tag { 2017 description 2018 "Base identity for error-app-tag."; 2019 } 2021 identity malformed-message { 2022 base error-app-tag; 2023 description 2024 "Returned by the CORECONF server when the payload received 2025 from the CORECONF client don't contain a well-formed CBOR 2026 content as defined in [RFC7049] section 3.3 or don't 2027 comply with the CBOR structure defined within this 2028 document."; 2029 } 2031 identity data-not-unique { 2032 base error-app-tag; 2033 description 2034 "Returned by the CORECONF server when the validation of the 2035 'unique' constraint of a list or leaf-list fails."; 2036 } 2038 identity too-many-elements { 2039 base error-app-tag; 2040 description 2041 "Returned by the CORECONF server when the validation of the 2042 'max-elements' constraint of a list or leaf-list fails."; 2043 } 2045 identity too-few-elements { 2046 base error-app-tag; 2047 description 2048 "Returned by the CORECONF server when the validation of the 2049 'min-elements' constraint of a list or leaf-list fails."; 2050 } 2052 identity must-violation { 2053 base error-app-tag; 2054 description 2055 "Returned by the CORECONF server when the restrictions 2056 imposed by a 'must' statement are violated."; 2057 } 2059 identity duplicate { 2060 base error-app-tag; 2061 description 2062 "Returned by the CORECONF server when a client tries to create 2063 a duplicate list or leaf-list entry."; 2064 } 2066 identity invalid-datatype { 2067 base error-app-tag; 2068 description 2069 "Returned by the CORECONF server when CBOR encoding is 2070 incorect or when the value encoded is incompatible with 2071 the YANG Built-In type. (e.g. value greater than 127 2072 for an int8, undefined enumeration)."; 2073 } 2075 identity not-in-range { 2076 base error-app-tag; 2077 description 2078 "Returned by the CORECONF server when the validation of the 2079 'range' property fails."; 2080 } 2082 identity invalid-length { 2083 base error-app-tag; 2084 description 2085 "Returned by the CORECONF server when the validation of the 2086 'length' property fails."; 2087 } 2089 identity pattern-test-failed { 2090 base error-app-tag; 2091 description 2092 "Returned by the CORECONF server when the validation of the 2093 'pattern' property fails."; 2094 } 2096 identity missing-key { 2097 base error-app-tag; 2098 description 2099 "Returned by the CORECONF server to further qualify a 2100 missing-element error. This error is returned when the 2101 CORECONF client tries to create or list instance, without all 2102 the 'key' specified or when the CORECONF client tries to 2103 delete a leaf listed as a 'key'."; 2104 } 2106 identity missing-input-parameter { 2107 base error-app-tag; 2108 description 2109 "Returned by the CORECONF server when the input parameters 2110 of a RPC or action are incomplete."; 2111 } 2113 identity instance-required { 2114 base error-app-tag; 2115 description 2116 "Returned by the CORECONF server when a leaf of type 2117 'instance-identifier' or 'leafref' marked with 2118 require-instance set to 'true' refers to an instance 2119 that does not exist."; 2120 } 2122 identity missing-choice { 2123 base error-app-tag; 2124 description 2125 "Returned by the CORECONF server when no nodes exist in a 2126 mandatory choice."; 2127 } 2129 rc:yang-data coreconf-error { 2130 container error { 2131 description 2132 "Optional payload of a 4.00 Bad Request CoAP error."; 2134 leaf error-tag { 2135 type identityref { 2136 base error-tag; 2137 } 2138 mandatory true; 2139 description 2140 "The enumerated error-tag."; 2141 } 2143 leaf error-app-tag { 2144 type identityref { 2145 base error-app-tag; 2146 } 2147 description 2148 "The application-specific error-tag."; 2149 } 2151 leaf error-data-node { 2152 type instance-identifier; 2153 description 2154 "When the error reported is caused by a specific data node, 2155 this leaf identifies the data node in error."; 2157 } 2159 leaf error-message { 2160 type string; 2161 description 2162 "A message describing the error."; 2163 } 2164 } 2165 } 2166 } 2167 2169 Appendix B. ietf-coreconf .sid file 2171 { 2172 "assignment-ranges": [ 2173 { 2174 "entry-point": 1000, 2175 "size": 100 2176 } 2177 ], 2178 "module-name": "ietf-coreconf", 2179 "module-revision": "2019-03-28", 2180 "items": [ 2181 { 2182 "namespace": "module", 2183 "identifier": "ietf-coreconf", 2184 "sid": 1000 2185 }, 2186 { 2187 "namespace": "identity", 2188 "identifier": "bad-element", 2189 "sid": 1001 2190 }, 2191 { 2192 "namespace": "identity", 2193 "identifier": "data-missing", 2194 "sid": 1002 2195 }, 2196 { 2197 "namespace": "identity", 2198 "identifier": "data-not-unique", 2199 "sid": 1003 2200 }, 2201 { 2202 "namespace": "identity", 2203 "identifier": "duplicate", 2204 "sid": 1004 2206 }, 2207 { 2208 "namespace": "identity", 2209 "identifier": "error", 2210 "sid": 1005 2211 }, 2212 { 2213 "namespace": "identity", 2214 "identifier": "error-app-tag", 2215 "sid": 1006 2216 }, 2217 { 2218 "namespace": "identity", 2219 "identifier": "error-tag", 2220 "sid": 1007 2221 }, 2222 { 2223 "namespace": "identity", 2224 "identifier": "instance-required", 2225 "sid": 1008 2226 }, 2227 { 2228 "namespace": "identity", 2229 "identifier": "invalid-datatype", 2230 "sid": 1009 2231 }, 2232 { 2233 "namespace": "identity", 2234 "identifier": "invalid-length", 2235 "sid": 1010 2236 }, 2237 { 2238 "namespace": "identity", 2239 "identifier": "invalid-value", 2240 "sid": 1011 2241 }, 2242 { 2243 "namespace": "identity", 2244 "identifier": "malformed-message", 2245 "sid": 1012 2246 }, 2247 { 2248 "namespace": "identity", 2249 "identifier": "missing-choice", 2250 "sid": 1013 2251 }, 2252 { 2253 "namespace": "identity", 2254 "identifier": "missing-element", 2255 "sid": 1014 2256 }, 2257 { 2258 "namespace": "identity", 2259 "identifier": "missing-input-parameter", 2260 "sid": 1015 2261 }, 2262 { 2263 "namespace": "identity", 2264 "identifier": "missing-key", 2265 "sid": 1016 2266 }, 2267 { 2268 "namespace": "identity", 2269 "identifier": "must-violation", 2270 "sid": 1017 2271 }, 2272 { 2273 "namespace": "identity", 2274 "identifier": "not-in-range", 2275 "sid": 1018 2276 }, 2277 { 2278 "namespace": "identity", 2279 "identifier": "operation-failed", 2280 "sid": 1019 2281 }, 2282 { 2283 "namespace": "identity", 2284 "identifier": "pattern-test-failed", 2285 "sid": 1020 2286 }, 2287 { 2288 "namespace": "identity", 2289 "identifier": "too-few-elements", 2290 "sid": 1021 2291 }, 2292 { 2293 "namespace": "identity", 2294 "identifier": "too-many-elements", 2295 "sid": 1022 2296 }, 2297 { 2298 "namespace": "identity", 2299 "identifier": "unified", 2300 "sid": 1029 2301 }, 2302 { 2303 "namespace": "identity", 2304 "identifier": "unknown-element", 2305 "sid": 1023 2306 }, 2307 { 2308 "namespace": "data", 2309 "identifier": "/ietf-coreconf:error", 2310 "sid": 1024 2311 }, 2312 { 2313 "namespace": "data", 2314 "identifier": "/ietf-coreconf:error/error-app-tag", 2315 "sid": 1025 2316 }, 2317 { 2318 "namespace": "data", 2319 "identifier": "/ietf-coreconf:error/error-data-node", 2320 "sid": 1026 2321 }, 2322 { 2323 "namespace": "data", 2324 "identifier": "/ietf-coreconf:error/error-message", 2325 "sid": 1027 2326 }, 2327 { 2328 "namespace": "data", 2329 "identifier": "/ietf-coreconf:error/error-tag", 2330 "sid": 1028 2331 } 2332 ] 2333 } 2335 Authors' Addresses 2337 Michel Veillette (editor) 2338 Trilliant Networks Inc. 2339 610 Rue du Luxembourg 2340 Granby, Quebec J2J 2V2 2341 Canada 2343 Email: michel.veillette@trilliant.com 2344 Peter van der Stok (editor) 2345 consultant 2347 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2348 Email: consultancy@vanderstok.org 2349 URI: www.vanderstok.org 2351 Alexander Pelov 2352 Acklio 2353 2bis rue de la Chataigneraie 2354 Cesson-Sevigne, Bretagne 35510 2355 France 2357 Email: a@ackl.io 2359 Andy Bierman 2360 YumaWorks 2361 685 Cochran St. 2362 Suite #160 2363 Simi Valley, CA 93065 2364 USA 2366 Email: andy@yumaworks.com 2368 Ivaylo Petrov (editor) 2369 Acklio 2370 1137A avenue des Champs Blancs 2371 Cesson-Sevigne, Bretagne 35510 2372 France 2374 Email: ivaylo@ackl.io