idnits 2.17.1 draft-ietf-core-comi-02.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 (December 01, 2017) is 2338 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 334 -- Looks like a reference, but probably isn't: '26' on line 335 -- Looks like a reference, but probably isn't: '57' on line 336 == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-02 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-05 == Outdated reference: A later version (-05) exists of draft-veillette-core-yang-library-01 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-10 -- 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: June 4, 2018 consultant 6 A. Pelov 7 Acklio 8 A. Bierman 9 YumaWorks 10 December 01, 2017 12 CoAP Management Interface 13 draft-ietf-core-comi-02 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 https://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 June 4, 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 (https://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 . . . . . . . . . . . . . . . . . . . . . . . . . 37 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 . . . . . . . . . . . . . . . . 46 113 Appendix C. YANG example specifications . . . . . . . . . . . . 49 114 C.1. ietf-system . . . . . . . . . . . . . . . . . . . . . . . 49 115 C.2. server list . . . . . . . . . . . . . . . . . . . . . . . 51 116 C.3. interfaces . . . . . . . . . . . . . . . . . . . . . . . 51 117 C.4. Example-port . . . . . . . . . . . . . . . . . . . . . . 52 118 C.5. IP-MIB . . . . . . . . . . . . . . . . . . . . . . . . . 53 119 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 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 in 126 an automatic fashion to handle the large quantities of devices that 127 are expected in future installations. Messages between devices need 128 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 CoMI and RESTCONF are intended to work in a stateless client-server 142 fashion. They use a single round-trip to complete a single editing 143 transaction, where NETCONF needs up to 10 round trips. 145 To promote small messges, CoMI 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", "MAY", and "OPTIONAL" in this 153 document are to be interpreted as described in [RFC2119]. 155 The following terms are defined in the YANG data modelling language 156 [RFC7950]: action, anydata, anyxml, client, configuration data, 157 container, data model, data node, datastore, identity, instance 158 identifier, key, key leaf, leaf, leaf-list, list, module, RPC, schema 159 node, server, state data, submodule. 161 The following term is defined in [I-D.ietf-core-yang-cbor]: YANG 162 schema item identifier (SID). 164 The following terms are defined in the CoAP protocol [RFC7252]: 165 Confirmable Message, Content-Format. 167 The following terms are defined in this document: 169 data node resource: a CoAP resource that models a YANG data node. 171 datastore resource: a CoAP resource that models a YANG datastore. 173 event stream resource: a CoAP resource used by clients to observe 174 YANG notifications. 176 target resource: the resource that is associated with a particular 177 CoAP request, identified by the request URI. 179 data node instance: An instance of a data node specified in a YANG 180 module and stored in the server. 182 notification instance: An instance of a schema node of type 183 notification, specified in a YANG module implemented by the 184 server. The instance is generated in the server at the occurrence 185 of the corresponding event and reported by an event stream. 187 list instance identifier: Handle used to identify a YANG data node 188 that is an instance of a YANG "list" specified with the values of 189 the key leaves of the list. 191 single instance identifier: Handle used to identify a specific data 192 node which can be instantiated only once. This includes data 193 nodes defined at the root of a YANG module or data nodes defined 194 within a container. This excludes data nodes defined within a 195 list or any children of these data nodes. 197 instance identifier: List instance identifier or single instance 198 identifier. 200 data node value: The value assigned to a data node instance. Data 201 node values are serialized into the payload according to the rules 202 defined in section 4 of [I-D.ietf-core-yang-cbor]. 204 2. CoMI Architecture 206 This section describes the CoMI architecture to use CoAP for reading 207 and modifying the content of datastore(s) used for the management of 208 the instrumented node. 210 +------------------------------------------------------------+ 211 | SMIv2 specification (2) | 212 +------------------------------------------------------------+ 213 | 214 V 215 +------------------------------------------------------------+ 216 | YANG specification (1) | 217 +------------------------------------------------------------+ 218 | | 219 Client V Server V 220 +----------------+ +-------------------+ 221 | Request |--> CoAP request(3) -->| Indication | 222 | Confirm |<-- CoAP response(3)<--| Response (4) | 223 | | | | 224 | |<==== Security (7) ===>|+-----------------+| 225 +----------------+ || Datastore (5) || 226 |+-----------------+| 227 |+-----------------+| 228 || Event stream (6)|| 229 |+-----------------+| 230 +-------------------+ 232 Figure 1: Abstract CoMI architecture 234 Figure 1 is a high-level representation of the main elements of the 235 CoMI management architecture. The different numbered components of 236 Figure 1 are discussed according to component number. 238 (1) YANG specification: contains a set of named and versioned 239 modules. 241 (2) SMIv2 specification: A named module specifies a set of variables 242 and "conceptual tables". There is an algorithm to translate SMIv2 243 specifications to YANG specifications. 245 (3) CoAP request/response messages: The CoMI client sends request 246 messages to and receives response messages from the CoMI server. 248 (4) Request, Indication, Response, Confirm: The processes performed 249 by the CoMI clients and servers. 251 (5) Datastore: A resource used to access configuration data, state 252 data, RPCs and actions. A CoMI server may support multiple 253 datastores to support more complex operations such as 254 configuration rollback, scheduled update. 256 (6) Event stream: An observable resource used to get real time 257 notifications. A CoMI server may support multiple Event streams 258 serving different purposes such as normal monitoring, diagnostic, 259 syslog, security monitoring. 261 (7) Security: The server MUST prevent unauthorized users from 262 reading or writing any CoMI resources. CoMI relies on security 263 protocols such as DTLS [RFC6347] to secure CoAP communication. 265 2.1. Major differences between RESTCONF and CoMI 267 CoMI is a RESTful protocol for small devices where saving bytes to 268 transport counts. Contrary to RESTCONF, many design decisions are 269 motivated by the saving of bytes. Consequently, CoMI is not a 270 RESTCONF over CoAP protocol, but differs more significantly from 271 RESTCONF. Some major differences are cited below: 273 o CoMI uses CoAP/UDP as transport protocol and CBOR as payload 274 format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as 275 transport protocol and JSON [RFC7159] or XML [XML] as payload 276 formats. 278 o CoMI encodes YANG identifier strings as numbers, where RESTCONF 279 does not. 281 o CoMI uses the methods FETCH and iPATCH, not used by RESTCONF. 282 RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not 283 used by CoMI. 285 o CoMI does not support "insert" query parameter (first, last, 286 before, after) and the "point" query parameter which are supported 287 by RESTCONF. 289 o CoMI does not support the "start-time" and "stop-time" query 290 parameters to retrieve past notifications. 292 o CoMI and RESTCONF also differ in the handling of: 294 * notifications. 296 * default values. 298 2.2. Compression of YANG identifiers 300 In the YANG specification, items are identified with a name string. 301 In order to significantly reduce the size of identifiers used in 302 CoMI, numeric identifiers are used instead of these strings. YANG 303 Schema Item iDentifier (SID) is defined in [I-D.ietf-core-yang-cbor] 304 section 2.1. 306 When used in a URI, SIDs are encoded in based64 using the URL and 307 Filename safe alphabet as defined by [RFC4648] section 5. The last 6 308 bits encoded is always aligned with the least significant 6 bits of 309 the SID represented using an unsigned integer. 'A' characters (value 310 0) at the start of the resulting string are removed. 312 SID in basae64 = URLsafeChar[SID >> 60 & 0x3F] | 313 URLsafeChar[SID >> 54 & 0x3F] | 314 URLsafeChar[SID >> 48 & 0x3F] | 315 URLsafeChar[SID >> 42 & 0x3F] | 316 URLsafeChar[SID >> 36 & 0x3F] | 317 URLsafeChar[SID >> 30 & 0x3F] | 318 URLsafeChar[SID >> 24 & 0x3F] | 319 URLsafeChar[SID >> 18 & 0x3F] | 320 URLsafeChar[SID >> 12 & 0x3F] | 321 URLsafeChar[SID >> 6 & 0x3F] | 322 URLsafeChar[SID & 0x3F] 324 For example, SID 1721 is encoded as follow. 326 URLsafeChar[1721 >> 60 & 0x3F] = URLsafeChar[0] = 'A' 327 URLsafeChar[1721 >> 54 & 0x3F] = URLsafeChar[0] = 'A' 328 URLsafeChar[1721 >> 48 & 0x3F] = URLsafeChar[0] = 'A' 329 URLsafeChar[1721 >> 42 & 0x3F] = URLsafeChar[0] = 'A' 330 URLsafeChar[1721 >> 36 & 0x3F] = URLsafeChar[0] = 'A' 331 URLsafeChar[1721 >> 30 & 0x3F] = URLsafeChar[0] = 'A' 332 URLsafeChar[1721 >> 24 & 0x3F] = URLsafeChar[0] = 'A' 333 URLsafeChar[1721 >> 18 & 0x3F] = URLsafeChar[0] = 'A' 334 URLsafeChar[1721 >> 12 & 0x3F] = URLsafeChar[0] = 'A' 335 URLsafeChar[1721 >> 6 & 0x3F] = URLsafeChar[26] = 'a' 336 URLsafeChar[1721 & 0x3F] = URLsafeChar[57] = '5' 337 The resulting base64 representation of SID 1721 is "a5" 339 2.3. Instance identifier 341 Instance identifiers are used to uniquely identify data node 342 instances within a datastore. This YANG built-in type is defined in 343 [RFC7950] section 9.13. An instance identifier is composed of the 344 data node identifier (i.e. a SID) and for data nodes within list(s) 345 the keys used to index within these list(s). 347 When part of a payload, instance identifiers are encoded in CBOR 348 based on the rules defined in [I-D.ietf-core-yang-cbor] section 349 5.13.1. When part of a URI, the SID is appended to the URI of the 350 targeted datastore, the keys are specified using the 'k' URI-Query as 351 defined in Section 5.1. 353 2.4. CBOR ordered map schematic 355 An ordered map is used as a root container of the application/yang- 356 tree+cbor Content-Format. This datatype share the same 357 functionalities as a CBOR map without the following limitations: 359 o The ordering of the pairs of data items is preserved from 360 serialization to deserialization. 362 o Duplicate keys are allowed 364 This schematic is constructed using a CBOR array comprising pairs of 365 data items, each pair consisting of a key that is immediately 366 followed by a value. Unlike a CBOR map for which the length denotes 367 the number of pairs, the length of the ordered map denotes the number 368 of items (i.e. number of keys plus number of values). 370 The use of this schematic can be inferred from its context or by the 371 presence of a preceding tag. The tag assigned to the Ordered map is 372 defined in Section 11.4. 374 In the case of CoMI, the use of the ordered map as the root container 375 of the application/yang-tree+cbor Content-Format is inferred, the 376 Ordered map tag is not used. 378 2.5. Content-Formats 380 ComI uses Content-Formats based on the YANG to CBOR mapping specified 381 in [I-D.ietf-core-yang-cbor]. All Content-Formats defined hereafter 382 are constructed using one or both of these constructs: 384 o YANG data node value, encoded based on the rules defined in 385 [I-D.ietf-core-yang-cbor] section 4. 387 o YANG instance identifier, encoded based on the rules defined in 388 [I-D.ietf-core-yang-cbor] section 5.13.1. 390 The following Content-formats are defined: 392 application/yang-value+cbor: represents a CBOR YANG document 393 containing one YANG data node value. The YANG data node instance 394 can be a leaf, a container, a list, a list instance, a RPC input, 395 a RPC output, an action input, an action output, a leaf-list, an 396 anydata or an anyxml. The CBOR encoding for each of these YANG 397 data node instances are defined in [I-D.ietf-core-yang-cbor] 398 section 4. 400 FORMAT: data-node-value 402 DELTA ENCODING: SIDs included in a YANG container, a list 403 instance, a RPC input, a RPC output, an action input, an actions 404 output and an anydata are encoded using a delta value equal to the 405 SID of the current schema node minus the SID of the parent. The 406 parent SID of root data nodes is defined by the URI carried in the 407 associated request (i.e. GET, PUT, POST). 409 application/yang-values+cbor: represents a YANG document containing 410 a list of data node values. 412 FORMAT: CBOR array of data-node-value 414 DELTA ENCODING: SIDs included in a YANG container, a list instance 415 and an anydata are encoded using a delta value equal to the SID of 416 the current schema node minus the SID of the parent. The parent 417 SID of root data nodes is defined by the corresponding instance- 418 identifier carried in the FETCH request. 420 application/yang-tree+cbor: represents a CBOR YANG document 421 containing a YANG data tree. 423 FORMAT: ordered map of single-instance-identifier, data-node-value 425 DELTA ENCODING: The SID part of the first instance-identifier 426 within the ordered map is encoded using its absolute value. 427 Subsequent instance-identifiers are encoded using a delta value 428 equal to the SID of the current instance-identifiers minus the SID 429 of the previous instance-identifier. 431 application/yang-selectors+cbor: represents a CBOR YANG document 432 containing a list of data node selectors (i.e. instance 433 identifier). 435 FORMAT: CBOR array of instance-identifier 437 DELTA ENCODING: The SID part of the first instance-identifier 438 within the CBOR array is encoded using its absolute value. 439 Subsequent instance-identifiers are encoded using a delta value 440 equal to the SID of the current instance-identifiers minus the SID 441 of the previous instance-identifier. 443 application/yang-patch+cbor: represents a CBOR YANG document 444 containing a list of data nodes to be replaced, created, or 445 deleted. 447 For each data node instance, D, for which the instance identifier 448 is the same as for a data node instance, I, in the targeted 449 resource: the data node value of D replaces the data node value of 450 I. When the data node value of D is null, the data node instance 451 I is removed. When the targeted resource does not contain a data 452 node instance with the same instance identifier as D, a new data 453 node instance is created in the targeted resource with the same 454 instance identifier and data node value as D. 456 FORMAT: ordered map of instance-identifier, data-node-value 458 DELTA ENCODING: Same as Content-Format application/yang-tree+cbor 460 The different Content-formats usage is summarized in the table below: 462 +----------------+--------------+----------------------------------+ 463 | Method | Resource | Content-Format | 464 +----------------+--------------+----------------------------------+ 465 | GET response | data node | /application/yang-value+cbor | 466 | | | | 467 | PUT request | data node | /application/yang-value+cbor | 468 | | | | 469 | POST request | data node | /application/yang-value+cbor | 470 | | | | 471 | DELETE | data node | n/a | 472 | | | | 473 | GET response | datastore | /application/yang-tree+cbor | 474 | | | | 475 | PUT request | datastore | /application/yang-tree+cbor | 476 | | | | 477 | POST request | datastore | /application/yang-tree+cbor | 478 | | | | 479 | FETCH request | datastore | /application/yang-selectors+cbor | 480 | | | | 481 | FETCH response | datastore | /application/yang-values+cbor | 482 | | | | 483 | iPATCH request | datastore | /application/yang-patch+cbor | 484 | | | | 485 | GET response | event stream | /application/yang-tree+cbor | 486 | | | | 487 | POST request | rpc, action | /application/yang-value+cbor | 488 | | | | 489 | POST response | rpc, action | /application/yang-value+cbor | 490 +----------------+--------------+----------------------------------+ 492 3. Example syntax 494 This section presents the notation used for the examples. The YANG 495 modules that are used throughout this document are shown in 496 Appendix C. The example modules are copied from existing modules and 497 annotated with SIDs. The values of the SIDs are taken over from 498 [yang-cbor]. 500 CBOR is used to encode CoMI request and response payloads. The CBOR 501 syntax of the YANG payloads is specified in [RFC7049]. The payload 502 examples are notated in Diagnostic notation (defined in section 6 of 503 [RFC7049]) that can be automatically converted to CBOR. 505 SIDs in URIs are represented as a base64 number, SIDs in the payload 506 are represented as decimal numbers. 508 4. CoAP Interface 510 The format of the links is specified in [I-D.ietf-core-interfaces]. 511 This note specifies a Management Collection Interface. CoMI end- 512 points that implement the CoMI management protocol, support at least 513 one discoverable management resource of resource type (rt): 514 core.c.datastore, with example path: /c, where c is short-hand for 515 CoMI. The path /c is recommended but not compulsory (see Section 8). 517 Three CoMI resources are accessible with the following three example 518 paths: 520 /c: Datastore resource with path "/c" and using CBOR content 521 encoding format. Sub-resouces of format /c/instance-identifier 522 may be available to access directly each data node resource for 523 this datastore. 525 /mod.uri: URI identifying the location of the YANG module library 526 used by this server, with path "/mod.uri" and Content-Format 527 "text/plain; charset=utf-8". An ETag MUST be maintained for this 528 resource by the server, which MUST be changed to a new value when 529 the set of YANG modules in use by the server changes. 531 /s: Event stream resource to which YANG notification instances are 532 reported. Notification support is optional, so this resource will 533 not exist if the server does not support any notifications. 535 The mapping of YANG data node instances to CoMI resources is as 536 follows. Every data node of the YANG modules loaded in the CoMI 537 server represents a sub-resource of the datastore resource (e.g. /c/ 538 instance-identifier). 540 When multiple instances of a list exist, instance selection is 541 possible as described in Section 5.1, Section 5.2.4, and 542 Section 5.2.3.1. 544 The description of the management collection interface, with 545 if=core.c, is shown in the table below, following the guidelines of 546 [I-D.ietf-core-interfaces]: 548 +---------------------+------------------------+--------------------+ 549 | Function | Recommended path | rt | 550 +---------------------+------------------------+--------------------+ 551 | Datastore | /c | core.c.datastore | 552 | | | | 553 | Data node | /c/instance-identifier | core.c.datanode | 554 | | | | 555 | YANG module library | /mod.uri | core.c.moduri | 556 | | | | 557 | Event steam | /s | core.c.eventstream | 558 +---------------------+------------------------+--------------------+ 560 The path values are example values. On discovery, the server makes 561 the actual path values known for these four resources. 563 5. CoMI Collection Interface 565 The CoMI Collection Interface provides a CoAP interface to manage 566 YANG servers. 568 The methods used by CoMI are: 570 +-----------+-------------------------------------------------------+ 571 | Operation | Description | 572 +-----------+-------------------------------------------------------+ 573 | GET | Retrieve the datastore resource or a data node | 574 | | resource | 575 | | | 576 | FETCH | Retrieve specific data nodes within a datastore | 577 | | resource | 578 | | | 579 | POST | Create a datastore resource or a data node resource, | 580 | | invoke an RPC or action | 581 | | | 582 | PUT | Create or replace a datastore resource or a data node | 583 | | resource | 584 | | | 585 | iPATCH | Idem-potently create, replace, and delete data node | 586 | | resource(s) within a datastore resource | 587 | | | 588 | DELETE | Delete a datastore resource or a data node resource | 589 +-----------+-------------------------------------------------------+ 591 There is one Uri-Query option for the GET, PUT, POST, and DELETE 592 methods. 594 +------------------+----------------------------------------+ 595 | Uri-Query option | Description | 596 +------------------+----------------------------------------+ 597 | k | Select an instance within YANG list(s) | 598 +------------------+----------------------------------------+ 600 This parameter is not used for FETCH and iPATCH, because their 601 request payloads support list instance selection. 603 5.1. Using the 'k' Uri-Query option 605 The "k" (key) parameter specifies a specific instance of a data node. 606 The SID in the URI is followed by the (?k=key1, key2,..). Where SID 607 identifies a data node, and key1, key2 are the values of the key 608 leaves that specify an instance. Lists can have multiple keys, and 609 lists can be part of lists. The order of key value generation is 610 given recursively by: 612 o For a given list, if a parent data node is a list, generate the 613 keys for the parent list first. 615 o For a given list, generate key values in the order specified in 616 the YANG module. 618 Key values are encoded using the rules defined in the following 619 table. 621 +-----------------------------+--------------------------------+ 622 | YANG datatype | Uri-Query text content | 623 +-----------------------------+--------------------------------+ 624 | uint8,uint16,unit32, uint64 | int2str(key) | 625 | | | 626 | int8, int16,int32, int64 | urlSafeBase64(CBORencode(key)) | 627 | | | 628 | decimal64 | urlSafeBase64(CBOR key) | 629 | | | 630 | string | key | 631 | | | 632 | boolean | "0" or "1" | 633 | | | 634 | enumeration | int2str(key) | 635 | | | 636 | bits | urlSafeBase64(CBORencode(key)) | 637 | | | 638 | binary | urlSafeBase64(key) | 639 | | | 640 | identityref | int2str(key) | 641 | | | 642 | union | urlSafeBase64(CBORencode(key)) | 643 | | | 644 | instance-identifier | urlSafeBase64(CBORencode(key)) | 645 +-----------------------------+--------------------------------+ 647 In this table: 649 o The method int2str() is used to convert an integer value to a 650 string. For example, int2str(0x0123) return the string "291". 652 o The method urlSafeBase64() is used to convert a binary string to 653 base64 using the URL and Filename safe alphabet as defined by 654 [RFC4648] section 5. For example, urlSafeBase64(\xF9\x56\xA1\x3C) 655 return the string "-VahPA". 657 o The method CBORencode() is used to convert a YANG value to CBOR as 658 specified in [I-D.ietf-core-yang-cbor] section 5, item 8. 660 The resulting key string is encoded in a Uri-Query as specified in 661 [RFC7252] section 6.5. 663 5.2. Data Retrieval 665 One or more data nodes can be retrieved by the client. The operation 666 is mapped to the GET method defined in section 5.8.1 of [RFC7252] and 667 to the FETCH method defined in section 2 of [RFC8132]. 669 It is possible that the size of the payload is too large to fit in a 670 single message. In the case that management data is bigger than the 671 maximum supported payload size, the Block mechanism from [RFC7959] 672 may be used, as explained in more detail in Section 7. 674 There are two additional Uri-Query options for the GET and FETCH 675 methods. 677 +-------------+-----------------------------------------------------+ 678 | Uri-Query | Description | 679 | option | | 680 +-------------+-----------------------------------------------------+ 681 | c | Control selection of configuration and non- | 682 | | configuration data nodes (GET and FETCH) | 683 | | | 684 | d | Control retrieval of default values. | 685 +-------------+-----------------------------------------------------+ 687 5.2.1. Using the 'c' Uri-Query option 689 The 'c' (content) parameter controls how descendant nodes of the 690 requested data nodes will be processed in the reply. 692 The allowed values are: 694 +-------+-----------------------------------------------------+ 695 | Value | Description | 696 +-------+-----------------------------------------------------+ 697 | c | Return only configuration descendant data nodes | 698 | | | 699 | n | Return only non-configuration descendant data nodes | 700 | | | 701 | a | Return all descendant data nodes | 702 +-------+-----------------------------------------------------+ 704 This parameter is only allowed for GET and FETCH methods on datastore 705 and data node resources. A 4.02 (Bad Option) error is returned if 706 used for other methods or resource types. 708 If this Uri-Query option is not present, the default value is "a". 710 5.2.2. Using the 'd' Uri-Query option 712 The "d" (with-defaults) parameter controls how the default values of 713 the descendant nodes of the requested data nodes will be processed. 715 The allowed values are: 717 +-------+-----------------------------------------------------------+ 718 | Value | Description | 719 +-------+-----------------------------------------------------------+ 720 | a | All data nodes are reported. Defined as 'report-all' in | 721 | | section 3.1 of [RFC6243]. | 722 | | | 723 | t | Data nodes set to the YANG default are not reported. | 724 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 725 +-------+-----------------------------------------------------------+ 727 If the target of a GET or FETCH method is a data node that represents 728 a leaf that has a default value, and the leaf has not been given a 729 value by any client yet, the server MUST return the default value of 730 the leaf. 732 If the target of a GET method is a data node that represents a 733 container or list that has child resources with default values, and 734 these have not been given value yet, 736 The server MUST not return the child resource if d= 't' 738 The server MUST return the child resource if d= 'a'. 740 If this Uri-Query option is not present, the default value is 't'. 742 5.2.3. GET 744 A request to read the values of a data node instance is sent with a 745 confirmable CoAP GET message. An instance identifier is specified in 746 the URI path prefixed with the example path /c. 748 FORMAT: 749 GET /c/instance-identifier 751 2.05 Content (Content-Format: application/yang-value+cbor) 752 data-node-value 754 The returned payload contains the CBOR encoding of the specified data 755 node instance value. 757 5.2.3.1. GET Examples 759 Using for example the current-datetime leaf from Appendix C.1, a 760 request is sent to retrieve the value of system-state/clock/current- 761 datetime specified in container system-state. The SID of system- 762 state/clock/current-datetime is 1723, encoded in octal 3273, yields 763 two 6 bit decimal numbers 32 and 73, encoded in base64, (according to 764 table 2 of [RFC4648]) yields a7. The response to the request returns 765 the CBOR encoding of this leaf of type 'string' as defined in 766 [I-D.ietf-core-yang-cbor] section 5.4. 768 REQ: GET example.com/c/a3 770 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 771 "2014-10-26T12:16:31Z" 773 The next example represents the retrieval of a YANG container. In 774 this case, the CoMI client performs a GET request on the clock 775 container (SID = 1721; base64: a5). The container returned is 776 encoded using a CBOR map as specified by [I-D.ietf-core-yang-cbor] 777 section 4.2. 779 REQ: GET example.com/c/a5 781 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 782 { 783 +2 : "2014-10-26T12:16:51Z", / current-datetime SID 1723 / 784 +1 : "2014-10-21T03:00:00Z" / boot-datetime SID 1722 / 785 } 787 This example shows the retrieval of the /interfaces/interface YANG 788 list accessed using SID 1533 (base64: X9). The return payload is 789 encoded using a CBOR array as specified by [I-D.ietf-core-yang-cbor] 790 section 4.4.1 containing 2 instances. 792 REQ: GET example.com/c/X9 794 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 795 [ 796 { 797 +4 : "eth0", / name (SID 1537) / 798 +1 : "Ethernet adaptor", / description (SID 1534) / 799 +5 : 1880, / type, (SID 1538) identity / 800 / ethernetCsmacd (SID 1880) / 801 +2 : true / enabled ( SID 1535) / 802 }, 803 { 804 +4 : "eth1", / name (SID 1537) / 805 +1 : "Ethernet adaptor", / description (SID 1534) / 806 +5 : 1880, / type, (SID 1538) identity / 807 / ethernetCsmacd (SID 1880) / 808 +2 : false / enabled / 809 } 810 ] 811 It is equally possible to select a leaf of a specific instance of a 812 list. The example below requests the description leaf (SID=1534, 813 base64: X-) within the interface list corresponding to the list key 814 "eth0". The returned value is encoded in CBOR based on the rules 815 specified by [I-D.ietf-core-yang-cbor] section 5.4. 817 REQ: GET example.com/c/X-?k="eth0" 819 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 820 "Ethernet adaptor" 822 5.2.4. FETCH 824 The FETCH is used to retrieve multiple data node values. The FETCH 825 request payload contains a list of instance-identifier encoded based 826 on the rules defined by Content-Format application/yang- 827 selectors+cbor in Section 2.5. The return response payload contains 828 a list of values encoded based on the rules defined by Content-Format 829 application/yang-values+cbor in Section 2.5. A value MUST be 830 returned for each instance-identifier specified in the request. A 831 CBOR null is returned for each data node requested by the client, not 832 supported by the server or not currently instantiated. 834 FORMAT: 835 FETCH /c (Content-Format :application/yang-selectors+cbor) 836 CBOR array of instance-identifier 838 2.05 Content (Content-Format: application/yang-values+cbor) 839 CBOR array of data-node-value 841 5.2.4.1. FETCH examples 843 The example uses the current-datetime leaf and the interface list 844 from Appendix C.1. In the following example the value of current- 845 datetime (SID 1723 and the interface list (SID 1533) instance 846 identified with name="eth0" are queried. 848 REQ: FETCH /c (Content-Format :application/yang-selectors+cbor) 849 [ 850 1723, / current-datetime SID 1723 / 851 [-190, "eth0"] / interface SID 1533 with name = "eth0" / 852 ] 854 RES: 2.05 Content (Content-Format :application/yang-value+cbor) 855 [ 856 "2014-10-26T12:16:31Z", / current-datetime (SID 1723) / 857 { 858 +4 : "eth0", / name (SID 1537) / 859 +1 : "Ethernet adaptor", / description (SID 1534) / 860 +5 : 1880, / type (SID 1538), identity / 861 / ethernetCsmacd (SID 1880) / 862 +2 : true / enabled (SID 1535) / 863 } 864 ] 866 5.3. Data Editing 868 CoMI allows datastore contents to be created, modified and deleted 869 using CoAP methods. 871 5.3.1. Data Ordering 873 A CoMI server SHOULD preserve the relative order of all user-ordered 874 list and leaf-list entries that are received in a single edit 875 request. These YANG data node types are encoded as CBOR arrays so 876 messages will preserve their order. 878 5.3.2. POST 880 The CoAP POST operation is used in CoMI for creation of data node 881 resources and the invocation of "ACTION" and "RPC" resources. Refer 882 to Section 5.6 for details on "ACTION" and "RPC" resources. 884 A request to create a data node resource is sent with a confirmable 885 CoAP POST message. The URI specifies the data node to be 886 instantiated at the exception of list intances. In this case, for 887 compactness, the URI specifies the list for which an instance is 888 created. 890 FORMAT: 891 POST /c/ 892 (Content-Format :application/yang-value+cbor) 893 data-node-value 895 2.01 Created 897 If the data node resource already exists, then the POST request MUST 898 fail and a "4.09 Conflict" response code MUST be returned 900 5.3.2.1. Post example 902 The example uses the interface list from Appendix C.1. Example is 903 creating a new list instance within the interface list (SID = 1533): 905 REQ: POST /c/X9 (Content-Format :application/yang-value+cbor) 906 { 907 +4 : "eth5", / name (SID 1537) / 908 +1 : "Ethernet adaptor", / description (SID 1534) / 909 +5 : 1880, / type (SID 1538), identity / 910 / ethernetCsmacd (SID 1880) / 911 +2 : true / enabled (SID 1535) / 912 } 914 RES: 2.01 Created 916 5.3.3. PUT 918 A data node resource instance is created or replaced with the PUT 919 method. A request to set the value of a data node instance is sent 920 with a confirmable CoAP PUT message. 922 FORMAT: 923 PUT /c/ 924 (Content-Format :application/yang-value+cbor) 925 data-node-value 927 2.01 Created 929 5.3.3.1. PUT example 931 The example uses the interface list from Appendix C.1. Example is 932 renewing an instance of the list interface (SID = 1533) with key 933 name="eth0": 935 REQ: PUT /c/X9?k="eth0" 936 (Content-Format :application/yang-value+cbor) 937 { 938 +4 : "eth0", / name (SID 1537) / 939 +1 : "Ethernet adaptor", / description (SID 1534) / 940 +5 : 1880, / type (SID 1538), identity / 941 / ethernetCsmacd (SID 1880) / 942 +2 : true / enabled (SID 1535) / 943 } 945 RES: 2.04 Changed 947 5.3.4. iPATCH 949 One or multiple data node instances are replaced with the idempotent 950 iPATCH method [RFC8132]. A request is sent with a confirmable CoAP 951 iPATCH message. 953 There are no Uri-Query options for the iPATCH method. 955 The processing of the iPATCH command is specified by Content-Format 956 application/yang-patch+cbor. In summary, if the CBOR patch payload 957 contains a data node instance that is not present in the target, this 958 instance is added. If the target contains the specified instance, 959 the content of this instance is replaced with the value of the 960 payload. A null value indicates the removal of an existing data node 961 instance. 963 FORMAT: 964 iPATCH /c (Content-Format :application/yang-patch+cbor) 965 ordered map of instance-identifier, data-node-value 967 2.04 Changed 969 5.3.4.1. iPATCH example 971 In this example, a CoMI client requests the following operations: 973 o Set "/system/ntp/enabled" (SID 1755) to true. 975 o Remove the server "tac.nrc.ca" from the"/system/ntp/server" (SID 976 1756) list. 978 o Add the server "NTP Pool server 2" to the list "/system/ntp/ 979 server" (SID 1756). 981 REQ: iPATCH /c (Content-Format :application/yang-patch+cbor) 982 [ 983 1751 , true, / enabled (1755) / 984 [+1, "tac.nrc.ca"], null, / server (SID 1756) / 985 +0, / server (SID 1756) / 986 { 987 +3 : "tic.nrc.ca", / name (SID 1759) / 988 +4 : true, / prefer (SID 1760) / 989 +5 : { / udp (SID 1761) / 990 +1 : "132.246.11.231" / address (SID 1762) / 991 } 992 } 993 ] 995 RES: 2.04 Changed 997 5.3.5. DELETE 999 A data node resource is deleted with the DELETE method. 1001 FORMAT: 1002 Delete /c/ 1004 2.02 Deleted 1006 5.3.5.1. DELETE example 1008 The example uses the interface list from Appendix C.3. Example is 1009 deleting an instance of the interface list (SID = 1533): 1011 REQ: DELETE /c/X9?k="eth0" 1013 RES: 2.02 Deleted 1015 5.4. Full datastore access 1017 The methods GET, PUT, POST, and DELETE can be used to request, 1018 replace, create, and delete a whole datastore respectively. 1020 FORMAT: 1021 GET /c 1023 2.05 Content (Content-Format: application/yang-tree+cbor) 1024 ordered map of single-instance-identifier, data-node-value 1026 FORMAT: 1027 PUT /c (Content-Format: application/yang-tree+cbor) 1028 ordered map of single-instance-identifier, data-node-value 1030 2.04 Changed 1032 FORMAT: 1033 POST /c (Content-Format: application/yang-tree+cbor) 1034 ordered map of single-instance-identifier, data-node-value 1036 2.01 Created 1038 FORMAT: 1039 DELETE /c 1041 2.02 Deleted 1043 The content of the ordered map represents the complete datastore of 1044 the server at the GET indication of after a successful processing of 1045 a PUT or POST request. When an Ordered map is used to carry a whole 1046 datastore, all data nodes MUST be identified using single instance 1047 identifiers (i.e. a SID), list instance identifiers are not allowed. 1049 5.4.1. Full datastore examples 1051 The example uses the interface list and the clock container from 1052 Appendix C.3. Assume that the datastore contains two modules ietf- 1053 system (SID 1700) and ietf-interfaces (SID 1500); they contain the 1054 list interface (SID 1533) with one instance and the container Clock 1055 (SID 1721). After invocation of GET, a map with these two modules is 1056 returned: 1058 REQ: GET /c 1060 RES: 2.05 Content (Content-Format :application/yang-tree+cbor) 1061 [ 1062 1721, / Clock (SID 1721) / 1063 { 1064 +2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) / 1065 +1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) / 1066 }, 1067 -188, / clock (SID 1533) / 1068 { 1069 +4 : "eth0", / name (SID 1537) / 1070 +1 : "Ethernet adaptor", / description (SID 1534) / 1071 +5 : 1880, / type (SID 1538), identity: / 1072 / ethernetCsmacd (SID 1880) / 1073 +2 : true / enabled (SID 1535) / 1074 } 1075 ] 1077 5.5. Event stream 1079 Event notification is an essential function for the management of 1080 servers. CoMI allows notifications specified in YANG [RFC5277] to be 1081 reported to a list of clients. The recommended path of the default 1082 event stream is /s. The server MAY support additional event stream 1083 resources to address different notification needs. 1085 Reception of notification instances is enabled with the CoAP Observe 1086 [RFC7641] function. Clients subscribe to the notifications by 1087 sending a GET request with an "Observe" option, specifying the /s 1088 resource when the default stream is selected. 1090 Each response payload carries one or multiple notifications. The 1091 number of notification reported and the conditions used to remove 1092 notifications from the reported list is left to the implementers. 1093 When multiple notifications are reported, they MUST be ordered 1094 starting from the newest notification at index zero. 1096 An example implementation is: 1098 Every time an event is generated, the generated notification 1099 instance is appended to the chosen stream(s). After appending the 1100 instance, the content of the instance is sent to all clients 1101 observing the modified stream. 1103 Dependending on the storage space allocated to the notification 1104 stream, the oldest notifications that do not fit inside the 1105 notification stream storage space are removed. 1107 FORMAT: 1108 Get / Observe(0) 1110 2.05 Content (Content-Format :application/yang-tree+cbor) 1111 ordered map of instance-identifier, data-node-value 1113 The array of data node instances may contain identical entries which 1114 have been generated at different times. 1116 5.5.1. Notify Examples 1118 Suppose the server generates the event specified in Appendix C.4. By 1119 executing a GET on the /s resource the client receives the following 1120 response: 1122 REQ: GET /s Observe(0) Token(0x93) 1124 RES: 2.05 Content (Content-Format :application/yang-tree+cbor) 1125 Observe(12) Token(0x93) 1126 [ 1127 60010, / example-port-fault (SID 60010) / 1128 { 1129 +1 : "0/4/21", / port-name (SID 60011) / 1130 +2 : "Open pin 2" / port-fault (SID 60012) / 1131 }, 1132 +0, / example-port-fault (SID 60010) / 1133 { 1134 +1 : "1/4/21", / port-name (SID 60011) / 1135 +2 : "Open pin 5" / port-fault (SID 60012) / 1136 } 1137 ] 1139 In the example, the request returns a success response with the 1140 contents of the last two generated events. Consecutively the server 1141 will regularly notify the client when a new event is generated. 1143 To check that the client is still alive, the server MUST send 1144 confirmable notifications periodically. When the client does not 1145 confirm the notification from the server, the server will remove the 1146 client from the list of observers [RFC7641]. 1148 5.6. RPC statements 1150 The YANG "action" and "RPC" statements specify the execution of a 1151 Remote procedure Call (RPC) in the server. It is invoked using a 1152 POST method to an "Action" or "RPC" resource instance. The request 1153 payload contains the values assigned to the input container when 1154 specified. The response payload contains the values of the output 1155 container when specified. Both the input and output containers are 1156 encoded in CBOR using the rules defined in [I-D.ietf-core-yang-cbor] 1157 section 4.2.1. Root data nodes are encoded using the delta between 1158 the current SID and the SID of the invoked instance identifier a 1159 specified by the URI. 1161 The returned success response code is 2.05 Content. 1163 FORMAT: 1164 POST /c/ 1165 (Content-Format :application/yang-value+cbor) 1166 data-node-value 1168 2.05 Content (Content-Format :application/yang-value+cbor) 1169 data-node-value 1171 5.6.1. RPC Example 1173 The example is based on the YANG action specification of 1174 Appendix C.2. A server list is specified and the action "reset" (SID 1175 60002, base64: Opq), that is part of a "server instance" with key 1176 value "myserver", is invoked. 1178 REQ: POST /c/Opq?k="myserver" 1179 (Content-Format :application/yang-value+cbor) 1180 { 1181 +1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / 1182 } 1184 RES: 2.05 Content (Content-Format :application/yang-value+cbor) 1185 { 1186 +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ 1187 } 1189 6. Access to MIB Data 1191 Appendix C.5 shows a YANG module mapped from the SMI specification 1192 "IP-MIB" [RFC4293]. The following example shows the 1193 "ipNetToPhysicalEntry" list with 2 instances, using diagnostic 1194 notation without delta encoding. 1196 { 1197 60021 : / list ipNetToPhysicalEntry / 1198 [ 1199 { 1200 60022 : 1, / ipNetToPhysicalIfIndex / 1201 60023 : 1, / ipNetToPhysicalNetAddressType / 1202 60024 : h'0A000033', / ipNetToPhysicalNetAddress / 1203 60025 : h'00000A01172D',/ ipNetToPhysicalPhysAddress / 1204 60026 : 2333943, / ipNetToPhysicalLastUpdated / 1205 60027 : 4, / ipNetToPhysicalType / 1206 60028 : 1, / ipNetToPhysicalState / 1207 60029 : 1 / ipNetToPhysicalRowStatus / 1208 }, 1209 { 1210 60022 : 1, / ipNetToPhysicalIfIndex / 1211 60023 : 1, / ipNetToPhysicalNetAddressType / 1212 60024 : h'09020304', / ipNetToPhysicalNetAddress / 1213 60025 : h'00000A36200A',/ ipNetToPhysicalPhysAddress / 1214 60026 : 2329836, / ipNetToPhysicalLastUpdated / 1215 60027 : 3, / ipNetToPhysicalType / 1216 60028 : 6, / ipNetToPhysicalState / 1217 60029 : 1 / ipNetToPhysicalRowStatus / 1218 } 1219 ] 1220 } 1222 In this example one instance of /ip/ipNetToPhysicalEntry (SID 60021, 1223 base64: Oz1) that matches the keys ipNetToPhysicalIfIndex = 1, 1224 ipNetToPhysicalNetAddressType = ipv4 and ipNetToPhysicalNetAddress = 1225 9.2.3.4 (h'09020304', base64: CQIDBA) is requested. 1227 REQ: GET example.com/c/Oz1?k="1,1,CQIDBA" 1229 RES: 2.05 Content (Content-Format: application/yang-value+cbor) 1230 { 1231 +1 : 1, / ( SID 60022 ) / 1232 +2 : 1, / ( SID 60023 ) / 1233 +3 : h'09020304', / ( SID 60024 ) / 1234 +4 : h'00000A36200A', / ( SID 60025 ) / 1235 +5 : 2329836, / ( SID 60026 ) / 1236 +6 : 3, / ( SID 60027 ) / 1237 +7 : 6, / ( SID 60028 ) / 1238 +8 : 1 / ( SID 60029 ) / 1239 } 1241 7. Use of Block 1243 The CoAP protocol provides reliability by acknowledging the UDP 1244 datagrams. However, when large pieces of data need to be 1245 transported, datagrams get fragmented, thus creating constraints on 1246 the resources in the client, server and intermediate routers. The 1247 block option [RFC7959] allows the transport of the total payload in 1248 individual blocks of which the size can be adapted to the underlying 1249 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1250 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1251 acknowledged to guarantee reliability. 1253 Notice that the Block mechanism splits the data at fixed positions, 1254 such that individual data fields may become fragmented. Therefore, 1255 assembly of multiple blocks may be required to process the complete 1256 data field. 1258 Beware of race conditions. Blocks are filled one at a time and care 1259 should be taken that the whole data representation is sent in 1260 multiple blocks sequentially without interruption. On the server, 1261 values are changed, lists are re-ordered, extended or reduced. When 1262 these actions happen during the serialization of the contents of the 1263 resource, the transported results do not correspond with a state 1264 having occurred in the server; or worse the returned values are 1265 inconsistent. For example: array length does not correspond with the 1266 actual number of items. It may be advisable to use CBOR maps or CBOR 1267 arrays of undefined length, which are foreseen for data streaming 1268 purposes. 1270 8. Resource Discovery 1272 The presence and location of (path to) the management data are 1273 discovered by sending a GET request to "/.well-known/core" including 1274 a resource type (RT) parameter with the value "core.c.datastore" 1275 [RFC6690]. Upon success, the return payload will contain the root 1276 resource of the management data. It is up to the implementation to 1277 choose its root resource, the value "/c" is used as an example. The 1278 example below shows the discovery of the presence and location of 1279 management data. 1281 REQ: GET /.well-known/core?rt=core.c.datastore 1283 RES: 2.05 Content 1284 ; rt="core.c.datastore" 1286 Implemented data nodes MAY be discovered using the standard CoAP 1287 resource discovery. The implementation can add the data node 1288 identifiers (SID) supported to /.well-known/core with 1289 rt="core.c.datanode". The available SIDs can be discovered by 1290 sending a GET request to "/.well-known/core" including a resource 1291 type (rt) parameter with the value "core.c.datanode". Upon success, 1292 the return payload will contain the registered SIDs and their 1293 location. 1295 The example below shows the discovery of the presence and location of 1296 data nodes. 1298 REQ: GET /.well-known/core?rt=core.c.datanode 1300 RES: 2.05 Content 1301 ; rt="core.c.datanode", 1302 ; rt="core.c.datanode" 1304 The list of data nodes may become prohibitively long. Therefore, it 1305 is recommended to discover the details about the YANG modules 1306 implemented by reading a YANG module library (e.g. "ietf-comi-yang- 1307 library" ad defined by [I-D.veillette-core-yang-library]). 1309 The resource "/mod.uri" is used to retrieve the location of the YANG 1310 module library. This library can be stored locally on each server, 1311 or remotely on a different server. The latter is advised when the 1312 deployment of many servers are identical. 1314 The following example shows the URI of a local instance of container 1315 modules-state (SID=1802) as defined in 1316 [I-D.veillette-core-yang-library]. 1318 REQ: GET example.com/mod.uri 1320 RES: 2.05 Content (Content-Format: text/plain; charset=utf-8) 1321 example.com/c/cK 1323 The following example shows the URI of a remote instance of same 1324 container. 1326 REQ: GET example.com/mod.uri 1328 RES: 2.05 Content (Content-Format: text/plain; charset=utf-8) 1329 example-remote-server.com/group17/cK 1331 Within the YANG module library all information about the module is 1332 stored such as: module identifier, identifier hierarchy, grouping, 1333 features and revision numbers. 1335 9. Error Handling 1337 In case a request is received which cannot be processed properly, the 1338 CoMI server MUST return an error message. This error message MUST 1339 contain a CoAP 4.xx or 5.xx response code. 1341 Errors returned by a CoMI server can be broken into two categories, 1342 those associated to the CoAP protocol itself and those generated 1343 during the validation of the YANG data model constrains as described 1344 in [RFC7950] section 8. 1346 The following list of common CoAP errors should be implemented by 1347 CoMI servers. This list is not exhaustive, other errors defined by 1348 CoAP and associated RFCs may be applicable. 1350 o Error 4.01 (Unauthorized) is returned by the CoMI server when the 1351 CoMI client is not authorized to perform the requested action on 1352 the targeted resource (i.e. data node, datastore, rpc, action or 1353 event stream). 1355 o Error 4.02 (Bad Option) is returned by the CoMI server when one or 1356 more CoAP options are unknown or malformed. 1358 o Error 4.04 (Not Found) is returned by the CoMI server when the 1359 CoMI client is requesting a non-instantiated resource (i.e. data 1360 node, datastore, rpc, action or event stream). 1362 o Error 4.05 (Method Not Allowed) is returned by the CoMI server 1363 when the CoMI client is requesting a method not supported on the 1364 targeted resource. (e.g. GET on an rpc, PUT or POST on a data 1365 node with "config" set to false). 1367 o Error 4.08 (Request Entity Incomplete) is returned by the CoMI 1368 server if one or multiple blocks of a block transfer request is 1369 missing, see [RFC7959] for more details. 1371 o Error 4.13 (Request Entity Too Large) may be returned by the CoMI 1372 server during a block transfer request, see [RFC7959] for more 1373 details. 1375 o Error 4.15 (Unsupported Content-Format) is returned by the CoMI 1376 server when the Content-Format used in the request don't match 1377 those specified in section 2.3. 1379 CoMI server MUST also enforce the different constraints associated to 1380 the YANG data models implemented. These constraints are described in 1381 [RFC7950] section 8. These errors are reported using the CoAP error 1382 code 4.00 (Bad Request) and may have the following error container as 1383 payload. The YANG definition and associated .sid file are available 1384 in Appendix A and Appendix B. The error container is encoded using 1385 delta value equal to the SID of the current schema node minus the SID 1386 of the parent container (i.e 1024). 1388 +--rw error! 1389 +--rw error-tag identityref 1390 +--rw error-app-tag? identityref 1391 +--rw error-data-node? instance-identifier 1392 +--rw error-message? string 1394 The following error-tag and error-app-tag are defined by the ietf- 1395 comi YANG module, these tags are implemented as YANG identity and can 1396 be extended as needed. 1398 o error-tag operation-failed is returned by the CoMI server when the 1399 operation request cannot be processed successfully. 1401 * error-app-tag malformed-message is returned by the CoMI server 1402 when the payload received from the CoMI client don't contain a 1403 well-formed CBOR content as defined in [RFC7049] section 3.3 or 1404 don't comply with the CBOR structure defined within this 1405 document. 1407 * error-app-tag data-not-unique is returned by the CoMI server 1408 when the validation of the 'unique' constraint of a list or 1409 leaf-list fails. 1411 * error-app-tag too-many-elements is returned by the CoMI server 1412 when the validation of the 'max-elements' constraint of a list 1413 or leaf-list fails. 1415 * error-app-tag too-few-elements is returned by the CoMI server 1416 when the validation of the 'min-elements' constraint of a list 1417 or leaf-list fails. 1419 * error-app-tag must-violation is returned by the CoMI server 1420 when the restrictions imposed by a 'must' statement are 1421 violated. 1423 * error-app-tag duplicate is returned by the CoMI server when a 1424 client tries to create a duplicate list or leaf-list entry. 1426 o error-tag invalid-value is returned by the CoMI server when the 1427 CoMI client tries to update or create a leaf with a value encoded 1428 using an invalid CBOR datatype or if the 'range', 'length', 1429 'pattern' or 'require-instance' constrain is not fulfilled. 1431 * error-app-tag invalid-datatype is returned by the CoMI server 1432 when CBOR encoding don't follow the rules set by or when the 1433 value is incompatible with the YANG Built-In type. (e.g. a 1434 value greater than 127 for an int8, undefined enumeration) 1436 * error-app-tag not-in-range is returned by the CoMI server when 1437 the validation of the 'range' property fails. 1439 * error-app-tag invalid-length is returned by the CoMI server 1440 when the validation of the 'length' property fails. 1442 * error-app-tag pattern-test-failed is returned by the CoMI 1443 server when the validation of the 'pattern' property fails. 1445 o error-tag missing-element is returned by the CoMI server when the 1446 operation requested by a CoMI client fail to comply with the 1447 'mandatory' constraint defined. The 'mandatory' constraint is 1448 enforced for leafs and choices, unless the node or any of its 1449 ancestors have a 'when' condition or 'if-feature' expression that 1450 evaluates to 'false'. 1452 * error-app-tag missing-key is returned by the CoMI server to 1453 further qualify an missing-element error. This error is 1454 returned when the CoMI client tries to create or list instance, 1455 without all the 'key' specified or when the CoMI client tries 1456 to delete a leaf listed as a 'key'. 1458 * error-app-tag missing-input-parameter is returned by the CoMI 1459 server when the input parameters of an RPC or action are 1460 incomplete. 1462 o error-tag unknown-element is returned by the CoMI server when the 1463 CoMI client tries to access a data node of a YANG module not 1464 supported, of a data node associated to an 'if-feature' expression 1465 evaluated to 'false' or to a 'when' condition evaluated to 1466 'false'. 1468 o error-tag bad-element is returned by the CoMI server when the CoMI 1469 client tries to create data nodes for more than one case in a 1470 choice. 1472 o error-tag data-missing is returned by the CoMI server when a data 1473 node required to accept the request is not present. 1475 * error-app-tag instance-required is returned by the CoMI server 1476 when a leaf of type 'instance-identifier' or 'leafref' marked 1477 with require-instance set to 'true' refers to an instance that 1478 does not exist. 1480 * error-app-tag missing-choice is returned by the CoMI server 1481 when no nodes exist in a mandatory choice. 1483 o error-tag error is returned by the CoMI server when an unspecified 1484 error has occurred. 1486 For example, the CoMI server might return the following error. 1488 RES: 4.00 Bad Request (Content-Format :application/yang-value+cbor) 1489 { 1490 +4 : 1011, / error-tag (SID 1028) / 1491 / = invalid-value (SID 1011) / 1492 +1 : 1018, / error-app-tag (SID 1025) / 1493 / = not-in-range (SID 1018) / 1494 +2 : 1740, / error-data-node (SID 1026) / 1495 / = timezone-utc-offset (SID 1740) / 1496 +3 : "maximum value exceeded" / error-message (SID 1027) / 1497 } 1499 10. Security Considerations 1501 For secure network management, it is important to restrict access to 1502 configuration variables only to authorized parties. CoMI re-uses the 1503 security mechanisms already available to CoAP, this includes DTLS 1504 [RFC6347] for protected access to resources, as well suitable 1505 authentication and authorization mechanisms. 1507 Among the security decisions that need to be made are selecting 1508 security modes and encryption mechanisms (see [RFC7252]). This 1509 requires a trade-off, as the NoKey mode gives no protection at all, 1510 but is easy to implement, whereas the X.509 mode is quite secure, but 1511 may be too complex for constrained devices. 1513 In addition, mechanisms for authentication and authorization may need 1514 to be selected. 1516 CoMI avoids defining new security mechanisms as much as possible. 1517 However, some adaptations may still be required, to cater for CoMI's 1518 specific requirements. 1520 11. IANA Considerations 1522 11.1. Resource Type (rt=) Link Target Attribute Values Registry 1524 This document adds the following resource type to the "Resource Type 1525 (rt=) Link Target Attribute Values", within the "Constrained RESTful 1526 Environments (CoRE) Parameters" registry. 1528 +--------------------+---------------------+-----------+ 1529 | Value | Description | Reference | 1530 +--------------------+---------------------+-----------+ 1531 | core.c.datastore | YANG datastore | RFC XXXX | 1532 | | | | 1533 | core.c.datanode | YANG data node | RFC XXXX | 1534 | | | | 1535 | core.c.liburi | YANG module library | RFC XXXX | 1536 | | | | 1537 | core.c.eventstream | YANG event stream | RFC XXXX | 1538 +--------------------+---------------------+-----------+ 1540 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1541 note. 1543 11.2. CoAP Content-Formats Registry 1545 This document adds the following Content-Format to the "CoAP Content- 1546 Formats", within the "Constrained RESTful Environments (CoRE) 1547 Parameters" registry. 1549 +---------------------------------+-------------+-----------+ 1550 | Media Type | Excoding ID | Reference | 1551 +---------------------------------+-------------+-----------+ 1552 | application/yang-value+cbor | XXX | RFC XXXX | 1553 | | | | 1554 | application/yang-values+cbor | XXX | RFC XXXX | 1555 | | | | 1556 | application/yang-selectors+cbor | XXX | RFC XXXX | 1557 | | | | 1558 | application/yang-tree+cbor | XXX | RFC XXXX | 1559 | | | | 1560 | application/yang-ipatch+cbor | XXX | RFC XXXX | 1561 +---------------------------------+-------------+-----------+ 1563 // RFC Ed.: replace XXX with assigned IDs and remove this note. // 1564 RFC Ed.: replace RFC XXXX with this RFC number and remove this note. 1566 11.3. Media Types Registry 1568 This document adds the following media types to the "Media Types" 1569 registry. 1571 +---------------------+---------------------------------+-----------+ 1572 | Name | Template | Reference | 1573 +---------------------+---------------------------------+-----------+ 1574 | yang-value+cbor | application/yang-value+cbor | RFC XXXX | 1575 | | | | 1576 | yang-values+cbor | application/yang-values+cbor | RFC XXXX | 1577 | | | | 1578 | yang-selectors+cbor | application/yang-selectors+cbor | RFC XXXX | 1579 | | | | 1580 | yang-tree+cbor | application/yang-tree+cbor | RFC XXXX | 1581 | | | | 1582 | yang-ipatch+cbor | application/yang-ipatch+cbor | RFC XXXX | 1583 +---------------------+---------------------------------+-----------+ 1585 Each of these media types share the following information: 1587 o Subtype name: 1589 o Required parameters: N/A 1591 o Optional parameters: N/A 1593 o Encoding considerations: binary 1595 o Security considerations: See the Security Considerations section 1596 of RFC XXXX 1598 o Interoperability considerations: N/A 1600 o Published specification: RFC XXXX 1602 o Applications that use this media type: CoMI 1604 o Fragment identifier considerations: N/A 1606 o Additional information: 1608 * Deprecated alias names for this type: N/A 1610 * Magic number(s): N/A 1612 * File extension(s): N/A 1614 * Macintosh file type code(s): N/A 1616 o Person & email address to contact for further information: 1617 iesg&ietf.org 1619 o Intended usage: COMMON 1621 o Restrictions on usage: N/A 1623 o Author: Michel Veillette, ietf&augustcellars.com 1625 o Change Controller: IESG 1627 o Provisional registration? No 1629 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1630 note. 1632 11.4. Concise Binary Object Representation (CBOR) Tags Registry 1634 This document adds the following tags to the "Concise Binary Object 1635 Representation (CBOR) Tags" registry. 1637 +-----+-----------+-------------+-----------+ 1638 | Tag | Data Item | Semantics | Reference | 1639 +-----+-----------+-------------+-----------+ 1640 | xxx | array | Oedered map | RFC XXXX | 1641 +-----+-----------+-------------+-----------+ 1643 // RFC Ed.: replace xxx by the assigned Tag and remove this note. // 1644 RFC Ed.: replace RFC XXXX with this RFC number and remove this note. 1646 12. Acknowledgements 1648 We are very grateful to Bert Greevenbosch who was one of the original 1649 authors of the CoMI specification and specified CBOR encoding and use 1650 of hashes. 1652 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1653 transported under SNMP. Carsten Bormann has given feedback on the 1654 use of CBOR. 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 1662 13.1. Normative References 1664 [I-D.ietf-core-sid] 1665 Veillette, M. and A. Pelov, "YANG Schema Item iDentifier 1666 (SID)", draft-ietf-core-sid-02 (work in progress), October 1667 2017. 1669 [I-D.ietf-core-yang-cbor] 1670 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 1671 Minaburo, "CBOR Encoding of Data Modeled with YANG", 1672 draft-ietf-core-yang-cbor-05 (work in progress), August 1673 2017. 1675 [I-D.veillette-core-yang-library] 1676 Veillette, M., "Constrained YANG Module Library", draft- 1677 veillette-core-yang-library-01 (work in progress), July 1678 2017. 1680 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1681 Requirement Levels", BCP 14, RFC 2119, 1682 DOI 10.17487/RFC2119, March 1997, 1683 . 1685 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1686 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1687 . 1689 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1690 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1691 . 1693 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1694 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1695 . 1697 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1698 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1699 October 2013, . 1701 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1702 Application Protocol (CoAP)", RFC 7252, 1703 DOI 10.17487/RFC7252, June 2014, 1704 . 1706 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1707 Application Protocol (CoAP)", RFC 7641, 1708 DOI 10.17487/RFC7641, September 2015, 1709 . 1711 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1712 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1713 . 1715 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1716 the Constrained Application Protocol (CoAP)", RFC 7959, 1717 DOI 10.17487/RFC7959, August 2016, 1718 . 1720 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1721 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1722 . 1724 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1725 FETCH Methods for the Constrained Application Protocol 1726 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1727 . 1729 13.2. Informative References 1731 [I-D.ietf-core-interfaces] 1732 Shelby, Z., Vial, M., Koster, M., Groves, C., Zhu, J., and 1733 B. Silverajan, "Reusable Interface Definitions for 1734 Constrained RESTful Environments", draft-ietf-core- 1735 interfaces-10 (work in progress), September 2017. 1737 [netconfcentral] 1738 YUMAworks, "NETCONF Central: library of YANG modules", 1739 Web http://www.netconfcentral.org/modulelist. 1741 [RFC4293] Routhier, S., Ed., "Management Information Base for the 1742 Internet Protocol (IP)", RFC 4293, DOI 10.17487/RFC4293, 1743 April 2006, . 1745 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1746 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1747 January 2012, . 1749 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1750 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1751 . 1753 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1754 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1755 2014, . 1757 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1758 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1759 . 1761 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1762 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1763 2014, . 1765 [XML] W3C, "Extensible Markup Language (XML)", 1766 Web http://www.w3.org/xml. 1768 [yang-cbor] 1769 Veillette, M., "yang-cbor Registry", Web 1770 https://github.com/core-wg/yang- 1771 cbor/tree/master/registry/. 1773 Appendix A. ietf-comi YANG module 1775 file "ietf-comi@2017-07-01.yang" 1776 module ietf-comi { 1777 yang-version 1.1; 1779 namespace "urn:ietf:params:xml:ns:yang:ietf-comi"; 1780 prefix comi; 1782 organization 1783 "IETF Core Working Group"; 1785 contact 1786 "Michel Veillette 1787 1789 Alexander Pelov 1790 1792 Peter van der Stok 1793 1795 Andy Bierman 1796 "; 1798 description 1799 "This module contains the different definitions required 1800 by the CoMI protocol."; 1802 revision 2017-07-01 { 1803 description 1804 "Initial revision."; 1806 reference 1807 "[I-D.ietf-core-comi] CoAP Management Interface"; 1808 } 1810 typedef sid { 1811 type uint64; 1812 description 1813 "YANG Schema Item iDentifier"; 1814 reference 1815 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 1816 } 1818 typedef date_and_time_b { 1819 type int64; 1820 description 1821 "Binary representation of a date and time. This value is 1822 encoded using a positive or negative value representing 1823 a number of seconds relative to 1970-01-01T00:00Z in UTC 1824 time (i.e. the epoch). Negative values represent a date 1825 and time before the epoch, positive values represent a 1826 date and time after the epoch. 1827 This representation is defined in [RFC 7049] section 1828 2.4.1. When implemented using CoMI, tag 0 is assumed 1829 and not encoded."; 1830 reference 1831 "[RFC 7049] Concise Binary Object Representation (CBOR)"; 1832 } 1834 identity error-tag { 1835 description 1836 "Base identity for error-tag."; 1837 } 1839 identity operation-failed { 1840 base error-tag; 1841 description 1842 "Returned by the CoMI server when the operation request 1843 can't be processed successfully."; 1844 } 1846 identity invalid-value { 1847 base error-tag; 1848 description 1849 "Returned by the CoMI server when the CoMI client tries to 1850 update or create a leaf with a value encoded using an 1851 invalid CBOR datatype or if the 'range', 'length', 1852 'pattern' or 'require-instance' constrain is not 1853 fulfilled."; 1855 } 1857 identity missing-element { 1858 base error-tag; 1859 description 1860 "Returned by the CoMI server when the operation requested 1861 by a CoMI client fails to comply with the 'mandatory' 1862 constraint defined. The 'mandatory' constraint is 1863 enforced for leafs and choices, unless the node or any of 1864 its ancestors have a 'when' condition or 'if-feature' 1865 expression that evaluates to 'false'."; 1866 } 1868 identity unknown-element { 1869 base error-tag; 1870 description 1871 "Returned by the CoMI server when the CoMI client tries to 1872 access a data node of a YANG module not supported, of a 1873 data node associated with an 'if-feature' expression 1874 evaluated to 'false' or to a 'when' condition evaluated 1875 to 'false'."; 1876 } 1878 identity bad-element { 1879 base error-tag; 1880 description 1881 "Returned by the CoMI server when the CoMI client tries to 1882 create data nodes for more than one case in a choice."; 1883 } 1885 identity data-missing { 1886 base error-tag; 1887 description 1888 "Returned by the CoMI server when a data node required to 1889 accept the request is not present."; 1890 } 1892 identity error { 1893 base error-tag; 1894 description 1895 "Returned by the CoMI server when an unspecified error has 1896 occurred."; 1897 } 1899 identity error-app-tag { 1900 description 1901 "Base identity for error-app-tag."; 1902 } 1903 identity malformed-message { 1904 base error-app-tag; 1905 description 1906 "Returned by the CoMI server when the payload received 1907 from the CoMI client don't contain a well-formed CBOR 1908 content as defined in [RFC7049] section 3.3 or don't 1909 comply with the CBOR structure defined within this 1910 document."; 1911 } 1913 identity data-not-unique { 1914 base error-app-tag; 1915 description 1916 "Returned by the CoMI server when the validation of the 1917 'unique' constraint of a list or leaf-list fails."; 1918 } 1920 identity too-many-elements { 1921 base error-app-tag; 1922 description 1923 "Returned by the CoMI server when the validation of the 1924 'max-elements' constraint of a list or leaf-list fails."; 1925 } 1927 identity too-few-elements { 1928 base error-app-tag; 1929 description 1930 "Returned by the CoMI server when the validation of the 1931 'min-elements' constraint of a list or leaf-list fails."; 1932 } 1934 identity must-violation { 1935 base error-app-tag; 1936 description 1937 "Returned by the CoMI server when the restrictions 1938 imposed by a 'must' statement are violated."; 1939 } 1941 identity duplicate { 1942 base error-app-tag; 1943 description 1944 "Returned by the CoMI server when a client tries to create 1945 a duplicate list or leaf-list entry."; 1946 } 1948 identity invalid-datatype { 1949 base error-app-tag; 1950 description 1951 "Returned by the CoMI server when CBOR encoding is 1952 incorect or when the value encoded is incompatible with 1953 the YANG Built-In type. (e.g. value greater than 127 1954 for an int8, undefined enumeration)."; 1955 } 1957 identity not-in-range { 1958 base error-app-tag; 1959 description 1960 "Returned by the CoMI server when the validation of the 1961 'range' property fails."; 1962 } 1964 identity invalid-length { 1965 base error-app-tag; 1966 description 1967 "Returned by the CoMI server when the validation of the 1968 'length' property fails."; 1969 } 1971 identity pattern-test-failed { 1972 base error-app-tag; 1973 description 1974 "Returned by the CoMI server when the validation of the 1975 'pattern' property fails."; 1976 } 1978 identity missing-key { 1979 base error-app-tag; 1980 description 1981 "Returned by the CoMI server to further qualify a 1982 missing-element error. This error is returned when the 1983 CoMI client tries to create or list instance, without all 1984 the 'key' specified or when the CoMI client tries to 1985 delete a leaf listed as a 'key'."; 1986 } 1988 identity missing-input-parameter { 1989 base error-app-tag; 1990 description 1991 "Returned by the CoMI server when the input parameters 1992 of a RPC or action are incomplete."; 1993 } 1995 identity instance-required { 1996 base error-app-tag; 1997 description 1998 "Returned by the CoMI server when a leaf of type 1999 'instance-identifier' or 'leafref' marked with 2000 require-instance set to 'true' refers to an instance 2001 that does not exist."; 2002 } 2004 identity missing-choice { 2005 base error-app-tag; 2006 description 2007 "Returned by the CoMI server when no nodes exist in a 2008 mandatory choice."; 2009 } 2011 container error { 2012 presence "Error paylaod"; 2014 description 2015 "Optional payload of a 4.00 Bad Request CoAP error."; 2017 leaf error-tag { 2018 type identityref { 2019 base error-tag; 2020 } 2021 mandatory true; 2022 description 2023 "The enumerated error-tag."; 2024 } 2026 leaf error-app-tag { 2027 type identityref { 2028 base error-app-tag; 2029 } 2030 description 2031 "The application-specific error-tag."; 2032 } 2034 leaf error-data-node { 2035 type instance-identifier; 2036 description 2037 "When the error reported is caused by a specific data node, 2038 this leaf identifies the data node in error."; 2039 } 2041 leaf error-message { 2042 type string; 2043 description 2044 "A message describing the error."; 2045 } 2046 } 2048 } 2049 2051 Appendix B. ietf-comi .sid file 2053 { 2054 "assignment-ranges": [ 2055 { 2056 "entry-point": 1000, 2057 "size": 100 2058 } 2059 ], 2060 "module-name": "ietf-comi", 2061 "module-revision": "2017-07-01", 2062 "items": [ 2063 { 2064 "namespace": "module", 2065 "identifier": "ietf-comi", 2066 "sid": 1000 2067 }, 2068 { 2069 "namespace": "identity", 2070 "identifier": "bad-element", 2071 "sid": 1001 2072 }, 2073 { 2074 "namespace": "identity", 2075 "identifier": "data-missing", 2076 "sid": 1002 2077 }, 2078 { 2079 "namespace": "identity", 2080 "identifier": "data-not-unique", 2081 "sid": 1003 2082 }, 2083 { 2084 "namespace": "identity", 2085 "identifier": "duplicate", 2086 "sid": 1004 2087 }, 2088 { 2089 "namespace": "identity", 2090 "identifier": "error", 2091 "sid": 1005 2092 }, 2093 { 2094 "namespace": "identity", 2095 "identifier": "error-app-tag", 2096 "sid": 1006 2097 }, 2098 { 2099 "namespace": "identity", 2100 "identifier": "error-tag", 2101 "sid": 1007 2102 }, 2103 { 2104 "namespace": "identity", 2105 "identifier": "instance-required", 2106 "sid": 1008 2107 }, 2108 { 2109 "namespace": "identity", 2110 "identifier": "invalid-datatype", 2111 "sid": 1009 2112 }, 2113 { 2114 "namespace": "identity", 2115 "identifier": "invalid-length", 2116 "sid": 1010 2117 }, 2118 { 2119 "namespace": "identity", 2120 "identifier": "invalid-value", 2121 "sid": 1011 2122 }, 2123 { 2124 "namespace": "identity", 2125 "identifier": "malformed-message", 2126 "sid": 1012 2127 }, 2128 { 2129 "namespace": "identity", 2130 "identifier": "missing-choice", 2131 "sid": 1013 2132 }, 2133 { 2134 "namespace": "identity", 2135 "identifier": "missing-element", 2136 "sid": 1014 2137 }, 2138 { 2139 "namespace": "identity", 2140 "identifier": "missing-input-parameter", 2141 "sid": 1015 2142 }, 2143 { 2144 "namespace": "identity", 2145 "identifier": "missing-key", 2146 "sid": 1016 2147 }, 2148 { 2149 "namespace": "identity", 2150 "identifier": "must-violation", 2151 "sid": 1017 2152 }, 2153 { 2154 "namespace": "identity", 2155 "identifier": "not-in-range", 2156 "sid": 1018 2157 }, 2158 { 2159 "namespace": "identity", 2160 "identifier": "operation-failed", 2161 "sid": 1019 2162 }, 2163 { 2164 "namespace": "identity", 2165 "identifier": "pattern-test-failed", 2166 "sid": 1020 2167 }, 2168 { 2169 "namespace": "identity", 2170 "identifier": "too-few-elements", 2171 "sid": 1021 2172 }, 2173 { 2174 "namespace": "identity", 2175 "identifier": "too-many-elements", 2176 "sid": 1022 2177 }, 2178 { 2179 "namespace": "identity", 2180 "identifier": "unknown-element", 2181 "sid": 1023 2182 }, 2183 { 2184 "namespace": "data", 2185 "identifier": "/ietf-comi:error", 2186 "sid": 1024 2187 }, 2188 { 2189 "namespace": "data", 2190 "identifier": "/ietf-comi:error/error-app-tag", 2191 "sid": 1025 2193 }, 2194 { 2195 "namespace": "data", 2196 "identifier": "/ietf-comi:error/error-data-node", 2197 "sid": 1026 2198 }, 2199 { 2200 "namespace": "data", 2201 "identifier": "/ietf-comi:error/error-message", 2202 "sid": 1027 2203 }, 2204 { 2205 "namespace": "data", 2206 "identifier": "/ietf-comi:error/error-tag", 2207 "sid": 1028 2208 } 2209 ] 2210 } 2212 Appendix C. YANG example specifications 2214 This appendix shows five YANG example specifications taken over from 2215 as many existing YANG modules. The YANG modules are available from 2216 [netconfcentral]. Each YANG item identifier is accompanied by its 2217 SID shown after the "//" comment sign. 2219 C.1. ietf-system 2221 Excerpt of the YANG module ietf-system [RFC7317]. 2223 module ietf-system { // SID 1700 2224 container system { // SID 1717 2225 container clock { // SID 1738 2226 choice timezone { 2227 case timezone-name { 2228 leaf timezone-name { // SID 1739 2229 type timezone-name; 2230 } 2231 } 2232 case timezone-utc-offset { 2233 leaf timezone-utc-offset { // SID 1740 2234 type int16 { 2235 } 2236 } 2237 } 2238 } 2239 } 2240 container ntp { // SID 1754 2241 leaf enabled { // SID 1755 2242 type boolean; 2243 default true; 2244 } 2245 list server { // SID 1756 2246 key name; 2247 leaf name { // SID 1759 2248 type string; 2249 } 2250 choice transport { 2251 case udp { 2252 container udp { // SID 1761 2253 leaf address { // SID 1762 2254 type inet:host; 2255 } 2256 leaf port { // SID 1763 2257 type inet:port-number; 2258 } 2259 } 2260 } 2261 } 2262 leaf association-type { // SID 1757 2263 type enumeration { 2264 enum server { 2265 } 2266 enum peer { 2267 } 2268 enum pool { 2269 } 2270 } 2271 } 2272 leaf iburst { // SID 1758 2273 type boolean; 2274 } 2275 leaf prefer { // SID 1760 2276 type boolean; 2277 default false; 2278 } 2279 } 2280 } 2281 container system-state { // SID 1720 2282 container clock { // SID 1721 2283 leaf current-datetime { // SID 1723 2284 type yang:date-and-time; 2285 } 2286 leaf boot-datetime { // SID 1722 2287 type yang:date-and-time; 2288 } 2290 } 2291 } 2292 } 2294 C.2. server list 2296 Taken over from [RFC7950] section 7.15.3. 2298 module example-server-farm { 2299 yang-version 1.1; 2300 namespace "urn:example:server-farm"; 2301 prefix "sfarm"; 2303 import ietf-yang-types { 2304 prefix "yang"; 2305 } 2307 list server { // SID 60000 2308 key name; 2309 leaf name { // SID 60001 2310 type string; 2311 } 2312 action reset { // SID 60002 2313 input { 2314 leaf reset-at { // SID 60003 2315 type yang:date-and-time; 2316 mandatory true; 2317 } 2318 } 2319 output { 2320 leaf reset-finished-at { // SID 60004 2321 type yang:date-and-time; 2322 mandatory true; 2323 } 2324 } 2325 } 2326 } 2327 } 2329 C.3. interfaces 2331 Excerpt of the YANG module ietf-interfaces [RFC7223]. 2333 module ietf-interfaces { // SID 1500 2334 container interfaces { // SID 1505 2335 list interface { // SID 1533 2336 key "name"; 2337 leaf name { // SID 1537 2338 type string; 2339 } 2340 leaf description { // SID 1534 2341 type string; 2342 } 2343 leaf type { // SID 1538 2344 type identityref { 2345 base interface-type; 2346 } 2347 mandatory true; 2348 } 2350 leaf enabled { // SID 1535 2351 type boolean; 2352 default "true"; 2353 } 2355 leaf link-up-down-trap-enable { // SID 1536 2356 if-feature if-mib; 2357 type enumeration { 2358 enum enabled { 2359 value 1; 2360 } 2361 enum disabled { 2362 value 2; 2363 } 2364 } 2365 } 2366 } 2367 } 2368 } 2370 C.4. Example-port 2372 Notification example defined within this document. 2374 module example-port { 2375 ... 2376 notification example-port-fault { // SID 60010 2377 description 2378 "Event generated if a hardware fault on a 2379 line card port is detected"; 2380 leaf port-name { // SID 60011 2381 type string; 2382 description "Port name"; 2383 } 2384 leaf port-fault { // SID 60012 2385 type string; 2386 description "Error condition detected"; 2387 } 2388 } 2389 } 2391 C.5. IP-MIB 2393 The YANG translation of the SMI specifying the IP-MIB [RFC4293], 2394 extended with example SID numbers, yields: 2396 module IP-MIB { 2397 import IF-MIB { 2398 prefix if-mib; 2399 } 2400 import INET-ADDRESS-MIB { 2401 prefix inet-address; 2402 } 2403 import SNMPv2-TC { 2404 prefix smiv2; 2405 } 2406 import ietf-inet-types { 2407 prefix inet; 2408 } 2409 import yang-smi { 2410 prefix smi; 2411 } 2412 import ietf-yang-types { 2413 prefix yang; 2414 } 2416 container ip { // SID 60020 2417 list ipNetToPhysicalEntry { // SID 60021 2418 key "ipNetToPhysicalIfIndex 2419 ipNetToPhysicalNetAddressType 2420 ipNetToPhysicalNetAddress"; 2421 leaf ipNetToPhysicalIfIndex { // SID 60022 2422 type if-mib:InterfaceIndex; 2423 } 2424 leaf ipNetToPhysicalNetAddressType { // SID 60023 2425 type inet-address:InetAddressType; 2426 } 2427 leaf ipNetToPhysicalNetAddress { // SID 60024 2428 type inet-address:InetAddress; 2429 } 2430 leaf ipNetToPhysicalPhysAddress { // SID 60025 2431 type yang:phys-address { 2432 length "0..65535"; 2433 } 2434 } 2435 leaf ipNetToPhysicalLastUpdated { // SID 60026 2436 type yang:timestamp; 2437 } 2438 leaf ipNetToPhysicalType { // SID 60027 2439 type enumeration { 2440 enum "other" { 2441 value 1; 2442 } 2443 enum "invalid" { 2444 value 2; 2445 } 2446 enum "dynamic" { 2447 value 3; 2448 } 2449 enum "static" { 2450 value 4; 2451 } 2452 enum "local" { 2453 value 5; 2454 } 2455 } 2456 } 2457 leaf ipNetToPhysicalState { // SID 60028 2458 type enumeration { 2459 enum "reachable" { 2460 value 1; 2461 } 2462 enum "stale" { 2463 value 2; 2464 } 2465 enum "delay" { 2466 value 3; 2467 } 2468 enum "probe" { 2469 value 4; 2471 } 2472 enum "invalid" { 2473 value 5; 2474 } 2475 enum "unknown" { 2476 value 6; 2477 } 2478 enum "incomplete" { 2479 value 7; 2480 } 2481 } 2482 } 2483 leaf ipNetToPhysicalRowStatus { // SID 60029 2484 type smiv2:RowStatus; 2485 } // list ipNetToPhysicalEntry 2486 } // container ip 2487 } // module IP-MIB 2489 Authors' Addresses 2491 Michel Veillette (editor) 2492 Trilliant Networks Inc. 2493 610 Rue du Luxembourg 2494 Granby, Quebec J2J 2V2 2495 Canada 2497 Email: michel.veillette@trilliantinc.com 2499 Peter van der Stok (editor) 2500 consultant 2502 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2503 Email: consultancy@vanderstok.org 2504 URI: www.vanderstok.org 2506 Alexander Pelov 2507 Acklio 2508 2bis rue de la Chataigneraie 2509 Cesson-Sevigne, Bretagne 35510 2510 France 2512 Email: a@ackl.io 2513 Andy Bierman 2514 YumaWorks 2515 685 Cochran St. 2516 Suite #160 2517 Simi Valley, CA 93065 2518 USA 2520 Email: andy@yumaworks.com