CoAP Management InterfaceTrilliant Networks Inc.610 Rue du LuxembourgGranbyQuebecJ2J 2V2Canadamichel.veillette@trilliantinc.comconsultant+31-492474673 (Netherlands), +33-966015248 (France)consultancy@vanderstok.orgwww.vanderstok.orgAcklio2bis rue de la ChataigneraieCesson-SevigneBretagne35510Francea@ackl.ioYumaWorks685 Cochran St.Suite #160Simi ValleyCA93065USAandy@yumaworks.com
Applications
CoREThis document describes a network management interface for constrained devices
and networks, called CoAP Management Interface (CoMI). The Constrained Application
Protocol (CoAP) is used to access datastore and data node resources specified
in YANG, or SMIv2 converted to YANG. CoMI uses the YANG to CBOR mapping and converts
YANG identifier strings to numeric identifiers for payload size reduction.
CoMI extends the set of YANG based protocols, NETCONF and RESTCONF, with
the capability to manage constrained devices and networks.Discussion and suggestions for improvement are requested,
and should be sent to core@ietf.org.The Constrained Application Protocol (CoAP) is designed for
Machine to Machine (M2M) applications such as smart energy, smart city 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. 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.This draft describes the CoAP Management Interface which uses CoAP methods
to access structured data defined in YANG . This draft is
complementary to which describes a REST-like interface
called RESTCONF, which uses HTTP methods to access structured data
defined in YANG.The use of standardized data models specified in a standardized language, such
as YANG, promotes interoperability between devices and applications from
different manufacturers.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.To promote small messges, CoMI uses a YANG to CBOR mapping
and numeric identifiers
to minimize CBOR payloads and URI length.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 .The following terms are defined in the YANG data modelling language : action, anydata, anyxml, client, configuration data, container, data model, data node, datastore, identity, instance identifier, key, key leaf, leaf, leaf-list, list, module, RPC, schema node, server, state data, submodule.The following term is defined in : YANG schema item identifier (SID).The following terms are defined in the CoAP protocol : Confirmable Message, Content-Format.The following terms are defined in this document:
a CoAP resource that models a YANG data node.
a CoAP resource that models a YANG datastore.
a CoAP resource used by clients to observe YANG notifications.
the resource that is associated with a particular CoAP request,
identified by the request URI.
An instance of a data node specified in a YANG module and stored in the server.
An instance of a schema node of type notification, specified in a YANG module
implemented by the server. The instance is generated in the server at the occurrence
of the corresponding event and reported by an event stream.
Handle used to identify a YANG data node that is an instance of a YANG “list”
specified with the values of the key leaves of the list.
Handle used to identify a specific data node which can be instantiated only
once. This includes data nodes defined at the root of a YANG module or
data nodes defined within a container. This excludes data nodes defined
within a list or any children of these data nodes.
List instance identifier or single instance identifier.
The value assigned to a data node instance. Data node values are serialized into
the payload according to the rules defined in section 4 of .This section describes the CoMI architecture to use CoAP for reading and
modifying the content of datastore(s) used for the management of the instrumented
node. is a high-level representation of the main elements of the CoMI management
architecture. The different numbered components of are discussed according to component number.
contains a set of named and versioned modules.
A named module specifies a set of variables and “conceptual tables”. There
is an algorithm to translate SMIv2 specifications to YANG specifications.
The CoMI client sends request messages to and receives response messages
from the CoMI server.
The processes performed by the CoMI clients and servers.
A resource used to access configuration data, state data, RPCs and actions. A CoMI server may support multiple datastores to support more complex operations such as configuration rollback, scheduled update.
An observable resource used to get real time notifications. A CoMI server may support multiple Event streams serving different purposes such as normal monitoring, diagnostic, syslog, security monitoring.
The server MUST prevent unauthorized users from reading or writing any CoMI
resources. CoMI relies on security protocols such as DTLS to secure CoAP communication.CoMI is a RESTful protocol for small devices where saving bytes to transport
counts. Contrary to RESTCONF, many design decisions are motivated by the
saving of bytes. Consequently, CoMI is not a RESTCONF over CoAP protocol,
but differs more significantly from RESTCONF. Some major differences are
cited below: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 identifier strings as numbers, where RESTCONF does not.CoMI uses the methods FETCH and iPATCH, not used by RESTCONF. RESTCONF uses
the HTTP methods HEAD, and OPTIONS, which are not used by CoMI.CoMI does not support “insert” query parameter (first, last, before, after)
and the “point” query parameter which are supported by RESTCONF.CoMI does not support the “start-time” and “stop-time” query parameters
to retrieve past notifications.CoMI and RESTCONF also differ in the handling of: notifications.default values.In the YANG specification, items are identified with a name string. In order
to significantly reduce the size of identifiers used in CoMI, numeric
identifiers are used instead of these strings.
YANG Schema Item iDentifier (SID) is defined in section 2.1.When used in a URI, SIDs are encoded in based64 using the URL and Filename safe
alphabet as defined by section 5. The last 6 bits encoded is always aligned
with the least significant 6 bits of the SID represented using an unsigned integer.
‘A’ characters (value 0) at the start of the resulting string are removed.For example, SID 1721 is encoded as follow.The resulting base64 representation of SID 1721 is “a5”Instance identifiers are used to uniquely identify data node instances within a datastore. This YANG built-in type is defined in section 9.13. An instance identifier is composed of the data node identifier (i.e. a SID) and for data nodes within list(s) the keys used to index within these list(s).When part of a payload, instance identifiers are encoded in CBOR based on the rules defined in section 5.13.1. When part of a URI, the SID is appended to the URI of the targeted datastore, the keys are specified using the ‘k’ URI-Query as defined in .An ordered map is used as a root container of the application/yang-tree+cbor Content-Format. This datatype share the same functionalities as a CBOR map without the following limitations:The ordering of the pairs of data items is preserved from serialization to deserialization.Duplicate keys are allowedThis schematic is constructed using a CBOR array comprising pairs of data items, each pair consisting of a key that is immediately followed by a value. Unlike a CBOR map for which the length denotes the number of pairs, the length of the ordered map denotes the number of items (i.e. number of keys plus number of values).The use of this schematic can be inferred from its context or by the presence of a preceding tag. The tag assigned to the Ordered map is defined in .In the case of CoMI, the use of the ordered map as the root container of the application/yang-tree+cbor Content-Format is inferred, the Ordered map tag is not used.ComI uses Content-Formats based on the YANG to CBOR mapping specified
in . All Content-Formats defined hereafter are
constructed using one or both of these constructs:YANG data node value, encoded based on the rules defined in section 4.YANG instance identifier, encoded based on the rules defined in section 5.13.1.The following Content-formats are defined:
represents a CBOR YANG document containing one YANG data node value.
The YANG data node instance can be a leaf, a container, a list, a list instance,
a RPC input, a RPC output, an action input, an action output, a leaf-list, an anydata
or an anyxml. The CBOR encoding for each of these YANG data node instances are defined in
section 4.FORMAT: data-node-valueDELTA ENCODING: SIDs included in a YANG container, a list instance, a RPC input, a RPC output,
an action input, an actions output and an anydata are encoded using a delta value equal to the
SID of the current schema node minus the SID of the parent. The parent SID of root data
nodes is defined by the URI carried in the associated request (i.e. GET, PUT, POST).
represents a YANG document containing a list of data node values.FORMAT: CBOR array of data-node-valueDELTA ENCODING: SIDs included in a YANG container, a list instance and an anydata are encoded
using a delta value equal to the SID of the current schema node minus the SID of the parent.
The parent SID of root data nodes is defined by the corresponding instance-identifier carried
in the FETCH request.
represents a CBOR YANG document containing a YANG data tree.FORMAT: ordered map of single-instance-identifier, data-node-valueDELTA ENCODING: The SID part of the first instance-identifier within the ordered map is
encoded using its absolute value. Subsequent instance-identifiers are
encoded using a delta value equal to the SID of the current instance-identifiers
minus the SID of the previous instance-identifier.
represents a CBOR YANG document containing a list of data node selectors (i.e. instance identifier).FORMAT: CBOR array of instance-identifierDELTA ENCODING: The SID part of the first instance-identifier within the CBOR array is
encoded using its absolute value. Subsequent instance-identifiers are
encoded using a delta value equal to the SID of the current instance-identifiers
minus the SID of the previous instance-identifier.
represents a CBOR YANG document containing a list of data nodes to be replaced, created, or deleted.For each data node instance, D, for which the
instance identifier is the same as for a data node instance, I, in the targeted
resource: the data node value of D replaces the data node value of I. When
the data node value of D is null, the data node instance I is removed. When
the targeted resource does not contain a data node instance with the same
instance identifier as D, a new data node instance is created in the targeted
resource with the same instance identifier and data node value as D.FORMAT: ordered map of instance-identifier, data-node-valueDELTA ENCODING: Same as Content-Format application/yang-tree+cborThe different Content-formats usage is summarized in the table below:MethodResourceContent-FormatGET responsedata node/application/yang-value+cborPUT requestdata node/application/yang-value+cborPOST requestdata node/application/yang-value+cborDELETEdata noden/aGET responsedatastore/application/yang-tree+cborPUT requestdatastore/application/yang-tree+cborPOST requestdatastore/application/yang-tree+cborFETCH requestdatastore/application/yang-selectors+cborFETCH responsedatastore/application/yang-values+cboriPATCH requestdatastore/application/yang-patch+cborGET responseevent stream/application/yang-tree+cborPOST requestrpc, action/application/yang-value+cborPOST responserpc, action/application/yang-value+cborThis section presents the notation used for the examples. The YANG modules
that are used throughout this document are shown in .
The example modules are copied from existing modules and annotated with
SIDs. The values of the SIDs are taken over from .CBOR is used to encode CoMI request and response payloads. The CBOR syntax
of the YANG payloads is specified in . The payload examples are
notated in Diagnostic notation (defined in section 6 of ) that
can be automatically converted to CBOR.SIDs in URIs are represented as a base64 number, SIDs in the payload are
represented as decimal numbers.The format of the links is specified in .
This note specifies a Management Collection Interface. CoMI end-points that
implement the CoMI management protocol, support
at least one discoverable management resource of resource type (rt): core.c.datastore,
with example path: /c, where c is short-hand for CoMI. The path /c is recommended
but not compulsory (see ).Three CoMI resources are accessible with the following three example paths:
Datastore resource with path “/c” and using CBOR content encoding format.
Sub-resouces of format /c/instance-identifier may be available to access
directly each data node resource for this datastore.
URI identifying the location of the YANG module library used by this server,
with path “/mod.uri” and Content-Format “text/plain; charset=utf-8”. An ETag
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.
Event stream resource to which YANG notification instances are reported.
Notification support is optional, so this resource will not exist if the
server does not support any notifications.The mapping of YANG data node instances to CoMI resources is as follows.
Every data node of the YANG modules loaded in the CoMI server represents
a sub-resource of the datastore resource (e.g. /c/instance-identifier).When multiple instances of a list exist, instance selection is possible
as described in , , and .The description of the management collection interface, with if=core.c, is
shown in the table below, following the guidelines of :FunctionRecommended pathrtDatastore/ccore.c.datastoreData node/c/instance-identifiercore.c.datanodeYANG module library/mod.uricore.c.moduriEvent steam/score.c.eventstreamThe path values are example values. On discovery, the server makes the actual
path values known for these four resources.The CoMI Collection Interface provides a CoAP interface to manage YANG servers.The methods used by CoMI are:OperationDescriptionGETRetrieve the datastore resource or a data node resourceFETCHRetrieve specific data nodes within a datastore resourcePOSTCreate a datastore resource or a data node resource, invoke an RPC or actionPUTCreate or replace a datastore resource or a data node resourceiPATCHIdem-potently create, replace, and delete data node resource(s) within a datastore resourceDELETEDelete a datastore resource or a data node resourceThere is one Uri-Query option for the GET, PUT, POST, and DELETE methods.Uri-Query optionDescriptionkSelect an instance within YANG list(s)This parameter is not used for FETCH and iPATCH, because their request payloads
support list instance selection.The “k” (key) parameter specifies a specific instance of a data node.
The SID in the URI is followed by the (?k=key1, key2,..). Where SID identifies
a data node, and key1, key2 are the values of the key leaves that specify
an instance. Lists can have multiple keys, and lists can be part
of lists. The order of key value generation is given recursively by:For a given list, if a parent data node is a list, generate the keys for the parent list first.For a given list, generate key values in the order specified in the YANG module.Key values are encoded using the rules defined in the following table.YANG datatypeUri-Query text contentuint8,uint16,unit32, uint64int2str(key)int8, int16,int32, int64urlSafeBase64(CBORencode(key))decimal64urlSafeBase64(CBOR key)stringkeyboolean“0” or “1”enumerationint2str(key)bitsurlSafeBase64(CBORencode(key))binaryurlSafeBase64(key)identityrefint2str(key)unionurlSafeBase64(CBORencode(key))instance-identifierurlSafeBase64(CBORencode(key))In this table:The method int2str() is used to convert an integer value to a string. For example, int2str(0x0123) return the string “291”.The method urlSafeBase64() is used to convert a binary string to base64 using the URL and Filename safe alphabet as defined by section 5. For example, urlSafeBase64(\xF9\x56\xA1\x3C) return the string “-VahPA”.The method CBORencode() is used to convert a YANG value to CBOR as specified in section 5, item 8.The resulting key string is encoded in a Uri-Query as specified in section 6.5.One or more data nodes can be retrieved by the client.
The operation is mapped to the GET method defined in
section 5.8.1 of and to the FETCH method defined in section 2 of .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 may be used, as explained in more detail in .There are two additional Uri-Query options for the GET and FETCH methods.Uri-Query optionDescriptioncControl selection of configuration and non-configuration data nodes (GET and FETCH)dControl retrieval of default values.The ‘c’ (content) parameter controls how descendant nodes of the
requested data nodes will be processed in the reply.The allowed values are:ValueDescriptioncReturn only configuration descendant data nodesnReturn only non-configuration descendant data nodesaReturn all descendant data nodesThis parameter is only allowed for GET and FETCH methods on datastore and
data node resources. A 4.02 (Bad Option) error is returned if used for other
methods or resource types.If this Uri-Query option is not present, the default value is “a”.The “d” (with-defaults) parameter controls how the default values of the
descendant nodes of the requested data nodes will be processed.The allowed values are:ValueDescriptionaAll data nodes are reported. Defined as ‘report-all’ in section 3.1 of .tData nodes set to the YANG default are not reported. Defined as ‘trim’ in section 3.2 of .If the target of a GET or FETCH method is a data node that represents a leaf
that has a default value, and the leaf has not been given a value by any
client yet, the server MUST return the default value of the leaf.If the target of a GET method is a data node that represents a
container or list that has child resources with default values,
and these have not been given value yet,The server MUST not return the child resource if d= ‘t’The server MUST return the child resource if d= ‘a’.If this Uri-Query option is not present, the default value is ‘t’.A request to read the values of a data node instance is sent with a confirmable
CoAP GET message. An instance identifier is specified in the URI path
prefixed with the example path /c.The returned payload contains the CBOR encoding of the specified data node instance value.Using for example the current-datetime leaf from , a request is sent to
retrieve the value of system-state/clock/current-datetime specified in container system-state.
The SID of system-state/clock/current-datetime is 1723, encoded in octal 3273,
yields two 6 bit decimal numbers 32 and 73, encoded in base64, (according to table 2 of )
yields a7. The response to the request returns the CBOR encoding of this leaf of type ‘string’
as defined in section 5.4.The next example represents the retrieval of a YANG container. In this
case, the CoMI client performs a GET request on the clock container
(SID = 1721; base64: a5). The container returned is encoded using a
CBOR map as specified by section 4.2.This example shows the retrieval of the /interfaces/interface YANG list
accessed using SID 1533 (base64: X9). The return payload is encoded using
a CBOR array as specified by section 4.4.1
containing 2 instances.It is equally possible to select a leaf of a specific instance of a list.
The example below requests the description leaf (SID=1534, base64: X-)
within the interface list corresponding to the list key “eth0”.
The returned value is encoded in CBOR based on the rules
specified by section 5.4.The FETCH is used to retrieve multiple data node values. The FETCH request
payload contains a list of instance-identifier encoded based on the rules
defined by Content-Format application/yang-selectors+cbor in .
The return response payload contains a list of values encoded based on the rules
defined by Content-Format application/yang-values+cbor in .
A value MUST be returned for each instance-identifier specified in the request.
A CBOR null is returned for each data node requested by the client, not supported
by the server or not currently instantiated.The example uses the current-datetime leaf and the interface list from .
In the following example the value of current-datetime (SID 1723 and the interface
list (SID 1533) instance identified with name=”eth0” are queried.CoMI allows datastore contents to be created, modified and deleted using
CoAP methods.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 CBOR arrays so messages will preserve their
order.The CoAP POST operation is used in CoMI for creation of data node resources and the
invocation of “ACTION” and “RPC” resources.
Refer to for details on “ACTION” and “RPC” resources.A request to create a data node resource is sent with a confirmable CoAP POST message.
The URI specifies the data node to be instantiated at the exception of list intances.
In this case, for compactness, the URI specifies the list for which an instance is created.If the data node resource already exists, then the POST request MUST fail and
a “4.09 Conflict” response code MUST be returnedThe example uses the interface list from .
Example is creating a new list instance within the interface list (SID = 1533):A data node resource instance is created or replaced with the PUT method.
A request to set the value of a data node instance is sent with a confirmable
CoAP PUT message.The example uses the interface list from .
Example is renewing an instance of the list interface (SID = 1533) with key
name=”eth0”:One or multiple data node instances are replaced with the idempotent
iPATCH method . A request is sent with a confirmable CoAP iPATCH message.There are no Uri-Query options for the iPATCH method.The processing of the iPATCH command is specified by Content-Format application/yang-patch+cbor.
In summary, if the CBOR patch payload contains a data node instance that is not present
in the target, this instance is added. If the target contains the specified instance,
the content of this instance is replaced with the value of the payload.
A null value indicates the removal of an existing data node instance.In this example, a CoMI client requests the following operations:Set “/system/ntp/enabled” (SID 1755) to true.Remove the server “tac.nrc.ca” from the”/system/ntp/server” (SID 1756) list.Add the server “NTP Pool server 2” to the list “/system/ntp/server” (SID 1756).A data node resource is deleted with the DELETE method.The example uses the interface list from .
Example is deleting an instance of the interface list (SID = 1533):The methods GET, PUT, POST, and DELETE can be used to request, replace, create,
and delete a whole datastore respectively.The content of the ordered map represents the complete datastore of the server
at the GET indication of after a successful processing of a PUT or POST request.
When an Ordered map is used to carry a whole datastore, all data nodes MUST
be identified using single instance identifiers (i.e. a SID), list instance
identifiers are not allowed.The example uses the interface list and the clock container from .
Assume that the datastore contains two modules ietf-system (SID 1700) and
ietf-interfaces (SID 1500); they contain the list interface (SID 1533) with
one instance and the container Clock (SID 1721). After invocation of GET, a
map with these two modules is returned:Event notification is an essential function for the management of servers.
CoMI allows notifications specified in YANG to be reported to a list
of clients. The recommended path of the default event stream is /s.
The server MAY support additional event stream resources to address different
notification needs.Reception of notification instances is enabled with the CoAP Observe
function. Clients subscribe to the notifications by sending a
GET request with an “Observe” option, specifying the /s resource when the
default stream is selected.Each response payload carries one or multiple notifications. The number of
notification reported and the conditions used to remove notifications
from the reported list is left to the implementers.
When multiple notifications are reported, they MUST be ordered starting from
the newest notification at index zero.An example implementation is:Every time an event is generated, the generated notification instance is
appended to the chosen stream(s). After appending the instance, the content
of the instance is sent to all clients observing the modified stream.Dependending on the storage space allocated to the notification stream, the
oldest notifications that do not fit inside the notification stream storage
space are removed.The array of data node instances may contain identical entries which have
been generated at different times.Suppose the server generates the event specified in .
By executing a GET on the /s resource the client receives the following response:In the example, the request returns a success response with the contents
of the last two generated events. Consecutively the server will regularly
notify the client when a new event is generated.To check that the client is still alive, the server MUST send confirmable
notifications periodically. When the client does not confirm the notification
from the server, the server will remove the client from the list of observers
.The YANG “action” and “RPC” statements specify the execution of a Remote
procedure Call (RPC) in the server. It is invoked using a POST method to
an “Action” or “RPC” resource instance. The request payload contains the
values assigned to the input container when specified. The response payload
contains the values of the output container when specified. Both the
input and output containers are encoded in CBOR using the rules defined in
section 4.2.1. Root data nodes are encoded using the delta
between the current SID and the SID of the invoked instance identifier
a specified by the URI.The returned success response code is 2.05 Content.The example is based on the YANG action specification of .
A server list is specified and the action “reset” (SID 60002, base64: Opq),
that is part of a “server instance” with key value “myserver”, is invoked. shows a YANG module mapped from the SMI specification “IP-MIB” .
The following example shows the “ipNetToPhysicalEntry” list with 2 instances,
using diagnostic notation without delta encoding.In this example one instance of /ip/ipNetToPhysicalEntry (SID 60021, base64: Oz1)
that matches the keys ipNetToPhysicalIfIndex = 1, ipNetToPhysicalNetAddressType = ipv4
and ipNetToPhysicalNetAddress = 9.2.3.4 (h’09020304’, base64: CQIDBA) is requested.The CoAP protocol provides reliability by acknowledging the UDP datagrams.
However, when large pieces of data need to be transported, datagrams get
fragmented, thus creating constraints on the resources in the client, server
and intermediate routers. The block option allows the transport
of the total payload in individual blocks of which the
size can be adapted to the underlying transport 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.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.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. On the server, values are changed, lists are re-ordered,
extended or reduced. When these actions happen during the serialization of
the contents of the resource, 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 the 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.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.c.datastore” .
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,
the value “/c” is used as an example. The example below shows the discovery
of the presence and location of management data.Implemented data nodes MAY be discovered using the standard CoAP resource discovery.
The implementation can add the data node identifiers (SID) supported to
/.well-known/core with rt=”core.c.datanode”. The available SIDs can be discovered
by sending a GET request to “/.well-known/core” including a resource type (rt)
parameter with the value “core.c.datanode”. Upon success, the return payload will
contain the registered SIDs and their location.The example below shows the discovery of the presence and location of data nodes.The list of data nodes may become prohibitively long. Therefore, it is recommended
to discover the details about the YANG modules implemented by reading
a YANG module library (e.g. “ietf-comi-yang-library” ad defined by ).The resource “/mod.uri” is used to retrieve the location of the YANG module library.
This library 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.The following example shows the URI of a local instance of container modules-state
(SID=1802) as defined in .The following example shows the URI of a remote instance of same container.Within the YANG module library all information about the module is stored
such as: module identifier, identifier hierarchy, grouping, features and
revision numbers.In case a request is received which cannot be processed properly, the CoMI server MUST return an error message. This error message MUST contain a CoAP 4.xx or 5.xx response code.Errors returned by a CoMI server can be broken into two categories, those associated to the CoAP protocol itself and those generated during the validation of the YANG data model constrains as described in section 8.The following list of common CoAP errors should be implemented by CoMI servers. This list is not exhaustive, other errors defined by CoAP and associated RFCs may be applicable.Error 4.01 (Unauthorized) is returned by the CoMI server when the CoMI client is not authorized to perform the requested action on the targeted resource (i.e. data node, datastore, rpc, action or event stream).Error 4.02 (Bad Option) is returned by the CoMI server when one or more CoAP options are unknown or malformed.Error 4.04 (Not Found) is returned by the CoMI server when the CoMI client is requesting a non-instantiated resource (i.e. data node, datastore, rpc, action or event stream).Error 4.05 (Method Not Allowed) is returned by the CoMI server when the CoMI client is requesting a method not supported on the targeted resource. (e.g. GET on an rpc, PUT or POST on a data node with “config” set to false).Error 4.08 (Request Entity Incomplete) is returned by the CoMI server if one or multiple blocks of a block transfer request is missing, see for more details.Error 4.13 (Request Entity Too Large) may be returned by the CoMI server during a block transfer request, see for more details.Error 4.15 (Unsupported Content-Format) is returned by the CoMI server when the Content-Format used in the request don’t match those specified in section 2.3.CoMI server MUST also enforce the different constraints associated to the YANG data models implemented. These constraints are described in section 8. These errors are reported using the CoAP error code 4.00 (Bad Request) and may have the following error container as payload. The YANG definition and associated .sid file are available in and . The error container is encoded using delta value equal to the SID of the current schema node minus the SID of the parent container (i.e 1024).The following error-tag and error-app-tag are defined by the ietf-comi YANG module, these tags are implemented as YANG identity and can be extended as needed.error-tag operation-failed is returned by the CoMI server when the operation request cannot be processed successfully. error-app-tag malformed-message is returned by the CoMI server when the payload received from the CoMI client don’t contain a well-formed CBOR content as defined in section 3.3 or don’t comply with the CBOR structure defined within this document.error-app-tag data-not-unique is returned by the CoMI server when the validation of the ‘unique’ constraint of a list or leaf-list fails.error-app-tag too-many-elements is returned by the CoMI server when the validation of the ‘max-elements’ constraint of a list or leaf-list fails.error-app-tag too-few-elements is returned by the CoMI server when the validation of the ‘min-elements’ constraint of a list or leaf-list fails.error-app-tag must-violation is returned by the CoMI server when the restrictions imposed by a ‘must’ statement are violated.error-app-tag duplicate is returned by the CoMI server when a client tries to create a duplicate list or leaf-list entry.error-tag invalid-value is returned by the CoMI server when the CoMI client tries to update or create a leaf with a value encoded using an invalid CBOR datatype or if the ‘range’, ‘length’, ‘pattern’ or ‘require-instance’ constrain is not fulfilled. error-app-tag invalid-datatype is returned by the CoMI server when CBOR encoding don’t follow the rules set by or when the value is incompatible with the YANG Built-In type. (e.g. a value greater than 127 for an int8, undefined enumeration)error-app-tag not-in-range is returned by the CoMI server when the validation of the ‘range’ property fails.error-app-tag invalid-length is returned by the CoMI server when the validation of the ‘length’ property fails.error-app-tag pattern-test-failed is returned by the CoMI server when the validation of the ‘pattern’ property fails.error-tag missing-element is returned by the CoMI server when the operation requested by a CoMI client fail to comply with the ‘mandatory’ constraint defined. The ‘mandatory’ constraint is enforced for leafs and choices, unless the node or any of its ancestors have a ‘when’ condition or ‘if-feature’ expression that evaluates to ‘false’. error-app-tag missing-key is returned by the CoMI server to further qualify an missing-element error. This error is returned when the CoMI client tries to create or list instance, without all the ‘key’ specified or when the CoMI client tries to delete a leaf listed as a ‘key’.error-app-tag missing-input-parameter is returned by the CoMI server when the input parameters of an RPC or action are incomplete.error-tag unknown-element is returned by the CoMI server when the CoMI client tries to access a data node of a YANG module not supported, of a data node associated to an ‘if-feature’ expression evaluated to ‘false’ or to a ‘when’ condition evaluated to ‘false’.error-tag bad-element is returned by the CoMI server when the CoMI client tries to create data nodes for more than one case in a choice.error-tag data-missing is returned by the CoMI server when a data node required to accept the request is not present. error-app-tag instance-required is returned by the CoMI server when a leaf of type ‘instance-identifier’ or ‘leafref’ marked with require-instance set to ‘true’ refers to an instance that does not exist.error-app-tag missing-choice is returned by the CoMI server when no nodes exist in a mandatory choice.error-tag error is returned by the CoMI server when an unspecified error has occurred.For example, the CoMI server might return the following error.For secure network management, it is important to restrict access to configuration variables
only to authorized parties. CoMI re-uses the security mechanisms already available to CoAP,
this includes DTLS for protected access to resources, as well suitable
authentication and authorization mechanisms.Among the security decisions that need to be made are selecting security modes and encryption
mechanisms (see ). 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.In addition, mechanisms for authentication and authorization may need to be selected.CoMI avoids defining new security mechanisms as much as possible.
However, some adaptations may still be required, to cater for CoMI’s specific requirements.This document adds the following resource type to the “Resource Type (rt=) Link Target Attribute Values”, within the “Constrained RESTful Environments (CoRE) Parameters” registry.ValueDescriptionReferencecore.c.datastoreYANG datastoreRFC XXXXcore.c.datanodeYANG data nodeRFC XXXXcore.c.liburiYANG module libraryRFC XXXXcore.c.eventstreamYANG event streamRFC XXXX// RFC Ed.: replace RFC XXXX with this RFC number and remove this note.This document adds the following Content-Format to the “CoAP Content-Formats”, within the “Constrained RESTful Environments (CoRE) Parameters” registry.Media TypeExcoding IDReferenceapplication/yang-value+cborXXXRFC XXXXapplication/yang-values+cborXXXRFC XXXXapplication/yang-selectors+cborXXXRFC XXXXapplication/yang-tree+cborXXXRFC XXXXapplication/yang-ipatch+cborXXXRFC XXXX// RFC Ed.: replace XXX with assigned IDs and remove this note.
// RFC Ed.: replace RFC XXXX with this RFC number and remove this note.This document adds the following media types to the “Media Types” registry.NameTemplateReferenceyang-value+cborapplication/yang-value+cborRFC XXXXyang-values+cborapplication/yang-values+cborRFC XXXXyang-selectors+cborapplication/yang-selectors+cborRFC XXXXyang-tree+cborapplication/yang-tree+cborRFC XXXXyang-ipatch+cborapplication/yang-ipatch+cborRFC XXXXEach of these media types share the following information:Subtype name: <as listed in table>Required parameters: N/AOptional parameters: N/AEncoding considerations: binarySecurity considerations: See the Security Considerations section of RFC XXXXInteroperability considerations: N/APublished specification: RFC XXXXApplications that use this media type: CoMIFragment identifier considerations: N/AAdditional information:Person & email address to contact for further information: iesg&ietf.orgIntended usage: COMMONRestrictions on usage: N/AAuthor: Michel Veillette, ietf&augustcellars.comChange Controller: IESGProvisional registration? No// RFC Ed.: replace RFC XXXX with this RFC number and remove this note.This document adds the following tags to the “Concise Binary Object Representation (CBOR) Tags” registry.TagData ItemSemanticsReferencexxxarrayOedered mapRFC XXXX// RFC Ed.: replace xxx by the assigned Tag and remove this note.
// RFC Ed.: replace RFC XXXX with this RFC number and remove this note.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 Rodney Cummings,
Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy Ropitault, Juergen
Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes Tschofenig, Michael Verschoor,
and Thomas Watteyne.Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.The Base16, Base32, and Base64 Data EncodingsThis document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK]NETCONF Event NotificationsThis document defines mechanisms that provide an asynchronous message notification delivery service for the Network Configuration protocol (NETCONF). This is an optional capability built on top of the base NETCONF definition. This document defines the capabilities and operations necessary to support this service. [STANDARDS-TRACK]With-defaults Capability for NETCONFThe Network Configuration Protocol (NETCONF) defines ways to read and edit configuration data from a NETCONF server. In some cases, part of this data may not be set by the NETCONF client, but rather a default value known to the server is used instead. In many situations the NETCONF client has a priori knowledge about default data, so the NETCONF server does not need to save it in a NETCONF configuration datastore or send it to the client in a retrieval operation reply. In other situations the NETCONF client will need this data from the server. Not all server implementations treat this default data the same way. This document defines a capability-based extension to the NETCONF protocol that allows the NETCONF client to identify how defaults are processed by the server, and also defines new mechanisms for client control of server processing of default data. [STANDARDS-TRACK]Concise Binary Object Representation (CBOR)The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack.The Constrained Application Protocol (CoAP)The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation.CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments.The YANG 1.1 Data Modeling LanguageYANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF).Block-Wise Transfers in the Constrained Application Protocol (CoAP)The Constrained Application Protocol (CoAP) is a RESTful transfer protocol for constrained nodes and networks. Basic CoAP messages work well for small payloads from sensors and actuators; however, applications will need to transfer larger payloads occasionally -- for instance, for firmware updates. In contrast to HTTP, where TCP does the grunt work of segmenting and resequencing, CoAP is based on datagram transports such as UDP or Datagram Transport Layer Security (DTLS). These transports only offer fragmentation, which is even more problematic in constrained nodes and networks, limiting the maximum size of resource representations that can practically be transferred.Instead of relying on IP fragmentation, this specification extends basic CoAP with a pair of "Block" options for transferring multiple blocks of information from a resource representation in multiple request-response pairs. In many important cases, the Block options enable a server to be truly stateless: the server can handle each block transfer separately, with no need for a connection setup or other server-side memory of previous block transfers. Essentially, the Block options provide a minimal way to transfer larger representations in a block-wise fashion.A CoAP implementation that does not support these options generally is limited in the size of the representations that can be exchanged, so there is an expectation that the Block options will be widely used in CoAP implementations. Therefore, this specification updates RFC 7252.Observing Resources in the Constrained Application Protocol (CoAP)The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server.PATCH and FETCH Methods for the Constrained Application Protocol (CoAP)The methods defined in RFC 7252 for the Constrained Application Protocol (CoAP) only allow access to a complete resource, not to parts of a resource. In case of resources with larger or complex data, or in situations where resource continuity is required, replacing or requesting the whole resource is undesirable. Several applications using CoAP need to access parts of the resources.This specification defines the new CoAP methods, FETCH, PATCH, and iPATCH, which are used to access and update parts of a resource.RESTCONF ProtocolThis document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF).CBOR Encoding of Data Modeled with YANGThis document defines encoding rules for serializing configuration data, state data, RPC input and RPC output, Action input, Action output and notifications defined within YANG modules using the Concise Binary Object Representation (CBOR) [RFC7049].YANG Schema Item iDentifier (SID)YANG Schema Item iDentifiers (SID) are globally unique 64-bit unsigned numbers used to identify YANG items. This document defines the semantics, the registration, and assignment processes of SIDs. To enable the implementation of these processes, this document also defines a file format used to persist and publish assigned SIDs.Constrained YANG Module LibraryThis document describes a YANG library that provides information about all the YANG modules used by a constrained network management server (e.g., a CoAP Management Interface (CoMI) server). Simple caching mechanisms are provided to allow clients to minimize retrieval of this information.Management Information Base for the Internet Protocol (IP)This memo defines a portion of the Management Information Base (MIB) for use with network management protocols in the Internet community. In particular, it describes managed objects used for implementations of the Internet Protocol (IP) in an IP version independent manner. This memo obsoletes RFCs 2011, 2465, and 2466. [STANDARDS-TRACK]Datagram Transport Layer Security Version 1.2This document specifies version 1.2 of the Datagram Transport Layer Security (DTLS) protocol. The DTLS protocol provides communications privacy for datagram protocols. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. The DTLS protocol is based on the Transport Layer Security (TLS) protocol and provides equivalent security guarantees. Datagram semantics of the underlying transport are preserved by the DTLS protocol. This document updates DTLS 1.0 to work with TLS version 1.2. [STANDARDS-TRACK]Constrained RESTful Environments (CoRE) Link FormatThis specification defines Web Linking using a link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links. Based on the HTTP Link Header field defined in RFC 5988, the Constrained RESTful Environments (CoRE) Link Format is carried as a payload and is assigned an Internet media type. "RESTful" refers to the Representational State Transfer (REST) architecture. A well-known URI is defined as a default entry point for requesting the links hosted by a server. [STANDARDS-TRACK]The JavaScript Object Notation (JSON) Data Interchange FormatJavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data.This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.A YANG Data Model for Interface ManagementThis document defines a YANG data model for the management of network interfaces. It is expected that interface-type-specific data models augment the generic interfaces data model defined in this document. The data model includes configuration data and state data (status information and counters for the collection of statistics).A YANG Data Model for System ManagementThis document defines a YANG data model for the configuration and identification of some common system properties within a device containing a Network Configuration Protocol (NETCONF) server. This document also includes data node definitions for system identification, time-of-day management, user management, DNS resolver configuration, and some protocol operations for system management.Reusable Interface Definitions for Constrained RESTful EnvironmentsThis document defines a set of Constrained RESTful Environments (CoRE) Link Format Interface Descriptions [RFC6690] applicable for use in constrained environments. These include the: Actuator, Parameter, Read-only parameter, Sensor, Batch, Linked Batch and Link List interfaces. The Batch, Linked Batch and Link List interfaces make use of resource collections. This document further describes how collections relate to interfaces. Many applications require a set of interface descriptions in order provide the required functionality. This document defines the concept of function sets to specify this set of interfaces and resources. Editor's notes: o The git repository for the draft is found at https://github.com/Extensible Markup Language (XML)W3CNETCONF Central: library of YANG modulesYUMAworksyang-cbor RegistryThis appendix shows five YANG example specifications taken over from as many
existing YANG modules. The YANG modules are available from .
Each YANG item identifier is accompanied by its SID shown after the “//”
comment sign.Excerpt of the YANG module ietf-system .Taken over from section 7.15.3.Excerpt of the YANG module ietf-interfaces .Notification example defined within this document.The YANG translation of the SMI specifying the IP-MIB , extended with example SID numbers, yields: