idnits 2.17.1 draft-ietf-core-comi-01.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 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The server MUST not return the child resource if d= 't' -- The document date (July 17, 2017) is 2473 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 335 -- Looks like a reference, but probably isn't: '26' on line 336 -- Looks like a reference, but probably isn't: '53' on line 337 == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-01 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-04 == Outdated reference: A later version (-05) exists of draft-veillette-core-yang-library-00 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-09 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 7 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 18, 2018 consultant 6 A. Pelov 7 Acklio 8 A. Bierman 9 YumaWorks 10 July 17, 2017 12 CoAP Management Interface 13 draft-ietf-core-comi-01 15 Abstract 17 This document describes a network management interface for 18 constrained devices and networks, called CoAP Management Interface 19 (CoMI). The Constrained Application Protocol (CoAP) is used to 20 access datastore and data node resources specified in YANG, or SMIv2 21 converted to YANG. CoMI uses the YANG to CBOR mapping and converts 22 YANG identifier strings to numeric identifiers for payload size 23 reduction. CoMI extends the set of YANG based protocols, NETCONF and 24 RESTCONF, with the capability to manage constrained devices and 25 networks. 27 Note 29 Discussion and suggestions for improvement are requested, and should 30 be sent to core@ietf.org. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on January 18, 2018. 49 Copyright Notice 51 Copyright (c) 2017 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5 69 2.1. Major differences between RESTCONF and CoMI . . . . . . . 6 70 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 71 2.3. Instance identifier . . . . . . . . . . . . . . . . . . . 8 72 2.4. CBOR ordered map schematic . . . . . . . . . . . . . . . 8 73 2.5. Content-Formats . . . . . . . . . . . . . . . . . . . . . 8 74 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11 75 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 12 76 5. CoMI Collection Interface . . . . . . . . . . . . . . . . . . 13 77 5.1. Using the 'k' Uri-Query option . . . . . . . . . . . . . 14 78 5.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 15 79 5.2.1. Using the 'c' Uri-Query option . . . . . . . . . . . 16 80 5.2.2. Using the 'd' Uri-Query option . . . . . . . . . . . 16 81 5.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 17 82 5.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 19 83 5.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 20 84 5.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 20 85 5.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 20 86 5.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 21 87 5.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 22 88 5.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 23 89 5.4. Full datastore access . . . . . . . . . . . . . . . . . . 23 90 5.4.1. Full datastore examples . . . . . . . . . . . . . . . 24 91 5.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 25 92 5.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 26 93 5.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 26 94 5.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 27 95 6. Access to MIB Data . . . . . . . . . . . . . . . . . . . . . 27 96 7. Use of Block . . . . . . . . . . . . . . . . . . . . . . . . 29 97 8. Resource Discovery . . . . . . . . . . . . . . . . . . . . . 29 98 9. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 31 99 10. Security Considerations . . . . . . . . . . . . . . . . . . . 34 100 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 101 11.1. Resource Type (rt=) Link Target Attribute Values 102 Registry . . . . . . . . . . . . . . . . . . . . . . . . 34 103 11.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 35 104 11.3. Media Types Registry . . . . . . . . . . . . . . . . . . 35 105 11.4. Concise Binary Object Representation (CBOR) Tags 106 Registry . . . . . . . . . . . . . . . . . . . . . . . . 37 107 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 108 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 109 13.1. Normative References . . . . . . . . . . . . . . . . . . 38 110 13.2. Informative References . . . . . . . . . . . . . . . . . 39 111 Appendix A. ietf-comi YANG module . . . . . . . . . . . . . . . 40 112 Appendix B. ietf-comi .sid file . . . . . . . . . . . . . . . . 45 113 Appendix C. YANG example specifications . . . . . . . . . . . . 49 114 C.1. ietf-system . . . . . . . . . . . . . . . . . . . . . . . 49 115 C.2. server list . . . . . . . . . . . . . . . . . . . . . . . 50 116 C.3. interfaces . . . . . . . . . . . . . . . . . . . . . . . 51 117 C.4. Example-port . . . . . . . . . . . . . . . . . . . . . . 52 118 C.5. IP-MIB . . . . . . . . . . . . . . . . . . . . . . . . . 53 119 Appendix D. Comparison with LWM2M . . . . . . . . . . . . . . . 55 120 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 122 1. Introduction 124 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 125 Machine to Machine (M2M) applications such as smart energy, smart 126 city and building control. Constrained devices need to be managed in 127 an automatic fashion to handle the large quantities of devices that 128 are expected in future installations. Messages between devices need 129 to be as small and infrequent as possible. The implementation 130 complexity and runtime resources need to be as small as possible. 132 This draft describes the CoAP Management Interface which uses CoAP 133 methods to access structured data defined in YANG [RFC7950]. This 134 draft is complementary to [RFC8040] which describes a REST-like 135 interface called RESTCONF, which uses HTTP methods to access 136 structured data defined in YANG. 138 The use of standardized data models specified in a standardized 139 language, such as YANG, promotes interoperability between devices and 140 applications from different manufacturers. 142 CoMI and RESTCONF are intended to work in a stateless client-server 143 fashion. They use a single round-trip to complete a single editing 144 transaction, where NETCONF needs up to 10 round trips. 146 To promote small messges, CoMI uses a YANG to CBOR mapping 147 [I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid] 148 to minimize CBOR payloads and URI length. 150 1.1. Terminology 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 154 document are to be interpreted as described in [RFC2119]. 156 The following terms are defined in the YANG data modelling language 157 [RFC7950]: action, anydata, anyxml, client, configuration data, 158 container, data model, data node, datastore, identity, instance 159 identifier, key, key leaf, leaf, leaf-list, list, module, RPC, schema 160 node, server, state data, submodule. 162 The following term is defined in [I-D.ietf-core-yang-cbor]: YANG 163 schema item identifier (SID). 165 The following terms are defined in the CoAP protocol [RFC7252]: 166 Confirmable Message, Content-Format. 168 The following terms are defined in this document: 170 data node resource: a CoAP resource that models a YANG data node. 172 datastore resource: a CoAP resource that models a YANG datastore. 174 event stream resource: a CoAP resource used by clients to observe 175 YANG notifications. 177 target resource: the resource that is associated with a particular 178 CoAP request, identified by the request URI. 180 data node instance: An instance of a data node specified in a YANG 181 module and stored in the server. 183 notification instance: An instance of a schema node of type 184 notification, specified in a YANG module implemented by the 185 server. The instance is generated in the server at the occurrence 186 of the corresponding event and reported by an event stream. 188 list instance identifier: Handle used to identify a YANG data node 189 that is an instance of a YANG "list" specified with the values of 190 the key leaves of the list. 192 single instance identifier: Handle used to identify a specific data 193 node which can be instantiated only once. This includes data 194 nodes defined at the root of a YANG module or data nodes defined 195 within a container. This excludes data nodes defined within a 196 list or any children of these data nodes. 198 instance identifier: List instance identifier or single instance 199 identifier. 201 data node value: The value assigned to a data node instance. Data 202 node values are serialized into the payload according to the rules 203 defined in section 4 of [I-D.ietf-core-yang-cbor]. 205 2. CoMI Architecture 207 This section describes the CoMI architecture to use CoAP for reading 208 and modifying the content of datastore(s) used for the management of 209 the instrumented node. 211 +------------------------------------------------------------+ 212 | SMIv2 specification (2) | 213 +------------------------------------------------------------+ 214 | 215 V 216 +------------------------------------------------------------+ 217 | YANG specification (1) | 218 +------------------------------------------------------------+ 219 | | 220 Client V Server V 221 +----------------+ +-------------------+ 222 | Request |--> CoAP request(3) -->| Indication | 223 | Confirm |<-- CoAP response(3)<--| Response (4) | 224 | | | | 225 | |<==== Security (7) ===>|+-----------------+| 226 +----------------+ || Datastore (5) || 227 |+-----------------+| 228 |+-----------------+| 229 || Event stream (6)|| 230 |+-----------------+| 231 +-------------------+ 233 Figure 1: Abstract CoMI architecture 235 Figure 1 is a high-level representation of the main elements of the 236 CoMI management architecture. The different numbered components of 237 Figure 1 are discussed according to component number. 239 (1) YANG specification: contains a set of named and versioned 240 modules. 242 (2) SMIv2 specification: A named module specifies a set of variables 243 and "conceptual tables". There is an algorithm to translate SMIv2 244 specifications 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: The processes performed 250 by 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 multiple 254 datastores to support more complex operations such as 255 configuration rollback, scheduled update. 257 (6) Event stream: An observable resource used to get real time 258 notifications. A CoMI server may support multiple Event streams 259 serving different purposes such as normal monitoring, diagnostic, 260 syslog, security 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 communication. 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. Some major differences are cited below: 274 o CoMI uses CoAP/UDP as transport protocol and CBOR as payload 275 format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as 276 transport protocol and JSON [RFC7159] or XML [XML] as payload 277 formats. 279 o CoMI encodes YANG identifier strings as numbers, where RESTCONF 280 does not. 282 o CoMI uses the methods FETCH and iPATCH, not used by RESTCONF. 283 RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not 284 used by CoMI. 286 o CoMI does not support "insert" query parameter (first, last, 287 before, after) and the "point" query parameter which are supported 288 by RESTCONF. 290 o CoMI does not support the "start-time" and "stop-time" query 291 parameters to retrieve past notifications. 293 o CoMI and RESTCONF also differ in the handling of: 295 * notifications. 297 * default values. 299 2.2. Compression of YANG identifiers 301 In the YANG specification, items are identified with a name string. 302 In order to significantly reduce the size of identifiers used in 303 CoMI, numeric identifiers are used instead of these strings. YANG 304 Schema Item iDentifier (SID) is defined in [I-D.ietf-core-yang-cbor] 305 section 2.1. 307 When used in a URI, SIDs are encoded in based64 using the URL and 308 Filename safe alphabet as defined by [RFC4648] section 5. The last 6 309 bits encoded is always aligned with the least significant 6 bits of 310 the SID represented using an unsigned integer. 'A' characters (value 311 0) at the start of the resulting string are removed. 313 SID in basae64 = URLsafeChar[SID >> 60 & 0x3F] | 314 URLsafeChar[SID >> 54 & 0x3F] | 315 URLsafeChar[SID >> 48 & 0x3F] | 316 URLsafeChar[SID >> 42 & 0x3F] | 317 URLsafeChar[SID >> 36 & 0x3F] | 318 URLsafeChar[SID >> 30 & 0x3F] | 319 URLsafeChar[SID >> 24 & 0x3F] | 320 URLsafeChar[SID >> 18 & 0x3F] | 321 URLsafeChar[SID >> 12 & 0x3F] | 322 URLsafeChar[SID >> 6 & 0x3F] | 323 URLsafeChar[SID & 0x3F] 325 For example, SID 1717 is encoded as follow. 327 URLsafeChar[1717 >> 60 & 0x3F] = URLsafeChar[0] = 'A' 328 URLsafeChar[1717 >> 54 & 0x3F] = URLsafeChar[0] = 'A' 329 URLsafeChar[1717 >> 48 & 0x3F] = URLsafeChar[0] = 'A' 330 URLsafeChar[1717 >> 42 & 0x3F] = URLsafeChar[0] = 'A' 331 URLsafeChar[1717 >> 36 & 0x3F] = URLsafeChar[0] = 'A' 332 URLsafeChar[1717 >> 30 & 0x3F] = URLsafeChar[0] = 'A' 333 URLsafeChar[1717 >> 24 & 0x3F] = URLsafeChar[0] = 'A' 334 URLsafeChar[1717 >> 18 & 0x3F] = URLsafeChar[0] = 'A' 335 URLsafeChar[1717 >> 12 & 0x3F] = URLsafeChar[0] = 'A' 336 URLsafeChar[1717 >> 6 & 0x3F] = URLsafeChar[26] = 'a' 337 URLsafeChar[1717 & 0x3F] = URLsafeChar[53] = '1' 338 The resulting base64 representation of SID 1717 is "a1" 340 2.3. Instance identifier 342 Instance identifiers are used to uniquely identify data node 343 instances within a datastore. This YANG built-in type is defined in 344 [RFC7950] section 9.13. An instance identifier is composed of the 345 data node identifier (i.e. a SID) and for data nodes within list(s) 346 the keys used to index within these list(s). 348 When part of a payload, instance identifiers are encoded in CBOR 349 based on the rules defined in [I-D.ietf-core-yang-cbor] section 350 5.13.1. When part of a URI, the SID is appended to the URI of the 351 targeted datastore, the keys are specified using the 'k' URI-Query as 352 defined in Section 5.1. 354 2.4. CBOR ordered map schematic 356 An ordered map is used as a root container of the application/yang- 357 tree+cbor Content-Format. This datatype share the same 358 functionalities as a CBOR map without the following limitations: 360 o The ordering of the pairs of data items is preserved from 361 serialization to deserialization. 363 o Duplicate keys are allowed 365 This schematic is constructed using a CBOR array comprising pairs of 366 data items, each pair consisting of a key that is immediately 367 followed by a value. Unlike a CBOR map for which the length denotes 368 the number of pairs, the length of the ordered map denotes the number 369 of items (i.e. number of keys plus number of values). 371 The use of this schematic can be inferred from its context or by the 372 presence of a preceding tag. The tag assigned to the Ordered map is 373 defined in Section 11.4. 375 In the case of CoMI, the use of the ordered map as the root container 376 of the application/yang-tree+cbor Content-Format is inferred, the 377 Ordered map tag is not used. 379 2.5. Content-Formats 381 ComI uses Content-Formats based on the YANG to CBOR mapping specified 382 in [I-D.ietf-core-yang-cbor]. All Content-Formats defined hereafter 383 are constructed using one or both of these constructs: 385 o YANG data node value, encoded based on the rules defined in 386 [I-D.ietf-core-yang-cbor] section 4. 388 o YANG instance identifier, encoded based on the rules defined in 389 [I-D.ietf-core-yang-cbor] section 5.13.1. 391 The following Content-formats are defined: 393 application/yang-value+cbor: represents a CBOR YANG document 394 containing one YANG data node value. The YANG data node instance 395 can be a leaf, a container, a list, a list instance, a RPC input, 396 a RPC output, an action input, an action output, a leaf-list, an 397 anydata or an anyxml. The CBOR encoding for each of these YANG 398 data node instances are defined in [I-D.ietf-core-yang-cbor] 399 section 4. 401 FORMAT: data-node-value 403 DELTA ENCODING: SIDs included in a YANG container, a list 404 instance, a RPC input, a RPC output, an action input, an actions 405 output and an anydata are encoded using a delta value equal to the 406 SID of the current schema node minus the SID of the parent. The 407 parent SID of root data nodes is defined by the URI carried in the 408 associated request (i.e. GET, PUT, POST). 410 application/yang-values+cbor: represents a YANG document containing 411 a list of data node values. 413 FORMAT: CBOR array of data-node-value 415 DELTA ENCODING: SIDs included in a YANG container, a list instance 416 and an anydata are encoded using a delta value equal to the SID of 417 the current schema node minus the SID of the parent. The parent 418 SID of root data nodes is defined by the corresponding instance- 419 identifier carried in the FETCH request. 421 application/yang-tree+cbor: represents a CBOR YANG document 422 containing a YANG data tree. 424 FORMAT: ordered map of single-instance-identifier, data-node-value 426 DELTA ENCODING: The SID part of the first instance-identifier 427 within the ordered map is encoded using its absolute value. 428 Subsequent instance-identifiers are encoded using a delta value 429 equal to the SID of the current instance-identifiers minus the SID 430 of the previous instance-identifier. 432 application/yang-selectors+cbor: represents a CBOR YANG document 433 containing a list of data node selectors (i.e. instance 434 identifier). 436 FORMAT: CBOR array of instance-identifier 438 DELTA ENCODING: The SID part of the first instance-identifier 439 within the CBOR array is encoded using its absolute value. 440 Subsequent instance-identifiers are encoded using a delta value 441 equal to the SID of the current instance-identifiers minus the SID 442 of the previous instance-identifier. 444 application/yang-patch+cbor: represents a CBOR YANG document 445 containing a list of data nodes to be replaced, created, or 446 deleted. 448 For each data node instance, D, for which the instance identifier 449 is the same as for a data node instance, I, in the targeted 450 resource: the data node value of D replaces the data node value of 451 I. When the data node value of D is null, the data node instance 452 I is removed. When the targeted resource does not contain a data 453 node instance with the same instance identifier as D, a new data 454 node instance is created in the targeted resource with the same 455 instance identifier and data node value as D. 457 FORMAT: CBOR array of instance-identifier, data-node-value 459 DELTA ENCODING: Same as Content-Format application/yang-tree+cbor 461 The different Content-formats usage is summarized in the table below: 463 +----------------+--------------+----------------------------------+ 464 | Method | Resource | Content-Format | 465 +----------------+--------------+----------------------------------+ 466 | GET response | data node | /application/yang-value+cbor | 467 | | | | 468 | PUT request | data node | /application/yang-value+cbor | 469 | | | | 470 | POST request | data node | /application/yang-value+cbor | 471 | | | | 472 | DELETE | data node | n/a | 473 | | | | 474 | GET response | datastore | /application/yang-tree+cbor | 475 | | | | 476 | PUT request | datastore | /application/yang-tree+cbor | 477 | | | | 478 | POST request | datastore | /application/yang-tree+cbor | 479 | | | | 480 | FETCH request | datastore | /application/yang-selectors+cbor | 481 | | | | 482 | FETCH response | datastore | /application/yang-values+cbor | 483 | | | | 484 | iPATCH request | datastore | /application/yang-patch+cbor | 485 | | | | 486 | GET response | event stream | /application/yang-tree+cbor | 487 | | | | 488 | POST request | rpc, action | /application/yang-value+cbor | 489 | | | | 490 | POST response | rpc, action | /application/yang-value+cbor | 491 +----------------+--------------+----------------------------------+ 493 3. Example syntax 495 This section presents the notation used for the examples. The YANG 496 modules that are used throughout this document are shown in 497 Appendix C. The example modules are copied from existing modules and 498 annotated with SIDs. The values of the SIDs are taken over from 499 [yang-cbor]. 501 CBOR is used to encode CoMI request and response payloads. The CBOR 502 syntax of the YANG payloads is specified in [RFC7049]. The payload 503 examples are notated in Diagnostic notation (defined in section 6 of 504 [RFC7049]) that can be automatically converted to CBOR. 506 SIDs in URIs are represented as a base64 number, SIDs in the payload 507 are represented as decimal numbers. 509 4. CoAP Interface 511 The format of the links is specified in [I-D.ietf-core-interfaces]. 512 This note specifies a Management Collection Interface. CoMI end- 513 points that implement the CoMI management protocol, support at least 514 one discoverable management resource of resource type (rt): 515 core.c.datastore, with example path: /c, where c is short-hand for 516 CoMI. The path /c is recommended but not compulsory (see Section 8). 518 Three CoMI resources are accessible with the following three example 519 paths: 521 /c: Datastore resource with path "/c" and using CBOR content 522 encoding format. Sub-resouces of format /c/instance-identifier 523 may be available to access directly each data node resource for 524 this datastore. 526 /mod.uri: URI identifying the location of the YANG module library 527 used by this server, with path "/mod.uri" and Content-Format 528 "text/plain; charset=utf-8". An ETag MUST be maintained for this 529 resource by the server, which MUST be changed to a new value when 530 the set of YANG modules in use by the server changes. 532 /s: Event stream resource to which YANG notification instances are 533 reported. Notification support is optional, so this resource will 534 not exist if the server does not support any notifications. 536 The mapping of YANG data node instances to CoMI resources is as 537 follows. Every data node of the YANG modules loaded in the CoMI 538 server represents a sub-resource of the datastore resource (e.g. /c/ 539 instance-identifier). 541 When multiple instances of a list exist, instance selection is 542 possible as described in Section 5.1, Section 5.2.4, and 543 Section 5.2.3.1. 545 The description of the management collection interface, with 546 if=core.c, is shown in the table below, following the guidelines of 547 [I-D.ietf-core-interfaces]: 549 +---------------------+------------------------+--------------------+ 550 | Function | Recommended path | rt | 551 +---------------------+------------------------+--------------------+ 552 | Datastore | /c | core.c.datastore | 553 | | | | 554 | Data node | /c/instance-identifier | core.c.datanode | 555 | | | | 556 | YANG module library | /mod.uri | core.c.moduri | 557 | | | | 558 | Event steam | /s | core.c.eventstream | 559 +---------------------+------------------------+--------------------+ 561 The path values are example values. On discovery, the server makes 562 the actual path values known for these four resources. 564 5. CoMI Collection Interface 566 The CoMI Collection Interface provides a CoAP interface to manage 567 YANG servers. 569 The methods used by CoMI are: 571 +-----------+-------------------------------------------------------+ 572 | Operation | Description | 573 +-----------+-------------------------------------------------------+ 574 | GET | Retrieve the datastore resource or a data node | 575 | | resource | 576 | | | 577 | FETCH | Retrieve specific data nodes within a datastore | 578 | | resource | 579 | | | 580 | POST | Create a datastore resource or a data node resource, | 581 | | invoke an RPC or action | 582 | | | 583 | PUT | Create or replace a datastore resource or a data node | 584 | | resource | 585 | | | 586 | iPATCH | Idem-potently create, replace, and delete data node | 587 | | resource(s) within a datastore resource | 588 | | | 589 | DELETE | Delete a datastore resource or a data node resource | 590 +-----------+-------------------------------------------------------+ 592 There is one Uri-Query option for the GET, PUT, POST, and DELETE 593 methods. 595 +------------------+----------------------------------------+ 596 | Uri-Query option | Description | 597 +------------------+----------------------------------------+ 598 | k | Select an instance within YANG list(s) | 599 +------------------+----------------------------------------+ 601 This parameter is not used for FETCH and iPATCH, because their 602 request payloads support list instance selection. 604 5.1. Using the 'k' Uri-Query option 606 The "k" (key) parameter specifies a specific instance of a data node. 607 The SID in the URI is followed by the (?k=key1, key2,..). Where SID 608 identifies a data node, and key1, key2 are the values of the key 609 leaves that specify an instance. Lists can have multiple keys, and 610 lists can be part of lists. The order of key value generation is 611 given recursively by: 613 o For a given list, if a parent data node is a list, generate the 614 keys for the parent list first. 616 o For a given list, generate key values in the order specified in 617 the YANG module. 619 Key values are encoded using the rules defined in the following 620 table. 622 +-----------------------------+--------------------------------+ 623 | YANG datatype | Uri-Query text content | 624 +-----------------------------+--------------------------------+ 625 | uint8,uint16,unit32, uint64 | int2str(key) | 626 | | | 627 | int8, int16,int32, int64 | urlSafeBase64(CBORencode(key)) | 628 | | | 629 | decimal64 | urlSafeBase64(CBOR key) | 630 | | | 631 | string | key | 632 | | | 633 | boolean | "0" or "1" | 634 | | | 635 | enumeration | int2str(key) | 636 | | | 637 | bits | urlSafeBase64(CBORencode(key)) | 638 | | | 639 | binary | urlSafeBase64(key) | 640 | | | 641 | identityref | int2str(key) | 642 | | | 643 | union | urlSafeBase64(CBORencode(key)) | 644 | | | 645 | instance-identifier | urlSafeBase64(CBORencode(key)) | 646 +-----------------------------+--------------------------------+ 648 In this table: 650 o The method int2str() is used to convert an integer value to a 651 string. For example, int2str(0x0123) return the string "291". 653 o The method urlSafeBase64() is used to convert a binary string to 654 base64 using the URL and Filename safe alphabet as defined by 655 [RFC4648] section 5. For example, urlSafeBase64(\xF9\x56\xA1\x3C) 656 return the string "-VahPA". 658 o The method CBORencode() is used to convert a YANG value to CBOR as 659 specified in [I-D.ietf-core-yang-cbor] section 5, item 8. 661 The resulting key string is encoded in a Uri-Query as specified in 662 [RFC7252] section 6.5. 664 5.2. Data Retrieval 666 One or more data nodes can be retrieved by the client. The operation 667 is mapped to the GET method defined in section 5.8.1 of [RFC7252] and 668 to the FETCH method defined in section 2 of [RFC8132]. 670 It is possible that the size of the payload is too large to fit in a 671 single message. In the case that management data is bigger than the 672 maximum supported payload size, the Block mechanism from [RFC7959] 673 may be used, as explained in more detail in Section 7. 675 There are two additional Uri-Query options for the GET and FETCH 676 methods. 678 +-------------+-----------------------------------------------------+ 679 | Uri-Query | Description | 680 | option | | 681 +-------------+-----------------------------------------------------+ 682 | c | Control selection of configuration and non- | 683 | | configuration data nodes (GET and FETCH) | 684 | | | 685 | d | Control retrieval of default values. | 686 +-------------+-----------------------------------------------------+ 688 5.2.1. Using the 'c' Uri-Query option 690 The 'c' (content) parameter controls how descendant nodes of the 691 requested data nodes will be processed in the reply. 693 The allowed values are: 695 +-------+-----------------------------------------------------+ 696 | Value | Description | 697 +-------+-----------------------------------------------------+ 698 | c | Return only configuration descendant data nodes | 699 | | | 700 | n | Return only non-configuration descendant data nodes | 701 | | | 702 | a | Return all descendant data nodes | 703 +-------+-----------------------------------------------------+ 705 This parameter is only allowed for GET and FETCH methods on datastore 706 and data node resources. A 4.02 (Bad Option) error is returned if 707 used for other methods or resource types. 709 If this Uri-Query option is not present, the default value is "a". 711 5.2.2. Using the 'd' Uri-Query option 713 The "d" (with-defaults) parameter controls how the default values of 714 the descendant nodes of the requested data nodes will be processed. 716 The allowed values are: 718 +-------+-----------------------------------------------------------+ 719 | Value | Description | 720 +-------+-----------------------------------------------------------+ 721 | a | All data nodes are reported. Defined as 'report-all' in | 722 | | section 3.1 of [RFC6243]. | 723 | | | 724 | t | Data nodes set to the YANG default are not reported. | 725 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 726 +-------+-----------------------------------------------------------+ 728 If the target of a GET or FETCH method is a data node that represents 729 a leaf that has a default value, and the leaf has not been given a 730 value by any client yet, the server MUST return the default value of 731 the leaf. 733 If the target of a GET method is a data node that represents a 734 container or list that has child resources with default values, and 735 these have not been given value yet, 737 The server MUST not return the child resource if d= 't' 739 The server MUST return the child resource if d= 'a'. 741 If this Uri-Query option is not present, the default value is 't'. 743 5.2.3. GET 745 A request to read the values of a data node instance is sent with a 746 confirmable CoAP GET message. An instance identifier is specified in 747 the URI path prefixed with the example path /c. 749 FORMAT: 750 GET /c/instance-identifier 752 2.05 Content (Content-Format: application/yang-value+cbor) 753 data-node-value 755 The returned payload contains the CBOR encoding of the specified data 756 node instance value. 758 5.2.3.1. GET Examples 760 Using for example the current-datetime leaf from Appendix C.1, a 761 request is sent to retrieve the value of system-state/clock/current- 762 datetime specified in container system-state. The SID of system- 763 state/clock/current-datetime is 1719, encoded in octal 3267, yields 764 two 6 bit decimal numbers 26 and 55, encoded in base64, (according to 765 table 2 of [RFC4648]) yields a3. The response to the request returns 766 the CBOR encoding of this leaf of type 'string' as defined in 767 [I-D.ietf-core-yang-cbor] section 5.4. 769 REQ: GET example.com/c/a3 771 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 772 "2014-10-26T12:16:31Z" 774 The next example represents the retrieval of a YANG container. In 775 this case, the CoMI client performs a GET request on the clock 776 container (SID = 1717; base64: a1). The container returned is 777 encoded using a CBOR map as specified by [I-D.ietf-core-yang-cbor] 778 section 4.2. 780 REQ: GET example.com/c/a1 782 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 783 { 784 +2 : "2014-10-26T12:16:51Z", / SID 1719 / 785 +1 : "2014-10-21T03:00:00Z" / SID 1718 / 786 } 788 This example shows the retrieval of the /interfaces/interface YANG 789 list accessed using SID 1533 (base64: X9). The return payload is 790 encoded using a CBOR array as specified by [I-D.ietf-core-yang-cbor] 791 section 4.4.1 containing 2 instances. 793 REQ: GET example.com/c/X9 795 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 796 [ 797 { 798 +4 : "eth0", / name (SID 1537) / 799 +1 : "Ethernet adaptor", / description (SID 1534) / 800 +5 : 1179, / type, (SID 1538) identity / 801 / ethernetCsmacd (SID 1179) / 802 +2 : true / enabled ( SID 1535) / 803 }, 804 { 805 +4 : "eth1", / name (SID 1537) / 806 +1 : "Ethernet adaptor", / description (SID 1534) / 807 +5 : 1179, / type, (SID 1538) identity / 808 / ethernetCsmacd (SID 1179) / 809 +2 : false / enabled / 810 } 811 ] 812 It is equally possible to select a leaf of a specific instance of a 813 list. The example below requests the description leaf (SID=1534, 814 base64: X-) within the interface list corresponding to the list key 815 "eth0". The returned value is encoded in CBOR based on the rules 816 specified by [I-D.ietf-core-yang-cbor] section 5.4. 818 REQ: GET example.com/c/X-?k="eth0" 820 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 821 "Ethernet adaptor" 823 5.2.4. FETCH 825 The FETCH is used to retrieve multiple data node values. The FETCH 826 request payload contains a list of instance-identifier encoded based 827 on the rules defined by Content-Format application/yang- 828 selectors+cbor in Section 2.5. The return response payload contains 829 a list of values encoded based on the rules defined by Content-Format 830 application/yang-values+cbor in Section 2.5. A value MUST be 831 returned for each instance-identifier specified in the request. A 832 CBOR null is returned for each data node requested by the client, not 833 supported by the server or not currently instantiated. 835 FORMAT: 836 FETCH /c (Content-Format :application/yang-selectors+cbor) 837 CBOR array of instance-identifier 839 2.05 Content (Content-Format: application/yang-values+cbor) 840 CBOR array of data-node-value 842 5.2.4.1. FETCH examples 844 The example uses the current-datetime leaf and the interface list 845 from Appendix C.1. In the following example the value of current- 846 datetime (SID 1719 and the interface list (SID 1533) instance 847 identified with name="eth0" are queried. 849 REQ: FETCH /c (Content-Format :application/yang-selectors+cbor) 850 [ 851 1719, / SID 1719 / 852 [-186, "eth0"] / SID 1533 with name = "eth0" / 853 ] 855 RES: 2.05 Content (Content-Format :application/yang-value+cbor) 856 [ 857 "2014-10-26T12:16:31Z", 858 { 859 +4 : "eth0", / name (SID 1537) / 860 +1 : "Ethernet adaptor", / description (SID 1534) / 861 +5 : 1179, / type (SID 1538), identity / 862 / ethernetCsmacd (SID 1179) / 863 +2 : true / enabled (SID 1535) / 864 } 865 ] 867 5.3. Data Editing 869 CoMI allows datastore contents to be created, modified and deleted 870 using CoAP methods. 872 5.3.1. Data Ordering 874 A CoMI server SHOULD preserve the relative order of all user-ordered 875 list and leaf-list entries that are received in a single edit 876 request. These YANG data node types are encoded as CBOR arrays so 877 messages will preserve their order. 879 5.3.2. POST 881 The CoAP POST operation is used in CoMI for creation of data node 882 resources and the invocation of "ACTION" and "RPC" resources. Refer 883 to Section 5.6 for details on "ACTION" and "RPC" resources. 885 A request to create a data node resource is sent with a confirmable 886 CoAP POST message. The URI specifies the data node to be 887 instantiated at the exception of list intances. In this case, for 888 compactness, the URI specifies the list for which an instance is 889 created. 891 FORMAT: 892 POST /c/ 893 (Content-Format :application/yang-value+cbor) 894 data-node-value 896 2.01 Created 898 If the data node resource already exists, then the POST request MUST 899 fail and a "4.09 Conflict" response code MUST be returned 901 5.3.2.1. Post example 903 The example uses the interface list from Appendix C.1. Example is 904 creating a new list instance within the interface list (SID = 1533): 906 REQ: POST /c/X9 (Content-Format :application/yang-value+cbor) 907 { 908 +4 : "eth5", / name (SID 1537) / 909 +1 : "Ethernet adaptor", / description (SID 1534) / 910 +5 : 1179, / type (SID 1538), identity / 911 / ethernetCsmacd (SID 1179) / 912 +2 : true / enabled (SID 1535) / 913 } 915 RES: 2.01 Created 917 5.3.3. PUT 919 A data node resource instance is created or replaced with the PUT 920 method. A request to set the value of a data node instance is sent 921 with a confirmable CoAP PUT message. 923 FORMAT: 924 PUT /c/ 925 (Content-Format :application/yang-value+cbor) 926 data-node-value 928 2.01 Created 930 5.3.3.1. PUT example 932 The example uses the interface list from Appendix C.1. Example is 933 renewing an instance of the list interface (SID = 1533) with key 934 name="eth0": 936 REQ: PUT /c/X9?k="eth0" 937 (Content-Format :application/yang-value+cbor) 938 { 939 +4 : "eth0", / name (SID 1537) / 940 +1 : "Ethernet adaptor", / description (SID 1534) / 941 +5 : 1179, / type (SID 1538), identity / 942 / ethernetCsmacd ( SID 1179) / 943 +2 : true / enabled (SID 1535) / 944 } 946 RES: 2.04 Changed 948 5.3.4. iPATCH 950 One or multiple data node instances are replaced with the idempotent 951 iPATCH method [RFC8132]. A request is sent with a confirmable CoAP 952 iPATCH message. 954 There are no Uri-Query options for the iPATCH method. 956 The processing of the iPATCH command is specified by Content-Format 957 application/yang-patch+cbor. In summary, if the CBOR patch payload 958 contains a data node instance that is not present in the target, this 959 instance is added. If the target contains the specified instance, 960 the content of this instance is replaced with the value of the 961 payload. A null value indicates the removal of an existing data node 962 instance. 964 FORMAT: 965 iPATCH /c (Content-Format :application/yang-patch+cbor) 966 ordered map of instance-identifier, data-node-value 968 2.04 Changed 970 5.3.4.1. iPATCH example 972 In this example, a CoMI client requests the following operations: 974 o Set "/system/ntp/enabled" (SID 1751) to true. 976 o Remove the server "tac.nrc.ca" from the"/system/ntp/server" (SID 977 1752) list. 979 o Add the server "NTP Pool server 2" to the list "/system/ntp/ 980 server" (SID 1752). 982 REQ: iPATCH /c (Content-Format :application/yang-patch+cbor) 983 [ 984 1751 , true, / enabled (1751) / 985 [+1, "tac.nrc.ca"], null, / server (SID 1752) / 986 +0, / server (SID 1752) / 987 { 988 +3 : "tic.nrc.ca", / name (SID 1755) / 989 +4 : true, / prefer (SID 1756) / 990 +5 : { / udp (SID 1757) / 991 +1 : "132.246.11.231" / address (SID 1758) / 992 } 993 } 994 ] 996 RES: 2.04 Changed 998 5.3.5. DELETE 1000 A data node resource is deleted with the DELETE method. 1002 FORMAT: 1003 Delete /c/ 1005 2.02 Deleted 1007 5.3.5.1. DELETE example 1009 The example uses the interface list from Appendix C.3. Example is 1010 deleting an instance of the interface list (SID = 1533): 1012 REQ: DELETE /c/X9?k="eth0" 1014 RES: 2.02 Deleted 1016 5.4. Full datastore access 1018 The methods GET, PUT, POST, and DELETE can be used to request, 1019 replace, create, and delete a whole datastore respectively. 1021 FORMAT: 1022 GET /c 1024 2.05 Content (Content-Format: application/yang-tree+cbor) 1025 ordered map of single-instance-identifier, data-node-value 1027 FORMAT: 1028 PUT /c (Content-Format: application/yang-tree+cbor) 1029 ordered map of single-instance-identifier, data-node-value 1031 2.04 Changed 1033 FORMAT: 1034 POST /c (Content-Format: application/yang-tree+cbor) 1035 ordered map of single-instance-identifier, data-node-value 1037 2.01 Created 1039 FORMAT: 1040 DELETE /c 1042 2.02 Deleted 1044 The content of the ordered map represents the complete datastore of 1045 the server at the GET indication of after a successful processing of 1046 a PUT or POST request. When an Ordered map is used to carry a whole 1047 datastore, all data nodes MUST be identified using single instance 1048 identifiers (i.e. a SID), list instance identifiers are not allowed. 1050 5.4.1. Full datastore examples 1052 The example uses the interface list and the clock container from 1053 Appendix C.3. Assume that the datastore contains two modules ietf- 1054 system (SID 1700) and ietf-interfaces (SID 1500); they contain the 1055 list interface (SID 1533) with one instance and the container Clock 1056 (SID 1717). After invocation of GET, a map with these two modules is 1057 returned: 1059 REQ: GET /c 1061 RES: 2.05 Content (Content-Format :application/yang-tree+cbor) 1062 [ 1063 1717, / Clock (SID 1717) / 1064 { 1065 +2: "2016-10-26T12:16:31Z", / current-datetime (SID 1719) / 1066 +1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1718) / 1067 }, 1068 -186, / clock (SID 1533) / 1069 { 1070 +4 : "eth0", / name (SID 1537) / 1071 +1 : "Ethernet adaptor", / description (SID 1534) / 1072 +5 : 1179, / type (SID 1538), identity: / 1073 / ethernetCsmacd (SID 1179) / 1074 +2 : true / enabled (SID 1535) / 1075 } 1076 ] 1078 5.5. Event stream 1080 Event notification is an essential function for the management of 1081 servers. CoMI allows notifications specified in YANG [RFC5277] to be 1082 reported to a list of clients. The recommended path of the default 1083 event stream is /s. The server MAY support additional event stream 1084 resources to address different notification needs. 1086 Reception of notification instances is enabled with the CoAP Observe 1087 [RFC7641] function. Clients subscribe to the notifications by 1088 sending a GET request with an "Observe" option, specifying the /s 1089 resource when the default stream is selected. 1091 Each response payload carries one or multiple notifications. The 1092 number of notification reported and the conditions used to remove 1093 notifications from the reported list is left to the implementers. 1094 When multiple notifications are reported, they MUST be ordered 1095 starting from the newest notification at index zero. 1097 An example implementation is: 1099 Every time an event is generated, the generated notification 1100 instance is appended to the chosen stream(s). After appending the 1101 instance, the content of the instance is sent to all clients 1102 observing the modified stream. 1104 Dependending on the storage space allocated to the notification 1105 stream, the oldest notifications that do not fit inside the 1106 notification stream storage space are removed. 1108 FORMAT: 1109 Get / Observe(0) 1111 2.05 Content (Content-Format :application/yang-tree+cbor) 1112 ordered map of instance-identifier, data-node-value 1114 The array of data node instances may contain identical entries which 1115 have been generated at different times. 1117 5.5.1. Notify Examples 1119 Suppose the server generates the event specified in Appendix C.4. By 1120 executing a GET on the /s resource the client receives the following 1121 response: 1123 REQ: GET /s Observe(0) Token(0x93) 1125 RES: 2.05 Content (Content-Format :application/yang-tree+cbor) 1126 Observe(12) Token(0x93) 1127 [ 1128 60010, / example-port-fault (SID 60010) / 1129 { 1130 +1 : "0/4/21", / port-name (SID 60011) / 1131 +2 : "Open pin 2" / port-fault (SID 60012) / 1132 }, 1133 +0, / example-port-fault (SID 60010) / 1134 { 1135 +1 : "1/4/21", / port-name (SID 60011) / 1136 +2 : "Open pin 5" / port-fault (SID 60012) / 1137 } 1138 ] 1140 In the example, the request returns a success response with the 1141 contents of the last two generated events. Consecutively the server 1142 will regularly notify the client when a new event is generated. 1144 To check that the client is still alive, the server MUST send 1145 confirmable notifications periodically. When the client does not 1146 confirm the notification from the server, the server will remove the 1147 client from the list of observers [RFC7641]. 1149 5.6. RPC statements 1151 The YANG "action" and "RPC" statements specify the execution of a 1152 Remote procedure Call (RPC) in the server. It is invoked using a 1153 POST method to an "Action" or "RPC" resource instance. The request 1154 payload contains the values assigned to the input container when 1155 specified. The response payload contains the values of the output 1156 container when specified. Both the input and output containers are 1157 encoded in CBOR using the rules defined in [I-D.ietf-core-yang-cbor] 1158 section 4.2.1. Root data nodes are encoded using the delta between 1159 the current SID and the SID of the invoked instance identifier a 1160 specified by the URI. 1162 The returned success response code is 2.05 Content. 1164 FORMAT: 1165 POST /c/ 1166 (Content-Format :application/yang-value+cbor) 1167 data-node-value 1169 2.05 Content (Content-Format :application/yang-value+cbor) 1170 data-node-value 1172 5.6.1. RPC Example 1174 The example is based on the YANG action specification of 1175 Appendix C.2. A server list is specified and the action "reset" (SID 1176 60002, base64: Opq), that is part of a "server instance" with key 1177 value "myserver", is invoked. 1179 REQ: POST /c/Opq?k="myserver" 1180 (Content-Format :application/yang-value+cbor) 1181 { 1182 +1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / 1183 } 1185 RES: 2.05 Content (Content-Format :application/yang-value+cbor) 1186 { 1187 +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ 1188 } 1190 6. Access to MIB Data 1192 Appendix C.5 shows a YANG module mapped from the SMI specification 1193 "IP-MIB" [RFC4293]. The following example shows the 1194 "ipNetToPhysicalEntry" list with 2 instances, using diagnostic 1195 notation without delta encoding. 1197 { 1198 60021 : / list ipNetToPhysicalEntry / 1199 [ 1200 { 1201 60022 : 1, / ipNetToPhysicalIfIndex / 1202 60023 : 1, / ipNetToPhysicalNetAddressType / 1203 60024 : h'0A000033', / ipNetToPhysicalNetAddress / 1204 60025 : h'00000A01172D',/ ipNetToPhysicalPhysAddress / 1205 60026 : 2333943, / ipNetToPhysicalLastUpdated / 1206 60027 : 4, / ipNetToPhysicalType / 1207 60028 : 1, / ipNetToPhysicalState / 1208 60029 : 1 / ipNetToPhysicalRowStatus / 1209 }, 1210 { 1211 60022 : 1, / ipNetToPhysicalIfIndex / 1212 60023 : 1, / ipNetToPhysicalNetAddressType / 1213 60024 : h'09020304', / ipNetToPhysicalNetAddress / 1214 60025 : h'00000A36200A',/ ipNetToPhysicalPhysAddress / 1215 60026 : 2329836, / ipNetToPhysicalLastUpdated / 1216 60027 : 3, / ipNetToPhysicalType / 1217 60028 : 6, / ipNetToPhysicalState / 1218 60029 : 1 / ipNetToPhysicalRowStatus / 1219 } 1220 ] 1221 } 1223 In this example one instance of /ip/ipNetToPhysicalEntry (SID 60021, 1224 base64: Oz1) that matches the keys ipNetToPhysicalIfIndex = 1, 1225 ipNetToPhysicalNetAddressType = ipv4 and ipNetToPhysicalNetAddress = 1226 9.2.3.4 (h'09020304', base64: CQIDBA) is requested. 1228 REQ: GET example.com/c/Oz1?k="1,1,CQIDBA" 1230 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 1231 { 1232 +1 : 1, / ( SID 60022 ) / 1233 +2 : 1, / ( SID 60023 ) / 1234 +3 : h'09020304', / ( SID 60024 ) / 1235 +4 : h'00000A36200A', / ( SID 60025 ) / 1236 +5 : 2329836, / ( SID 60026 ) / 1237 +6 : 3, / ( SID 60027 ) / 1238 +7 : 6, / ( SID 60028 ) / 1239 +8 : 1 / ( SID 60029 ) / 1240 } 1242 7. Use of Block 1244 The CoAP protocol provides reliability by acknowledging the UDP 1245 datagrams. However, when large pieces of data need to be 1246 transported, datagrams get fragmented, thus creating constraints on 1247 the resources in the client, server and intermediate routers. The 1248 block option [RFC7959] allows the transport of the total payload in 1249 individual blocks of which the size can be adapted to the underlying 1250 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1251 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1252 acknowledged to guarantee reliability. 1254 Notice that the Block mechanism splits the data at fixed positions, 1255 such that individual data fields may become fragmented. Therefore, 1256 assembly of multiple blocks may be required to process the complete 1257 data field. 1259 Beware of race conditions. Blocks are filled one at a time and care 1260 should be taken that the whole data representation is sent in 1261 multiple blocks sequentially without interruption. On the server, 1262 values are changed, lists are re-ordered, extended or reduced. When 1263 these actions happen during the serialization of the contents of the 1264 resource, the transported results do not correspond with a state 1265 having occurred in the server; or worse the returned values are 1266 inconsistent. For example: array length does not correspond with the 1267 actual number of items. It may be advisable to use CBOR maps or CBOR 1268 arrays of undefined length, which are foreseen for data streaming 1269 purposes. 1271 8. Resource Discovery 1273 The presence and location of (path to) the management data are 1274 discovered by sending a GET request to "/.well-known/core" including 1275 a resource type (RT) parameter with the value "core.c.datastore" 1276 [RFC6690]. Upon success, the return payload will contain the root 1277 resource of the management data. It is up to the implementation to 1278 choose its root resource, the value "/c" is used as an example. The 1279 example below shows the discovery of the presence and location of 1280 management data. 1282 REQ: GET /.well-known/core?rt=core.c.datastore 1284 RES: 2.05 Content 1285 ; rt="core.c.datastore" 1287 Implemented data nodes MAY be discovered using the standard CoAP 1288 resource discovery. The implementation can add the data node 1289 identifiers (SID) supported to /.well-known/core with 1290 rt="core.c.datanode". The available SIDs can be discovered by 1291 sending a GET request to "/.well-known/core" including a resource 1292 type (rt) parameter with the value "core.c.datanode". Upon success, 1293 the return payload will contain the registered SIDs and their 1294 location. 1296 The example below shows the discovery of the presence and location of 1297 data nodes. 1299 REQ: GET /.well-known/core?rt=core.c.datanode 1301 RES: 2.05 Content 1302 ; rt="core.c.datanode", 1303 ; rt="core.c.datanode" 1305 The list of data nodes may become prohibitively long. Therefore, it 1306 is recommended to discover the details about the YANG modules 1307 implemented by reading a YANG module library (e.g. "ietf-comi-yang- 1308 library" ad defined by [I-D.veillette-core-yang-library]). 1310 The resource "/mod.uri" is used to retrieve the location of the YANG 1311 module library. This library can be stored locally on each server, 1312 or remotely on a different server. The latter is advised when the 1313 deployment of many servers are identical. 1315 The following example shows the URI of a local instance of container 1316 modules-state (SID=1802) as defined in 1317 [I-D.veillette-core-yang-library]. 1319 REQ: GET example.com/mod.uri 1321 RES: 2.05 Content (Content-Format: text/plain; charset=utf-8) 1322 example.com/c/cK 1324 The following example shows the URI of a remote instance of same 1325 container. 1327 REQ: GET example.com/mod.uri 1329 RES: 2.05 Content (Content-Format: text/plain; charset=utf-8) 1330 example-remote-server.com/group17/cK 1332 Within the YANG module library all information about the module is 1333 stored such as: module identifier, identifier hierarchy, grouping, 1334 features and revision numbers. 1336 9. Error Handling 1338 In case a request is received which cannot be processed properly, the 1339 CoMI server MUST return an error message. This error message MUST 1340 contain a CoAP 4.xx or 5.xx response code. 1342 Errors returned by a CoMI server can be broken into two categories, 1343 those associated to the CoAP protocol itself and those generated 1344 during the validation of the YANG data model constrains as described 1345 in [RFC7950] section 8. 1347 The following list of common CoAP errors should be implemented by 1348 CoMI servers. This list is not exhaustive, other errors defined by 1349 CoAP and associated RFCs may be applicable. 1351 o Error 4.01 (Unauthorized) is returned by the CoMI server when the 1352 CoMI client is not authorized to perform the requested action on 1353 the targeted resource (i.e. data node, datastore, rpc, action or 1354 event stream). 1356 o Error 4.02 (Bad Option) is returned by the CoMI server when one or 1357 more CoAP options are unknown or malformed. 1359 o Error 4.04 (Not Found) is returned by the CoMI server when the 1360 CoMI client is requesting a non-instantiated resource (i.e. data 1361 node, datastore, rpc, action or event stream). 1363 o Error 4.05 (Method Not Allowed) is returned by the CoMI server 1364 when the CoMI client is requesting a method not supported on the 1365 targeted resource. (e.g. GET on an rpc, PUT or POST on a data 1366 node with "config" set to false). 1368 o Error 4.08 (Request Entity Incomplete) is returned by the CoMI 1369 server if one or multiple blocks of a block transfer request is 1370 missing, see [RFC7959] for more details. 1372 o Error 4.13 (Request Entity Too Large) may be returned by the CoMI 1373 server during a block transfer request, see [RFC7959] for more 1374 details. 1376 o Error 4.15 (Unsupported Content-Format) is returned by the CoMI 1377 server when the Content-Format used in the request don't match 1378 those specified in section 2.3. 1380 CoMI server MUST also enforce the different constraints associated to 1381 the YANG data models implemented. These constraints are described in 1382 [RFC7950] section 8. These errors are reported using the CoAP error 1383 code 4.00 (Bad Request) and may have the following error container as 1384 payload. The YANG definition and associated .sid file are available 1385 in Appendix A and Appendix B. The error container is encoded using 1386 delta value equal to the SID of the current schema node minus the SID 1387 of the parent container (i.e 1024). 1389 +--rw error! 1390 +--rw error-tag identityref 1391 +--rw error-app-tag? identityref 1392 +--rw data-node-in-error? instance-identifier 1393 +--rw error-message? string 1395 The following error-tag and error-app-tag are defined by the ietf- 1396 comi YANG module, these tags are implemented as YANG identity and can 1397 be extended as needed. 1399 o error-tag operation-failed is returned by the CoMI server when the 1400 operation request cannot be processed successfully. 1402 * error-app-tag malformed-message is returned by the CoMI server 1403 when the payload received from the CoMI client don't contain a 1404 well-formed CBOR content as defined in [RFC7049] section 3.3 or 1405 don't comply with the CBOR structure defined within this 1406 document. 1408 * error-app-tag data-not-unique is returned by the CoMI server 1409 when the validation of the 'unique' constraint of a list or 1410 leaf-list fails. 1412 * error-app-tag too-many-elements is returned by the CoMI server 1413 when the validation of the 'max-elements' constraint of a list 1414 or leaf-list fails. 1416 * error-app-tag too-few-elements is returned by the CoMI server 1417 when the validation of the 'min-elements' constraint of a list 1418 or leaf-list fails. 1420 * error-app-tag must-violation is returned by the CoMI server 1421 when the restrictions imposed by a 'must' statement are 1422 violated. 1424 * error-app-tag duplicate is returned by the CoMI server when a 1425 client tries to create a duplicate list or leaf-list entry. 1427 o error-tag invalid-value is returned by the CoMI server when the 1428 CoMI client tries to update or create a leaf with a value encoded 1429 using an invalid CBOR datatype or if the 'range', 'length', 1430 'pattern' or 'require-instance' constrain is not fulfilled. 1432 * error-app-tag invalid-datatype is returned by the CoMI server 1433 when CBOR encoding don't follow the rules set by or when the 1434 value is incompatible with the YANG Built-In type. (e.g. a 1435 value greater than 127 for an int8, undefined enumeration) 1437 * error-app-tag not-in-range is returned by the CoMI server when 1438 the validation of the 'range' property fails. 1440 * error-app-tag invalid-length is returned by the CoMI server 1441 when the validation of the 'length' property fails. 1443 * error-app-tag pattern-test-failed is returned by the CoMI 1444 server when the validation of the 'pattern' property fails. 1446 o error-tag missing-element is returned by the CoMI server when the 1447 operation requested by a CoMI client fail to comply with the 1448 'mandatory' constraint defined. The 'mandatory' constraint is 1449 enforced for leafs and choices, unless the node or any of its 1450 ancestors have a 'when' condition or 'if-feature' expression that 1451 evaluates to 'false'. 1453 * error-app-tag missing-key is returned by the CoMI server to 1454 further qualify an missing-element error. This error is 1455 returned when the CoMI client tries to create or list instance, 1456 without all the 'key' specified or when the CoMI client tries 1457 to delete a leaf listed as a 'key'. 1459 * error-app-tag missing-input-parameter is returned by the CoMI 1460 server when the input parameters of an RPC or action are 1461 incomplete. 1463 o error-tag unknown-element is returned by the CoMI server when the 1464 CoMI client tries to access a data node of a YANG module not 1465 supported, of a data node associated to an 'if-feature' expression 1466 evaluated to 'false' or to a 'when' condition evaluated to 1467 'false'. 1469 o error-tag bad-element is returned by the CoMI server when the CoMI 1470 client tries to create data nodes for more than one case in a 1471 choice. 1473 o error-tag data-missing is returned by the CoMI server when a data 1474 node required to accept the request is not present. 1476 * error-app-tag instance-required is returned by the CoMI server 1477 when a leaf of type 'instance-identifier' or 'leafref' marked 1478 with require-instance set to 'true' refers to an instance that 1479 does not exist. 1481 * error-app-tag missing-choice is returned by the CoMI server 1482 when no nodes exist in a mandatory choice. 1484 o error-tag error is returned by the CoMI server when an unspecified 1485 error has occurred. 1487 For example, the CoMI server might return the following error. 1489 RES: 4.00 Bad Request (Content-Format :application/yang-value+cbor) 1490 { 1491 +4 : 1020, / error-tag = invalid-value / 1492 +2 : 1012, / error-app-tag = not-in-range / 1493 +1 : 1736, / data-node-in-error = timezone-utc-offset / 1494 +3 : "maximum value exceeded" / error-message / 1495 } 1497 10. Security Considerations 1499 For secure network management, it is important to restrict access to 1500 configuration variables only to authorized parties. CoMI re-uses the 1501 security mechanisms already available to CoAP, this includes DTLS 1502 [RFC6347] for protected access to resources, as well suitable 1503 authentication and authorization mechanisms. 1505 Among the security decisions that need to be made are selecting 1506 security modes and encryption mechanisms (see [RFC7252]). This 1507 requires a trade-off, as the NoKey mode gives no protection at all, 1508 but is easy to implement, whereas the X.509 mode is quite secure, but 1509 may be too complex for constrained devices. 1511 In addition, mechanisms for authentication and authorization may need 1512 to be selected. 1514 CoMI avoids defining new security mechanisms as much as possible. 1515 However, some adaptations may still be required, to cater for CoMI's 1516 specific requirements. 1518 11. IANA Considerations 1520 11.1. Resource Type (rt=) Link Target Attribute Values Registry 1522 This document adds the following resource type to the "Resource Type 1523 (rt=) Link Target Attribute Values", within the "Constrained RESTful 1524 Environments (CoRE) Parameters" registry. 1526 +--------------------+---------------------+-----------+ 1527 | Value | Description | Reference | 1528 +--------------------+---------------------+-----------+ 1529 | core.c.datastore | YANG datastore | RFC XXXX | 1530 | | | | 1531 | core.c.datanode | YANG data node | RFC XXXX | 1532 | | | | 1533 | core.c.liburi | YANG module library | RFC XXXX | 1534 | | | | 1535 | core.c.eventstream | YANG event stream | RFC XXXX | 1536 +--------------------+---------------------+-----------+ 1538 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1539 note. 1541 11.2. CoAP Content-Formats Registry 1543 This document adds the following Content-Format to the "CoAP Content- 1544 Formats", within the "Constrained RESTful Environments (CoRE) 1545 Parameters" registry. 1547 +---------------------------------+-------------+-----------+ 1548 | Media Type | Excoding ID | Reference | 1549 +---------------------------------+-------------+-----------+ 1550 | application/yang-value+cbor | XXX | RFC XXXX | 1551 | | | | 1552 | application/yang-values+cbor | XXX | RFC XXXX | 1553 | | | | 1554 | application/yang-selectors+cbor | XXX | RFC XXXX | 1555 | | | | 1556 | application/yang-tree+cbor | XXX | RFC XXXX | 1557 | | | | 1558 | application/yang-ipatch+cbor | XXX | RFC XXXX | 1559 +---------------------------------+-------------+-----------+ 1561 // RFC Ed.: replace XXX with assigned IDs and remove this note. // 1562 RFC Ed.: replace RFC XXXX with this RFC number and remove this note. 1564 11.3. Media Types Registry 1566 This document adds the following media types to the "Media Types" 1567 registry. 1569 +---------------------+---------------------------------+-----------+ 1570 | Name | Template | Reference | 1571 +---------------------+---------------------------------+-----------+ 1572 | yang-value+cbor | application/yang-value+cbor | RFC XXXX | 1573 | | | | 1574 | yang-values+cbor | application/yang-values+cbor | RFC XXXX | 1575 | | | | 1576 | yang-selectors+cbor | application/yang-selectors+cbor | RFC XXXX | 1577 | | | | 1578 | yang-tree+cbor | application/yang-tree+cbor | RFC XXXX | 1579 | | | | 1580 | yang-ipatch+cbor | application/yang-ipatch+cbor | RFC XXXX | 1581 +---------------------+---------------------------------+-----------+ 1583 Each of these media types share the following information: 1585 o Subtype name: 1587 o Required parameters: N/A 1589 o Optional parameters: N/A 1591 o Encoding considerations: binary 1593 o Security considerations: See the Security Considerations section 1594 of RFC XXXX 1596 o Interoperability considerations: N/A 1598 o Published specification: RFC XXXX 1600 o Applications that use this media type: CoMI 1602 o Fragment identifier considerations: N/A 1604 o Additional information: 1606 * Deprecated alias names for this type: N/A 1608 * Magic number(s): N/A 1610 * File extension(s): N/A 1612 * Macintosh file type code(s): N/A 1614 o Person & email address to contact for further information: 1615 iesg&ietf.org 1617 o Intended usage: COMMON 1619 o Restrictions on usage: N/A 1621 o Author: Michel Veillette, ietf&augustcellars.com 1623 o Change Controller: IESG 1625 o Provisional registration? No 1627 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1628 note. 1630 11.4. Concise Binary Object Representation (CBOR) Tags Registry 1632 This document adds the following tags to the "Concise Binary Object 1633 Representation (CBOR) Tags" registry. 1635 +-----+-----------+-------------+-----------+ 1636 | Tag | Data Item | Semantics | Reference | 1637 +-----+-----------+-------------+-----------+ 1638 | xxx | array | Oedered map | RFC XXXX | 1639 +-----+-----------+-------------+-----------+ 1641 // RFC Ed.: replace xxx by the assigned Tag and remove this note. // 1642 RFC Ed.: replace RFC XXXX with this RFC number and remove this note. 1644 12. Acknowledgements 1646 We are very grateful to Bert Greevenbosch who was one of the original 1647 authors of the CoMI specification and specified CBOR encoding and use 1648 of hashes. 1650 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1651 transported under SNMP. Carsten Bormann has given feedback on the 1652 use of CBOR. 1654 Timothy Carey has provided the text for Appendix D. 1656 The draft has benefited from comments (alphabetical order) by Rodney 1657 Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy 1658 Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes 1659 Tschofenig, Michael Verschoor, and Thomas Watteyne. 1661 13. References 1663 13.1. Normative References 1665 [I-D.ietf-core-sid] 1666 Veillette, M., Pelov, A., Turner, R., Minaburo, A., and A. 1667 Somaraju, "YANG Schema Item iDentifier (SID)", draft-ietf- 1668 core-sid-01 (work in progress), May 2017. 1670 [I-D.ietf-core-yang-cbor] 1671 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 1672 Minaburo, "CBOR Encoding of Data Modeled with YANG", 1673 draft-ietf-core-yang-cbor-04 (work in progress), February 1674 2017. 1676 [I-D.veillette-core-yang-library] 1677 Veillette, M., "Constrained YANG Module Library", draft- 1678 veillette-core-yang-library-00 (work in progress), January 1679 2017. 1681 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1682 Requirement Levels", BCP 14, RFC 2119, 1683 DOI 10.17487/RFC2119, March 1997, 1684 . 1686 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1687 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1688 . 1690 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1691 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1692 . 1694 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1695 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1696 . 1698 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1699 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1700 October 2013, . 1702 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1703 Application Protocol (CoAP)", RFC 7252, 1704 DOI 10.17487/RFC7252, June 2014, 1705 . 1707 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1708 Application Protocol (CoAP)", RFC 7641, 1709 DOI 10.17487/RFC7641, September 2015, 1710 . 1712 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1713 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1714 . 1716 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1717 the Constrained Application Protocol (CoAP)", RFC 7959, 1718 DOI 10.17487/RFC7959, August 2016, 1719 . 1721 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1722 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1723 . 1725 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1726 FETCH Methods for the Constrained Application Protocol 1727 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1728 . 1730 13.2. Informative References 1732 [I-D.ietf-core-interfaces] 1733 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Reusable 1734 Interface Definitions for Constrained RESTful 1735 Environments", draft-ietf-core-interfaces-09 (work in 1736 progress), March 2017. 1738 [netconfcentral] 1739 YUMAworks, "NETCONF Central: library of YANG modules", 1740 Web http://www.netconfcentral.org/modulelist. 1742 [RFC4293] Routhier, S., Ed., "Management Information Base for the 1743 Internet Protocol (IP)", RFC 4293, DOI 10.17487/RFC4293, 1744 April 2006, . 1746 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1747 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1748 January 2012, . 1750 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1751 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1752 . 1754 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1755 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1756 2014, . 1758 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1759 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1760 . 1762 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1763 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1764 2014, . 1766 [XML] W3C, "Extensible Markup Language (XML)", 1767 Web http://www.w3.org/xml. 1769 [yang-cbor] 1770 Veillette, M., "yang-cbor Registry", Web 1771 https://github.com/core-wg/yang- 1772 cbor/tree/master/registry/. 1774 Appendix A. ietf-comi YANG module 1776 file "ietf-comi@2017-07-01.yang" 1777 module ietf-comi { 1778 yang-version 1.1; 1780 namespace "urn:ietf:params:xml:ns:yang:ietf-comi"; 1781 prefix comi; 1783 organization 1784 "IETF Core Working Group"; 1786 contact 1787 "Michel Veillette 1788 1790 Alexander Pelov 1791 1793 Peter van der Stok 1794 1796 Andy Bierman 1797 "; 1799 description 1800 "This module contains the different definitions required 1801 by the CoMI protocol."; 1803 revision 2017-07-01 { 1804 description 1805 "Initial revision."; 1806 reference 1807 "draft-ietf-core-comi"; 1808 } 1810 identity error-tag { 1811 description 1812 "Base identity for error-tag."; 1813 } 1815 identity operation-failed { 1816 base error-tag; 1817 description 1818 "Returned by the CoMI server when the operation request 1819 can't be processed successfully."; 1820 } 1822 identity invalid-value { 1823 base error-tag; 1824 description 1825 "Returned by the CoMI server when the CoMI client tries to 1826 update or create a leaf with a value encoded using an 1827 invalid CBOR datatype or if the 'range', 'length', 1828 'pattern' or 'require-instance' constrain is not 1829 fulfilled."; 1830 } 1832 identity missing-element { 1833 base error-tag; 1834 description 1835 "Returned by the CoMI server when the operation requested 1836 by a CoMI client fails to comply with the 'mandatory' 1837 constraint defined. The 'mandatory' constraint is 1838 enforced for leafs and choices, unless the node or any of 1839 its ancestors have a 'when' condition or 'if-feature' 1840 expression that evaluates to 'false'."; 1841 } 1843 identity unknown-element { 1844 base error-tag; 1845 description 1846 "Returned by the CoMI server when the CoMI client tries to 1847 access a data node of a YANG module not supported, of a 1848 data node associated with an 'if-feature' expression 1849 evaluated to 'false' or to a 'when' condition evaluated 1850 to 'false'."; 1852 } 1854 identity bad-element { 1855 base error-tag; 1856 description 1857 "Returned by the CoMI server when the CoMI client tries to 1858 create data nodes for more than one case in a choice."; 1859 } 1861 identity data-missing { 1862 base error-tag; 1863 description 1864 "Returned by the CoMI server when a data node required to 1865 accept the request is not present."; 1866 } 1868 identity error { 1869 base error-tag; 1870 description 1871 "Returned by the CoMI server when an unspecified error has 1872 occurred."; 1873 } 1875 identity error-app-tag { 1876 description 1877 "Base identity for error-app-tag."; 1878 } 1880 identity malformed-message { 1881 base error-app-tag; 1882 description 1883 "Returned by the CoMI server when the payload received 1884 from the CoMI client don't contain a well-formed CBOR 1885 content as defined in [RFC7049] section 3.3 or don't 1886 comply with the CBOR structure defined within this 1887 document."; 1888 } 1890 identity data-not-unique { 1891 base error-app-tag; 1892 description 1893 "Returned by the CoMI server when the validation of the 1894 'unique' constraint of a list or leaf-list fails."; 1895 } 1897 identity too-many-elements { 1898 base error-app-tag; 1899 description 1900 "Returned by the CoMI server when the validation of the 1901 'max-elements' constraint of a list or leaf-list fails."; 1902 } 1904 identity too-few-elements { 1905 base error-app-tag; 1906 description 1907 "Returned by the CoMI server when the validation of the 1908 'min-elements' constraint of a list or leaf-list fails."; 1909 } 1911 identity must-violation { 1912 base error-app-tag; 1913 description 1914 "Returned by the CoMI server when the restrictions 1915 imposed by a 'must' statement are violated."; 1916 } 1918 identity duplicate { 1919 base error-app-tag; 1920 description 1921 "Returned by the CoMI server when a client tries to create 1922 a duplicate list or leaf-list entry."; 1923 } 1925 identity invalid-datatype { 1926 base error-app-tag; 1927 description 1928 "Returned by the CoMI server when CBOR encoding is 1929 incorect or when the value encoded is incompatible with 1930 the YANG Built-In type. (e.g. value greater than 127 1931 for an int8, undefined enumeration)."; 1932 } 1934 identity not-in-range { 1935 base error-app-tag; 1936 description 1937 "Returned by the CoMI server when the validation of the 1938 'range' property fails."; 1939 } 1941 identity invalid-length { 1942 base error-app-tag; 1943 description 1944 "Returned by the CoMI server when the validation of the 1945 'length' property fails."; 1946 } 1947 identity pattern-test-failed { 1948 base error-app-tag; 1949 description 1950 "Returned by the CoMI server when the validation of the 1951 'pattern' property fails."; 1952 } 1954 identity missing-key { 1955 base error-app-tag; 1956 description 1957 "Returned by the CoMI server to further qualify a 1958 missing-element error. This error is returned when the 1959 CoMI client tries to create or list instance, without all 1960 the 'key' specified or when the CoMI client tries to 1961 delete a leaf listed as a 'key'."; 1962 } 1964 identity missing-input-parameter { 1965 base error-app-tag; 1966 description 1967 "Returned by the CoMI server when the input parameters 1968 of a RPC or action are incomplete."; 1969 } 1971 identity instance-required { 1972 base error-app-tag; 1973 description 1974 "Returned by the CoMI server when a leaf of type 1975 'instance-identifier' or 'leafref' marked with 1976 require-instance set to 'true' refers to an instance 1977 that does not exist."; 1978 } 1980 identity missing-choice { 1981 base error-app-tag; 1982 description 1983 "Returned by the CoMI server when no nodes exist in a 1984 mandatory choice."; 1985 } 1987 container error { 1988 presence "Error paylaod"; 1990 description 1991 "Optional payload of a 4.00 Bad Request CoAP error."; 1993 leaf error-tag { 1994 type identityref { 1995 base error-tag; 1996 } 1997 mandatory true; 1998 description 1999 "The enumerated error-tag."; 2000 } 2002 leaf error-app-tag { 2003 type identityref { 2004 base error-app-tag; 2005 } 2006 description 2007 "The application-specific error-tag."; 2008 } 2010 leaf data-node-in-error { 2011 type instance-identifier; 2012 description 2013 "When the error reported is caused by a specific data node, 2014 this leaf identifies the data node in error."; 2015 } 2017 leaf error-message { 2018 type string; 2019 description 2020 "A message describing the error."; 2021 } 2022 } 2023 } 2024 2026 Appendix B. ietf-comi .sid file 2028 { 2029 "assignment-ranges": [ 2030 { 2031 "entry-point": 1000, 2032 "size": 100 2033 } 2034 ], 2035 "module-name": "ietf-comi", 2036 "module-revision": "2017-07-01", 2037 "items": [ 2038 { 2039 "type": "Module", 2040 "label": "ietf-comi", 2041 "sid": 1000 2042 }, 2043 { 2044 "type": "identity", 2045 "label": "/error-app-tag", 2046 "sid": 1001 2047 }, 2048 { 2049 "type": "identity", 2050 "label": "/error-app-tag/data-not-unique", 2051 "sid": 1002 2052 }, 2053 { 2054 "type": "identity", 2055 "label": "/error-app-tag/duplicate", 2056 "sid": 1003 2057 }, 2058 { 2059 "type": "identity", 2060 "label": "/error-app-tag/instance-required", 2061 "sid": 1004 2062 }, 2063 { 2064 "type": "identity", 2065 "label": "/error-app-tag/invalid-datatype", 2066 "sid": 1005 2067 }, 2068 { 2069 "type": "identity", 2070 "label": "/error-app-tag/invalid-length", 2071 "sid": 1006 2072 }, 2073 { 2074 "type": "identity", 2075 "label": "/error-app-tag/malformed-message", 2076 "sid": 1007 2077 }, 2078 { 2079 "type": "identity", 2080 "label": "/error-app-tag/missing-choice", 2081 "sid": 1008 2082 }, 2083 { 2084 "type": "identity", 2085 "label": "/error-app-tag/missing-input-parameter", 2086 "sid": 1009 2087 }, 2088 { 2089 "type": "identity", 2090 "label": "/error-app-tag/missing-key", 2091 "sid": 1010 2092 }, 2093 { 2094 "type": "identity", 2095 "label": "/error-app-tag/must-violation", 2096 "sid": 1011 2097 }, 2098 { 2099 "type": "identity", 2100 "label": "/error-app-tag/not-in-range", 2101 "sid": 1012 2102 }, 2103 { 2104 "type": "identity", 2105 "label": "/error-app-tag/pattern-test-failed", 2106 "sid": 1013 2107 }, 2108 { 2109 "type": "identity", 2110 "label": "/error-app-tag/too-few-elements", 2111 "sid": 1014 2112 }, 2113 { 2114 "type": "identity", 2115 "label": "/error-app-tag/too-many-elements", 2116 "sid": 1015 2117 }, 2118 { 2119 "type": "identity", 2120 "label": "/error-tag", 2121 "sid": 1016 2122 }, 2123 { 2124 "type": "identity", 2125 "label": "/error-tag/bad-element", 2126 "sid": 1017 2127 }, 2128 { 2129 "type": "identity", 2130 "label": "/error-tag/data-missing", 2131 "sid": 1018 2132 }, 2133 { 2134 "type": "identity", 2135 "label": "/error-tag/error", 2136 "sid": 1019 2137 }, 2138 { 2139 "type": "identity", 2140 "label": "/error-tag/invalid-value", 2141 "sid": 1020 2142 }, 2143 { 2144 "type": "identity", 2145 "label": "/error-tag/missing-element", 2146 "sid": 1021 2147 }, 2148 { 2149 "type": "identity", 2150 "label": "/error-tag/operation-failed", 2151 "sid": 1022 2152 }, 2153 { 2154 "type": "identity", 2155 "label": "/error-tag/unknown-element", 2156 "sid": 1023 2157 }, 2158 { 2159 "type": "node", 2160 "label": "/error", 2161 "sid": 1024 2162 }, 2163 { 2164 "type": "node", 2165 "label": "/error/data-node-in-error", 2166 "sid": 1025 2167 }, 2168 { 2169 "type": "node", 2170 "label": "/error/error-app-tag", 2171 "sid": 1026 2172 }, 2173 { 2174 "type": "node", 2175 "label": "/error/error-message", 2176 "sid": 1027 2177 }, 2178 { 2179 "type": "node", 2180 "label": "/error/error-tag", 2181 "sid": 1028 2182 } 2183 ] 2184 } 2186 Appendix C. YANG example specifications 2188 This appendix shows five YANG example specifications taken over from 2189 as many existing YANG modules. The YANG modules are available from 2190 [netconfcentral]. Each YANG item identifier is accompanied by its 2191 SID shown after the "//" comment sign. 2193 C.1. ietf-system 2195 Excerpt of the YANG module ietf-system [RFC7317]. 2197 module ietf-system { // SID 1700 2198 container system { // SID 1715 2199 container clock { // SID 1734 2200 choice timezone { 2201 case timezone-name { 2202 leaf timezone-name { // SID 1735 2203 type timezone-name; 2204 } 2205 } 2206 case timezone-utc-offset { 2207 leaf timezone-utc-offset { // SID 1736 2208 type int16 { 2209 } 2210 } 2211 } 2212 } 2213 } 2214 container ntp { // SID 1750 2215 leaf enabled { // SID 1751 2216 type boolean; 2217 default true; 2218 } 2219 list server { // SID 1752 2220 key name; 2221 leaf name { // SID 1755 2222 type string; 2223 } 2224 choice transport { 2225 case udp { 2226 container udp { // SID 1757 2227 leaf address { // SID 1758 2228 type inet:host; 2229 } 2230 leaf port { // SID 1759 2231 type inet:port-number; 2232 } 2233 } 2235 } 2236 } 2237 leaf association-type { // SID 1753 2238 type enumeration { 2239 enum server { 2240 } 2241 enum peer { 2242 } 2243 enum pool { 2244 } 2245 } 2246 } 2247 leaf iburst { // SID 1754 2248 type boolean; 2249 } 2250 leaf prefer { // SID 1756 2251 type boolean; 2252 default false; 2253 } 2254 } 2255 } 2256 container system-state { // SID 1716 2257 container clock { // SID 1717 2258 leaf current-datetime { // SID 1719 2259 type yang:date-and-time; 2260 } 2261 leaf boot-datetime { // SID 1718 2262 type yang:date-and-time; 2263 } 2264 } 2265 } 2266 } 2268 C.2. server list 2270 Taken over from [RFC7950] section 7.15.3. 2272 module example-server-farm { 2273 yang-version 1.1; 2274 namespace "urn:example:server-farm"; 2275 prefix "sfarm"; 2277 import ietf-yang-types { 2278 prefix "yang"; 2279 } 2281 list server { // SID 60000 2282 key name; 2283 leaf name { // SID 60001 2284 type string; 2285 } 2286 action reset { // SID 60002 2287 input { 2288 leaf reset-at { // SID 60003 2289 type yang:date-and-time; 2290 mandatory true; 2291 } 2292 } 2293 output { 2294 leaf reset-finished-at { // SID 60004 2295 type yang:date-and-time; 2296 mandatory true; 2297 } 2298 } 2299 } 2300 } 2301 } 2303 C.3. interfaces 2305 Excerpt of the YANG module ietf-interfaces [RFC7223]. 2307 module ietf-interfaces { // SID 1500 2308 container interfaces { // SID 1505 2309 list interface { // SID 1533 2310 key "name"; 2311 leaf name { // SID 1537 2312 type string; 2313 } 2314 leaf description { // SID 1534 2315 type string; 2316 } 2317 leaf type { // SID 1538 2318 type identityref { 2319 base interface-type; 2320 } 2321 mandatory true; 2322 } 2324 leaf enabled { // SID 1535 2325 type boolean; 2326 default "true"; 2327 } 2329 leaf link-up-down-trap-enable { // SID 1536 2330 if-feature if-mib; 2331 type enumeration { 2332 enum enabled { 2333 value 1; 2334 } 2335 enum disabled { 2336 value 2; 2337 } 2338 } 2339 } 2340 } 2341 } 2342 } 2344 C.4. Example-port 2346 Notification example defined within this document. 2348 module example-port { 2349 ... 2350 notification example-port-fault { // SID 60010 2351 description 2352 "Event generated if a hardware fault on a 2353 line card port is detected"; 2354 leaf port-name { // SID 60011 2355 type string; 2356 description "Port name"; 2357 } 2358 leaf port-fault { // SID 60012 2359 type string; 2360 description "Error condition detected"; 2361 } 2362 } 2363 } 2365 C.5. IP-MIB 2367 The YANG translation of the SMI specifying the IP-MIB [RFC4293], 2368 extended with example SID numbers, yields: 2370 module IP-MIB { 2371 import IF-MIB { 2372 prefix if-mib; 2373 } 2374 import INET-ADDRESS-MIB { 2375 prefix inet-address; 2376 } 2377 import SNMPv2-TC { 2378 prefix smiv2; 2379 } 2380 import ietf-inet-types { 2381 prefix inet; 2382 } 2383 import yang-smi { 2384 prefix smi; 2385 } 2386 import ietf-yang-types { 2387 prefix yang; 2388 } 2390 container ip { // SID 60020 2391 list ipNetToPhysicalEntry { // SID 60021 2392 key "ipNetToPhysicalIfIndex 2393 ipNetToPhysicalNetAddressType 2394 ipNetToPhysicalNetAddress"; 2395 leaf ipNetToPhysicalIfIndex { // SID 60022 2396 type if-mib:InterfaceIndex; 2397 } 2398 leaf ipNetToPhysicalNetAddressType { // SID 60023 2399 type inet-address:InetAddressType; 2400 } 2401 leaf ipNetToPhysicalNetAddress { // SID 60024 2402 type inet-address:InetAddress; 2403 } 2404 leaf ipNetToPhysicalPhysAddress { // SID 60025 2405 type yang:phys-address { 2406 length "0..65535"; 2407 } 2408 } 2409 leaf ipNetToPhysicalLastUpdated { // SID 60026 2410 type yang:timestamp; 2411 } 2412 leaf ipNetToPhysicalType { // SID 60027 2413 type enumeration { 2414 enum "other" { 2415 value 1; 2416 } 2417 enum "invalid" { 2418 value 2; 2419 } 2420 enum "dynamic" { 2421 value 3; 2422 } 2423 enum "static" { 2424 value 4; 2425 } 2426 enum "local" { 2427 value 5; 2428 } 2429 } 2430 } 2431 leaf ipNetToPhysicalState { // SID 60028 2432 type enumeration { 2433 enum "reachable" { 2434 value 1; 2435 } 2436 enum "stale" { 2437 value 2; 2438 } 2439 enum "delay" { 2440 value 3; 2441 } 2442 enum "probe" { 2443 value 4; 2445 } 2446 enum "invalid" { 2447 value 5; 2448 } 2449 enum "unknown" { 2450 value 6; 2451 } 2452 enum "incomplete" { 2453 value 7; 2454 } 2455 } 2456 } 2457 leaf ipNetToPhysicalRowStatus { // SID 60029 2458 type smiv2:RowStatus; 2459 } // list ipNetToPhysicalEntry 2460 } // container ip 2461 } // module IP-MIB 2463 Appendix D. Comparison with LWM2M 2465 TO DO Need updated text based on the current version of CoMI. 2466 Multiple assumptions used in the original text are no more valid. 2468 Authors' Addresses 2470 Michel Veillette (editor) 2471 Trilliant Networks Inc. 2472 610 Rue du Luxembourg 2473 Granby, Quebec J2J 2V2 2474 Canada 2476 Email: michel.veillette@trilliantinc.com 2478 Peter van der Stok (editor) 2479 consultant 2481 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2482 Email: consultancy@vanderstok.org 2483 URI: www.vanderstok.org 2484 Alexander Pelov 2485 Acklio 2486 2bis rue de la Chataigneraie 2487 Cesson-Sevigne, Bretagne 35510 2488 France 2490 Email: a@ackl.io 2492 Andy Bierman 2493 YumaWorks 2494 685 Cochran St. 2495 Suite #160 2496 Simi Valley, CA 93065 2497 USA 2499 Email: andy@yumaworks.com