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