idnits 2.17.1 draft-vanderstok-core-comi-10.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 : ---------------------------------------------------------------------------- No issues found here. 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 (October 30, 2016) is 2732 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 1864, but not defined == Missing Reference: 'SID' is mentioned on line 1917, but not defined ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-06) exists of draft-becker-core-coap-sms-gprs-05 ** Downref: Normative reference to an Informational draft: draft-vanderstok-core-etch (ref. 'I-D.vanderstok-core-etch') == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-02 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-06 Summary: 3 errors (**), 0 flaws (~~), 8 warnings (==), 3 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: May 3, 2017 YumaWorks 6 M. Veillette 7 Trilliant Networks Inc. 8 A. Pelov 9 Acklio 10 October 30, 2016 12 CoAP Management Interface 13 draft-vanderstok-core-comi-10 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 the 24 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 May 3, 2017. 48 Copyright Notice 50 Copyright (c) 2016 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 data node instance identifier . . . . . . 8 70 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 8 71 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 8 72 5. /c Function Set . . . . . . . . . . . . . . . . . . . . . . . 10 73 5.1. Using the 'k' query parameter . . . . . . . . . . . . . . 11 74 5.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 13 75 5.2.1. Using the 'c' query parameter . . . . . . . . . . . . 13 76 5.2.2. Using the 'd' query parameter . . . . . . . . . . . . 14 77 5.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 14 78 5.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 16 79 5.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 17 80 5.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 17 81 5.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 17 82 5.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 18 83 5.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 19 84 5.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 20 85 5.4. Full Data Store access . . . . . . . . . . . . . . . . . 20 86 5.4.1. Full Data Store examples . . . . . . . . . . . . . . 21 87 5.5. Notify functions . . . . . . . . . . . . . . . . . . . . 22 88 5.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 23 89 5.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 23 90 5.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 24 91 6. Access to MIB Data . . . . . . . . . . . . . . . . . . . . . 24 92 7. Use of Block . . . . . . . . . . . . . . . . . . . . . . . . 26 93 8. Resource Discovery . . . . . . . . . . . . . . . . . . . . . 26 94 9. Error Return Codes . . . . . . . . . . . . . . . . . . . . . 28 95 10. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 29 96 11. Security Considerations . . . . . . . . . . . . . . . . . . . 30 97 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 98 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31 99 14. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 32 100 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 101 15.1. Normative References . . . . . . . . . . . . . . . . . . 35 102 15.2. Informative References . . . . . . . . . . . . . . . . . 37 103 Appendix A. YANG example specifications . . . . . . . . . . . . 38 104 A.1. ietf-system . . . . . . . . . . . . . . . . . . . . . . . 39 105 A.2. server list . . . . . . . . . . . . . . . . . . . . . . . 40 106 A.3. interfaces . . . . . . . . . . . . . . . . . . . . . . . 40 107 A.4. Example-port . . . . . . . . . . . . . . . . . . . . . . 41 108 A.5. ipNetToMediaTable . . . . . . . . . . . . . . . . . . . . 42 109 Appendix B. Comparison with LWM2M . . . . . . . . . . . . . . . 43 110 B.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 43 111 B.2. Defining Management Resources . . . . . . . . . . . . . . 44 112 B.3. Identifying Management Resources . . . . . . . . . . . . 45 113 B.4. Encoding of Management Resources . . . . . . . . . . . . 45 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 116 1. Introduction 118 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 119 Machine to Machine (M2M) applications such as smart energy and 120 building control. Constrained devices need to be managed in an 121 automatic fashion to handle the large quantities of devices that are 122 expected in future installations. The messages between devices need 123 to be as small and infrequent as possible. The implementation 124 complexity and runtime resources need to be as small as possible. 126 This draft describes the CoAP Management Interface which uses CoAP 127 methods to access structured data defined in YANG [RFC6020]. This 128 draft is complementary to the draft [I-D.ietf-netconf-restconf] which 129 describes a REST-like interface called RESTCONF, which uses HTTP 130 methods to access structured data defined in YANG. 132 The use of standardized data sets, specified in a standardized 133 language such as YANG, promotes interoperability between devices and 134 applications from different manufacturers. A large amount of 135 Management Information Base (MIB) [RFC3418] [mibreg] specifications 136 already exists for monitoring purposes. This data can be accessed in 137 RESTCONF or CoMI if the server converts the SMIv2 modules to YANG, 138 using the mapping rules defined in [RFC6643]. 140 CoMI and RESTCONF are intended to work in a stateless client-server 141 fashion. They use a single round-trip to complete a single editing 142 transaction, where NETCONF needs up to 10 round trips. 144 To promote small packets, CoMI uses a YANG to CBOR mapping 145 [I-D.ietf-core-yang-cbor] and an additional "data-identifier string- 146 to-number conversion" to minimize CBOR payloads and URI length. 148 1.1. Terminology 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 152 document are to be interpreted as described in [RFC2119]. 154 Readers of this specification should be familiar with all the terms 155 and concepts discussed in [RFC3410], [RFC3416], and [RFC2578]. 157 The following terms are defined in the NETCONF protocol [RFC6241]: 158 client, configuration data, datastore, and server. 160 The following terms are defined in the YANG data modelling language 161 [RFC6020]: container, data node, key, key leaf, leaf, leaf-list, and 162 list. 164 The following terms are defined in RESTCONF protocol 165 [I-D.ietf-netconf-restconf]: data resource, datastore resource, edit 166 operation, query parameter, and target resource. 168 The following terms are defined in this document: 170 data node instance: An instance of a data node specified in a YANG 171 module present in the server. The instance is stored in the 172 memory of the server. 174 Notification instance: An instance of a schema node of type 175 notification, specified in a YANG module present in the server. 176 The instance is generated in the server at the occurrence of the 177 corresponding event and appended to a stream. 179 YANG schema item identifier: Numeric identifier which replaces the 180 name identifying a YANG item ( see section 6.2 of [RFC7950]) (data 181 node, RPC, Action, Notification, Identity, Module name, Submodule 182 name, Feature). 184 list instance identifier: Handle used to identify a YANG data node 185 that is an instance of a YANG "list" specified with the values of 186 the key leaves of the list. 188 single instance identifier: Handle used to identify a specific data 189 node which can be instantiated only once. This includes data 190 nodes defined at the root of a YANG module or submodule and data 191 nodes defined within a container. This excludes data nodes 192 defined within a list or any children of these data nodes. 194 instance identifier: List instance identifier or single instance 195 identifier. 197 data node value: Value assigned to a data node instance. Data node 198 values are encoded based on the rules defined in section 4 of 199 [I-D.ietf-core-yang-cbor]. 201 set of data node instances: Represents the payload of CoAP methods 202 when a collection is sent or returned. There are two 203 possibilities, dependent on Request context : 205 1. CBOR array of pair(s) 207 2. CBOR map of pair(s) 209 The following list contains the abbreviations used in this document. 211 SID: YANG Schema Item iDentifier. 213 2. CoMI Architecture 215 This section describes the CoMI architecture to use CoAP for the 216 reading and modifying of instrumentation variables used for the 217 management of the instrumented node. 219 Client 220 +--------------------------------------------------------------+ 221 | +----------------+ +----------------+ | 222 | | SMIv2 | > | YANG | > COAP | 223 | |specification(2)| |specification(1)| Request(3) | 224 | +----------------+ +----------------+[ * | 225 +-----------------------------*-----------[---------*----------+ 226 * [ * 227 * [ +-----------+ 228 mapping * security[ | Network | 229 * (8) [ | packet(4) | 230 * [ +-----------+ 231 Server * [ * 232 +-----------------------------*-----------[---------*----------+ 233 | * [ * | 234 | * Retrieval, | 235 | * Modification(5) | 236 | \*/ * | 237 | +-------------------------------------------------*--------+ | 238 | | +--------------+ +------------+ | | 239 | | |configuration | |Operational | | | 240 | | | (6b) | | state(6a) | | | 241 | | +--------------+ +------------+ | | 242 | | datastore (6) * | | 243 | +-------------------------------------------------*--------+ | 244 | * | 245 | Variable | 246 | Instrumentation(7)| 247 +--------------------------------------------------------------+ 249 Figure 1: Abstract CoMI architecture 251 Figure 1 is a high level representation of the main elements of the 252 CoAP management architecture. A client sends requests as payload in 253 packets over the network to a managed constrained node. 255 The different numbered components of Figure 1 are discussed according 256 to component number. 258 (1) YANG specification: contains a set of named and versioned 259 modules. 261 (2) SMIv2 specification: A named module specifies a set of variables 262 and "conceptual tables". There is an algorithm to translate SMIv2 263 specifications to YANG specifications. 265 (3) CoAP request: The CoAP request needs a Universal Resource 266 Identifier (URI). The CoMI client sends request messages and 267 receives response messages. 269 (4) Network packet: The payload contains CBOR encoded YANG data node 270 instances. 272 (5) Retrieval, modification: The server needs to parse the CBOR 273 encoded message and identify the corresponding instances in the 274 datastore. 276 (6) Datastore: The store is composed of two parts: Operational state 277 and Configuration datastore. 279 (7) Variable instrumentation: This code depends on implementation of 280 drivers and other node specific aspects. 282 (8) Security: The server MUST prevent unauthorized users from 283 reading or writing any data resources. CoMI relies on the 284 security measures specified for CoAP such as DTLS [RFC6347]. 286 2.1. Major differences between RESTCONF and CoMI 288 CoMI uses CoAP/UDP as transport protocol and CBOR as payload format 289 [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as transport 290 protocol and JSON [RFC7159] or XML [XML] as payload formats. CoMI 291 encodes YANG identifier strings as numbers, where RESTCONF does not. 293 CoMI uses the methods FETCH and iPATCH, not used by RESTCONF. 294 RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not used 295 by CoMI. 297 CoAP servers MUST maintain the order of user-ordered data. CoMI does 298 not support insert-mode (first, last, before, after) and insertion- 299 point (before, after) which are supported by RESTCONF. Many CoAP 300 servers will not support date and time functions. For that reason 301 CoMI does not support the start, stop options for events. 303 CoMI servers only implement the efficient "trim" mode for default 304 values 306 The CoMI servers do not support the following RESTCONF functionality: 308 o The "fields" query parameter to query multiple instances. 310 o The 'filter' query that involves XML parsing, 'content', and 311 'depth', query parameters. 313 2.2. Compression of data node instance identifier 315 In the YANG specification the nodes are identified with a name 316 string. The name string contains the module name, hierarchy of 317 container/list names, and the leaf name. 319 In order to significantly reduce the size of identifiers used in 320 CoMI, numeric object identifiers are used instead of these strings. 321 The specific encoding of the object identifiers is not hard-wired in 322 the protocol. 324 Examples of object identifier encoding formats are described in 325 [I-D.somaraju-core-sid]. 327 3. Example syntax 329 This section presents the notation used for the examples. The YANG 330 specifications that are used throughout this document are shown in 331 Appendix A. The example specifications are taken over from existing 332 modules and annotated with SIDs. The values of the SIDs are taken 333 over from [yang-cbor]. 335 CBOR is used for the payload of the request- and the return-packets. 336 The CBOR syntax of the YANG payloads is specified in [RFC7049]. The 337 payload examples are notated in Diagnostic notation (defined in 338 section 6 of [RFC7049]) that can be automatically converted to CBOR. 340 A YANG leaf (YANG item identifier, YANG item value) pair is mapped to 341 a CBOR(key, value) pair. The YANG leaf value is encoded as specified 342 in [I-D.ietf-core-yang-cbor]. The YANG leaf identifier can be a SID 343 or a CBOR array with the structure [SID, key1, key2], where SID is a 344 list identifier and the key values specify the list instance. The 345 YANG leaf value can be a simple value, a CBOR array, or a CBOR map. 347 Delta encoding is used for the SIDs. The notation +n is used when 348 the SID has the value PREC+n where PREC is the SID of the parent 349 container, or PREC is the SID of the preceding entity in a CBOR 350 array. 352 In all examples the resource path in the URI is expressed as a SID, 353 represented as a base64 number. SIDs in the payload are represented 354 as decimal numbers. 356 4. CoAP Interface 358 In CoAP a group of links can constitute a Function Set. The format of 359 the links is specified in [I-D.ietf-core-interfaces]. This note 360 specifies a Management Function Set. CoMI end-points that implement 361 the CoMI management protocol support at least one discoverable 362 management resource of resource type (rt): core.c, with path: /c, 363 where c is short-hand for CoMI. The path root /c is recommended but 364 not compulsory (see Section 8). 366 The path prefix /c has resources accessible with the following three 367 paths: 369 /c: YANG-based data with path "/c" and using CBOR content encoding 370 format. This path represents a datastore resource which contains 371 YANG data resources as its descendant nodes. The data nodes are 372 identified with their SID with format /c/SID. 374 /c/mod.uri: URI identifying the location of the server module 375 information, with path "/c/mod.uri" and CBOR content format. This 376 YANG data is encoded with plain identifier strings, not YANG 377 encoded values. An Entity Tag MUST be maintained for this 378 resource by the server, which MUST be changed to a new value when 379 the set of YANG modules in use by the server changes. 381 /c/s: String identifying the default stream resource to which YANG 382 notification instances are appended. Notification support is 383 optional, so this resource will not exist if the server does not 384 support any notifications. 386 The mapping of YANG data node instances to CoMI resources is as 387 follows: A YANG module describes a set of data trees composed of YANG 388 data nodes. Every root of a data tree in a YANG module loaded in the 389 CoMI server represents a resource of the server. All data root 390 descendants represent sub-resources. 392 The resource identifiers of the instances of the YANG specifications 393 are encoded YANG identifier strings. When multiple instances of a 394 list node exist, instance selection is possible as described in 395 Section 5.2.4 and Section 5.2.3.1. 397 The profile of the management function set, with IF=core.c, is shown 398 in the table below, following the guidelines of 399 [I-D.ietf-core-interfaces]: 401 +----------------+-------------+----------------+-------------------+ 402 | name | path | rt | Data Type | 403 +----------------+-------------+----------------+-------------------+ 404 | Management | /c | core.c | n/a | 405 | | | | | 406 | Data | /c | core.c.data | application/cbor | 407 | | | | | 408 | Module Set URI | /c/mod.uri | core.c.moduri | application/cbor | 409 | | | | | 410 | Events | /c/s | core.c.stream | application/cbor | 411 +----------------+-------------+----------------+-------------------+ 413 5. /c Function Set 415 The /c Function Set provides a CoAP interface to manage YANG servers. 417 The methods used by CoMI are: 419 +-----------+-----------------------------------------------------+ 420 | Operation | Description | 421 +-----------+-----------------------------------------------------+ 422 | GET | Retrieve the datastore resource or a data resource | 423 | | | 424 | FETCH | Retrieve partial data resources | 425 | | | 426 | POST | Create a data resource, invoke RPC | 427 | | | 428 | PUT | Create or replace a data resource | 429 | | | 430 | iPATCH | Idem-potently replace a data resource partially | 431 | | | 432 | DELETE | Delete a data resource | 433 +-----------+-----------------------------------------------------+ 435 There is one query parameters for the GET, PUT, POST, and DELETE 436 methods. 438 +-----------------+------------------------------------+ 439 | Query Parameter | Description | 440 +-----------------+------------------------------------+ 441 | k | Select an instance of a list node | 442 +-----------------+------------------------------------+ 444 This parameter is not used for FETCH and iPATCH, because their 445 request payloads support list instance selection. 447 5.1. Using the 'k' query parameter 449 The "k" (key) parameter specifies the instance of a list node. The 450 SID in the URI is followed by the (?k=key1, key2,..). Where SID 451 identifies a list node, and key1, key2 are the values of the key 452 leafs that specify an instance of the list. 454 Key values are encoded using the rules defined in the following 455 table: 457 +-----------------------+------------------+------------------------+ 458 | YANG datatype | Binary | Text representation | 459 | | representation | | 460 +-----------------------+------------------+------------------------+ 461 | uint8,uint16,unit32, | CBOR unsigned | int_to_text(number) | 462 | uint64 | integer | | 463 | | | | 464 | int8, int16,int32, | CBOR negative | Base64 (CBOR | 465 | int64 | integer | representation) | 466 | | | | 467 | | CBOR unsigned | | 468 | | integer | | 469 | | | | 470 | decimal64 | CBOR decimal | base64 (CBOR | 471 | | fractions | representation | 472 | | | | 473 | string | CBOR text or | text | 474 | | string | | 475 | | | | 476 | boolean | CBOR false or | "0" or "1" | 477 | | true | | 478 | | | | 479 | enumeration | CBOR unsigned | int_to_text (number) | 480 | | integer | | 481 | | | | 482 | bits | CBOR byte string | Base64 (CBOR | 483 | | | representation) | 484 | | | | 485 | binary | CBOR byte string | Base64 (CBOR | 486 | | | representation) | 487 | | | | 488 | identityref | CBOR unsigned | int_to_text (number) | 489 | | integer | | 490 | | | | 491 | union | | Base64 (CBOR | 492 | | | representation) | 493 | | | | 494 | List instance | CBOR unsigned | Base64 (CBOR | 495 | identifier | integer | representation) | 496 | | | | 497 | List instance | CBOR array | Base64 (CBOR | 498 | identifier | | representation) | 499 +-----------------------+------------------+------------------------+ 501 5.2. Data Retrieval 503 One or more data node instances can be retrieved by the client. The 504 operation is mapped to the GET method defined in section 5.8.1 of 505 [RFC7252] and to the FETCH method defined in section 2 of 506 [I-D.vanderstok-core-etch]. 508 It is possible that the size of the payload is too large to fit in a 509 single message. In the case that management data is bigger than the 510 maximum supported payload size, the Block mechanism from [RFC7959] is 511 used, as explained in more detail in Section 7. 513 CoMI uses the FETCH payload for filtering sub-trees and retrieving 514 only a subset that a managing application is interested in. 516 There is one additional query parameters for the GET and FETCH 517 methods. 519 +-------------+-----------------------------------------------------+ 520 | Query | Description | 521 | Parameter | | 522 +-------------+-----------------------------------------------------+ 523 | c | Request to select configuration and non- | 524 | | configuration nodes (GET and FETCH) | 525 | | | 526 | d | Control retrieval of default values. | 527 +-------------+-----------------------------------------------------+ 529 5.2.1. Using the 'c' query parameter 531 The 'c' (content) parameter controls how descendant nodes of the 532 requested data nodes will be processed in the reply. 534 The allowed values are: 536 +-------+------------------------------------------------------+ 537 | Value | Description | 538 +-------+------------------------------------------------------+ 539 | c | Return only configuration descendant data nodes | 540 | | | 541 | n | Return only non-configuration descendant data nodes | 542 | | | 543 | a | Return all descendant data nodes | 544 +-------+------------------------------------------------------+ 546 This parameter is only allowed for GET and FETCH methods on datastore 547 and data resources. A 4.00 Bad Request error is returned if used for 548 other methods or resource types. 550 If this query parameter is not present the default value is "a". 552 5.2.2. Using the 'd' query parameter 554 The "d" (with-defaults) parameter controls how the default values of 555 the descendant nodes of the requested data nodes will be processed. 557 The allowed values are: 559 +-------+-----------------------------------------------------------+ 560 | Value | Description | 561 +-------+-----------------------------------------------------------+ 562 | a | All data nodes are reported| Defined as 'report-all' in | 563 | | section 3.1 of [RFC6243]. | 564 | | | 565 | t | Data nodes set to the YANG default are not reported. | 566 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 567 +-------+-----------------------------------------------------------+ 569 If the target of a GET or FETCH method is a data node that represents 570 a leaf that has a default value, and the leaf has not been given a 571 value yet, the server MUST return the leaf. 573 If the target of a GET method is a data node that represents a 574 container or list that has any child resources with default values, 575 for the child resources that have not been given value yet, the 576 server MUST not return the child resource if this query parameter is 577 set to 't' and MUST return the child resource if this query parameter 578 is set to 'a'. 580 If this query parameter is not present, the default value is 't'. 582 5.2.3. GET 584 A request to read the values of instances of a management object is 585 sent with a confirmable CoAP GET message. A single object is 586 specified in the URI path prefixed with /c. 588 FORMAT: 589 GET /c/ 591 2.05 Content (Content-Format: application/cbor) 592 594 The specified object MUST be a complete object. Accordingly, the 595 returned payload is composed of all the leaves associated with the 596 object. 598 The instance identifier is a SID or a SID followed by the "k" query 599 parameter. 601 5.2.3.1. GET Examples 603 Using for example the current-datetime leaf from Appendix A.1, a 604 request is sent to retrieve the value of system-state/clock/current- 605 datetime specified in container system-state. The ID of system- 606 state/clock/current-datetime is 1719, encoded in base64 this yields 607 a3. The answer to the request returns a , transported as a 608 single CBOR string item. 610 REQ: GET example.com/c/a3 612 RES: 2.05 Content (Content-Format: application/cbor) 613 "2014-10-26T12:16:31Z" 615 For example, the GET of the clock node (ID = 1717; base64: a1), sent 616 by the client, results in the following returned value sent by the 617 server, transported as a CBOR map containing 2 pairs: 619 REQ: GET example.com/c/a1 621 RES: 2.05 Content (Content-Format: application/cbor) 622 { 623 +2 : "2014-10-26T12:16:51Z", # ID 1719 624 +1 : "2014-10-21T03:00:00Z" # ID 1718 625 } 627 A "list" node can have multiple instances. Accordingly, the returned 628 payload of GET is composed of all the instances associated with the 629 selected list node. 631 For example, look at the example in Appendix A.3. The GET of the 632 /interfaces/interface/ (with identifier 1533, base64: Bf0) results in 633 the following returned payload, transported as a CBOR array with 2 634 elements. 636 REQ: GET example.com/c/Bf0 638 RES: 2.05 Content (Content-Format: application/cbor) 639 [ 640 {+4 : "eth0", # name (ID 1537) 641 +1 : "Ethernet adaptor", # description (ID 1534) 642 +5 : 1179, # type, (ID 1538)identity 643 # ethernetCsmacd (ID 1179) 644 +2 : true # enabled ( ID 1535) 645 }, 646 {+4 : "eth1", # name 647 +1 : "Ethernet adaptor", # description 648 +5 : 1179, # type, identity ethernetCsmacd (ID 1179) 649 +2 : false # enabled 650 ] 652 It is equally possible to select a leaf of one instance of a list or 653 a complete instance container with GET. The instance identifier is 654 the numeric identifier of the list followed by the specification of 655 the values for the key leafs that uniquely identify the list 656 instance. The instance identifier looks like: SID?k=key-value. The 657 key of "interface" is the "name" leaf. The example below requests 658 the description leaf of the instance with name="eth0" (ID=1534, 659 base64: Bf4). The value of the description leaf is returned. 661 REQ: GET example.com/c/Bf4?k="eth0" 663 RES: 2.05 Content (Content-Format: application/cbor) 664 "Ethernet adaptor" 666 5.2.4. FETCH 668 The FETCH is used to retrieve a list of data node values. The FETCH 669 Request payload contains a CBOR list of instance identifiers. 671 FORMAT: 672 FETCH /c/ Content-Format (application/YANG-fetch+cbor) 673 675 2.05 Content (Content-Format: application/YANG-patch+cbor) 676 678 The instance identifier is a SID or a CBOR array containing the SID 679 followed by key values that identify the list instance (sec 5.13.1 of 680 [I-D.ietf-core-yang-cbor]. In the payload of the returned data node 681 values, delta encoding is used as described in 682 [I-D.ietf-core-yang-cbor]. 684 5.2.4.1. FETCH examples 686 The example uses the current-datetime leaf and the interface list 687 from Appendix A.1. In the following example the value of current- 688 datetime (ID 1719)and the interface list (ID 1533) instance 689 identified with name="eth0" are queried. 691 FETCH /c Content-Format (application/YANG-fetch+cbor) 692 [ 1719, # ID 1719 693 [-186, "eth0"] # ID 1533 with name = "eth0" 694 ] 696 2.05 Content Content-Format (application/YANG-patch+cbor) 697 [ 698 "2014-10-26T12:16:31Z", 699 { 700 +4 : "eth0", # name (ID 1537) 701 +1 : "Ethernet adaptor", # description (ID 1534) 702 +5 : 1179, # type (ID 1538), identity ethernetCsmacd 703 +2 : true # enabled (ID 1535) 704 } 706 5.3. Data Editing 708 CoMI allows datastore contents to be created, modified and deleted 709 using CoAP methods. 711 5.3.1. Data Ordering 713 A CoMI server SHOULD preserve the relative order of all user-ordered 714 list and leaf-list entries that are received in a single edit 715 request. These YANG data node types are encoded as arrays so 716 messages will preserve their order. 718 5.3.2. POST 720 Data resource instances are created with the POST method. The CoAP 721 POST operation is used in CoMI for creation of data resources and the 722 invocation of "ACTION" and "RPC" resources. Refer to Section 5.6 for 723 details on "ACTION" and "RPC" resources. 725 A request to create the values of an instance of a container or leaf 726 is sent with a confirmable CoAP POST message. A single SID is 727 specified in the URI path prefixed with /c. 729 FORMAT: 730 POST /c/ Content-Format(application/cbor) 731 733 2.01 Created (Content-Format: application/cbor) 735 If the data resource already exists, then the POST request MUST fail 736 and a "4.09 Conflict" status-line MUST be returned 738 The instance identifier is a SID or a SID followed by the "k" query 739 parameter. 741 5.3.2.1. Post example 743 The example uses the interface list from Appendix A.1. Example is 744 creating a new version of the container interface (ID = 1533): 746 FORMAT: 747 POST /c/Bf0 Content-Format(application/cbor) 748 { 749 +4 : "eth0", # name (ID 1537) 750 +1 : "Ethernet adaptor", # description (ID 1534) 751 +5 : 1179, # type (ID 1538), identity 752 # ethernetCsmacd (ID 1179) 753 +2 : true # enabled (ID 1535) 754 } 755 2.01 Created (Content-Format: application/cbor) 757 5.3.3. PUT 759 Data resource instances are created or replaced with the PUT method. 760 The PUT operation is supported in CoMI. A request to set the value 761 of an instance of data node is sent with a confirmable CoAP PUT 762 message. 764 FORMAT: 765 PUT /c/ Content-Format(application/cbor) 766 768 2.01 Created 770 The instance identifier is a SID or a SID followed by the "k" query 771 parameter. 773 5.3.3.1. PUT example 775 The example uses the interface list from Appendix A.1. Example is 776 renewing an instance of the list interface (ID = 1533) with key 777 name="eth0": 779 FORMAT: 780 PUT /c/Bf0?k="eth0" Content-Format(application/cbor) 781 { 782 +4 : "eth0", # name (ID 1537) 783 +1 : "Ethernet adaptor", # description (ID 1534) 784 +5 : 1179, # type (ID 1538), identity 785 # ethernetCsmacd ( ID 1179) 786 +2 : true # enabled (ID 1535) 787 } 788 2.04 Changed 790 5.3.4. iPATCH 792 One or multiple data resource instances are replaced with the idem- 793 potent iPATCH method [I-D.vanderstok-core-etch]. A request to set 794 the values of instances of a subset of the values of the resource is 795 sent with a confirmable CoAP iPATCH message. 797 There are no query parameters for the iPATCH method. 799 The processing of the iPATCH command is specified by the CBOR 800 payload. The CBOR patch payload describes the changes to be made to 801 target YANG data nodes REF TO BE DEFINED. If the CBOR patch payload 802 contains data node instances that are not present in the target, 803 these instances are added or silently ignored dependent of the 804 payload information. If the target contains the specified instance, 805 the contents of the instances are replaced with the values of the 806 payload. Null values indicate the removal of existing values. 808 FORMAT: 809 iPATCH /c Content-Format(application/YANG-patch+cbor) 810 812 2.04 Changed 814 5.3.4.1. iPATCH example 816 The example uses the interface list from Appendix A.3, and the 817 timezone-utc-offset leaf from Appendix A.1. In the example one leaf 818 (timezone-utc-offset ) and one container (interface) instance are 819 changed. 821 iPATCH /c Content-Format(application/YANG-patch+cbor) 822 [ 823 [1533, "eth0"] , # interface (ID = 1533) 824 { 825 +4 : "eth0", # name (ID 1537) 826 +1 : "Ethernet adaptor", # description (ID 1534) 827 +5 : 1179, # type (ID 1538), 828 # identity ethernetCsmacd 829 +2 : true # enabled (ID 1535) 830 } 831 +203 , 60 # timezone-utc-offset (delta = 1736 - 1533) 832 ] 834 2.04 Changed 836 5.3.5. DELETE 838 Data resource instances are deleted with the DELETE method. The 839 RESTCONF DELETE operation is supported in CoMI. 841 FORMAT: 842 Delete /c/ 844 2.02 Deleted 846 The instance identifier is a SID or a SID followed by the "k" query 847 parameter. 849 5.3.5.1. DELETE example 851 The example uses the interface list from Appendix A.3. Example is 852 deleting an instance of the container interface (ID = 1533): 854 FORMAT: 855 DELETE /c/Bf0?k="eth0" 857 2.02 Deleted 859 5.4. Full Data Store access 861 The methods GET, PUT, POST, and DELETE can be used to return, 862 replace, create, and delete the whole data store respectively. 864 FORMAT: 865 GET /c 866 2.05 Content (Content-Format: application/cbor) 867 869 PUT /c 870 (Content-Format: application/cbor) 871 872 2.04 Changed 874 POST /c 875 (Content-Format: application/cbor) 876 877 2.01 Created 879 DELETE /c 880 (Content-Format: application/cbor) 881 882 2.02 Deleted 884 The array of data node instances represents an array of all root 885 nodes in the data store after the PUT, POST and GET method 886 invocations. 888 5.4.1. Full Data Store examples 890 The example uses the interface list and the clock container from 891 Appendix A.3. Assume that the data store contains two root objects: 892 the list interface (ID 1533) with one instance and the container 893 Clock (ID 1717). After invocation of GET an array with these two 894 objects is returned: 896 GET /c 897 2.05 Content Content-Format (application/YANG-patch+cbor) 898 [ 899 1717: 900 { +1: "2016-10-26T12:16:31Z", # current-datetime (ID 501) 901 +2: "2014-10-05T09:00:00Z" # boot-datetime (ID 502) 902 } 903 -186: # clock (ID 1533) 904 { 905 +4 : "eth0", # name (ID 1537) 906 +1 : "Ethernet adaptor", # description (ID 1534) 907 +5 : 1179, # type (ID 1538), identity: 908 # ethernetCsmacd (ID 1179) 909 +2 : true # enabled (ID 1535) 910 } 911 ] 913 5.5. Notify functions 915 Notification by the server to a selection of clients when an event 916 occurs in the server is an essential function for the management of 917 servers. CoMI allows events specified in YANG [RFC5277] to be 918 notified to a selection of requesting clients. The server appends 919 newly generated events to a stream. There is one, so-called 920 "default", stream in a CoMI server. The /c/s resource identifies the 921 default stream. The server MAY create additional stream resources. 922 When a CoMI server generates an internal event, it is appended to the 923 chosen stream, and the content of a notification instance is ready to 924 be sent to all CoMI clients which observe the chosen stream resource. 926 Reception of generated notification instances is enabled with the 927 CoAP Observe [RFC7641] function. The client subscribes to the 928 notifications by sending a GET request with an "Observe" option, 929 specifying the /c/s resource when the default stream is selected. 931 Every time an event is generated, the chosen stream is cleared, and 932 the generated notification instance is appended to the chosen 933 stream(s). After appending the instance, the contents of the 934 instance is sent to all clients observing the modified stream. 936 FORMAT: 937 Get / 938 Content-Format(application/YANG-patch+cbor) Observe(0) 940 2.05 Content Content-Format(application/YANG-patch+cbor) 941 942 TODO: addition of generic information 944 5.5.1. Notify Examples 946 Suppose the server generates the event specified in Appendix A.4. By 947 executing a GET on the /c/s resource the client receives the 948 following response: 950 GET /c/s Observe(0) Token(0x93) 952 2.05 Content Content-Format(application/YANG-patch+cbor) 953 Observe(12) Token(0x93) 954 { 955 2600 : # example-port-fault (ID 2600) 956 { 957 +1 : "0/4/21", # port-name (ID 2601) 958 +2 : "Open pin 2", # port-fault (ID 2602) 959 }, 960 2600 : # example-port-fault (ID 2600) 961 { 962 +1 : "1/4/21", # port-name (ID 2601) 963 +2 : "Open pin 5", # port-fault (ID 2602) 964 } 966 } 968 In the example, the request returns a success response with the 969 contents of the last two generated events. Consecutively the server 970 will regularly notify the client when a new event is generated. 972 To check that the client is still alive, the server MUST send 973 confirmable notifications once in a while. When the client does not 974 confirm the notification from the server, the server will remove the 975 client from the list of observers [RFC7641]. 977 In the registration request, the client MAY include a "Response-To- 978 Uri-Host" and optionally "Response-To-Uri-Port" option as defined in 979 [I-D.becker-core-coap-sms-gprs]. In this case, the observations 980 SHOULD be sent to the address and port indicated in these options. 981 This can be useful when the client wants the managed device to send 982 the trap information to a multicast address. 984 5.6. RPC statements 986 The YANG "action" and "RPC" statements specify the execution of a 987 Remote procedure Call (RPC) in the server. It is invoked using a 988 POST method to the "Action" or "RPC" identifier. The Request payload 989 contains the values assigned to the input container when specified 990 with the action station. The Response payload contains the values of 991 the output container when specified with the action statement. 993 The returned success response code is 2.05 Content. 995 FORMAT: 996 POST /c/ 997 Content-Format(application/YANG-patch+cbor) 998 1000 2.05 Content Content-Format (application/YANG-patch+cbor) 1001 1003 There "k" query parameter is allowed for the POST method when used 1004 for RPC invocation. 1006 5.6.1. RPC Example 1008 The example is based on the YANG action specification of 1009 Appendix A.2. A server list is specified and the action "reset", 1010 that is part of a "server instance" with key value "myserver", is 1011 invoked. 1013 POST /c/B24?k="myserver" 1014 Content-Format(application/YANG-patch+cbor) 1015 { 1016 +1 : "2016-02-08T14:10:08Z09:00" # reset-at (ID 1903) 1017 } 1019 2.05 Content Content-Format(application/YANG-patch+cbor) 1020 { 1021 +2 : "2016-02-08T14:10:08Z09:18" # reset-finished-at (ID 1904) 1022 } 1024 6. Access to MIB Data 1026 Appendix A.5 shows a YANG specification mapped from the SMI 1027 specification "ipNetToPhysicalTable". The following example shows 1028 the YANG "ipNetToPhysicalTable" with 2 instances, using diagnostic 1029 notation encoding and annotating the leaf names with SID numbers. 1031 { 1032 "IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry" : # ID 302 1033 [ 1034 { 1035 "ipNetToPhysicalIfIndex" : 1, # ID 303 1036 "ipNetToPhysicalNetAddressType" : "ipv4", # ID 304 1037 "ipNetToPhysicalNetAddress" : "10.0.0.51", # ID 305 1038 "ipNetToPhysicalPhysAddress" : "00:00:10:01:23:45", # ID 306 1039 "ipNetToPhysicalLastUpdated" : "2333943", # ID 307 1040 "ipNetToPhysicalType" : "static", # ID 308 1041 "ipNetToPhysicalState" : "reachable", # ID 309 1042 "ipNetToPhysicalRowStatus" : "active" # ID 310 1043 }, 1044 { 1045 "ipNetToPhysicalIfIndex" : 1, # ID 303 1046 "ipNetToPhysicalNetAddressType" : "ipv4", # ID 304 1047 "ipNetToPhysicalNetAddress" : "9.2.3.4", # ID 305 1048 "ipNetToPhysicalPhysAddress" : "00:00:10:54:32:10",# ID 306 1049 "ipNetToPhysicalLastUpdated" : "2329836", # ID 307 1050 "ipNetToPhysicalType" : "dynamic", # ID 308 1051 "ipNetToPhysicalState" : "unknown", # ID 309 1052 "ipNetToPhysicalRowStatus" : "active" # ID 310 1053 } 1054 ] 1055 } 1057 In the following example exactly one instance is requested from the 1058 ipNetToPhysicalEntry. The CBOR payload, here represented with 1059 diagnostic JSON, permits to transport the selected instance and 1060 nothing more. 1062 REQ: FETCH example.com/c/ 1063 (Content-Format: application/YANG-fetch+cbor) 1064 [ 1065 302,1,"ipv4",9.2.3.4 1066 ] 1068 RES: 2.05 Content (Content-Format: application/YANG-patch+cbor) 1069 { 1070 +1 : 1, ( ID 303) 1071 +2 : "ipv4", ( ID 304) 1072 +3 : "9.2.3.4", ( ID 305) 1073 +4 : "00:00:10:54:32:10", ( ID 306) 1074 +5 : "2329836", ( ID 307) 1075 +6 : "dynamic", ( ID 308) 1076 +7 : "unknown", ( ID 309) 1077 +8 : "active" ( ID 310) 1078 } 1079 In this example one instance of ipNetToPhysicalTable/ 1080 ipNetToPhysicalEntry that matches the key values (1,"ipv4",9.2.3.4) 1081 is returned. 1083 7. Use of Block 1085 The CoAP protocol provides reliability by acknowledging the UDP 1086 datagrams. However, when large pieces of text need to be transported 1087 the datagrams get fragmented, thus creating constraints on the 1088 resources in the client, server and intermediate routers. The block 1089 option [RFC7959] allows the transport of the total payload in 1090 individual blocks of which the size can be adapted to the underlying 1091 fragment sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1092 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1093 acknowledged to guarantee reliability. 1095 Notice that the Block mechanism splits the data at fixed positions, 1096 such that individual data fields may become fragmented. Therefore, 1097 assembly of multiple blocks may be required to process the complete 1098 data field. 1100 Beware of race conditions. Blocks are filled one at a time and care 1101 should be taken that the whole data representation is sent in 1102 multiple blocks sequentially without interruption. In the server, 1103 values are changed, lists are re-ordered, extended or reduced. When 1104 these actions happen during the serialization of the contents of the 1105 variables, the transported results do not correspond with a state 1106 having occurred in the server; or worse the returned values are 1107 inconsistent. For example: array length does not correspond with 1108 actual number of items. It may be advisable to use CBOR maps or CBOR 1109 arrays of undefined length which are foreseen for data streaming 1110 purposes. 1112 8. Resource Discovery 1114 The presence and location of (path to) the management data are 1115 discovered by sending a GET request to "/.well-known/core" including 1116 a resource type (RT) parameter with the value "core.c" [RFC6690]. 1117 Upon success, the return payload will contain the root resource of 1118 the management data. It is up to the implementation to choose its 1119 root resource, but it is recommended that the value "/c" is used, 1120 where possible. The example below shows the discovery of the 1121 presence and location of management data. 1123 REQ: GET /.well-known/core?rt=core.c 1125 RES: 2.05 Content ; rt="core.c" 1127 Management objects MAY be discovered with the standard CoAP resource 1128 discovery. The implementation can add the encoded values of the 1129 object identifiers to /.well-known/core with rt="core.c.data". The 1130 available objects identified by the encoded values can be discovered 1131 by sending a GET request to "/.well-known/core" including a resource 1132 type (RT) parameter with the value "core.c.data". Upon success, the 1133 return payload will contain the registered encoded values and their 1134 location. The example below shows the discovery of the presence and 1135 location of management data. 1137 REQ: GET /.well-known/core?rt=core.c.data 1139 RES: 2.05 Content ; rt="core.c.data", 1140 ; rt="core.c.data" 1142 Lists of encoded values may become prohibitively long. It is 1143 discouraged to provide long lists of objects on discovery. 1144 Therefore, it is recommended that details about management objects 1145 are discovered by reading the YANG module information stored in the 1146 "ietf-YANG-library" module [I-D.ietf-netconf-restconf]. The resource 1147 "/c/mod.uri" is used to retrieve the location of the YANG module 1148 library. 1150 TODO: additional references using SIDs 1152 The module list can be stored locally on each server, or remotely on 1153 a different server. The latter is advised when the deployment of 1154 many servers are identical. 1156 Local in example.com server: 1158 REQ: GET example.com/c/mod.uri 1160 RES: 2.05 Content (Content-Format: application/cbor) 1161 { 1162 "mod.uri" : "example.com/c/modules" 1163 } 1165 Remote in example-remote-server: 1167 REQ: GET example.com/c/mod.uri 1169 RES: 2.05 Content (Content-Format: application/cbor) 1170 { 1171 "moduri" : "example-remote-server.com/c/group17/modules" 1172 } 1174 Within the YANG module library all information about the module is 1175 stored such as: module identifier, identifier hierarchy, grouping, 1176 features and revision numbers. 1178 9. Error Return Codes 1180 The RESTCONF return status codes defined in section 7 of 1181 [I-D.ietf-netconf-restconf] are used in CoMI error responses, except 1182 they are converted to CoAP error codes. 1184 +-------------------------------+------------------+ 1185 | RESTCONF Status Line | CoAP Status Code | 1186 +-------------------------------+------------------+ 1187 | 100 Continue | none? | 1188 | | | 1189 | 200 OK | 2.05 | 1190 | | | 1191 | 201 Created | 2.01 | 1192 | | | 1193 | 202 Accepted | none? | 1194 | | | 1195 | 204 No Content | 2.04 Changed | 1196 | | | 1197 | 304 Not Modified | 2.03 | 1198 | | | 1199 | 400 Bad Request | 4.00 | 1200 | | | 1201 | 403 Forbidden | 4.03 | 1202 | | | 1203 | 404 Not Found | 4.04 | 1204 | | | 1205 | 405 Method Not Allowed | 4.05 | 1206 | | | 1207 | 409 Conflict | none? | 1208 | | | 1209 | 412 Precondition Failed | 4.12 | 1210 | | | 1211 | 413 Request Entity Too Large | 4.13 | 1212 | | | 1213 | 414 Request-URI Too Large | 4.00 | 1214 | | | 1215 | 415 Unsupported Media Type | 4.15 | 1216 | | | 1217 | 500 Internal Server Error | 5.00 | 1218 | | | 1219 | 501 Not Implemented | 5.01 | 1220 | | | 1221 | 503 Service Unavailable | 5.03 | 1222 +-------------------------------+------------------+ 1224 10. Error Handling 1226 In case a request is received which cannot be processed properly, the 1227 CoMI server MUST return an error message. This error message MUST 1228 contain a CoAP 4.xx or 5.xx response code, and SHOULD include 1229 additional information in the payload. 1231 Such an error message payload is encoded in CBOR, using the following 1232 structure: 1234 errorMsg : ErrorMsg; 1236 *ErrorMsg { 1237 errorCode : uint; 1238 ?errorText : tstr; 1239 } 1241 The variable "errorCode" has one of the values from the table below, 1242 and the OPTIONAL "errorText" field contains a human readable 1243 explanation of the error. 1245 TODO: Alternatives? 1247 +----------------+----------------+---------------------------------+ 1248 | CoMI Error | CoAP Error | Description | 1249 | Code | Code | | 1250 +----------------+----------------+---------------------------------+ 1251 | 0 | 4.00 | General error | 1252 | | | | 1253 | 1 | 4.00 | Malformed CBOR data | 1254 | | | | 1255 | 2 | 4.00 | Incorrect CBOR datatype | 1256 | | | | 1257 | 3 | 4.00 | Unknown MIB variable | 1258 | | | | 1259 | 4 | 4.00 | Unknown conversion table | 1260 | | | | 1261 | 5 | 4.05 | Attempt to write read-only | 1262 | | | variable | 1263 | | | | 1264 | 0..2 | 5.01 | Access exceptions | 1265 | | | | 1266 | 0..18 | 5.00 | SMI error status | 1267 +----------------+----------------+---------------------------------+ 1269 The CoAP error code 5.01 is associated with the exceptions defined in 1270 [RFC3416] and CoAP error code 5.00 is associated with the error- 1271 status defined in [RFC3416]. 1273 11. Security Considerations 1275 For secure network management, it is important to restrict access to 1276 configuration variables only to authorized parties. This requires 1277 integrity protection of both requests and responses, and depending on 1278 the application encryption. 1280 CoMI re-uses the security mechanisms already available to CoAP as 1281 much as possible. This includes DTLS [RFC6347] for protected access 1282 to resources, as well suitable authentication and authorization 1283 mechanisms. 1285 Among the security decisions that need to be made are selecting 1286 security modes and encryption mechanisms (see [RFC7252]). This 1287 requires a trade-off, as the NoKey mode gives no protection at all, 1288 but is easy to implement, whereas the X.509 mode is quite secure, but 1289 may be too complex for constrained devices. 1291 In addition, mechanisms for authentication and authorization may need 1292 to be selected. 1294 CoMI avoids defining new security mechanisms as much as possible. 1295 However some adaptations may still be required, to cater for CoMI's 1296 specific requirements. 1298 12. IANA Considerations 1300 'rt="core.c"' needs registration with IANA. 1302 'rt="core.c.data"' needs registration with IANA. 1304 'rt="core.c.moduri"' needs registration with IANA. 1306 'rt="core.c.stream"' needs registration with IANA. 1308 Content types to be registered: 1310 o application/YANG-patch+cbor 1312 o application/YANG-fetch+cbor 1314 13. Acknowledgements 1316 We are very grateful to Bert Greevenbosch who was one of the original 1317 authors of the CoMI specification and specified CBOR encoding and use 1318 of hashes. 1320 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1321 transported under SNMP. Carsten Bormann has given feedback on the 1322 use of CBOR. 1324 Timothy Carey has provided the text for Appendix B. 1326 The draft has benefited from comments (alphabetical order) by Rodney 1327 Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Juergen 1328 Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes Tschofenig, Michael 1329 Verschoor, and Thomas Watteyne. 1331 14. Changelog 1333 Changes from version 00 to version 01 1335 o Focus on MIB only 1337 o Introduced CBOR, JSON, removed BER 1339 o defined mappings from SMI to xx 1341 o Introduced the concept of addressable table rows 1343 Changes from version 01 to version 02 1345 o Focus on CBOR, used JSON for examples, removed XML and EXI 1347 o added uri-query attributes mod and con to specify modules and 1348 contexts 1350 o Definition of CBOR string conversion tables for data reduction 1352 o use of Block for multiple fragments 1354 o Error returns generalized 1356 o SMI - YANG - CBOR conversion 1358 Changes from version 02 to version 03 1360 o Added security considerations 1362 Changes from version 03 to version 04 1364 o Added design considerations section 1366 o Extended comparison of management protocols in introduction 1368 o Added automatic generation of CBOR tables 1370 o Moved lowpan table to Appendix 1372 Changes from version 04 to version 05 1373 o Merged SNMP access with RESTCONF access to management objects in 1374 small devices 1376 o Added CoMI architecture section 1378 o Added RESTCONf NETMOD description 1380 o Rewrote section 5 with YANG examples 1382 o Added server and payload size appendix 1384 o Removed Appendix C for now. It will be replaced with a YANG 1385 example. 1387 Changes from version 04 to version 05 1389 o Extended examples with hash representation 1391 o Added keys query parameter text 1393 o Added select query parameter text 1395 o Better separation between specification and instance 1397 o Section on discovery updated 1399 o Text on rehashing introduced 1401 o Elaborated SMI MIB example 1403 o YANG library use described 1405 o use of BigEndian/LittleEndian in Hash generation specified 1407 Changes from version 05 to version 06 1409 o Hash values in payload as hexadecimal and in URL in base64 numbers 1411 o Streamlined CoMI architecture text 1413 o Added select query parameter text 1415 o Data editing optional 1417 o Text on Notify added 1419 o Text on rehashing improved with example 1420 Changes from version 06 to version 07 1422 o reduced payload size by removing JSON hierarchy 1424 o changed rehash handling to support small clients 1426 o added LWM2M comparison 1428 o Notification handling as specified in YANG 1430 o Added Patch function 1432 o Rehashing completely reviewed 1434 o Discover type of YANG name encoding 1436 o Added new resource types 1438 o Read-only servers introduced 1440 o Multiple updates explained 1442 Changes from version 07 to version 08 1444 o Changed YANG Hash algorithm to use module name instead of prefix 1446 o Added rehash bit to allow return values to identify rehashed nodes 1447 in the response 1449 o Removed /c/mod.set resource since this is not needed 1451 o Clarified that YANG Hash is done even for unimplemented objects 1453 o YANG lists transported as CBOR maps of maps 1455 o Adapted examples with more CBOR explanation 1457 o Added CBOR code examples in new appendix 1459 o Possibility to use other than default stream 1461 o Added text and examples for Patch payload 1463 o Repaired some examples 1465 o Added appendices on hash clash probability and hash clash storage 1466 overhead 1468 Changes from version 08 to version 09 1470 o Removed hash and YANG to CBOR sections 1472 o removed hashes from examples. 1474 o Added RPC 1476 o Added content query parameter. 1478 o Added default handling. 1480 o Listed differences with RESTCONF 1482 Changes from version 09 to version 10. This is the merge of cool-01 1483 with comi-09. 1485 o Merged with CoOL SIDs 1487 o Introduced iPATCH, PATCH and FETCH 1489 o Update of LWM2M comparison 1491 o Added appendix with module examples 1493 o Removed introductory text 1495 o Removed refernces 1497 15. References 1499 15.1. Normative References 1501 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1502 Requirement Levels", BCP 14, RFC 2119, 1503 DOI 10.17487/RFC2119, March 1997, 1504 . 1506 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1507 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1508 . 1510 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1511 the Network Configuration Protocol (NETCONF)", RFC 6020, 1512 DOI 10.17487/RFC6020, October 2010, 1513 . 1515 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1516 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1517 October 2013, . 1519 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1520 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1521 2014, . 1523 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1524 Application Protocol (CoAP)", RFC 7252, 1525 DOI 10.17487/RFC7252, June 2014, 1526 . 1528 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1529 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1530 . 1532 [I-D.becker-core-coap-sms-gprs] 1533 Becker, M., Li, K., Kuladinithi, K., and T. Poetsch, 1534 "Transport of CoAP over SMS", draft-becker-core-coap-sms- 1535 gprs-05 (work in progress), August 2014. 1537 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1538 the Constrained Application Protocol (CoAP)", RFC 7959, 1539 DOI 10.17487/RFC7959, August 2016, 1540 . 1542 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1543 Application Protocol (CoAP)", RFC 7641, 1544 DOI 10.17487/RFC7641, September 2015, 1545 . 1547 [I-D.ietf-netconf-restconf] 1548 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1549 Protocol", draft-ietf-netconf-restconf-18 (work in 1550 progress), October 2016. 1552 [I-D.vanderstok-core-etch] 1553 Stok, P., Bormann, C., and A. Sehgal, "Patch and Fetch 1554 Methods for Constrained Application Protocol (CoAP)", 1555 draft-vanderstok-core-etch-00 (work in progress), March 1556 2016. 1558 [I-D.somaraju-core-sid] 1559 Somaraju, A., Veillette, M., Pelov, A., Turner, R., and A. 1560 Minaburo, "Structure Identifier (SID)", draft-somaraju- 1561 core-sid-01 (work in progress), July 2016. 1563 [I-D.ietf-core-yang-cbor] 1564 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 1565 Minaburo, "CBOR Encoding of Data Modeled with YANG", 1566 draft-ietf-core-yang-cbor-02 (work in progress), July 1567 2016. 1569 15.2. Informative References 1571 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1572 Schoenwaelder, Ed., "Structure of Management Information 1573 Version 2 (SMIv2)", STD 58, RFC 2578, 1574 DOI 10.17487/RFC2578, April 1999, 1575 . 1577 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 1578 "Introduction and Applicability Statements for Internet- 1579 Standard Management Framework", RFC 3410, 1580 DOI 10.17487/RFC3410, December 2002, 1581 . 1583 [RFC3416] Presuhn, R., Ed., "Version 2 of the Protocol Operations 1584 for the Simple Network Management Protocol (SNMP)", 1585 STD 62, RFC 3416, DOI 10.17487/RFC3416, December 2002, 1586 . 1588 [RFC3418] Presuhn, R., Ed., "Management Information Base (MIB) for 1589 the Simple Network Management Protocol (SNMP)", STD 62, 1590 RFC 3418, DOI 10.17487/RFC3418, December 2002, 1591 . 1593 [RFC4293] Routhier, S., Ed., "Management Information Base for the 1594 Internet Protocol (IP)", RFC 4293, DOI 10.17487/RFC4293, 1595 April 2006, . 1597 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1598 and A. Bierman, Ed., "Network Configuration Protocol 1599 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1600 . 1602 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1603 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1604 . 1606 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1607 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1608 January 2012, . 1610 [RFC6643] Schoenwaelder, J., "Translation of Structure of Management 1611 Information Version 2 (SMIv2) MIB Modules to YANG 1612 Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012, 1613 . 1615 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1616 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1617 . 1619 [I-D.ietf-core-interfaces] 1620 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Reusable 1621 Interface Definitions for Constrained RESTful 1622 Environments", draft-ietf-core-interfaces-06 (work in 1623 progress), October 2016. 1625 [XML] "Extensible Markup Language (XML)", 1626 Web http://www.w3.org/xml. 1628 [OMA] "OMA-TS-LightweightM2M-V1_0-20131210-C", Web 1629 http://technical.openmobilealliance.org/Technical/ 1630 current_releases.aspx. 1632 [OMNA] "Open Mobile Naming Authority (OMNA)", Web 1633 http://http://technical.openmobilealliance.org/Technical/ 1634 technical-information/omna. 1636 [netconfcentral] 1637 "NETCONF Central: library of YANG modules", 1638 Web http://www.netconfcentral.org/modulelist. 1640 [mibreg] "Structure of Management Information (SMI) Numbers (MIB 1641 Module Registrations)", Web 1642 http://www.iana.org/assignments/smi-numbers/ 1643 smi-numbers.xhtml/. 1645 [yang-cbor] 1646 "yang-cbor Registry", Web https://github.com/core-wg/yang- 1647 cbor/tree/master/registry/. 1649 Appendix A. YANG example specifications 1651 This appendix shows 5 YANG example specifications taken over from as 1652 many existing YANG modules. The YANG modules are available from 1653 [netconfcentral]. Each YANG item identifier is accompanied by its 1654 SID shown after the "#" character, taken from [yang-cbor]. 1656 A.1. ietf-system 1658 Taken over from the module ietf-system. 1660 module ietf-system { 1661 container system-state{ # ID 1716 1662 container clock { # ID 1717 1663 leaf current-datetime{ # ID 1719 1664 type YANG:date-and-time 1665 } 1666 leaf boot-datetime{ # ID 1718 1667 type YANG:date-and-time 1668 } 1669 ... 1670 container system { 1671 leaf timezone-name 1672 leaf timezone-utc-offset{ # ID 1736 1673 type int16 1674 } 1675 ... 1676 container ntp { # ID 1750 1677 leaf enabled { # ID 1751 1678 type boolean; 1679 } 1680 list server { # ID 1752 1681 key name; 1682 leaf name { # ID 1755 1683 type string; 1684 } 1685 choice transport { 1686 case udp { 1687 container udp { # ID 1757 1688 leaf address { # ID 1758 1689 type inet:host; 1690 } 1691 leaf port { # ID 1759 1692 type inet:port-number; 1693 } 1694 } 1695 } 1696 } 1697 leaf association-type { # ID 1753 1698 type enumeration { 1699 enum server {} 1700 enum peer {} 1701 enum pool {} 1702 } 1703 } 1704 leaf iburst { # ID 1754 1705 type boolean; 1706 } 1707 leaf prefer { # ID 1756 1708 type boolean; 1709 } 1710 } 1711 } 1712 ... 1713 } 1714 } 1716 A.2. server list 1718 Taken over from module 1720 list server # ID = 1901 1721 { 1722 key name; 1723 leaf name { 1724 type string; 1725 } 1726 action reset { # ID = 1902 1727 input { 1728 leaf reset-at { # ID = 1903 1729 type YANG:date-and-time; 1730 mandatory true; 1731 } 1732 } 1733 output { 1734 leaf reset-finished-at { # ID = 1904 1735 type YANG:date-and-time; 1736 mandatory true; 1737 } 1738 } 1739 } 1740 } 1742 A.3. interfaces 1744 Taken over from module ietf-interfaces. 1746 container interfaces { 1747 list interface { # ID = 1533 1748 key "name"; 1749 leaf name { # ID = 1537 1750 type string; 1751 } 1752 leaf description { # ID = 1534 1753 type string; 1754 } 1756 leaf type { # ID = 1538 1757 type identityref { 1758 base interface-type; 1759 } 1760 mandatory true; 1761 } 1762 leaf enabled { # ID = 1535 1763 type boolean; 1764 default "true"; 1765 } 1767 leaf link-up-down-trap-enable { 1768 if-feature if-mib; 1769 type enumeration { 1770 enum enabled { 1771 value 1; 1772 } 1773 enum disabled { 1774 value 2; 1775 } 1776 } 1777 } } } } 1779 A.4. Example-port 1781 Taken over from module example-port. 1783 module example-port { 1784 ... 1785 prefix ep; 1786 ... 1787 notification example-port-fault { # ID 2600 1788 description 1789 "Event generated if a hardware fault on a 1790 line card port is detected"; 1791 leaf port-name { # ID 2601 1792 type string; 1793 description "Port name"; 1794 } 1795 leaf port-fault { # ID 2601 1796 type string; 1797 description "Error condition detected"; 1798 } 1799 } 1800 } 1802 A.5. ipNetToMediaTable 1804 The YANG translation of the SMI specifying the 1805 ipNetToMediaTable [RFC4293], extended with example SID numbers, 1806 yields: 1808 container IP-MIB { 1809 container ipNetToPhysicalTable { # ID 301 1810 list ipNetToPhysicalEntry { # ID 302 1811 key "ipNetToPhysicalIfIndex 1812 ipNetToPhysicalNetAddressType 1813 ipNetToPhysicalNetAddress"; 1814 leaf ipNetToMediaIfIndex { # ID 303 1815 type: int32; 1816 } 1817 leaf ipNetToPhysicalIfIndex { # ID 304 1818 type if-mib:InterfaceIndex; 1819 } 1820 leaf ipNetToPhysicalNetAddressType { # ID 305 1821 type inet-address:InetAddressType; 1822 } 1823 leaf ipNetToPhysicalPhysAddress { # ID 306 1824 type YANG:phys-address { 1825 length "0..65535"; 1826 } 1827 } 1828 leaf ipNetToPhysicalLastUpdated { # ID 307 1829 type YANG:timestamp; 1830 } 1831 leaf ipNetToPhysicalType { # ID 308 1832 type enumeration { ... } 1833 } 1834 leaf ipNetToPhysicalState { # ID 309 1835 type enumeration { ... } 1836 } 1837 leaf ipNetToPhysicalRowStatus { # ID 310 1838 type snmpv2-tc:RowStatus; 1839 } 1840 } 1841 } 1843 Appendix B. Comparison with LWM2M 1845 B.1. Introduction 1847 CoMI and LWM2M [OMA], both, provide RESTful device management 1848 services over CoAP. Differences between the designs are highlighted 1849 in this section. 1851 The intent of the LWM2M protocol is to provide a single protocol to 1852 control and manage IoT devices. This means the IoT device implements 1853 and uses the same LWM2M agent function for the actuation and sensing 1854 features of the IoT device as well as for the management of the IoT 1855 device. The intent of CoMI Interface as described in the Abstract 1856 section of this document is to provide management of constrained 1857 devices and devices in constrained networks using RESTCONF and YANG. 1858 This implies that the device, although reusing the CoAP protocol, 1859 would need a separate CoAP based agent in the future to control the 1860 actuation and sensing features of the device and another CoMI agent 1861 that performs the management functions. 1863 It should be noted that the mapping of a LWM2M server to YANG is 1864 specified in [YANGlwm2m]. The converted server can be invoked with 1865 CoMI as specified in this document. 1867 For the purposes of managing IoT devices the following points related 1868 to the protocols compare how management resources are defined, 1869 identified, encoded and updated. 1871 B.2. Defining Management Resources 1873 Management resources in LWM2M (LWM2M objects) are defined using a 1874 standardized number. When a new management resource is defined, 1875 either by a standards organization or a private enterprise, the 1876 management resource is registered with the Open Mobile Naming 1877 Authority [OMNA] in order to ensure different resource definitions do 1878 not use the same identifier. CoMI, by virtue of using YANG as its 1879 data modeling language, allows enterprises and standards 1880 organizations to define new management resources (YANG nodes) within 1881 YANG modules without having to register each individual management 1882 resource. Instead YANG modules are scoped within a registered name 1883 space. As such, the CoMI approach provides additional flexibility in 1884 defining management resources. Likewise, since CoMI utilizes YANG, 1885 existing YANG modules can be reused. The flexibility and reuse 1886 capabilities afforded to CoMI can be useful in management of devices 1887 like routers and switches in constrained networks. However for 1888 management of IoT devices, the usefulness of this flexibility and 1889 applicability of reuse of existing YANG modules may not be warranted. 1890 The reason is that IoT devices typically do not require complex sets 1891 of configuration or monitoring operations required by devices like a 1892 router or a switch. To date, OMA has defined approximately 15 1893 management resources for constrained and non-constrained mobile or 1894 fixed IoT devices while other 3rd Party SDOs have defined another 10 1895 management resources for their use in non-constrained IoT devices. 1896 Likewise, the Constrained Object Language [I-D.somaraju-core-sid] 1897 which is used by CoMI when managing constrained IoT devices uses YANG 1898 schema item identifiers, which are registered with IANA, in order to 1899 define management resources that are encoded using CBOR when 1900 targeting constrained IoT Devices. 1902 B.3. Identifying Management Resources 1904 As LWM2M and CoMI can similarly be used to manage IoT devices, 1905 comparison of the CoAP URIs used to identify resources is relevant as 1906 the size of the resource URI becomes applicable for IoT devices in 1907 constrained networks. LWM2M uses a flat identifier structure to 1908 identify management resources and are identified using the LWM2M 1909 object's identifier, instance identifier and optionally resource 1910 identifier (for access to and object's attributes). For example, 1911 identifier of a device object (object id = 3) would be "/3/0" and 1912 identification of the device object's manufacturer attribute would be 1913 "/3/0/0". Effectively LWM2M identifiers for management resources are 1914 between 4 and 10 bytes in length. 1916 CoMI is expected to be used to manage constrained IoT devices. CoMI 1917 utilizes the YANG schema item identifier[SID] that identify the 1918 resources. CoMI recommends that IoT device expose resources to 1919 identify the data stores and event streams of the CoMI agent. 1920 Individual resources (e.g., device object) are not directly 1921 identified but are encoded within the payload. As such the 1922 identifier of the CoMI resource is smaller (4 to 7 bytes) but the 1923 overall payload size isn't smaller as resource identifiers are 1924 encoded on the payload. 1926 B.4. Encoding of Management Resources 1928 LWM2M provides a separation of the definition of the management 1929 resources from how the payloads are encoded. As of the writing of 1930 this document LWM2M encodes LWM2M encodes payload data in Type- 1931 length-value (TLV), JSON or plain text formats. JSON encoding is the 1932 most common encoding scheme with TLV encoding used on the simplest 1933 IoT devices. CoMI's use of CBOR provides a more efficient transfer 1934 mechanism [RFC7049] than the current LWM2M encoding formats. 1936 In situations where resources need to be modified, CoMI uses the CoAP 1937 PATCH operation resources only require a partial update. LWM2M does 1938 not currently use the CoAP PATCH operation but instead uses the CoAP 1939 PUT and POST operations which are less efficient. 1941 Authors' Addresses 1943 Peter van der Stok 1944 consultant 1946 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 1947 Email: consultancy@vanderstok.org 1948 URI: www.vanderstok.org 1949 Andy Bierman 1950 YumaWorks 1951 685 Cochran St. 1952 Suite #160 1953 Simi Valley, CA 93065 1954 USA 1956 Email: andy@yumaworks.com 1958 Michel Veillette 1959 Trilliant Networks Inc. 1960 610 Rue du Luxembourg 1961 Granby, Quebec J2J 2V2 1962 Canada 1964 Phone: +14503750556 1965 Email: michel.veillette@trilliantinc.com 1967 Alexander Pelov 1968 Acklio 1969 2bis rue de la Chataigneraie 1970 Cesson-Sevigne, Bretagne 35510 1971 France 1973 Email: a@ackl.io