One document matched: draft-veillette-core-cool-01.xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.0.30 -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>
<?rfc strict="yes"?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc ipr="trust200902" docName="draft-veillette-core-cool-01" category="info">
<front>
<title>Constrained Objects Language</title>
<author initials="M.V." surname="Veillette" fullname="Michel Veillette" role="editor">
<organization>Trilliant Networks Inc.</organization>
<address>
<postal>
<street>610 Rue du Luxembourg</street>
<city>Granby</city>
<region>Quebec</region>
<code>J2J 2V2</code>
<country>Canada</country>
</postal>
<phone>+14503750556</phone>
<email>michel.veillette@trilliantinc.com</email>
</address>
</author>
<author initials="A.P." surname="Pelov" fullname="Alexander Pelov" role="editor">
<organization>Acklio</organization>
<address>
<postal>
<street>2bis rue de la Chataigneraie</street>
<city>Cesson-Sevigne</city>
<region>Bretagne</region>
<code>35510</code>
<country>France</country>
</postal>
<email>a@ackl.io</email>
</address>
</author>
<author initials="A.S." surname="Somaraju" fullname="Abhinav Somaraju">
<organization>Tridonic GmbH & Co KG</organization>
<address>
<postal>
<street>Farbergasse 15</street>
<city>Dornbirn</city>
<region>Vorarlberg</region>
<code>6850</code>
<country>Austria</country>
</postal>
<phone>+43664808926169</phone>
<email>abhinav.somaraju@tridonic.com</email>
</address>
</author>
<author initials="R.T." surname="Turner" fullname="Randy Turner">
<organization>Landis+Gyr</organization>
<address>
<postal>
<street>30000 Mill Creek Ave</street> <street>Suite 100</street>
<city>Alpharetta</city>
<region>GA</region>
<code>30022</code>
<country>US</country>
</postal>
<phone>++16782581292</phone>
<email>randy.turner@landisgyr.com</email>
<uri>http://www.landisgyr.com/</uri>
</address>
</author>
<author initials="A.M." surname="Minaburo" fullname="Ana Minaburo">
<organization>Acklio</organization>
<address>
<postal>
<street>2bis rue de la châtaigneraie</street>
<city>Cesson-Sévigné</city>
<region>Bretagne</region>
<code>35510</code>
<country>France</country>
</postal>
<email>ana@ackl.io</email>
</address>
</author>
<date year="2016" month="March" day="11"/>
<area>Applications and Real-Time Area (art)</area>
<workgroup>Internet Engineering Task Force</workgroup>
<keyword>CBOR</keyword>
<abstract>
<t>This document describes a management function set adapted to constrained devices and constrained networks (e.g., low-power, lossy). CoOL objects (datastores, RPCs, actions and notifications) are defined using the YANG modelling language <xref target="I-D.ietf-netmod-rfc6020bis"/>. Interactions with these objects are performed using the CoAP web transfer protocol <xref target="RFC7252"/>. Payloads are encoded using the CBOR data format <xref target="RFC7049"/>. The mapping between YANG data models and the CBOR data format is defined in [I-D.veillette-core-yang-cbor-mapping].</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>This document defines a CoAP function set for accessing YANG defined resources. YANG data models are encoded in CBOR based on the mapping rules defined in [I-D.veillette-core-yang-cbor-mapping]. YANG items are identified using a compact identifier called Structured Identifiers (SIDs) as defined in [I-D.somaraju-core-sid].</t>
<t>The resulting protocol based on CoAP, CBOR encoded data and structured identifiers (SID) has a low implementation footprint and low network bandwidth requirements and is suitable for both constrained devices and constrained networks as defined by <xref target="RFC7228"/>. This protocol is applicable to the different management topology options described by <xref target="I-D.ersue-constrained-mgmt"/>; centralized, distributed and hierarchical.</t>
</section>
<section anchor="terminology-and-notation" title="Terminology and Notation">
<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>The following terms are defined in <xref target="I-D.ietf-netmod-rfc6020bis"/>:</t>
<t><list style="symbols">
<t>action</t>
<t>data node</t>
<t>data tree</t>
<t>module</t>
<t>notification</t>
<t>RPC</t>
<t>schema node</t>
<t>schema tree</t>
<t>submodule</t>
</list></t>
<t>This specification also makes use of the following terminology:</t>
<t><list style="symbols">
<t>candidate configuration datastore: A configuration datastore that can be manipulated without impacting the device’s current configuration and that can be committed to the running configuration datastore. Not all devices support a candidate configuration datastore.</t>
<t>CoOL client: The originating endpoint of a request, and the destination endpoint of a response.</t>
<t>CoOL server: The destination endpoint of a request, and the originating endpoint of a response.</t>
<t>delta: Within a list, a delta represents the different between the current SID and the SID of the previous entry within this list. Within a collection, a delta represents the difference between the SID assigned to the current schema node and the SID assigned to the parent. When no previous entry or parent exist, the delta is set to the absolute SID value.</t>
<t>child: A schema node defined within a collection such as a container, a list, a case, a notification, a RPC input, a RPC output, an action input, an action output.</t>
<t>datastore: Resource used to store and access information.</t>
<t>endpoint: An entity participating in the CoOL protocol. Multiple CoOL endpoints may be accessible using a single CoAP endpoint. In this case, each CoOL endpoint is accessed using a distinct URI.</t>
<t>event stream: Resource used to access notifications generated by a CoOL server. Events are defined using the YANG notification statement.</t>
<t>function set: A group of well-known resources that provides a particular service.</t>
<t>object: Within CoOL, an object is a data node, an RPC or an action within a datastore resource or a notification within an event stream resource.</t>
<t>parent: The collection in which a schema node is defined.</t>
<t>resource: Content identified by a URI.</t>
<t>running configuration datastore: A configuration datastore holding the complete configuration currently active on the device. The running configuration datastore always exists.</t>
<t>Structured IDentifier (SID). Unsigned integer used to identify different YANG items.</t>
</list></t>
</section>
<section anchor="architecture" title="Architecture">
<t>The CoOL protocol is based on the client-server model. The CoOL server is the provider of the datastore resource(s) and the event stream resource(s). The CoOL client is the requester of these resources.</t>
<t>CoOL objects are defined using the YANG modeling language <xref target="RFC6020"/>. Interactions with these objects are performed using the Constrained Application Protocol (CoAP) <xref target="RFC7252"/>. Payloads are encoded using the Concise Binary Object Representation (CBOR) <xref target="RFC7049"/>.</t>
<t>This specification is applicable to any transport and security protocols supported by CoAP. Implementers are free to select the most appropriate transport for the targeted applications.</t>
<figure><artwork><![CDATA[
+--------------+ +----------------------------------+
| CoOL client | | CoOL Server |
| | | - Datastore resource(s) |
| | | - Event stream resource(s) |
+--------------+ +----------------------------------+
| CoAP client | <-------> | CoAP Server |
+--------------+ +----------------------------------+
| | | |
| Lower layers | | Lower layers |
| | | |
+--------------+ +----------------------------------+
]]></artwork></figure>
</section>
<section anchor="resources" title="Resources">
<t>This section lists the URIs recommended for the different CoOL resources. A CoOL server MAY implement a different set of URIs. See the Resource discovery section (Section 7.15) for more details on how a CoOL client can discover the list of URIs supported by a CoOL server using the “/.well-known/core” resource.</t>
<t><list style="symbols">
<t>/c – The default datastore resource</t>
<t>/c/c – The candidate configuration datastore resource</t>
<t>/c/r - The running configuration datastore resource</t>
<t>/c/b – The backup configuration datastore (use to implement rollbacks)</t>
<t>/c/e - URI used to access the default event stream for this device.</t>
<t>/c/e0, /c/e1, … - URI used to access alternate event streams.</t>
<t>/c/0, /c/1, … - URI used to access a specific endpoint. Each end point represents a virtual device which can support any of the resources listed above.</t>
</list></t>
<t>For example:</t>
<t><list style="symbols">
<t>/c/1 is the default datastore resource for endpoint 1</t>
<t>/c/1/c is the candidate datastore resource for endpoint 1</t>
<t>/c/1/r is the running configuration datastore resource for endpoint 1</t>
<t>/c/1/b is the backup configuration datastore resource for endpoint 1</t>
<t>/c/1/e is the default event stream resource for endpoint 1</t>
<t>/c/1/e0 is an alternate event stream resource for endpoint 1</t>
</list></t>
<t>All these resources are optional at the exception of the default datastore resource. The CoAP response code 4.04 (Not Found) MUST be returned when a CoOL client tries to access a resource that is unavailable.</t>
<t>RPCs commit and cancel-commit defined in ietf-cool YANG module are available to perform the following operations on datastores:</t>
<t><list style="symbols">
<t>Immediate or differed commit of a candidate or backup datastore.</t>
<t>Confirmed commit</t>
<t>Cancel of a different or confirmed commit.</t>
</list></t>
</section>
<section anchor="operations" title="Operations">
<t>This section defines the different interactions supported between a CoOL client and a CoOL server.</t>
<section anchor="get-retrieving-all-data-nodes-of-a-datastore" title="GET - Retrieving all data nodes of a datastore">
<t>The GET method is used by CoOL clients to retrieve the entire contents of a datastore. Implementation of this function is optional and dependent of the capability of the CoOL server to transfer a relatively large response.</t>
<t>To retrieve all instantiated data nodes of a datastore resource, a CoOL client sends a CoAP GET request to the URI of the targeted datastore. If the request is accepted by the CoOL server, a 2.05 (Content) response code is returned. The payload of the GET response MUST carry a CBOR array containing the contents of the targeted datastore. The CBOR array MUST contain a list of pairs of delta and associated value. A delta represents the difference between the current SID and the SID of the previous pair within the CBOR array. Each value is encoded using the rules defined by [I-D.veillette-core-yang-cbor-mapping].</t>
<t>If the request is rejected by the CoOL server, a 5.01 Not implemented or 4.13 Request Entity Too Large response code is returned.</t>
<t>Example:</t>
<t>In this example, the CoOL server returns a datastore containing the following data nodes defined in the YANG module “ietf-system” <xref target="RFC7317"/> and YANG module “ietf-interfaces” <xref target="RFC7223"/>:</t>
<t><list style="symbols">
<t>“/interfaces/interface” (SID 1529)</t>
<t>“/interfaces/interface/description” (SID 1530)</t>
<t>“/interfaces/interface/enabled” (SID 1531)</t>
<t>“/interfaces/interface/name” (SID 1533)</t>
<t>“/interfaces/interface/type” (SID 1534)</t>
<t>“/system-state/clock” (SID 1708)</t>
<t>“/system-state/clock/boot-datetime” (SID 1709)</t>
<t>“/system-state/clock/current-datetime” (SID 1710)</t>
<t>“/system/clock/timezone/timezone-utc-offset/timezone-utc-offset” (SID 1721)</t>
</list></t>
<t>CoAP Request:</t>
<figure><artwork><![CDATA[
GET /c
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/cool+cbor)
[
1529,
{
4 : "eth0", # name (SID 1533)
1 : "Ethernet adaptor", # description (SID 1530)
5 : 1179, # type (SID 1534), identity ethernetCsmacd
2 : true # enabled (SID 1531)
},
179, # clock (SID 1708)
{
1 : "2015-02-08T14:10:08Z09:00", # boot-datetime (SID 1709)
2 : "2015-04-04T09:32:51Z09:00" # current-datetime (SID 1710)
}
13, 60 # timezone-utc-offset (SID 1721)
]
]]></artwork></figure>
</section>
<section anchor="fetch-retrieving-specific-data-nodes" title="FETCH - Retrieving specific data nodes">
<t>The FETCH method is used by the CoOL client of retrieve a subset of the data nodes within a datastore.</t>
<t>To retrieve a list of data node instances, the CoOL client sends a CoAP FETCH request to the URI of the targeted datastore. The payload of the FETCH request contains the list of data node(s) instance to be retrieved. This list is encoded using a CBOR array, each entry containing an “instance-identifier” as defined by [I-D.veillette-core-yang-cbor-mapping]. Within each “instance-identifier”, data nodes are identified using SIDs as defined by [I-D.somaraju-core-sid].</t>
<t>SIDs within the list of “instance-identifier” are encoded using delta. A delta represents the different between the current SID and the SID of the previous entry within this list. The delta of the first entry within the list is set to the absolute SID value (current SID minus zero).</t>
<t>On successful processing of the CoAP request, the CoOL server MUST return a CoAP response with a response code 2.05 (Content).</t>
<t>When a single data node is requested, the payload of the GET response MUST carry the data node instance requested encoded using the rules defined in [I-D.veillette-core-yang-cbor-mapping].</t>
<t>When a multiple data nodes are requested, the payload of the GET response MUST carry a CBOR array containing the data node instance(s) requested. Each entry within this array MUST be encoding using the rules defined in [I-D.veillette-core-yang-cbor-mapping].</t>
<t>When a collection is returned (YANG container, YANG list or YANG list instance), delta(s) are computed using the requested SID as parent.</t>
<t>The CBOR value undefined (0xf7) must be returned for each data node requested but not currently available.</t>
<section anchor="example-1-simple-data-node" title="Example #1 - Simple data node">
<t>In this example, a CoOL client retrieves the leaf “/system-state/clock/current-datetime” (SID 1704) and the container “/system/clock” (SID 1719) containing the leaf “/system/clock/timezone/timezone-utc-offset/timezone-utc-offset” (SID 1721). These data nodes are defined in the YANG module “ietf-system” <xref target="RFC7317"/>.</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
FETCH /c Content-Format(application/cool+cbor)
[1704, 15]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/cool+cbor)
[
"2015-10-08T14:10:08Z09:00", # current-datetime (SID 1704)
{ # clock (SID 1719)
2 : 540 # timezone-utc-offset (SID 1721)
}
]
]]></artwork></figure>
<t>CoAP requests and responses MUST be encoded in accordance with <xref target="RFC7252"/> or <xref target="I-D.ietf-core-coap-tcp-tls"/>. An encoding example is shown below:</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Ver| T | TKL | Code (0x01) | Message ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Token (0 to 8 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Opt Delta (12)| Opt Length (1)| na | Opt Delta (3) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Opt Length (2)| '/' | 'c' |1 1 1 1 1 1 1 1|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x82 | 0x19 | 0x06 | 0xa8 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x0f |
+-+-+-+-+-+-+-+-+
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Ver| T | TKL | Code (0x45) | Message ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Token (0 to 8 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Opt Delta (12)| Opt Length (1)| na |1 1 1 1 1 1 1 1|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0xa2 | 0x78 | 0x19 | 0x32 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x30 | 0x31 | 0x35 | 0x2d |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x31 | 0x30 | 0x2d | 0x30 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x38 | 0x54 | 0x31 | 0x34 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x3a | 0x31 | 0x30 | 0x2d |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x30 | 0x38 | 0x5a | 0x30 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x39 | 0x3a | 0x30 | 0x30 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0xa1 | 0x02 | 0x19 | 0x02 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x1c |
+-+-+-+-+-+-+-+-+
]]></artwork></figure>
</section>
<section anchor="example-2-data-node-instance-within-a-yang-list" title="Example #2 - Data node instance within a YANG list">
<t>The data type “instance-identifier” allows the selection of an instance of a specific data node within a list. In this example, a CoOL client retrieves the “/interfaces/interface/type” (SID 1529) leaf from the “/interfaces/interface” list. The “/interfaces/interface/name” associated to this interface is equal to “eth0”. This example is based on the YANG module “ietf-interfaces” <xref target="RFC7223"/>.</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
FETCH /c Content-Format(application/cool+cbor)
[[1529, "eth0"]]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/cool+cbor)
"Ethernet adaptor"
]]></artwork></figure>
</section>
<section anchor="example-3-yang-list" title="Example #3 - YANG list">
<t>To retrieve all instances of a list, the CoOL client excludes from the “instance-identifier” the key(s) of the targeted list. The list returned is encoded using the rules defined in [I-D.veillette-core-yang-cbor-mapping] section 4.4.</t>
<t>In this example, a CoOL client retrieves the list “/interfaces/interface” (SID 1529). The response returns contain two instances, one for an Ethernet adaptor and one for a WIFI interface.</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
FETCH /c Content-Format(application/cool+cbor)
[1529]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/cool+cbor)
[
{
4 : "eth0", # name (SID 1533)
1 : "Ethernet adaptor", # description (SID 1530)
5 : 1179, # type (SID 1534), identity ethernetCsmacd
2 : true # enabled (SID 1531)
},
{
4 : "wlan0", # name (SID 1533)
1 : "WIFI ", # description (SID 1530)
5 : 1220, # type (SID 1534), identity ieee80211
2 : false # enabled (SID 1531)
}
]
]]></artwork></figure>
</section>
<section anchor="example-4-yang-list-instance" title="Example #4 - YANG list instance">
<t>To retrieve a list instance, the CoOL client MUST use an “instance-identifier” with a SID set to the targeted list and the key(s) set to the value(s) associated to the targeted instance.</t>
<t>In this example, the CoOL client requests the instance of the list “/interfaces/interface” (SID 1529) associated to the name “eth1”. The response returned by the CoOL server contains the targeted list instance formatted as YANG container.</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
FETCH /c Content-Format(application/cool+cbor)
[[1529, "eth1"]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/cool+cbor)
{
4 : "eth0" # name (SID 1533)
1 : "Ethernet adaptor" # description (SID 1530)
5 : 1179 # type (SID 1534), identity ethernetCsmacd
2 : true # enabled (SID 1531)
}
]]></artwork></figure>
</section>
<section anchor="example-5-yang-list-instance-filtering" title="Example #5 - YANG list instance filtering">
<t>This “instance-identifier” extension allows the selection of a subset of data nodes within a list. This is accomplished by adding an extra element to the “instance-identifier”. This element contains the subset of data nodes to be returned encoded as CBOR array. Each entry within this CBOR array is set to the delta between the current SID and the SID of targeted container as specified in the first entry of the “instance-identifier”.</t>
<t>CoOL servers SHOULD implement this “instance-identifier” extension. When this extension is not supported, the CoOL server MUST ignore the third element of the “instance-identifier” and return the list instance as specified by the first two elements of the “instance-identifier”.</t>
<t>In this example, a CoOL client retrieves from within the “/interfaces/interface” list (SID 1528) the leafs “/interfaces/interface/type” (SID 1533) and “/interfaces/interface/enabled” (SID 1530). The CoOL client also includes in this request the selection of the leaf “/system/hostname” defined in “ietf-system” <xref target="RFC7317"/>.</t>
<t>For example:</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
FETCH /c Content-Format(application/cool+cbor)
[ [1528, ["eth0"], [5, 2]], 211]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/cool+cbor)
[
{
5 : 1179, # type (SID 1533), identity ethernetCsmacd
2 : true # enabled (SID 1530)
},
"datatracker.ietf.org", # hostname (SID 1739)
]
]]></artwork></figure>
</section>
<section anchor="example-6-all-instances-of-a-data-node-within-a-yang-list" title="Example #6 - All instances of a data node within a YANG list">
<t>This “instance-identifier” extension allows the efficient transfer of all instances of a data node within a YANG list. To retrieve all instances, the CoOL client excludes form the “instance-identifier” the key(s) of the list containing the targeted data node.</t>
<t>The response MUST be encoded as a CBOR ARRAY containing the available instances of the requested data node. This special encoding minimizes significantly this commonly used type of request.</t>
<t>In this example, a CoOL client retrieves all instances of data node “/interfaces-state/interface/name” (SID 1532).</t>
<t>Example:</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
FETCH /c Content-Format(application/cool+cbor)
[1532]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/cool+cbor)
["eth0", "eth1", "wlan0"]
]]></artwork></figure>
</section>
</section>
<section anchor="put-updating-all-data-nodes-of-a-datastore" title="PUT - Updating all data nodes of a datastore">
<t>The CoAP PUT method is used by CoOL clients to update the content of a datastore.</t>
<t>The URI of the PUT request MUST be set to the URI of the targeted datastore.</t>
<t>The payload of the PUT request MUST carry a CBOR array containing the new content of the datastore. The CBOR array MUST contain a list of pairs of delta and associated value. A delta represents the different between the current SID and the SID of the previous pair within the CBOR array. Each value is encoded using the rules defined by [I-D.veillette-core-yang-cbor-mapping].</t>
<t>On successful processing of the CoAP request, the CoOL server MUST return a CoAP response with a response code 2.04 (Changed).</t>
<t>A PUT request MUST be processed as an atomic transaction, if any of the data node transferred is rejected for any reason, the entire PUT request MUST be rejected and the CoOL server MUST return an appropriate error response as defined in section 6.</t>
<t>Example:</t>
<t>In this example, a CoOL client sets the default runtime datastore with these data nodes:</t>
<t><list style="symbols">
<t>“/system/clock/timezone/timezone-utc-offset/timezone-utc-offset” (SID 1721)</t>
<t>“/system/ntp/enabled” (SID 1742)</t>
<t>“/system/ntp/server” (SID 1743)</t>
<t>“/system/ntp/server/name” (SID 1746)</t>
<t>“/system/ntp/server/prefer” (SID 1747)</t>
<t>“/system/ntp/server/transport/udp/udp” (SID 1748)</t>
<t>“/system/ntp/server/transport/udp/udp/address” (SID 1749)</t>
<t>“/system/ntp/server/transport/udp/udp/port” (SID 1750)</t>
</list></t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
PUT /c/r Content-Format(application/cool+cbor)
[
1727, 540, # timezone-utc-offset (SID 1721)
15, true, # enabled (SID 1742)
1, [ # server (SID 1743)
{
3 : "tic.nrc.ca", # name (SID 1746)
4 : true, # prefer (SID 1747)
5 : { # udp (SID 1748)
6 : "132.246.11.231", # address (SID 1749)
7 : 123 # port (SID 1750)
}
},
{
3 : "tac.nrc.ca", # name (SID 1746)
4 : false, # prefer (SID 1747)
5 : { # udp (SID 1748)
6 : "132.246.11.232" # address (SID 1749)
}
}
]
]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.04 Changed
]]></artwork></figure>
</section>
<section anchor="patch-updating-specific-data-nodes" title="PATCH - Updating specific data nodes">
<t>The PATCH method is used by CoOL clients to modify a subset of a datastore.</t>
<t>To modify a datastore, the CoOL client sends a CoAP PATH request to the URI of the targeted datastore. The payload of the FETCH request contains the list of data node instance(s) to be updated, inserted or deleted. This list is encoded using a CBOR array and contains a sequence of pairs of “instance-identifier” and associated values.</t>
<t>Within each “instance-identifier”, data nodes are identified using SIDs as defined by [I-D.somaraju-core-sid]. SIDs within the list are encoded as delta.</t>
<t>On reception, the list is processed by the CoOL server as follows:</t>
<t><list style="symbols">
<t>If the targeted data instance already exists, this instance is replaced by the associated value (not merged). To update only some children of a collection, each child data node MUST be provided individually.</t>
<t>If the targeted data instance doesn’t exist, this instance is created.</t>
<t>If the targeted data instance already exists but is associated with the value “null”, this instance is deleted.</t>
</list></t>
<t>On successful processing of the CoAP request, the CoOL server MUST return a CoAP response with a response code 2.05 (Content).</t>
<t>A PATCH request MUST be processed as an atomic transaction, if any of the data nodes transferred is rejected for any reasons, the entire PATCH request MUST be rejected and the CoOL server MUST return an appropriate error response as defined in section 6.</t>
<t>Example:</t>
<t>In this example, a CoOL client performs the following operations:</t>
<t><list style="symbols">
<t>Set “/system/ntp/enabled” to true.</t>
<t>Remove the server “tac.nrc.ca” from the”/system/ntp/server” list.</t>
<t>Add the server “NTP Pool server 2” to the list “/system/ntp/server”.</t>
<t>Set “prefer” to false for the server “tic.nrc.ca”.</t>
</list></t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
PATCH /c/r Content-Format(application/cool+cbor)
[
1742 , true, # enabled (1742)
[1, "tac.nrc.ca"], null, # server (SID 1743)
0, # server (SID 1743)
{
3 : "NTP Pool server 2", # name (SID 1746)
4 : true, # prefer (SID 1747)
5 : { # udp (SID 1748)
6 : "2620:10a:800f::11", # address (SID 1749)
}
}
[4, "tic.nrc.ca"], false # prefer (SID 1747)
]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.04 Changed
]]></artwork></figure>
</section>
<section anchor="post-protocol-operation" title="POST - Protocol operation">
<t>Protocol operations are defined using the YANG “rpc” or YANG “action” statements.</t>
<t>To execute a protocol operation, the CoOL client sents a CoAP POST request to the URI of the targeted datastore.</t>
<t>The payload of the POST request carries a CBOR array with up to two entries. The first entry carries the instance-identifier identifying the targeted protocol operation. The second entry carries the protocol operation input(s). Input(s) are present only if defined for the invoked protocol operation and used by the CoOL client. Input(s) are encoded using the rules defined for a YANG container, deltas are relative to the SID assigned to the protocol operation.</t>
<t>On successful completion on the protocol operation, the CoOL server returns a CoAP response with the response code set to 2.05 (Content). When output parameters are returned by the CoOL server, these parameter(s) are carried in the CoAP response payload. Output(s) are encoded using the rules defined for a YANG container, deltas are relative to the SID assigned to the protocol operation.</t>
<section anchor="example-1-rpc" title="Example #1 - RPC">
<t>This example is based on the “activate-software-image” RPC defined in <xref target="I-D.ietf-netmod-rfc6020bis"/>, assuming that this RPC is assigned to SID 1932, leaf image-name to SID 1933 and leaf status to SID 1934. These SIDs are defined strictly for the purpose of this example.</t>
<t>rpc activate-software-image {
input {
leaf image-name {
type string;
}
}
output {
leaf status {
type string;
}
}
}</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
POST /c Content-Format(application/cool+cbor)
[
1932,
{
1 : "acmefw-2.3" # image-name (SID 1933)
}
]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content
{
2 : "installed" # status (SID 1934)
}
]]></artwork></figure>
</section>
<section anchor="example-2-action" title="Example #2 - Action">
<t>This example is based on the “reset” action defined in <xref target="I-D.ietf-netmod-rfc6020bis"/> assuming that this action is assigned to SID 1902, leaf reset-at to SID 1903 and leaf reset-finished-at to SID 1904. These SIDs are defined strictly for the purpose of this example.</t>
<t>list server {
key name;
leaf name {
type string;
}
action reset {
input {
leaf reset-at {
type yang:date-and-time;
mandatory true;
}
}
output {
leaf reset-finished-at {
type yang:date-and-time;
mandatory true;
}
}
}
}</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
POST /c Content-Format(application/cool+cbor)
[
[1902, "myServer"],
{
1 : "2016-02-08T14:10:08Z09:00" # reset-at (SID 1903)
}
]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content
{
2 : "2016-08T14:10:08Z09:18" # reset-finished-at (SID 1904)
}
]]></artwork></figure>
</section>
</section>
<section anchor="event-stream" title="Event stream">
<figure><artwork><![CDATA[
WARNING
This section requires more work to address the following identified issues:
* Retrieval of past events (e.g. start-time, stop-time)
* Retrieval of specific events (e.g. filter)
* Configuration persistence
* Configuration of by a third entity (configuration tool)
* Support of multicast
* Event congestion-avoidance
* Transfer reliability
The current solution based on the observe CoAP option can be augmented
or completely replaced by a future version of this draft.
]]></artwork></figure>
<t>Notifications are defined using the YANG “notification” statement. Subscriptions to an event stream and notification reporting are performed using an event stream resource. When multiple event stream resources are supported, the list of notifications associated with each stream is either pre-defined or configured in the CoOL server. CoOL clients MAY subscribe to one or more event stream resources.</t>
<t>To subscribe to an event stream resource, a CoOL client MUST send a CoAP GET with the Observe CoAP option set to 0. To unsubscribe, a CoOL client MAY send a CoAP reset or a CoAP GET with the Observe option set to 1. For more information on the observe mechanism, see <xref target="RFC7641"/>.</t>
<t>Each notification transferred by a CoOL server to each of the registered CoOL clients is carried in a CoAP response with a response code set to 2.05 (Content). Each CoAP response MUST carry in its payload at least one notification but MAY carry multiple. Each notification is carried in a notification-payload defined in ietf-cool, see <xref target="cool-module"/>. The notification-payload supports different meta-data associated to this notification, such as the notification identifier, event timestamp, sequence number, severity level and facility. All of these meta information are optional with the exception of the notification identifier.</t>
<t>The CoAP response payload is encoded using the rules defined for the PUT request. When multiple notifications are reported, the CoAP response payload carries a CBOR array, with each entry containing a notification.</t>
<t>This example is based on the “link-failure” and “interface-enabled” notifications defined in <xref target="I-D.ietf-netmod-rfc6020bis"/> assuming the following SID assignment:</t>
<t><list style="symbols">
<t>“/link-failure” (SID 1942)</t>
<t>“/link-failure/if-name” (SID 1943)</t>
<t>“/link-failure/admin-status” (SID 1944)</t>
<t>“/interfaces/interface/interface-enabled” (SID 1538)</t>
<t>“/interfaces/interface/interface-enabled/by-user” (SID 1539)</t>
</list></t>
<t>These SIDs are defined strictly for the purpose of this example.</t>
<figure><artwork><![CDATA[
notification link-failure {
leaf if-name {
type leafref {
path "/interface/name";
}
}
leaf admin-status {
type leafref {
path "/interface[name = current()/../if-name]/admin-status";
}
}
}
]]></artwork></figure>
<figure><artwork><![CDATA[
container interfaces {
list interface {
key "name";
leaf name {
type string;
}
notification interface-enabled {
leaf by-user {
type string;
}
}
}
}
]]></artwork></figure>
<t>In this example, a CoOL client starts by registering to the default event stream resource “/c/e”.</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
GET /c/e observe(0) Token(0x9372)
]]></artwork></figure>
<t>The CoOL server confirms this registration by returning a first CoAP response. The payload of this CoAP response may be empty or may carry the last notification reported by this server.</t>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Observe(52) Token(0xD937)
]]></artwork></figure>
<t>After detecting an event, the CoOL server sends its first notification to the registered CoOL client.</t>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Observe(53) Token(0xD937)
Content-Format(application/cool+cbor)
[
1010 , [1538, "eth0"], # _id (SID 1010)
1,{ # content (SID 1011)
1 : "bob" # by-user (SID 1539)
}
5 , "2016-03-08T14:10:08Z09:00", # timestamp (SID 1015)
]
]]></artwork></figure>
<t>To optimize communications or because of other constraints, the CoOL server might transfer multiple notifications in a single CoAP response.</t>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Observe(52) Token(0xD937)
Content-Format(application/cool+cbor)
[
[
1010 , [1538, "eth0"], # _id = interface-enabled (SID 1010)
1,{ # content (SID 1011)
1 : "jack" # by-user (SID 1539)
}
5 , "2016-03-12T15:49:51Z09:00", # timestamp (SID 1015)
],
[
1010 , 1942, # _id = link-failure (SID 1010)
1,{ # content (SID 1011)
1 : "eth0", # if-name (SID 1943)
1 : 1 # admin-status = up (SID 1944)
}
5 , "2016-03-12T15:50:06Z09:00", # timestamp (SID 1015)
]
]
]]></artwork></figure>
</section>
</section>
<section anchor="coap-compatibility" title="CoAP compatibility">
<section anchor="working-with-uri-host-uri-port-uri-path-and-uri-query" title="Working with Uri-Host, Uri-Port, Uri-Path, and Uri-Query">
<t>Uri-Query is not currently used by this protocol. Uri-Host, Uri-Port and Uri-Path MUST be used as specified by <xref target="RFC6690"/> to target the CoOL resources as defined by section 3.</t>
</section>
<section anchor="working-with-location-path-and-location-query" title="Working with Location-Path and Location-Query">
<t>This version of CoOL doesn’t support the creation of resources (datastore or event stream). For this reason, the use of Location-Path and Location-Query is not required.</t>
</section>
<section anchor="working-with-accept" title="Working with Accept">
<t>This option is not required since this protocol supports a single content format, “application/cool+cbor”.</t>
</section>
<section anchor="working-with-max-age" title="Working with Max-Age">
<t>This option MUST be supported as specified by <xref target="RFC6690"/>.</t>
</section>
<section anchor="working-with-proxy-uri-and-proxy-scheme" title="Working with Proxy-Uri and Proxy-Scheme">
<t>This option MUST be supported as specified by <xref target="RFC6690"/>.</t>
</section>
<section anchor="working-with-if-match-if-none-match-and-etag" title="Working with If-Match, If-None-Match and ETag">
<t>This option MUST be supported as specified by <xref target="RFC6690"/>. Each ETag is associated to all schema nodes within a datastore.</t>
</section>
<section anchor="working-with-size1-size2-block1-and-block2" title="Working with Size1, Size2, Block1 and Block2">
<t>When the UDP transport is used and a large payload need to be transferred, support of the CoAP block transfer as defined by <xref target="I-D.ietf-core-block"/> is recommended.</t>
<t>6.8. Working with Observe</t>
<t>A CoOL server MAY support state change notifications to some or all its leaf data nodes. When supported the CoOL server MUST implement the Server-Side requirements defined in <xref target="RFC7641"/> section 3 and the CoOL client MUST implement the Client-Side requirements defined in <xref target="RFC7641"/> section 4.</t>
<t>To start observing a leaf data node, a CoOL client MUST send a CoAP FETCH with the Observe CoAP option set to 0.</t>
<t>The payload of the FETCH request carries a CBOR array of instance-identifier.
The first entry MUST be set to the “instance-identifier” of the data node instance observed. The following entries are optional and allow the selection of coincidental values, data nodes reported at the same time as the observed data node. Coincidental values are included in each notification reported, but changes to these extra data nodes MUST not trigger notification messages.</t>
<t>A subscription can be terminated by the CoOL client by returning a CoAP Reset message or by sending a GET request with an Observe CoAP option set to deregister (1). More details are available in <xref target="RFC7641"/>.</t>
<t>Example:</t>
<t>In this example, a CoOL client subscribes to state changes of the data node “/system/ntp/enabled” (SID = 1742) and requests that data node “/system/hostname” (SID 1739) is reported as coincidental value.</t>
<t>A first response is immediately returned by the CoOL server to confirm the subscription and to report the current values of the requested data nodes.</t>
<t>Subsequent responses are returned by the CoOL server each time the state of data node “/system/ntp/enabled” changes.</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
FETCH /c Content-Format(application/cool+cbor) Observe(0)
[ [1742, "tic.nrc.ca"], -3 ]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/cool+cbor) Observe(2631)
[
false, # enabled (SID 1742)
"tic" # hostname (SID 1739)
]
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/cool+cbor) Observe(2632)
[
true, # enabled (SID 1742)
"tic" # hostname (SID 1739)
]
]]></artwork></figure>
</section>
<section anchor="working-with-resource-discovery" title="Working with resource discovery">
<t>The “/.well-known/core” resource is used by CoOL clients to discover resources implemented by CoOL servers. Each CoOL server MUST have an entry in the “/.well-known/core” resource for each datastore resource and event stream resource supported.</t>
<t>Resource discovery can be performed using a CoAP GET request. If successful, the CoAP response MUST have a response code set to 2.05 (Content), a Content-Format set to “application/link-format”, and a payload containing a list of web links.</t>
<t>To enable discovery of specific resource types, the CoAP server MUST support the query string “rt”.</t>
<t>Link format and the “/.well-known/core” resource are defined in <xref target="RFC6690"/>.</t>
<t>Example:</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
GET /.well-known/core
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/link-format)
</c>;rt="cool.datastore",
</c/r>;rt="cool.datastore",
</c/b>;rt="cool.datastore",
</c/e>;rt="cool.event-stream",
]]></artwork></figure>
<t>In this example, a CoOL client retrieves the list of all resources available on a CoOL server.</t>
<t>Alternatively, the CoOL client may query for a specific resource type. In this example, the CoOL client queries for resource type (rt) “cool.datastore”.</t>
<t>CoAP request:</t>
<figure><artwork><![CDATA[
GET /.well-known/core?rt=cool.datastore
]]></artwork></figure>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
2.05 Content Content-Format(application/link-format)
</c>;rt="cool.datastore",
]]></artwork></figure>
</section>
</section>
<section anchor="error-handling" title="Error Handling">
<t>All CoAP response codes defined by <xref target="RFC7252"/> MUST be accepted and processed accordingly by CoOL clients. Optionally, client errors (CoAP response codes 4.xx) or server errors (CoAP response codes 5.xx) MAY have a payload providing further information about the cause of the error. This payload contains the “ error-payload” container (SID 1006) defined in the “ietf-cool” YANG module, see <xref target="cool-module"/>.</t>
<t>Example:</t>
<t>CoAP response:</t>
<figure><artwork><![CDATA[
4.00 Bad Request (Content-Format: application/cool+cbor)
[
1006 , {
1 : 2, # error-code, SID 1007
2 : "Unknown data node 69687" # error-text, SID 1008
}
]
]]></artwork></figure>
</section>
<section anchor="security-considerations" title="Security Considerations">
<t>This application protocol relies on the lower layers to provide confidentiality, integrity, and availability. A typical approach to archive these requirements is to implement CoAP using the DTLS binding as defined in <xref target="RFC7252"/> section 9. Other approaches are possible to fulfill these requirements, such as the use of a network layer security mechanism as discussed in <xref target="I-D.bormann-core-ipsec-for-coap"/> or a link layer security mechanism for exchanges done within a single sub-network.</t>
<t>In some applications, different access rights to objects (data nodes, protocol operations and notifications) need to be granted to different CoOL clients. Different solutions are possible, such as the implementation of Access Control Lists (ACL) using YANG module(s) or the use of an authorization certificate as defined in <xref target="RFC5755"/>. These access control mechanisms need to be addressed in complementary specifications.</t>
<t>The Security Considerations section of CoAP <xref target="RFC7252"/> is especially relevant to this application protocol and should be reviewed carefully by implementers.</t>
</section>
<section anchor="iana-considerations" title="IANA Considerations">
<section anchor="fetch-coap-method-code" title="“FETCH” CoAP Method Code">
<t>This draft makes use of the PATCH CoAP method as defined in <xref target="I-D.bormann-core-coap-fetch"/>. This method needs to be registered in the CoAP Method Codes sub-registry as defined in <xref target="RFC7252"/> section 12.1.1.</t>
</section>
<section anchor="patch-coap-method-code" title="“PATCH” CoAP Method Code">
<t>This draft makes use of the PATCH CoAP method as defined in <xref target="I-D.vanderstok-core-patch"/>. This method needs to be registered in the CoAP Method Codes sub-registry as defined in <xref target="RFC7252"/> section 12.1.1.</t>
</section>
</section>
<section anchor="acknowledgments" title="Acknowledgments">
<t>This document have been largely inspired by the extensive works done by Andy Bierman and Peter van der Stok on <xref target="I-D.vanderstok-core-comi"/>. <xref target="I-D.ietf-netconf-restconf"/> have also been a critical input to this work. The authors would like to thank the authors and contributors to these two drafts.</t>
<t>The authors would also like to thank Carsten Bormann for his help during the development of this document and his useful comments during the review process.</t>
</section>
</middle>
<back>
<references title='Normative References'>
<reference anchor='I-D.ietf-core-block'>
<front>
<title>Block-wise transfers in CoAP</title>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<author initials='Z' surname='Shelby' fullname='Zach Shelby'>
<organization />
</author>
<date month='September' day='14' year='2015' />
<abstract><t>CoAP is a RESTful transfer protocol for constrained nodes and networks. Basic CoAP messages work well for the small payloads we expect from temperature sensors, light switches, and similar building-automation devices. Occasionally, however, applications will need to transfer larger payloads -- for instance, for firmware updates. With HTTP, TCP does the grunt work of slicing large payloads up into multiple packets and ensuring that they all arrive and are handled in the right order. CoAP is based on datagram transports such as UDP or DTLS, which limits the maximum size of resource representations that can be transferred without too much fragmentation. Although UDP supports larger payloads through IP fragmentation, it is limited to 64 KiB and, more importantly, doesn't really work well for constrained applications and networks. 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. In summary, the Block options provide a minimal way to transfer larger representations in a block-wise fashion.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-core-block-18' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-core-block-18.txt' />
</reference>
<reference anchor='I-D.bormann-core-coap-fetch'>
<front>
<title>CoAP FETCH Method</title>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<date month='October' day='19' year='2015' />
<abstract><t>Similar to HTTP, the existing Constrained Application Protocol (CoAP) GET method only allows the specification of a URI and request parameters in CoAP options, not the transfer of a request payload detailing the request. This leads to some applications to using POST where actually a cacheable, idempotent, safe request is desired. The present proposal adds a new CoAP method, FETCH, to perform the equivalent of a GET with a request body. This specification is inspired by I-D.snell-search-method, which updates the definition and semantics of the HTTP SEARCH request method previously defined by RFC5323. However, there is no intention to limit FETCH to search-type operations, and the resulting properties may not be the same as those of HTTP SEARCH. For now, we therefore prefer to discuss the proposal under a different name, for which we have chosen the GET synonym FETCH.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-bormann-core-coap-fetch-00' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-bormann-core-coap-fetch-00.txt' />
</reference>
<reference anchor='I-D.vanderstok-core-patch'>
<front>
<title>Patch Method for Constrained Application Protocol (CoAP)</title>
<author initials='P' surname='Stok' fullname='Peter Van der Stok'>
<organization />
</author>
<author initials='A' surname='Sehgal' fullname='Anuj Sehgal'>
<organization />
</author>
<date month='October' day='5' year='2015' />
<abstract><t>The existing Constrained Application Protocol (CoAP) PUT method only allows a complete replacement of a resource. This does not permit applications to perform partial resource modifications. In case of resources with larger or complex data, or in situations where a resource continuity is required, replacing a resource is not an option. Several applications using CoAP will need to perform partial resource modifications. This proposal adds new CoAP methods, PATCH and iPATCH, to modify an existing CoAP resource partially.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-vanderstok-core-patch-02' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-vanderstok-core-patch-02.txt' />
<format type='PDF'
target='http://www.ietf.org/internet-drafts/draft-vanderstok-core-patch-02.pdf' />
</reference>
<reference anchor='I-D.ietf-netmod-rfc6020bis'>
<front>
<title>The YANG 1.1 Data Modeling Language</title>
<author initials='M' surname='Bjorklund' fullname='Martin Bjorklund'>
<organization />
</author>
<date month='February' day='16' year='2016' />
<abstract><t>YANG is a data modeling language used to model configuration data, state data, remote procedure calls, and notifications for network management protocols like the Network Configuration Protocol (NETCONF).</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-netmod-rfc6020bis-11' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-netmod-rfc6020bis-11.txt' />
</reference>
<reference anchor='RFC2119' target='http://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>In 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.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>
<reference anchor='RFC6020' target='http://www.rfc-editor.org/info/rfc6020'>
<front>
<title>YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)</title>
<author initials='M.' surname='Bjorklund' fullname='M. Bjorklund' role='editor'><organization /></author>
<date year='2010' month='October' />
<abstract><t>YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='6020'/>
<seriesInfo name='DOI' value='10.17487/RFC6020'/>
</reference>
<reference anchor='RFC6690' target='http://www.rfc-editor.org/info/rfc6690'>
<front>
<title>Constrained RESTful Environments (CoRE) Link Format</title>
<author initials='Z.' surname='Shelby' fullname='Z. Shelby'><organization /></author>
<date year='2012' month='August' />
<abstract><t>This 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]</t></abstract>
</front>
<seriesInfo name='RFC' value='6690'/>
<seriesInfo name='DOI' value='10.17487/RFC6690'/>
</reference>
<reference anchor='RFC7049' target='http://www.rfc-editor.org/info/rfc7049'>
<front>
<title>Concise Binary Object Representation (CBOR)</title>
<author initials='C.' surname='Bormann' fullname='C. Bormann'><organization /></author>
<author initials='P.' surname='Hoffman' fullname='P. Hoffman'><organization /></author>
<date year='2013' month='October' />
<abstract><t>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.</t></abstract>
</front>
<seriesInfo name='RFC' value='7049'/>
<seriesInfo name='DOI' value='10.17487/RFC7049'/>
</reference>
<reference anchor='RFC7252' target='http://www.rfc-editor.org/info/rfc7252'>
<front>
<title>The Constrained Application Protocol (CoAP)</title>
<author initials='Z.' surname='Shelby' fullname='Z. Shelby'><organization /></author>
<author initials='K.' surname='Hartke' fullname='K. Hartke'><organization /></author>
<author initials='C.' surname='Bormann' fullname='C. Bormann'><organization /></author>
<date year='2014' month='June' />
<abstract><t>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.</t><t>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.</t></abstract>
</front>
<seriesInfo name='RFC' value='7252'/>
<seriesInfo name='DOI' value='10.17487/RFC7252'/>
</reference>
<reference anchor='RFC7317' target='http://www.rfc-editor.org/info/rfc7317'>
<front>
<title>A YANG Data Model for System Management</title>
<author initials='A.' surname='Bierman' fullname='A. Bierman'><organization /></author>
<author initials='M.' surname='Bjorklund' fullname='M. Bjorklund'><organization /></author>
<date year='2014' month='August' />
<abstract><t>This 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.</t></abstract>
</front>
<seriesInfo name='RFC' value='7317'/>
<seriesInfo name='DOI' value='10.17487/RFC7317'/>
</reference>
<reference anchor='RFC7641' target='http://www.rfc-editor.org/info/rfc7641'>
<front>
<title>Observing Resources in the Constrained Application Protocol (CoAP)</title>
<author initials='K.' surname='Hartke' fullname='K. Hartke'><organization /></author>
<date year='2015' month='September' />
<abstract><t>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.</t></abstract>
</front>
<seriesInfo name='RFC' value='7641'/>
<seriesInfo name='DOI' value='10.17487/RFC7641'/>
</reference>
</references>
<references title='Informative References'>
<reference anchor='I-D.ietf-netconf-restconf'>
<front>
<title>RESTCONF Protocol</title>
<author initials='A' surname='Bierman' fullname='Andy Bierman'>
<organization />
</author>
<author initials='M' surname='Bjorklund' fullname='Martin Bjorklund'>
<organization />
</author>
<author initials='K' surname='Watsen' fullname='Kent Watsen'>
<organization />
</author>
<date month='December' day='15' year='2015' />
<abstract><t>This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastores defined in NETCONF.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-netconf-restconf-09' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-netconf-restconf-09.txt' />
</reference>
<reference anchor='I-D.ersue-constrained-mgmt'>
<front>
<title>Management of Networks with Constrained Devices: Problem Statement, Use Cases and Requirements</title>
<author initials='M' surname='Ersue' fullname='Mehmet Ersue'>
<organization />
</author>
<author initials='D' surname='Romascanu' fullname='Dan Romascanu'>
<organization />
</author>
<author initials='J' surname='Schoenwaelder' fullname='Juergen Schoenwaelder'>
<organization />
</author>
<date month='February' day='14' year='2013' />
<abstract><t>This document provides a problem statement and discusses the use cases and requirements for the management of networks with constrained devices.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ersue-constrained-mgmt-03' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ersue-constrained-mgmt-03.txt' />
</reference>
<reference anchor='I-D.ietf-core-coap-tcp-tls'>
<front>
<title>A TCP and TLS Transport for the Constrained Application Protocol (CoAP)</title>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<author initials='S' surname='Lemay' fullname='Simon Lemay'>
<organization />
</author>
<author initials='Z' surname='Technologies' fullname='Zebra Technologies'>
<organization />
</author>
<author initials='H' surname='Tschofenig' fullname='Hannes Tschofenig'>
<organization />
</author>
<date month='November' day='19' year='2015' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) was designed with TCP as the underlying transport protocol. The Constrained Application Protocol (CoAP), while inspired by HTTP, has been defined to make use of UDP instead of TCP. Therefore, reliable delivery and a simple congestion control and flow control mechanism are provided by the message layer of the CoAP protocol. A number of environments benefit from the use of CoAP directly over a reliable byte stream such as TCP, which already provides these services. This document defines the use of CoAP over TCP as well as CoAP over TLS.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-core-coap-tcp-tls-01' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-core-coap-tcp-tls-01.txt' />
</reference>
<reference anchor='I-D.bormann-core-ipsec-for-coap'>
<front>
<title>Using CoAP with IPsec</title>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<date month='December' day='6' year='2012' />
<abstract><t>CoAP is a RESTful transfer protocol for constrained nodes and networks. Security for the protocol can be supplied in a number of ways. The mandatory-to-implement security mode for CoAP makes use of DTLS. Other applications may want to use IPsec. This document will discuss considerations for the use of IPsec with CoAP. It will be advanced on a timescale separate from the main CoAP specification, as most experience in securing CoAP so far has been made with DTLS. The current version of this specification is a placeholder, built out of text extracted from draft-ietf-core-coap-12. It is meant to pick up http://trac.tools.ietf.org/wg/core/trac/ticket/262 and provide a home for its considerations. It might be merged with other documents later.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-bormann-core-ipsec-for-coap-00' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-bormann-core-ipsec-for-coap-00.txt' />
</reference>
<reference anchor='I-D.vanderstok-core-comi'>
<front>
<title>CoAP Management Interface</title>
<author initials='P' surname='Stok' fullname='Peter Van der Stok'>
<organization />
</author>
<author initials='A' surname='Bierman' fullname='Andy Bierman'>
<organization />
</author>
<date month='March' day='7' year='2016' />
<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. Note Discussion and suggestions for improvement are requested, and should be sent to core@ietf.org.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-vanderstok-core-comi-09' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-vanderstok-core-comi-09.txt' />
<format type='PDF'
target='http://www.ietf.org/internet-drafts/draft-vanderstok-core-comi-09.pdf' />
</reference>
<reference anchor='RFC5755' target='http://www.rfc-editor.org/info/rfc5755'>
<front>
<title>An Internet Attribute Certificate Profile for Authorization</title>
<author initials='S.' surname='Farrell' fullname='S. Farrell'><organization /></author>
<author initials='R.' surname='Housley' fullname='R. Housley'><organization /></author>
<author initials='S.' surname='Turner' fullname='S. Turner'><organization /></author>
<date year='2010' month='January' />
<abstract><t>This specification defines a profile for the use of X.509 Attribute Certificates in Internet Protocols. Attribute certificates may be used in a wide range of applications and environments covering a broad spectrum of interoperability goals and a broader spectrum of operational and assurance requirements. The goal of this document is to establish a common baseline for generic applications requiring broad interoperability as well as limited special purpose requirements. The profile places emphasis on attribute certificate support for Internet electronic mail, IPsec, and WWW security applications. This document obsoletes RFC 3281. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='5755'/>
<seriesInfo name='DOI' value='10.17487/RFC5755'/>
</reference>
<reference anchor='RFC7223' target='http://www.rfc-editor.org/info/rfc7223'>
<front>
<title>A YANG Data Model for Interface Management</title>
<author initials='M.' surname='Bjorklund' fullname='M. Bjorklund'><organization /></author>
<date year='2014' month='May' />
<abstract><t>This 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).</t></abstract>
</front>
<seriesInfo name='RFC' value='7223'/>
<seriesInfo name='DOI' value='10.17487/RFC7223'/>
</reference>
<reference anchor='RFC7228' target='http://www.rfc-editor.org/info/rfc7228'>
<front>
<title>Terminology for Constrained-Node Networks</title>
<author initials='C.' surname='Bormann' fullname='C. Bormann'><organization /></author>
<author initials='M.' surname='Ersue' fullname='M. Ersue'><organization /></author>
<author initials='A.' surname='Keranen' fullname='A. Keranen'><organization /></author>
<date year='2014' month='May' />
<abstract><t>The Internet Protocol Suite is increasingly used on small devices with severe constraints on power, memory, and processing resources, creating constrained-node networks. This document provides a number of basic terms that have been useful in the standardization work for constrained-node networks.</t></abstract>
</front>
<seriesInfo name='RFC' value='7228'/>
<seriesInfo name='DOI' value='10.17487/RFC7228'/>
</reference>
</references>
<section anchor="cool-module" title="File “ietf-cool.yang”">
<t>Module containing the different definitions required by the CoOL protocol.</t>
<figure align="left"><artwork><![CDATA[
module ietf-cool {
namespace "urn:ietf:ns:cool";
prefix cool;
organization
"IETF Core Working Group";
contact
"Ana Minaburo
<mailto:ana@ackl.io>
Abhinav Somaraju
<mailto:abhinav.somaraju@tridonic.com>
Alexander Pelov
<mailto:a@ackl.io>
Michel Veillette
<mailto:michel.veillette@trilliantinc.com>
Randy Turner
<mailto:Randy.Turner@landisgyr.com>";
description
"This module contains the different definitions required
by the CoOL protocol.";
revision 2016-01-01 {
description
"Initial revision.";
reference
"draft-veillette-core-cool";
}
// List of useful derived YANG data types for constrained devices
typedef sid {
type uint32;
description
"Structure Identifier value (SID).";
}
typedef utc-time {
type uint32;
description
"Unsigned 32-bit value representing the number of seconds
since 0 hours, 0 minutes, 0 seconds, on the 1st of January,
2000 UTC (Universal Coordinated Time).";
}
// Error payload
container error-payload {
description
"Optional payload of a client error (CoAP response 4.xx)
or server error (CoAP response 5.xx).";
leaf error-code {
mandatory true;
type enumeration {
enum ok {
value 0;
description
"The requested edit have been performed successfully.";
}
enum error {
value 1;
description "Unspecified error.";
}
enum malformed {
value 2;
description "Malformed CBOR payload.";
}
enum invalid {
value 3;
description "The value specified in the request can't be
apply to the target data node.";
}
enum doesNotExist {
value 4;
description "The target data node instance specified in
the request doesn't exist.";
}
enum alreadyExist {
value 5;
description "The target data node instance specified in
the request already exists.";
}
enum readOnly {
value 6;
description "Attempt to update a read-only data node.";
}
}
}
leaf error-text {
mandatory false;
type string;
description "Textual descriptions of the error.";
}
}
// Notification payload
identity facility-type {
description
"A facility code is used to specify the type of process that
is logging the message. Notifications from different facilities
may be handled differently. Other YANG module may add new
facility type as needed.";
}
identity os {
base facility-type;
}
identity protocol-stack {
base facility-type;
}
identity security {
base facility-type;
}
identity hardware-monitoring {
base facility-type;
}
identity application {
base facility-type;
}
container notification-payload {
leaf _id {
mandatory true;
type instance-identifier;
description
"Identifier associated to the notification reported.";
}
leaf timestamp {
mandatory false;
type utc-time;
description
"Event timestamp. Support of this field is optional
since its not expected that all implementations have
implement a real time clock and if so, this clock is
available at all time.";
}
leaf sequence-number {
mandatory false;
type uint32;
description
"Sequence number associated to each event created by CoOL
server within a specific event stream.";
}
leaf severity-level {
reference "RFC 5424";
mandatory false;
type enumeration {
enum emergency {
value 0;
description
"System is unusable.";
}
enum alert {
value 1;
description
"Should be corrected immediately.";
}
enum critical {
value 2;
description
"Critical conditions.";
}
enum error {
value 3;
description
"Error conditions.";
}
enum warning {
value 4;
description
"May indicate that an error will occur if action is
not taken.";
}
enum notice {
value 5;
description
"Events that are unusual, but not error conditions.";
}
enum informational {
value 6;
description
"Normal operational messages that require no action.";
}
enum debug {
value 7;
description
"Information useful to developers for debugging the
application.";
}
}
description
"Severity associated with this event.";
}
leaf facility {
mandatory false;
type identityref {
base facility-type;
}
description
"Type of process that is logging the message.";
reference "RFC 5424";
}
leaf content {
mandatory false;
type anydata;
description
"Notification container as defined by the notification YANG
statement.";
}
}
rpc commit {
description
"Used to commit the changes present in a candidate datastore on
the runtime datastore specify by the URI used to execute this
operation.";
input {
leaf datastore {
description
"Path of the datastore resource used as the source of the
commit operation. When not present, the default candidate
datastore resource is used.";
type string;
mandatory false;
}
leaf commit-date-time {
description
"When specified, the commit operation is postponed at the
specified date and time. When not present, the commit is
performed on reception of this RPC. Supports of this feature
is optional.";
type utc-time;
mandatory false;
}
leaf confirm-timeout {
description
"When present, a confirming commit MUST be received within
this period after the start of the commit process.
A confirming commit is a commit RPC without the
confirm-timeout field presents. Supports of this feature
is optional.";
type string;
mandatory false;
}
}
}
rpc cancel-commit {
description
"Cancels an ongoing scheduled or confirmed commit.";
}
}
]]></artwork></figure>
</section>
<section anchor="cool-sid-file" title="File “ietf-cool@2016-01-01.sid”">
<t>Following is the “.sid” file generated for the “ietf-cool” YANG module. See [I-D.somaraju-core-sid] for more details on SID and “.sid” file.</t>
<figure align="left"><artwork><![CDATA[
{
"assignment-ranges": [
{
"entry-point": 1000,
"size": 100
}
],
"module-name": "ietf-cool",
"module-revision": "2016-01-01",
"items": [
{
"type": "identity",
"assigned": "2016-03-08T21:59:45Z",
"label": "ietf-cool:application",
"sid": 1000
},
{
"type": "identity",
"assigned": "2016-03-08T21:59:45Z",
"label": "ietf-cool:facility-type",
"sid": 1001
},
{
"type": "identity",
"assigned": "2016-03-08T21:59:45Z",
"label": "ietf-cool:hardware-monitoring",
"sid": 1002
},
{
"type": "identity",
"assigned": "2016-03-08T21:59:45Z",
"label": "ietf-cool:os",
"sid": 1003
},
{
"type": "identity",
"assigned": "2016-03-08T21:59:45Z",
"label": "ietf-cool:protocol-stack",
"sid": 1004
},
{
"type": "identity",
"assigned": "2016-03-08T21:59:45Z",
"label": "ietf-cool:security",
"sid": 1005
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/error-payload",
"sid": 1006
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/error-payload/error-code",
"sid": 1007
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/error-payload/error-text",
"sid": 1008
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/notification-payload",
"sid": 1009
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/notification-payload/_id",
"sid": 1010
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/notification-payload/content",
"sid": 1011
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/notification-payload/facility",
"sid": 1012
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/notification-payload/sequence-number",
"sid": 1013
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/notification-payload/severity-level",
"sid": 1014
},
{
"type": "node",
"assigned": "2016-03-08T21:59:45Z",
"label": "/notification-payload/timestamp",
"sid": 1015
},
{
"type": "rpc",
"assigned": "2016-03-08T21:59:45Z",
"label": "/cancel-commit",
"sid": 1016
},
{
"type": "rpc",
"assigned": "2016-03-08T21:59:45Z",
"label": "/commit",
"sid": 1017
},
{
"type": "rpc",
"assigned": "2016-03-08T21:59:45Z",
"label": "/commit/input/commit-date-time",
"sid": 1018
},
{
"type": "rpc",
"assigned": "2016-03-08T21:59:45Z",
"label": "/commit/input/confirm-timeout",
"sid": 1019
},
{
"type": "rpc",
"assigned": "2016-03-08T21:59:45Z",
"label": "/commit/input/datastore",
"sid": 1020
}
]
}
]]></artwork></figure>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 04:07:37 |