idnits 2.17.00 (12 Aug 2021) /tmp/idnits37567/draft-vanderstok-core-comi-04.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 38 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 7 characters in excess of 72. == There are 2 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 == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (May 8, 2014) is 2934 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: Informational ---------------------------------------------------------------------------- == Unused Reference: 'I-D.ietf-json-rfc4627bis' is defined on line 1196, but no explicit reference was found in the text == Unused Reference: 'RFC2863' is defined on line 1214, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 1238, but no explicit reference was found in the text == Unused Reference: 'RFC4113' is defined on line 1246, but no explicit reference was found in the text == Unused Reference: 'RFC4291' is defined on line 1249, but no explicit reference was found in the text == Unused Reference: 'RFC6347' is defined on line 1263, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-core-groupcomm' is defined on line 1282, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-06) exists of draft-becker-core-coap-sms-gprs-04 == Outdated reference: draft-ietf-core-block has been published as RFC 7959 == Outdated reference: draft-ietf-core-coap has been published as RFC 7252 == Outdated reference: draft-ietf-core-observe has been published as RFC 7641 == Outdated reference: draft-ietf-json-rfc4627bis has been published as RFC 7158 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: draft-ietf-core-groupcomm has been published as RFC 7390 == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-01 == Outdated reference: draft-ietf-6lo-lowpan-mib has been published as RFC 7388 Summary: 2 errors (**), 0 flaws (~~), 19 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: Informational B. Greevenbosch 5 Expires: November 9, 2014 Huawei Technologies 6 May 8, 2014 8 CoAp Management Interfaces 9 draft-vanderstok-core-comi-04 11 Abstract 13 The draft describes an interface based on CoAP to manage constrained 14 devices via MIBs. The proposed integration of CoAP with SNMP reduces 15 the code- and application development complexity by accessing MIBs 16 via a standard CoAP server. The payload of the MIB request is CBOR 17 based on JSON. The mapping from SMI to CBOR is specified. The 18 introduction motivates the choices of CoMI with respect to 19 utilization of YANG, NETCONF, SMI, CBOR, CoAP, and URI structure. 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 November 9, 2014. 43 Copyright Notice 45 Copyright (c) 2014 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. Design considerations . . . . . . . . . . . . . . . . . . 4 62 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 63 2. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. MIB Function Set . . . . . . . . . . . . . . . . . . . . . . 6 65 3.1. SNMP/MIB architecture . . . . . . . . . . . . . . . . . . 6 66 3.1.1. SNMP functions . . . . . . . . . . . . . . . . . . . 7 67 3.1.2. MIB structure . . . . . . . . . . . . . . . . . . . . 7 68 3.2. CoMI Function Set . . . . . . . . . . . . . . . . . . . . 9 69 3.2.1. Single MIB values . . . . . . . . . . . . . . . . . . 10 70 3.2.2. multi MIB values . . . . . . . . . . . . . . . . . . 12 71 3.2.3. Table row . . . . . . . . . . . . . . . . . . . . . . 14 72 3.2.4. MIB discovery . . . . . . . . . . . . . . . . . . . . 15 73 3.2.5. Error returns . . . . . . . . . . . . . . . . . . . . 16 74 4. Mapping SMI to CoMI payload . . . . . . . . . . . . . . . . . 16 75 4.1. CBOR format for MIB data . . . . . . . . . . . . . . . . 16 76 4.2. Table generation . . . . . . . . . . . . . . . . . . . . 17 77 4.3. Mapping SMI to CBOR . . . . . . . . . . . . . . . . . . . 18 78 4.3.1. General overview . . . . . . . . . . . . . . . . . . 18 79 4.3.2. Conversion from YANG datatypes to CBOR datatypes . . 18 80 4.3.3. Examples . . . . . . . . . . . . . . . . . . . . . . 20 81 4.3.4. 6LoWPAN MIB . . . . . . . . . . . . . . . . . . . . . 22 82 5. Trap functions . . . . . . . . . . . . . . . . . . . . . . . 23 83 6. MIB access management . . . . . . . . . . . . . . . . . . . . 23 84 6.1. Notify destinations . . . . . . . . . . . . . . . . . . . 23 85 6.2. Conversion table management . . . . . . . . . . . . . . . 23 86 7. Error handling . . . . . . . . . . . . . . . . . . . . . . . 24 87 8. Security Considerations . . . . . . . . . . . . . . . . . . . 25 88 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 89 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 26 90 11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 26 91 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 92 12.1. Normative References . . . . . . . . . . . . . . . . . . 27 93 12.2. Informative References . . . . . . . . . . . . . . . . . 28 94 Appendix A. Notational Convention for CBOR data . . . . . . . . 30 95 Appendix B. Example conversion table and instance for the LOWPAN 96 MIB . . . . . . . . . . . . . . . . . . . . . . . . 31 97 B.1. Generating the convTableId . . . . . . . . . . . . . . . 31 98 B.2. Generating the string numbers . . . . . . . . . . . . . . 31 99 B.3. Example instance . . . . . . . . . . . . . . . . . . . . 35 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 102 1. Introduction 104 The Constrained RESTful Environments (CoRE) working group aims at 105 Machine to Machine (M2M) applications such as smart energy and 106 building control. 108 Small M2M devices need to be managed in an automatic fashion to 109 handle the large quantities of devices that are expected to be 110 installed in future installations. The management protocol of choice 111 for Internet is SNMP [RFC3410] as is testified by the large number of 112 Management Information Base (MIB) [RFC3418] specifications currently 113 published [STD0001]. More recently, the NETCONF protocol [RFC6241] 114 was developed with an extended set of messages using XML [XML] as 115 data format. The data syntax is specified with YANG [RFC6020] and a 116 mapping from Yang to XML is specified. In [RFC6643] SMIv2 syntax is 117 expressed in Yang. Contrary to SNMP and also CoAP, NETCONF assumes 118 persistent connections for example provided by SSH. The NETCONF 119 protocol provides operations to retrieve, configure, copy, and delete 120 configuration data-stores. Configuring data-stores distinguishes 121 NETCONF from SNMP which operates on standardized MIBs. 123 The CoRE Management Interface (CoMI) is intended to work on 124 standardized data-sets in a stateless client-server fashion and is 125 thus closer to SNMP than to NETCONF. Standardized data sets promote 126 interoperability between small devices and applications from 127 different manufacturers. Stateless communication is encouraged to 128 keep communications simple and the amount of state information small 129 in line with the design objectives of 6lowpan [RFC4944] [RFC6775], 130 RPL [RFC6650], and CoAP [I-D.ietf-core-coap]. 132 The draft [I-D.bierman-netconf-restconf] describes a restful 133 interface to NETCONF data stores and approaches the CoMI approach. 134 CoMI uses SMI encoded in CBOR, and CoAP/UDP to access MIBs, whereas 135 RESTCONF uses YANG encoded in JSON and HTTP/TCP to access NETCONF 136 data stores. CoMI is more low resource oriented than RESTCONF is, 137 and only supports the methods GET, PUT, POST and DELETE. RESTCONF 138 also uses uses the HTTP methods HEAD, OPTIONS and PATCH, which are 139 not available in CoAP. 141 Given the automatic conversion from SMI to YANG, from YANG to JSON, 142 from YANG to XML and from JSON to CBOR, the transported data format 143 is not strongly related to the chosen management protocol. 145 Currently, managed devices need to support two protocols: CoAP and 146 SNMP. When the MIB can be accessed with the CoAP protocol, the SNMP 147 protocol can be replaced with the CoAP protocol. This arrangement 148 reduces the code complexity of the stack in the constrained device, 149 and harmonizes applications development. 151 The objective of CoMI is to provide a CoAP based Function Set that 152 reads and sets values of MIB variables in devices to (1) initialize 153 parameter values at start-up, (2) acquire statistics during 154 operation, and (3) maintain nodes by adjusting parameter values 155 during operation. 157 The payload of CoMI is encoded in CBOR [RFC7049] which is similar to 158 JSON [JSON], but has a binary format and hence has more coding 159 efficiency. CoMI is intended for small devices. The JSON overhead 160 can be prohibitive. It is therefore chosen to transport CBOR in the 161 payload. CBOR, like BER used for SNMP, transports the data type in 162 the payload. 164 The end goal of CoMI is to provide information exchange over the CoAP 165 transport protocol in a uniform manner as a first step to the full 166 management functionality as specified in 167 [I-D.ersue-constrained-mgmt]. 169 1.1. Design considerations 171 COMI supports discovery of resources, accompanied by reading, writing 172 and notification of resource values. As such it is close to the 173 device management of the Open Mobile Alliance described in [OMA]. 174 However, the structure of the MIB does not reflect the structure of 175 the OMA management objects. It is assumed that the structure and 176 semantics of the management data are the most important aspect of a 177 standard like the MIB. The right path forward to integrate OMA 178 management with COMI is the adapatation of the MIB structure by OMA. 180 COMI supports the conversion of SMIv2 via YANG to CBOR. Assuming 181 that CBOR is used for the tanport of NETCONF data, the utilization of 182 the CBOR conversion table to reduce payload size can be envisaged for 183 NETCONF data as well. 185 COMI uses a simple URI to access the MIB resources. Complexity 186 introduced by module name, context specification, or row selection, 187 is expressed with uri-query attributes. The choice for uri-query 188 attributes makes the uri structure less context dependent. 190 1.2. Terminology 192 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 193 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",and "OPTIONAL" in this 194 document are to be interpreted as described in [RFC2119]. 196 Readers of this specification are required to be familiar with all 197 the terms and concepts discussed in [RFC3410], [RFC3416], and 198 [RFC2578]. 200 Core Management Interface (CoMI) specifies the profile of Function 201 Sets which access MIBs with the purpose of managing the operation of 202 constrained devices in a network. 204 The following list defines the terms used in this document: 206 Managing Entity: An entity that manages one or more managed devices. 207 Within the CoMI framework, the managing entity acts as a CoAP 208 client for CoMI. 210 Managed Device: An entity that is being managed. The managed device 211 acts as a CoAP server for CoMI. 213 NOTE: It is assumed that the managed device is the most constrained 214 entity. The managing entity might be more capable, however this is 215 not necessarily the case. 217 The following list contains the abbreviations used in this document. 219 OID: ASN.1 OBJECT-IDENTIFIER, which is used to uniquely identify MIB 220 objects in the managed device. 222 2. CoAP Interface 224 In CoRE a group of links can constitute a Function Set. The format of 225 the links is specified in [I-D.ietf-core-interfaces]. This note 226 specifies a Management Function Set. CoMI end-points that implement 227 the CoMI management protocol support at least one discoverable 228 management resource of resource type (rt): core.mg, with path: /mg, 229 where mg is short-hand for management. The mg resource has two sub- 230 resources accessible with the paths: 232 o MIB with path /mg/mib and a CBOR content format. 234 o conv with path /mg/conv and CBOR content format. 236 The mib resource provides access to the MIBs as described in 237 Section 3.2. The conv resource provides access to a table that maps 238 a string to CBOR identifier, as described in Section 4.1. The mib 239 and conv resources are introduced as sub resources to mg to permit 240 later additions to CoMI mg resource. 242 The profile of the management function set, with IF=core.mg.mib, is 243 shown in the table below, following the guidelines of 244 [I-D.ietf-core-interfaces]: 246 +-----------------+-----------+---------------+-------------------+ 247 | name | path | RT | Data Type | 248 +-----------------+-----------+---------------+-------------------+ 249 | Management | /mg | core.mg | n/a | 250 | | | | | 251 | MIB | /mg/mib | core.mg.mib | application/cbor | 252 | | | | | 253 | conv | /mg/conv | core.mg.conv | application/cbor | 254 +-----------------+-----------+---------------+-------------------+ 256 3. MIB Function Set 258 The MIB Function Set provides a CoAP interface to perform equivalent 259 functions to the ones provided by SNMP. Section 3.1 explains the 260 structure of SNMP Protocol Data Units (PDU), their transport, and the 261 structure of the MIB modules. An excellent overview of the documents 262 describing the SNMP/MIB architecture is provided in section 7 of 263 [RFC3410]. 265 3.1. SNMP/MIB architecture 267 The architecture of the Internet Standard management framework 268 consists of: 270 o A data definition language that is referred to as Structure of 271 Management Information (SMI)[RFC2578]. 273 o The Management Information Base (MIB) which contains the 274 information to be managed and is defined for each specific 275 function to be managed [RFC3418]. 277 o A protocol definition referred to as Simple Network Management 278 Protocol (SNMP) [RFC3416]. 280 o Security and administration that provides SNMP message based 281 security on the basis of the user-based security model [RFC3414]. 283 o A management domain definition where a SNMP entity has access to a 284 collection of management information called a "context" [RFC3411]. 286 In addition [RFC4088] describes a URI scheme to refer to a specific 287 MIB instance. 289 Separation in modules was motivated by the wish to respond to the 290 evolution of Internet. The protocol part (SNMP) and data definition 291 part (MIB) are independent of each other. The separation has enabled 292 the progressive passage from SNMPv1 via SNMPv2 to SNMPv3. This draft 293 leverages this separation to replace the SNMP protocol with a CoAP 294 based protocol. 296 3.1.1. SNMP functions 298 The SNMP protocol supports seven types of access supported by as many 299 Protocol Data Unit (PDU) types: 301 o Get Request, transmits a list of OBJECT-IDENTIFIERs to be paired 302 with values. 304 o GetNext Request, transmits a list of OBJECT-IDENTIFIERs to which 305 lexicographic successors are returned for table traversal. 307 o GetBulk Request, transmits a list of OBJECT-IDENTIFIERs and the 308 maximum number of expected paired values. 310 o Response, returns an error or the (OBJECT-IDENTIFIER, value) pairs 311 for the OBJECT-IDENTIFIERs specified in Get, GetNext, GetBulk, 312 Set, or Inform Requests. 314 o Set Request, transmits a list of (OBJECT-IDENTIFIERs, value) pairs 315 to be set in the specified MIB object. 317 o Trap, sends an unconfirmed message with a list of (OBJECT- 318 IDENTIFIERs, value) pairs to a notification requesting end-point. 320 o Inform Request, sends a confirmed message with a list of (OBJECT- 321 IDENTIFIERs, value) pairs to a notification requesting end-point. 323 3.1.2. MIB structure 325 A MIB module is composed of MIB objects. MIB objects are 326 standardized by the IETF or by other relevant Standards Developing 327 Organizations (SDO). 329 MIB objects have a descriptor and an identifier: OBJECT-IDENTIFIER 330 (OID). The identifier, following the OSI hierarchy, is an ordered 331 list of non-negative numbers [RFC2578]. OID values are unique. Each 332 number in the list is referred as a sub-identifier. The descriptor 333 is unique within a module. Different modules may contain the same 334 descriptor. Consequently, a descriptor can be related to several 335 OIDs. 337 Many instances of an object type exist within a management domain. 338 Each instance can be identified within some scope or "context", where 339 there are multiple such contexts within the management domain. 340 Often, a context is a physical or logical device. A context is 341 always defined as a subset of a single SNMP entity. To identify an 342 individual item of management information within the management 343 domain, its contextName and contextEngineID must be identified in 344 addition to its object type and its instance. A default context is 345 assumed when no context is specified. 347 A MIB object is usually a scalar object. A MIB object may have a 348 tabular form with rows and columns. Such an object is composed of a 349 sequence of rows, with each row composed of a sequence of typed 350 values. The index is a subset (1-2 items) of the typed values in the 351 row. An index value identifies the row in the table. 353 In SMI, a table is constructed as a SEQUENCE OF its entries. For 354 example, the IpAddrTable from [RFC4293] has the following definition: 356 ipv6InterfaceTable OBJECT-TYPE 357 SYNTAX SEQUENCE OF Ipv6InterfaceEntry 358 MAX-ACCESS not-accessible 359 STATUS current 360 DESCRIPTION 361 "The table containing per-interface IPv6-specific 362 information." 363 ::= { ip 30 } 365 ipv6InterfaceEntry OBJECT-TYPE 366 SYNTAX Ipv6InterfaceEntry 367 MAX-ACCESS not-accessible 368 STATUS current 369 DESCRIPTION 370 "An entry containing IPv6-specific information for a given 371 interface." 372 INDEX { ipv6InterfaceIfIndex } 373 ::= { ipv6InterfaceTable 1 } 375 Ipv6InterfaceEntry ::= SEQUENCE { 376 ipv6InterfaceIfIndex InterfaceIndex, 377 ipv6InterfaceReasmMaxSize Unsigned32, 378 ipv6InterfaceIdentifier Ipv6AddressIfIdentifierTC, 379 ipv6InterfaceEnableStatus INTEGER, 380 ipv6InterfaceReachableTime Unsigned32, 381 ipv6InterfaceRetransmitTime Unsigned32, 382 ipv6InterfaceForwarding INTEGER 383 } 385 The descriptor (name) of the MIB table is used for the name of the 386 CoMI variable. However, there is no explicit mention of the names 387 "ipv6InterfaceEntry" and "Ipv6InterfaceEntry". Instead, the value of 388 the main CoMI variable, ipv6InterfaceTable, consists of an array, 389 each element of which contains 7 CoMI variables: one element for 390 "ipv6InterfaceIfIndex", one for "ipv6InterfaceReasmMaxSize" and so on 391 until "ipv6InterfaceForwarding". 393 3.2. CoMI Function Set 395 Three types of interfaces are supported by CoMI: 397 Single value: Reading/Writing one MIB variable, specified in the URI 398 with path /mg/mib/descriptor or with path /mg/mib/OID. 400 Multiple values: Reading writing arrays or multiple MIB variables, 401 specified in the payload. 403 Discovery: Discovery of MIB descriptors as specified in [RFC6690]. 405 The examples in this section use a JSON payload with one or more 406 entries describing the pair (descriptor, value), or (OID, value). 407 CoMI transports the CBOR format to transport the equivalent contents. 408 The CBOR syntax of the payloads is specified in Section 4. 410 3.2.1. Single MIB values 412 A request to read the value of a MIB variable is sent with a 413 confirmable CoAP GET message. The single MIB variable is specified 414 in the URI path with the OID or descriptor suffixing the /mg/mib/ 415 path name. When the descriptor is used to specify the MIB value, the 416 same descriptor may be present in multiple module. To disambiguate 417 the descriptor the "mod" uri-query attribute specifies the enveloping 418 modules. A request to set the value of a MIB variable is sent with a 419 confirmable CoAP PUT message. The Response is piggybacked to the 420 CoAP ACK message corresponding with the Request. 422 TODO: for multicast send unconfirmed PUT 424 Using for example the same MIB from [RFC1213] as used in [RFC3416], a 425 request is sent to retrieve the value of sysUpTime specified in 426 module SNMPv2-MIB. The answer to the request returns a (descriptor, 427 value) pair. 429 As announced, in all examples the payload is expressed in JSON, 430 although the operational payload is specified to be in CBOR. 432 REQ: GET example.com/mg/mib/sysUpTime?mod=SNMPv2-MIB 434 RES: 2.05 Content (Content-Format: application/json) 435 { 436 "sysUpTime" : 123456 437 } 439 Another way to express the descriptor of the required value is by 440 specifying the pair (descriptor or oid, null value) in the payload of 441 the request message. 443 REQ: GET example.com/mg/mib/(Content-Format: application/json) 444 { 445 "SNMPv2-MIB.sysUpTime" : "null" 446 } 448 RES: 2.05 Content (Content-Format: application/json) 449 { 450 "SNMPv2-MIB.sysUpTime" : 123456 451 } 453 The module name SNMPv2-MIB can be omitted when there is no 454 possibility of ambiguity. The module.descriptor can of course be 455 replaced with the corresponding oid. 457 In some cases it is necessary to determine the "context" by 458 specifying a context name and a contextEngine identifier. The 459 context can be specified in the URI with the uri-query attribute 460 "con". Based on the example of figure 3 in section 3.3 of [RFC3411], 461 the context name, bridge1, and the context Engine Identifier, 462 800002b804616263, separated by an underscore, are specified in the 463 following example: 465 REQ: GET example.com/mg/mib/sysUPTime?con=bridge1_800002b804616263 467 RES: 2.05 Content (Content-Format: application/json) 468 { 469 "sysUpTime" : 123456 470 } 472 The specified object can be a table. The returned payload is 473 composed of all the rows associated with the table. Each row is 474 returned as a set of (column name, value) pairs. For example the GET 475 of the ipNetToMediaTable, sent by the managing entity, results in the 476 following returned payload sent by the managed entity: 478 REQ: GET example.com/mg/mib/ipNetToMediaTable 480 RES: 2.05 Content (Content-Format: application/json) 481 { 482 "ipNetTOMediaTable" : [ 483 { 484 "ipNetToMediaIfIndex" : 1, 485 "ipNetToMediaPhysAddress" : "00:00::10:01:23:45", 486 "ipNetToMediaNetAddress" : "10.0.0.51", 487 "ipNetToMediaType" : "static" 488 }, 489 { 490 "ipNetToMediaIfIndex" : 1, 491 "ipNetToMediaPhysAddress" : "00:00::10:54:32:10", 492 "ipNetToMediaNetAddress" : "9.2.3.4", 493 "ipNetToMediaType" : "dynamic" 494 }, 495 { 496 "ipNetToMediaIfIndex" : 2, 497 "ipNetToMediaPhysAddress" : "00:00::10:98:76:54", 498 "ipNetToMediaNetAddress" : "10.0.0.15", 499 "ipNetToMediaType" : "dynamic" 500 } 501 ] 502 } 504 It is possible that the size of the returned payload is too large to 505 fit in a single message. 507 CoMI gives the possibility to send the contents of the objects in 508 several fragments with a maximum size. The "sz" link-format 509 attribute [RFC6690] can be used to specify the expected maximum size 510 of the mib resource in (identifier, value) pairs. The returned data 511 MUST terminate with a complete (identifier, value) pair. 513 In the case that management data is bigger than the maximum supported 514 payload size, the Block mechanism from [I-D.ietf-core-block] is used. 515 Notice that the Block mechanism splits the data at fixed positions, 516 such that individual data fields may become fragmented. Therefore, 517 assembly of multiple blocks may be required to process the complete 518 data field. 520 3.2.2. multi MIB values 522 A request to read multiple MIB variables is done by expressing the 523 pairs (MIB descriptor, null) in the payload of the GET request 524 message. A request to set multiple MIB variables is done by 525 expressing the pairs (MIB descriptor, value) in the payload of the 526 PUT request message. The key word _multiMIB is used as array name to 527 signal that the payload contains multiple MIB values as separate 528 _multiMIB array entries. 530 The following example shows a request that specifies to return the 531 values of sysUpTime and ipNetToMediaTable: 533 REQ: GET example.com/mg/mib (Content-Format: application/json) 534 { 535 "_multiMIB" : [ 536 { "sysUpTime" : "null"}, 537 { "ipNetToMediaTable" : "null" } 538 ] 539 } 541 RES: 2.05 Content (Content-Format: application/json) 542 { 543 "_multiMIB" : [ 544 { "sysUpTime" : 123456}, 545 { "ipNetTOMediaTable" : [ 546 { 547 "ipNetToMediaIfIndex" : 1, 548 "ipNetToMediaPhysAddress" : "00:00::10:01:23:45", 549 "ipNetToMediaNetAddress" : "10.0.0.51", 550 "ipNetToMediaType" : "static" 551 }, 552 { 553 "ipNetToMediaIfIndex" : 1, 554 "ipNetToMediaPhysAddress" : "00:00::10:54:32:10", 555 "ipNetToMediaNetAddress" : "9.2.3.4", 556 "ipNetToMediaType" : "dynamic" 557 }, 558 { 559 "ipNetToMediaIfIndex" : 2, 560 "ipNetToMediaPhysAddress" : "00:00::10:98:76:54", 561 "ipNetToMediaNetAddress" : "10.0.0.15", 562 "ipNetToMediaType" : "dynamic" 563 } 564 ] 565 } 566 ] 567 } 569 3.2.3. Table row 571 The managing entity MAY be interested only in certain table entries. 572 One way to specify a row is to specify its row number in the URI with 573 the "row" uri-query attribute. The specification of row=1 returns 574 row 1 values of the ipNetToMediaTable in the example: 576 REQ: GET example.com/mg/mib/ipNetToMediaTable?row=1 578 RES: 2.05 Content (Content-Format: application/json) 579 { "ipNetTOMediaTable" : [ 580 { 581 "ipNetToMediaIfIndex" : 1, 582 "ipNetToMediaPhysAddress" : "00:00::10:01:23:45", 583 "ipNetToMediaNetAddress" : "10.0.0.51", 584 "ipNetToMediaType" : "static" 585 } 586 ] 587 } 589 An alternative mode of selection is by specifying the value of the 590 INDEX attributes. Towards this end, the managing entity can include 591 the required entries in the payload of its "GET" request by 592 specifying the values of the index attributes. The key word 593 _indexMIB is used to specify the index value. 595 For example, to obtain a table entry from ipNetToMediaTable, the rows 596 are specified by specifying the index attributes: ipNetToMediaIfIndex 597 and ipNetToMediaNetAddress. The managing entity could have sent a 598 GET with the following payload: 600 REQ: GET example.com/mg/mib/ipNetToMediaTable(Content-Format: application/json) 602 { "_indexMIB" : 603 { 604 "ipNetToMediaIfIndex" : 1, 605 "ipNetToMediaNetAddress" : "9.2.3.4" 606 } 607 } 609 RES: 2.05 Content (Content-Format: application/json) 610 { "ipNetTOMediaTable" : [ 611 { 612 "ipNetToMediaIfIndex" : 1, 613 "ipNetToMediaPhysAddress" : "00:00::10:01:23:45", 614 "ipNetToMediaNetAddress" : "9.2.3.4", 615 "ipNetToMediaType" : "static" 616 } 617 ] 618 } 620 Constrained devices MAY support this kind of filtering. However, if 621 they don't support it, they MUST ignore the payload in the GET 622 request and handle the message as if the payload was empty. 624 It is advised to keep MIBs for constrained entities as simple as 625 possible, and therefore it would be best to avoid extensive tables. 627 TODO: Describe how the contents of the next lexicographical row can 628 be returned. 630 3.2.4. MIB discovery 632 MIB objects are discovered like resources with the standard CoAP 633 resource discovery. Performing a GET on "/.well-known/core" with 634 rt=core.mg.mib returns all MIB descriptors and all OIDs which are 635 available on this device. For table objects there is no further 636 possibility to discover the row descriptors. For example, consider 637 there are two MIB objects with descriptors "sysUpTime" and 638 "ipNetToMediaTable" associated with OID 1.3.6.1.2.1.1.3 and 639 1.3.6.1.2.1.4.22 641 REQ: GET example.com/.well-known/core?rt=core.mg.mib 643 RES: 2.05 Content (Content-Format: application/text) 644 ;rt="core.mg.mib";oid="1.3.6.1.2.1.1.3"; 645 mod="SNMPv2-MIB" 646 ;rt="core.mg.mib";oid="1.3.6.1.2.1.4.22"; 647 mod="ipMIB" 649 The link format attribute 'oid' is used to associate the name of the 650 MIB resource with its OID. The OID is written as a string in its 651 conventional form. 653 Notice that a MIB variable normally is associated with a descriptor 654 and an OID. The OID is unique, whereas the descriptor is unique in 655 combination with the module name. 657 The "mod", "con", and "rt" attributes can be used to filter resource 658 queries as specified in [RFC6690]. 660 3.2.5. Error returns 662 When a variable with the specified name cannot be processed, CoAP 663 Error code 5.01 is returned. In addition, a MIB specific error can 664 be returned in the payload as specified in Section 7. 666 4. Mapping SMI to CoMI payload 668 The SMI syntax is mapped to CBOR necessary for the transport of MIB 669 data in the CoAP payload. This section first describes an additional 670 data reduction technique by creating a table that maps string values 671 to numbers used in CBOR encoded data. 673 The section continues by describing the mapping from SMI to CBOR. 674 The mapping is inspired by the mapping from SMI to JSON via YANG 675 [RFC6020], as described in [RFC6643] defining a mapping from SMI to 676 YANG, and [I-D.lhotka-netmod-yang-json] defining a mapping from YANG 677 to JSON. 679 Notice that such conversion chain MAY be virtual only, as SMI could 680 be converted directly to JSON by combining the rules from the above 681 documents. 683 4.1. CBOR format for MIB data 685 Because descriptors may be rather long and may occur repeatedly, CoMI 686 allows for association of a given string value with an integer, 687 henceforth called "string number". The association between string 688 value and string number is done through a conversion table, 689 leveraging CBOR encoding. Section 4.2 defines how the conversion 690 table is generated. 692 Using the notational convention from Appendix A, the CBOR data has 693 the following syntax: 695 cBorMIB : CBorMIB; 697 *CBorMIB { 698 convTableId : tstr; 699 mibData : map( uint, . ); 700 } 702 The main structure consist of an array of two elements: "convTableId" 703 and "mibData". 705 The conversion table identifier "convTableId" is constructed from the 706 LAST_UPDATED attribute and module name as defined in Section 4.2. 708 The values of the MIB variables are stored in the "mibData" field. 709 This field consist of integer-value pairs. The integers correspond 710 to the string numbers, whereas the values contain the actual value of 711 the associated MIB variable. Section 4.3 elaborates on the mapping 712 from SMI to CBOR. 714 4.2. Table generation 716 The conversion table contents MUST be automatically generated from 717 the MIB module as specified in this section. Automatic generation in 718 the managed device removes the need to transport the tables and 719 subsequently store them in the nodes, and avoids a cumbersome 720 management of the conversion tables. 722 The conversion table identifier "convTableId" is generated from the 723 LAST-UPDATED field in the MODULE IDENTITY macro, and the module name 724 as follows: 726 convTableId = moduleName UNDERSCORE lastUpdateTimestamp 727 UNDERSCORE = %x5F 729 where moduleName is the module name, and lastUpdateTimestamp is the 730 value of the related LAST-UPDATED field in the MODULE-IDENTITY macro, 731 using the format with four year digits as defined in [RFC2578]. 733 The conversion table is generated using the following algorithm: 735 1. Collect all used OIDs/descriptors defined in the MIB object, and 736 as well as those imported using IMPORTS. 738 2. Sort the collection of OIDs according to the following rules: 740 1. x.y.z < x.y.z.k 742 2. x.y.z... < x.y.k... if z