idnits 2.17.1 draft-vanderstok-core-comi-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == It seems as if not all pages are separated by form feeds - found 0 form feeds but 46 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 19 characters in excess of 72. == There are 2 instances 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: If the target of a GET method is a data node that represents a container or list that has any child resources with default values, for the child resources that have not been given value yet, the server MUST not return the child resource if this query parameter is set to 't' and MUST return the child resource if this query parameter is set to 'a'. -- The document date (January 18, 2017) is 2652 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) == Missing Reference: 'YANGlwm2m' is mentioned on line 1905, but not defined == Missing Reference: 'SID' is mentioned on line 1958, but not defined ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-03 -- 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) == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-07 == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-00 Summary: 2 errors (**), 0 flaws (~~), 9 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE P. van der Stok 3 Internet-Draft consultant 4 Intended status: Standards Track A. Bierman 5 Expires: July 22, 2017 YumaWorks 6 M. Veillette 7 Trilliant Networks Inc. 8 A. Pelov 9 Acklio 10 January 18, 2017 12 CoAP Management Interface 13 draft-vanderstok-core-comi-11 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 data resources specified in YANG, or SMIv2 converted to YANG. 21 CoMI uses the YANG to CBOR mapping and converts YANG identifier 22 strings to numeric identifiers for payload size reduction. CoMI 23 extends the set of YANG based protocols, NETCONF and RESTCONF, with 24 the capability to manage constrained devices and networks. 26 Note 28 Discussion and suggestions for improvement are requested, and should 29 be sent to core@ietf.org. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on July 22, 2017. 48 Copyright Notice 50 Copyright (c) 2017 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 67 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5 68 2.1. Major differences between RESTCONF and CoMI . . . . . . . 7 69 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 70 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 8 71 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 8 72 5. /c Function Set . . . . . . . . . . . . . . . . . . . . . . . 9 73 5.1. Using the 'k' query parameter . . . . . . . . . . . . . . 10 74 5.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 11 75 5.2.1. Using the 'c' query parameter . . . . . . . . . . . . 12 76 5.2.2. Using the 'd' query parameter . . . . . . . . . . . . 12 77 5.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 13 78 5.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 15 79 5.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 16 80 5.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 16 81 5.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 16 82 5.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 17 83 5.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 18 84 5.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 19 85 5.4. Full Data Store access . . . . . . . . . . . . . . . . . 19 86 5.4.1. Full Data Store examples . . . . . . . . . . . . . . 20 87 5.5. Notify functions . . . . . . . . . . . . . . . . . . . . 21 88 5.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 22 89 5.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 22 90 5.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 23 91 6. Access to MIB Data . . . . . . . . . . . . . . . . . . . . . 23 92 7. Use of Block . . . . . . . . . . . . . . . . . . . . . . . . 25 93 8. Resource Discovery . . . . . . . . . . . . . . . . . . . . . 25 94 9. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 27 95 10. Security Considerations . . . . . . . . . . . . . . . . . . . 28 96 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 97 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 98 13. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 30 99 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 100 14.1. Normative References . . . . . . . . . . . . . . . . . . 33 101 14.2. Informative References . . . . . . . . . . . . . . . . . 35 102 Appendix A. YANG example specifications . . . . . . . . . . . . 37 103 A.1. ietf-system . . . . . . . . . . . . . . . . . . . . . . . 37 104 A.2. server list . . . . . . . . . . . . . . . . . . . . . . . 38 105 A.3. interfaces . . . . . . . . . . . . . . . . . . . . . . . 39 106 A.4. Example-port . . . . . . . . . . . . . . . . . . . . . . 40 107 A.5. IP-MIB . . . . . . . . . . . . . . . . . . . . . . . . . 41 108 Appendix B. Comparison with LWM2M . . . . . . . . . . . . . . . 43 109 B.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 43 110 B.2. Defining Management Resources . . . . . . . . . . . . . . 44 111 B.3. Identifying Management Resources . . . . . . . . . . . . 44 112 B.4. Encoding of Management Resources . . . . . . . . . . . . 45 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 115 1. Introduction 117 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 118 Machine to Machine (M2M) applications such as smart energy and 119 building control. Constrained devices need to be managed in an 120 automatic fashion to handle the large quantities of devices that are 121 expected in future installations. The messages between devices need 122 to be as small and infrequent as possible. The implementation 123 complexity and runtime resources need to be as small as possible. 125 This draft describes the CoAP Management Interface which uses CoAP 126 methods to access structured data defined in YANG [RFC7950]. This 127 draft is complementary to the draft [I-D.ietf-netconf-restconf] which 128 describes a REST-like interface called RESTCONF, which uses HTTP 129 methods to access structured data defined in YANG. 131 The use of standardized data sets, specified in a standardized 132 language such as YANG, promotes interoperability between devices and 133 applications from different manufacturers. A large amount of 134 Management Information Base (MIB) [mibreg] specifications already 135 exists for monitoring purposes. This data can be accessed in 136 RESTCONF or CoMI if the server converts the SMIv2 modules to YANG, 137 using the mapping rules defined in [RFC6643]. 139 CoMI and RESTCONF are intended to work in a stateless client-server 140 fashion. They use a single round-trip to complete a single editing 141 transaction, where NETCONF needs up to 10 round trips. 143 To promote small packets, CoMI uses a YANG to CBOR mapping 144 [I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid] 145 to minimize CBOR payloads and URI length. 147 1.1. Terminology 149 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 150 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 151 document are to be interpreted as described in [RFC2119]. 153 Readers of this specification should be familiar with all the terms 154 and concepts discussed in [RFC3410], [RFC3416], and [RFC2578]. 156 The following terms are defined in the NETCONF protocol [RFC6241]: 157 client, configuration data, datastore, and server. 159 The following terms are defined in the YANG data modelling language 160 [RFC7950]: anydata, anyxml, container, data node, key, key leaf, 161 leaf, leaf-list, and list. 163 The following terms are defined in RESTCONF protocol 164 [I-D.ietf-netconf-restconf]: data resource, datastore resource, edit 165 operation, query parameter, and target resource. 167 The following terms are defined in this document: 169 data node instance: An instance of a data node specified in a YANG 170 module present in the server. The instance is stored in the 171 memory of the server. 173 Notification instance: An instance of a schema node of type 174 notification, specified in a YANG module present in the server. 175 The instance is generated in the server at the occurrence of the 176 corresponding event and appended to a stream. 178 YANG schema item identifier: Numeric identifier which replaces the 179 name identifying a YANG item (see section 6.2 of [RFC7950]) 180 (anydata, anyxml, data node, RPC, Action, Notification, Identity, 181 Module name, Submodule name, Feature). 183 list instance identifier: Handle used to identify a YANG data node 184 that is an instance of a YANG "list" specified with the values of 185 the key leaves of the list. 187 single instance identifier: Handle used to identify a specific data 188 node which can be instantiated only once. This includes data 189 nodes defined at the root of a YANG module or submodule and data 190 nodes defined within a container. This excludes data nodes 191 defined within a list or any children of these data nodes. 193 instance identifier: List instance identifier or single instance 194 identifier. 196 data node value: Value assigned to a data node instance. Data node 197 values are encoded based on the rules defined in section 4 of 198 [I-D.ietf-core-yang-cbor]. 200 set of data node instances: Represents the payload of CoAP methods 201 when a collection is sent or returned. There are two 202 possibilities, dependent on Request context: 204 1. CBOR array of pair(s) 206 2. CBOR map of pair(s) 208 TODO: Reduce to one, if possible 210 The following list contains the abbreviations used in this document. 212 SID: YANG Schema Item iDentifier. 214 2. CoMI Architecture 216 This section describes the CoMI architecture to use CoAP for the 217 reading and modifying the content of a datastore used for the 218 management of the instrumented node. 220 +--------------------------------------------------------------+ 221 | SMIv2 specification (2) | 222 +--------------------------------------------------------------+ 223 \/ 224 +--------------------------------------------------------------+ 225 | YANG specification (1) | 226 +---------*-----------------------------------------*----------+ 227 | compilation | compilation 228 | security (7) | 229 client \|/ [===========================] \|/ Server 230 +--------------------+ +------------------+ 231 | | | | 232 | Request generation +--> CoAP request(3) -->| Request retrieval| 233 | answer retrieval |<-- CoAP response(3)<--| answer generation| 234 | (4) | | (4) | 235 +--------------------+ | +---------------+| 236 | | datastore (5) || 237 | +---------------+| 238 | | 239 | Variable | 240 |Instrumentation(6)| 241 +------------------+ 243 Figure 1: Abstract CoMI architecture 245 Figure 1 is a high level representation of the main elements of the 246 CoAP management architecture. A client sends requests as payload in 247 packets over the network to a managed constrained node. 249 The different numbered components of Figure 1 are discussed according 250 to component number. 252 (1) YANG specification: contains a set of named and versioned 253 modules. 255 (2) SMIv2 specification: A named module specifies a set of variables 256 and "conceptual tables". There is an algorithm to translate SMIv2 257 specifications to YANG specifications. 259 (3) CoMI messages: The CoMI client sends request messages to and 260 receives response messages from the CoMI server. 262 (4) Retrieval, generation: The server and client parse the CoMI 263 request/response and identify the corresponding instances in the 264 datastore based on YANG specification. 266 (5) Datastore: The store is composed of two parts: Operational state 267 and Configuration datastore. Datastore also supports RPCs and 268 event streams. 270 (6) Variable instrumentation: This code depends on implementation of 271 drivers and other node specific aspects. 273 (7) Security: The server MUST prevent unauthorized users from 274 reading or writing any data resources. CoMI relies on security 275 protocols such as DTLS [RFC6347] to secure CoAP communication. 277 2.1. Major differences between RESTCONF and CoMI 279 CoMI uses CoAP/UDP as transport protocol and CBOR as payload format 280 [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as transport 281 protocol and JSON [RFC7159] or XML [XML] as payload formats. CoMI 282 encodes YANG identifier strings as numbers, where RESTCONF does not. 284 CoMI uses the methods FETCH and iPATCH, not used by RESTCONF. 285 RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not used 286 by CoMI. 288 CoMI servers cannot change the order of user-ordered data. CoMI does 289 not support insert-mode (first, last, before, after) and insertion- 290 point (before, after) which are supported by RESTCONF. Many CoAP 291 servers will not support date and time functions. For that reason 292 CoMI does not support the start, stop options for events. 294 CoMI servers only implement the efficient "trim" mode for default 295 values. 297 The CoMI servers do not support the following RESTCONF functionality: 299 o The "fields" query parameter to query multiple instances. 301 o The 'filter' query that involves XML parsing, 'content', and 302 'depth', query parameters. 304 2.2. Compression of YANG identifiers 306 In the YANG specification items are identified with a name string. 307 In order to significantly reduce the size of identifiers used in 308 CoMI, numeric object identifiers are used instead of these strings. 309 The specific encoding of the object identifiers is not hard-wired in 310 the protocol. 312 Examples of object identifier encoding formats are described in 313 [I-D.ietf-core-sid]. 315 3. Example syntax 317 This section presents the notation used for the examples. The YANG 318 specifications that are used throughout this document are shown in 319 Appendix A. The example specifications are taken over from existing 320 modules and annotated with SIDs. The values of the SIDs are taken 321 over from [yang-cbor]. 323 CBOR is used to encode CoMI request- and response- payloads. The 324 CBOR syntax of the YANG payloads is specified in [RFC7049]. The 325 payload examples are notated in Diagnostic notation (defined in 326 section 6 of [RFC7049]) that can be automatically converted to CBOR. 328 A YANG (item identifier, item value) pair is mapped to a CBOR (key, 329 value) pair. The YANG item value is encoded as specified in 330 [I-D.ietf-core-yang-cbor]. The YANG item identifier can be a SID 331 (single node identifier) or a CBOR array with the structure [SID, 332 key1, key2] (list node identifier), where SID is a list identifier 333 and the key values specify the list instance. The YANG item value 334 can be any CBOR major type. 336 Delta encoding is used for the SIDs. The notation +n is used when 337 the SID has the value PREC+n where PREC is the SID of the parent 338 container, or PREC is the SID of the preceding entity in a CBOR 339 array. 341 In all examples the resource path in the URI is expressed as a SID, 342 represented as a base64 number. SIDs in the payload are represented 343 as decimal numbers. 345 4. CoAP Interface 347 In CoAP a group of links can constitute a Function Set. 349 TODO: what will happen to term Function Set ? 351 The format of the links is specified in [I-D.ietf-core-interfaces]. 352 This note specifies a Management Function Set. CoMI end-points that 353 implement the CoMI management protocol support at least one 354 discoverable management resource of resource type (rt): core.c, with 355 path: /c, where c is short-hand for CoMI. The path root /c is 356 recommended but not compulsory (see Section 8). 358 The path prefix /c has resources accessible with the following three 359 paths: 361 /c: YANG-based data with path "/c" and using CBOR content encoding 362 format. This path represents a datastore resource which contains 363 YANG data resources as its descendant nodes. The data nodes are 364 identified with their SID with format /c/SID. 366 /c/mod.uri: URI identifying the location of the server module 367 information, with path "/c/mod.uri" and CBOR content format. This 368 YANG data is encoded with plain identifier strings, not YANG 369 encoded values. An Entity Tag MUST be maintained for this 370 resource by the server, which MUST be changed to a new value when 371 the set of YANG modules in use by the server changes. 373 /c/s: String identifying the default stream resource to which YANG 374 notification instances are appended. Notification support is 375 optional, so this resource will not exist if the server does not 376 support any notifications. 378 The mapping of YANG data node instances to CoMI resources is as 379 follows: A YANG module describes a set of data trees composed of YANG 380 data nodes. Every data node of the YANG modules loaded in the CoMI 381 server represents a resource of the datastore container (e.g. 382 /c/ 384 When multiple instances of a list node exist, instance selection is 385 possible as described in Section 5.2.4 and Section 5.2.3.1. 387 TODO; reference to fetch and patch content formats. 389 The profile of the management function set, with IF=core.c, is shown 390 in the table below, following the guidelines of 391 [I-D.ietf-core-interfaces]: 393 +----------------+-------------+----------------+-------------------+ 394 | name | path | rt | Data Type | 395 +----------------+-------------+----------------+-------------------+ 396 | Management | /c | core.c | n/a | 397 | | | | | 398 | Data | /c | core.c.data | application/cbor | 399 | | | | | 400 | Module Set URI | /c/mod.uri | core.c.moduri | application/cbor | 401 | | | | | 402 | Events | /c/s | core.c.stream | application/cbor | 403 +----------------+-------------+----------------+-------------------+ 405 5. /c Function Set 407 The /c Function Set provides a CoAP interface to manage YANG servers. 409 The methods used by CoMI are: 411 +-----------+-------------------------------------------------------+ 412 | Operation | Description | 413 +-----------+-------------------------------------------------------+ 414 | GET | Retrieve the datastore resource or a data resource | 415 | | | 416 | FETCH | Retrieve (partial) data resource(s) | 417 | | | 418 | POST | Create a data resource, invoke RPC | 419 | | | 420 | PUT | Create or replace a data resource | 421 | | | 422 | iPATCH | Idem-potently create, replace, and delete data | 423 | | resource(s) (partially) | 424 | | | 425 | DELETE | Delete a data resource | 426 +-----------+-------------------------------------------------------+ 428 There is one query parameters for the GET, PUT, POST, and DELETE 429 methods. 431 +-----------------+------------------------------------+ 432 | Query Parameter | Description | 433 +-----------------+------------------------------------+ 434 | k | Select an instance of a list node | 435 +-----------------+------------------------------------+ 437 This parameter is not used for FETCH and iPATCH, because their 438 request payloads support list instance selection. 440 5.1. Using the 'k' query parameter 442 The "k" (key) parameter specifies the instance of a list node. The 443 SID in the URI is followed by the (?k=key1, key2,..). Where SID 444 identifies a list node, and key1, key2 are the values of the key 445 leaves that specify an instance of the list. 447 Key values are encoded using the rules defined in the following 448 table: 450 +-----------------------+------------------+------------------------+ 451 | YANG datatype | Binary | Text representation | 452 | | representation | | 453 +-----------------------+------------------+------------------------+ 454 | uint8,uint16,unit32, | CBOR unsigned | int_to_text(number) | 455 | uint64 | integer | | 456 | | | | 457 | int8, int16,int32, | CBOR negative | base64 (CBOR | 458 | int64 | integer | representation) | 459 | | | | 460 | decimal64 | CBOR decimal | base64 (CBOR | 461 | | fractions | representation | 462 | | | | 463 | string | CBOR text or | text | 464 | | string | | 465 | | | | 466 | boolean | CBOR false or | "0" or "1" | 467 | | true | | 468 | | | | 469 | enumeration | CBOR unsigned | int_to_text (number) | 470 | | integer | | 471 | | | | 472 | bits | CBOR byte string | base64 (CBOR | 473 | | | representation) | 474 | | | | 475 | binary | CBOR byte string | base64 (binary value) | 476 | | | | 477 | identityref | CBOR unsigned | int_to_text (number) | 478 | | integer | | 479 | | | | 480 | union | | base64 (CBOR | 481 | | | representation) | 482 | | | | 483 | List instance | CBOR unsigned | base64 (CBOR | 484 | identifier | integer | representation) | 485 | | | | 486 | List instance | CBOR array | Base64 (CBOR | 487 | identifier | | representation) | 488 +-----------------------+------------------+------------------------+ 490 5.2. Data Retrieval 492 One or more data node instances can be retrieved by the client. The 493 operation is mapped to the GET method defined in section 5.8.1 of 494 [RFC7252] and to the FETCH method defined in section 2 of 495 [I-D.ietf-core-etch]. 497 It is possible that the size of the payload is too large to fit in a 498 single message. In the case that management data is bigger than the 499 maximum supported payload size, the Block mechanism from [RFC7959] is 500 used, as explained in more detail in Section 7. 502 CoMI uses the FETCH payload for retrieving a subset of the datastore. 504 There are two additional query parameters for the GET and FETCH 505 methods. 507 +------------+------------------------------------------------------+ 508 | Query | Description | 509 | Parameter | | 510 +------------+------------------------------------------------------+ 511 | c | Control selection of configuration and non- | 512 | | configuration data nodes (GET and FETCH) | 513 | | | 514 | d | Control retrieval of default values. | 515 +------------+------------------------------------------------------+ 517 5.2.1. Using the 'c' query parameter 519 The 'c' (content) parameter controls how descendant nodes of the 520 requested data nodes will be processed in the reply. 522 The allowed values are: 524 +-------+------------------------------------------------------+ 525 | Value | Description | 526 +-------+------------------------------------------------------+ 527 | c | Return only configuration descendant data nodes | 528 | | | 529 | n | Return only non-configuration descendant data nodes | 530 | | | 531 | a | Return all descendant data nodes | 532 +-------+------------------------------------------------------+ 534 This parameter is only allowed for GET and FETCH methods on datastore 535 and data resources. A 4.00 Bad Request error is returned if used for 536 other methods or resource types. 538 If this query parameter is not present, the default value is "a". 540 5.2.2. Using the 'd' query parameter 542 The "d" (with-defaults) parameter controls how the default values of 543 the descendant nodes of the requested data nodes will be processed. 545 The allowed values are: 547 +-------+-----------------------------------------------------------+ 548 | Value | Description | 549 +-------+-----------------------------------------------------------+ 550 | a | All data nodes are reported| Defined as 'report-all' in | 551 | | section 3.1 of [RFC6243]. | 552 | | | 553 | t | Data nodes set to the YANG default are not reported. | 554 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 555 +-------+-----------------------------------------------------------+ 557 If the target of a GET or FETCH method is a data node that represents 558 a leaf that has a default value, and the leaf has not been given a 559 value yet, the server MUST return the leaf. 561 If the target of a GET method is a data node that represents a 562 container or list that has any child resources with default values, 563 for the child resources that have not been given value yet, the 564 server MUST not return the child resource if this query parameter is 565 set to 't' and MUST return the child resource if this query parameter 566 is set to 'a'. 568 If this query parameter is not present, the default value is 't'. 570 5.2.3. GET 572 A request to read the values of a data node instance is sent with a 573 confirmable CoAP GET message. A single instance identifier is 574 specified in the URI path prefixed with /c. 576 FORMAT: 577 GET /c/ 579 2.05 Content (Content-Format: application/cbor) 580 582 The returned payload is composed of all the children associated with 583 the specified data node instance. 585 The instance identifier is a SID or a SID followed by the "k" query 586 parameter. 588 5.2.3.1. GET Examples 590 Using for example the current-datetime leaf from Appendix A.1, a 591 request is sent to retrieve the value of system-state/clock/current- 592 datetime specified in container system-state. The ID of system- 593 state/clock/current-datetime is 1719, encoded in base64 this yields 594 a3. The answer to the request returns a , transported as a 595 single CBOR string item. 597 REQ: GET example.com/c/a3 599 RES: 2.05 Content (Content-Format: application/cbor) 600 "2014-10-26T12:16:31Z" 602 For example, the GET of the clock node (ID = 1717; base64: a1), sent 603 by the client, results in the following returned value sent by the 604 server, transported as a CBOR map containing 2 pairs: 606 REQ: GET example.com/c/a1 608 RES: 2.05 Content (Content-Format: application/cbor) 609 { 610 +2 : "2014-10-26T12:16:51Z", / ID 1719 / 611 +1 : "2014-10-21T03:00:00Z" / ID 1718 / 612 } 614 A "list" node can have multiple instances. Accordingly, the returned 615 payload of GET is composed of all the instances associated with the 616 selected list node. 618 For example, look at the example in Appendix A.3. The GET of the 619 /interfaces/interface/ (with identifier 1533, base64: X9) results in 620 the following returned payload, transported as a CBOR array with 2 621 elements. 623 REQ: GET example.com/c/X9 625 RES: 2.05 Content (Content-Format: application/cbor) 626 [ 627 {+4 : "eth0", / name (ID 1537) / 628 +1 : "Ethernet adaptor", / description (ID 1534) / 629 +5 : 1179, / type, (ID 1538) identity / 630 / ethernetCsmacd (ID 1179) / 631 +2 : true / enabled ( ID 1535) / 632 }, 633 {+4 : "eth1", / name (ID 1537) / 634 +1 : "Ethernet adaptor", / description (ID 1534) / 635 +5 : 1179, / type, (ID 1538) identity / 636 / ethernetCsmacd (ID 1179) / 637 +2 : false / enabled / 638 } 639 ] 641 It is equally possible to select a leaf of one instance of a list or 642 a complete instance container with GET. The instance identifier is 643 the numeric identifier of the list followed by the specification of 644 the values for the key leaves that uniquely identify the list 645 instance. The instance identifier looks like: SID?k=key-value. The 646 key of "interface" is the "name" leaf. The example below requests 647 the description leaf of the instance with name="eth0" (ID=1534, 648 base64: X-). The value of the description leaf is returned. 650 REQ: GET example.com/c/X-?k="eth0" 652 RES: 2.05 Content (Content-Format: application/cbor) 653 "Ethernet adaptor" 655 5.2.4. FETCH 657 The FETCH is used to retrieve a list of data node values. The FETCH 658 Request payload contains a CBOR list of instance identifiers. 660 FORMAT: 661 FETCH /c/ Content-Format (application/YANG-fetch+cbor) 662 664 2.05 Content (Content-Format: application/YANG-patch+cbor) 665 667 The instance identifier is a SID or a CBOR array containing the SID 668 followed by key values that identify the list instance (sec 5.13.1 of 669 [I-D.ietf-core-yang-cbor]. In the payload of the returned data node 670 values, delta encoding is used as described in 671 [I-D.ietf-core-yang-cbor]. 673 5.2.4.1. FETCH examples 675 The example uses the current-datetime leaf and the interface list 676 from Appendix A.1. In the following example the value of current- 677 datetime (ID 1719)and the interface list (ID 1533) instance 678 identified with name="eth0" are queried. 680 REQ: FETCH /c Content-Format (application/YANG-fetch+cbor) 681 [ 1719, / ID 1719 / 682 [-186, "eth0"] / ID 1533 with name = "eth0" / 683 ] 685 RES: 2.05 Content Content-Format (application/YANG-patch+cbor) 686 [ 687 "2014-10-26T12:16:31Z", 688 { 689 +4 : "eth0", / name (ID 1537) / 690 +1 : "Ethernet adaptor", / description (ID 1534) / 691 +5 : 1179, / type (ID 1538), identity / 692 / ethernetCsmacd (ID 1179) / 693 +2 : true / enabled (ID 1535) / 694 } 695 ] 697 TODO: align with future FETCH content format. 699 5.3. Data Editing 701 CoMI allows datastore contents to be created, modified and deleted 702 using CoAP methods. 704 5.3.1. Data Ordering 706 A CoMI server SHOULD preserve the relative order of all user-ordered 707 list and leaf-list entries that are received in a single edit 708 request. These YANG data node types are encoded as arrays so 709 messages will preserve their order. 711 5.3.2. POST 713 Data resources are created with the POST method. The CoAP POST 714 operation is used in CoMI for creation of data resources and the 715 invocation of "ACTION" and "RPC" resources. Refer to Section 5.6 for 716 details on "ACTION" and "RPC" resources. 718 A request to create the values of an instance of a container or leaf 719 is sent with a confirmable CoAP POST message. A single SID is 720 specified in the URI path prefixed with /c. 722 FORMAT: 723 POST /c/ Content-Format(application/cbor) 724 726 2.01 Created (Content-Format: application/cbor) 728 If the data resource already exists, then the POST request MUST fail 729 and a "4.09 Conflict" status-line MUST be returned 731 The instance identifier is a SID or a SID followed by the "k" query 732 parameter. 734 5.3.2.1. Post example 736 The example uses the interface list from Appendix A.1. Example is 737 creating a new version of the container interface (ID = 1533): 739 REQ: POST /c/X9 Content-Format(application/cbor) 740 { 741 +4 : "eth0", / name (ID 1537) / 742 +1 : "Ethernet adaptor", / description (ID 1534) / 743 +5 : 1179, / type (ID 1538), identity / 744 / ethernetCsmacd (ID 1179) / 745 +2 : true / enabled (ID 1535) / 746 } 748 RES: 2.01 Created (Content-Format: application/cbor) 750 5.3.3. PUT 752 Data resource instances are created or replaced with the PUT method. 753 The PUT operation is supported in CoMI. A request to set the value 754 of a data node instance is sent with a confirmable CoAP PUT message. 756 FORMAT: 757 PUT /c/ Content-Format(application/cbor) 758 760 2.01 Created 762 The instance identifier is a SID or a SID followed by the "k" query 763 parameter. 765 5.3.3.1. PUT example 767 The example uses the interface list from Appendix A.1. Example is 768 renewing an instance of the list interface (ID = 1533) with key 769 name="eth0": 771 REQ: PUT /c/X9?k="eth0" Content-Format(application/cbor) 772 { 773 +4 : "eth0", / name (ID 1537) / 774 +1 : "Ethernet adaptor", / description (ID 1534) / 775 +5 : 1179, / type (ID 1538), identity / 776 / ethernetCsmacd ( ID 1179) / 777 +2 : true / enabled (ID 1535) / 778 } 779 RES: 2.04 Changed 781 5.3.4. iPATCH 783 One or multiple data resource instances are replaced with the idem- 784 potent iPATCH method [I-D.ietf-core-etch]. A request is sent with a 785 confirmable CoAP iPATCH message. 787 There are no query parameters for the iPATCH method. 789 The processing of the iPATCH command is specified by the CBOR 790 payload. The CBOR patch payload describes the changes to be made to 791 target YANG data nodes [I-D.bormann-appsawg-cbor-merge-patch]. If 792 the CBOR patch payload contains data node instances that are not 793 present in the target, these instances are added or silently ignored 794 dependent of the payload information. If the target contains the 795 specified instance, the contents of the instances are replaced with 796 the values of the payload. Null values indicate the removal of 797 existing values. 799 FORMAT: 800 iPATCH /c Content-Format(application/YANG-patch+cbor) 801 803 2.04 Changed 805 5.3.4.1. iPATCH example 807 The example uses the interface list from Appendix A.3, and the 808 timezone-utc-offset leaf from Appendix A.1. In the example one leaf 809 (timezone-utc-offset ) and one container (interface) instance are 810 changed. 812 REQ: iPATCH /c Content-Format(application/YANG-patch+cbor) 813 [ 814 [1533, "eth0"] , / interface (ID = 1533) / 815 { 816 +4 : "eth0", / name (ID 1537) / 817 +1 : "Ethernet adaptor", / description (ID 1534) / 818 +5 : 1179, / type (ID 1538), identity / 819 / ethernetCsmacd (ID 1179) / 820 +2 : true / enabled (ID 1535) / 821 }, 822 +203 , 60 / timezone-utc-offset (delta = 1736-1533) / 823 ] 825 RES: 2.04 Changed 827 TODO: Align with future cbor-merge-patch content format. 829 5.3.5. DELETE 831 Data resource instances are deleted with the DELETE method. The 832 RESTCONF DELETE operation is supported in CoMI. 834 FORMAT: 835 Delete /c/ 837 2.02 Deleted 839 The instance identifier is a SID or a SID followed by the "k" query 840 parameter. 842 5.3.5.1. DELETE example 844 The example uses the interface list from Appendix A.3. Example is 845 deleting an instance of the container interface (ID = 1533): 847 REQ: DELETE /c/X9?k="eth0" 849 RES: 2.02 Deleted 851 5.4. Full Data Store access 853 The methods GET, PUT, POST, and DELETE can be used to return, 854 replace, create, and delete the whole data store respectively. 856 FORMAT: 857 GET /c 858 2.05 Content (Content-Format: application/cbor) 859 861 PUT /c 862 (Content-Format: application/cbor) 863 864 2.04 Changed 866 POST /c 867 (Content-Format: application/cbor) 868 869 2.01 Created 871 DELETE /c 872 2.02 Deleted 874 The array of data node instances represents an array of all root 875 nodes in the data store after the PUT, POST and GET method 876 invocations. 878 5.4.1. Full Data Store examples 880 The example uses the interface list and the clock container from 881 Appendix A.3. Assume that the data store contains two root objects: 882 the list interface (ID 1533) with one instance and the container 883 Clock (ID 1717). After invocation of GET an array with these two 884 objects is returned: 886 RQ: GET /c 887 RES: 2.05 Content Content-Format (application/YANG-patch+cbor) 888 [ 889 {1717: 890 { +2: "2016-10-26T12:16:31Z", / current-datetime (ID 1719) / 891 +1: "2014-10-05T09:00:00Z" / boot-datetime (ID 1718) / 892 }, 893 -186: / clock (ID 1533) / 894 { 895 +4 : "eth0", / name (ID 1537) / 896 +1 : "Ethernet adaptor", / description (ID 1534) / 897 +5 : 1179, / type (ID 1538), identity: / 898 / ethernetCsmacd (ID 1179) / 899 +2 : true / enabled (ID 1535) / 900 } 901 } 902 ] 904 5.5. Notify functions 906 Notification by the server to a selection of clients when an event 907 occurs in the server is an essential function for the management of 908 servers. CoMI allows events specified in YANG [RFC5277] to be 909 notified to a selection of requesting clients. The server appends 910 newly generated events to a stream. There is one, so-called 911 "default", stream in a CoMI server. The /c/s resource identifies the 912 default stream. The server MAY create additional stream resources. 913 When a CoMI server generates an internal event, it is appended to the 914 chosen stream, and the content of a notification instance is ready to 915 be sent to all CoMI clients which observe the chosen stream resource. 917 Reception of generated notification instances is enabled with the 918 CoAP Observe [RFC7641] function. The client subscribes to the 919 notifications by sending a GET request with an "Observe" option, 920 specifying the /c/s resource when the default stream is selected. 922 Every time an event is generated, the chosen stream is cleared, and 923 the generated notification instance is appended to the chosen 924 stream(s). After appending the instance, the contents of the 925 instance is sent to all clients observing the modified stream. 927 FORMAT: 928 Get / 929 Content-Format(application/YANG-patch+cbor) Observe(0) 931 2.05 Content Content-Format(application/YANG-patch+cbor) 932 934 5.5.1. Notify Examples 936 Suppose the server generates the event specified in Appendix A.4. By 937 executing a GET on the /c/s resource the client receives the 938 following response: 940 REQ: GET /c/s Observe(0) Token(0x93) 942 RES: 2.05 Content Content-Format(application/YANG-patch+cbor) 943 Observe(12) Token(0x93) 944 { 945 60010 : / example-port-fault (ID 60010) / 946 { 947 +1 : "0/4/21", / port-name (ID 60011) / 948 +2 : "Open pin 2" / port-fault (ID 60012) / 949 }, 950 60010 : / example-port-fault (ID 60010) / 951 { 952 +1 : "1/4/21", / port-name (ID 60011) / 953 +2 : "Open pin 5" / port-fault (ID 60012) / 954 } 955 } 957 In the example, the request returns a success response with the 958 contents of the last two generated events. Consecutively the server 959 will regularly notify the client when a new event is generated. 961 To check that the client is still alive, the server MUST send 962 confirmable notifications once in a while. When the client does not 963 confirm the notification from the server, the server will remove the 964 client from the list of observers [RFC7641]. 966 5.6. RPC statements 968 The YANG "action" and "RPC" statements specify the execution of a 969 Remote procedure Call (RPC) in the server. It is invoked using a 970 POST method to an "Action" or "RPC" resource instance. The Request 971 payload contains the values assigned to the input container when 972 specified with the action station. The Response payload contains the 973 values of the output container when specified. 975 The returned success response code is 2.05 Content. 977 FORMAT: 978 POST /c/ 979 Content-Format(application/YANG-patch+cbor) 980 982 2.05 Content Content-Format (application/YANG-patch+cbor) 983 985 There "k" query parameter is allowed for the POST method when used 986 for an action invocation. 988 5.6.1. RPC Example 990 The example is based on the YANG action specification of 991 Appendix A.2. A server list is specified and the action "reset" (ID 992 60002, base64: Opq), that is part of a "server instance" with key 993 value "myserver", is invoked. 995 REQ: POST /c/Opq?k="myserver" 996 Content-Format(application/YANG-patch+cbor) 997 { 998 +1 : "2016-02-08T14:10:08Z09:00" / reset-at (ID 60003) / 999 } 1001 RES: 2.05 Content Content-Format(application/YANG-patch+cbor) 1002 { 1003 +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (ID 60004)/ 1004 } 1006 6. Access to MIB Data 1008 Appendix A.5 shows a YANG module mapped from the SMI specification 1009 "IP-MIB" [RFC4293]. The following example shows the 1010 "ipNetToPhysicalEntry" list with 2 instances, using diagnostic 1011 notation without delta encoding. 1013 { 1014 60021 : / list ipNetToPhysicalEntry / 1015 [ 1016 { 1017 60022 : 1, / ipNetToPhysicalIfIndex / 1018 60023 : 1, / ipNetToPhysicalNetAddressType: ipv4 / 1019 60024 : h'0A000033', / ipNetToPhysicalNetAddress / 1020 60025 : h'00000A01172D',/ ipNetToPhysicalPhysAddress / 1021 60026 : 2333943, / ipNetToPhysicalLastUpdated / 1022 60027 : 4, / ipNetToPhysicalType: static / 1023 60028 : 1, / ipNetToPhysicalState: reachable / 1024 60029 : 1 / ipNetToPhysicalRowStatus: active / 1025 }, 1026 { 1027 60022 : 1, / ipNetToPhysicalIfIndex / 1028 60023 : 1, / ipNetToPhysicalNetAddressType: ipv4 / 1029 60024 : h'09020304', / ipNetToPhysicalNetAddress / 1030 60025 : h'00000A36200A',/ ipNetToPhysicalPhysAddress / 1031 60026 : 2329836, / ipNetToPhysicalLastUpdated / 1032 60027 : 3, / ipNetToPhysicalType: dynamic / 1033 60028 : 6, / ipNetToPhysicalState: unknown / 1034 60029 : 1 / ipNetToPhysicalRowStatus: active / 1035 } 1036 ] 1037 } 1039 The IPv4 addresses A.0.0.33 and 9.2.3.4 are encoded in CBOR as 1040 h'0A000033' and h'09020304' respectively. In the following example 1041 exactly one instance is requested from the ipNetToPhysicalEntry (ID 1042 60021, base64: Oz1). The h'09020304' value is encoded in base64 as 1043 AJAgME. 1045 In this example one instance of /ip/ipNetToPhysicalEntry that matches 1046 the keys ipNetToPhysicalIfIndex = 1, ipNetToPhysicalNetAddressType = 1047 ipv4 and ipNetToPhysicalNetAddress = 9.2.3.4 (h'09020304', base64: 1048 AJAgME). 1050 REQ: GET example.com/c/Oz1?k="1,1,AJAgME" 1052 RES: 2.05 Content (Content-Format: application/YANG-patch+cbor) 1053 { 1054 +1 : 1, / ( SID 60022 ) / 1055 +2 : 1, / ( SID 60023 ) / 1056 +3 : h'09020304', / ( SID 60024 ) / 1057 +4 : h'00000A36200A', / ( SID 60025 ) / 1058 +5 : 2329836, / ( SID 60026 ) / 1059 +6 : 3, / ( SID 60027 ) / 1060 +7 : 6, / ( SID 60028 ) / 1061 +8 : 1 / ( SID 60029 ) / 1062 } 1064 7. Use of Block 1066 The CoAP protocol provides reliability by acknowledging the UDP 1067 datagrams. However, when large pieces of text need to be transported 1068 the datagrams get fragmented, thus creating constraints on the 1069 resources in the client, server and intermediate routers. The block 1070 option [RFC7959] allows the transport of the total payload in 1071 individual blocks of which the size can be adapted to the underlying 1072 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1073 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1074 acknowledged to guarantee reliability. 1076 Notice that the Block mechanism splits the data at fixed positions, 1077 such that individual data fields may become fragmented. Therefore, 1078 assembly of multiple blocks may be required to process the complete 1079 data field. 1081 Beware of race conditions. Blocks are filled one at a time and care 1082 should be taken that the whole data representation is sent in 1083 multiple blocks sequentially without interruption. In the server, 1084 values are changed, lists are re-ordered, extended or reduced. When 1085 these actions happen during the serialization of the contents of the 1086 variables, the transported results do not correspond with a state 1087 having occurred in the server; or worse the returned values are 1088 inconsistent. For example: array length does not correspond with 1089 actual number of items. It may be advisable to use CBOR maps or CBOR 1090 arrays of undefined length which are foreseen for data streaming 1091 purposes. 1093 8. Resource Discovery 1095 The presence and location of (path to) the management data are 1096 discovered by sending a GET request to "/.well-known/core" including 1097 a resource type (RT) parameter with the value "core.c" [RFC6690]. 1099 Upon success, the return payload will contain the root resource of 1100 the management data. It is up to the implementation to choose its 1101 root resource, but it is recommended that the value "/c" is used, 1102 where possible. The example below shows the discovery of the 1103 presence and location of management data. 1105 REQ: GET /.well-known/core?rt=core.c 1107 RES: 2.05 Content ; rt="core.c" 1109 Management objects MAY be discovered with the standard CoAP resource 1110 discovery. The implementation can add the encoded values of the 1111 object identifiers to /.well-known/core with rt="core.c.data". The 1112 available objects identified by the encoded values can be discovered 1113 by sending a GET request to "/.well-known/core" including a resource 1114 type (RT) parameter with the value "core.c.data". Upon success, the 1115 return payload will contain the registered encoded values and their 1116 location. The example below shows the discovery of the presence and 1117 location of management data. 1119 REQ: GET /.well-known/core?rt=core.c.data 1121 RES: 2.05 Content ; rt="core.c.data", 1122 ; rt="core.c.data" 1124 Lists of encoded values may become prohibitively long. It is 1125 discouraged to provide long lists of objects on discovery. 1126 Therefore, it is recommended that details about management objects 1127 are discovered by reading the YANG module information stored in for 1128 example the "ietf-comi-yang-library" module 1129 [I-D.veillette-core-cool-library]. The resource "/c/mod.uri" is used 1130 to retrieve the location of the YANG module library. 1132 The module list can be stored locally on each server, or remotely on 1133 a different server. The latter is advised when the deployment of 1134 many servers are identical. 1136 Local in example.com server: 1138 REQ: GET example.com/c/mod.uri 1140 RES: 2.05 Content (Content-Format: application/cbor) 1141 { 1142 "mod.uri" : "example.com/c/modules" 1143 } 1145 Remote in example-remote-server: 1147 REQ: GET example.com/c/mod.uri 1149 RES: 2.05 Content (Content-Format: application/cbor) 1150 { 1151 "moduri" : "example-remote-server.com/c/group17/modules" 1152 } 1154 Within the YANG module library all information about the module is 1155 stored such as: module identifier, identifier hierarchy, grouping, 1156 features and revision numbers. 1158 9. Error Handling 1160 In case a request is received which cannot be processed properly, the 1161 CoMI server MUST return an error message. This error message MUST 1162 contain a CoAP 4.xx or 5.xx response code, and SHOULD include 1163 additional information in the payload. 1165 Such an error message payload is a text string, using the following 1166 structure: 1168 CoMI error: xxxx "error text" 1170 The characters xxxx represent one of the values from the table below, 1171 and the OPTIONAL "error text" field contains a human readable 1172 explanation of the error. 1174 +----------------+----------------+---------------------------------+ 1175 | CoMI Error | CoAP Error | Description | 1176 | Code | Code | | 1177 +----------------+----------------+---------------------------------+ 1178 | 0 | 4.xx | General error | 1179 | | | | 1180 | 1 | 4.13 | Request too big | 1181 | | | | 1182 | 2 | 4.00 | Response too big | 1183 | | | | 1184 | 3 | 4.00 | Unknown identifier | 1185 | | | | 1186 | 4 | 4.00 | Invalid value | 1187 | | | | 1188 | 5 | 4.05 | Attempt to write read-only | 1189 | | | variable | 1190 | | | | 1191 | 6 | 5.01 | No access | 1192 | | | | 1193 | 7 | 4.00 | Wrong type | 1194 | | | | 1195 | 8 | 4.15 | Unknown encoding | 1196 | | | | 1197 | 9 | 4.0 | Wrong value | 1198 | | | | 1199 | 10 | 4.0 | Not created | 1200 | | | | 1201 | 11 | 4.04 | Resource unavailable | 1202 | | | | 1203 | 12 | 4.01 | Authorization error | 1204 | | | | 1205 | 13 | 4.0 | Bad attribute | 1206 | | | | 1207 | 14 | 4.0 | Unknown attribute | 1208 | | | | 1209 | 15 | 4.0 | Missing attribute | 1210 +----------------+----------------+---------------------------------+ 1212 The CoMI error codes are motivated by the error-status values defined 1213 in [RFC3416], and the error tags defined in 1214 [I-D.ietf-netconf-restconf]. 1216 10. Security Considerations 1218 For secure network management, it is important to restrict access to 1219 configuration variables only to authorized parties. This requires 1220 integrity protection of both requests and responses, and depending on 1221 the application encryption. 1223 CoMI re-uses the security mechanisms already available to CoAP as 1224 much as possible. This includes DTLS [RFC6347] for protected access 1225 to resources, as well suitable authentication and authorization 1226 mechanisms. 1228 Among the security decisions that need to be made are selecting 1229 security modes and encryption mechanisms (see [RFC7252]). This 1230 requires a trade-off, as the NoKey mode gives no protection at all, 1231 but is easy to implement, whereas the X.509 mode is quite secure, but 1232 may be too complex for constrained devices. 1234 In addition, mechanisms for authentication and authorization may need 1235 to be selected. 1237 CoMI avoids defining new security mechanisms as much as possible. 1238 However some adaptations may still be required, to cater for CoMI's 1239 specific requirements. 1241 11. IANA Considerations 1243 'rt="core.c"' needs registration with IANA. 1245 'rt="core.c.data"' needs registration with IANA. 1247 'rt="core.c.moduri"' needs registration with IANA. 1249 'rt="core.c.stream"' needs registration with IANA. 1251 Content types to be registered: 1253 o application/YANG-patch+cbor 1255 o application/YANG-fetch+cbor 1257 12. Acknowledgements 1259 We are very grateful to Bert Greevenbosch who was one of the original 1260 authors of the CoMI specification and specified CBOR encoding and use 1261 of hashes. 1263 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1264 transported under SNMP. Carsten Bormann has given feedback on the 1265 use of CBOR. 1267 Timothy Carey has provided the text for Appendix B. 1269 The draft has benefited from comments (alphabetical order) by Rodney 1270 Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Juergen 1271 Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes Tschofenig, Michael 1272 Verschoor, and Thomas Watteyne. 1274 13. Changelog 1276 Changes from version 00 to version 01 1278 o Focus on MIB only 1280 o Introduced CBOR, JSON, removed BER 1282 o defined mappings from SMI to xx 1284 o Introduced the concept of addressable table rows 1286 Changes from version 01 to version 02 1288 o Focus on CBOR, used JSON for examples, removed XML and EXI 1290 o added uri-query attributes mod and con to specify modules and 1291 contexts 1293 o Definition of CBOR string conversion tables for data reduction 1295 o use of Block for multiple fragments 1297 o Error returns generalized 1299 o SMI - YANG - CBOR conversion 1301 Changes from version 02 to version 03 1303 o Added security considerations 1305 Changes from version 03 to version 04 1307 o Added design considerations section 1309 o Extended comparison of management protocols in introduction 1311 o Added automatic generation of CBOR tables 1313 o Moved lowpan table to Appendix 1315 Changes from version 04 to version 05 1317 o Merged SNMP access with RESTCONF access to management objects in 1318 small devices 1320 o Added CoMI architecture section 1322 o Added RESTCONf NETMOD description 1324 o Rewrote section 5 with YANG examples 1326 o Added server and payload size appendix 1328 o Removed Appendix C for now. It will be replaced with a YANG 1329 example. 1331 Changes from version 04 to version 05 1333 o Extended examples with hash representation 1335 o Added keys query parameter text 1337 o Added select query parameter text 1339 o Better separation between specification and instance 1341 o Section on discovery updated 1343 o Text on rehashing introduced 1345 o Elaborated SMI MIB example 1347 o YANG library use described 1349 o use of BigEndian/LittleEndian in Hash generation specified 1351 Changes from version 05 to version 06 1353 o Hash values in payload as hexadecimal and in URL in base64 numbers 1355 o Streamlined CoMI architecture text 1357 o Added select query parameter text 1359 o Data editing optional 1361 o Text on Notify added 1363 o Text on rehashing improved with example 1365 Changes from version 06 to version 07 1367 o reduced payload size by removing JSON hierarchy 1368 o changed rehash handling to support small clients 1370 o added LWM2M comparison 1372 o Notification handling as specified in YANG 1374 o Added Patch function 1376 o Rehashing completely reviewed 1378 o Discover type of YANG name encoding 1380 o Added new resource types 1382 o Read-only servers introduced 1384 o Multiple updates explained 1386 Changes from version 07 to version 08 1388 o Changed YANG Hash algorithm to use module name instead of prefix 1390 o Added rehash bit to allow return values to identify rehashed nodes 1391 in the response 1393 o Removed /c/mod.set resource since this is not needed 1395 o Clarified that YANG Hash is done even for unimplemented objects 1397 o YANG lists transported as CBOR maps of maps 1399 o Adapted examples with more CBOR explanation 1401 o Added CBOR code examples in new appendix 1403 o Possibility to use other than default stream 1405 o Added text and examples for Patch payload 1407 o Repaired some examples 1409 o Added appendices on hash clash probability and hash clash storage 1410 overhead 1412 Changes from version 08 to version 09 1414 o Removed hash and YANG to CBOR sections 1415 o removed hashes from examples. 1417 o Added RPC 1419 o Added content query parameter. 1421 o Added default handling. 1423 o Listed differences with RESTCONF 1425 Changes from version 09 to version 10. This is the merge of cool-01 1426 with comi-09. 1428 o Merged with CoOL SIDs 1430 o Introduced iPATCH, PATCH and FETCH 1432 o Update of LWM2M comparison 1434 o Added appendix with module examples 1436 o Removed introductory text 1438 o Removed references 1440 Changes from version 10 to version 11 1442 o Introduction streamlined 1444 o Error codes streamlined 1446 o Examples updated to latest SID values 1448 o Update of the YANG specifications in the appendix 1450 14. References 1452 14.1. Normative References 1454 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1455 Requirement Levels", BCP 14, RFC 2119, 1456 DOI 10.17487/RFC2119, March 1997, 1457 . 1459 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1460 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1461 . 1463 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1464 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1465 . 1467 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1468 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1469 October 2013, . 1471 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1472 Application Protocol (CoAP)", RFC 7252, 1473 DOI 10.17487/RFC7252, June 2014, 1474 . 1476 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1477 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1478 . 1480 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1481 the Constrained Application Protocol (CoAP)", RFC 7959, 1482 DOI 10.17487/RFC7959, August 2016, 1483 . 1485 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1486 Application Protocol (CoAP)", RFC 7641, 1487 DOI 10.17487/RFC7641, September 2015, 1488 . 1490 [I-D.ietf-netconf-restconf] 1491 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1492 Protocol", draft-ietf-netconf-restconf-18 (work in 1493 progress), October 2016. 1495 [I-D.ietf-core-etch] 1496 Stok, P., Bormann, C., and A. Sehgal, "Patch and Fetch 1497 Methods for Constrained Application Protocol (CoAP)", 1498 draft-ietf-core-etch-04 (work in progress), November 2016. 1500 [I-D.bormann-appsawg-cbor-merge-patch] 1501 Bormann, C. and P. Stok, "CBOR Merge Patch", draft- 1502 bormann-appsawg-cbor-merge-patch-00 (work in progress), 1503 March 2016. 1505 [I-D.ietf-core-yang-cbor] 1506 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 1507 Minaburo, "CBOR Encoding of Data Modeled with YANG", 1508 draft-ietf-core-yang-cbor-03 (work in progress), October 1509 2016. 1511 14.2. Informative References 1513 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1514 Schoenwaelder, Ed., "Structure of Management Information 1515 Version 2 (SMIv2)", STD 58, RFC 2578, 1516 DOI 10.17487/RFC2578, April 1999, 1517 . 1519 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 1520 "Introduction and Applicability Statements for Internet- 1521 Standard Management Framework", RFC 3410, 1522 DOI 10.17487/RFC3410, December 2002, 1523 . 1525 [RFC3416] Presuhn, R., Ed., "Version 2 of the Protocol Operations 1526 for the Simple Network Management Protocol (SNMP)", 1527 STD 62, RFC 3416, DOI 10.17487/RFC3416, December 2002, 1528 . 1530 [RFC4293] Routhier, S., Ed., "Management Information Base for the 1531 Internet Protocol (IP)", RFC 4293, DOI 10.17487/RFC4293, 1532 April 2006, . 1534 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1535 and A. Bierman, Ed., "Network Configuration Protocol 1536 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1537 . 1539 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1540 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1541 January 2012, . 1543 [RFC6643] Schoenwaelder, J., "Translation of Structure of Management 1544 Information Version 2 (SMIv2) MIB Modules to YANG 1545 Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012, 1546 . 1548 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1549 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1550 . 1552 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1553 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1554 2014, . 1556 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1557 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1558 . 1560 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1561 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1562 2014, . 1564 [I-D.ietf-core-interfaces] 1565 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Reusable 1566 Interface Definitions for Constrained RESTful 1567 Environments", draft-ietf-core-interfaces-07 (work in 1568 progress), December 2016. 1570 [I-D.ietf-core-sid] 1571 Somaraju, A., Veillette, M., Pelov, A., Turner, R., and A. 1572 Minaburo, "YANG Schema Item iDentifier (SID)", draft-ietf- 1573 core-sid-00 (work in progress), October 2016. 1575 [I-D.veillette-core-cool] 1576 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 1577 Minaburo, "Constrained Objects Language", draft-veillette- 1578 core-cool-02 (work in progress), July 2016. 1580 [I-D.veillette-core-cool-library] 1581 Veillette, M., "Constrained YANG Module Library", draft- 1582 veillette-core-cool-library-00 (work in progress), August 1583 2016. 1585 [XML] "Extensible Markup Language (XML)", 1586 Web http://www.w3.org/xml. 1588 [OMA] "OMA-TS-LightweightM2M-V1_0-20131210-C", Web 1589 http://technical.openmobilealliance.org/Technical/ 1590 current_releases.aspx. 1592 [OMNA] "Open Mobile Naming Authority (OMNA)", Web 1593 http://http://technical.openmobilealliance.org/Technical/ 1594 technical-information/omna. 1596 [netconfcentral] 1597 "NETCONF Central: library of YANG modules", 1598 Web http://www.netconfcentral.org/modulelist. 1600 [mibreg] "Structure of Management Information (SMI) Numbers (MIB 1601 Module Registrations)", Web 1602 http://www.iana.org/assignments/smi-numbers/ 1603 smi-numbers.xhtml/. 1605 [yang-cbor] 1606 "yang-cbor Registry", Web https://github.com/core-wg/yang- 1607 cbor/tree/master/registry/. 1609 Appendix A. YANG example specifications 1611 This appendix shows 5 YANG example specifications taken over from as 1612 many existing YANG modules. The YANG modules are available from 1613 [netconfcentral]. Each YANG item identifier is accompanied by its 1614 SID shown after the "//" comment sign, taken from [yang-cbor]. 1616 A.1. ietf-system 1618 Excerpt of the YANG module ietf-system [RFC7317]. 1620 module ietf-system { 1621 container system { // SID 1715 1622 container clock { // SID 1734 1623 choice timezone { 1624 case timezone-name { 1625 leaf timezone-name { // SID 1735 1626 type timezone-name; 1627 } 1628 } 1629 case timezone-utc-offset { 1630 leaf timezone-utc-offset { // SID 1736 1631 type int16 { 1632 } 1633 } 1634 } 1635 } 1636 } 1637 container ntp { // SID 1750 1638 leaf enabled { // SID 1751 1639 type boolean; 1640 default true; 1641 } 1642 list server { // SID 1752 1643 key name; 1644 leaf name { // SID 1755 1645 type string; 1646 } 1647 choice transport { 1648 case udp { 1649 container udp { // SID 1757 1650 leaf address { // SID 1758 1651 type inet:host; 1652 } 1653 leaf port { // SID 1759 1654 type inet:port-number; 1655 } 1656 } 1658 } 1659 } 1660 leaf association-type { // SID 1753 1661 type enumeration { 1662 enum server { 1663 } 1664 enum peer { 1665 } 1666 enum pool { 1667 } 1668 } 1669 } 1670 leaf iburst { // SID 1754 1671 type boolean; 1672 } 1673 leaf prefer { // SID 1756 1674 type boolean; 1675 default false; 1676 } 1677 } 1678 } 1679 container system-state { // SID 1716 1680 container clock { // SID 1717 1681 leaf current-datetime { // SID 1719 1682 type yang:date-and-time; 1683 } 1684 leaf boot-datetime { // SID 1718 1685 type yang:date-and-time; 1686 } 1687 } 1688 } 1689 } 1691 A.2. server list 1693 Taken over from [RFC7950] section 7.15.3. 1695 module example-server-farm { 1696 yang-version 1.1; 1697 namespace "urn:example:server-farm"; 1698 prefix "sfarm"; 1700 import ietf-yang-types { 1701 prefix "yang"; 1702 } 1704 list server { // SID 60000 1705 key name; 1706 leaf name { // SID 60001 1707 type string; 1708 } 1709 action reset { // SID 60002 1710 input { 1711 leaf reset-at { // SID 60003 1712 type yang:date-and-time; 1713 mandatory true; 1714 } 1715 } 1716 output { 1717 leaf reset-finished-at { // SID 60004 1718 type yang:date-and-time; 1719 mandatory true; 1720 } 1721 } 1722 } 1723 } 1724 } 1726 A.3. interfaces 1728 Excerpt of the YANG module ietf-interfaces [RFC7223]. 1730 module ietf-interfaces { 1731 container interfaces { // SID 1505 1732 list interface { // SID 1533 1733 key "name"; 1734 leaf name { // SID 1537 1735 type string; 1736 } 1737 leaf description { // SID 1534 1738 type string; 1739 } 1740 leaf type { // SID 1538 1741 type identityref { 1742 base interface-type; 1743 } 1744 mandatory true; 1745 } 1747 leaf enabled { // SID 1535 1748 type boolean; 1749 default "true"; 1750 } 1752 leaf link-up-down-trap-enable { // SID 1536 1753 if-feature if-mib; 1754 type enumeration { 1755 enum enabled { 1756 value 1; 1757 } 1758 enum disabled { 1759 value 2; 1760 } 1761 } 1762 } 1763 } 1764 } 1765 } 1767 A.4. Example-port 1769 Notification example defined within this document. 1771 module example-port { 1772 ... 1773 notification example-port-fault { // SID 60010 1774 description 1775 "Event generated if a hardware fault on a 1776 line card port is detected"; 1777 leaf port-name { // SID 60011 1778 type string; 1779 description "Port name"; 1780 } 1781 leaf port-fault { // SID 60012 1782 type string; 1783 description "Error condition detected"; 1784 } 1785 } 1786 } 1788 A.5. IP-MIB 1790 The YANG translation of the SMI specifying the IP-MIB [RFC4293], 1791 extended with example SID numbers, yields: 1793 module IP-MIB { 1794 import IF-MIB { 1795 prefix if-mib; 1796 } 1797 import INET-ADDRESS-MIB { 1798 prefix inet-address; 1799 } 1800 import SNMPv2-TC { 1801 prefix smiv2; 1802 } 1803 import ietf-inet-types { 1804 prefix inet; 1805 } 1806 import yang-smi { 1807 prefix smi; 1808 } 1809 import ietf-yang-types { 1810 prefix yang; 1811 } 1813 container ip { // SID 60020 1814 list ipNetToPhysicalEntry { // SID 60021 1815 key "ipNetToPhysicalIfIndex ipNetToPhysicalNetAddressType ipNetToPhysicalNetAddress"; 1816 leaf ipNetToPhysicalIfIndex { // SID 60022 1817 type if-mib:InterfaceIndex; 1819 } 1820 leaf ipNetToPhysicalNetAddressType { // SID 60023 1821 type inet-address:InetAddressType; 1822 } 1823 leaf ipNetToPhysicalNetAddress { // SID 60024 1824 type inet-address:InetAddress; 1825 } 1826 leaf ipNetToPhysicalPhysAddress { // SID 60025 1827 type yang:phys-address { 1828 length "0..65535"; 1829 } 1830 } 1831 leaf ipNetToPhysicalLastUpdated { // SID 60026 1832 type yang:timestamp; 1833 } 1834 leaf ipNetToPhysicalType { // SID 60027 1835 type enumeration { 1836 enum "other" { 1837 value 1; 1838 } 1839 enum "invalid" { 1840 value 2; 1841 } 1842 enum "dynamic" { 1843 value 3; 1844 } 1845 enum "static" { 1846 value 4; 1847 } 1848 enum "local" { 1849 value 5; 1850 } 1851 } 1852 } 1853 leaf ipNetToPhysicalState { // SID 60028 1854 type enumeration { 1855 enum "reachable" { 1856 value 1; 1857 } 1858 enum "stale" { 1859 value 2; 1860 } 1861 enum "delay" { 1862 value 3; 1863 } 1864 enum "probe" { 1865 value 4; 1866 } 1867 enum "invalid" { 1868 value 5; 1869 } 1870 enum "unknown" { 1871 value 6; 1872 } 1873 enum "incomplete" { 1874 value 7; 1875 } 1876 } 1877 } 1878 leaf ipNetToPhysicalRowStatus { // SID 60029 1879 type smiv2:RowStatus; 1880 } // list ipNetToPhysicalEntry 1881 } // container ip 1882 } // module IP-MIB 1884 Appendix B. Comparison with LWM2M 1886 B.1. Introduction 1888 CoMI and LWM2M [OMA], both, provide RESTful device management 1889 services over CoAP. Differences between the designs are highlighted 1890 in this section. 1892 The intent of the LWM2M protocol is to provide a single protocol to 1893 control and manage IoT devices. This means the IoT device implements 1894 and uses the same LWM2M agent function for the actuation and sensing 1895 features of the IoT device as well as for the management of the IoT 1896 device. The intent of CoMI Interface as described in the Abstract 1897 section of this document is to provide management of constrained 1898 devices and devices in constrained networks using RESTCONF and YANG. 1899 This implies that the device, although reusing the CoAP protocol, 1900 would need a separate CoAP based agent in the future to control the 1901 actuation and sensing features of the device and another CoMI agent 1902 that performs the management functions. 1904 It should be noted that the mapping of a LWM2M server to YANG is 1905 specified in [YANGlwm2m]. The converted server can be invoked with 1906 CoMI as specified in this document. 1908 For the purposes of managing IoT devices the following points related 1909 to the protocols compare how management resources are defined, 1910 identified, encoded and updated. 1912 B.2. Defining Management Resources 1914 Management resources in LWM2M (LWM2M objects) are defined using a 1915 standardized number. When a new management resource is defined, 1916 either by a standards organization or a private enterprise, the 1917 management resource is registered with the Open Mobile Naming 1918 Authority [OMNA] in order to ensure different resource definitions do 1919 not use the same identifier. CoMI, by virtue of using YANG as its 1920 data modeling language, allows enterprises and standards 1921 organizations to define new management resources (YANG nodes) within 1922 YANG modules without having to register each individual management 1923 resource. Instead YANG modules are scoped within a registered name 1924 space. As such, the CoMI approach provides additional flexibility in 1925 defining management resources. Likewise, since CoMI utilizes YANG, 1926 existing YANG modules can be reused. The flexibility and reuse 1927 capabilities afforded to CoMI can be useful in management of devices 1928 like routers and switches in constrained networks. However for 1929 management of IoT devices, the usefulness of this flexibility and 1930 applicability of reuse of existing YANG modules may not be warranted. 1931 The reason is that IoT devices typically do not require complex sets 1932 of configuration or monitoring operations required by devices like a 1933 router or a switch. To date, OMA has defined approximately 15 1934 management resources for constrained and non-constrained mobile or 1935 fixed IoT devices while other 3rd Party SDOs have defined another 10 1936 management resources for their use in non-constrained IoT devices. 1937 Likewise, the Constrained Object Language [I-D.veillette-core-cool] 1938 which is used by CoMI when managing constrained IoT devices uses YANG 1939 schema item identifiers, which are registered with IANA, in order to 1940 define management resources that are encoded using CBOR when 1941 targeting constrained IoT Devices. 1943 B.3. Identifying Management Resources 1945 As LWM2M and CoMI can similarly be used to manage IoT devices, 1946 comparison of the CoAP URIs used to identify resources is relevant as 1947 the size of the resource URI becomes applicable for IoT devices in 1948 constrained networks. LWM2M uses a flat identifier structure to 1949 identify management resources and are identified using the LWM2M 1950 object's identifier, instance identifier and optionally resource 1951 identifier (for access to and object's attributes). For example, 1952 identifier of a device object (object id = 3) would be "/3/0" and 1953 identification of the device object's manufacturer attribute would be 1954 "/3/0/0". Effectively LWM2M identifiers for management resources are 1955 between 4 and 10 bytes in length. 1957 CoMI is expected to be used to manage constrained IoT devices. CoMI 1958 utilizes the YANG schema item identifier[SID] that identify the 1959 resources. CoMI recommends that IoT device expose resources to 1960 identify the data stores and event streams of the CoMI agent. 1961 Individual resources (e.g., device object) are not directly 1962 identified but are encoded within the payload. As such the 1963 identifier of the CoMI resource is smaller (4 to 7 bytes) but the 1964 overall payload size isn't smaller as resource identifiers are 1965 encoded on the payload. 1967 B.4. Encoding of Management Resources 1969 LWM2M provides a separation of the definition of the management 1970 resources from how the payloads are encoded. As of the writing of 1971 this document LWM2M encodes LWM2M encodes payload data in Type- 1972 length-value (TLV), JSON or plain text formats. JSON encoding is the 1973 most common encoding scheme with TLV encoding used on the simplest 1974 IoT devices. CoMI's use of CBOR provides a more efficient transfer 1975 mechanism [RFC7049] than the current LWM2M encoding formats. 1977 In situations where resources need to be modified, CoMI uses the CoAP 1978 PATCH operation resources only require a partial update. LWM2M does 1979 not currently use the CoAP PATCH operation but instead uses the CoAP 1980 PUT and POST operations which are less efficient. 1982 Authors' Addresses 1984 Peter van der Stok 1985 consultant 1987 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 1988 Email: consultancy@vanderstok.org 1989 URI: www.vanderstok.org 1991 Andy Bierman 1992 YumaWorks 1993 685 Cochran St. 1994 Suite #160 1995 Simi Valley, CA 93065 1996 USA 1998 Email: andy@yumaworks.com 1999 Michel Veillette 2000 Trilliant Networks Inc. 2001 610 Rue du Luxembourg 2002 Granby, Quebec J2J 2V2 2003 Canada 2005 Phone: +14503750556 2006 Email: michel.veillette@trilliantinc.com 2008 Alexander Pelov 2009 Acklio 2010 2bis rue de la Chataigneraie 2011 Cesson-Sevigne, Bretagne 35510 2012 France 2014 Email: a@ackl.io