One document matched: draft-vanderstok-core-comi-09.xml
<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'[
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2578 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2578.xml">
<!ENTITY RFC3410 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3410.xml">
<!ENTITY RFC3411 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3411.xml">
<!ENTITY RFC3414 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3414.xml">
<!ENTITY RFC3416 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3416.xml">
<!ENTITY RFC3418 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3418.xml">
<!ENTITY RFC4293 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4293.xml">
<!ENTITY RFC4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC4944 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4944.xml">
<!ENTITY RFC5277 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5277.xml">
<!ENTITY RFC6020 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6020.xml">
<!ENTITY RFC6241 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6241.xml">
<!ENTITY RFC6347 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6347.xml">
<!ENTITY RFC6643 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6643.xml">
<!ENTITY RFC6650 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6650.xml">
<!ENTITY RFC6775 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6775.xml">
<!ENTITY RFC6690 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6690.xml">
<!ENTITY RFC7049 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7049.xml">
<!ENTITY RFC7159 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7159.xml">
<!ENTITY RFC7228 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7228.xml">
<!ENTITY RFC7252 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7252.xml">
<!ENTITY RFC7277 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7277.xml">
<!ENTITY RFC7317 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7317.xml">
<!ENTITY RFC7396 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7396.xml">
<!ENTITY I-D.ietf-core-block SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-block.xml">
<!ENTITY I-D.ietf-core-interfaces SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-interfaces.xml">
<!ENTITY I-D.ietf-core-observe SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-observe.xml">
<!ENTITY I-D.becker-core-coap-sms-gprs SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.becker-core-coap-sms-gprs.xml">
<!ENTITY I-D.ietf-netmod-yang-json SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-netmod-yang-json.xml">
<!ENTITY I-D.ietf-netconf-restconf SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-netconf-restconf.xml">
<!ENTITY I-D.ietf-netconf-yang-patch SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-netconf-yang-patch.xml">
<!ENTITY I-D.ietf-lwig-coap SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-lwig-coap.xml">
<!ENTITY I-D.vanderstok-core-patch SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.vanderstok-core-patch.xml">
<!ENTITY I-D.ietf-netconf-yang-patch SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-netconf-yang-patch.xml">
<!ENTITY I-D.bierman-core-yang-hash SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.bierman-core-yang-hash.xml">
]>
<?rfc toc="yes"?>
<?rfc symrefs="yes" ?>
<rfc category="std" ipr="trust200902" docName="draft-vanderstok-core-comi-09">
<front>
<title abbrev="CoMI">CoAP Management Interface</title>
<author initials="P." surname="van der Stok" fullname="Peter van der Stok">
<organization abbrev="consultant">consultant</organization>
<address>
<phone>+31-492474673 (Netherlands), +33-966015248 (France)</phone>
<email>consultancy@vanderstok.org</email>
<uri>www.vanderstok.org</uri>
</address>
</author>
<author initials="A" surname="Bierman" fullname='Andy Bierman' >
<organization>YumaWorks</organization>
<address>
<postal>
<street>685 Cochran St.</street>
<street>Suite #160</street>
<city>Simi Valley</city>
<region>CA</region>
<code>93065</code>
<country>USA</country>
</postal>
<email>andy@yumaworks.com</email>
</address>
</author>
<date />
<area>Applications</area>
<workgroup>core</workgroup>
<abstract>
<t>
This document describes a network management interface for constrained devices, called CoMI.
CoMI is an adaptation of the RESTCONF protocol for use in constrained devices and networks.
The Constrained Application Protocol (CoAP) is used to access management data resources specified in YANG,
or SMIv2 converted to YANG. CoMI use the YANG to CBOR mapping and encodes YANG names to reduce payload size.
</t>
</abstract>
<note title="Note">
<t>
Discussion and suggestions for improvement are requested,
and should be sent to core@ietf.org.
</t>
</note>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>
The Constrained Application Protocol (CoAP) <xref target="RFC7252"/> is designed for
Machine to Machine (M2M) applications such as smart energy and building control.
Constrained devices need to be managed in an automatic fashion to handle the large quantities of devices that are expected in
future installations. The messages between devices need to be as small and infrequent as possible. The implementation
complexity and runtime resources need to be as small as possible.
</t><t>
This draft describes the CoAP Management Interface which uses CoAP methods to access structured data defined in YANG <xref target="RFC6020"/>. This draft is complementary to
the draft <xref target="I-D.ietf-netconf-restconf"/> which describes a REST-like interface called RESTCONF,
which uses HTTP methods to access structured data defined in YANG.
</t><t>
The use of standardized data sets, specified in a standardized language such as YANG, promotes interoperability between devices and applications from different manufacturers.
A large amount of Management Information Base (MIB) <xref target="RFC3418"/> <xref target="mibreg"/> specifications already
exists for monitoring purposes. This data can be accessed in RESTCONF or CoMI if the server converts the
SMIv2 modules to YANG, using the mapping rules defined in <xref target="RFC6643"/>.
</t><t>
RESTCONF allows access to data resources contained in NETCONF <xref target="RFC6241"/> data-stores.
RESTCONF messages can be encoded in XML <xref target="XML"/> or JSON <xref target="RFC7159"/>. The GET method is used
to retrieve data resources and the POST, PUT, PATCH, and DELETE methods are used to create, replace,
merge, and delete data resources.
</t><t>
CoMI supports the methods GET, PUT, PATCH, POST and DELETE. The payload of CoMI is encoded in CBOR <xref target="RFC7049"/> which can be automatically generated from JSON <xref target="RFC7159"/>.
CBOR has a binary format and hence has more coding efficiency than JSON. RESTCONF relies on HTTP with TCP in contrast to CoMI which uses CoAP that is optimized for UDP with less overhead for small messages. RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not used by CoMI.
</t><t>
CoMI and RESTCONF are intended to work in a stateless client-server fashion. They use a single round-trip to complete a single editing transaction, where NETCONF needs up to 10 round trips.
</t><t>
To promote small packets, CoMI uses an additional "data-identifier string-to-number conversion" to minimize CBOR payloads and URI length.
</t><t>
Currently, small managed devices need to support at least two protocols: CoAP and SNMP <xref target="RFC3411"/>.
When the MIB can be accessed with the CoMI protocol, the SNMP protocol can be replaced with the CoAP protocol. Although the SNMP server size is not huge (see <xref target="code-sizes"/>), the code for the security aspects of SMIv3 <xref target="RFC3414"/> is not negligible.
Using CoAP to access secured management objects reduces the code complexity of the stack in the constrained device, and harmonizes applications development.
</t>
<section anchor="terminology" title="Terminology">
<t>
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 <xref target="RFC2119"/>.
</t>
<t>
Readers of this specification should be familiar with all the terms and concepts discussed in <xref target="RFC3410"/>, <xref target="RFC3416"/>, and <xref target="RFC2578"/>.
</t>
<t>
The following terms are defined in the NETCONF protocol <xref target="RFC6241"/>: client, configuration data, data-store, and server.
</t>
<t>
The following terms are defined in the YANG data modelling language <xref target="RFC6020"/>: container, data node, key, key leaf, leaf, leaf-list, and list. The following terms are defined in RESTCONF protocol <xref target="I-D.ietf-netconf-restconf"/>: data resource, data-store resource, edit operation, query parameter, target resource, and unified data-store. The terms YANG hash, and Rehash bit are defined in I-D.yang-hash.
</t>
<t>
The following terms are defined in this document:
<list style="hanging">
<t hangText="Data-node instance:"> An instance of a data-node specified in a YANG module present in the server. The instance is stored in the memory of the server.
</t>
<t hangText="Notification-node instance:"> An instance of a schema node of type notification, specified in a YANG module present in the server. The instance is generated in the server at the occurrence of the corresponding event and appended to a stream.
</t>
</list>
</t>
<t>
The following list contains the abbreviations used in this document.
<list style="hanging">
<t hangText="XXXX:">TODO, and others to follow.</t>
</list>
</t>
<section anchor="tree-diagrams" title="Tree Diagrams">
<t>
A simplified graphical representation of the data model is used in the YANG modules specified in
this document. The meaning of the symbols in these
diagrams is as follows:
</t>
<t>
<list>
<t>Brackets "[" and "]" enclose list keys.</t>
<t>Abbreviations before data node names: "rw" means configuration
data (read-write) and "ro" state data (read-only).</t>
<t>Symbols after data node names: "?" means an optional node, "!" means
a presence container, and "*" denotes a list and leaf-list.</t>
<t>Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":").</t>
<t>Ellipsis ("...") stands for contents of subtrees that are not shown.</t>
</list>
</t>
</section> <!-- Tree diagrams -->
</section> <!-- Terminology -->
</section> <!-- Introduction -->
<section anchor="comi-architecture" title="CoMI Architecture">
<t>
This section describes the CoMI architecture to use CoAP for the reading and modifying of instrumentation variables used for the management of the instrumented node.
</t>
<figure anchor="archit" title="Abstract CoMI architecture"><artwork align="left"><![CDATA[
Client
+--------------------------------------------------------------+
| +----------------+ +----------------+ |
| | SMIv2 | > | YANG | > COAP |
| |specification(2)| |specification(1)| Request(3) |
| +----------------+ +----------------+[ * |
+-----------------------------*-----------[---------*----------+
* [ *
* [ +-----------+
mapping * security[ | Network |
* (8) [ | packet(4) |
* [ +-----------+
Server * [ *
+-----------------------------*-----------[---------*----------+
| * [ * |
| * Retrieval, |
| * Modification(5) |
| \*/ * |
| +-------------------------------------------------*--------+ |
| | +--------------+ +------------+ | |
| | |configuration | |Operational | | |
| | | (6b) | | state(6a) | | |
| | +--------------+ +------------+ | |
| | variable store (6) * | |
| +-------------------------------------------------*--------+ |
| * |
| Variable |
| Instrumentation(7)|
+--------------------------------------------------------------+
]]></artwork></figure>
<t>
<xref target="archit"/> is a high level representation of the main elements of the CoAP management architecture. A client sends requests as payload in packets over the network to a managed constrained node.
</t>
<t>
Objectives are:
<list style="symbols">
<t>Equip a constrained node with a management server that provides information about the operational characteristics of the code running in the constrained node.</t>
<t>The server provides this information in a variable store that contains values describing the performance characteristics and the code parameter values.</t>
<t>The client receives the performance characteristics on a regular basis or on request.</t>
<t>The client sets the parameter values in the server at bootstrap and intermittently when operational conditions change.</t>
<t>The constrained network requires the payload to be as small as possible, and the constrained server memory
requirements should be as small as possible.</t>
</list>
</t>
<t>
For interoperability it is required that in addition to using the Internet Protocol for data transport:
<list style="symbols">
<t>The names, type, and semantics of the instrumentation variables are standardized.</t>
<t>The instrumentation variables are described in a standard language. </t>
<t>The URI of the CoAP request is standardized.</t>
<t>The format of the packet payload is standardized.</t>
<t>The notification from server to client is standardized.</t>
</list>
</t>
<t>
The different numbered components of Figure 1 are discussed according to component number.
<list style="hanging">
<t hangText="(1) YANG specification:"> contains a set of named and versioned modules. A module specifies a hierarchy of named and typed resources. A resource is uniquely identified by a sequence of its name and the names of the enveloping resources following the hierarchy order. The YANG specification serves as input to the writers of application and instrumentation code and the humans analyzing the returned values (arrow from YANG specification to Variable store). The specification can be used to check the correctness of the CoAP request and do the CBOR
encoding.
</t>
<t hangText="(2) SMIv2 specification:"> A named module specifies a set of variables and "conceptual tables". Named variables have simple types. Conceptual tables are composed of typed named columns. The variable name and module name identify the variable uniquely. There is an algorithm to translate SMIv2 specifications to YANG specifications.
</t>
<t hangText="(3) CoAP request:"> The CoAP request needs a Universal Resource Identifier (URI) and the payload of the packet to send a request. The URI is composed of the schema, server, path and query and looks like coap://entry.example.com/<path>?<query>. Fragments are not supported. Allowed operations are PUT, PATCH, GET, DELETE, and POST. New variables can be created with POST when they exist in the YANG specification. The Observe option is used to return variable values regularly or on event occurrence (notification).
</t>
<t hangText="(3.1) CoAP <path>:"> The path identifies the variable in the form "/mg/<encoded-name>".</t>
<t hangText="(3.2) CoAP <query>:"> The query parameter is used to specify additional (optional) aspects like the container name, list instance, and others. The idea is to keep the path simple and put variations on variable specification in the query.
</t>
<t hangText="(3.3) CoAP discovery:"> Discovery of the variables is done with standard CoAP resource discovery using /.well-known/core with ?rt=/core.mg.
</t>
<t hangText="(4) Network packet:"> The payload contains the CBOR encoding of JSON objects.
This object corresponds with the converted RESTCONF message payload.
</t>
<t hangText="(5) Retrieval, modification:"> The server needs to parse the CBOR encoded message
and identify the corresponding instances in the Variable store. In addition, this component
includes the code for CoAP Observe and block options.
</t>
<t hangText="(6) Variable store:"> The store is composed of two parts: Operational state and Configuration data-store (see <xref target= "restconf-architecture"/>). CoMI does not differentiate between variable store types. The Variable store contains data-node instances. Values are stored in the appropriate instances, and or values are returned from the instances into the payload of the packet.
</t>
<t hangText="(7) Variable instrumentation:"> This code depends on implementation of drivers and other node specific aspects. The Variable instrumentation code stores the values of the parameters into the appropriate places in the operational code. The variable instrumentation code reads current execution values from the operational code and stores them in the appropriate instances.
</t>
<t hangText="(8) Security:"> The server MUST prevent unauthorized users from reading or writing
any data resources. CoMI relies on DTLS <xref target="RFC6347"/> which is specified to secure CoAP communication.
</t>
</list>
</t>
<section anchor="restconf-architecture" title="RESTCONF/YANG Architecture">
<t>
CoMI adapts the RESTCONF architecture so data exchange and implementation requirements
are optimized for constrained devices.
</t>
<t>
The RESTCONF protocol uses a unified data-store to edit conceptual data structures
supported by the server. The details of transaction preparation and non-volatile
storage of the data are hidden from the RESTCONF client. CoMI also uses a unified data-store,
to allow stateless editing of configuration variables and the notification of operational variables.
</t>
<t>
The child schema nodes of the unified data-store include all the top-level YANG data nodes
in all the YANG modules supported by the server. The YANG data structures represent
a hierarchy of data resources. The client discovers the list of YANG
modules, and important conformance information such as the module revision dates,
YANG features supported, and YANG deviations required. The individual data nodes are
discovered indirectly by parsing the YANG modules supported by the server.
</t>
<t>
The YANG data definition statements contain a lot of information that can help automation
tools, developers, and operators use the data model correctly and efficiently. The YANG definitions
and server YANG module capability advertisements provide an "API contract" that allow a client
to determine the detailed server management capabilities very quickly
</t>
<t>
RESTCONF and CoMI use a simple algorithmic mapping from YANG to URI syntax to identify the target resource
of a retrieval or edit operation. A client can construct operations or scripts using a
predictable syntax, based on the YANG data definitions. The target resource URI can
reference a data resource instance, or the data-store itself (to retrieve the entire data-store
or create a top-level data resource instance). A compression algorithm reduces the size of the data-node instance identifier (see <xref target="object-id-compression"/>).
</t>
<section title="Major differences between RESTCONF and CoMI" anchor = "MAJDIF">
<t>
CoMI uses CoAP/UDP as transport protocol and CBOR as payload format. RESTCONF uses HTTP/TCP as transport protocol and JSON or XML as payload formats. CoMI encodes YANG name strings as numbers, where RESTCONF does not.
</t><t>
CoAP servers MUST maintain the order of user-ordered data. CoMI does not support insert-mode (first, last, before, after) and insertion-point (before, after) which are supported by RESTCONF.
Many CoAP servers will not support date and time functions. For that reason CoMI does not support the start, stop options for events.
</t><t>
The CoMI "select" query parameter is equivalent to the RESTCONF "fields" query parameter but has a much simpler syntax. CoMI servers only implement the efficient "trim" mode for default values. CoMI servers implement a less rich syntax to specify key values in the URI than RESTCONF servers.
</t><t>
CoMI servers do not support 'filter' query that involves XML parsing, 'content', 'depth', and 'with-defaults' query parameters.
</t><t>
CoMI servers do not support the YANG functionality of anyxml, anydata, and xpath.
</t>
</section> <!-- Major differences -->
</section> <!-- RESTCONF /YANG architetcture -->
<section anchor="object-id-compression" title="Compression of data-node instance identifier">
<t>
The JSON/CBOR encoding will include the module name string to specify
the YANG module.
If a representation of the target resource is included in the
request or response message, then the
data definition name string is used to identify each node in the message.
The module namespace (or name) may also be present in these identifiers.
</t>
<t>
In order to significantly reduce the size of identifiers used in CoMI, numeric
object identifiers are used instead of these strings.
The specific encoding of the object identifiers
is not hard-wired in the protocol.
</t>
<t>
YANG Hash is the default encoding for object identifiers <xref target="I-D.bierman-core-yang-hash"/>.
This encoding in considered to be "unstructured" since the particular
values for each object are determined by a hash algorithm.
It is possible for 2 different objects to generate the same
hash value. If this occurs, then the client and server will
both need to rehash the colliding object identifiers to new unused hash values.
</t>
<t>
In order to eliminate the need for rehashing, CoMI allows for
alternate "structured" object identifier encoding formats.
Structured object identifier MUST be managed such that
no object ID collisions are possible, and therefore no rehash
procedures are needed. Structured object identifiers can also be
selected to minimize the size of a subset of the
object identifiers (e.g., the most requested objects).
</t>
</section> <!-- Compression -->
</section> <!-- CoMI Architecture -->
<section anchor="coap-interface" title="CoAP Interface">
<t>
In CoAP a group of links can constitute a Function Set. The format of the links is specified in <xref target="I-D.ietf-core-interfaces"/>.
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 name /mg is recommended but not compulsory (see <xref target="discovery"/>).
</t>
<t>
The path prefix /mg has resources accessible with the following five paths:
<list style="hanging">
<t hangText="/mg:">YANG-based data with path "/mg" and using CBOR content encoding format.
This path represents a data-store resource which contains YANG data resources as its descendant nodes.
All identifiers referring to YANG data nodes within this path are encoded YANG names (see for example <xref target="I-D.bierman-core-yang-hash"/>.</t>
<t hangText="/mg/mod.uri:">URI identifying the location of the server module information, with path "/mg/mod.uri" and CBOR content format. This YANG data is encoded with plain identifier strings, not YANG encoded values. An Entity Tag MUST be maintained
for this resource by the server, which MUST be changed to a new value when the set of YANG modules in use by the server changes.</t>
<t hangText="/mg/num.typ:">String identifying the object ID numbering scheme used
by the CoMI server. Two values are defined in this document: (1) 'yanghash' to
indicate that the YANG Hash numbering scheme is used, and (2) 'yangmanag' to indicate that a managed numbering scheme is used.
It is possible for other object numbering schemes to be defined outside the
scope of this document.
</t>
<t hangText="/mg/srv.typ:">String identifying the CoMI server type.
The value 'ro' indicates that the server is a read-only server and no editing operations
are supported. A read-only server is not required to provide YANG deviation statements
for any writable YANG data nodes.
The value 'rw' indicates that the server is a read-write server and editing operations
are supported. A read-write server is required to provide YANG deviation statements
for any writable YANG data nodes that are not fully implemented.
</t>
<t hangText="/mg/yh.uri:">
URI indicating the location of the server YANG hash information if any objects needed
to be re-hashed by the server. It has the path "/mg/yh.uri" and is encoded in CBOR format.
The "yang-hash" container within the "ietf-yang-hash" module, described in <xref target="I-D.bierman-core-yang-hash"/>, is used to define the syntax and semantics of this data structure.
This YANG data is encoded with plain identifier strings, not YANG hash values.
The server will only have this resource if there are any objects that needed to be
re-hashed due to a hash collision.
</t>
<t hangText="/mg/stream:"> String identifying the default stream resource to which YANG notification instances are appended. Notification support is optional, so this resource will not exist
if the server does not support any notifications.
</t>
<t hangText="/mg/op:"> String identifying the resource to which YANG operations are appended.
</t>
</list>
</t><t>
The mapping of YANG data node instances to CoMI resources is as follows:
A YANG module describes a set of data trees composed of YANG data nodes.
Every root of a data tree in a YANG module loaded in the CoMI server represents a resource of the server.
All data root descendants represent sub-resources.
</t><t>
The resource identifiers of the instances of the YANG specifications are encoded YANG names. When multiple instances of a list node exist, the instance selection is described in <xref target="keysParm"/>
</t>
<t>
The profile of the management function set, with IF=core.mg, is shown in the table below,
following the guidelines of <xref target="I-D.ietf-core-interfaces"/>:
</t>
<texttable>
<ttcol align="left">name</ttcol>
<ttcol align="left">path</ttcol>
<ttcol align="left">rt</ttcol>
<ttcol align="left">Data Type</ttcol>
<c> Management </c> <c> /mg </c> <c> core.mg </c> <c> n/a </c>
<c> Data </c> <c> /mg </c> <c> core.mg.data </c> <c> application/cbor </c>
<c> Module Set URI </c> <c> /mg/mod.uri </c> <c> core.mg.moduri </c> <c> application/cbor </c>
<c> Numbering Type </c> <c> /mg/num.typ </c> <c> core.mg.num-type </c> <c> application/cbor </c>
<c> Server Type </c> <c> /mg/srv.typ </c> <c> core.mg.srv-type </c> <c> application/cbor </c>
<c> YANG Hash Info </c> <c> /mg/yh.uri </c> <c> core.mg.yang-hash </c> <c> application/cbor </c>
<c> Events </c> <c> /mg/stream </c> <c> core.mg.stream </c> <c> application/cbor </c>
<c> Operations </c> <c> /mg/op </c> <c> core.mg.op </c> <c> application/cbor </c>
</texttable>
</section> <!-- CoAP Interface -->
<section anchor="mgFS" title="MG Function Set">
<t>
The MG Function Set provides a CoAP interface to perform a subset of the functions provided by RESTCONF.
</t>
<t>
A subset of the operations defined in RESTCONF are used in CoMI:
</t>
<texttable>
<ttcol align="left">Operation</ttcol>
<ttcol align="left">Description</ttcol>
<c> GET </c> <c> Retrieve the data-store resource or a data resource </c>
<c> POST </c> <c> Create a data resource </c>
<c> PUT </c> <c> Create or replace a data resource </c>
<c> PATCH </c> <c> Replace a data resource partially </c>
<c> DELETE </c> <c> Delete a data resource </c>
</texttable>
<section anchor="DataRetrieval" title="Data Retrieval">
<section anchor="GetOperation" title="GET">
<t>
One or more instances of data resources are retrieved by the client with the GET method.
The RESTCONF GET operation is supported in CoMI.
The same constraints apply as defined in section 3.3 of <xref target="I-D.ietf-netconf-restconf"/>.
The operation is mapped to the GET method defined in section 5.8.1 of <xref target="RFC7252"/>.
</t><t>
It is possible that the size of the payload is too large to fit in a single message.
In the case that management data is bigger than the maximum supported payload size,
the Block mechanism from <xref target="I-D.ietf-core-block"/> is used, as explained in more detail in <xref target="block"/>.
</t>
<t>
There are three query parameters for the GET method.
A CoMI server MUST implement the keys parameter and the content parameter, and MAY implement the select parameter to allow common data retrieval filtering functionality.
</t>
<texttable>
<ttcol align="left">Query Parameter</ttcol>
<ttcol align="left">Description</ttcol>
<c> keys </c> <c> Request to select instances of a YANG definition </c>
<c> select </c> <c> Request to select sub-trees from the target resource </c>
<c> content </c> <c> Request to select configuration and non-configuration nodes </c>
</texttable>
<t>
The "keys" parameter is used to specify a specific instance of the list resource. When keys is not specified, all instances are returned. When no or one instance of the resource exists, the keys parameter is ignored.
</t>
</section> <!-- GET -->
<section anchor="SelectParam" title="Using the 'select' Parameter">
<t>
RESTCONF uses the 'filter' parameter next to the 'fields' parameter to specify an expression
which can represent a subset of all data nodes within the target
resource <xref target="I-D.ietf-netconf-restconf"/>. The 'select'
parameter is local to CoMI and is useful for filtering sub-trees and retrieving only a
subset that a managing application is interested in.
</t>
<t>
Because filtering is a resource intensive task and not all
constrained devices can be expected to have enough computing
resources such that they will be able to successfully filter and
return a subset of a sub-tree. This is especially likely to be
true with Class 0 devices that have significantly lesser RAM than
10 KiB <xref target="RFC7228"/>. Since CoMI is targeted at
constrained devices and networks, the
'filter' parameter is not used here.
</t>
<t>
The implementation of the 'select' parameter is already optional
for constrained devices, however, even when implemented it is
expected to be a best effort feature, rather than a service that
nodes must provide. This implies that if a node receives the
'select' parameter specifying a set of sub-trees that should be
returned, it will only return those that it is able to return.
</t>
</section> <!-- Select -->
<section anchor="content" title="Using the 'content' query parameter">
<t>
The "content" parameter controls how descendant nodes of the
requested data nodes will be processed in the reply.
</t><t>
The allowed values are:
</t>
<texttable>
<ttcol align="left">Value</ttcol>
<ttcol align="left">Description</ttcol>
<c> config </c> <c> Return only configuration descendant data nodes</c>
<c> nonconfig </c> <c> Return only non-configuration descendant data nodes </c>
<c> all </c> <c> Return all descendant data nodes </c>
</texttable>
<t>
This parameter is only allowed for GET methods on datastore and data
resources. A 4.00 Bad Request error is returned if used for other
methods or resource types.
</t><t>
The default value is determined by the "config" statement value of
the requested data nodes. If the "config" value is "false", then the
default for the "content" parameter is "nonconfig". If "config" is
"true" then the default for the "content" parameter is "config".
</t>
</section>
<section anchor="RetrievalExamples" title="Retrieval Examples">
<t>
In all examples the path is expressed in readable names and as a encoded value of the name (where the encoded value in the payload is expressed as a hexadecimal number, and the encoded value in the URL as a base64 number).
CoMI payloads use the CBOR format. The CBOR syntax of the YANG payloads is specified in TODO REF. The examples in this section use a JSON payload with extensions to approach the permissible CBOR payload, called "diagnostic JSON".
</t>
<section anchor="single" title="Single instance retrieval">
<t>
A request to read the values of instances of a management object or the leaf of an object is sent with a confirmable CoAP GET message. A single object is specified in the URI path prefixed with /mg.
</t>
<t>
Using for example the clock container from <xref target="RFC7317"/>, a request is sent to retrieve the value of clock/current-datetime specified in module system-state. The answer to the request returns a (identifier, value) pair, transported as a CBOR map with a single item.
</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET example.com/mg/system-state/clock/current-datetime
RES: 2.05 Content (Content-Format: application/cbor)
{
"current-datetime" : "2014-10-26T12:16:31Z"
}
]]></artwork>
</figure>
<t>
The specified object can be an entire object. Accordingly, the returned payload is composed of all the leaves associated with the object. The payload is a CBOR map where each leaf is returned as a (encoded YANG name, value) pair. For example, the GET of the clock object, sent by the client, results in the following returned payload sent by the managed entity, transported as A CBOR map with two items:
</t>
<figure><artwork align="left">
<![CDATA[
REQ: GET example.com/mg/system-state/clock
(Content-Format: application/cbor)
RES: 2.05 Content (Content-Format: application/cbor)
{
"clock" : {
"current-datetime" : "2014-10-26T12:16:51Z",
"boot-datetime" : "2014-10-21T03:00:00Z"
}
}
]]></artwork></figure>
<t>
For example, the YANG names can be replaced by the hash values for 'clock', 'current-datetime', and 'boot-datetime'. The 30 bit murmur3 hash value of 'clock' equates: CDKSQ (xref target="I-D.bierman-core-yang-hash"/>.
The request using hash values is shown below:
</t>
<figure><artwork align="left">
<![CDATA[
REQ: GET example.com/mg/CDKSQ
(Content-Format: application/cbor)
RES: 2.05 Content (Content-Format: application/cbor)
{
0x021ca491 : {
0x047c468b : "2014-10-26T12:16:51Z",
0x1fb5f4f8 : "2014-10-21T03:00:00Z"
}
}
]]></artwork></figure>
<t>
</t>
</section> <!-- Single instance retrieval -->
<section anchor="multiple" title="Multiple instance retrieval">
<t>
A "list" node can have multiple instances. Accordingly, the returned payload is composed of all the instances associated with the list node. Each instance is returned as a (key, object) pair, where key and object are composed of one or more (identifier, value) pairs.
</t><t>
For example, the GET of the /interfaces/interface/ipv6/neighbor results in the following returned payload sent by the managed entity, transported as a CBOR map of 3 (key : object) pairs, where key and value are CBOR maps with one entry each. In this case the key is the "ip" attribute and the value is the "link-layer-address" attribute.
</t>
<figure><artwork align="left">
<![CDATA[
REQ: GET example.com/mg/interfaces/interface/ipv6/neighbor
(Content-Format: application/cbor)
RES: 2.05 Content (Content-Format: application/cbor)
{
"neighbor" :{
{"ip" : "fe80::200:f8ff:fe21:67cf"}:
{"link-layer-address" : "00:00::10:01:23:45"}
,
{"ip" : "fe80::200:f8ff:fe21:6708"}:
{"link-layer-address" : "00:00::10:54:32:10"}
,
{"ip" : "fe80::200:f8ff:fe21:88ee"}:
{"link-layer-address" : "00:00::10:98:76:54"}
}
}
]]></artwork></figure>
</section> <!-- Multiple instance retrieval -->
<section anchor="MIB" title="Access to MIB Data">
<t>
The YANG translation of the SMI specifying the ipNetToMediaTable <xref target="RFC4293"/> yields:
</t>
<figure><artwork align="left">
<![CDATA[
container IP-MIB {
container ipNetToPhysicalTable {
list ipNetToPhysicalEntry {
key "ipNetToPhysicalIfIndex
ipNetToPhysicalNetAddressType
ipNetToPhysicalNetAddress";
leaf ipNetToMediaIfIndex {
type: int32;
}
leaf ipNetToPhysicalIfIndex {
type if-mib:InterfaceIndex;
}
leaf ipNetToPhysicalNetAddressType {
type inet-address:InetAddressType;
}
leaf ipNetToPhysicalNetAddress {
type inet-address:InetAddress;
}
leaf ipNetToPhysicalPhysAddress {
type yang:phys-address {
length "0..65535";
}
}
leaf ipNetToPhysicalLastUpdated {
type yang:timestamp;
}
leaf ipNetToPhysicalType {
type enumeration { ... }
}
leaf ipNetToPhysicalState {
type enumeration { ... }
}
leaf ipNetToPhysicalRowStatus {
type snmpv2-tc:RowStatus;
}
}
}
]]></artwork></figure>
<t>
The following example shows an "ipNetToPhysicalTable" with 2 instances, using JSON encoding as defined in <xref target="I-D.ietf-netmod-yang-json"/>:
</t>
<figure><artwork align="left">
<![CDATA[
{
"IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry" : [
{
"ipNetToPhysicalIfIndex" : 1,
"ipNetToPhysicalNetAddressType" : "ipv4",
"ipNetToPhysicalNetAddress" : "10.0.0.51",
"ipNetToPhysicalPhysAddress" : "00:00:10:01:23:45",
"ipNetToPhysicalLastUpdated" : "2333943",
"ipNetToPhysicalType" : "static",
"ipNetToPhysicalState" : "reachable",
"ipNetToPhysicalRowStatus" : "active"
},
{
"ipNetToPhysicalIfIndex" : 1,
"ipNetToPhysicalNetAddressType" : "ipv4",
"ipNetToPhysicalNetAddress" : "9.2.3.4",
"ipNetToPhysicalPhysAddress" : "00:00:10:54:32:10",
"ipNetToPhysicalLastUpdated" : "2329836",
"ipNetToPhysicalType" : "dynamic",
"ipNetToPhysicalState" : "unknown",
"ipNetToPhysicalRowStatus" : "active"
}
]
}
}
}
]]></artwork></figure>
</section> <!-- MIB example -->
<section anchor="keysParm" title="The 'keys' Query Parameter">
<t>
There is a query parameter that MUST be supported by servers called "keys".
This parameter is used to specify the key values for an instance of an object
identified by an encoded YANG name. All key leaf values of the instance are passed
in order. The first key leaf in the top-most list is the first key encoded in
the 'keys' parameter.
</t>
<t>
The key leafs from top to bottom and left to right are encoded
as a comma-delimited list. If a key leaf value is missing then
all values for that key leaf are returned.
</t>
<t>
Example:
In this example exactly one instance is requested from
the ipNetToPhysicalEntry (from a previous example). The CBOR payload, here represented with diagnostic JSON, permits to transport the selected instance and nothing more.
</t><t>
TODO refer to the section in YANG to CBOR mapping
</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET example.com/mg/IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry?keys=1,ipv4,9.2.3.4
RES: 2.05 Content (Content-Format: application/cbor)
{
"IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry": {
{
"ipNetToPhysicalIfIndex" : 1,
"ipNetToPhysicalNetAddressType" : "ipv4",
"ipNetToPhysicalNetAddress" : "9.2.3.4"}:
{
"ipNetToPhysicalPhysAddress" : "00:00:10:54:32:10",
"ipNetToPhysicalLastUpdated" : "2329836",
"ipNetToPhysicalType" : "dynamic",
"ipNetToPhysicalState" : "unknown",
"ipNetToPhysicalRowStatus" : "active"
}
}
}
]]></artwork>
</figure>
<t>
An example illustrates the syntax of keys query parameter.
In this example the following YANG module is used:
</t>
<figure>
<artwork align="left"><![CDATA[
module foo-mod {
namespace foo-mod-ns;
prefix foo;
list A {
key "key1 key2";
leaf key1 { type string; }
leaf key2 { type int32; }
list B {
key "key3";
leaf key3 { type string; }
leaf col1 { type uint32; }
}
}
}
]]></artwork>
</figure>
<t>
The following string represents the CoMI target resource identifier for the instance
of the "col1" leaf with key values "top", 17, "group":
</t>
<figure>
<artwork align="left"><![CDATA[
/mg/foo-mod:A/B/col1?keys="top",17,"group1"
]]></artwork>
</figure>
</section> <!-- key query -->
<section anchor="SelectExample" title="The 'select' Query Parameter">
<t>
The select parameter is used along with the GET method to provide
a sub-tree filter mechanism. A list of encoded YANG names that should be
filtered is provided along with a list of keys identifying the
instances that should be returned. When the keys parameter is used together with the select, the key values are added in brackets without using the "keys=" text.
</t><t>
Data may be retrieved using the select query parameter in the
following way, transported as a CBOR maps of maps:
</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET example.com/mg/IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry?select=(10.0.0.51)
RES: 2.05 Content (Content-Format: application/cbor)
{
"IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry": {
{
"ipNetToPhysicalIfIndex" : 1,
"ipNetToPhysicalNetAddressType" : "ipv4",
"ipNetToPhysicalNetAddress" : "10.0.0.51"}:
{
"ipNetToPhysicalPhysAddress" : "00:00:10:01:23:45",
"ipNetToPhysicalLastUpdated" : "2333943",
"ipNetToPhysicalType" : "static",
"ipNetToPhysicalState" : "reachable",
"ipNetToPhysicalRowStatus" : "active"
}
}
}
]]></artwork>
</figure>
<t>
In this example exactly one instance is returned as response from
the ipNetToPhysicalTable because only this instance matches the
provided keys.
</t>
<t>
Supposing there were multiple YANG fields with their own sets of
keys that were to be filtered, the select query parameter can be
used to retrieve results from these in one go as well. Using the "foo-mod" module of <xref target="keysParm"/>, the
following string represents the CoMI target resource identifier
when multiple fields, with their own sets of key values are
queried:
</t>
<figure>
<artwork>
/mg/foo-mod:A?select=B/col1("top",17,"group"),key2("top")
</artwork>
</figure>
</section> <!-- Select Example -->
<section anchor="default" title="Defaults handling">
<t>
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.
</t><t>
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.
</t>
</section> <!-- defaults handling -->
</section> <!-- Retrieval Examples -->
</section> <!-- Data Retrieval -->
<section anchor="DataEditing" title="Data Editing">
<t>
CoMI allows data-store contents to be created, modified and deleted using CoAP methods.
</t>
<t>
Data-editing is an optional feature.
The server will indicate its editing capability with the "/core.mg.srv-type
resource type. If the value is 'rw' then the server supports editing operations.
If the value is 'ro' then the server does not support editing operations.
</t>
<section anchor="DataOrdering" title="Data Ordering">
<t>
A CoMI server is not required to support entry insertion of lists and leaf-lists
that are ordered by the user (i.e., YANG statement "ordered-by user").
The 'insert' and 'point' query parameters from RESTCONF are not used in CoMI.
</t>
<t>
A CoMI server SHOULD preserve the relative order of all user-ordered list and
leaf-list entries that are received in a single edit request. These YANG
data node types are encoded as arrays so messages will preserve their order.
</t>
</section>
<section anchor="PostOperation" title="POST">
<t>
Data resource instances are created with the POST method.
The RESTCONF POST operation is supported in CoMI
for creation of data resources and the invocation operation resources. Refer to <xref target="RPC"/> for details on operation resources.
The same constraints apply as defined in section 4.4.1 of <xref target="I-D.ietf-netconf-restconf"/>.
The operation is mapped to the POST method defined in section 5.8.2 of <xref target="RFC7252"/>.
</t>
<t>
There are no query parameters for the POST method.
</t>
</section>
<section anchor="PutOperation" title="PUT">
<t>
Data resource instances are created or replaced with the PUT method.
The PUT operation is supported in CoMI.
A request to set the values of instances of an object/leaf is sent with a confirmable CoAP PUT message.
The Response is piggybacked to the CoAP ACK message corresponding with the Request.
The same constraints apply as defined in section 3.5 of <xref target="I-D.ietf-netconf-restconf"/>.
The operation is mapped to the PUT method defined in section 5.8.3 of <xref target="RFC7252"/>.
</t>
<t>
There are no query parameters for the PUT method.
</t>
</section>
<section anchor="PatchOperation" title="PATCH">
<t>
Data resource instances are partially replaced with the PATCH method <xref target="I-D.vanderstok-core-patch"/>.
The PATCH operation is supported in CoMI.
A request to set the values of instances of a subset of the values of the resource is sent with a confirmable CoAP PATCH message.
The Response is piggybacked to the CoAP ACK message corresponding with the Request.
The same constraints apply as defined in section 3.5 of <xref target="I-D.ietf-netconf-restconf"/>.
The operation is mapped to the PATCH method defined in <xref target="I-D.vanderstok-core-patch"/>.
</t><t>
The processing of the PATCH command is specified by the CBOR payload. The CBOR patch payload describes the changes to be made to target YANG data nodes. It follows closely the rules described in <xref target="RFC7396"/>. If the CBOR patch payload contains objects that are not present in the target, these objects are added. If the target contains the specified object, the contents of the objects are replaced with the values of the payload. Null values indicate the removal of existing values. The CBOR patch extends <xref target="RFC7396"/> by specifying rules for list elements.
</t><t>
TODO, review text after publication of YANG/CBOR and CBOR-merge drafts.
</t><t> For example consider the following YANG specification:
</t>
<figure>
<artwork align="left"><![CDATA[
module foo {
namespace "http://example.com/book";
prefix "bo";
revision 2015-06-07;
list B {
key key1;
key key2;
leaf key1 { type string; }
leaf key2 {type string; }
leaf col1 { type int32; }
leaf counter1 { type uint32; }
}
container book {
leaf title { type string; }
container author {
leaf givenName {type string; }
leaf familyName {type string; }
}
leaf-list tags {type string; }
leaf content{type string;}
leaf phoneNumber {type string;}
}
]]></artwork>
</figure>
<t>
Consider the following target data nodes described with the JSON encoding of <xref target="I-D.ietf-netmod-yang-json"/>.
</t>
<figure>
<artwork align="left"><![CDATA[
"B": [
{
"key1" : "author1",
"key2" : "book2",
"col1" : 25,
"counter1" : 4321
},
{
"key1" : "author5",
"key2" : "book6",
"col1" : 2,
"counter1" : 1234
}
]
"book": {
"title" : "mytitle",
"author": {
"givenName" : "John",
"familyName" : "Doe"
}
"tags" : [ "example", "sample"],
"content" : "This will be unchanged"
}
]]></artwork>
</figure>
<t>
The following changes are requested for the document (following the example from <xref target="RFC7396"/>: the title changes from "mytitle" to "favoured", the phoneNumber is added to the book container, the familyName is deleted, and "sample" is removed from the tags leaf-list. In addition author1, book1 item is removed, author5 counter1 is upgraded, and a new author is added in B list. The following CBOR Patch payload, represented in JSON is sent.
</t><t>
TODO: edit after publication of CBOR-merge draft.
</t>
<figure>
<artwork align="left"><![CDATA[
{
"B": {
{ "key1" : "author1",
"key2" : "book2"}:
{ null : null},
{ "key1" : "author5"} :
{"counter1" : 4444},
{ "key1" : "newauthor",
"key2" : "newbook"}:
{ "col1" : 1,
"counter1" : 1}
},
"book" : {
"title" : "favoured",
"author": {"familyName" : null},
"tags" : [ "example"],
"phoneNumber" : "+01-123-456-7890"
}
}
]]></artwork>
</figure>
<t>
In his example, the value "author5" specifies the entry uniquely. However, when several entries exist with the "author5" value for "key1", the outcome of the example Patch is undefined.
</t><t>
The processing of the Patch payload results in the following new target data nodes.
</t>
<figure>
<artwork align="left"><![CDATA[
"B": [
{
"key1" : "newauthor",
"key2" : "newbook",
"col1" : 1,
"counter1" : 1
},
{
"key1" : "author5",
"key2" : "book6",
"col1" : 2,
"counter1" : 4444
}
]
"book": {
"title" : "favoured",
"author": {
"givenName" : "John"
}
"tags" : [ "example"],
"content" : "This will be unchanged",
"phoneNumber" : +01-123-456-7890"
}
]]></artwork>
</figure>
<t>
There are no query parameters for the PATCH method.
</t>
</section>
<section anchor="DeleteOperation" title="DELETE">
<t>
Data resource instances are deleted with the DELETE method.
The RESTCONF DELETE operation is supported in CoMI.
The same constraints apply as defined in section 3.7 of <xref target="I-D.ietf-netconf-restconf"/>.
The operation is mapped to the DELETE method defined in section 5.8.4 of <xref target="RFC7252"/>.
</t>
<t>
There are no optional query parameters for the DELETE method.
</t>
</section>
<section anchor="MultipleEdits" title="Editing Multiple Resources">
<t>
Editing multiple data resources at once can allow a client to use fewer
messages to make a configuration change. It also allows multiple
edits to all be applied or none applied, which is not possible
if the data resources are edited one at a time.
</t>
<t>
It is easy to add multiple entries at once. The "PATCH" method can be used
to simply patch the parent node(s) of the data resources to be added.
If multiple top-level data resources need to be added, then the
data-store itself ('/mg') can be patched.
</t>
<t>
If other operations need to be performed, or multiple operations
need to be performed at once, then the YANG Patch <xref target="I-D.ietf-netconf-yang-patch"/>
media type can be used with the PATCH method.
A YANG patch is an ordered list of edits on the target resource,
which can be a specific data node instance, or the data-store itself.
The resource type used by
YANG Patch is 'application/yang.patch'. A status message is returned in the
response, using resource type 'application/yang.patch.status'.
</t>
<t>
The following YANG tree diagram describes the YANG Patch structure,
Each 'edit' list entry has its own operation, sub-resource target,
and new value (if needed).
</t>
<figure>
<artwork align="left"><![CDATA[
+--rw yang-patch
+--rw patch-id? string
+--rw comment? string
+--rw edit* [edit-id]
+--rw edit-id string
+--rw operation enumeration
+--rw target target-resource-offset
+--rw point? target-resource-offset
+--rw where? enumeration
+--rw value
]]></artwork>
</figure>
<t>
Refer to <xref target="I-D.ietf-netconf-yang-patch"/> for more details on
the YANG Patch request and response contents.
</t>
</section>
</section> <!-- Edit Operations -->
<section anchor="Notify" title="Notify functions">
<t>
Notification by the server to a selection of clients when an event occurs in the server is an essential function for the management of servers. CoMI allows events specified in YANG <xref target="RFC5277"/> to be notified to a selection of requesting clients. The server appends newly generated events to a stream. There is one, so-called "default", stream in a CoMI server. The /mg/stream resource identifies the default stream. The server MAY create additional streams. When a CoMI server generates an internal event, it is appended to the chosen stream, and the contents of a notification instance is ready to be sent to all CoMI clients which observe the chosen stream resource.
</t><t>
Reception of generated notification instances is enabled with the CoAP Observe <xref target="I-D.ietf-core-observe"/> function.
The client subscribes to the notifications by sending a GET request with an "Observe" option, specifying the /mg/stream resource when the default stream is selected.
</t><t>
Every time an event is generated, the chosen stream is cleared, and the generated notification instance is appended to the chosen stream. After appending the instance, the contents of the instance is sent to all clients observing the modified stream.
</t><t>
Suppose the server generates the event specified with:
</t>
<figure>
<artwork align="left"><![CDATA[
module example-port {
...
prefix ep;
...
notification example-port-fault {
description
"Event generated if a hardware fault on a
line card port is detected";
leaf port-name {
type string;
description "Port name";
}
leaf port-fault {
type string;
description "Error condition detected";
}
}
}
}]]></artwork>
</figure>
<t>
By executing a GET on the /mg/stream resource the client receives the following response:
</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET example.com/mg/stream
(observe option register)
RES: 2.05 Content (Content-Format: application/cbor)
{
"example-port-fault":{
"port-name" : "0/4/21",
"port-fault" : "Open pin 2"
}
}
]]></artwork>
</figure>
<t>
In the example, the request returns a success response with the contents of the last generated event. Consecutively the server will regularly notify the client when a new event is generated.
</t><t>
To check that the client is still alive,
the server MUST send confirmable notifications once in a while. When the client does
not confirm the notification from the server, the server will remove
the client from the list of observers <xref target="I-D.ietf-core-observe"/>.
</t><t>
In the registration request,
the client MAY include a "Response-To-Uri-Host" and optionally "Response-To-Uri-Port" option as defined in
<xref target="I-D.becker-core-coap-sms-gprs"/>.
In this case,
the observations SHOULD be sent to the address and port indicated in these options.
This can be useful when the client wants the managed device to send the trap information to a multicast address.
</t>
</section>
<section anchor="RPC" title="RPC statements">
<t>
An operation resource represents a protocol operation defined with
the YANG "rpc" statement. It is invoked using a POST method on the
operation resource with a Token value as specified in section 5.3 "Request/Resonse matching" of <xref target="RFC7252"/> to match the operation request sent by the RPC requester to the Operation request sent by the RPC executor.
</t>
<figure>
<artwork align="left"><![CDATA[
POST mg/op/<operation>
]]></artwork>
</figure>
<t>
The <operation> field identifies the module name and rpc identifier
string for the desired operation.
</t><t>
For example, if "module-A" defined a "reset" operation, then invoking
the operation from "module-A" would be requested as follows:
</t>
<figure>
<artwork align="left"><![CDATA[
POST example.com/mg/op/module-A:reset
]]></artwork>
</figure>
<t>
If the "rpc" statement has input parameters, then a message-body
MAY be sent by the client in the request, otherwise the request
message MUST NOT include a message-body.
</t><t>
If the operation is successfully invoked the server MUST send a 2.04 Changed status code. If the operation is not successfully invoked, then a message-body
SHOULD be sent by the server, containing an error, as
defined in <xref target="error"/>.
</t><t>
If the "rpc" statement
has return parameters, then the server invokes a POST method with the same Token value as used in the request from the client. The payload contains the values of the return parameters.
</t>
<section anchor="RPC-INPUT" title="Encoding RPC input parameters">
<t>
If the "rpc" statement has an "input" section, then the "input" node
is provided in the message-body, corresponding to the YANG data
definition statements within Request payload.
</t><t>
The following YANG definition is used for the examples in this
section.
</t>
<figure>
<artwork align="left"><![CDATA[
module example-ops {
namespace "https://example.com/ns/example-ops";
prefix "ops";
rpc reboot {
input {
leaf delay {
units seconds;
type uint32;
default 0;
}
leaf message { type string; }
leaf language { type string; }
}
}
rpc get-reboot-info {
output {
leaf reboot-time {
units seconds;
type uint32;
}
leaf message { type string; }
leaf language { type string; }
}
}
}
]]></artwork>
</figure>
<t>
The client might send the following POST request message:
</t>
<figure>
<artwork align="left"><![CDATA[
POST example.com/restconf/operations/example-ops:reboot
Token:0x56
Content-Type:
{ "example-ops:input":
{
"delay": 600,
"message": "Going down for system maintenance"
"language": "en-US"
}
}
]]></artwork>
</figure>
<t>
The server may respond with a 2.04 Changed.
</t>
</section> <!-- RPC input parameters -->
<section anchor="RPC-OUTPUT" title="Encoding RPC output parameters">
<t>
If the "rpc" statement has output parameters, then the "output"
node is provided in a PUT message, corresponding to the YANG data
definition statements within the "output" section.
</t><t>
The "example-ops" YANG module defined <xref target="RPC"/> is used for
the examples in this section.
</t><t>
The client might send the following POST request message:
</t>
<figure>
<artwork align="left"><![CDATA[
POST example.com/mg/op/example-ops:get-reboot-info
Token: 0x56
]]></artwork>
</figure>
<t>
The server might respond with a POST request that is related to the original RPC invocation by the Token value:
</t>
<figure>
<artwork align="left"><![CDATA[
POST [ip:port]/mg/op/example-ops:output
Token: 0x56
{"example-ops:output" :
{
"reboot-time" : 30,
"message" : "Going down for system maintenance",
"language" : "en-US"
}
}
]]></artwork>
</figure>
</section> <!-- RPC output parameters -->
</section> <!-- RPC statement -->
<section anchor="block" title="Use of Block">
<t>
The CoAP protocol provides reliability by acknowledging the UDP datagrams. However, when large pieces of text need to be transported the datagrams get fragmented, thus creating constraints on the resources in the client, server and intermediate routers. The block option <xref target="I-D.ietf-core-block"/> allows the transport of the total payload in individual blocks of which the size can be adapted to the underlying fragment sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, IEEE 802.15.4 payload of 60-80 bytes). Each block is individually acknowledged to guarantee reliability.
</t><t>
The block size is specified as exponents of the power 2. The SZX exponent value can have 7 values ranging from 0 to 6 with associated block sizes given by 2**(SZX+4); for example SZX=0 specifies block size 16, and SZX=3 specifies block size 128.
</t><t>
The block number of the block to transmit can be specified. There are two block options: Block1 option for the request payload transported with PUT, POST or PATCH, and the block2 option for the response payload with GET. Block1 and block2 can be combined. Examples showing the use of block option in conjunction with observer options are provided in <xref target="I-D.ietf-core-block"/>.
</t><t>
Notice that the Block mechanism splits the data at fixed positions,
such that individual data fields may become fragmented.
Therefore, assembly of multiple blocks may be required to process the complete data field.
</t><t>
Beware of race conditions. Blocks are filled one at a time and care should be taken that the whole data representation is sent in multiple blocks sequentially without interruption. In the server, values are changed, lists are re-ordered, extended or reduced. When these actions happen during the serialization of the contents of the variables, the transported results do not correspond with a state having occurred in the server; or worse the returned values are inconsistent. For example: array length does not correspond with actual number of items. It may be advisable to use CBOR maps or CBOR arrays of undefined length which are foreseen for data streaming purposes.
</t>
</section>
<section anchor="discovery" title="Resource Discovery">
<t>
The presence and location of (path to) the management data are discovered by sending a GET request to "/.well-known/core" including a resource type (RT) parameter with the value "core.mg" <xref target="RFC6690"/>. Upon success, the return payload will contain the root resource of the management data. It is up to the implementation to choose its root resource, but it is recommended that the value "/mg" is used, where possible. The example below shows the discovery of the presence and location of management data.
</t>
<figure><artwork align="left"><![CDATA[
REQ: GET /.well-known/core?rt=core.mg
RES: 2.05 Content </mg>; rt="core.mg"
]]></artwork>
</figure>
<t>
Management objects MAY be discovered with the standard CoAP resource discovery. The implementation can add the encoded values of the object identifiers to /.well-known/core with rt="core.mg.data". The available objects identified by the encoded values can be discovered by sending a GET request to "/.well-known/core" including a resource type (RT) parameter with the value "core.mg.data". Upon success, the return payload will contain the registered encoded values and their location.
The example below shows the discovery of the presence and location of management data.
</t>
<figure><artwork align="left"><![CDATA[
REQ: GET /.well-known/core?rt=core.mg.data
RES: 2.05 Content </mg/BaAiN>; rt="core.mg.data",
</mg/CF_fA>; rt="core.mg.data"
]]></artwork>
</figure>
<t>
Lists of encoded values may become prohibitively long. It is discouraged to provide long lists of objects on discovery. Therefore, it is recommended that details about management objects are discovered by reading the YANG module information stored in the "ietf-yang-library" module <xref target="I-D.ietf-netconf-restconf"/>.
The resource "/mg/mod.uri" is used to retrieve the location of the YANG module library.
</t>
<t>
The module list can be stored locally on each server, or remotely on a different server. The latter is advised when the deployment of many servers are identical.
</t>
<figure><artwork align="left"><![CDATA[
Local in example.com server:
REQ: GET example.com/mg/mod.uri
RES: 2.05 Content (Content-Format: application/cbor)
{
"mod.uri" : "example.com/mg/modules"
}
Remote in example-remote-server:
REQ: GET example.com/mg/mod.uri
RES: 2.05 Content (Content-Format: application/cbor)
{
"moduri" : "example-remote-server.com/mg/group17/modules"
}
]]></artwork>
</figure>
<t>
Within the YANG module library all information about the module is stored such as: module identifier, identifier hierarchy, grouping, features and revision numbers.
</t><t>
The hash identifier is obtained as specified in <xref target="I-D.bierman-core-yang-hash"/>. When a collision occurred in the name space of the target server, a rehash is executed.
</t>
</section>
<section anchor="error" title="Error Return Codes">
<t>
The RESTCONF return status codes defined in section 6 of the RESTCONF draft are used
in CoMI error responses, except they are converted to CoAP error codes.
</t>
<texttable>
<ttcol align="left">RESTCONF Status Line</ttcol>
<ttcol align="left">CoAP Status Code</ttcol>
<c> 100 Continue </c> <c> none? </c>
<c> 200 OK </c> <c> 2.05 </c>
<c> 201 Created </c> <c> 2.01 </c>
<c> 202 Accepted </c> <c> none? </c>
<c> 204 No Content </c> <c> 2.04 Changed</c>
<c> 304 Not Modified </c> <c> 2.03 </c>
<c> 400 Bad Request </c> <c> 4.00 </c>
<c> 403 Forbidden </c> <c> 4.03 </c>
<c> 404 Not Found </c> <c> 4.04 </c>
<c> 405 Method Not Allowed </c> <c> 4.05 </c>
<c> 409 Conflict </c> <c> none? </c>
<c> 412 Precondition Failed </c> <c> 4.12 </c>
<c> 413 Request Entity Too Large </c> <c> 4.13 </c>
<c> 414 Request-URI Too Large </c> <c> 4.00 </c>
<c> 415 Unsupported Media Type </c> <c> 4.15 </c>
<c> 500 Internal Server Error </c> <c> 5.00 </c>
<c> 501 Not Implemented </c> <c> 5.01 </c>
<c> 503 Service Unavailable </c> <c> 5.03 </c>
</texttable>
</section> <!-- error return codes -->
</section> <!-- MG Function Set -->
<section anchor="ERRORS" title="Error Handling">
<t>
In case a request is received which cannot be processed properly,
the managed entity MUST return an error message.
This error message MUST contain a CoAP 4.xx or 5.xx response code,
and SHOULD include additional information in the payload.
</t>
<t>
Such an error message payload is encoded in CBOR,
using the following structure:
</t>
<t>
TODO: Adapt RESTCONF <errors> data structure for use in CoMI. Need
to select the most important fields like <error-path>.
</t>
<figure><artwork align="left">
<![CDATA[
errorMsg : ErrorMsg;
*ErrorMsg {
errorCode : uint;
?errorText : tstr;
}
]]></artwork></figure>
<t>
The variable "errorCode" has one of the values from the table below,
and the OPTIONAL "errorText" field contains a human readable explanation of the error.
</t>
<texttable>
<ttcol align="left">CoMI Error Code</ttcol>
<ttcol align="left">CoAP Error Code</ttcol>
<ttcol align="left">Description</ttcol>
<c>0</c>
<c>4.00</c>
<c>General error</c>
<c>1</c>
<c>4.00</c>
<c>Malformed CBOR data</c>
<c>2</c>
<c>4.00</c>
<c>Incorrect CBOR datatype</c>
<c>3</c>
<c>4.00</c>
<c>Unknown MIB variable</c>
<c>4</c>
<c>4.00</c>
<c>Unknown conversion table</c>
<c>5</c>
<c>4.05</c>
<c>Attempt to write read-only variable</c>
<c>0..2</c>
<c>5.01</c>
<c>Access exceptions</c>
<c>0..18</c>
<c>5.00</c>
<c> SMI error status </c>
</texttable>
<t>
The CoAP error code 5.01 is associated with the exceptions defined in <xref target="RFC3416"/> and CoAP error code 5.00 is associated with the error-status defined in <xref target="RFC3416"/>.
</t>
</section>
<section title="Security Considerations">
<t>
For secure network management,
it is important to restrict access to configuration variables only to authorized parties.
This requires integrity protection of both requests and responses,
and depending on the application encryption.
</t>
<t>
CoMI re-uses the security mechanisms already available to CoAP as much as possible.
This includes DTLS <xref target="RFC6347"/> for protected access to resources,
as well suitable authentication and authorization mechanisms.
</t>
<t>
Among the security decisions that need to be made are
selecting security modes and encryption mechanisms (see <xref target="RFC7252"/>).
This requires a trade-off,
as the NoKey mode gives no protection at all,
but is easy to implement,
whereas the X.509 mode is quite secure,
but may be too complex for constrained devices.
</t>
<t>
In addition,
mechanisms for authentication and authorization may need to be selected.
</t>
<t>
CoMI avoids defining new security mechanisms as much as possible.
However some adaptations may still be required,
to cater for CoMI's specific requirements.
</t>
</section>
<section title="IANA Considerations">
<t>
'rt="core.mg.data"' needs registration with IANA.
</t>
<t>
'rt="core.mg.moduri"' needs registration with IANA.
</t>
<t>
'rt="core.mg.num-type"' needs registration with IANA.
</t>
<t>
'rt="core.mg.srv-type"' needs registration with IANA.
</t>
<t>
'rt="core.mg.yang-hash"' needs registration with IANA.
</t>
<t>
'rt="core.mg.stream"' needs registration with IANA.
</t>
<t>
'rt="core.mg.op"' needs registration with IANA.
</t>
<t>
Content types to be registered:
<list style="symbols">
<t>application/comi+cbor</t>
</list>
</t>
</section>
<section title="Acknowledgements">
<t>
We are very grateful to Bert Greevenbosch who was one of the original authors of the CoMI specification and specified CBOR encoding and use of hashes.
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 (alphabetical order) by Somaraju Abhinav, Rodney Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Alexander Pelov, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes Tschofenig, Michel Veillette, Michael Verschoor, and Thomas Watteyne.
</t>
</section>
<section title="Changelog">
<t>
Changes from version 00 to version 01
<list style="symbols">
<t> Focus on MIB only</t>
<t> Introduced CBOR, JSON, removed BER </t>
<t> defined mappings from SMI to xx </t>
<t> Introduced the concept of addressable table rows </t>
</list>
</t>
<t>
Changes from version 01 to version 02
<list style="symbols">
<t> Focus on CBOR, used JSON for examples, removed XML and EXI</t>
<t> added uri-query attributes mod and con to specify modules and contexts </t>
<t> Definition of CBOR string conversion tables for data reduction </t>
<t> use of Block for multiple fragments </t>
<t> Error returns generalized </t>
<t> SMI - YANG - CBOR conversion </t>
</list>
</t>
<t>
Changes from version 02 to version 03
<list style="symbols">
<t> Added security considerations</t>
</list>
</t>
<t>
Changes from version 03 to version 04
<list style="symbols">
<t> Added design considerations section</t>
<t> Extended comparison of management protocols in introduction </t>
<t> Added automatic generation of CBOR tables </t>
<t> Moved lowpan table to Appendix </t>
</list>
Changes from version 04 to version 05
<list style="symbols">
<t> Merged SNMP access with RESTCONF access to management objects in small devices </t>
<t> Added CoMI architecture section</t>
<t> Added RESTCONf NETMOD description </t>
<t> Rewrote section 5 with YANG examples </t>
<t> Added server and payload size appendix</t>
<t> Removed Appendix C for now. It will be replaced with a YANG example. </t>
</list>
Changes from version 04 to version 05
<list style="symbols">
<t> Extended examples with hash representation </t>
<t> Added keys query parameter text</t>
<t> Added select query parameter text </t>
<t> Better separation between specification and instance </t>
<t> Section on discovery updated</t>
<t> Text on rehashing introduced </t>
<t> Elaborated SMI MIB example </t>
<t> Yang library use described </t>
<t> use of BigEndian/LittleEndian in Hash generation specified </t>
</list>
Changes from version 05 to version 06
<list style="symbols">
<t> Hash values in payload as hexadecimal and in URL in base64 numbers </t>
<t> Streamlined CoMI architecture text</t>
<t> Added select query parameter text </t>
<t> Data editing optional </t>
<t> Text on Notify added</t>
<t> Text on rehashing improved with example </t>
</list>
Changes from version 06 to version 07
<list style="symbols">
<t> reduced payload size by removing JSON hierarchy </t>
<t> changed rehash handling to support small clients </t>
<t> added LWM2M comparison </t>
<t> Notification handling as specified in YANG </t>
<t> Added Patch function </t>
<t> Rehashing completely reviewed </t>
<t> Discover type of YANG name encoding </t>
<t> Added new resource types </t>
<t> Read-only servers introduced </t>
<t> Multiple updates explained </t>
</list>
Changes from version 07 to version 08
<list style="symbols">
<t> Changed YANG Hash algorithm to use module name instead of prefix </t>
<t> Added rehash bit to allow return values to identify rehashed nodes
in the response </t>
<t> Removed /mg/mod.set resource since this is not needed </t>
<t> Clarified that YANG Hash is done even for unimplemented objects </t>
<t> YANG lists transported as CBOR maps of maps </t>
<t> Adapted examples with more CBOR explanation </t>
<t> Added CBOR code examples in new appendix </t>
<t> Possibility to use other than default stream </t>
<t> Added text and examples for Patch payload </t>
<t> Repaired some examples </t>
<t> Added appendices on hash clash probability and hash clash storage overhead </t>
</list>
Changes from version 08 to version 09
<list style="symbols">
<t> Removed hash and YANG to CBOR sections </t>
<t> removed hashes from examples. </t>
<t> Added RPC </t>
<t> Added content query parameter. </t>
<t> Added default handling. </t>
<t> Listed differences with RESTCONF </t>
</list>
</t>
</section>
</middle>
<back>
<references title="Normative References">
&RFC2119;
&RFC5277;
&RFC6020;
&RFC7049;
&RFC7159;
&RFC7252;
&RFC7396;
&I-D.becker-core-coap-sms-gprs;
&I-D.ietf-core-block;
&I-D.ietf-core-observe;
&I-D.ietf-netmod-yang-json;
&I-D.ietf-netconf-restconf;
&I-D.vanderstok-core-patch;
&I-D.ietf-netconf-yang-patch;
&I-D.bierman-core-yang-hash;
</references>
<references title="Informative References">
&RFC2578;
&RFC3410;
&RFC3411;
&RFC3414;
&RFC3416;
&RFC3418;
&RFC4293;
&RFC6241;
&RFC6347;
&RFC6643;
&RFC6690;
&RFC7228;
&RFC7317;
&I-D.ietf-core-interfaces;
&I-D.ietf-lwig-coap;
<reference anchor="XML">
<front>
<title>Extensible Markup Language (XML)</title>
<author />
<date />
</front>
<seriesInfo name="Web" value="http://www.w3.org/xml"/>
</reference>
<reference anchor="OMA">
<front>
<title>OMA-TS-LightweightM2M-V1_0-20131210-C</title>
<author fullname="Open Mobile Alliance (OMA)"/>
<date />
</front>
<seriesInfo name="Web" value="http://technical.openmobilealliance.org/Technical/current_releases.aspx"/>
</reference>
<reference anchor="DTLS-size">
<front>
<title>Delegation-based Authentication and Authorization for the IP-based Internet of Things</title>
<author fullname="R.Hummen" initials="R." surname="Hummen"/>
<author fullname="H.Shafagh" initials="H." surname="Shafagh"/>
<author fullname="S.Raza" initials="S." surname="Raza"/>
<author fullname="T.Voigt" initials="T." surname="Voigt"/>
<author fullname="K.Wehrle" initials="K." surname="Wehrle"/>
<date />
</front>
<seriesInfo name="Web" value="http://www.vs.inf.ethz.ch/publ/papers/mshafagh_secon14.pdf"/>
</reference>
<reference anchor="mibreg">
<front>
<title>Structure of Management Information (SMI) Numbers (MIB Module Registrations)
</title>
<author fullname="IANA"/>
<date />
</front>
<seriesInfo name="Web" value="http://www.iana.org/assignments/smi-numbers/smi-numbers.xhtml/" />
</reference>
<reference anchor="management">
<front>
<title>Management of the Internet of Things</title>
<author fullname="Juergen Schoenwalder" initials="J." surname="Schoenwalder"/>
<author fullname="Anuj Sehgal" initials="A." surname="Sehgal"/>
<date year="2013"/>
</front>
<seriesInfo name="Web" value="http://cnds.eecs.jacobs-university.de/slides/2013-im-iot-management.pdf"/>
</reference>
<reference anchor="dcaf">
<front>
<title>Delegated Authenticated Authorization for
Constrained Environments </title>
<author fullname="Carsten Bormann" initials="C." surname="Bormann"/>
<author fullname="Olaf Bergmann" initials="O." surname="Bergmann"/>
<author fullname="Stefanie Gerdes" initials="S." surname="Gerdes"/>
<date />
</front>
<seriesInfo name="Private Information" value=""/>
</reference>
<reference anchor="openwsn">
<front>
<title>Coap size in Openwsn
</title>
<author fullname="Thomas Watteijne" initials="T." surname="Watteijne"/>
<date />
</front>
<seriesInfo name="Web" value="http://builder.openwsn.org/" />
</reference>
<reference anchor="Erbium">
<front>
<title>Erbium Memory footprint for coap-18</title>
<author fullname="Matthias Kovatsch" initials="M." surname="Kovatsch"/>
<date />
</front>
<seriesInfo name="Private Communication" value=""/>
</reference>
</references>
<section title="Payload and Server sizes" anchor="code-sizes">
<t>
This section provides information on code sizes and payload sizes for a set of management servers. Approximate code sizes are:
</t>
<texttable>
<ttcol align="left">Code</ttcol>
<ttcol align="left">processor</ttcol>
<ttcol align="left">Text</ttcol>
<ttcol align="left">Data</ttcol>
<ttcol align="left">reference</ttcol>
<c> Observe agent</c> <c> erbium </c> <c> 800 </c> <c> n/a </c> <c> <xref target="Erbium"/> </c>
<c> CoAP server </c> <c> MSP430 </c> <c> 1K </c> <c> 6 </c> <c> <xref target="openwsn"/> </c>
<c> SNMP server </c> <c> ATmega128 </c> <c> 9K </c> <c> 700 </c> <c> <xref target="management"/> </c>
<c> Secure SNMP </c> <c> ATmega128</c> <c> 30K </c> <c> 1.5K </c> <c> <xref target="management"/> </c>
<c> DTLS server </c> <c> ATmega128</c> <c> 37K </c> <c> 2K </c> <c> <xref target="management"/> </c>
<c> NETCONF </c> <c> ATmega128</c> <c> 23K </c> <c> 627 </c> <c> <xref target="management"/> </c>
<c> JSON parser </c> <c> CC2538</c> <c> 4.6K </c> <c> 8 </c> <c> <xref target="dcaf"/> </c>
<c> CBOR parser </c> <c> CC2538</c> <c> 1.5K </c> <c> 2.6K </c> <c> <xref target="dcaf"/> </c>
<c> DTLS server </c> <c> ARM7</c> <c> 15K </c> <c> 4 </c> <c> <xref target="I-D.ietf-lwig-coap"/> </c>
<c> DTLS server </c> <c> MSP430</c> <c> 15K </c> <c> 4 </c> <c><xref target="DTLS-size"/> </c>
<c> Certificate </c> <c> MSP430</c> <c> 23K </c> <c> </c> <c> <xref target="DTLS-size"/> </c>
<c> Crypto </c> <c> MSP430</c> <c> 2-8K </c> <c> </c> <c> <xref target="DTLS-size"/> </c>
</texttable>
<t>
Thomas says that the size of the CoAP server is rather arbitrary, as its size depends mostly on the implementation of the underlying library modules and interfaces.
</t><t>
Payload sizes are compared for the following request payloads, where each attribute value is null (N.B. these sizes are educated guesses, will be replaced with generated data). The identifier are assumed to be a string representation of the OID. Sizes for SysUpTime differ due to preambles of payload. "CBOR opt" stands for CBOR payload where the strings are replaced by table numbers.
</t>
<texttable>
<ttcol align="left">Request</ttcol>
<ttcol align="left">BERR SNMP</ttcol>
<ttcol align="left">JSON</ttcol>
<ttcol align="left">CBOR</ttcol>
<ttcol align="left">CBOR opt</ttcol>
<c> IPnetTOMediaTable</c> <c> 205 </c> <c> 327 </c> <c> ~327</c> <c> ~51 </c>
<c> lowpanIfStatsTable </c> <c> </c> <c> 710 </c> <c> 614 </c> <c> 121 </c>
<c> sysUpTime </c> <c> 29 </c> <c> 13 </c> <c> ~13 </c> <c> 20 </c>
<c> RESTCONF example </c> <c> </c> <c> </c> <c> </c> <c> </c>
</texttable>
</section>
<section anchor="LWM2M" title="Comparison with LWM2M">
<t>
CoMI and LWM2M, both, provide RESTful device management services
over CoAP. Differences between the
designs are highlighted in this section.
</t>
<t> LWM2M <xref target="OMA"/> objects are defined by standardized numbers. When new types are needed, new numbers need to be defined. This is the major difference with CoMI and YANG, where new modules can incorporate any type that is required without going through a standardization process, but may lead to rehashing. On the one hand LWM2M is static with very small numbered objects, where CoMI with YANG is more dynamic, with a number conversion overhead.
</t>
<t>
Unlike CoMI, which enables the use of SMIv2 and YANG data models
for device management, LWM2M defines a new object resource
model. This means that data models need to be redefined in order
to use LWM2M. In contrast, CoMI provides access to a large variety of
SMIv2 and YANG data modules that can be used immediately.
</t>
<t>
Objects and resources within CoMI are identified with a YANG hash
value, however, each object is described as a link in the CoRE
Link Format by LWM2M. This approach by LWM2M can lead to larger
complex URIs and more importantly payloads can grow large in
size. Using a hash value to represent the objects and resources
allows URIs and payloads to be smaller in size, which is important
for constrained devices that may not have enough resources to
process large messages.
</t>
<t>
LWM2M encodes payload data in Type-length-value (TLV), JSON or
plain text formats. While the TLV encoding is binary and can
result in reduced message sizes, JSON and plain text are likely to
result in large message sizes when lots of resources are being
monitored or configured. Furthermore, CoMI's use of CBOR gives it
an advantage over the LWM2M's TLV encoding as well since this too
is more efficient [citation needed].
</t>
<t>
CoMI is aligned with RESTCONF for constrained devices and uses YANG data models that have objects containing resources
organized in a tree-like structure. On the other hand, LWM2M uses
a very flat data model that follows the "object/instance/resource"
format, with no possibility to have sub-resources. Complex data
models are, as such, harder to model with LWM2M.
</t>
<t>
In situations where resources need to be modified, CoMI uses the
CoAP PATCH operation when resources are modified partially. However, LWM2M
uses the CoAP PUT and POST operations, even when a subset of the resource
needs modifications.
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-22 04:56:32 |