]> consultant

+31-492474673 (Netherlands), +33-966015248 (France) consultancy@vanderstok.org www.vanderstok.org

Huawei Technologies Co., Ltd.

Huawei Industrial Base Bantian, Longgang District Shenzhen 518129 P.R. China bert.greevenbosch@huawei.com

Applications core The draft describes an interface based on CoAP to manage constrained devices via MIBs. The proposed integration of CoAP with SNMP reduces the code- and application development complexity by accessing MIBs via a standard CoAP server. The payload of the MIB request is JSON, CBOR or XML (EXI). The mapping from SMI to XML, JSON and CBOR is specified. Discussion and suggestions for improvement are requested, and should be sent to core@ietf.org.

The Constrained RESTful Environments (CoRE) working group aims at Machine to Machine (M2M) applications such as smart energy and building control. Small M2M devices need to be managed in an automatic fashion to handle the large quantities of devices that are expected to be installed in future installations. The management protocol of choice for Internet is SNMP as is testified by the large number of Management Information Base (MIB) specifications currently published . More recently, the NETCONF protocol was developed with an extended set of messages using XML as data format. The data syntax is specified with YANG and a mapping from Yang to XML is specified. In SMIv2 syntax is expressed in Yang. Contrary to SNMP and also CoAP, NETCONF assumes persistent connections for example provided by SSH. The NETCONF protocol provides operations to retrieve, configure, copy, and delete configuration data-stores. Configuring data-stores distinguishes NETCONF from SNMP which operates on standardized MIBs. The CoRE Management Interface (CoMI) is intended to work on standardized data-sets in a stateless client-server fashion and is thus closer to SNMP than to NETCONF. Standardized data sets are necessary when small devices from different manufacturers are managed by applications originating from another set of manufacturers. Stateless communication is encouraged to keep communications simple and the amount of state information small in line with the design objectives of 6lowpan , RPL , and CoAP . Currently, managed devices need to support two protocols: CoAP and SNMP. When the MIB can be accessed with the CoAP protocol, the SNMP protocol can be replaced with the CoAP protocol. This arrangement reduces the code complexity of the stack in the constrained device, and harmonizes applications development. The objective of CoMI is to provide a CoAP based Function Set that reads and sets values of MIB variables in devices to (1) initialize parameter values at start-up, (2) acquire statistics during operation, and (3) maintain nodes by adjusting parameter values during operation. The payload of CoMI is encoded in JSON , CBOR or XML . CoMI is intended for small devices. The XML or JSON overhead can be prohibitive. It is therefore recommended to transport CBOR or EXI in the payload. CBOR, like BER used for SNMP, transports the data type in the payload. EXI uses a schema file that provides information about transported data types. In it is shown that EXI can be an order of magnitude smaller than the equivalent XML representation. Actually, the EXI structure adds the overhead per data unit of an EXI event (indicates the type of the following XML element) with a size that depends on the number of EXI event types present in the schema and its frequency of occurrence. In it is shown that memory and CPU usage for sending JSON encoded or XML encoded objects led on average to a 50% lower resource usage for JSON. Consequently, from a resource utilization point of view EXI and CBOR seem the right choice. CBOR does not need a schema, but EXI requires one for decoding. Consequently, for EXI different schema versions must be handled by a versioning scheme. The end goal of CoMI is to provide information exchange over the CoAP transport protocol in a uniform manner to approach the full management functionality as specified in .

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",and "OPTIONAL" in this document are to be interpreted as described in . Readers of this specification are required to be familiar with all the terms and concepts discussed in , , and . Core Management Interface (CoMI) specifies the profile of Function Sets which access MIBs with the purpose of managing the operation of constrained devices in a network. The following list defines the terms used in this document: An entity that manages one or more managed devices. Within the CoMI framework, the managing entity acts as a CoAP client for CoMI. An entity that is being managed. The managed device acts as a CoAP server for CoMI. NOTE: It is assumed that the managed device is the most constrained entity. The managing entity might be more capable, however this is not necessarily the case. The following list contains the abbreviations used in this document. ASN.1 OBJECT-IDENTIFIER, which is used to uniquely identify MIB objects in the managed device

In CoRE a group of links can constitute a Function Set. The format of the links is specified in . This note specifies a Management Function Set. CoMI end-points that implement the CoMI management protocol support at least one discoverable management resource of resource type (rt): core.mg, with path: /mg, where mg is short-hand for management. The mg resource has one sub-resource accessible with the path: MIB with path /mg/mib and an XML (EXI), JSON or CBOR content format. The mib resource provides access to the MIBs described in . The mib resource is introduced as a sub resource to mg to permit later additions to CoMI mg resource. XML and JSON schemas describe the structure of the MIBs. It is expected that given the verbosity of XML and JSON, CoMI messages will mostly use EXI or CBOR. The profile of the management function set, with IF=core.mg.mib, is shown in the table below, following the guidelines of : name path RT Data Type Management /mg core.mg n/a MIB /mg/mib core.mg.mib application/json MIB /mg/mib core.mg.mib application/cbor MIB /mg/mib core.mg.mib application/xml MIB /mg/mib core.mg.mib application/exi The value of the EXI events have a different meaning dependent on the accompanying schema file. Schemas are sent to the device at initialization such that it can prepare the parsing tables in advance. Schema management is discussed in . No such schema is needed for CBOR.

The MIB Function Set provides a CoAP interface to perform equivalent functions to the ones provided by SNMP. explains the structure of SNMP PDUs and their transport.

The architecture of the Internet Standard management framework consists of: A data definition language that is referred to as Structure of Management Information (SMI). The Management Information Base (MIB) which contains the information to be managed and is defined for each specific function to be managed . A protocol definition referred to as Simple Network Management Protocol (SNMP) . Security and administration that provides SNMP message based security on the basis of the user-based security model . Separation in modules was motivated by the wish to respond to the evolution of Internet. The protocol part (SNMP) and data definition part (MIB) are independent of each other. The separation has enabled the progressive passage from SNMPv1 via SNMPv2 to SNMPv3. This draft leverages this separation to replace the SNMP protocol with a CoAP based protocol.

The SNMP protocol supports seven types of access supported by as many Protocol Data Unit (PDU) types: Get Request, transmits a list of OBJECT-IDENTIFIERs to be paired with values. GetNext Request, transmits a list of OBJECT-IDENTIFIERs to which lexicographic successors are returned for table traversal. GetBulk Request, transmits a list of OBJECT-IDENTIFIERs and the maximum number of expected paired values. Response, returns an error or the (OBJECT-IDENTIFIER, value) pairs for the OBJECT-IDENTIFIERs specified in Get, GetNext, GetBulk, Set, or Inform Requests. Set Request, transmits a list of (OBJECT-IDENTIFIERs, value) pairs to be set in the specified MIB object. Trap, sends an unconfirmed message with a list of (OBJECT-IDENTIFIERs, value) pairs to a notification requesting end-point. Inform Request, sends a confirmed message with a list of (OBJECT-IDENTIFIERs, value) pairs to a notification requesting end-point. The binding of the notification to a destination is discussed in .

A MIB module is composed of MIB objects. MIB objects have a descriptor and an identifier: OBJECT-IDENTIFIER (OID). The identifier, following the OSI hierarchy, is an ordered list of non-negative numbers . OID values are unique. Each number in the list is referred as a sub-identifier. One descriptor can be related to several OIDs. A MIB object is usually a scalar object. A MIB object may have a tabular form with rows and columns. Such an object is composed of a sequence of rows, with each row composed of a sequence of typed values. An index value identifies the row in the table. In SMI, a table is constructed as a SEQUENCE OF its entries. For example, the IpAddrTable from has the following definition:

The name of the MIB table is used for the name of the CoMI variable. However, there is no explicit mention of the names "ipv6InterfaceEntry" and "Ipv6InterfaceEntry". Instead, the value of the main CoMI variable consists of an array, each element of which contains 7 CoMI variables: one element for "ipv6InterfaceIfIndex", one for "ipv6InterfaceReasmMaxSize" and so on until "ipv6InterfaceForwarding".

Two types of interfaces are supported by CoMI: Reading/Writing one MIB variable, specified in the URI with path /mg/mib/descriptor or with path /mg/mib/OID. Reading writing arrays or multiple MIB variables, specified in the payload. A MIB object has a descriptor and an OID that identifies it uniquely within the device. MIB objects are standardized by the IETF or by other relevant Standards Developing Organizations (SDO). The examples in this section use a payload with one or more entries describing the pair (descriptor, value), or (OID, value). The syntax of the payloads is specified in .

A request to read the value of a MIB variable is sent with a confirmable CoAP GET message. The single MIB variable is specified in the URI path with the OID or descriptor suffixing the /mg/mib/ path name. A request to set a value is sent with a confirmable CoAP PUT message. The Response is piggybacked to the CoAP ACK message corresponding with the Request. Using for example the same MIB from as used in , a request is sent to retrieve the value of sysUpTime. The answer to the request returns a (descriptor, value) pair. The syntax of the payload is specified in .

The specified object can be a table. The returned payload is composed of all the rows associated with the table. Each row is returned as a set of (column name, value) pairs. For example the a GET of the ipNetToMediaTable, sent by the managing entity, results in the following returned payload sent by the managed entity:

The used syntax is for demonstration purposes only. Rows are encapsulated witin brackets, similar to the individual row elements. The syntax of the payload is specified in . It is possible that the size of the returned payload is too large to fit in a single message. CoMI gives the possibility to send the contents of the objects in several fragments with a maximum size. The "sz" link-format attribute can be used to specify the expected maximum size of the mib resource in (identifier, value) pairs. The returned data MUST terminate with a complete (identifier, value) pair. The sequel can be asked by sending the same request but with a uri-query indicating the offset of the first of the next requested pairs. This offset is equal to the already received number of pairs. The uri-query has the form "of=" (without the quotes) followed by the offset as an integer in text format.

A request to read multiple MIB variables is done by expressing the pairs (MIB descriptor, null) in the payload of the GET request message. A request to set multiple MIB variables is done by expressing the pairs (MIB descriptor, null value) in the payload of the PUT request message.

The managing entity MAY be interested only in certain table entries. One way to specify a row is to specify its row number in the URI with the "row" uri-query attribute. The specification of row=1 returns row 1 values of the ipNetToMediaTable in the example:

An alternative mode of selection is by specifying the value of the INDEX atttributes. Towards this end, the managing entity can include the required entries in the payload of its "GET" request by specifying the values of the index attributes. For example, to obtain a table entry from ipNetToMediaTable, the rows are specified by specifying the index attributes: ipNetToMediaIfIndex and ipNetToMediaNetAddress. The managing entity could have sent a GET with the following payload:

Constrained devices MAY support this kind of filtering. However, if they don't support it, they MUST ignore the payload in the GET request and handle the message as if the payload was empty. It is advised to keep MIBs for constrained entities as simple as possible, and therefore it would be best to avoid extensive tables.

When a variable with the specified name cannot be processed, CoAP Error code 5.01 is returned. In addition, a MIB specific error can be returned in the payload. Two types of error code can be returned: exception or error-status as specified in , according to the rules of . For example when MIB "variable" does not exist:

The SMI syntax is mapped to XML, CBOR, and JSON syntax, necessary for the transport of MIB data in the CoAP payload.

MIB information can be stored in JSON through a JSON object containing a set of Name-Value pairs, where each pair has the following syntax: Name : Value "Name" is a string that either contains the variable descriptor from the SMI definition, or the OID of the associated variable. In the latter case, the "Name" string has the following ABNF syntax, where we borrow some ABNF definitions from :

In other words, when "Name" contains an OID, it is represented as a JSON string in which the dots of the OID are replaced by underscores, and the OID is prefixed by "oid_". The "Value" field contains the variable value, using the JSON data type as indicated in . SMI type JSON type Specification OBJECT-IDENTIFIER array of integers Integer32 integer INTEGER integer OCTET-STRING Base64 encoded string BITS array of integers The integers can only take the values 0 and 1. IpAddress string Counter32 integer Gauge32 integer TimeTicks integer Counter64 integer Unsigned32 integer Table array For example, the number of UDP datagrams received can be obtained through the udpInDatagrams variable as specified in . It could have the following outcome:

Alternatively, when the response uses an OID instead of the variable identifier, the outcome would be as follows:

Another example of a JSON encoding of two (fictional) MIB variables "aBitString" and "anObjectID", with types BITS and OBJECT-IDENTIFIER, is as follows:

If a MIB object is a table, it is represented as an array of rows, the elements of which contain tuples related to the rows. For example, an udpEndpointTable would be encoded as follows:

CBOR is a binary format designated for the transmission of structured information. This section discusses how CBOR can be used to exchange MIB data. The MIB variables are represented in a CBOR map of indefinite length. Such a map is a list of paired data fields. The first data field of each pair contains either a string containing the name of the MIB variable, or an array of integers containing the MIB variable's OID. The second datafield contains the variable's value. gives an overview of the conversion from SMI to CBOR. If the first element of a pair in the map contains an OID, it uses the same CBOR format for the first element as defined in the table in the "OBJECT-IDENTIFIER" row. SMI type CBOR type Specification OBJECT-IDENTIFIER array of unsigned integers First element corresponds to the most left number in the OID. Integer32 unsigned integer or negative integer INTEGER unsigned integer or negative integer OCTET-STRING byte string BITS array of unsigned integers The integers can only take the values 0 and 1. IpAddress text string Counter32 unsigned integer Gauge32 unsigned integer TimeTicks unsigned integer Counter64 unsigned integer Unsigned32 unsigned integer Table array of maps For example, the variable "udpInDatagrams" of SMI type "Counter32" and value "82174" is reflected in CBOR as follows:

Or alternatively, using the OID of "udpInDatagrams":

In case a MIB variable is a table, it is represented in CBOR with a indefinite length array of maps. The array corresponds to the rows in the MIB table, and its elements consist of maps corresponding to the elements of each row. The encoding of the maps has the same syntax as the main map. For example, the "udpEndpointTable" from would be encoded in CBOR as follows:

TBD: we may consider splitting up the CBOR definition in two parts, the first part containing a translation table with ( integer, descriptor/oid ) pairs, the second as above but using instead of the descriptor/oid the integers defined in the translation table. This would increase coding efficiency, but requires some extra work especially on the client (managing entity) side. This suggestion would lead to the following CBOR data:

Obviously this leads to less bytes to transmit, but it needs to define an extra translation table. The server can include the fixed mapping as a macro, so it does not need to calculate it for each request. In this example the translation map is for the whole structure. The map can be restricted to the entries that are used.

The types specified by SMI can be represented by a XML syntax according to the specification in this section. The XML syntax is taken over from http://www.w3c.org/2001/XMLSchema-datatypes. SMI type XML type Specification OBJECT-IDENTIFIER: array of int Integer32: int INTEGER: int OCTET-STRING: Base64 encoded string BITS: bits IPAddress: string Counter32: nonNegativeInteger Gauge32: nonNegativeInteger TimeTicks: time Counter64: unsignedlong Unsigned32: unsignedInt Table MIBTable

In case a MIB variable is a table, it is represented in XML with an indefinite length SEQUENCE of type entry. Each element of entry has a name and a choice of XML types. The associated schema is shown in . For example the udpEndPointTable would look like:

"udpEndpointTable" ]]>

When the MIBidentifier is an OID the syntax for MIB object 1.3.6.1.2.1.1.3 looks like:

1 3 6 1 2 1 1 3 ]]>

MIB objects are discovered like resources with the standard CoAP resource discovery. Performing a GET on "/.well-known/core" with rt=core.mg.mib returns all MIB descriptors and all OIDs which are available on this device. For table objects there is no further possibility to discover the row descriptors. For example, consider there are two MIB objects with descriptors "sysUpTime" and "ipNetToMediaTable" associated with OID 1.3.6.1.2.1.1.3 and 1.3.6.1.2.1.4.22

;rt="core.mg.mib";oid="1.3.6.1.2.1.1.3" ;rt="core.mg.mib";oid="1.3.6.1.2.1.4.22" ]]>

The link format attribute 'oid' is used to associate the name of the MIB resource with its OID. The OID is written as a string in its conventional form. Notice that a MIB variable normally is associated with a descriptor and an OID. The OID is unique, whereas the descriptor may not.

A trap can be set through the CoAP Observe function. As regular with Observe, the managing entity subscribes to the variable by sending a GET request with an "Observe" option. In the registration request, the managing entity MAY include a "Response-To-Uri-Host" and optionally "Response-To-Uri-Port" option as defined in . In this case, the observations SHOULD be sent to the address and port indicated in these options. This can be useful when the managing entity wants the managed device to send the trap information to a multicast address.

Setting up parameter values and establishing relations between devices during commissioning of a managed network is needed for the TRAP function. Draft describes the binding of end-points to end-points on remote devices. This is just a table that contains the destination addresses of the MIB variables. A list of objects describing different aspects of commissioning comprise: Binding table as described in , schema presented in . Notification sources as referred to in , schema presented in . Names of files containing the schemas to be expected, schema presented in . The object with type "binding table" contains a sequence of bindings. The contents of bindings contains the methods, location, the interval specifications, and the step value as suggested in . The method "notify" has been added to the binding methods "poll", "obs" and "push", to cater for the binding of notification source to the receiver. The object of type "Schema-files" contains a sequence of schema files describing the data structure transportable in CoMI messages.

TODO: follows CoAP security provisioning.

'rt="core.mg.mib"' needs registration with IANA. Content types to be registered: application/comi+xml application/comi+exi application/comi+json application/comi+cbor

Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs transported under SNMP. Carsten Bormann has given feedback on the use of CBOR. The draft has benefited from comments by Dee Denteneer, Esko Dijk, and Michael van Hartskamp.

Changes from version 00 to version 01 Focus on MIB only Introduced CBOR, JSON, removed BER defined mappings from SMI to xx Introduced the concept of addressable table rows

&RFC2119; &I-D.bormann-cbor; &I-D.becker-core-coap-sms-gprs; &I-D.ietf-core-observe; &I-D.ietf-json-rfc4627bis; &RFC1213; &RFC2578; &RFC3410; &RFC3414; &RFC3416; &RFC3418; &RFC3986; &RFC4113; &RFC4291; &RFC4293; &RFC4944; &RFC6020; &RFC6241; &RFC6347; &RFC6643; &RFC6650; &RFC6690; &RFC6775; &I-D.ietf-core-coap; &I-D.ietf-core-groupcomm; &I-D.ietf-core-interfaces; &I-D.ersue-constrained-mgmt;

This appendix describes the XML schema that defines the payload contents for MIB requests via the CoMI Function Set. It is assumed that MIB variables are referred by descriptor or by OID. TODO: The schema needs to be updated to define basic types and notifications. Access may be more sophisticated than described here.

]]>

This appendix describes the XML schema that defines the payload contents for requests via the CoMI Function Set to the CoMI objects for multicast group, binding table, and SNMP notifications. For the SNMP notifications the Binding Method table specification of has been extended with "notify".

Binding table contains several simple Bindings, composed of timing parameters and Function signature.

]]>

File names are stored in Schema

]]>