idnits 2.17.1 draft-vanderstok-core-comi-09.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 48 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 20 characters in excess of 72. == There are 7 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1028 has weird spacing: '... leaf given...' == Line 1029 has weird spacing: '... leaf famil...' == Line 1168 has weird spacing: '...eration enu...' == 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 leaf that has a default value, and the leaf has not been given a value yet, the server MUST not return the leaf. == 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. -- The document date (March 7, 2016) is 2971 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) ** 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 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-18 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-yang-json-08 == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-09 == Outdated reference: A later version (-03) exists of draft-vanderstok-core-patch-02 ** Downref: Normative reference to an Informational draft: draft-vanderstok-core-patch (ref. 'I-D.vanderstok-core-patch') == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-07 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-04 == Outdated reference: A later version (-06) exists of draft-ietf-lwig-coap-03 Summary: 4 errors (**), 0 flaws (~~), 16 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: September 8, 2016 YumaWorks 6 March 7, 2016 8 CoAP Management Interface 9 draft-vanderstok-core-comi-09 11 Abstract 13 This document describes a network management interface for 14 constrained devices, called CoMI. CoMI is an adaptation of the 15 RESTCONF protocol for use in constrained devices and networks. The 16 Constrained Application Protocol (CoAP) is used to access management 17 data resources specified in YANG, or SMIv2 converted to YANG. CoMI 18 use the YANG to CBOR mapping and encodes YANG names to reduce payload 19 size. 21 Note 23 Discussion and suggestions for improvement are requested, and should 24 be sent to core@ietf.org. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on September 8, 2016. 43 Copyright Notice 45 Copyright (c) 2016 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.1.1. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 5 63 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5 64 2.1. RESTCONF/YANG Architecture . . . . . . . . . . . . . . . 9 65 2.1.1. Major differences between RESTCONF and CoMI . . . . . 9 66 2.2. Compression of data-node instance identifier . . . . . . 10 67 3. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11 68 4. MG Function Set . . . . . . . . . . . . . . . . . . . . . . . 13 69 4.1. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 13 70 4.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 13 71 4.1.2. Using the 'select' Parameter . . . . . . . . . . . . 14 72 4.1.3. Using the 'content' query parameter . . . . . . . . . 14 73 4.1.4. Retrieval Examples . . . . . . . . . . . . . . . . . 15 74 4.2. Data Editing . . . . . . . . . . . . . . . . . . . . . . 22 75 4.2.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 22 76 4.2.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 22 77 4.2.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 23 78 4.2.4. PATCH . . . . . . . . . . . . . . . . . . . . . . . . 23 79 4.2.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 27 80 4.2.6. Editing Multiple Resources . . . . . . . . . . . . . 27 81 4.3. Notify functions . . . . . . . . . . . . . . . . . . . . 28 82 4.4. RPC statements . . . . . . . . . . . . . . . . . . . . . 30 83 4.4.1. Encoding RPC input parameters . . . . . . . . . . . . 31 84 4.4.2. Encoding RPC output parameters . . . . . . . . . . . 32 85 4.5. Use of Block . . . . . . . . . . . . . . . . . . . . . . 32 86 4.6. Resource Discovery . . . . . . . . . . . . . . . . . . . 33 87 4.7. Error Return Codes . . . . . . . . . . . . . . . . . . . 35 88 5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 36 89 6. Security Considerations . . . . . . . . . . . . . . . . . . . 38 90 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 91 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39 92 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 39 93 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 94 10.1. Normative References . . . . . . . . . . . . . . . . . . 42 95 10.2. Informative References . . . . . . . . . . . . . . . . . 44 97 Appendix A. Payload and Server sizes . . . . . . . . . . . . . . 46 98 Appendix B. Comparison with LWM2M . . . . . . . . . . . . . . . 47 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 101 1. Introduction 103 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 104 Machine to Machine (M2M) applications such as smart energy and 105 building control. Constrained devices need to be managed in an 106 automatic fashion to handle the large quantities of devices that are 107 expected in future installations. The messages between devices need 108 to be as small and infrequent as possible. The implementation 109 complexity and runtime resources need to be as small as possible. 111 This draft describes the CoAP Management Interface which uses CoAP 112 methods to access structured data defined in YANG [RFC6020]. This 113 draft is complementary to the draft [I-D.ietf-netconf-restconf] which 114 describes a REST-like interface called RESTCONF, which uses HTTP 115 methods to access structured data defined in YANG. 117 The use of standardized data sets, specified in a standardized 118 language such as YANG, promotes interoperability between devices and 119 applications from different manufacturers. A large amount of 120 Management Information Base (MIB) [RFC3418] [mibreg] specifications 121 already exists for monitoring purposes. This data can be accessed in 122 RESTCONF or CoMI if the server converts the SMIv2 modules to YANG, 123 using the mapping rules defined in [RFC6643]. 125 RESTCONF allows access to data resources contained in NETCONF 126 [RFC6241] data-stores. RESTCONF messages can be encoded in XML [XML] 127 or JSON [RFC7159]. The GET method is used to retrieve data resources 128 and the POST, PUT, PATCH, and DELETE methods are used to create, 129 replace, merge, and delete data resources. 131 CoMI supports the methods GET, PUT, PATCH, POST and DELETE. The 132 payload of CoMI is encoded in CBOR [RFC7049] which can be 133 automatically generated from JSON [RFC7159]. CBOR has a binary 134 format and hence has more coding efficiency than JSON. RESTCONF 135 relies on HTTP with TCP in contrast to CoMI which uses CoAP that is 136 optimized for UDP with less overhead for small messages. RESTCONF 137 uses the HTTP methods HEAD, and OPTIONS, which are not used by CoMI. 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 an additional "data-identifier 144 string-to-number conversion" to minimize CBOR payloads and URI 145 length. 147 Currently, small managed devices need to support at least two 148 protocols: CoAP and SNMP [RFC3411]. When the MIB can be accessed 149 with the CoMI protocol, the SNMP protocol can be replaced with the 150 CoAP protocol. Although the SNMP server size is not huge (see 151 Appendix A), the code for the security aspects of SMIv3 [RFC3414] is 152 not negligible. Using CoAP to access secured management objects 153 reduces the code complexity of the stack in the constrained device, 154 and harmonizes applications development. 156 1.1. Terminology 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 160 document are to be interpreted as described in [RFC2119]. 162 Readers of this specification should be familiar with all the terms 163 and concepts discussed in [RFC3410], [RFC3416], and [RFC2578]. 165 The following terms are defined in the NETCONF protocol [RFC6241]: 166 client, configuration data, data-store, and server. 168 The following terms are defined in the YANG data modelling language 169 [RFC6020]: container, data node, key, key leaf, leaf, leaf-list, and 170 list. The following terms are defined in RESTCONF protocol 171 [I-D.ietf-netconf-restconf]: data resource, data-store resource, edit 172 operation, query parameter, target resource, and unified data-store. 173 The terms YANG hash, and Rehash bit are defined in I-D.yang-hash. 175 The following terms are defined in this document: 177 Data-node instance: An instance of a data-node specified in a YANG 178 module present in the server. The instance is stored in the 179 memory of the server. 181 Notification-node instance: An instance of a schema node of type 182 notification, specified in a YANG module present in the server. 183 The instance is generated in the server at the occurrence of the 184 corresponding event and appended to a stream. 186 The following list contains the abbreviations used in this document. 188 XXXX: TODO, and others to follow. 190 1.1.1. Tree Diagrams 192 A simplified graphical representation of the data model is used in 193 the YANG modules specified in this document. The meaning of the 194 symbols in these diagrams is as follows: 196 Brackets "[" and "]" enclose list keys. 198 Abbreviations before data node names: "rw" means configuration 199 data (read-write) and "ro" state data (read-only). 201 Symbols after data node names: "?" means an optional node, "!" 202 means a presence container, and "*" denotes a list and leaf-list. 204 Parentheses enclose choice and case nodes, and case nodes are also 205 marked with a colon (":"). 207 Ellipsis ("...") stands for contents of subtrees that are not 208 shown. 210 2. CoMI Architecture 212 This section describes the CoMI architecture to use CoAP for the 213 reading and modifying of instrumentation variables used for the 214 management of the instrumented node. 216 Client 217 +--------------------------------------------------------------+ 218 | +----------------+ +----------------+ | 219 | | SMIv2 | > | YANG | > COAP | 220 | |specification(2)| |specification(1)| Request(3) | 221 | +----------------+ +----------------+[ * | 222 +-----------------------------*-----------[---------*----------+ 223 * [ * 224 * [ +-----------+ 225 mapping * security[ | Network | 226 * (8) [ | packet(4) | 227 * [ +-----------+ 228 Server * [ * 229 +-----------------------------*-----------[---------*----------+ 230 | * [ * | 231 | * Retrieval, | 232 | * Modification(5) | 233 | \*/ * | 234 | +-------------------------------------------------*--------+ | 235 | | +--------------+ +------------+ | | 236 | | |configuration | |Operational | | | 237 | | | (6b) | | state(6a) | | | 238 | | +--------------+ +------------+ | | 239 | | variable store (6) * | | 240 | +-------------------------------------------------*--------+ | 241 | * | 242 | Variable | 243 | Instrumentation(7)| 244 +--------------------------------------------------------------+ 246 Figure 1: Abstract CoMI architecture 248 Figure 1 is a high level representation of the main elements of the 249 CoAP management architecture. A client sends requests as payload in 250 packets over the network to a managed constrained node. 252 Objectives are: 254 o Equip a constrained node with a management server that provides 255 information about the operational characteristics of the code 256 running in the constrained node. 258 o The server provides this information in a variable store that 259 contains values describing the performance characteristics and the 260 code parameter values. 262 o The client receives the performance characteristics on a regular 263 basis or on request. 265 o The client sets the parameter values in the server at bootstrap 266 and intermittently when operational conditions change. 268 o The constrained network requires the payload to be as small as 269 possible, and the constrained server memory requirements should be 270 as small as possible. 272 For interoperability it is required that in addition to using the 273 Internet Protocol for data transport: 275 o The names, type, and semantics of the instrumentation variables 276 are standardized. 278 o The instrumentation variables are described in a standard 279 language. 281 o The URI of the CoAP request is standardized. 283 o The format of the packet payload is standardized. 285 o The notification from server to client is standardized. 287 The different numbered components of Figure 1 are discussed according 288 to component number. 290 (1) YANG specification: contains a set of named and versioned 291 modules. A module specifies a hierarchy of named and typed 292 resources. A resource is uniquely identified by a sequence of its 293 name and the names of the enveloping resources following the 294 hierarchy order. The YANG specification serves as input to the 295 writers of application and instrumentation code and the humans 296 analyzing the returned values (arrow from YANG specification to 297 Variable store). The specification can be used to check the 298 correctness of the CoAP request and do the CBOR encoding. 300 (2) SMIv2 specification: A named module specifies a set of variables 301 and "conceptual tables". Named variables have simple types. 302 Conceptual tables are composed of typed named columns. The 303 variable name and module name identify the variable uniquely. 304 There is an algorithm to translate SMIv2 specifications to YANG 305 specifications. 307 (3) CoAP request: The CoAP request needs a Universal Resource 308 Identifier (URI) and the payload of the packet to send a request. 309 The URI is composed of the schema, server, path and query and 310 looks like coap://entry.example.com/?. Fragments are 311 not supported. Allowed operations are PUT, PATCH, GET, DELETE, 312 and POST. New variables can be created with POST when they exist 313 in the YANG specification. The Observe option is used to return 314 variable values regularly or on event occurrence (notification). 316 (3.1) CoAP : The path identifies the variable in the form 317 "/mg/". 319 (3.2) CoAP : The query parameter is used to specify 320 additional (optional) aspects like the container name, list 321 instance, and others. The idea is to keep the path simple and put 322 variations on variable specification in the query. 324 (3.3) CoAP discovery: Discovery of the variables is done with 325 standard CoAP resource discovery using /.well-known/core with 326 ?rt=/core.mg. 328 (4) Network packet: The payload contains the CBOR encoding of JSON 329 objects. This object corresponds with the converted RESTCONF 330 message payload. 332 (5) Retrieval, modification: The server needs to parse the CBOR 333 encoded message and identify the corresponding instances in the 334 Variable store. In addition, this component includes the code for 335 CoAP Observe and block options. 337 (6) Variable store: The store is composed of two parts: Operational 338 state and Configuration data-store (see Section 2.1). CoMI does 339 not differentiate between variable store types. The Variable 340 store contains data-node instances. Values are stored in the 341 appropriate instances, and or values are returned from the 342 instances into the payload of the packet. 344 (7) Variable instrumentation: This code depends on implementation of 345 drivers and other node specific aspects. The Variable 346 instrumentation code stores the values of the parameters into the 347 appropriate places in the operational code. The variable 348 instrumentation code reads current execution values from the 349 operational code and stores them in the appropriate instances. 351 (8) Security: The server MUST prevent unauthorized users from 352 reading or writing any data resources. CoMI relies on DTLS 353 [RFC6347] which is specified to secure CoAP communication. 355 2.1. RESTCONF/YANG Architecture 357 CoMI adapts the RESTCONF architecture so data exchange and 358 implementation requirements are optimized for constrained devices. 360 The RESTCONF protocol uses a unified data-store to edit conceptual 361 data structures supported by the server. The details of transaction 362 preparation and non-volatile storage of the data are hidden from the 363 RESTCONF client. CoMI also uses a unified data-store, to allow 364 stateless editing of configuration variables and the notification of 365 operational variables. 367 The child schema nodes of the unified data-store include all the top- 368 level YANG data nodes in all the YANG modules supported by the 369 server. The YANG data structures represent a hierarchy of data 370 resources. The client discovers the list of YANG modules, and 371 important conformance information such as the module revision dates, 372 YANG features supported, and YANG deviations required. The 373 individual data nodes are discovered indirectly by parsing the YANG 374 modules supported by the server. 376 The YANG data definition statements contain a lot of information that 377 can help automation tools, developers, and operators use the data 378 model correctly and efficiently. The YANG definitions and server 379 YANG module capability advertisements provide an "API contract" that 380 allow a client to determine the detailed server management 381 capabilities very quickly 383 RESTCONF and CoMI use a simple algorithmic mapping from YANG to URI 384 syntax to identify the target resource of a retrieval or edit 385 operation. A client can construct operations or scripts using a 386 predictable syntax, based on the YANG data definitions. The target 387 resource URI can reference a data resource instance, or the data- 388 store itself (to retrieve the entire data-store or create a top-level 389 data resource instance). A compression algorithm reduces the size of 390 the data-node instance identifier (see Section 2.2). 392 2.1.1. Major differences between RESTCONF and CoMI 394 CoMI uses CoAP/UDP as transport protocol and CBOR as payload format. 395 RESTCONF uses HTTP/TCP as transport protocol and JSON or XML as 396 payload formats. CoMI encodes YANG name strings as numbers, where 397 RESTCONF does not. 399 CoAP servers MUST maintain the order of user-ordered data. CoMI does 400 not support insert-mode (first, last, before, after) and insertion- 401 point (before, after) which are supported by RESTCONF. Many CoAP 402 servers will not support date and time functions. For that reason 403 CoMI does not support the start, stop options for events. 405 The CoMI "select" query parameter is equivalent to the RESTCONF 406 "fields" query parameter but has a much simpler syntax. CoMI servers 407 only implement the efficient "trim" mode for default values. CoMI 408 servers implement a less rich syntax to specify key values in the URI 409 than RESTCONF servers. 411 CoMI servers do not support 'filter' query that involves XML parsing, 412 'content', 'depth', and 'with-defaults' query parameters. 414 CoMI servers do not support the YANG functionality of anyxml, 415 anydata, and xpath. 417 2.2. Compression of data-node instance identifier 419 The JSON/CBOR encoding will include the module name string to specify 420 the YANG module. If a representation of the target resource is 421 included in the request or response message, then the data definition 422 name string is used to identify each node in the message. The module 423 namespace (or name) may also be present in these identifiers. 425 In order to significantly reduce the size of identifiers used in 426 CoMI, numeric object identifiers are used instead of these strings. 427 The specific encoding of the object identifiers is not hard-wired in 428 the protocol. 430 YANG Hash is the default encoding for object identifiers 431 [I-D.bierman-core-yang-hash]. This encoding in considered to be 432 "unstructured" since the particular values for each object are 433 determined by a hash algorithm. It is possible for 2 different 434 objects to generate the same hash value. If this occurs, then the 435 client and server will both need to rehash the colliding object 436 identifiers to new unused hash values. 438 In order to eliminate the need for rehashing, CoMI allows for 439 alternate "structured" object identifier encoding formats. 440 Structured object identifier MUST be managed such that no object ID 441 collisions are possible, and therefore no rehash procedures are 442 needed. Structured object identifiers can also be selected to 443 minimize the size of a subset of the object identifiers (e.g., the 444 most requested objects). 446 3. CoAP Interface 448 In CoAP a group of links can constitute a Function Set. The format of 449 the links is specified in [I-D.ietf-core-interfaces]. This note 450 specifies a Management Function Set. CoMI end-points that implement 451 the CoMI management protocol support at least one discoverable 452 management resource of resource type (rt): core.mg, with path: /mg, 453 where mg is short-hand for management. The name /mg is recommended 454 but not compulsory (see Section 4.6). 456 The path prefix /mg has resources accessible with the following five 457 paths: 459 /mg: YANG-based data with path "/mg" and using CBOR content encoding 460 format. This path represents a data-store resource which contains 461 YANG data resources as its descendant nodes. All identifiers 462 referring to YANG data nodes within this path are encoded YANG 463 names (see for example [I-D.bierman-core-yang-hash]. 465 /mg/mod.uri: URI identifying the location of the server module 466 information, with path "/mg/mod.uri" and CBOR content format. 467 This YANG data is encoded with plain identifier strings, not YANG 468 encoded values. An Entity Tag MUST be maintained for this 469 resource by the server, which MUST be changed to a new value when 470 the set of YANG modules in use by the server changes. 472 /mg/num.typ: String identifying the object ID numbering scheme used 473 by the CoMI server. Two values are defined in this document: (1) 474 'yanghash' to indicate that the YANG Hash numbering scheme is 475 used, and (2) 'yangmanag' to indicate that a managed numbering 476 scheme is used. It is possible for other object numbering schemes 477 to be defined outside the scope of this document. 479 /mg/srv.typ: String identifying the CoMI server type. The value 480 'ro' indicates that the server is a read-only server and no 481 editing operations are supported. A read-only server is not 482 required to provide YANG deviation statements for any writable 483 YANG data nodes. The value 'rw' indicates that the server is a 484 read-write server and editing operations are supported. A read- 485 write server is required to provide YANG deviation statements for 486 any writable YANG data nodes that are not fully implemented. 488 /mg/yh.uri: URI indicating the location of the server YANG hash 489 information if any objects needed to be re-hashed by the server. 490 It has the path "/mg/yh.uri" and is encoded in CBOR format. The 491 "yang-hash" container within the "ietf-yang-hash" module, 492 described in [I-D.bierman-core-yang-hash], is used to define the 493 syntax and semantics of this data structure. This YANG data is 494 encoded with plain identifier strings, not YANG hash values. The 495 server will only have this resource if there are any objects that 496 needed to be re-hashed due to a hash collision. 498 /mg/stream: String identifying the default stream resource to which 499 YANG notification instances are appended. Notification support is 500 optional, so this resource will not exist if the server does not 501 support any notifications. 503 /mg/op: String identifying the resource to which YANG operations are 504 appended. 506 The mapping of YANG data node instances to CoMI resources is as 507 follows: A YANG module describes a set of data trees composed of YANG 508 data nodes. Every root of a data tree in a YANG module loaded in the 509 CoMI server represents a resource of the server. All data root 510 descendants represent sub-resources. 512 The resource identifiers of the instances of the YANG specifications 513 are encoded YANG names. When multiple instances of a list node 514 exist, the instance selection is described in Section 4.1.4.4 516 The profile of the management function set, with IF=core.mg, is shown 517 in the table below, following the guidelines of 518 [I-D.ietf-core-interfaces]: 520 +--------------+-------------+-------------------+------------------+ 521 | name | path | rt | Data Type | 522 +--------------+-------------+-------------------+------------------+ 523 | Management | /mg | core.mg | n/a | 524 | | | | | 525 | Data | /mg | core.mg.data | application/cbor | 526 | | | | | 527 | Module Set | /mg/mod.uri | core.mg.moduri | application/cbor | 528 | URI | | | | 529 | | | | | 530 | Numbering | /mg/num.typ | core.mg.num-type | application/cbor | 531 | Type | | | | 532 | | | | | 533 | Server Type | /mg/srv.typ | core.mg.srv-type | application/cbor | 534 | | | | | 535 | YANG Hash | /mg/yh.uri | core.mg.yang-hash | application/cbor | 536 | Info | | | | 537 | | | | | 538 | Events | /mg/stream | core.mg.stream | application/cbor | 539 | | | | | 540 | Operations | /mg/op | core.mg.op | application/cbor | 541 +--------------+-------------+-------------------+------------------+ 543 4. MG Function Set 545 The MG Function Set provides a CoAP interface to perform a subset of 546 the functions provided by RESTCONF. 548 A subset of the operations defined in RESTCONF are used in CoMI: 550 +-----------+------------------------------------------------------+ 551 | Operation | Description | 552 +-----------+------------------------------------------------------+ 553 | GET | Retrieve the data-store resource or a data resource | 554 | | | 555 | POST | Create a data resource | 556 | | | 557 | PUT | Create or replace a data resource | 558 | | | 559 | PATCH | Replace a data resource partially | 560 | | | 561 | DELETE | Delete a data resource | 562 +-----------+------------------------------------------------------+ 564 4.1. Data Retrieval 566 4.1.1. GET 568 One or more instances of data resources are retrieved by the client 569 with the GET method. The RESTCONF GET operation is supported in 570 CoMI. The same constraints apply as defined in section 3.3 of 571 [I-D.ietf-netconf-restconf]. The operation is mapped to the GET 572 method defined in section 5.8.1 of [RFC7252]. 574 It is possible that the size of the payload is too large to fit in a 575 single message. In the case that management data is bigger than the 576 maximum supported payload size, the Block mechanism from 577 [I-D.ietf-core-block] is used, as explained in more detail in 578 Section 4.5. 580 There are three query parameters for the GET method. A CoMI server 581 MUST implement the keys parameter and the content parameter, and MAY 582 implement the select parameter to allow common data retrieval 583 filtering functionality. 585 +---------------+---------------------------------------------------+ 586 | Query | Description | 587 | Parameter | | 588 +---------------+---------------------------------------------------+ 589 | keys | Request to select instances of a YANG definition | 590 | | | 591 | select | Request to select sub-trees from the target | 592 | | resource | 593 | | | 594 | content | Request to select configuration and non- | 595 | | configuration nodes | 596 +---------------+---------------------------------------------------+ 598 The "keys" parameter is used to specify a specific instance of the 599 list resource. When keys is not specified, all instances are 600 returned. When no or one instance of the resource exists, the keys 601 parameter is ignored. 603 4.1.2. Using the 'select' Parameter 605 RESTCONF uses the 'filter' parameter next to the 'fields' parameter 606 to specify an expression which can represent a subset of all data 607 nodes within the target resource [I-D.ietf-netconf-restconf]. The 608 'select' parameter is local to CoMI and is useful for filtering sub- 609 trees and retrieving only a subset that a managing application is 610 interested in. 612 Because filtering is a resource intensive task and not all 613 constrained devices can be expected to have enough computing 614 resources such that they will be able to successfully filter and 615 return a subset of a sub-tree. This is especially likely to be true 616 with Class 0 devices that have significantly lesser RAM than 10 KiB 617 [RFC7228]. Since CoMI is targeted at constrained devices and 618 networks, the 'filter' parameter is not used here. 620 The implementation of the 'select' parameter is already optional for 621 constrained devices, however, even when implemented it is expected to 622 be a best effort feature, rather than a service that nodes must 623 provide. This implies that if a node receives the 'select' parameter 624 specifying a set of sub-trees that should be returned, it will only 625 return those that it is able to return. 627 4.1.3. Using the 'content' query parameter 629 The "content" parameter controls how descendant nodes of the 630 requested data nodes will be processed in the reply. 632 The allowed values are: 634 +------------+------------------------------------------------------+ 635 | Value | Description | 636 +------------+------------------------------------------------------+ 637 | config | Return only configuration descendant data nodes | 638 | | | 639 | nonconfig | Return only non-configuration descendant data nodes | 640 | | | 641 | all | Return all descendant data nodes | 642 +------------+------------------------------------------------------+ 644 This parameter is only allowed for GET methods on datastore and data 645 resources. A 4.00 Bad Request error is returned if used for other 646 methods or resource types. 648 The default value is determined by the "config" statement value of 649 the requested data nodes. If the "config" value is "false", then the 650 default for the "content" parameter is "nonconfig". If "config" is 651 "true" then the default for the "content" parameter is "config". 653 4.1.4. Retrieval Examples 655 In all examples the path is expressed in readable names and as a 656 encoded value of the name (where the encoded value in the payload is 657 expressed as a hexadecimal number, and the encoded value in the URL 658 as a base64 number). CoMI payloads use the CBOR format. The CBOR 659 syntax of the YANG payloads is specified in TODO REF. The examples 660 in this section use a JSON payload with extensions to approach the 661 permissible CBOR payload, called "diagnostic JSON". 663 4.1.4.1. Single instance retrieval 665 A request to read the values of instances of a management object or 666 the leaf of an object is sent with a confirmable CoAP GET message. A 667 single object is specified in the URI path prefixed with /mg. 669 Using for example the clock container from [RFC7317], a request is 670 sent to retrieve the value of clock/current-datetime specified in 671 module system-state. The answer to the request returns a 672 (identifier, value) pair, transported as a CBOR map with a single 673 item. 675 REQ: GET example.com/mg/system-state/clock/current-datetime 677 RES: 2.05 Content (Content-Format: application/cbor) 678 { 679 "current-datetime" : "2014-10-26T12:16:31Z" 680 } 681 The specified object can be an entire object. Accordingly, the 682 returned payload is composed of all the leaves associated with the 683 object. The payload is a CBOR map where each leaf is returned as a 684 (encoded YANG name, value) pair. For example, the GET of the clock 685 object, sent by the client, results in the following returned payload 686 sent by the managed entity, transported as A CBOR map with two items: 688 REQ: GET example.com/mg/system-state/clock 689 (Content-Format: application/cbor) 691 RES: 2.05 Content (Content-Format: application/cbor) 692 { 693 "clock" : { 694 "current-datetime" : "2014-10-26T12:16:51Z", 695 "boot-datetime" : "2014-10-21T03:00:00Z" 696 } 697 } 699 For example, the YANG names can be replaced by the hash values for 700 'clock', 'current-datetime', and 'boot-datetime'. The 30 bit murmur3 701 hash value of 'clock' equates: CDKSQ (xref target="I-D.bierman-core- 702 yang-hash"/>. The request using hash values is shown below: 704 REQ: GET example.com/mg/CDKSQ 705 (Content-Format: application/cbor) 707 RES: 2.05 Content (Content-Format: application/cbor) 708 { 709 0x021ca491 : { 711 0x047c468b : "2014-10-26T12:16:51Z", 712 0x1fb5f4f8 : "2014-10-21T03:00:00Z" 713 } 714 } 716 4.1.4.2. Multiple instance retrieval 718 A "list" node can have multiple instances. Accordingly, the returned 719 payload is composed of all the instances associated with the list 720 node. Each instance is returned as a (key, object) pair, where key 721 and object are composed of one or more (identifier, value) pairs. 723 For example, the GET of the /interfaces/interface/ipv6/neighbor 724 results in the following returned payload sent by the managed entity, 725 transported as a CBOR map of 3 (key : object) pairs, where key and 726 value are CBOR maps with one entry each. In this case the key is the 727 "ip" attribute and the value is the "link-layer-address" attribute. 729 REQ: GET example.com/mg/interfaces/interface/ipv6/neighbor 730 (Content-Format: application/cbor) 732 RES: 2.05 Content (Content-Format: application/cbor) 733 { 734 "neighbor" :{ 735 {"ip" : "fe80::200:f8ff:fe21:67cf"}: 736 {"link-layer-address" : "00:00::10:01:23:45"} 737 , 738 {"ip" : "fe80::200:f8ff:fe21:6708"}: 739 {"link-layer-address" : "00:00::10:54:32:10"} 740 , 741 {"ip" : "fe80::200:f8ff:fe21:88ee"}: 742 {"link-layer-address" : "00:00::10:98:76:54"} 743 } 744 } 746 4.1.4.3. Access to MIB Data 748 The YANG translation of the SMI specifying the 749 ipNetToMediaTable [RFC4293] yields: 751 container IP-MIB { 752 container ipNetToPhysicalTable { 753 list ipNetToPhysicalEntry { 754 key "ipNetToPhysicalIfIndex 755 ipNetToPhysicalNetAddressType 756 ipNetToPhysicalNetAddress"; 757 leaf ipNetToMediaIfIndex { 758 type: int32; 759 } 760 leaf ipNetToPhysicalIfIndex { 761 type if-mib:InterfaceIndex; 762 } 763 leaf ipNetToPhysicalNetAddressType { 764 type inet-address:InetAddressType; 765 } 766 leaf ipNetToPhysicalNetAddress { 767 type inet-address:InetAddress; 768 } 769 leaf ipNetToPhysicalPhysAddress { 770 type yang:phys-address { 771 length "0..65535"; 772 } 773 } 774 leaf ipNetToPhysicalLastUpdated { 775 type yang:timestamp; 776 } 777 leaf ipNetToPhysicalType { 778 type enumeration { ... } 779 } 780 leaf ipNetToPhysicalState { 781 type enumeration { ... } 782 } 783 leaf ipNetToPhysicalRowStatus { 784 type snmpv2-tc:RowStatus; 785 } 786 } 787 } 789 The following example shows an "ipNetToPhysicalTable" with 2 790 instances, using JSON encoding as defined in 791 [I-D.ietf-netmod-yang-json]: 793 { 794 "IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry" : [ 795 { 796 "ipNetToPhysicalIfIndex" : 1, 797 "ipNetToPhysicalNetAddressType" : "ipv4", 798 "ipNetToPhysicalNetAddress" : "10.0.0.51", 799 "ipNetToPhysicalPhysAddress" : "00:00:10:01:23:45", 800 "ipNetToPhysicalLastUpdated" : "2333943", 801 "ipNetToPhysicalType" : "static", 802 "ipNetToPhysicalState" : "reachable", 803 "ipNetToPhysicalRowStatus" : "active" 804 }, 805 { 806 "ipNetToPhysicalIfIndex" : 1, 807 "ipNetToPhysicalNetAddressType" : "ipv4", 808 "ipNetToPhysicalNetAddress" : "9.2.3.4", 809 "ipNetToPhysicalPhysAddress" : "00:00:10:54:32:10", 810 "ipNetToPhysicalLastUpdated" : "2329836", 811 "ipNetToPhysicalType" : "dynamic", 812 "ipNetToPhysicalState" : "unknown", 813 "ipNetToPhysicalRowStatus" : "active" 814 } 815 ] 816 } 817 } 818 } 820 4.1.4.4. The 'keys' Query Parameter 822 There is a query parameter that MUST be supported by servers called 823 "keys". This parameter is used to specify the key values for an 824 instance of an object identified by an encoded YANG name. All key 825 leaf values of the instance are passed in order. The first key leaf 826 in the top-most list is the first key encoded in the 'keys' 827 parameter. 829 The key leafs from top to bottom and left to right are encoded as a 830 comma-delimited list. If a key leaf value is missing then all values 831 for that key leaf are returned. 833 Example: In this example exactly one instance is requested from the 834 ipNetToPhysicalEntry (from a previous example). The CBOR payload, 835 here represented with diagnostic JSON, permits to transport the 836 selected instance and nothing more. 838 TODO refer to the section in YANG to CBOR mapping 840 REQ: GET example.com/mg/IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry?keys=1,ipv4,9.2.3.4 842 RES: 2.05 Content (Content-Format: application/cbor) 843 { 844 "IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry": { 845 { 846 "ipNetToPhysicalIfIndex" : 1, 847 "ipNetToPhysicalNetAddressType" : "ipv4", 848 "ipNetToPhysicalNetAddress" : "9.2.3.4"}: 849 { 850 "ipNetToPhysicalPhysAddress" : "00:00:10:54:32:10", 851 "ipNetToPhysicalLastUpdated" : "2329836", 852 "ipNetToPhysicalType" : "dynamic", 853 "ipNetToPhysicalState" : "unknown", 854 "ipNetToPhysicalRowStatus" : "active" 855 } 856 } 857 } 859 An example illustrates the syntax of keys query parameter. In this 860 example the following YANG module is used: 862 module foo-mod { 863 namespace foo-mod-ns; 864 prefix foo; 866 list A { 867 key "key1 key2"; 868 leaf key1 { type string; } 869 leaf key2 { type int32; } 870 list B { 871 key "key3"; 872 leaf key3 { type string; } 873 leaf col1 { type uint32; } 874 } 875 } 876 } 878 The following string represents the CoMI target resource identifier 879 for the instance of the "col1" leaf with key values "top", 17, 880 "group": 882 /mg/foo-mod:A/B/col1?keys="top",17,"group1" 884 4.1.4.5. The 'select' Query Parameter 886 The select parameter is used along with the GET method to provide a 887 sub-tree filter mechanism. A list of encoded YANG names that should 888 be filtered is provided along with a list of keys identifying the 889 instances that should be returned. When the keys parameter is used 890 together with the select, the key values are added in brackets 891 without using the "keys=" text. 893 Data may be retrieved using the select query parameter in the 894 following way, transported as a CBOR maps of maps: 896 REQ: GET example.com/mg/IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry?select=(10.0.0.51) 898 RES: 2.05 Content (Content-Format: application/cbor) 899 { 900 "IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry": { 901 { 902 "ipNetToPhysicalIfIndex" : 1, 903 "ipNetToPhysicalNetAddressType" : "ipv4", 904 "ipNetToPhysicalNetAddress" : "10.0.0.51"}: 905 { 906 "ipNetToPhysicalPhysAddress" : "00:00:10:01:23:45", 907 "ipNetToPhysicalLastUpdated" : "2333943", 908 "ipNetToPhysicalType" : "static", 909 "ipNetToPhysicalState" : "reachable", 910 "ipNetToPhysicalRowStatus" : "active" 911 } 912 } 913 } 915 In this example exactly one instance is returned as response from the 916 ipNetToPhysicalTable because only this instance matches the provided 917 keys. 919 Supposing there were multiple YANG fields with their own sets of keys 920 that were to be filtered, the select query parameter can be used to 921 retrieve results from these in one go as well. Using the "foo-mod" 922 module of Section 4.1.4.4, the following string represents the CoMI 923 target resource identifier when multiple fields, with their own sets 924 of key values are queried: 926 /mg/foo-mod:A?select=B/col1("top",17,"group"),key2("top") 928 4.1.4.6. Defaults handling 930 If the target of a GET method is a data node that represents a leaf 931 that has a default value, and the leaf has not been given a value 932 yet, the server MUST not return the leaf. 934 If the target of a GET method is a data node that represents a 935 container or list that has any child resources with default values, 936 for the child resources that have not been given value yet, the 937 server MUST not return the child resource. 939 4.2. Data Editing 941 CoMI allows data-store contents to be created, modified and deleted 942 using CoAP methods. 944 Data-editing is an optional feature. The server will indicate its 945 editing capability with the "/core.mg.srv-type resource type. If the 946 value is 'rw' then the server supports editing operations. If the 947 value is 'ro' then the server does not support editing operations. 949 4.2.1. Data Ordering 951 A CoMI server is not required to support entry insertion of lists and 952 leaf-lists that are ordered by the user (i.e., YANG statement 953 "ordered-by user"). The 'insert' and 'point' query parameters from 954 RESTCONF are not used in CoMI. 956 A CoMI server SHOULD preserve the relative order of all user-ordered 957 list and leaf-list entries that are received in a single edit 958 request. These YANG data node types are encoded as arrays so 959 messages will preserve their order. 961 4.2.2. POST 963 Data resource instances are created with the POST method. The 964 RESTCONF POST operation is supported in CoMI for creation of data 965 resources and the invocation operation resources. Refer to 966 Section 4.4 for details on operation resources. The same constraints 967 apply as defined in section 4.4.1 of [I-D.ietf-netconf-restconf]. 968 The operation is mapped to the POST method defined in section 5.8.2 969 of [RFC7252]. 971 There are no query parameters for the POST method. 973 4.2.3. PUT 975 Data resource instances are created or replaced with the PUT method. 976 The PUT operation is supported in CoMI. A request to set the values 977 of instances of an object/leaf is sent with a confirmable CoAP PUT 978 message. The Response is piggybacked to the CoAP ACK message 979 corresponding with the Request. The same constraints apply as 980 defined in section 3.5 of [I-D.ietf-netconf-restconf]. The operation 981 is mapped to the PUT method defined in section 5.8.3 of [RFC7252]. 983 There are no query parameters for the PUT method. 985 4.2.4. PATCH 987 Data resource instances are partially replaced with the PATCH method 988 [I-D.vanderstok-core-patch]. The PATCH operation is supported in 989 CoMI. A request to set the values of instances of a subset of the 990 values of the resource is sent with a confirmable CoAP PATCH message. 991 The Response is piggybacked to the CoAP ACK message corresponding 992 with the Request. The same constraints apply as defined in section 993 3.5 of [I-D.ietf-netconf-restconf]. The operation is mapped to the 994 PATCH method defined in [I-D.vanderstok-core-patch]. 996 The processing of the PATCH command is specified by the CBOR payload. 997 The CBOR patch payload describes the changes to be made to target 998 YANG data nodes. It follows closely the rules described in 999 [RFC7396]. If the CBOR patch payload contains objects that are not 1000 present in the target, these objects are added. If the target 1001 contains the specified object, the contents of the objects are 1002 replaced with the values of the payload. Null values indicate the 1003 removal of existing values. The CBOR patch extends [RFC7396] by 1004 specifying rules for list elements. 1006 TODO, review text after publication of YANG/CBOR and CBOR-merge 1007 drafts. 1009 For example consider the following YANG specification: 1011 module foo { 1012 namespace "http://example.com/book"; 1013 prefix "bo"; 1014 revision 2015-06-07; 1016 list B { 1017 key key1; 1018 key key2; 1019 leaf key1 { type string; } 1020 leaf key2 {type string; } 1021 leaf col1 { type int32; } 1022 leaf counter1 { type uint32; } 1023 } 1025 container book { 1026 leaf title { type string; } 1027 container author { 1028 leaf givenName {type string; } 1029 leaf familyName {type string; } 1030 } 1031 leaf-list tags {type string; } 1032 leaf content{type string;} 1033 leaf phoneNumber {type string;} 1034 } 1036 Consider the following target data nodes described with the JSON 1037 encoding of [I-D.ietf-netmod-yang-json]. 1039 "B": [ 1040 { 1041 "key1" : "author1", 1042 "key2" : "book2", 1043 "col1" : 25, 1044 "counter1" : 4321 1045 }, 1046 { 1047 "key1" : "author5", 1048 "key2" : "book6", 1049 "col1" : 2, 1050 "counter1" : 1234 1051 } 1052 ] 1054 "book": { 1055 "title" : "mytitle", 1056 "author": { 1057 "givenName" : "John", 1058 "familyName" : "Doe" 1059 } 1060 "tags" : [ "example", "sample"], 1061 "content" : "This will be unchanged" 1062 } 1064 The following changes are requested for the document (following the 1065 example from [RFC7396]: the title changes from "mytitle" to 1066 "favoured", the phoneNumber is added to the book container, the 1067 familyName is deleted, and "sample" is removed from the tags leaf- 1068 list. In addition author1, book1 item is removed, author5 counter1 1069 is upgraded, and a new author is added in B list. The following CBOR 1070 Patch payload, represented in JSON is sent. 1072 TODO: edit after publication of CBOR-merge draft. 1074 { 1075 "B": { 1076 { "key1" : "author1", 1077 "key2" : "book2"}: 1078 { null : null}, 1079 { "key1" : "author5"} : 1080 {"counter1" : 4444}, 1081 { "key1" : "newauthor", 1082 "key2" : "newbook"}: 1083 { "col1" : 1, 1084 "counter1" : 1} 1085 }, 1086 "book" : { 1087 "title" : "favoured", 1088 "author": {"familyName" : null}, 1089 "tags" : [ "example"], 1090 "phoneNumber" : "+01-123-456-7890" 1091 } 1092 } 1094 In his example, the value "author5" specifies the entry uniquely. 1095 However, when several entries exist with the "author5" value for 1096 "key1", the outcome of the example Patch is undefined. 1098 The processing of the Patch payload results in the following new 1099 target data nodes. 1101 "B": [ 1102 { 1103 "key1" : "newauthor", 1104 "key2" : "newbook", 1105 "col1" : 1, 1106 "counter1" : 1 1107 }, 1108 { 1109 "key1" : "author5", 1110 "key2" : "book6", 1111 "col1" : 2, 1112 "counter1" : 4444 1113 } 1114 ] 1116 "book": { 1117 "title" : "favoured", 1118 "author": { 1119 "givenName" : "John" 1120 } 1121 "tags" : [ "example"], 1122 "content" : "This will be unchanged", 1123 "phoneNumber" : +01-123-456-7890" 1124 } 1126 There are no query parameters for the PATCH method. 1128 4.2.5. DELETE 1130 Data resource instances are deleted with the DELETE method. The 1131 RESTCONF DELETE operation is supported in CoMI. The same constraints 1132 apply as defined in section 3.7 of [I-D.ietf-netconf-restconf]. The 1133 operation is mapped to the DELETE method defined in section 5.8.4 of 1134 [RFC7252]. 1136 There are no optional query parameters for the DELETE method. 1138 4.2.6. Editing Multiple Resources 1140 Editing multiple data resources at once can allow a client to use 1141 fewer messages to make a configuration change. It also allows 1142 multiple edits to all be applied or none applied, which is not 1143 possible if the data resources are edited one at a time. 1145 It is easy to add multiple entries at once. The "PATCH" method can 1146 be used to simply patch the parent node(s) of the data resources to 1147 be added. If multiple top-level data resources need to be added, 1148 then the data-store itself ('/mg') can be patched. 1150 If other operations need to be performed, or multiple operations need 1151 to be performed at once, then the YANG Patch 1152 [I-D.ietf-netconf-yang-patch] media type can be used with the PATCH 1153 method. A YANG patch is an ordered list of edits on the target 1154 resource, which can be a specific data node instance, or the data- 1155 store itself. The resource type used by YANG Patch is 'application/ 1156 yang.patch'. A status message is returned in the response, using 1157 resource type 'application/yang.patch.status'. 1159 The following YANG tree diagram describes the YANG Patch structure, 1160 Each 'edit' list entry has its own operation, sub-resource target, 1161 and new value (if needed). 1163 +--rw yang-patch 1164 +--rw patch-id? string 1165 +--rw comment? string 1166 +--rw edit* [edit-id] 1167 +--rw edit-id string 1168 +--rw operation enumeration 1169 +--rw target target-resource-offset 1170 +--rw point? target-resource-offset 1171 +--rw where? enumeration 1172 +--rw value 1174 Refer to [I-D.ietf-netconf-yang-patch] for more details on the YANG 1175 Patch request and response contents. 1177 4.3. Notify functions 1179 Notification by the server to a selection of clients when an event 1180 occurs in the server is an essential function for the management of 1181 servers. CoMI allows events specified in YANG [RFC5277] to be 1182 notified to a selection of requesting clients. The server appends 1183 newly generated events to a stream. There is one, so-called 1184 "default", stream in a CoMI server. The /mg/stream resource 1185 identifies the default stream. The server MAY create additional 1186 streams. When a CoMI server generates an internal event, it is 1187 appended to the chosen stream, and the contents of a notification 1188 instance is ready to be sent to all CoMI clients which observe the 1189 chosen stream resource. 1191 Reception of generated notification instances is enabled with the 1192 CoAP Observe [I-D.ietf-core-observe] function. The client subscribes 1193 to the notifications by sending a GET request with an "Observe" 1194 option, specifying the /mg/stream resource when the default stream is 1195 selected. 1197 Every time an event is generated, the chosen stream is cleared, and 1198 the generated notification instance is appended to the chosen stream. 1199 After appending the instance, the contents of the instance is sent to 1200 all clients observing the modified stream. 1202 Suppose the server generates the event specified with: 1204 module example-port { 1205 ... 1206 prefix ep; 1207 ... 1208 notification example-port-fault { 1209 description 1210 "Event generated if a hardware fault on a 1211 line card port is detected"; 1212 leaf port-name { 1213 type string; 1214 description "Port name"; 1215 } 1216 leaf port-fault { 1217 type string; 1218 description "Error condition detected"; 1219 } 1220 } 1221 } 1223 } 1225 By executing a GET on the /mg/stream resource the client receives the 1226 following response: 1228 REQ: GET example.com/mg/stream 1229 (observe option register) 1231 RES: 2.05 Content (Content-Format: application/cbor) 1232 { 1233 "example-port-fault":{ 1234 "port-name" : "0/4/21", 1235 "port-fault" : "Open pin 2" 1236 } 1237 } 1239 In the example, the request returns a success response with the 1240 contents of the last generated event. Consecutively the server will 1241 regularly notify the client when a new event is generated. 1243 To check that the client is still alive, the server MUST send 1244 confirmable notifications once in a while. When the client does not 1245 confirm the notification from the server, the server will remove the 1246 client from the list of observers [I-D.ietf-core-observe]. 1248 In the registration request, the client MAY include a "Response-To- 1249 Uri-Host" and optionally "Response-To-Uri-Port" option as defined in 1250 [I-D.becker-core-coap-sms-gprs]. In this case, the observations 1251 SHOULD be sent to the address and port indicated in these options. 1252 This can be useful when the client wants the managed device to send 1253 the trap information to a multicast address. 1255 4.4. RPC statements 1257 An operation resource represents a protocol operation defined with 1258 the YANG "rpc" statement. It is invoked using a POST method on the 1259 operation resource with a Token value as specified in section 5.3 1260 "Request/Resonse matching" of [RFC7252] to match the operation 1261 request sent by the RPC requester to the Operation request sent by 1262 the RPC executor. 1264 POST mg/op/ 1266 The field identifies the module name and rpc identifier 1267 string for the desired operation. 1269 For example, if "module-A" defined a "reset" operation, then invoking 1270 the operation from "module-A" would be requested as follows: 1272 POST example.com/mg/op/module-A:reset 1274 If the "rpc" statement has input parameters, then a message-body MAY 1275 be sent by the client in the request, otherwise the request message 1276 MUST NOT include a message-body. 1278 If the operation is successfully invoked the server MUST send a 2.04 1279 Changed status code. If the operation is not successfully invoked, 1280 then a message-body SHOULD be sent by the server, containing an 1281 error, as defined in Section 4.7. 1283 If the "rpc" statement has return parameters, then the server invokes 1284 a POST method with the same Token value as used in the request from 1285 the client. The payload contains the values of the return 1286 parameters. 1288 4.4.1. Encoding RPC input parameters 1290 If the "rpc" statement has an "input" section, then the "input" node 1291 is provided in the message-body, corresponding to the YANG data 1292 definition statements within Request payload. 1294 The following YANG definition is used for the examples in this 1295 section. 1297 module example-ops { 1298 namespace "https://example.com/ns/example-ops"; 1299 prefix "ops"; 1301 rpc reboot { 1302 input { 1303 leaf delay { 1304 units seconds; 1305 type uint32; 1306 default 0; 1307 } 1308 leaf message { type string; } 1309 leaf language { type string; } 1310 } 1311 } 1313 rpc get-reboot-info { 1314 output { 1315 leaf reboot-time { 1316 units seconds; 1317 type uint32; 1318 } 1319 leaf message { type string; } 1320 leaf language { type string; } 1321 } 1322 } 1323 } 1325 The client might send the following POST request message: 1327 POST example.com/restconf/operations/example-ops:reboot 1328 Token:0x56 1329 Content-Type: 1330 { "example-ops:input": 1331 { 1332 "delay": 600, 1333 "message": "Going down for system maintenance" 1334 "language": "en-US" 1335 } 1336 } 1338 The server may respond with a 2.04 Changed. 1340 4.4.2. Encoding RPC output parameters 1342 If the "rpc" statement has output parameters, then the "output" node 1343 is provided in a PUT message, corresponding to the YANG data 1344 definition statements within the "output" section. 1346 The "example-ops" YANG module defined Section 4.4 is used for the 1347 examples in this section. 1349 The client might send the following POST request message: 1351 POST example.com/mg/op/example-ops:get-reboot-info 1352 Token: 0x56 1354 The server might respond with a POST request that is related to the 1355 original RPC invocation by the Token value: 1357 POST [ip:port]/mg/op/example-ops:output 1358 Token: 0x56 1359 {"example-ops:output" : 1360 { 1361 "reboot-time" : 30, 1362 "message" : "Going down for system maintenance", 1363 "language" : "en-US" 1364 } 1365 } 1367 4.5. Use of Block 1369 The CoAP protocol provides reliability by acknowledging the UDP 1370 datagrams. However, when large pieces of text need to be transported 1371 the datagrams get fragmented, thus creating constraints on the 1372 resources in the client, server and intermediate routers. The block 1373 option [I-D.ietf-core-block] allows the transport of the total 1374 payload in individual blocks of which the size can be adapted to the 1375 underlying fragment sizes such as: (UDP datagram size ~64KiB, IPv6 1376 MTU of 1280, IEEE 802.15.4 payload of 60-80 bytes). Each block is 1377 individually acknowledged to guarantee reliability. 1379 The block size is specified as exponents of the power 2. The SZX 1380 exponent value can have 7 values ranging from 0 to 6 with associated 1381 block sizes given by 2**(SZX+4); for example SZX=0 specifies block 1382 size 16, and SZX=3 specifies block size 128. 1384 The block number of the block to transmit can be specified. There 1385 are two block options: Block1 option for the request payload 1386 transported with PUT, POST or PATCH, and the block2 option for the 1387 response payload with GET. Block1 and block2 can be combined. 1388 Examples showing the use of block option in conjunction with observer 1389 options are provided in [I-D.ietf-core-block]. 1391 Notice that the Block mechanism splits the data at fixed positions, 1392 such that individual data fields may become fragmented. Therefore, 1393 assembly of multiple blocks may be required to process the complete 1394 data field. 1396 Beware of race conditions. Blocks are filled one at a time and care 1397 should be taken that the whole data representation is sent in 1398 multiple blocks sequentially without interruption. In the server, 1399 values are changed, lists are re-ordered, extended or reduced. When 1400 these actions happen during the serialization of the contents of the 1401 variables, the transported results do not correspond with a state 1402 having occurred in the server; or worse the returned values are 1403 inconsistent. For example: array length does not correspond with 1404 actual number of items. It may be advisable to use CBOR maps or CBOR 1405 arrays of undefined length which are foreseen for data streaming 1406 purposes. 1408 4.6. Resource Discovery 1410 The presence and location of (path to) the management data are 1411 discovered by sending a GET request to "/.well-known/core" including 1412 a resource type (RT) parameter with the value "core.mg" [RFC6690]. 1413 Upon success, the return payload will contain the root resource of 1414 the management data. It is up to the implementation to choose its 1415 root resource, but it is recommended that the value "/mg" is used, 1416 where possible. The example below shows the discovery of the 1417 presence and location of management data. 1419 REQ: GET /.well-known/core?rt=core.mg 1421 RES: 2.05 Content ; rt="core.mg" 1423 Management objects MAY be discovered with the standard CoAP resource 1424 discovery. The implementation can add the encoded values of the 1425 object identifiers to /.well-known/core with rt="core.mg.data". The 1426 available objects identified by the encoded values can be discovered 1427 by sending a GET request to "/.well-known/core" including a resource 1428 type (RT) parameter with the value "core.mg.data". Upon success, the 1429 return payload will contain the registered encoded values and their 1430 location. The example below shows the discovery of the presence and 1431 location of management data. 1433 REQ: GET /.well-known/core?rt=core.mg.data 1435 RES: 2.05 Content ; rt="core.mg.data", 1436 ; rt="core.mg.data" 1438 Lists of encoded values may become prohibitively long. It is 1439 discouraged to provide long lists of objects on discovery. 1440 Therefore, it is recommended that details about management objects 1441 are discovered by reading the YANG module information stored in the 1442 "ietf-yang-library" module [I-D.ietf-netconf-restconf]. The resource 1443 "/mg/mod.uri" is used to retrieve the location of the YANG module 1444 library. 1446 The module list can be stored locally on each server, or remotely on 1447 a different server. The latter is advised when the deployment of 1448 many servers are identical. 1450 Local in example.com server: 1452 REQ: GET example.com/mg/mod.uri 1454 RES: 2.05 Content (Content-Format: application/cbor) 1455 { 1456 "mod.uri" : "example.com/mg/modules" 1457 } 1459 Remote in example-remote-server: 1461 REQ: GET example.com/mg/mod.uri 1463 RES: 2.05 Content (Content-Format: application/cbor) 1464 { 1465 "moduri" : "example-remote-server.com/mg/group17/modules" 1466 } 1468 Within the YANG module library all information about the module is 1469 stored such as: module identifier, identifier hierarchy, grouping, 1470 features and revision numbers. 1472 The hash identifier is obtained as specified in 1473 [I-D.bierman-core-yang-hash]. When a collision occurred in the name 1474 space of the target server, a rehash is executed. 1476 4.7. Error Return Codes 1478 The RESTCONF return status codes defined in section 6 of the RESTCONF 1479 draft are used in CoMI error responses, except they are converted to 1480 CoAP error codes. 1482 +-------------------------------+------------------+ 1483 | RESTCONF Status Line | CoAP Status Code | 1484 +-------------------------------+------------------+ 1485 | 100 Continue | none? | 1486 | | | 1487 | 200 OK | 2.05 | 1488 | | | 1489 | 201 Created | 2.01 | 1490 | | | 1491 | 202 Accepted | none? | 1492 | | | 1493 | 204 No Content | 2.04 Changed | 1494 | | | 1495 | 304 Not Modified | 2.03 | 1496 | | | 1497 | 400 Bad Request | 4.00 | 1498 | | | 1499 | 403 Forbidden | 4.03 | 1500 | | | 1501 | 404 Not Found | 4.04 | 1502 | | | 1503 | 405 Method Not Allowed | 4.05 | 1504 | | | 1505 | 409 Conflict | none? | 1506 | | | 1507 | 412 Precondition Failed | 4.12 | 1508 | | | 1509 | 413 Request Entity Too Large | 4.13 | 1510 | | | 1511 | 414 Request-URI Too Large | 4.00 | 1512 | | | 1513 | 415 Unsupported Media Type | 4.15 | 1514 | | | 1515 | 500 Internal Server Error | 5.00 | 1516 | | | 1517 | 501 Not Implemented | 5.01 | 1518 | | | 1519 | 503 Service Unavailable | 5.03 | 1520 +-------------------------------+------------------+ 1522 5. Error Handling 1524 In case a request is received which cannot be processed properly, the 1525 managed entity MUST return an error message. This error message MUST 1526 contain a CoAP 4.xx or 5.xx response code, and SHOULD include 1527 additional information in the payload. 1529 Such an error message payload is encoded in CBOR, using the following 1530 structure: 1532 TODO: Adapt RESTCONF data structure for use in CoMI. Need 1533 to select the most important fields like . 1535 errorMsg : ErrorMsg; 1537 *ErrorMsg { 1538 errorCode : uint; 1539 ?errorText : tstr; 1540 } 1542 The variable "errorCode" has one of the values from the table below, 1543 and the OPTIONAL "errorText" field contains a human readable 1544 explanation of the error. 1546 +----------------+----------------+---------------------------------+ 1547 | CoMI Error | CoAP Error | Description | 1548 | Code | Code | | 1549 +----------------+----------------+---------------------------------+ 1550 | 0 | 4.00 | General error | 1551 | | | | 1552 | 1 | 4.00 | Malformed CBOR data | 1553 | | | | 1554 | 2 | 4.00 | Incorrect CBOR datatype | 1555 | | | | 1556 | 3 | 4.00 | Unknown MIB variable | 1557 | | | | 1558 | 4 | 4.00 | Unknown conversion table | 1559 | | | | 1560 | 5 | 4.05 | Attempt to write read-only | 1561 | | | variable | 1562 | | | | 1563 | 0..2 | 5.01 | Access exceptions | 1564 | | | | 1565 | 0..18 | 5.00 | SMI error status | 1566 +----------------+----------------+---------------------------------+ 1568 The CoAP error code 5.01 is associated with the exceptions defined in 1569 [RFC3416] and CoAP error code 5.00 is associated with the error- 1570 status defined in [RFC3416]. 1572 6. Security Considerations 1574 For secure network management, it is important to restrict access to 1575 configuration variables only to authorized parties. This requires 1576 integrity protection of both requests and responses, and depending on 1577 the application encryption. 1579 CoMI re-uses the security mechanisms already available to CoAP as 1580 much as possible. This includes DTLS [RFC6347] for protected access 1581 to resources, as well suitable authentication and authorization 1582 mechanisms. 1584 Among the security decisions that need to be made are selecting 1585 security modes and encryption mechanisms (see [RFC7252]). This 1586 requires a trade-off, as the NoKey mode gives no protection at all, 1587 but is easy to implement, whereas the X.509 mode is quite secure, but 1588 may be too complex for constrained devices. 1590 In addition, mechanisms for authentication and authorization may need 1591 to be selected. 1593 CoMI avoids defining new security mechanisms as much as possible. 1594 However some adaptations may still be required, to cater for CoMI's 1595 specific requirements. 1597 7. IANA Considerations 1599 'rt="core.mg.data"' needs registration with IANA. 1601 'rt="core.mg.moduri"' needs registration with IANA. 1603 'rt="core.mg.num-type"' needs registration with IANA. 1605 'rt="core.mg.srv-type"' needs registration with IANA. 1607 'rt="core.mg.yang-hash"' needs registration with IANA. 1609 'rt="core.mg.stream"' needs registration with IANA. 1611 'rt="core.mg.op"' needs registration with IANA. 1613 Content types to be registered: 1615 o application/comi+cbor 1617 8. Acknowledgements 1619 We are very grateful to Bert Greevenbosch who was one of the original 1620 authors of the CoMI specification and specified CBOR encoding and use 1621 of hashes. Mehmet Ersue and Bert Wijnen explained the encoding 1622 aspects of PDUs transported under SNMP. Carsten Bormann has given 1623 feedback on the use of CBOR. The draft has benefited from comments 1624 (alphabetical order) by Somaraju Abhinav, Rodney Cummings, Dee 1625 Denteneer, Esko Dijk, Michael van Hartskamp, Alexander Pelov, Juergen 1626 Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes Tschofenig, Michel 1627 Veillette, Michael Verschoor, and Thomas Watteyne. 1629 9. Changelog 1631 Changes from version 00 to version 01 1633 o Focus on MIB only 1635 o Introduced CBOR, JSON, removed BER 1637 o defined mappings from SMI to xx 1639 o Introduced the concept of addressable table rows 1641 Changes from version 01 to version 02 1643 o Focus on CBOR, used JSON for examples, removed XML and EXI 1645 o added uri-query attributes mod and con to specify modules and 1646 contexts 1648 o Definition of CBOR string conversion tables for data reduction 1650 o use of Block for multiple fragments 1652 o Error returns generalized 1654 o SMI - YANG - CBOR conversion 1656 Changes from version 02 to version 03 1658 o Added security considerations 1660 Changes from version 03 to version 04 1662 o Added design considerations section 1664 o Extended comparison of management protocols in introduction 1665 o Added automatic generation of CBOR tables 1667 o Moved lowpan table to Appendix 1669 Changes from version 04 to version 05 1671 o Merged SNMP access with RESTCONF access to management objects in 1672 small devices 1674 o Added CoMI architecture section 1676 o Added RESTCONf NETMOD description 1678 o Rewrote section 5 with YANG examples 1680 o Added server and payload size appendix 1682 o Removed Appendix C for now. It will be replaced with a YANG 1683 example. 1685 Changes from version 04 to version 05 1687 o Extended examples with hash representation 1689 o Added keys query parameter text 1691 o Added select query parameter text 1693 o Better separation between specification and instance 1695 o Section on discovery updated 1697 o Text on rehashing introduced 1699 o Elaborated SMI MIB example 1701 o Yang library use described 1703 o use of BigEndian/LittleEndian in Hash generation specified 1705 Changes from version 05 to version 06 1707 o Hash values in payload as hexadecimal and in URL in base64 numbers 1709 o Streamlined CoMI architecture text 1711 o Added select query parameter text 1712 o Data editing optional 1714 o Text on Notify added 1716 o Text on rehashing improved with example 1718 Changes from version 06 to version 07 1720 o reduced payload size by removing JSON hierarchy 1722 o changed rehash handling to support small clients 1724 o added LWM2M comparison 1726 o Notification handling as specified in YANG 1728 o Added Patch function 1730 o Rehashing completely reviewed 1732 o Discover type of YANG name encoding 1734 o Added new resource types 1736 o Read-only servers introduced 1738 o Multiple updates explained 1740 Changes from version 07 to version 08 1742 o Changed YANG Hash algorithm to use module name instead of prefix 1744 o Added rehash bit to allow return values to identify rehashed nodes 1745 in the response 1747 o Removed /mg/mod.set resource since this is not needed 1749 o Clarified that YANG Hash is done even for unimplemented objects 1751 o YANG lists transported as CBOR maps of maps 1753 o Adapted examples with more CBOR explanation 1755 o Added CBOR code examples in new appendix 1757 o Possibility to use other than default stream 1759 o Added text and examples for Patch payload 1760 o Repaired some examples 1762 o Added appendices on hash clash probability and hash clash storage 1763 overhead 1765 Changes from version 08 to version 09 1767 o Removed hash and YANG to CBOR sections 1769 o removed hashes from examples. 1771 o Added RPC 1773 o Added content query parameter. 1775 o Added default handling. 1777 o Listed differences with RESTCONF 1779 10. References 1781 10.1. Normative References 1783 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1784 Requirement Levels", BCP 14, RFC 2119, 1785 DOI 10.17487/RFC2119, March 1997, 1786 . 1788 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1789 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1790 . 1792 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1793 the Network Configuration Protocol (NETCONF)", RFC 6020, 1794 DOI 10.17487/RFC6020, October 2010, 1795 . 1797 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1798 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1799 October 2013, . 1801 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1802 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1803 2014, . 1805 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1806 Application Protocol (CoAP)", RFC 7252, 1807 DOI 10.17487/RFC7252, June 2014, 1808 . 1810 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 1811 DOI 10.17487/RFC7396, October 2014, 1812 . 1814 [I-D.becker-core-coap-sms-gprs] 1815 Becker, M., Li, K., Kuladinithi, K., and T. Poetsch, 1816 "Transport of CoAP over SMS", draft-becker-core-coap-sms- 1817 gprs-05 (work in progress), August 2014. 1819 [I-D.ietf-core-block] 1820 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 1821 draft-ietf-core-block-18 (work in progress), September 1822 2015. 1824 [I-D.ietf-core-observe] 1825 Hartke, K., "Observing Resources in CoAP", draft-ietf- 1826 core-observe-16 (work in progress), December 2014. 1828 [I-D.ietf-netmod-yang-json] 1829 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1830 draft-ietf-netmod-yang-json-08 (work in progress), 1831 February 2016. 1833 [I-D.ietf-netconf-restconf] 1834 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1835 Protocol", draft-ietf-netconf-restconf-09 (work in 1836 progress), December 2015. 1838 [I-D.vanderstok-core-patch] 1839 Stok, P. and A. Sehgal, "Patch Method for Constrained 1840 Application Protocol (CoAP)", draft-vanderstok-core- 1841 patch-02 (work in progress), October 2015. 1843 [I-D.ietf-netconf-yang-patch] 1844 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 1845 Media Type", draft-ietf-netconf-yang-patch-07 (work in 1846 progress), December 2015. 1848 [I-D.bierman-core-yang-hash] 1849 Bierman, A. and P. Stok, "YANG Hash", draft-bierman-core- 1850 yang-hash-00 (work in progress), February 2016. 1852 10.2. Informative References 1854 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1855 Schoenwaelder, Ed., "Structure of Management Information 1856 Version 2 (SMIv2)", STD 58, RFC 2578, 1857 DOI 10.17487/RFC2578, April 1999, 1858 . 1860 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 1861 "Introduction and Applicability Statements for Internet- 1862 Standard Management Framework", RFC 3410, 1863 DOI 10.17487/RFC3410, December 2002, 1864 . 1866 [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An 1867 Architecture for Describing Simple Network Management 1868 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 1869 DOI 10.17487/RFC3411, December 2002, 1870 . 1872 [RFC3414] Blumenthal, U. and B. Wijnen, "User-based Security Model 1873 (USM) for version 3 of the Simple Network Management 1874 Protocol (SNMPv3)", STD 62, RFC 3414, 1875 DOI 10.17487/RFC3414, December 2002, 1876 . 1878 [RFC3416] Presuhn, R., Ed., "Version 2 of the Protocol Operations 1879 for the Simple Network Management Protocol (SNMP)", 1880 STD 62, RFC 3416, DOI 10.17487/RFC3416, December 2002, 1881 . 1883 [RFC3418] Presuhn, R., Ed., "Management Information Base (MIB) for 1884 the Simple Network Management Protocol (SNMP)", STD 62, 1885 RFC 3418, DOI 10.17487/RFC3418, December 2002, 1886 . 1888 [RFC4293] Routhier, S., Ed., "Management Information Base for the 1889 Internet Protocol (IP)", RFC 4293, DOI 10.17487/RFC4293, 1890 April 2006, . 1892 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1893 and A. Bierman, Ed., "Network Configuration Protocol 1894 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1895 . 1897 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1898 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1899 January 2012, . 1901 [RFC6643] Schoenwaelder, J., "Translation of Structure of Management 1902 Information Version 2 (SMIv2) MIB Modules to YANG 1903 Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012, 1904 . 1906 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1907 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1908 . 1910 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1911 Constrained-Node Networks", RFC 7228, 1912 DOI 10.17487/RFC7228, May 2014, 1913 . 1915 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1916 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1917 2014, . 1919 [I-D.ietf-core-interfaces] 1920 Shelby, Z., Vial, M., and M. Koster, "Reusable Interface 1921 Definitions for Constrained RESTful Environments", draft- 1922 ietf-core-interfaces-04 (work in progress), October 2015. 1924 [I-D.ietf-lwig-coap] 1925 Kovatsch, M., Bergmann, O., and C. Bormann, "CoAP 1926 Implementation Guidance", draft-ietf-lwig-coap-03 (work in 1927 progress), July 2015. 1929 [XML] "Extensible Markup Language (XML)", 1930 Web http://www.w3.org/xml. 1932 [OMA] "OMA-TS-LightweightM2M-V1_0-20131210-C", Web 1933 http://technical.openmobilealliance.org/Technical/ 1934 current_releases.aspx. 1936 [DTLS-size] 1937 Hummen, R., Shafagh, H., Raza, S., Voigt, T., and K. 1938 Wehrle, "Delegation-based Authentication and Authorization 1939 for the IP-based Internet of Things", Web 1940 http://www.vs.inf.ethz.ch/publ/papers/ 1941 mshafagh_secon14.pdf. 1943 [mibreg] "Structure of Management Information (SMI) Numbers (MIB 1944 Module Registrations)", Web 1945 http://www.iana.org/assignments/smi-numbers/ 1946 smi-numbers.xhtml/. 1948 [management] 1949 Schoenwalder, J. and A. Sehgal, "Management of the 1950 Internet of Things", Web http://cnds.eecs.jacobs- 1951 university.de/slides/2013-im-iot-management.pdf, 2013. 1953 [dcaf] Bormann, C., Bergmann, O., and S. Gerdes, "Delegated 1954 Authenticated Authorization for Constrained Environments", 1955 Private Information . 1957 [openwsn] Watteijne, T., "Coap size in Openwsn", 1958 Web http://builder.openwsn.org/. 1960 [Erbium] Kovatsch, M., "Erbium Memory footprint for coap-18", 1961 Private Communication . 1963 Appendix A. Payload and Server sizes 1965 This section provides information on code sizes and payload sizes for 1966 a set of management servers. Approximate code sizes are: 1968 +---------------+------------+-------+-------+----------------------+ 1969 | Code | processor | Text | Data | reference | 1970 +---------------+------------+-------+-------+----------------------+ 1971 | Observe agent | erbium | 800 | n/a | [Erbium] | 1972 | | | | | | 1973 | CoAP server | MSP430 | 1K | 6 | [openwsn] | 1974 | | | | | | 1975 | SNMP server | ATmega128 | 9K | 700 | [management] | 1976 | | | | | | 1977 | Secure SNMP | ATmega128 | 30K | 1.5K | [management] | 1978 | | | | | | 1979 | DTLS server | ATmega128 | 37K | 2K | [management] | 1980 | | | | | | 1981 | NETCONF | ATmega128 | 23K | 627 | [management] | 1982 | | | | | | 1983 | JSON parser | CC2538 | 4.6K | 8 | [dcaf] | 1984 | | | | | | 1985 | CBOR parser | CC2538 | 1.5K | 2.6K | [dcaf] | 1986 | | | | | | 1987 | DTLS server | ARM7 | 15K | 4 | [I-D.ietf-lwig-coap] | 1988 | | | | | | 1989 | DTLS server | MSP430 | 15K | 4 | [DTLS-size] | 1990 | | | | | | 1991 | Certificate | MSP430 | 23K | | [DTLS-size] | 1992 | | | | | | 1993 | Crypto | MSP430 | 2-8K | | [DTLS-size] | 1994 +---------------+------------+-------+-------+----------------------+ 1995 Thomas says that the size of the CoAP server is rather arbitrary, as 1996 its size depends mostly on the implementation of the underlying 1997 library modules and interfaces. 1999 Payload sizes are compared for the following request payloads, where 2000 each attribute value is null (N.B. these sizes are educated guesses, 2001 will be replaced with generated data). The identifier are assumed to 2002 be a string representation of the OID. Sizes for SysUpTime differ 2003 due to preambles of payload. "CBOR opt" stands for CBOR payload 2004 where the strings are replaced by table numbers. 2006 +-------------------------+-----------+------+------+----------+ 2007 | Request | BERR SNMP | JSON | CBOR | CBOR opt | 2008 +-------------------------+-----------+------+------+----------+ 2009 | IPnetTOMediaTable | 205 | 327 | ~327 | ~51 | 2010 | | | | | | 2011 | lowpanIfStatsTable | | 710 | 614 | 121 | 2012 | | | | | | 2013 | sysUpTime | 29 | 13 | ~13 | 20 | 2014 | | | | | | 2015 | RESTCONF example | | | | | 2016 +-------------------------+-----------+------+------+----------+ 2018 Appendix B. Comparison with LWM2M 2020 CoMI and LWM2M, both, provide RESTful device management services over 2021 CoAP. Differences between the designs are highlighted in this 2022 section. 2024 LWM2M [OMA] objects are defined by standardized numbers. When new 2025 types are needed, new numbers need to be defined. This is the major 2026 difference with CoMI and YANG, where new modules can incorporate any 2027 type that is required without going through a standardization 2028 process, but may lead to rehashing. On the one hand LWM2M is static 2029 with very small numbered objects, where CoMI with YANG is more 2030 dynamic, with a number conversion overhead. 2032 Unlike CoMI, which enables the use of SMIv2 and YANG data models for 2033 device management, LWM2M defines a new object resource model. This 2034 means that data models need to be redefined in order to use LWM2M. 2035 In contrast, CoMI provides access to a large variety of SMIv2 and 2036 YANG data modules that can be used immediately. 2038 Objects and resources within CoMI are identified with a YANG hash 2039 value, however, each object is described as a link in the CoRE Link 2040 Format by LWM2M. This approach by LWM2M can lead to larger complex 2041 URIs and more importantly payloads can grow large in size. Using a 2042 hash value to represent the objects and resources allows URIs and 2043 payloads to be smaller in size, which is important for constrained 2044 devices that may not have enough resources to process large messages. 2046 LWM2M encodes payload data in Type-length-value (TLV), JSON or plain 2047 text formats. While the TLV encoding is binary and can result in 2048 reduced message sizes, JSON and plain text are likely to result in 2049 large message sizes when lots of resources are being monitored or 2050 configured. Furthermore, CoMI's use of CBOR gives it an advantage 2051 over the LWM2M's TLV encoding as well since this too is more 2052 efficient [citation needed]. 2054 CoMI is aligned with RESTCONF for constrained devices and uses YANG 2055 data models that have objects containing resources organized in a 2056 tree-like structure. On the other hand, LWM2M uses a very flat data 2057 model that follows the "object/instance/resource" format, with no 2058 possibility to have sub-resources. Complex data models are, as such, 2059 harder to model with LWM2M. 2061 In situations where resources need to be modified, CoMI uses the CoAP 2062 PATCH operation when resources are modified partially. However, 2063 LWM2M uses the CoAP PUT and POST operations, even when a subset of 2064 the resource needs modifications. 2066 Authors' Addresses 2068 Peter van der Stok 2069 consultant 2071 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2072 Email: consultancy@vanderstok.org 2073 URI: www.vanderstok.org 2075 Andy Bierman 2076 YumaWorks 2077 685 Cochran St. 2078 Suite #160 2079 Simi Valley, CA 93065 2080 USA 2082 Email: andy@yumaworks.com